@namzu/sdk 32.0.0 → 33.0.0

package/src/execution/hybrid.ts

@@ -21,6 +21,7 @@ export interface HybridExecutionContextOptions {
 		envVars?: Record<string, string>
 		capabilities?: ExecutionCapability[]
 		shell?: string
+		maxOutputBytes?: number
 	}
 	remotes: RemoteTarget[]
 	routingStrategy?: ExecutionRoutingStrategy
@@ -36,6 +37,7 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 	private remoteTargets: RemoteTarget[]
 	private routingStrategy: ExecutionRoutingStrategy
 	private roundRobinIndex = 0
+	private admissionsOpen = true
 
 	constructor(options: HybridExecutionContextOptions) {
 		super(options.log)
@@ -50,6 +52,7 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 			envVars: options.local.envVars,
 			capabilities: options.local.capabilities,
 			shell: options.local.shell,
+			maxOutputBytes: options.local.maxOutputBytes,
 			log: options.log,
 		})
 
@@ -83,13 +86,29 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 		})
 	}
 
+	protected override onInitializationStarted(): void {
+		this.admissionsOpen = false
+	}
+
+	protected override onInitializationCommitted(): void {
+		this.admissionsOpen = true
+	}
+
+	protected override onTeardownRequested(): void {
+		this.admissionsOpen = false
+	}
+
 	protected async doTeardown(): Promise<void> {
-		const teardownPromises: Promise<void>[] = []
-		for (const remote of this.remoteCtxs.values()) {
-			teardownPromises.push(remote.teardown())
+		const contexts: BaseExecutionContext[] = [this.localCtx, ...this.remoteCtxs.values()]
+		const results = await Promise.allSettled(contexts.map((context) => context.teardown()))
+		const failures = results.flatMap((result) =>
+			result.status === 'rejected' ? [result.reason] : [],
+		)
+
+		if (failures.length === 1) throw failures[0]
+		if (failures.length > 1) {
+			throw new AggregateError(failures, 'Multiple hybrid execution contexts failed to tear down')
 		}
-		await Promise.allSettled(teardownPromises)
-		await this.localCtx.teardown()
 	}
 
 	getLocal(): LocalExecutionContext {
@@ -122,11 +141,16 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 	}
 
 	async disconnectAllRemotes(): Promise<void> {
-		const promises: Promise<void>[] = []
-		for (const remote of this.remoteCtxs.values()) {
-			promises.push(remote.disconnect())
+		const results = await Promise.allSettled(
+			Array.from(this.remoteCtxs.values(), (remote) => remote.disconnect()),
+		)
+		const failures = results.flatMap((result) =>
+			result.status === 'rejected' ? [result.reason] : [],
+		)
+		if (failures.length === 1) throw failures[0]
+		if (failures.length > 1) {
+			throw new AggregateError(failures, 'Multiple remote execution contexts failed to disconnect')
 		}
-		await Promise.allSettled(promises)
 	}
 
 	async executeCommand(
@@ -134,6 +158,11 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 		args: string[] = [],
 		options?: CommandOptions,
 	): Promise<CommandResult> {
+		if (!this.admissionsOpen) {
+			throw new Error(
+				`Hybrid execution context "${this.id}" is initializing, tearing down, or torn down. Wait for initialization to commit before executing another command.`,
+			)
+		}
 		switch (this.routingStrategy) {
 			case 'local-first':
 				return this.localCtx.executeCommand(command, args, options)
@@ -141,8 +170,7 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 			case 'remote-first': {
 				const connectedRemote = this.getFirstConnectedRemote()
 				if (connectedRemote) {
-					const fullCommand = args.length > 0 ? `${command} ${args.join(' ')}` : command
-					return connectedRemote.executeRemote(fullCommand, options)
+					return connectedRemote.executeCommand(command, args, options)
 				}
 				return this.localCtx.executeCommand(command, args, options)
 			}
@@ -162,8 +190,7 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 				if (target === this.localCtx) {
 					return this.localCtx.executeCommand(command, args, options)
 				}
-				const fullCommand = args.length > 0 ? `${command} ${args.join(' ')}` : command
-				return (target as RemoteExecutionContext).executeRemote(fullCommand, options)
+				return (target as RemoteExecutionContext).executeCommand(command, args, options)
 			}
 
 			default: {
@@ -174,13 +201,17 @@ export class HybridExecutionContext extends BaseExecutionContext implements Comm
 	}
 
 	toConfig(): HybridExecutionContextConfig {
+		const local = this.localCtx.toConfig()
 		return {
 			id: this.id,
 			environment: 'hybrid',
 			local: {
-				cwd: this.localCtx.getCwd(),
-				fsAccess: this.localCtx.hasFsAccess(),
-				envVars: this.localCtx.getEnvVars(),
+				cwd: local.cwd,
+				fsAccess: local.fsAccess,
+				envVars: local.envVars,
+				capabilities: local.capabilities,
+				shell: local.shell,
+				maxOutputBytes: local.maxOutputBytes,
 			},
 			remotes: this.remoteTargets.map((t) => ({ ...t })),
 			routingStrategy: this.routingStrategy,

package/src/execution/index.ts

@@ -18,6 +18,7 @@
  */
 
 export { BaseExecutionContext } from './base.js'
+export { CommandCancellationUnsupportedError, RemoteExecutionBusyError } from './errors.js'
 export { ExecutionContextFactory } from './factory.js'
 export { HybridExecutionContext } from './hybrid.js'
 export type { HybridExecutionContextOptions } from './hybrid.js'

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
+	}
+}