@namzu/sdk 38.1.0 → 39.0.0

package/src/runtime/query/executor.ts

@@ -43,12 +43,14 @@ import type {
 	ToolCallRepairReason,
 } from '../../types/tool/repair.js'
 import { abortReasonText } from '../../utils/abort.js'
+import { awaitWithAbort } from '../../utils/await-with-abort.js'
 import { type BackoffPolicy, backoffWithJitter, sleep } from '../../utils/backoff.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { generateToolCallId } from '../../utils/id.js'
 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 { describeVisibleFileEvidence } from './file-evidence-context.js'
 import type { ToolResultObservation } from './project-instructions.js'
 import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js'
 import {
@@ -376,6 +378,8 @@ export interface ToolExecutorConfig {
 	 * {@link DEFAULT_MAX_TOOL_OUTPUT_CHARS}; set `0` to disable.
 	 */
 	maxToolOutputChars?: number
+	/** See QueryParams.retainedToolPreviewChars; applies to the recorded host output. */
+	retainedToolPreviewChars?: number
 
 	/**
 	 * Cap on the RICH channel of a single tool result, in base64
@@ -401,7 +405,8 @@ export interface ToolExecutorConfig {
 	 * with `read`/`grep`. Absent ⇒ over-budget output is middle-elided and
 	 * the overflow is lost.
 	 */
-	toolOutputDir?: string
+	captureRunEvidence?: ToolContext['captureRunEvidence']
+	toolOutputDir?: string | (() => string | undefined)
 	/**
 	 * Last chance to fix a tool call the model got wrong, before the error
 	 * reaches it. See {@link RepairToolCall}.
@@ -491,6 +496,12 @@ export function deniedToolOutput(toolName: string, reason: string): string {
 }
 
 export class ToolExecutor {
+	private outputDirectory(): string | undefined {
+		return typeof this.config.toolOutputDir === 'function'
+			? this.config.toolOutputDir()
+			: this.config.toolOutputDir
+	}
+
 	private config: ToolExecutorConfig
 	private activityStore: ActivityStore
 	private emitEvent: EmitEvent
@@ -536,6 +547,16 @@ export class ToolExecutor {
 		this.config = { ...this.config, sandbox }
 	}
 
+	/** Request-only evidence from the same ledger used by mutation admission. No filesystem I/O. */
+	describeFileEvidence(messages: readonly Message[]): string | undefined {
+		return describeVisibleFileEvidence(
+			messages,
+			this.fileReadTracker,
+			this.config.workingDirectory,
+			this.config.sandbox !== undefined,
+		)
+	}
+
 	/**
 	 * Span that this executor's tool spans should hang off — the current
 	 * iteration. Re-set each turn by the orchestrator, because a tool span
@@ -1175,7 +1196,8 @@ export class ToolExecutor {
 			toolUseId: nestedId,
 			output: rawOutput,
 			maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
-			spillDir: this.config.toolOutputDir,
+			retainedPreviewChars: this.config.retainedToolPreviewChars,
+			spillDir: this.outputDirectory(),
 			onError: (message) =>
 				this.log.warn('Failed to spill oversized nested tool output', {
 					[NAMZU.RUN_ID]: this.config.runId,
@@ -1206,6 +1228,7 @@ export class ToolExecutor {
 			outputLength: budgeted.originalLength,
 			...(budgeted.truncated ? { outputTruncated: true } : {}),
 			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
+			...(budgeted.spillIntegrity ? { outputSpillIntegrity: budgeted.spillIntegrity } : {}),
 			...(via ? { via } : {}),
 		})
 		recordObservation({
@@ -1253,6 +1276,7 @@ export class ToolExecutor {
 				workingDirectory: this.config.workingDirectory,
 			},
 			invocationState: this.config.invocationState,
+			captureRunEvidence: this.config.captureRunEvidence,
 			toolRegistry: this.config.tools,
 			// The step's list wins where it has one; the run's is the default.
 			// Same precedence the request already uses when it decides which
@@ -1628,8 +1652,8 @@ export class ToolExecutor {
 			: formatFailedToolOutput(result.output, result.error)
 
 		const postOverride = post.override
-		let output =
-			postOverride?.output ?? (result.success ? this.maybeCompress(toolName, rawOutput) : rawOutput)
+		let output = postOverride?.output ?? rawOutput
+		const preview = !postOverride && result.success ? this.maybeCompress(toolName, output) : output
 		let selectedContent = postOverride?.isError
 			? undefined
 			: (postOverride?.content ?? result.content)
@@ -1655,16 +1679,22 @@ export class ToolExecutor {
 			toolName,
 			toolUseId: toolCall.id,
 			output,
+			preview,
 			maxChars: maxToolOutputChars,
-			spillDir: this.config.toolOutputDir,
+			retainedPreviewChars: this.config.retainedToolPreviewChars,
+			spillDir: this.outputDirectory(),
 			onError: (message) =>
-				this.log.warn('Failed to spill oversized tool output', {
+				this.log.warn('Failed to retain original tool output', {
 					[NAMZU.RUN_ID]: this.config.runId,
 					[GENAI.TOOL_NAME]: toolName,
 					'exception.message': message,
 				}),
 		})
-		if (budgeted.truncated) {
+		if (
+			budgeted.truncated &&
+			maxToolOutputChars > 0 &&
+			budgeted.originalLength > maxToolOutputChars
+		) {
 			this.log.warn('Tool output exceeded the model-visible budget', {
 				[NAMZU.RUN_ID]: this.config.runId,
 				[GENAI.TOOL_NAME]: toolName,
@@ -1736,6 +1766,7 @@ export class ToolExecutor {
 			outputLength: budgeted.originalLength,
 			...(budgeted.truncated ? { outputTruncated: true } : {}),
 			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
+			...(budgeted.spillIntegrity ? { outputSpillIntegrity: budgeted.spillIntegrity } : {}),
 		})
 		recordObservation({
 			runId: this.config.runId,
@@ -1864,9 +1895,20 @@ export class ToolExecutor {
 				}
 			}
 
+			const inheritedCapture = toolContext.captureRunEvidence
+			const scopedCapture: ToolContext['captureRunEvidence'] = inheritedCapture
+				? async (maxReadBytes, signal) => {
+						const combined = signal
+							? AbortSignal.any([controller.signal, signal])
+							: controller.signal
+						combined.throwIfAborted()
+						return awaitWithAbort(inheritedCapture(maxReadBytes, combined), combined)
+					}
+				: undefined
 			const context = {
 				...toolContext,
 				abortSignal: controller.signal,
+				...(scopedCapture ? { captureRunEvidence: scopedCapture } : {}),
 				...(scopedDispatch ? { dispatchTool: scopedDispatch } : {}),
 			}
 			const execution = prepared
@@ -2686,8 +2728,8 @@ export class ToolExecutor {
 						...(notice ? { notice } : {}),
 						// A tool may return different host and model text. They must
 						// never compete for the same exclusive spill filename.
-						spillDir: this.config.toolOutputDir
-							? join(this.config.toolOutputDir, 'content')
+						spillDir: this.outputDirectory()
+							? join(this.outputDirectory() as string, 'content')
 							: undefined,
 						onError: (message) =>
 							this.log.warn('Failed to spill oversized model tool content', {

package/src/runtime/query/file-evidence-context.ts

@@ -0,0 +1,65 @@
+import { resolve } from 'node:path'
+import { isClearedToolResult } from '../../compaction/tool-result-editing.js'
+import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
+import { WriteFileTool } from '../../tools/builtins/write-file.js'
+import type { Message, ToolCall } from '../../types/message/index.js'
+import type { FileReadTracker } from '../../types/tool/index.js'
+
+/** Join visible call bodies, successful receipts and this executor's observation ledger. */
+export function describeVisibleFileEvidence(
+	messages: readonly Message[],
+	tracker: FileReadTracker,
+	workingDirectory: string,
+	sandboxed: boolean,
+): string | undefined {
+	// Execution-owned witnesses survive transparent wrappers; a name alone proves nothing.
+	if (!tracker.writeCallId || !tracker.fingerprint) return
+	const calls = new Map<string, ToolCall | null>()
+	const results = new Map<string, Message | null>()
+	for (const message of messages) {
+		if (message.role === 'assistant') {
+			for (const call of message.toolCalls ?? []) {
+				calls.set(call.id, calls.has(call.id) ? null : call)
+			}
+		} else if (message.role === 'tool') {
+			results.set(message.toolCallId, results.has(message.toolCallId) ? null : message)
+		}
+	}
+	const files = new Map<string, { path: string; bodyInCall: string; observedFingerprint: string }>()
+	for (const [id, call] of calls) {
+		const receipt = results.get(id)
+		if (
+			!call ||
+			call.function.name !== 'write' ||
+			call.metadata?.inputTruncated ||
+			call.function.arguments.length > 32_000 ||
+			id.length > 256 ||
+			!receipt ||
+			receipt.role !== 'tool' ||
+			receipt.isError ||
+			typeof receipt.content !== 'string' ||
+			isClearedToolResult(receipt.content)
+		)
+			continue
+		try {
+			const input = WriteFileTool.inputSchema.safeParse(JSON.parse(call.function.arguments))
+			if (!input.success || input.data.path.length > 512) continue
+			const body = input.data.content ?? input.data.newStr
+			if (typeof body !== 'string') continue
+			const key = sandboxed ? input.data.path : resolve(workingDirectory, input.data.path)
+			const fingerprint = fingerprintContent(body)
+			if (tracker.writeCallId(key) !== id || tracker.fingerprint(key) !== fingerprint) continue
+			files.delete(key)
+			files.set(key, {
+				path: input.data.path,
+				bodyInCall: id,
+				observedFingerprint: fingerprint,
+			})
+			if (files.size > 6) files.delete(files.keys().next().value as string)
+		} catch {
+			// Malformed retained inputs or a custom tracker cannot establish evidence.
+		}
+	}
+	if (files.size === 0) return
+	return `Visible file evidence (this request only): each complete body remains in the named successful write call and matches the latest conversation observation. Reuse that body for a targeted edit; a read solely to recall it is unnecessary. This is NOT a fresh disk check. Built-in edit/write still compare the disk body at mutation admission and refuse observed drift; on refusal inspect the current file and replan. Missing entries establish nothing.\n${JSON.stringify([...files.values()])}`
+}

package/src/runtime/query/guard.ts

@@ -83,6 +83,7 @@ export class GuardCoordinator {
 	 * on the RUN rather than on the process now hosting it.
 	 */
 	remainingBeforeFinalizeMs(): number {
+		if (this.limitConfig.timeoutMs === 0) return Number.POSITIVE_INFINITY
 		const finalizeAt = this.limitConfig.timeoutMs * this.limitConfig.budgetWarningThreshold
 		return Math.max(0, finalizeAt - (Date.now() - this.startTime))
 	}
@@ -96,6 +97,7 @@ export class GuardCoordinator {
 	 * deadline around such work instead of inventing a second clock.
 	 */
 	remainingUntilTimeoutMs(): number {
+		if (this.limitConfig.timeoutMs === 0) return Number.POSITIVE_INFINITY
 		return Math.max(0, this.limitConfig.timeoutMs - (Date.now() - this.startTime))
 	}
 

package/src/runtime/query/index.ts

@@ -139,10 +139,10 @@ import { ResultAssembler } from './result.js'
 import {
 	type PendingResumePlan,
 	applyPendingResume,
+	interruptedToolCalls,
 	planCrashResume,
 	planPendingResume,
 	recoverCompletedCalls,
-	unansweredToolCalls,
 } from './resume-pending.js'
 import {
 	acquireSandbox,
@@ -362,6 +362,14 @@ export interface QueryParams {
 	 * agent decides the rest is worth re-reading. Set `0` to disable.
 	 */
 	maxToolOutputChars?: number
+	/**
+	 * Smaller preview for text that exceeded maxToolOutputChars, after its full
+	 * host output and integrity manifest have been saved. Unset/0 keeps the old
+	 * preview size. Does not change the spill threshold, rich blocks or ordinary
+	 * results. A failed spill/manifest or a cap too small for its recovery path
+	 * retains the ordinary output budget. Re-supply on resume.
+	 */
+	retainedToolPreviewChars?: number
 
 	/**
 	 * Cap on the RICH channel of a single tool result, in base64 characters.
@@ -411,6 +419,7 @@ export interface QueryParams {
 	 *
 	 * Bounded by {@link maxAnswerReviews}. Never called on the forced-final
 	 * turn, which exists to extract a closing summary under pressure.
+	 * Exceptions or malformed verdicts fail the run; cancellation stops waiting.
 	 */
 	reviewAnswer?: ReviewAnswer
 
@@ -422,7 +431,7 @@ export interface QueryParams {
 	 */
 	promoteMemory?: PromoteMemory
 
-	/** Rejections allowed before the run stops. Default 3. */
+	/** Corrections allowed before the run stops. Nonnegative safe integer; default 3. Consumed rejections survive checkpoints. */
 	maxAnswerReviews?: number
 
 	/** Called with each completed step, as it completes. */
@@ -931,11 +940,10 @@ async function resolveProviderContextWindow(
 		onAbort = () => resolve(interrupted)
 		resolverSignal.addEventListener('abort', onAbort, { once: true })
 	})
-	// Wire and directory config validation already limit this field to one
-	// hour. The clamp also keeps a direct QueryParams caller from triggering
-	// Node's >2^31-1 one-millisecond timer coercion and turning a huge run
-	// budget into an immediate metadata fallback.
-	const deadlineMs = Math.min(Math.max(0, timeoutMs), 2_147_483_647)
+	// Direct QueryParams callers can supply a large run deadline. The clamp
+	// avoids Node's >2^31-1 one-millisecond timer coercion during metadata lookup.
+	// Metadata discovery remains optional and bounded even without a run deadline.
+	const deadlineMs = timeoutMs === 0 ? 5_000 : Math.min(Math.max(0, timeoutMs), 2_147_483_647)
 	const timer = setTimeout(() => {
 		deadline.abort(new Error(`Provider context-window lookup exceeded ${deadlineMs}ms`))
 	}, deadlineMs)
@@ -1707,10 +1715,24 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		? new AuthorizationGate(gateConfig, ctx.log)
 		: undefined
 
-	//  is null only when the run has no disk layout (tests,
-	// in-memory hosts); the budget then degrades to middle-elision.
-	const runDirForTools = ctx.runMgr.getRunDir()
-	const toolOutputDir = runDirForTools ? join(runDirForTools, TOOL_OUTPUT_DIR_NAME) : undefined
+	// The store is initialized when the async query starts, after tooling is
+	// composed. Resolve lazily at execution time: capturing getRunDir() here
+	// permanently disabled retention for fresh disk-backed invocations.
+	const toolOutputDir = () => {
+		const runDir = ctx.runMgr.getRunDir()
+		return runDir ? join(runDir, TOOL_OUTPUT_DIR_NAME) : undefined
+	}
+	// The same invocation-owned capability serves tools and optional preparation.
+	// Local cancellation cannot override the run's cancellation or settled state.
+	const captureRunEvidence = async (maxReadBytes?: number, signal?: AbortSignal) => {
+		const combined = signal
+			? AbortSignal.any([ctx.abortController.signal, signal])
+			: ctx.abortController.signal
+		combined.throwIfAborted()
+		const source = await eventTranslator.captureRunEvidence(maxReadBytes, combined)
+		combined.throwIfAborted()
+		return source
+	}
 
 	const toolExecutor = ToolingBootstrap.init(
 		{
@@ -1741,8 +1763,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			...(params.maxToolCalls !== undefined
 				? {
 						maxToolCalls: params.maxToolCalls,
-						readToolCallBudgetEvents: () =>
-							ctx.runMgr.getRunStore().readEvents({ integrity: 'strict' }),
+						readToolCallBudgetEvents: () => eventTranslator.readEvents({ integrity: 'strict' }),
 					}
 				: {}),
 			...(params.maxToolConcurrency !== undefined
@@ -1751,13 +1772,17 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			...(params.maxToolOutputChars !== undefined
 				? { maxToolOutputChars: params.maxToolOutputChars }
 				: {}),
+			...(params.retainedToolPreviewChars !== undefined
+				? { retainedToolPreviewChars: params.retainedToolPreviewChars }
+				: {}),
 			...(params.maxToolContentBytes !== undefined
 				? { maxToolContentBytes: params.maxToolContentBytes }
 				: {}),
 			// Overflow lands beside the run's other artifacts, so it is
 			// cleaned up with the run and reachable by the model's own
 			// `read`/`grep` without a new affordance.
-			...(toolOutputDir ? { toolOutputDir } : {}),
+			toolOutputDir,
+			captureRunEvidence,
 			...(params.repairToolCall ? { repairToolCall: params.repairToolCall } : {}),
 			...(verificationGate ? { authorizationGate: verificationGate } : {}),
 			recordAudit: (input) => ctx.runMgr.recordAudit(input),
@@ -1931,6 +1956,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					: undefined
 			return {
 				messages: ctx.runMgr.messages,
+				turn: iterationOrchestrator.getAdvisoryTurnContext(),
 				...(summary !== undefined ? { workingStateSummary: summary } : {}),
 				...(advisoryConfig.includeToolCatalog
 					? { toolCatalog: params.tools.toLLMTools(effectiveAllowedTools) }
@@ -1951,6 +1977,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 	}
 
 	const iterationOrchestrator = new IterationOrchestrator({
+		captureRunEvidence,
 		provider: resilientProvider,
 		providerCapabilities: capabilities,
 		strictCapabilities: params.strictCapabilities === true,
@@ -2295,23 +2322,19 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 						? planPendingResume(projectedCheckpoint, params.pendingDecision, ctx.log)
 						: null
 
-				// Results of tools that finished before the process died. The
-				// executor already emits one `tool_completed` per tool inline
-				// and the transcript already persists it, so the record was
-				// durable all along — it was simply never read back, and the
-				// resumed run re-ran calls that had already charged a card or
-				// sent an email.
-				const unanswered = unansweredToolCalls(projectedCheckpoint.messages)
+				// Recover completed observations and explicitly unknown outcomes.
+				// A recorded start is not proof that its external effect failed.
+				const unanswered = interruptedToolCalls(projectedCheckpoint.messages)
 				recoveredResults =
 					unanswered.length > 0
-						? await recoverCompletedCalls(ctx.runMgr, unanswered, ctx.log)
+						? await recoverCompletedCalls(ctx.runMgr, unanswered, ctx.log, {
+								answers: pendingResume?.answers,
+								signal: ctx.abortController.signal,
+							})
 						: new Map()
 
-				// A batch caught MID-execution is a resume, not a fresh
-				// decision: stripping the turn and letting the model re-decide
-				// would re-run everything that already ran. Only taken when
-				// the transcript proves execution had begun — a tool-review
-				// park has no completions and keeps the cheap repair below.
+				// Preserve both known and unknown outcomes before continuing calls
+				// whose absence of a start was established by a complete scan.
 				if (!pendingResume && recoveredResults.size > 0) {
 					pendingResume = planCrashResume(projectedCheckpoint, recoveredResults, ctx.log)
 				}