@demicodes/agent 0.19.2 → 0.19.3

package/dist/index.d.mts

@@ -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> {
@@ -364,7 +365,8 @@ interface ChildSupervisorOptions<State> {
  * 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 leaves nothing behind.
+ * 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;
@@ -399,6 +401,18 @@ declare class ChildSupervisor<State = unknown> {
    */
   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). */
@@ -407,6 +421,8 @@ declare class ChildSupervisor<State = unknown> {
   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;
@@ -516,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.";
@@ -2663,7 +2664,8 @@ const SPAWN_PROMPT_DESCRIPTION = "The child's first user message and only task b
 * 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 leaves nothing behind.
+* 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;
@@ -2712,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: [
 				{
@@ -2794,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 };
 					}
 				},
@@ -2901,11 +2937,18 @@ var ChildSupervisor = class {
 		}
 	}
 	async restoreJob(id) {
-		const parent = this.parentSession;
-		if (!parent) return;
+		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,
@@ -2925,7 +2968,59 @@ var ChildSupervisor = class {
 			...this.options.sessionOptions
 		});
 		this.attachSession(job, session);
-		this.watchTurn(job, session.resume(meta.metadata ? { metadata: meta.metadata } : {}));
+		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);
@@ -3068,6 +3163,34 @@ var ChildSupervisor = class {
 		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) {
 		const content = [{
@@ -3134,7 +3257,15 @@ var ChildSupervisor = class {
 		const result = phase === "completed" ? boundedResultText(lastAssistantText(job.session.transcript().blocks)) : void 0;
 		await job.session.dispose().catch(noop);
 		await this.disposeJobShells(job);
-		await this.deletePersistedJob(job.id);
+		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 } : {},
@@ -4360,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/agent",
   "description": "Session runtime and transport-neutral client and server protocol for Demi.",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "private": false,
   "type": "module",
   "exports": {
@@ -19,10 +19,10 @@
     }
   },
   "dependencies": {
-    "@demicodes/core": "^0.19.2",
-    "@demicodes/provider": "^0.19.2",
-    "@demicodes/shell": "^0.19.2",
-    "@demicodes/utils": "^0.19.2",
+    "@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",