@deepseek-ai/dsh-subagent 0.2.1-alpha.1 → 0.2.1-alpha.3

package/lib/typert.remote-client.d.ts

@@ -1,7 +1,8 @@
 /* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
 import type {
   RemoteResult,
-  TypertRemoteContribution,
+  TypertRemoteInfo,
+  TypertRemoteMethod,
 } from '@deepseek-ai/dsh-typert-protocol'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { SubagentInterruptReceipt, SubagentPromptReceipt, SubagentPromptRequest } from '@deepseek-ai/dsh-subagent/client'
@@ -20,6 +21,9 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
   }
 }
 
-export declare const TYPERT_REMOTE: TypertRemoteContribution
+export declare const TYPERT_REMOTE: TypertRemoteInfo<{
+  readonly 'subagents/interruptByParent': TypertRemoteMethod<{ readonly 'childSessionId': SessionId; readonly 'parentSessionId': SessionId; readonly 'mode': 'continuable' }, SubagentInterruptReceipt>
+  readonly 'subagents/prompt': TypertRemoteMethod<{ readonly 'request': SubagentPromptRequest }, SubagentPromptReceipt>
+}>
 export default TYPERT_REMOTE
 //# sourceMappingURL=typert.remote-client.d.ts.map

package/lib/typert.remote-client.js

@@ -1,10 +1,12 @@
 /* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
 import { z } from 'zod'
 
+import { createTypertRemoteInfo } from '@deepseek-ai/dsh-typert-protocol/remote-info'
+
 let _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema$value
-const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema$value ??= z.string())
 let _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema$value
-const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema$value ??= z.intersection(z.string(), z.unknown()))
+const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema$value ??= z.string())
 let _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2$schema$value
 const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2$schema$value ??= z.literal("continuable"))
 let _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema$value
@@ -13,11 +15,11 @@ const _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema = () =
 }))
 let _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema$value
 const _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema = () => (_deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema$value ??= z.object({
-  'requestId': z.intersection(z.string(), z.unknown()).readonly(),
-  'parentSessionId': z.intersection(z.string(), z.unknown()).readonly(),
-  'childSessionId': z.intersection(z.string(), z.unknown()).readonly(),
-  'mode': z.literal("continuable").readonly(),
-  'delivery': z.union([z.literal("queue"), z.literal("steer")]).readonly(),
+  'requestId': z.string().readonly().describe('Identity persisted on the accepted message, minted before the call.'),
+  'parentSessionId': z.string().readonly(),
+  'childSessionId': z.string().readonly(),
+  'mode': z.literal("continuable").readonly().describe('Required discriminator retained from the browser control address.'),
+  'delivery': z.union([z.literal("queue"), z.literal("steer")]).readonly().describe('Whether this message queues a later turn or targets the nearest step.'),
   'content': z.array(z.union([z.object({
   'type': z.literal("text").readonly(),
   'text': z.string().readonly(),
@@ -26,52 +28,95 @@ const _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema = () => (_de
   'mediaType': z.union([z.literal("image/png"), z.literal("image/jpeg"), z.literal("image/webp"), z.literal("image/gif")]).readonly(),
   'data': z.string().readonly(),
   'name': z.string().readonly().optional(),
-})])).readonly(),
-  'clientTimeZone': z.string().readonly().optional(),
+})])).readonly().describe('Browser prompt parts delivered as the child\'s user message. The Host admits and persists image parts before delivery, so the wire never carries a durable attachment reference the caller could fabricate.'),
+  'clientTimeZone': z.string().readonly().optional().describe('Optional browser zone sampled for this exact human prompt.'),
 }))
 let _deepseek_ai_dsh_subagent_subagents_prompt_result$schema$value
 const _deepseek_ai_dsh_subagent_subagents_prompt_result$schema = () => (_deepseek_ai_dsh_subagent_subagents_prompt_result$schema$value ??= z.object({
-  'messageId': z.intersection(z.string(), z.unknown()).readonly(),
+  'messageId': z.string().readonly(),
+}))
+let _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0_strict$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0_strict$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0_strict$schema$value ??= z.string())
+let _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1_strict$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1_strict$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1_strict$schema$value ??= z.string())
+let _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2_strict$schema$value
+const _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2_strict$schema = () => (_deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2_strict$schema$value ??= z.literal("continuable"))
+let _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0_strict$schema$value
+const _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0_strict$schema = () => (_deepseek_ai_dsh_subagent_subagents_prompt_parameter_0_strict$schema$value ??= z.strictObject({
+  'requestId': z.string().readonly().describe('Identity persisted on the accepted message, minted before the call.'),
+  'parentSessionId': z.string().readonly(),
+  'childSessionId': z.string().readonly(),
+  'mode': z.literal("continuable").readonly().describe('Required discriminator retained from the browser control address.'),
+  'delivery': z.union([z.literal("queue"), z.literal("steer")]).readonly().describe('Whether this message queues a later turn or targets the nearest step.'),
+  'content': z.array(z.union([z.strictObject({
+  'type': z.literal("text").readonly(),
+  'text': z.string().readonly(),
+}), z.strictObject({
+  'type': z.literal("image").readonly(),
+  'mediaType': z.union([z.literal("image/png"), z.literal("image/jpeg"), z.literal("image/webp"), z.literal("image/gif")]).readonly(),
+  'data': z.string().readonly(),
+  'name': z.string().readonly().optional(),
+})])).readonly().describe('Browser prompt parts delivered as the child\'s user message. The Host admits and persists image parts before delivery, so the wire never carries a durable attachment reference the caller could fabricate.'),
+  'clientTimeZone': z.string().readonly().optional().describe('Optional browser zone sampled for this exact human prompt.'),
 }))
 
-export const TYPERT_REMOTE = {
+export const TYPERT_REMOTE = createTypertRemoteInfo({
   package: '@deepseek-ai/dsh-subagent',
-  descriptors: [
-    {
-      id: '@deepseek-ai/dsh-subagent#subagents/interruptByParent',
+  methods: {
+    'subagents/interruptByParent': {
       service: 'subagents',
-      namespace: 'subagents',
-      method: 'interruptByParent',
+      description: 'Remote face of {@link interrupt} under one durable parent address. No catalog, history, persistence, or parent Agent lookup runs: the core primitive alone authorizes the address against the live Activation, which is what keeps a live child interruptible while its parent Agent is offline. Absent, idle, and already-completed targets are accepted no-ops there.',
       invocation: { kind: 'direct' },
       parameters: [
         {
           name: 'childSessionId',
-          wire: 'childSessionId',
+          description: 'durable child session id to interrupt.',
           source: 'json',
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
             create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0$schema,
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_0_strict$schema,
+            jsonSchema: {"type":"string"},
           },
         },
         {
           name: 'parentSessionId',
-          wire: 'parentSessionId',
+          description: 'durable direct parent whose authority is claimed.',
           source: 'json',
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
             create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1$schema,
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_1_strict$schema,
+            jsonSchema: {"type":"string"},
           },
         },
         {
           name: 'mode',
-          wire: 'mode',
+          description: 'required continuable-address discriminator.',
           source: 'json',
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-subagent#subagents/interruptByParent:mode',
             create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2$schema,
+            jsonSchema: {"type":"string","const":"continuable"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-subagent#subagents/interruptByParent:mode',
+            create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_parameter_2_strict$schema,
+            jsonSchema: {"type":"string","const":"continuable"},
           },
         },
       ],
@@ -79,24 +124,31 @@ export const TYPERT_REMOTE = {
         mode: 'strict',
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentInterruptReceipt',
         create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema,
+        description: 'acknowledgement that the cancel signal was admitted, not that the target is quiescent.',
+        jsonSchema: {"type":"object","properties":{"accepted":{"type":"boolean","const":true}},"required":["accepted"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":481,"column":3},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":517,"column":3},
     },
-    {
-      id: '@deepseek-ai/dsh-subagent#subagents/prompt',
+    'subagents/prompt': {
       service: 'subagents',
-      namespace: 'subagents',
-      method: 'prompt',
+      description: 'Deliver one browser-authored message to a continuable child through the exact live direct parent, retaining the caller-minted request identity and validated browser zone on the accepted message. Success identifies the message the child\'s inbox accepted; later execution is independent of this call. Queue delivery targets a later turn; steer delivery targets the nearest step and retains the Agent loop\'s best-effort fallback semantics. Image parts are admitted and persisted through the attachment store before delivery, and the child\'s model must accept image input. Cold resume at capacity rejects with `subagent/delivery-unavailable`.',
       invocation: { kind: 'direct' },
       parameters: [
         {
           name: 'request',
-          wire: 'request',
+          description: 'durable address, delivery, minted identity, content, and optional browser zone.',
           source: 'json',
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptRequest',
             create: _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0$schema,
+            jsonSchema: {"type":"object","properties":{"requestId":{"type":"string","description":"Identity persisted on the accepted message, minted before the call."},"parentSessionId":{"type":"string"},"childSessionId":{"type":"string"},"mode":{"type":"string","const":"continuable","description":"Required discriminator retained from the browser control address."},"delivery":{"type":"string","enum":["queue","steer"],"description":"Whether this message queues a later turn or targets the nearest step."},"content":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":true},{"type":"object","properties":{"type":{"type":"string","const":"image"},"mediaType":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/gif"]},"data":{"type":"string"},"name":{"type":"string"}},"required":["type","mediaType","data"],"additionalProperties":true}]},"description":"Browser prompt parts delivered as the child's user message. The Host admits and persists image parts before delivery, so the wire never carries a durable attachment reference the caller could fabricate."},"clientTimeZone":{"type":"string","description":"Optional browser zone sampled for this exact human prompt."}},"required":["requestId","parentSessionId","childSessionId","mode","delivery","content"],"additionalProperties":true},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptRequest',
+            create: _deepseek_ai_dsh_subagent_subagents_prompt_parameter_0_strict$schema,
+            jsonSchema: {"type":"object","properties":{"requestId":{"type":"string","description":"Identity persisted on the accepted message, minted before the call."},"parentSessionId":{"type":"string"},"childSessionId":{"type":"string"},"mode":{"type":"string","const":"continuable","description":"Required discriminator retained from the browser control address."},"delivery":{"type":"string","enum":["queue","steer"],"description":"Whether this message queues a later turn or targets the nearest step."},"content":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image"},"mediaType":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/gif"]},"data":{"type":"string"},"name":{"type":"string"}},"required":["type","mediaType","data"],"additionalProperties":false}]},"description":"Browser prompt parts delivered as the child's user message. The Host admits and persists image parts before delivery, so the wire never carries a durable attachment reference the caller could fabricate."},"clientTimeZone":{"type":"string","description":"Optional browser zone sampled for this exact human prompt."}},"required":["requestId","parentSessionId","childSessionId","mode","delivery","content"],"additionalProperties":false},
           },
         },
       ],
@@ -105,10 +157,12 @@ export const TYPERT_REMOTE = {
         mode: 'strict',
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptReceipt',
         create: _deepseek_ai_dsh_subagent_subagents_prompt_result$schema,
+        description: 'the accepted message\'s inbox identity.',
+        jsonSchema: {"type":"object","properties":{"messageId":{"type":"string"}},"required":["messageId"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":414,"column":9},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":448,"column":9},
     },
-  ],
-}
+  },
+}, z)
 
 export default TYPERT_REMOTE

package/lib/types/activation.d.ts

@@ -0,0 +1,114 @@
+/** Execution-period records, capacity slots, child serialization, and local output capture.
+ * @module @deepseek-ai/dsh-subagent/activation
+ */
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session';
+import type { ActivationObserver } from './lifecycle.ts';
+import type { StructuredAttachment } from './structured.ts';
+import type { SubagentResult, SubagentRun } from './types.ts';
+/** Process-local slots shared through uninterrupted continuable parent links. */
+export declare class ActivationPool {
+    private readonly slots;
+    /**
+     * Reserve before reconstruction; release also tolerates unpublished rollback.
+     * @param capacity - the maximum simultaneous activations in this pool.
+     * @returns an idempotent slot release.
+     */
+    reserve(capacity: number): () => void;
+}
+/**
+ * One residency epoch for a local child or an external execution.
+ * The manager owns admission, execution handles, and resource release.
+ */
+interface ActivationBase {
+    /** Shared capacity for this Activation and all its managed descendants. */
+    readonly pool: ActivationPool;
+    /** Return this epoch's slot after its handle has finished disposal. */
+    readonly releaseSlot: () => void;
+    /** The durable child this Activation is an epoch of. */
+    readonly childId: SessionId;
+    readonly parent: Agent;
+    readonly delivery: 'parent' | 'caller';
+    readonly result: PromiseWithResolvers<SubagentResult>;
+    /** Published synchronously before teardown; subsequent callers share this transaction. */
+    closing: Promise<void> | undefined;
+    /**
+     * Exact live Agent ancestry observed when this Activation materialized.
+     * Weak membership preserves host-scope identity across an intermediate
+     * ancestor leaving the registry without retaining that ancestor's runtime.
+     */
+    readonly ancestry: WeakSet<Agent>;
+    /**
+     * Session ids of the child Activations this one owns. Because one Session has
+     * at most one live Activation, the id identifies the live child without
+     * another runtime-incarnation reference. Non-empty blocks settlement.
+     */
+    readonly ownedChildren: Set<SessionId>;
+    /** The lifecycle observer that emits this epoch's start and terminal edges. */
+    readonly observer: ActivationObserver;
+    /**
+     * Whether any delivery to this child was ever accepted. A materialization
+     * rolled back before its first acceptance is a child the caller was told does
+     * not exist, so its teardown owes the parent no settlement account.
+     */
+    announced: boolean;
+}
+/** Resources retained only for the selected execution kind. */
+export type ActivationResource = {
+    readonly kind: 'local';
+    readonly handle: AgentHandle;
+    readonly outputStart: SessionLogOffset;
+    readonly structured: StructuredAttachment | undefined;
+    /** Latest live failure not superseded by a later committed turn ending. */
+    failureAt: SessionLogOffset | undefined;
+    /** Renewed when local settlement must recheck input or owned children. */
+    poke: PromiseWithResolvers<void>;
+} | {
+    readonly kind: 'external';
+    readonly run: SubagentRun;
+    readonly controller: AbortController;
+};
+/** One managed execution period with its provider-specific resources. */
+export type Activation = ActivationBase & ActivationResource;
+/** Local residency with input admission and Session-backed result capture. */
+export type LocalActivation = Extract<Activation, {
+    kind: 'local';
+}>;
+/**
+ * Read the live Agent retained by local execution.
+ * @param activation - the managed local or external execution.
+ * @returns the local Agent, absent for an external run.
+ */
+export declare function activationAgent(activation: Activation): Agent | undefined;
+/**
+ * Require local residency before accepting further input.
+ * @param activation - execution targeted by message delivery.
+ * @returns the local activation.
+ * @throws when the external backend cannot accept another message.
+ */
+export declare function requireLocalActivation(activation: Activation): LocalActivation;
+/**
+ * Retain local failures whose turn ending could not be committed.
+ * @param activation - exact local Agent and epoch receiving the scoped observers.
+ * @param wake - notify its settlement watcher when failure changes readiness.
+ */
+export declare function observeLocalFailure(activation: LocalActivation, wake: () => void): void;
+/**
+ * Capture local output and retain failures without a later committed turn ending.
+ * @param activation - the settled local execution and any structured result.
+ * @returns final output, stop reason, and committed structured value.
+ */
+export declare function captureLocalResult(activation: LocalActivation): SubagentResult;
+/** Serialize each durable child's delivery, release, and disposal. */
+export declare class ChildLock {
+    private tails;
+    /**
+     * Run `operation` after every previously queued operation for `childId`.
+     * @param childId - the durable child whose operations are linearized.
+     * @param operation - the critical section to run in order.
+     * @returns the operation's own settlement.
+     */
+    run<T>(childId: SessionId, operation: () => Promise<T>): Promise<T>;
+}
+export {};
+//# sourceMappingURL=activation.d.ts.map

package/lib/types/activation.js

@@ -0,0 +1,112 @@
+/** Execution-period records, capacity slots, child serialization, and local output capture.
+ * @module @deepseek-ai/dsh-subagent/activation
+ */
+import { assertNever } from '@deepseek-ai/dsh-util-values';
+import { finalAssistantOutput } from "./assistant-output.js";
+import { epochStopReason } from "./lifecycle.js";
+import { SubagentError } from "./error.js";
+/** Process-local slots shared through uninterrupted continuable parent links. */
+export class ActivationPool {
+    slots = new Set();
+    /**
+     * Reserve before reconstruction; release also tolerates unpublished rollback.
+     * @param capacity - the maximum simultaneous activations in this pool.
+     * @returns an idempotent slot release.
+     */
+    reserve(capacity) {
+        if (this.slots.size >= capacity) {
+            throw new SubagentError(`subagent limit reached (active child limit: ${capacity}); wait for an existing child to finish `
+                + 'or complete this work with the current agents', 'ACTIVATION_LIMIT_REACHED');
+        }
+        const slot = Symbol();
+        this.slots.add(slot);
+        return () => { this.slots.delete(slot); };
+    }
+}
+/**
+ * Read the live Agent retained by local execution.
+ * @param activation - the managed local or external execution.
+ * @returns the local Agent, absent for an external run.
+ */
+export function activationAgent(activation) {
+    return activation.kind === 'local' ? activation.handle.agent : undefined;
+}
+/**
+ * Require local residency before accepting further input.
+ * @param activation - execution targeted by message delivery.
+ * @returns the local activation.
+ * @throws when the external backend cannot accept another message.
+ */
+export function requireLocalActivation(activation) {
+    switch (activation.kind) {
+        case 'local': return activation;
+        case 'external':
+            throw new SubagentError(`subagent "${activation.childId}" does not accept follow-up input`, 'NOT_CONTINUABLE');
+        /* v8 ignore next 2 -- Both execution kinds are handled above. */
+        default: return assertNever(activation);
+    }
+}
+/**
+ * Retain local failures whose turn ending could not be committed.
+ * @param activation - exact local Agent and epoch receiving the scoped observers.
+ * @param wake - notify its settlement watcher when failure changes readiness.
+ */
+export function observeLocalFailure(activation, wake) {
+    const child = activation.handle.agent;
+    child.ctx.on('agent/error', ({ agent }) => {
+        if (agent !== child)
+            return;
+        activation.failureAt = child.session.seq;
+        wake();
+    });
+    child.ctx.on('session/event', (session, event) => {
+        if (session === child.session && event.type === 'turn/end'
+            && activation.failureAt !== undefined && event.seq >= activation.failureAt) {
+            activation.failureAt = undefined;
+        }
+    });
+}
+/**
+ * Capture local output and retain failures without a later committed turn ending.
+ * @param activation - the settled local execution and any structured result.
+ * @returns final output, stop reason, and committed structured value.
+ */
+export function captureLocalResult(activation) {
+    // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+    const events = activation.handle.agent.session.snapshotEvents(activation.outputStart);
+    const output = finalAssistantOutput(events) ?? [];
+    const stopReason = activation.failureAt === undefined ? epochStopReason(events) : 'error';
+    const structured = activation.structured;
+    if (structured !== undefined) {
+        const captured = structured.captured();
+        if (captured !== undefined)
+            return { output, stopReason, structured: captured.value };
+        if (stopReason === 'completed')
+            return { output, stopReason: 'error' };
+    }
+    return { output, stopReason };
+}
+/** Serialize each durable child's delivery, release, and disposal. */
+export class ChildLock {
+    tails = new Map();
+    /**
+     * Run `operation` after every previously queued operation for `childId`.
+     * @param childId - the durable child whose operations are linearized.
+     * @param operation - the critical section to run in order.
+     * @returns the operation's own settlement.
+     */
+    run(childId, operation) {
+        const previous = this.tails.get(childId) ?? Promise.resolve();
+        const result = previous.then(operation, operation);
+        // Absorb rejections in the chaining tail so one failed critical section
+        // cannot reject an unrelated later caller.
+        const tail = result.then(() => undefined, () => undefined);
+        this.tails.set(childId, tail);
+        void tail.then(() => {
+            if (this.tails.get(childId) === tail)
+                this.tails.delete(childId);
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=activation.js.map

package/lib/types/catalog.d.ts

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import type { ChunkedList } from '@deepseek-ai/dsh-chunked-list';
 import type { Session, SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session';
 import type { SubagentCatalogEntry } from './projection-types.ts';
-/** Catalog payload version emitted by live child creation. */
+/** Catalog payload version emitted by local child creation. */
 export declare const SUBAGENT_CATALOG_VERSION = 0;
 type KnownCatalogMode = {
     readonly mode: 'one-shot';
@@ -16,7 +16,7 @@ type KnownCatalogMode = {
     readonly mode: 'continuable';
     readonly label: string;
 };
-/** Parent catalog v0 records known modes; v1 also retains children with unknown mode. */
+/** Parent catalog v0 records local modes, v1 adds unknown children, and v2 records external executions. */
 export type SubagentCatalogEvent = {
     readonly childId: SessionId;
     readonly childCreatedAt: number;
@@ -27,7 +27,11 @@ export type SubagentCatalogEvent = {
 } & (KnownCatalogMode | {
     readonly mode: 'unknown';
     readonly label?: string;
-})));
+})) | {
+    readonly version: 2;
+    readonly mode: 'external';
+    readonly label?: string;
+});
 declare module '@deepseek-ai/dsh-session/types' {
     interface SessionEventMap {
         /**
@@ -74,11 +78,15 @@ export declare const subagentCatalogProjectionDefinition: {
  * @param descriptor - mode-discriminated creation label frozen with the child.
  */
 export declare function establishCatalogChild(parent: Session, child: SessionHeader, descriptor: {
-    readonly mode: 'one-shot';
-    readonly label?: string;
-} | {
     readonly mode: 'continuable';
     readonly label: string;
 }): void;
+/**
+ * Record an external execution without a local child Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param childId - identity returned by the external provider.
+ * @param label - display label assigned by the caller.
+ */
+export declare function establishExternalCatalogChild(parent: Session, childId: SessionId, label: string): void;
 export {};
 //# sourceMappingURL=catalog.d.ts.map

package/lib/types/catalog.js

@@ -5,7 +5,7 @@
  */
 import { z } from 'zod';
 import { appendChunkedList, chunkedListSchema, iterateChunkedList } from '@deepseek-ai/dsh-chunked-list';
-/** Catalog payload version emitted by live child creation. */
+/** Catalog payload version emitted by local child creation. */
 export const SUBAGENT_CATALOG_VERSION = 0;
 const sessionIdSchema = z.string();
 const oneShotCatalogSchema = z.object({
@@ -22,9 +22,11 @@ const continuableCatalogSchema = z.object({
     mode: z.literal('continuable'),
     label: z.string(),
 }).strict();
+const externalCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(2), mode: z.literal('external') });
 const unknownCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(1), mode: z.literal('unknown') });
 const eventDataSchema = z.union([
     oneShotCatalogSchema,
+    externalCatalogSchema,
     continuableCatalogSchema,
     unknownCatalogSchema,
 ]);
@@ -33,6 +35,10 @@ const viewSchema = z.array(z.union([
         id: sessionIdSchema,
         createdAt: oneShotCatalogSchema.shape.childCreatedAt,
     }),
+    externalCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: externalCatalogSchema.shape.childCreatedAt,
+    }),
     continuableCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
         id: sessionIdSchema,
         createdAt: continuableCatalogSchema.shape.childCreatedAt,
@@ -54,19 +60,8 @@ const stateSchema = z.object({
 function subagentCatalogEntries(state) {
     const entries = [];
     for (const data of iterateChunkedList(state.head)) {
-        entries.push(data.mode !== 'continuable'
-            ? {
-                id: data.childId,
-                createdAt: data.childCreatedAt,
-                mode: data.mode,
-                ...data.label === undefined ? {} : { label: data.label },
-            }
-            : {
-                id: data.childId,
-                createdAt: data.childCreatedAt,
-                mode: data.mode,
-                label: data.label,
-            });
+        const { version: _version, childId, childCreatedAt, ...descriptor } = data;
+        entries.push({ id: childId, createdAt: childCreatedAt, ...descriptor });
     }
     return entries;
 }
@@ -80,7 +75,7 @@ export const subagentCatalogProjectionDefinition = {
             return state;
         return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) };
     },
-    stateVersion: 3,
+    stateVersion: 6,
     wire: { viewSchema, view: subagentCatalogEntries },
 };
 /**
@@ -90,20 +85,29 @@ export const subagentCatalogProjectionDefinition = {
  * @param descriptor - mode-discriminated creation label frozen with the child.
  */
 export function establishCatalogChild(parent, child, descriptor) {
-    parent.append('subagent/catalog', descriptor.mode === 'one-shot'
-        ? {
-            version: SUBAGENT_CATALOG_VERSION,
-            childId: child.id,
-            childCreatedAt: child.createdAt,
-            mode: descriptor.mode,
-            ...descriptor.label === undefined ? {} : { label: descriptor.label },
-        }
-        : {
-            version: SUBAGENT_CATALOG_VERSION,
-            childId: child.id,
-            childCreatedAt: child.createdAt,
-            mode: descriptor.mode,
-            label: descriptor.label,
-        });
+    parent.append('subagent/catalog', {
+        version: SUBAGENT_CATALOG_VERSION,
+        childId: child.id,
+        childCreatedAt: child.createdAt,
+        mode: descriptor.mode,
+        label: descriptor.label,
+    });
+}
+/** Catalog payload version emitted by external execution creation. */
+const EXTERNAL_SUBAGENT_CATALOG_VERSION = 2;
+/**
+ * Record an external execution without a local child Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param childId - identity returned by the external provider.
+ * @param label - display label assigned by the caller.
+ */
+export function establishExternalCatalogChild(parent, childId, label) {
+    parent.append('subagent/catalog', {
+        version: EXTERNAL_SUBAGENT_CATALOG_VERSION,
+        childId,
+        childCreatedAt: Date.now(),
+        mode: 'external',
+        label,
+    });
 }
 //# sourceMappingURL=catalog.js.map