@namzu/sdk 25.0.0 → 26.1.0

package/src/connector/mcp/stdio.ts

@@ -13,6 +13,111 @@ import { type Logger, getRootLogger } from '../../utils/logger.js'
  */
 const TERMINATE_GRACE_MS = 2_000
 
+/**
+ * The variables a child needs in order to be a working process at all.
+ *
+ * This spawn used to pass `{ ...process.env, ...config.env }`, so a connected
+ * server received every credential the host happened to hold — measured at 119
+ * variables on a developer machine, including a planted secret the server had
+ * no reason to see. A server that needs one token was handed all of them, and
+ * nothing in the config said so.
+ *
+ * The list below is process plumbing, not secrets: where to find executables,
+ * where the home and temp directories are, what the locale is. Dropping any of
+ * it does not harden anything and does break servers — a child with no `PATH`
+ * cannot resolve its own interpreter.
+ *
+ * Anything else a server needs is now named: `env` gives it a literal value,
+ * and `inheritEnv` names a parent variable to pass through. Naming is the
+ * point — a grant that has to be written down is a grant somebody can review.
+ *
+ * Windows spellings are matched case-insensitively, because its environment is
+ * case-insensitive and a lookup for `Path` against a key stored as `PATH` would
+ * silently drop it — which would present as "the server does not start on
+ * Windows" rather than as anything to do with this list.
+ */
+const BASE_ENV_KEYS: readonly string[] = [
+	// Everywhere.
+	'PATH',
+	'LANG',
+	'LC_ALL',
+	'LC_CTYPE',
+	'TZ',
+	// POSIX.
+	'HOME',
+	'SHELL',
+	'TMPDIR',
+	'USER',
+	'LOGNAME',
+	// Windows. `SystemRoot` and `ComSpec` are load-bearing: without them a
+	// child cannot resolve system DLLs or the command interpreter.
+	'PATHEXT',
+	'SystemRoot',
+	'SystemDrive',
+	'ComSpec',
+	'WINDIR',
+	'TEMP',
+	'TMP',
+	'USERPROFILE',
+	'HOMEDRIVE',
+	'HOMEPATH',
+	'APPDATA',
+	'LOCALAPPDATA',
+	'PROGRAMDATA',
+	'PROGRAMFILES',
+	'NUMBER_OF_PROCESSORS',
+	'PROCESSOR_ARCHITECTURE',
+]
+
+/**
+ * Read one variable from the parent, honouring the platform's own casing rules.
+ *
+ * Node exposes `process.env` on Windows through a case-insensitive proxy, so a
+ * direct lookup already works there — but the KEY this returns has to be the
+ * one the parent actually uses, or a child comparing key names sees a spelling
+ * the host never set.
+ */
+function readParentVar(source: NodeJS.ProcessEnv, name: string): [string, string] | undefined {
+	const direct = source[name]
+	if (direct !== undefined) return [name, direct]
+	if (process.platform !== 'win32') return undefined
+	const lowered = name.toLowerCase()
+	for (const [key, value] of Object.entries(source)) {
+		if (key.toLowerCase() === lowered && value !== undefined) return [key, value]
+	}
+	return undefined
+}
+
+/**
+ * What the child is handed: plumbing, then the named inheritances, then the
+ * literal values.
+ *
+ * Later wins, and the order is the precedence an operator would guess: a
+ * literal `env` entry overrides an inherited one, and both override the base.
+ * Exported for the tests, which assert on the ENV rather than on the spawn —
+ * a test that only checked the config was accepted would have passed against
+ * the version this replaces.
+ */
+export function buildChildEnv(
+	config: Pick<MCPStdioTransportConfig, 'env' | 'inheritEnv'>,
+	source: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+	const env: Record<string, string> = {}
+	for (const name of BASE_ENV_KEYS) {
+		const found = readParentVar(source, name)
+		if (found) env[found[0]] = found[1]
+	}
+	for (const name of config.inheritEnv ?? []) {
+		const found = readParentVar(source, name)
+		// A named variable the parent does not hold is simply absent. Refusing
+		// the spawn would turn an optional credential into a startup failure,
+		// and inventing an empty string would tell the server it has one.
+		if (found) env[found[0]] = found[1]
+	}
+	for (const [name, value] of Object.entries(config.env ?? {})) env[name] = value
+	return env
+}
+
 export class StdioTransport implements MCPTransport {
 	private process: ChildProcess | null = null
 	private messageHandlers: Array<(message: MCPJsonRpcMessage) => void> = []
@@ -32,7 +137,7 @@ export class StdioTransport implements MCPTransport {
 		if (this.connected) return
 
 		this.process = spawn(this.config.command, this.config.args ?? [], {
-			env: { ...process.env, ...this.config.env },
+			env: buildChildEnv(this.config),
 			cwd: this.config.cwd,
 			stdio: ['pipe', 'pipe', 'pipe'],
 		})

package/src/constants/telemetry/index.ts

@@ -23,7 +23,22 @@ export const GENAI = {
 
 	TOOL_NAME: 'gen_ai.tool.name',
 	TOOL_TYPE: 'gen_ai.tool.type',
-	TOOL_CALL_ID: 'gen_ai.tool.call_id',
+
+	/**
+	 * The id of the tool call this span is about.
+	 *
+	 * Spelled `call.id`, matching the registry and matching the two
+	 * neighbours above — this read `gen_ai.tool.call_id`, one underscore
+	 * where the convention has a dot, so a consumer grouping by the
+	 * conventional name found nothing under it. Nothing errored, because a
+	 * span attribute is a free-form key and a wrong one is simply a key
+	 * nobody asked for.
+	 *
+	 * Pinned by `telemetry/__tests__/tool-call-id-attribute.test.ts`, which
+	 * also drives the emitter: the spelling was only half the defect, and
+	 * the constant had no writer at all.
+	 */
+	TOOL_CALL_ID: 'gen_ai.tool.call.id',
 
 	AGENT_NAME: 'gen_ai.agent.name',
 	AGENT_ID: 'gen_ai.agent.id',

package/src/provider/fallback.ts

@@ -382,7 +382,13 @@ export function withProviderFallback(
 		},
 		chatStream,
 		...(first.provider.listModels ? { listModels: () => first.provider.listModels?.() } : {}),
-		...(first.provider.healthCheck ? { healthCheck: () => first.provider.healthCheck?.() } : {}),
-		...(first.provider.doctorCheck ? { doctorCheck: () => first.provider.doctorCheck?.() } : {}),
+		// Forwarded for the reason `retry.ts` forwards it: a wrapper that drops
+		// the model turns a probe the caller could answer into one it cannot.
+		...(first.provider.healthCheck
+			? { healthCheck: (model?: string) => first.provider.healthCheck?.(model) }
+			: {}),
+		...(first.provider.doctorCheck
+			? { doctorCheck: (model?: string) => first.provider.doctorCheck?.(model) }
+			: {}),
 	} as LLMProvider
 }

package/src/provider/retry.ts

@@ -231,7 +231,15 @@ export function withProviderRetry(
 		},
 		chatStream,
 		...(provider.listModels ? { listModels: () => provider.listModels?.() } : {}),
-		...(provider.healthCheck ? { healthCheck: () => provider.healthCheck?.() } : {}),
-		...(provider.doctorCheck ? { doctorCheck: () => provider.doctorCheck?.() } : {}),
+		// The model is forwarded, not dropped. A wrapper that swallowed it would
+		// leave the wrapped driver probing whatever it probes with no argument
+		// — which for at least one driver is "nothing", so the check would come
+		// back unanswerable purely because it was wrapped.
+		...(provider.healthCheck
+			? { healthCheck: (model?: string) => provider.healthCheck?.(model) }
+			: {}),
+		...(provider.doctorCheck
+			? { doctorCheck: (model?: string) => provider.doctorCheck?.(model) }
+			: {}),
 	} as LLMProvider
 }

package/src/registry/tool/execute.ts

@@ -415,9 +415,21 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 
 		return tracer.startActiveSpan(toolSpanName(toolName), {}, parentCtx, async (span) => {
 			try {
+				// The call id joins this span to the assistant block that asked
+				// for it. Without it a trace shows that `Bash` ran four times
+				// this turn and cannot say which span answers which
+				// `tool_use` — and the id was already in hand here, threaded
+				// through `ToolContext` for the tools that reply
+				// asynchronously.
+				//
+				// Conditional because `toolUseId` is optional: a host calling
+				// a tool directly, outside a run, has no call to correlate to,
+				// and an attribute set to `undefined` is worse than an absent
+				// one — it reaches the exporter as a key with no value.
 				span.setAttributes({
 					[GENAI.TOOL_NAME]: toolName,
 					[GENAI.TOOL_TYPE]: 'function',
+					...(context.toolUseId !== undefined ? { [GENAI.TOOL_CALL_ID]: context.toolUseId } : {}),
 				})
 
 				const tool = this.getOrThrow(toolName)

package/src/session/workspace/git-worktree.ts

@@ -89,7 +89,26 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 		try {
 			await this.exec('git', argv)
 		} catch (cause) {
-			throw new WorkspaceBackendError({ op: 'create', kind: this.kind, cause })
+			// A non-zero exit here does not mean the worktree was not created.
+			// `git worktree add` runs the repository's post-checkout hook AFTER
+			// the checkout has completed, so a hook that fails — or that a
+			// timeout kills — reports failure over a worktree that is finished
+			// and usable. Treating the status as the answer throws away a good
+			// checkout AND leaks it: the path stays registered, and the next
+			// attempt fails differently, with "already exists".
+			//
+			// So the exit code is a hint and the repository is the evidence.
+			// The bar is deliberately high: registered under this exact path
+			// AND carrying the branch this call asked for. A registered path
+			// alone can be a half-finished checkout, or somebody else's.
+			if (!(await this.createdDespite(worktreePath, branch))) {
+				throw new WorkspaceBackendError({ op: 'create', kind: this.kind, cause })
+			}
+			this.log.warn('git-worktree add reported failure but the worktree is present', {
+				branch,
+				worktreePath,
+				cause: cause instanceof Error ? cause.message : String(cause),
+			})
 		}
 
 		const meta: GitWorktreeBackendMeta = {
@@ -142,6 +161,41 @@ export class GitWorktreeDriver implements WorkspaceBackendDriver {
 		}
 	}
 
+	/**
+	 * Did the worktree arrive despite the command reporting failure?
+	 *
+	 * Answers only for the branch this call created. A path registered
+	 * without that branch is not this call's worktree — it is a leftover
+	 * from a killed attempt, or a checkout somebody else owns, and the two
+	 * are indistinguishable from here. Claiming either would mean handing
+	 * a caller a workspace whose contents nobody vouched for, so both are
+	 * left to surface as the failure they are.
+	 *
+	 * Any error while checking is itself a "no". This runs on a path that
+	 * has already gone wrong once, and guessing optimistically there is how
+	 * a recovery turns a bad situation into a wrong one.
+	 */
+	private async createdDespite(worktreePath: string, branch: string): Promise<boolean> {
+		try {
+			const { stdout } = await this.exec('git', [
+				'-C',
+				this.repoRoot,
+				'worktree',
+				'list',
+				'--porcelain',
+			])
+			const entry = parseWorktreeList(stdout, worktreePath)
+			// `--porcelain` writes the branch as a full ref (`refs/heads/x`),
+			// and `branch` here is the short name this call passed to `-b`.
+			// Comparing them directly is a check that can never pass, which
+			// would make this whole recovery path silently dead — the exact
+			// shape it exists to catch.
+			return entry?.branch === `refs/heads/${branch}`
+		} catch {
+			return false
+		}
+	}
+
 	async inspect(ref: WorkspaceRef): Promise<WorkspaceInspection> {
 		let listStdout: string
 		try {

package/src/tools/builtins/bash.ts

@@ -60,6 +60,27 @@ const inputSchema = z.object({
 
 type BashInput = z.infer<typeof inputSchema>
 
+/**
+ * The last line worth showing from one chunk of streamed output.
+ *
+ * A progress line is a status, not a log: the host renders one line and
+ * replaces it as the next arrives, so sending a whole chunk sends a wall
+ * of text into a slot that shows one line of it. A chunk usually ends
+ * mid-line and usually ends with a newline, so the last NON-EMPTY line is
+ * the most recent complete thing the command actually said.
+ *
+ * Progress is capped rather than truncated with an ellipsis: this is
+ * glanced at, and a marker in a line nobody reads to the end is noise.
+ */
+function lastNonEmptyLine(chunk: string): string | undefined {
+	const lines = chunk.split('\n')
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const line = lines[i]?.trim()
+		if (line) return line.length > 160 ? line.slice(0, 160) : line
+	}
+	return undefined
+}
+
 function isDangerousCommand(command: string): boolean {
 	return DANGEROUS_PATTERNS.some((pattern) => pattern.test(command))
 }
@@ -114,6 +135,19 @@ export const BashTool = defineTool({
 				// Same reason as the host path below: a Stop must reach the
 				// process, not just the promise waiting on it.
 				signal: context.abortSignal,
+				// The worker has always streamed its output; nothing asked for
+				// it, so a command that ran for minutes said nothing until it
+				// exited. `report` is ephemeral by design — it answers "is it
+				// still working?" for a live view and is excluded from the
+				// durable transcript — so this is a progress signal, not a
+				// second copy of the output. `result.stdout` remains the
+				// answer the model is given.
+				onOutput: context.report
+					? ({ data }) => {
+							const line = lastNonEmptyLine(data)
+							if (line) context.report?.(line)
+						}
+					: undefined,
 			})
 
 			if (result.timedOut) {

package/src/tools/coordinator/agent.ts

@@ -7,6 +7,7 @@ import { defineTool } from '../defineTool.js'
 import { wrapUntrusted } from '../untrusted-envelope.js'
 import { failureLabel, taskSucceeded } from './outcome.js'
 
+import { DELEGATION_TIMEOUT_MS } from './index.js'
 import type { TaskLaunchedCallback } from './index.js'
 
 /**
@@ -107,6 +108,17 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 		readOnly: false,
 		destructive: false,
 		concurrencySafe: true,
+		// Declaring nothing here does not mean "no deadline"; it means the
+		// executor's 120-second default, which is a bound for a tool call and
+		// absurd for a whole agent run. `create_task` in the sibling module
+		// carries the same reasoning and the same hour, and the measurement
+		// behind that number is in its docblock: three delegated children took
+		// 4m21s, 5m58s and 8m04s, and all three parents gave up at 120s.
+		//
+		// This surface did not get that fix when its twin did, and the file's
+		// own note above records the pair doing exactly this before. The two
+		// tools are twins; a bound applied to one of them is not applied.
+		timeoutMs: DELEGATION_TIMEOUT_MS,
 		...(opts.terminal !== undefined ? { terminal: opts.terminal } : {}),
 		async execute({ description, prompt, subagent_type }, context) {
 			// With a single registered subagent the type is optional — default to

package/src/tools/coordinator/index.ts

@@ -157,6 +157,73 @@ const askUserQuestionModelInputSchema: Record<string, unknown> = {
 	additionalProperties: false,
 }
 
+/** One well-formed tag token: `<step>`, `</step>`, `<a href="…">`, `<br/>`. */
+const TAG_TOKEN = /<\/?[A-Za-z][\w-]*(?:\s[^<>]*)?\/?>/g
+const DESCRIPTION_BLOCK = /<description>([\s\S]*?)<\/description>/gi
+
+/**
+ * Remove every tag token, including the ones removing a tag creates.
+ *
+ * One pass is not enough and the reason is not obvious: deleting an inner
+ * tag can splice its neighbours into a new one. `<<step>step>` loses the
+ * inner `<step>` and the halves close up into `<step>` again, so a line
+ * that is nothing but markup comes back non-empty and is offered to a
+ * human as a step to approve — which is the exact outcome this whole path
+ * exists to prevent.
+ *
+ * Repeating to a fixed point terminates: every pass that changes the
+ * string removes at least one token and so strictly shortens it.
+ *
+ * Only ever used to ANSWER "is there anything here besides markup". The
+ * result is never shown to anyone, so this is a test rather than a
+ * sanitiser, and it does not have to defend against every way a tag can
+ * be spelled.
+ */
+function withoutTags(text: string): string {
+	let current = text
+	for (;;) {
+		const next = current.replace(TAG_TOKEN, '')
+		if (next === current) return current
+		current = next
+	}
+}
+
+/**
+ * Peel tag wrappers off the ENDS of one line, and nowhere else — a step
+ * that legitimately says "wrap it in a <div>" keeps its sentence.
+ */
+function unwrapStepLine(line: string): string {
+	let text = line.trim()
+	for (;;) {
+		const next = text
+			.replace(/^<[A-Za-z][\w-]*(?:\s[^<>]*)?>\s*/, '')
+			.replace(/\s*<\/[A-Za-z][\w-]*>$/, '')
+			.trim()
+		if (next === text) break
+		text = next
+	}
+	return text
+}
+
+/**
+ * A step list the model serialized instead of building.
+ *
+ * The line-splitting fallback below is the general case, and it had one
+ * shape badly wrong. A model that serializes this array tends to reach for
+ * MARKUP, not for prose:
+ *
+ *     <steps>
+ *     <step>
+ *     <description>Convert the document to Word</description>
+ *     </step>
+ *     </steps>
+ *
+ * Split on newlines, that is seven "steps", five of which are tags. A host
+ * then numbered them in an approval card and asked a person to approve
+ * `</steps>` — reported from a real run. The descriptions the model named
+ * are right there, so read them; fall back to lines only when there are
+ * none, and drop the lines that carry no words at all.
+ */
 function normalizeApprovePlanSteps(value: unknown): unknown {
 	if (typeof value !== 'string') return value
 
@@ -171,19 +238,84 @@ function normalizeApprovePlanSteps(value: unknown): unknown {
 		}
 	}
 
+	const described = [...trimmed.matchAll(DESCRIPTION_BLOCK)]
+		.map((match) => (match[1] ?? '').trim())
+		.filter(Boolean)
+	if (described.length > 0) {
+		return described.map((description) => ({ description }))
+	}
+
 	const lines = trimmed
 		.split(/\r?\n+/)
 		.map((line) =>
-			line
-				.trim()
-				.replace(/^(?:[-*•]|\d+[.)])\s*/, '')
-				.trim(),
+			unwrapStepLine(
+				line
+					.trim()
+					.replace(/^(?:[-*•]|\d+[.)])\s*/, '')
+					.trim(),
+			),
 		)
-		.filter(Boolean)
+		.filter((line) => line.length > 0 && withoutTags(line).trim().length > 0)
+
+	// Every line was markup: there is no plan in this string, and inventing
+	// one step reading `<steps>` is worse than saying so.
+	if (lines.length === 0) {
+		return withoutTags(unwrapStepLine(trimmed)).trim()
+			? [{ description: unwrapStepLine(trimmed) }]
+			: []
+	}
 
-	return (lines.length ? lines : [trimmed]).map((description) => ({
-		description,
-	}))
+	return lines.map((description) => ({ description }))
+}
+
+/**
+ * The single closed shape a capable provider constrains this call to —
+ * the same instrument `ask_user_question` carries, for the same failure.
+ *
+ * `steps` arriving as a STRING is what everything above exists to survive,
+ * and surviving it is not the same as preventing it: the normalizer can
+ * only guess at a structure the model already threw away. Advertising the
+ * closed shape turns the guess into a refusal at generation time.
+ */
+const approvePlanModelInputSchema: Record<string, unknown> = {
+	type: 'object',
+	properties: {
+		title: {
+			type: 'string',
+			description: 'Short title for the plan (e.g. "TypeScript Security & Performance Review").',
+		},
+		summary: {
+			type: 'string',
+			description: '1-3 sentence summary of what you plan to do.',
+		},
+		steps: {
+			type: 'array',
+			description:
+				'A JSON array of ordered step objects. Never a string, and never markup — no <step> or <description> tags.',
+			items: {
+				type: 'object',
+				properties: {
+					description: {
+						type: 'string',
+						description: 'What this step does, as one plain sentence a person can read.',
+					},
+					agent_id: {
+						type: 'string',
+						description: 'Which agent handles this; omit for steps you carry out yourself.',
+					},
+					depends_on: {
+						type: 'array',
+						items: { type: 'string' },
+						description: 'Descriptions of the steps that must finish before this one.',
+					},
+				},
+				required: ['description'],
+				additionalProperties: false,
+			},
+		},
+	},
+	required: ['title', 'summary', 'steps'],
+	additionalProperties: false,
 }
 
 /**
@@ -1013,6 +1145,10 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					.preprocess(normalizeApprovePlanSteps, z.array(approvePlanStepSchema))
 					.describe('Ordered list of planned steps'),
 			}),
+			modelInputSchema: structuredClone(approvePlanModelInputSchema),
+			enforceModelInput: true,
+			validationErrorHint:
+				'Required shape: {"title":"…","summary":"…","steps":[{"description":"One plain sentence"}]}. "steps" must be a JSON array of objects — never a string, and never markup such as <step> or <description>.',
 			category: 'custom',
 			permissions: [],
 			readOnly: true,

package/src/types/connector/mcp.ts

@@ -18,7 +18,24 @@ export interface MCPStdioTransportConfig extends MCPTransportConfigBase {
 	type: 'stdio'
 	command: string
 	args?: string[]
+	/** Literal values for the child. Highest precedence. */
 	env?: Record<string, string>
+	/**
+	 * Parent variables the child may have, named one at a time.
+	 *
+	 * The spawn used to pass the whole parent environment, so a server that
+	 * needed one token received every credential the host held. It now gets
+	 * process plumbing plus what is named here and in `env`, which is what
+	 * makes the grant reviewable: the config says which secrets cross the
+	 * boundary instead of the answer being "all of them".
+	 *
+	 * Use this rather than `env` for a credential — `env` puts the value in the
+	 * config file, and this keeps it in the environment where it already lives.
+	 *
+	 * A name the parent does not hold is absent from the child rather than
+	 * empty, and does not fail the spawn.
+	 */
+	inheritEnv?: readonly string[]
 	cwd?: string
 }
 

package/src/types/provider/interface.ts

@@ -73,7 +73,23 @@ export interface LLMProvider {
 	 */
 	probeCredential?(): Promise<void>
 
-	healthCheck?(): Promise<boolean>
+	/**
+	 * Is this driver able to serve traffic? A summary bit; `doctorCheck` is
+	 * the same probe with its reasoning intact.
+	 *
+	 * `model` is the model the CALLER intends to run, and it is a parameter
+	 * rather than something the driver reads off its own config because at
+	 * least one driver's config does not carry a model at all. That driver
+	 * hardcoded an id instead, which is how its check came to probe a model
+	 * nobody used — and, once the id went stale, could not pass at any
+	 * credential, region or service state. A health check against a model the
+	 * operator does not run tests the wrong thing even while the id is valid.
+	 *
+	 * Optional, and a driver may ignore it: one that probes an endpoint rather
+	 * than a model has nothing to do with the argument. Passing it is always
+	 * safe.
+	 */
+	healthCheck?(model?: string): Promise<boolean>
 
 	/**
 	 * Optional structured health probe used by `runDoctor()`.
@@ -82,8 +98,13 @@ export interface LLMProvider {
 	 * (latency, model availability, auth status, …). Providers that
 	 * cannot be cheaply probed should return `{ status: 'inconclusive' }`
 	 * so the doctor doesn't mark them as failing — see ses_007 Q6.4.
+	 *
+	 * Takes `model` for the reason `healthCheck` does, and a driver is free to
+	 * return a SUBTYPE of `DoctorCheckResult` carrying its own machine-readable
+	 * detail. `status` is what `runDoctor()` reads; a caller holding the
+	 * concrete driver can read more.
 	 */
-	doctorCheck?(): Promise<DoctorCheckResult>
+	doctorCheck?(model?: string): Promise<DoctorCheckResult>
 
 	/**
 	 * Which {@link ChatCompletionParams.effort} levels this model accepts,

package/src/types/sandbox/index.ts

@@ -103,6 +103,29 @@ export interface SandboxExecOptions {
 	readonly timeout?: number
 	readonly env?: Record<string, string>
 	readonly cwd?: string
+	/**
+	 * Called as output arrives, before the command has finished.
+	 *
+	 * Every container-tier worker already streams its output a chunk at a
+	 * time — the wire carries `stdout_delta` and `stderr_delta` events —
+	 * and every backend concatenated them into a string and returned that
+	 * when the process exited. So a command that takes eight minutes said
+	 * nothing for eight minutes, on a transport that had been reporting
+	 * the whole time.
+	 *
+	 * Additive and optional: a backend that cannot stream simply never
+	 * calls it, and `SandboxExecResult.stdout` still carries the complete
+	 * output either way. A caller that wants only the result ignores this
+	 * and behaves exactly as before.
+	 *
+	 * The callback must not throw and must not be awaited — it is on the
+	 * read path of a running process, so a slow or failing consumer would
+	 * otherwise become a slow or failing command.
+	 */
+	readonly onOutput?: (chunk: {
+		readonly stream: 'stdout' | 'stderr'
+		readonly data: string
+	}) => void
 	/**
 	 * Cancellation for the command. A backend that honours it kills the
 	 * process; one that does not simply ignores it, so this is additive.