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

package/lib/types/continuation.d.ts

@@ -23,31 +23,22 @@
 import type { Context } from '@xneog/cordis';
 import type { Agent } from '@xneog/dsh-agent';
 import type { ContentBlock, MessageId, MessageSource } from '@xneog/dsh-llm';
-import { SessionId } from '@xneog/dsh-session';
+import type { SessionId } from '@xneog/dsh-session';
 import type { SubagentDescriptorData } from './descriptor.ts';
 import type { ContinuableCreateRequest, ContinuableCreateSpec, SubagentStartRequest } from './types.ts';
 import type { ActivationObserver } from './lifecycle.ts';
-import type SubagentActivationSetupRegistry from './activation-setup-registry.ts';
-/** Attribution for a model coordinator's follow-up to one of its children. */
-export interface CoordinatorMessageSource {
-    readonly kind: 'coordinator';
+/** Durable attribution for one model-authored message between adjacent Agents. */
+export interface AgentMessageSource {
+    readonly kind: 'agent-message';
     /** A message another agent addressed to this one (`relay` context form). */
     readonly form: 'relay';
-    /** Session id of the agent whose tool call produced the follow-up. */
-    readonly senderSessionId: SessionId;
-}
-/** Durable attribution for a continuable child's explicit parent report. */
-export interface SubagentReportMessageSource {
-    readonly kind: 'subagent-report';
-    /** A message another agent addressed to this one (`relay` context form). */
-    readonly form: 'relay';
-    /** Session id of the reporting child. */
+    /** Session id of the Agent whose tool call produced the message. */
     readonly senderSessionId: SessionId;
 }
 /**
  * Durable attribution for the runtime's own account of a continuable child
  * settling. Deliberately a different kind from
- * {@link SubagentReportMessageSource}: a report is content the child chose,
+ * {@link AgentMessageSource}: an Agent message is content the sender chose,
  * while this message is the manager stating what became of the child, and a
  * transcript that merged them would credit the child with words it never wrote.
  */
@@ -62,26 +53,22 @@ export interface SubagentSettledMessageSource {
 }
 declare module '@xneog/dsh-llm' {
     interface MessageSourceMap {
-        coordinator: CoordinatorMessageSource;
-        'subagent-report': SubagentReportMessageSource;
+        'agent-message': AgentMessageSource;
         'subagent-settled': SubagentSettledMessageSource;
     }
 }
-/** Deployment scheduling policy for accepted child reports. */
-export type SubagentReportDelivery = 'quiet' | 'wakeup';
-/** Options for one continuable child's report to its direct parent. */
-export interface SubagentReportOptions {
-    /** Already-resolved parent scheduling policy. */
-    readonly delivery: SubagentReportDelivery;
-    /** Caller cancellation, owning authorization and admission until acceptance. */
-    readonly signal: AbortSignal;
-}
 /** What a caller asks for when starting a continuable background child. */
 export interface ContinuableStartSpec {
     /** The `ctx.subagents` provider whose continuable-creation capability establishes the child. */
     readonly provider: string;
     /** The initial delegation's short `description`, persisted as the child's creation label. */
     readonly label: string;
+    /**
+     * Optional caller-reserved child identity. Omission preserves the manager's
+     * UUID allocation; supplying one lets a durable parent record provisioning
+     * before child materialization without a second identity handshake.
+     */
+    readonly childId?: SessionId;
     /**
      * The delegation request. The manager reserves the stable child id, resolves
      * the durable descriptor, and composes the child itself.
@@ -109,10 +96,8 @@ export type SubagentInterruptAuthority = {
     readonly kind: 'ancestor';
     readonly agent: Agent;
 };
-/** Options for following up with one continuable child. */
-export interface SubagentFollowupOptions {
-    /** Durable attribution retained on the delivered message; it grants no authority. */
-    readonly source: MessageSource;
+/** Options for one model-authored message between adjacent Agents. */
+export interface SubagentSendMessageOptions {
     /** Caller cancellation, owning the operation only until inbox acceptance. */
     readonly signal: AbortSignal;
 }
@@ -149,7 +134,6 @@ interface ContinuationHost {
 export declare class SubagentContinuationManager {
     private readonly ctx;
     private readonly host;
-    private readonly setupRegistry;
     /** Child session id → its live Activation. Process-local, never durable. */
     private activations;
     /** Materializations admitted before drain, tracked through publication or rollback. */
@@ -165,7 +149,7 @@ export declare class SubagentContinuationManager {
      */
     private readonly closingScopes;
     private draining;
-    constructor(ctx: Context, host: ContinuationHost, setupRegistry: SubagentActivationSetupRegistry);
+    constructor(ctx: Context, host: ContinuationHost);
     /**
      * Start one continuable background child: reserve its durable identity,
      * resolve the provider's detached creation spec, create the child Agent
@@ -183,23 +167,59 @@ export declare class SubagentContinuationManager {
      */
     startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>;
     /**
-     * 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.
+     * 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.
+     */
+    private holdOwnership;
+    /** Reject one child identity already owned by a live Agent or Session. */
+    private assertChildIdAvailable;
+    /**
+     * 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.
+     */
+    sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;
+    /**
+     * 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.
+     */
+    queuePrompt(parent: Agent, childId: SessionId, content: ContentBlock[], source: MessageSource, signal: AbortSignal): Promise<MessageId>;
+    /**
+     * 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.
      */
-    followup(parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions): Promise<MessageId>;
+    steerPrompt(parent: Agent, childId: SessionId, content: ContentBlock[], source: MessageSource, signal: AbortSignal): Promise<MessageId>;
+    /** Route one parent-originated delivery through residency and cold resume. */
+    private deliverToChild;
+    /** The delivery loop behind {@link deliverToChild}, run under the parent hold. */
+    private deliverFollowup;
     /**
      * Interrupt one live continuable child's current turn. Admission is
      * synchronous and the effect is asynchronous: this authorizes the caller,
@@ -222,37 +242,20 @@ export declare class SubagentContinuationManager {
      *   an ancestor outside the target's recorded live lineage.
      */
     interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;
-    /**
-     * 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.
-     */
-    reportFrom(child: Agent, content: ContentBlock[], options: SubagentReportOptions): Promise<MessageId>;
-    /** Authorize only the exact Agent of one resident Activation. */
-    private authorizeReporter;
-    /** Resolve the reporting child's live direct parent from durable lineage. */
-    private resolveReportParent;
-    /** Deliver one framed report through the selected parent scheduling preset. */
-    private deliverReport;
+    /** Deliver one resident continuable child's message to its live direct parent. */
+    private sendToParent;
     /**
      * 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.
      */
     private sendWaking;
-    /** Send one report while translating only the parent's own rejection. */
-    private sendReport;
+    /** Send one Agent message while translating only the target's own rejection. */
+    private sendAgentMessage;
     /**
      * Close admission, await every already-admitted materialization through
      * publication or rollback, then dispose the stable live Activation forest
@@ -273,6 +276,17 @@ export declare class SubagentContinuationManager {
      * @throws an aggregate error after all scoped branches settle when any failed.
      */
     drainDescendants(parents: readonly Agent[]): Promise<void>;
+    /**
+     * 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.
+     */
+    drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;
     /** Dispose independent roots and report every branch failure after all settle. */
     private disposeRoots;
     /** Return the retained member set for one exact scoped-teardown root. */
@@ -304,7 +318,7 @@ export declare class SubagentContinuationManager {
      */
     private stateOf;
     /**
-     * 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
@@ -315,12 +329,24 @@ export declare class SubagentContinuationManager {
      * 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.
      */
     private submitMaterialized;
+    /**
+     * 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.
+     */
+    private assertImageCapable;
     /**
      * Create or resume the child Agent through the private activation-owner
      * scope, install the handle in a fresh Activation, and register ownership on
@@ -430,6 +456,8 @@ export declare class SubagentContinuationManager {
     private flushFinalState;
     /** Resolve the persistence service continuable children require, or fail loud. */
     private requirePersistence;
+    /** Resolve the Session query service used for cold child observations. */
+    private requireSessionQuery;
 }
 export type { SubagentDescriptorData };
 export default SubagentContinuationManager;