@namzu/sdk 53.0.0 → 53.2.0

package/src/store/session-log/core.ts

@@ -51,6 +51,7 @@ import {
 	isLeaseLive,
 } from './lease.js'
 import type { SpillReadOptions, SpillRef, SpillStore } from './spill.js'
+import { TOOL_INPUT_RECORD_TYPES, spilledInput, toolInputSlots } from './spilled-input.js'
 
 // ─── public types ─────────────────────────────────────────────────────────
 
@@ -666,6 +667,9 @@ export class SessionLogCore implements SessionLog {
 			? await this.#spillStructuredResults(original)
 			: original
 		const type = candidate.type
+		if (typeof type === 'string' && TOOL_INPUT_RECORD_TYPES.has(type)) {
+			return this.#spillToolInputs(candidate)
+		}
 		if (
 			type !== 'message' &&
 			type !== 'message_replaced' &&
@@ -715,6 +719,30 @@ export class SessionLogCore implements SessionLog {
 		return { ...candidate, content: preview, spill: ref }
 	}
 
+	/**
+	 * A record that carries tool inputs and would not fit a line: each large
+	 * input goes to `tool-results/` and the record keeps a stand-in, so the
+	 * person is still asked and the call is still restored on resume.
+	 */
+	async #spillToolInputs(candidate: Record<string, unknown>): Promise<Record<string, unknown>> {
+		const sizeOf = (record: Record<string, unknown>): number =>
+			Buffer.byteLength(`${JSON.stringify(record)}\n`, 'utf8')
+		if (sizeOf(candidate) <= this.#spillAbove) return candidate
+		const copy = structuredClone(candidate)
+		const slots = toolInputSlots(copy)
+		const bodies = slots.map(({ holder, key }) => JSON.stringify(holder[key]) ?? 'null')
+		// Largest first, and only as many as it takes to fit.
+		const order = slots.map((_, i) => i).sort((a, b) => bodies[b]!.length - bodies[a]!.length)
+		for (const index of order) {
+			const slot = slots[index]!
+			const body = bodies[index]!
+			const ref = await this.#spills.write(`input:${String(candidate.id)}:${index}`, 'text', body)
+			slot.holder[slot.key] = spilledInput(ref, body)
+			if (sizeOf(copy) <= this.#spillAbove) break
+		}
+		return copy
+	}
+
 	async #spillStructuredResults(
 		candidate: Record<string, unknown>,
 	): Promise<Record<string, unknown>> {

package/src/store/session-log/spilled-input.ts

@@ -0,0 +1,90 @@
+import type { SpillRef } from './spill.js'
+
+/**
+ * A tool call's input can be larger than a session-log record may be (a
+ * write of a few megabytes, a batch of large writes). The record that carries
+ * it then holds this stand-in, and the input itself sits in `tool-results/`
+ * under the same rules as any other spilled body.
+ */
+export const SPILLED_INPUT_KEY = '$spilledInput'
+
+/** Characters of the input kept inline beside the reference. */
+const INPUT_PREVIEW_CHARS = 200
+
+export interface SpilledInput {
+	readonly [SPILLED_INPUT_KEY]: SpillRef
+	readonly preview: string
+}
+
+export function spilledInput(ref: SpillRef, json: string): SpilledInput {
+	return { [SPILLED_INPUT_KEY]: ref, preview: json.slice(0, INPUT_PREVIEW_CHARS) }
+}
+
+export function isSpilledInput(value: unknown): value is SpilledInput {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		SPILLED_INPUT_KEY in value &&
+		typeof (value as Record<string, unknown>)[SPILLED_INPUT_KEY] === 'object'
+	)
+}
+
+/** Where a record keeps tool inputs: the holder object and the key of the input in it. */
+export interface InputSlot {
+	readonly holder: Record<string, unknown>
+	readonly key: string
+}
+
+function callSlots(calls: unknown): InputSlot[] {
+	if (!Array.isArray(calls)) return []
+	const slots: InputSlot[] = []
+	for (const call of calls) {
+		if (typeof call === 'object' && call !== null && 'input' in call) {
+			slots.push({ holder: call as Record<string, unknown>, key: 'input' })
+		}
+	}
+	return slots
+}
+
+/** Record types that carry a tool call's whole input. */
+export const TOOL_INPUT_RECORD_TYPES: ReadonlySet<string> = new Set([
+	'tool_review_requested',
+	'decision_requested',
+	'tool_executing',
+	'tool_input_completed',
+])
+
+/**
+ * The input slots of one record. The record is read, never changed; the
+ * caller copies what it replaces.
+ */
+export function toolInputSlots(record: Record<string, unknown>): InputSlot[] {
+	switch (record.type) {
+		case 'tool_review_requested':
+			return callSlots(record.toolCalls)
+		case 'decision_requested': {
+			const request = record.request as { toolCalls?: unknown } | undefined
+			return request ? callSlots(request.toolCalls) : []
+		}
+		case 'tool_executing':
+		case 'tool_input_completed':
+			return 'input' in record ? [{ holder: record, key: 'input' }] : []
+		default:
+			return []
+	}
+}
+
+/**
+ * The input slots of a request read back from a log, with any stand-in
+ * replaced by the input it stands for. Mutates and returns `request`.
+ */
+export async function restoreSpilledRequestInputs<T extends { toolCalls?: unknown }>(
+	request: T,
+	read: (ref: SpillRef) => Promise<string>,
+): Promise<T> {
+	for (const { holder, key } of callSlots(request.toolCalls)) {
+		const value = holder[key]
+		if (isSpilledInput(value)) holder[key] = JSON.parse(await read(value[SPILLED_INPUT_KEY]))
+	}
+	return request
+}

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.