@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/engine/__tests__/registry.test.ts

@@ -3,19 +3,31 @@
 // registry 专属测试（P1 验收 4）：注册/获取/listEngines/hasEngine/
 // 未注册 id 报 engine_not_found（错误文案含已注册清单——错误规格表第 1 行契约）。
 // [R1 D6] 追加：重注册先 dispose 旧单例（D6②）+ disposeEngines 收割遍历（D6③）。
+// [W3] 追加：EngineDescriptor 双模（inproc 快捷 / cli portFactory 代理透明——
+// cli 形态 EnginePort 实例 = W2 RemoteEngine）+ D4 displayName 稳定序 +
+// 全不可用 engine_not_found 文案（「未发现任何引擎包」+ 安装指引）。
 
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+import { EngineClient } from "../client/engine-client.ts";
+import { RemoteEngine } from "../client/remote-engine.ts";
 import type { EnginePort, RunContext } from "../port.ts";
 import {
   clearEngines,
   DEFAULT_ENGINE_ID,
   disposeEngines,
   EngineNotFoundError,
+  firstAvailableEngineId,
   getEngine,
   hasEngine,
   listEngines,
+  listEnginesByDisplayName,
   registerEngine,
+  registerEngineDescriptor,
+  type EngineManifestSnapshot,
 } from "../registry.ts";
 import type { SessionView } from "../types.ts";
 import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
@@ -209,3 +221,196 @@ describe("engine registry", () => {
     });
   });
 });
+
+// ============================================================
+// [W3] EngineDescriptor 双模 + manifest 快照 + D4（impl-plan §2.3）
+// ============================================================
+
+/** cli 形态 manifest 快照样本（与 RemoteEngineManifestSnapshot 结构闭包的运行时互证载体）。 */
+function makeManifestSnapshot(displayName?: string): EngineManifestSnapshot {
+  return {
+    capabilities: {
+      schemaEnforcement: "emulated",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "stream",
+      sandbox: "emulated",
+      sessionRead: "full",
+      resume: "cold",
+      interrupt: "kill-only",
+      permissionMode: "fixed",
+      maxTurns: false,
+    },
+    modelCatalog: { dynamic: true, models: [{ id: "glm-4.6", canonicalRef: "zai/glm-4.6" }] },
+    ...(displayName !== undefined ? { displayName } : {}),
+  };
+}
+
+/** W2 真实 cli 形态 port 装配（构造同步、不 spawn——ensureConnected 才 spawn）。 */
+function makeRemoteEngine(id: string, manifest: EngineManifestSnapshot): RemoteEngine {
+  const client = new EngineClient({
+    engineId: id,
+    command: process.execPath,
+    args: ["-e", ""],
+    hostKind: "test",
+    dataDir: join(tmpdir(), `registry-w3-${id}`),
+    manifestDiagnostics: { capabilities: manifest.capabilities, models: manifest.modelCatalog?.models ?? null },
+  });
+  return new RemoteEngine({
+    engineId: id,
+    client,
+    manifest: { capabilities: manifest.capabilities, modelCatalog: manifest.modelCatalog },
+    dataDir: join(tmpdir(), `registry-w3-${id}`),
+    hostKind: "test",
+  });
+}
+
+describe("EngineDescriptor 双模（W3 D1）", () => {
+  beforeEach(() => {
+    clearEngines();
+  });
+
+  it("registerEngine = inproc 快捷：descriptor kind=inproc，getEngine 透明（既有工厂语义不变）", () => {
+    registerEngine("fake", () => makeFakeEngine("fake"));
+    const engine = getEngine("fake");
+    expect(engine.id).toBe("fake");
+    expect(hasEngine("fake")).toBe(true);
+    expect(listEngines()).toEqual(["fake"]);
+  });
+
+  it("cli descriptor：getEngine 返回 portFactory 产物，两形态透明（cli 形态实例 = W2 RemoteEngine）", () => {
+    const manifest = makeManifestSnapshot();
+    const port = makeRemoteEngine("zcode-cli", manifest);
+    const portFactory = vi.fn(() => port as EnginePort);
+    registerEngineDescriptor("zcode-cli", {
+      kind: "cli",
+      command: process.execPath,
+      args: ["-e", ""],
+      capabilities: manifest.capabilities,
+      portFactory,
+      manifest: { modelCatalog: manifest.modelCatalog, displayName: manifest.displayName },
+    });
+    const engine = getEngine("zcode-cli");
+    // 两形态透明：上层拿到的是同一个 EnginePort 面；cli 实例 = W2 RemoteEngine
+    expect(portFactory).toHaveBeenCalledTimes(1);
+    expect(engine).toBe(port);
+    expect(engine).toBeInstanceOf(RemoteEngine);
+    expect(engine.id).toBe("zcode-cli");
+    // 同步成员直读 manifest 快照（W2 形态映射经 registry descriptor 快照成立）
+    expect(engine.capabilities()).toBe(manifest.capabilities);
+  });
+
+  it("cli descriptor 惰性单例：portFactory 首次取用才执行，重复 getEngine 同实例", () => {
+    const manifest = makeManifestSnapshot();
+    const portFactory = vi.fn(() => makeRemoteEngine("lazy", manifest) as EnginePort);
+    registerEngineDescriptor("lazy", {
+      kind: "cli",
+      command: process.execPath,
+      args: [],
+      capabilities: manifest.capabilities,
+      portFactory,
+    });
+    // 注册本身不触发 portFactory（descriptor 首次使用才解析——§3.5.3 代理形态）
+    expect(portFactory).not.toHaveBeenCalled();
+    expect(hasEngine("lazy")).toBe(true);
+    const a = getEngine("lazy");
+    const b = getEngine("lazy");
+    expect(a).toBe(b);
+    expect(portFactory).toHaveBeenCalledTimes(1);
+  });
+
+  it("cli descriptor 覆盖同 id：旧单例 dispose 触发 + 新 portFactory 重建（与 inproc 覆盖同语义）", () => {
+    const manifest = makeManifestSnapshot();
+    const dispose = vi.fn(() => Promise.resolve());
+    const oldPort = makeRemoteEngine("overwrite", manifest);
+    (oldPort as unknown as { dispose: typeof dispose }).dispose = dispose;
+    registerEngineDescriptor("overwrite", {
+      kind: "cli",
+      command: process.execPath,
+      args: [],
+      capabilities: manifest.capabilities,
+      portFactory: () => oldPort as EnginePort,
+    });
+    getEngine("overwrite");
+    const newPort = makeRemoteEngine("overwrite", manifest);
+    registerEngineDescriptor("overwrite", {
+      kind: "cli",
+      command: process.execPath,
+      args: [],
+      capabilities: manifest.capabilities,
+      portFactory: () => newPort as EnginePort,
+    });
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(getEngine("overwrite")).toBe(newPort);
+  });
+});
+
+describe("D4：displayName 稳定序与首个可用引擎（W3）", () => {
+  beforeEach(() => {
+    clearEngines();
+  });
+
+  it("listEnginesByDisplayName：displayName 排序（码点序），缺省 = id，displayName 相同按 id 决胜", () => {
+    // 注册序故意与 displayName 序不同——排序键是 manifest displayName 而非注册序
+    registerEngineDescriptor("beta", {
+      kind: "cli",
+      command: process.execPath,
+      args: [],
+      capabilities: makeManifestSnapshot("Zulu").capabilities,
+      portFactory: () => makeFakeEngine("beta"),
+      manifest: { displayName: "Zulu" },
+    });
+    registerEngine("alpha", () => makeFakeEngine("alpha")); // inproc 无 manifest → displayName = id
+    registerEngineDescriptor("gamma", {
+      kind: "cli",
+      command: process.execPath,
+      args: [],
+      capabilities: makeManifestSnapshot().capabilities,
+      portFactory: () => makeFakeEngine("gamma"),
+      // 无 displayName → 缺省 = id
+    });
+    registerEngineDescriptor("delta", {
+      kind: "cli",
+      command: process.execPath,
+      args: [],
+      capabilities: makeManifestSnapshot("Zulu").capabilities,
+      portFactory: () => makeFakeEngine("delta"),
+      manifest: { displayName: "Zulu" },
+    });
+    // 码点序：'Z'(0x5A) < 'a'(0x61) —— displayName "Zulu" 组（beta/delta，组内按 id
+    // 决胜 beta < delta）排在 "alpha"/"gamma" 之前
+    expect(listEnginesByDisplayName()).toEqual(["beta", "delta", "alpha", "gamma"]);
+  });
+
+  it("firstAvailableEngineId：清单第一项；空注册表 undefined（调用方转 engine_not_found）", () => {
+    expect(firstAvailableEngineId()).toBeUndefined();
+    registerEngineDescriptor("zcode", {
+      kind: "cli",
+      command: process.execPath,
+      args: [],
+      capabilities: makeManifestSnapshot("ZCode").capabilities,
+      portFactory: () => makeFakeEngine("zcode"),
+      manifest: { displayName: "ZCode" },
+    });
+    registerEngine("pi", () => makeFakeEngine("pi"));
+    // 码点序："ZCode"(Z=0x5A) < "pi"(p=0x70)——displayName 序与 id 序不同向正是本用例点
+    expect(firstAvailableEngineId()).toBe("zcode");
+  });
+});
+
+describe("engine_not_found 空清单文案（W3 D4：未发现任何引擎包）", () => {
+  it("registered 为空：文案含「No engine packages were discovered」+ 安装指引", () => {
+    const err = new EngineNotFoundError("pi", []);
+    expect(err.code).toBe("engine_not_found");
+    expect(err.message).toContain("No engine packages were discovered");
+    expect(err.message).toContain("XYZ_AGENT_ENGINE_ROOTS");
+    expect(err.message).toContain("(none)");
+  });
+
+  it("registered 非空：维持既有恢复指引（frontmatter / 默认引擎设置修 typo）", () => {
+    const err = new EngineNotFoundError("ghost", ["pi", "zcode"]);
+    expect(err.message).toContain("frontmatter");
+    expect(err.message).not.toContain("No engine packages were discovered");
+  });
+});

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

@@ -54,6 +54,8 @@ function makeRoute(overrides?: {
   taskModel?: string;
   /** 额外注册第三引擎（probe ok）——fallback 目标为「非 pi 的其他全局默认」用例。 */
   globalEngine?: string;
+  /** D4 可用清单覆盖（缺省 = 注册表插入序 pi 优先；displayName 序由注册方负责）。 */
+  available?: string[];
 }) {
   const engines = new Map<string, EnginePort>();
   engines.set(DEFAULT_ENGINE_ID, makeFakeEngine("pi", true));
@@ -77,6 +79,7 @@ function makeRoute(overrides?: {
     },
     hasEngineFn: (id) => engines.has(id),
     listEnginesFn: () => [...engines.keys()],
+    listAvailableEnginesFn: () => overrides?.available ?? [...engines.keys()],
   };
   return { opts, probeCalls, engines };
 }
@@ -338,3 +341,97 @@ describe("routeEngineForHost：宿主统一路由（D3-②）", () => {
     expect((err as EngineNotFoundError).registered).toContain("pi");
   });
 });
+
+// ============================================================
+// [W3] D4 缺省引擎回落链 + fallback 目标「首个可用引擎」（impl-plan §2.3）
+// ============================================================
+
+describe("D4 缺省引擎回落链（default 层宽容 / call/frontmatter 层显式报错）", () => {
+  it("defaultEngine 指向未注册 id（已卸载）：warn + 回落首个可用 + engineFallback 留痕（A12④）", async () => {
+    const { opts } = makeRoute({
+      routing: { globalDefaultEngine: "ghost-engine" },
+      available: ["pi", "zcode"],
+    });
+    const result = await routeEngine(opts);
+    expect(result.engineId).toBe("pi"); // 首个可用（displayName 序第一）
+    expect(result.requestedEngineId).toBe("ghost-engine");
+    expect(result.engineFallback).toEqual({ from: "ghost-engine", reason: "engine_not_found" });
+    expect(result.source).toBe("default");
+  });
+
+  it("default 层回落不探（目标引擎不可用由 run 期显式失败，probe 已失败一次不重复）", async () => {
+    const { opts, probeCalls } = makeRoute({
+      routing: { globalDefaultEngine: "ghost-engine" },
+      available: ["pi", "zcode"],
+    });
+    await routeEngine(opts);
+    expect(probeCalls).toEqual([]);
+  });
+
+  it("全不可用（清单空）：engine_not_found + 「未发现任何引擎包」+ 安装指引（D4）", async () => {
+    const { opts } = makeRoute({
+      routing: { globalDefaultEngine: "ghost-engine" },
+      available: [],
+    });
+    const err = await routeEngine(opts).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(EngineNotFoundError);
+    expect((err as EngineNotFoundError).message).toContain("No engine packages were discovered");
+  });
+
+  it("call 层未知 id：仍 engine_not_found 前置暴露（D4 宽容回落只作用 default 层）", async () => {
+    const { opts } = makeRoute({
+      routing: { callEngine: "ghost-engine" },
+      available: ["pi", "zcode"],
+    });
+    await expect(routeEngine(opts)).rejects.toThrowError(EngineNotFoundError);
+  });
+
+  it("frontmatter 层未知 id：同 call 层前置暴露（配置错误不静默换引擎）", async () => {
+    const { opts } = makeRoute({
+      routing: { agentEngine: "ghost-engine" },
+      available: ["pi", "zcode"],
+    });
+    await expect(routeEngine(opts)).rejects.toThrowError(EngineNotFoundError);
+  });
+});
+
+describe("fallbackTargetId「首个可用引擎」语义（W3：恒 'pi' 作废）", () => {
+  it("probe 失败兜底：全局默认不在可用清单 → 首个可用引擎（排除 from）", async () => {
+    // globalDefaultEngine='ghost'（未注册）→ 既有逻辑会 get('ghost') 炸；D4 后校验
+    // 可用性，落「首个可用引擎」
+    const { opts, engines } = makeRoute({
+      zcodeProbeOk: false,
+      globalEngine: "claude",
+      routing: { agentEngine: "zcode", globalDefaultEngine: "ghost" },
+      available: ["claude", "zcode"],
+    });
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("claude")); // 可用清单内第一 ≠ from
+    expect(result.engineId).toBe("claude");
+  });
+
+  it("可用清单只含刚失败的引擎（from）：不原地重试，直接报 engine_probe_failed（D4 无可用不 fallback）", async () => {
+    const { opts } = makeRoute({
+      zcodeProbeOk: false,
+      routing: { agentEngine: "zcode" },
+      available: ["zcode"],
+    });
+    const err = await routeEngine(opts).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(EngineError);
+    expect((err as EngineError).code).toBe("engine_probe_failed");
+    expect((err as EngineError).message).toContain("无其他可用引擎");
+  });
+
+  it("default 层 probe 失败（defaultEngine 配了坏引擎）：首个可用引擎，不再恒回 'pi'", async () => {
+    const { opts, engines } = makeRoute({
+      zcodeProbeOk: false,
+      globalEngine: "alpha",
+      routing: { globalDefaultEngine: "zcode" },
+      available: ["alpha", "zcode"],
+    });
+    // available 无 pi：D4 语义下不再强行回 'pi'——首个可用（≠from）= alpha
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("alpha"));
+    expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+});

package/src/execution/engine/__tests__/run-failure-worktree-cleanup.test.ts

@@ -0,0 +1,97 @@
+// run-failure-worktree-cleanup.test.ts —— [W3 契约变更⑤] run 期失败清理前置副作用的
+// 链路锚定单测。
+//
+// 设计权威源：docs/design/subagent-engine-protocolization.md §3.3 能力位段（manifest
+// 多声明 → initialize 发现 → engine_capability_mismatch 该 run 失败 + record 标 failed
+// + **清理 run 前已建的前置副作用**）；impl-plan §2.3 契约变更⑤。
+//
+// 链路事实（2026-09-09 grep/read 实测，W3 以测试锚定防后续单元破坏）：
+//   executeViaEngine（worktree 创建，record.worktreeHandle 绑定）
+//     → kickOffEngineRun → runEngineTask catch（engine.run prepare 期 reject，含协议
+//       握手 engine_capability_mismatch 形态）
+//     → finalizeFailed（CAS tryTransition closed/gc 抢到锁）
+//     → finalizeRecord → doFinalizeRecord Step 3b cleanupWorktreeIfBound
+//     → worktreeManager.cleanup(record.worktreeHandle)。
+//   前置副作用唯一实体 = worktree（并发池槽在 kickOffEngineRun finally 自回收；journal
+//   是宿主②级数据源不清理）。本文件直接锚定执行体 doFinalizeRecord 的 worktree 清理
+//   行为——subagent-service.finalizeFailed 的 JSDoc 为链路登记处。
+
+import { describe, expect, it, vi } from "vitest";
+
+import { doFinalizeRecord, type FinalizeDeps } from "../../finalize-record.ts";
+import type { AgentResult, ExecutionRecord, WorktreeHandle } from "../../types.ts";
+
+/** 最小 record（worktree 绑定可注入；status running 供终态迁移）。 */
+function makeRecord(worktreeHandle?: WorktreeHandle): ExecutionRecord {
+  return {
+    id: "sa-w3-cleanup",
+    agent: "tester",
+    model: "prov/model",
+    task: "t",
+    status: "running",
+    mode: "background",
+    startedAt: Date.now(),
+    turnCount: 0,
+    chatMode: false,
+    ...(worktreeHandle !== undefined ? { worktreeHandle } : {}),
+  } as unknown as ExecutionRecord;
+}
+
+function makeDeps(cleanup: ReturnType<typeof vi.fn>): FinalizeDeps {
+  return {
+    manifestStore: {
+      writeManifest: vi.fn(async () => undefined),
+    } as unknown as FinalizeDeps["manifestStore"],
+    worktreeManager: { cleanup } as unknown as FinalizeDeps["worktreeManager"],
+    store: { archive: vi.fn() } as unknown as FinalizeDeps["store"],
+    modelService: { getAgentDir: () => "/tmp/w3-test-agentdir" } as unknown as FinalizeDeps["modelService"],
+    pi: null,
+    emitUnregister: vi.fn(),
+  };
+}
+
+describe("契约⑤：run 期失败路径清理前置副作用（worktree）", () => {
+  it("record.worktreeHandle 绑定：doFinalizeRecord（finalizeFailed 执行体）调用 worktreeManager.cleanup 且传入原 handle", async () => {
+    const handle: WorktreeHandle = Object.freeze({
+      path: "/tmp/w3-test-worktree",
+      branch: "pi-sub-sa-w3-cleanup",
+      baseCommit: "deadbeef",
+      mainCwd: "/tmp/w3-test-repo",
+    });
+    const cleanup = vi.fn(async () => undefined);
+    const record = makeRecord(handle);
+    await doFinalizeRecord(makeDeps(cleanup), record, { success: false } as AgentResult, "closed", "gc");
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(cleanup).toHaveBeenCalledWith(handle);
+  });
+
+  it("无 worktree 绑定：cleanup 不被调（幂等守卫——非 worktree 任务零清理副作用）", async () => {
+    const cleanup = vi.fn(async () => undefined);
+    const record = makeRecord(undefined);
+    await doFinalizeRecord(makeDeps(cleanup), record, { success: false } as AgentResult, "closed", "gc");
+    expect(cleanup).not.toHaveBeenCalled();
+  });
+
+  it("cleanup 抛错不阻断收尾链（best-effort：manifest/emitUnregister 仍执行）", async () => {
+    const handle: WorktreeHandle = Object.freeze({
+      path: "/tmp/w3-test-worktree",
+      branch: "pi-sub-sa-w3-cleanup",
+      baseCommit: "deadbeef",
+      mainCwd: "/tmp/w3-test-repo",
+    });
+    const emitUnregister = vi.fn();
+    const cleanup = vi.fn(async () => {
+      throw new Error("git worktree remove failed (simulated)");
+    });
+    const record = makeRecord(handle);
+    await doFinalizeRecord(
+      { ...makeDeps(cleanup), emitUnregister },
+      record,
+      { success: false } as AgentResult,
+      "closed",
+      "gc",
+    );
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(emitUnregister).toHaveBeenCalledWith("sa-w3-cleanup", "closed");
+  });
+});