@namzu/sdk 51.1.0 → 52.1.0

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'
@@ -331,6 +338,17 @@ export interface QueryParams {
 	maxToolConcurrency?: number
 	/** Per-turn cumulative tool attempt limit, including nested calls and retries. Unset is unlimited. Re-supply on resume; durable reservations are never refunded. */
 	maxToolCalls?: number
+	/**
+	 * How many times in a row the loop nudges the model to carry on after a
+	 * reply was cut off at its output limit, before the turn stops with an
+	 * error naming the limit. The count restarts after any call that finishes
+	 * on its own.
+	 *
+	 * Unset keeps the earlier behaviour: nudge every time, bounded only by
+	 * `maxIterations`. Opt-in because a cap is a stop a host did not have
+	 * before; `0` stops at the first cut-off.
+	 */
+	maxOutputContinuations?: number
 
 	/**
 	 * Model-visible size cap for a single tool result. Over-budget output is
@@ -339,6 +357,18 @@ export interface QueryParams {
 	 * agent decides the rest is worth re-reading. Set `0` to disable.
 	 */
 	maxToolOutputChars?: number
+	/**
+	 * Cap on the COMBINED model-visible text of every tool result one assistant
+	 * message produced. Defaults to {@link DEFAULT_MAX_TOOL_OUTPUT_CHARS_PER_MESSAGE}
+	 * (200,000 characters); `0` disables it. When a batch exceeds it, the
+	 * largest results are replaced, largest first, by a short preview that
+	 * names where the full text was kept, until the batch fits. The
+	 * replacement is written into the result before it reaches the history, so
+	 * it never changes afterwards and the prompt-cache prefix stays stable.
+	 * Tools that bound their own output (`selfLimitingOutput`) are never
+	 * replaced.
+	 */
+	maxToolOutputCharsPerMessage?: number
 	/**
 	 * Screens to run against every tool result. The turn builds its manager
 	 * from `toolsets` and gives it this policy.
@@ -726,6 +756,13 @@ export interface QueryParams {
 	 * started. See `BaseAgentConfig.inboundMessages` for what it closes.
 	 */
 	inboundMessages?: () => import('../../types/message/index.js').Message[]
+	/**
+	 * Hidden reminders a host feeds into the conversation, asked for before
+	 * every model request of the turn. Opt-in: omitted, a turn carries none.
+	 * See {@link ReminderSource}.
+	 */
+	reminders?: import('./reminders.js').ReminderSource
+
 	/**
 	 * Wake a background-task hold when operator input is available, without draining it.
 	 * Resolve immediately if input is already pending. Otherwise wait for its arrival;
@@ -1407,6 +1444,11 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				...(params.maxToolOutputChars !== undefined
 					? { maxToolOutputChars: params.maxToolOutputChars }
 					: {}),
+				...(params.maxToolOutputCharsPerMessage !== undefined
+					? {
+							maxToolOutputCharsPerMessage: params.maxToolOutputCharsPerMessage,
+						}
+					: {}),
 				...(params.toolResultGuardrails !== undefined
 					? { toolResultGuardrails: params.toolResultGuardrails }
 					: {}),
@@ -1474,9 +1516,9 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		// Normalised once, defaults applied. A host that passes a partial
 		// object — a strategy and a window, nothing else — used to reach the
 		// phase with `triggerThreshold` undefined, and `usage < undefined` is
-		// false: the pass ran on every iteration and the salience strategy fell
-		// through to the stale-result clearing it exists to replace. The eval
-		// suite that passed exactly that object found it.
+		// false: the pass ran on every iteration. An absent threshold now means
+		// the derived trigger (`resolveTriggerThreshold`), resolved where it is
+		// compared.
 		const compactionConfig = params.compactionConfig
 			? CompactionConfigSchema.parse(params.compactionConfig)
 			: undefined
@@ -1635,7 +1677,11 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			// would leak exactly that way.
 			...(params.repeatCallAdvisory === false ? {} : { repeatCalls: new RepeatCallTracker() }),
 			compactionConfig,
+			...(params.maxOutputContinuations !== undefined
+				? { maxOutputContinuations: params.maxOutputContinuations }
+				: {}),
 			...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
+			...(params.reminders ? { reminders: params.reminders } : {}),
 			...(params.durableInbound ? { durableInbound: params.durableInbound } : {}),
 			...(params.resumeFromCheckpoint ? { resumedInput: queuedForThisRun } : {}),
 			...(params.waitForInbound ? { waitForInbound: params.waitForInbound } : {}),
@@ -1666,6 +1712,8 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			agentBus: params.agentBus,
 			verificationGate,
 			pluginManager: params.pluginManager,
+			...(params.parentSessionId !== undefined ? { parentSessionId: params.parentSessionId } : {}),
+			...(params.parentTurnId !== undefined ? { parentTurnId: params.parentTurnId } : {}),
 		})
 
 		const tracer = getTracer()
@@ -1784,6 +1832,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
@@ -2259,6 +2311,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'
@@ -2290,40 +2356,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,
 								},
 							)
 						}
@@ -2333,32 +2419,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
@@ -2484,16 +2578,35 @@ 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,
 					eventTranslator,
 					takeSteps: () => iterationOrchestrator.getSteps(),
+					turnEndHooksFired: () => iterationOrchestrator.turnEndHooksFired,
 					workingStateManager,
 					resultAssembler,
 					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.
@@ -2504,6 +2617,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,