dsh-pause-session 0.2.0 → 0.2.1

package/lib/index.js

@@ -1,8 +1,9 @@
 import { z } from "zod";
 import { SessionId, deriveEventMessage, foldRequestHeader, foldSurface, interruptedTurnClosers } from "@deepseek-ai/dsh-session";
+import { randomUUID } from "node:crypto";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { applyChildComposition, foldSubagentDescriptor } from "@deepseek-ai/dsh-subagent";
-import { Remote, RemoteError, TypertRemoteService, principalOf } from "@deepseek-ai/dsh-typert-protocol";
+import { Remote, RemoteError, TypertRemoteService, principalOf, remoteErrorOf } from "@deepseek-ai/dsh-typert-protocol";
+import { foldSubagentDescriptor } from "@deepseek-ai/dsh-subagent";
 import { DomainError, defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 //#region lib/types/history.js
 /**
@@ -730,7 +731,13 @@ function mountGlobalPause(ctx, watch, registry, deps) {
 //#endregion
 //#region lib/types/release-order.js
 /**
-* The order a tree release walks: parent before child, shallowest first.
+* The order a batch release walks: parent before child, shallowest first.
+*
+* A single tree release already has the pre-order from its own walk, so this
+* module serves the batch path, where the recorded sessions may span several
+* trees. `listDescendants` stamps each row with its distance from the listing
+* root, so one catalog read per recorded root places every member. A session
+* the walk never reached is its own root and releases with the first level.
 * @module dsh-pause-session/release-order
 */
 /**
@@ -738,100 +745,54 @@ function mountGlobalPause(ctx, watch, registry, deps) {
 * @param ctx - host context carrying the optional subagent catalog.
 * @param sessionIds - every recorded session, in registry order.
 * @param signal - cancellation for each catalog read.
-* @returns the parent of each child, and one list per depth level.
+* @returns one list per depth level, shallowest first.
 */
 async function releaseOrder(ctx, sessionIds, signal) {
-	const owned = new Set(sessionIds);
-	const parentOf = /* @__PURE__ */ new Map();
+	const depth = /* @__PURE__ */ new Map();
 	const subagents = ctx.get("subagents");
-	if (subagents !== void 0) for (const sessionId of sessionIds) {
-		signal?.throwIfAborted();
-		try {
-			for (const child of await subagents.listChildren(sessionId, signal)) if (owned.has(child.id)) parentOf.set(child.id, sessionId);
-		} catch (error) {
-			if (signal?.aborted === true) throw error;
-			ctx.logger.warn(`pause: could not read the children of "${sessionId}": ${describeError(error)}`);
+	if (subagents !== void 0) {
+		const owned = new Set(sessionIds);
+		for (const sessionId of sessionIds) {
+			signal?.throwIfAborted();
+			if (depth.has(sessionId)) continue;
+			depth.set(sessionId, 0);
+			try {
+				for (const row of await subagents.listDescendants(sessionId, signal)) {
+					if (row.kind !== "child" || !owned.has(row.id)) continue;
+					depth.set(row.id, row.depth);
+				}
+			} catch (error) {
+				if (signal?.aborted === true) throw error;
+				ctx.logger.warn(`pause: could not read the descendants of "${sessionId}": ${describeError(error)}`);
+			}
 		}
 	}
-	const depthOf = (sessionId) => {
-		let steps = 0;
-		const seen = /* @__PURE__ */ new Set([sessionId]);
-		for (let at = parentOf.get(sessionId); at !== void 0; at = parentOf.get(at)) {
-			if (seen.has(at)) break;
-			seen.add(at);
-			steps += 1;
-		}
-		return steps;
-	};
 	const levels = /* @__PURE__ */ new Map();
 	for (const sessionId of sessionIds) {
-		const level = depthOf(sessionId);
+		const level = depth.get(sessionId) ?? 0;
 		const bucket = levels.get(level);
 		if (bucket === void 0) levels.set(level, [sessionId]);
 		else bucket.push(sessionId);
 	}
-	return {
-		parents: parentOf,
-		levels: [...levels.keys()].sort((left, right) => left - right).map((level) => levels.get(level) ?? [])
-	};
+	return { levels: [...levels.keys()].sort((left, right) => left - right).map((level) => levels.get(level) ?? []) };
 }
 //#endregion
 //#region lib/types/composition.js
 /**
-* Rebuild the scoped Agent composition a parked Session ran under.
-*
-* Activation is not only a persisted Session: the Agent preset supplies the
-* scoped tools, prompt sections, skills, and — for a subagent child — the
-* delegation context, persona, and tool restriction that were in force before
-* the park. A resume that loads the log without that setup starts a different
-* Agent on the same history.
+* What a parked Session needs to come back as itself.
 *
-* The preset a Session runs is the `agentPreset` projection, never the
-* creation-time header alone: a blank Session may select another preset before
-* its first turn, and the projection records the selection that actually ran.
-* A child with no independent selection joins its live parent's preset
-* generation; one that selected independently mounts the projected preset.
-* The durable child descriptor supplies the persona, tool filter, and route
-* that are reapplied only on cold resume.
+* A root Session is loaded directly: the Agent preset it ran supplies the
+* scoped tools, prompt sections, and skills, so the resume mounts that preset
+* before the Agent is published. A subagent child is not loaded here at all —
+* the subagent runtime owns its activation, composition, and tree membership,
+* and cold-resumes it when this plugin delivers the wake through
+* `ctx.subagents.prompt`.
 *
-* Both services are optional. A profile without `agentPresets` has no scoped
-* preset composition to restore, and this module leaves the resume unchanged.
-* A profile that mounts one but cannot read the Session projection cannot
-* prove what composition the Session ran, so it fails the resume instead of
-* silently starting a different Agent.
+* The two cases are told apart by one read of the Session's own log, which is
+* the same read the press-time resumability check already pays for.
 * @module dsh-pause-session/composition
 */
 /**
-* A stored subagent route that no resume may reactivate.
-*
-* A one-shot child is terminal by contract; activating it as a root Agent
-* would turn a finished delegation into an ordinary conversation that happens
-* to share its Session id.
-*/
-var UnresumableSessionError = class extends Error {
-	constructor(sessionId) {
-		super(`subagent session "${String(sessionId)}" has a one-shot route and cannot be resumed`);
-		this.name = "UnresumableSessionError";
-	}
-};
-/**
-* Whether the child's own log selected a preset before its descriptor.
-*
-* The creation-time selection precedes the first `subagent/descriptor`; a
-* selection after the descriptor belongs to the child's own later history and
-* does not decide which composition cold resume joins. This mirrors the
-* subagent runtime's own cold-resume rule.
-* @param events - the child's own log suffix, without the fork-inherited prefix.
-* @returns whether the child carries an independent preset selection.
-*/
-function hasIndependentPresetSelection(events) {
-	for (const event of events) {
-		if (event.type === "subagent/descriptor") return false;
-		if (event.type === "agent-preset/selected") return true;
-	}
-	return false;
-}
-/**
 * Whether a local Session may be parked under a promise of a later resume.
 *
 * A normal root Session has no child descriptor and is resumable. A local
@@ -860,64 +821,40 @@ async function isResumableSession(ctx, sessionId, signal) {
 	}
 }
 /**
-* Read one parked Session's stored composition and build the resume options.
+* Read one parked Session's own log and decide how it comes back.
 *
-* The returned `setup` belongs to the unpublished Agent scope, so all
-* registrations exist before `agent/created`. For a root Session the setup
-* mounts the Session's projected preset, or the profile's default when the
-* Session never selected one. For a child under a live parent it applies the
-* child composition: an independent preset mounts separately, while an
-* inherited composition joins the parent's current generation; the historical
-* descriptor's persona and tool filter are reapplied in both cases.
+* A child returns as `child` with no setup: the subagent runtime restores the
+* composition from the descriptor and the preset projection, and mounting a
+* second one here would start a different Agent on the same history.
+*
+* A root resolves the preset it ran — the projection, never the creation-time
+* header alone, because a blank Session may select another preset before its
+* first turn — and hands back the setup that mounts it. A profile with no
+* preset roster has no scoped composition to restore and resumes unchanged.
 * @param ctx - host context carrying the optional preset and Session-query services.
 * @param sessionId - the parked Session being resumed.
-* @param parent - the live direct parent, when a child is resumed under it.
 * @param signal - cancellation for the observation read.
-* @returns the Agent options and setup to pass to `agents.resume`.
-* @throws {UnresumableSessionError} when the stored child route is one-shot.
-* @throws when a mounted preset roster cannot read the Session projection, or
-* a recorded preset cannot be restored.
+* @returns how this Session comes back.
+* @throws when a mounted preset roster cannot read the Session projection.
 */
-async function restoreComposition(ctx, sessionId, parent, signal) {
+async function readParkedComposition(ctx, sessionId, signal) {
 	const presets = ctx.get("agentPresets");
 	const query = ctx.get("sessionQuery");
 	if (query === void 0) {
 		if (presets !== void 0) throw new Error("resuming a composed Agent requires the session-query service");
-		return {};
+		return { kind: "root" };
 	}
 	const observation = await query.observeSession(sessionId, { ...signal === void 0 ? {} : { signal } });
 	try {
+		if (foldSubagentDescriptor(observation.events.slice(observation.inheritedEventCount)) !== void 0 || observation.header.origin === "subagent") return { kind: "child" };
+		if (presets === void 0) return { kind: "root" };
 		const projections = observation.projections;
-		const ownEvents = observation.events.slice(observation.inheritedEventCount);
-		const descriptor = foldSubagentDescriptor(ownEvents);
-		if (descriptor?.mode === "one-shot") throw new UnresumableSessionError(sessionId);
-		if (presets === void 0 || projections === void 0) {
-			if (presets !== void 0) throw new Error("resuming a composed Agent requires projected Session state");
-			return {};
-		}
-		if (parent === void 0) {
-			const resolved = await presets.resolve(projections.values.agentPreset ?? void 0);
-			return { setup: async (agentCtx) => {
-				await presets.mount(agentCtx, resolved.id);
-			} };
-		}
-		const independentlySelected = hasIndependentPresetSelection(ownEvents);
-		const presetId = independentlySelected ? projections.values.agentPreset : void 0;
-		if (independentlySelected && typeof presetId !== "string") throw new Error(`subagent "${String(sessionId)}" has no projected agent preset to restore`);
-		const composition = {
-			...typeof presetId === "string" ? { agentPreset: presetId } : {},
-			...descriptor?.mode === "continuable" && descriptor.persona !== void 0 ? { persona: descriptor.persona } : {},
-			...descriptor?.mode === "continuable" && descriptor.toolFilter !== void 0 ? { toolFilter: descriptor.toolFilter } : {}
-		};
-		const agentOptions = descriptor?.mode === "continuable" ? {
-			...descriptor.agentProvider === void 0 ? {} : { provider: descriptor.agentProvider },
-			...descriptor.agentModel === void 0 ? {} : { model: descriptor.agentModel },
-			...descriptor.agentReasoningEffort === void 0 ? {} : { reasoningEffort: descriptor.agentReasoningEffort }
-		} : void 0;
+		if (projections === void 0) throw new Error("resuming a composed Agent requires projected Session state");
+		const resolved = await presets.resolve(projections.values.agentPreset ?? void 0);
 		return {
-			...agentOptions === void 0 ? {} : { agentOptions },
+			kind: "root",
 			setup: async (agentCtx) => {
-				await applyChildComposition(agentCtx, parent, composition);
+				await presets.mount(agentCtx, resolved.id);
 			}
 		};
 	} finally {
@@ -965,16 +902,25 @@ function summarizeTreeRelease(released) {
 //#endregion
 //#region lib/types/resume-activation.js
 /**
-* Reactivate one parked session: restore its composition, give it the route its
-* log recorded, deliver the wake it owes, and only then drop the gate and record.
+* Reactivate one parked Session and deliver the wake it owes.
+*
+* The two Session kinds come back through different owners. An ordinary
+* Session is loaded by this plugin and given the route its own log recorded.
+* A subagent child belongs to the subagent runtime: delivering the wake through
+* `ctx.subagents.prompt` is what cold-resumes it as a managed activation, under
+* its live tree root, with its persisted composition and tree membership
+* restored by the runtime itself.
+*
+* Both paths keep the same release order: the durable record goes first, then
+* the gate, so a record that cannot be dropped leaves the Session parked.
 * @module dsh-pause-session/resume-activation
 */
 /**
 * Build the activation closure.
-* @param ctx - host context carrying the agent store and goal service.
+* @param ctx - host context carrying the agent store, subagent runtime, and goal service.
 * @param gate - the pause gate released after activation.
 * @param registry - the durable list the release forgets from.
-* @param options - the route knowledge the wake content depends on.
+* @param options - the route knowledge the root wake content depends on.
 * @returns the activation methods the resume path uses.
 */
 function createActivator(ctx, gate, registry, options) {
@@ -1023,27 +969,29 @@ function createActivator(ctx, gate, registry, options) {
 			ctx.logger.warn(`pause: could not re-open the goal of "${agent.id}": ${describeError(error)}`);
 		}
 	};
-	const activate = async (sessionId, request, rearm, parentId, signal) => {
-		const parent = parentId === void 0 ? void 0 : ctx.agents.get(parentId);
+	/** Drop the durable record, then the gate: the order every release keeps. */
+	const releaseRecord = async (sessionId) => {
+		try {
+			await registry.forget(sessionId);
+		} catch (error) {
+			ctx.logger.warn(`pause: could not drop "${sessionId}" from the pause registry: ${describeError(error)}`);
+			return {
+				kind: "error",
+				text: UNRECORDED_TEXT
+			};
+		}
+		gate.resume(sessionId);
+	};
+	/** Load an ordinary Session, give it its recorded route, and deliver the wake. */
+	const activateRoot = async (sessionId, request, rearm, composition, signal) => {
 		let agent;
 		try {
-			const composition = await restoreComposition(ctx, sessionId, parent, signal);
 			agent = (await ctx.root.agents.resume({
 				resumeSessionId: sessionId,
-				...parent === void 0 ? {} : { parentAgent: parent },
-				...composition,
+				...composition.setup === void 0 ? {} : { setup: composition.setup },
 				...signal === void 0 ? {} : { signal }
 			})).agent;
 		} catch (error) {
-			if (error instanceof UnresumableSessionError) return {
-				sessionId,
-				resumed: false,
-				refusal: "unresumable",
-				answer: {
-					kind: "error",
-					text: UNRESUMABLE_TEXT
-				}
-			};
 			ctx.logger.warn(`pause: could not open "${sessionId}" from its stored log: ${describeError(error)}`);
 			return {
 				sessionId,
@@ -1057,22 +1005,78 @@ function createActivator(ctx, gate, registry, options) {
 		}
 		ensureRoute(agent);
 		wake(agent, request);
+		const refused = await releaseRecord(sessionId);
+		if (refused !== void 0) return {
+			sessionId,
+			resumed: false,
+			refusal: "unrecorded",
+			answer: refused
+		};
+		if (rearm) rearmGoal(agent);
+		return {
+			sessionId,
+			resumed: true,
+			answer: {
+				kind: "success",
+				text: RESUMED_TEXT
+			}
+		};
+	};
+	/**
+	* Hand a subagent child the wake through the subagent runtime.
+	*
+	* The runtime owns the activation, so it is also the only thing that can
+	* cold-resume the child under its live tree root. An empty message would be
+	* dropped by a route whose conversion discards it, and the route is unknown
+	* before the child is live, so the marker is the content that always wakes it.
+	*/
+	const activateChild = async (sessionId, request, rearm, signal) => {
+		const subagents = ctx.get("subagents");
+		if (subagents === void 0) {
+			ctx.logger.warn(`pause: subagent runtime is not mounted; opening "${sessionId}" as a root Session`);
+			return await activateRoot(sessionId, request, rearm, { kind: "root" }, signal);
+		}
+		const content = [{
+			type: "text",
+			text: request.kind === "message" ? request.text : WAKE_MARKER
+		}];
 		try {
-			await registry.forget(sessionId);
+			await subagents.prompt({
+				requestId: randomUUID(),
+				childSessionId: sessionId,
+				delivery: "queue",
+				content
+			}, signal ?? new AbortController().signal);
 		} catch (error) {
-			ctx.logger.warn(`pause: could not drop "${sessionId}" from the pause registry: ${describeError(error)}`);
+			if (remoteErrorOf(error)?.code === "subagent/not-resumable") return {
+				sessionId,
+				resumed: false,
+				refusal: "unresumable",
+				answer: {
+					kind: "error",
+					text: UNRESUMABLE_TEXT
+				}
+			};
+			ctx.logger.warn(`pause: could not continue subagent "${sessionId}": ${describeError(error)}`);
 			return {
 				sessionId,
 				resumed: false,
-				refusal: "unrecorded",
+				refusal: "activation-failed",
 				answer: {
 					kind: "error",
-					text: UNRECORDED_TEXT
+					text: ACTIVATION_FAILED_TEXT
 				}
 			};
 		}
-		gate.resume(sessionId);
-		if (rearm) rearmGoal(agent);
+		const refused = await releaseRecord(sessionId);
+		if (refused !== void 0) return {
+			sessionId,
+			resumed: false,
+			refusal: "unrecorded",
+			answer: refused
+		};
+		const agent = ctx.agents.get(sessionId);
+		if (rearm && agent !== void 0) rearmGoal(agent);
 		return {
 			sessionId,
 			resumed: true,
@@ -1082,6 +1086,24 @@ function createActivator(ctx, gate, registry, options) {
 			}
 		};
 	};
+	const activate = async (sessionId, request, rearm, signal) => {
+		let composition;
+		try {
+			composition = await readParkedComposition(ctx, sessionId, signal);
+		} catch (error) {
+			ctx.logger.warn(`pause: could not read the composition of "${sessionId}": ${describeError(error)}`);
+			return {
+				sessionId,
+				resumed: false,
+				refusal: "activation-failed",
+				answer: {
+					kind: "error",
+					text: ACTIVATION_FAILED_TEXT
+				}
+			};
+		}
+		return composition.kind === "child" ? await activateChild(sessionId, request, rearm, signal) : await activateRoot(sessionId, request, rearm, composition, signal);
+	};
 	return {
 		activate,
 		ensureRoute,
@@ -1156,11 +1178,10 @@ function installResumePath(ctx, gate, registry, options, deps) {
 	* @param finalize - whether the decision continues the session (`'release'`)
 	* or only answers it (`'review'`); a review activates nothing and writes
 	* nothing.
-	* @param parentId - the direct parent a batch release already brought back, when there is one.
 	* @param signal - cancellation for the cold load and setup.
 	* @returns what happened, and the copy for whoever asked.
 	*/
-	const decideUnclean = async (sessionId, request, finalize, parentId, signal) => {
+	const decideUnclean = async (sessionId, request, finalize, signal) => {
 		const record = registry.get(sessionId);
 		if (record === void 0) return {
 			sessionId,
@@ -1181,7 +1202,7 @@ function installResumePath(ctx, gate, registry, options, deps) {
 			}
 		};
 		const live = ctx.agents.get(sessionId);
-		if (live === void 0) return await activate(sessionId, request, record.rearmGoal, parentId, signal);
+		if (live === void 0) return await activate(sessionId, request, record.rearmGoal, signal);
 		if (!gate.isPaused(sessionId)) {
 			ensureRoute(live);
 			wake(live, request);
@@ -1238,11 +1259,10 @@ function installResumePath(ctx, gate, registry, options, deps) {
 	* back is the press's own undo, and it delivers no wake.
 	* @param sessionId - the recorded session to resume.
 	* @param request - which wake this resume delivers; see {@link WakeRequest}.
-	* @param parentId - the direct parent a batch release already brought back, when there is one.
 	* @param signal - cancellation for the cold load and setup.
 	* @returns what happened, and the copy for whoever asked.
 	*/
-	const resumeSession = async (sessionId, request, parentId, signal) => {
+	const resumeSession = async (sessionId, request, signal) => {
 		const record = registry.get(sessionId);
 		const live = ctx.agents.get(sessionId);
 		if (live !== void 0) {
@@ -1337,18 +1357,8 @@ function installResumePath(ctx, gate, registry, options, deps) {
 				text: UNCLEAN_TEXT
 			}
 		};
-		return await activate(sessionId, request, record.rearmGoal, parentId, signal);
+		return await activate(sessionId, request, record.rearmGoal, signal);
 	};
-	/**
-	* Order the recorded sessions so a session is released after the parent it
-	* hangs from: waking a child needs its direct parent to be live first. The
-	* relation is read from the parent catalogs themselves (which children this
-	* session actually has), never guessed from ids; a branch whose catalog
-	* cannot be read simply has no known parent and is released with the roots.
-	* @param sessionIds - every recorded session, in registry order.
-	* @param signal - cancellation for each catalog read.
-	* @returns the parent of each child, and one list per depth level, shallowest first.
-	*/
 	return {
 		resumeSession,
 		decideUnclean,
@@ -1382,27 +1392,22 @@ function installResumePath(ctx, gate, registry, options, deps) {
 					answer
 				});
 			}
-			else {
-				const release = await releaseOrder(ctx, registered, signal);
-				for (const level of release.levels) {
-					signal?.throwIfAborted();
-					for (const member of level) {
-						const record = registry.get(member);
-						if (record !== void 0 && record.phase !== "safe") {
-							released.push({
-								sessionId: member,
-								resumed: false,
-								refusal: "not-clean",
-								answer: {
-									kind: "error",
-									text: UNCLEAN_TEXT
-								}
-							});
-							continue;
+			else for (const member of registered) {
+				signal?.throwIfAborted();
+				const record = registry.get(member);
+				if (record !== void 0 && record.phase !== "safe") {
+					released.push({
+						sessionId: member,
+						resumed: false,
+						refusal: "not-clean",
+						answer: {
+							kind: "error",
+							text: UNCLEAN_TEXT
 						}
-						released.push(await resumeSession(member, { kind: "silent" }, release.parents.get(member), signal));
-					}
+					});
+					continue;
 				}
+				released.push(await resumeSession(member, { kind: "silent" }, signal));
 			}
 			const root = released.find((attempt) => attempt.sessionId === sessionId);
 			const refusals = released.filter((attempt) => !attempt.resumed && attempt.refusal !== void 0).map((attempt) => ({
@@ -1427,7 +1432,7 @@ function installResumePath(ctx, gate, registry, options, deps) {
 			const attempts = [];
 			for (const level of release.levels) {
 				signal?.throwIfAborted();
-				attempts.push(...await Promise.all(level.map((sessionId) => resumeSession(sessionId, { kind: "silent" }, release.parents.get(sessionId), signal))));
+				attempts.push(...await Promise.all(level.map((sessionId) => resumeSession(sessionId, { kind: "silent" }, signal))));
 			}
 			return attempts;
 		},
@@ -1617,12 +1622,12 @@ function mountTriageList(ctx, registry, resumePath, windowEvents = TRIAGE_WINDOW
 			text: TRIAGE_LEFT_TEXT
 		};
 		if (action === "goal") return await resumePath.setRearmGoal(sessionId, !record.rearmGoal);
-		if (action === "review") return (await resumePath.decideUnclean(sessionId, { kind: "none" }, "review", void 0, signal)).answer;
+		if (action === "review") return (await resumePath.decideUnclean(sessionId, { kind: "none" }, "review", signal)).answer;
 		const wake = action === "continue" ? { kind: "silent" } : {
 			kind: "message",
 			text: UNKNOWN_OUTCOME_NOTE
 		};
-		return (await resumePath.decideUnclean(sessionId, wake, "release", void 0, signal)).answer;
+		return (await resumePath.decideUnclean(sessionId, wake, "release", signal)).answer;
 	};
 	return {
 		read: async (caller, signal) => {