@morlay/dsh-subagent 0.0.1-alpha.2 → 0.0.1

package/README.md

@@ -1,13 +1,18 @@
 # @morlay/dsh-subagent
 
-上游 `@deepseek-ai/dsh-subagent` 的**薄壳 fork**：host 半只改一件事——continuable 子代理首条任务后面的
-**回报指引换成中文**（上游是英文）。服务名（`ctx.subagents`）、providers、其余子路径（`./internal` 等）
-与装配位置都不变。设置页那张「子代理」卡片是本包自己的 client 半（见下），不是从上游 fork 来的。
+上游 `@deepseek-ai/dsh-subagent` 的**薄壳 fork**：host 半只改两件事——continuable 子代理首条任务后面的
+**回报指引**换成中文（上游是英文，且只在"会话挂着本部署那份 preset"时用，其余会话保持上游那套），以及
+**接管官方那一行**（行 id 仍是 `subagent`，见下）。服务名（`ctx.subagents`）、providers、其余子路径
+（`./internal` 等）与装配位置都不变。配置页由**官方**那张卡片承担（行 id 没换，`subagent` namespace 照旧）。
 
-装配由本包的 bundle patch 完成（`cordis.patch.yml`）：官方 `subagent` 行 `disabled: true` + insert
-`subagent-fork`（`@morlay/dsh-subagent`），并停掉官方设置卡那两条行（`ui-settings-subagent` 与
-`subagent-model-selection-settings`，理由见 [ADR](./.agents/adrs/20260923-设置页自建client半并停掉官方两条入口行.md)）；
-app 的 `dsh.profile.bundles` 里引用本包。
+装配由本包的装配数据完成（`cordis.patch.yml` / `rows` 出口）：**按官方行 id 复用**——插一条
+`{ id: "subagent", name: "@morlay/dsh-subagent" }`，Loader 对同 id 复用同一个 Entry、后者替换入口 options，
+所以行 id 与 settings namespace 都还是 `subagent`，官方设置卡（`ui-settings-subagent`）与它的服务行
+（`subagent-model-selection-settings`）都不动；顺序前提是本包排在 `@deepseek-ai/dsh-base` 之后。理由与被否的
+路线见 [ADR 接管官方行按 id 复用](./.agents/adrs/20260928-接管官方行按id复用而非换id.md)。
+
+回报指引的名单走这一行的 `config.localizedReturnGuidancePresets`（装配给，`.hidden()` 不进设置页）；app 的
+`dsh.profile.bundles` 里引用本包。
 
 ## 保留文件（3 个）
 
@@ -15,16 +20,20 @@ app 的 `dsh.profile.bundles` 里引用本包。
 `vendor/deepseek-harness/packages/subagent/subagent/src/...`，构建时内联进 `dist/index.mjs`
 （发布物自包含）。
 
-| 保留文件（`src/`）         | 保留什么                                                                       |
-| -------------------------- | ------------------------------------------------------------------------------ |
-| `continuation-messages.ts` | **唯一实质改动**：`withContinuableReturnGuidance` 的中文文案（保留父 id 插值） |
-| `continuation.ts`          | 只有一行接线不同：`continuation-messages.ts` 指向本包那一份                    |
-| `index.ts`                 | 接线 + 两处结构性偏离（见下）                                                  |
+| 保留文件（`src/`）         | 保留什么                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `continuation-messages.ts` | 中文文案 + 判定函数 `localizedReturnGuidance`（"这个会话要不要本包那份文案"）              |
+| `continuation.ts`          | 接线 + 调用点从"永远是本包文案"改成"按会话选"（读 `ctx.agentPresets` 的 `composedPreset`） |
+| `index.ts`                 | 接线 + 装配面配置字段（`localizedReturnGuidancePresets`）+ 两处结构性偏离（见下）          |
 
 静态 import 链决定了复制面：`continuation-messages` ← `continuation` ← `index`，要替换中间那一份就得
 连同引用它的两个文件一起接管。原因、被否掉的路线与后果见
 [ADR 薄壳 fork 接管 subagent 行只改回报文案](./.agents/adrs/20260923-薄壳fork接管subagent行只改回报文案.md)。
 
+**偏离清单是可执行的**：`src/__tests__/upstream-wiring.spec.ts` 的 `DELTAS` 表逐条登记上面每处偏离（新增
+块、改过的行、装配面字段），偏离表里的片段没命中就红——加偏离必须同时登记，否则测试报"偏离表里的片段不在
+文件里"。
+
 ## 两处结构性偏离
 
 - **`index.ts` 不复述 cordis 合并接口**：上游此处 `declare module '@deepseek-ai/cordis'` 声明
@@ -36,27 +45,26 @@ app 的 `dsh.profile.bundles` 里引用本包。
 本包三个保留文件**不做格式化**（`.oxfmtrc.json` 的 `ignorePatterns`）：它们与上游逐行对照是同步纪律的
 守护面，格式改了那条守护就失去意义。
 
-## 设置页（client 半）
+## 配置页
+
+**子代理用哪个模型不在这张卡上**：它跟着**父会话的模式**走（`@morlay/dsh-session-mode` 顶层 `models` 里
+「模式 → 服务商 / 模型」那两个选择器）。
 
-`src/client/` 是**本包自己的代码**（不与上游对照，格式照常走 oxfmt）：Plugins 页里那张「子代理」卡片，
-只有限额一段——递归深度（≥ 0）与并行上限（≥ 1），staged 编辑 + 保存/丢弃。
+限额两个字段（`maxDepth` / `maxActiveSubagents`，标了 `.volatile()`）由**官方**那张设置卡承担：接管没换行 id，
+`subagent` namespace 照旧，`ui-settings-subagent` 与 `subagent-model-selection-settings` 都不动。
 
-| 面                                              | 内容                                                                          |
-| ----------------------------------------------- | ----------------------------------------------------------------------------- |
-| `plugins.row.config`（key `@morlay/dsh-subagent#subagent-fork`） | `view: 'summary'` 给一句话说明；`view: 'page'` 给限额表单 |
-| settings namespace `subagent-fork`              | 本包 host 行 id 就是 namespace 名；可编辑字段是 `Config` 的两个 volatile 字段 |
-| locale namespace `settings.subagent`            | 卡片文案（zh + en，标题「子代理」）                                           |
+本包**不再有 client 半**（`./client` 出口、字典与字段文案槽都删了）：卡片回来之后它是重复面——两套都注册
+`settings.subagent` 字典时，`locale.register` 对同 namespace 同 locale 直接抛错
+（`locale namespace "settings.subagent" already has locale "zh"`），官方卡片那一行会加载失败。
 
-装配只有两条：包声明了 `dsh.client`（`platform: 'web'`）与 `./client` 入口，client 半就随 app-boot 的
-browser roster 一起装（**不需要额外的插行**）；host 行被描述出来之后（`configForms.whileServed(['subagent-fork'])`）
-卡片才注册，行不在时卡片一起消失。表单原语来自 fork 的 `@morlay/dsh-client-ui-primitives/client`
-（`SettingsForm` / `SettingsValueField` / `SettingsFormModel` / `settingsNumberField`）。
+`Config` 的 `localizedReturnGuidancePresets` 是**装配面**字段（`.hidden()`）：它不进设置页，由装配那一行给。
 
 ## 文档
 
 - 决策与理由：
   [ADR 薄壳 fork 接管 subagent 行只改回报文案](./.agents/adrs/20260923-薄壳fork接管subagent行只改回报文案.md)、
-  [ADR 设置页自建 client 半并停掉官方两条入口行](./.agents/adrs/20260923-设置页自建client半并停掉官方两条入口行.md)
+  [ADR 接管官方行按 id 复用](./.agents/adrs/20260928-接管官方行按id复用而非换id.md)、
+  （已作废）[ADR 停掉官方设置卡的两条入口行](./.agents/adrs/20260923-停掉官方设置卡的两条入口行.md)
 - 已知的债（两处 `continuation-messages` 实例、保留文件跟随方式）：
   [债务 continuation-messages 两份实例与保留文件跟随](./.agents/debts/20260923-continuation-messages两份实例与保留文件跟随.md)
 - 测试落点与判据：[本包规范 how-to-verify](./.agents/standards/how-to-verify.md)；薄壳 fork 的通用写法约束见

package/dist/index.d.mts

@@ -19,47 +19,43 @@ import { SessionId as SessionId$1, SessionSeq as SessionSeq$1 } from "@deepseek-
  * rather than imported.
  */
 type SubagentPromptRequestId = Branded<'session-request-id'>;
-/** Shared child fields for complete-descendant listing. */
+/** Shared child fields for recursive catalog listing. */
 type SubagentCatalogRow = {
   /** The durable child session id, stable across Activations. */
   readonly id: SessionId$1;
   /**
-   * 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.
  */
 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$1;
   /**
-   * 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';
 };
@@ -699,13 +695,9 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 }
 //#endregion
 //#region ../../../vendor/deepseek-harness/packages/subagent/subagent/src/list-children.d.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. */
 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;
@@ -1609,7 +1601,10 @@ interface ChildComposition {
 declare function applyChildComposition(childCtx: Context, parent: Agent, composition: ChildComposition): void;
 /** Policy seeded onto a child session's log at the delegation boundary. */
 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;
@@ -1834,19 +1829,19 @@ declare class SubagentRuntime$1 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[]>;
   /**
@@ -1981,6 +1976,13 @@ interface Config {
   maxActiveSubagents: Volatile<number>;
   /** Default delegation depth for tools without an explicit limit; defaults to 1. */
   maxDepth: Volatile<number>;
+  /**
+   * Preset ids whose sessions get this package's Chinese return guidance; default empty.
+   *
+   * 名单由**装配**给（这一行的 `config`）：文案是模型可见的东西，跟着 preset 走，其余会话走上游英文那套。
+   * 装配面，不是用户面——所以不进设置页（`.hidden()`）。
+   */
+  localizedReturnGuidancePresets: string[];
 }
 /** Named provider registry with one-shot runs, durable discovery, and continuable-child operations. */
 declare class SubagentRuntime extends TypertRemoteService {
@@ -1988,9 +1990,11 @@ declare class SubagentRuntime extends TypertRemoteService {
   static Config: z<Schemastery.ObjectS<NoInfer<{
     maxDepth: z<number, number, "volatile-defined">;
     maxActiveSubagents: z<number, number, "volatile-defined">;
+    localizedReturnGuidancePresets: z<string[], string[], "defined">;
   }>>, Schemastery.ObjectT<NoInfer<{
     maxDepth: z<number, number, "volatile-defined">;
     maxActiveSubagents: z<number, number, "volatile-defined">;
+    localizedReturnGuidancePresets: z<string[], string[], "defined">;
   }>>, "plain">;
   private providers;
   private continuations;
@@ -2094,19 +2098,19 @@ 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[]>;
   /**