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

package/lib/typert.host.js

@@ -175,8 +175,8 @@ export const TYPERT = {
             "kind": "method",
             "name": "listDescendants",
             "signature": "listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>",
-            "summary": "Enumerate the root's complete session-backed subagent tree in stable pre-order from one live-preferred corpus, without loading or resuming an Agent.",
-            "jsDoc": "/**\n * Enumerate the root's complete session-backed subagent tree in stable\n * pre-order from one live-preferred corpus, without loading or resuming an\n * Agent. Ordinary sessions and one-shot children remain traversal nodes so\n * continuable descendants below them are discovered; each returned entry\n * adds its durable `parentId` and root-relative `depth`. Identity resolution,\n * diagnostics, optional persistence, and cancellation use the registered\n * child identity projection and complete Session corpus.\n * @param rootSessionId - session whose complete descendant tree is listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-candidate diagnostics with tree position, in\n *   stable pre-order.\n * @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.\n */"
+            "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 */"
           },
           {
             "kind": "method",
@@ -222,6 +222,10 @@ export const TYPERT = {
           }
         ],
         "types": [
+          {
+            "name": "AfterScheduleRecord",
+            "declaration": "export interface AfterScheduleRecord {\n    readonly id: ScheduleId;\n    readonly kind: 'after';\n    readonly title: string;\n    readonly prompt: string;\n    readonly afterSeconds: number;\n    readonly scheduledAt: string;\n}"
+          },
           {
             "name": "Agent",
             "declaration": "export interface Agent {\n    readonly id: SessionId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly inbox: Inbox;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n    whenIdle(): Promise<void>;\n    runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;\n    send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;\n    followup(message: UserMessage): void;\n    steer(message: UserMessage): void;\n    inject(message: UserMessage): void;\n}"
@@ -266,6 +270,10 @@ export const TYPERT = {
             "name": "AssistantStreamRecord",
             "declaration": "export type AssistantStreamRecord = { readonly type: 'text-chunks'; readonly time0: number; readonly index: number; readonly dt: readonly number[]; readonly texts: readonly string[]; } | { readonly type: 'reasoning-chunks'; readonly time0: number; readonly index: number; readonly dt: readonly number[]; readonly texts: readonly string[]; } | { readonly type: 'tool-call-chunks'; readonly time0: number; readonly index: number; readonly dt: readonly number[]; readonly id: ToolCallId; readonly name?: string; readonly args: readonly string[]; } | { readonly type: 'chunk'; readonly time: number; readonly chunk: StreamChunk; };"
           },
+          {
+            "name": "AtScheduleRecord",
+            "declaration": "export interface AtScheduleRecord {\n    readonly id: ScheduleId;\n    readonly kind: 'at';\n    readonly title: string;\n    readonly prompt: string;\n    readonly scheduledAt: string;\n}"
+          },
           {
             "name": "AttachmentId",
             "declaration": "export type AttachmentId = Branded<'AttachmentId'>;"
@@ -350,6 +358,14 @@ export const TYPERT = {
             "name": "EpochHeader",
             "declaration": "export interface EpochHeader {\n    config: LlmCallConfig;\n    adapterDefaults?: LlmCallConfigAdapterDefaults;\n    tools?: ToolSchema[];\n    system?: never;\n}"
           },
+          {
+            "name": "EveryScheduleDispatchChange",
+            "declaration": "export interface EveryScheduleDispatchChange {\n    readonly version: 1;\n    readonly operation: 'dispatch';\n    readonly id: ScheduleId;\n    readonly acceptedAt: string;\n}"
+          },
+          {
+            "name": "EveryScheduleRecord",
+            "declaration": "export interface EveryScheduleRecord {\n    readonly id: ScheduleId;\n    readonly kind: 'every';\n    readonly title: string;\n    readonly prompt: string;\n    readonly everySeconds: number;\n    readonly scheduledAt: string;\n}"
+          },
           {
             "name": "FeedbackCategory",
             "declaration": "export type FeedbackCategory = 'task-result' | 'instruction-following' | 'product-interaction' | 'service-stability' | 'resource-cost' | 'security-privacy-permission' | 'other';"
@@ -458,6 +474,22 @@ export const TYPERT = {
             "name": "KnownCatalogMode",
             "declaration": "export type KnownCatalogMode = { readonly mode: 'one-shot'; readonly label?: string; } | { readonly mode: 'continuable'; readonly label: string; };"
           },
+          {
+            "name": "LegacyAfterScheduleRecord",
+            "declaration": "export interface LegacyAfterScheduleRecord extends Omit<AfterScheduleRecord, 'title'> {\n    readonly title?: string;\n}"
+          },
+          {
+            "name": "LegacyAtScheduleRecord",
+            "declaration": "export interface LegacyAtScheduleRecord extends Omit<AtScheduleRecord, 'title'> {\n    readonly title?: string;\n}"
+          },
+          {
+            "name": "LegacyEveryScheduleRecord",
+            "declaration": "export interface LegacyEveryScheduleRecord extends Omit<EveryScheduleRecord, 'title'> {\n    readonly title?: string;\n}"
+          },
+          {
+            "name": "LegacyScheduleRecord",
+            "declaration": "export type LegacyScheduleRecord = LegacyAfterScheduleRecord | LegacyAtScheduleRecord | LegacyEveryScheduleRecord;"
+          },
           {
             "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}"
@@ -512,7 +544,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    'team-message': TeamMessageSource;\n    goal: GoalMessageSource;\n    'compact-checkpoint': CompactionCheckpointSource;\n    'session-reference': SessionReferenceSource;\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    '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}"
           },
           {
             "name": "ModelMessageSource",
@@ -526,6 +558,10 @@ export const TYPERT = {
             "name": "ObjectJsonSchema",
             "declaration": "export type ObjectJsonSchema = JsonSchemaNode & { type: 'object'; };"
           },
+          {
+            "name": "OneShotScheduleDispatchChange",
+            "declaration": "export interface OneShotScheduleDispatchChange {\n    readonly version: 1;\n    readonly operation: 'dispatch';\n    readonly id: ScheduleId;\n}"
+          },
           {
             "name": "OneShotSubagentDescriptorData",
             "declaration": "export interface OneShotSubagentDescriptorData extends SubagentDescriptorBase {\n    readonly mode: 'one-shot';\n    readonly label?: string;\n}"
@@ -578,9 +614,29 @@ export const TYPERT = {
             "name": "SandboxMode",
             "declaration": "export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';"
           },
+          {
+            "name": "ScheduleChange",
+            "declaration": "export type ScheduleChange = ScheduleCreateChange | ScheduleDeleteChange | ScheduleDispatchChange;"
+          },
+          {
+            "name": "ScheduleCreateChange",
+            "declaration": "export interface ScheduleCreateChange {\n    readonly version: 1;\n    readonly operation: 'create';\n    readonly schedule: LegacyScheduleRecord;\n}"
+          },
+          {
+            "name": "ScheduleDeleteChange",
+            "declaration": "export interface ScheduleDeleteChange {\n    readonly version: 1;\n    readonly operation: 'delete';\n    readonly id: ScheduleId;\n}"
+          },
+          {
+            "name": "ScheduleDispatchChange",
+            "declaration": "export type ScheduleDispatchChange = OneShotScheduleDispatchChange | EveryScheduleDispatchChange;"
+          },
+          {
+            "name": "ScheduleId",
+            "declaration": "export type ScheduleId = Branded<'ScheduleId'>;"
+          },
           {
             "name": "Session",
-            "declaration": "export class Session {\n    get surface(): SessionSurface;\n    readonly header: SessionHeader;\n    readonly inheritedEventCount: SessionLogOffset;\n    get id(): SessionId;\n    readonly firstLiveSeq: SessionLogOffset;\n    readonly firstLifecycleSeq: SessionLogOffset;\n    eventAt(seq: SessionSeq): SessionEvent | undefined;\n    snapshotEvents(fromSeq: SessionLogOffset = SessionLogOffset(0), toSeqExclusive: SessionLogOffset = this.seq): readonly SessionEvent[];\n    ownEvents(): readonly SessionEvent[];\n    isOwnSeq(seq: SessionSeq): boolean;\n    get seq(): SessionLogOffset;\n    append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : []): SessionEvent<T>;\n    requestHeader(): EpochHeader | undefined;\n    requestContext(): RequestContext | undefined;\n    deriveMessages(): Message[];\n    deriveEventMessage(event: SessionEvent): Message | null;\n}"
+            "declaration": "export class Session {\n    get surface(): SessionSurface;\n    readonly header: SessionHeader;\n    readonly inheritedEventCount: SessionLogOffset;\n    get id(): SessionId;\n    readonly firstLiveSeq: SessionLogOffset;\n    readonly firstLifecycleSeq: SessionLogOffset;\n    eventAt(seq: SessionSeq): SessionEvent | undefined;\n    snapshotEvents(fromSeq: SessionLogOffset = SessionLogOffset(0), toSeqExclusive: SessionLogOffset = this.seq): readonly SessionEvent[];\n    ownEvents(): readonly SessionEvent[];\n    isOwnSeq(seq: SessionSeq): boolean;\n    get seq(): SessionLogOffset;\n    append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : []): SessionEvent<T>;\n    requestHeader(): EpochHeader | undefined;\n    requestContext(): RequestContext | undefined;\n    toolHistory(): ToolHistory;\n    deriveMessages(): Message[];\n    deriveEventMessage(event: SessionEvent): Message | null;\n}"
           },
           {
             "name": "SessionEvent",
@@ -588,7 +644,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    'feedback/record': FeedbackRecord;\n    'team/member': { version: 2; teamId: TeamId; member: TeamMemberSnapshot; };\n    'team/task': { version: 2; teamId: TeamId; task: TeamTaskSnapshot; };\n    'team/message/queued': { version: 2; teamId: TeamId; message: TeamMessageSnapshot; };\n    'team/message/delivered': { version: 2; teamId: TeamId; messageId: TeamMessageId; targetId: SessionId; };\n    'goal/change': GoalChangeMeta;\n    'feedback/message-put': MessageFeedbackPut;\n    'feedback/message-delete': MessageFeedbackDelete;\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}"
+            "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    'feedback/record': FeedbackRecord;\n    'goal/change': GoalChangeMeta;\n    'feedback/message-put': MessageFeedbackPut;\n    'feedback/message-delete': MessageFeedbackDelete;\n    'schedule/change': ScheduleChange;\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}"
           },
           {
             "name": "SessionEventType",
@@ -754,42 +810,6 @@ export const TYPERT = {
             "name": "SystemPromptUpdate",
             "declaration": "export type SystemPromptUpdate = 'in-history';"
           },
-          {
-            "name": "TeamId",
-            "declaration": "export type TeamId = Branded<'TeamId'>;"
-          },
-          {
-            "name": "TeamMemberPhase",
-            "declaration": "export type TeamMemberPhase = 'provisioning' | 'active' | 'failed';"
-          },
-          {
-            "name": "TeamMemberSnapshot",
-            "declaration": "export interface TeamMemberSnapshot {\n    readonly id: SessionId;\n    readonly name: string;\n    readonly description: string;\n    readonly provider: string;\n    readonly context: 'fresh' | 'fork';\n    readonly phase: TeamMemberPhase;\n    readonly error?: string;\n}"
-          },
-          {
-            "name": "TeamMessageId",
-            "declaration": "export type TeamMessageId = Branded<'TeamMessageId'>;"
-          },
-          {
-            "name": "TeamMessageSnapshot",
-            "declaration": "export interface TeamMessageSnapshot {\n    readonly id: TeamMessageId;\n    readonly senderId: SessionId;\n    readonly senderName: string;\n    readonly targetId: SessionId;\n    readonly content: ContentBlock[];\n}"
-          },
-          {
-            "name": "TeamMessageSource",
-            "declaration": "export interface TeamMessageSource {\n    readonly kind: 'team-message';\n    readonly teamId: TeamId;\n    readonly messageId: TeamMessageId;\n    readonly senderId: SessionId;\n    readonly senderName: string;\n}"
-          },
-          {
-            "name": "TeamTaskId",
-            "declaration": "export type TeamTaskId = Branded<'TeamTaskId'>;"
-          },
-          {
-            "name": "TeamTaskSnapshot",
-            "declaration": "export interface TeamTaskSnapshot {\n    readonly id: TeamTaskId;\n    readonly revision: number;\n    readonly subject: string;\n    readonly description: string;\n    readonly status: TeamTaskStatus;\n    readonly ownerId?: SessionId;\n    readonly blockedBy: TeamTaskId[];\n    readonly writeScopes: string[];\n}"
-          },
-          {
-            "name": "TeamTaskStatus",
-            "declaration": "export type TeamTaskStatus = 'pending' | 'in_progress' | 'completed' | 'deleted';"
-          },
           {
             "name": "TextBlock",
             "declaration": "export interface TextBlock {\n    type: 'text';\n    text: string;\n}"
@@ -814,6 +834,10 @@ export const TYPERT = {
             "name": "ToolCallId",
             "declaration": "export type ToolCallId = Branded<'ToolCallId'>;"
           },
+          {
+            "name": "ToolHistory",
+            "declaration": "export interface ToolHistory {\n    readonly tools: readonly ToolSchema[];\n    readonly updates: readonly { readonly messageId: MessageId; readonly additions: readonly ToolSchema[]; }[];\n}"
+          },
           {
             "name": "ToolMessageSource",
             "declaration": "export interface ToolMessageSource {\n    kind: 'tool';\n    callId: ToolCallId;\n}"

package/lib/types/child-agent.d.ts

@@ -106,7 +106,10 @@ export declare const SUBAGENT_DELEGATION_CONTEXT: string;
 export declare function applyChildComposition(childCtx: Context, parent: Agent, composition: ChildComposition): void;
 /** Policy seeded onto a child session's log at the delegation boundary. */
 export interface DelegatedPolicyOverrides {
-    /** The shared-bundle preset identity when the parent currently runs in Auto or Full access. */
+    /**
+     * The parent's current preset identity when it runs in Auto or Full access;
+     * the child keeps it under the pinned `never` approval policy.
+     */
     readonly permissionPreset: 'auto' | 'danger-full-access' | undefined;
     /** The parent session's explicit sandbox-mode override, or `undefined` without one. */
     readonly sandboxMode: SandboxMode | undefined;

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

@@ -1,5 +1,5 @@
 /**
- * Client-safe complete-descendant rows and browser continuation requests,
+ * Client-safe recursive catalog rows and browser continuation requests,
  * receipts, and failures.
  *
  * @module @deepseek-ai/dsh-subagent/control-types
@@ -16,47 +16,43 @@ import type { SessionId } from '@deepseek-ai/dsh-session/types';
  * rather than imported.
  */
 export type SubagentPromptRequestId = Branded<'session-request-id'>;
-/** Shared child fields for complete-descendant listing. */
+/** Shared child fields for recursive catalog listing. */
 export type SubagentCatalogRow = {
     /** The durable child session id, stable across Activations. */
     readonly id: SessionId;
     /**
-     * Whether complete-descendant listing observed a resident Session. This
+     * Whether recursive catalog listing observed a resident Session. This
      * 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 owning catalog or child descriptor. */
+    /** Optional durable creation label from the parent catalog. */
     readonly label?: string;
 } | {
     /** A resumable conversation. */
     readonly mode: 'continuable';
-    /** Durable creation label from the owning catalog or child descriptor. */
+    /** Durable creation label from the parent catalog. */
     readonly label: string;
 });
 /**
- * One complete-descendant row. Enumeration may also return diagnostics for
- * child identity observations from the complete Session corpus.
+ * One recursive catalog row. Traversal may also return diagnostics for
+ * unknown catalog modes or unreadable child catalogs.
  */
 export type SubagentListEntry = SubagentCatalogRow & {
     readonly kind: 'child';
-    /** Whether complete-corpus enumeration observed a direct child. */
+    /** Whether the child catalog contains a direct child. */
     readonly hasChildren: boolean;
 } | {
     readonly kind: 'diagnostic';
     /** The candidate's session id. */
     readonly id: SessionId;
     /**
-     * Why the candidate has no `child` row: `corrupt` for a settled candidate
-     * whose projection fold served no identity (a missing, malformed, or
-     * unrecognized-version descriptor — deliberately undistinguished), and
-     * for any candidate whose log makes a registered unit's fold or schema
-     * throw (deterministic data damage, contained per child); `unavailable`
-     * when the candidate's Session observation was absent or transiently
-     * unreadable (retried on the next listing). `unsupported` is never produced; it remains in the
-     * union for consumers that route on it.
+     * `corrupt` means the child catalog read found invalid or conflicting
+     * Session data; `unavailable` means it could not be read. Either failure
+     * stops that branch. `unsupported` means the parent catalog records an
+     * unknown child mode; its readable catalog is still traversed.
      */
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable';
 };

package/lib/types/control-types.js

@@ -1,5 +1,5 @@
 /**
- * Client-safe complete-descendant rows and browser continuation requests,
+ * Client-safe recursive catalog rows and browser continuation requests,
  * receipts, and failures.
  *
  * @module @deepseek-ai/dsh-subagent/control-types

package/lib/types/index.d.ts

@@ -18,8 +18,8 @@
  * continuation manager holds their `AgentHandle` directly and orders every turn
  * through the child's own inbox, so providers contribute only the detached
  * creation spec and see no handle, turn, or teardown. Direct-child
- * discovery uses the parent catalog; descendant discovery uses the Session
- * corpus. Neither read requires the continuation runtime.
+ * discovery reads the parent catalog; descendant discovery recursively reads
+ * those child catalogs. Neither read requires the continuation runtime.
  *
  * Same-process providers are trusted typed collaborators. Requests, provider
  * descriptors, results, and lifecycle payloads are borrowed immutable values;
@@ -217,19 +217,19 @@ export declare class SubagentRuntime extends TypertRemoteService {
      */
     listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>;
     /**
-     * Enumerate the root's complete session-backed subagent tree in stable
-     * pre-order from one live-preferred corpus, without loading or resuming an
-     * Agent. Ordinary sessions and one-shot children remain traversal nodes so
-     * continuable descendants below them are discovered; each returned entry
-     * adds its durable `parentId` and root-relative `depth`. Identity resolution,
-     * diagnostics, optional persistence, and cancellation use the registered
-     * child identity projection and complete Session corpus.
-     * @param rootSessionId - session whose complete descendant tree is listed.
-     * @param signal - caller-owned cancellation forwarded to persistence reads
-     *   and observed around every read await.
-     * @returns children and per-candidate diagnostics with tree position, in
-     *   stable pre-order.
+     * Recursively list reachable parent catalogs in stable pre-order, preserving
+     * each catalog's event order. Each row carries its catalog parent and depth;
+     * one-shot and unknown-mode children remain traversal nodes. Unknown modes
+     * produce unsupported diagnostics. Unreadable child catalogs produce corrupt
+     * or unavailable diagnostics and stop only that branch. Root read failures,
+     * missing services or projections, and cancellation reject the whole listing.
+     * Each catalog is observed once and released before the next read. No Agent
+     * is loaded or resumed; Sessions absent from reachable catalogs are omitted.
+     * @param rootSessionId - session whose catalog starts descendant discovery.
+     * @param signal - cancellation forwarded to and checked around each catalog read.
+     * @returns children and branch diagnostics in parent-catalog pre-order.
      * @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.
+     * @throws SessionQueryError when the root catalog cannot be read.
      */
     listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;
     /**

package/lib/types/index.js

@@ -234,19 +234,19 @@ let SubagentRuntime = (() => {
             return listSubagentChildren(this.ctx, parentSessionId, signal);
         }
         /**
-         * Enumerate the root's complete session-backed subagent tree in stable
-         * pre-order from one live-preferred corpus, without loading or resuming an
-         * Agent. Ordinary sessions and one-shot children remain traversal nodes so
-         * continuable descendants below them are discovered; each returned entry
-         * adds its durable `parentId` and root-relative `depth`. Identity resolution,
-         * diagnostics, optional persistence, and cancellation use the registered
-         * child identity projection and complete Session corpus.
-         * @param rootSessionId - session whose complete descendant tree is listed.
-         * @param signal - caller-owned cancellation forwarded to persistence reads
-         *   and observed around every read await.
-         * @returns children and per-candidate diagnostics with tree position, in
-         *   stable pre-order.
+         * Recursively list reachable parent catalogs in stable pre-order, preserving
+         * each catalog's event order. Each row carries its catalog parent and depth;
+         * one-shot and unknown-mode children remain traversal nodes. Unknown modes
+         * produce unsupported diagnostics. Unreadable child catalogs produce corrupt
+         * or unavailable diagnostics and stop only that branch. Root read failures,
+         * missing services or projections, and cancellation reject the whole listing.
+         * Each catalog is observed once and released before the next read. No Agent
+         * is loaded or resumed; Sessions absent from reachable catalogs are omitted.
+         * @param rootSessionId - session whose catalog starts descendant discovery.
+         * @param signal - cancellation forwarded to and checked around each catalog read.
+         * @returns children and branch diagnostics in parent-catalog pre-order.
          * @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.
+         * @throws SessionQueryError when the root catalog cannot be read.
          */
         listDescendants(rootSessionId, signal) {
             return listSubagentDescendants(this.ctx, rootSessionId, signal);

package/lib/types/list-children.d.ts

@@ -1,10 +1,6 @@
 /**
- * Direct-child discovery from a parent-owned `subagent/catalog` projection,
- * plus complete descendant-tree enumeration from the Session corpus. A direct
- * listing owns one parent observation and reads no child log. Descendant
- * enumeration retains the complete corpus and the child identity projection
- * because ordinary Sessions and one-shot children remain traversal nodes.
- *
+ * Direct-child and recursive descendant discovery from parent-owned catalogs.
+ * Each catalog read releases its Session observation before the next branch.
  * @module @deepseek-ai/dsh-subagent
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -12,13 +8,9 @@ import type { SessionId } from '@deepseek-ai/dsh-session';
 import type { SubagentListEntry } from './control-types.ts';
 import type { SubagentCatalogEntry } from './projection-types.ts';
 export type { SubagentListEntry } from './control-types.ts';
-/**
- * One entry of a descendant listing: the interpreted subagent facts plus its
- * position in the complete session tree. `parentId` is the durable direct
- * parent from the enumerated header, and `depth` counts edges from the root.
- */
+/** One catalog descendant with its direct parent and edge distance from the requested root. */
 export type SubagentDescendantListEntry = SubagentListEntry & {
-    /** Durable direct parent of this candidate in the enumerated tree. */
+    /** Parent whose catalog contains this child. */
     readonly parentId: SessionId;
     /** Edge distance from the requested root; direct children are `1`. */
     readonly depth: number;
@@ -33,16 +25,12 @@ export type SubagentDescendantListEntry = SubagentListEntry & {
  */
 export declare function listChildren(ctx: Context, parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>;
 /**
- * Enumerate every session-backed subagent below one root in stable pre-order.
- * Ordinary sessions and one-shot children remain traversal nodes, so a
- * continuable child below either is still discovered. Classification uses the
- * registered child identity projection; no Agent is loaded or resumed.
- * @see SubagentRuntime.listDescendants for the public cancellation and failure contract.
- * @param ctx - context carrying the session store, projection registry, and optional persistence/cache.
- * @param rootSessionId - session whose complete descendant tree is listed.
- * @param signal - caller-owned cancellation observed around every persistence read.
- * @returns interpreted subagents with durable direct-parent and root-relative depth.
- * @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.
+ * Walk reachable parent catalogs in stable pre-order without loading Agents.
+ * @see SubagentRuntime.listDescendants for failure and cancellation semantics.
+ * @param ctx - context carrying the Session store and query service.
+ * @param rootSessionId - parent whose catalog starts the traversal.
+ * @param signal - cancellation checked around each catalog read.
+ * @returns children and branch diagnostics with catalog parent and depth.
  */
 export declare function listDescendants(ctx: Context, rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;
 //# sourceMappingURL=list-children.d.ts.map