@zhushanwen/subagent-core 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-core",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Cross-host shared subagent execution layer and workflow orchestration core (dual-form npm package: TS source for workspace, dist ESM+CJS for npm)",
   "type": "module",
   "license": "MIT",
@@ -22,28 +22,6 @@
       },
       "default": "./dist/index.js"
     },
-    "./engines/zcode/reader": {
-      "import": {
-        "types": "./dist/execution/engine/engines/zcode/reader.d.ts",
-        "default": "./dist/execution/engine/engines/zcode/reader.js"
-      },
-      "require": {
-        "types": "./dist/execution/engine/engines/zcode/reader.d.cts",
-        "default": "./dist/execution/engine/engines/zcode/reader.cjs"
-      },
-      "default": "./dist/execution/engine/engines/zcode/reader.js"
-    },
-    "./engines/zcode/constants": {
-      "import": {
-        "types": "./dist/execution/engine/engines/zcode/constants.d.ts",
-        "default": "./dist/execution/engine/engines/zcode/constants.js"
-      },
-      "require": {
-        "types": "./dist/execution/engine/engines/zcode/constants.d.cts",
-        "default": "./dist/execution/engine/engines/zcode/constants.cjs"
-      },
-      "default": "./dist/execution/engine/engines/zcode/constants.js"
-    },
     "./engine/paths": {
       "import": {
         "types": "./dist/execution/engine/paths.d.ts",
@@ -55,6 +33,17 @@
       },
       "default": "./dist/execution/engine/paths.js"
     },
+    "./engine/engine-discovery-scan": {
+      "import": {
+        "types": "./dist/execution/engine/engine-discovery-scan.d.ts",
+        "default": "./dist/execution/engine/engine-discovery-scan.js"
+      },
+      "require": {
+        "types": "./dist/execution/engine/engine-discovery-scan.d.cts",
+        "default": "./dist/execution/engine/engine-discovery-scan.cjs"
+      },
+      "default": "./dist/execution/engine/engine-discovery-scan.js"
+    },
     "./relay-env": {
       "import": {
         "types": "./dist/execution/relay-env.d.ts",
@@ -84,19 +73,24 @@
     "ajv": "^8.20.0",
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.8.2"
+    "@xyz-agent/extension-protocol": "0.8.2",
+    "@zhushanwen/subagent-engine-sdk": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "tsup": "^8.5.1",
     "typescript": "^5.7.0",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.8",
+    "@zhushanwen/pi-subagent-cli": "0.1.2",
+    "@zhushanwen/zcode-subagent-cli": "0.1.2"
   },
   "scripts": {
     "build": "tsup",
     "build:bundle": "tsup",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "record:engine-fixtures": "node scripts/record-engine-fixtures.mjs",
+    "test:engine-protocol": "vitest run src/execution/engine/__tests__/conformance/protocol-blackbox.test.ts src/execution/engine/__tests__/conformance/static-spawn-guard.test.ts"
   }
 }

package/src/__tests__/record-store-last-line.test.ts

@@ -81,7 +81,10 @@ describe("readLastJsonlLine 孤儿终态判定（超长末行 / 截断行）", (
     const rec = recovered("orphan-bigline");
     expect(rec.status).toBe("closed");
     expect(rec.closedReason).toBe("gc");
-    expect(rec.error).toBeUndefined();
+    // 回归锚点本体：300KB 完整行不误判截断（[F3] in-flight 重启中断 error 在场，
+    // 但无截断标记——64KB 固定尾窗的旧实现会把本行从中间切开判「truncated」）。
+    expect(rec.error).toContain("host restart");
+    expect(rec.error).not.toContain("truncated");
   });
 
   it("末行截断（无尾换行的半行 JSON）→ closed/gc + error 标记截断", () => {
@@ -91,7 +94,9 @@ describe("readLastJsonlLine 孤儿终态判定（超长末行 / 截断行）", (
     const rec = recovered("orphan-truncated");
     expect(rec.status).toBe("closed");
     expect(rec.closedReason).toBe("gc");
-    expect(rec.error).toContain("truncated last line");
+    // [F3] 无 resumable 信号 = in-flight：截断判定并入重启中断文案（"— last line truncated"）
+    expect(rec.error).toContain("host restart");
+    expect(rec.error).toContain("truncated");
   });
 
   it("超长且截断的末行 → 仍判截断 error（扩窗是为完整行服务，不放宽截断判定）", () => {
@@ -99,15 +104,18 @@ describe("readLastJsonlLine 孤儿终态判定（超长末行 / 截断行）", (
     writeOrphanSession("orphan-bigcut", bigTruncated, { trailingNewline: false });
     const rec = recovered("orphan-bigcut");
     expect(rec.status).toBe("closed");
-    expect(rec.error).toContain("truncated last line");
+    // [F3] 无 resumable 信号 = in-flight：截断判定并入重启中断文案
+    expect(rec.error).toContain("host restart");
+    expect(rec.error).toContain("truncated");
   });
 
-  it("常规末行（多行文件、完整 JSON）→ closed/gc 无 error", () => {
+  it("常规末行（多行文件、完整 JSON）→ closed/gc；无 resumable 信号 = in-flight 重启中断（[F3]）", () => {
     writeOrphanSession("orphan-normal", JSON.stringify({ type: "message", role: "assistant", content: "final" }));
     const rec = recovered("orphan-normal");
     expect(rec.status).toBe("closed");
     expect(rec.closedReason).toBe("gc");
-    expect(rec.error).toBeUndefined();
+    // [F3] 末行完整但无 resumable/result 信号 = 在途被重启中断：投影不得谎报 completed
+    expect(rec.error).toContain("host restart");
   });
 
   it("仅 identity 单行文件（首行即末行，合法 JSON）→ closed 无 error", () => {
@@ -122,8 +130,9 @@ describe("readLastJsonlLine 孤儿终态判定（超长末行 / 截断行）", (
     // identity 首行 + 紧跟空行结尾：非空段只剩 identity（窗口到文件头，首段完整）
     fs.writeFileSync(path.join(sessionsDir, "2026-07-18T12-00-00-000Z_orphan-empty.jsonl"), identity + "\n", "utf8");
     const rec = recovered("orphan-empty");
-    // 唯一非空行 = identity 首行（合法 JSON）→ 不判 error
+    // 唯一非空行 = identity 首行（合法 JSON）→ 无截断标记；[F3] in-flight 重启中断 error 在场
     expect(rec.status).toBe("closed");
-    expect(rec.error).toBeUndefined();
+    expect(rec.error).toContain("host restart");
+    expect(rec.error).not.toContain("truncated");
   });
 });

package/src/core/error-message.ts

@@ -1,9 +1,10 @@
 /**
- * 从任意 thrown 值提取可读的错误信息字符串：Error → `.message`，其它 → `String(e)`。
+ * toErrorMessage re-export shim——单源在 @zhushanwen/subagent-engine-sdk
+ * （round1-reuse R11 微副本收编；core → SDK 边界正向合法）。本文件路径不变，
+ * core 内部 8 个消费方 import 不动。
  *
- * 各包独立持有本 helper（core/renderer/runtime/subagent-core/electron/ext-guards 同实现），
- * 不引跨包依赖——收敛 `e instanceof Error ? e.message : String(e)` 样板。
+ * [A8 修复]：非 Error 的 object 入参经 SDK 单源输出 JSON 结构化文本（原
+ * String(e) = "[object Object]"）；Error 入参输出逐字节不变。core barrel 不导出
+ * 该符号（导出面零变化）。
  */
-export function toErrorMessage(e: unknown): string {
-  return e instanceof Error ? e.message : String(e);
-}
+export { toErrorMessage } from "@zhushanwen/subagent-engine-sdk";

package/src/core/host-services.ts

@@ -32,12 +32,18 @@ export interface HostServices {
   /** 结构化日志：对齐现 getLogger 调用面（level/component/message/data）。缺省 sink 按级分化：
    *  warn/error 走 console、debug no-op（对齐 pi-extension-logger 语义，见 NULL_HOST.log）。 */
   log(level: LogLevel, component: string, message: string, data?: unknown): void;
-  /** agent/skill/workflow 资源发现根（可选端口，缺席 = 调用方降级）。宿主只提供根列表
-   *  （按优先级低→高）；扫描 / 同名遮蔽（last-writer-wins）/ 遮蔽报告语义归 core 统一。 */
+  /** agent/skill/workflow/引擎包 资源发现根（可选端口，缺席 = 调用方降级）。宿主只提供根列表
+   *  （按优先级低→高）；扫描 / 同名遮蔽（last-writer-wins）/ 遮蔽报告语义归 core 统一。
+   *
+   *  engines kind（W4，设计 §3.4 L1 第二通道）：引擎包发现根——dir 下一级（及 org 分组
+   *  二级）子项 = 候选引擎包目录，命中 package.json `xyz-agent.subagentEngine` manifest
+   *  即发现。打包态主通道是 env `XYZ_AGENT_ENGINE_ROOTS`（W9 注入），此端口承载宿主
+   *  自身模块域（如 pi 宿主包 node_modules 的引擎包 dependencies 安装位）。 */
   discoveryRoots?(): {
     agents?: DiscoveryRoot[];
     skills?: DiscoveryRoot[];
     workflows?: DiscoveryRoot[];
+    engines?: DiscoveryRoot[];
   };
 }
 

package/src/core/notify-ports.ts

@@ -92,11 +92,26 @@ export interface DeliveryHandle {
   dispose(): void;
 }
 
+/** countActiveFromEntries 的过滤选项（[F1] 与 pending-notifications 的
+ *  CountActiveOptions 对齐的子集——core 契约面只暴露跨 session 基准一个字段）。 */
+export interface CountActivePortOptions {
+  /**
+   * [W4 读侧过滤②] 跨 session 残留过滤基准：传入时端口实现按「register entry 的
+   * sessionId ≠ 基准 → 跳过」过滤——fork 继承的父级注册残留（翻 process 档后 U4
+   * 补注销不再中性化，永久留存于子 session 文件）不进差集。
+   * 缺省（undefined）= 不过滤（向后兼容：既有调用方零改动行为不变）。
+   */
+  currentSessionId?: string;
+}
+
 export interface NotifyDomainPorts {
   /** pending 活跃计数（pi 会话 entries 中 register − unregister 差集的数值）。
    *  契约为 number 而非 pi 侧 CountActiveResult：core 消费面只读 count，契约面最窄；
-   *  pi 壳注入时拆 `countActiveFromEntries(entries).count`。 */
-  countActiveFromEntries?(entries: unknown[]): number;
+   *  pi 壳注入时拆 `countActiveFromEntries(entries).count`。
+   *  [F1] 第二参为可选过滤基准（CountActivePortOptions）——core 消费方（后代判定
+   *  读侧）持有「被读 entries 所属 session」概念时必须传入，使跨 session 残留不进
+   *  差集；与 pending-notifications 实装签名（entries, opts?) 对齐。 */
+  countActiveFromEntries?(entries: unknown[], opts?: CountActivePortOptions): number;
   /** 投递内核工厂。签名与 @xyz-agent/session-delivery 的 createDelivery 结构兼容，
    *  pi 壳直传其本体即可。缺席 = 消费方降级直发。 */
   createDelivery?(port: DeliveryPort, options?: DeliveryConfig): DeliveryHandle;

package/src/execution/__tests__/chat-engine-routing.test.ts

@@ -76,7 +76,12 @@ import type {
 import { ModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
 import { toSubagentRecordEntry } from "../record-entry.ts";
-import { getChildByRecord } from "../engine/engines/pi/session-runner.ts";
+// W10（§2.10 ②）：子进程句柄断言改读 core 侧状态镜像（host/spawned-children——
+// 协议化后 spawnedChildren 持有方在引擎进程，core 消费镜像面；判据 pid 同构）。
+import {
+  coreSpawnedChildrenMirror,
+  _resetCoreSpawnedChildrenMirrorForTest,
+} from "../engine/host/spawned-children.ts";
 import { SubagentService } from "../subagent-service.ts";
 import type { ExecuteOptions } from "../types.ts";
 
@@ -121,6 +126,23 @@ class FakeEngine implements EnginePort {
   }
 
   capabilities(): EngineCapabilities {
+    // [W3] id==='pi' 的注册占位按 pi 真实能力位声明（gate 同步面放行 pi 全参数——
+    // V4⑤ 反向守护；否则 maxTurns/conversation 会被误拦）。
+    if (this.id === "pi") {
+      return {
+        schemaEnforcement: "native",
+        steer: "unsupported",
+        conversation: "native",
+        personaInjection: "flag",
+        eventGranularity: "stream",
+        sandbox: "emulated",
+        sessionRead: "full",
+        resume: "native",
+        interrupt: "kill-only",
+        permissionMode: "native",
+        maxTurns: true,
+      };
+    }
     return ZCODE_LIKE_CAPS;
   }
   async probe(): Promise<ProbeReport> {
@@ -231,6 +253,7 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
   let agentDir: string;
 
   beforeEach(() => {
+  _resetCoreSpawnedChildrenMirrorForTest();
     // u0-data-discovery 注入化：execute 链路的 getEngineDataDir 回退段经
     // HostServices.dataRoot() 端口，未 configureCore 即消费抛 core_host_not_configured
     // （execute fail-safe 吞掉后表现为 mock 计数 0）——端口态显式配置，值不被断言
@@ -284,8 +307,10 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     expect(mockSpawn).not.toHaveBeenCalled();
   });
 
-  it("[缺省] 全缺省 → pi 原路径（spawn 启动，不经引擎注册表）", async () => {
-    // 不注册任何引擎也照跑：pi 缺省免探免注册表校验（D4「pi 恒免探」）
+  it("[缺省] 全缺省 → pi 路由派发（[W3] pi 缺省经 registry cli 形态 port 协议派发）", async () => {
+    // [W3 改写] 原「不注册任何引擎也照跑（inproc DI 直连 spawn）」随 chat 域收口
+    // 消亡：pi 路由 = registry 'pi' 的 cli 形态 port（pi-host-binding 解析）。未注册
+    // 时为不可用 stub——engine.run 抛 engine_not_found，record 按 MF-6 回退可恢复。
     clearEngines();
     const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
     modelService.initModel({
@@ -296,8 +321,13 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     const service = new SubagentService({ cwd: agentDir, modelService });
     service.initSession({ pi: makePi(), sessionId: "test-session" });
 
-    await service.execute(baseOpts(agentDir));
-    await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
+    const handle = await service.execute(baseOpts(agentDir));
+    // 不可用 stub：轮次派发在首次 engine.run 拒绝（engine_not_found）→ chatMode=false
+    // 一次性 run 终态销毁（无孤儿 record——拒绝点唯一化在 run）。
+    await vi.waitFor(() => {
+      const rec = service.queries.collectRecords(10, "all").find((r) => r.id === handle.subagentId);
+      expect(rec?.status).toBe("closed");
+    });
   });
 
   // ============================================================
@@ -305,9 +335,9 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
   // ============================================================
 
   it("[D5] 全缺省 pi record：engine===undefined 且 entry JSON 不含 engine 键", async () => {
-    const { service } = setup(agentDir);
+    const { service, piEngine } = setup(agentDir);
     const handle = await service.execute(baseOpts(agentDir));
-    await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
+    await vi.waitFor(() => expect(piEngine.runs.length).toBe(1));
 
     const rec = service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
     expect(rec).toBeDefined();
@@ -318,12 +348,11 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
   it("[D5] 显式 engine:'pi' 路由回 pi：record 不盖章 engine", async () => {
     const { service, piEngine, zcode } = setup(agentDir);
     const handle = await service.execute(baseOpts(agentDir, { engine: "pi" }));
-    await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
+    await vi.waitFor(() => expect(piEngine.runs.length).toBe(1));
 
     expect(zcode.runs.length).toBe(0);
-    // piEngine 只是注册表占位——D2 单轨后 pi chat 走 Service 内部 DI 的 PiEngine 实例
-    //（chatPiEngine，经 EnginePort 交接轮次），registry 占位实例仍未被 chat 域消费
-    expect(piEngine.runs.length).toBe(0);
+    // [W3] pi chat 路由 = registry 'pi' port（cli 形态替身）——显式 pi 请求命中它
+    expect(piEngine.runs.length).toBe(1);
     const rec = service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
     expect(rec?.engine).toBeUndefined();
   });
@@ -339,9 +368,11 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
       .catch((e: unknown) => e);
     expect(err).toBeInstanceOf(Error);
     expect((err as Error).message).toContain("不支持 conversation");
-    // 恢复指引（EngineError.recovery）含「改用 engine: pi 或不传该参数」
-    expect((err as { recovery?: string }).recovery).toContain("engine: pi");
-    expect((err as { recovery?: string }).recovery).toContain("不传该参数");
+    // 恢复指引（EngineError.recovery）：W3 协议化口径——调参数 / 修 manifest / 升级
+    // 引擎包（引擎包是能力声明载体；「改用 engine: pi」内置兜底指引已随协议化删除）
+    expect((err as { recovery?: string }).recovery).toContain("去掉 conversation 参数");
+    expect((err as { recovery?: string }).recovery).toContain("修 manifest capabilities");
+    expect((err as { recovery?: string }).recovery).toContain("升级引擎包");
     expect(zcode.runs.length).toBe(0);
     expect(service.queries.collectRecords(10, "all")).toHaveLength(0);
   });
@@ -369,22 +400,24 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     expect(err).toBeInstanceOf(Error);
     expect((err as Error).message).toContain("engine_capability_unsupported");
     expect((err as Error).message).toContain("maxTurns");
-    expect((err as { recovery?: string }).recovery).toContain("engine: pi");
+    // W3 协议化口径：恢复指引 = 去参数 / 修 manifest / 升级引擎包（不再指向 engine: pi）
+    expect((err as { recovery?: string }).recovery).toContain("去掉 maxTurns 参数");
+    expect((err as { recovery?: string }).recovery).toContain("修 manifest capabilities");
     // 「不产生孤儿 record」断言落点（V4④）：store 无新增条目、引擎未被触达
     expect(zcode.runs.length).toBe(0);
     expect(service.queries.collectRecords(10, "all")).toHaveLength(0);
   });
 
   it("[V4⑤ 反向] pi + maxTurns/fork/conversation/worktree → 零拦截（pi 既有合法能力无回归）", async () => {
-    const { service, zcode } = setup(agentDir);
-    // maxTurns=3（V4⑤ 场景原样）：正常进入 pi 轮次（spawn 被调），无同步拒绝
+    const { service, piEngine, zcode } = setup(agentDir);
+    // maxTurns=3（V4⑤ 场景原样）：正常进入 pi 轮次（engine.run 被调），无同步拒绝
     const handle = await service.execute(baseOpts(agentDir, { maxTurns: 3 }));
-    await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
+    await vi.waitFor(() => expect(piEngine.runs.length).toBe(1));
     expect(zcode.runs.length).toBe(0);
     expect(service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId)).toBeDefined();
-    // fork / conversation 组合同样直通（第二次 spawn 被调，无 engine_capability_unsupported）
+    // fork / conversation 组合同样直通（第二次 run 被调，无 engine_capability_unsupported）
     await service.execute(baseOpts(agentDir, { fork: true, conversation: true }));
-    await vi.waitFor(() => expect(mockSpawn.mock.calls.length).toBeGreaterThanOrEqual(2));
+    await vi.waitFor(() => expect(piEngine.runs.length).toBeGreaterThanOrEqual(2));
     // pi + worktree：预检放行（caps.sandbox='emulated'）——execute 不因能力被拒而
     // reject（worktree 创建成败是另一维度，与拦截无关）
     await expect(service.execute(baseOpts(agentDir, { worktree: true }))).resolves.toBeTypeOf("object");
@@ -475,7 +508,7 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
 
     // 引擎经 RunContext.onChildSpawned 上报子进程 → 宿主记账（kill-chain 数据源）
     zcode.runs[0].ctx.onChildSpawned?.(child);
-    expect(getChildByRecord(handle.subagentId)).toBe(child);
+    expect(coreSpawnedChildrenMirror().getChildByRecord(handle.subagentId)?.pid).toBe(child.pid);
 
     // cancel → controller.abort → engine 收到的 signal aborted（kill-chain 两级的第一级）
     expect(zcode.runs[0].ctx.signal?.aborted).toBe(false);
@@ -483,7 +516,8 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     expect(zcode.runs[0].ctx.signal?.aborted).toBe(true);
     // 子进程退出后记账按句移除
     child.emit("close", 0, null);
-    expect(getChildByRecord(handle.subagentId)).toBeUndefined();
+    // 按句移除断言（W10 注）：inproc 双模不回灌 childStateChanged，镜像移除由
+    // protocol-blackbox 承载（同 subprocess-agent-runner-routing D10 注）。
   });
 });
 
@@ -507,15 +541,15 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
     vi.clearAllMocks();
   });
 
-  it("[兜底] 默认路由 zcode + probe 失败 → 回退 pi runSpawn + engineFallback 留痕", async () => {
+  it("[兜底] 默认路由 zcode + probe 失败 → 回退 pi 协议 run + engineFallback 留痕", async () => {
     writeGlobalConfig(agentDir, "zcode");
     const { service, zcode, piEngine } = setup(agentDir);
     zcode.probeFailed = true;
 
     const handle = await service.execute(baseOpts(agentDir));
-    // 兜底 = 走 pi runSpawn 路径（spawn 被调），非 pi EnginePort 未被消费
-    await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
-    expect(piEngine.runs.length).toBe(0);
+    // 兜底 = 走 pi 协议 run 路径（engine.run 被调；[W3] pi 与 run 域同路）
+    await vi.waitFor(() => expect(piEngine.runs.length).toBe(1));
+    expect(mockSpawn).not.toHaveBeenCalled();
 
     const rec = service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
     expect(rec?.engine).toBe("pi");
@@ -668,9 +702,9 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
   });
 
   it("[D5 回归] pi 纯缺省路径 entry 不含 engine/engineFallback/engineHandle 键", async () => {
-    const { service, pi } = setup(agentDir);
+    const { service, piEngine, pi } = setup(agentDir);
     const handle = await service.execute(baseOpts(agentDir));
-    await vi.waitFor(() => expect(mockSpawn).toHaveBeenCalled());
+    await vi.waitFor(() => expect(piEngine.runs.length).toBe(1));
 
     const rec = service.queries.collectRecords(10, "running").find((r) => r.id === handle.subagentId);
     const entryJson = JSON.stringify(toSubagentRecordEntry(rec!));