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

package/lib/types/manager.js

@@ -0,0 +1,1294 @@
+/**
+ * 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 = (this && this.__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: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__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;
+});
+import { randomUUID } from 'node:crypto';
+import { isAbsolute, resolve } from 'node:path';
+import { brandString } from '@qlzt/dsh-brand';
+import { ReasoningEffortId, contentHasImage, createUserMessage, errorChain } from '@qlzt/dsh-llm';
+import { SessionLogOffset } from '@qlzt/dsh-session';
+import { appendDelegatedPolicyOverrides, applyChildComposition, captureDelegatedPolicyOverrides, childSessionMeta, resolveChildAgentOptions, resolveChildDepth, } from "./child-agent.js";
+import { createAgentMessage, withContinuableReturnGuidance, createSettlementMessage } from "./continuation-messages.js";
+import { assertSubagentMaxDepth } from "./depth.js";
+import { foldSubagentDescriptor, snapshotSubagentDescriptor } from "./descriptor.js";
+import { establishCatalogChild, establishExternalCatalogChild } from "./catalog.js";
+import { SubagentError } from "./error.js";
+import { isAdjacentAgentSendMessageTool } from "./internal.js";
+import { attachStructuredRuntime } from "./structured.js";
+import { ActivationPool, ChildLock, activationAgent, captureLocalResult, observeLocalFailure, requireLocalActivation } from "./activation.js";
+/** 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. */
+export class SubagentManager {
+    ctx;
+    host;
+    maxActiveSubagents;
+    /** Child session id → its live Activation. Process-local, never durable. */
+    resident = new Map();
+    /** Root identities retain their pool across child settlement without retaining dead roots. */
+    rootPools = new WeakMap();
+    /** Materializations admitted before drain, tracked through publication or rollback. */
+    materializations = 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 = 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;
+        // Ordinary Cordis owner effects unwind in reverse registration order, which
+        // cannot express the dynamic child graph. Register the private scope's
+        // structural disposer FIRST and the drain SECOND, so reverse unwind invokes
+        // the drain before releasing the scope; a cleanup effect on the same scope
+        // as the Agent handles would let structural handle disposal bypass
+        // child-first ordering.
+        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 === undefined)
+            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');
+        }
+        // Disposal already stopped the target with a whole-Activation teardown;
+        // a second cancel would be a redundant signal on a closing handle.
+        if (activation.closing !== undefined)
+            return;
+        const kind = authority.kind === 'user' ? 'user' : 'parent';
+        if (activation.kind === 'local') {
+            activation.handle.agent.cancel({ kind }, { keepInbox: true });
+        }
+        else {
+            activation.controller.abort({ kind });
+            // The settlement observer reports teardown failures.
+            void this.dispose(activation).catch(() => undefined);
+        }
+    }
+    /**
+     * 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 = 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 !== undefined) {
+                    waits.push(item.result.promise.catch(() => undefined));
+                    continue;
+                }
+                if (item.handle.agent.status !== 'idle') {
+                    waits.push(item.handle.agent.whenIdle());
+                    continue;
+                }
+                if (item.ownedChildren.size > 0) {
+                    // Published descendants are observed separately; preparation holds
+                    // keep the owner pending until publication or rollback wakes it.
+                    if ([...item.ownedChildren].some(id => !this.resident.has(id)))
+                        waits.push(item.poke.promise);
+                    continue;
+                }
+                const inbox = item.handle.agent.inbox;
+                if (item.failureAt === undefined && (inbox.nextTurn.length > 0 || inbox.nextStep.length > 0))
+                    continue;
+                waits.push(Promise.race([item.result.promise.catch(() => undefined), item.poke.promise]));
+            }
+            if (waits.length > 0) {
+                observed = true;
+                await Promise.all(waits);
+                continue;
+            }
+            // A descendant can be published while whenIdle follows another child.
+            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 !== undefined)
+                    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 = 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) {
+            const disposal = this.dispose(activation);
+            void disposal.catch(() => undefined);
+        }
+        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 === undefined)
+                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) {
+            const disposal = this.dispose(activation);
+            void disposal.catch(() => undefined);
+        }
+        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);
+        // Snapshot before any await: invalid descriptor JSON rejects the call
+        // before a child exists, and the detached value is what reaches the log.
+        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 !== undefined ? { agentProvider } : {},
+            ...agentModel !== undefined ? { agentModel } : {},
+            ...agentReasoningEffort !== undefined ? { agentReasoningEffort } : {},
+            ...request.persona !== undefined ? { persona: request.persona } : {},
+            ...request.toolFilter !== undefined ? { toolFilter: request.toolFilter } : {},
+        });
+        // Capture before the first await: a later parent switch belongs to the
+        // parent's future, not to this child.
+        const delegatedPolicies = captureDelegatedPolicyOverrides(parent);
+        // An idle continuation-managed parent must not settle while a caller is
+        // still creating its child. A turn-scoped delegation does not need this,
+        // but the service is also callable outside a turn.
+        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 !== undefined) {
+                    const persisted = await persistence?.stat(childId, { signal: spec.signal });
+                    spec.signal.throwIfAborted();
+                    this.assertAdmitting(parent);
+                    this.assertChildIdAvailable(childId);
+                    if (persisted !== undefined) {
+                        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 !== undefined),
+                        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 !== undefined) {
+                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 !== undefined && 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 !== undefined
+            && 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 !== undefined) {
+            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) !== undefined || this.ctx.get('sessions')?.get(childId) !== undefined) {
+            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 === undefined || activationAgent(parentActivation) !== parent)
+            return () => { };
+        if (parentActivation.closing !== undefined) {
+            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 !== undefined && live.closing === undefined)
+                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 !== undefined && 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 === undefined)
+            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 !== undefined)
+            return activation.closing;
+        const completion = Promise.withResolvers();
+        activation.closing = completion.promise;
+        void 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 failures = await Promise.all(roots.map(async (activation) => {
+            try {
+                await this.dispose(activation);
+                return undefined;
+            }
+            catch (error) {
+                return error;
+            }
+        }));
+        const reasons = failures.filter(failure => failure !== undefined);
+        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 !== undefined)
+            return existing;
+        const members = 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 !== undefined) {
+            const parent = this.ctx.agents.get(parentSession);
+            if (parent === undefined || 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;
+        }
+        return undefined;
+    }
+    /** Resolve a root's pool once; descendants inherit their resident parent's pool directly. */
+    rootPool(parent) {
+        let pool = this.rootPools.get(parent);
+        if (pool === undefined) {
+            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 };
+                void run.result.catch(() => undefined);
+                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) => {
+                // Only fresh creation appends the descriptor and delegated policy after
+                // the inherited marker; a cold resume replays those persisted events.
+                if (create !== undefined) {
+                    child.session.append('subagent/descriptor', create.descriptor);
+                    appendDelegatedPolicyOverrides(child.session, create.delegatedPolicies);
+                    const workingDirectory = childCtx.get('workingDirectory');
+                    if (workingDirectory === undefined)
+                        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 !== undefined) {
+                    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 === undefined
+                ? 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 === undefined ? {} : { seed: create.seed }),
+                    inheritedEventCount: create.inheritedEventCount,
+                    agentOptions: inputs.agentOptions,
+                    signal: inputs.signal,
+                    setup,
+                });
+            resource = { kind: 'local', handle, outputStart: handle.agent.session.seq, structured, failureAt: undefined, 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: undefined,
+            ancestry: new WeakSet(resource.kind === 'external' ? parentLineage : [resource.handle.agent, ...parentLineage]),
+            ownedChildren: new Set(),
+            observer,
+            announced: false,
+        };
+        void activation.result.promise.catch(() => undefined);
+        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(() => undefined);
+            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));
+            void 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 === undefined)
+            return;
+        if (parentActivation.closing !== undefined) {
+            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) {
+        void (async () => {
+            while (true) {
+                const idleObservation = activation.poke;
+                await activation.handle.agent.whenIdle();
+                if (activation.closing !== undefined)
+                    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 {
+                        void activation.handle.agent.runMaintenance(() => {
+                            done = this.close(activation, () => this.finishDisposal(activation, false));
+                            return Promise.resolve();
+                        });
+                    }
+                    catch (_error) {
+                        // Another activity already owns the Agent's idle phase.
+                        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 !== undefined)
+            return 'closed';
+        if (activation.poke !== observation)
+            return 'retry';
+        const inbox = activation.handle.agent.inbox;
+        if (activation.ownedChildren.size > 0)
+            return 'wait';
+        if (activation.failureAt === undefined && (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 === undefined
+            ? failureMessage(error)
+            : errorChain(error);
+        try {
+            if (activation.kind === 'external') {
+                if (stop) {
+                    activation.controller.abort({ kind: 'parent' });
+                    // Some backends settle their result only when disposal begins.
+                    externalDisposal = Promise.resolve().then(() => activation.run.dispose());
+                    void externalDisposal.catch(() => undefined);
+                }
+                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 !== undefined);
+                    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 childFailures = await Promise.all(childDisposals.map(async (disposal) => {
+                        try {
+                            await disposal;
+                            return undefined;
+                        }
+                        catch (error) {
+                            return error;
+                        }
+                    }));
+                    const reasons = childFailures.filter(reason => reason !== undefined);
+                    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 === undefined ? result : { output: [], stopReason: 'error' };
+        this.notifySettlement(activation, result);
+        this.releaseOwnership(childId);
+        activation.observer.settle(terminal);
+        if (resultFailure === undefined)
+            activation.result.resolve(result);
+        else
+            activation.result.reject(resultFailure.error);
+        if (failure !== undefined)
+            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) !== undefined);
+            if (this.closingTeardownFor(parent) !== undefined) {
+                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 === undefined)
+                    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 !== undefined) {
+                    return disposal.then(() => undefined, () => undefined);
+                }
+                if (contentHasImage(content)) {
+                    await this.assertImageCapable(requireLocalActivation(activation).handle.agent, options.signal);
+                    if (activation.closing !== undefined) {
+                        await Promise.allSettled([activation.closing]);
+                        return undefined;
+                    }
+                }
+                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 !== undefined)
+                return live;
+            this.assertAdmitting(parent);
+            options.signal.throwIfAborted();
+            /* v8 ignore stop */
+        }
+    }
+    /** 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 !== undefined) {
+            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(env_1, observation, false);
+            this.assertAdmitting(parent);
+            this.authorizeLineage(parent, childId, source.header.parentSession);
+            const descriptor = foldSubagentDescriptor(source.events.slice(source.inheritedEventCount));
+            if (descriptor === undefined || 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 !== undefined ? { provider: descriptor.agentProvider } : {},
+                        ...descriptor.agentModel !== undefined ? { model: descriptor.agentModel } : {},
+                        ...descriptor.agentReasoningEffort !== undefined
+                            ? { 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(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 !== undefined) {
+                    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 === undefined
+            ? 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 === undefined || model === undefined)
+            return;
+        const llm = this.ctx.get('llm');
+        /* v8 ignore next -- without an LLM registry, delivery defers to projection. */
+        if (llm === undefined)
+            return;
+        const info = await llm.resolveModelInfo(provider, model, signal);
+        if (info.inputModalities !== undefined && !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 === undefined) {
+            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 === undefined) {
+            throw new SubagentError('continuable subagents require session query (load @qlzt/dsh-session-query)', 'CONTINUATION_UNAVAILABLE');
+        }
+        return query;
+    }
+}
+export default SubagentManager;
+//# sourceMappingURL=manager.js.map