@fishwithcat/dsh-subagent 0.2.2-alpha.2 → 0.2.2-alpha.3

package/lib/types/continuation-messages.js

@@ -4,7 +4,7 @@
  * @module @deepseek-ai/dsh-subagent/continuation-messages
  */
 import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm';
-/** Build durable attribution for one adjacent-Agent message. */
+/** Build durable attribution for one Agent message. */
 function agentMessageSource(sender) {
     return {
         kind: 'agent-message',
@@ -13,7 +13,7 @@ function agentMessageSource(sender) {
     };
 }
 /**
- * Build the model-visible and durable representation of one adjacent-Agent message.
+ * Build the model-visible and durable representation of one Agent message.
  * @param sender - exact live Agent that authored the message.
  * @param content - model-visible message blocks supplied by the sender.
  * @returns the durable user-message representation delivered to the recipient.
@@ -28,22 +28,19 @@ export function createAgentMessage(sender, content) {
     });
 }
 /**
- * Append adjacent-Agent return guidance to a continuable child's initial task.
- * @param parentId - durable parent session id named in the guidance.
+ * Append automatic result-delivery guidance to a parent-delivered child's initial task.
  * @param prompt - initial model-visible task blocks.
- * @returns task blocks followed by the continuable return guidance.
+ * @returns task blocks followed by the result-delivery guidance.
  */
-export function withContinuableReturnGuidance(parentId, prompt) {
-    const encodedParentId = JSON.stringify(parentId);
+export function withResultDeliveryGuidance(prompt) {
     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.',
+            text: 'Your final answer is delivered automatically if your '
+                + 'parent is still online. Include the result and relevant evidence in that answer; the parent does not '
+                + 'receive your full transcript, tool output, or reasoning. If your last action is a message to your '
+                + 'parent, the completion notice omits your final answer; include the result and relevant evidence in that message.',
         },
     ];
 }
@@ -84,8 +81,8 @@ function settlementSummary(childId, stopReason, continuable) {
  * @param childId - durable child session id named in the notice.
  * @param terminal - recorded terminal state for the settled Activation.
  * @param continuable - whether the child can accept another task.
- * @param omitClosingText - replace the closing text with a note that the child's
- *   last message to the parent already carries it.
+ * @param omitClosingText - replace the closing text when the child's last action
+ *   was a message to its direct parent.
  * @returns the durable user-message representation delivered to the parent.
  */
 export function createSettlementMessage(childId, terminal, continuable = true, omitClosingText = false) {
@@ -111,6 +108,7 @@ export function createSettlementMessage(childId, terminal, continuable = true, o
             kind: 'subagent-settled',
             form: 'notice',
             summary: boundContextSummary(summary),
+            stopReason: terminal.stopReason,
             senderSessionId: childId,
         },
     });

package/lib/types/control-types.d.ts

@@ -8,6 +8,7 @@ import type { PromptContentPart } from '@deepseek-ai/dsh-attachment/types';
 import type { Branded } from '@deepseek-ai/dsh-brand';
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { KnownSubagentCatalogFields } from './projection-types.ts';
 /**
  * Client-minted identity of one browser prompt, persisted on the exact accepted
  * message. It carries the Session Controller's `session-request-id` brand so a
@@ -25,22 +26,7 @@ export type SubagentCatalogRow = {
      * does not encode a durable outcome or guarantee continuation delivery.
      */
     readonly activity: 'running' | 'inactive';
-} & ({
-    /** A terminal one-shot child. */
-    readonly mode: 'one-shot';
-    /** Optional durable creation label from the parent catalog. */
-    readonly label?: string;
-} | {
-    /** An external execution without a local child Session. */
-    readonly mode: 'external';
-    /** Optional durable creation label from the parent catalog. */
-    readonly label?: string;
-} | {
-    /** A resumable conversation. */
-    readonly mode: 'continuable';
-    /** Durable creation label from the parent catalog. */
-    readonly label: string;
-});
+} & KnownSubagentCatalogFields;
 /**
  * One recursive catalog row. Traversal may also return diagnostics for
  * unknown catalog modes or unreadable child catalogs.
@@ -72,18 +58,15 @@ export type SubagentAddress = {
 } | {
     readonly mode: 'unknown';
 });
-/** One Agent inbox destination, as the prompt request selects it. */
-export type SubagentDelivery = SubagentPromptRequest['delivery'];
-/** One human message addressed to a continuable direct child. */
+/** One Agent inbox destination for a continuation message. */
+export type SubagentDelivery = 'queue' | 'steer';
+/** One human message addressed to a continuable subagent. */
 export interface SubagentPromptRequest {
     /** Identity persisted on the accepted message, minted before the call. */
     readonly requestId: SubagentPromptRequestId;
-    readonly parentSessionId: SessionId;
     readonly childSessionId: SessionId;
-    /** Required discriminator retained from the browser control address. */
-    readonly mode: 'continuable';
     /** Whether this message queues a later turn or targets the nearest step. */
-    readonly delivery: 'queue' | 'steer';
+    readonly delivery: SubagentDelivery;
     /**
      * Browser prompt parts delivered as the child's user message. The Host
      * admits and persists image parts before delivery, so the wire never
@@ -117,15 +100,11 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
         'subagent/invalid-time-zone': {
             readonly value: string;
         };
-        /** No live Agent carries the addressed parent session. */
-        'subagent/parent-unavailable': {
-            readonly parentSessionId: SessionId;
-        };
         /** The addressed child cannot take a continuation. */
         'subagent/not-resumable': {
             readonly childSessionId: SessionId;
         };
-        /** The claimed parent does not own the addressed child. */
+        /** The supplied address or live subagent-tree identity could not be verified. */
         'subagent/unauthorized': {
             readonly childSessionId: SessionId;
         };

package/lib/types/control.d.ts

@@ -8,18 +8,14 @@ import type { SessionId } from '@deepseek-ai/dsh-session';
 import { z } from 'zod';
 declare const CONTROL_ID_SCHEMAS: {
     readonly 'subagent.prompt': z.ZodObject<{
-        parentSessionId: z.ZodString;
         childSessionId: z.ZodString;
-        mode: z.ZodLiteral<"continuable">;
         delivery: z.ZodEnum<{
             queue: "queue";
             steer: "steer";
         }>;
     }, z.core.$strip>;
     readonly 'subagent.interrupt': z.ZodObject<{
-        parentSessionId: z.ZodString;
         childSessionId: z.ZodString;
-        mode: z.ZodLiteral<"continuable">;
     }, z.core.$strip>;
 };
 /**

package/lib/types/control.js

@@ -11,15 +11,11 @@ import { SubagentError } from "./error.js";
 const SESSION_ID_SCHEMA = z.string().min(1);
 const CONTROL_ID_SCHEMAS = {
     'subagent.prompt': z.object({
-        parentSessionId: SESSION_ID_SCHEMA,
         childSessionId: SESSION_ID_SCHEMA,
-        mode: z.literal('continuable'),
         delivery: z.enum(['queue', 'steer']),
     }),
     'subagent.interrupt': z.object({
-        parentSessionId: SESSION_ID_SCHEMA,
         childSessionId: SESSION_ID_SCHEMA,
-        mode: z.literal('continuable'),
     }),
 };
 /**
@@ -59,7 +55,7 @@ export function rejectPrompt(error, childSessionId, signal) {
             case 'NOT_RESUMABLE':
                 throw new RemoteError('subagent/not-resumable', 'subagent cannot be resumed', { childSessionId }, { cause: error });
             case 'UNAUTHORIZED':
-                throw new RemoteError('subagent/unauthorized', 'subagent does not belong to this parent', { childSessionId }, { cause: error });
+                throw new RemoteError('subagent/unauthorized', 'subagent membership in the active tree could not be verified', { childSessionId }, { cause: error });
             case 'DRAINING':
             case 'ACTIVATION_CLOSING':
             case 'ACTIVATION_LIMIT_REACHED':

package/lib/types/descriptor.d.ts

@@ -14,7 +14,7 @@
  * to one activation's result contract rather than durable child composition.
  * Per-activation knobs such as `maxTokens` are omitted for the same reason as
  * `outputSchema`: they budget one activation. Cold resume requires the exact
- * live parent for authorization but reconstructs child options only from the
+ * live subagent tree root for authorization but reconstructs child options only from the
  * durable descriptor, so it neither restores the prior budget nor inherits
  * the parent's current one; the resumed route's defaults apply instead.
  *

package/lib/types/descriptor.js

@@ -14,7 +14,7 @@
  * to one activation's result contract rather than durable child composition.
  * Per-activation knobs such as `maxTokens` are omitted for the same reason as
  * `outputSchema`: they budget one activation. Cold resume requires the exact
- * live parent for authorization but reconstructs child options only from the
+ * live subagent tree root for authorization but reconstructs child options only from the
  * durable descriptor, so it neither restores the prior budget nor inherits
  * the parent's current one; the resumed route's defaults apply instead.
  *

package/lib/types/index.d.ts

@@ -14,7 +14,7 @@
  * `startActivation` establishes every child under the activation manager, which
  * owns execution, result delivery, and resource release. Local providers seed
  * resumable Agents; external providers return a single execution handle.
- * `sendMessage` steers between adjacent local Agents without exposing
+ * `sendMessage` steers between local Agents in one subagent tree without exposing
  * whether a child is resident. Discovery combines real child Sessions with
  * parent-owned records for external executions.
  * Direct discovery reads parent catalogs; descendants recursively read reachable
@@ -38,10 +38,9 @@ import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { SubagentInterruptReceipt, SubagentPromptReceipt, SubagentPromptRequest } from './control-types.ts';
 import type { SubagentActivation, SubagentActivationSpec, SubagentInterruptAuthority, SubagentProvider, SubagentRunEndInfo, SubagentRunInfo, SubagentSendMessageOptions } from './types.ts';
 import type { SubagentDescendantListEntry } from './list-children.ts';
-import type { SubagentCatalogEntry } from './projection-types.ts';
-import { deliverSubagentPrompt } from './internal.ts';
 import type { DelegatedApprovalPolicy } from './child-agent.ts';
 export type {} from './catalog.ts';
+export type {} from './projection.ts';
 export * from './out-of-process.ts';
 export { AssistantOutputFold, finalAssistantOutput } from './assistant-output.ts';
 export { SubagentRunId } from './types.ts';
@@ -78,18 +77,18 @@ declare module '@deepseek-ai/cordis' {
         /**
          * A provider established a published child. For in-process providers,
          * `ctx.agents.get(info.id)` resolves during this notification.
-         * Scope-filtered dispatch keys the carrier by the delegating parent, so a
-         * parent-scoped listener observes only its own delegations. Paired with
+         * Scope-filtered dispatch keys the carrier by the subagent tree root, so a
+         * root-scoped listener observes all subagent tree activations. Paired with
          * `subagent/end`.
-         * @param info - the provider and published child identity.
+         * @param info - provider, child identity, and durable direct creator `parentSessionId`.
          * @mode emit
          */
         'subagent/start'(this: Scoped<SubagentRuntime>, info: SubagentRunInfo): void;
         /**
-         * A published child settled. Scope-filtered dispatch uses the same delegating
-         * parent carrier as `subagent/start`, so the lifecycle pair reaches the
+         * A published child settled. Scope-filtered dispatch uses the same subagent tree-root
+         * carrier as `subagent/start`, so the lifecycle pair reaches the
          * same scoped audience.
-         * @param info - the run identity and terminal outcome.
+         * @param info - run identity, durable direct creator `parentSessionId`, and terminal outcome.
          * @mode emit
          */
         'subagent/end'(this: Scoped<SubagentRuntime>, info: SubagentRunEndInfo): void;
@@ -156,43 +155,36 @@ export declare class SubagentRuntime extends TypertRemoteService {
      */
     startActivation(spec: SubagentActivationSpec): Promise<SubagentActivation>;
     /**
-     * Join progressing descendants without cancelling them. Idle descendants whose
-     * inboxes require a later wake stay resident and do not delay host completion.
-     * @param parent - the exact parent whose descendant work is observed.
-     * @returns whether work was joined; hosts recheck parent idle after true.
+     * Resolve the root shared by an Agent and its other agents in its subagent tree.
+     * @param caller - exact live Agent whose subagent ancestry selects the tree.
+     * @returns the live root; ordinary Session forks lead independent trees.
+     * @throws when the caller or its runtime owner is unavailable.
      */
-    waitForChildren(parent: Agent): Promise<boolean>;
+    rootOf(caller: Agent): Agent;
     /**
-     * Steer one model-authored message to the sender's direct parent or direct
-     * continuable child. A running target admits it at the nearest step boundary;
-     * an idle target starts a turn, and an absent direct child cold-resumes from
-     * persistence. The service derives durable sender attribution from the exact
-     * live sender. Caller cancellation stops only pre-acceptance work.
-     * @param sender - exact live Agent authorizing and originating the message.
-     * @param targetId - durable direct-parent or direct-child session id.
+     * Join progressing subagent tree work for its root. Idle members with parked input
+     * stay resident without delaying host completion. Ordinary members return false.
+     * @param root - exact live subagent tree root whose member work is awaited.
+     * @returns whether work was joined; hosts recheck root idle after true.
+     */
+    waitForTreeWork(root: Agent): Promise<boolean>;
+    /**
+     * Steer one model-authored message to another member of the same subagent tree.
+     * A running target receives it at its next step; an idle target starts a turn.
+     * A cold target resumes under its runtime subagent tree root without restoring
+     * its creation ancestors. Sender identity is rechecked before inbox acceptance; cancellation
+     * stops only pre-acceptance work and never retracts an accepted message.
+     * @param sender - exact live root or resident continuable Agent originating the message.
+     * @param targetId - another root or continuable member's durable Session id.
      * @param content - model-authored content to deliver.
      * @param options - caller cancellation before inbox acceptance.
      * @returns the accepted message's inbox id.
-     * @throws when continuation services are unavailable, adjacency is rejected,
-     *   or the message was not admitted.
+     * @throws when the target is outside the tree, cannot resume, or rejects input.
      */
     sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;
     /**
-     * Deliver one host-protocol message to a direct continuable child.
-     * Symbol-keyed so host adapters can preserve their own source descriptors without
-     * widening the public Service Definition or impersonating an Agent sender.
-     * @param parent - exact live direct parent authorizing delivery.
-     * @param childId - durable direct-child session id.
-     * @param content - host-authored content to deliver.
-     * @param source - durable host-protocol source descriptor.
-     * @param signal - caller cancellation before inbox acceptance.
-     * @param delivery - Queue as a distinct turn or Steer at the nearest step.
-     * @returns the accepted message's inbox id.
-     */
-    private [deliverSubagentPrompt];
-    /**
-     * Interrupt one live child's current execution under a human parent
-     * address or an exact live ancestor Agent. Fire-and-return: the cancel
+     * Interrupt one live child's current execution under a trusted user
+     * operation or an exact live ancestor Agent. Fire-and-return: the cancel
      * signal is issued before this returns, but the target may keep running
      * until it observes the signal. Unclaimed pending inbox work, the Activation,
      * and published descendants are preserved; claimed work is not requeued.
@@ -201,43 +193,20 @@ export declare class SubagentRuntime extends TypertRemoteService {
      * is an accepted no-op, as is a manager-less composition, which cannot own a
      * live Activation.
      * @param targetSessionId - the durable child session id to interrupt.
-     * @param authority - the human parent address or exact live ancestor Agent.
+     * @param authority - a trusted user operation or exact live ancestor Agent.
      * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
      *   live target.
      */
     interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;
     /**
-     * Close subagent admission below exact live parent Agents, stop only their
-     * visible descendant Activations synchronously, then await admitted scoped
-     * materializations and release those forests child-first. The scoped cutoff
-     * lasts until each exact parent leaves the registry; unrelated parent trees
-     * remain live.
-     * @param parents - exact host-owned parent Agents entering teardown.
-     * @returns once every retained descendant activation released its execution handle.
+     * Close admission and stop all instances in the selected subagent trees, then await
+     * pending startup and cleanup. Ordinary members are ignored. The cutoff lasts
+     * until each exact root leaves the registry; unrelated subagent trees remain live.
+     * @param parents - exact live subagent tree roots entering teardown.
+     * @returns once all admitted startup and member cleanup have settled.
      * @throws an aggregate error after all branches settle when any failed.
      */
     drainDescendants(parents: readonly Agent[]): Promise<void>;
-    /**
-     * Release selected resident direct children of one exact live
-     * parent. Other children of the same parent remain admitted and resident.
-     * Absent targets and a manager-less composition are accepted no-ops.
-     * @param parent - exact live direct parent authorizing the selected release.
-     * @param childIds - durable direct-child ids to release when resident.
-     * @returns once every selected activation released its execution handle.
-     * @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a
-     *   different parent or the supplied parent identity is stale.
-     */
-    drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;
-    /**
-     * Read the parent's durable direct-child catalog without loading or resuming an Agent.
-     * The service owns and releases the live-preferred Session observation.
-     * @param parentSessionId - parent whose direct children are requested.
-     * @param signal - cancellation forwarded to the Session query.
-     * @returns catalog children in parent event order.
-     * @throws {@link SubagentError} when query or catalog projection is unavailable.
-     * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
-     */
-    listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>;
     /**
      * Recursively list reachable parent catalogs in stable pre-order, preserving
      * each catalog's event order. Each row carries its catalog parent and depth;
@@ -256,8 +225,8 @@ export declare class SubagentRuntime extends TypertRemoteService {
      */
     listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;
     /**
-     * Deliver one browser-authored message to a continuable child through the
-     * exact live direct parent, retaining the caller-minted request identity and
+     * Deliver one browser-authored message to a continuable child through its
+     * live subagent tree root, retaining the caller-minted request identity and
      * validated browser zone on the accepted message. Success identifies the
      * message the child's inbox accepted; later execution is independent of this
      * call. Queue delivery targets a later turn; steer delivery targets the
@@ -265,30 +234,26 @@ export declare class SubagentRuntime extends TypertRemoteService {
      * Image parts are admitted and persisted through the attachment store
      * before delivery, and the child's model must accept image input.
      * Cold resume at capacity rejects with `subagent/delivery-unavailable`.
-     * @param request - durable address, delivery, minted identity, content, and optional browser zone.
+     * Access is checked on the target Session before attachment admission or restoration.
+     * @param request - target id, delivery, minted identity, content, and optional browser zone.
      * @param signal - carrier cancellation, owning the call until inbox acceptance.
      * @returns the accepted message's inbox identity.
      * @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`,
-     *   `subagent/invalid-time-zone`, `subagent/parent-unavailable`,
+     *   `subagent/invalid-time-zone`,
      *   `subagent/not-resumable`, `subagent/unauthorized`,
      *   `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.
      */
     prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>;
     /**
-     * Remote face of {@link interrupt} under one durable parent address. No
-     * catalog, history, persistence, or parent Agent lookup runs: the core
-     * primitive alone authorizes the address against the live Activation, which
-     * is what keeps a live child interruptible while its parent Agent is offline.
+     * Remote face of {@link interrupt}, authorized on the target Session by the Gateway.
+     * No catalog, history, persistence, or parent Agent lookup runs.
      * Absent, idle, and already-completed targets are accepted no-ops there.
      * @param childSessionId - durable child session id to interrupt.
-     * @param parentSessionId - durable direct parent whose authority is claimed.
-     * @param mode - required continuable-address discriminator.
      * @returns acknowledgement that the cancel signal was admitted, not that the target is quiescent.
      * @throws {RemoteError} `gateway/bad-request` for an empty id,
-     *   `subagent/unauthorized` when the address does not own the live target,
      *   otherwise `gateway/internal`.
      */
-    interruptByParent(childSessionId: SessionId, parentSessionId: SessionId, mode: 'continuable'): SubagentInterruptReceipt;
+    interruptByUser(childSessionId: SessionId): SubagentInterruptReceipt;
     /**
      * Register a provider under its name. Registration is effect-scoped and HMR
      * safe; removing a provider blocks new starts but does not revoke runs that
@@ -304,26 +269,12 @@ export declare class SubagentRuntime extends TypertRemoteService {
      * @returns the provider, or undefined when absent.
      */
     getProvider(name: string): SubagentProvider | undefined;
-    /**
-     * List registered provider names in insertion order.
-     * @returns the registered names.
-     */
-    list(): string[];
-    /**
-     * Resolve one provider's detached continuable-creation contribution. Method
-     * presence on the provider IS the capability, so a provider without it is
-     * rejected before the manager reserves any child resources.
-     */
-    private prepareContinuable;
+    /** A pending start must use the exact provider whose capabilities were checked. */
+    private assertProviderCurrent;
     /** Look up a provider for dispatch or fail loud. */
     private expectProvider;
     /** Resolve the subagent manager or fail loud. */
     private requireManager;
-    /**
-     * Build the lifecycle observer for one continuable Activation's residency
-     * epoch, so the manager publishes its edges without owning event dispatch.
-     */
-    private observeActivation;
     /** Reject the first requested capability that the provider lacks. */
     private assertCapabilities;
 }