feat(gates): runtime + CI gates for the five incident classes (#190)

- provision-payload size gate (240KB, per-section breakdown) before the
  sandbox create POST in ensureWorkspaceSandbox
- env-var size gate at the same choke point (120KB/entry, 200KB total;
  E2BIG class)
- composed-systemPrompt byte budget in composeAgentProfile (default 40KB,
  warnOnly escape hatch, top-3 section report)
- chat-stream error events fail loud when no onErrorEvent is wired:
  synthesized into the transcript text channel + console.error
- generalize the catalog browser-safe walker into a declared manifest of
  14 browser subpaths (tests/browser-safe-subpaths.test.ts)

Author: drewstone

src/profile/index.test.ts

@@ -1,11 +1,14 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import type {
   AgentProfile,
   AgentProfileFileMount,
   AgentProfileMcpServer,
 } from '@tangle-network/sandbox'
 import {
+  assertSystemPromptWithinBudget,
   composeAgentProfile,
+  DEFAULT_MAX_SYSTEM_PROMPT_BYTES,
+  largestPromptSections,
   makeEvolvableSection,
   stripComments,
   userSkillMounts,
@@ -217,3 +220,61 @@ describe('composeAgentProfile — canonical wire shape', () => {
     expect(out.prompt?.instructions).toContain('per-turn directive')
   })
 })
+
+describe('composeAgentProfile — system-prompt byte budget', () => {
+  // Two markdown sections whose combined size blows the default 40KB budget;
+  // "Big Section" dominates so the error must name it first.
+  const OVER_BUDGET_PROMPT =
+    `# Big Section\n${'a'.repeat(45_000)}\n## Small Section\n${'b'.repeat(2_000)}`
+
+  it('passes an under-budget prompt through unchanged (default budget)', () => {
+    const out = composeAgentProfile(BASE, {}, { systemPrompt: 'short prompt' })
+    expect(out.prompt?.systemPrompt).toBe('short prompt')
+  })
+
+  it('REDS on a composed prompt over the default 40KB budget, reporting size and top sections', () => {
+    expect(() => composeAgentProfile(BASE, {}, { systemPrompt: OVER_BUDGET_PROMPT })).toThrow(
+      /is 4\d{4} bytes — over the 40000-byte budget[\s\S]*Big Section/,
+    )
+  })
+
+  it('respects a custom maxSystemPromptBytes', () => {
+    expect(() =>
+      composeAgentProfile(BASE, {}, { systemPrompt: 'x'.repeat(200) }, { maxSystemPromptBytes: 100 }),
+    ).toThrow(/over the 100-byte budget/)
+    // And a raised budget lets a known-big prompt through.
+    const out = composeAgentProfile(
+      BASE,
+      {},
+      { systemPrompt: OVER_BUDGET_PROMPT },
+      { maxSystemPromptBytes: 100_000 },
+    )
+    expect(out.prompt?.systemPrompt).toBe(OVER_BUDGET_PROMPT)
+  })
+
+  it('warnOnly downgrades the throw to a console.warn that still yells', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const out = composeAgentProfile(BASE, {}, { systemPrompt: OVER_BUDGET_PROMPT }, { warnOnly: true })
+      expect(out.prompt?.systemPrompt).toBe(OVER_BUDGET_PROMPT)
+      expect(warn).toHaveBeenCalledTimes(1)
+      expect(String(warn.mock.calls[0]?.[0])).toMatch(/over the 40000-byte budget/)
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  it('assertSystemPromptWithinBudget measures UTF-8 bytes, not code units', () => {
+    // 3 bytes per char in UTF-8; 40 chars over a 100-byte cap.
+    expect(() => assertSystemPromptWithinBudget('€'.repeat(40), { maxSystemPromptBytes: 100 })).toThrow(
+      /is 120 bytes/,
+    )
+    expect(DEFAULT_MAX_SYSTEM_PROMPT_BYTES).toBe(40_000)
+  })
+
+  it('largestPromptSections ranks heading-delimited sections by bytes, preamble included', () => {
+    const sections = largestPromptSections(`intro\n# A\n${'a'.repeat(50)}\n## B\n${'b'.repeat(500)}`)
+    expect(sections[0]).toEqual({ title: 'B', bytes: expect.any(Number) })
+    expect(sections.map((s) => s.title)).toEqual(['B', 'A', '(preamble)'])
+  })
+})

src/profile/index.ts

@@ -109,6 +109,74 @@ export interface ProfileOverlay {
   name?: string
 }
 
+/** Byte budget on the FINAL composed `prompt.systemPrompt`. Past this the
+ *  model degrades sharply (a 122,659-byte prompt shipped once and the model
+ *  returned empty answers), so the default gate throws well before that. */
+export const DEFAULT_MAX_SYSTEM_PROMPT_BYTES = 40_000
+
+/** Budget config for the composed system prompt. */
+export interface ComposeProfileBudget {
+  /** Byte cap on the composed `prompt.systemPrompt`.
+   *  Default {@link DEFAULT_MAX_SYSTEM_PROMPT_BYTES}. */
+  maxSystemPromptBytes?: number
+  /** Downgrade the over-budget throw to a `console.warn` — the escape hatch
+   *  for a product with a known-big prompt that must still ship (it yells on
+   *  every compose instead of blocking). */
+  warnOnly?: boolean
+}
+
+/** Largest markdown-heading-delimited sections of a prompt, by UTF-8 bytes.
+ *  Cheap heuristic: split on `#`-heading lines; the preamble before the first
+ *  heading reports as "(preamble)". */
+export function largestPromptSections(
+  prompt: string,
+  top = 3,
+): Array<{ title: string; bytes: number }> {
+  const encoder = new TextEncoder()
+  const sections: Array<{ title: string; bytes: number }> = []
+  let title = '(preamble)'
+  let start = 0
+  const flush = (end: number) => {
+    const body = prompt.slice(start, end)
+    if (body.trim()) sections.push({ title, bytes: encoder.encode(body).byteLength })
+  }
+  const headingRe = /^#{1,6}\s+(.+)$/gm
+  for (const match of prompt.matchAll(headingRe)) {
+    flush(match.index)
+    title = (match[1] ?? '').trim() || '(untitled section)'
+    start = match.index
+  }
+  flush(prompt.length)
+  return sections.sort((a, b) => b.bytes - a.bytes).slice(0, top)
+}
+
+/** Enforce {@link ComposeProfileBudget} on a composed system prompt: over
+ *  budget throws (or warns with `warnOnly`) with the actual size and the
+ *  top-3 largest sections. Exported so a product assembling its prompt
+ *  outside {@link composeAgentProfile} (e.g. via the `/prompt` assembler) can
+ *  run the same gate at its own final-composition point. */
+export function assertSystemPromptWithinBudget(
+  systemPrompt: string,
+  budget: ComposeProfileBudget = {},
+): void {
+  const max = budget.maxSystemPromptBytes ?? DEFAULT_MAX_SYSTEM_PROMPT_BYTES
+  const bytes = new TextEncoder().encode(systemPrompt).byteLength
+  if (bytes <= max) return
+  const sections = largestPromptSections(systemPrompt)
+    .map((s) => `"${s.title}" (${s.bytes}B)`)
+    .join(', ')
+  const message =
+    `composed systemPrompt is ${bytes} bytes — over the ${max}-byte budget ` +
+    `(oversized prompts degrade to empty answers). ` +
+    (sections ? `Largest sections: ${sections}. ` : '') +
+    `Trim the prompt, move content to skills/knowledge mounts, or raise maxSystemPromptBytes deliberately.`
+  if (budget.warnOnly) {
+    console.warn(`[profile] ${message}`)
+    return
+  }
+  throw new Error(message)
+}
+
 /** Project per-user skills onto SDK file mounts at the harness skill-discovery
  *  path. No tier gate — a user skill is mounted because the user added it.
  *  Sorted by path for determinism (matches {@link registrySkills}). */
@@ -140,11 +208,16 @@ export function userSkillMounts(userSkills: UserSkill[]): AgentProfileFileMount[
  * not a hand-rolled spread. `mergeAgentProfiles(base, overlay)` returns
  * `undefined` only when BOTH are `undefined`; `base` is always defined here, so
  * the result is non-`undefined` by construction and we assert that to the caller.
+ *
+ * The composed `prompt.systemPrompt` is byte-budgeted here — the single point
+ * where the FINAL prompt exists ({@link assertSystemPromptWithinBudget};
+ * default {@link DEFAULT_MAX_SYSTEM_PROMPT_BYTES}, `warnOnly` escape hatch).
  */
 export function composeAgentProfile(
   base: AgentProfile,
   channels: ProfileChannels = {},
   overlay: ProfileOverlay = {},
+  budget: ComposeProfileBudget = {},
 ): AgentProfile {
   const shellInput: ComposeShellResourcesInput = {
     skills: channels.skills,
@@ -174,6 +247,10 @@ export function composeAgentProfile(
   const merged = mergeAgentProfiles(base, overlayProfile)
   if (!merged)
     throw new Error('composeAgentProfile: mergeAgentProfiles returned undefined for a defined base')
+  // Byte-budget gate on the FINAL composed systemPrompt — this is the single
+  // point where every channel and overlay has been merged in.
+  const systemPrompt = merged.prompt?.systemPrompt
+  if (typeof systemPrompt === 'string') assertSystemPromptWithinBudget(systemPrompt, budget)
   return pruneEmptyResourceChannels(merged)
 }
 

src/sandbox/index.test.ts

@@ -63,6 +63,11 @@ import {
   runSandboxToolPathSetup,
   splitDeferredProfileFiles,
   writeProfileFilesToBox,
+  assertProvisionPayloadWithinCap,
+  assertEnvWithinLimits,
+  PROVISION_PAYLOAD_MAX_BYTES,
+  ENV_VALUE_MAX_BYTES,
+  ENV_TOTAL_MAX_BYTES,
   SandboxRuntimeAuthRefreshError,
   type SandboxRuntimeConfig,
   type SecretStore,
@@ -698,6 +703,92 @@ describe('mintSandboxScopedToken', () => {
   })
 })
 
+describe('provision S-cost gates', () => {
+  it('assertEnvWithinLimits REDS on a single env value over the per-entry cap, naming the variable', () => {
+    expect(() =>
+      assertEnvWithinLimits({ SMALL: 'ok', OPENCODE_CONFIG_CONTENT: 'x'.repeat(ENV_VALUE_MAX_BYTES) }),
+    ).toThrow(/OPENCODE_CONFIG_CONTENT is \d+ bytes[\s\S]*MAX_ARG_STRLEN/)
+  })
+
+  it('assertEnvWithinLimits REDS on total env size over the block cap, naming the largest entry', () => {
+    const env: Record<string, string> = {}
+    for (let i = 0; i < 4; i += 1) env[`VAR_${i}`] = 'x'.repeat(60_000)
+    env.VAR_3 = 'x'.repeat(61_000)
+    expect(() => assertEnvWithinLimits(env)).toThrow(
+      new RegExp(`env block is \\d+ bytes total — over the ${ENV_TOTAL_MAX_BYTES}-byte gate[\\s\\S]*VAR_3`),
+    )
+  })
+
+  it('assertEnvWithinLimits passes a normal env untouched', () => {
+    expect(() => assertEnvWithinLimits({ WORKSPACE_ID: 'w1', NODE_ENV: 'test' })).not.toThrow()
+  })
+
+  it('assertProvisionPayloadWithinCap REDS over 240KB with a per-section breakdown and the defer hint', () => {
+    const payload = {
+      env: { WORKSPACE_ID: 'w1' },
+      secrets: ['SECRET_A'],
+      backend: {
+        profile: {
+          name: 'big',
+          resources: {
+            files: [
+              { path: 'corpus.md', resource: { kind: 'inline', name: 'corpus', content: 'x'.repeat(280_000) } },
+            ],
+          },
+        } as AgentProfile,
+      },
+    }
+    expect(() => assertProvisionPayloadWithinCap(payload)).toThrow(
+      new RegExp(
+        `payload is \\d+ bytes — over the ${PROVISION_PAYLOAD_MAX_BYTES}-byte gate` +
+          `[\\s\\S]*profile=\\d+B \\(files=\\d+B\\), env=\\d+B, secrets=\\d+B` +
+          `[\\s\\S]*deferProfileFiles: true or move content to resources`,
+      ),
+    )
+  })
+
+  it('assertProvisionPayloadWithinCap passes an under-cap payload', () => {
+    expect(() =>
+      assertProvisionPayloadWithinCap({ env: { A: 'a' }, secrets: [], backend: { profile: PROFILE } }),
+    ).not.toThrow()
+  })
+
+  it('ensureWorkspaceSandbox rejects an over-cap payload BEFORE the create POST', async () => {
+    listMock.mockResolvedValue([])
+    createMock.mockResolvedValue(fakeBox())
+    const bigProfile: AgentProfile = {
+      name: 'big',
+      resources: {
+        files: [
+          { path: 'corpus.md', resource: { kind: 'inline', name: 'corpus', content: 'x'.repeat(280_000) } },
+        ],
+      },
+    } as AgentProfile
+    await expect(
+      ensureWorkspaceSandbox(shellFor({ apiKey: 'k', baseUrl: 'https://s' }, { profile: () => bigProfile }), {
+        workspaceId: 'w1',
+        harness: 'opencode',
+      }),
+    ).rejects.toThrow(/over the 240000-byte gate[\s\S]*deferProfileFiles/)
+    expect(createMock).not.toHaveBeenCalled()
+  })
+
+  it('ensureWorkspaceSandbox rejects an E2BIG-class env var BEFORE the create POST', async () => {
+    listMock.mockResolvedValue([])
+    createMock.mockResolvedValue(fakeBox())
+    await expect(
+      ensureWorkspaceSandbox(
+        shellFor(
+          { apiKey: 'k', baseUrl: 'https://s' },
+          { env: async () => ({ OPENCODE_CONFIG_CONTENT: 'x'.repeat(130_000) }) },
+        ),
+        { workspaceId: 'w1', harness: 'opencode' },
+      ),
+    ).rejects.toThrow(/OPENCODE_CONFIG_CONTENT/)
+    expect(createMock).not.toHaveBeenCalled()
+  })
+})
+
 describe('ensureWorkspaceSandbox — new seams', () => {
   beforeEach(() => {
     resetClientCache()

src/sandbox/index.ts

@@ -1009,6 +1009,94 @@ async function deleteBox(box: SandboxInstance): Promise<Outcome<void>> {
 // named harness) is what enforces correctness.
 type CreatePayload = Parameters<Sandbox['create']>[0]
 
+// ---------------------------------------------------------------------------
+// Provision-time S-cost gates. Both run immediately before `client.create` —
+// each catches an input class that can NEVER produce a working sandbox, so
+// failing at POST-time with actionable detail beats a platform 4xx (or a box
+// that boots and then E2BIGs on every exec).
+
+/** Gate on the provision body: the platform orchestrator caps the create
+ *  payload at 256 KiB; 240 KB leaves headroom for transport framing. An
+ *  over-cap payload fails provisioning 100% of the time (a 282 KB payload
+ *  shipped once and no sandbox could ever be created). */
+export const PROVISION_PAYLOAD_MAX_BYTES = 240_000
+
+/** Per-variable env gate: the kernel rejects any single `NAME=value` env entry
+ *  over MAX_ARG_STRLEN (131072 bytes) with E2BIG, killing every exec inside
+ *  the box. 120 KB leaves headroom for the name and framing. */
+export const ENV_VALUE_MAX_BYTES = 120_000
+
+/** Total env gate: the whole environment block shares the payload budget with
+ *  the profile; past 200 KB the provision body cannot stay under the cap. */
+export const ENV_TOTAL_MAX_BYTES = 200_000
+
+function utf8ByteLength(value: unknown): number {
+  return new TextEncoder().encode(typeof value === 'string' ? value : JSON.stringify(value ?? null))
+    .byteLength
+}
+
+/** The provision-payload sections the size gates need to see. Structural so
+ *  the gate is testable without the SDK's (unexported) create-payload type. */
+export interface ProvisionPayloadSections {
+  env?: Record<string, string>
+  secrets?: readonly string[]
+  backend?: { profile?: AgentProfile }
+}
+
+/**
+ * Throw when the serialized provision payload exceeds
+ * {@link PROVISION_PAYLOAD_MAX_BYTES}. The error carries a per-section byte
+ * breakdown (profile/files/env/secrets) so the offending channel is named, not
+ * guessed.
+ */
+export function assertProvisionPayloadWithinCap(payload: ProvisionPayloadSections): void {
+  const total = utf8ByteLength(payload)
+  if (total <= PROVISION_PAYLOAD_MAX_BYTES) return
+  const profile = payload.backend?.profile
+  const files = profile?.resources?.files ?? []
+  const breakdown =
+    `profile=${utf8ByteLength(profile ?? null)}B ` +
+    `(files=${utf8ByteLength(files)}B), ` +
+    `env=${utf8ByteLength(payload.env ?? {})}B, ` +
+    `secrets=${utf8ByteLength(payload.secrets ?? [])}B`
+  throw new Error(
+    `sandbox provision payload is ${total} bytes — over the ${PROVISION_PAYLOAD_MAX_BYTES}-byte gate ` +
+      `(the platform caps the create body at 256 KiB; an over-cap payload can never create a sandbox). ` +
+      `Breakdown: ${breakdown}. ` +
+      `Hint: set deferProfileFiles: true or move content to resources.`,
+  )
+}
+
+/**
+ * Throw when any single env value exceeds {@link ENV_VALUE_MAX_BYTES} or the
+ * whole env block exceeds {@link ENV_TOTAL_MAX_BYTES}, naming the offending
+ * variable. This is the E2BIG incident class: the box may even provision, but
+ * every exec inside it dies on the oversized entry.
+ */
+export function assertEnvWithinLimits(env: Record<string, string>): void {
+  let total = 0
+  let largest: { name: string; bytes: number } | null = null
+  for (const [name, value] of Object.entries(env)) {
+    const bytes = utf8ByteLength(`${name}=${value}`)
+    total += bytes
+    if (!largest || bytes > largest.bytes) largest = { name, bytes }
+    if (bytes > ENV_VALUE_MAX_BYTES) {
+      throw new Error(
+        `sandbox env var ${name} is ${bytes} bytes — over the ${ENV_VALUE_MAX_BYTES}-byte gate ` +
+          `(kernel MAX_ARG_STRLEN is 131072 bytes per env entry; anything larger E2BIGs every exec). ` +
+          `Write large content to a file mount or resource instead of an env var.`,
+      )
+    }
+  }
+  if (total > ENV_TOTAL_MAX_BYTES) {
+    const worst = largest ? ` Largest: ${largest.name} (${largest.bytes}B).` : ''
+    throw new Error(
+      `sandbox env block is ${total} bytes total — over the ${ENV_TOTAL_MAX_BYTES}-byte gate.${worst} ` +
+        `Write large content to a file mount or resource instead of env vars.`,
+    )
+  }
+}
+
 // Generic exec+sidecar liveness probe. Absent probe => always alive (the prior
 // reuse-on-metadata-match behavior). With a probe: the container must answer an
 // `echo alive` exec within execTimeoutMs, and the sidecar process must be found
@@ -1457,6 +1545,12 @@ export async function ensureWorkspaceSandbox(
     },
   } as CreatePayload
 
+  // S-cost gates: an oversized env entry (E2BIG class) or an over-cap
+  // provision body can never produce a working sandbox — fail loud here,
+  // before the POST, with the offending section named.
+  assertEnvWithinLimits(env)
+  assertProvisionPayloadWithinCap(payload as ProvisionPayloadSections)
+
   let box = await client.create(payload)
 
   await box.waitFor('running', { timeoutMs: 120_000, ...(onProgress ? { onProgress } : {}) })