@deepseek-ai/dsh-subagent 0.2.0-rc.2 → 0.2.1-alpha.2

package/lib/typert.host.js

@@ -83,7 +83,7 @@ export const TYPERT = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentInterruptReceipt',
         create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":483,"column":3},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":513,"column":3},
     },
     {
       id: '@deepseek-ai/dsh-subagent#subagents/prompt',
@@ -109,16 +109,16 @@ export const TYPERT = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptReceipt',
         create: _deepseek_ai_dsh_subagent_subagents_prompt_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":416,"column":9},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":446,"column":9},
     },
   ],
   model: {
     "services": [
       {
-        "description": "Named provider registry with one-shot runs, durable discovery, and continuable-child operations.",
-        "summary": "Named provider registry with one-shot runs, durable discovery, and continuable-child operations.",
+        "description": "Named provider registry with managed activations, durable discovery, and local child messaging.",
+        "summary": "Named provider registry with managed activations, durable discovery, and local child messaging.",
         "tags": [],
-        "jsDoc": "/** Named provider registry with one-shot runs, durable discovery, and continuable-child operations. */",
+        "jsDoc": "/** Named provider registry with managed activations, durable discovery, and local child messaging. */",
         "key": "subagents",
         "exportName": "SubagentRuntime",
         "members": [
@@ -131,10 +131,24 @@ export const TYPERT = {
           },
           {
             "kind": "method",
-            "name": "startContinuable",
-            "signature": "async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>",
-            "summary": "Establish one durable continuable child and deliver its initial prompt.",
-            "jsDoc": "/**\n * Establish one durable continuable child and deliver its initial prompt.\n * Resolves when the child's inbox accepts that prompt, without waiting for the\n * turn to start or for the message to reach the Session log; any earlier\n * failure rejects with no ids and rolls back the child entirely.\n * @param spec - provider, delegation request, and caller cancellation.\n * @returns the durable child id and the accepted prompt's message id.\n * @throws when continuation services are unavailable or materialization fails.\n */"
+            "name": "startActivation",
+            "signature": "startActivation(spec: SubagentActivationSpec & { readonly childId: SessionId }): Promise<SubagentActivation & { readonly messageId: MessageId }>",
+            "summary": "Start a local child under its reserved identity.",
+            "jsDoc": "/**\n * Start a local child under its reserved identity.\n * @param spec - local task, reserved child id, and result recipient.\n * @returns activation with its accepted initial message id.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "startActivation",
+            "signature": "startActivation(spec: SubagentActivationSpec): Promise<SubagentActivation>",
+            "summary": "Start a local or external child.",
+            "jsDoc": "/**\n * Start a local or external child.\n * @param spec - task, backend, and result recipient.\n * @returns activation with a message id only for local children.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "waitForChildren",
+            "signature": "async waitForChildren(parent: Agent): Promise<boolean>",
+            "summary": "Join progressing descendants without cancelling them.",
+            "jsDoc": "/**\n * Join progressing descendants without cancelling them. Idle descendants whose\n * inboxes require a later wake stay resident and do not delay host completion.\n * @param parent - the exact parent whose descendant work is observed.\n * @returns whether work was joined; hosts recheck parent idle after true.\n */"
           },
           {
             "kind": "method",
@@ -147,22 +161,22 @@ export const TYPERT = {
             "kind": "method",
             "name": "interrupt",
             "signature": "interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void",
-            "summary": "Interrupt one live continuable child's current turn under a human parent address or an exact live ancestor Agent.",
-            "jsDoc": "/**\n * Interrupt one live continuable child's current turn under a human parent\n * address or an exact live ancestor Agent. Fire-and-return: the cancel\n * signal is issued before this returns, but the target may keep running\n * until it observes the signal. Unclaimed pending inbox work, the Activation,\n * and published descendants are preserved; claimed work is not requeued.\n * Once the interrupted driver is idle, a waking send resumes the parked FIFO\n * queue. An absent target — including a one-shot or unknown id —\n * is an accepted no-op, as is a manager-less composition, which cannot own a\n * live Activation.\n * @param targetSessionId - the durable child session id to interrupt.\n * @param authority - the human parent address or exact live ancestor Agent.\n * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the\n *   live target.\n */"
+            "summary": "Interrupt one live child's current execution under a human parent address or an exact live ancestor Agent.",
+            "jsDoc": "/**\n * Interrupt one live child's current execution under a human parent\n * address or an exact live ancestor Agent. Fire-and-return: the cancel\n * signal is issued before this returns, but the target may keep running\n * until it observes the signal. Unclaimed pending inbox work, the Activation,\n * and published descendants are preserved; claimed work is not requeued.\n * Once the interrupted Agent is idle, a waking send resumes the parked FIFO\n * queue. External backends stop their single execution. An absent target\n * is an accepted no-op, as is a manager-less composition, which cannot own a\n * live Activation.\n * @param targetSessionId - the durable child session id to interrupt.\n * @param authority - the human parent address or exact live ancestor Agent.\n * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the\n *   live target.\n */"
           },
           {
             "kind": "method",
-            "name": "drainContinuableDescendants",
-            "signature": "async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>",
-            "summary": "Close continuable admission below exact live parent Agents, stop only their visible descendant Activations synchronously, then await admitted scoped materializations and release those forests child-first.",
-            "jsDoc": "/**\n * Close continuable admission below exact live parent Agents, stop only their\n * visible descendant Activations synchronously, then await admitted scoped\n * materializations and release those forests child-first. The scoped cutoff\n * lasts until each exact parent leaves the registry; unrelated parent trees\n * remain live.\n * @param parents - exact host-owned parent Agents entering teardown.\n * @returns once every retained descendant Activation released its `AgentHandle`.\n * @throws an aggregate error after all branches settle when any failed.\n */"
+            "name": "drainDescendants",
+            "signature": "async drainDescendants(parents: readonly Agent[]): Promise<void>",
+            "summary": "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.",
+            "jsDoc": "/**\n * Close subagent admission below exact live parent Agents, stop only their\n * visible descendant Activations synchronously, then await admitted scoped\n * materializations and release those forests child-first. The scoped cutoff\n * lasts until each exact parent leaves the registry; unrelated parent trees\n * remain live.\n * @param parents - exact host-owned parent Agents entering teardown.\n * @returns once every retained descendant activation released its execution handle.\n * @throws an aggregate error after all branches settle when any failed.\n */"
           },
           {
             "kind": "method",
-            "name": "drainContinuableChildren",
-            "signature": "async drainContinuableChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>",
-            "summary": "Release selected resident continuable direct children of one exact live parent.",
-            "jsDoc": "/**\n * Release selected resident continuable direct children of one exact live\n * parent. Other children of the same parent remain admitted and resident.\n * Absent targets and a manager-less composition are accepted no-ops.\n * @param parent - exact live direct parent authorizing the selected release.\n * @param childIds - durable direct-child ids to release when resident.\n * @returns once every selected Activation released its `AgentHandle`.\n * @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a\n *   different parent or the supplied parent identity is stale.\n */"
+            "name": "drainChildren",
+            "signature": "async drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>",
+            "summary": "Release selected resident direct children of one exact live parent.",
+            "jsDoc": "/**\n * Release selected resident direct children of one exact live\n * parent. Other children of the same parent remain admitted and resident.\n * Absent targets and a manager-less composition are accepted no-ops.\n * @param parent - exact live direct parent authorizing the selected release.\n * @param childIds - durable direct-child ids to release when resident.\n * @returns once every selected activation released its execution handle.\n * @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a\n *   different parent or the supplied parent identity is stale.\n */"
           },
           {
             "kind": "method",
@@ -176,7 +190,7 @@ export const TYPERT = {
             "name": "listDescendants",
             "signature": "listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>",
             "summary": "Recursively list reachable parent catalogs in stable pre-order, preserving each catalog's event order.",
-            "jsDoc": "/**\n * Recursively list reachable parent catalogs in stable pre-order, preserving\n * each catalog's event order. Each row carries its catalog parent and depth;\n * one-shot and unknown-mode children remain traversal nodes. Unknown modes\n * produce unsupported diagnostics. Unreadable child catalogs produce corrupt\n * or unavailable diagnostics and stop only that branch. Root read failures,\n * missing services or projections, and cancellation reject the whole listing.\n * Each catalog is observed once and released before the next read. No Agent\n * is loaded or resumed; Sessions absent from reachable catalogs are omitted.\n * @param rootSessionId - session whose catalog starts descendant discovery.\n * @param signal - cancellation forwarded to and checked around each catalog read.\n * @returns children and branch diagnostics in parent-catalog pre-order.\n * @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.\n * @throws SessionQueryError when the root catalog cannot be read.\n */"
+            "jsDoc": "/**\n * Recursively list reachable parent catalogs in stable pre-order, preserving\n * each catalog's event order. Each row carries its catalog parent and depth;\n * external children are leaves; one-shot and unknown-mode children remain\n * traversal nodes. Unknown modes\n * produce unsupported diagnostics. Unreadable child catalogs produce corrupt\n * or unavailable diagnostics and stop only that branch. Root read failures,\n * missing services or projections, and cancellation reject the whole listing.\n * Each catalog is observed once and released before the next read. No Agent\n * is loaded or resumed; Sessions absent from reachable catalogs are omitted.\n * @param rootSessionId - session whose catalog starts descendant discovery.\n * @param signal - cancellation forwarded to and checked around each catalog read.\n * @returns children and branch diagnostics in parent-catalog pre-order.\n * @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.\n * @throws SessionQueryError when the root catalog cannot be read.\n */"
           },
           {
             "kind": "method",
@@ -197,7 +211,7 @@ export const TYPERT = {
             "name": "registerProvider",
             "signature": "registerProvider(provider: SubagentProvider): () => void",
             "summary": "Register a provider under its name.",
-            "jsDoc": "/**\n * Register a provider under its name. Registration is effect-scoped and HMR\n * safe; removing a provider blocks new starts but does not revoke runs that\n * were already returned to their holders.\n * @param provider - the trusted provider implementation.\n * @returns the exact Cordis effect disposer.\n */"
+            "jsDoc": "/**\n * Register a provider under its name. Registration is effect-scoped and HMR\n * safe; removing a provider blocks new starts but does not revoke runs that\n * were already returned to their holders. Providers without either execution\n * method are rejected with UNSUPPORTED_CAPABILITY before registration.\n * @param provider - the trusted provider implementation.\n * @returns the exact Cordis effect disposer.\n */"
           },
           {
             "kind": "method",
@@ -212,13 +226,6 @@ export const TYPERT = {
             "signature": "list(): string[]",
             "summary": "List registered provider names in insertion order.",
             "jsDoc": "/**\n * List registered provider names in insertion order.\n * @returns the registered names.\n */"
-          },
-          {
-            "kind": "method",
-            "name": "start",
-            "signature": "async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>",
-            "summary": "Establish a published child on the named provider.",
-            "jsDoc": "/**\n * Establish a published child on the named provider. Capability and semantic\n * checks run before delegation. Provider ownership lasts until its promise\n * fulfills; a rejection therefore has no run for the caller to dispose and\n * emits no run lifecycle events. Post-publication turn and infrastructure\n * failures settle through the returned run.\n * A catalog append failure disposes the run and handles its result rejection;\n * the caller receives the catalog error even if disposal also fails.\n * @param name - the provider to use.\n * @param request - child label, prompt, parent, signal, and optional capabilities.\n * @returns the published holder-owned run.\n */"
           }
         ],
         "types": [
@@ -332,20 +339,12 @@ export const TYPERT = {
           },
           {
             "name": "ContinuableCreateRequest",
-            "declaration": "export interface ContinuableCreateRequest {\n    readonly sessionId: SessionId;\n    readonly parent: Agent;\n    readonly signal: AbortSignal;\n}"
+            "declaration": "export interface ContinuableCreateRequest {\n    readonly cwd: string;\n    readonly sessionId: SessionId;\n    readonly parent: Agent;\n    readonly signal: AbortSignal;\n}"
           },
           {
             "name": "ContinuableCreateSpec",
             "declaration": "export interface ContinuableCreateSpec {\n    readonly seed?: readonly SessionEvent[];\n}"
           },
-          {
-            "name": "ContinuableStart",
-            "declaration": "export interface ContinuableStart {\n    readonly childId: SessionId;\n    readonly messageId: MessageId;\n}"
-          },
-          {
-            "name": "ContinuableStartSpec",
-            "declaration": "export interface ContinuableStartSpec {\n    readonly provider: string;\n    readonly label: string;\n    readonly childId?: SessionId;\n    readonly request: Omit<SubagentStartRequest, 'label' | 'signal' | 'outputSchema'>;\n    readonly signal: AbortSignal;\n}"
-          },
           {
             "name": "ContinuableSubagentDescriptorData",
             "declaration": "export interface ContinuableSubagentDescriptorData extends SubagentDescriptorBase {\n    readonly mode: 'continuable';\n    readonly label: string;\n    readonly agentProvider?: string;\n    readonly agentModel?: string;\n    readonly agentReasoningEffort?: ReasoningEffortId;\n    readonly persona?: string;\n    readonly toolFilter?: ToolRestriction;\n}"
@@ -492,16 +491,28 @@ export const TYPERT = {
           },
           {
             "name": "LlmCallConfig",
-            "declaration": "export interface LlmCallConfig {\n    provider: string;\n    model: string;\n    reasoningEffort?: ReasoningEffortId;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}"
+            "declaration": "export interface LlmCallConfig extends LlmCallControls {\n    provider: string;\n    model: string;\n}"
           },
           {
             "name": "LlmCallConfigAdapterDefaults",
             "declaration": "export interface LlmCallConfigAdapterDefaults {\n    reasoningEffort?: true;\n    maxTokens?: true;\n}"
           },
+          {
+            "name": "LlmCallControls",
+            "declaration": "export interface LlmCallControls {\n    reasoningEffort?: ReasoningEffortId;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}"
+          },
           {
             "name": "LlmFailure",
             "declaration": "export interface LlmFailure {\n    readonly message: string;\n    readonly code: string;\n    readonly status?: number;\n    readonly providerRetryAfterMs?: number;\n    readonly requestId?: ProviderRequestId;\n    readonly offloadImages?: number;\n}"
           },
+          {
+            "name": "LlmRetryEventData",
+            "declaration": "export type LlmRetryEventData = { retryId: RetryId; turn: number; step: number; provider: string; mode: 'normal'; policyKey: string; retry: number; maxRetries: number; delayMs: number; failure: LlmFailure; } | { retryId: RetryId; turn: number; step: number; provider: string; mode: 'always'; policyKey: string; retry: number; delayMs: number; failure: LlmFailure; };"
+          },
+          {
+            "name": "LlmRetryStartedEventData",
+            "declaration": "export interface LlmRetryStartedEventData {\n    retryId: RetryId;\n    turn: number;\n    step: number;\n    retry: number;\n}"
+          },
           {
             "name": "Message",
             "declaration": "export type Message = MessageRoleMap[keyof MessageRoleMap];"
@@ -544,7 +555,7 @@ export const TYPERT = {
           },
           {
             "name": "MessageSourceMap",
-            "declaration": "export interface MessageSourceMap {\n    user: { kind: 'user'; };\n    model: ModelMessageSource;\n    tool: ToolMessageSource;\n    'system-prompt': SystemPromptMessageSource;\n    'model-selection': { kind: 'model-selection'; } & ContextFormed;\n    'user-approval': { kind: 'user-approval'; } & ContextFormed;\n    'ptc-mode': { kind: 'ptc-mode'; };\n    'tool-registry': { kind: 'tool-registry'; };\n    'user-rpc': { kind: 'user'; rpcId: SessionRequestId; clientTimeZone?: string; };\n    'agent-message': AgentMessageSource;\n    'subagent-settled': SubagentSettledMessageSource;\n    'skill-invocation': SkillInvocationSource;\n    'cordis-host-runner': { kind: 'cordis-host-runner'; };\n    goal: GoalMessageSource;\n    schedule: { kind: 'schedule'; } & ContextFormed;\n    'compact-checkpoint': CompactionCheckpointSource;\n    'session-reference': SessionReferenceSource;\n    'user-question-reply': { kind: 'user-question-reply'; callId: ToolCallId; outcome: 'answered'; };\n}"
+            "declaration": "export interface MessageSourceMap {\n    user: { kind: 'user'; };\n    model: ModelMessageSource;\n    tool: ToolMessageSource;\n    'system-prompt': SystemPromptMessageSource;\n    'model-selection': { kind: 'model-selection'; } & ContextFormed;\n    'working-directory': { kind: 'working-directory'; };\n    'user-approval': { kind: 'user-approval'; } & ContextFormed;\n    'ptc-mode': { kind: 'ptc-mode'; };\n    'tool-registry': { kind: 'tool-registry'; };\n    'user-rpc': { kind: 'user'; rpcId: SessionRequestId; clientTimeZone?: string; };\n    'agent-message': AgentMessageSource;\n    'subagent-settled': SubagentSettledMessageSource;\n    'skill-invocation': SkillInvocationSource;\n    'cordis-host-runner': { kind: 'cordis-host-runner'; };\n    'compact-checkpoint': CompactionCheckpointSource;\n    'user-question-reply': { kind: 'user-question-reply'; callId: ToolCallId; outcome: 'answered'; };\n    goal: GoalMessageSource;\n    schedule: { kind: 'schedule'; } & ContextFormed;\n    'session-reference': SessionReferenceSource;\n}"
           },
           {
             "name": "ModelMessageSource",
@@ -580,7 +591,7 @@ export const TYPERT = {
           },
           {
             "name": "PtcDispatchEventData",
-            "declaration": "export interface PtcDispatchEventData extends PtcDispatchStartEventData {\n    isError: boolean;\n    content: ContentBlock[];\n    error?: { name: string; code: string; reason?: string; };\n}"
+            "declaration": "export interface PtcDispatchEventData extends PtcDispatchStartEventData {\n    isError: boolean;\n    content: ContentBlock[];\n    meta?: JsonValue;\n    error?: { name: string; code: string; reason?: string; };\n}"
           },
           {
             "name": "PtcDispatchStartEventData",
@@ -608,7 +619,11 @@ export const TYPERT = {
           },
           {
             "name": "ResolvedSubagentStartRequest",
-            "declaration": "export interface ResolvedSubagentStartRequest extends SubagentStartRequest {\n    readonly descriptor: SubagentDescriptorData;\n}"
+            "declaration": "export interface ResolvedSubagentStartRequest extends SubagentStartRequest {\n    readonly cwd: string;\n}"
+          },
+          {
+            "name": "RetryId",
+            "declaration": "export type RetryId = Branded<'RetryId'>;"
           },
           {
             "name": "SandboxMode",
@@ -644,7 +659,7 @@ export const TYPERT = {
           },
           {
             "name": "SessionEventMap",
-            "declaration": "export interface SessionEventMap {\n    'turn/start': { turn: number; };\n    'turn/end': { turn: number; reason: TurnEndReason; };\n    'step/start': { turn: number; step: number; };\n    'step/end': { turn: number; step: number; };\n    'user/message': UserMessage;\n    'developer/message': { turn: number; step: number; message: DeveloperMessage; headerSeq?: SessionSeq; };\n    'system/message': { turn: number; step: number; message: SystemMessage; };\n    'assistant/message': { turn: number; step: number; message: AssistantMessage; stream: AssistantStreamRecord[]; usage?: TokenUsage; interrupted?: true; };\n    'assistant/attempt': { turn: number; step: number; stream: AssistantStreamRecord[]; };\n    'tool/call': { turn: number; step: number; callId: ToolCallId; name: string; arguments: string; };\n    'tool/result': { turn: number; step: number; message: ToolResultMessage; error?: { name: string; code: string; reason?: string; }; meta?: JsonValue; };\n    'request/header': { header: EpochHeader; reason: RequestHeaderReason; startsSeries?: true; };\n    'request/context': RequestContext;\n    'session/end-seed': { inherited?: true; };\n    'agent/inbox/spliced': { target: InboxTarget; start: number; removedCount?: number; inserted: UserMessage[]; outcome?: 'canceled'; };\n    'sandbox/mode': { mode: SandboxMode; source?: 'delegation'; };\n    'approval/asked': { id: ApprovalRequestId; toolName: string; callId?: ToolCallId; reason?: string; };\n    'approval/decided': { id: ApprovalRequestId; outcome: ApprovalOutcome; };\n    'approval/policy': { policy: ApprovalPolicy; source?: 'delegation'; };\n    'tool/ptc-dispatch-start': PtcDispatchStartEventData;\n    'tool/ptc-dispatch': PtcDispatchEventData;\n    'agent-preset/selected': { agentPreset: string; };\n    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource; };\n    'command/done': { commandId: CommandId; kind: 'success' | 'error'; text?: string; sourceEventSeq?: import('@deepseek-ai/dsh-session/types').SessionSeq; };\n    'image/offload': { targets: ImageOffloadTarget[]; };\n    'session/title': SessionTitleEventData;\n    'todo/write': { todos: TodoItem[]; };\n    'model/selection': ModelSelection;\n    'subagent/descriptor': SubagentDescriptorData;\n    'permission/preset': { preset: string; };\n    'subagent/catalog': SubagentCatalogEvent;\n    'compaction/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; };\n    'compaction/summary': { compactionId: CompactionId; sourceCommandId?: CommandId; summary: ContentBlock[]; shadowedRange: { start: SessionSeq; end: SessionSeq; }; shadowedSeqs: SessionSeq[]; shadowedTokenCount: number; provider: string; model: string; maxTokens?: number; usage?: TokenUsage; } & ({ rawOutput: ContentBlock[]; llmStreamCall: true; } | { rawOutput?: ContentBlock[]; llmStreamCall?: never; });\n    'compaction/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string; };\n    'compaction/prune': { shadowedRange: { start: SessionSeq; end: SessionSeq; }; shadowedSeqs: SessionSeq[]; shadowedTokenCount: number; };\n    'feedback/record': FeedbackRecord;\n    'goal/change': GoalChangeMeta;\n    'feedback/message-put': MessageFeedbackPut;\n    'feedback/message-delete': MessageFeedbackDelete;\n    'schedule/change': ScheduleChange;\n}"
+            "declaration": "export interface SessionEventMap {\n    'turn/start': { turn: number; };\n    'turn/end': { turn: number; reason: TurnEndReason; };\n    'step/start': { turn: number; step: number; };\n    'step/end': { turn: number; step: number; };\n    'user/message': UserMessage;\n    'developer/message': { turn: number; step: number; message: DeveloperMessage; headerSeq?: SessionSeq; };\n    'system/message': { turn: number; step: number; message: SystemMessage; };\n    'assistant/message': { turn: number; step: number; message: AssistantMessage; stream: AssistantStreamRecord[]; usage?: TokenUsage; interrupted?: true; };\n    'assistant/attempt': { turn: number; step: number; stream: AssistantStreamRecord[]; };\n    'tool/call': { turn: number; step: number; callId: ToolCallId; name: string; arguments: string; };\n    'tool/result': { turn: number; step: number; message: ToolResultMessage; error?: { name: string; code: string; reason?: string; }; meta?: JsonValue; };\n    'request/header': { header: EpochHeader; reason: RequestHeaderReason; startsSeries?: true; };\n    'request/context': RequestContext;\n    'session/end-seed': { inherited?: true; };\n    'agent/inbox/spliced': { target: InboxTarget; start: number; removedCount?: number; inserted: UserMessage[]; outcome?: 'canceled'; };\n    'working-directory/change': { cwd: string; };\n    'sandbox/mode': { mode: SandboxMode; source?: 'delegation'; };\n    'approval/asked': { id: ApprovalRequestId; toolName: string; callId?: ToolCallId; reason?: string; };\n    'approval/decided': { id: ApprovalRequestId; outcome: ApprovalOutcome; };\n    'approval/policy': { policy: ApprovalPolicy; source?: 'delegation'; };\n    'tool/ptc-dispatch-start': PtcDispatchStartEventData;\n    'tool/ptc-dispatch': PtcDispatchEventData;\n    'agent-preset/selected': { agentPreset: string; };\n    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource; };\n    'command/done': { commandId: CommandId; kind: 'success' | 'error'; text?: string; sourceEventSeq?: import('@deepseek-ai/dsh-session/types').SessionSeq; };\n    'image/offload': { targets: ImageOffloadTarget[]; };\n    'session/title': SessionTitleEventData;\n    'todo/write': { todos: TodoItem[]; };\n    'model/selection': ModelSelection;\n    'permission/preset': { preset: string; };\n    'subagent/descriptor': SubagentDescriptorData;\n    'subagent/catalog': SubagentCatalogEvent;\n    'compaction/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; };\n    'compaction/summary': { compactionId: CompactionId; sourceCommandId?: CommandId; summary: ContentBlock[]; shadowedRange: { start: SessionSeq; end: SessionSeq; }; shadowedSeqs: SessionSeq[]; shadowedTokenCount: number; provider: string; model: string; maxTokens?: number; usage?: TokenUsage; } & ({ rawOutput: ContentBlock[]; llmStreamCall: true; } | { rawOutput?: ContentBlock[]; llmStreamCall?: never; });\n    'compaction/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string; };\n    'compaction/prune': { shadowedRange: { start: SessionSeq; end: SessionSeq; }; shadowedSeqs: SessionSeq[]; shadowedTokenCount: number; };\n    'feedback/record': FeedbackRecord;\n    'llm/retry': LlmRetryEventData;\n    'llm/retry-started': LlmRetryStartedEventData;\n    'goal/change': GoalChangeMeta;\n    'feedback/message-put': MessageFeedbackPut;\n    'feedback/message-delete': MessageFeedbackDelete;\n    'schedule/change': ScheduleChange;\n}"
           },
           {
             "name": "SessionEventType",
@@ -702,21 +717,29 @@ export const TYPERT = {
             "name": "StreamChunk",
             "declaration": "export type StreamChunk = { type: 'block-start'; index: number; blockType: ContentBlockType; } | { type: 'text-delta'; index: number; text: string; } | { type: 'reasoning-delta'; index: number; text: string; } | { type: 'tool-call-delta'; index: number; id: ToolCallId; name?: string; argumentsDelta: string; } | { type: 'block-end'; index: number; block: ContentBlock; } | { type: 'usage'; usage: TokenUsage; } | { type: 'finish'; reason: FinishReason; replayState?: ReplayEnvelope; };"
           },
+          {
+            "name": "SubagentActivation",
+            "declaration": "export interface SubagentActivation {\n    readonly childId: SessionId;\n    readonly messageId?: MessageId;\n    readonly result: Promise<SubagentResult>;\n    dispose(): Promise<void>;\n}"
+          },
+          {
+            "name": "SubagentActivationSpec",
+            "declaration": "export interface SubagentActivationSpec {\n    readonly provider: string;\n    readonly label: string;\n    readonly childId?: SessionId;\n    readonly request: Omit<SubagentStartRequest, 'label' | 'signal'>;\n    readonly signal: AbortSignal;\n    readonly delivery: 'parent' | 'caller';\n}"
+          },
           {
             "name": "SubagentCapabilities",
             "declaration": "export interface SubagentCapabilities {\n    readonly agentOptions: boolean;\n    readonly outputSchema: boolean;\n    readonly depthLimit: boolean;\n    readonly toolFilter: boolean;\n    readonly persona: boolean;\n}"
           },
           {
             "name": "SubagentCatalogEntry",
-            "declaration": "export type SubagentCatalogEntry = { readonly id: SessionId; readonly createdAt: number; } & ({ readonly mode: 'one-shot'; readonly label?: string; } | { readonly mode: 'continuable'; readonly label: string; } | { readonly mode: 'unknown'; readonly label?: string; });"
+            "declaration": "export type SubagentCatalogEntry = { readonly id: SessionId; readonly createdAt: number; } & ({ readonly mode: 'one-shot'; readonly label?: string; } | { readonly mode: 'external'; readonly label?: string; } | { readonly mode: 'continuable'; readonly label: string; } | { readonly mode: 'unknown'; readonly label?: string; });"
           },
           {
             "name": "SubagentCatalogEvent",
-            "declaration": "export type SubagentCatalogEvent = { readonly childId: SessionId; readonly childCreatedAt: number; } & (({ readonly version: 0; } & KnownCatalogMode) | ({ readonly version: 1; } & (KnownCatalogMode | { readonly mode: 'unknown'; readonly label?: string; })));"
+            "declaration": "export type SubagentCatalogEvent = { readonly childId: SessionId; readonly childCreatedAt: number; } & (({ readonly version: 0; } & KnownCatalogMode) | ({ readonly version: 1; } & (KnownCatalogMode | { readonly mode: 'unknown'; readonly label?: string; })) | { readonly version: 2; readonly mode: 'external'; readonly label?: string; });"
           },
           {
             "name": "SubagentCatalogRow",
-            "declaration": "export type SubagentCatalogRow = { readonly id: SessionId; readonly activity: 'running' | 'inactive'; } & ({ readonly mode: 'one-shot'; readonly label?: string; } | { readonly mode: 'continuable'; readonly label: string; });"
+            "declaration": "export type SubagentCatalogRow = { readonly id: SessionId; readonly activity: 'running' | 'inactive'; } & ({ readonly mode: 'one-shot'; readonly label?: string; } | { readonly mode: 'external'; readonly label?: string; } | { readonly mode: 'continuable'; readonly label: string; });"
           },
           {
             "name": "SubagentDescendantListEntry",
@@ -756,7 +779,7 @@ export const TYPERT = {
           },
           {
             "name": "SubagentProvider",
-            "declaration": "export interface SubagentProvider {\n    readonly name: string;\n    readonly capabilities: SubagentCapabilities;\n    readonly inheritsParentContext: boolean;\n    readonly agentRouteDefaults?: Readonly<{ provider: string; model: string; }>;\n    start(request: ResolvedSubagentStartRequest): Promise<SubagentRun>;\n    prepareContinuable?(request: ContinuableCreateRequest): Promise<ContinuableCreateSpec>;\n}"
+            "declaration": "export interface SubagentProvider {\n    readonly name: string;\n    readonly capabilities: SubagentCapabilities;\n    readonly inheritsParentContext: boolean;\n    readonly agentRouteDefaults?: Readonly<{ provider: string; model: string; }>;\n    start?(request: ResolvedSubagentStartRequest): Promise<SubagentRun>;\n    prepareContinuable?(request: ContinuableCreateRequest): Promise<ContinuableCreateSpec>;\n}"
           },
           {
             "name": "SubagentResult",
@@ -764,7 +787,7 @@ export const TYPERT = {
           },
           {
             "name": "SubagentRun",
-            "declaration": "export interface SubagentRun {\n    readonly id: SessionId;\n    readonly localAgent: Agent | undefined;\n    readonly result: Promise<SubagentResult>;\n    dispose(): Promise<void>;\n}"
+            "declaration": "export interface SubagentRun {\n    readonly id: SessionId;\n    readonly result: Promise<SubagentResult>;\n    dispose(): Promise<void>;\n}"
           },
           {
             "name": "SubagentSendMessageOptions",
@@ -776,7 +799,7 @@ export const TYPERT = {
           },
           {
             "name": "SubagentStartRequest",
-            "declaration": "export interface SubagentStartRequest {\n    readonly label?: string;\n    readonly prompt: ContentBlock[];\n    readonly parent: Agent;\n    readonly signal: AbortSignal;\n    readonly agentOptions?: AgentOptions;\n    readonly outputSchema?: ObjectJsonSchema;\n    readonly maxDepth?: number;\n    readonly toolFilter?: ToolRestriction;\n    readonly persona?: string;\n}"
+            "declaration": "export interface SubagentStartRequest {\n    readonly cwd?: string;\n    readonly label?: string;\n    readonly prompt: ContentBlock[];\n    readonly parent: Agent;\n    readonly signal: AbortSignal;\n    readonly agentOptions?: AgentOptions;\n    readonly outputSchema?: ObjectJsonSchema;\n    readonly maxDepth?: number;\n    readonly toolFilter?: ToolRestriction;\n    readonly persona?: string;\n}"
           },
           {
             "name": "SubagentStopReason",
@@ -888,18 +911,13 @@ export const TYPERT = {
             "comment": "- the run identity and terminal outcome.",
             "text": "@param info - the run identity and terminal outcome.\n     *"
           },
-          {
-            "name": "dshScopeScan",
-            "comment": "unsupported",
-            "text": "@dshScopeScan unsupported\n     *"
-          },
           {
             "name": "mode",
             "comment": "emit",
             "text": "@mode emit"
           }
         ],
-        "jsDoc": "/**\n * A published child settled. Scope-filtered dispatch uses the same delegating\n * parent carrier as `subagent/start`, so the lifecycle pair reaches the\n * same scoped audience.\n * @param info - the run identity and terminal outcome.\n * @dshScopeScan unsupported\n * @mode emit\n */",
+        "jsDoc": "/**\n * A published child settled. Scope-filtered dispatch uses the same delegating\n * parent carrier as `subagent/start`, so the lifecycle pair reaches the\n * same scoped audience.\n * @param info - the run identity and terminal outcome.\n * @mode emit\n */",
         "name": "subagent/end",
         "mode": "emit",
         "signature": "'subagent/end'(this: Scoped<SubagentRuntime>, info: SubagentRunEndInfo): void"
@@ -956,18 +974,13 @@ export const TYPERT = {
             "comment": "- the provider and published child identity.",
             "text": "@param info - the provider and published child identity.\n     *"
           },
-          {
-            "name": "dshScopeScan",
-            "comment": "unsupported",
-            "text": "@dshScopeScan unsupported\n     *"
-          },
           {
             "name": "mode",
             "comment": "emit",
             "text": "@mode emit"
           }
         ],
-        "jsDoc": "/**\n * A provider established a published child. For in-process providers,\n * `ctx.agents.get(info.id)` resolves during this notification.\n * Scope-filtered dispatch keys the carrier by the delegating parent, so a\n * parent-scoped listener observes only its own delegations. Paired with\n * `subagent/end`.\n * @param info - the provider and published child identity.\n * @dshScopeScan unsupported\n * @mode emit\n */",
+        "jsDoc": "/**\n * A provider established a published child. For in-process providers,\n * `ctx.agents.get(info.id)` resolves during this notification.\n * Scope-filtered dispatch keys the carrier by the delegating parent, so a\n * parent-scoped listener observes only its own delegations. Paired with\n * `subagent/end`.\n * @param info - the provider and published child identity.\n * @mode emit\n */",
         "name": "subagent/start",
         "mode": "emit",
         "signature": "'subagent/start'(this: Scoped<SubagentRuntime>, info: SubagentRunInfo): void"

package/lib/typert.remote-client.js

@@ -80,7 +80,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentInterruptReceipt',
         create: _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":483,"column":3},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":513,"column":3},
     },
     {
       id: '@deepseek-ai/dsh-subagent#subagents/prompt',
@@ -106,7 +106,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptReceipt',
         create: _deepseek_ai_dsh_subagent_subagents_prompt_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":416,"column":9},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":446,"column":9},
     },
   ],
 }

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