@namzu/sdk 56.1.0 → 57.0.0

package/src/runtime/query/iteration/step-context.ts

@@ -1,6 +1,5 @@
 import { createRuntimeContextMessage } from '../../../types/message/index.js'
 import type { Message } from '../../../types/message/index.js'
-import { isOperatorUserMessage } from '../steering.js'
 
 /**
  * Request-only context, as the model reads it: a runtime-context user
@@ -18,167 +17,40 @@ export function stepContextMessage(content: string) {
 	)
 }
 
-/**
- * Put `blocks` in front of the operator's new message when that message is
- * what the model is about to answer, so the request is the last thing it
- * reads and the longest data comes before it. Only the reminders and other
- * request-only context may follow that message: once the turn has an
- * assistant or tool message after it, the blocks stay at the end of the
- * history, where a caching driver ends its breakpoint before them, so the
- * tool loop of a long turn is not re-read at full price on every step.
- *
- * Reminders and notices that follow the operator's message stay where they
- * are: they are short, and the edge after the request is where they are read.
- */
-export function placeBeforeLatestOperatorMessage(history: Message[], blocks: readonly Message[]) {
-	if (blocks.length === 0) return
-	let at = history.length
-	for (let i = history.length - 1; i >= 0; i--) {
-		const message = history[i] as Message
-		if (isOperatorUserMessage(message)) {
-			at = i
-			break
-		}
-		// A reply or a tool result after the message: the model has moved on.
-		if (message.role === 'assistant' || message.role === 'tool') break
-	}
-	history.splice(at, 0, ...blocks)
-}
-
-interface PlacedBlock {
-	readonly text: string
-	/** The operator message this block precedes, or the history message it follows. */
-	at: { readonly before: Message } | { readonly after: Message | undefined }
-}
-
 function textOf(message: Message): string {
 	return typeof message.content === 'string' ? message.content : JSON.stringify(message.content)
 }
 
-/** The operator message the model is about to answer, when there is one. */
-function pendingOperatorMessage(history: readonly Message[]): Message | undefined {
-	for (let i = history.length - 1; i >= 0; i--) {
-		const message = history[i] as Message
-		if (isOperatorUserMessage(message)) return message
-		if (message.role === 'assistant' || message.role === 'tool') return undefined
-	}
-	return undefined
-}
-
-/** A block whose own text says that a later one replaces it, under the name of what it reports. */
-export interface ReplaceableBlock {
-	readonly key: string
-	readonly message: Message
-}
-
-/** How many superseded versions of a replaceable block still go with the latest. */
-export const EARLIER_VERSIONS_KEPT = 2
-
-interface VersionedBlock extends PlacedBlock {
-	readonly message: Message
-}
-
 /**
- * Where a turn's request-only data sits, so it stays put from call to call.
- *
- * What a block says is the step's own business: a block it offers again with
- * the same text is the same block, and it keeps the place it first had; a
- * block it no longer offers is withdrawn, so corrected data never lingers.
- * A block seen for the first time goes before the operator's message when that
- * message is what the model is answering, and otherwise after the history of
- * that moment. So the requests of a turn share their opening up to the first
- * block that changed, and a caching driver keeps reading the same prefix
- * instead of re-reading the turn from the operator's message on.
+ * Put a request's own data into it: after everything the history holds, in
+ * the order offered, each distinct text once.
  *
- * A block that says of itself that a later one replaces it (the file
- * evidence) is never taken back. When its text changes, the earlier text stays
- * where it went and the new text follows the history of that moment, which is
- * how the block itself tells the model to read it; when it stops holding, a
- * short block says so. Only the latest version and the last
- * `EARLIER_VERSIONS_KEPT` before it are carried, and an earlier version whose
- * place a compaction rewrote is dropped, so the stale text stays small. Until
- * a version is dropped no request of the turn rewrites the one before it.
+ * Request-only data is what the model needs for this request alone (a note
+ * that something is unavailable, the work still running). It is re-placed on
+ * every call and always last, so the history before it never changes shape
+ * from one call to the next and a caching driver, which ends its breakpoint
+ * before the first such block, covers the whole history on every call. What
+ * the model should keep reading in later requests is recorded as turn context
+ * instead (`PrepareStepResult.recordedContext`), and the loop records what it
+ * learns about files and finished work the same way.
  *
- * One carry per turn. A position whose message has left the history (a
- * compaction rewrote it) is given up and the block follows the history.
+ * `request` is the projected history. `recorded` are entries the loop has just
+ * recorded: they join the history at the end of this call, so they go ahead
+ * of the first request-only block already in `request` (`tail` of them, at the
+ * end), which is where the next request will find them.
  */
-export class TurnContextCarry {
-	private placed = new Map<string, PlacedBlock>()
-	private readonly versions = new Map<string, VersionedBlock[]>()
-
-	/**
-	 * Put `blocks` and the `replaceable` ones into `request`, the projected copy
-	 * of `history` (same length and order). `end` is the last message of the
-	 * turn's own history. `retractions` says, per replaceable key, what to
-	 * write when an earlier block of that key no longer holds.
-	 */
-	place(
-		request: Message[],
-		history: readonly Message[],
-		end: Message | undefined,
-		blocks: readonly Message[],
-		replaceable: readonly ReplaceableBlock[] = [],
-		retractions: Readonly<Record<string, Message>> = {},
-	): void {
-		const index = (message: Message | undefined) =>
-			message ? history.lastIndexOf(message) : history.length - 1
-		const operator = pendingOperatorMessage(history)
-		const positionOf = (slot: PlacedBlock) =>
-			'before' in slot.at ? index(slot.at.before) : index(slot.at.after) + 1
-		const anchorOf = (slot: PlacedBlock) => ('before' in slot.at ? slot.at.before : slot.at.after)
-		const next = new Map<string, PlacedBlock>()
-		const inserts: { at: number; message: Message }[] = []
-		for (const message of blocks) {
-			const text = textOf(message)
-			if (next.has(text)) continue
-			let slot: PlacedBlock | undefined = this.placed.get(text)
-			if (slot) {
-				const anchor = anchorOf(slot)
-				if (anchor && index(anchor) < 0) slot = { text, at: { after: end } }
-			} else {
-				slot = { text, at: operator ? { before: operator } : { after: end } }
-			}
-			next.set(text, slot)
-			inserts.push({ at: positionOf(slot), message })
-		}
-		this.placed = next
-
-		const offered = new Map(replaceable.map((block) => [block.key, block.message]))
-		for (const key of new Set([...this.versions.keys(), ...offered.keys()])) {
-			const held = this.versions.get(key) ?? []
-			const wanted = offered.get(key) ?? retractions[key]
-			const last = held.at(-1)
-			if (wanted !== undefined && (last === undefined || last.text !== textOf(wanted)))
-				held.push({
-					text: textOf(wanted),
-					message: wanted,
-					// The first version goes where the other blocks go; a later one
-					// follows the history, after the one it replaces.
-					at: last === undefined && operator ? { before: operator } : { after: end },
-				})
-			// An earlier version whose place a compaction rewrote is given up: the
-			// request is rewritten at that point anyway, and stacking stale copies
-			// at the end would only add bulk. The latest version is never given up.
-			const kept = held.filter((version, i) => {
-				if (i === held.length - 1) return true
-				const anchor = anchorOf(version)
-				return !anchor || index(anchor) >= 0
-			})
-			// Only the latest and a few earlier versions are carried, so a long turn
-			// does not grow by a full copy per change.
-			kept.splice(0, Math.max(0, kept.length - (EARLIER_VERSIONS_KEPT + 1)))
-			this.versions.set(key, kept)
-			for (const version of kept) {
-				const anchor = anchorOf(version)
-				if (anchor && index(anchor) < 0) version.at = { after: end }
-				inserts.push({ at: positionOf(version), message: version.message })
-			}
-		}
-
-		// Back to front, so an earlier position is not shifted by a later one;
-		// blocks at one position keep the order they were offered in.
-		const order = inserts.map((entry, position) => ({ ...entry, position }))
-		order.sort((a, b) => b.at - a.at || b.position - a.position)
-		for (const entry of order) request.splice(entry.at, 0, entry.message)
+export function placeRequestContext(
+	request: Message[],
+	recorded: readonly Message[],
+	tail: number,
+	blocks: readonly Message[],
+): void {
+	if (recorded.length > 0) request.splice(request.length - tail, 0, ...recorded)
+	const seen = new Set<string>()
+	for (const message of blocks) {
+		const text = textOf(message)
+		if (seen.has(text)) continue
+		seen.add(text)
+		request.push(message)
 	}
 }

package/src/runtime/query/iteration/step-shaping.ts

@@ -1,30 +1,30 @@
 import { resolveContextWindow } from '../../../compaction/context-window.js'
-import { estimateMessageTokens } from '../../../compaction/token-estimate.js'
+import { estimateMessageTokens, estimateTextTokens } from '../../../compaction/token-estimate.js'
 import { NAMZU } from '../../../constants/telemetry/index.js'
 import { renderSkillsSection } from '../../../persona/assembler.js'
+import { recordedOwnedTaskIds } from '../../../scheduler/completion-inbox.js'
 import { PreparationContextError } from '../../../turn/preparation-context-error.js'
 import {
 	type Message,
 	type UserMessage,
 	createSystemMessage,
+	turnContextEntries,
 } from '../../../types/message/index.js'
 import type { ToolChoice } from '../../../types/provider/chat.js'
 import type {
 	PrepareStepContext,
 	PrepareStepResult,
+	RecordedContextItem,
 	StepResult,
 	StepVeto,
 } from '../../../types/session/index.js'
 import type { Skill } from '../../../types/skills/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
 import { createCallbackInference } from '../callback-inference.js'
+import { recordFileEvidence } from '../file-evidence-context.js'
 import { measureContext } from './phases/compaction.js'
 import type { IterationContext } from './phases/index.js'
-import {
-	type ReplaceableBlock,
-	placeBeforeLatestOperatorMessage,
-	stepContextMessage,
-} from './step-context.js'
+import { stepContextMessage } from './step-context.js'
 
 /**
  * How the next request is shaped: admission, preparation, and the context
@@ -48,57 +48,68 @@ export interface StepShaping {
 
 export { stepContextMessage }
 
-/** Derived after request projection; never accumulates in canonical history or replaces operator intent. */
-export function appendWorkContext(
-	shaping: StepShaping,
-	messages: Message[],
-	stepNumber: number,
-	prepared: PrepareStepResult,
-): void {
-	// Per-turn data goes in front of the operator's new message while that is
-	// what the model is answering, like the other blocks of request-only data.
-	placeBeforeLatestOperatorMessage(
-		messages,
-		workContextBlocks(shaping, messages, stepNumber, prepared).map((block) => block.message),
-	)
-}
-
-/** What the two work-context blocks report; each tells the model a later one replaces it. */
+/** The names the two kinds of recorded work context are filed under. */
 export const OWNED_WORK_KEY = 'owned-work'
 export const FILE_EVIDENCE_KEY = 'file-evidence'
 
+/** What the work context says for one request. */
+export interface WorkContext {
+	/** Facts that do not change once true, to be kept in the conversation. */
+	readonly recorded: RecordedContextItem[]
+	/** Facts about now, shown with this request only. */
+	readonly requestOnly: Message[]
+}
+
 /**
- * The work-context blocks for a request whose projected messages are
- * `messages`, each under the name of what it reports.
+ * The work context for a request whose projected messages are `messages`.
+ *
+ * Two kinds of fact, each where it belongs. What holds until something
+ * changes it, or never changes, is recorded: the file entries that are new or
+ * changed since the last record (with the paths whose entry no longer holds),
+ * and each owned task once it has finished. What is true only now, the tasks
+ * still running, goes with this request alone. Each text is admitted whole or
+ * not at all, within the room the request has left.
  */
-export function workContextBlocks(
+export function workContext(
 	shaping: StepShaping,
 	messages: readonly Message[],
 	stepNumber: number,
 	prepared: PrepareStepResult,
-): ReplaceableBlock[] {
+): WorkContext {
 	const { ctx } = shaping
+	const held = (key: string) => turnContextEntries(ctx.recorder.messages, key)
+	const inbox = ctx.completionInbox
 
-	const contributions = (
-		[
-			[OWNED_WORK_KEY, ctx.completionInbox?.describeOwnedWork()],
-			[FILE_EVIDENCE_KEY, ctx.toolExecutor.describeFileEvidence(messages)],
-		] as [string, string | undefined][]
-	).filter((entry): entry is [string, string] => Boolean(entry[1]))
-	if (contributions.length === 0) return []
-	const placed: ReplaceableBlock[] = []
+	const contributions: { content: string | undefined; key?: string }[] = [
+		{ content: inbox?.describeRunningWork() },
+		{
+			content: inbox?.describeSettledWork(recordedOwnedTaskIds(held(OWNED_WORK_KEY))),
+			key: OWNED_WORK_KEY,
+		},
+		{
+			content: recordFileEvidence(
+				ctx.toolExecutor.fileEvidenceEntries(messages),
+				held(FILE_EVIDENCE_KEY),
+			),
+			key: FILE_EVIDENCE_KEY,
+		},
+	]
+	const present = contributions.filter((entry) => Boolean(entry.content))
+	const work: WorkContext = { recorded: [], requestOnly: [] }
+	if (present.length === 0) return work
 	let room = stepContext(shaping, stepNumber, prepared).contextBudget?.remainingTokens ?? 0
 	// Leave room for the actual task; admit whole contributions, never dangling partial references.
-	if (room < 1_500) return []
-	for (const [key, content] of contributions) {
+	if (room < 1_500) return work
+	for (const { content, key } of present) {
 		if (!content || content.length > 8_000) continue
 		const message = stepContextMessage(content)
 		const tokens = estimateMessageTokens(message)
 		if (tokens > Math.min(2_000, room - 1_000)) continue
-		placed.push({ key, message })
+		if (key) work.recorded.push({ key, text: content })
+		else work.requestOnly.push(message)
 		room -= tokens
 	}
-	return placed
+	return work
 }
 
 export function stepContext(
@@ -122,7 +133,8 @@ export function stepContext(
 	const preamble = [prepared.system, skills].filter(Boolean).join('\n\n')
 	const preparedTokens =
 		(preamble ? estimateMessageTokens(createSystemMessage(preamble)) : 0) +
-		(prepared.context ? estimateMessageTokens(stepContextMessage(prepared.context)) : 0)
+		(prepared.context ? estimateMessageTokens(stepContextMessage(prepared.context)) : 0) +
+		(prepared.recordedContext ?? []).reduce((sum, item) => sum + estimateTextTokens(item.text), 0)
 	const responseReserve = Math.min(
 		prepared.maxResponseTokens ?? ctx.turnConfig.maxResponseTokens ?? Math.floor(window.tokens / 4),
 		Math.floor(window.tokens / 4),
@@ -180,6 +192,7 @@ export async function prepareStep(
 	model?: string
 	system?: string
 	context?: string
+	recordedContext?: readonly RecordedContextItem[]
 	skills?: readonly Skill[]
 	temperature?: number
 	maxResponseTokens?: number
@@ -206,7 +219,16 @@ export async function prepareStep(
 				...stepContext(shaping, stepNumber, result),
 				generateText: inference.generateText,
 			})
-			if (decided) result = { ...result, ...decided }
+			if (decided) {
+				// Recorded context adds up across stages: each stage files its own
+				// keys, and one stage must not erase what an earlier one recorded.
+				const recorded = [...(result.recordedContext ?? []), ...(decided.recordedContext ?? [])]
+				result = {
+					...result,
+					...decided,
+					...(recorded.length > 0 ? { recordedContext: recorded } : {}),
+				}
+			}
 			await selectContextModel(shaping, result.model ?? ctx.turnConfig.model)
 		} catch (err) {
 			// Skipped, and the rest still run: one broken concern must
@@ -242,6 +264,7 @@ export async function prepareStep(
 		model?: string
 		system?: string
 		context?: string
+		recordedContext?: readonly RecordedContextItem[]
 		skills?: readonly Skill[]
 		temperature?: number
 		maxResponseTokens?: number
@@ -279,6 +302,7 @@ export async function prepareStep(
 	if (result.model !== undefined) prepared.model = result.model
 	if (result.system !== undefined) prepared.system = result.system
 	if (result.context !== undefined) prepared.context = result.context
+	if (result.recordedContext !== undefined) prepared.recordedContext = result.recordedContext
 	if (result.skills !== undefined) prepared.skills = result.skills
 	if (result.temperature !== undefined) prepared.temperature = result.temperature
 	if (result.maxResponseTokens !== undefined) {

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({