@namzu/sdk 32.0.0 → 33.0.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/fallback.ts

@@ -230,6 +230,40 @@ function memberReasoningEffortLevels(
 	return member.provider.effortLevelsFor?.(model, thinking)
 }
 
+/** Read one member's model-owned default using its routed model id. */
+function memberReasoningEffortDefault(
+	member: ProviderChainMember,
+	requestModel: string,
+	thinking?: ThinkingConfig,
+): ReasoningEffort | undefined {
+	return member.provider.reasoningEffortDefaultFor?.(member.model ?? requestModel, thinking)
+}
+
+/**
+ * A fallback request has one unambiguous default only when every route agrees.
+ *
+ * Omitting effort lets whichever member serves the request choose its own
+ * default. Publishing the head's answer as the chain's answer can therefore
+ * make the same shortcut move in opposite directions after fallback. The
+ * agreed value must also survive the chain-wide exact menu.
+ */
+function commonReasoningEffortDefault(
+	members: readonly ProviderChainMember[],
+	requestModel: string,
+	thinking?: ThinkingConfig,
+): ReasoningEffort | undefined {
+	const common = commonReasoningEffortLevels(members, requestModel, thinking)
+	if (common === undefined) return undefined
+	let agreed: ReasoningEffort | undefined
+	for (const member of members) {
+		const value = memberReasoningEffortDefault(member, requestModel, thinking)
+		if (value === undefined) return undefined
+		if (agreed !== undefined && value !== agreed) return undefined
+		agreed = value
+	}
+	return agreed !== undefined && common.includes(agreed) ? agreed : undefined
+}
+
 /**
  * The levels one request may carry safely through every member it can reach.
  *
@@ -463,6 +497,11 @@ export function withProviderFallback(
 		// answer when any member cannot enumerate its selected model.
 		reasoningEffortLevelsFor: (model: string, thinking?: ThinkingConfig) =>
 			commonReasoningEffortLevels(members, model, thinking),
+		// Present on the chain wrapper for the same reason the menu method is:
+		// `undefined` is the honest answer when a member cannot answer, defaults
+		// disagree, or the value is absent from the common exact menu.
+		reasoningEffortDefaultFor: (model: string, thinking?: ThinkingConfig) =>
+			commonReasoningEffortDefault(members, model, thinking),
 		// Compatibility projection only. Existing consumers of the deprecated
 		// member keep the head-only answer they had; new consumers use the
 		// canonical chain-aware member above.

package/src/provider/idle-timeout.ts

@@ -220,6 +220,14 @@ export function withStreamIdleTimeout(
 					) => provider.reasoningEffortLevelsFor?.(model, thinking),
 				}
 			: {}),
+		...(provider.reasoningEffortDefaultFor
+			? {
+					reasoningEffortDefaultFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['reasoningEffortDefaultFor']>>[1],
+					) => provider.reasoningEffortDefaultFor?.(model, thinking),
+				}
+			: {}),
 		...(provider.effortLevelsFor
 			? {
 					effortLevelsFor: (

package/src/provider/retry.ts

@@ -275,6 +275,14 @@ export function withProviderRetry(
 					) => provider.reasoningEffortLevelsFor?.(model, thinking),
 				}
 			: {}),
+		...(provider.reasoningEffortDefaultFor
+			? {
+					reasoningEffortDefaultFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['reasoningEffortDefaultFor']>>[1],
+					) => provider.reasoningEffortDefaultFor?.(model, thinking),
+				}
+			: {}),
 		// Forwarded for the same reason `healthCheck` is, and both were
 		// missing until something consumed them. A member this wrapper drops
 		// does not fail — it reads as "this driver cannot answer", which is a

package/src/public-runtime.ts

@@ -293,7 +293,11 @@ export {
 	formatSteeringNote,
 } from './runtime/query/steering.js'
 export type { SteeringChannel } from './runtime/query/steering.js'
-export { createMockBidiProvider, startBidiRun } from './runtime/bidi/index.js'
+export {
+	BidiSessionCloseTimeoutError,
+	createMockBidiProvider,
+	startBidiRun,
+} from './runtime/bidi/index.js'
 export { PromptCache } from './runtime/query/prompt-cache.js'
 export {
 	CheckpointManager,
@@ -672,6 +676,7 @@ export {
 export {
 	BaseConnector,
 	BaseExecutionContext,
+	CommandCancellationUnsupportedError,
 	ConnectorManager,
 	ConnectorRegistry,
 	EnvironmentConnectorManager,
@@ -695,6 +700,7 @@ export {
 	mcpToolResultToToolResult,
 	mcpToolToToolDefinition,
 	RemoteExecutionContext,
+	RemoteExecutionBusyError,
 	ScopedConnectorRegistry,
 	// The only transport in the tree that can RUN an `MCPServer`. It reached
 	// `connector/mcp/index.ts` and stopped there, so the server was public