@namzu/sdk 56.1.0 → 56.2.0

package/src/runtime/query/iteration/index.ts

@@ -28,7 +28,6 @@ import {
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js'
 import type { ToolManager } from '../../../toolsets/manager.js'
-import { splitAtEvidenceBlocks } from '../../../turn/evidence-recall.js'
 import type { CostInfo, TokenUsage } from '../../../types/common/index.js'
 import { NamzuError } from '../../../types/errors/index.js'
 import type { MessageId, SessionId, TurnId } from '../../../types/ids/index.js'
@@ -58,7 +57,6 @@ import { createCallbackInference } from '../callback-inference.js'
 import { SandboxAcquisitionStopped } from '../deferred-sandbox.js'
 import { deliverDurableInbound } from '../durable-inbound.js'
 import type { ToolCallOutcome } from '../executor.js'
-import { FILE_EVIDENCE_NONE } from '../file-evidence-context.js'
 import { projectObservationContext } from '../observation-context.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
 import {
@@ -103,17 +101,16 @@ import {
 	type TextOnlyModelRefusal,
 	streamWithProviderRejectedImageRecovery,
 } from './provider-rejected-image.js'
+import { appendRecordedContext } from './recorded-context.js'
 import { type MediaRemoval, RequestRepair } from './request-repair.js'
-import { TurnContextCarry } from './step-context.js'
+import { placeRequestContext } from './step-context.js'
 import {
-	FILE_EVIDENCE_KEY,
 	type StepShaping,
-	appendWorkContext,
 	beforeStep,
 	prepareStep,
 	selectContextModel,
 	stepContextMessage,
-	workContextBlocks,
+	workContext,
 } from './step-shaping.js'
 import { streamProviderTurn } from './stream-turn.js'
 
@@ -194,8 +191,7 @@ export class IterationOrchestrator {
 	 * one process must not suppress each other's first envelope.
 	 */
 	private lastEnvelopeKey: string | undefined
-	/** Where this turn's request-only data first went, so it stays there. */
-	private readonly turnContext = new TurnContextCarry()
+	/** The previous request's context, so a pre-call hook is told what changed. */
 	private previousRequestContext: RequestContextSnapshot | undefined
 
 	private projectObservations(messages: Message[]): Message[] {
@@ -838,6 +834,11 @@ export class IterationOrchestrator {
 								'limit-finalization',
 							)
 						: undefined
+					// What the step asked to have kept in the conversation joins the
+					// history now, after its last message, so this request and every
+					// later one begin with it. Nothing is inserted ahead of a message
+					// that is already recorded.
+					appendRecordedContext(recorder, step.recordedContext, this.ctx.log)
 					const baseMessages = recorder.messages
 
 					// Step guidance is appended to the REQUEST, never pushed onto
@@ -911,24 +912,30 @@ export class IterationOrchestrator {
 							DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 						{ imagesReadable: this.modelReadsImages(stepModel) },
 					)
-					// The blocks of data that belong to this turn (recalled memory and
-					// evidence, the context contributions, the work context) sit just
-					// before the operator's latest message the first time the model
-					// answers it, so the request is the last thing it reads. They stay
-					// there on every later call of the turn, and a block that first
-					// appears on a later call follows the history of that moment, so each
-					// request begins with the whole of the one before it. The short
-					// reminders and notices stay after the history.
+					// Request-only data (the context contributions, notes about the
+					// search, the work context) goes last on every call, after the
+					// whole history, so the history a caching driver reads never
+					// changes shape from one call to the next. What a step wants
+					// kept is recorded in the history above instead. The short
+					// reminders and notices follow it.
 					const messages = [...projected]
-					this.turnContext.place(
+					// What the loop learns about files and finished work holds until it
+					// changes, so it is recorded, after the history as it stands, and
+					// carried in this request where it will sit in the next one's history.
+					const work = workContext(shaping, projected, iterationNum, step)
+					const recordedNow = appendRecordedContext(recorder, work.recorded, this.ctx.log)
+					placeRequestContext(
 						messages,
-						requestHistory,
-						workingMemory.history.at(-1),
-						[contextText, ...(step.context ? splitAtEvidenceBlocks(step.context) : [])]
-							.filter((text): text is string => Boolean(text))
-							.map(stepContextMessage),
-						workContextBlocks(shaping, projected, iterationNum, step),
-						{ [FILE_EVIDENCE_KEY]: stepContextMessage(FILE_EVIDENCE_NONE) },
+						recordedNow,
+						// The working-memory block and the policy notice already end the
+						// request; the entries just recorded belong ahead of them.
+						(workingMemory.context ? 1 : 0) + (policyNotice ? 1 : 0),
+						[
+							...[contextText, step.context]
+								.filter((text): text is string => Boolean(text))
+								.map(stepContextMessage),
+							...work.requestOnly,
+						],
 					)
 					if (closingDirective) messages.push(closingDirective)
 					await this.reportUnsupportedToolResults(messages)
@@ -2896,9 +2903,8 @@ export class IterationOrchestrator {
 				this.ctx.turnConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 				{ imagesReadable: this.modelReadsImages(model) },
 			)
-			appendWorkContext(this.stepShaping(), finalMessages, this.steps.length + 1, { model })
 			// The closing directive is the last thing the model reads: after
-			// the working memory and any work context above.
+			// the working memory above.
 			finalMessages.push(
 				createRuntimeContextMessage(
 					`[SYSTEM] Turn is ending due to ${reason}. ${CLOSING_RESPONSE_GUIDANCE}`,

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

@@ -0,0 +1,48 @@
+import { NAMZU } from '../../../constants/telemetry/index.js'
+import type { TurnRecorder } from '../../../manager/session/turn-recorder.js'
+import {
+	type Message,
+	createTurnContextEntry,
+	isTurnContextKey,
+	turnContextEntries,
+} from '../../../types/message/index.js'
+import type { RecordedContextItem } from '../../../types/session/index.js'
+import type { Logger } from '../../../utils/logger.js'
+
+/**
+ * Append what a step asked to have recorded, after whatever the history
+ * ends with.
+ *
+ * Only at the end: an entry slipped in ahead of the operator's message would
+ * put the live array out of log order, and the recorder would then write a
+ * whole compaction record to re-base it on every turn. An item adds nothing
+ * when its text is empty or equals the last entry under its key, so a step
+ * that offers the same text on every call records it once. Returns the
+ * entries it added, so a request built before they were added can carry them
+ * at the place they will hold.
+ */
+export function appendRecordedContext(
+	recorder: Pick<TurnRecorder, 'messages' | 'pushMessage' | 'turnId'>,
+	items: readonly RecordedContextItem[] | undefined,
+	log: Pick<Logger, 'warn'>,
+	at: Date = new Date(),
+): Message[] {
+	const appended: Message[] = []
+	for (const item of items ?? []) {
+		const text = item.text.trim()
+		if (text.length === 0) continue
+		if (!isTurnContextKey(item.key)) {
+			log.warn('A step recorded context under a key that is not a name; it was skipped', {
+				[NAMZU.TURN_ID]: recorder.turnId,
+				'namzu.runtime.key': String(item.key).slice(0, 80),
+			})
+			continue
+		}
+		const earlier = turnContextEntries(recorder.messages, item.key)
+		if (earlier.at(-1) === text) continue
+		const entry = createTurnContextEntry(item.key, text, at, { later: earlier.length > 0 })
+		recorder.pushMessage(entry)
+		appended.push(entry)
+	}
+	return appended
+}

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