@zhushanwen/subagent-core 0.8.0 → 0.9.0

package/src/execution/engine/__tests__/conformance/chat-round-protocol.test.ts

@@ -1,230 +0,0 @@
-// chat-round-protocol.test.ts —— [W6] chat 轮次协议 v1.x 增量的协议黑盒契约。
-//
-// 设计权威源：chat-domain-v1x-liveness-governance.md §3.2 D1-A + §5 W1/W6 行 +
-// 验收 A6。W1 SDK 已交付第 9 反向通道 host/roundLifecycle（settled/idle/failed
-// 三相位，关联键 runId|recordId 互斥分路）与 conversation gate 负向构造器；本套件
-// 在 conformance 层（协议客户端 × fake 引擎 CLI）钉住三条语义，供 W3 chat 改线与
-// A7 live 门回归：
-//
-//   ① roundLifecycle 三相位（settled/idle/failed）× 双关联键：数据面回执链闭合
-//      （宿主必须确认收到——fake 引擎收到帧②应答后回发 host/log "ack …" 回声，
-//      NDJSON 单连接有序保证回声先于 run 应答帧到达）；core 不误判引擎故障
-//      （run 正常 resolve + 客户端保持 ready，10s 数据面守卫不触发）。
-//   ② recordId 键 streamDelta 分路：续聊轮 delta 经 recordId 关联（D1-A 裁定，
-//      InteractParams/Result 无 runId）。[W3 接线落地] reverse-router 的 recordId
-//      分支接 EngineClient.recordRoutes 真实消费——本用例钉「宿主确认收到 +
-//      delta 投递到 recordId 注册的 chat 轮消费点 + 不误投 runId 路由」。
-//   ③ conversation gate 负向（A6）：manifest 无 conversation 位的引擎（capabilities
-//      覆写 unsupported）→ assertChatConversationSupported 同步拒——错误码
-//      engine_capability_unsupported + 恢复指引含「升级引擎包」文案契约；同一
-//      客户端的 run 域完全正常（gate 只拦 chat 面不伤 run 域）。
-//
-// 帧载荷类型权威 = W1 SDK `HostRoundLifecycleParams`（isHostRoundLifecycleParams
-// 的相位居留形状由 SDK 包内测试覆盖）；fake 引擎按该形状发帧，本套件断言消费侧。
-
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-
-import {
-  assertChatConversationSupported,
-  isHostRoundLifecycleParams,
-  type InitializeResult,
-} from "@zhushanwen/subagent-engine-sdk";
-
-import { EngineClient } from "../../client/engine-client.ts";
-
-const FIXTURE_DIR = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__", "engine-protocol");
-const FAKE_ENGINE = join(FIXTURE_DIR, "fake-engine-protocol.mjs");
-const FIXTURE = join(FIXTURE_DIR, "smoke-run.fixture.json");
-
-let dataDir: string;
-
-beforeEach(() => {
-  dataDir = mkdtempSync(join(tmpdir(), "w6-chat-round-protocol-"));
-});
-
-afterEach(() => {
-  rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
-});
-
-interface Harness {
-  client: EngineClient;
-  logs: Array<{ level: string; message: string }>;
-  streamDeltas: string[];
-  /** [W3] recordId 键 chat 轮路由捕获（续聊轮 delta 消费点）。 */
-  recordDeltas: string[];
-  recordPhases: Array<Record<string, unknown>>;
-}
-
-function makeHarness(extraEnv: Record<string, string> = {}): Harness {
-  const h: Harness = {
-    client: undefined as unknown as EngineClient,
-    logs: [],
-    streamDeltas: [],
-    recordDeltas: [],
-    recordPhases: [],
-  };
-  h.client = new EngineClient({
-    engineId: "fake",
-    command: process.execPath,
-    args: [FAKE_ENGINE],
-    hostKind: "test",
-    hostVersion: "w6-chat-round-protocol",
-    dataDir,
-    envPrefixes: [],
-    log: (p) => h.logs.push({ level: p.level, message: p.message }),
-    baseEnv: {
-      ...process.env,
-      FAKE_PROTOCOL_FIXTURE: FIXTURE,
-      ...extraEnv,
-    },
-  });
-  const unregister = h.client.registerRunRoute("run-smoke-1", {
-    onStreamDelta: (delta) => {
-      h.streamDeltas.push(delta);
-    },
-  });
-  void unregister;
-  // [W3] recordId 键 chat 轮路由（registerRecordRoute——RemoteEngine.registerChatRoundRoute
-  // 的底层实现；conformance 层直接驱动 EngineClient 面）。
-  const unregisterRecord = h.client.registerRecordRoute("rec-chat-1", {
-    onStreamDelta: (delta) => {
-      h.recordDeltas.push(delta);
-    },
-    onRoundLifecycle: (phase) => {
-      h.recordPhases.push(phase as Record<string, unknown>);
-    },
-  });
-  void unregisterRecord;
-  return h;
-}
-
-describe("[W6] host/roundLifecycle 三相位 × 双关联键（协议黑盒回执链）", () => {
-  it("settled/idle/failed 相位 × runId|recordId 键全部被宿主确认（ack 回声）且不判引擎故障", async () => {
-    const h = makeHarness({ FAKE_RUN_LIFECYCLE: "1" });
-    try {
-      await h.client.ensureConnected();
-      const result = (await h.client.request("run", {
-        runId: "run-smoke-1",
-        task: "w6 round lifecycle probe",
-        ctx: { poolKey: "shared", cwd: dataDir, model: "fake/fake-1" },
-      })) as { outcome: Record<string, unknown> };
-      void result;
-
-      // 回执链闭合：6 帧（三相位 × runId 键 "run-smoke-1" / recordId 键 "rec-chat-1"）
-      // 的帧②应答全部到达 fake 引擎并回发回声——「宿主必须确认收到」的数据面契约。
-      // 回声帧经引擎侧往返（core 帧②应答 → fake 收到 → 回发 log），晚于 run 应答
-      // 帧到达——断言轮询等待（NDJSON 单连接有序，run resolve 后毫秒级必达）。
-      await expect
-        .poll(
-          () => h.logs.map((l) => l.message).filter((m) => m.startsWith("ack roundLifecycle ")),
-          { timeout: 5_000, interval: 20 },
-        )
-        .toEqual([
-        "ack roundLifecycle run-smoke-1 settled",
-        "ack roundLifecycle run-smoke-1 idle",
-        "ack roundLifecycle run-smoke-1 failed",
-        "ack roundLifecycle rec-chat-1 settled",
-        "ack roundLifecycle rec-chat-1 idle",
-        "ack roundLifecycle rec-chat-1 failed",
-      ]);
-
-      // [W3 接线契约] recordId 键相位帧投递到 registerRecordRoute 注册的 chat 轮
-      // 消费点（settled/idle/failed 三相位按序；宿主编排层据此做交棒/挂 idle timer/
-      // 失败分诊——分发层只做键路由）。
-      await expect
-        .poll(() => h.recordPhases.map((p) => `${p.recordId}:${String(p.phase)}`), { timeout: 5_000, interval: 20 })
-        .toEqual([
-          "rec-chat-1:settled",
-          "rec-chat-1:idle",
-          "rec-chat-1:failed",
-        ]);
-
-      // 不误判引擎故障：run 正常 resolve + 客户端保持 ready（10s 数据面应答守卫
-      // 未触发杀链——roundLifecycle 是数据面回执语义，不是故障信号）。
-      expect(h.client.currentState).toBe("ready");
-
-      // failed 相位的 error{code,message} 居留形状（isHostRoundLifecycleParams
-      // 判据的 failed 分支）——fake 引擎按 W1 载荷类型构造，宿主侧对同形状自证。
-      const failedShape = {
-        runId: "run-smoke-1",
-        phase: "failed",
-        error: { code: "engine_run_failed", message: "round failed (scripted)", recovery: "retry" },
-      };
-      expect(isHostRoundLifecycleParams(failedShape)).toBe(true);
-      const malformedShape = { runId: "r", recordId: "c", phase: "settled" };
-      expect(isHostRoundLifecycleParams(malformedShape)).toBe(false);
-    } finally {
-      await h.client.dispose();
-    }
-  });
-});
-
-describe("[W6] recordId 键 streamDelta / roundLifecycle 分路（续聊轮关联键，D1-A）", () => {
-  it("recordId 键 delta：宿主确认收到（ack 回声）+ 投递到 recordId 注册的 chat 轮消费点，不误投 runId 路由", async () => {
-    const h = makeHarness({ FAKE_RUN_RECORD_DELTA: "1" });
-    try {
-      await h.client.ensureConnected();
-      await h.client.request("run", {
-        runId: "run-smoke-1",
-        task: "w6 record-key delta probe",
-        ctx: { poolKey: "shared", cwd: dataDir, model: "fake/fake-1" },
-      });
-
-      // 宿主确认收到（数据面回执闭合；回声帧晚于 run 应答到达，轮询等待）。
-      await expect
-        .poll(() => h.logs.map((l) => l.message), { timeout: 5_000, interval: 20 })
-        .toContain("ack streamDelta recordId=rec-chat-1");
-      // [W3 接线契约] recordId 键投递到 recordRoutes 注册的 chat 轮消费点
-      //（W1 偏差 #1 的 no-op 分支已替换为真实分发——reverse-router recordId 分支）。
-      expect(h.recordDeltas).toEqual(["chat-delta-not-routed-to-runId"]);
-      // 关联键分路互斥：recordId 键不误投 runId 路由（runId 键 fixture delta 不受影响）。
-      expect(h.streamDeltas).toEqual(["Hello", " world"]);
-      expect(h.client.currentState).toBe("ready");
-    } finally {
-      await h.client.dispose();
-    }
-  });
-
-});
-
-describe("[W6] conversation gate 负向（A6：无 gate 位引擎 chat 请求同步拒，run 域不受影响）", () => {
-  it("capabilities.conversation=unsupported → assertChatConversationSupported 同步拒 + 文案契约；同客户端 run 正常", async () => {
-    const h = makeHarness({ FAKE_CAPABILITIES_CONVERSATION: "unsupported" });
-    try {
-      await h.client.ensureConnected();
-      const diagnostics = h.client.getInitializeDiagnostics() as InitializeResult;
-      expect(diagnostics.capabilities.conversation).toBe("unsupported");
-
-      // W1 具名构造器（W3 chat 路由接线的判据单源）：同步拒、错误码与恢复指引
-      // 文案契约——「升级引擎包」恢复指引对齐 core capability-gate conversation
-      // 分支（错误 → 权威源 → 重试闭环）。
-      let thrown: unknown;
-      try {
-        assertChatConversationSupported("fake", diagnostics.capabilities);
-      } catch (err) {
-        thrown = err;
-      }
-      expect(thrown).toMatchObject({
-        name: "EngineSdkError",
-        code: "engine_capability_unsupported",
-      });
-      expect((thrown as Error).message).toContain("conversation");
-      expect((thrown as { recovery: string }).recovery).toContain("升级引擎包");
-
-      // A6 后半：gate 只拦 chat 面——同一客户端的 run 域完全正常。
-      const result = (await h.client.request("run", {
-        runId: "run-smoke-1",
-        task: "w6 gate-negative run-domain probe",
-        ctx: { poolKey: "shared", cwd: dataDir, model: "fake/fake-1" },
-      })) as { outcome: Record<string, unknown> };
-      expect(result.outcome).toBeDefined();
-      expect(h.client.currentState).toBe("ready");
-    } finally {
-      await h.client.dispose();
-    }
-  });
-});

package/src/execution/finalized-marker.ts

@@ -1,70 +0,0 @@
-// src/runtime/execution/finalized-marker.ts
-//
-// Finalized 状态的 sidecar 持久化。
-//
-// 背景：subagent 执行完成（done/failed）后，session.jsonl 的最终写入可能因进程
-// 异常终止而丢失。`.finalized` sidecar 标记该 session 已正常结束，collectRecords
-// 重建时可用它区分「正常结束但文件截断」与「执行中断」。
-//
-// 设计：对称 cancelled sidecar（tombstone-store.ts）。`.finalized` 内容为可选的
-// 关闭原因字符串（v8.5 起 writeFinalized 第二参数写入），旧格式为空文件——空内容
-// 表示死因不可考，磁盘重建兜底 closedReason=disconnected（不再误导为 gc）。
-// 与 `.cancelled` 互斥——一个 session 要么 finalized 要么 cancelled，不可能两者兼有。
-//
-// best-effort：写 IO 错静默，不阻断主流程。
-
-import * as fs from "node:fs";
-
-// ============================================================
-// 公开函数
-// ============================================================
-
-/**
- * 在 session.jsonl 旁写 `.finalized` sidecar。
- * best-effort：任何 I/O 错误静默（finalize 标记是次要信号，status 已在内存 record 上设好）。
- *
- * 与 `.cancelled` 互斥（BC-4）：写前删除 `.cancelled`（如存在），确保不会两者共存。
- *
- * @param sessionFile session.jsonl 绝对路径
- * @param reason 可选的 L2 关闭原因写入 sidecar 内容（v8.5 起）：磁盘重建时用它区分
- *        真实死因（user-close / parent-* 等），替代旧的「一律 gc」误导标签。传
- *        undefined = 空文件（旧格式兼容：未知死因，重建兜底 disconnected）。
- */
-export function writeFinalized(sessionFile: string, reason?: string): void {
-  try {
-    // BC-4 互斥：清理可能存在的 .cancelled。force:true 静默 ENOENT——
-    // 未 cancel 过的 session（done/failed/aborted）本就无 .cancelled，属正常路径。
-    // 此前用 unlinkSync+bestEffort 记 console.debug，取消嵌套链条时每层 ENOENT 刷屏。
-    fs.rmSync(`${sessionFile}.cancelled`, { force: true });
-    fs.writeFileSync(`${sessionFile}.finalized`, reason ?? "", "utf-8");
-  } catch (_e) {
-    void _e; // 静默：写失败不阻断 finalize 主流程。
-  }
-}
-
-/**
- * 读 session.jsonl 旁的 `.finalized` sidecar 内容携带的关闭原因。
- * 返回 trim 后的字符串：sidecar 存在时可能为空串（旧格式空文件 / 未携 reason）。
- * 返回 undefined：sidecar 不存在 / 读取失败（与空串区分「没正常结束过」）。
- */
-export function readFinalizedReason(sessionFile: string): string | undefined {
-  try {
-    return fs.readFileSync(`${sessionFile}.finalized`, "utf-8").trim();
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * 读 session.jsonl 旁的 `.finalized` sidecar 是否存在。
- * 返回 true：sidecar 存在（内容不校验，存在性即信号）。
- * 返回 false：sidecar 不存在 / 读取失败。
- */
-export function readFinalized(sessionFile: string): boolean {
-  try {
-    fs.accessSync(`${sessionFile}.finalized`);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/execution/tombstone-store.ts

@@ -1,72 +0,0 @@
-// src/runtime/execution/tombstone-store.ts
-//
-// Cancelled 状态的 sidecar 持久化。
-//
-// 背景：用户 cancel background subagent 时 session.abort() → prompt() reject →
-// session.jsonl 被中途截断（无最终 assistant message，无 stopReason 标记）。所以
-// cancelled 状态无法从 session.jsonl 可靠检测。本模块在 session.jsonl 旁写一个
-// `.cancelled` sidecar 文件（单行 JSON），collectRecords 重建时读它 override status。
-//
-// 设计：单条 cancelled = 单 sidecar，无全局 index 可损坏，无并发问题，被现有
-// session-file-gc 的目录扫描自然清理（GC 已扩展为也清理 .cancelled）。YAGNI 更重方案。
-
-import * as fs from "node:fs";
-
-// ============================================================
-// 类型
-// ============================================================
-
-/** Tombstone 内容（单行 JSON）。 */
-export interface CancelledTombstone {
-  id: string;
-  status: "cancelled";
-  agent: string;
-  startedAt: number;
-  endedAt: number;
-}
-
-// ============================================================
-// 公开函数
-// ============================================================
-
-/**
- * 在 session.jsonl 旁写 cancelled tombstone。
- * best-effort：任何 I/O 错误静默（cancel 已成功，持久化是次要的——内存 record 即将被
- * archive 淘汰，下次读靠 tombstone 标记 cancelled）。
- */
-export function writeCancelledTombstone(sessionFile: string, meta: CancelledTombstone): void {
-  try {
-    const tombstonePath = `${sessionFile}.cancelled`;
-    fs.writeFileSync(tombstonePath, `${JSON.stringify(meta)}\n`, "utf-8");
-  } catch (_e) {
-    void _e; // 静默：写失败不阻断 cancel 主流程（status 已在内存 record 上设好）。
-  }
-}
-
-/**
- * 读 session.jsonl 旁的 cancelled tombstone。
- * 返回 undefined：sidecar 不存在 / 损坏 / 解析失败。
- */
-export function readCancelledTombstone(sessionFile: string): CancelledTombstone | undefined {
-  let raw: string;
-  try {
-    raw = fs.readFileSync(`${sessionFile}.cancelled`, "utf-8");
-  } catch {
-    return undefined; // sidecar 不存在（正常——非 cancelled record 无 sidecar）。
-  }
-  try {
-    const parsed = JSON.parse(raw) as Partial<CancelledTombstone>;
-    if (
-      typeof parsed.id === "string" &&
-      parsed.status === "cancelled" &&
-      typeof parsed.agent === "string" &&
-      typeof parsed.startedAt === "number" &&
-      typeof parsed.endedAt === "number"
-    ) {
-      return parsed as CancelledTombstone;
-    }
-    return undefined; // 结构不合法 → 降级。
-  } catch {
-    return undefined; // JSON 损坏 → 降级。
-  }
-}