@namzu/sdk 53.1.0 → 53.2.0

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.