@namzu/sdk 52.0.0 → 52.2.0

package/src/runtime/query/executor.ts

@@ -336,6 +336,7 @@ export const DEFAULT_TOOL_RETRY_BACKOFF: BackoffPolicy = {
 
 export interface ToolExecutorConfig {
 	fileReadTracker?: FileReadTracker
+	codeAnalysis?: import('../../types/code-analysis/index.js').CodeAnalysisProvider
 	tools: ToolManager
 	/** Exact runtime output-tool owner allowed to retain post-screen, post-hook JSON before preview capping. */
 	durableStructuredOutputTool?: ToolDefinition
@@ -653,6 +654,7 @@ export class ToolExecutor {
 	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
 	private stepAllowedTools?: readonly string[]
 	private readonly fileReadTracker: FileReadTracker
+	private sandboxGate?: () => Promise<void>
 	/** A ledger is rebuilt from history at most once; a second pass would re-append its chains. */
 	private fileObservationsSeeded = false
 
@@ -686,6 +688,25 @@ export class ToolExecutor {
 
 	setSandbox(sandbox: Sandbox): void {
 		this.config = { ...this.config, sandbox }
+		this.sandboxGate = undefined
+	}
+
+	/**
+	 * Hold tool admission until a sandbox that is still being acquired exists.
+	 * The gate rejects when none will, and the turn settles that rejection. It
+	 * is cleared by {@link setSandbox}, so a turn pays the check once.
+	 */
+	setSandboxGate(gate: () => Promise<void>): void {
+		this.sandboxGate = gate
+	}
+
+	private async awaitSandbox(): Promise<void> {
+		await this.sandboxGate?.()
+	}
+
+	/** True once the turn has a sandbox, or is certain to get one before a tool runs. */
+	private get sandboxed(): boolean {
+		return this.config.sandbox !== undefined || this.sandboxGate !== undefined
 	}
 
 	/** Classify only the exact successful result executed by this executor. */
@@ -771,7 +792,7 @@ export class ToolExecutor {
 			messages,
 			this.fileReadTracker,
 			this.config.workingDirectory,
-			this.config.sandbox !== undefined,
+			this.sandboxed,
 		)
 	}
 
@@ -953,7 +974,7 @@ export class ToolExecutor {
 		const tool = this.config.tools.get(toolName)
 		return (
 			tool?.commandDialect?.({
-				sandboxed: this.config.sandbox !== undefined,
+				sandboxed: this.sandboxed,
 			}) ?? 'sh'
 		)
 	}
@@ -979,6 +1000,7 @@ export class ToolExecutor {
 		hostModifiedCallIds?: ReadonlySet<string>,
 	): Promise<PreparedToolBatch> {
 		assertUniqueToolCallIds(response.message.toolCalls ?? [])
+		if ((response.message.toolCalls ?? []).length > 0) await this.awaitSandbox()
 		const calls = new Map<string, PreparedDirectCall>()
 		const escalations = new Map<string, ToolCallEscalation>()
 		for (const toolCall of response.message.toolCalls ?? []) {
@@ -1012,7 +1034,7 @@ export class ToolExecutor {
 		const tool = this.config.tools.get(call.toolName)
 		if (!tool || call.input === null || typeof call.input !== 'object') return undefined
 		const input = call.input as Record<string, unknown>
-		const sandboxed = this.config.sandbox !== undefined
+		const sandboxed = this.sandboxed
 		let outsidePaths: string[] | undefined
 		if (
 			this.config.outsideRootAccess === 'review' &&
@@ -1199,6 +1221,7 @@ export class ToolExecutor {
 			return { messages: [], results: [], observations: [] }
 		}
 		assertUniqueToolCallIds(toolCalls)
+		if (toolCalls.length > 0) await this.awaitSandbox()
 
 		// Sampled here, once, and held for every call below. See the note on
 		// `permissionMode` in the config type.
@@ -1883,6 +1906,7 @@ export class ToolExecutor {
 				this.dispatchNested(name, input, context, recordObservation, undefined, options),
 			sandbox: this.config.sandbox,
 			fileReadTracker: this.fileReadTracker,
+			...(this.config.codeAnalysis ? { codeAnalysis: this.config.codeAnalysis } : {}),
 			// Bound to this turn, once. Binding here rather than passing the
 			// owner from the tool is what makes the scoping structural: there
 			// is no argument a tool could pass to reach another turn's jobs.

package/src/runtime/query/index.ts

@@ -104,6 +104,13 @@ import { AwaitedJobs } from '../jobs/awaited-jobs.js'
 import type { BackgroundJobRegistry } from '../jobs/registry.js'
 import { catchUpFromCursor, settlePreStartCancellation } from './cancelled-before-start.js'
 import { CheckpointManager, findPendingCheckpoint } from './checkpoint.js'
+import {
+	type DeferredSandbox,
+	type SandboxAcquireMode,
+	type SandboxAcquisitionStop,
+	SandboxAcquisitionStopped,
+	createDeferredSandbox,
+} from './deferred-sandbox.js'
 import type { EventTranslator } from './events.js'
 import { finalizeTurn } from './finalize-turn.js'
 import { GuardCoordinator } from './guard.js'
@@ -146,6 +153,8 @@ import { ToolingBootstrap } from './tooling.js'
 export interface QueryParams {
 	/** Share observations across turns of one conversation and filesystem; otherwise run-local. */
 	fileReadTracker?: import('../../types/tool/index.js').FileReadTracker
+	/** The `code_analysis` tool's index; see `ToolContext.codeAnalysis`. Absent: the tool is not offered. */
+	codeAnalysis?: import('../../types/code-analysis/index.js').CodeAnalysisProvider
 	/** One ledger shared with the task scheduler and descendant child sessions, keyed by (rootSessionId, rootTurnId). */
 	budget?: SessionTokenBudget
 	/**
@@ -1421,6 +1430,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				...(params.skillRegistry ? { skills: params.skillRegistry } : {}),
 				...(params.web ? { web: params.web } : {}),
 				...(params.fileReadTracker ? { fileReadTracker: params.fileReadTracker } : {}),
+				...(params.codeAnalysis ? { codeAnalysis: params.codeAnalysis } : {}),
 				...(params.toolTimeoutMs !== undefined ? { toolTimeoutMs: params.toolTimeoutMs } : {}),
 				...(params.toolRetryBackoff !== undefined
 					? { toolRetryBackoff: params.toolRetryBackoff }
@@ -1825,6 +1835,10 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			})
 
 			let sandbox: Sandbox | undefined
+			/** Set only for `sandbox.acquire: 'concurrent' | 'on-first-use'`. */
+			let deferredSandbox: DeferredSandbox | undefined
+			/** How a stopped acquisition settles the turn; set where the provider is known. */
+			let applyAcquisitionStop: (acquisition: SandboxAcquisitionStop) => void = () => {}
 			// Decided during checkpoint restore, executed after the sandbox
 			// exists — the approved tools may well need it.
 			let pendingResume: PendingResumePlan | null = null
@@ -2300,6 +2314,20 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					yield* eventTranslator.drainPending()
 				}
 
+				// Checked whether or not a provider is present: a host that mistypes the
+				// option should hear about it before it wires a provider in, not after.
+				const acquireMode: SandboxAcquireMode = turnConfig.sandbox?.acquire ?? 'eager'
+				if (
+					acquireMode !== 'eager' &&
+					acquireMode !== 'concurrent' &&
+					acquireMode !== 'on-first-use'
+				) {
+					throw new NamzuError({
+						code: 'invalid_config',
+						message: `sandbox.acquire must be 'eager', 'concurrent' or 'on-first-use'; received ${String(acquireMode)}`,
+						details: { acquire: String(acquireMode) },
+					})
+				}
 				// --- Sandbox lifecycle: create before iteration loop ---
 				if (params.sandboxProvider) {
 					const rootAtCwd = turnConfig.sandbox?.workspace === 'working-directory'
@@ -2331,40 +2359,60 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 							},
 						})
 					}
-					const acquisition = await acquireSandbox({
-						provider: params.sandboxProvider,
-						config: {
-							...(rootAtCwd ? { workingDirectory: ctx.cwd } : {}),
-							...(rootAtCwd && params.additionalDirectories?.length
-								? { additionalDirectories: params.additionalDirectories }
-								: {}),
-							timeoutMs: turnConfig.sandbox?.timeoutMs,
-							memoryLimitMb: turnConfig.sandbox?.memoryLimitMb,
-							maxProcesses: turnConfig.sandbox?.maxProcesses,
-						},
-						signal: ctx.abortController.signal,
-						timeoutMs: guard.remainingUntilTimeoutMs(),
-						teardownTimeoutMs: sandboxTeardownTimeoutMs,
-						onLateTeardown: (result) => {
-							if (result.kind === 'destroyed') {
-								ctx.log.info('Late sandbox allocation was destroyed after the turn stopped', {
+					const sandboxProvider = params.sandboxProvider
+					const startAcquisition = (signal: AbortSignal) =>
+						acquireSandbox({
+							provider: sandboxProvider,
+							config: {
+								...(rootAtCwd ? { workingDirectory: ctx.cwd } : {}),
+								...(rootAtCwd && params.additionalDirectories?.length
+									? { additionalDirectories: params.additionalDirectories }
+									: {}),
+								timeoutMs: turnConfig.sandbox?.timeoutMs,
+								memoryLimitMb: turnConfig.sandbox?.memoryLimitMb,
+								maxProcesses: turnConfig.sandbox?.maxProcesses,
+							},
+							signal,
+							timeoutMs: guard.remainingUntilTimeoutMs(),
+							teardownTimeoutMs: sandboxTeardownTimeoutMs,
+							onLateTeardown: (result) => {
+								if (result.kind === 'destroyed') {
+									ctx.log.info('Late sandbox allocation was destroyed after the turn stopped', {
+										[NAMZU.TURN_ID]: ctx.turnId,
+									})
+									return
+								}
+								ctx.log.error('Late sandbox allocation did not stop cleanly', {
 									[NAMZU.TURN_ID]: ctx.turnId,
+									...errorAttributes(result.error),
 								})
-								return
-							}
-							ctx.log.error('Late sandbox allocation did not stop cleanly', {
-								[NAMZU.TURN_ID]: ctx.turnId,
-								...errorAttributes(result.error),
-							})
-						},
-					})
-					if (acquisition.kind !== 'created') {
+							},
+						})
+					const publishSandbox = async (acquired: Sandbox): Promise<void> => {
+						sandbox = acquired
+						toolExecutor.setSandbox(acquired)
+
+						await eventTranslator.emitEvent({
+							type: 'sandbox_created',
+							turnId: ctx.turnId,
+							sandboxId: acquired.id,
+							environment: acquired.environment,
+						})
+					}
+					const logSandboxCreated = (acquired: Sandbox): void => {
+						ctx.log.info('Sandbox created for run', {
+							'namzu.sandbox.id': acquired.id,
+							'namzu.execution.environment': acquired.environment,
+							'namzu.runtime.root_dir': acquired.rootDir,
+						})
+					}
+					applyAcquisitionStop = (acquisition) => {
 						if (acquisition.createPending) {
 							ctx.log.warn(
 								'Sandbox creation was unsettled when the turn stopped; any returned handle will be released, but a remote allocation hidden behind a lost response requires provider-side reconciliation or a fleet reaper',
 								{
 									[NAMZU.TURN_ID]: ctx.turnId,
-									'namzu.sandbox.provider_id': params.sandboxProvider.id,
+									'namzu.sandbox.provider_id': sandboxProvider.id,
 								},
 							)
 						}
@@ -2374,32 +2422,40 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 							ctx.recorder.setStopReason('timeout')
 							ctx.log.warn('Sandbox creation exhausted the turn timeout', {
 								[NAMZU.TURN_ID]: ctx.turnId,
-								'namzu.sandbox.provider_id': params.sandboxProvider.id,
+								'namzu.sandbox.provider_id': sandboxProvider.id,
 								...errorAttributes(acquisition.error),
 							})
 						}
-						yield* resultAssembler.completeTurn(rootSpan)
-						// The turn HAS settled, so the outer `finally` must not read
-						// this as an abandonment — it would persist a second time.
-						settled = true
-						return await resultAssembler.finalize()
 					}
-					sandbox = acquisition.sandbox
-					toolExecutor.setSandbox(sandbox)
-
-					await eventTranslator.emitEvent({
-						type: 'sandbox_created',
-						turnId: ctx.turnId,
-						sandboxId: sandbox.id,
-						environment: sandbox.environment,
-					})
-					yield* eventTranslator.drainPending()
-
-					ctx.log.info('Sandbox created for run', {
-						'namzu.sandbox.id': sandbox.id,
-						'namzu.execution.environment': sandbox.environment,
-						'namzu.runtime.root_dir': sandbox.rootDir,
-					})
+					if (acquireMode === 'eager') {
+						const acquisition = await startAcquisition(ctx.abortController.signal)
+						if (acquisition.kind !== 'created') {
+							applyAcquisitionStop(acquisition)
+							yield* resultAssembler.completeTurn(rootSpan)
+							// The turn HAS settled, so the outer `finally` must not read
+							// this as an abandonment — it would persist a second time.
+							settled = true
+							return await resultAssembler.finalize()
+						}
+						await publishSandbox(acquisition.sandbox)
+						yield* eventTranslator.drainPending()
+						logSandboxCreated(acquisition.sandbox)
+					} else {
+						// The handle is published, and `sandbox_created` emitted, when
+						// the provider answers. Until then the executor holds tool
+						// admission on the gate, so nothing runs without it.
+						const deferred = createDeferredSandbox({
+							turnSignal: ctx.abortController.signal,
+							acquire: startAcquisition,
+							publish: async (acquired) => {
+								await publishSandbox(acquired)
+								logSandboxCreated(acquired)
+							},
+						})
+						deferredSandbox = deferred
+						toolExecutor.setSandboxGate(() => deferred.ensure())
+						if (acquireMode === 'concurrent') deferred.start()
+					}
 				}
 
 				// Before the first model call: the cheapest place to refuse, since
@@ -2525,6 +2581,14 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 
 				yield* iterationOrchestrator.runLoop()
 
+				// A turn that never needed the sandbox still settles it: a failure or
+				// a timeout ends the turn the way an eager acquisition would have, and
+				// a handle that arrives after that is released by the lifecycle.
+				if (deferredSandbox) {
+					await deferredSandbox.settle()
+					yield* eventTranslator.drainPending()
+				}
+
 				yield* finalizeTurn({
 					ctx,
 					params,
@@ -2536,6 +2600,16 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					rootSpan,
 				})
 			} catch (err) {
+				// A deferred acquisition stopped (cancelled, or out of time) and the
+				// turn found out at its first tool call or at its end. Settled the
+				// way the eager path settles it, with nothing else to report.
+				if (err instanceof SandboxAcquisitionStopped) {
+					applyAcquisitionStop(err.acquisition)
+					yield* eventTranslator.drainPending()
+					yield* resultAssembler.completeTurn(rootSpan)
+					settled = true
+					return await resultAssembler.finalize()
+				}
 				// Another turn is active in this session: nothing of this turn was
 				// written, so there is nothing to settle. The caller gets the
 				// refusal itself.
@@ -2546,6 +2620,10 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				yield* eventTranslator.drainPending()
 				yield* resultAssembler.handleError(err, rootSpan)
 			} finally {
+				// A pending acquisition is withdrawn and awaited first, so a handle
+				// that arrives now is either published (and released below) or
+				// handed to the late-teardown path. Nothing is left allocated.
+				await deferredSandbox?.cancel()
 				yield* releaseTurnResources({
 					ctx,
 					eventTranslator,