@namzu/sdk 35.0.0 → 37.0.0

package/src/runtime/query/executor.ts

@@ -50,6 +50,7 @@ import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
 import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
 import type { ToolResultObservation } from './project-instructions.js'
+import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js'
 import {
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS,
 	type ToolOutputBudgetResult,
@@ -356,6 +357,10 @@ export interface ToolExecutorConfig {
 	toolRetryBackoff?: Partial<BackoffPolicy>
 	/** Max concurrently-executing concurrency-safe tools. */
 	maxToolConcurrency?: number
+	/** Per-run cumulative attempt admission limit; unset is unlimited. */
+	maxToolCalls?: number
+	/** Complete strict event replay for restoring a configured call budget. */
+	readToolCallBudgetEvents?: () => Promise<readonly RunEvent[]>
 
 	/**
 	 * Builds the durable-pause seam handed to one tool call.
@@ -492,6 +497,7 @@ export class ToolExecutor {
 	private workingStateManager?: WorkingStateManager
 	private probes: ProbeEnforcement
 	private parentSpan?: Span
+	private readonly toolCallBudget?: ToolCallBudget
 	private readonly preparedBatches = new WeakSet<PreparedToolBatch>()
 	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
 	private stepAllowedTools?: readonly string[]
@@ -517,6 +523,15 @@ export class ToolExecutor {
 		log: Logger,
 		probes: ProbeEnforcement = defaultProbeRegistry,
 	) {
+		assertMaxToolCalls(config.maxToolCalls)
+		if (config.maxToolCalls !== undefined) {
+			this.toolCallBudget = new ToolCallBudget(
+				config.maxToolCalls,
+				config.runId,
+				emitEvent,
+				config.readToolCallBudgetEvents,
+			)
+		}
 		this.config = config
 		this.activityStore = activityStore
 		this.emitEvent = emitEvent
@@ -730,6 +745,18 @@ export class ToolExecutor {
 			if (owned && !this.preparedBatches.has(owned)) {
 				throw new Error('Prepared tool batch is not owned by this executor.')
 			}
+			const refusal = this.toolCallBudget
+				? await this.toolCallBudget.admit(
+						toolCalls.filter((call) => prior?.get(call.id) === undefined).length,
+						'batch',
+						this.config.abortSignal,
+					)
+				: undefined
+			if (refusal) {
+				const refused = new Map(denials)
+				for (const call of toolCalls) if (!refused.has(call.id)) refused.set(call.id, refusal)
+				return await this.runBatch(toolCalls, refused, prior, owned)
+			}
 			return await this.runBatch(toolCalls, denials, prior, owned)
 		} finally {
 			// Cleared so a later single execution outside a batch resolves
@@ -779,6 +806,24 @@ export class ToolExecutor {
 		const results: ToolCallOutcome[] = new Array(toolCalls.length)
 		const parallel: Promise<void>[] = []
 		let serial: Promise<void> = Promise.resolve()
+		let barrier: Promise<void> | undefined
+		const schedule = (run: () => Promise<void>, safe: boolean, isBarrier: boolean): void => {
+			if (isBarrier) {
+				// Settle the entire preceding segment, even when host plumbing
+				// rejects. A rejected host operation prevents dependent execution.
+				barrier = Promise.allSettled([...parallel, serial]).then(async (settled) => {
+					const failed = settled.find((entry) => entry.status === 'rejected')
+					if (failed?.status === 'rejected') throw failed.reason
+					await run()
+				})
+				parallel.length = 0
+				serial = barrier
+			} else if (safe) {
+				parallel.push(barrier ? barrier.then(run) : run())
+			} else {
+				serial = serial.then(run)
+			}
+		}
 		// Bounded fan-out. A model emitting fifty parallel reads used to open
 		// fifty file handles and fifty activity records simultaneously; the
 		// gate keeps that at a working-set size while preserving completion
@@ -786,6 +831,8 @@ export class ToolExecutor {
 		const gate = new Semaphore(this.config.maxToolConcurrency ?? DEFAULT_TOOL_CONCURRENCY)
 		toolCalls.forEach((toolCall, i) => {
 			const preparedCall = preparedBatch?.calls.get(toolCall.id)
+			const tool = this.config.tools.get(preparedCall?.toolName ?? toolCall.function.name)
+			const isBarrier = tool?.executionBarrier === true
 			const recovered = prior?.get(toolCall.id)
 			if (recovered !== undefined) {
 				// This call already ran, in a process that died before the
@@ -798,19 +845,21 @@ export class ToolExecutor {
 					output: recovered.result,
 					isError: recovered.isError,
 				}
+				if (isBarrier) schedule(async () => {}, true, true)
 				return
 			}
 
 			const denialReason = denials?.get(toolCall.id)
 			if (denialReason !== undefined) {
 				// Denied calls never touch the tool; they still get a result
-				// message so the assistant turn stays fully answered. Run them
-				// on the parallel branch — they perform no side effects, so
-				// serialization would only add latency.
-				parallel.push(
-					this.recordDenial(toolCall, denialReason, preparedCall).then((r) => {
-						results[i] = r
-					}),
+				// message so the assistant turn stays fully answered. They can
+				// overlap other calls within a segment, respecting its barriers.
+				schedule(
+					async () => {
+						results[i] = await this.recordDenial(toolCall, denialReason, preparedCall)
+					},
+					true,
+					isBarrier,
 				)
 				return
 			}
@@ -868,13 +917,8 @@ export class ToolExecutor {
 			} catch {
 				// non-JSON args → treat as unsafe (serialize), the conservative path
 			}
-			const preparedToolName = preparedCall?.toolName
-			const safe =
-				this.config.tools
-					.get(preparedToolName ?? toolCall.function.name)
-					?.isConcurrencySafe?.(input) === true
-			if (safe) parallel.push(gated())
-			else serial = serial.then(run)
+			const safe = tool?.isConcurrencySafe?.(input) === true
+			schedule(safe ? gated : run, safe, isBarrier)
 		})
 		await Promise.all([...parallel, serial])
 
@@ -942,8 +986,14 @@ export class ToolExecutor {
 		// retained closure must be observationally inert after its invocation
 		// ends, not merely unable to finish the registry call it already started.
 		signal.throwIfAborted()
+		// Preparation detaches input synchronously before its first await.
+		// Admission must not add an earlier yield where the caller can mutate it.
 		const preparedCall = await this.prepareNestedCall(name, input, signal)
 		signal.throwIfAborted()
+		if (this.toolCallBudget) {
+			const refusal = await this.toolCallBudget.admit(1, 'nested', signal)
+			if (refusal) return { success: false, output: '', error: refusal }
+		}
 		const preparedInput = preparedCall.input
 
 		const parent = context.toolUseId
@@ -1279,6 +1329,9 @@ export class ToolExecutor {
 		settleProgress: () => Promise<void>,
 		preparedCall?: PreparedDirectCall,
 	): Promise<ToolCallOutcome> {
+		if (this.config.abortSignal.aborted) {
+			return this.recordCancelledBeforeExecution(toolCall.id, toolCall.function.name, {})
+		}
 		if (preparedCall?.kind === 'synthetic') {
 			return this.recordSyntheticPreparation(preparedCall)
 		}
@@ -1376,7 +1429,15 @@ export class ToolExecutor {
 
 			input = resolved.input
 
-			const preOutcome = await this.runPreToolHook(toolName, input)
+			let preOutcome: PreToolHookOutcome
+			try {
+				preOutcome = await this.runPreToolHook(toolName, input)
+			} catch (error) {
+				if (!this.config.abortSignal.aborted) throw error
+				// A later call's interrupted preparation must not reject the batch
+				// that already holds an earlier call's settled side-effect receipt.
+				return this.recordCancelledBeforeExecution(toolCall.id, toolName, input)
+			}
 			if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
 				return this.recordSyntheticHookOutcome(toolCall.id, toolName, preOutcome.input, preOutcome)
 			}
@@ -1483,6 +1544,7 @@ export class ToolExecutor {
 			...this.config.toolRetryBackoff,
 		}
 		for (let attempt = 1; ; attempt++) {
+			if (this.config.abortSignal.aborted) break
 			// A missing file will not appear on the second attempt; burning
 			// the budget on it only delays the error the model needs to see.
 			const toolWants = !result.success && result.retryable === true
@@ -1538,6 +1600,19 @@ export class ToolExecutor {
 				break
 			}
 
+			let refusal: string | undefined
+			try {
+				if (this.toolCallBudget)
+					refusal = await this.toolCallBudget.admit(1, 'retry', this.config.abortSignal)
+			} catch (error) {
+				if (this.config.abortSignal.aborted) break
+				throw error
+			}
+			if (refusal) {
+				result = { success: false, output: '', error: refusal }
+				post = { override: null, retry: false }
+				break
+			}
 			result = await this.runOnce(toolName, input, toolContext, prepared)
 			post = await this.runPostToolHook(toolName, input, result)
 		}
@@ -1606,7 +1681,7 @@ export class ToolExecutor {
 
 		if (this.workingStateManager) {
 			extractFromToolResult(this.workingStateManager, toolName, output, effectiveIsError)
-			for (const pin of result.workingState ?? []) {
+			for (const pin of this.config.abortSignal.aborted ? [] : (result.workingState ?? [])) {
 				this.workingStateManager.pin(pin.key, pin.text, toolName)
 			}
 		}
@@ -1623,7 +1698,7 @@ export class ToolExecutor {
 				[NAMZU.RUN_ID]: this.config.runId,
 				[GENAI.TOOL_NAME]: toolName,
 				'namzu.duration_ms': durationMs,
-				'exception.message': result.error ?? 'unknown',
+				'exception.message': postOverride ? output : (result.error ?? 'unknown'),
 			})
 		}
 
@@ -2369,17 +2444,33 @@ export class ToolExecutor {
 		toolResult: ToolResult,
 	): Promise<{ override: PostToolOverride | null; retry: boolean }> {
 		if (!this.config.pluginManager) return { override: null, retry: false }
-		const results = await this.config.pluginManager.executeHooks(
-			'post_tool_use',
-			{
-				runId: this.config.runId,
-				toolName,
-				toolInput: input,
-				toolResult,
-				signal: this.config.abortSignal,
-			},
-			this.emitEvent,
-		)
+		let results: PluginHookResult[]
+		try {
+			results = await this.config.pluginManager.executeHooks(
+				'post_tool_use',
+				{
+					runId: this.config.runId,
+					toolName,
+					toolInput: input,
+					toolResult,
+					signal: this.config.abortSignal,
+				},
+				this.emitEvent,
+			)
+		} catch (error) {
+			if (!this.config.abortSignal.aborted) throw error
+			// The tool has already returned. Cancellation of a later redaction
+			// cannot erase that execution or turn it into a safe-to-repeat call.
+			// Withhold both channels until their post-tool policy has completed.
+			const outcome = toolResult.success
+				? 'reported success before cancellation. The call already executed.'
+				: 'reported failure while cancellation was in progress. Side effects are possible.'
+			const output = `Tool "${toolName}" ${outcome} Output withheld because post-tool review was interrupted. Inspect external state before any retry.`
+			return {
+				override: { output, content: output, isError: !toolResult.success },
+				retry: false,
+			}
+		}
 		let override: PostToolOverride | null = null
 		let retry = false
 		for (const result of results) {
@@ -2484,6 +2575,18 @@ export class ToolExecutor {
 		return { toolCallId: toolCall.id, toolName, output, isError: true }
 	}
 
+	private recordCancelledBeforeExecution(
+		toolCallId: string,
+		toolName: string,
+		input: unknown,
+	): Promise<ToolCallOutcome> {
+		const reason = abortReasonText(this.config.abortSignal.reason)
+		return this.recordSyntheticHookOutcome(toolCallId, toolName, input, {
+			kind: 'error',
+			output: `Tool "${toolName}" was not started because the run was cancelled${reason ? `: ${reason}` : '.'}`,
+		})
+	}
+
 	private async recordSyntheticHookOutcome(
 		toolCallId: string,
 		toolName: string,

package/src/runtime/query/index.ts

@@ -149,8 +149,9 @@ import {
 	resolveSandboxTeardownTimeoutMs,
 	teardownSandbox,
 } from './sandbox-lifecycle.js'
-import { SteeringBinding, type SteeringChannel } from './steering.js'
+import { SteeringBinding, type SteeringChannel, isOperatorUserMessage } from './steering.js'
 import { resolveQueryBudget } from './token-budget.js'
+import { assertMaxToolCalls } from './tool-call-budget.js'
 import { ToolGrantSet } from './tool-grants.js'
 import { createToolPause } from './tool-pause.js'
 import { ToolingBootstrap } from './tooling.js'
@@ -349,6 +350,8 @@ export interface QueryParams {
 
 	/** Max concurrently-executing concurrency-safe tools in one batch. */
 	maxToolConcurrency?: number
+	/** Per-run cumulative tool attempt limit, including nested calls and retries. Unset is unlimited. Re-supply on resume; durable reservations are never refunded. */
+	maxToolCalls?: number
 
 	/**
 	 * Model-visible size cap for a single tool result. Over-budget output is
@@ -450,14 +453,9 @@ export interface QueryParams {
 	beforeStep?: BeforeStep
 
 	/**
-	 * Force the run to finish by calling a schema-validated tool, and land
-	 * the parsed value on `Run.structuredOutput`.
-	 *
-	 * Both leaf pieces already shipped and neither was reachable:
-	 * `createStructuredOutputTool` is excluded from the default builtin set,
-	 * and `StructuredOutputConfig` had no field on QueryParams at all. A host
-	 * needing a typed result had to register the tool by hand and hope —
-	 * nothing forced the call, and nothing stopped the loop when it came.
+	 * Produce a locally validated structured result. Defaults to an output tool;
+	 * mode:'native' requests JSON Schema from an explicitly capable driver.
+	 * Host review and bounded corrections apply before publication.
 	 */
 	structuredOutput?: StructuredOutputConfig
 
@@ -671,6 +669,13 @@ export interface QueryParams {
 	 * started. See `BaseAgentConfig.inboundMessages` for what it closes.
 	 */
 	inboundMessages?: () => import('../../types/message/index.js').Message[]
+	/**
+	 * 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;
+	 * the supplied signal ends the wait and must release any listeners. Messages are
+	 * still consumed only through `inboundMessages` at a provider-valid boundary.
+	 */
+	waitForInbound?: (signal: AbortSignal) => Promise<void>
 
 	/**
 	 * Live project policy for this run. Unlike `inboundMessages`, snapshot
@@ -1020,6 +1025,19 @@ function withoutOwnedResumeTurn(
 }
 
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
+	assertMaxToolCalls(params.maxToolCalls)
+	// Required types do not protect JavaScript callers. Reject missing scope
+	// before opening a budget or persisting a run without its owning identity.
+	const missingFields = (['sessionId', 'topicId', 'projectId', 'tenantId'] as const).filter(
+		(field) => !params[field],
+	)
+	if (missingFields.length > 0) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `query requires sessionId, topicId, projectId, and tenantId; missing: ${missingFields.join(', ')}.`,
+			details: { missingFields },
+		})
+	}
 	const selectedResumeState = selectedResumeStates.get(params)
 	selectedResumeStates.delete(params)
 	// Resolved at the DOOR, before a run id exists or a logger is built.
@@ -1147,6 +1165,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		runConfig.timeoutMs,
 		log,
 	)
+	const modelContextWindows = new Map<string, number | undefined>()
+	if (runConfig.model) modelContextWindows.set(runConfig.model, providerContextWindow)
 
 	// The mode this conversation was left in, when the run config names none.
 	// Read once, before the loop exists, for the same reason the context
@@ -1549,7 +1569,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	// invalidate the whole prompt cache for the rest of the run — the same
 	// reason the forced-final turn keeps its tools array and uses
 	// `toolChoice: 'none'` instead of dropping it.
-	if (params.structuredOutput && !params.tools.has(STRUCTURED_OUTPUT_TOOL_NAME)) {
+	if (
+		params.structuredOutput &&
+		params.structuredOutput.mode !== 'native' &&
+		!params.tools.has(STRUCTURED_OUTPUT_TOOL_NAME)
+	) {
 		params.tools.register(createStructuredOutputTool(params.structuredOutput.schema))
 	}
 
@@ -1711,6 +1735,13 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			...(params.toolRetryBackoff !== undefined
 				? { toolRetryBackoff: params.toolRetryBackoff }
 				: {}),
+			...(params.maxToolCalls !== undefined
+				? {
+						maxToolCalls: params.maxToolCalls,
+						readToolCallBudgetEvents: () =>
+							ctx.runMgr.getRunStore().readEvents({ integrity: 'strict' }),
+					}
+				: {}),
 			...(params.maxToolConcurrency !== undefined
 				? { maxToolConcurrency: params.maxToolConcurrency }
 				: {}),
@@ -1963,10 +1994,27 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		...(params.repeatCallAdvisory === false ? {} : { repeatCalls: new RepeatCallTracker() }),
 		compactionConfig,
 		...(params.inboundMessages ? { inboundMessages: params.inboundMessages } : {}),
+		...(params.resumeFromCheckpoint ? { resumedInput: queuedForThisRun } : {}),
+		...(params.waitForInbound ? { waitForInbound: params.waitForInbound } : {}),
 		...(params.projectInstructionContext
 			? { projectInstructionContext: params.projectInstructionContext }
 			: {}),
 		...(providerContextWindow !== undefined ? { providerContextWindow } : {}),
+		resolveModelContextWindow: async (model) => {
+			if (!modelContextWindows.has(model)) {
+				modelContextWindows.set(
+					model,
+					await resolveProviderContextWindow(
+						resilientProvider,
+						model,
+						ctx.abortController.signal,
+						runConfig.timeoutMs,
+						log,
+					),
+				)
+			}
+			return modelContextWindows.get(model)
+		},
 		workingStateManager,
 		taskRouter: params.taskRouter,
 		contextReducer: params.contextReducer,
@@ -2325,7 +2373,6 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				}
 			} else {
 				pushSystemMessages()
-				let isFirstUserMessage = true
 				for (const msg of initialMessages) {
 					if (msg.role === 'system') {
 						// A fresh run rebuilds its current static/dynamic prompt above,
@@ -2343,11 +2390,18 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 						continue
 					}
 					ctx.runMgr.pushMessage(msg)
-
-					if (workingStateManager && msg.role === 'user' && msg.content) {
-						extractFromUserMessage(workingStateManager, msg.content, isFirstUserMessage)
-						isFirstUserMessage = false
-					}
+				}
+			}
+			// Fresh and continuation histories seed the same operator state.
+			// A worker report or project-policy message may have role `user`,
+			// but it must not become the task or an operator requirement.
+			// Resume restores this state and adopts only its newer queue arrivals.
+			if (!params.resumeFromCheckpoint && workingStateManager) {
+				let isFirstUserMessage = true
+				for (const message of initialMessages) {
+					if (!isOperatorUserMessage(message) || !message.content.trim()) continue
+					extractFromUserMessage(workingStateManager, message.content, isFirstUserMessage)
+					isFirstUserMessage = false
 				}
 			}
 
@@ -2705,6 +2759,16 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					ctx.log,
 				)
 
+				if (outputVerdict.blocked || outputVerdict.rewritten !== undefined) {
+					ctx.runMgr.clearStructuredOutput()
+					if (
+						params.structuredOutput &&
+						outputVerdict.rewritten !== undefined &&
+						ctx.runMgr.stopReason === 'end_turn'
+					)
+						ctx.runMgr.setStopReason('output_guardrail')
+				}
+
 				if (outputVerdict.blocked) {
 					await eventTranslator.emitEvent({
 						type: 'guardrail_triggered',
@@ -2765,6 +2829,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					}
 				}
 			}
+			if (ctx.abortController.signal.aborted) ctx.runMgr.markCancelled()
 			yield* resultAssembler.completeRun(rootSpan)
 		} catch (err) {
 			// A failed run still spent its steps; report them.