@namzu/sdk 53.1.0 → 53.2.1

package/src/runtime/query/tool-output-budget.ts

@@ -42,6 +42,58 @@ export const MESSAGE_BUDGET_PREVIEW_CHARS = 2_000
  */
 export const SPILL_MARKER = 'The full output was written to:'
 
+/**
+ * The recovery routes a host has mounted for a retained output. A pointer
+ * names only a tool that exists, so the same sentence is true wherever it is
+ * read: in the result, in the cleared placeholder that keeps it, and in a
+ * summary that quotes it.
+ */
+export interface RetainedOutputRoutes {
+	/** The `read` tool is mounted and may open this session's own retained files. */
+	readonly read?: boolean
+	/** `search_conversation` and `read_conversation` are both mounted. */
+	readonly conversation?: boolean
+}
+
+/** Opening of the sentence that follows the spill line; how a pointer is recognised. */
+export const RETAINED_OUTPUT_NOTE = 'This path identifies retained output, not the original input.'
+
+const REPLAY_WARNING =
+	'A fresh observation of the original input cannot recover its earlier contents. If recovery is unavailable, report the missing detail; do not replay the original action.'
+
+/**
+ * The one sentence that says how to get at a retained output. Without routes
+ * (an embedder that told the budget nothing) it keeps the neutral wording.
+ */
+export function describeRetainedOutputRecovery(routes?: RetainedOutputRoutes): string {
+	const read = routes?.read === true
+	const conversation = routes?.conversation === true
+	const how = [
+		read ? 'To read more of it, open this file with the read tool (offset and limit).' : '',
+		conversation
+			? read
+				? 'For anything else from earlier in this conversation, call search_conversation with a phrase from it, then read_conversation with the seq and part it returns.'
+				: 'To read more of it, call search_conversation with a phrase from it, then read_conversation with the seq and part it returns. The path is not a workspace file, so read and grep cannot open it.'
+			: '',
+	].filter(Boolean)
+	if (how.length === 0)
+		return `${RETAINED_OUTPUT_NOTE} Use the host-authorized retained-output recovery tools when available; the path does not grant filesystem access. ${REPLAY_WARNING}`
+	return [RETAINED_OUTPUT_NOTE, ...how, REPLAY_WARNING].join(' ')
+}
+
+/**
+ * The spill line and the recovery sentence under it, when `text` carries them.
+ * Whatever shortens a result keeps this pair, so the route survives.
+ */
+export function retainedOutputPointer(text: string): string | undefined {
+	// A tool may end its lines with \r\n or a bare \r; the pointer is one line either way.
+	const lines = text.split(/\r\n|\r|\n/)
+	const at = lines.findIndex((line) => line.startsWith(SPILL_MARKER))
+	if (at < 0) return undefined
+	const next = lines[at + 1]
+	return next?.startsWith(RETAINED_OUTPUT_NOTE) ? `${lines[at]}\n${next}` : (lines[at] as string)
+}
+
 /**
  * Share of the budget spent on the head. The rest goes to the tail.
  *
@@ -91,7 +143,7 @@ function boundedPreview(
 		'',
 	].join('\n')
 	const compactMiddle = '\n[... omitted ...]\n'
-	const spillLine = recovery.split('\n').find((line) => line.startsWith(SPILL_MARKER))
+	const spillLine = recovery.split(/\r\n|\r|\n/).find((line) => line.startsWith(SPILL_MARKER))
 	const compactRecovery = spillLine ? `${compactMiddle}${spillLine}\n` : compactMiddle
 	const middle =
 		detailedMiddle.length < maxChars
@@ -182,6 +234,8 @@ export interface ApplyToolOutputBudgetOptions {
 	 * middle-elided instead — degraded, but never unbounded.
 	 */
 	readonly spillDir?: string | undefined
+	/** Which recovery routes the host has mounted; see {@link describeRetainedOutputRecovery}. */
+	readonly recoveryRoutes?: RetainedOutputRoutes
 	readonly onError?: (message: string) => void
 }
 
@@ -189,8 +243,9 @@ export interface ApplyToolOutputBudgetOptions {
  * Bound a tool result to the model-visible budget.
  *
  * Retention keeps the original while bounding its model-visible preview.
- * The host owns the recovery route and its permissions; a spill path is not
- * proof that workspace read/grep tools can access it. Middle-elision is the
+ * The recovery sentence names only the routes the host says are mounted
+ * ({@link RetainedOutputRoutes}); a spill path alone is not proof that a
+ * workspace tool can open it. Middle-elision is the
  * fallback for a turn with no directory to write to.
  *
  * The preview keeps head AND tail because the two ends carry different
@@ -224,10 +279,9 @@ export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolO
 
 	const spillPath = retained?.path
 	const recovery = spillPath
-		? [
-				`${SPILL_MARKER} ${spillPath}`,
-				'This path identifies retained output, not the original input. Use the host-authorized retained-output recovery tools when available; the path does not grant filesystem access. A fresh observation of the original input cannot recover its earlier contents. If recovery is unavailable, report the missing detail; do not replay the original action.',
-			].join('\n')
+		? [`${SPILL_MARKER} ${spillPath}`, describeRetainedOutputRecovery(opts.recoveryRoutes)].join(
+				'\n',
+			)
 		: 'The full output was not retained. Use a saved artifact or a read-only observation; do not repeat a state-changing action to recover its output.'
 	const requestedPreview = opts.retainedPreviewChars
 	// Separate the spill threshold from the cost of carrying its preview on every
@@ -358,11 +412,10 @@ export interface MessageBudgetReplacement {
 export interface FitResultsToMessageBudgetOptions {
 	readonly maxChars: number
 	readonly spillDir?: string | undefined
+	readonly recoveryRoutes?: RetainedOutputRoutes
 	readonly onError?: (message: string) => void
 }
 
-const SPILL_LINE = new RegExp(`^${SPILL_MARKER} .+$`, 'm')
-
 /**
  * Hold one assistant message's combined tool results under a cap.
  *
@@ -409,7 +462,7 @@ function previewForMessageBudget(
 	item: MessageBudgetItem,
 	opts: FitResultsToMessageBudgetOptions,
 ): MessageBudgetReplacement {
-	const spilledAt = SPILL_LINE.exec(item.output)?.[0]
+	const spilledAt = retainedOutputPointer(item.output)
 	if (spilledAt !== undefined) {
 		const output = [
 			safeHead(item.output, MESSAGE_BUDGET_PREVIEW_CHARS / 2),
@@ -420,7 +473,7 @@ function previewForMessageBudget(
 		return {
 			output,
 			originalLength: item.output.length,
-			spillPath: spilledAt.slice(SPILL_MARKER.length + 1),
+			spillPath: (spilledAt.split('\n')[0] as string).slice(SPILL_MARKER.length + 1),
 		}
 	}
 	const budgeted = applyToolOutputBudget({
@@ -430,6 +483,7 @@ function previewForMessageBudget(
 		output: item.output,
 		maxChars: MESSAGE_BUDGET_PREVIEW_CHARS,
 		spillDir: opts.spillDir,
+		...(opts.recoveryRoutes ? { recoveryRoutes: opts.recoveryRoutes } : {}),
 		...(opts.onError ? { onError: opts.onError } : {}),
 	})
 	return {

package/src/scheduler/local.ts

@@ -1,7 +1,11 @@
 import { GENAI } from '../constants/telemetry/index.js'
 import { taskFailed } from '../tools/coordinator/outcome.js'
 import type { AgentInput } from '../types/agent/base.js'
-import type { AgentManagerContract } from '../types/agent/manager.js'
+import type {
+	AgentManagerContract,
+	RestoreChildOptions,
+	RestoreChildResult,
+} from '../types/agent/manager.js'
 import type {
 	CreateTaskOptions,
 	SiblingFailurePolicy,
@@ -113,6 +117,9 @@ export class LocalTaskScheduler implements TaskScheduler {
 			{
 				agentId: options.agentId,
 				...(options.resumeSessionId ? { resumeSessionId: options.resumeSessionId } : {}),
+				...(options.continuationProfile
+					? { continuationProfile: options.continuationProfile }
+					: {}),
 				beforeStart: options.beforeStart,
 				...(options.workspace ? { workspace: options.workspace } : {}),
 				...(options.planId ? { planId: options.planId } : {}),
@@ -363,6 +370,12 @@ export class LocalTaskScheduler implements TaskScheduler {
 		await this.agentManager.continueTask(taskId, message)
 	}
 
+	async restoreChild(options: RestoreChildOptions): Promise<RestoreChildResult> {
+		if (!this.agentManager.restoreChildConversation)
+			return { status: 'refused', reason: 'no-layout' }
+		return this.agentManager.restoreChildConversation(options, this.taskContext)
+	}
+
 	cancelTask(taskId: TaskId, cause?: CancelCause): void {
 		this.agentManager.cancel(taskId, cause)
 	}

package/src/store/evidence/disk.ts

@@ -110,8 +110,9 @@ export interface EvidenceAnchor {
  * session log, or one turn of it. Closed by default (no active turn in scope);
  * snapshot mode also reads a session whose turn is running, without assuming
  * its writer is dead. The host owns authorization and the log's directory.
- * Changes to the log invalidate addresses; record and chunk digests detect
- * changed bytes. This is not a hostile filesystem sandbox.
+ * An address names a record by offset, length and digest and survives appends
+ * to the log; a replaced or rewritten log is refused and record and chunk
+ * digests detect changed bytes. This is not a hostile filesystem sandbox.
  */
 export function createSessionTextEvidenceSource(
 	options: SessionEvidenceSourceOptions,
@@ -261,9 +262,18 @@ function createSource(
 			if (!state.closed && consistency === 'closed') {
 				throw new Error('Evidence scope has an active turn; it is not closed.')
 			}
+			// The anchored prefix is verified here and again after the action. It is not
+			// part of the seal: the anchor moves with every record the writer appends, so
+			// binding it would void an address the moment the search call that returned
+			// it is itself recorded.
 			const anchorKey = anchor ? await verifyAnchor(handle, anchor) : undefined
+			// A session log only grows. An address names one record by offset, length and
+			// digest, and a read verifies all three against the bytes, so what must
+			// bind a seal is the file's identity, never its size or times: those change
+			// with every append and would void every address and cursor handed out a
+			// moment earlier, including one a search just returned.
 			const sourceKey = digest(
-				`session-v1:${consistency}:${mode}:${scopeKey}:${anchorKey ?? stamp(before)}`,
+				`session-v1:${consistency}:${mode}:${scopeKey}:${fileIdentity(before)}`,
 			)
 			const seal = evidenceSeal(state.first, sourceKey)
 			const value = await action(handle, size, seal, sourceKey, budget, !state.closed)
@@ -552,6 +562,21 @@ function createSource(
 	})
 }
 
+/**
+ * What names the log file across appends: device and inode, plus the creation
+ * time where the filesystem reports no inode (zero), so a replaced file still
+ * changes the identity there.
+ */
+function fileIdentity(stats: {
+	dev: number | bigint
+	ino: number | bigint
+	birthtimeMs: number
+}): string {
+	return Number(stats.ino) === 0
+		? `${stats.dev}:0:${stats.birthtimeMs}`
+		: `${stats.dev}:${stats.ino}`
+}
+
 /** The anchor record must still hold the bytes the writer vouched for. */
 async function verifyAnchor(handle: FileHandle, anchor: EvidenceAnchor): Promise<string> {
 	const bytes = await readBytes(handle, anchor.offset, anchor.length, {

package/src/store/evidence/source-text.ts

@@ -235,6 +235,28 @@ async function sourceText(
 	}
 }
 
+/**
+ * @experimental A read named a byte offset the retained text cannot start at.
+ * `inside_character` means the offset falls inside a multi-byte character (the
+ * character starts up to three bytes earlier); `past_end` means it lies beyond
+ * the text. Every other read failure (integrity, ownership, a changed source)
+ * is a plain `Error`, so a caller can recover from a bad position without
+ * treating a refusal as one.
+ */
+export class SessionEvidenceOffsetError extends Error {
+	constructor(
+		readonly code: 'inside_character' | 'past_end',
+		message: string,
+		/** Bytes of the retained text. */
+		readonly totalBytes: number,
+		/** Bytes this failed read was charged. */
+		readonly scannedBytes: number,
+	) {
+		super(message)
+		this.name = 'SessionEvidenceOffsetError'
+	}
+}
+
 export async function readTextPage(
 	source: TextSource,
 	scope: SessionEvidenceScope,
@@ -242,13 +264,27 @@ export async function readTextPage(
 	budget: EvidenceBudget,
 ): Promise<SessionTextEvidenceReadResult> {
 	const entry = source.entry
-	if (offset > source.bytes) throw new Error('Offset exceeds retained text.')
+	if (offset > source.bytes)
+		throw new SessionEvidenceOffsetError(
+			'past_end',
+			'Offset exceeds retained text.',
+			source.bytes,
+			budget.bytes,
+		)
 	const chunk = entry.spill
 		? Math.min(Math.floor(offset / EVIDENCE_CHUNK_BYTES), source.chunks - 1)
 		: 0
 	const window = await source.window(chunk)
-	if (offset < window.offset) throw new Error('Offset splits a UTF-8 character.')
+	const splits = () =>
+		new SessionEvidenceOffsetError(
+			'inside_character',
+			'Offset splits a UTF-8 character.',
+			source.bytes,
+			budget.bytes,
+		)
+	if (offset < window.offset) throw splits()
 	const bytes = window.bytes.subarray(offset - window.offset)
+	if (bytes.length && ((bytes[0] ?? 0) & 0xc0) === 0x80) throw splits()
 	let text = decode(utf8Page(bytes, 24_000))
 	if (text.length > 6000) {
 		let end = 6000

package/src/tools/builtins/read-file.ts

@@ -5,6 +5,7 @@ import type { ToolContext } from '../../types/tool/index.js'
 import type { ToolFacts } from '../../types/tool/presentation.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
+import { resolveRetainedOutput } from '../retained-output.js'
 import { looksBinary } from '../text-window.js'
 import { fingerprintContent } from './content-fingerprint.js'
 import { type RenderedRead, renderCappedRead } from './read-render.js'
@@ -71,8 +72,12 @@ export const ReadFileTool = defineTool({
 	},
 
 	async execute(input, context) {
+		// This session's own retained tool output lives on the host, outside the
+		// roots and outside any sandbox. It is read here, as a plain window of text,
+		// because the result that named it told the model to.
+		const retained = await resolveRetainedOutput(context.retainedOutputDirectory, input.path)
 		// Sandbox-aware: route through sandbox.readFile() when available
-		if (context.sandbox) {
+		if (context.sandbox && retained === undefined) {
 			const buffer = await context.sandbox.readFile(input.path)
 			const binaryGuidance = describeStructuredBinaryRead(input.path, buffer)
 			if (binaryGuidance) {
@@ -112,7 +117,7 @@ export const ReadFileTool = defineTool({
 			}
 		}
 
-		const filePath = await resolveWithinAnyReal(toolRoots(context), input.path)
+		const filePath = retained ?? (await resolveWithinAnyReal(toolRoots(context), input.path))
 		// Refused on the size alone, before the file is in memory, when no window
 		// was named: the cap exists so a huge file is never loaded to be refused.
 		if (input.readRange === undefined && input.limit === undefined) {

package/src/tools/retained-output.ts

@@ -0,0 +1,38 @@
+import { lstat, realpath } from 'node:fs/promises'
+import { dirname, extname, isAbsolute, relative, resolve } from 'node:path'
+
+function inside(root: string, path: string): boolean {
+	const rel = relative(root, path)
+	return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
+}
+
+/**
+ * The real path of a retained tool-output file the model may read, or
+ * `undefined` when `candidate` is not one.
+ *
+ * Only this session's own retained directory counts. The file must be an
+ * absolute path to a regular `.txt` file that is not a symbolic link, has no
+ * other hard link, and whose real location is inside the directory's real
+ * location (so a link anywhere along the path, or `..`, takes it out). Nothing
+ * is created, and nothing but a read is offered.
+ */
+export async function resolveRetainedOutput(
+	directory: string | undefined,
+	candidate: string | undefined,
+): Promise<string | undefined> {
+	if (!directory || !candidate || !isAbsolute(candidate) || candidate.includes('\0'))
+		return undefined
+	try {
+		const base = await realpath(directory)
+		const lexical = resolve(candidate)
+		if (extname(lexical).toLowerCase() !== '.txt') return undefined
+		if (!inside(resolve(directory), lexical) && !inside(base, lexical)) return undefined
+		const stat = await lstat(lexical)
+		if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) return undefined
+		const real = await realpath(lexical)
+		if (!inside(base, real) || dirname(real) === real) return undefined
+		return real
+	} catch {
+		return undefined
+	}
+}

package/src/types/agent/manager.ts

@@ -5,6 +5,48 @@ import type { SessionEventListener } from '../session/events.js'
 import type { AgentLifecycleListener } from './lifecycle-event.js'
 import type { AgentTask, AgentTaskContext, AgentTaskState, SendMessageOptions } from './task.js'
 
+/** Why a saved child could not be made continuable again. */
+export type RestoreChildRefusal =
+	/** No project layout is known, so there is no saved log to read. */
+	| 'no-layout'
+	/** Nothing readable is saved under that id for this parent. */
+	| 'not-saved'
+	/** The saved record belongs to another parent session. */
+	| 'foreign'
+	/** The saved record carries no continuation profile, was isolated, or names an agent the host cannot rebuild. */
+	| 'not-resumable'
+	/** The child never recorded an end: its process died mid-turn. */
+	| 'unsettled'
+	/** The child was cancelled. */
+	| 'stopped'
+	/** This manager already holds a continuation for it that is still running. */
+	| 'running'
+	/** Too many continuations are retained to take another. */
+	| 'full'
+
+export interface RestoreChildOptions {
+	/** The saved child's session id. */
+	readonly childSessionId: SessionId
+	/** The directory the continued child works in; the same one it ran in. */
+	readonly workingDirectory: string
+	/**
+	 * Which registered agent the child continues as, given the profile the host
+	 * recorded at launch. Return `undefined` when the host cannot rebuild it.
+	 */
+	readonly agentFor: (profile: Readonly<Record<string, string>>) => string | undefined
+}
+
+export type RestoreChildResult =
+	| {
+			readonly status: 'restored'
+			readonly childSessionId: SessionId
+			/** The agent chosen by {@link RestoreChildOptions.agentFor}; pass it to `createTask` with `resumeSessionId`. */
+			readonly agentId: string
+			readonly profile: Readonly<Record<string, string>>
+			readonly description: string
+	  }
+	| { readonly status: 'refused'; readonly reason: RestoreChildRefusal }
+
 /**
  * Agent task lifecycle contract — task creation, cancellation, messaging, and completion tracking.
  * Concrete implementation: `AgentManager` in `manager/agent/lifecycle.ts`.
@@ -48,6 +90,18 @@ export interface AgentManagerContract {
 	on(listener: AgentLifecycleListener): void
 	off(listener: AgentLifecycleListener): void
 
+	/**
+	 * Rebuild the right to continue a child that finished in an earlier process
+	 * from its saved log and meta document, under the invoking parent's scope.
+	 * Optional: only a manager that can read saved children offers it. Grants
+	 * nothing by itself; continuing still goes through `sendMessage` with
+	 * `resumeSessionId`, with the invoking turn's authority and limits.
+	 */
+	restoreChildConversation?(
+		options: RestoreChildOptions,
+		context: AgentTaskContext,
+	): Promise<RestoreChildResult>
+
 	cleanup(): void
 	dispose(): void
 }

package/src/types/agent/scheduler.ts

@@ -5,6 +5,7 @@ import type { CancelCause } from '../session/cancel-cause.js'
 import type { ChildSessionLifecycleEvent, SessionEventListener } from '../session/events.js'
 import type { WorkspaceRef } from '../workspace/ref.js'
 import type { AgentRuntimeContext, BaseAgentConfig, BaseAgentResult } from './base.js'
+import type { RestoreChildOptions, RestoreChildResult } from './manager.js'
 import type { AgentTaskState, ChildWorkspaceRequest } from './task.js'
 
 export interface TaskHandle {
@@ -41,6 +42,15 @@ export interface CreateTaskOptions {
 	 * and unchanged agent definition. A saved log alone grants no authority.
 	 */
 	readonly resumeSessionId?: SessionId
+	/**
+	 * What a later process needs to rebuild this child, written to the child's
+	 * saved meta document: at most 16 string entries, keys up to 64 and values up
+	 * to 256 characters. The host defines the keys (which agent to rebuild,
+	 * which model) and reads them back from `restoreChild`. Never put a secret
+	 * here; it lands on disk beside the log. Absent, the child cannot be
+	 * continued from disk after its process ends.
+	 */
+	readonly continuationProfile?: Readonly<Record<string, string>>
 	/** Per-task filesystem choice, forwarded to the local manager at admission. */
 	readonly workspace?: ChildWorkspaceRequest
 	/**
@@ -156,6 +166,17 @@ export interface TaskScheduler {
 
 	continueTask(taskId: TaskId, message: string): Promise<void>
 
+	/**
+	 * Make a child saved by an earlier process continuable again, from its saved
+	 * log and meta document, under this scheduler's parent scope. OPTIONAL: only
+	 * a scheduler that can read saved children offers it. It runs nothing; the
+	 * caller then continues the child with `createTask({ resumeSessionId })`, so
+	 * the invoking turn's authority and limits apply. See
+	 * {@link CreateTaskOptions.continuationProfile} for what must have been
+	 * recorded at launch.
+	 */
+	restoreChild?(options: RestoreChildOptions): Promise<RestoreChildResult>
+
 	/**
 	 * Stop one task. A cause is relative to the child: a blocking delegation
 	 * abandoned by the turn that launched it is cancelled by its `parent`.

package/src/types/agent/task.ts

@@ -238,6 +238,8 @@ export interface AgentTask {
 export interface SendMessageOptions {
 	/** See {@link import('./scheduler.js').CreateTaskOptions.resumeSessionId}. */
 	readonly resumeSessionId?: SessionId
+	/** See {@link import('./scheduler.js').CreateTaskOptions.continuationProfile}. */
+	readonly continuationProfile?: Readonly<Record<string, string>>
 	/** Explicit child filesystem policy; omitted preserves legacy backend behavior. */
 	readonly workspace?: ChildWorkspaceRequest
 	/**

package/src/types/session/records.ts

@@ -1039,6 +1039,22 @@ export const ChildSessionMetaSchema = z
 		status: turnExecutionStatus,
 		createdAt: isoUtc,
 		endedAt: isoUtc.optional(),
+		/**
+		 * What a later process needs to continue this child from its saved log:
+		 * the filesystem policy it ran under and a small host-defined profile
+		 * (which agent to rebuild, which model). Absent on children saved before
+		 * this field existed and on children whose host recorded no profile; those
+		 * cannot be continued from disk.
+		 */
+		continuation: z
+			.object({
+				workspace: z.enum(['shared', 'isolated']),
+				profile: z
+					.record(z.string().min(1).max(64), z.string().max(256))
+					.refine((value) => Object.keys(value).length <= 16, 'At most 16 profile entries'),
+			})
+			.strict()
+			.optional(),
 	})
 	.strict()
 export type ChildSessionMeta = z.infer<typeof ChildSessionMetaSchema>

package/src/types/tool/index.ts

@@ -458,6 +458,14 @@ export interface ToolContext {
 	 * directory; an absolute path inside any of these is accepted.
 	 */
 	additionalDirectories?: readonly string[]
+	/**
+	 * Absolute path of the directory holding THIS session's retained tool
+	 * output (the files an oversized result was saved to). The `read` tool may
+	 * open a regular file in it, and only that, without the path being a
+	 * reviewed or added directory: the model was already shown the path in the
+	 * result it came from. Set by the executor whenever the turn retains output.
+	 */
+	retainedOutputDirectory?: string
 	/**
 	 * Absolute paths outside the working directory and the added directories
 	 * that THIS call was approved to reach.