@namzu/sdk 32.0.0 → 33.1.0

package/src/execution/local.ts

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { killTree } from '../process/kill-tree.js'
 import type { LocalExecutionContextConfig } from '../types/connector/index.js'
 import type {
 	CommandExecutor,
@@ -9,8 +10,22 @@ import type {
 	ExecutionCapability,
 	ExecutionEnvironment,
 } from '../types/execution/index.js'
+import { subscribeToAbort } from '../utils/abort.js'
 import type { Logger } from '../utils/logger.js'
 import { BaseExecutionContext } from './base.js'
+import { BoundedTailCapture } from './output.js'
+
+const LOCAL_COMMAND_DEFAULT_TIMEOUT_MS = 30_000
+const LOCAL_COMMAND_KILL_GRACE_MS = 3_000
+const LOCAL_COMMAND_DEFAULT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024
+const LOCAL_COMMAND_HARD_MAX_OUTPUT_BYTES = 64 * 1024 * 1024
+
+type LocalCommandCancellation = 'caller' | 'deadline' | 'teardown'
+
+interface ActiveLocalCommand {
+	readonly closed: Promise<void>
+	cancel(origin: LocalCommandCancellation): void
+}
 
 export interface LocalExecutionContextOptions {
 	id: string
@@ -19,6 +34,8 @@ export interface LocalExecutionContextOptions {
 	envVars?: Record<string, string>
 	capabilities?: ExecutionCapability[]
 	shell?: string
+	/** Retained bytes per stdout/stderr stream. Defaults to 4 MiB; maximum 64 MiB. */
+	maxOutputBytes?: number
 	log?: Logger
 }
 
@@ -31,6 +48,14 @@ export class LocalExecutionContext extends BaseExecutionContext implements Comma
 	private envVars: Record<string, string>
 	private capabilities: ExecutionCapability[]
 	private shell: string | undefined
+	private maxOutputBytes: number
+	/**
+	 * Constructor-created contexts are intentionally executable before
+	 * `initialize()`: `createCommandGate()` has always used that public path.
+	 * Teardown closes admission synchronously; an explicit initialize reopens it.
+	 */
+	private acceptsCommands = true
+	private readonly activeCommands = new Set<ActiveLocalCommand>()
 
 	constructor(options: LocalExecutionContextOptions) {
 		super(options.log)
@@ -40,6 +65,17 @@ export class LocalExecutionContext extends BaseExecutionContext implements Comma
 		this.envVars = options.envVars ?? {}
 		this.capabilities = options.capabilities ?? ['filesystem', 'process', 'shell']
 		this.shell = options.shell
+		const maxOutputBytes = options.maxOutputBytes ?? LOCAL_COMMAND_DEFAULT_MAX_OUTPUT_BYTES
+		if (
+			!Number.isSafeInteger(maxOutputBytes) ||
+			maxOutputBytes <= 0 ||
+			maxOutputBytes > LOCAL_COMMAND_HARD_MAX_OUTPUT_BYTES
+		) {
+			throw new RangeError(
+				`The value of "maxOutputBytes" is out of range. It must be a positive safe integer no greater than ${LOCAL_COMMAND_HARD_MAX_OUTPUT_BYTES}. Received ${maxOutputBytes}`,
+			)
+		}
+		this.maxOutputBytes = maxOutputBytes
 	}
 
 	protected async doInitialize(): Promise<void> {
@@ -49,7 +85,23 @@ export class LocalExecutionContext extends BaseExecutionContext implements Comma
 		this.log.info('Local context initialized', { 'namzu.execution.cwd': this.cwd })
 	}
 
-	protected async doTeardown(): Promise<void> {}
+	protected override onInitializationStarted(): void {
+		this.acceptsCommands = false
+	}
+
+	protected override onInitializationCommitted(): void {
+		this.acceptsCommands = true
+	}
+
+	protected override onTeardownRequested(): void {
+		this.acceptsCommands = false
+	}
+
+	protected async doTeardown(): Promise<void> {
+		const admitted = [...this.activeCommands]
+		for (const operation of admitted) operation.cancel('teardown')
+		await Promise.all(admitted.map((operation) => operation.closed))
+	}
 
 	getCwd(): string {
 		return this.cwd
@@ -92,63 +144,155 @@ export class LocalExecutionContext extends BaseExecutionContext implements Comma
 		args: string[] = [],
 		options?: CommandOptions,
 	): Promise<CommandResult> {
+		if (!this.acceptsCommands) {
+			throw new Error(
+				`Local execution context "${this.id}" is tearing down or torn down. Call initialize() before executing another command.`,
+			)
+		}
 		if (!this.hasCapability('process') && !this.hasCapability('shell')) {
 			return {
 				exitCode: 1,
 				stdout: '',
 				stderr: 'Command execution not available: context lacks process/shell capability',
+				stdoutTruncated: false,
+				stderrTruncated: false,
 				durationMs: 0,
 			}
 		}
 
 		const cwd = options?.cwd ? resolve(this.cwd, options.cwd) : this.cwd
 		const env = { ...process.env, ...this.envVars, ...options?.env }
-		const timeoutMs = options?.timeoutMs ?? 30_000
+		const timeoutMs = options?.timeoutMs ?? LOCAL_COMMAND_DEFAULT_TIMEOUT_MS
+		if (!Number.isInteger(timeoutMs) || timeoutMs < 0) {
+			throw new RangeError(
+				`The value of "timeoutMs" is out of range. It must be an unsigned integer. Received ${timeoutMs}`,
+			)
+		}
 		// node's spawn() only keeps argv separation when it execs the binary directly;
 		// with shell enabled it re-joins command+args into one unescaped string and hands
 		// it to sh/cmd.exe, so any caller-supplied arg becomes shell syntax rather than a
 		// literal value. Since `command`/`args` here are whatever a tool call passed in,
 		// shell interpretation must be an explicit opt-in, never the silent default.
 		const shell = options?.shell ?? this.shell ?? false
+		const callerSignal = options?.signal
+		if (callerSignal?.aborted) {
+			return {
+				exitCode: null,
+				stdout: '',
+				stderr: '',
+				stdoutTruncated: false,
+				stderrTruncated: false,
+				durationMs: 0,
+				termination: { origin: 'caller', admitted: false },
+			}
+		}
 
-		return new Promise<CommandResult>((resolvePromise) => {
+		let operation: ActiveLocalCommand
+		const result = new Promise<CommandResult>((resolvePromise) => {
 			const start = performance.now()
 			const proc = spawn(command, args, {
 				cwd,
 				env,
 				shell,
-				timeout: timeoutMs,
+				// POSIX process-group ownership is the strongest boundary available
+				// to this host execution context. Windows uses taskkill /T in
+				// `killTree`; neither path relies on Node's direct-child timeout.
+				detached: process.platform !== 'win32',
 			})
 
-			let stdout = ''
-			let stderr = ''
+			const stdout = new BoundedTailCapture(this.maxOutputBytes)
+			const stderr = new BoundedTailCapture(this.maxOutputBytes)
+			let spawnError: Error | undefined
+			let cancellation: LocalCommandCancellation | undefined
+			let escalation: ReturnType<typeof setTimeout> | undefined
+			let deadline: ReturnType<typeof setTimeout> | undefined
+			let disposeCallerAbort: (() => void) | undefined
+			let settled = false
+
+			const terminate = (signal: NodeJS.Signals): void => {
+				killTree(proc, signal)
+			}
+			const cancel = (origin: LocalCommandCancellation): void => {
+				if (settled || cancellation !== undefined) return
+				cancellation = origin
+				terminate('SIGTERM')
+				escalation = setTimeout(() => {
+					escalation = undefined
+					terminate('SIGKILL')
+				}, LOCAL_COMMAND_KILL_GRACE_MS)
+				escalation.unref?.()
+			}
+
+			let resolveClosed: (() => void) | undefined
+			const closed = new Promise<void>((resolveClose) => {
+				resolveClosed = resolveClose
+			})
+			operation = { cancel, closed }
+			this.activeCommands.add(operation)
+
+			if (timeoutMs > 0) {
+				deadline = setTimeout(() => cancel('deadline'), timeoutMs)
+				deadline.unref?.()
+			}
 
 			proc.stdout?.on('data', (data: Buffer) => {
-				stdout += data.toString()
+				stdout.push(data)
 			})
 
 			proc.stderr?.on('data', (data: Buffer) => {
-				stderr += data.toString()
+				stderr.push(data)
 			})
 
-			proc.on('close', (code) => {
-				resolvePromise({
-					exitCode: code ?? 1,
-					stdout,
-					stderr,
-					durationMs: Math.round(performance.now() - start),
-				})
+			proc.once('error', (err) => {
+				// `close` follows `error` and is the point at which inherited stdio
+				// has drained. Releasing ownership here would strand a descendant
+				// which still holds those descriptors.
+				spawnError = err
 			})
 
-			proc.on('error', (err) => {
+			proc.once('close', (code, signal) => {
+				if (settled) return
+				settled = true
+				disposeCallerAbort?.()
+				if (deadline !== undefined) clearTimeout(deadline)
+				if (escalation !== undefined) {
+					clearTimeout(escalation)
+					escalation = undefined
+					// Do not retain a numeric process-group id for a later timer after
+					// close: the host can reuse it. Force the cancellation boundary now.
+					terminate('SIGKILL')
+				}
+				this.activeCommands.delete(operation)
+				resolveClosed?.()
+				if (spawnError !== undefined) {
+					if (stderr.retainedBytes > 0) stderr.push(Buffer.from('\n'))
+					stderr.push(Buffer.from(spawnError.message))
+				}
 				resolvePromise({
-					exitCode: 1,
-					stdout,
-					stderr: err.message,
+					exitCode: spawnError === undefined ? code : 1,
+					stdout: stdout.text,
+					stderr: stderr.text,
+					stdoutTruncated: stdout.truncated,
+					stderrTruncated: stderr.truncated,
 					durationMs: Math.round(performance.now() - start),
+					...(cancellation === undefined
+						? {}
+						: {
+								termination: {
+									origin: cancellation === 'deadline' ? ('timeout' as const) : cancellation,
+									admitted: true as const,
+									...(signal === null ? {} : { signal }),
+								},
+							}),
 				})
 			})
+
+			if (callerSignal !== undefined) {
+				disposeCallerAbort = subscribeToAbort(callerSignal, () => cancel('caller'))
+				if (callerSignal.aborted) cancel('caller')
+			}
 		})
+		return result
 	}
 
 	toConfig(): LocalExecutionContextConfig {
@@ -160,6 +304,7 @@ export class LocalExecutionContext extends BaseExecutionContext implements Comma
 			envVars: this.envVars,
 			capabilities: this.capabilities,
 			shell: this.shell,
+			maxOutputBytes: this.maxOutputBytes,
 		}
 	}
 }

package/src/execution/output.ts

@@ -0,0 +1,104 @@
+/**
+ * Retain the newest bytes of one command-output stream under a hard bound.
+ *
+ * Bytes stay undecoded until the command closes, so a UTF-8 code point split
+ * across ordinary stream chunks is not corrupted. The backing store grows
+ * geometrically up to the configured cap and becomes a ring only when output
+ * crosses it; no incoming chunk is retained by reference.
+ */
+export class BoundedTailCapture {
+	private storage = Buffer.alloc(0)
+	private start = 0
+	private length = 0
+	private lostBytes = false
+
+	constructor(private readonly capBytes: number) {
+		if (!Number.isSafeInteger(capBytes) || capBytes <= 0) {
+			throw new RangeError('BoundedTailCapture capBytes must be a positive safe integer')
+		}
+	}
+
+	push(chunk: Buffer): void {
+		if (chunk.length === 0) return
+
+		if (chunk.length >= this.capBytes) {
+			if (chunk.length > this.capBytes || this.length > 0) this.lostBytes = true
+			this.ensureCapacity(this.capBytes)
+			chunk.copy(this.storage, 0, chunk.length - this.capBytes)
+			this.start = 0
+			this.length = this.capBytes
+			return
+		}
+
+		const combinedLength = this.length + chunk.length
+		if (combinedLength <= this.capBytes) {
+			this.ensureCapacity(combinedLength)
+			chunk.copy(this.storage, this.length)
+			this.length = combinedLength
+			return
+		}
+
+		this.lostBytes = true
+		this.ensureCapacity(this.capBytes)
+		const end = (this.start + this.length) % this.capBytes
+		const first = Math.min(chunk.length, this.capBytes - end)
+		chunk.copy(this.storage, end, 0, first)
+		if (first < chunk.length) chunk.copy(this.storage, 0, first)
+		this.start = (this.start + combinedLength - this.capBytes) % this.capBytes
+		this.length = this.capBytes
+	}
+
+	/** Ordered copy of the retained raw bytes. */
+	get bytes(): Buffer {
+		const ordered = Buffer.allocUnsafe(this.length)
+		if (this.length === 0) return ordered
+		const first = Math.min(this.length, this.storage.length - this.start)
+		this.storage.copy(ordered, 0, this.start, this.start + first)
+		if (first < this.length) this.storage.copy(ordered, first, 0, this.length - first)
+		return ordered
+	}
+
+	get text(): string {
+		const ordered = this.bytes
+		let offset = 0
+		// Tail eviction can leave continuation bytes from a valid UTF-8 code
+		// point at the new left edge. They are an artifact of the cut, not an
+		// authored replacement character, so discard only that partial prefix.
+		if (this.lostBytes) {
+			while (offset < ordered.length) {
+				const firstByte = ordered[offset]
+				if (firstByte === undefined || (firstByte & 0xc0) !== 0x80) break
+				offset++
+			}
+		}
+		return ordered.toString('utf8', offset)
+	}
+
+	get truncated(): boolean {
+		return this.lostBytes
+	}
+
+	/** Diagnostic invariant used by the internal killing observers. */
+	get retainedBytes(): number {
+		return this.length
+	}
+
+	/** Diagnostic invariant used by the internal killing observers. */
+	get allocatedBytes(): number {
+		return this.storage.length
+	}
+
+	private ensureCapacity(required: number): void {
+		if (this.storage.length >= required) return
+		let capacity = Math.max(1, this.storage.length)
+		while (capacity < required) capacity = Math.min(this.capBytes, capacity * 2)
+		const grown = Buffer.allocUnsafe(capacity)
+		if (this.length > 0) {
+			const first = Math.min(this.length, this.storage.length - this.start)
+			this.storage.copy(grown, 0, this.start, this.start + first)
+			if (first < this.length) this.storage.copy(grown, first, 0, this.length - first)
+		}
+		this.storage = grown
+		this.start = 0
+	}
+}

package/src/execution/remote.ts

@@ -1,4 +1,5 @@
 import type {
+	CommandExecutor,
 	CommandOptions,
 	CommandResult,
 	ExecutionCapability,
@@ -9,29 +10,41 @@ import type {
 } from '../types/connector/index.js'
 import type { Logger } from '../utils/logger.js'
 import { BaseExecutionContext } from './base.js'
+import { CommandCancellationUnsupportedError, RemoteExecutionBusyError } from './errors.js'
 
 export interface RemoteExecutionContextOptions {
 	id: string
 	target: RemoteTarget
 	capabilities?: ExecutionCapability[]
+	/**
+	 * Executes a command while preserving its argument boundaries at Namzu's
+	 * remote seam. A downstream executor may still interpret `shell` according
+	 * to its own target.
+	 */
+	commandExecutor?: CommandExecutor
+	/** @deprecated Use `commandExecutor`. */
 	commandHandler?: RemoteCommandHandler
 	log?: Logger
 }
 
-export class RemoteExecutionContext extends BaseExecutionContext {
+export class RemoteExecutionContext extends BaseExecutionContext implements CommandExecutor {
 	readonly id: string
 	readonly environment: ExecutionEnvironment = 'remote'
 
 	private target: RemoteTarget
 	private connected = false
 	private capabilities: ExecutionCapability[]
+	private commandExecutor: CommandExecutor | undefined
 	private commandHandler: RemoteCommandHandler | undefined
+	private lifecycleAdmissionsOpen = true
+	private readonly activeCommands = new Set<symbol>()
 
 	constructor(options: RemoteExecutionContextOptions) {
 		super(options.log)
 		this.id = options.id
 		this.target = options.target
 		this.capabilities = options.capabilities ?? ['network']
+		this.commandExecutor = options.commandExecutor
 		this.commandHandler = options.commandHandler
 	}
 
@@ -43,18 +56,30 @@ export class RemoteExecutionContext extends BaseExecutionContext {
 		})
 	}
 
+	protected override onInitializationStarted(): void {
+		this.lifecycleAdmissionsOpen = false
+	}
+
+	protected override onInitializationCommitted(): void {
+		this.lifecycleAdmissionsOpen = true
+	}
+
+	protected override onTeardownRequested(): void {
+		this.lifecycleAdmissionsOpen = false
+	}
+
 	protected async doTeardown(): Promise<void> {
-		if (this.connected) {
-			this.connected = false
-			this.emit({
-				type: 'remote_disconnected',
-				contextId: this.id,
-				host: this.target.host,
-			})
-		}
+		this.assertIdleForDisconnect()
+		await this.disconnect()
 	}
 
 	async connect(): Promise<void> {
+		if (!this.lifecycleAdmissionsOpen) {
+			throw new Error(
+				`Remote execution context "${this.id}" cannot connect until initialization commits after teardown or failed initialization.`,
+			)
+		}
+		if (this.connected) return
 		this.connected = true
 		this.emit({
 			type: 'remote_connected',
@@ -70,6 +95,7 @@ export class RemoteExecutionContext extends BaseExecutionContext {
 
 	async disconnect(): Promise<void> {
 		if (!this.connected) return
+		this.assertIdleForDisconnect()
 		this.connected = false
 		this.emit({
 			type: 'remote_disconnected',
@@ -100,20 +126,49 @@ export class RemoteExecutionContext extends BaseExecutionContext {
 		return this.capabilities.includes(cap)
 	}
 
+	setCommandExecutor(executor: CommandExecutor): void {
+		this.commandExecutor = executor
+	}
+
+	/** @deprecated Use `setCommandExecutor()`. */
 	setCommandHandler(handler: RemoteCommandHandler): void {
 		this.commandHandler = handler
 	}
 
-	async executeRemote(command: string, options?: CommandOptions): Promise<CommandResult> {
-		if (!this.commandHandler) {
-			throw new Error(
-				`No remote command handler configured for context "${this.id}". Set one via setCommandHandler() before calling executeRemote().`,
+	async executeCommand(
+		command: string,
+		args: string[] = [],
+		options?: CommandOptions,
+	): Promise<CommandResult> {
+		if (this.commandExecutor) {
+			const executor = this.admitCommand(
+				this.commandExecutor,
+				`No remote command executor configured for context "${this.id}". Set one via setCommandExecutor() before calling executeCommand().`,
 			)
+			this.assertCancellationUnsupported(options?.signal)
+			return this.trackCommand(() => executor.executeCommand(command, args, options))
 		}
-		if (!this.connected) {
-			throw new Error(`Remote context "${this.id}" is not connected. Call connect() first.`)
-		}
-		return this.commandHandler.executeRemote(command, options)
+
+		const handler = this.admitCommand(
+			this.commandHandler,
+			`No remote command executor configured for context "${this.id}". Set one via setCommandExecutor() before calling executeCommand().`,
+		)
+		this.assertCancellationUnsupported(options?.signal)
+		const fullCommand = args.length > 0 ? `${command} ${args.join(' ')}` : command
+		return this.trackCommand(() => handler.executeRemote(fullCommand, options))
+	}
+
+	/**
+	 * @deprecated Use `executeCommand()` so command arguments retain their
+	 * boundaries at Namzu's remote execution seam.
+	 */
+	async executeRemote(command: string, options?: CommandOptions): Promise<CommandResult> {
+		const handler = this.admitCommand(
+			this.commandHandler,
+			`No remote command handler configured for context "${this.id}". Set one via setCommandHandler() before calling executeRemote().`,
+		)
+		this.assertCancellationUnsupported(options?.signal)
+		return this.trackCommand(() => handler.executeRemote(command, options))
 	}
 
 	toConfig(): RemoteExecutionContextConfig {
@@ -133,4 +188,54 @@ export class RemoteExecutionContext extends BaseExecutionContext {
 			throw new Error(`Unsupported remote target type: "${target.type}"`)
 		}
 	}
+
+	private admitCommand<T>(implementation: T | undefined, missingMessage: string): T {
+		if (implementation === undefined) throw new Error(missingMessage)
+		if (!this.lifecycleAdmissionsOpen) {
+			throw new Error(
+				`Remote execution context "${this.id}" is initializing, tearing down, or torn down. Wait for initialization to commit before executing another command.`,
+			)
+		}
+		if (!this.connected) {
+			throw new Error(`Remote context "${this.id}" is not connected. Call connect() first.`)
+		}
+		return implementation
+	}
+
+	private assertCancellationUnsupported(signal: AbortSignal | undefined): void {
+		if (signal !== undefined) throw new CommandCancellationUnsupportedError(this.id)
+	}
+
+	private assertIdleForDisconnect(): void {
+		if (this.activeCommands.size > 0) {
+			throw new RemoteExecutionBusyError(this.id, this.activeCommands.size)
+		}
+	}
+
+	private trackCommand(invoke: () => Promise<CommandResult>): Promise<CommandResult> {
+		const ownership = Symbol('remote-command')
+		this.activeCommands.add(ownership)
+		const release = (): void => {
+			this.activeCommands.delete(ownership)
+		}
+
+		let operation: Promise<CommandResult>
+		try {
+			operation = Promise.resolve(invoke())
+		} catch (error) {
+			release()
+			return Promise.reject(error)
+		}
+
+		return operation.then(
+			(result) => {
+				release()
+				return result
+			},
+			(error: unknown) => {
+				release()
+				throw error
+			},
+		)
+	}
 }

package/src/plugin/lifecycle.ts

@@ -711,6 +711,12 @@ export class PluginLifecycleManager {
 		}
 
 		const results: PluginHookResult[] = []
+		// Interrupt hooks are cleanup/notification observers. One extension's
+		// skip, error, retry, or timeout must not suppress the extensions that
+		// follow it, and none of those results can change the cancellation that
+		// already happened. Other hook events retain their existing flow-control
+		// semantics.
+		const observationalFanOut = event === 'run_interrupt'
 
 		// Determine execution order: post_* hooks run backward (for cleanup semantics)
 		const isPost = event.startsWith('post_')
@@ -830,16 +836,16 @@ export class PluginLifecycleManager {
 
 			results.push(result)
 
-			if (result.action === 'modify') {
+			if (!observationalFanOut && result.action === 'modify') {
 				toolInputOverlay = result.input
 			}
 
 			// Handle flow control: check priority order: error > skip > retry > resume > modify > continue
 			// Short-circuit on error or skip; return immediately on resume or retry
-			if (result.action === 'error' || result.action === 'skip') {
+			if (!observationalFanOut && (result.action === 'error' || result.action === 'skip')) {
 				break
 			}
-			if (result.action === 'retry') {
+			if (!observationalFanOut && result.action === 'retry') {
 				break
 			}
 		}

package/src/process/kill-tree.ts

@@ -10,23 +10,21 @@ import type { spawn } from 'node:child_process'
  * paid for by a bug where a cancelled command kept running, and a
  * near-copy would reproduce the bug in the copy.
  *
- * Every caller reaches a real command through `/bin/sh -c "cmd"`, and under
- * the local sandbox's `linux-namespace`/`macos-seatbelt` tiers that shell is
- * wrapped again (`unshare …`/`sandbox-exec … -- /bin/sh -c "cmd"`). Either
- * way, `child.pid` names the OUTERMOST wrapper Node spawned, not `cmd` —
- * signalling only that pid, which is both what `child.kill()` does and what
- * `spawn`'s own `signal` option does internally on abort, reaps the wrapper
- * and leaves `cmd`, and anything it forked, running past both a cancel and a
- * timeout.
+ * Some callers reach a command through a shell or isolation wrapper; the
+ * local execution context can also spawn the authored executable directly.
+ * In every case, signalling only `child.pid` — which is both what
+ * `child.kill()` does and what `spawn`'s own `signal`/`timeout` options do —
+ * can reap that direct child while leaving a descendant running past both a
+ * cancel and a timeout.
  *
  * POSIX: the caller must spawn with `detached: true`, which makes the child
  * the leader of a new process group (pgid === pid) instead of joining this
  * Node process's own. A negative pid signals that whole group in one call.
- * Group membership is a host-kernel fact that a fork()'d descendant inherits
- * from its parent whether or not it — or an ancestor such as `unshare --pid`
- * — subsequently entered a new PID namespace, so this reaches `cmd` and its
- * descendants along with the wrapper itself even under the namespaced
- * isolation tiers.
+ * Group membership is a host-kernel fact that an ordinary forked descendant
+ * inherits from its parent, including under the namespaced isolation tiers.
+ * A process which deliberately starts a new session/process group can escape
+ * this boundary; this helper is process-group signalling, not a portable
+ * arbitrary-descendant ownership primitive.
  *
  * Windows has no process-group id to sign a kill with — `process.kill` with
  * a negative pid there either throws or silently does nothing, depending on

package/src/provider/capabilities.ts

@@ -10,6 +10,8 @@ export interface ResolvedProviderCapabilities {
 	supportsFunctionCalling: boolean
 	supportsVision: boolean
 	supportsDocuments: boolean
+	supportsToolResultImages: boolean
+	supportsToolResultDocuments: boolean
 	maxOutputTokens?: number
 }
 
@@ -25,6 +27,8 @@ export const PERMISSIVE_PROVIDER_CAPABILITIES: ResolvedProviderCapabilities = {
 	supportsFunctionCalling: true,
 	supportsVision: true,
 	supportsDocuments: true,
+	supportsToolResultImages: true,
+	supportsToolResultDocuments: true,
 }
 
 /**
@@ -46,6 +50,12 @@ export function resolveProviderCapabilities(
 		supportsVision: declared?.supportsVision ?? PERMISSIVE_PROVIDER_CAPABILITIES.supportsVision,
 		supportsDocuments:
 			declared?.supportsDocuments ?? PERMISSIVE_PROVIDER_CAPABILITIES.supportsDocuments,
+		supportsToolResultImages:
+			declared?.supportsToolResultImages ??
+			PERMISSIVE_PROVIDER_CAPABILITIES.supportsToolResultImages,
+		supportsToolResultDocuments:
+			declared?.supportsToolResultDocuments ??
+			PERMISSIVE_PROVIDER_CAPABILITIES.supportsToolResultDocuments,
 		maxOutputTokens: declared?.maxOutputTokens,
 	}
 }