@namzu/sdk 36.0.0 → 38.0.0

package/src/runtime/query/executor.ts

@@ -11,8 +11,8 @@ import { probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ProbeEnforcement } from '../../probe/registry.js'
 import { renderToolSchema } from '../../registry/tool/schema.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
-import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
 import { SKILL_TOOL_NAME } from '../../tools/builtins/skill.js'
+import { createFileReadTracker } from '../../tools/file-read-tracker.js'
 import type { RunId, ToolUseId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import {
@@ -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,
@@ -289,6 +290,7 @@ function parseArguments(raw: string): unknown {
 }
 
 export interface ToolExecutorConfig {
+	fileReadTracker?: FileReadTracker
 	tools: ToolRegistryContract
 	runId: RunId
 	workingDirectory: string
@@ -356,6 +358,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,23 +498,11 @@ 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[]
-	private readonly readPaths: Set<string> = new Set()
-	private readonly readFingerprints: Map<string, string> = new Map()
-	private readonly fileReadTracker: FileReadTracker = {
-		recordRead: (key: string, content?: string) => {
-			this.readPaths.add(key)
-			// Only when the reader had the body. A tool that records a read
-			// without one leaves the previous fingerprint alone rather than
-			// clearing it, so a later write is still checked against the last
-			// body anyone actually saw.
-			if (content !== undefined) this.readFingerprints.set(key, fingerprintContent(content))
-		},
-		hasRead: (key: string) => this.readPaths.has(key),
-		fingerprint: (key: string) => this.readFingerprints.get(key),
-	}
+	private readonly fileReadTracker: FileReadTracker
 
 	constructor(
 		config: ToolExecutorConfig,
@@ -517,6 +511,16 @@ 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.fileReadTracker = config.fileReadTracker ?? createFileReadTracker()
 		this.config = config
 		this.activityStore = activityStore
 		this.emitEvent = emitEvent
@@ -730,6 +734,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 +795,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 +820,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 +834,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 +906,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 +975,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
@@ -1161,6 +1200,7 @@ export class ToolExecutor {
 			toolUseId: nestedId,
 			toolName: name,
 			result: budgeted.output,
+			...(!budgeted.truncated ? this.resultPresentation(name, preparedInput, result) : {}),
 			isError: !result.success,
 			durationMs: Date.now() - startedAt,
 			outputLength: budgeted.originalLength,
@@ -1180,6 +1220,21 @@ export class ToolExecutor {
 		return visibleResult
 	}
 
+	private resultPresentation(name: string, input: unknown, result: ToolResult) {
+		if (!result.success) return {}
+		try {
+			const view = this.config.tools.get(name)?.presentResult?.(input, result)
+			if (view?.kind !== 'diff') return {}
+			const serialized = JSON.stringify(view)
+			if (serialized.length > (this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS))
+				return {}
+			return { presentation: view }
+		} catch {
+			// A presentation hook must not fail an already completed mutation.
+			return {}
+		}
+	}
+
 	private buildToolContext(
 		recordObservation: (observation: ToolResultObservation) => void = () => {},
 	): ToolContext {
@@ -1550,6 +1605,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)
 		}
@@ -1658,6 +1726,9 @@ export class ToolExecutor {
 			toolUseId: toolCall.id,
 			toolName,
 			result: output,
+			...(!postOverride && !budgeted.truncated && rawOutput === output
+				? this.resultPresentation(toolName, input, result)
+				: {}),
 			isError: effectiveIsError,
 			durationMs,
 			// Pre-truncation size, so a host can show "returned 2.1 MB" even

package/src/runtime/query/index.ts

@@ -149,13 +149,16 @@ 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'
 
 export interface QueryParams {
+	/** Share observations across turns of one conversation and filesystem; otherwise run-local. */
+	fileReadTracker?: import('../../types/tool/index.js').FileReadTracker
 	/** One account shared with the task scheduler and descendant runs. */
 	budget?: TokenBudget
 	/** Canonical tree ledger; defaults to disk beside the root run. */
@@ -349,6 +352,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 +455,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
 
@@ -1027,6 +1027,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.
@@ -1154,6 +1167,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
@@ -1556,7 +1571,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))
 	}
 
@@ -1714,10 +1733,18 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// registry would answer about whatever the last run configured.
 			...(params.skillRegistry ? { skills: params.skillRegistry } : {}),
 			...(params.web ? { web: params.web } : {}),
+			...(params.fileReadTracker ? { fileReadTracker: params.fileReadTracker } : {}),
 			...(params.toolTimeoutMs !== undefined ? { toolTimeoutMs: params.toolTimeoutMs } : {}),
 			...(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 }
 				: {}),
@@ -1970,11 +1997,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,
@@ -2333,7 +2376,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,
@@ -2351,11 +2393,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
 				}
 			}
 
@@ -2713,6 +2762,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',
@@ -2773,6 +2832,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.