dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/kb/extra/subsystems/subagent.zh.md

@@ -1,688 +0,0 @@
-# 子代理
-
-[English](subagent.md) | 中文
-
-统一的 activation API 管理本地会话和外部执行。
-
-## 能力与 activation 请求
-
-所有后端都使用 startActivation。能力标记校验请求选项；prepareContinuable 选择本地 Agent 创建，start 选择一次外部执行。面向模型的工具采用 parent 回传。Workflow 与 code mode 消费者可以等待 caller 结果，不额外向父代理注入消息。历史子会话的 descriptor 不可用时，以 `mode: 'unknown'` 保持可发现性，但不授予继续执行能力；[包 README](../../packages/subagent/subagent/README.zh.md) 定义目录持久化语义。
-
-可选的 `request.cwd` 指定子级的初始目录；相对路径以父级当前有效目录为基准解析。省略时，在准入阶段捕获该目录。本地子 Session 保留父级的原始项目，冷恢复保留其日志中的目录状态。
-
-```ts type-equiv
-/**
- * Start-time options supported by a registered backend. The manager checks
- * every requested option before preparing a local child or starting an external
- * execution. depthLimit controls maxDepth; the remaining flag names match
- * SubagentStartRequest fields.
- */
-interface SubagentCapabilities {
-  readonly agentOptions: boolean
-  /** Supports selecting a preset independently of the parent's composition. */
-  readonly agentPreset: boolean
-  readonly outputSchema: boolean
-  readonly depthLimit: boolean
-}
-```
-
-```ts type-equiv
-/** One managed child execution and its result delivery policy. */
-interface SubagentActivationSpec {
-  /** Registered backend to use. */
-  readonly provider: string
-  /** Short task label retained in cataloged child membership. */
-  readonly label: string
-  /** Optional reserved identity for a local child; external backends allocate their own ids. */
-  readonly childId?: SessionId
-  /** Task, parent, and backend-supported execution options. */
-  readonly request: Omit<SubagentStartRequest, 'label' | 'signal'>
-  /** Cancellation before publication; callers own later cancellation through dispose. */
-  readonly signal: AbortSignal
-  /** Parent delivery notifies the model; caller delivery only returns the result. Local children always enter the parent catalog. */
-  readonly delivery: 'parent' | 'caller'
-}
-```
-
-```ts type-equiv
-/** A managed execution; disposal addresses this exact activation, never a later resume. */
-interface SubagentActivation {
-  /** Stable identity of the child. */
-  readonly childId: SessionId
-  /** Accepted inbox message, when the backend has a local inbox. */
-  readonly messageId?: MessageId
-  /**
-   * Execution result after teardown settles and notifications are sent; capture failures reject.
-   * Teardown failures are reported by dispose() without replacing a captured result.
-   */
-  readonly result: Promise<SubagentResult>
-  /** Stop and release this activation and its owned descendants; rejects on teardown failure. */
-  dispose(): Promise<void>
-}
-```
-
-```ts type-equiv
-/**
- * Task and optional capabilities supplied to a backend. startActivation carries
- * these fields in request while owning its label, cancellation, and delivery
- * policy separately.
- */
-interface SubagentStartRequest {
-  /** Initial child directory; relative paths resolve against the parent's current directory. Omitted inherits that directory at start. */
-  readonly cwd?: string
-  /**
-   * Independent preset id; omission joins the parent's current generation.
-   * Requires a provider with `capabilities.agentPreset` that does not inherit
-   * parent context.
-   */
-  readonly agentPreset?: string
-  /** Optional short display label persisted with a session-backed child. */
-  readonly label?: string
-  /** Content delivered as the child's user message. */
-  readonly prompt: ContentBlock[]
-  /**
-   * The spawning agent. Its effective directory supplies the default cwd;
-   * in-process children retain its origin, lineage, and delegation depth.
-   */
-  readonly parent: Agent
-  /**
-   * Cancellation signal from the spawning context (the tool's `exec.signal`).
-   * This is the canonical cancellation channel both before and after startup:
-   * a provider rejects `start()` after cleaning partial resources when it
-   * fires before the run is published, and cancels the published run's
-   * remaining turn work when it fires afterward.
-   */
-  readonly signal: AbortSignal
-  /**
-   * Optional host-Agent provider, model, reasoning-effort, and output-token
-   * overrides. Requires {@link SubagentCapabilities.agentOptions}; in-process
-   * providers merge them over the parent Agent's options when they create the
-   * child, while the DSH SDK provider merges them over its instance defaults
-   * before initializing the separate child runtime.
-   */
-  readonly agentOptions?: AgentOptions
-  /**
-   * Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
-   * unsupported schemas or providers without the capability. Data must be plain host-realm JSON;
-   * a successful child returns the matching value as {@link SubagentResult.structured}.
-   */
-  readonly outputSchema?: ObjectJsonSchema
-  /**
-   * Optional absolute delegation-depth cap for the child being started: its
-   * computed depth must be less than or equal to this non-negative safe
-   * integer. Requires {@link SubagentCapabilities.depthLimit}; rejected at
-   * start otherwise.
-   */
-  readonly maxDepth?: number
-}
-```
-
-```ts type-equiv
-/** Provider-facing request with an absolute directory selected before startup. */
-interface ResolvedSubagentStartRequest extends SubagentStartRequest {
-  /** Absolute child directory captured from the parent or explicit request. */
-  readonly cwd: string
-}
-```
-
-## 本地子代理与 activation
-
-只有 spawn 支持独立的 `agentPreset`；省略选择与 fork 都继承父方的活跃组装。[子级 preset 规则](../../packages/subagent/subagent/README.zh.md#restoring-child-composition)定义显式选择、事件顺序和历史恢复行为。
-
-本地子代理拥有持久 Session，最多有一个在线 activation。Manager 预留身份和容量，通过后端准备子代理，并管理输入准入、冷恢复以及先子后父的释放顺序。activation 结果在资源释放和完成通知之后结算。释放操作单独报告清理失败，不会覆盖已捕获的结果。结构化结果提交会关闭该 activation 的输入；之后的冷恢复不会继承输出 schema。
-
-```ts type-equiv
-/**
- * What the continuation manager asks a provider for while materializing one
- * continuable child's FIRST activation. The manager has already reserved the
- * durable child identity and owns every later operation, so this request
- * carries only what distinguishes a fresh child from one seeded with parent
- * history.
- */
-interface ContinuableCreateRequest {
-  /** Absolute initial directory captured before provider preparation. */
-  readonly cwd: string
-  /** The reserved durable child session id, for provider diagnostics. */
-  readonly sessionId: SessionId
-  /** The delegating parent agent whose history a seeding provider reads. */
-  readonly parent: Agent
-  /**
-   * Caller cancellation, which owns preparation only until the manager accepts
-   * the initial prompt into the child's inbox.
-   */
-  readonly signal: AbortSignal
-}
-```
-
-```ts type-equiv
-/**
- * A provider's detached contribution to one continuable child's creation. This
- * is DATA, never a capability: it carries no Agent, `AgentHandle`, prompt
- * delivery, result, disposal, or resume operation, because the continuation
- * manager owns the child's whole lifecycle after preparation.
- */
-interface ContinuableCreateSpec {
-  /**
-   * Completed-turn prefix of the parent's log to seed the child session with,
-   * or absent for a fresh child. Same durable contract as
-   * `CreateAgentOptions.seed`: contiguous from seq 0, lossless JSON, balanced.
-   */
-  readonly seed?: readonly SessionEvent[]
-}
-```
-
-## 消息与中断
-
-sendMessage 根据确切的在线发送者实例授权，仅允许相邻本地代理通信。运行中的子代理接收引导输入；不在线的可继续子代理从持久化恢复。外部执行拒绝后续消息。本地与外部执行都会通过父级结束通知自动回传最终文本、结构化结果、诊断和状态。本地子代理也可以通过 send_message 发送消息。caller 回传会抑制结束通知。drainDescendants 与 drainChildren 对本地和外部 activation 都等待所属任务清理完成。
-
-```ts type-equiv
-/** Durable attribution for one model-authored message between Agents. */
-interface AgentMessageSource {
-  readonly kind: 'agent-message'
-  /** A message another agent addressed to this one (`relay` context form). */
-  readonly form: 'relay'
-  /** Session id of the Agent whose tool call produced the message. */
-  readonly senderSessionId: SessionId
-}
-```
-
-```ts type-equiv
-/**
- * Durable attribution for the runtime's own account of a continuable child
- * settling. Deliberately a different kind from
- * {@link AgentMessageSource}: an Agent message is content the sender chose,
- * while this message is the manager stating what became of the child, and a
- * transcript that merged them would credit the child with words it never wrote.
- */
-interface SubagentSettledMessageSource {
-  readonly kind: 'subagent-settled'
-  /** A runtime account shown without expanding the row (`notice` context form). */
-  readonly form: 'notice'
-  /** One-line account of how the child ended. */
-  readonly summary: string
-  /** Session id of the child that settled. */
-  readonly senderSessionId: SessionId
-}
-```
-
-```ts type-equiv
-/** Options for one model-authored message between adjacent Agents. */
-interface SubagentSendMessageOptions {
-  /** Caller cancellation, owning the operation only until inbox acceptance. */
-  readonly signal: AbortSignal
-}
-```
-
-```ts type-equiv
-/**
- * Authority under which one interrupt request is admitted. `user` carries the
- * durable direct-parent address a human client presented; `ancestor` carries
- * the exact live Agent object whose recorded lineage must contain the caller.
- */
-type SubagentInterruptAuthority =
-  | { readonly kind: 'user'; readonly parentSessionId: SessionId }
-  | { readonly kind: 'ancestor'; readonly agent: Agent }
-```
-
-## 持久枚举
-
-`listChildren` 读取父级拥有的目录，其中包含所有本地子级及 parent 投递的外部子级。caller 投递的外部执行由调用方负责成员关系与结果收集；本地工作流子级在完成后仍可被发现。外部条目携带 `mode: 'external'`，不能打开子 Session 或接受后续消息。目录在创建时记录成员关系，不携带执行状态。`list_agents` 展示可继续的直接子级，其活跃状态为 `running` 或 `inactive`；参见[控制工具](../../packages/subagent/tool-subagent-control/README.zh.md#list_agents)。
-
-## 结果与后端句柄
-
-SubagentResult 供程序消费方读取。activation 注册表保留外部后端句柄，直到释放完成。清理失败不会覆盖已捕获的执行结果：activation 结果与父级通知保留该结果，dispose 拒绝，而在线 subagent/end 事件报告 error。后端提供的诊断必须满足下述安全信息要求。
-
-```ts type-equiv
-/**
- * The terminal outcome of a subagent run, resolved by {@link SubagentRun.result}.
- */
-interface SubagentResult {
-  /**
-   * The child's final assistant output is the content of its last non-empty
-   * assistant message. Empty-content messages, including usage-only messages,
-   * are skipped. Without a non-empty message, the output is its accumulated
-   * assistant text stream, or `[]` when the child produced neither.
-   */
-  readonly output: readonly ContentBlock[]
-  /**
-   * The structured result after a requested `outputSchema` was successfully
-   * satisfied. Requesting a schema does not guarantee presence: a provider can
-   * end with `stopReason: 'error'` when the child fails or finishes without a
-   * valid capture. The structured value is validated against the requested
-   * output schema by the provider; `unknown` here because the seam is
-   * schema-agnostic.
-   */
-  readonly structured?: unknown
-  /**
-   * Provider-authored, non-assistant failure detail for a non-`completed`
-   * result. Providers keep this text free of tool inputs, file contents,
-   * environment values, credentials, and raw protocol payloads, and limit it
-   * to 4096 UTF-8 bytes. Consumers present it separately from {@link output}.
-   */
-  readonly diagnostic?: string
-  /** Why the run ended. A non-`completed` reason means `output` may be partial. */
-  readonly stopReason: SubagentStopReason
-}
-```
-
-```ts type-equiv
-/**
- * Why a subagent run ended. Merge-extensible (a backend may add variants);
- * consumers branch on the known cases and fall through `default`. The known
- * cases mirror the harness turn-end vocabulary so the tool layer can map a
- * non-`completed` result to an `isError` tool result.
- */
-interface SubagentStopReasonMap {
-  /** The child finished its turn normally. */
-  completed: 'completed'
-  /** Cancelled through the request signal or disposal. */
-  aborted: 'aborted'
-  /** Model or transport failure. */
-  error: 'error'
-  /** The child hit its token ceiling before finishing. */
-  'max-tokens': 'max-tokens'
-  /** The child declined the task. */
-  refusal: 'refusal'
-}
-```
-
-```ts type-equiv
-/**
- * Backend execution handle owned directly by the activation registry.
- * A result may become available before resource release; the manager always
- * disposes the handle and awaits cleanup. Backend startup failures clean up
- * partial resources before rejecting, while accepted execution failures settle
- * through result.
- */
-interface SubagentRun {
-  /** Provider-minted id, unique across all parents, providers, and local Sessions in this runtime. */
-  readonly id: SessionId
-  /**
-   * Resolves with the child's terminal {@link SubagentResult} when the run
-   * settles. Does NOT reject on a child-level failure — a model/transport
-   * failure resolves with `stopReason: 'error'` so the consumer maps it to an
-   * `isError` tool result. Rejects on an infrastructure fault the seam cannot
-   * represent as a stop reason.
-   */
-  readonly result: Promise<SubagentResult>
-  /**
-   * Cancel remaining work, reach child quiescence, and release resources.
-   * Idempotent.
-   */
-  dispose(): Promise<void>
-}
-```
-
-## 提供方约定：SubagentProvider
-
-`SubagentManager` 统一管理启动、消息准入与执行生命周期。Spawn 与 Fork 提供用于本地 Agent 的独立创建输入。Codex、Claude Code、ACP 和 DSH SDK 提供一个执行句柄，不增加多轮能力。每条 activation 都是直接持有 AgentHandle 或 SubagentRun 的执行期记录。外部完成由句柄的 result promise 确定；inbox 与空闲准入仅属于本地执行。两条路径共用准入、容量、父子所有权、取消和释放机制。[包参考](../../packages/subagent/subagent/README.zh.md)说明组合与部署要求。
-
-```ts type-equiv
-/**
- * One registered transport for running child agents. Providers are trusted
- * same-process implementations; callers treat descriptors and returned values
- * as borrowed immutable data. The service may call one provider concurrently
- * for distinct children. Providers isolate operation-local mutable state; a
- * shared capacity controller may delay an operation but must not couple its
- * settlement or cleanup to a sibling.
- */
-interface SubagentProvider {
-  /** Unique registry name (e.g. `spawn`, `fork`, `acp`). */
-  readonly name: string
-  /** The start-time features this provider supports (see {@link SubagentCapabilities}). */
-  readonly capabilities: SubagentCapabilities
-  /**
-   * Whether the child sees the parent's completed-turn prefix. This is descriptive, not a
-   * service-validated start capability: the model-facing tool derives truthful wording from it.
-   * It says nothing about tool registration, injected services, or authority inheritance.
-   */
-  readonly inheritsParentContext: boolean
-  /**
-   * Optional static provider-owned provider/model route for child Agent
-   * options. Consumers merge tool/model overrides over these values before
-   * preflight; providers whose route derives from the parent omit it. The value
-   * is detached immutable data and requires `agentOptions` support.
-   */
-  readonly agentRouteDefaults?: Readonly<{ provider: string; model: string }>
-  /**
-   * Establish one external execution and return its owned handle.
-   * The service has already validated that every requested start-time
-   * capability is supported. Before fulfillment, the provider owns setup and
-   * cleans any unpublished partial resources before rejecting. Ownership transfers on
-   * fulfillment; subsequent turn or infrastructure failure settles through
-   * the returned run. Distinct starts may overlap; cancellation, failure,
-   * result settlement, and disposal remain independent for each run.
-   */
-  start?(request: ResolvedSubagentStartRequest): Promise<SubagentRun>
-  /**
-   * OPTIONAL (continuable-creation capability): contribute the detached
-   * creation inputs that distinguish this provider's continuable children —
-   * only whether the child session is seeded with parent history. Method
-   * presence selects local activation execution. Providers without it execute
-   * through start and do not accept subsequent messages.
-   *
-   * This is the provider's ONLY participation in a continuable child. The
-   * continuation manager owns identity reservation, composition, Agent
-   * creation, prompt delivery, cold resume, ownership, and disposal, so a
-   * provider never sees the child's Agent, handle, turns, or teardown.
-   * Distinct preparations may overlap; each follows its own signal and returns
-   * data belonging only to `request.sessionId`.
-   */
-  prepareContinuable?(request: ContinuableCreateRequest): Promise<ContinuableCreateSpec>
-}
-```
-
-## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
-
-模型侧的 `list_agents` 适配器将当前活动表示为 `running` 或 `inactive`。这些值不描述任务完成情况，也不保证 `send_message` 会成功。
-
-`SubagentRuntime.listChildren(parentSessionId, signal?)` 通过优先使用在线 Session 的观察读取父会话的 `subagentCatalog` 视图，并在成功或失败时释放观察。它按父会话事件顺序返回直接子级条目，不读取子级日志，也不枚举 Session 语料库。查询失败直接传播；缺少目录投影时显式失败。浏览器条目从共享 projection store 派生成员关系，并从 Session 状态补充活动状态；control stream 推送完整目录更新。`listDescendants()` 递归读取这些目录，并从每个子级目录推导 `hasChildren`。[父目录 Agent Note](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明创建、fork 隔离、排序和持久化成本。
-
-`SubagentRuntime.listDescendants(rootSessionId)` 以稳定前序递归调用同一目录读取函数，保留每个父级的事件顺序。外部条目是没有本地 Session 的叶节点。一次性和未知模式条目仍是遍历节点；未知模式产生 `unsupported` 诊断。无法读取的子级目录产生 `corrupt` 或 `unavailable`，只停止该分支。根读取失败、服务或投影缺失、取消会使整个查询失败。每个可达目录只观察一次，并在下一次读取前释放；重复 id 和循环引用会被跳过。可达目录中不存在的 Session 不会被发现，包括普通 Session fork 及其下的子 agent。每行携带目录中的父级和相对根的深度：
-
-```ts type-equiv
-/** One catalog descendant with its direct parent and edge distance from the requested root. */
-type SubagentDescendantListEntry = SubagentListEntry & {
-  /** Parent whose catalog contains this child. */
-  readonly parentId: SessionId
-  /** Edge distance from the requested root; direct children are `1`. */
-  readonly depth: number
-}
-```
-
-
-<a id="the-terminal-result-subagentresult"></a>
-
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxsubagentmodelselection--subagentmodelselectionconfig"></a>
-
-### `ctx.subagentModelSelection` — `SubagentModelSelectionConfig`
-
-Singleton settings owner read when delegation tools are composed for a Session.
-
-```ts cordis-catalog
-/**
- * Read a detached selection preference for the next eligible Session composition.
- * @returns the enabled state and exact allowed routes.
- */
-current(): SubagentModelSelectionSettings
-```
-
-Source: [`packages/subagent/tool-subagent/src/model-selection-settings.ts`](../../packages/subagent/tool-subagent/src/model-selection-settings.ts)
-
-<a id="ctxsubagents--subagentruntime"></a>
-
-### `ctx.subagents` — `SubagentRuntime`
-
-Named provider registry with managed activations, durable discovery, and local child messaging.
-
-```ts cordis-catalog
-/**
- * Resolve a delegation tool's depth policy against the current user setting.
- * @param configured - Explicit tool limit, or provider-managed for external delegation.
- * @returns The numeric limit, or undefined when the provider owns depth enforcement.
- */
-resolveMaxDepth(configured?: number | 'provider-managed'): number | undefined
-
-/**
- * Start a local child under its reserved identity.
- * @param spec - local task, reserved child id, and result recipient.
- * @returns activation with its accepted initial message id.
- */
-startActivation(spec: SubagentActivationSpec & { readonly childId: SessionId }): Promise<SubagentActivation & { readonly messageId: MessageId }>
-
-/**
- * Start a local or external child.
- * @param spec - task, backend, and result recipient.
- * @returns activation with a message id only for local children.
- */
-startActivation(spec: SubagentActivationSpec): Promise<SubagentActivation>
-
-/**
- * Join progressing descendants without cancelling them. Idle descendants whose
- * inboxes require a later wake stay resident and do not delay host completion.
- * @param parent - the exact parent whose descendant work is observed.
- * @returns whether work was joined; hosts recheck parent idle after true.
- */
-async waitForChildren(parent: Agent): Promise<boolean>
-
-/**
- * Steer one model-authored message to the sender's direct parent or direct
- * continuable child. A running target admits it at the nearest step boundary;
- * an idle target starts a turn, and an absent direct child cold-resumes from
- * persistence. The service derives durable sender attribution from the exact
- * live sender. Caller cancellation stops only pre-acceptance work.
- * @param sender - exact live Agent authorizing and originating the message.
- * @param targetId - durable direct-parent or direct-child session id.
- * @param content - model-authored content to deliver.
- * @param options - caller cancellation before inbox acceptance.
- * @returns the accepted message's inbox id.
- * @throws when continuation services are unavailable, adjacency is rejected,
- *   or the message was not admitted.
- */
-async sendMessage( sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions, ): Promise<MessageId>
-
-/**
- * Interrupt one live child's current execution under a human parent
- * address or an exact live ancestor Agent. Fire-and-return: the cancel
- * signal is issued before this returns, but the target may keep running
- * until it observes the signal. Unclaimed pending inbox work, the Activation,
- * and published descendants are preserved; claimed work is not requeued.
- * Once the interrupted Agent is idle, a waking send resumes the parked FIFO
- * queue. External backends stop their single execution. An absent target
- * is an accepted no-op, as is a manager-less composition, which cannot own a
- * live Activation.
- * @param targetSessionId - the durable child session id to interrupt.
- * @param authority - the human parent address or exact live ancestor Agent.
- * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
- *   live target.
- */
-interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
-
-/**
- * Close subagent admission below exact live parent Agents, stop only their
- * visible descendant Activations synchronously, then await admitted scoped
- * materializations and release those forests child-first. The scoped cutoff
- * lasts until each exact parent leaves the registry; unrelated parent trees
- * remain live.
- * @param parents - exact host-owned parent Agents entering teardown.
- * @returns once every retained descendant activation released its execution handle.
- * @throws an aggregate error after all branches settle when any failed.
- */
-async drainDescendants(parents: readonly Agent[]): Promise<void>
-
-/**
- * Release selected resident direct children of one exact live
- * parent. Other children of the same parent remain admitted and resident.
- * Absent targets and a manager-less composition are accepted no-ops.
- * @param parent - exact live direct parent authorizing the selected release.
- * @param childIds - durable direct-child ids to release when resident.
- * @returns once every selected activation released its execution handle.
- * @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a
- *   different parent or the supplied parent identity is stale.
- */
-async drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>
-
-/**
- * Read the parent's durable direct-child catalog without loading or resuming an Agent.
- * The service owns and releases the live-preferred Session observation.
- * @param parentSessionId - parent whose direct children are requested.
- * @param signal - cancellation forwarded to the Session query.
- * @returns catalog children in parent event order.
- * @throws {@link SubagentError} when query or catalog projection is unavailable.
- * @throws SessionQueryError when the parent cannot be read or the query is cancelled.
- */
-listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>
-
-/**
- * Recursively list reachable parent catalogs in stable pre-order, preserving
- * each catalog's event order. Each row carries its catalog parent and depth;
- * external children are leaves; 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[]>
-
-/**
- * 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`.
- * @param request - durable address, delivery, minted identity, content, and optional browser zone.
- * @param signal - carrier cancellation, owning the call until inbox acceptance.
- * @returns the accepted message's inbox identity.
- * @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`,
- *   `subagent/invalid-time-zone`, `subagent/parent-unavailable`,
- *   `subagent/not-resumable`, `subagent/unauthorized`,
- *   `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.
- */
-@Remote('prompt') async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>
-
-/**
- * Remote face of {@link interrupt} under one durable parent address. No
- * catalog, history, persistence, or parent Agent lookup runs: the core
- * primitive alone authorizes the address against the live Activation, which
- * is what keeps a live child interruptible while its parent Agent is offline.
- * Absent, idle, and already-completed targets are accepted no-ops there.
- * @param childSessionId - durable child session id to interrupt.
- * @param parentSessionId - durable direct parent whose authority is claimed.
- * @param mode - required continuable-address discriminator.
- * @returns acknowledgement that the cancel signal was admitted, not that the target is quiescent.
- * @throws {RemoteError} `gateway/bad-request` for an empty id,
- *   `subagent/unauthorized` when the address does not own the live target,
- *   otherwise `gateway/internal`.
- */
-@Remote('interruptByParent') interruptByParent( childSessionId: SessionId, parentSessionId: SessionId, mode: 'continuable', ): SubagentInterruptReceipt
-
-/**
- * Register a provider under its name. Registration is effect-scoped and HMR
- * safe; removing a provider blocks new starts but does not revoke runs that
- * were already returned to their holders. Providers without either execution
- * method are rejected with UNSUPPORTED_CAPABILITY before registration.
- * @param provider - the trusted provider implementation.
- * @returns the exact Cordis effect disposer.
- */
-registerProvider(provider: SubagentProvider): () => void
-
-/**
- * Look up a provider by name.
- * @param name - the provider name.
- * @returns the provider, or undefined when absent.
- */
-getProvider(name: string): SubagentProvider | undefined
-
-/**
- * List registered provider names in insertion order.
- * @returns the registered names.
- */
-list(): string[]
-```
-
-Types: [Agent](core.zh.md) · [ContentBlock](llm-streaming.zh.md) · [MessageId](llm-streaming.zh.md) · [SessionId](core.zh.md)
-
-Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
-
-<a id="subagent-events"></a>
-
-### `subagent/*` events
-
-<a id="subagentend--emit"></a>
-
-#### `subagent/end` — emit
-
-A published child settled. Scope-filtered dispatch uses the same delegating parent carrier as `subagent/start`, so the lifecycle pair reaches the same scoped audience.
-
-```ts cordis-catalog
-/**
- * A published child settled. Scope-filtered dispatch uses the same delegating
- * parent carrier as `subagent/start`, so the lifecycle pair reaches the
- * same scoped audience.
- * @param info - the run identity and terminal outcome.
- * @mode emit
- */
-'subagent/end'(this: Scoped<SubagentRuntime>, info: SubagentRunEndInfo): void
-```
-
-Types: [Scoped](scope.zh.md)
-
-Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
-
-<a id="subagentprovider-added--emit"></a>
-
-#### `subagent/provider-added` — emit
-
-A provider became resolvable in the registry.
-
-```ts cordis-catalog
-/**
- * A provider became resolvable in the registry.
- * @param provider - the registered provider.
- * @mode emit
- */
-'subagent/provider-added'(provider: SubagentProvider): void
-```
-
-Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
-
-<a id="subagentprovider-removed--emit"></a>
-
-#### `subagent/provider-removed` — emit
-
-A provider left the registry. Accepted runs remain holder-owned.
-
-```ts cordis-catalog
-/**
- * A provider left the registry. Accepted runs remain holder-owned.
- * @param name - the provider name that no longer resolves.
- * @mode emit
- */
-'subagent/provider-removed'(name: string): void
-```
-
-Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
-
-<a id="subagentstart--emit"></a>
-
-#### `subagent/start` — emit
-
-A provider established a published child. For in-process providers, `ctx.agents.get(info.id)` resolves during this notification. Scope-filtered dispatch keys the carrier by the delegating parent, so a parent-scoped listener observes only its own delegations. Paired with `subagent/end`.
-
-```ts cordis-catalog
-/**
- * A provider established a published child. For in-process providers,
- * `ctx.agents.get(info.id)` resolves during this notification.
- * Scope-filtered dispatch keys the carrier by the delegating parent, so a
- * parent-scoped listener observes only its own delegations. Paired with
- * `subagent/end`.
- * @param info - the provider and published child identity.
- * @mode emit
- */
-'subagent/start'(this: Scoped<SubagentRuntime>, info: SubagentRunInfo): void
-```
-
-Types: [Scoped](scope.zh.md)
-
-Source: [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)
-<!-- END GENERATED cordis-surface -->