@namzu/sdk 49.0.0 → 50.1.0

package/src/runtime/query/repeat-call.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import { createRuntimeContextMessage } from '../../types/message/index.js'
 import type { Message } from '../../types/message/index.js'
 import { stableStringify } from './tool-grants.js'
@@ -66,8 +67,8 @@ export class RepeatCallTracker {
 	/** Which keys have already been reported at which level, so one repeat
 	 *  does not produce the same sentence on every subsequent turn. */
 	private readonly announced = new Map<string, 'notice' | 'escalated'>()
-	/** Consecutive failures per key; a success deletes the entry. */
-	private readonly failures = new Map<string, number>()
+	/** Identical actual results since the last successful possible mutation. */
+	private readonly failures = new Map<string, { fingerprint: string; count: number }>()
 
 	constructor(private readonly thresholds: RepeatCallThresholds = DEFAULT_REPEAT_THRESHOLDS) {}
 
@@ -80,13 +81,12 @@ export class RepeatCallTracker {
 	record(
 		toolName: string,
 		input: unknown,
-		outcome?: { readonly failed: boolean },
+		outcome?: { readonly failed: boolean; readonly result?: unknown },
 	): RepeatCallNotice | undefined {
 		const key = keyFor(toolName, input)
 		const count = (this.counts.get(key) ?? 0) + 1
 		this.counts.set(key, count)
-		if (outcome?.failed === true) this.failures.set(key, (this.failures.get(key) ?? 0) + 1)
-		else if (outcome?.failed === false) this.failures.delete(key)
+		if (outcome) this.recordOutcome(toolName, input, outcome)
 
 		const already = this.announced.get(key)
 		if (count >= this.thresholds.escalateAfter && already !== 'escalated') {
@@ -95,7 +95,7 @@ export class RepeatCallTracker {
 				toolName,
 				count,
 				level: 'escalated',
-				text: `You have now called \`${toolName}\` with identical arguments ${count} times in this turn. Repeating it again will produce the same result. Change the arguments, use a different tool, or tell the user what is blocking you and stop.`,
+				text: `You have now called \`${toolName}\` with identical arguments ${count} times in this turn. Check whether the results or the state have changed. If there is no progress, change the approach or tell the user what is blocking you.`,
 			}
 		}
 		if (count >= this.thresholds.notifyAfter && already === undefined) {
@@ -110,6 +110,33 @@ export class RepeatCallTracker {
 		return undefined
 	}
 
+	/** Only actual executions count. Denials and recovered receipts do not. */
+	recordOutcome(
+		toolName: string,
+		input: unknown,
+		outcome: { readonly failed: boolean; readonly result?: unknown },
+	): void {
+		const key = keyFor(toolName, input)
+		if (!outcome.failed) {
+			this.failures.delete(key)
+			return
+		}
+		const fingerprint = createHash('sha256')
+			.update(stableStringify(outcome.result ?? null))
+			.digest('hex')
+		const previous = this.failures.get(key)
+		this.failures.set(key, {
+			fingerprint,
+			count: previous?.fingerprint === fingerprint ? previous.count + 1 : 1,
+		})
+	}
+
+	/** A successful potentially mutating execution permits a new experiment.
+	 * This does not prove progress; the turn's existing budgets still apply. */
+	stateMayHaveChanged(): void {
+		this.failures.clear()
+	}
+
 	/** Repeats seen for one call, for a host that wants to render it. */
 	countOf(toolName: string, input: unknown): number {
 		return this.counts.get(keyFor(toolName, input)) ?? 0
@@ -118,11 +145,11 @@ export class RepeatCallTracker {
 	/**
 	 * The refusal for a call that has failed identically too many times in
 	 * a row, or `undefined` when the call may run. Asked BEFORE execution;
-	 * the refused call is still recorded afterwards, as a failure, so the
-	 * refusal holds until the model changes something.
+	 * a synthetic refusal is not an execution and does not replace its result
+	 * fingerprint. The refusal holds until a real state change or new outcome.
 	 */
 	refusal(toolName: string, input: unknown): string | undefined {
-		const failed = this.failures.get(keyFor(toolName, input)) ?? 0
+		const failed = this.failures.get(keyFor(toolName, input))?.count ?? 0
 		if (failed < this.thresholds.refuseFailedAfter) return undefined
 		return `Refused: \`${toolName}\` with these exact arguments has failed ${failed} times in a row in this turn, with the same result each time. It will not be run again with these arguments. Change the arguments, use a different tool, or tell the user what is blocking you and stop.`
 	}
@@ -167,7 +194,10 @@ export function attachRepeatNotice(
 
 	if (target && typeof target.content === 'string') {
 		const next = [...messages]
-		next[lastToolIndex] = { ...target, content: `${target.content}\n\n${noticeText}` }
+		next[lastToolIndex] = {
+			...target,
+			content: `${target.content}\n\n${noticeText}`,
+		}
 		return next
 	}
 

package/src/runtime/query/resume-pending.ts

@@ -15,7 +15,14 @@ import type { ToolExecutionSnapshot } from '../../types/session/tool-execution.j
 import type { Logger } from '../../utils/logger.js'
 import type { RestoredCheckpoint } from './checkpoint.js'
 import { DECLINED_TOOL_CALL_FEEDBACK } from './declined.js'
-import type { PriorToolResults, ToolCallDenials, ToolExecutor } from './executor.js'
+import type {
+	PriorToolResult,
+	PriorToolResults,
+	ToolCallDeclines,
+	ToolCallDenials,
+	ToolExecutionBatch,
+	ToolExecutor,
+} from './executor.js'
 import { PendingAnswers } from './question-park.js'
 import { readToolExecutions } from './tool-executions.js'
 import { isPauseForCall } from './tool-pause.js'
@@ -60,6 +67,8 @@ export interface PendingResumePlan {
 	readonly response: ChatCompletionResponse
 	/** Per-call refusals derived from the decision. */
 	readonly denials: ToolCallDenials
+	/** The denials a person gave; see {@link ToolCallDeclines}. Absent for every other refusal. */
+	readonly declines?: ToolCallDeclines
 	/** Exact projections and gate decisions persisted with a tool review. */
 	readonly reviewedCalls?: readonly ToolCallSummary[]
 	/** Calls whose raw input the human replaced in the durable decision. */
@@ -139,6 +148,7 @@ export function planPendingResume(
 
 	const denials = derriveDenials(assistant.toolCalls, decision)
 	if (!denials) return null
+	const declines = derriveDeclines(assistant.toolCalls, decision, pending.request.toolCalls)
 
 	return {
 		source: 'decision',
@@ -146,6 +156,7 @@ export function planPendingResume(
 		assistant,
 		response: synthesizeResponse(assistant),
 		denials,
+		...(declines ? { declines } : {}),
 		reviewedCalls: pending.request.toolCalls,
 		modifiedCallIds: modifiedCallIds(decision),
 		...((decision.action === 'approve_tools' || decision.action === 'modify_tools') &&
@@ -417,7 +428,7 @@ export async function applyPendingResume(
 	executor: ToolExecutor,
 	prior?: PriorToolResults,
 	assistantMessageId?: MessageId,
-): Promise<void> {
+): Promise<ToolExecutionBatch> {
 	const denials = new Map(plan.denials)
 	const reviewedById = new Map(plan.reviewedCalls?.map((call) => [call.id, call]))
 
@@ -439,7 +450,10 @@ export async function applyPendingResume(
 		...plan.response,
 		message: { ...plan.response.message, toolCalls: callsToPrepare },
 	}
-	const preparedBatch = await executor.prepareBatchForReview(responseToPrepare)
+	const preparedBatch = await executor.prepareBatchForReview(
+		responseToPrepare,
+		plan.modifiedCallIds,
+	)
 
 	for (const call of preparedBatch.reviewCalls) {
 		const reviewed = reviewedById.get(call.id)
@@ -508,10 +522,17 @@ export async function applyPendingResume(
 	// The parked assistant message is already in the log: it goes back into
 	// the context under its own record id, never as a second copy.
 	recorder.pushMessage(plan.assistant, assistantMessageId ? { messageId: assistantMessageId } : {})
-	const batch = await executor.executeBatch(plan.response, denials, prior, preparedBatch)
+	const batch = await executor.executeBatch(
+		plan.response,
+		denials,
+		prior,
+		preparedBatch,
+		plan.declines,
+	)
 	for (const msg of batch.messages) {
 		recorder.pushMessage(msg)
 	}
+	return batch
 }
 
 /**
@@ -567,8 +588,8 @@ export async function recoverCompletedCalls(
 	toolCalls: readonly ToolCall[],
 	log: Logger,
 	options: { answers?: PendingAnswers; signal?: AbortSignal } = {},
-): Promise<Map<string, { result: string; isError: boolean }>> {
-	const recovered = new Map<string, { result: string; isError: boolean }>()
+): Promise<Map<string, PriorToolResult>> {
+	const recovered = new Map<string, PriorToolResult>()
 	let snapshot: ToolExecutionSnapshot | undefined
 	try {
 		await recorder.flush()
@@ -592,7 +613,15 @@ export async function recoverCompletedCalls(
 		) {
 			if (!record) continue // Complete evidence proves this call has no recorded start.
 			if (record.status === 'completed') {
-				recovered.set(call.id, { result: record.result, isError: record.isError })
+				recovered.set(call.id, {
+					result: record.result,
+					isError: record.isError,
+					...(record.inputFailure ? { inputFailure: record.inputFailure } : {}),
+					...(record.skipped ? { skipped: true as const } : {}),
+					...(record.structuredResultJson !== undefined
+						? { structuredResultJson: record.structuredResultJson }
+						: {}),
+				})
 				continue
 			}
 		}
@@ -615,6 +644,30 @@ export async function recoverCompletedCalls(
 	return recovered
 }
 
+/** The calls a person refused in `decision`, for the record; `undefined` when none. */
+function derriveDeclines(
+	toolCalls: readonly ToolCall[],
+	decision: HITLResumeDecision,
+	reviewed: readonly ToolCallSummary[] = [],
+): ToolCallDeclines | undefined {
+	// A call the gate refused was never the person's to decline.
+	const gateDenied = new Set(
+		reviewed.filter((call) => call.authorization?.decision === 'deny').map((call) => call.id),
+	)
+	if (decision.action === 'reject_tools' && decision.declined) {
+		const declined = decision.declined
+		const calls = toolCalls.filter((tc) => !gateDenied.has(tc.id))
+		return calls.length > 0 ? new Map(calls.map((tc) => [tc.id, declined])) : undefined
+	}
+	if (decision.action === 'modify_tools') {
+		const denied = decision.modifications.filter(
+			(mod) => mod.action === 'deny' && !gateDenied.has(mod.toolCallId),
+		)
+		if (denied.length > 0) return new Map(denied.map((mod) => [mod.toolCallId, {}]))
+	}
+	return undefined
+}
+
 /**
  * Turn a decision into per-call refusals, or `null` when the decision does
  * not resolve the park at all.

package/src/runtime/query/resume-session.ts

@@ -79,7 +79,7 @@ export async function resumeSession(params: ResumeSessionParams): Promise<Resume
 	// A caller-chosen checkpoint scope is not proof that the source log belongs
 	// to it. Refuse foreign attribution before reading any checkpoint or park.
 	assertResumeRequestAttribution(params, scope)
-	if (!(await assertSessionLogAttribution(sessionLog, scope))) {
+	if (!(await assertSessionLogAttribution(sessionLog, scope, { execution: 'kernel' }))) {
 		return { resumed: false, reason: 'no-checkpoint' }
 	}
 	const checkpointStore =

package/src/runtime/query/review-policy.ts

@@ -23,7 +23,12 @@
 
 import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
 import type { ToolManager } from '../../toolsets/manager.js'
-import type { HITLResumeDecision, ResumeHandler, ToolCallSummary } from '../../types/hitl/index.js'
+import type {
+	HITLResumeDecision,
+	ResumeHandler,
+	ToolCallDeclined,
+	ToolCallSummary,
+} from '../../types/hitl/index.js'
 import type { ApprovalPolicy } from '../../types/hitl/policy.js'
 import type { SessionId, TurnId } from '../../types/ids/index.js'
 import { PLAN_MODE_REFUSAL } from '../../types/permission/index.js'
@@ -266,7 +271,17 @@ export type ToolReviewAnswer =
 	| { readonly kind: 'approve' }
 	/** Approve, and stop asking for the rest of the turn. */
 	| { readonly kind: 'approve-all' }
-	| { readonly kind: 'reject'; readonly feedback?: string }
+	| {
+			readonly kind: 'reject'
+			readonly feedback?: string
+			/**
+			 * Set by a host when a person said No, so the refusal is recorded as
+			 * theirs. `feedback` is what the model is told and a host may fill it
+			 * for its own reasons (a closed screen, an interrupted turn), so it
+			 * cannot carry this. `note` is the person's own words.
+			 */
+			readonly declined?: ToolCallDeclined
+	  }
 
 /** How a host asks a person. The one thing the kernel cannot supply. */
 export type ToolReviewPrompt = (request: ToolReviewRequest) => Promise<ToolReviewAnswer>
@@ -400,6 +415,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				return {
 					action: 'reject_tools',
 					feedback: answer.feedback ?? SCREEN_CONSENT_DECLINED_FEEDBACK,
+					...(answer.declined ? { declined: answer.declined } : {}),
 				}
 			}
 			consent.sessions.add(sessionKey)
@@ -471,6 +487,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				return {
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
+					...(answer.declined ? { declined: answer.declined } : {}),
 				}
 			}
 			// "Approve all" still latches for the calls that follow; it never
@@ -489,6 +506,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				return {
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
+					...(answer.declined ? { declined: answer.declined } : {}),
 				}
 			}
 			// Latches for the ordinary calls that follow, never for the next path.
@@ -508,6 +526,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				return {
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
+					...(answer.declined ? { declined: answer.declined } : {}),
 				}
 			}
 			if (answer.kind === 'approve-all') remembered.all = true
@@ -527,6 +546,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				return {
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
+					...(answer.declined ? { declined: answer.declined } : {}),
 				}
 			}
 			if (answer.kind === 'approve-all') remembered.all = true
@@ -573,6 +593,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				return {
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
+					...(answer.declined ? { declined: answer.declined } : {}),
 				}
 		}
 	}

package/src/runtime/query/saved-presentation.ts

@@ -0,0 +1,70 @@
+import { genericPrimary } from '../../registry/tool/presentation.js'
+import type { ToolCallView, ToolResultView } from '../../types/tool/presentation.js'
+
+/** One line is all a saved row needs; the output is not kept. */
+export const SAVED_LABEL_MAX = 200
+
+function firstLine(text: string | undefined): string | undefined {
+	const line = text
+		?.split(/\r?\n/)
+		.find((candidate) => candidate.trim())
+		?.trim()
+	if (!line) return undefined
+	// By code point so a surrogate pair is never split.
+	const points = Array.from(line)
+	return points.length > SAVED_LABEL_MAX
+		? `${points.slice(0, SAVED_LABEL_MAX - 1).join('')}…`
+		: line
+}
+
+/**
+ * What the journal keeps of a successful call that has no diff: the label the
+ * live row already showed, never the output. A host that replays history then
+ * names the action instead of calling it a saved one.
+ *
+ * `undefined` means there is nothing worth saving (no label, no command), so
+ * the host falls back to the tool's name.
+ */
+export function savedPresentation(
+	input: unknown,
+	callView: ToolCallView | undefined,
+	resultView: ToolResultView | undefined,
+): ToolResultView | undefined {
+	if (resultView?.kind === 'diff') return undefined
+	const callLabel = callView?.kind === 'generic' ? firstLine(callView.label) : undefined
+	const commandInput =
+		input &&
+		typeof input === 'object' &&
+		typeof (input as { command?: unknown }).command === 'string'
+			? (input as { command: string }).command
+			: undefined
+	// A tool with no view of its own is drawn as a terminal, so a command input is a command.
+	const command =
+		resultView?.kind === 'terminal' || callView?.kind === 'terminal'
+			? ((resultView?.kind === 'terminal' ? resultView.command : undefined) ??
+				(callView?.kind === 'terminal' ? callView.command : undefined) ??
+				commandInput ??
+				callLabel ??
+				'')
+			: !resultView && !callView && commandInput !== undefined
+				? commandInput
+				: undefined
+	if (command !== undefined) {
+		const line = firstLine(command)
+		return line ? { kind: 'terminal', command: line, output: '' } : undefined
+	}
+	const label =
+		callLabel ??
+		(resultView?.kind === 'generic' ? firstLine(resultView.label) : undefined) ??
+		(callView || resultView ? undefined : firstLine(genericPrimary(input)))
+	if (!label) return undefined
+	const own = callView?.kind === 'generic' ? callView : undefined
+	const hidden = resultView?.kind === 'generic' && resultView.visibility === 'hidden'
+	return {
+		kind: 'generic',
+		label,
+		...(own?.presentation === 'activity' ? { presentation: 'activity' as const } : {}),
+		...(own?.activity === 'exploration' ? { activity: 'exploration' as const } : {}),
+		...(hidden ? { visibility: 'hidden' as const } : {}),
+	}
+}

package/src/runtime/query/steering.ts

@@ -14,14 +14,11 @@ export function isOperatorUserMessage(message: Message): message is UserMessage
 /**
  * Guidance a host hands to a turn that is already running.
  *
- * The gap this closes is narrow and was documented rather than fixed:
- * `AgentManager` has had `queueMessage` / `drainMessages` for a while, and
- * nothing in the iteration loop ever read them — the type says so in as many
- * words. So a host watching a turn go the wrong way had two options, and both
- * are worse than they sound. Cancel and start over throws away every tool
- * result the turn had already paid for. Reject through the review gate only
- * works if a tool call happens to be pending approval, and it says "no" when
- * the host wanted to say "yes, but look at this first".
+ * This tool-result channel is distinct from `inboundMessages`. The manager
+ * injects its mailbox through that callback, and query-backed agents consume
+ * it at provider-valid message boundaries. Custom agents must consume their
+ * injected callback themselves. This channel instead lets a host attach
+ * guidance to a completed tool batch without adding another user message.
  *
  * **Why the text rides on a tool result rather than arriving as a user
  * message.** A `tool_use` block must be answered by a `tool_result` with the
@@ -34,7 +31,7 @@ export function isOperatorUserMessage(message: Message): message is UserMessage
  * attends to for tool outcomes. Steering is the same delivery with the
  * refusal removed.
  *
- * **What it deliberately is not.** It does not interrupt. The batch in flight
+ * It does not interrupt. The batch in flight
  * finishes, and the guidance lands where the model looks next. A host that
  * wants the current work stopped wants `AbortSignal`, which is a different
  * question with a different answer — and conflating the two is how "please

package/src/runtime/query/tool-executions.ts

@@ -1,20 +1,30 @@
 import type { SessionLog } from '../../store/session-log/index.js'
+import type { SpillRef } from '../../store/session-log/spill.js'
+import { readStructuredResultSpill } from '../../store/session-log/structured-result.js'
+import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../tools/builtins/structuredOutput.js'
 import type { TurnId } from '../../types/ids/index.js'
-import type { SessionRecord } from '../../types/session/records.js'
+import { type SessionRecord, SessionRecordSchema } from '../../types/session/records.js'
 import type {
+	CompletedToolRecord,
 	ToolExecutionRecord,
 	ToolExecutionSnapshot,
 } from '../../types/session/tool-execution.js'
+import { parseStructuredResultJson } from '../../utils/structured-result-json.js'
+
+/** Full JSON retained across one recovery snapshot, after superseded calls are removed. */
+const STRUCTURED_RECOVERY_MAX_BYTES = 64 * 1024 * 1024
 
 /**
  * Collects the latest execution boundary of selected tool calls from one
- * turn's records: metadata only, never retained output bodies beyond the
- * completion's own result.
+ * turn's records, including bounded receipts and optional runtime-owned JSON
+ * candidates. Structured spill bodies are hydrated separately, after the
+ * whole log has verified; ordinary output spills remain bounded receipts.
  */
 export class ToolExecutionCollector {
 	private started = false
 	private readonly wanted: Set<string>
 	private readonly records = new Map<string, ToolExecutionRecord>()
+	private readonly structuredSpills = new Map<string, SpillRef>()
 
 	constructor(
 		private readonly turnId: TurnId,
@@ -36,21 +46,101 @@ export class ToolExecutionCollector {
 		if (record.type === 'tool_executing') {
 			// A later start invalidates an earlier completion, including retries.
 			this.records.set(event.toolUseId, { ...identity, status: 'started' })
+			this.structuredSpills.delete(event.toolUseId)
 			return
 		}
 		if (typeof event.result !== 'string' || typeof event.isError !== 'boolean')
 			throw new Error('Tool recovery found an invalid completion.')
+		const inputFailure = event.inputFailure
+		if (
+			inputFailure !== undefined &&
+			(typeof inputFailure !== 'string' ||
+				!['invalid_json', 'schema_validation', 'input_truncated'].includes(inputFailure) ||
+				event.isError !== true)
+		)
+			throw new Error('Tool recovery found an invalid input failure classification.')
+		const skipped = event.skipped
+		if (
+			skipped !== undefined &&
+			(skipped !== true || event.isError !== false || inputFailure !== undefined)
+		)
+			throw new Error('Tool recovery found an invalid skipped completion classification.')
+		const structuredResultJson = event.structuredResultJson
+		const structuredResultSpill = event.structuredResultSpill
+		if (structuredResultJson !== undefined || structuredResultSpill !== undefined) {
+			if (
+				event.toolName !== STRUCTURED_OUTPUT_TOOL_NAME ||
+				event.isError !== false ||
+				skipped !== undefined ||
+				inputFailure !== undefined ||
+				event.via !== undefined
+			)
+				throw new Error(
+					'Tool recovery found an invalid durable structured completion classification.',
+				)
+			if (structuredResultSpill !== undefined) {
+				// Also refuse malformed references and contradictory inline evidence
+				// when the collector is driven outside the strict log reader.
+				SessionRecordSchema.parse(record)
+			} else {
+				parseStructuredResultJson(structuredResultJson)
+			}
+		}
+		this.structuredSpills.delete(event.toolUseId)
+		if (structuredResultSpill !== undefined)
+			this.structuredSpills.set(event.toolUseId, structuredResultSpill as SpillRef)
 		this.records.set(event.toolUseId, {
 			...identity,
 			status: 'completed',
 			result: event.result,
 			isError: event.isError,
+			...(inputFailure !== undefined
+				? { inputFailure: inputFailure as CompletedToolRecord['inputFailure'] }
+				: {}),
+			...(skipped ? { skipped: true as const } : {}),
+			...(structuredResultJson !== undefined
+				? { structuredResultJson: structuredResultJson as string }
+				: {}),
 		})
 	}
 
 	/** Complete only when the turn's beginning was seen and the whole log verified. */
 	finish(complete = true): ToolExecutionSnapshot {
-		return { complete: complete && this.started, records: this.records }
+		// A synchronous fold cannot establish spilled structured evidence.
+		// Its snapshot is incomplete until checked hydration finishes.
+		return {
+			complete: complete && this.started && this.structuredSpills.size === 0,
+			records: this.records,
+		}
+	}
+
+	/** Hydrate only the latest selected completion; overwritten retry bodies are irrelevant. */
+	async finishWithSpills(
+		log: SessionLog,
+		complete = true,
+		signal?: AbortSignal,
+	): Promise<ToolExecutionSnapshot> {
+		signal?.throwIfAborted()
+		if (!complete || !this.started) return this.finish(false)
+		let totalBytes = 0
+		for (const ref of this.structuredSpills.values()) {
+			totalBytes += ref.bytes
+			if (totalBytes > STRUCTURED_RECOVERY_MAX_BYTES) {
+				throw new Error(
+					`Structured recovery exceeds the ${STRUCTURED_RECOVERY_MAX_BYTES}-byte aggregate limit.`,
+				)
+			}
+		}
+		const records = new Map(this.records)
+		for (const [id, ref] of this.structuredSpills) {
+			const record = records.get(id)
+			if (!record || record.status !== 'completed')
+				throw new Error('Structured spill lacks a completed call.')
+			const { json: structuredResultJson } = await readStructuredResultSpill(log, ref, signal)
+			records.set(id, { ...record, structuredResultJson })
+		}
+		signal?.throwIfAborted()
+		return { complete: true, records }
 	}
 }
 
@@ -68,10 +158,19 @@ export async function readToolExecutions(
 	signal?.throwIfAborted()
 	const collector = new ToolExecutionCollector(turnId, ids)
 	const walk = log.read({ mode: 'strict' })
-	for (;;) {
-		signal?.throwIfAborted()
-		const step = await walk.next()
-		if (step.done) return collector.finish(step.value.intact && step.value.tornBytes === 0)
-		collector.accept(step.value.record)
+	try {
+		for (;;) {
+			signal?.throwIfAborted()
+			const step = await walk.next()
+			if (step.done)
+				return collector.finishWithSpills(
+					log,
+					step.value.intact && step.value.tornBytes === 0,
+					signal,
+				)
+			collector.accept(step.value.record)
+		}
+	} finally {
+		await walk.return({ intact: false, throughSeq: 0, head: null, tornBytes: 0 })
 	}
 }

package/src/runtime/query/tooling.ts

@@ -8,7 +8,7 @@ import type { InvocationState } from '../../types/invocation/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
 import type { AuditEventInput } from '../../types/session/audit.js'
 import type { SessionRecord } from '../../types/session/records.js'
-import type { RequestToolPause, SkillRegistryRef } from '../../types/tool/index.js'
+import type { RequestToolPause, SkillRegistryRef, ToolDefinition } from '../../types/tool/index.js'
 import type { RepairToolCall } from '../../types/tool/repair.js'
 import type { BackoffPolicy } from '../../utils/backoff.js'
 import type { Logger } from '../../utils/logger.js'
@@ -20,6 +20,8 @@ import type { EmitEvent } from './events.js'
 export interface ToolingBootstrapConfig {
 	fileReadTracker?: import('../../types/tool/index.js').FileReadTracker
 	tools: ToolManager
+	/** Exact runtime output-tool owner for opt-in JSON retention; see ToolExecutorConfig. */
+	durableStructuredOutputTool?: ToolDefinition
 	sessionId: SessionId
 	turnId: TurnId
 	workingDirectory: string
@@ -79,6 +81,9 @@ export class ToolingBootstrap {
 		return new ToolExecutor(
 			{
 				tools: config.tools,
+				...(config.durableStructuredOutputTool
+					? { durableStructuredOutputTool: config.durableStructuredOutputTool }
+					: {}),
 				...(config.fileReadTracker ? { fileReadTracker: config.fileReadTracker } : {}),
 				sessionId: config.sessionId,
 				turnId: config.turnId,