@namzu/sdk 31.1.0 → 33.0.0

package/src/execution/base.ts

@@ -12,6 +12,21 @@ export interface BaseExecutionEvent {
 
 export type ExecutionEventListener = (event: BaseExecutionEvent) => void
 
+type ExecutionLifecycleState =
+	| 'idle'
+	| 'initializing'
+	| 'ready'
+	| 'tearing-down'
+	| 'teardown-failed'
+	| 'torn-down'
+
+class InitializationSupersededError extends Error {
+	constructor(contextId: string) {
+		super(`Execution context "${contextId}" initialization was superseded by teardown`)
+		this.name = 'InitializationSupersededError'
+	}
+}
+
 export abstract class BaseExecutionContext implements ExecutionContextLifecycle {
 	abstract readonly id: string
 	abstract readonly environment: ExecutionEnvironment
@@ -19,6 +34,9 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 	protected log: Logger
 	protected ready = false
 	private listeners: ExecutionEventListener[] = []
+	private lifecycleState: ExecutionLifecycleState = 'idle'
+	private initializationOperation: Promise<void> | undefined
+	private teardownOperation: Promise<void> | undefined
 
 	constructor(log?: Logger) {
 		this.log = resolveLogger(log).child({
@@ -27,17 +45,62 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 		})
 	}
 
-	async initialize(): Promise<void> {
+	initialize(): Promise<void> {
+		if (this.lifecycleState === 'ready') return Promise.resolve()
+		if (this.lifecycleState === 'initializing' && this.initializationOperation) {
+			return this.initializationOperation
+		}
+		if (this.lifecycleState === 'tearing-down') {
+			return Promise.reject(
+				new Error(`Execution context "${this.id}" cannot initialize while teardown is in progress`),
+			)
+		}
+		if (this.lifecycleState === 'teardown-failed') {
+			return Promise.reject(
+				new Error(
+					`Execution context "${this.id}" cannot initialize until its failed teardown is retried`,
+				),
+			)
+		}
+
+		this.lifecycleState = 'initializing'
+		const operation = this.performInitialize()
+		this.initializationOperation = operation
+		void operation.then(
+			() => this.releaseInitialization(operation),
+			() => this.releaseInitialization(operation),
+		)
+		return operation
+	}
+
+	private async performInitialize(): Promise<void> {
 		try {
+			this.onInitializationStarted()
 			await this.doInitialize()
+			if (this.lifecycleState !== 'initializing') {
+				throw new InitializationSupersededError(this.id)
+			}
+			this.onInitializationCommitted()
+			if (this.lifecycleState !== 'initializing') {
+				throw new InitializationSupersededError(this.id)
+			}
 			this.ready = true
-			this.emit({ type: 'context_initialized', contextId: this.id, environment: this.environment })
-			this.emit({ type: 'context_ready', contextId: this.id })
+			this.lifecycleState = 'ready'
 			this.log.info('Execution context initialized', {
 				'namzu.execution.context_id': this.id,
 				'namzu.execution.environment': this.environment,
 			})
+			this.emit({
+				type: 'context_initialized',
+				contextId: this.id,
+				environment: this.environment,
+			})
+			if (this.lifecycleState !== 'ready') return
+			this.emit({ type: 'context_ready', contextId: this.id })
 		} catch (err) {
+			if (err instanceof InitializationSupersededError) throw err
+			this.ready = false
+			if (this.lifecycleState === 'initializing') this.lifecycleState = 'idle'
 			const message = toErrorMessage(err)
 			this.emit({ type: 'context_error', contextId: this.id, error: message })
 			this.log.error('Execution context initialization failed', {
@@ -48,20 +111,65 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 		}
 	}
 
+	private releaseInitialization(operation: Promise<void>): void {
+		if (this.initializationOperation === operation) this.initializationOperation = undefined
+	}
+
 	isReady(): boolean {
 		return this.ready
 	}
 
-	async teardown(): Promise<void> {
+	teardown(): Promise<void> {
+		if (this.lifecycleState === 'tearing-down' && this.teardownOperation) {
+			return this.teardownOperation
+		}
+		if (this.lifecycleState === 'torn-down') return Promise.resolve()
+
+		this.ready = false
+		this.lifecycleState = 'tearing-down'
+		const operation = this.performTeardown(this.initializationOperation)
+		this.teardownOperation = operation
+		void operation.then(
+			() => this.releaseTeardown(operation),
+			() => this.releaseTeardown(operation),
+		)
+		return operation
+	}
+
+	private async performTeardown(pendingInitialization: Promise<void> | undefined): Promise<void> {
 		try {
+			// Runs before the first await. Subclasses close public admission here so
+			// work cannot slip behind an initialization this teardown must await.
+			this.onTeardownRequested()
+			if (pendingInitialization) {
+				try {
+					await pendingInitialization
+				} catch {
+					// Initialization errors are reported by their owner. Cleanup still runs.
+				}
+			}
 			await this.doTeardown()
-		} finally {
-			this.ready = false
+			this.lifecycleState = 'torn-down'
+			this.log.info('Execution context torn down', {
+				'namzu.execution.context_id': this.id,
+			})
 			this.emit({ type: 'context_teardown', contextId: this.id })
-			this.log.info('Execution context torn down', { 'namzu.execution.context_id': this.id })
+		} catch (err) {
+			this.lifecycleState = 'teardown-failed'
+			const message = toErrorMessage(err)
+			this.emit({ type: 'context_error', contextId: this.id, error: message })
+			this.log.error('Execution context teardown failed', {
+				'namzu.execution.context_id': this.id,
+				'exception.message': message,
+			})
+			throw err
 		}
 	}
 
+	private releaseTeardown(operation: Promise<void>): void {
+		if (this.teardownOperation === operation) this.teardownOperation = undefined
+	}
+
 	on(listener: ExecutionEventListener): void {
 		this.listeners.push(listener)
 	}
@@ -85,4 +193,13 @@ export abstract class BaseExecutionContext implements ExecutionContextLifecycle
 
 	protected abstract doInitialize(): Promise<void>
 	protected abstract doTeardown(): Promise<void>
+
+	/** Fence subclass-owned public admission before initialization begins. */
+	protected onInitializationStarted(): void {}
+
+	/** Reopen admission only after Base has proved initialization was not superseded. */
+	protected onInitializationCommitted(): void {}
+
+	/** Fence subclass-owned public admission synchronously when teardown is requested. */
+	protected onTeardownRequested(): void {}
 }

package/src/execution/code-runtime/types.ts

@@ -42,6 +42,17 @@ export interface HostCallResult {
 	readonly error?: string
 }
 
+/** Authority and provenance for one call from a running program. */
+export interface HostCallContext {
+	/** Unique within this program execution. */
+	readonly runtimeToolCallId: string
+	/**
+	 * Revoked when the caller cancels or the program's own wall clock expires.
+	 * A conforming host threads this into the operation it starts.
+	 */
+	readonly signal: AbortSignal
+}
+
 /**
  * What the host will answer.
  *
@@ -50,7 +61,10 @@ export interface HostCallResult {
  * exactly the point: the program's reach is the run's reach, resolved at
  * the moment of the call rather than frozen when the program started.
  */
-export type HostCallHandler = (request: HostCallRequest) => Promise<HostCallResult>
+export type HostCallHandler = (
+	request: HostCallRequest,
+	context: HostCallContext,
+) => Promise<HostCallResult>
 
 export interface RunCodeOptions {
 	/** The program. Untrusted text, from the model. */

package/src/execution/code-runtime/worker.ts

@@ -105,6 +105,17 @@ export class WorkerCodeRuntime implements CodeRuntime {
 		let output = ''
 		let truncated = false
 
+		// A withdrawn caller owns admission. Do not start an isolate merely to
+		// discover the signal was already aborted after construction.
+		if (options.signal?.aborted) {
+			return {
+				outcome: { status: 'cancelled' },
+				output,
+				outputTruncated: truncated,
+				calls,
+			}
+		}
+
 		const appendOutput = (lines: readonly string[]): void => {
 			for (const line of lines) {
 				if (truncated) return
@@ -143,6 +154,10 @@ export class WorkerCodeRuntime implements CodeRuntime {
 
 		return await new Promise<CodeRunResult>((resolve) => {
 			let settled = false
+			let terminal: CodeRunResult | undefined
+			const inFlight = new Set<Promise<void>>()
+			const operation = new AbortController()
+
 			const finish = (result: CodeRunResult): void => {
 				// The Promise already ignores a second `resolve`, so removing
 				// this guard changes no result — a mutation removing it
@@ -153,18 +168,42 @@ export class WorkerCodeRuntime implements CodeRuntime {
 				// then `exit` is the ordinary sequence, not an edge case.
 				if (settled) return
 				settled = true
+				// Terminating the worker only stops the program. Host work already
+				// admitted through onHostCall lives outside it, so revoke the signal
+				// that was handed to every such call before reporting settlement.
+				if (!operation.signal.aborted) {
+					operation.abort(new Error(`Code runtime settled with status ${result.outcome.status}`))
+				}
 				clearTimeout(deadline)
 				options.signal?.removeEventListener('abort', onAbort)
 				void worker.terminate()
-				resolve(result)
+				// A late, non-cooperative host call must not mutate a result the
+				// caller already received.
+				resolve({ ...result, calls: [...calls] })
+			}
+
+			const finishTerminalWhenHostCallsSettle = (): void => {
+				if (terminal && inFlight.size === 0) finish(terminal)
 			}
 
 			const deadline = setTimeout(() => {
-				finish({ outcome: { status: 'timed-out' }, output, outputTruncated: truncated, calls })
+				operation.abort(new Error(`Code runtime exceeded ${options.timeoutMs}ms`))
+				finish({
+					outcome: { status: 'timed-out' },
+					output,
+					outputTruncated: truncated,
+					calls,
+				})
 			}, options.timeoutMs)
 
 			const onAbort = (): void => {
-				finish({ outcome: { status: 'cancelled' }, output, outputTruncated: truncated, calls })
+				operation.abort(options.signal?.reason)
+				finish({
+					outcome: { status: 'cancelled' },
+					output,
+					outputTruncated: truncated,
+					calls,
+				})
 			}
 			options.signal?.addEventListener('abort', onAbort, { once: true })
 			if (options.signal?.aborted) {
@@ -185,13 +224,23 @@ export class WorkerCodeRuntime implements CodeRuntime {
 							kind: 'call-result',
 							id,
 							ok: false,
-							error: new HostCallDeniedError({ name, allowed: options.allowedCalls }).message,
+							error: new HostCallDeniedError({
+								name,
+								allowed: options.allowedCalls,
+							}).message,
 						})
 						return
 					}
-					void options
-						.onHostCall({ name, input: message.input })
+					const runtimeToolCallId = String(id)
+					const hostCall = Promise.resolve()
+						.then(() =>
+							options.onHostCall(
+								{ name, input: message.input },
+								{ runtimeToolCallId, signal: operation.signal },
+							),
+						)
 						.then((result) => {
+							if (settled) return
 							calls.push({ name, ok: result.ok })
 							worker.postMessage({
 								kind: 'call-result',
@@ -202,6 +251,7 @@ export class WorkerCodeRuntime implements CodeRuntime {
 							})
 						})
 						.catch((err: unknown) => {
+							if (settled) return
 							calls.push({ name, ok: false })
 							worker.postMessage({
 								kind: 'call-result',
@@ -210,6 +260,11 @@ export class WorkerCodeRuntime implements CodeRuntime {
 								error: err instanceof Error ? err.message : String(err),
 							})
 						})
+						.finally(() => {
+							inFlight.delete(hostCall)
+							finishTerminalWhenHostCallsSettle()
+						})
+					inFlight.add(hostCall)
 					return
 				}
 
@@ -219,12 +274,17 @@ export class WorkerCodeRuntime implements CodeRuntime {
 				}
 
 				if (message.kind === 'done') {
-					finish({
+					// A program may start a host call without awaiting it. The worker
+					// declaring its JavaScript body complete is not evidence that the
+					// effect it started is complete, so keep the runtime open until the
+					// already-admitted host calls settle (or the deadline revokes them).
+					terminal = {
 						outcome: { status: 'completed', result: message.result },
 						output,
 						outputTruncated: truncated,
 						calls,
-					})
+					}
+					finishTerminalWhenHostCallsSettle()
 					return
 				}
 
@@ -255,7 +315,10 @@ export class WorkerCodeRuntime implements CodeRuntime {
 				// `error` message — a hard crash, or a program that called
 				// `process.exit` through something we failed to withhold.
 				finish({
-					outcome: { status: 'failed', error: `The program exited with code ${code}.` },
+					outcome: {
+						status: 'failed',
+						error: `The program exited with code ${code}.`,
+					},
 					output,
 					outputTruncated: truncated,
 					calls,

package/src/execution/errors.ts

@@ -0,0 +1,24 @@
+export class CommandCancellationUnsupportedError extends Error {
+	readonly code = 'command_cancellation_unsupported' as const
+
+	constructor(readonly contextId: string) {
+		super(
+			`Remote execution context "${contextId}" cannot accept command cancellation because its generic executor has no reservation and terminal-acknowledgement protocol. No remote command was started. Use the Sandbox.exec() contract for cancellable remote command execution.`,
+		)
+		this.name = 'CommandCancellationUnsupportedError'
+	}
+}
+
+export class RemoteExecutionBusyError extends Error {
+	readonly code = 'remote_execution_busy' as const
+
+	constructor(
+		readonly contextId: string,
+		readonly activeCommandCount: number,
+	) {
+		super(
+			`Remote execution context "${contextId}" still owns ${activeCommandCount} active command${activeCommandCount === 1 ? '' : 's'}. Disconnect or teardown was refused; wait for the command${activeCommandCount === 1 ? '' : 's'} to settle, then retry.`,
+		)
+		this.name = 'RemoteExecutionBusyError'
+	}
+}

package/src/execution/factory.ts

@@ -15,6 +15,7 @@ export class ExecutionContextFactory {
 					envVars: config.envVars,
 					capabilities: config.capabilities,
 					shell: config.shell,
+					maxOutputBytes: config.maxOutputBytes,
 				})
 
 			case 'remote':

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'