@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/engine/engines/zcode/__tests__/zcode-engine-degrade.test.ts

@@ -0,0 +1,168 @@
+// zcode-engine-degrade.test.ts —— appserver 错误分类回归门（降级链已删，仅存本主题）。
+// 2026-09 单一 app-server 形态重构删除了整条降级机制：CLI spawn 降级重跑、probe 冒烟
+// 门控、模式钉扎 env 三态均不复存在——协议漂移类错误直接上报可操作错误，不再换通道
+// 保底。原「首败漂移降级」「probe 冒烟」「env 三态」describe 随机制删除，本文件仅存
+// 错误规格表回归门：
+//   - -32603 "Model config is missing" → engine_credential_missing（共享宿主 HOME——
+//     凭据在 ZCode 桌面端管理），不换路径（第二任务仍走 app-server，create 帧计数增长）；
+//   - -32004 / -32010 → engine_run_failed 按任务失败上报（非漂移类，无 fallback 标注）。
+// 全部跑 __fixtures__/fake-appserver.mjs 子进程（scenario 注入），绝不 spawn 真 zcode.cjs。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { RunContext } from "../../../port.ts";
+import type { AgentCallOpts } from "../../../../../orchestration/models/types.ts";
+import { ZCODE_APPSERVER_GOLDEN } from "../golden-sample.ts";
+import { ZcodeEngine, type ZcodeEngineDeps } from "../zcode-engine.ts";
+
+const FAKE_CLI = fileURLToPath(new URL("./__fixtures__/fake-appserver.mjs", import.meta.url));
+const PROVIDER = "test-provider";
+
+const engines: ZcodeEngine[] = [];
+let seq = 0;
+let tmpRoot: string;
+let dataDir: string;
+let v2Path: string;
+
+function writeJson(p: string, v: unknown): void {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(v, null, 2));
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "zcode-eng-degrade-"));
+  dataDir = path.join(tmpRoot, "data");
+  v2Path = path.join(tmpRoot, "v2.json");
+  writeJson(v2Path, {
+    provider: { [PROVIDER]: { options: { apiKey: "k", baseURL: "https://t.example" }, models: { m1: {} } } },
+  });
+});
+
+afterEach(async () => {
+  for (const engine of engines.splice(0)) await engine.dispose().catch(() => undefined);
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+interface ErrorScenario {
+  /** 主连接（常驻）scenario 覆盖：create/send 阶段错误注入。 */
+  createError?: { code: number; message: string; data?: unknown };
+  sendError?: { code: number; message: string; data?: unknown };
+}
+
+/** 建一个连到 fake 的引擎（scenario 文件随 env 固化进子进程；每测试独立 state 文件）。 */
+function makeEngine(s: ErrorScenario = {}) {
+  seq += 1;
+  const stateFile = path.join(tmpRoot, `state-${seq}.jsonl`);
+  const scenarioFile = path.join(tmpRoot, `scenario-${seq}.json`);
+  const workspace = path.join(tmpRoot, `ws-${seq}`);
+  const pushes = [...ZCODE_APPSERVER_GOLDEN.pushStream, ...ZCODE_APPSERVER_GOLDEN.terminal].map((l) =>
+    typeof l === "string" ? (JSON.parse(l) as Record<string, unknown>) : l,
+  );
+  writeJson(scenarioFile, {
+    createResult: JSON.parse(ZCODE_APPSERVER_GOLDEN.createResponse),
+    readResult: JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse),
+    sendPushes: pushes,
+    ...(s.createError !== undefined ? { createError: s.createError } : {}),
+    ...(s.sendError !== undefined ? { sendError: s.sendError } : {}),
+  });
+  const deps: ZcodeEngineDeps = {
+    engineDataDir: () => dataDir,
+    cliPath: FAKE_CLI,
+    sources: { v2ConfigPath: v2Path },
+    processEnv: {
+      PATH: process.env.PATH ?? "",
+      FAKE_STATE_FILE: stateFile,
+      FAKE_SESSION_SCENARIO: scenarioFile,
+    },
+  };
+  const engine = new ZcodeEngine(deps);
+  engines.push(engine);
+  return { engine, stateFile, workspace };
+}
+
+// ── 流水读取 helpers（与 zcode-engine-appserver.test.ts 同款） ──
+
+interface StateEvent {
+  seq: number;
+  ev: string;
+  [key: string]: unknown;
+}
+
+function readState(file: string): StateEvent[] {
+  try {
+    return fs
+      .readFileSync(file, "utf8")
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as StateEvent);
+  } catch {
+    return [];
+  }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function recvFrames(stateFile: string, method: string): Array<{ id: number; params: Record<string, unknown> }> {
+  return readState(stateFile)
+    .filter((e) => e.ev === "recv")
+    .map((e) => e.frame)
+    .filter(
+      (f): f is { id: number; params: Record<string, unknown> } =>
+        isRecord(f) && f.method === method && isRecord(f.params) && typeof f.id === "number",
+    );
+}
+
+function makeTask(overrides?: Partial<AgentCallOpts>): AgentCallOpts {
+  return { prompt: "做点什么", description: "s", model: `${PROVIDER}/m1`, ...overrides };
+}
+
+function makeCtx(overrides?: Partial<RunContext>): RunContext {
+  return { taskId: "sa-degrade", poolKey: "", ...overrides };
+}
+
+// ============================================================
+// 错误分类表（非漂移类：-32603 / -32004 / -32010 不降级）
+// ============================================================
+
+describe("错误分类（错误规格表）", () => {
+  it("-32603 'Model config is missing' → engine_credential_missing，不降级（第二任务仍走 app-server）", async () => {
+    const { engine, stateFile, workspace } = makeEngine({
+      createError: { code: -32603, message: "Model config is missing" },
+    });
+    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
+    expect(r1.outcome.error).toContain("engine_credential_missing");
+    expect(r1.outcome.engineFallback).toBeUndefined();
+    const createsBefore = recvFrames(stateFile, "session/create").length;
+    const r2 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
+    expect(r2.outcome.error).toContain("engine_credential_missing");
+    expect(recvFrames(stateFile, "session/create").length).toBeGreaterThan(createsBefore);
+  }, 20_000);
+
+  it("-32004 'Session is not active' → 任务失败上报，不降级", async () => {
+    const { engine, workspace } = makeEngine({
+      createError: { code: -32004, message: "Session is not active" },
+    });
+    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
+    expect(r1.outcome.error).toContain("engine_run_failed");
+    expect(r1.outcome.error).toContain("-32004");
+    expect(r1.outcome.engineFallback).toBeUndefined();
+  }, 20_000);
+
+  it("-32010（send busy）→ 任务失败上报，不降级", async () => {
+    const { engine, workspace } = makeEngine({
+      sendError: { code: -32010, message: "A turn is already running" },
+    });
+    const r1 = await engine.run(makeTask({ cwd: workspace }), makeCtx());
+    expect(r1.outcome.error).toContain("engine_run_failed");
+    expect(r1.outcome.error).toContain("-32010");
+    expect(r1.outcome.engineFallback).toBeUndefined();
+  }, 20_000);
+});

package/src/execution/engine/engines/zcode/__tests__/zcode-engine-dispose.test.ts

@@ -0,0 +1,210 @@
+// zcode-engine-dispose.test.ts —— P0-1 U5 dispose 收割（引擎集成面，fake-appserver
+// 子进程，绝不 spawn 真 zcode.cjs）。
+//
+// 设计权威源：docs/design/timeout-zcode-turn-and-settled-watchdog.md §3.4（退化
+// 路径）、§6 D7（dispose 收割兜底）、§11 P-Z3。真实现场（真实环境的 close 吞没）
+// 归 Gate B；本文件验证引擎层可注入的集成行为：
+//   ① dispose 时在途 turn 收敛为明确失败（不挂满 turn 预算）且不触发重试轮
+//     （u-z4 disposed 标志衔接：收割 ≠ 瞬时崩溃——boot 1 / create×1 机械证据）；
+//   ② dispose 全链窗口 = HARVEST_GRACE 量级（与 awaitConnFinalized 同源常量——
+//     行为耗时断言 + 源码常量同源静态断言）。
+// channel 层 close 吞没形态的机制断言在 session-channel-dispose-harvest.test.ts
+// （mock 连接——真实子进程形态下 Node close 事件不可吞没，P-Z3 真实现场归 Gate B）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { EngineRunResult, RunContext } from "../../../port.ts";
+import type { AgentCallOpts } from "../../../../../orchestration/models/types.ts";
+import {
+  ZCODE_APPSERVER_HARVEST_GRACE_MS,
+  ZCODE_KILL_GRACE_MS,
+} from "../constants.ts";
+import { ZCODE_APPSERVER_GOLDEN } from "../golden-sample.ts";
+import { ZcodeEngine, type ZcodeEngineDeps } from "../zcode-engine.ts";
+
+const FAKE_CLI = fileURLToPath(new URL("./__fixtures__/fake-appserver.mjs", import.meta.url));
+const PROVIDER = "test-provider";
+
+const GOLDEN_SESSION_ID = "sess_golden_r3_01";
+/** 挂起场景：send 后零推送——turn 无事件无终态（dispose 收割的形态前提）。 */
+const HANG_PUSHES: string[] = [];
+
+const engines: ZcodeEngine[] = [];
+let seq = 0;
+let tmpRoot: string;
+let dataDir: string;
+let v2Path: string;
+
+function writeJson(p: string, v: unknown): void {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(v, null, 2));
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "zcode-eng-dispose-"));
+  dataDir = path.join(tmpRoot, "data");
+  v2Path = path.join(tmpRoot, "v2.json");
+  writeJson(v2Path, {
+    provider: { [PROVIDER]: { options: { apiKey: "k", baseURL: "https://t.example" }, models: { m1: {} } } },
+  });
+});
+
+afterEach(async () => {
+  vi.unstubAllEnvs();
+  for (const engine of engines.splice(0)) await engine.dispose().catch(() => undefined);
+  fs.rmSync(tmpRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+});
+
+interface EngineFixture {
+  engine: ZcodeEngine;
+  stateFile: string;
+  scenarioFile: string;
+  workspace: string;
+}
+
+function makeEngine(): EngineFixture {
+  seq += 1;
+  const stateFile = path.join(tmpRoot, `state-${seq}.jsonl`);
+  const scenarioFile = path.join(tmpRoot, `scenario-${seq}.json`);
+  const workspace = path.join(tmpRoot, `ws-${seq}`);
+  writeJson(scenarioFile, {
+    createResult: JSON.parse(ZCODE_APPSERVER_GOLDEN.createResponse),
+    readResult: JSON.parse(ZCODE_APPSERVER_GOLDEN.readResponse),
+    sendPushes: HANG_PUSHES.map((l) => JSON.parse(l) as Record<string, unknown>),
+  });
+  const deps: ZcodeEngineDeps = {
+    engineDataDir: () => dataDir,
+    cliPath: FAKE_CLI,
+    sources: { v2ConfigPath: v2Path },
+    processEnv: {
+      PATH: process.env.PATH ?? "",
+      XYZ_ZCODE_MODE: "appserver",
+      FAKE_STATE_FILE: stateFile,
+      FAKE_SESSION_SCENARIO: scenarioFile,
+    },
+  };
+  const engine = new ZcodeEngine(deps);
+  engines.push(engine);
+  return { engine, stateFile, scenarioFile, workspace };
+}
+
+// ── 流水读取 helpers（与 zcode-engine-timeout.test.ts 同款） ──
+
+interface StateEvent {
+  seq: number;
+  ev: string;
+  [key: string]: unknown;
+}
+
+function readState(file: string): StateEvent[] {
+  try {
+    return fs
+      .readFileSync(file, "utf8")
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as StateEvent);
+  } catch {
+    return [];
+  }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function sentMethods(stateFile: string): string[] {
+  return readState(stateFile)
+    .map((e) => e.frame)
+    .filter((f): f is Record<string, unknown> => isRecord(f) && typeof f.method === "string")
+    .map((f) => f.method as string);
+}
+
+function bootCount(stateFile: string): number {
+  return readState(stateFile).filter((e) => e.ev === "boot").length;
+}
+
+/** 轮询流水直到指定 method 出现（在途 turn 已挂的同步点；超时抛错防静默空转）。 */
+async function waitForMethod(stateFile: string, method: string, timeoutMs = 5000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (sentMethods(stateFile).includes(method)) return;
+    await new Promise((r) => setTimeout(r, 20));
+  }
+  throw new Error(`流水 ${timeoutMs}ms 内未出现 ${method}——在途 turn 未建立`);
+}
+
+function makeTask(overrides?: Partial<AgentCallOpts>): AgentCallOpts {
+  return { prompt: "做点什么", description: "s", model: `${PROVIDER}/m1`, ...overrides };
+}
+
+function makeCtx(overrides?: Partial<RunContext>): RunContext {
+  return { taskId: "sa-dispose", poolKey: "", ...overrides };
+}
+
+// ============================================================
+// dispose 收割（P0-1 U5/D7：在途 turn 收敛 + 不重试 + 窗口量级）
+// ============================================================
+
+describe("dispose 收割（P0-1 U5：引擎集成面）", () => {
+  it("dispose 时在途 turn 收敛为明确失败且不重试：engine_run_failed、boot 1、create×1（收割≠瞬时崩溃，u-z4 disposed 短路）", async () => {
+    // 两 timer 显式关闭（规则 19 opt-out 形态）——排除 timeout 判死路径，
+    // 本用例的失败终态只能来自 dispose 收割链（onClose failAllTurns → dispose
+    // no-op 幂等；close 吞没变体由 channel 层 mock 测试承载）
+    vi.stubEnv("XYZ_ZCODE_TURN_IDLE_TIMEOUT_MS", "0");
+    vi.stubEnv("XYZ_ZCODE_TURN_MAX_TIMEOUT_MS", "0");
+    const f = makeEngine();
+    const runPromise: Promise<EngineRunResult> = f.engine.run(makeTask({ cwd: f.workspace }), makeCtx());
+    await waitForMethod(f.stateFile, "session/send"); // 在途 turn 已建立
+
+    const disposeStartedAt = Date.now();
+    await f.engine.dispose();
+    const disposeMs = Date.now() - disposeStartedAt;
+
+    // run promise 在 dispose 窗口内落定（收割生效的结构性证据——5s 保护超时）
+    const r = await Promise.race([
+      runPromise,
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error("run promise 未在 dispose 后 5s 内落定——收割未生效")), 5000),
+      ),
+    ]);
+    expect(r.outcome.error).toMatch(/^engine_run_failed:/);
+    // 收割错误带连接层崩溃 reason（close 正常到达形态：onClose 主路径先收割）
+    expect(r.outcome.error).toContain("进程退出");
+
+    // 收割 ≠ 瞬时崩溃：无重试轮、无惰性重建（boot 1 / create×1 机械证据）
+    const methods = sentMethods(f.stateFile);
+    expect(methods.filter((m) => m === "session/create").length).toBe(1);
+    expect(bootCount(f.stateFile)).toBe(1);
+
+    // 窗口量级：dispose 全链不超 kill 链 + HARVEST_GRACE + 进程调度余量——
+    // 收割在 grace 量级窗口闭合，而非挂满 turn 预算（30min/60min 量级差异）
+    expect(disposeMs).toBeLessThan(ZCODE_KILL_GRACE_MS + ZCODE_APPSERVER_HARVEST_GRACE_MS + 2000);
+  }, 30_000);
+
+  it("grace 窗口量级一致性：dispose 收割 race 窗口与 awaitConnFinalized 同源 ZCODE_APPSERVER_HARVEST_GRACE_MS（验收⑤静态断言）", async () => {
+    const engineSrc = fs.readFileSync(
+      fileURLToPath(new URL("../zcode-engine.ts", import.meta.url)),
+      "utf8",
+    );
+    // awaitConnFinalized：close 永不到达时同量级兜底（u-z2 先例）
+    expect(engineSrc).toContain("setTimeout(() => finish(), ZCODE_APPSERVER_HARVEST_GRACE_MS)");
+    // shutdownRuntimeAndDisposeChannel：dispose 收割 race 窗口（本单元挂接点）
+    expect(engineSrc).toContain("delayResolved(ZCODE_APPSERVER_HARVEST_GRACE_MS");
+    // channel dispose 收割本体是同步操作（无自有 timer）——窗口归引擎 race 单点
+    const channelSrc = fs.readFileSync(
+      fileURLToPath(new URL("../session-channel.ts", import.meta.url)),
+      "utf8",
+    );
+    const disposeBody = channelSrc.slice(
+      channelSrc.indexOf("  dispose(): void {"),
+      channelSrc.indexOf("  /** 连接死亡收割"),
+    );
+    expect(disposeBody).not.toContain("setTimeout");
+  });
+});