@xneog/dsh-subagent 0.1.0 → 0.1.3-alpha.1

package/lib/types/continuation.js

@@ -20,14 +20,67 @@
  *
  * @module @xneog/dsh-subagent
  */
+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 { boundContextSummary, createUserMessage, errorChain } from '@xneog/dsh-llm';
-import { SessionId } from '@xneog/dsh-session';
+import { brandString } from '@xneog/dsh-brand';
+import { ReasoningEffortId, boundContextSummary, contentHasImage, createUserMessage, errorChain } from '@xneog/dsh-llm';
+import { SessionLogOffset } from '@xneog/dsh-session';
 import { foldSubagentDescriptor, snapshotSubagentDescriptor } from "./descriptor.js";
 import { appendDelegatedPolicyOverrides, applyChildComposition, captureDelegatedPolicyOverrides, childSessionMeta, resolveChildAgentOptions, resolveChildDepth, } from "./child-agent.js";
 import { assertSubagentMaxDepth } from "./depth.js";
-import { seedDescriptorTurn } from "./descriptor-seed.js";
 import { SubagentError } from "./error.js";
+import { isAdjacentAgentSendMessageTool } from "./internal.js";
 /**
  * Read one Activation's current disposal transaction. This indirection exists
  * because TypeScript would otherwise narrow repeated reads of the mutable field
@@ -38,6 +91,39 @@ import { SubagentError } from "./error.js";
 function disposalOf(activation) {
     return activation.disposal;
 }
+/** 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. */
+function agentMessage(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. */
+function continuableInitialPrompt(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.
@@ -99,7 +185,6 @@ class ChildLock {
 export class SubagentContinuationManager {
     ctx;
     host;
-    setupRegistry;
     /** Child session id → its live Activation. Process-local, never durable. */
     activations = new Map();
     /** Materializations admitted before drain, tracked through publication or rollback. */
@@ -115,10 +200,9 @@ export class SubagentContinuationManager {
      */
     closingScopes = new Map();
     draining = false;
-    constructor(ctx, host, setupRegistry) {
+    constructor(ctx, host) {
         this.ctx = ctx;
         this.host = host;
-        this.setupRegistry = setupRegistry;
         // 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
@@ -154,68 +238,199 @@ export class SubagentContinuationManager {
         const request = spec.request;
         const parent = request.parent;
         this.assertAdmitting(parent);
-        this.requirePersistence();
+        const persistence = this.requirePersistence();
         assertSubagentMaxDepth(request.maxDepth);
-        const childId = SessionId(randomUUID());
+        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 agentProvider = request.agentOptions?.provider ?? parent.options.provider;
-        const agentModel = request.agentOptions?.model ?? parent.options.model;
+        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);
-        const prepared = await this.host.prepareContinuable(spec.provider, {
-            sessionId: childId,
-            parent,
-            signal: spec.signal,
-        });
-        spec.signal.throwIfAborted();
-        this.assertAdmitting(parent);
-        const lineageSeedLength = prepared.seed?.length ?? 0;
-        const seed = seedDescriptorTurn(childId, prepared.seed, descriptor);
-        const messageId = await this.locks.run(childId, async () => {
-            const activation = await this.materialize({
-                childId,
-                provider: spec.provider,
+        // Hold the parent's own Activation open across the establishment awaits:
+        // an idle continuation-managed parent must not settle while a caller is
+        // still creating its child, or the admitted delivery would find a stale
+        // parent identity. A turn-scoped delegation never needs this (the parent
+        // is `running`), but this service is also callable outside a turn.
+        const releaseHold = this.holdOwnership(parent, childId);
+        try {
+            const prepared = await this.host.prepareContinuable(spec.provider, {
+                sessionId: childId,
                 parent,
-                create: { seed, meta: childSessionMeta(parent, childDepth, lineageSeedLength), delegatedPolicies },
-                agentOptions: resolveChildAgentOptions(parent, request.agentOptions, childDepth),
-                composition: { persona: request.persona, toolFilter: request.toolFilter },
                 signal: spec.signal,
             });
-            return this.submitMaterialized(activation, request.prompt, { kind: 'user' }, parent, spec.signal);
+            spec.signal.throwIfAborted();
+            this.assertAdmitting(parent);
+            const inheritedEventCount = SessionLogOffset(prepared.seed?.length ?? 0);
+            const seed = prepared.seed;
+            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({
+                    childId,
+                    provider: spec.provider,
+                    parent,
+                    create: {
+                        seed,
+                        meta: childSessionMeta(parent, childDepth, prepared.seed !== undefined),
+                        inheritedEventCount,
+                        delegatedPolicies,
+                        descriptor,
+                    },
+                    agentOptions,
+                    composition: { persona: request.persona, toolFilter: request.toolFilter },
+                    signal: spec.signal,
+                });
+                return this.submitMaterialized(activation, isAdjacentAgentSendMessageTool(this.ctx.get('tools')?.get('send_message', activation.handle.agent))
+                    ? continuableInitialPrompt(parent.id, request.prompt)
+                    : request.prompt, { source: { kind: 'user' }, signal: spec.signal, delivery: 'queue' }, parent);
+            });
+            return { childId, messageId };
+        }
+        catch (error) {
+            releaseHold();
+            throw error;
+        }
+    }
+    /**
+     * 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 (an admitted delivery owns it from then on). A parent
+     * without an Activation needs no hold: only this manager settles parents.
+     * @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.
+     * @throws {SubagentError} `ACTIVATION_CLOSING` when the parent's own
+     *   disposal transaction is already open.
+     */
+    holdOwnership(parent, childId) {
+        const parentActivation = this.activations.get(parent.id);
+        if (parentActivation === undefined || parentActivation.handle.agent !== parent)
+            return () => { };
+        if (parentActivation.disposal !== 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.activations.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.disposal === undefined)
+                return;
+            if (parentActivation.ownedChildren.delete(childId))
+                this.wake(parentActivation);
+        };
+    }
+    /** Reject one child identity already owned by a live Agent or Session. */
+    assertChildIdAvailable(childId) {
+        if (this.ctx.agents.get(childId) !== undefined || this.ctx.get('sessions')?.get(childId) !== undefined) {
+            throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD');
+        }
+    }
+    /**
+     * Deliver one model-authored message to a direct continuable child or to the
+     * sender's direct parent. Both directions use Steer: a running target admits
+     * the message at its nearest step boundary, while an idle target starts a
+     * turn. A missing direct child cold-resumes through the ordinary continuation
+     * lifecycle. The caller signal owns the operation only until inbox acceptance.
+     * @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.
+     * @throws when adjacency, availability, or admission rejects delivery.
+     */
+    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.activations.get(sender.id);
+        if (senderActivation !== undefined
+            && senderActivation.handle.agent === sender
+            && senderActivation.parentSession === 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',
         });
-        return { childId, messageId };
     }
     /**
-     * Deliver one later message to a known continuable child as its next FIFO
-     * turn. Routing depends only on Activation residency: a `running` Activation
-     * enqueues, a `waiting` one wakes the same Agent, and an absent one
-     * cold-resumes a new Activation from the persisted Session. The Agent inbox
-     * is the only queue, so every accepted message has one observable order.
-     *
-     * The caller signal owns lookup, materialization, and admission only until
-     * inbox acceptance; afterwards the accepted turn cannot be cancelled through
-     * this service.
-     * @param parent - the exact live direct parent authorizing this delivery.
-     * @param childId - the durable child session id.
-     * @param content - the user-role content to deliver.
-     * @param options - the message source fields and caller cancellation.
+     * 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 - human-authored content to deliver.
+     * @param source - durable host-protocol provenance.
+     * @param signal - caller cancellation before inbox acceptance.
+     * @returns the accepted message's inbox 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 - host-authored content to deliver.
+     * @param source - durable host-protocol provenance.
+     * @param signal - caller cancellation before inbox acceptance.
      * @returns the accepted message's inbox id.
-     * @throws when parent authority, availability, or admission rejects the delivery.
      */
-    async followup(parent, childId, content, options) {
+    async steerPrompt(parent, childId, content, source, signal) {
+        return this.deliverToChild(parent, childId, content, { source, signal, delivery: 'steer' });
+    }
+    /** Route one parent-originated delivery through residency and cold resume. */
+    async deliverToChild(parent, childId, content, options) {
         this.assertAdmitting(parent);
+        // Same hold as `startContinuable`: an idle continuation-managed parent
+        // must not settle underneath a cold resume it is authorizing.
+        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.activations.get(childId);
@@ -223,14 +438,27 @@ export class SubagentContinuationManager {
                     return this.coldResume(parent, childId, content, options);
                 // A delivery that arrives after the disposal transaction began must not
                 // reach a handle being torn down; wait for release, then cold-resume.
+                const disposal = activation.disposal;
                 /* v8 ignore next 3 -- the send-versus-dispose cutoff: reaching this arm needs a
                  * delivery to observe the transaction inside the same critical section that opened it,
                  * which no test can schedule deterministically. The behavior is covered end-to-end by
                  * "cold-resumes a delivery that lost the race with final disposal". */
-                if (activation.disposal !== undefined) {
-                    return activation.disposal.then(() => undefined, () => undefined);
+                if (disposal !== undefined) {
+                    return disposal.then(() => undefined, () => undefined);
+                }
+                // Text-only delivery stays await-free, so the disposal-cutoff check
+                // above and the submit share one critical window. The image path
+                // awaits a capability read, so it re-checks the cutoff afterwards; a
+                // disposal that began during the read is waited out and retried like
+                // one observed on entry.
+                if (contentHasImage(content)) {
+                    await this.assertImageCapable(activation.handle.agent, options.signal);
+                    if (activation.disposal !== undefined) {
+                        await Promise.allSettled([activation.disposal]);
+                        return undefined;
+                    }
                 }
-                return this.submitAdmitted(activation, content, options.source, parent, options.signal);
+                return this.submitAdmitted(activation, content, options, parent);
             });
             /* v8 ignore start -- only the lost-cutoff arm above returns undefined, so only that
              * race reaches the retry below, which then cold-resumes a new Activation. */
@@ -291,75 +519,26 @@ export class SubagentContinuationManager {
             return;
         activation.handle.agent.cancel(authority.kind === 'user' ? { kind: 'user' } : { kind: 'parent' }, { keepInbox: true });
     }
-    /**
-     * Deliver explicitly selected content from one resident continuable child to
-     * its durable direct parent. Sender authorization, parent resolution, and
-     * send acceptance share one no-await span. Reporting neither concludes the
-     * child's turn nor changes its Activation lifetime.
-     * @param child - exact live reporting child; this is the authority credential.
-     * @param content - selected model-facing content.
-     * @param options - scheduling policy and pre-acceptance cancellation.
-     * @returns the stable identity of the message accepted by the parent.
-     * @throws {SubagentError} when the sender is unauthorized, the parent is not
-     *   live, or continuation admission is closing.
-     */
-    // oxlint-disable-next-line typescript/require-await -- keep rejection semantics without yielding during admission
-    async reportFrom(child, content, options) {
-        options.signal.throwIfAborted();
-        this.assertAdmitting(child);
-        const activation = this.authorizeReporter(child);
-        const parent = this.resolveReportParent(child);
-        return this.deliverReport(activation, parent, content, options.delivery);
-    }
-    /** Authorize only the exact Agent of one resident Activation. */
-    authorizeReporter(child) {
-        const activation = this.activations.get(child.id);
-        if (activation === undefined || activation.handle.agent !== child) {
-            throw new SubagentError(`agent "${child.id}" is not a live continuable subagent and cannot report`, 'UNAUTHORIZED');
-        }
-        /* v8 ignore next 6 -- only a synchronous re-entrant disposer can open this
-         * transaction between exact-agent authorization and this no-await cutoff. */
+    /** 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.disposal !== undefined) {
-            throw new SubagentError(`subagent "${child.id}" activation is being disposed; the report was not delivered`, 'ACTIVATION_CLOSING');
+            throw new SubagentError(`subagent "${sender.id}" activation is being disposed; the message was not delivered`, 'ACTIVATION_CLOSING');
         }
-        return activation;
-    }
-    /** Resolve the reporting child's live direct parent from durable lineage. */
-    resolveReportParent(child) {
-        const parentId = child.session.header.parentSession;
-        /* v8 ignore next -- every continuation-managed child has direct-parent metadata. */
-        const parent = parentId === undefined ? undefined : this.ctx.agents.get(parentId);
+        const parent = this.ctx.agents.get(activation.parentSession);
         if (parent === undefined) {
-            throw new SubagentError('direct parent is not live; report was not delivered', 'PARENT_UNAVAILABLE');
-        }
-        return parent;
-    }
-    /** Deliver one framed report through the selected parent scheduling preset. */
-    deliverReport(activation, parent, content, delivery) {
-        const message = createUserMessage({
-            content: [
-                { type: 'text', text: `Background subagent ${activation.childId} reported:` },
-                ...content,
-            ],
-            source: {
-                kind: 'subagent-report',
-                form: 'relay',
-                senderSessionId: activation.childId,
-            },
-        });
-        if (delivery === 'wakeup') {
-            this.sendWaking(parent, message, () => { this.sendReport(parent, message, delivery); });
-        }
-        else {
-            this.sendReport(parent, message, delivery);
+            throw new SubagentError('direct parent is not live; the message was not delivered', 'PARENT_UNAVAILABLE');
         }
+        const message = agentMessage(sender, content);
+        this.sendWaking(parent, message, () => { this.sendAgentMessage(parent, message); });
         return message.id;
     }
     /**
      * Perform one waking send to a parent, accounted against that parent's own
      * Activation when it has one. Registering the id before the send is what
      * keeps a continuation-managed parent from being judged quiescent in the
-     * window between `followup()` and the microtask that admits it.
+     * window between a waking send and the microtask that admits it.
      * @param parent - the exact live parent receiving the waking message.
      * @param message - the message whose id is accounted.
      * @param send - the synchronous waking send to perform.
@@ -373,16 +552,13 @@ export class SubagentContinuationManager {
             send();
         }
     }
-    /** Send one report while translating only the parent's own rejection. */
-    sendReport(parent, message, delivery) {
+    /** Send one Agent message while translating only the target's own rejection. */
+    sendAgentMessage(parent, message) {
         try {
-            if (delivery === 'wakeup')
-                parent.followup(message);
-            else
-                parent.inject(message);
+            parent.steer(message);
         }
         catch (error) {
-            throw new SubagentError('direct parent is not live; report was not delivered', 'PARENT_UNAVAILABLE', { cause: error });
+            throw new SubagentError('direct parent is not live; the message was not delivered', 'PARENT_UNAVAILABLE', { cause: error });
         }
     }
     /**
@@ -471,6 +647,38 @@ export class SubagentContinuationManager {
         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 without
+     * closing admission for the parent's other continuable children. Owned
+     * descendants are released recursively through the same lifecycle.
+     * @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 handle.
+     * @throws {SubagentError} `UNAUTHORIZED` when a resident target is not the
+     *   parent's direct continuable child or the parent identity is stale.
+     */
+    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.activations.get(childId);
+            if (activation === undefined)
+                continue;
+            if (activation.parentSession !== parent.id || !activation.ancestry.has(parent)) {
+                throw new SubagentError(`subagent "${childId}" is not a direct child of agent "${parent.id}"`, 'UNAUTHORIZED');
+            }
+            targets.push(activation);
+        }
+        // Open every transaction before the first await so cancellation propagates
+        // across the selected roots in one synchronous span.
+        for (const activation of targets) {
+            const disposal = this.dispose(activation);
+            void disposal.catch(() => undefined);
+        }
+        await this.disposeRoots(targets, 'selected activation(s)');
+    }
     /** Dispose independent roots and report every branch failure after all settle. */
     async disposeRoots(roots, failureSubject) {
         const failures = await Promise.all(roots.map(async (activation) => {
@@ -559,69 +767,91 @@ export class SubagentContinuationManager {
         return 'settled';
     }
     /**
-     * Cold-resume a persisted child: inspect and authorize its Session, fold the
+     * Cold-resume a persisted child: retain and authorize its prepared Session, fold the
      * generic descriptor, create the Activation through `ctx.agents.resume()`,
      * and submit the waiting turn. This never dispatches through a subagent
      * provider — the persisted Session already holds the initial prefix and the
      * descriptor is the whole reconstruction input.
      */
     async coldResume(parent, childId, content, options) {
-        const persistence = this.requirePersistence();
-        let loaded;
+        const env_1 = { stack: [], error: void 0, hasError: false };
         try {
-            loaded = await persistence.inspect(childId, options.signal);
-        }
-        catch (error) {
-            options.signal.throwIfAborted();
-            throw new SubagentError(`subagent "${childId}" is unavailable`, 'NOT_RESUMABLE', { cause: error });
-        }
-        options.signal.throwIfAborted();
-        this.assertAdmitting(parent);
-        // Authorize the persisted header before folding: only the durable child's
-        // exact live direct parent may continue it.
-        this.authorizeLineage(parent, childId, loaded.meta.parentSession);
-        // Fold only the child's own suffix: a fork seed replays the parent's log,
-        // which may carry an ANCESTOR's descriptor when the parent is itself a
-        // continuable child.
-        const descriptor = foldSubagentDescriptor(loaded.events.slice(loaded.meta.seedLength ?? 0));
-        if (descriptor === undefined || descriptor.mode !== 'continuable') {
-            throw new SubagentError(`subagent "${childId}" has no supported continuation state and cannot be resumed; `
-                + 'do not retry send_message with this id', 'NOT_RESUMABLE');
+            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);
+            // Authorize the persisted header before folding: only the durable child's
+            // exact live direct parent may continue it.
+            this.authorizeLineage(parent, childId, source.header.parentSession);
+            // Fold only the child's own suffix: a fork seed replays the parent's log,
+            // which may carry an ANCESTOR's descriptor when the parent is itself a
+            // continuable child.
+            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({
+                    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);
         }
-        let activation;
-        try {
-            activation = await this.materialize({
-                childId,
-                provider: descriptor.provider,
-                parent,
-                agentOptions: {
-                    ...descriptor.agentProvider !== undefined ? { provider: descriptor.agentProvider } : {},
-                    ...descriptor.agentModel !== undefined ? { model: descriptor.agentModel } : {},
-                },
-                composition: { persona: descriptor.persona, toolFilter: descriptor.toolFilter },
-                signal: options.signal,
-            });
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
         }
-        catch (error) {
-            options.signal.throwIfAborted();
-            if (error instanceof SubagentError)
-                throw error;
-            throw new SubagentError(`subagent "${childId}" is unavailable`, 'NOT_RESUMABLE', { cause: error });
+        finally {
+            __disposeResources(env_1);
         }
-        return this.submitMaterialized(activation, content, options.source, parent, options.signal);
     }
     /**
      * Submit to a freshly materialized Activation or roll it back completely.
      * @param activation - the just-published Activation to admit or release.
      * @param content - the initial or resumed message content.
-     * @param source - durable fields naming who supplied the accepted message.
+     * @param options - durable source, scheduling, and pre-acceptance cancellation.
      * @param parent - the live direct parent authorizing admission.
-     * @param signal - caller cancellation owning admission until acceptance.
      * @returns the accepted inbox message id.
      */
-    async submitMaterialized(activation, content, source, parent, signal) {
+    async submitMaterialized(activation, content, options, parent) {
         try {
-            return this.submitAdmitted(activation, content, source, parent, signal);
+            if (contentHasImage(content)) {
+                // The capability read awaits with the activation already published, so
+                // the disposal cutoff is re-checked before the submit; a drain that
+                // began during the read turns into a clean closing rejection.
+                await this.assertImageCapable(activation.handle.agent, options.signal);
+                if (activation.disposal !== undefined) {
+                    throw new SubagentError(`subagent "${activation.childId}" is closing`, 'ACTIVATION_CLOSING');
+                }
+            }
+            return this.submitAdmitted(activation, content, options, parent);
         }
         catch (error) {
             /* v8 ignore next -- rollback disposal failures must not mask the
@@ -630,6 +860,32 @@ export class SubagentContinuationManager {
             throw error;
         }
     }
+    /**
+     * Refuse image content addressed to a child whose model accepts text only.
+     * Callers guard with `contentHasImage`, so text-only delivery never awaits.
+     * The check runs inside the per-child delivery lock, before the message
+     * exists, so a rejection leaves no partial user message. When the child's
+     * route is not fixed by its options (a request-waterfall listener owns it)
+     * or no LLM registry is composed, delivery proceeds and the LLM layer's
+     * text-only projection replaces each image with its stable placeholder.
+     * @param agent - the live or freshly materialized child agent.
+     * @param signal - caller cancellation bounding the model-info read.
+     * @throws {SubagentError} `MODEL_DOES_NOT_SUPPORT_IMAGES` when the child's resolved model declines image input.
+     */
+    async assertImageCapable(agent, signal) {
+        const { provider, model } = agent.options;
+        if (provider === undefined || model === undefined)
+            return;
+        const llm = this.ctx.get('llm');
+        /* v8 ignore next -- a deployment without the LLM registry serves no model
+         * to refuse against; delivery then defers to the text-only 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');
+        }
+    }
     /**
      * Create or resume the child Agent through the private activation-owner
      * scope, install the handle in a fresh Activation, and register ownership on
@@ -663,14 +919,14 @@ export class SubagentContinuationManager {
         // some other owner holds — a duplicate would reject there with rollback.
         inputs.signal.throwIfAborted();
         const setup = (childCtx) => {
-            // Only fresh creation seeds the delegation policy onto the child's own
-            // log (after any fork seed, so fresh policy wins stale seed state); a
-            // cold resume replays those persisted events instead.
+            const child = childCtx.agent;
+            // Only fresh creation appends the descriptor and delegated policy after
+            // the inherited marker; a cold resume replays those persisted events.
             if (create !== undefined) {
-                appendDelegatedPolicyOverrides(childCtx.agent.session, create.delegatedPolicies);
+                child.session.append('subagent/descriptor', create.descriptor);
+                appendDelegatedPolicyOverrides(child.session, create.delegatedPolicies);
             }
             applyChildComposition(childCtx, parent, inputs.composition);
-            return this.setupRegistry.apply(childCtx);
         };
         const observer = this.host.observeActivation(provider, childId, parent);
         // Agent creation owns rollback before handle transfer. A rejection leaves
@@ -685,7 +941,8 @@ export class SubagentContinuationManager {
             : await this.ownerCtx.agents.create({
                 sessionId: childId,
                 meta: create.meta,
-                seed: create.seed,
+                ...(create.seed === undefined ? {} : { seed: create.seed }),
+                inheritedEventCount: create.inheritedEventCount,
                 agentOptions: inputs.agentOptions,
                 signal: inputs.signal,
                 setup,
@@ -793,13 +1050,18 @@ export class SubagentContinuationManager {
      * inbox id. Acceptance is the operation's success boundary; the manager owns
      * the Activation independently afterwards.
      */
-    submit(activation, content, source, parent) {
+    submit(activation, content, options, parent) {
         // Parent-originated delivery keeps the parent live through ownership, so
         // establish it before the message can enter the child's inbox.
         this.acquireOwnership(parent, activation.childId);
-        const message = createUserMessage({ content, source });
+        const message = options.source === undefined
+            ? agentMessage(parent, content)
+            : createUserMessage({ content, source: options.source });
         const accepted = this.admitWaking(activation, message.id, () => {
-            activation.handle.agent.followup(message);
+            if (options.delivery === 'steer')
+                activation.handle.agent.steer(message);
+            else
+                activation.handle.agent.followup(message);
         });
         // Past this point the caller has an id for this child, so its eventual
         // settlement is something the parent is owed an account of.
@@ -814,7 +1076,7 @@ export class SubagentContinuationManager {
      * @returns the accepted message id.
      */
     admitWaking(activation, messageId, send) {
-        // `Agent.followup()` publishes inbox events synchronously, so observers must
+        // Waking Agent sends publish inbox events synchronously, so observers must
         // see this Activation as busy before the call begins.
         activation.accepted.add(messageId);
         try {
@@ -834,8 +1096,8 @@ export class SubagentContinuationManager {
      * manager drain, or Activation disposal that wins before this synchronous
      * span rejects without inbox acceptance.
      */
-    submitAdmitted(activation, content, source, parent, signal) {
-        signal.throwIfAborted();
+    submitAdmitted(activation, content, options, parent) {
+        options.signal.throwIfAborted();
         this.assertAdmitting(parent);
         /* v8 ignore next 6 -- only a synchronous re-entrant disposer can change
          * this field between the caller's live check and this no-await boundary. */
@@ -843,7 +1105,7 @@ export class SubagentContinuationManager {
             throw new SubagentError(`subagent "${activation.childId}" activation is being disposed; the message was not accepted`, 'ACTIVATION_CLOSING');
         }
         this.authorizeLineage(parent, activation.childId, activation.handle.agent.session.header.parentSession);
-        return this.submit(activation, content, source, parent);
+        return this.submit(activation, content, options, parent);
     }
     /**
      * Authorize one operation against the durable direct-parent lineage. Other
@@ -1095,6 +1357,14 @@ export class SubagentContinuationManager {
         }
         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 @xneog/dsh-session-query)', 'CONTINUATION_UNAVAILABLE');
+        }
+        return query;
+    }
 }
 export default SubagentContinuationManager;
 //# sourceMappingURL=continuation.js.map