@namzu/sdk 32.0.0 → 33.1.0

package/src/connector/mcp/stdio.ts

@@ -95,6 +95,10 @@ export class StdioTransport implements MCPTransport {
 	private closeHandlers: Array<() => void> = []
 	private errorHandlers: Array<(error: Error) => void> = []
 	private connected = false
+	/** The response channel ended for this process generation. */
+	private retired = false
+	/** Prevents a late event from an old child retiring its replacement. */
+	private generation = 0
 	/** True between kill and the process's own `close` event. */
 	private exitPending = false
 	private buffer = ''
@@ -109,38 +113,47 @@ export class StdioTransport implements MCPTransport {
 
 	async connect(): Promise<void> {
 		if (this.connected) return
+		// A protocol channel can end while its process stays alive. Reconnect
+		// must reap that old owner before publishing a new generation; otherwise
+		// both children remain live and teardown owns only the newest one.
+		if (this.process) await this.close()
+		const generation = ++this.generation
+		this.retired = false
+		this.buffer = ''
 
-		this.process = spawn(this.config.command, this.config.args ?? [], {
+		const child = spawn(this.config.command, this.config.args ?? [], {
 			env: buildChildEnv(this.config),
 			cwd: this.config.cwd,
 			stdio: ['pipe', 'pipe', 'pipe'],
 		})
+		this.process = child
 
-		this.process.stdout?.on('data', (chunk: Buffer) => {
+		child.stdout?.on('data', (chunk: Buffer) => {
+			if (generation !== this.generation || this.retired) return
 			this.buffer += chunk.toString('utf-8')
 			this.processBuffer()
 		})
+		child.stdout?.once('end', () => this.retire(generation, 'close'))
+		child.stdout?.once('close', () => this.retire(generation, 'close'))
+		child.stdout?.once('error', (err) => this.retire(generation, 'error', err))
 
-		this.process.stderr?.on('data', (chunk: Buffer) => {
+		child.stderr?.on('data', (chunk: Buffer) => {
 			this.log.warn('MCP server stderr', {
 				'namzu.mcp.stderr': chunk.toString('utf-8').trim(),
 			})
 		})
 
-		this.process.on('close', (code) => {
-			this.connected = false
-			this.log.info('MCP server process exited', { 'namzu.mcp.exit_code': code })
-			for (const handler of this.closeHandlers) handler()
-			// After the notification, not before it: this event is what tells
-			// `MCPClient` the session ended.
+		child.stdin?.once('close', () => this.retire(generation, 'close'))
+		child.stdin?.once('error', (err) => this.retire(generation, 'error', err))
+
+		child.on('close', (code) => {
+			if (this.process === child) this.process = null
 			this.exitPending = false
-			this.clearHandlers()
+			this.log.info('MCP server process exited', { 'namzu.mcp.exit_code': code })
+			this.retire(generation, 'close')
 		})
 
-		this.process.on('error', (err) => {
-			this.connected = false
-			for (const handler of this.errorHandlers) handler(err)
-		})
+		child.on('error', (err) => this.retire(generation, 'error', err))
 
 		this.connected = true
 		this.log.info('StdioTransport connected', {
@@ -175,7 +188,10 @@ export class StdioTransport implements MCPTransport {
 		// so both settle this, and two timers make a hang impossible: the
 		// first escalates to SIGKILL for a child ignoring SIGTERM, the second
 		// gives up waiting. Neither holds the event loop open.
-		if (child.pid === undefined) return
+		if (child.pid === undefined) {
+			this.exitPending = false
+			return
+		}
 		await new Promise<void>((resolve) => {
 			let settled = false
 			const finish = (): void => {
@@ -185,18 +201,20 @@ export class StdioTransport implements MCPTransport {
 				clearTimeout(giveUp)
 				resolve()
 			}
-			child.once('exit', finish)
+			child.once('close', finish)
 			child.once('error', finish)
-			child.kill('SIGTERM')
+			if (child.exitCode === null && child.signalCode === null) {
+				child.kill('SIGTERM')
+			}
 			const escalate = setTimeout(() => child.kill('SIGKILL'), TERMINATE_GRACE_MS)
 			const giveUp = setTimeout(finish, TERMINATE_GRACE_MS * 2)
 			escalate.unref?.()
 			giveUp.unref?.()
 		})
-		// The handlers deliberately survive this call. `process.on('close')`
-		// fires them when the process actually exits, and dropping them here
-		// would leave `MCPClient` believing it is still connected — so its next
-		// `connect()` would be refused with "already connected".
+		this.exitPending = false
+		// The active generation's terminal stream/process event owns handler
+		// retirement. A reconnect can register its handlers before `connect()`
+		// reaps an already-retired child, so `close()` must not clear them here.
 	}
 
 	/**
@@ -214,6 +232,30 @@ export class StdioTransport implements MCPTransport {
 		this.errorHandlers = []
 	}
 
+	/**
+	 * Publish one terminal result for the current response channel.
+	 *
+	 * A child may close stdout and keep running. That is just as terminal for
+	 * JSON-RPC as process exit: no pending or future request can receive a
+	 * response. Keeping the child handle is intentional; `close()` still owns
+	 * and reaps that process after the protocol session has been retired.
+	 */
+	private retire(generation: number, kind: 'close' | 'error', error?: Error): void {
+		if (generation !== this.generation || this.retired) return
+		this.retired = true
+		this.connected = false
+		this.buffer = ''
+		const closeHandlers = this.closeHandlers
+		const errorHandlers = this.errorHandlers
+		this.clearHandlers()
+		if (kind === 'error') {
+			const reason = error ?? new Error('MCP stdio transport failed')
+			for (const handler of errorHandlers) handler(reason)
+			return
+		}
+		for (const handler of closeHandlers) handler()
+	}
+
 	async send(message: MCPJsonRpcMessage, options?: MCPTransportSendOptions): Promise<void> {
 		options?.signal?.throwIfAborted()
 		if (!this.process?.stdin?.writable) {

package/src/connector/mcp/streamable-http.ts

@@ -7,6 +7,7 @@ import type {
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { ConnectorHttpOperation, validateConnectorTimeoutMs } from '../http-operation.js'
+import { refuseMcpHttpRedirect } from './http-redirect.js'
 
 const DEFAULT_TIMEOUT_MS = 30_000
 
@@ -83,10 +84,12 @@ export class StreamableHttpTransport implements MCPTransport {
 					method: 'POST',
 					headers: this.buildHeaders(),
 					body: JSON.stringify(message),
+					redirect: 'manual',
 					signal: operation.signal,
 				}),
 			)
 
+			refuseMcpHttpRedirect(response, message.method)
 			if (!response.ok) {
 				throw new Error(`StreamableHttpTransport: HTTP ${response.status}: ${response.statusText}`)
 			}

package/src/constants/tools/index.ts

@@ -1,4 +1,4 @@
-// Patterns the verification gate's `deny_dangerous_patterns` rule
+// Patterns the authorization gate's `deny_dangerous_patterns` rule
 // matches against the JSON-serialised tool input. The list is
 // intentionally short and high-signal: the goal is to catch the
 // canonical "I will brick the host" mistakes (filesystem wipes,

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/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'