@namzu/sdk 56.1.0 → 57.0.0

package/src/agents/plan.ts

@@ -0,0 +1,30 @@
+/**
+ * The delegate that plans without touching anything.
+ *
+ * A parent that wants a design before it changes code has two bad options:
+ * plan in its own context, which spends the window on exploration, or hand
+ * the whole job to a delegate that can also edit. This type is the third:
+ * the same roster as `explore` (`EXPLORE_AGENT_ID`, built by filtering each
+ * contributing toolset with `isTrustedReadOnly`), under a prompt that asks
+ * for a step plan naming the files it touches and the risks it sees. The
+ * roster is the host's to build; only the identity and the prompt live here.
+ */
+
+export const PLAN_AGENT_ID = 'plan'
+
+export const PLAN_AGENT_DESCRIPTION =
+	'A read-only sub-agent that studies the code and returns a step plan with the files it touches and the risks.'
+
+/**
+ * What a plan delegate is told. It states its limits in the first person so a
+ * model does not describe a change as made, and fixes the shape of the answer
+ * because the parent acts on the steps and opens the files.
+ */
+export const PLAN_AGENT_PROMPT = [
+	'You are a read-only sub-agent dispatched to plan a change: you study the code and return a plan, never the change itself.',
+	'You cannot see the parent conversation — work only from the prompt you were given.',
+	'You have reading and searching tools only. You cannot edit, write or run commands, and you must not describe a change as made.',
+	'Read first: find the code the change touches, the patterns it should follow and the tests that cover it. Prefer what the code already does over a design of your own.',
+	'Return the plan in this shape: a one-paragraph approach; numbered steps in the order to do them, each naming the files it changes; the files to read or change first, as paths with line numbers where it helps; the risks and open questions, including what could break and how to check it.',
+	'Say plainly what you could not determine. End with the plan; do not ask the parent questions.',
+].join('\n')

package/src/compaction/context-breakdown.ts

@@ -12,7 +12,7 @@
  */
 
 import { CHARS_PER_TOKEN } from '../constants/limits.js'
-import type { Message } from '../types/message/index.js'
+import { type Message, isTurnContextEntry } from '../types/message/index.js'
 import type { LLMToolSchema } from '../types/tool/index.js'
 import { TRIGGER_BUFFER_TOKENS, TRIGGER_OUTPUT_RESERVE_CAP_TOKENS } from './context-window.js'
 import { estimateMessageTokens, estimateTextTokens } from './token-estimate.js'
@@ -166,6 +166,9 @@ function breakdownMessages(messages: readonly Message[]): ContextMessageBreakdow
 			const name = nameOfCall.get(message.toolCallId) ?? 'unknown'
 			toolResultsByType[name] = (toolResultsByType[name] ?? 0) + tokensOfContent(message)
 		} else if (message.role === 'user') {
+			// Recorded context is what the host recalled for the model, not
+			// something the operator said, so it is counted under memory.
+			if (isTurnContextEntry(message)) continue
 			userTokens += tokensOfContent(message)
 		}
 	}
@@ -175,13 +178,15 @@ function breakdownMessages(messages: readonly Message[]): ContextMessageBreakdow
 /** Split a window into the parts that fill it. */
 export function analyzeContextUsage(input: ContextUsageInput): ContextBreakdown {
 	const windowTokens = Math.max(0, Math.round(input.windowTokens))
+	const recorded = (input.messages ?? []).filter(isTurnContextEntry)
+	const recordedTokens = recorded.reduce((sum, message) => sum + tokensOfContent(message), 0)
 	const fixed: Record<(typeof CONTEXT_CATEGORY_ORDER)[number], number> = {
 		'system-prompt': nonNegative(input.systemPromptTokens),
 		'system-tools': nonNegative(input.systemToolTokens),
 		'mcp-tools': nonNegative(input.mcpToolTokens),
 		'mcp-instructions': nonNegative(input.mcpInstructionTokens),
 		agents: nonNegative(input.agentTokens),
-		memory: nonNegative(input.memoryTokens),
+		memory: nonNegative(input.memoryTokens) + recordedTokens,
 		skills: nonNegative(input.skillTokens),
 		messages: 0,
 	}
@@ -195,7 +200,10 @@ export function analyzeContextUsage(input: ContextUsageInput): ContextBreakdown
 	const rawMessages =
 		measured > 0
 			? Math.max(0, measured - fixedTotal)
-			: messages.reduce((sum, message) => sum + tokensOfContent(message), 0)
+			: messages.reduce(
+					(sum, message) => (isTurnContextEntry(message) ? sum : sum + tokensOfContent(message)),
+					0,
+				)
 	fixed.messages = Math.min(rawMessages, Math.max(0, windowTokens - fixedTotal - bufferTokens))
 
 	const totalTokens = measured > 0 ? Math.max(measured, fixedTotal) : fixedTotal + rawMessages

package/src/compaction/dangling.ts

@@ -231,6 +231,8 @@ export interface ToolHistoryRepairReport {
 	readonly orphanedToolResultsRemoved: number
 	/** Error results inserted for calls whose durable outcome is unavailable. */
 	readonly syntheticToolResultsInserted: number
+	/** Of those, the results that say the call never started. Absent when none. */
+	readonly neverRanToolResultsInserted?: number
 }
 
 /** A repaired copy and the exact changes made to it. */
@@ -274,7 +276,30 @@ function validateToolCallIds(messages: readonly Message[]): void {
 	}
 }
 
-function unknownOutcomeResult(call: ToolCall, assistant: AssistantMessage): ToolMessage {
+/** What is known about the unanswered calls of a history being repaired. */
+export interface ToolHistoryRepairOptions {
+	/**
+	 * Ids of calls known never to have started (queued, or waiting for a
+	 * person's approval, when the session ended). Their synthetic result says
+	 * nothing ran, instead of calling the outcome unknown.
+	 */
+	readonly neverRan?: ReadonlySet<string>
+}
+
+function unknownOutcomeResult(
+	call: ToolCall,
+	assistant: AssistantMessage,
+	neverRan: boolean,
+): ToolMessage {
+	if (neverRan) {
+		return {
+			role: CONSTANTS.TOOL_ROLE,
+			toolCallId: call.id,
+			isError: true,
+			content: `The \`${call.function.name}\` call did not run: the session ended before it started (it may have been waiting for the user's approval, which was never given). Nothing was changed. If it is still needed, call it again.`,
+			...(assistant.timestamp !== undefined ? { timestamp: assistant.timestamp } : {}),
+		}
+	}
 	return {
 		role: CONSTANTS.TOOL_ROLE,
 		toolCallId: call.id,
@@ -294,13 +319,17 @@ function unknownOutcomeResult(call: ToolCall, assistant: AssistantMessage): Tool
  * fail closed: changing ids or tool calls would invalidate opaque native replay
  * state carried by the assistant message.
  */
-export function repairToolMessageHistory(messages: readonly Message[]): ToolHistoryRepairResult {
+export function repairToolMessageHistory(
+	messages: readonly Message[],
+	options: ToolHistoryRepairOptions = {},
+): ToolHistoryRepairResult {
 	validateToolCallIds(messages)
 
 	const repaired: Message[] = []
 	let duplicateToolResultsRemoved = 0
 	let orphanedToolResultsRemoved = 0
 	let syntheticToolResultsInserted = 0
+	let neverRanToolResultsInserted = 0
 	let index = 0
 
 	while (index < messages.length) {
@@ -352,8 +381,10 @@ export function repairToolMessageHistory(messages: readonly Message[]): ToolHist
 
 		for (const call of calls) {
 			if (answered.has(call.id)) continue
-			repaired.push(unknownOutcomeResult(call, assistant))
+			const neverRan = options.neverRan?.has(call.id) === true
+			repaired.push(unknownOutcomeResult(call, assistant, neverRan))
 			syntheticToolResultsInserted++
+			if (neverRan) neverRanToolResultsInserted++
 		}
 		index = resultEnd
 	}
@@ -364,6 +395,7 @@ export function repairToolMessageHistory(messages: readonly Message[]): ToolHist
 			duplicateToolResultsRemoved,
 			orphanedToolResultsRemoved,
 			syntheticToolResultsInserted,
+			...(neverRanToolResultsInserted > 0 ? { neverRanToolResultsInserted } : {}),
 		},
 	}
 }

package/src/compaction/index.ts

@@ -4,6 +4,9 @@ export type {
 	FileSlot,
 	PinSlot,
 	PlanSlot,
+	RestorableFile,
+	RestorableSkill,
+	RestorableState,
 	ToolResultSlot,
 	WorkingState,
 	WorkingStatePin,
@@ -11,6 +14,7 @@ export type {
 
 export type {
 	DanglingResult,
+	ToolHistoryRepairOptions,
 	ToolHistoryRepairReport,
 	ToolHistoryRepairResult,
 } from './dangling.js'

package/src/compaction/manager.ts

@@ -4,10 +4,18 @@ import type {
 	FileSlot,
 	PinSlot,
 	PlanSlot,
+	RestorableState,
 	ToolResultSlot,
 	WorkingState,
 } from './types.js'
 
+/** Skills kept for restoring; the oldest is dropped past this. */
+export const MAX_RESTORABLE_SKILLS = 8
+/** Files kept for restoring; the oldest is dropped past this. */
+export const MAX_RESTORABLE_FILES = 12
+/** Characters of one skill or file kept for restoring (a little over the 5,000 tokens a restore shows, so the cut is visible). */
+export const MAX_RESTORABLE_CHARS = 24_000
+
 /** Pins kept at most; the oldest is dropped past this, and the drop is counted. */
 export const MAX_PINS = 40
 /** Characters one pin may carry; a pin is a fact, not a document. */
@@ -23,6 +31,10 @@ export function truncateStateText(text: string, max: number): string {
 	return `${head}${marker}`
 }
 
+function normalizeRestorablePath(path: string): string {
+	return path.trim().replace(/^\.\//, '')
+}
+
 function createEmptyState(): WorkingState {
 	return {
 		task: '',
@@ -90,6 +102,47 @@ export class WorkingStateManager {
 		}
 	}
 
+	private restorableState(): RestorableState {
+		if (!this.state.restorable) this.state.restorable = { skills: [], files: [] }
+		return this.state.restorable
+	}
+
+	/**
+	 * Remember a skill's instructions so a compaction can put them back.
+	 * `append` adds a later page of a skill that arrives in pages.
+	 */
+	recordSkillBody(name: string, body: string, append = false): void {
+		const key = name.trim()
+		if (key.length === 0 || body.trim().length === 0) return
+		const restorable = this.restorableState()
+		const index = restorable.skills.findIndex((skill) => skill.name === key)
+		const previous = index >= 0 ? restorable.skills[index] : undefined
+		const joined = append && previous ? `${previous.body}${body}` : body
+		if (index >= 0) restorable.skills.splice(index, 1)
+		restorable.skills.push({ name: key, body: joined.slice(0, MAX_RESTORABLE_CHARS) })
+		while (restorable.skills.length > MAX_RESTORABLE_SKILLS) restorable.skills.shift()
+	}
+
+	/** Remember what a read returned so a compaction can put it back. */
+	recordFileText(path: string, text: string): void {
+		const key = normalizeRestorablePath(path)
+		if (key.length === 0 || text.trim().length === 0) return
+		const restorable = this.restorableState()
+		const index = restorable.files.findIndex((file) => file.path === key)
+		if (index >= 0) restorable.files.splice(index, 1)
+		restorable.files.push({ path: key, text: text.slice(0, MAX_RESTORABLE_CHARS) })
+		while (restorable.files.length > MAX_RESTORABLE_FILES) restorable.files.shift()
+	}
+
+	/** A file that was changed after it was read no longer has a body worth restoring. */
+	forgetFileText(path: string): void {
+		const files = this.state.restorable?.files
+		if (!files) return
+		const key = normalizeRestorablePath(path)
+		const index = files.findIndex((file) => file.path === key)
+		if (index >= 0) files.splice(index, 1)
+	}
+
 	addDecision(decision: string): void {
 		this.pushWithEviction('decisions', this.state.decisions, decision, this.config.maxListSize)
 	}

package/src/compaction/manual.ts

@@ -17,6 +17,7 @@ import {
 } from './extractor.js'
 import { WorkingStateManager } from './manager.js'
 import { planCompaction } from './plan.js'
+import { recordRestorable, renderRestoredContext } from './restore.js'
 import { findRetainedIndices } from './retention.js'
 import { buildCompactionMessage, isCompactionMessage } from './summary.js'
 import { type CompactionVerificationOptions, buildVerifiedSummary } from './verifier.js'
@@ -69,6 +70,8 @@ export interface CompactNowInput extends CompactionVerificationOptions {
 	 * model at the originals ({@link COMPACTION_RECOVERY_NOTE}). Absent adds none.
 	 */
 	readonly recoveryNote?: string
+	/** Text the host wants carried across, such as where its plan file is; added to the restored context. */
+	readonly restoreNote?: string
 }
 
 async function publishManualCompaction(
@@ -116,6 +119,23 @@ function splice(
 	return { messages: [...preservedSystem, summary, ...retainedOlder, ...recentMessages], summary }
 }
 
+/** The summary with the loaded skills and read files put back after it. */
+function withRestoredContext(
+	body: string,
+	manager: WorkingStateManager,
+	input: CompactNowInput,
+): string {
+	const window = resolveContextWindow(
+		input.contextWindowTokens ?? input.config.contextWindowTokens,
+		input.model,
+	)
+	const restored = renderRestoredContext(manager.getState(), {
+		contextWindowTokens: window.tokens,
+		...(input.restoreNote ? { hostNote: input.restoreNote } : {}),
+	})
+	return restored ? `${body}\n\n${restored}` : body
+}
+
 /** Build the state a host-triggered pass is about to replace. */
 function populateWorkingState(
 	manager: WorkingStateManager,
@@ -124,6 +144,7 @@ function populateWorkingState(
 ): void {
 	let firstUser = true
 	const toolNames = new Map<string, string>()
+	const toolInputs = new Map<string, unknown>()
 
 	for (const message of messages) {
 		switch (message.role) {
@@ -139,17 +160,26 @@ function populateWorkingState(
 				if (message.content) extractFromAssistantMessage(manager, message.content, config)
 				for (const call of message.toolCalls ?? []) {
 					toolNames.set(call.id, call.function.name)
+					try {
+						toolInputs.set(call.id, JSON.parse(call.function.arguments))
+					} catch {
+						// Unparseable arguments restore nothing.
+					}
 					extractFromToolCall(manager, call.function.name, call.function.arguments)
 				}
 				break
-			case 'tool':
-				extractFromToolResult(
-					manager,
-					toolNames.get(message.toolCallId) ?? 'tool',
-					toolResultToText(message.content),
-					message.isError === true,
-				)
+			case 'tool': {
+				const toolName = toolNames.get(message.toolCallId) ?? 'tool'
+				const text = toolResultToText(message.content)
+				extractFromToolResult(manager, toolName, text, message.isError === true)
+				recordRestorable(manager, {
+					toolName,
+					input: toolInputs.get(message.toolCallId),
+					output: text,
+					success: message.isError !== true,
+				})
 				break
+			}
 			case 'system':
 				break
 		}
@@ -218,7 +248,7 @@ export async function compactNow(input: CompactNowInput): Promise<CompactionResu
 
 	const { messages, summary } = splice(
 		preservedSystem,
-		body,
+		withRestoredContext(body, manager, input),
 		retainedOlder,
 		plan.recentMessages,
 		input.recoveryNote,
@@ -230,7 +260,6 @@ export async function compactNow(input: CompactNowInput): Promise<CompactionResu
 		usage,
 	})
 }
-
 export interface CompactRegionInput extends CompactNowInput {
 	/** First index to summarise, inclusive. */
 	readonly start: number
@@ -311,7 +340,10 @@ export async function compactRegion(input: CompactRegionInput): Promise<Compacti
 
 	// Same cross-run ownership as compactNow: a selected region has been
 	// replaced outside a turn, so its only surviving account is pinned.
-	const summary = { ...buildCompactionMessage(body, input.recoveryNote), retain: true }
+	const summary = {
+		...buildCompactionMessage(withRestoredContext(body, manager, input), input.recoveryNote),
+		retain: true,
+	}
 	const out = [...messages.slice(0, start), summary, ...retainedSelected, ...messages.slice(end)]
 
 	// Checked after the splice, not only before it. The edges being

package/src/compaction/restore.ts

@@ -0,0 +1,159 @@
+import { resolve as resolvePath } from 'node:path'
+
+import { CHARS_PER_TOKEN } from '../constants/limits.js'
+import type { WorkingStateManager } from './manager.js'
+import type { WorkingState } from './types.js'
+
+/**
+ * What a compaction puts back after the summary.
+ *
+ * A summary says a skill was loaded and a file was read; it cannot give the
+ * model the skill's steps or the file's lines, so the next step either guesses
+ * from a paraphrase or loads and reads the same things again. This puts the
+ * most recent of each back, verbatim, inside fixed caps — and inside a share
+ * of the window, so a small window is not refilled by the thing that was meant
+ * to free it.
+ */
+
+/** Skills restored per pass, most recent first. */
+export const RESTORE_MAX_SKILLS = 8
+/** Tokens of one restored skill. */
+export const RESTORE_SKILL_TOKENS = 5_000
+/** Tokens of all restored skills together. */
+export const RESTORE_SKILLS_TOTAL_TOKENS = 25_000
+/** Files restored per pass, most recent first. */
+export const RESTORE_MAX_FILES = 5
+/** Tokens of one restored file. */
+export const RESTORE_FILE_TOKENS = 5_000
+/** Tokens of all restored files together. */
+export const RESTORE_FILES_TOTAL_TOKENS = 50_000
+/** The share of the window all restored files may take. */
+export const RESTORE_FILES_WINDOW_SHARE = 0.1
+/** The share of the window all restored skills may take. */
+export const RESTORE_SKILLS_WINDOW_SHARE = 0.05
+
+const CUT_MARKER = '\n… [cut to fit the restore budget]'
+const SKILL_CONTINUATION = /\n\n\[More skill instructions remain\.[^\]]*\]/g
+
+function isInstructionPath(path: string): boolean {
+	const normal = path.replace(/\\/g, '/')
+	const name = normal.slice(normal.lastIndexOf('/') + 1)
+	return name === 'AGENTS.md' || name === 'AGENTS.local.md' || normal.includes('/.namzu/rules/')
+}
+
+function resolveAgainst(path: string, workingDirectory: string | undefined): string {
+	return workingDirectory ? resolvePath(workingDirectory, path) : path
+}
+
+function isPlanPath(path: string): boolean {
+	return /(^|\/)plans\/plan\.md$/.test(path.replace(/\\/g, '/'))
+}
+
+/**
+ * Note a finished tool call, if it is one whose result a compaction restores.
+ * Called with the call's input and the text the model was shown.
+ */
+export function recordRestorable(
+	manager: WorkingStateManager,
+	call: {
+		readonly toolName: string
+		readonly input: unknown
+		readonly output: string
+		readonly success: boolean
+		/** The read was answered as unchanged: the body is already stored from the earlier read. */
+		readonly unchanged?: boolean
+		/** Resolves a relative path, so one file is one entry however the model spelled it. */
+		readonly workingDirectory?: string
+	},
+): void {
+	const input =
+		typeof call.input === 'object' && call.input !== null
+			? (call.input as Record<string, unknown>)
+			: undefined
+	if (!input) return
+	if (call.toolName === 'skill') {
+		if (!call.success || typeof input.name !== 'string') return
+		manager.recordSkillBody(
+			input.name,
+			call.output.replace(SKILL_CONTINUATION, ''),
+			typeof input.cursor === 'string' && input.cursor.length > 0,
+		)
+		return
+	}
+	if (call.toolName === 'read') {
+		const path = typeof input.path === 'string' ? input.path : undefined
+		if (!path || !call.success || call.unchanged) return
+		manager.recordFileText(resolveAgainst(path, call.workingDirectory), call.output)
+		return
+	}
+	if (call.toolName === 'write' || call.toolName === 'edit') {
+		const path = typeof input.path === 'string' ? input.path : undefined
+		// The body a read showed is behind the file now.
+		if (path && call.success) manager.forgetFileText(resolveAgainst(path, call.workingDirectory))
+	}
+}
+
+function fit(text: string, tokens: number): string {
+	const room = tokens * CHARS_PER_TOKEN
+	return text.length <= room
+		? text
+		: `${text.slice(0, Math.max(0, room - CUT_MARKER.length))}${CUT_MARKER}`
+}
+
+export interface RestoreRenderOptions {
+	/** The window the pass is working against; caps scale down on a small one. */
+	readonly contextWindowTokens?: number
+	/** A host's own line to carry across, such as where its plan file is. */
+	readonly hostNote?: string
+}
+
+/** The section to append after a summary, or `undefined` when there is nothing to put back. */
+export function renderRestoredContext(
+	state: WorkingState,
+	options: RestoreRenderOptions = {},
+): string | undefined {
+	const window = options.contextWindowTokens
+	const skillsTotal =
+		window === undefined
+			? RESTORE_SKILLS_TOTAL_TOKENS
+			: Math.min(RESTORE_SKILLS_TOTAL_TOKENS, Math.floor(window * RESTORE_SKILLS_WINDOW_SHARE))
+	const filesTotal =
+		window === undefined
+			? RESTORE_FILES_TOTAL_TOKENS
+			: Math.min(RESTORE_FILES_TOTAL_TOKENS, Math.floor(window * RESTORE_FILES_WINDOW_SHARE))
+
+	const sections: string[] = []
+
+	let skillBudget = skillsTotal
+	const skills = [...(state.restorable?.skills ?? [])].reverse()
+	for (const skill of skills) {
+		if (sections.length >= RESTORE_MAX_SKILLS || skillBudget <= 0) break
+		const body = fit(skill.body, Math.min(RESTORE_SKILL_TOKENS, skillBudget))
+		skillBudget -= Math.ceil(body.length / CHARS_PER_TOKEN)
+		sections.push(`### Skill: ${skill.name}\n\n${body}`)
+	}
+
+	let fileBudget = filesTotal
+	let files = 0
+	const candidates = [...(state.restorable?.files ?? [])].reverse()
+	for (const file of candidates) {
+		if (files >= RESTORE_MAX_FILES || fileBudget <= 0) break
+		if (isInstructionPath(file.path) || isPlanPath(file.path)) continue
+		const text = fit(file.text, Math.min(RESTORE_FILE_TOKENS, fileBudget))
+		fileBudget -= Math.ceil(text.length / CHARS_PER_TOKEN)
+		files += 1
+		sections.push(`### File: ${file.path}\n\n${text}`)
+	}
+
+	const note = options.hostNote?.trim()
+	if (note) sections.push(note)
+	if (sections.length === 0) return undefined
+
+	return [
+		'## Restored after compaction',
+		'',
+		'These were loaded or read earlier in this conversation and are put back here so you can keep using them. A file below may have changed on disk since it was read; read it again before you rely on it for an edit.',
+		'',
+		sections.join('\n\n'),
+	].join('\n')
+}

package/src/compaction/types.ts

@@ -28,6 +28,31 @@ export interface WorkingState {
 	 * of the state".
 	 */
 	evicted: Record<string, number>
+	/**
+	 * Bodies a compaction puts back after the summary: the skills the model
+	 * loaded and the files it read. Kept apart from the slots above because
+	 * they are verbatim text, not a summary of it, and are never rendered into
+	 * the working-memory block.
+	 */
+	restorable?: RestorableState
+}
+
+/** A skill the model loaded, as its instructions read. */
+export interface RestorableSkill {
+	readonly name: string
+	readonly body: string
+}
+
+/** A file the model read, as the read returned it. */
+export interface RestorableFile {
+	readonly path: string
+	readonly text: string
+}
+
+/** Oldest first; a later load or read of the same name or path replaces and moves to the end. */
+export interface RestorableState {
+	skills: RestorableSkill[]
+	files: RestorableFile[]
 }
 
 export interface PinSlot {

package/src/compaction/verifier.ts

@@ -55,7 +55,9 @@ function isStandingContext(message: Message): boolean {
 	return (
 		source?.type === 'project-instructions' ||
 		(source?.type === 'runtime-context' &&
-			(source.kind === 'step-context' || source.kind === 'reminder'))
+			(source.kind === 'step-context' ||
+				source.kind === 'reminder' ||
+				source.kind === 'turn-context'))
 	)
 }
 

package/src/compaction/wire.ts

@@ -1,6 +1,13 @@
 import type { CompactionConfig } from '../config/runtime.js'
 import { WorkingStateManager } from './manager.js'
-import type { FileSlot, PinSlot, PlanSlot, ToolResultSlot, WorkingState } from './types.js'
+import type {
+	FileSlot,
+	PinSlot,
+	PlanSlot,
+	RestorableState,
+	ToolResultSlot,
+	WorkingState,
+} from './types.js'
 
 /**
  * The working state in a form that survives a process boundary.
@@ -42,6 +49,8 @@ export interface WorkingStateSnapshot {
 	 * completeness it does not have.
 	 */
 	readonly evicted: Readonly<Record<string, number>>
+	/** Absent in snapshots written before bodies were restored; restored as none. */
+	readonly restorable?: RestorableState
 }
 
 export function snapshotWorkingState(manager: WorkingStateManager): WorkingStateSnapshot {
@@ -59,6 +68,14 @@ export function snapshotWorkingState(manager: WorkingStateManager): WorkingState
 		userRequirements: [...state.userRequirements],
 		assistantNotes: [...state.assistantNotes],
 		evicted: { ...state.evicted },
+		...(state.restorable
+			? {
+					restorable: {
+						skills: state.restorable.skills.map((skill) => ({ ...skill })),
+						files: state.restorable.files.map((file) => ({ ...file })),
+					},
+				}
+			: {}),
 	}
 }
 
@@ -89,6 +106,14 @@ export function restoreWorkingState(
 		userRequirements: [...snapshot.userRequirements],
 		assistantNotes: [...snapshot.assistantNotes],
 		evicted: { ...snapshot.evicted },
+		...(snapshot.restorable
+			? {
+					restorable: {
+						skills: snapshot.restorable.skills.map((skill) => ({ ...skill })),
+						files: snapshot.restorable.files.map((file) => ({ ...file })),
+					},
+				}
+			: {}),
 	}
 	manager.replaceState(state)
 	return manager

package/src/index.ts

@@ -47,6 +47,8 @@ export {
 } from './runtime/jobs/job-id.js'
 export type {
 	BackgroundJob,
+	ForegroundCommand,
+	ForegroundHandoffReason,
 	BackgroundJobOutput,
 	BackgroundJobRegistryConfig,
 	BackgroundJobStatus,