@namzu/sdk 56.2.0 → 57.1.0

package/src/runtime/query/executor.ts

@@ -6,6 +6,7 @@ import { unknownProgramInLine } from '../../authorization/program.js'
 import { type SkillGrantSet, compileSkillGrant } from '../../authorization/skill-grant.js'
 import { extractFromToolCall, extractFromToolResult } from '../../compaction/extractor.js'
 import type { WorkingStateManager } from '../../compaction/manager.js'
+import { recordRestorable } from '../../compaction/restore.js'
 import { GENAI, NAMZU } from '../../constants/telemetry/index.js'
 import type { PluginLifecycleManager } from '../../plugin/lifecycle.js'
 import { buildProbeContext } from '../../probe/context.js'
@@ -13,6 +14,7 @@ import { ProbeVetoError } from '../../probe/errors.js'
 import { probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ProbeEnforcement } from '../../probe/registry.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
+import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
 import { sandboxShellSpawn, withoutBashStartup } from '../../tools/command-shell.js'
 import { isAlwaysDestructive } from '../../tools/defineTool.js'
 import { createFileReadTracker } from '../../tools/file-read-tracker.js'
@@ -700,6 +702,8 @@ export class ToolExecutor {
 	private emitEvent: EmitEvent
 	private log: Logger
 	private workingStateManager?: WorkingStateManager
+	private historyView?: () => readonly Message[]
+	private systemPromptView?: () => string | undefined
 	private probes: ProbeEnforcement
 	private parentSpan?: Span
 	private readonly toolCallBudget?: ToolCallBudget
@@ -749,6 +753,35 @@ export class ToolExecutor {
 		this.workingStateManager = manager
 	}
 
+	/**
+	 * Read the conversation the model is shown, as it is now. Lets a tool ask
+	 * whether an earlier receipt is still there (see `ToolContext.receiptVisible`)
+	 * without being handed the history.
+	 */
+	setHistoryView(view: () => readonly Message[]): void {
+		this.historyView = view
+	}
+
+	/** The system prompt assembled for the current iteration, for `ToolContext.conversation`. */
+	setSystemPromptView(view: () => string | undefined): void {
+		this.systemPromptView = view
+	}
+
+	private receiptVisible = (callId: string, renderedFingerprint: string): boolean => {
+		const history = this.historyView?.()
+		if (!history) return false
+		for (let index = history.length - 1; index >= 0; index -= 1) {
+			const message = history[index]
+			if (message?.role !== 'tool' || message.toolCallId !== callId) continue
+			return (
+				typeof message.content === 'string' &&
+				message.isError !== true &&
+				fingerprintContent(message.content) === renderedFingerprint
+			)
+		}
+		return false
+	}
+
 	setSandbox(sandbox: Sandbox): void {
 		this.config = { ...this.config, sandbox }
 		this.sandboxGate = undefined
@@ -2185,6 +2218,15 @@ export class ToolExecutor {
 				this.dispatchNested(name, input, context, recordObservation, undefined, options),
 			sandbox: this.config.sandbox,
 			fileReadTracker: this.fileReadTracker,
+			receiptVisible: this.receiptVisible,
+			...(this.historyView
+				? {
+						conversation: {
+							messages: () => this.historyView?.() ?? [],
+							systemPrompt: () => this.systemPromptView?.(),
+						},
+					}
+				: {}),
 			...(this.config.codeAnalysis ? { codeAnalysis: this.config.codeAnalysis } : {}),
 			// Bound to this turn, once. Binding here rather than passing the
 			// owner from the tool is what makes the scoping structural: there
@@ -2584,6 +2626,15 @@ export class ToolExecutor {
 
 		if (this.workingStateManager) {
 			extractFromToolResult(this.workingStateManager, toolName, output, effectiveIsError)
+			// What the model was shown, kept whole so a compaction can put it back.
+			recordRestorable(this.workingStateManager, {
+				toolName,
+				input,
+				output: typeof modelContent === 'string' ? modelContent : output,
+				success: !effectiveIsError,
+				unchanged: result.facts?.kind === 'read' && result.facts.unchanged === true,
+				workingDirectory: this.config.workingDirectory,
+			})
 			for (const pin of this.config.abortSignal.aborted ? [] : (result.workingState ?? [])) {
 				this.workingStateManager.pin(pin.key, pin.text, toolName)
 			}

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

@@ -149,7 +149,7 @@ export function recordFileEvidence(
 	const lead =
 		recorded.length === 0
 			? `${FILE_EVIDENCE_HEADING}: ${FILE_EVIDENCE_GUIDANCE}`
-			: `${FILE_EVIDENCE_HEADING}, changed since the last entry. An entry for a path replaces the earlier entries for that path.`
+			: `${FILE_EVIDENCE_HEADING}, changed since the last entry; \`bodyInCall\` and \`observedFingerprint\` read as before. An entry for a path replaces the earlier entries for that path.`
 	return [
 		lead,
 		...(gone.length > 0 ? [`${NO_LONGER_HOLDS}${JSON.stringify(gone)}`] : []),

package/src/runtime/query/index.ts

@@ -10,6 +10,7 @@ import { SkillGrantSet } from '../../authorization/skill-grant.js'
 import { repairToolMessageHistory, toolHistoryRepairChanged } from '../../compaction/dangling.js'
 import { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
+import type { CompactionSummaryRouter } from '../../compaction/model-summary.js'
 import type { ContextReducer } from '../../compaction/reducer.js'
 import { serializeState as serializeWorkingState } from '../../compaction/serializer.js'
 import { restoreWorkingState, snapshotWorkingState } from '../../compaction/wire.js'
@@ -814,6 +815,19 @@ export interface QueryParams {
 	 */
 	projectInstructionContext?: ProjectInstructionContext
 
+	/**
+	 * Text the host wants carried across a compaction, such as where its plan
+	 * file is. Asked once per pass, after the summary is written; the answer is
+	 * appended to the restored context. Returning nothing adds nothing.
+	 */
+	postCompactionContext?: () => string | undefined | Promise<string | undefined>
+
+	/**
+	 * Names the model that writes a compaction summary. Asked once per pass;
+	 * resolving nothing, or a call that fails, keeps the extracted summary.
+	 */
+	compactionSummaryRoute?: CompactionSummaryRouter
+
 	/**
 	 * Where this conversation's durable state lives.
 	 *
@@ -1656,6 +1670,8 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		const compactionConfig = params.compactionConfig
 			? CompactionConfigSchema.parse(params.compactionConfig)
 			: undefined
+		// The live history, so a tool can ask whether an earlier receipt is still in it.
+		toolExecutor.setHistoryView(() => ctx.recorder.messages)
 		if (compactionConfig && compactionConfig.strategy !== 'disabled') {
 			workingStateManager = new WorkingStateManager(compactionConfig)
 			toolExecutor.setWorkingStateManager(workingStateManager)
@@ -1829,6 +1845,12 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			...(params.projectInstructionContext
 				? { projectInstructionContext: params.projectInstructionContext }
 				: {}),
+			...(params.postCompactionContext
+				? { postCompactionContext: params.postCompactionContext }
+				: {}),
+			...(params.compactionSummaryRoute
+				? { compactionSummaryRoute: params.compactionSummaryRoute }
+				: {}),
 			...(providerContextWindow !== undefined ? { providerContextWindow } : {}),
 			resolveModelContextWindow: async (model) => {
 				if (!modelContextWindows.has(model)) {
@@ -2339,6 +2361,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 						? `${segments.static}\n\n---\n\n${segments.dynamic}`
 						: segments.static
 
+				toolExecutor.setSystemPromptView(() => assembledPrompt)
 				ctx.recorder.markRunning()
 				// A resumed turn already began; `turn_resuming` above continued it.
 				if (!params.resumeFromCheckpoint) {

package/src/runtime/query/iteration/phases/compaction.ts

@@ -3,6 +3,7 @@ import {
 	resolveTriggerThreshold,
 } from '../../../../compaction/context-window.js'
 import { findDanglingMessages } from '../../../../compaction/dangling.js'
+import { replaceableSummaries, summarizeWithModel } from '../../../../compaction/model-summary.js'
 import {
 	type CompactionPlan,
 	DEFAULT_SOFT_TARGET,
@@ -11,6 +12,7 @@ import {
 } from '../../../../compaction/plan.js'
 import type { ContextReducer, ContextReduction } from '../../../../compaction/reducer.js'
 import { createSlidingWindowReducer } from '../../../../compaction/reducer.js'
+import { renderRestoredContext } from '../../../../compaction/restore.js'
 import { findRetainedIndices } from '../../../../compaction/retention.js'
 import { serializeState } from '../../../../compaction/serializer.js'
 import {
@@ -959,7 +961,51 @@ async function runCompactionCheckInner(
 
 	let compactedContent: string
 
-	if (config.llmVerification && manager.slotCount() < config.richStateThreshold) {
+	// A model the host set aside writes the summary when it can. Its own cost
+	// goes on the turn's ledger at the price of the model that answered. When
+	// there is no such model, or its call does not give a summary, the
+	// extracted state below is used, with its verifier step where that applies.
+	let modelRoute: { providerId: string; model: string } | undefined
+	const modelWritten = !ctx.compactionSummaryRoute
+		? undefined
+		: await summarizeWithModel({
+				manager,
+				olderMessages,
+				previousSummaries: replaceableSummaries(systemMessages),
+				config,
+				resolveRoute: async (signal) => {
+					const route = await ctx.compactionSummaryRoute?.(signal)
+					if (route) {
+						modelRoute = {
+							providerId: route.providerId ?? ctx.recorder.servingProviderId,
+							model: route.model,
+						}
+					}
+					return route
+				},
+				onUsage: (usage) => {
+					if (modelRoute) ctx.recorder.accumulateUsage(usage, modelRoute)
+				},
+				signal: ctx.abortController.signal,
+				onFallback: (reason, error) => {
+					if (reason === 'no_route') return
+					if (error !== undefined) noteCompactionError(ctx, error)
+					ctx.log.warn(
+						'The model-written compaction summary was not used — using the extracted state',
+						{
+							[NAMZU.TURN_ID]: ctx.recorder.turnId,
+							'namzu.runtime.reason': reason,
+							...(error !== undefined
+								? { 'exception.message': error instanceof Error ? error.message : String(error) }
+								: {}),
+						},
+					)
+				},
+			})
+
+	if (modelWritten !== undefined) {
+		compactedContent = modelWritten
+	} else if (config.llmVerification && manager.slotCount() < config.richStateThreshold) {
 		// Named once and used twice on purpose. The model the summariser is
 		// asked for is also the model its tokens are priced at, and computing
 		// the two separately is how they drift — a router that sends compaction
@@ -1003,6 +1049,24 @@ async function runCompactionCheckInner(
 		compactedContent = serializeState(manager.getState())
 	}
 
+	// Skills the model loaded and files it read go back verbatim after the
+	// summary, with whatever the host wants carried across (its plan file).
+	let hostNote: string | undefined
+	try {
+		hostNote = await ctx.postCompactionContext?.()
+	} catch (error) {
+		// A host note is an addition; the pass does not depend on it.
+		ctx.log.warn('The host note for a compaction could not be read — leaving it out', {
+			[NAMZU.TURN_ID]: ctx.recorder.turnId,
+			'exception.message': error instanceof Error ? error.message : String(error),
+		})
+	}
+	const restored = renderRestoredContext(manager.getState(), {
+		contextWindowTokens: budget,
+		...(hostNote ? { hostNote } : {}),
+	})
+	if (restored) compactedContent = `${compactedContent}\n\n${restored}`
+
 	// The pointer is only worth a line when both tools it names are mounted.
 	const mounted = new Set(ctx.tools?.listNames?.() ?? [])
 	const compactionMessage = buildCompactionMessage(

package/src/runtime/query/iteration/phases/context.ts

@@ -2,6 +2,7 @@ import type { AdvisoryContext } from '../../../../advisory/context.js'
 import type { SkillGrantSet } from '../../../../authorization/skill-grant.js'
 import type { AgentBus } from '../../../../bus/index.js'
 import type { WorkingStateManager } from '../../../../compaction/manager.js'
+import type { CompactionSummaryRouter } from '../../../../compaction/model-summary.js'
 import type { ContextReducer } from '../../../../compaction/reducer.js'
 import type { CompactionConfig } from '../../../../config/runtime.js'
 import { NAMZU } from '../../../../constants/telemetry/index.js'
@@ -256,6 +257,12 @@ export interface IterationContext {
 	/** Live project policy; separate from human inbound continuation. */
 	readonly projectInstructionContext?: ProjectInstructionContext
 
+	/** Host text appended to the restored context after a compaction. */
+	readonly postCompactionContext?: () => string | undefined | Promise<string | undefined>
+
+	/** Where a model-written compaction summary is asked for; see {@link CompactionSummaryRouter}. */
+	readonly compactionSummaryRoute?: CompactionSummaryRouter
+
 	readonly workingStateManager?: WorkingStateManager
 
 	/**

package/src/runtime/query/iteration/stream-turn.ts

@@ -30,7 +30,7 @@ import type {
 	ReasoningBlock,
 	ToolInputError,
 } from '../../../types/message/index.js'
-import { ProviderError } from '../../../types/provider/errors.js'
+import { ProviderError, classifyProviderError } from '../../../types/provider/errors.js'
 import type {
 	ChatCompletionResponse,
 	LLMProvider,
@@ -298,7 +298,7 @@ export async function* streamProviderTurn(
 	let streamedLength = 0
 	const toolBuckets = new Map<number, ToolCallBucket>()
 	// Places a fragment that came without an index; see `ToolCallIndexer`.
-	const toolIndexer = new ToolCallIndexer()
+	let toolIndexer = new ToolCallIndexer()
 	// The call the model's latest output went to, or `undefined` once text,
 	// reasoning or a hosted tool followed it. An output limit, a content
 	// filter or a dropped stream stops the response wherever it is, so this
@@ -397,6 +397,36 @@ export async function* streamProviderTurn(
 			})
 		: undefined
 
+	/**
+	 * Drop everything the failed attempt wrote, so the request starts over under
+	 * the same message: after a restarting retry, or a swap that says the same.
+	 * The failed attempt's text, reasoning and tool calls are void. A call is
+	 * restarted only while still being written and nothing runs before the
+	 * response settles, so a half-written call never reaches the model.
+	 */
+	const discardAttempt = () => {
+		toolBuckets.clear()
+		toolIndexer = new ToolCallIndexer()
+		framingViolated = false
+		text = new StreamTextAccumulator()
+		reasoningBuckets.clear()
+		citations.length = 0
+		replayState = undefined
+		id = ''
+		finishReason = 'stop'
+		reportedFinishReason = undefined
+		finishDetail = undefined
+		streamedLength = 0
+		lastOutputCall = undefined
+		usage = {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+	}
+
 	try {
 		for (;;) {
 			const next = it.next()
@@ -426,28 +456,7 @@ export async function* streamProviderTurn(
 					...(chunk.retry.restart ? { restart: true } : {}),
 				})
 				yield* drainPending()
-				if (chunk.retry.restart) {
-					// The failed attempt's text and reasoning are void: the request
-					// starts over under the same message. The decorator never
-					// restarts once a tool call began, so no bucket is left behind.
-					text = new StreamTextAccumulator()
-					reasoningBuckets.clear()
-					citations.length = 0
-					replayState = undefined
-					id = ''
-					finishReason = 'stop'
-					reportedFinishReason = undefined
-					finishDetail = undefined
-					streamedLength = 0
-					lastOutputCall = undefined
-					usage = {
-						promptTokens: 0,
-						completionTokens: 0,
-						totalTokens: 0,
-						cachedTokens: 0,
-						cacheWriteTokens: 0,
-					}
-				}
+				if (chunk.retry.restart) discardAttempt()
 				continue
 			}
 
@@ -472,8 +481,10 @@ export async function* streamProviderTurn(
 					code: chunk.fallback.code,
 					...(chunk.fallback.status !== undefined ? { status: chunk.fallback.status } : {}),
 					reason: chunk.fallback.reason,
+					...(chunk.fallback.restart ? { restart: true } : {}),
 				})
 				yield* drainPending()
+				if (chunk.fallback.restart) discardAttempt()
 				continue
 			}
 
@@ -947,10 +958,21 @@ export async function* streamProviderTurn(
 
 	// Not after a framing violation: the calls it would recover are the ones
 	// the stream was just refused for garbling.
+	//
+	// Nor when the stream was cut by a connection that may come back and no
+	// call came through whole: the retries are spent, the half-written call is
+	// not the model's mistake, and telling the model about it would spend a
+	// turn on a fault it cannot fix. The failure goes up and the turn pauses.
+	const cutByConnection =
+		streamError !== undefined &&
+		streamCause !== undefined &&
+		classifyProviderError(streamCause).retryable
 	const recoveredToolInputFromStreamError =
 		streamError !== undefined &&
 		!framingViolated &&
-		toolCalls.some((tc) => tc.id && tc.function.name)
+		toolCalls.some(
+			(tc) => tc.id && tc.function.name && (!cutByConnection || !tc.metadata?.inputError),
+		)
 	const effectiveFinishReason: ChatCompletionResponse['finishReason'] =
 		recoveredToolInputFromStreamError ? 'tool_calls' : finishReason
 

package/src/runtime/query/prepare-turn.ts

@@ -43,6 +43,7 @@ import { generateCheckpointId, generateTurnId } from '../../utils/id.js'
 import { errorAttributes } from '../../utils/log/exception.js'
 import type { Logger } from '../../utils/logger.js'
 import { AUTO_APPROVE_POLICY_NAME, createSessionApprovalPolicy } from './approval-policy.js'
+import { readCallsThatNeverStarted } from './calls-that-never-started.js'
 import { type TurnContext, TurnContextFactory } from './context.js'
 import { EventTranslator } from './events.js'
 import type { QueryParams } from './index.js'
@@ -681,9 +682,17 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 						pinCompaction: true,
 					})),
 		])
-		const initialRepair = params.resumeFromCheckpoint
+		let initialRepair = params.resumeFromCheckpoint
 			? { messages: projectedInitialMessages, report: undefined }
 			: repairToolMessageHistory(projectedInitialMessages)
+		if (initialRepair.report && initialRepair.report.syntheticToolResultsInserted > 0) {
+			// A call that was waiting for approval when the session ended never ran;
+			// the model is told so rather than that its outcome is unknown.
+			const neverRan = await readCallsThatNeverStarted(storage.log)
+			if (neverRan.size > 0) {
+				initialRepair = repairToolMessageHistory(projectedInitialMessages, { neverRan })
+			}
+		}
 		const initialMessages = initialRepair.messages
 		if (initialRepair.report && toolHistoryRepairChanged(initialRepair.report)) {
 			pendingHistoryRepairs.push({

package/src/scheduler/completion-inbox.ts

@@ -46,7 +46,7 @@ const OWNED_WORK_DISPLAY_LIMIT = 16
 
 /** What the model is told about owned work, wherever it is shown. */
 const OWNED_WORK_GUIDANCE =
-	'Each task gives its id (taskId), its state, how its turn ended (turnStatus), why it stopped (stopReason), and whether its result has reached this conversation (resultDelivery: delivered-to-history, or not-delivered). Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.'
+	'Each task gives its id (taskId), its state, how its turn ended (turnStatus), why it stopped (stopReason), and whether its result has reached this conversation (resultDelivery: delivered-to-history, or not-delivered). Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Results reach you and not the user, so before you end a reply check that the result of every finished task has been reported to the user, once. Do not repeat a synthesis already given.'
 
 /**
  * The ids of the tasks that earlier recorded entries name, read from the
@@ -809,8 +809,8 @@ export function formatCompletionNotification(handles: readonly TaskHandle[]): st
 
 	const preamble =
 		handles.length === 1
-			? 'A task you launched has finished. This is its result — you were not waiting on it, so it arrives here rather than as a tool result.'
-			: `${handles.length} tasks you launched have finished. These are their results — you were not waiting on them, so they arrive here rather than as tool results.`
+			? 'A task you launched has finished. This is its result — you were not waiting on it, so it arrives here rather than as a tool result. The user has not seen it; tell them what it found in your next message.'
+			: `${handles.length} tasks you launched have finished. These are their results — you were not waiting on them, so they arrive here rather than as tool results. The user has not seen them; tell them what each found in your next message.`
 
 	return `${preamble}\n\n${blocks.join('\n\n')}`
 }

package/src/scheduler/local.ts

@@ -133,7 +133,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 				...(options.phaseDetail ? { phaseDetail: options.phaseDetail } : {}),
 				...(options.phaseOrder !== undefined ? { phaseOrder: options.phaseOrder } : {}),
 				input: {
-					messages: [createUserMessage(options.prompt)],
+					messages: [...(options.inheritedMessages ?? []), createUserMessage(options.prompt)],
 					workingDirectory: options.workingDirectory,
 					taskStore: this.parentInput?.taskStore,
 					runtimeToolOverrides: this.parentInput?.runtimeToolOverrides,

package/src/tools/admit-facts.ts

@@ -118,6 +118,7 @@ export function admitToolFacts(value: unknown): ToolFacts | undefined {
 						? { bytes: count(value.binary.bytes) }
 						: undefined,
 				background: flag(value.background),
+				continued: flag(value.continued),
 			})
 		case 'read': {
 			const path = text(value.path)