@demicodes/agent 0.19.1 → 0.19.3

package/dist/client-entry.d.mts

@@ -1,4 +1,4 @@
-import { f as TranscriptPatch, l as ServerFrame, n as AgentServerTransport, o as ClientFrame, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike, x as AgentMetadata } from "./transport-BRqZoaeo.mjs";
-import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C6Y5CeLG.mjs";
+import { f as TranscriptPatch, l as ServerFrame, n as AgentServerTransport, o as ClientFrame, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike, x as AgentMetadata } from "./transport-CHrPzcrU.mjs";
+import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-NZ5Btmb4.mjs";
 import { ProviderSelection } from "@demicodes/provider";
 export { type AgentActionOptions, AgentClient, type AgentClientListener, type AgentClientTransport, type AgentMetadata, type AgentServerTransport, type AgentTransport, type ClientFrame, type ClientSessionEvent, type JsonWebSocket, type ProviderSelection, type ServerFrame, type ShellCommandStatusLike, type TranscriptPatch, createWebSocketClientTransport, createWebSocketServerTransport };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { A as AgentSystemPromptContext, B as CompactionWindow, C as AgentReferenceResolveContext, D as AgentSessionParams, E as AgentSessionOptions, F as ExternalMutationReservation, G as DEFAULT_TURN_RETRY_POLICY, H as TranscriptLog, I as ModelSwitchApply, J as resolveRetryPolicy, K as TurnRetryPolicy, L as SessionEvent, M as AgentToolContext, N as AgentToolInvokeContext, O as AgentSessionRestoreParams, P as AgentToolInvokeResult, R as SessionEventListener, S as AgentPromptContext, T as AgentSessionCloneParams, U as TranscriptOptions, V as DrainedTranscriptPatches, W as estimateTranscriptBlockTokens, Y as retryDelayMs, _ as AgentHarnessContext, a as createInProcessTransportPair, b as AgentLifecycleEvent, c as ConversationSummary, d as SubagentJob, f as TranscriptPatch, g as AgentHarness, h as AgentDisposeContext, i as InProcessTransportPair, j as AgentTool, k as AgentSessionStore, l as ServerFrame, m as AbortTarget, n as AgentServerTransport, o as ClientFrame, p as AbortResult, q as isRetryableCode, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike, v as AgentHarnessRuntime, w as AgentSessionCheckpoint, x as AgentMetadata, y as AgentHostContext, z as SubagentProfile } from "./transport-BRqZoaeo.mjs";
-import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C6Y5CeLG.mjs";
-import { BashAuditEvent, BashEnvironment, BashEnvironmentOptions, Command, CommandMetadataRecord, Host, ShellCommandStatus, ShellOutputChunk } from "@demicodes/shell";
+import { A as AgentSystemPromptContext, B as CompactionWindow, C as AgentReferenceResolveContext, D as AgentSessionParams, E as AgentSessionOptions, F as ExternalMutationReservation, G as DEFAULT_TURN_RETRY_POLICY, H as TranscriptLog, I as ModelSwitchApply, J as resolveRetryPolicy, K as TurnRetryPolicy, L as SessionEvent, M as AgentToolContext, N as AgentToolInvokeContext, O as AgentSessionRestoreParams, P as AgentToolInvokeResult, R as SessionEventListener, S as AgentPromptContext, T as AgentSessionCloneParams, U as TranscriptOptions, V as DrainedTranscriptPatches, W as estimateTranscriptBlockTokens, Y as retryDelayMs, _ as AgentHarnessContext, a as createInProcessTransportPair, b as AgentLifecycleEvent, c as ConversationSummary, d as SubagentJob, f as TranscriptPatch, g as AgentHarness, h as AgentDisposeContext, i as InProcessTransportPair, j as AgentTool, k as AgentSessionStore, l as ServerFrame, m as AbortTarget, n as AgentServerTransport, o as ClientFrame, p as AbortResult, q as isRetryableCode, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike, v as AgentHarnessRuntime, w as AgentSessionCheckpoint, x as AgentMetadata, y as AgentHostContext, z as SubagentProfile } from "./transport-CHrPzcrU.mjs";
+import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-NZ5Btmb4.mjs";
+import { BashAuditEvent, BashEnvironment, BashEnvironmentOptions, Command, CommandMetadataRecord, Host, HostStore, ShellCommandStatus, ShellOutputChunk } from "@demicodes/shell";
 import { AgentProvider, Provider } from "@demicodes/provider";
 import { Block, Model, ModelMediaKind, ModelSelection, ProviderErrorDiagnostics, QueuedMessage, SessionPhase, UserContentBlock } from "@demicodes/core";
 //#region src/recovery.d.ts
@@ -339,6 +339,7 @@ declare class AgentServer {
 //#endregion
 //#region src/subagent.d.ts
 declare const MAX_LIVE_SUBAGENTS = 8;
+declare const MAX_ARCHIVED_SUBAGENTS = 16;
 declare const SUBAGENT_RESULT_MAX_BYTES: number;
 type SubagentExecution = 'idle' | 'provider_streaming' | 'tool_executing' | 'compacting' | 'finalizing' | 'pending_yield';
 interface ChildSupervisorOptions<State> {
@@ -353,14 +354,19 @@ interface ChildSupervisorOptions<State> {
   sessionOptions: AgentServerSessionOptions;
   /** When false, a child closing never wakes an idle parent; the host app orchestrates the wakeup from the `subagent closed` frame. */
   notifyParentOnIdle: boolean;
+  /** Backing store for child checkpoints and job metadata, keyed under the parent's session directory. */
+  store: HostStore;
   emit(frame: ServerFrame): void;
 }
 /**
  * Per-parent subagent supervisor. Owns every child `AgentSession` this parent
  * spawns: lifecycle (spawn / steer / abort / natural end), the `demi agent`
  * command tree, child shell environments, and the `subagent*` protocol frames
- * on the parent connection. Children are in-memory only: no store, no
- * checkpoint, gone with the parent.
+ * on the parent connection. Children persist exactly like the parent: each
+ * live child keeps a checkpoint and job record under the parent's session
+ * directory, and reopening the parent restores and resumes them (`restore`).
+ * A closed child moves to the archive: its transcript checkpoint stays on
+ * store and `demi agent resume` revives it with a new user message.
  */
 declare class ChildSupervisor<State = unknown> {
   private readonly options;
@@ -380,9 +386,43 @@ declare class ChildSupervisor<State = unknown> {
   } | null;
   /** Re-emits `subagent started` + transcript reset for every running child (transcript resync). */
   replay(): void;
+  /**
+   * Detaches every live child on connection teardown: aborts in-flight turns,
+   * flushes checkpoints, and keeps the persisted job so the next open of this
+   * parent restores it — the same dispose semantics as the parent session.
+   * No `closed` frame is emitted: the children are not done, just paused.
+   */
   dispose(): Promise<void>;
+  /**
+   * Rebuilds every persisted live child of this parent and finishes what it was
+   * doing: an interrupted turn resumes from its resume point; an already
+   * quiescent child closes with its result. Children share the parent's
+   * persistence lifecycle — a parent restore is a child restore.
+   */
+  restore(): Promise<void>;
+  private restoreJob;
+  /** Shared by restore and resume: rebuild a persisted child's job and session from its checkpoint. */
+  private reassembleJob;
+  /**
+   * Revives an archived child: its job record turns live again (this round's
+   * metadata, a fresh spawnedAt), the session rebuilds from the preserved
+   * checkpoint, and the message opens its next turn on top of the old
+   * transcript.
+   */
+  private resumeArchived;
+  /** Every archived (finished, revivable) child of this parent, newest first. */
+  private listArchivedJobs;
+  private pruneArchive;
   abortSubtree(id: string): Promise<void>;
   private spawn;
+  /** Everything spawn and restore share: the command tree, the harness runtime, and the job record (session attached separately). */
+  private assembleJob;
+  private attachSession;
+  private childStoreKey;
+  private childSessionStore;
+  private deletePersistedJob;
+  /** Shared spawn/resume foreground behaviour: announce the id, wire abort and stdin steers, wait for close, report the outcome. */
+  private attendChild;
   /** Delivers one steer to a child: mid-turn as a steer, idle as a new user turn. */
   private steerChild;
   private pumpStdinSteers;
@@ -392,6 +432,7 @@ declare class ChildSupervisor<State = unknown> {
   /** Resolves when the child is idle with no pending yield wakeups (or the job closed). */
   private waitForQuiescence;
   private closeJob;
+  private disposeJobShells;
   /** Wakes an idle parent with a user send; a parent blocked in the spawn gets the tool result instead. */
   private notifyIdleParent;
   private createChildAgentNode;
@@ -491,4 +532,4 @@ interface ShellToolView {
 declare function finishShellToolResult<State>(environment: BashEnvironment, result: ShellCommandStatus, ctx: AgentToolInvokeContext<State>): Promise<AgentToolInvokeResult>;
 declare function shellCommandHandleRequired(result: ShellCommandStatus, budgetTokens: number): boolean;
 //#endregion
-export { AbortResult, AbortTarget, ActiveTurnPhase, AgentActionOptions, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentHostContext, AgentLifecycleEvent, AgentMetadata, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionCheckpoint, AgentSessionCloneParams, AgentSessionOptions, AgentSessionParams, AgentSessionRestoreParams, AgentSessionStore, AgentSystemPromptContext, AgentTool, AgentToolContext, AgentToolInvokeContext, AgentToolInvokeResult, AgentTransport, AgentTransportBinding, ChildSupervisor, ChildSupervisorOptions, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, MAX_LIVE_SUBAGENTS, ModelSwitchApply, PrepareShell, PrepareShellContext, ProviderStreamError, ResumePoint, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, SUBAGENT_RESULT_MAX_BYTES, ServerFrame, SessionEvent, SessionEventListener, ShellCommandStatusLike, ShellToolResultOptions, ShellToolView, StandardAgentToolOptions, SubagentExecution, SubagentJob, SubagentProfile, TranscriptLog, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createReadonlyHost, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, injectSubagentCommand, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AbortResult, AbortTarget, ActiveTurnPhase, AgentActionOptions, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentHostContext, AgentLifecycleEvent, AgentMetadata, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionCheckpoint, AgentSessionCloneParams, AgentSessionOptions, AgentSessionParams, AgentSessionRestoreParams, AgentSessionStore, AgentSystemPromptContext, AgentTool, AgentToolContext, AgentToolInvokeContext, AgentToolInvokeResult, AgentTransport, AgentTransportBinding, ChildSupervisor, ChildSupervisorOptions, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, MAX_ARCHIVED_SUBAGENTS, MAX_LIVE_SUBAGENTS, ModelSwitchApply, PrepareShell, PrepareShellContext, ProviderStreamError, ResumePoint, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, SUBAGENT_RESULT_MAX_BYTES, ServerFrame, SessionEvent, SessionEventListener, ShellCommandStatusLike, ShellToolResultOptions, ShellToolView, StandardAgentToolOptions, SubagentExecution, SubagentJob, SubagentProfile, TranscriptLog, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createReadonlyHost, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, injectSubagentCommand, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/index.mjs

@@ -2653,6 +2653,7 @@ function shellCommandHandleRequired(result, budgetTokens) {
 //#endregion
 //#region src/subagent.ts
 const MAX_LIVE_SUBAGENTS = 8;
+const MAX_ARCHIVED_SUBAGENTS = 16;
 const SUBAGENT_RESULT_MAX_BYTES = 32768;
 const SHOW_RECENT_TOOLS = 8;
 const SPAWN_PROMPT_DESCRIPTION = "The child's first user message and only task brief. The child starts with an empty transcript and cannot see this conversation: do not refer to prior turns, and do not paste this conversation or the product user's message unchanged. Include the goal for this child, applicable decisions and constraints, whether to edit or only report, how to verify, and every concrete identifier it needs (paths, ids, error text, commands already tried and their key results). State the exact shape of the last assistant text it should return.";
@@ -2660,8 +2661,11 @@ const SPAWN_PROMPT_DESCRIPTION = "The child's first user message and only task b
 * Per-parent subagent supervisor. Owns every child `AgentSession` this parent
 * spawns: lifecycle (spawn / steer / abort / natural end), the `demi agent`
 * command tree, child shell environments, and the `subagent*` protocol frames
-* on the parent connection. Children are in-memory only: no store, no
-* checkpoint, gone with the parent.
+* on the parent connection. Children persist exactly like the parent: each
+* live child keeps a checkpoint and job record under the parent's session
+* directory, and reopening the parent restores and resumes them (`restore`).
+* A closed child moves to the archive: its transcript checkpoint stays on
+* store and `demi agent resume` revives it with a new user message.
 */
 var ChildSupervisor = class {
 	options;
@@ -2710,30 +2714,12 @@ var ChildSupervisor = class {
 					await io.stderr(`demi agent: ${errorMessage(error)}\n`);
 					return { exitCode: 1 };
 				}
-				await io.stderr(`subagentId: ${job.id}\n`);
-				const onAbort = () => {
-					this.abortSubtree(job.id).catch(noop);
-				};
-				if (signal.aborted) onAbort();
-				else signal.addEventListener("abort", onAbort, { once: true });
-				this.pumpStdinSteers(job.id, stdinStream);
-				const close = await job.closed;
-				signal.removeEventListener("abort", onAbort);
-				if (close.phase === "completed") {
-					const text = close.result ?? "";
-					if (parsed.json) await io.stdout(`${JSON.stringify({
-						subagentId: job.id,
-						text
-					})}\n`);
-					else if (text.length > 0) await io.stdout(text.endsWith("\n") ? text : `${text}\n`);
-					return { exitCode: 0 };
-				}
-				if (close.phase === "aborted") {
-					await io.stderr(`demi agent: subagent ${job.id} aborted\n`);
-					return { exitCode: 130 };
-				}
-				await io.stderr(`demi agent: subagent ${job.id} failed: ${close.failure ?? "unknown error"}\n`);
-				return { exitCode: 1 };
+				return this.attendChild(job, {
+					io,
+					isJson: parsed.json === true,
+					signal,
+					stdinStream
+				});
 			},
 			subcommands: [
 				{
@@ -2792,21 +2778,73 @@ var ChildSupervisor = class {
 						return { exitCode: 0 };
 					}
 				},
+				{
+					name: "resume",
+					summary: "Revive an archived (finished) child with a new user message on top of its preserved transcript. Behaves like the spawn command afterwards: stays running until the child ends again, stdout is its new last assistant text, shell_write steers, shell_abort aborts. Archived ids are in `demi agent list`.",
+					input: {
+						id: z.string().describe("subagentId of an archived child"),
+						message: z.string().optional().describe("The reviving user message; positional, or stdin/heredoc when omitted.")
+					},
+					positionals: ["id", "message"],
+					stdinField: "message",
+					output: { json: z.object({
+						subagentId: z.string(),
+						text: z.string()
+					}) },
+					run: async ({ parsed, io, signal, stdinStream }) => {
+						const id = String(parsed.values.id);
+						const message = String(parsed.values.message ?? "").trim();
+						if (!message) {
+							await io.stderr("demi agent resume: message must not be empty\n");
+							return { exitCode: 1 };
+						}
+						let job;
+						try {
+							job = await this.resumeArchived(id, message);
+						} catch (error) {
+							await io.stderr(`demi agent resume: ${errorMessage(error)}\n`);
+							return { exitCode: 1 };
+						}
+						return this.attendChild(job, {
+							io,
+							isJson: parsed.json === true,
+							signal,
+							stdinStream
+						});
+					}
+				},
 				{
 					name: "list",
-					summary: "Snapshot roster of this session's running children (finished children are absent). One line per child with ages relative to now. A read, not a wait — not for polling loops.",
-					output: { json: z.object({ agents: z.array(z.unknown()) }) },
+					summary: "Snapshot roster of this session's running children, then its archived (finished, revivable via resume) children. One line per child with ages relative to now. A read, not a wait — not for polling loops.",
+					output: { json: z.object({
+						agents: z.array(z.unknown()),
+						archived: z.array(z.unknown())
+					}) },
 					run: async ({ parsed, io }) => {
 						const jobs = [...this.jobs.values()];
+						const archived = await this.listArchivedJobs();
 						if (parsed.json) {
-							await io.stdout(`${JSON.stringify({ agents: jobs.map((job) => this.snapshot(job, false)) })}\n`);
-							return { exitCode: 0 };
-						}
-						if (jobs.length === 0) {
-							await io.stdout("no running subagents\n");
+							await io.stdout(`${JSON.stringify({
+								agents: jobs.map((job) => this.snapshot(job, false)),
+								archived: archived.map(({ id, meta }) => ({
+									subagentId: id,
+									description: meta.description,
+									profile: meta.profileName,
+									phase: meta.closedPhase,
+									closedAgoMs: meta.closedAt === void 0 ? null : Date.now() - meta.closedAt
+								}))
+							})}\n`);
 							return { exitCode: 0 };
 						}
+						if (jobs.length === 0) await io.stdout("no running subagents\n");
 						for (const job of jobs) await io.stdout(`${this.renderListLine(job)}\n`);
+						if (archived.length > 0) {
+							await io.stdout("archived (revivable with `demi agent resume <id>`):\n");
+							for (const { id, meta } of archived) {
+								const closedAgo = meta.closedAt === void 0 ? "" : `  closed ${formatDuration(Date.now() - meta.closedAt)} ago`;
+								await io.stdout(`  ${id}  ${meta.closedPhase}${closedAgo}  ${meta.description ? `"${meta.description}"` : "(no description)"}\n`);
+							}
+						}
 						return { exitCode: 0 };
 					}
 				},
@@ -2860,9 +2898,129 @@ var ChildSupervisor = class {
 			});
 		}
 	}
+	/**
+	* Detaches every live child on connection teardown: aborts in-flight turns,
+	* flushes checkpoints, and keeps the persisted job so the next open of this
+	* parent restores it — the same dispose semantics as the parent session.
+	* No `closed` frame is emitted: the children are not done, just paused.
+	*/
 	async dispose() {
 		this.isDisposed = true;
-		for (const job of [...this.jobs.values()]) await this.closeJob(job, "aborted");
+		for (const job of [...this.jobs.values()]) {
+			job.isClosing = true;
+			job.unsubscribe();
+			this.jobs.delete(job.id);
+			await job.session.dispose().catch(noop);
+			await this.disposeJobShells(job);
+			job.settleClosed({ phase: "aborted" });
+		}
+	}
+	/**
+	* Rebuilds every persisted live child of this parent and finishes what it was
+	* doing: an interrupted turn resumes from its resume point; an already
+	* quiescent child closes with its result. Children share the parent's
+	* persistence lifecycle — a parent restore is a child restore.
+	*/
+	async restore() {
+		const parent = this.parentSession;
+		if (!parent || this.isDisposed) return;
+		const prefix = `agent-sessions/${parent.id()}/subagents/`;
+		const keys = await this.options.store.list(prefix).catch(() => []);
+		const ids = [...new Set(keys.map((key) => key.slice(prefix.length).split("/")[0] ?? "").filter(Boolean))];
+		for (const id of ids) {
+			if (this.jobs.has(id)) continue;
+			try {
+				await this.restoreJob(id);
+			} catch {
+				await this.deletePersistedJob(id);
+			}
+		}
+	}
+	async restoreJob(id) {
+		if (!this.parentSession) return;
+		const meta = await this.options.store.readJson(this.childStoreKey(id, "job.json"));
+		if (meta?.closedPhase) return;
+		const checkpoint = await this.childSessionStore(id).loadCheckpoint();
+		if (!meta || !checkpoint) throw new Error("incomplete persisted subagent");
+		const job = this.reassembleJob(id, meta, checkpoint);
+		this.watchTurn(job, job.session.resume(meta.metadata ? { metadata: meta.metadata } : {}));
+	}
+	/** Shared by restore and resume: rebuild a persisted child's job and session from its checkpoint. */
+	reassembleJob(id, meta, checkpoint) {
+		const parent = this.parentSession;
+		if (!parent) throw new Error("subagent supervisor has no parent session");
+		const profile = this.resolveProfile(meta.profileName ?? void 0);
+		const { job, runtime } = this.assembleJob({
+			id,
+			description: meta.description,
+			profileName: meta.profileName,
+			profile,
+			metadata: meta.metadata,
+			spawnedAt: meta.spawnedAt
+		});
+		const session = AgentSession.fromCheckpoint({
+			provider: parent.cloneProviderRuntime(),
+			runtime,
+			checkpoint
+		}, {
+			agentSessionId: id,
+			store: this.childSessionStore(id),
+			...this.options.sessionOptions
+		});
+		this.attachSession(job, session);
+		return job;
+	}
+	/**
+	* Revives an archived child: its job record turns live again (this round's
+	* metadata, a fresh spawnedAt), the session rebuilds from the preserved
+	* checkpoint, and the message opens its next turn on top of the old
+	* transcript.
+	*/
+	async resumeArchived(id, message) {
+		const parent = this.parentSession;
+		if (!parent) throw new Error("subagent supervisor has no parent session");
+		if (this.isDisposed) throw new Error("parent session is closing");
+		if (this.jobs.has(id)) throw new Error(`subagent "${id}" is still running; steer it instead`);
+		if (this.jobs.size >= 8) throw new Error(`at most 8 running subagents per session; abort one or wait for a result`);
+		const meta = await this.options.store.readJson(this.childStoreKey(id, "job.json"));
+		if (!meta?.closedPhase) throw new Error(`no archived subagent "${id}" (see \`demi agent list\`)`);
+		const checkpoint = await this.childSessionStore(id).loadCheckpoint();
+		if (!checkpoint) throw new Error(`archived subagent "${id}" has no checkpoint left`);
+		const liveMeta = {
+			description: meta.description,
+			profileName: meta.profileName,
+			metadata: parent.actionMetadata(),
+			spawnedAt: Date.now()
+		};
+		await this.options.store.writeJson(this.childStoreKey(id, "job.json"), liveMeta);
+		const job = this.reassembleJob(id, liveMeta, checkpoint);
+		this.watchTurn(job, job.session.send([{
+			type: "text",
+			text: message
+		}], liveMeta.metadata ? { metadata: liveMeta.metadata } : {}));
+		return job;
+	}
+	/** Every archived (finished, revivable) child of this parent, newest first. */
+	async listArchivedJobs() {
+		const parent = this.parentSession;
+		if (!parent) return [];
+		const prefix = `agent-sessions/${parent.id()}/subagents/`;
+		const keys = await this.options.store.list(prefix).catch(() => []);
+		const ids = [...new Set(keys.map((key) => key.slice(prefix.length).split("/")[0] ?? "").filter(Boolean))];
+		const archived = [];
+		for (const id of ids) {
+			if (this.jobs.has(id)) continue;
+			const meta = await this.options.store.readJson(this.childStoreKey(id, "job.json"));
+			if (meta?.closedPhase) archived.push({
+				id,
+				meta
+			});
+		}
+		return archived.sort((a, b) => (b.meta.closedAt ?? 0) - (a.meta.closedAt ?? 0));
+	}
+	async pruneArchive() {
+		const archived = await this.listArchivedJobs();
+		for (const stale of archived.slice(16)) await this.deletePersistedJob(stale.id);
 	}
 	async abortSubtree(id) {
 		const job = this.jobs.get(id);
@@ -2877,6 +3035,40 @@ var ChildSupervisor = class {
 		const profile = this.resolveProfile(input.profileName);
 		const id = createId();
 		const metadata = parent.actionMetadata();
+		const profileName = input.profileName ?? (this.options.profiles ? profile.name : null);
+		const spawnedAt = Date.now();
+		const { job, runtime } = this.assembleJob({
+			id,
+			description: input.description,
+			profileName,
+			profile,
+			metadata,
+			spawnedAt
+		});
+		await this.options.store.writeJson(this.childStoreKey(id, "job.json"), {
+			description: input.description,
+			profileName,
+			metadata,
+			spawnedAt
+		});
+		const session = new AgentSession({
+			provider: parent.cloneProviderRuntime(),
+			model: profile.model ?? structuredClone(parent.modelSelection),
+			cwd: this.options.cwd,
+			runtime,
+			state: this.options.agent.initialState()
+		}, {
+			agentSessionId: id,
+			store: this.childSessionStore(id),
+			...this.options.sessionOptions
+		});
+		this.attachSession(job, session);
+		this.watchChild(job, input.prompt);
+		return job;
+	}
+	/** Everything spawn and restore share: the command tree, the harness runtime, and the job record (session attached separately). */
+	assembleJob(input) {
+		const { id, profile } = input;
 		const agentNode = this.createChildAgentNode(id, input.description);
 		const commands = injectSubagentCommand(profile.commands ? profile.commands([...this.options.parentCommands]) : [...this.options.parentCommands], agentNode);
 		const commandRegistry = new CommandRegistry();
@@ -2891,15 +3083,15 @@ var ChildSupervisor = class {
 			id,
 			description: input.description,
 			profile,
-			profileName: input.profileName ?? (this.options.profiles ? profile.name : null),
-			metadata,
+			profileName: input.profileName,
+			metadata: input.metadata,
 			session: null,
 			commandRegistry,
 			commandNames,
 			environments: /* @__PURE__ */ new Map(),
 			pendingEnvironments: /* @__PURE__ */ new Map(),
 			readonlyHosts: /* @__PURE__ */ new WeakMap(),
-			spawnedAt: Date.now(),
+			spawnedAt: input.spawnedAt,
 			lastEventAt: Date.now(),
 			tools: [],
 			lastAssistantTextAt: null,
@@ -2912,56 +3104,92 @@ var ChildSupervisor = class {
 		};
 		const agent = this.options.agent;
 		const preamble = this.subagentPreamble(id);
-		const runtime = {
-			harnessName: agent.name,
-			initialState: () => agent.initialState(),
-			systemPrompt: (ctx) => (profile.systemPrompt ?? agent.systemPrompt).call(agent, {
-				...ctx,
-				commandsPrompt
-			}),
-			preamble: async (ctx) => {
-				const inheritedPreamble = profile.systemPrompt ? null : await agent.preamble?.(ctx) ?? null;
-				return inheritedPreamble ? `${inheritedPreamble}\n\n${preamble}` : preamble;
-			},
-			tools: () => createStandardAgentTools({
-				environment: (ctx) => this.childEnvironment(job, ctx),
-				scheduleYield: (ctx, durationMs) => job.session.scheduleYieldWakeup(durationMs, ctx.metadata)
-			})
+		return {
+			job,
+			runtime: {
+				harnessName: agent.name,
+				initialState: () => agent.initialState(),
+				systemPrompt: (ctx) => (profile.systemPrompt ?? agent.systemPrompt).call(agent, {
+					...ctx,
+					commandsPrompt
+				}),
+				preamble: async (ctx) => {
+					const inheritedPreamble = profile.systemPrompt ? null : await agent.preamble?.(ctx) ?? null;
+					return inheritedPreamble ? `${inheritedPreamble}\n\n${preamble}` : preamble;
+				},
+				tools: () => createStandardAgentTools({
+					environment: (ctx) => this.childEnvironment(job, ctx),
+					scheduleYield: (ctx, durationMs) => job.session.scheduleYieldWakeup(durationMs, ctx.metadata)
+				})
+			}
 		};
-		job.session = new AgentSession({
-			provider: parent.cloneProviderRuntime(),
-			model: profile.model ?? structuredClone(parent.modelSelection),
-			cwd: this.options.cwd,
-			runtime,
-			state: agent.initialState()
-		}, {
-			agentSessionId: id,
-			...this.options.sessionOptions
-		});
-		job.unsubscribe = job.session.subscribe((event) => {
+	}
+	attachSession(job, session) {
+		job.session = session;
+		job.unsubscribe = session.subscribe((event) => {
 			if (event.type !== "transcript_changed") return;
 			this.recordTelemetry(job, event.patches);
 			this.options.emit({
 				type: "subagent_transcript_patch",
-				subagentId: id,
+				subagentId: job.id,
 				patches: event.patches,
 				revision: event.revision
 			});
 		});
-		this.jobs.set(id, job);
+		this.jobs.set(job.id, job);
 		this.options.emit({
 			type: "subagent",
 			event: "started",
 			job: this.wireJob(job)
 		});
+		const transcript = session.transcript();
 		this.options.emit({
 			type: "subagent_transcript_reset",
-			subagentId: id,
-			blocks: [],
-			revision: 0
+			subagentId: job.id,
+			blocks: structuredClone(transcript.blocks),
+			revision: transcript.revision
 		});
-		this.watchChild(job, input.prompt);
-		return job;
+	}
+	childStoreKey(childId, file) {
+		return `agent-sessions/${this.parentSession?.id() ?? ""}/subagents/${childId}/${file}`;
+	}
+	childSessionStore(childId) {
+		return {
+			saveCheckpoint: (checkpoint) => this.options.store.writeJson(this.childStoreKey(childId, "checkpoint.json"), checkpoint),
+			loadCheckpoint: () => this.options.store.readJson(this.childStoreKey(childId, "checkpoint.json"))
+		};
+	}
+	async deletePersistedJob(id) {
+		await this.options.store.delete(this.childStoreKey(id, "checkpoint.json")).catch(noop);
+		await this.options.store.delete(this.childStoreKey(id, "job.json")).catch(noop);
+	}
+	/** Shared spawn/resume foreground behaviour: announce the id, wire abort and stdin steers, wait for close, report the outcome. */
+	async attendChild(job, ctx) {
+		const { io, isJson, signal, stdinStream } = ctx;
+		await io.stderr(`subagentId: ${job.id}\n`);
+		const onAbort = () => {
+			this.abortSubtree(job.id).catch(noop);
+		};
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+		this.pumpStdinSteers(job.id, stdinStream);
+		const close = await job.closed;
+		signal.removeEventListener("abort", onAbort);
+		if (close.phase === "completed") {
+			const text = close.result ?? "";
+			if (isJson) await io.stdout(`${JSON.stringify({
+				subagentId: job.id,
+				text
+			})}\n`);
+			else if (text.length > 0) await io.stdout(text.endsWith("\n") ? text : `${text}\n`);
+			return { exitCode: 0 };
+		}
+		if (close.phase === "aborted") {
+			await io.stderr(`demi agent: subagent ${job.id} aborted\n`);
+			return { exitCode: 130 };
+		}
+		await io.stderr(`demi agent: subagent ${job.id} failed: ${close.failure ?? "unknown error"}\n`);
+		return { exitCode: 1 };
 	}
 	/** Delivers one steer to a child: mid-turn as a steer, idle as a new user turn. */
 	async steerChild(job, message) {
@@ -3028,12 +3256,16 @@ var ChildSupervisor = class {
 		this.jobs.delete(job.id);
 		const result = phase === "completed" ? boundedResultText(lastAssistantText(job.session.transcript().blocks)) : void 0;
 		await job.session.dispose().catch(noop);
-		const environments = /* @__PURE__ */ new Set([...job.environments.values()]);
-		for (const pending of job.pendingEnvironments.values()) {
-			const environment = await pending.catch(() => null);
-			if (environment) environments.add(environment);
-		}
-		for (const environment of environments) await environment.disposeAllShells().catch(noop);
+		await this.disposeJobShells(job);
+		await this.options.store.writeJson(this.childStoreKey(job.id, "job.json"), {
+			description: job.description,
+			profileName: job.profileName,
+			metadata: job.metadata,
+			spawnedAt: job.spawnedAt,
+			closedPhase: phase,
+			closedAt: Date.now()
+		}).catch(noop);
+		await this.pruneArchive().catch(noop);
 		const close = {
 			phase,
 			...result !== void 0 ? { result } : {},
@@ -3047,6 +3279,14 @@ var ChildSupervisor = class {
 		job.settleClosed(close);
 		this.notifyIdleParent(job, close);
 	}
+	async disposeJobShells(job) {
+		const environments = /* @__PURE__ */ new Set([...job.environments.values()]);
+		for (const pending of job.pendingEnvironments.values()) {
+			const environment = await pending.catch(() => null);
+			if (environment) environments.add(environment);
+		}
+		for (const environment of environments) await environment.disposeAllShells().catch(noop);
+	}
 	/** Wakes an idle parent with a user send; a parent blocked in the spawn gets the tool result instead. */
 	notifyIdleParent(job, close) {
 		if (this.isDisposed || !this.options.notifyParentOnIdle) return;
@@ -3308,6 +3548,7 @@ var ChildSupervisor = class {
 			description: job.description,
 			profile: job.profileName,
 			phase: job.phase,
+			metadata: job.metadata,
 			...result !== void 0 ? { result } : {}
 		};
 	}
@@ -3738,10 +3979,11 @@ var AgentTransportBindingImpl = class {
 		await this.sessions.claim(agentSessionId, this);
 		this.currentSessionId = agentSessionId;
 		const initialState = agent.initialState();
-		const store = new HostAgentSessionStore((await agent.host({
+		const provisionalHost = await agent.host({
 			state: initialState,
 			cwd: frame.cwd
-		})).store, agentSessionId);
+		});
+		const store = new HostAgentSessionStore(provisionalHost.store, agentSessionId);
 		const checkpoint = await store.loadCheckpoint();
 		const restoring = checkpoint !== null && checkpoint.harnessName === agent.name;
 		const state = restoring ? structuredClone(checkpoint.state) : initialState;
@@ -3760,6 +4002,7 @@ var AgentTransportBindingImpl = class {
 			prepareShell: this.prepareShell,
 			sessionOptions: this.sessionOptions,
 			notifyParentOnIdle: this.notifyParentOnIdle,
+			store: provisionalHost.store,
 			emit: (subagentFrame) => this.send(subagentFrame)
 		});
 		const commands = injectSubagentCommand(harnessCommands, supervisor.rootCommandNode());
@@ -3830,6 +4073,7 @@ var AgentTransportBindingImpl = class {
 			type: "queue",
 			queue: this.session.queuedMessages()
 		});
+		if (restoring) await supervisor.restore();
 	}
 	sendTranscriptReset(session) {
 		const transcript = session.transcript();
@@ -4247,4 +4491,4 @@ function createProviderMap(providers) {
 	return map;
 }
 //#endregion
-export { AgentClient, AgentServer, AgentSession, ChildSupervisor, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, MAX_LIVE_SUBAGENTS, ProviderStreamError, RunCommandLineCommandNotRegisteredError, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, SUBAGENT_RESULT_MAX_BYTES, TranscriptLog, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createReadonlyHost, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, injectSubagentCommand, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AgentClient, AgentServer, AgentSession, ChildSupervisor, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, MAX_ARCHIVED_SUBAGENTS, MAX_LIVE_SUBAGENTS, ProviderStreamError, RunCommandLineCommandNotRegisteredError, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, SUBAGENT_RESULT_MAX_BYTES, TranscriptLog, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createReadonlyHost, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, injectSubagentCommand, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/stdio-transport.d.mts

@@ -1,4 +1,4 @@
-import { n as AgentServerTransport, t as AgentClientTransport } from "./transport-BRqZoaeo.mjs";
+import { n as AgentServerTransport, t as AgentClientTransport } from "./transport-CHrPzcrU.mjs";
 import { Readable, Writable } from "node:stream";
 //#region src/stdio-transport.d.ts
 declare function createStdioClientTransport(readable: Readable, writable: Writable): AgentClientTransport;

package/dist/{transport-BRqZoaeo.d.mts → transport-CHrPzcrU.d.mts}

@@ -398,6 +398,8 @@ interface SubagentJob {
   description: string;
   profile: string | null;
   phase: 'running' | 'completed' | 'aborted' | 'error';
+  /** Action metadata of the round that spawned the child. */
+  metadata: AgentMetadata | null;
   /** Present on `closed`: the child's last assistant text, at most 32 KiB. */
   result?: string;
 }

package/dist/{websocket-transport-C6Y5CeLG.d.mts → websocket-transport-NZ5Btmb4.d.mts}

@@ -1,4 +1,4 @@
-import { I as ModelSwitchApply, c as ConversationSummary, n as AgentServerTransport, p as AbortResult, s as ClientSessionEvent, t as AgentClientTransport, x as AgentMetadata } from "./transport-BRqZoaeo.mjs";
+import { I as ModelSwitchApply, c as ConversationSummary, n as AgentServerTransport, p as AbortResult, s as ClientSessionEvent, t as AgentClientTransport, x as AgentMetadata } from "./transport-CHrPzcrU.mjs";
 import { ProviderSelection } from "@demicodes/provider";
 import { Block, UserContentBlock } from "@demicodes/core";
 //#region src/client.d.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/agent",
   "description": "Session runtime and transport-neutral client and server protocol for Demi.",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "private": false,
   "type": "module",
   "exports": {
@@ -19,10 +19,10 @@
     }
   },
   "dependencies": {
-    "@demicodes/core": "^0.19.1",
-    "@demicodes/provider": "^0.19.1",
-    "@demicodes/shell": "^0.19.1",
-    "@demicodes/utils": "^0.19.1",
+    "@demicodes/core": "^0.19.3",
+    "@demicodes/provider": "^0.19.3",
+    "@demicodes/shell": "^0.19.3",
+    "@demicodes/utils": "^0.19.3",
     "zod": "^4.0.0"
   },
   "license": "Apache-2.0",