@qlzt/dsh-subagent 0.0.0-stage → 0.2.1-alpha.3

package/lib/index.js

@@ -0,0 +1,3333 @@
+import z from "@deepseek-ai/schemastery";
+import { scopeTarget } from "@qlzt/dsh-scope";
+import { ToolArgsError, assertObjectJsonSchema, validateJsonSchemaValue } from "@qlzt/dsh-tools";
+import { canonicalClientTimeZone } from "@qlzt/dsh-util-time";
+import { Remote, RemoteError, TypertRemoteService } from "@qlzt/dsh-typert-protocol";
+import { AttachmentError } from "@qlzt/dsh-attachment";
+import { z as z$1 } from "zod";
+import { HarnessError, ReasoningEffortId, boundContextSummary, contentHasImage, createUserMessage, errorChain, joinAssistantStreamText } from "@qlzt/dsh-llm";
+import { randomUUID } from "node:crypto";
+import { foldConsumedWork } from "@qlzt/dsh-agent";
+import { isAbsolute, resolve } from "node:path";
+import { brandString } from "@qlzt/dsh-brand";
+import { SessionLogOffset, SessionSeq } from "@qlzt/dsh-session";
+import { assertNever, snapshotJsonValue } from "@qlzt/dsh-util-values";
+import { appendChunkedList, chunkedListSchema, iterateChunkedList } from "@qlzt/dsh-chunked-list";
+import { accessSync, constants, statSync } from "node:fs";
+//#region lib/types/error.js
+/**
+* Typed failures shared by subagent service and provider operations.
+*
+* @module @qlzt/dsh-subagent
+*/
+/** Typed failure for the subagent seam. */
+var SubagentError = class extends HarnessError {
+	constructor(message, code, options) {
+		super(message, code, options);
+		this.name = "SubagentError";
+	}
+};
+//#endregion
+//#region lib/types/control.js
+/**
+* Browser-facing subagent prompt and interrupt request validation plus the
+* stable prompt failure codes returned by the Remote surface.
+*
+* @module @qlzt/dsh-subagent
+*/
+const SESSION_ID_SCHEMA = z$1.string().min(1);
+const CONTROL_ID_SCHEMAS = {
+	"subagent.prompt": z$1.object({
+		parentSessionId: SESSION_ID_SCHEMA,
+		childSessionId: SESSION_ID_SCHEMA,
+		mode: z$1.literal("continuable"),
+		delivery: z$1.enum(["queue", "steer"])
+	}),
+	"subagent.interrupt": z$1.object({
+		parentSessionId: SESSION_ID_SCHEMA,
+		childSessionId: SESSION_ID_SCHEMA,
+		mode: z$1.literal("continuable")
+	})
+};
+/**
+* Apply the subagent payload checks that are stricter than generated
+* branded-string codecs.
+* @param method - method name carried in the failure message.
+* @param payload - decoded control fields to validate.
+* @throws {RemoteError} `gateway/bad-request` with the original Zod issues.
+*/
+function validateControlRequest(method, payload) {
+	const parsed = CONTROL_ID_SCHEMAS[method].safeParse(payload);
+	if (!parsed.success) throw new RemoteError("gateway/bad-request", `invalid payload for ${method}`, { issues: parsed.error.issues });
+}
+/**
+* Refuse one continuation prompt without exposing provider detail: admission
+* failures the caller can act on keep their own code, everything else is
+* internal.
+* @param error - the thrown value.
+* @param childSessionId - the addressed child.
+* @param signal - the caller's cancellation.
+* @returns Never — the refusal is thrown.
+* @throws {RemoteError} always.
+*/
+function rejectPrompt(error, childSessionId, signal) {
+	if (isCancellation(error, signal)) throw new RemoteError("gateway/cancelled", "subagent prompt was cancelled", {}, { cause: error });
+	if (error instanceof AttachmentError) throw new RemoteError("subagent/attachment-invalid", error.message, { reason: error.code }, { cause: error });
+	if (error instanceof SubagentError) switch (error.code) {
+		case "MODEL_DOES_NOT_SUPPORT_IMAGES": throw new RemoteError("subagent/attachment-invalid", error.message, { reason: error.code }, { cause: error });
+		case "NOT_RESUMABLE": throw new RemoteError("subagent/not-resumable", "subagent cannot be resumed", { childSessionId }, { cause: error });
+		case "UNAUTHORIZED": throw new RemoteError("subagent/unauthorized", "subagent does not belong to this parent", { childSessionId }, { cause: error });
+		case "DRAINING":
+		case "ACTIVATION_CLOSING":
+		case "ACTIVATION_LIMIT_REACHED":
+		case "CONTINUATION_UNAVAILABLE":
+		case "PERSISTENCE_UNAVAILABLE": throw new RemoteError("subagent/delivery-unavailable", "subagent follow-up is temporarily unavailable", { childSessionId }, { cause: error });
+		default: break;
+	}
+	throw new RemoteError("gateway/internal", "subagent prompt failed", {}, { cause: error });
+}
+function isCancellation(error, signal) {
+	return signal.aborted || error instanceof SubagentError && error.code === "CANCELLED";
+}
+//#endregion
+//#region lib/types/depth.js
+/**
+* Delegation-depth accounting: the recursion budget a parent passes to its
+* children. Kept apart from the service so composition helpers can read it
+* without importing the registry.
+*
+* @module @qlzt/dsh-subagent/depth
+*/
+/**
+* Read an agent's delegation depth, treating absence as top-level depth zero.
+* The persisted session header is authoritative and monotone: runtime
+* `AgentOptions.subagentDepth` may DEEPEN the count but can never lower it —
+* a resumed child arrives with fresh options, and counting it from zero would
+* let it delegate as if it were top-level.
+* @param agent - the agent whose header and options carry the depth.
+* @returns its non-negative safe-integer depth.
+* @throws if the runtime `AgentOptions.subagentDepth` is not a non-negative safe integer.
+*/
+function delegationDepthOf(agent) {
+	const runtime = agent.options.subagentDepth;
+	if (runtime !== void 0 && (!Number.isSafeInteger(runtime) || runtime < 0 || Object.is(runtime, -0))) throw new TypeError("agent subagentDepth must be a non-negative safe integer");
+	return Math.max(agent.session.header.delegationDepth ?? 0, runtime ?? 0);
+}
+/**
+* Reject a recursion cap that cannot represent an exact delegation depth.
+* @param maxDepth - the optional runtime value to validate.
+*/
+function assertSubagentMaxDepth(maxDepth) {
+	if (maxDepth !== void 0 && (typeof maxDepth !== "number" || !Number.isSafeInteger(maxDepth) || maxDepth < 0 || Object.is(maxDepth, -0))) throw new TypeError("subagent maxDepth must be a non-negative safe integer");
+}
+//#endregion
+//#region lib/types/types.js
+/**
+* The seam's consumer-facing contracts: request, result, and capability types
+* for {@link SubagentProvider}, plus the `subagent/start` and `subagent/end`
+* payloads that plugins and hosts observe. Internal control interfaces belong
+* with their implementation — the lifecycle observer in `./lifecycle.ts`, the
+* manager host in `./manager.ts` — so this module stays the published
+* surface rather than a bag of everything type-shaped.
+*
+* @module @qlzt/dsh-subagent/types
+*/
+/**
+* Brand a string as a {@link SubagentRunId}.
+* @param id - the raw run id.
+* @returns the same string, branded.
+*/
+function SubagentRunId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/lifecycle.js
+/**
+* Lifecycle-edge publication for managed subagent activations.
+*
+* Public event payloads live in `./types.ts`; the package-private observer
+* retains only the identity shared by each start/end pair.
+*
+* @module @qlzt/dsh-subagent/lifecycle
+*/
+/**
+* Build the contained lifecycle emitter this seam publishes every edge through.
+* Every listener is independently contained: a synchronous throw or a rejected
+* returned promise is logged without starving peer listeners, changing the run,
+* or — for provider removal, which fires from a disposer — breaking teardown.
+* @param ctx - the service's own context, owning dispatch and the logger.
+* @param carrier - resolve the scoped dispatch carrier for one delegating parent.
+* @returns the emitter both observers and the provider registry publish through.
+*/
+function createLifecycleEmitter(ctx, carrier) {
+	return (name, info, parent) => {
+		const dispatchArgs = parent === void 0 ? [name, info] : [
+			carrier(parent),
+			name,
+			info
+		];
+		for (const callback of ctx.events.dispatch("emit", dispatchArgs)) try {
+			const returned = callback(info);
+			Promise.resolve(returned).catch((error) => {
+				ctx.logger.warn(`subagent: ${name} listener rejected: ${renderThrown(error)}`);
+			});
+		} catch (error) {
+			ctx.logger.warn(`subagent: ${name} listener threw: ${renderThrown(error)}`);
+		}
+	};
+}
+/**
+* Build the observer for one local or external activation's residency epoch. Creation failure before residency emits no lifecycle edge.
+* @param emit - the contained lifecycle emitter.
+* @param provider - the provider name recorded in the durable descriptor.
+* @param childId - the durable child session id.
+* @param parent - the exact live direct parent keying scoped dispatch.
+* @returns the observer whose edges this epoch publishes.
+*/
+function createActivationObserver(emit, provider, childId, parent) {
+	const identity = {
+		runId: SubagentRunId(randomUUID()),
+		provider,
+		id: childId,
+		local: false
+	};
+	return {
+		start: (child) => {
+			identity.local = child !== void 0;
+			emit("subagent/start", identity, parent);
+		},
+		settle: ({ stopReason, output }) => {
+			emit("subagent/end", {
+				...identity,
+				stopReason,
+				...output.length === 0 ? {} : { lastAssistantMessage: output }
+			}, parent);
+		}
+	};
+}
+/**
+* Why this child's epoch ended, for the terminal lifecycle edge and the
+* manager's own parent delivery. The child's own log is authoritative:
+* teardown succeeding says nothing about whether the model errored, hit its
+* token ceiling, or was cancelled, so deriving the reason from disposal would
+* report failed work as completed.
+*
+* {@link foldConsumedWork} supplies both halves the raw turn sequence cannot:
+* which turn accounts for the work this epoch consumed, and whether accepted
+* work was cancelled after it without any turn opening over it. A recorded
+* failure still wins over a cancellation — stopping a child that had already
+* failed does not turn its failure into a cancellation.
+* @param events - this epoch's own event suffix.
+* @returns its terminal stop reason; `completed` only for an epoch that both
+*   closed cleanly and had nothing left to run.
+*/
+function epochStopReason(events) {
+	const { end, droppedUnrun } = foldConsumedWork(events);
+	switch (end?.data.reason.kind) {
+		case "max-tokens": return "max-tokens";
+		case "aborted":
+		case "interrupted": return "aborted";
+		case "error": return "error";
+		case "blocked": return "refusal";
+		case void 0:
+		case "completed": return droppedUnrun ? "aborted" : "completed";
+		/* v8 ignore next 4 -- `forked` appears only in constructor seed history, while
+		* this function reads an epoch-owned suffix. `TurnEndReason` is merge-extensible,
+		* so a backend-added variant cannot be listed; treating an unnameable reason as
+		* success would report failed work as completed. */
+		default: return "error";
+	}
+}
+/** Render any listener-thrown value without letting coercion escape containment. */
+function renderThrown(value) {
+	try {
+		return value instanceof Error ? `${value.name}: ${value.message}` : String(value);
+	} catch {
+		return "<unrenderable thrown value>";
+	}
+}
+//#endregion
+//#region lib/types/child-agent.js
+/**
+* Shared in-process child composition: the delegation-depth budget, the
+* durable session metadata, the resolved child `AgentOptions`, the delegated
+* policy seed, and the scoped setup used by local activations.
+*
+* @module @qlzt/dsh-subagent/child-agent
+*/
+/** Thrown when starting a child would exceed the requested depth cap. */
+var SubagentDepthError = class extends Error {
+	attemptedDepth;
+	maxDepth;
+	constructor(attemptedDepth, maxDepth) {
+		super(`subagent depth ${attemptedDepth} exceeds maxDepth ${maxDepth}`);
+		this.attemptedDepth = attemptedDepth;
+		this.maxDepth = maxDepth;
+		this.name = "SubagentDepthError";
+	}
+};
+/**
+* Resolve the child's delegation depth from its parent and enforce an optional
+* cap. The persisted parent header is the monotone floor, so a resumed parent
+* cannot delegate as if it were top-level.
+* @param parent - the delegating parent agent.
+* @param maxDepth - optional absolute cap the resolved depth must not exceed.
+* @returns the child's non-negative safe-integer depth.
+* @throws {SubagentDepthError} when the resolved depth exceeds `maxDepth`.
+* @throws {RangeError} when the resolved depth leaves the safe-integer range.
+*/
+function resolveChildDepth(parent, maxDepth) {
+	const childDepth = delegationDepthOf(parent) + 1;
+	if (!Number.isSafeInteger(childDepth)) throw new RangeError("subagent child depth exceeds the safe-integer range");
+	if (maxDepth !== void 0 && childDepth > maxDepth) throw new SubagentDepthError(childDepth, maxDepth);
+	return childDepth;
+}
+/**
+* Resolve the parent values inherited by a child. The latest request header
+* owns provider, model, and reasoning effort after request-time selection;
+* creation options remain the fallback before the first request and retain
+* the configured output-token limit.
+* @param parent - delegating parent Agent.
+* @returns detached Agent options for child-option merging.
+*/
+function parentAgentOptionsForDelegation(parent) {
+	const requestConfig = parent.session.requestHeader()?.config;
+	if (requestConfig === void 0) return { ...parent.options };
+	const { provider: _createdProvider, model: _createdModel, reasoningEffort: _createdReasoningEffort, ...createdOptions } = parent.options;
+	return {
+		...createdOptions,
+		provider: requestConfig.provider,
+		model: requestConfig.model,
+		...requestConfig.reasoningEffort === void 0 ? {} : { reasoningEffort: requestConfig.reasoningEffort }
+	};
+}
+/**
+* Resolve the child's `AgentOptions`: the parent's provider/model,
+* reasoning-effort, and maxTokens values unless the request overrides them,
+* stamped with the child's own delegation depth. Changing the route without
+* naming an effort clears the parent's route-owned effort so the selected
+* model resolves its own default.
+* @param parent - the delegating parent whose route the child inherits.
+* @param requested - per-child overrides, if any.
+* @param childDepth - the resolved delegation depth to stamp.
+* @returns the resolved options for `ctx.agents.create()`.
+*/
+function resolveChildAgentOptions(parent, requested, childDepth) {
+	const parentOptions = parentAgentOptionsForDelegation(parent);
+	const parentProvider = parentOptions.provider;
+	const parentModel = parentOptions.model;
+	const parentReasoningEffort = parentOptions.reasoningEffort;
+	const parentMaxTokens = parentOptions.maxTokens;
+	const resolved = {
+		...parentProvider !== void 0 ? { provider: parentProvider } : {},
+		...parentModel !== void 0 ? { model: parentModel } : {},
+		...parentReasoningEffort !== void 0 ? { reasoningEffort: parentReasoningEffort } : {},
+		...parentMaxTokens !== void 0 ? { maxTokens: parentMaxTokens } : {},
+		...requested,
+		subagentDepth: childDepth
+	};
+	if ((resolved.provider !== parentProvider || resolved.model !== parentModel) && requested?.reasoningEffort === void 0) delete resolved.reasoningEffort;
+	return resolved;
+}
+/**
+* Build the child session's durable creation metadata: the parent's workspace,
+* its direct lineage, coarse product origin, the recursion budget that must
+* survive persistence, the seed boundary that separates inherited parent
+* history from child work, and the composition the child runs under.
+*
+* The preset is read from the parent's LIVE scope chain rather than from its
+* header, because a parent that switched preset while blank runs on the newer
+* composition and its header still names the older one. Recording it is what
+* makes a child's history reconstructable: without it a cold read of the child
+* resolves the deployment default and rebuilds turns under a tool set the
+* child never had.
+* @param parent - the delegating parent agent.
+* @param childDepth - the resolved delegation depth to persist.
+* @param isSeeded - whether this child inherits a parent-log prefix, including an explicitly empty one.
+* @returns the `meta` for `ctx.agents.create()`.
+*/
+function childSessionMeta(parent, childDepth, isSeeded) {
+	const parentHeader = parent.session.header;
+	const agentPreset = parent.ctx.get("agentPresets")?.composedPreset(parent.ctx);
+	return {
+		...parentHeader.cwd !== void 0 ? { cwd: parentHeader.cwd } : {},
+		...agentPreset === void 0 ? {} : { agentPreset },
+		parentSession: parentHeader.id,
+		isSeeded,
+		origin: "subagent",
+		delegationDepth: childDepth
+	};
+}
+/**
+* Model-facing delegation-scope statement for every in-process child. A
+* runtime-context contribution rather than a system-prompt section, so the
+* deployment's system prompt stays uniform across parents and children.
+*/
+const SUBAGENT_DELEGATION_CONTEXT = "You are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it.";
+/**
+* Compose one child inside its creation window: join its parent's preset,
+* register the fixed delegation-scope statement, then apply the child's own
+* shadowing persona section and tool restriction, all owned by the child's
+* scope and therefore invisible to its parent and siblings. Creation and cold
+* resume both pass through here.
+*
+* The join comes first and the child's own registrations second, which is the
+* order the layering already implies — the nearest scope wins a name, and a
+* per-child restriction intersects with everything its chain admits — but
+* stating it here keeps the two steps from being read as independent.
+*
+* The join and the per-child registrations live in ONE call because a child
+* composed without the join is exactly the defect this function exists to
+* prevent: with every model-facing row on the agent plane, a child that joins
+* no preset sees an empty tool registry and none of its parent's prompt
+* sections. Taking the parent as a parameter is what makes that omission
+* unrepresentable at the call sites.
+* @param childCtx - the child agent's scoped creation context.
+* @param parent - the delegating parent whose composition the child joins.
+* @param composition - the per-child persona and tool filter to install.
+*/
+function applyChildComposition(childCtx, parent, composition) {
+	childCtx.get("agentPresets")?.composeFrom(childCtx, parent.ctx);
+	childCtx.systemPrompt.context({
+		name: "subagent:delegation",
+		order: childCtx.systemPrompt.getContextOrder("SUBAGENT_DELEGATION"),
+		text: SUBAGENT_DELEGATION_CONTEXT
+	});
+	if (composition.persona !== void 0) childCtx.systemPrompt.section({
+		name: "deployment:persona-prefix",
+		order: childCtx.systemPrompt.getSectionOrder("DEPLOYMENT_PERSONA_PREFIX"),
+		text: composition.persona
+	});
+	if (composition.toolFilter !== void 0) childCtx.tools.restrict(composition.toolFilter);
+}
+/**
+* Capture the permission state to seed into one delegation. Call synchronously before
+* the child start's first await: a later parent switch belongs to the
+* parent's future, not to this child. Auto and Full access identities are
+* inherited only through the in-process DSH path so either can replace a stale
+* same-bundle fork value. Only the parent session's explicit sandbox override
+* is captured — never deployment defaults or one-shot grants — and the approval
+* policy is pinned to `'never'` regardless of the parent's own policy.
+* @param parent - the delegating parent agent.
+* @returns the sandbox override (or `undefined` without one) and the approval pin.
+*/
+function captureDelegatedPolicyOverrides(parent) {
+	const preset = parent.ctx.get("permissionPresets")?.current(parent.session);
+	return {
+		permissionPreset: preset === "auto" || preset === "danger-full-access" ? preset : void 0,
+		sandboxMode: parent.ctx.get("sandboxPolicy")?.overrideOf(parent.session),
+		approvalPolicy: parent.ctx.get("approval") === void 0 ? void 0 : "never"
+	};
+}
+/**
+* Append the captured delegation policy onto the child's own log as
+* `source: 'delegation'` events inside the unpublished creation window, so the
+* child's effective policy is reconstructable from its log alone. Appends land
+* after any fork seed, so fresh policy wins stale seed state; later child
+* switches still win over these events.
+* @param childSession - the unpublished child's session.
+* @param overrides - the policy captured at delegation.
+*/
+function appendDelegatedPolicyOverrides(childSession, overrides) {
+	if (overrides.sandboxMode !== void 0) childSession.append("sandbox/mode", {
+		mode: overrides.sandboxMode,
+		source: "delegation"
+	});
+	if (overrides.approvalPolicy !== void 0) childSession.append("approval/policy", {
+		policy: overrides.approvalPolicy,
+		source: "delegation"
+	});
+	if (overrides.permissionPreset !== void 0) childSession.append("permission/preset", { preset: overrides.permissionPreset });
+}
+//#endregion
+//#region lib/types/continuation-messages.js
+/**
+* Model-visible messages owned by continuable-subagent orchestration.
+*
+* @module @qlzt/dsh-subagent/continuation-messages
+*/
+/** Build durable attribution for one adjacent-Agent message. */
+function agentMessageSource(sender) {
+	return {
+		kind: "agent-message",
+		form: "relay",
+		senderSessionId: sender.id
+	};
+}
+/**
+* Build the model-visible and durable representation of one adjacent-Agent message.
+* @param sender - exact live Agent that authored the message.
+* @param content - model-visible message blocks supplied by the sender.
+* @returns the durable user-message representation delivered to the recipient.
+*/
+function createAgentMessage(sender, content) {
+	return createUserMessage({
+		content: [{
+			type: "text",
+			text: `Agent ${sender.id} sent a message: `
+		}, ...content],
+		source: agentMessageSource(sender)
+	});
+}
+/**
+* Append adjacent-Agent return guidance to a continuable child's initial task.
+* @param parentId - durable parent session id named in the guidance.
+* @param prompt - initial model-visible task blocks.
+* @returns task blocks followed by the continuable return guidance.
+*/
+function withContinuableReturnGuidance(parentId, prompt) {
+	const encodedParentId = JSON.stringify(parentId);
+	return [...prompt, {
+		type: "text",
+		text: `Your parent agent id is ${encodedParentId}. Before you finish, send your result to that agent with send_message({ agent_id: ${encodedParentId}, message: "<self-contained result>" }). The parent shares your workspace but does not automatically receive your transcript, tool output, or reasoning. Send earlier messages as well when a finding changes what the parent should do next; sending a message does not end your turn.`
+	}];
+}
+/**
+* One line telling a parent that a background child is finished and why, in
+* the parent's own task vocabulary.
+* @param childId - the durable child the parent knows by id.
+* @param stopReason - how the child's last ordinary turn ended.
+* @param continuable - whether the child accepts a later message.
+* @returns the model-facing opening line of the settlement notice.
+*/
+function settlementSummary(childId, stopReason, continuable) {
+	const subject = `Background subagent ${childId}`;
+	switch (stopReason) {
+		case "completed": return continuable ? `${subject} finished and will do no further work unless you send it more.` : `${subject} finished. It cannot receive follow-up messages.`;
+		case "aborted": return `${subject} was stopped before it finished.`;
+		case "max-tokens": return `${subject} ran out of room before it finished.`;
+		case "refusal": return `${subject} declined the task.`;
+		case "error": return `${subject} failed before it finished.`;
+		/* v8 ignore next 4 -- `SubagentResult['stopReason']` is merge-extensible, so this arm
+		* needs a backend that adds a variant; an unnameable ending is reported as unfinished
+		* rather than silently as success. */
+		default: return `${subject} ended abnormally (${String(stopReason)}) before it finished.`;
+	}
+}
+/**
+* Build the runtime-owned settlement notice from the child's nonempty closing text.
+* @param childId - durable child session id named in the notice.
+* @param terminal - recorded terminal state for the settled Activation.
+* @param continuable - whether the child can accept another task.
+* @returns the durable user-message representation delivered to the parent.
+*/
+function createSettlementMessage(childId, terminal, continuable = true) {
+	const summary = settlementSummary(childId, terminal.stopReason, continuable);
+	const closingText = terminal.output.flatMap((block) => block.type === "text" && block.text.length > 0 ? [block] : []);
+	return createUserMessage({
+		content: [
+			{
+				type: "text",
+				text: summary
+			},
+			...closingText.length === 0 ? [{
+				type: "text",
+				text: "It left no closing message."
+			}] : [{
+				type: "text",
+				text: "Its closing message:"
+			}, ...closingText],
+			...terminal.structured !== void 0 ? [{
+				type: "text",
+				text: `Structured result: ${JSON.stringify(terminal.structured)}`
+			}] : [],
+			...terminal.diagnostic !== void 0 ? [{
+				type: "text",
+				text: terminal.diagnostic
+			}] : []
+		],
+		source: {
+			kind: "subagent-settled",
+			form: "notice",
+			summary: boundContextSummary(summary),
+			senderSessionId: childId
+		}
+	});
+}
+//#endregion
+//#region lib/types/descriptor.js
+/**
+* The durable subagent-child descriptor: the versioned, model-hidden
+* `subagent/descriptor` session event that identifies every session-backed
+* subagent, including historical one-shot records. The manager appends each
+* continuable child's descriptor inside its initial turn, preserving the
+* declared composition required for cold resume.
+*
+* The descriptor deliberately snapshots explicit fields rather than the
+* merge-extensible `AgentOptions` object: an unrelated extension value cannot
+* make continuation fail merely because it is not JSON, and later composition
+* inputs require a deliberate {@link SUBAGENT_DESCRIPTOR_VERSION} change. It
+* omits `subagentDepth` — cold resume trusts the persisted header's
+* `delegationDepth` as the monotone floor — and `outputSchema`, which belongs
+* to one activation's result contract rather than durable child composition.
+* Per-activation knobs such as `maxTokens` are omitted for the same reason as
+* `outputSchema`: they budget one activation. Cold resume requires the exact
+* live parent for authorization but reconstructs child options only from the
+* durable descriptor, so it neither restores the prior budget nor inherits
+* the parent's current one; the resumed route's defaults apply instead.
+*
+* @module @qlzt/dsh-subagent/descriptor
+*/
+/**
+* The current descriptor format version, stamped into every appended
+* `subagent/descriptor` event and required verbatim by {@link foldSubagentDescriptor}.
+* Supporting another composition input is a deliberate version change, never
+* an implicit extra field.
+*/
+const SUBAGENT_DESCRIPTOR_VERSION = 3;
+const DESCRIPTOR_BASE_KEYS = [
+	"version",
+	"mode",
+	"provider",
+	"label"
+];
+const ONE_SHOT_DESCRIPTOR_KEYS = new Set(DESCRIPTOR_BASE_KEYS);
+const CONTINUABLE_DESCRIPTOR_KEYS = new Set([
+	...DESCRIPTOR_BASE_KEYS,
+	"agentProvider",
+	"agentModel",
+	"agentReasoningEffort",
+	"persona",
+	"toolFilter"
+]);
+const TOOL_FILTER_KEYS = new Set(["allow", "deny"]);
+/** Whether a persisted JSON value is an object record. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Reject fields outside one versioned record's declared schema. */
+function assertKnownKeys(value, keys, path) {
+	const unknown = Object.keys(value).find((key) => !keys.has(key));
+	if (unknown !== void 0) throw new Error(`persisted subagent descriptor ${path} has unknown field "${unknown}"`);
+}
+/** Read one optional string field from a persisted descriptor record. */
+function optionalString(value, key) {
+	if (!Object.hasOwn(value, key)) return void 0;
+	const field = value[key];
+	if (typeof field !== "string") throw new Error(`persisted subagent descriptor ${key} must be a string`);
+	return field;
+}
+/** Read one optional string-array field from a persisted tool restriction. */
+function optionalStringArray(value, key) {
+	if (!Object.hasOwn(value, key)) return void 0;
+	const field = value[key];
+	if (!Array.isArray(field)) throw new Error(`persisted subagent descriptor toolFilter.${key} must be an array of strings`);
+	const items = field;
+	if (items.some((item) => typeof item !== "string")) throw new Error(`persisted subagent descriptor toolFilter.${key} must be an array of strings`);
+	return items;
+}
+/** Validate and reconstruct a persisted tool restriction. */
+function parseToolFilter(value) {
+	if (!isRecord(value)) throw new Error("persisted subagent descriptor toolFilter must be an object");
+	assertKnownKeys(value, TOOL_FILTER_KEYS, "toolFilter");
+	const allow = optionalStringArray(value, "allow");
+	const deny = optionalStringArray(value, "deny");
+	if (allow === void 0 && deny === void 0) throw new Error("persisted subagent descriptor toolFilter must declare allow and/or deny");
+	return {
+		...allow !== void 0 ? { allow } : {},
+		...deny !== void 0 ? { deny } : {}
+	};
+}
+/** Validate one persisted descriptor payload for the current runtime. */
+function parseSubagentDescriptor(value) {
+	if (!isRecord(value)) throw new Error("persisted subagent descriptor payload must be an object");
+	const version = value["version"];
+	if (typeof version !== "number") throw new Error("persisted subagent descriptor version must be a number");
+	if (version !== 3) return void 0;
+	const mode = value["mode"];
+	if (mode !== "one-shot" && mode !== "continuable") throw new Error("persisted subagent descriptor mode must be \"one-shot\" or \"continuable\"");
+	assertKnownKeys(value, mode === "one-shot" ? ONE_SHOT_DESCRIPTOR_KEYS : CONTINUABLE_DESCRIPTOR_KEYS, "payload");
+	const provider = value["provider"];
+	if (typeof provider !== "string") throw new Error("persisted subagent descriptor provider must be a string");
+	if (mode === "one-shot") {
+		const label = optionalString(value, "label");
+		return {
+			version: 3,
+			mode,
+			provider,
+			...label !== void 0 ? { label } : {}
+		};
+	}
+	const label = value["label"];
+	if (typeof label !== "string") throw new Error("persisted subagent descriptor label must be a string");
+	const agentProvider = optionalString(value, "agentProvider");
+	const agentModel = optionalString(value, "agentModel");
+	const agentReasoningEffort = optionalString(value, "agentReasoningEffort");
+	const persona = optionalString(value, "persona");
+	const toolFilter = Object.hasOwn(value, "toolFilter") ? parseToolFilter(value["toolFilter"]) : void 0;
+	return {
+		version: 3,
+		mode,
+		provider,
+		label,
+		...agentProvider !== void 0 ? { agentProvider } : {},
+		...agentModel !== void 0 ? { agentModel } : {},
+		...agentReasoningEffort !== void 0 ? { agentReasoningEffort } : {},
+		...persona !== void 0 ? { persona } : {},
+		...toolFilter !== void 0 ? { toolFilter } : {}
+	};
+}
+/**
+* Validate and detach a continuable descriptor input.
+* @param input - the caller-collected continuable composition fields.
+* @returns the versioned, detached continuable descriptor payload.
+* @throws when a field is not losslessly JSON-serializable.
+*/
+function snapshotSubagentDescriptor(input) {
+	const snapshot = snapshotJsonValue({
+		version: 3,
+		mode: input.mode,
+		provider: input.provider,
+		label: input.label,
+		...input.agentProvider !== void 0 ? { agentProvider: input.agentProvider } : {},
+		...input.agentModel !== void 0 ? { agentModel: input.agentModel } : {},
+		...input.agentReasoningEffort !== void 0 ? { agentReasoningEffort: input.agentReasoningEffort } : {},
+		...input.persona !== void 0 ? { persona: input.persona } : {},
+		...input.toolFilter !== void 0 ? { toolFilter: input.toolFilter } : {}
+	});
+	if (snapshot === void 0) throw new Error("subagent descriptor is not losslessly JSON-serializable");
+	return snapshot;
+}
+/**
+* Fold a persisted child log to its supported descriptor. The first
+* `subagent/descriptor` event is authoritative — the establishing provider
+* appends exactly one, so a later same-type event cannot rewrite the declared
+* composition.
+* @param events - the loaded child session events.
+* @returns the descriptor, or `undefined` when the log has none or its
+*   version is not {@link SUBAGENT_DESCRIPTOR_VERSION} (the child cannot be
+*   classified by this runtime).
+* @throws when a current-version persisted payload does not match its complete
+*   declared schema.
+*/
+function foldSubagentDescriptor(events) {
+	const event = events.find((candidate) => candidate.type === "subagent/descriptor");
+	if (event === void 0) return void 0;
+	return parseSubagentDescriptor(event.data);
+}
+const sessionIdSchema = z$1.string();
+const oneShotCatalogSchema = z$1.object({
+	version: z$1.union([z$1.literal(0), z$1.literal(1)]),
+	childId: sessionIdSchema,
+	childCreatedAt: z$1.number().int().nonnegative(),
+	mode: z$1.literal("one-shot"),
+	label: z$1.string().optional()
+}).strict();
+const continuableCatalogSchema = z$1.object({
+	version: z$1.union([z$1.literal(0), z$1.literal(1)]),
+	childId: sessionIdSchema,
+	childCreatedAt: z$1.number().int().nonnegative(),
+	mode: z$1.literal("continuable"),
+	label: z$1.string()
+}).strict();
+const externalCatalogSchema = oneShotCatalogSchema.extend({
+	version: z$1.literal(2),
+	mode: z$1.literal("external")
+});
+const unknownCatalogSchema = oneShotCatalogSchema.extend({
+	version: z$1.literal(1),
+	mode: z$1.literal("unknown")
+});
+const eventDataSchema = z$1.union([
+	oneShotCatalogSchema,
+	externalCatalogSchema,
+	continuableCatalogSchema,
+	unknownCatalogSchema
+]);
+const viewSchema = z$1.array(z$1.union([
+	oneShotCatalogSchema.omit({
+		version: true,
+		childId: true,
+		childCreatedAt: true
+	}).extend({
+		id: sessionIdSchema,
+		createdAt: oneShotCatalogSchema.shape.childCreatedAt
+	}),
+	externalCatalogSchema.omit({
+		version: true,
+		childId: true,
+		childCreatedAt: true
+	}).extend({
+		id: sessionIdSchema,
+		createdAt: externalCatalogSchema.shape.childCreatedAt
+	}),
+	continuableCatalogSchema.omit({
+		version: true,
+		childId: true,
+		childCreatedAt: true
+	}).extend({
+		id: sessionIdSchema,
+		createdAt: continuableCatalogSchema.shape.childCreatedAt
+	}),
+	unknownCatalogSchema.omit({
+		version: true,
+		childId: true,
+		childCreatedAt: true
+	}).extend({
+		id: sessionIdSchema,
+		createdAt: unknownCatalogSchema.shape.childCreatedAt
+	})
+]));
+const stateSchema = z$1.object({
+	inheritedEventCount: z$1.number().int().nonnegative(),
+	head: chunkedListSchema(eventDataSchema).optional()
+}).strict();
+/**
+* Materialize complete and unknown-mode child identities from parent catalog events.
+* @param state - parent catalog fold state.
+* @returns current direct-child rows in parent catalog event order.
+*/
+function subagentCatalogEntries(state) {
+	const entries = [];
+	for (const data of iterateChunkedList(state.head)) {
+		const { version: _version, childId, childCreatedAt, ...descriptor } = data;
+		entries.push({
+			id: childId,
+			createdAt: childCreatedAt,
+			...descriptor
+		});
+	}
+	return entries;
+}
+/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
+const subagentCatalogProjectionDefinition = {
+	key: "subagentCatalog",
+	stateSchema,
+	init: (_header, inheritedEventCount) => ({ inheritedEventCount }),
+	apply: (state, event) => {
+		if (event.type !== "subagent/catalog" || event.seq < state.inheritedEventCount) return state;
+		return {
+			...state,
+			head: appendChunkedList(state.head, eventDataSchema.parse(event.data))
+		};
+	},
+	stateVersion: 6,
+	wire: {
+		viewSchema,
+		view: subagentCatalogEntries
+	}
+};
+/**
+* Append a complete direct-child discovery fact to its parent Session.
+* @param parent - durable direct parent receiving the discovery fact.
+* @param child - established child's immutable Session metadata.
+* @param descriptor - mode-discriminated creation label frozen with the child.
+*/
+function establishCatalogChild(parent, child, descriptor) {
+	parent.append("subagent/catalog", {
+		version: 0,
+		childId: child.id,
+		childCreatedAt: child.createdAt,
+		mode: descriptor.mode,
+		label: descriptor.label
+	});
+}
+/** Catalog payload version emitted by external execution creation. */
+const EXTERNAL_SUBAGENT_CATALOG_VERSION = 2;
+/**
+* Record an external execution without a local child Session.
+* @param parent - durable direct parent receiving the discovery fact.
+* @param childId - identity returned by the external provider.
+* @param label - display label assigned by the caller.
+*/
+function establishExternalCatalogChild(parent, childId, label) {
+	parent.append("subagent/catalog", {
+		version: EXTERNAL_SUBAGENT_CATALOG_VERSION,
+		childId,
+		childCreatedAt: Date.now(),
+		mode: "external",
+		label
+	});
+}
+//#endregion
+//#region lib/types/internal.js
+/**
+* Continuation integration markers and host adapters outside the public
+* Service Definition and model-facing Agent messaging contract.
+* @module @qlzt/dsh-subagent/internal
+*/
+/** Process-stable identity carried only by the standard adjacent-Agent messaging tool. */
+const adjacentAgentSendMessageTool = Symbol.for("dsh.subagent.adjacentAgentSendMessageTool");
+/**
+* Test whether one visible definition is the standard adjacent-Agent messaging tool.
+* @param definition - the scope-resolved `send_message` candidate.
+* @returns whether the definition carries the internal standard-tool identity.
+*/
+function isAdjacentAgentSendMessageTool(definition) {
+	return definition !== void 0 && definition[adjacentAgentSendMessageTool] === true;
+}
+/**
+* Process-stable symbol-keyed host delivery shared by the bundled runtime
+* entry and this unbundled internal subpath.
+* @internal
+*/
+const deliverSubagentPrompt = Symbol.for("dsh.subagent.deliverPrompt");
+//#endregion
+//#region lib/types/structured.js
+/**
+* Child-scoped structured-output tool, prompt instruction, terminal guard, and authoritative
+* result capture for in-process subagents. Each child registers its real schema on its own
+* scope, so concurrent runs do not interact and disposal leaves no global residue. The prompt
+* contribution is ordinary reconstructed request state.
+*
+* Capture commits only after the authoritative `tools/result` succeeds; PTC mode capture also
+* waits for the enclosing `run_code` result. The terminal result marker and monotonic tool
+* guard prevent later calls from reopening a completed structured run.
+* @module @qlzt/dsh-subagent/structured
+*/
+/** The model-facing tool name a structured child must call to finish. */
+const STRUCTURED_OUTPUT_TOOL = "structured_output";
+/**
+* The instruction registered as the child's trailing scoped prompt section:
+* the demand travels with the
+* tool, as ordinary prompt state of exactly one agent.
+*/
+const STRUCTURED_OUTPUT_INSTRUCTION = `When you have your final answer, you MUST report it by calling the \`${STRUCTURED_OUTPUT_TOOL}\` tool with arguments matching its parameter schema exactly. Do not finish with a plain text answer: only the tool call counts as your result.`;
+/**
+* Attach the scoped capture tool, instruction, and enforcement to a child during
+* its creation window. Child disposal removes every registration.
+* @param childCtx - the child agent's scope context (`setup`'s argument).
+* @param schema - the trusted, already-asserted schema subset to enforce (see
+*   `assertObjectJsonSchema` in dsh-tools).
+* @param canComplete - whether accepted input and owned child work have finished.
+* @returns the attachment handle (read `captured()` after the child settles).
+*/
+function attachStructuredRuntime(childCtx, schema, canComplete) {
+	/**
+	* Validated values staged by the capture tool body, awaiting THEIR OWN
+	* authoritative `tools/result` notification. The execution object's identity
+	* uniquely identifies a trip through the pipeline: adapter call ids may
+	* repeat across steps, but another execution can never reach this Map
+	* entry. This is distinct from the opaque `ToolExecutionToken` used to
+	* correlate nested transports. The final notification always deletes its own
+	* stage, whether the result succeeded or failed.
+	*/
+	const staged = /* @__PURE__ */ new Map();
+	/** Successful nested capture waiting for its enclosing transport to commit. */
+	let pending;
+	let captured;
+	const schemaEntry = {
+		name: STRUCTURED_OUTPUT_TOOL,
+		description: "Report your final structured result. Call this exactly once, when your answer is complete; the arguments must match this tool's parameter schema exactly.",
+		parameters: { ...schema }
+	};
+	childCtx.tools.register({
+		...schemaEntry,
+		output: {
+			schema: {
+				type: "object",
+				properties: { recorded: {
+					type: "boolean",
+					const: true
+				} },
+				required: ["recorded"],
+				additionalProperties: false
+			},
+			render: () => [{
+				type: "text",
+				text: "Structured output recorded."
+			}]
+		},
+		execute(args, exec) {
+			const violations = validateJsonSchemaValue(schema, args);
+			if (violations.length > 0) throw new ToolArgsError(violations);
+			if (!canComplete()) throw new Error("Wait for all delegated child tasks to finish and process pending messages before submitting structured output.");
+			staged.set(exec, { value: args });
+			exec.concludeTurn();
+			return Promise.resolve({ recorded: true });
+		}
+	});
+	childCtx.systemPrompt.section({
+		name: `tool:${STRUCTURED_OUTPUT_TOOL}`,
+		order: childCtx.systemPrompt.getSectionOrder("STRUCTURED_OUTPUT"),
+		text: STRUCTURED_OUTPUT_INSTRUCTION
+	});
+	childCtx.tools.guard((exec) => captured === void 0 && pending === void 0 ? void 0 : `structured output already recorded: the run is complete, so \`${exec.name}\` is not executed`);
+	childCtx.on("tools/result", function(exec, result) {
+		if (exec.name === "structured_output") {
+			const entry = staged.get(exec);
+			if (entry === void 0) return;
+			staged.delete(exec);
+			if (result.isError) return;
+			if (exec.parent === void 0) {
+				/* v8 ignore else -- sequential agent-loop dispatch lets the guard block every later supported call */
+				if (captured === void 0) captured = { value: entry.value };
+			} else if (captured === void 0 && pending === void 0) pending = {
+				parent: exec.parent,
+				value: entry.value
+			};
+			return;
+		}
+		if (pending?.parent !== exec.token) return;
+		const entry = pending;
+		pending = void 0;
+		if (result.isError) return;
+		/* v8 ignore else -- PTC mode serializes outer executions, so the guard blocks every later supported call */
+		if (captured === void 0) captured = { value: entry.value };
+	});
+	return {
+		captured: () => captured,
+		acceptsInput: () => staged.size === 0 && pending === void 0 && captured === void 0
+	};
+}
+//#endregion
+//#region lib/types/assistant-output.js
+/**
+* Canonical selection of a child's final assistant output. Backend run results
+* and `subagent/end.lastAssistantMessage` apply the same rule: select the last
+* non-empty assistant message. An empty-content message records usage only
+* when the loop appends it after a max-tokens step with no executable blocks,
+* so it does not replace earlier output. If no non-empty message exists,
+* select the accumulated assistant text. Selection is independent of the
+* run's stop reason.
+*
+* @module @qlzt/dsh-subagent/assistant-output
+*/
+/**
+* Incremental fold of the selection rule, for backends that observe a child's
+* output as it streams: session-event backends {@link push} each event, and
+* transports without session events (ACP content chunks) {@link pushText} raw
+* text into the same streamed fallback.
+*/
+var AssistantOutputFold = class {
+	message;
+	partial = [];
+	/**
+	* Fold one session event: a non-empty assistant message becomes the
+	* candidate final answer, while its embedded stream and any log-only attempt
+	* extend the streamed fallback; every other event contributes nothing.
+	* @param event - the next observed session event.
+	*/
+	push(event) {
+		if (event.type === "assistant/message") {
+			const content = event.data.message.content;
+			if (content.length > 0) this.message = content;
+		}
+		if (event.type === "assistant/message" || event.type === "assistant/attempt") this.pushText(joinAssistantStreamText(event.data.stream));
+	}
+	/**
+	* Extend the streamed fallback with text observed outside session events.
+	* @param text - the next streamed text piece (an empty piece is a no-op).
+	*/
+	pushText(text) {
+		if (text.length > 0) this.partial.push(text);
+	}
+	/**
+	* Select the final output folded so far.
+	* @returns the last non-empty assistant message, else the accumulated
+	*   streamed text, or `undefined` when the child produced neither.
+	*/
+	collect() {
+		if (this.message !== void 0) return this.message;
+		const text = this.partial.join("");
+		return text.length > 0 ? [{
+			type: "text",
+			text
+		}] : void 0;
+	}
+};
+/**
+* Apply the selection rule to one complete child-owned event suffix.
+* @param events - the child-owned events (after any seed or epoch boundary).
+* @returns the selected output, or `undefined` when the child produced none.
+*/
+function finalAssistantOutput(events) {
+	const fold = new AssistantOutputFold();
+	for (const event of events) fold.push(event);
+	return fold.collect();
+}
+//#endregion
+//#region lib/types/activation.js
+/** Execution-period records, capacity slots, child serialization, and local output capture.
+* @module @qlzt/dsh-subagent/activation
+*/
+/** Process-local slots shared through uninterrupted continuable parent links. */
+var ActivationPool = class {
+	slots = /* @__PURE__ */ new Set();
+	/**
+	* Reserve before reconstruction; release also tolerates unpublished rollback.
+	* @param capacity - the maximum simultaneous activations in this pool.
+	* @returns an idempotent slot release.
+	*/
+	reserve(capacity) {
+		if (this.slots.size >= capacity) throw new SubagentError(`subagent limit reached (active child limit: ${capacity}); wait for an existing child to finish or complete this work with the current agents`, "ACTIVATION_LIMIT_REACHED");
+		const slot = Symbol();
+		this.slots.add(slot);
+		return () => {
+			this.slots.delete(slot);
+		};
+	}
+};
+/**
+* Read the live Agent retained by local execution.
+* @param activation - the managed local or external execution.
+* @returns the local Agent, absent for an external run.
+*/
+function activationAgent(activation) {
+	return activation.kind === "local" ? activation.handle.agent : void 0;
+}
+/**
+* Require local residency before accepting further input.
+* @param activation - execution targeted by message delivery.
+* @returns the local activation.
+* @throws when the external backend cannot accept another message.
+*/
+function requireLocalActivation(activation) {
+	switch (activation.kind) {
+		case "local": return activation;
+		case "external": throw new SubagentError(`subagent "${activation.childId}" does not accept follow-up input`, "NOT_CONTINUABLE");
+		/* v8 ignore next 2 -- Both execution kinds are handled above. */
+		default: return assertNever(activation);
+	}
+}
+/**
+* Retain local failures whose turn ending could not be committed.
+* @param activation - exact local Agent and epoch receiving the scoped observers.
+* @param wake - notify its settlement watcher when failure changes readiness.
+*/
+function observeLocalFailure(activation, wake) {
+	const child = activation.handle.agent;
+	child.ctx.on("agent/error", ({ agent }) => {
+		if (agent !== child) return;
+		activation.failureAt = child.session.seq;
+		wake();
+	});
+	child.ctx.on("session/event", (session, event) => {
+		if (session === child.session && event.type === "turn/end" && activation.failureAt !== void 0 && event.seq >= activation.failureAt) activation.failureAt = void 0;
+	});
+}
+/**
+* Capture local output and retain failures without a later committed turn ending.
+* @param activation - the settled local execution and any structured result.
+* @returns final output, stop reason, and committed structured value.
+*/
+function captureLocalResult(activation) {
+	const events = activation.handle.agent.session.snapshotEvents(activation.outputStart);
+	const output = finalAssistantOutput(events) ?? [];
+	const stopReason = activation.failureAt === void 0 ? epochStopReason(events) : "error";
+	const structured = activation.structured;
+	if (structured !== void 0) {
+		const captured = structured.captured();
+		if (captured !== void 0) return {
+			output,
+			stopReason,
+			structured: captured.value
+		};
+		if (stopReason === "completed") return {
+			output,
+			stopReason: "error"
+		};
+	}
+	return {
+		output,
+		stopReason
+	};
+}
+/** Serialize each durable child's delivery, release, and disposal. */
+var ChildLock = class {
+	tails = /* @__PURE__ */ new Map();
+	/**
+	* Run `operation` after every previously queued operation for `childId`.
+	* @param childId - the durable child whose operations are linearized.
+	* @param operation - the critical section to run in order.
+	* @returns the operation's own settlement.
+	*/
+	run(childId, operation) {
+		const result = (this.tails.get(childId) ?? Promise.resolve()).then(operation, operation);
+		const tail = result.then(() => void 0, () => void 0);
+		this.tails.set(childId, tail);
+		tail.then(() => {
+			if (this.tails.get(childId) === tail) this.tails.delete(childId);
+		});
+		return result;
+	}
+};
+//#endregion
+//#region lib/types/manager.js
+/**
+* Owns subagent startup, message admission, cold resume, and execution lifetimes.
+* One child lock orders input acceptance and closure; one activation map owns
+* capacity, parent relationships, and resource release across all providers.
+*
+* @module @qlzt/dsh-subagent/manager
+*/
+var __addDisposableResource$2 = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources$2 = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/** Render only the safe outer message from execution or teardown failures. */
+function failureMessage(error) {
+	return error instanceof Error ? error.message : "unknown teardown failure";
+}
+/** Own subagent requests and the resources of every live activation. */
+var SubagentManager = class {
+	ctx;
+	host;
+	maxActiveSubagents;
+	/** Child session id → its live Activation. Process-local, never durable. */
+	resident = /* @__PURE__ */ new Map();
+	/** Root identities retain their pool across child settlement without retaining dead roots. */
+	rootPools = /* @__PURE__ */ new WeakMap();
+	/** Materializations admitted before drain, tracked through publication or rollback. */
+	materializations = /* @__PURE__ */ new Set();
+	/** Per-child serializer shared by delivery, release, and disposal. */
+	locks = new ChildLock();
+	/** Structural Cordis owner of every Activation handle. */
+	ownerCtx;
+	/**
+	* Exact roots whose host teardown has begun, with the live lineage members
+	* observed under each root. Entries remain until that exact root leaves the
+	* Agent registry, closing admission throughout its host's teardown without
+	* poisoning a later same-id replacement.
+	*/
+	closingScopes = /* @__PURE__ */ new Map();
+	draining = false;
+	/**
+	* Build one manager inside the service's Agent-injected context.
+	* @param ctx - context providing Agents, Sessions, and teardown ownership.
+	* @param host - provider dispatch and lifecycle observation owned by the service.
+	* @param maxActiveSubagents - the current configured child capacity.
+	*/
+	constructor(ctx, host, maxActiveSubagents) {
+		this.ctx = ctx;
+		this.host = host;
+		this.maxActiveSubagents = maxActiveSubagents;
+		const scope = ctx.plugin(function activationOwner() {});
+		this.ownerCtx = scope.ctx;
+		ctx.on("agent/disposed", ({ agent }) => {
+			this.closingScopes.delete(agent);
+		});
+		ctx.effect(function* () {
+			yield scope.dispose;
+			yield () => this.drain();
+		}.bind(this), "subagents.manager()");
+	}
+	/**
+	* Interrupt one live continuable child's current turn under the supplied authority.
+	* @param targetSessionId - the durable child session id to interrupt.
+	* @param authority - the human parent address or exact live ancestor Agent.
+	*/
+	interrupt(targetSessionId, authority) {
+		if (authority.kind === "ancestor") {
+			const caller = authority.agent;
+			if (this.ctx.agents.get(caller.id) !== caller) throw new SubagentError(`interrupting "${targetSessionId}" requires the exact live ancestor agent`, "UNAUTHORIZED");
+			if (caller.id === targetSessionId) throw new SubagentError(`agent "${caller.id}" cannot interrupt itself`, "UNAUTHORIZED");
+		}
+		const activation = this.resident.get(targetSessionId);
+		if (activation === void 0) return;
+		if (authority.kind === "user") {
+			if (activation.parent.id !== authority.parentSessionId) throw new SubagentError(`subagent "${targetSessionId}" belongs to another parent session`, "UNAUTHORIZED");
+		} else if (!activation.ancestry.has(authority.agent)) throw new SubagentError(`subagent "${targetSessionId}" is not a live descendant of agent "${authority.agent.id}"`, "UNAUTHORIZED");
+		if (activation.closing !== void 0) return;
+		const kind = authority.kind === "user" ? "user" : "parent";
+		if (activation.kind === "local") activation.handle.agent.cancel({ kind }, { keepInbox: true });
+		else {
+			activation.controller.abort({ kind });
+			this.dispose(activation).catch(() => void 0);
+		}
+	}
+	/**
+	* Close admission, await every already-admitted materialization through
+	* publication or rollback, then dispose the stable live Activation graph
+	* child-first.
+	*/
+	async drain() {
+		this.draining = true;
+		for (const pending of this.materializations) pending.controller.abort();
+		await Promise.all([...this.materializations].map((materialization) => materialization.settled));
+		const owned = /* @__PURE__ */ new Set();
+		for (const activation of this.resident.values()) for (const child of activation.ownedChildren) owned.add(child);
+		const roots = [...this.resident.values()].filter((activation) => !owned.has(activation.childId));
+		await this.disposeRoots(roots, "activation(s)");
+	}
+	/**
+	* Join progressing child work, leaving idle parked inboxes resident.
+	* @param parent - exact live parent whose descendants are observed.
+	* @returns whether work was joined and the host must recheck parent completion.
+	*/
+	async waitForChildren(parent) {
+		let observed = false;
+		while (true) {
+			const pending = [...this.materializations].filter((item) => item.lineage.includes(parent));
+			const children = [...this.resident.values()].filter((item) => activationAgent(item) !== parent && item.ancestry.has(parent));
+			observed ||= children.some((item) => item.kind === "local" && item.handle.agent.status !== "idle");
+			await Promise.all(children.flatMap((item) => item.kind === "local" ? [item.handle.agent.whenIdle()] : []));
+			const waits = pending.map((item) => item.settled);
+			for (const item of children) {
+				if (item.kind === "external" || item.closing !== void 0) {
+					waits.push(item.result.promise.catch(() => void 0));
+					continue;
+				}
+				if (item.handle.agent.status !== "idle") {
+					waits.push(item.handle.agent.whenIdle());
+					continue;
+				}
+				if (item.ownedChildren.size > 0) {
+					if ([...item.ownedChildren].some((id) => !this.resident.has(id))) waits.push(item.poke.promise);
+					continue;
+				}
+				const inbox = item.handle.agent.inbox;
+				if (item.failureAt === void 0 && (inbox.nextTurn.length > 0 || inbox.nextStep.length > 0)) continue;
+				waits.push(Promise.race([item.result.promise.catch(() => void 0), item.poke.promise]));
+			}
+			if (waits.length > 0) {
+				observed = true;
+				await Promise.all(waits);
+				continue;
+			}
+			if ([...this.materializations].some((item) => item.lineage.includes(parent) && !pending.includes(item)) || [...this.resident.values()].some((item) => activationAgent(item) !== parent && item.ancestry.has(parent) && !children.includes(item))) continue;
+			return observed;
+		}
+	}
+	/**
+	* Stop the managed descendants of exact live host-owned parents.
+	* @param parents - exact live roots whose managed descendants must stop.
+	*/
+	async drainDescendants(parents) {
+		const roots = new Set(parents.filter((parent) => this.ctx.agents.get(parent.id) === parent));
+		if (roots.size === 0) return;
+		for (const root of roots) this.closingMembers(root).add(root);
+		const targets = [];
+		for (const activation of this.resident.values()) {
+			const child = activationAgent(activation);
+			const lineage = this.liveLineage(child ?? activation.parent);
+			const owners = [...roots].filter((root) => child !== root && activation.ancestry.has(root));
+			if (owners.length === 0) continue;
+			targets.push(activation);
+			for (const owner of owners) {
+				const members = this.closingMembers(owner);
+				if (child !== void 0) members.add(child);
+				for (const agent of lineage) members.add(agent);
+			}
+		}
+		const materializations = [...this.materializations].filter((materialization) => {
+			const owners = [...roots].filter((root) => materialization.lineage.includes(root));
+			for (const owner of owners) {
+				const members = this.closingMembers(owner);
+				for (const agent of materialization.lineage) members.add(agent);
+			}
+			if (owners.length > 0) materialization.controller.abort();
+			return owners.length > 0;
+		});
+		const ownedTargets = /* @__PURE__ */ new Set();
+		for (const activation of targets) for (const child of activation.ownedChildren) ownedTargets.add(child);
+		const targetRoots = targets.filter((activation) => !ownedTargets.has(activation.childId));
+		for (const activation of targets) this.dispose(activation).catch(() => void 0);
+		await Promise.all(materializations.map((materialization) => materialization.settled));
+		await this.disposeRoots(targetRoots, "scoped activation(s)");
+	}
+	/**
+	* Release selected resident direct children of one exact live parent.
+	* @param parent - exact live direct parent authorizing the selected release.
+	* @param childIds - durable direct-child ids to release when resident.
+	*/
+	async drainChildren(parent, childIds) {
+		if (this.ctx.agents.get(parent.id) !== parent) throw new SubagentError("selected child teardown requires the exact live parent agent", "UNAUTHORIZED");
+		const targets = [];
+		for (const childId of new Set(childIds)) {
+			const activation = this.resident.get(childId);
+			if (activation === void 0) continue;
+			if (activation.parent.id !== parent.id || !activation.ancestry.has(parent)) throw new SubagentError(`subagent "${childId}" is not a direct child of agent "${parent.id}"`, "UNAUTHORIZED");
+			targets.push(activation);
+		}
+		for (const activation of targets) this.dispose(activation).catch(() => void 0);
+		await this.disposeRoots(targets, "selected activation(s)");
+	}
+	/**
+	* Start one continuable background child and resolve at initial inbox acceptance.
+	* Every earlier failure disposes any created handle and rolls back Activation
+	* and parent ownership without returning either id.
+	* @param spec - provider, delegation request, and caller cancellation.
+	* @returns the durable child id and accepted initial prompt message id.
+	*/
+	async startLocal(spec) {
+		const request = spec.request;
+		const parent = request.parent;
+		this.assertAdmitting(parent);
+		const persistence = spec.delivery === "caller" ? this.ctx.get("sessionPersistence") : this.requirePersistence();
+		assertSubagentMaxDepth(request.maxDepth);
+		const childId = spec.childId ?? brandString(randomUUID());
+		this.assertChildIdAvailable(childId);
+		const childDepth = resolveChildDepth(parent, request.maxDepth);
+		const agentOptions = resolveChildAgentOptions(parent, request.agentOptions, childDepth);
+		const agentProvider = agentOptions.provider;
+		const agentModel = agentOptions.model;
+		const agentReasoningEffort = agentOptions.reasoningEffort;
+		const descriptor = snapshotSubagentDescriptor({
+			mode: "continuable",
+			provider: spec.provider,
+			label: spec.label,
+			...agentProvider !== void 0 ? { agentProvider } : {},
+			...agentModel !== void 0 ? { agentModel } : {},
+			...agentReasoningEffort !== void 0 ? { agentReasoningEffort } : {},
+			...request.persona !== void 0 ? { persona: request.persona } : {},
+			...request.toolFilter !== void 0 ? { toolFilter: request.toolFilter } : {}
+		});
+		const delegatedPolicies = captureDelegatedPolicyOverrides(parent);
+		const releaseHold = this.holdOwnership(parent, childId);
+		try {
+			const cwd = await this.resolveDirectory(request, spec.signal);
+			const prepared = await this.host.prepareContinuable(spec.provider, {
+				sessionId: childId,
+				cwd,
+				parent,
+				signal: spec.signal
+			});
+			spec.signal.throwIfAborted();
+			this.assertAdmitting(parent);
+			const inheritedEventCount = SessionLogOffset(prepared.seed?.length ?? 0);
+			const seed = prepared.seed;
+			let established;
+			const messageId = await this.locks.run(childId, async () => {
+				spec.signal.throwIfAborted();
+				this.assertAdmitting(parent);
+				this.assertChildIdAvailable(childId);
+				if (spec.childId !== void 0) {
+					const persisted = await persistence?.stat(childId, { signal: spec.signal });
+					spec.signal.throwIfAborted();
+					this.assertAdmitting(parent);
+					this.assertChildIdAvailable(childId);
+					if (persisted !== void 0) throw new SubagentError(`subagent "${childId}" already exists`, "DUPLICATE_CHILD");
+				}
+				const activation = await this.materialize({
+					kind: "local",
+					childId,
+					provider: spec.provider,
+					parent,
+					create: {
+						cwd,
+						seed,
+						meta: childSessionMeta(parent, childDepth, prepared.seed !== void 0),
+						inheritedEventCount,
+						delegatedPolicies,
+						descriptor
+					},
+					agentOptions,
+					composition: {
+						persona: request.persona,
+						toolFilter: request.toolFilter
+					},
+					signal: spec.signal,
+					delivery: spec.delivery,
+					outputSchema: spec.request.outputSchema
+				});
+				established = activation;
+				const child = requireLocalActivation(activation).handle.agent;
+				const childHeader = child.session.header;
+				return await this.submitMaterialized(activation, spec.delivery !== "caller" && isAdjacentAgentSendMessageTool(this.ctx.get("tools")?.get("send_message", child)) ? withContinuableReturnGuidance(parent.id, request.prompt) : request.prompt, {
+					source: { kind: "user" },
+					signal: spec.signal,
+					delivery: "queue"
+				}, parent, () => {
+					establishCatalogChild(parent.session, childHeader, descriptor);
+				});
+			});
+			return {
+				...this.receipt(established),
+				childId,
+				messageId
+			};
+		} catch (error) {
+			releaseHold();
+			throw error;
+		}
+	}
+	/**
+	* Start an external backend under activation ownership.
+	* @param spec - task, provider, cancellation, and delivery policy.
+	* @returns the accepted activation and its result/disposal capabilities.
+	*/
+	async startExternal(spec) {
+		const parent = spec.request.parent;
+		this.assertAdmitting(parent);
+		const pendingId = brandString(randomUUID());
+		const releaseHold = this.holdOwnership(parent, pendingId);
+		let activation;
+		try {
+			const cwd = await this.resolveDirectory(spec.request, spec.signal);
+			activation = await this.materialize({
+				kind: "external",
+				childId: pendingId,
+				provider: spec.provider,
+				parent,
+				signal: spec.signal,
+				delivery: spec.delivery,
+				start: (signal) => this.host.startExternal(spec.provider, {
+					...spec.request,
+					cwd,
+					label: spec.label,
+					signal
+				})
+			});
+			this.assertAdmitting(parent);
+			this.assertLiveParent(parent, activation.childId);
+			spec.signal.throwIfAborted();
+			if (spec.delivery === "parent") establishExternalCatalogChild(parent.session, activation.childId, spec.label);
+			this.announce(activation);
+			return this.receipt(activation);
+		} catch (error) {
+			if (activation !== void 0) try {
+				await this.dispose(activation);
+			} catch (cleanupError) {
+				this.ctx.logger.warn(`subagent "${activation.childId}" admission rollback failed: ${failureMessage(cleanupError)}`);
+			}
+			throw error;
+		} finally {
+			releaseHold();
+		}
+	}
+	/** Capture the explicit or inherited directory while the parent still owns startup. */
+	async resolveDirectory(request, signal) {
+		const cwd = request.cwd !== void 0 && isAbsolute(request.cwd) ? request.cwd : resolve(await this.ctx.workingDirectory.ensure(request.parent, signal), request.cwd ?? ".");
+		signal.throwIfAborted();
+		return cwd;
+	}
+	/**
+	* Deliver one model-authored message to a direct continuable child or to the
+	* sender's direct parent. A missing direct child cold-resumes through the
+	* ordinary continuation lifecycle.
+	* @param sender - exact live Agent authorizing and originating the message.
+	* @param targetId - durable direct-parent or direct-child session id.
+	* @param content - model-authored content to deliver.
+	* @param options - caller cancellation before acceptance.
+	* @returns the accepted message's inbox id.
+	*/
+	async sendMessage(sender, targetId, content, options) {
+		if (this.ctx.agents.get(sender.id) !== sender) throw new SubagentError("message delivery requires the exact live sender agent", "UNAUTHORIZED");
+		this.assertAdmitting(sender);
+		const senderActivation = this.resident.get(sender.id);
+		if (senderActivation !== void 0 && senderActivation.kind === "local" && senderActivation.handle.agent === sender && senderActivation.parent.id === targetId) {
+			options.signal.throwIfAborted();
+			return this.sendToParent(senderActivation, sender, content);
+		}
+		if (sender.session.header.parentSession === targetId) throw new SubagentError(`agent "${sender.id}" is not a resident continuable child and cannot send to parent "${targetId}"`, "UNAUTHORIZED");
+		return this.deliverToChild(sender, targetId, content, {
+			signal: options.signal,
+			delivery: "steer"
+		});
+	}
+	/**
+	* Queue one human-authored prompt as a distinct direct-child turn.
+	* @param parent - exact live direct parent authorizing delivery.
+	* @param childId - durable direct-child session id.
+	* @param content - model-visible prompt blocks.
+	* @param source - durable attribution for the human prompt.
+	* @param signal - caller cancellation before inbox acceptance.
+	* @returns the accepted durable message id.
+	*/
+	async queuePrompt(parent, childId, content, source, signal) {
+		return this.deliverToChild(parent, childId, content, {
+			source,
+			signal,
+			delivery: "queue"
+		});
+	}
+	/**
+	* Steer one host-authored prompt to a direct continuable child.
+	* @param parent - exact live direct parent authorizing delivery.
+	* @param childId - durable direct-child session id.
+	* @param content - model-visible prompt blocks.
+	* @param source - durable attribution for the host prompt.
+	* @param signal - caller cancellation before inbox acceptance.
+	* @returns the accepted durable message id.
+	*/
+	async steerPrompt(parent, childId, content, source, signal) {
+		return this.deliverToChild(parent, childId, content, {
+			source,
+			signal,
+			delivery: "steer"
+		});
+	}
+	/** Admit local input synchronously before any teardown can begin. */
+	deliver(activation, message, delivery) {
+		if (activation.closing !== void 0) throw new SubagentError("subagent activation is being disposed; the message was not accepted", "ACTIVATION_CLOSING");
+		const local = requireLocalActivation(activation);
+		if (local.structured?.acceptsInput() === false) throw new SubagentError("subagent is submitting or has submitted its structured result; the message was not accepted", "INPUT_CLOSED");
+		if (delivery === "steer") local.handle.agent.steer(message);
+		else local.handle.agent.followup(message);
+	}
+	/**
+	* Reject one child identity already owned by a live Agent or Session.
+	* @param childId - proposed durable child session id.
+	*/
+	assertChildIdAvailable(childId) {
+		if (this.resident.has(childId) || this.ctx.agents.get(childId) !== void 0 || this.ctx.get("sessions")?.get(childId) !== void 0) throw new SubagentError(`subagent "${childId}" already exists`, "DUPLICATE_CHILD");
+	}
+	/**
+	* Pre-register `childId` in a continuation-managed parent's owned set so the
+	* parent cannot settle while a caller is still establishing or resuming that
+	* child. Returns a releaser for the failure path; it removes only a hold
+	* this call added, and leaves ownership in place once a live Activation for
+	* the child exists.
+	* @param parent - the live direct parent the operation is admitted under.
+	* @param childId - the durable child the operation addresses.
+	* @returns the failure-path releaser; a no-op when nothing was added.
+	*/
+	holdOwnership(parent, childId) {
+		const parentActivation = this.resident.get(parent.id);
+		if (parentActivation === void 0 || activationAgent(parentActivation) !== parent) return () => {};
+		if (parentActivation.closing !== void 0) throw new SubagentError(`subagent parent "${parent.id}" is being disposed; the child was not established`, "ACTIVATION_CLOSING");
+		if (parentActivation.ownedChildren.has(childId)) return () => {};
+		parentActivation.ownedChildren.add(childId);
+		return () => {
+			const live = this.resident.get(childId);
+			/* v8 ignore next 4 -- reaching this arm needs another delivery to establish the child
+			* between this operation's failure and its releaser running, which no test can schedule
+			* deterministically: the ownership edge then belongs to that live Activation, so the
+			* conservative keep leaves it for finishDisposal's releaseOwnership. */
+			if (live !== void 0 && live.closing === void 0) return;
+			if (parentActivation.ownedChildren.delete(childId)) this.wake(parentActivation);
+		};
+	}
+	/**
+	* Apply activation admission to a resident parent before delivering input.
+	* @param parent - exact live Agent receiving the message.
+	* @param message - durable user message to deliver.
+	* @param delivery - receiving inbox destination.
+	*/
+	sendWaking(parent, message, delivery) {
+		const parentActivation = this.resident.get(parent.id);
+		if (parentActivation !== void 0 && activationAgent(parentActivation) === parent) {
+			try {
+				this.deliver(parentActivation, message, delivery);
+			} finally {
+				this.wake(parentActivation);
+			}
+			return;
+		}
+		if (delivery === "steer") parent.steer(message);
+		else parent.followup(message);
+	}
+	/**
+	* Reject new admission once the manager or this exact parent tree began draining.
+	* @param agent - exact live Agent whose lineage determines admission.
+	*/
+	assertAdmitting(agent) {
+		const closing = this.closingTeardownFor(agent);
+		if (closing === void 0) return;
+		throw new SubagentError(closing === "manager" ? "subagents are draining; the operation was not admitted" : `subagents below parent "${closing.id}" are draining; the operation was not admitted`, "DRAINING");
+	}
+	/**
+	* Authorize one operation against the durable direct-parent lineage.
+	* @param parent - exact live Agent claiming direct-parent authority.
+	* @param childId - durable child session id addressed by the operation.
+	* @param parentSession - durable direct-parent id recorded by the child.
+	*/
+	authorizeLineage(parent, childId, parentSession) {
+		this.assertLiveParent(parent, childId);
+		if (parentSession !== parent.id) throw new SubagentError(`subagent "${childId}" belongs to another parent session`, "UNAUTHORIZED");
+	}
+	/** Reject parent authority after the live registry entry changes. */
+	assertLiveParent(parent, childId) {
+		if (this.ctx.agents.get(parent.id) !== parent) throw new SubagentError(`subagent "${childId}" delivery requires the exact live parent agent`, "UNAUTHORIZED");
+	}
+	/**
+	* Create or resume one child Agent and publish its Activation.
+	* @param inputs - reconstruction and admission inputs for the residency epoch.
+	* @returns the published process-local Activation.
+	*/
+	materialize(inputs) {
+		this.assertAdmitting(inputs.parent);
+		inputs.signal.throwIfAborted();
+		const lineage = this.liveLineage(inputs.parent);
+		const pool = this.resident.get(inputs.parent.id)?.pool ?? this.rootPool(inputs.parent);
+		const releaseSlot = pool.reserve(this.maxActiveSubagents());
+		const settled = Promise.withResolvers();
+		const controller = new AbortController();
+		const materialization = {
+			lineage,
+			settled: settled.promise,
+			controller
+		};
+		this.materializations.add(materialization);
+		return this.materializeTracked({
+			...inputs,
+			signal: AbortSignal.any([inputs.signal, controller.signal])
+		}, lineage, pool, releaseSlot).catch((error) => {
+			releaseSlot();
+			if (error instanceof Error && error.name === "AbortError") this.assertAdmitting(inputs.parent);
+			throw error;
+		}).finally(() => {
+			this.materializations.delete(materialization);
+			settled.resolve();
+		});
+	}
+	/**
+	* Stop and release one Activation through its memoized close transaction.
+	* @param activation - exact residency epoch to close.
+	* @returns the shared close transaction.
+	*/
+	dispose(activation) {
+		return this.close(activation, () => this.finishDisposal(activation, true));
+	}
+	/** Close admission synchronously and share one release, including startup rollback. */
+	close(activation, release) {
+		if (activation.closing !== void 0) return activation.closing;
+		const completion = Promise.withResolvers();
+		activation.closing = completion.promise;
+		release().then(completion.resolve, completion.reject);
+		return completion.promise;
+	}
+	/** Dispose independent roots and report every branch failure after all settle. */
+	async disposeRoots(roots, failureSubject) {
+		const reasons = (await Promise.all(roots.map(async (activation) => {
+			try {
+				await this.dispose(activation);
+				return;
+			} catch (error) {
+				return error;
+			}
+		}))).filter((failure) => failure !== void 0);
+		if (reasons.length > 0) throw new SubagentError(`subagent teardown failed for ${reasons.length} ${failureSubject}: ` + reasons.map((reason) => failureMessage(reason)).join("; "), "ACTIVATION_TEARDOWN_FAILED");
+	}
+	/** Return the retained member set for one exact scoped-teardown root. */
+	closingMembers(root) {
+		const existing = this.closingScopes.get(root);
+		if (existing !== void 0) return existing;
+		const members = /* @__PURE__ */ new Set();
+		this.closingScopes.set(root, members);
+		return members;
+	}
+	/** Return the exact currently resolvable ancestry from `agent` upward. */
+	liveLineage(agent) {
+		const lineage = [agent];
+		const seen = new Set([agent.id]);
+		let parentSession = agent.session.header.parentSession;
+		while (parentSession !== void 0) {
+			const parent = this.ctx.agents.get(parentSession);
+			if (parent === void 0 || seen.has(parent.id)) break;
+			lineage.push(parent);
+			seen.add(parent.id);
+			parentSession = parent.session.header.parentSession;
+		}
+		return lineage;
+	}
+	/** Return the teardown that closed continuable admission for this agent's lineage. */
+	closingTeardownFor(agent) {
+		if (this.draining) return "manager";
+		const lineage = this.liveLineage(agent);
+		for (const [root, members] of this.closingScopes) if (members.has(agent) || lineage.includes(root)) return root;
+	}
+	/** Resolve a root's pool once; descendants inherit their resident parent's pool directly. */
+	rootPool(parent) {
+		let pool = this.rootPools.get(parent);
+		if (pool === void 0) {
+			pool = new ActivationPool();
+			this.rootPools.set(parent, pool);
+		}
+		return pool;
+	}
+	/** Perform one tracked materialization through publication or rollback. */
+	async materializeTracked(inputs, parentLineage, pool, releaseSlot) {
+		const { provider, parent } = inputs;
+		let childId = inputs.childId;
+		inputs.signal.throwIfAborted();
+		let resource;
+		if (inputs.kind === "external") {
+			const controller = new AbortController();
+			const cancelStartup = () => {
+				controller.abort(inputs.signal.reason);
+			};
+			inputs.signal.addEventListener("abort", cancelStartup, { once: true });
+			try {
+				const run = await inputs.start(controller.signal);
+				resource = {
+					kind: "external",
+					run,
+					controller
+				};
+				run.result.catch(() => void 0);
+				childId = run.id;
+				try {
+					this.assertChildIdAvailable(childId);
+				} catch (error) {
+					await run.dispose();
+					throw error;
+				}
+			} finally {
+				inputs.signal.removeEventListener("abort", cancelStartup);
+			}
+		} else {
+			const { create } = inputs;
+			let structured;
+			const setup = async (childCtx, child) => {
+				if (create !== void 0) {
+					child.session.append("subagent/descriptor", create.descriptor);
+					appendDelegatedPolicyOverrides(child.session, create.delegatedPolicies);
+					const workingDirectory = childCtx.get("workingDirectory");
+					if (workingDirectory === void 0) throw new Error("local subagents require the working-directory service");
+					await workingDirectory.set(child, create.cwd, inputs.signal);
+				}
+				applyChildComposition(childCtx, parent, inputs.composition);
+				if (inputs.outputSchema !== void 0) structured = attachStructuredRuntime(childCtx, inputs.outputSchema, () => this.resident.get(childId)?.ownedChildren.size === 0 && child.inbox.nextStep.length === 0 && child.inbox.nextTurn.length === 0);
+			};
+			const handle = create === void 0 ? await this.ownerCtx.agents.resume({
+				resumeSessionId: childId,
+				parentAgent: parent,
+				agentOptions: inputs.agentOptions,
+				signal: inputs.signal,
+				setup
+			}) : await this.ownerCtx.agents.create({
+				sessionId: childId,
+				parentAgent: parent,
+				meta: create.meta,
+				...create.seed === void 0 ? {} : { seed: create.seed },
+				inheritedEventCount: create.inheritedEventCount,
+				agentOptions: inputs.agentOptions,
+				signal: inputs.signal,
+				setup
+			});
+			resource = {
+				kind: "local",
+				handle,
+				outputStart: handle.agent.session.seq,
+				structured,
+				failureAt: void 0,
+				poke: Promise.withResolvers()
+			};
+		}
+		const observer = this.host.observeActivation(provider, childId, parent);
+		const activation = {
+			pool,
+			releaseSlot,
+			childId,
+			...resource,
+			parent,
+			delivery: inputs.delivery ?? "parent",
+			result: Promise.withResolvers(),
+			closing: void 0,
+			ancestry: new WeakSet(resource.kind === "external" ? parentLineage : [resource.handle.agent, ...parentLineage]),
+			ownedChildren: /* @__PURE__ */ new Set(),
+			observer,
+			announced: false
+		};
+		activation.result.promise.catch(() => void 0);
+		this.resident.set(childId, activation);
+		try {
+			this.assertAdmitting(parent);
+			inputs.signal.throwIfAborted();
+			if (this.ctx.agents.get(parent.id) !== parent) throw new SubagentError("subagent parent is no longer live", "UNAUTHORIZED");
+			this.acquireOwnership(parent, childId);
+			const wakeSettlement = () => {
+				this.wake(activation);
+			};
+			if (activation.kind === "local") {
+				observeLocalFailure(activation, wakeSettlement);
+				activation.handle.agent.ctx.on("agent/inbox/inserted", wakeSettlement);
+				activation.handle.agent.ctx.on("agent/inbox/claimed", wakeSettlement);
+				activation.handle.agent.ctx.on("agent/inbox/discarded", wakeSettlement);
+			}
+			observer.start(activationAgent(activation));
+		} catch (error) {
+			/* v8 ignore next -- rollback failure must not mask the admission failure
+			* that prevented this operation from returning an accepted message id. */
+			await this.rollbackUnpublished(activation, error).catch(() => void 0);
+			throw error;
+		}
+		return activation;
+	}
+	/**
+	* Begin settlement observation after initial acceptance is recorded.
+	* @param activation - accepted activation to observe.
+	*/
+	announce(activation) {
+		if (activation.announced) return;
+		activation.announced = true;
+		if (activation.kind === "local") this.watchLocalSettlement(activation);
+		else {
+			const finish = () => this.close(activation, () => this.finishDisposal(activation, false));
+			activation.run.result.then(finish, finish).catch((error) => {
+				this.reportTeardownFailure(activation, error);
+			});
+		}
+	}
+	/** Release an Activation whose start edge was not published. */
+	rollbackUnpublished(activation, error) {
+		return this.close(activation, async () => {
+			try {
+				await (activation.kind === "local" ? activation.handle.dispose() : activation.run.dispose());
+			} finally {
+				this.resident.delete(activation.childId);
+				activation.releaseSlot();
+				this.releaseOwnership(activation.childId);
+				activation.result.reject(error);
+			}
+		});
+	}
+	/** Register the child in a continuation-managed parent's owned set. */
+	acquireOwnership(parent, childId) {
+		const parentActivation = this.resident.get(parent.id);
+		if (parentActivation === void 0) return;
+		if (parentActivation.closing !== void 0) throw new SubagentError(`subagent parent "${parent.id}" is being disposed; the child was not established`, "ACTIVATION_CLOSING");
+		parentActivation.ownedChildren.add(childId);
+		this.wake(parentActivation);
+	}
+	/** Remove one child from its live owner's set and let that owner re-check settlement. */
+	releaseOwnership(childId) {
+		for (const candidate of this.resident.values()) if (candidate.ownedChildren.delete(childId)) this.wake(candidate);
+	}
+	/** Let a settlement watcher re-check residency after relevant state changes. */
+	wake(activation) {
+		if (activation.kind === "external") return;
+		activation.poke.resolve();
+		activation.poke = Promise.withResolvers();
+	}
+	/** Follow one Activation to natural settlement. */
+	watchLocalSettlement(activation) {
+		(async () => {
+			while (true) {
+				const idleObservation = activation.poke;
+				await activation.handle.agent.whenIdle();
+				if (activation.closing !== void 0) return;
+				const readiness = await this.locks.run(activation.childId, () => Promise.resolve(this.settlementState(activation, idleObservation)));
+				if (readiness === "closed") return;
+				if (readiness === "retry") continue;
+				if (readiness === "wait") {
+					await idleObservation.promise;
+					continue;
+				}
+				const finalSeq = activation.handle.agent.session.seq;
+				await this.flushFinalState(activation);
+				const attempt = await this.locks.run(activation.childId, () => {
+					const state = this.settlementState(activation, idleObservation);
+					if (state !== "ready") return Promise.resolve(state);
+					if (activation.handle.agent.session.seq !== finalSeq) return Promise.resolve("retry");
+					let done;
+					try {
+						activation.handle.agent.runMaintenance(() => {
+							done = this.close(activation, () => this.finishDisposal(activation, false));
+							return Promise.resolve();
+						});
+					} catch (_error) {
+						return Promise.resolve("retry");
+					}
+					return Promise.resolve({ done });
+				});
+				if (typeof attempt === "string") {
+					if (attempt === "closed") return;
+					continue;
+				}
+				try {
+					await attempt.done;
+				} catch (error) {
+					this.reportTeardownFailure(activation, error);
+				}
+				return;
+			}
+		})();
+	}
+	/** Report disposal failure once after the natural settlement observer finishes. */
+	reportTeardownFailure(activation, error) {
+		this.ctx.logger.warn(`subagent "${activation.childId}" activation teardown failed: ${failureMessage(error)}`);
+	}
+	/** Check pending input and owned children before closing admission. */
+	settlementState(activation, observation) {
+		if (activation.closing !== void 0) return "closed";
+		if (activation.poke !== observation) return "retry";
+		const inbox = activation.handle.agent.inbox;
+		if (activation.ownedChildren.size > 0) return "wait";
+		if (activation.failureAt === void 0 && (inbox.nextTurn.length > 0 || inbox.nextStep.length > 0)) return "wait";
+		return "ready";
+	}
+	/** Propagate stop synchronously and await descendant startup rollback before release. */
+	async finishDisposal(activation, stop) {
+		this.wake(activation);
+		const { childId } = activation;
+		const failures = [];
+		let result = {
+			output: [],
+			stopReason: "error"
+		};
+		let resultFailure;
+		let externalDisposal;
+		const child = activationAgent(activation);
+		const detail = (error) => child === void 0 ? failureMessage(error) : errorChain(error);
+		try {
+			if (activation.kind === "external") {
+				if (stop) {
+					activation.controller.abort({ kind: "parent" });
+					externalDisposal = Promise.resolve().then(() => activation.run.dispose());
+					externalDisposal.catch(() => void 0);
+				}
+				result = await activation.run.result;
+			} else {
+				if (stop) {
+					activation.handle.agent.cancel({ kind: "parent" });
+					const idle = activation.handle.agent.whenIdle();
+					const children = [...activation.ownedChildren].map((child) => this.resident.get(child)).filter((child) => child !== void 0);
+					const pending = [...this.materializations].filter((item) => item.lineage.includes(activation.handle.agent));
+					const childDisposals = children.map((child) => this.dispose(child));
+					for (const item of pending) item.controller.abort();
+					childDisposals.push(...pending.map((item) => item.settled));
+					const reasons = (await Promise.all(childDisposals.map(async (disposal) => {
+						try {
+							await disposal;
+							return;
+						} catch (error) {
+							return error;
+						}
+					}))).filter((reason) => reason !== void 0);
+					if (reasons.length > 0) failures.push(new SubagentError(`subagent "${childId}" child teardown failed: ${reasons.map((reason) => failureMessage(reason)).join("; ")}`, "ACTIVATION_TEARDOWN_FAILED"));
+					await idle;
+					await this.flushFinalState(activation);
+				}
+				result = captureLocalResult(activation);
+			}
+		} catch (error) {
+			resultFailure = { error };
+			failures.push(new SubagentError(`subagent "${childId}" activation teardown failed: ${detail(error)}`, "ACTIVATION_TEARDOWN_FAILED", { cause: error }));
+		}
+		try {
+			if (activation.kind === "local") await activation.handle.dispose();
+			else await (externalDisposal ?? activation.run.dispose());
+		} catch (error) {
+			failures.push(new SubagentError(`subagent "${childId}" activation handle disposal failed: ${detail(error)}`, "ACTIVATION_TEARDOWN_FAILED", { cause: error }));
+		}
+		let failure;
+		if (failures.length === 1) failure = failures[0];
+		else if (failures.length > 1) failure = new SubagentError(`subagent "${childId}" activation teardown failed at ${failures.length} boundaries: ` + failures.map((item) => detail(item)).join("; "), "ACTIVATION_TEARDOWN_FAILED", { cause: new AggregateError(failures) });
+		this.resident.delete(childId);
+		activation.releaseSlot();
+		const terminal = failure === void 0 ? result : {
+			output: [],
+			stopReason: "error"
+		};
+		this.notifySettlement(activation, result);
+		this.releaseOwnership(childId);
+		activation.observer.settle(terminal);
+		if (resultFailure === void 0) activation.result.resolve(result);
+		else activation.result.reject(resultFailure.error);
+		if (failure !== void 0) throw failure;
+	}
+	/** Deliver the captured execution result to the durable direct parent after cleanup. */
+	notifySettlement(activation, terminal) {
+		if (!activation.announced || activation.delivery === "caller") return;
+		try {
+			const parent = this.ctx.agents.get(activation.parent.id);
+			if (parent !== activation.parent) return;
+			const message = createSettlementMessage(activation.childId, terminal, activationAgent(activation) !== void 0);
+			if (this.closingTeardownFor(parent) !== void 0) {
+				parent.inject(message);
+				return;
+			}
+			this.sendWaking(parent, message, parent.status === "idle" ? "queue" : "steer");
+		} catch (error) {
+			this.ctx.logger.warn(`subagent "${activation.childId}" settlement notice was not delivered to its parent: ` + errorChain(error));
+		}
+	}
+	/** Request a best-effort final session flush before closing natural-settlement admission. */
+	async flushFinalState(activation) {
+		try {
+			await activation.handle.agent.ctx.sessions.flush(activation.handle.agent.session);
+		} catch (error) {
+			this.ctx.logger.warn(`subagent "${activation.childId}" best-effort final session flush failed; the persisted state may be unavailable or stale on resume: ${errorChain(error)}`);
+		}
+	}
+	/** Return capabilities bound to an exact activation instead of a future same-id instance. */
+	receipt(activation) {
+		return {
+			childId: activation.childId,
+			result: activation.result.promise,
+			dispose: () => this.dispose(activation)
+		};
+	}
+	/** Route one parent-originated delivery through residency and cold resume. */
+	async deliverToChild(parent, childId, content, options) {
+		this.assertAdmitting(parent);
+		const releaseHold = this.holdOwnership(parent, childId);
+		try {
+			return await this.deliverFollowup(parent, childId, content, options);
+		} catch (error) {
+			releaseHold();
+			throw error;
+		}
+	}
+	/** The delivery loop behind {@link deliverToChild}, run under the parent hold. */
+	async deliverFollowup(parent, childId, content, options) {
+		while (true) {
+			const live = await this.locks.run(childId, async () => {
+				const activation = this.resident.get(childId);
+				if (activation === void 0) return this.coldResume(parent, childId, content, options);
+				requireLocalActivation(activation);
+				const disposal = activation.closing;
+				/* v8 ignore next 3 -- the send-versus-dispose cutoff needs a delivery to
+				* observe the transaction inside the same critical section that opened it. */
+				if (disposal !== void 0) return disposal.then(() => void 0, () => void 0);
+				if (contentHasImage(content)) {
+					await this.assertImageCapable(requireLocalActivation(activation).handle.agent, options.signal);
+					if (activation.closing !== void 0) {
+						await Promise.allSettled([activation.closing]);
+						return;
+					}
+				}
+				const messageId = this.submitAdmitted(activation, content, options, parent);
+				this.announce(activation);
+				return messageId;
+			});
+			/* v8 ignore start -- only a delivery that lost the disposal cutoff retries. */
+			if (live !== void 0) return live;
+			this.assertAdmitting(parent);
+			options.signal.throwIfAborted();
+		}
+	}
+	/** Deliver one resident continuable child's message to its live direct parent. */
+	sendToParent(activation, sender, content) {
+		/* v8 ignore next 6 -- only synchronous re-entrant teardown can open this
+		* transaction between exact-agent authorization and this no-await span. */
+		if (activation.closing !== void 0) throw new SubagentError(`subagent "${sender.id}" activation is being disposed; the message was not delivered`, "ACTIVATION_CLOSING");
+		const parent = this.ctx.agents.get(activation.parent.id);
+		if (parent !== activation.parent) throw new SubagentError("direct parent is not live; the message was not delivered", "PARENT_UNAVAILABLE");
+		const message = createAgentMessage(sender, content);
+		this.sendAgentMessage(parent, message);
+		return message.id;
+	}
+	/** Send one Agent message while translating only the target's own rejection. */
+	sendAgentMessage(parent, message) {
+		try {
+			this.sendWaking(parent, message, "steer");
+		} catch (error) {
+			throw new SubagentError("direct parent is not live; the message was not delivered", "PARENT_UNAVAILABLE", { cause: error });
+		}
+	}
+	/**
+	* Cold-resume a persisted child and submit the waiting turn. The descriptor
+	* supplies every reconstruction input; no subagent provider is dispatched.
+	*/
+	async coldResume(parent, childId, content, options) {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			const query = this.requireSessionQuery();
+			let observation;
+			try {
+				observation = await query.observeSession(childId, { signal: options.signal });
+			} catch (error) {
+				options.signal.throwIfAborted();
+				throw new SubagentError(`subagent "${childId}" is unavailable`, "NOT_RESUMABLE", { cause: error });
+			}
+			const source = __addDisposableResource$2(env_1, observation, false);
+			this.assertAdmitting(parent);
+			this.authorizeLineage(parent, childId, source.header.parentSession);
+			const descriptor = foldSubagentDescriptor(source.events.slice(source.inheritedEventCount));
+			if (descriptor === void 0 || descriptor.mode !== "continuable") throw new SubagentError(`subagent "${childId}" has no supported continuation state and cannot be resumed; choose a different target`, "NOT_RESUMABLE");
+			let activation;
+			try {
+				activation = await this.materialize({
+					kind: "local",
+					childId,
+					provider: descriptor.provider,
+					parent,
+					agentOptions: {
+						...descriptor.agentProvider !== void 0 ? { provider: descriptor.agentProvider } : {},
+						...descriptor.agentModel !== void 0 ? { model: descriptor.agentModel } : {},
+						...descriptor.agentReasoningEffort !== void 0 ? { reasoningEffort: ReasoningEffortId(descriptor.agentReasoningEffort) } : {}
+					},
+					composition: {
+						persona: descriptor.persona,
+						toolFilter: descriptor.toolFilter
+					},
+					signal: options.signal
+				});
+			} catch (error) {
+				options.signal.throwIfAborted();
+				if (error instanceof SubagentError) throw error;
+				throw new SubagentError(`subagent "${childId}" is unavailable`, "NOT_RESUMABLE", { cause: error });
+			}
+			return await this.submitMaterialized(activation, content, options, parent);
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources$2(env_1);
+		}
+	}
+	/** Admit a materialized child, commit its creation fact, and release it on failure. */
+	async submitMaterialized(activation, content, options, parent, commit) {
+		try {
+			if (contentHasImage(content)) {
+				await this.assertImageCapable(requireLocalActivation(activation).handle.agent, options.signal);
+				if (activation.closing !== void 0) throw new SubagentError(`subagent "${activation.childId}" is closing`, "ACTIVATION_CLOSING");
+			}
+			const messageId = this.submitAdmitted(activation, content, options, parent);
+			commit?.();
+			this.announce(activation);
+			return messageId;
+		} catch (error) {
+			try {
+				await this.dispose(activation);
+			} catch (cleanupError) {
+				this.ctx.logger.warn(`subagent continuation: disposal after admission or catalog append failure also failed: ${String(cleanupError)}`);
+			}
+			throw error;
+		}
+	}
+	/** Build and submit one message across the final synchronous admission cutoff. */
+	submitAdmitted(activation, content, options, parent) {
+		const message = options.source === void 0 ? createAgentMessage(parent, content) : createUserMessage({
+			content,
+			source: options.source
+		});
+		options.signal.throwIfAborted();
+		this.assertAdmitting(parent);
+		this.authorizeLineage(parent, activation.childId, activation.parent.id);
+		this.acquireOwnership(parent, activation.childId);
+		try {
+			this.deliver(activation, message, options.delivery);
+		} finally {
+			this.wake(activation);
+		}
+		return message.id;
+	}
+	/** Refuse image content for a child whose fixed model accepts text only. */
+	async assertImageCapable(agent, signal) {
+		const { provider, model } = agent.options;
+		if (provider === void 0 || model === void 0) return;
+		const llm = this.ctx.get("llm");
+		/* v8 ignore next -- without an LLM registry, delivery defers to projection. */
+		if (llm === void 0) return;
+		const info = await llm.resolveModelInfo(provider, model, signal);
+		if (info.inputModalities !== void 0 && !info.inputModalities.includes("image")) throw new SubagentError(`Model "${model}" does not support image input.`, "MODEL_DOES_NOT_SUPPORT_IMAGES");
+	}
+	/** Resolve the persistence service continuable children require, or fail loud. */
+	requirePersistence() {
+		const persistence = this.ctx.get("sessionPersistence");
+		if (persistence === void 0) throw new SubagentError("continuable subagents require session persistence (load a dsh-session-persistence backend)", "PERSISTENCE_UNAVAILABLE");
+		return persistence;
+	}
+	/** Resolve the Session query service used for cold child observations. */
+	requireSessionQuery() {
+		const query = this.ctx.get("sessionQuery");
+		if (query === void 0) throw new SubagentError("continuable subagents require session query (load @qlzt/dsh-session-query)", "CONTINUATION_UNAVAILABLE");
+		return query;
+	}
+};
+//#endregion
+//#region lib/types/list-children.js
+/**
+* Direct-child and recursive descendant discovery from parent-owned catalogs.
+* Each catalog read releases its Session observation before the next branch.
+* @module @qlzt/dsh-subagent
+*/
+var __addDisposableResource$1 = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources$1 = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/**
+* Read one parent's durable catalog through a live-preferred Session observation.
+* @param ctx - context carrying the Session query service.
+* @param parentSessionId - parent whose direct children are requested.
+* @param signal - cancellation forwarded to the Session observation.
+* @returns direct-child rows in parent catalog event order.
+* @throws {@link SubagentError} when query or catalog projection is unavailable.
+*/
+async function listChildren(ctx, parentSessionId, signal) {
+	const env_1 = {
+		stack: [],
+		error: void 0,
+		hasError: false
+	};
+	try {
+		const query = ctx.get("sessionQuery");
+		if (query === void 0) throw new SubagentError("listing subagents requires the sessionQuery service (load @qlzt/dsh-session-query)", "SUBAGENT_CONTROL_QUERY_UNAVAILABLE");
+		const entries = __addDisposableResource$1(env_1, await query.observeSession(parentSessionId, { ...signal === void 0 ? {} : { signal } }), false).projections?.values.subagentCatalog;
+		if (entries === void 0) throw new SubagentError("listing subagents requires the registered subagentCatalog projection", "SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE");
+		return entries;
+	} catch (e_1) {
+		env_1.error = e_1;
+		env_1.hasError = true;
+	} finally {
+		__disposeResources$1(env_1);
+	}
+}
+/**
+* Walk reachable parent catalogs in stable pre-order without loading Agents.
+* @see SubagentRuntime.listDescendants for failure and cancellation semantics.
+* @param ctx - context carrying the Session store and query service.
+* @param rootSessionId - parent whose catalog starts the traversal.
+* @param signal - cancellation checked around each catalog read.
+* @returns children and branch diagnostics with catalog parent and depth.
+*/
+async function listDescendants(ctx, rootSessionId, signal) {
+	const sessions = ctx.get("sessions");
+	if (sessions === void 0) throw new SubagentError("listing subagents requires the session store (load @qlzt/dsh-session)", "SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE");
+	const readChildren = async (id) => {
+		assertListingNotCancelled(signal);
+		let children;
+		try {
+			children = await listChildren(ctx, id, signal);
+		} catch (error) {
+			assertListingNotCancelled(signal);
+			throw error;
+		}
+		assertListingNotCancelled(signal);
+		return children;
+	};
+	const stack = (await readChildren(rootSessionId)).map((entry) => ({
+		entry,
+		parentId: rootSessionId,
+		depth: 1
+	})).reverse();
+	const visited = new Set([rootSessionId]);
+	const result = [];
+	for (let position = stack.pop(); position !== void 0; position = stack.pop()) {
+		const { entry, parentId, depth } = position;
+		if (visited.has(entry.id)) continue;
+		visited.add(entry.id);
+		let children;
+		try {
+			children = entry.mode === "external" ? [] : await readChildren(entry.id);
+		} catch (error) {
+			if (error instanceof SubagentError) throw error;
+			const code = error instanceof Error && "code" in error ? error.code : void 0;
+			result.push({
+				kind: "diagnostic",
+				id: entry.id,
+				parentId,
+				depth,
+				reason: code === "SESSION_QUERY_CORRUPT_SESSION" || code === "SESSION_QUERY_SOURCE_CONFLICT" ? "corrupt" : "unavailable"
+			});
+			continue;
+		}
+		if (entry.mode === "unknown") result.push({
+			kind: "diagnostic",
+			id: entry.id,
+			parentId,
+			depth,
+			reason: "unsupported"
+		});
+		else {
+			const { createdAt: _createdAt, ...identity } = entry;
+			result.push({
+				...identity,
+				kind: "child",
+				parentId,
+				depth,
+				activity: sessions.get(entry.id) === void 0 ? "inactive" : "running",
+				hasChildren: children.length > 0
+			});
+		}
+		for (const child of [...children].reverse()) stack.push({
+			entry: child,
+			parentId: entry.id,
+			depth: depth + 1
+		});
+	}
+	return result;
+}
+/** Stop the complete traversal when its caller cancels. */
+function assertListingNotCancelled(signal) {
+	if (signal?.aborted) throw new SubagentError("subagent listing was cancelled", "CANCELLED");
+}
+//#endregion
+//#region lib/types/archive-admission.js
+/**
+* The `subagent` family of the Workspace registry's archive admission: which
+* subagent descendants of a Session are still inside a turn, and how they
+* stop when the Session is archived with its work.
+*
+* @module @qlzt/dsh-subagent
+*/
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/**
+* Answer `workspace/session-activity` with the running subagent descendants of
+* the asked Session, and `workspace/session-stop` by cancelling each of them
+* as their parent would. Both listeners live as long as `ctx`'s fiber.
+* @param ctx - context carrying the Agent registry; the Session query service is optional and only supplies labels.
+*/
+function installSubagentArchiveAdmission(ctx) {
+	ctx.on("workspace/session-activity", async ({ sessionId }, next) => {
+		const running = runningDescendants(ctx, sessionId);
+		const rest = await next();
+		if (running.length === 0) return rest;
+		return [{
+			kind: "subagent",
+			items: await Promise.all(running.map((child) => describe(ctx, child)))
+		}, ...rest];
+	});
+	ctx.on("workspace/session-stop", ({ sessionId }) => {
+		for (const child of runningDescendants(ctx, sessionId)) try {
+			child.cancel({ kind: "parent" });
+		} catch (error) {
+			ctx.logger.warn(`subagent: cancelling "${child.id}" for an archived Session failed: ${String(error)}`);
+		}
+	});
+}
+/**
+* Live subagent descendants inside a turn, by durable lineage: a child whose
+* header names its parent and carries the subagent origin this package
+* records, at any depth. A fork shares the lineage field without the origin
+* and is an independent conversation, so it never holds its source. Lineage
+* is read as data, so a damaged header chain that loops is visited once.
+*/
+function runningDescendants(ctx, rootId) {
+	const childrenOf = /* @__PURE__ */ new Map();
+	for (const agent of ctx.agents.list()) {
+		const { parentSession, origin } = agent.session.header;
+		if (parentSession === void 0 || origin !== "subagent") continue;
+		const siblings = childrenOf.get(parentSession) ?? [];
+		siblings.push(agent);
+		childrenOf.set(parentSession, siblings);
+	}
+	const running = [];
+	const pending = [rootId];
+	const visited = /* @__PURE__ */ new Set();
+	while (pending.length > 0) {
+		const parentId = pending.shift();
+		if (visited.has(parentId)) continue;
+		visited.add(parentId);
+		for (const child of childrenOf.get(parentId) ?? []) {
+			if (child.status === "running") running.push(child);
+			pending.push(child.id);
+		}
+	}
+	return running;
+}
+/**
+* The child's activity item: its id, plus the durable creation label its
+* descriptor carries, read through a live Session observation. Without the
+* Session query service, or with a descriptor that is absent or unreadable,
+* the item names the child by id alone.
+*/
+async function describe(ctx, child) {
+	const query = ctx.get("sessionQuery");
+	if (query === void 0) return { id: child.id };
+	try {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			const observation = __addDisposableResource(env_1, await query.observeSession(child.id, { projectionMode: "none" }), false);
+			const label = foldSubagentDescriptor(observation.events.slice(observation.inheritedEventCount))?.label;
+			return label === void 0 ? { id: child.id } : {
+				id: child.id,
+				label
+			};
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources(env_1);
+		}
+	} catch {
+		return { id: child.id };
+	}
+}
+//#endregion
+//#region lib/types/projection.js
+/**
+* Pure session projections for subagent identity (mode/label) and active-turn
+* duration.
+*
+* @module @qlzt/dsh-subagent/projection
+*/
+const activeIntervalSchema = z$1.object({
+	since: z$1.number().int().nonnegative(),
+	through: z$1.number().int().nonnegative()
+}).strict();
+const projectionSchema = z$1.object({
+	settledMs: z$1.number().int().nonnegative(),
+	active: activeIntervalSchema.optional(),
+	lastTurnCompleted: z$1.boolean().optional()
+}).strict().transform(({ settledMs, active, lastTurnCompleted }) => ({
+	settledMs,
+	...active === void 0 ? {} : { active },
+	...lastTurnCompleted === void 0 ? {} : { lastTurnCompleted }
+}));
+/**
+* Fold turn boundaries around the child's own durable descriptor.
+*
+* A fork seed may contain an ancestor descriptor and completed turns. Every
+* descriptor therefore resets the accumulated state; the healthy catalog
+* admits only a child with exactly one descriptor in its own suffix, making
+* the final reset the child's authoritative timing origin.
+*/
+const subagentTimingProjectionDefinition = {
+	key: "subagentTiming",
+	stateSchema: z$1.object({
+		settledMs: z$1.number().int().nonnegative(),
+		active: activeIntervalSchema.optional(),
+		pendingTurnStart: z$1.number().int().nonnegative().optional(),
+		descriptorSeen: z$1.boolean(),
+		lastTurnCompleted: z$1.boolean().optional()
+	}).strict(),
+	init: () => ({
+		descriptorSeen: false,
+		settledMs: 0
+	}),
+	apply: (state, event) => {
+		if (event.type === "turn/start") {
+			const { lastTurnCompleted: _closed, ...openState } = state;
+			return state.descriptorSeen ? {
+				...openState,
+				active: {
+					since: event.time,
+					through: event.time
+				}
+			} : {
+				...openState,
+				pendingTurnStart: event.time
+			};
+		}
+		if (event.type === "subagent/descriptor") {
+			const activeSince = state.active?.since ?? state.pendingTurnStart;
+			return {
+				descriptorSeen: true,
+				settledMs: 0,
+				...activeSince === void 0 ? {} : { active: {
+					since: activeSince,
+					through: event.time
+				} }
+			};
+		}
+		if (event.type === "turn/end") {
+			if (!state.descriptorSeen) {
+				if (state.pendingTurnStart === void 0) return state;
+				const { pendingTurnStart: _closed, ...next } = state;
+				return next;
+			}
+			if (state.active === void 0) return state;
+			const { active, ...rest } = state;
+			return {
+				...rest,
+				settledMs: state.settledMs + Math.max(0, event.time - active.since),
+				lastTurnCompleted: event.data.reason.kind === "completed"
+			};
+		}
+		if (state.active === void 0) return state;
+		return {
+			...state,
+			active: {
+				...state.active,
+				through: event.time
+			}
+		};
+	},
+	wire: {
+		viewSchema: projectionSchema,
+		view: (state) => ({
+			settledMs: state.settledMs,
+			...state.active === void 0 ? {} : { active: state.active },
+			...state.lastTurnCompleted === void 0 ? {} : { lastTurnCompleted: state.lastTurnCompleted }
+		})
+	},
+	stateVersion: 3
+};
+const identityValueSchema = z$1.discriminatedUnion("mode", [z$1.object({
+	mode: z$1.literal("one-shot"),
+	label: z$1.string().optional(),
+	seq: z$1.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq)
+}).strict(), z$1.object({
+	mode: z$1.literal("continuable"),
+	label: z$1.string(),
+	seq: z$1.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq)
+}).strict()]);
+const identitySchema = identityValueSchema.nullable();
+const identityStateSchema = z$1.object({ identity: identityValueSchema.optional() }).strict();
+/** Interpret one `subagent/descriptor` event's identity; no value when the payload cannot be trusted. */
+function descriptorIdentity(event) {
+	let descriptor;
+	try {
+		descriptor = foldSubagentDescriptor([event]);
+	} catch {
+		descriptor = void 0;
+	}
+	if (descriptor === void 0) return void 0;
+	return descriptor.mode === "one-shot" ? {
+		mode: "one-shot",
+		...descriptor.label !== void 0 ? { label: descriptor.label } : {},
+		seq: event.seq
+	} : {
+		mode: "continuable",
+		label: descriptor.label,
+		seq: event.seq
+	};
+}
+/**
+* Fold the durable mode/label identity from `subagent/descriptor` events,
+* last-wins: a fork seed may replay an ancestor's descriptor, and the child's
+* own descriptor must override it — the same reset discipline as
+* {@link subagentTimingProjectionDefinition}. A malformed or unknown-version
+* payload resets to the `null` sentinel instead of throwing, so a fork of a
+* healthy ancestor never inherits an identity its own descriptor failed to
+* establish — and the reset survives every JSON push frame, so a consumer
+* holding the earlier identity replaces it instead of keeping it stale;
+* `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
+*/
+const subagentIdentityProjectionDefinition = {
+	key: "subagent",
+	stateSchema: identityStateSchema,
+	init: () => ({}),
+	apply: (state, event) => {
+		if (event.type !== "subagent/descriptor") return state;
+		const identity = descriptorIdentity(event);
+		return identity === void 0 ? {} : { identity };
+	},
+	wire: {
+		viewSchema: identitySchema,
+		view: (state) => state.identity ?? null
+	},
+	stateVersion: 2
+};
+//#endregion
+//#region lib/types/out-of-process.js
+/**
+* Provider-side vocabulary for OUT-OF-PROCESS subagent backends — the pieces
+* that enforce this seam's own contracts around a child in another process:
+* the no-capabilities advertisement, timing-bound validation, child
+* working-directory validation, the never-reject result settlement, and the standard
+* run-handle publication. Backends compose these with their own wire drivers;
+* the process machinery itself (spawn, env scrub, managed-range teardown)
+* belongs to the `dsh-subprocess` seam.
+*
+* @module @qlzt/dsh-subagent/out-of-process
+*/
+/** Maximum UTF-8 size of {@link SubagentResult.diagnostic}. */
+const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4096;
+const DIAGNOSTIC_TRUNCATION_SUFFIX = "\n[diagnostic truncated]";
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+/**
+* Limit provider-authored failure detail without splitting a UTF-8 sequence.
+* @param diagnostic - safe diagnostic text produced by the provider.
+* @returns the original text, or a visibly truncated value within the limit.
+*/
+function limitSubagentDiagnostic(diagnostic) {
+	const bytes = utf8Encoder.encode(diagnostic);
+	if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES) return diagnostic;
+	let prefixBytes = MAX_SUBAGENT_DIAGNOSTIC_BYTES - utf8Encoder.encode(DIAGNOSTIC_TRUNCATION_SUFFIX).byteLength;
+	while ((bytes[prefixBytes] & 192) === 128) prefixBytes -= 1;
+	return utf8Decoder.decode(bytes.subarray(0, prefixBytes)) + DIAGNOSTIC_TRUNCATION_SUFFIX;
+}
+/** Enforce the byte limit on a provider-returned diagnostic. */
+function normalizeSubagentDiagnostic(result) {
+	return result.diagnostic === void 0 ? result : {
+		...result,
+		diagnostic: limitSubagentDiagnostic(result.diagnostic)
+	};
+}
+/**
+* The capability advertisement of an out-of-process backend: NONE. A child in
+* another process cannot honor parent-enforced start features
+* (`agentOptions`/`outputSchema`/`maxDepth`/`toolFilter`/`persona`), so the service rejects a
+* request needing any of them before `start` runs — never accepted-then-ignored.
+*/
+const NO_START_CAPABILITIES = Object.freeze({
+	agentOptions: false,
+	outputSchema: false,
+	depthLimit: false,
+	toolFilter: false,
+	persona: false
+});
+/**
+* Assert a configured timing bound is a positive finite number (it bounds a
+* teardown or shutdown wait; zero, negative, or NaN would skip or wedge it).
+* @param prefix - the consuming plugin's diagnostic prefix (e.g. `subagent-acp`).
+* @param name - the config field name, for the diagnostic.
+* @param value - the configured value.
+*/
+function assertPositiveFinite(prefix, name, value) {
+	if (!Number.isFinite(value) || value <= 0) throw new Error(`${prefix}: ${name} must be a positive finite number`);
+}
+/**
+* Whether `path` names an existing directory the harness can ENTER. The
+* search-permission probe matters: `statSync().isDirectory()` is true for a
+* mode-600 directory, but a subprocess cwd needs `X_OK` or spawn fails EACCES.
+*/
+function isEnterableDirectory(path) {
+	try {
+		if (!statSync(path).isDirectory()) return false;
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Assert `cwd` can actually host the child: absolute (it doubles as the
+* child's workspace identity, and a relative path would be re-anchored to the
+* server process's launch directory) and an existing directory (fail here,
+* before the process boundary, instead of as an ambiguous spawn ENOENT).
+* @param prefix - the consuming plugin's diagnostic prefix.
+* @param label - which source supplied the value, for the diagnostic.
+* @param cwd - the candidate working directory.
+* @returns `cwd`, validated.
+*/
+function assertUsableCwd(prefix, label, cwd) {
+	if (!isAbsolute(cwd)) throw new Error(`${prefix}: ${label} must be an absolute path: ${cwd}`);
+	if (!isEnterableDirectory(cwd)) throw new Error(`${prefix}: ${label} is not an accessible directory: ${cwd}`);
+	return cwd;
+}
+/** Normalize an unknown thrown value to an Error (the catch binding is `unknown`). */
+function toError(value) {
+	/* v8 ignore next */
+	return value instanceof Error ? value : new Error(String(value));
+}
+/**
+* Settle an out-of-process run result under the seam contract: `result` never
+* rejects after publication. A normally completed or rejected attempt resolves
+* as `aborted` when cancellation already settled locally; another rejection is
+* flattened to `stopReason: 'error'` through the contained diagnostic sink.
+* Provider-returned diagnostics use the same byte limit. The abort listener is
+* removed on every path.
+* @param parts - the attempt, output snapshot, cancellation state, sink, and signal wiring.
+* @returns the terminal result (never a rejection).
+*/
+async function settleRunResult(parts) {
+	try {
+		const result = await parts.attempt();
+		return parts.cancelled() ? {
+			output: parts.collectOutput(),
+			stopReason: "aborted"
+		} : normalizeSubagentDiagnostic(result);
+	} catch (error) {
+		if (parts.cancelled()) return {
+			output: parts.collectOutput(),
+			stopReason: "aborted"
+		};
+		try {
+			parts.onError?.(toError(error), "error");
+		} catch {}
+		const collected = parts.collectDiagnostic?.();
+		const diagnostic = collected === void 0 ? void 0 : limitSubagentDiagnostic(collected);
+		return {
+			output: parts.collectOutput(),
+			...diagnostic === void 0 ? {} : { diagnostic },
+			stopReason: "error"
+		};
+	} finally {
+		parts.signal.removeEventListener("abort", parts.onAbort);
+	}
+}
+/**
+* Publish the seam run handle for an out-of-process child. `dispose()` is
+* idempotent (one memoized teardown): it removes the abort listener, settles
+* local cancellation — there is no assumption the child cooperates — and then
+* awaits the backend's teardown to actual exit.
+* @param parts - the run identity, result, cancellation wiring, and teardown.
+* @returns the external run handle.
+*/
+function subprocessRunHandle(parts) {
+	let disposal;
+	return {
+		id: parts.id,
+		result: parts.result,
+		dispose() {
+			if (disposal !== void 0) return disposal;
+			parts.signal.removeEventListener("abort", parts.onAbort);
+			parts.requestCancel();
+			disposal = parts.teardown();
+			return disposal;
+		}
+	};
+}
+//#endregion
+//#region lib/types/index.js
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) if (kind === "field") initializers.unshift(_);
+		else descriptor[key] = _;
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+/** Named provider registry with managed activations, durable discovery, and local child messaging. */
+let SubagentRuntime = (() => {
+	let _classSuper = TypertRemoteService;
+	let _instanceExtraInitializers = [];
+	let _prompt_decorators;
+	let _interruptByParent_decorators;
+	return class SubagentRuntime extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_prompt_decorators = [Remote("prompt")];
+			_interruptByParent_decorators = [Remote("interruptByParent")];
+			__esDecorate(this, null, _prompt_decorators, {
+				kind: "method",
+				name: "prompt",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "prompt" in obj,
+					get: (obj) => obj.prompt
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _interruptByParent_decorators, {
+				kind: "method",
+				name: "interruptByParent",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "interruptByParent" in obj,
+					get: (obj) => obj.interruptByParent
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		config = __runInitializers(this, _instanceExtraInitializers);
+		static Config = z.object({
+			maxDepth: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(1).volatile(),
+			maxActiveSubagents: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(8).volatile()
+		});
+		static inject = ["workingDirectory"];
+		providers = /* @__PURE__ */ new Map();
+		manager;
+		/**
+		* The contained lifecycle-edge publisher. Built here because scoped dispatch
+		* keys its carrier by this exact service instance, whose own context filter
+		* composes into the carrier.
+		*/
+		emitLifecycle;
+		constructor(ctx, config) {
+			super(ctx, "subagents");
+			this.config = config;
+			this.emitLifecycle = createLifecycleEmitter(this.ctx, (parent) => scopeTarget(this, parent));
+			ctx.inject(["agents"], (childCtx) => {
+				const manager = new SubagentManager(childCtx, {
+					startExternal: (name, request) => {
+						return this.expectProvider(name).start(request);
+					},
+					prepareContinuable: (name, request) => this.prepareContinuable(name, request),
+					observeActivation: (provider, childId, parent) => this.observeActivation(provider, childId, parent)
+				}, () => this.config.maxActiveSubagents.get());
+				this.manager = manager;
+				childCtx.effect(() => () => {
+					/* v8 ignore else -- one injected binding owns the slot until its fiber disposes. */
+					if (this.manager === manager) this.manager = void 0;
+				}, "subagents.managerBinding()");
+			});
+			ctx.inject(["sessionProjections"], (projectionCtx) => {
+				projectionCtx.sessionProjections.register(subagentCatalogProjectionDefinition);
+				projectionCtx.sessionProjections.register(subagentTimingProjectionDefinition);
+				projectionCtx.sessionProjections.register(subagentIdentityProjectionDefinition);
+			});
+			ctx.inject(["agents"], (agentsCtx) => {
+				installSubagentArchiveAdmission(agentsCtx);
+			});
+		}
+		/**
+		* Resolve a delegation tool's depth policy against the current user setting.
+		* @param configured - Explicit tool limit, or provider-managed for external delegation.
+		* @returns The numeric limit, or undefined when the provider owns depth enforcement.
+		*/
+		resolveMaxDepth(configured) {
+			if (configured === "provider-managed") return void 0;
+			if (configured !== void 0) return configured;
+			const depth = this.config.maxDepth.get();
+			assertSubagentMaxDepth(depth);
+			return depth;
+		}
+		/**
+		* Establish a managed child with backend-specific execution capabilities.
+		* @param spec - task, backend, and result recipient.
+		* @returns identities, execution result, and exact-activation disposal. A reserved
+		* childId requires a local backend and guarantees an accepted messageId.
+		*/
+		async startActivation(spec) {
+			const provider = this.expectProvider(spec.provider);
+			if (spec.childId !== void 0 && provider.prepareContinuable === void 0) throw new SubagentError("reserved child ids require a local backend", "UNSUPPORTED_CAPABILITY");
+			assertSubagentMaxDepth(spec.request.maxDepth);
+			this.assertCapabilities(provider, {
+				...spec.request,
+				signal: spec.signal
+			});
+			const manager = this.requireManager();
+			if (this.ctx.get("agents")?.get(spec.request.parent.id) !== spec.request.parent) throw new SubagentError("subagent creation requires the exact live parent agent", "UNAUTHORIZED");
+			if (spec.request.outputSchema !== void 0) assertObjectJsonSchema(spec.request.outputSchema);
+			return provider.prepareContinuable === void 0 ? manager.startExternal(spec) : manager.startLocal(spec);
+		}
+		/**
+		* Join progressing descendants without cancelling them. Idle descendants whose
+		* inboxes require a later wake stay resident and do not delay host completion.
+		* @param parent - the exact parent whose descendant work is observed.
+		* @returns whether work was joined; hosts recheck parent idle after true.
+		*/
+		async waitForChildren(parent) {
+			return this.manager?.waitForChildren(parent) ?? false;
+		}
+		/**
+		* Steer one model-authored message to the sender's direct parent or direct
+		* continuable child. A running target admits it at the nearest step boundary;
+		* an idle target starts a turn, and an absent direct child cold-resumes from
+		* persistence. The service derives durable sender attribution from the exact
+		* live sender. Caller cancellation stops only pre-acceptance work.
+		* @param sender - exact live Agent authorizing and originating the message.
+		* @param targetId - durable direct-parent or direct-child session id.
+		* @param content - model-authored content to deliver.
+		* @param options - caller cancellation before inbox acceptance.
+		* @returns the accepted message's inbox id.
+		* @throws when continuation services are unavailable, adjacency is rejected,
+		*   or the message was not admitted.
+		*/
+		async sendMessage(sender, targetId, content, options) {
+			return this.requireManager().sendMessage(sender, targetId, content, options);
+		}
+		/**
+		* Deliver one host-protocol message to a direct continuable child.
+		* Symbol-keyed so host adapters can preserve their own source descriptors without
+		* widening the public Service Definition or impersonating an Agent sender.
+		* @param parent - exact live direct parent authorizing delivery.
+		* @param childId - durable direct-child session id.
+		* @param content - host-authored content to deliver.
+		* @param source - durable host-protocol source descriptor.
+		* @param signal - caller cancellation before inbox acceptance.
+		* @param delivery - Queue as a distinct turn or Steer at the nearest step.
+		* @returns the accepted message's inbox id.
+		*/
+		[deliverSubagentPrompt](parent, childId, content, source, signal, delivery) {
+			return delivery === "steer" ? this.requireManager().steerPrompt(parent, childId, content, source, signal) : this.requireManager().queuePrompt(parent, childId, content, source, signal);
+		}
+		/**
+		* Interrupt one live child's current execution under a human parent
+		* address or an exact live ancestor Agent. Fire-and-return: the cancel
+		* signal is issued before this returns, but the target may keep running
+		* until it observes the signal. Unclaimed pending inbox work, the Activation,
+		* and published descendants are preserved; claimed work is not requeued.
+		* Once the interrupted Agent is idle, a waking send resumes the parked FIFO
+		* queue. External backends stop their single execution. An absent target
+		* is an accepted no-op, as is a manager-less composition, which cannot own a
+		* live Activation.
+		* @param targetSessionId - the durable child session id to interrupt.
+		* @param authority - the human parent address or exact live ancestor Agent.
+		* @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
+		*   live target.
+		*/
+		interrupt(targetSessionId, authority) {
+			this.manager?.interrupt(targetSessionId, authority);
+		}
+		/**
+		* Close subagent admission below exact live parent Agents, stop only their
+		* visible descendant Activations synchronously, then await admitted scoped
+		* materializations and release those forests child-first. The scoped cutoff
+		* lasts until each exact parent leaves the registry; unrelated parent trees
+		* remain live.
+		* @param parents - exact host-owned parent Agents entering teardown.
+		* @returns once every retained descendant activation released its execution handle.
+		* @throws an aggregate error after all branches settle when any failed.
+		*/
+		async drainDescendants(parents) {
+			const manager = this.manager;
+			if (manager === void 0) return;
+			await manager.drainDescendants(parents);
+		}
+		/**
+		* Release selected resident direct children of one exact live
+		* parent. Other children of the same parent remain admitted and resident.
+		* Absent targets and a manager-less composition are accepted no-ops.
+		* @param parent - exact live direct parent authorizing the selected release.
+		* @param childIds - durable direct-child ids to release when resident.
+		* @returns once every selected activation released its execution handle.
+		* @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a
+		*   different parent or the supplied parent identity is stale.
+		*/
+		async drainChildren(parent, childIds) {
+			const manager = this.manager;
+			if (manager === void 0) return;
+			await manager.drainChildren(parent, childIds);
+		}
+		/**
+		* Read the parent's durable direct-child catalog without loading or resuming an Agent.
+		* The service owns and releases the live-preferred Session observation.
+		* @param parentSessionId - parent whose direct children are requested.
+		* @param signal - cancellation forwarded to the Session query.
+		* @returns catalog children in parent event order.
+		* @throws {@link SubagentError} when query or catalog projection is unavailable.
+		* @throws SessionQueryError when the parent cannot be read or the query is cancelled.
+		*/
+		listChildren(parentSessionId, signal) {
+			return listChildren(this.ctx, parentSessionId, signal);
+		}
+		/**
+		* Recursively list reachable parent catalogs in stable pre-order, preserving
+		* each catalog's event order. Each row carries its catalog parent and depth;
+		* external children are leaves; one-shot and unknown-mode children remain
+		* traversal nodes. Unknown modes
+		* produce unsupported diagnostics. Unreadable child catalogs produce corrupt
+		* or unavailable diagnostics and stop only that branch. Root read failures,
+		* missing services or projections, and cancellation reject the whole listing.
+		* Each catalog is observed once and released before the next read. No Agent
+		* is loaded or resumed; Sessions absent from reachable catalogs are omitted.
+		* @param rootSessionId - session whose catalog starts descendant discovery.
+		* @param signal - cancellation forwarded to and checked around each catalog read.
+		* @returns children and branch diagnostics in parent-catalog pre-order.
+		* @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.
+		* @throws SessionQueryError when the root catalog cannot be read.
+		*/
+		listDescendants(rootSessionId, signal) {
+			return listDescendants(this.ctx, rootSessionId, signal);
+		}
+		/**
+		* Deliver one browser-authored message to a continuable child through the
+		* exact live direct parent, retaining the caller-minted request identity and
+		* validated browser zone on the accepted message. Success identifies the
+		* message the child's inbox accepted; later execution is independent of this
+		* call. Queue delivery targets a later turn; steer delivery targets the
+		* nearest step and retains the Agent loop's best-effort fallback semantics.
+		* Image parts are admitted and persisted through the attachment store
+		* before delivery, and the child's model must accept image input.
+		* Cold resume at capacity rejects with `subagent/delivery-unavailable`.
+		* @param request - durable address, delivery, minted identity, content, and optional browser zone.
+		* @param signal - carrier cancellation, owning the call until inbox acceptance.
+		* @returns the accepted message's inbox identity.
+		* @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`,
+		*   `subagent/invalid-time-zone`, `subagent/parent-unavailable`,
+		*   `subagent/not-resumable`, `subagent/unauthorized`,
+		*   `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.
+		*/
+		async prompt(request, signal) {
+			const { parentSessionId, childSessionId, clientTimeZone, delivery } = request;
+			validateControlRequest("subagent.prompt", request);
+			const canonicalTimeZone = clientTimeZone === void 0 ? void 0 : canonicalClientTimeZone(clientTimeZone);
+			if (clientTimeZone !== void 0 && canonicalTimeZone === void 0) throw new RemoteError("subagent/invalid-time-zone", "clientTimeZone must be UTC or a valid IANA Area/Location name", { value: clientTimeZone });
+			const parent = this.ctx.get("agents")?.get(parentSessionId);
+			if (parent === void 0) throw new RemoteError("subagent/parent-unavailable", `parent session "${parentSessionId}" is not live`, { parentSessionId });
+			const source = {
+				kind: "user",
+				rpcId: request.requestId,
+				...canonicalTimeZone === void 0 ? {} : { clientTimeZone: canonicalTimeZone }
+			};
+			try {
+				let content;
+				if (request.content.every((part) => part.type === "text")) content = request.content.map((part) => ({
+					type: "text",
+					text: part.text
+				}));
+				else {
+					const attachments = this.ctx.get("attachments");
+					if (attachments === void 0) throw new Error("subagent image prompt requires an attachment store");
+					content = await attachments.admitPromptContent(request.content);
+				}
+				return { messageId: await this[deliverSubagentPrompt](parent, childSessionId, content, source, signal, delivery) };
+			} catch (error) {
+				return rejectPrompt(error, childSessionId, signal);
+			}
+		}
+		/**
+		* Remote face of {@link interrupt} under one durable parent address. No
+		* catalog, history, persistence, or parent Agent lookup runs: the core
+		* primitive alone authorizes the address against the live Activation, which
+		* is what keeps a live child interruptible while its parent Agent is offline.
+		* Absent, idle, and already-completed targets are accepted no-ops there.
+		* @param childSessionId - durable child session id to interrupt.
+		* @param parentSessionId - durable direct parent whose authority is claimed.
+		* @param mode - required continuable-address discriminator.
+		* @returns acknowledgement that the cancel signal was admitted, not that the target is quiescent.
+		* @throws {RemoteError} `gateway/bad-request` for an empty id,
+		*   `subagent/unauthorized` when the address does not own the live target,
+		*   otherwise `gateway/internal`.
+		*/
+		interruptByParent(childSessionId, parentSessionId, mode) {
+			validateControlRequest("subagent.interrupt", {
+				childSessionId,
+				parentSessionId,
+				mode
+			});
+			try {
+				this.interrupt(childSessionId, {
+					kind: "user",
+					parentSessionId
+				});
+			} catch (error) {
+				if (error instanceof SubagentError && error.code === "UNAUTHORIZED") throw new RemoteError("subagent/unauthorized", "subagent does not belong to this parent", { childSessionId }, { cause: error });
+				throw new RemoteError("gateway/internal", "subagent interrupt failed", {}, { cause: error });
+			}
+			return { accepted: true };
+		}
+		/**
+		* Register a provider under its name. Registration is effect-scoped and HMR
+		* safe; removing a provider blocks new starts but does not revoke runs that
+		* were already returned to their holders. Providers without either execution
+		* method are rejected with UNSUPPORTED_CAPABILITY before registration.
+		* @param provider - the trusted provider implementation.
+		* @returns the exact Cordis effect disposer.
+		*/
+		registerProvider(provider) {
+			const name = provider.name;
+			if (provider.start === void 0 && provider.prepareContinuable === void 0) throw new SubagentError(`subagent provider "${name}" must implement start or prepareContinuable`, "UNSUPPORTED_CAPABILITY");
+			return this.ctx.effect(function* () {
+				if (this.providers.has(name)) throw new SubagentError(`a subagent provider named "${name}" is already registered`, "DUPLICATE_PROVIDER");
+				this.providers.set(name, provider);
+				yield () => {
+					this.providers.delete(name);
+					this.emitLifecycle("subagent/provider-removed", name);
+				};
+				this.ctx.emit("subagent/provider-added", provider);
+			}.bind(this), "subagents.registerProvider()");
+		}
+		/**
+		* Look up a provider by name.
+		* @param name - the provider name.
+		* @returns the provider, or undefined when absent.
+		*/
+		getProvider(name) {
+			return this.providers.get(name);
+		}
+		/**
+		* List registered provider names in insertion order.
+		* @returns the registered names.
+		*/
+		list() {
+			return [...this.providers.keys()];
+		}
+		/**
+		* Resolve one provider's detached continuable-creation contribution. Method
+		* presence on the provider IS the capability, so a provider without it is
+		* rejected before the manager reserves any child resources.
+		*/
+		async prepareContinuable(name, request) {
+			return this.expectProvider(name).prepareContinuable(request);
+		}
+		/** Look up a provider for dispatch or fail loud. */
+		expectProvider(name) {
+			const provider = this.providers.get(name);
+			if (provider === void 0) throw new SubagentError(`no subagent provider registered for "${name}"`, "NO_PROVIDER");
+			return provider;
+		}
+		/** Resolve the subagent manager or fail loud. */
+		requireManager() {
+			if (this.manager === void 0) throw new SubagentError("continuable subagents require the agents service", "CONTINUATION_UNAVAILABLE");
+			return this.manager;
+		}
+		/**
+		* Build the lifecycle observer for one continuable Activation's residency
+		* epoch, so the manager publishes its edges without owning event dispatch.
+		*/
+		observeActivation(provider, childId, parent) {
+			return createActivationObserver(this.emitLifecycle, provider, childId, parent);
+		}
+		/** Reject the first requested capability that the provider lacks. */
+		assertCapabilities(provider, request) {
+			const needs = [
+				{
+					when: request.agentOptions !== void 0,
+					cap: "agentOptions"
+				},
+				{
+					when: request.outputSchema !== void 0,
+					cap: "outputSchema"
+				},
+				{
+					when: request.maxDepth !== void 0,
+					cap: "depthLimit"
+				},
+				{
+					when: request.toolFilter !== void 0,
+					cap: "toolFilter"
+				},
+				{
+					when: request.persona !== void 0,
+					cap: "persona"
+				}
+			];
+			for (const { when, cap } of needs) if (when && !provider.capabilities[cap]) throw new SubagentError(`subagent provider "${provider.name}" does not support the "${cap}" capability`, "UNSUPPORTED_CAPABILITY");
+		}
+	};
+})();
+//#endregion
+export { AssistantOutputFold, NO_START_CAPABILITIES, STRUCTURED_OUTPUT_TOOL, SUBAGENT_DESCRIPTOR_VERSION, SubagentDepthError, SubagentError, SubagentRunId, SubagentRuntime, SubagentRuntime as default, appendDelegatedPolicyOverrides, applyChildComposition, assertPositiveFinite, assertSubagentMaxDepth, assertUsableCwd, captureDelegatedPolicyOverrides, childSessionMeta, delegationDepthOf, finalAssistantOutput, foldSubagentDescriptor, parentAgentOptionsForDelegation, resolveChildAgentOptions, resolveChildDepth, settleRunResult, snapshotSubagentDescriptor, subprocessRunHandle };