@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/orchestration/__tests__/file-run-store-prune.test.ts

@@ -0,0 +1,168 @@
+// file-run-store-prune.test.ts —— FileRunStore.pruneStateFilesBeyondCap 磁盘保留测试（U7/C1/D8 + OR-5 ⑥b）。
+//
+// 语义对齐 pi jsonl-run-store mtime 裁剪实现（逐段平移）：mtime 升序删最旧、
+// 只碰 wf-*.jsonl、旁路容错（任何失败不抛）。
+//
+// 覆盖（验收条款②③ + OR-5 ⑥b 默认开）：
+// - 超 cap 裁剪最旧（mtime 递增序列，剩最新的 cap 个）
+// - 未超 cap 不动
+// - envName 语义（OR-5 ⑥b 默认开）：env 未设/空 → 按默认上限 DEFAULT_STATE_MAX_RUNS
+//   裁剪（修复前「默认关」即跨 run 无界累积缺陷本身）；有效值 → 上限 = env 值；
+//   非法值（非有限数/≤0）→ 不清理（显式 opt-out 通道）
+// - 非 state 文件（不命中 glob）永不碰；目录不存在静默 no-op
+//
+// dataRoot 经 configureCore(tmp) 注入（对齐 file-run-store.test.ts 配置态隔离模式）。
+
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { configureCore, resetCoreForTests, type HostServices } from "../../core/host-services.ts";
+import { DEFAULT_STATE_MAX_RUNS, FileRunStore } from "../file-run-store.ts";
+
+const ENV_NAME = "XYZ_SUBAGENT_STATE_MAX_RUNS";
+
+let dataRoot: string;
+let store: FileRunStore;
+
+beforeEach(() => {
+  resetCoreForTests();
+  dataRoot = mkdtempSync(join(tmpdir(), "file-run-store-prune-"));
+  const host: HostServices = {
+    dataRoot: () => dataRoot,
+    log: () => {},
+  };
+  configureCore(host);
+  store = new FileRunStore();
+  delete process.env[ENV_NAME];
+});
+
+afterEach(() => {
+  resetCoreForTests();
+  rmSync(dataRoot, { recursive: true, force: true });
+  delete process.env[ENV_NAME];
+});
+
+/** 往 workflow-state 目录写 state 文件并设定 mtime（秒级间距保证严格序）。 */
+function writeStateFile(name: string, mtimeMs?: number): string {
+  const dir = join(dataRoot, "workflow-state");
+  mkdirSync(dir, { recursive: true });
+  const full = join(dir, name);
+  writeFileSync(full, `{"runId":"${name}"}\n`);
+  if (mtimeMs !== undefined) {
+    utimesSync(full, mtimeMs / 1000, mtimeMs / 1000);
+  }
+  return full;
+}
+
+/** 目录内文件名集合（断言终态）。 */
+function listDir(): string[] {
+  return readdirSync(join(dataRoot, "workflow-state")).sort();
+}
+
+/** 写 N 个 mtime 递增的 state 文件（wf-1..wf-N，mtime 间隔 1s，wf-N 最新）。 */
+function writeDatedStateFiles(n: number, baseMs: number): void {
+  for (let i = 1; i <= n; i++) {
+    writeStateFile(`wf-${i}.jsonl`, baseMs + i * 1000);
+  }
+}
+
+describe("FileRunStore.pruneStateFilesBeyondCap — max 直接裁剪", () => {
+  it("超 cap：mtime 升序删最旧，剩最新的 cap 个", async () => {
+    writeDatedStateFiles(5, 1_000_000);
+
+    await store.pruneStateFilesBeyondCap(3);
+
+    // wf-1/2 最旧先删，剩 mtime 最新的 3 个
+    expect(listDir()).toEqual(["wf-3.jsonl", "wf-4.jsonl", "wf-5.jsonl"]);
+  });
+
+  it("未超 cap：目录原样不动", async () => {
+    writeDatedStateFiles(3, 1_000_000);
+
+    await store.pruneStateFilesBeyondCap(10);
+
+    expect(listDir()).toEqual(["wf-1.jsonl", "wf-2.jsonl", "wf-3.jsonl"]);
+  });
+
+  it("恰等于 cap：no-op（边界 ≤ 判定）", async () => {
+    writeDatedStateFiles(3, 1_000_000);
+
+    await store.pruneStateFilesBeyondCap(3);
+
+    expect(listDir()).toEqual(["wf-1.jsonl", "wf-2.jsonl", "wf-3.jsonl"]);
+  });
+
+  it("只碰命中 wf-*.jsonl glob 的文件，非 state 文件永不删", async () => {
+    writeDatedStateFiles(4, 1_000_000);
+    writeStateFile("readme.txt", 900_000); // 最旧但非 state 文件
+    writeStateFile("other.jsonl", 950_000); // 不带 wf- 前缀
+
+    await store.pruneStateFilesBeyondCap(2);
+
+    // wf-1/2 被删；readme.txt 与 other.jsonl 虽更旧但不在 glob 内
+    expect(listDir()).toEqual(["other.jsonl", "readme.txt", "wf-3.jsonl", "wf-4.jsonl"]);
+  });
+
+  it("目录不存在（从未持久化）：静默 no-op 不抛", async () => {
+    await expect(store.pruneStateFilesBeyondCap(3)).resolves.toBeUndefined();
+  });
+});
+
+describe("FileRunStore.pruneStateFilesBeyondCap — envName 语义（OR-5 ⑥b 默认开）", () => {
+  it("env 未设：按默认上限 DEFAULT_STATE_MAX_RUNS 裁剪（默认开，OR-5 修复）", async () => {
+    writeDatedStateFiles(DEFAULT_STATE_MAX_RUNS + 1, 1_000_000);
+
+    await store.pruneStateFilesBeyondCap(2, ENV_NAME);
+
+    // 默认上限生效：51 → 50，最旧的 wf-1 被删（修复前此处为 no-op = 无界累积）
+    const rest = listDir();
+    expect(rest).toHaveLength(DEFAULT_STATE_MAX_RUNS);
+    expect(rest).not.toContain("wf-1.jsonl");
+    expect(rest).toContain(`wf-${DEFAULT_STATE_MAX_RUNS + 1}.jsonl`);
+  });
+
+  it("env 设空串：视同未设，按默认上限裁剪", async () => {
+    writeDatedStateFiles(DEFAULT_STATE_MAX_RUNS + 1, 1_000_000);
+    process.env[ENV_NAME] = "";
+
+    await store.pruneStateFilesBeyondCap(2, ENV_NAME);
+
+    expect(listDir()).toHaveLength(DEFAULT_STATE_MAX_RUNS);
+  });
+
+  it("env 设有效值：上限 = env 值（覆盖默认值与 max 参数）", async () => {
+    writeDatedStateFiles(5, 1_000_000);
+    process.env[ENV_NAME] = "2";
+
+    // max=4 传入但 env=2 优先 → 裁到 2
+    await store.pruneStateFilesBeyondCap(4, ENV_NAME);
+
+    expect(listDir()).toEqual(["wf-4.jsonl", "wf-5.jsonl"]);
+  });
+
+  it("env 显式非法值（非有限数 / 0 / 负数）：不清理（显式 opt-out 通道）", async () => {
+    for (const bad of ["abc", "0", "-1"]) {
+      writeDatedStateFiles(4, 1_000_000);
+      process.env[ENV_NAME] = bad;
+
+      await store.pruneStateFilesBeyondCap(2, ENV_NAME);
+
+      expect(listDir()).toEqual(["wf-1.jsonl", "wf-2.jsonl", "wf-3.jsonl", "wf-4.jsonl"]);
+      for (const f of readdirSync(join(dataRoot, "workflow-state"))) {
+        rmSync(join(dataRoot, "workflow-state", f));
+      }
+      delete process.env[ENV_NAME];
+    }
+  });
+
+  it("envName 缺省：直接按 max 裁剪（调用方自管启用时机，env 无关）", async () => {
+    writeDatedStateFiles(4, 1_000_000);
+
+    await store.pruneStateFilesBeyondCap(1);
+
+    expect(listDir()).toEqual(["wf-4.jsonl"]);
+  });
+});

package/src/orchestration/__tests__/file-run-store-throttle.test.ts

@@ -0,0 +1,168 @@
+// file-run-store-throttle.test.ts —— FileRunStore save 节流（OR-5 单 run 快照 O(n²) 修复 ⑥a）。
+//
+// 语义锁定：
+// - running 中间态：同一 runId 两次落盘间隔 < saveMinIntervalMs → 跳过 append
+//   （高频 save 落盘次数有界 = ceil(run 时长 / 间隔)）；
+// - 首写永不节流（新 run 至少一条快照，loadAll 可发现）；
+// - 终态（done）永不节流（最终状态必落盘，节流窗口内到达也不丢）；
+// - runId 之间互不影响；saveMinIntervalMs=0 = 禁用节流；
+// - 默认间隔 DEFAULT_SAVE_MIN_INTERVAL_MS = 60s。
+//
+// 时间推进用 vitest fake timers（默认 fake Date.now——save 节流判据的时间源）；
+// fs 真实 IO 不受 fake timers 影响。
+
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { configureCore, resetCoreForTests, type HostServices } from "../../core/host-services.ts";
+import { Budget } from "../models/budget.ts";
+import { Trace } from "../models/trace.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+import { DEFAULT_SAVE_MIN_INTERVAL_MS, FileRunStore } from "../file-run-store.ts";
+
+let dataRoot: string;
+
+beforeEach(() => {
+  resetCoreForTests();
+  dataRoot = mkdtempSync(join(tmpdir(), "file-run-store-throttle-"));
+  const host: HostServices = {
+    dataRoot: () => dataRoot,
+    log: () => {},
+  };
+  configureCore(host);
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  resetCoreForTests();
+  rmSync(dataRoot, { recursive: true, force: true });
+});
+
+/** 构造可持久化的 WorkflowRun（对齐 file-run-store.test.ts makeRun 模式）。 */
+function makeRun(runId: string, status: "running" | "done" = "running"): WorkflowRun {
+  return WorkflowRun.reconstruct(
+    runId,
+    {
+      scriptSource: "export function execute() { return 'ok'; }",
+      args: { topic: "demo" },
+      scriptName: "test-script",
+      scriptPath: "/fake/test.js",
+      parameters: { type: "object" },
+      budgetTokens: 1000,
+    },
+    {
+      status,
+      ...(status === "done" ? { reason: "completed" as const } : {}),
+      budget: new Budget({ maxTokens: 1000, usedTokens: 1, usedCost: 0, totalCallCount: 1 }),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+    },
+    { startedAt: "2026-09-01T00:00:00.000Z" },
+  );
+}
+
+/** 某 runId 的 state 文件行数 = 实际落盘快照次数。 */
+function snapshotLineCount(runId: string): number {
+  const content = readFileSync(join(dataRoot, "workflow-state", `${runId}.jsonl`), "utf8");
+  return content.split("\n").filter((l) => l.trim() !== "").length;
+}
+
+describe("FileRunStore save 节流（OR-5 ⑥a）", () => {
+  it("高频 running save：节流窗口内只落盘 1 次（落盘次数有界）", async () => {
+    const store = new FileRunStore({ saveMinIntervalMs: 1000 });
+    const run = makeRun("wf-throttle-1");
+
+    for (let i = 0; i < 10; i++) {
+      await store.save(run); // 不推进时间——全部命中节流窗口
+    }
+    expect(snapshotLineCount("wf-throttle-1")).toBe(1);
+  });
+
+  it("窗口过期后恢复落盘：次数 = 窗口数 + 1（首写）", async () => {
+    const store = new FileRunStore({ saveMinIntervalMs: 1000 });
+    const run = makeRun("wf-throttle-2");
+
+    await store.save(run); // 首写（窗口 0 时刻）
+    vi.advanceTimersByTime(600);
+    await store.save(run); // 窗口内：跳过
+    vi.advanceTimersByTime(400); // 累计 1000ms = 窗口到期
+    await store.save(run); // 落盘第 2 行
+    vi.advanceTimersByTime(999);
+    await store.save(run); // 差 1ms：跳过
+    expect(snapshotLineCount("wf-throttle-2")).toBe(2);
+
+    vi.advanceTimersByTime(1);
+    await store.save(run); // 恰好到期：落盘第 3 行
+    expect(snapshotLineCount("wf-throttle-2")).toBe(3);
+  });
+
+  it("终态强制落盘：节流窗口内到达的 done 不被跳过，loadAll 恢复最终状态", async () => {
+    const store = new FileRunStore({ saveMinIntervalMs: 1000 });
+    const runId = "wf-throttle-3";
+
+    await store.save(makeRun(runId, "running"));
+    vi.advanceTimersByTime(100);
+    await store.save(makeRun(runId, "running")); // 窗口内：跳过
+    expect(snapshotLineCount(runId)).toBe(1);
+
+    // 同 runId 终态到达（不推进时间——永不节流）
+    await store.save(makeRun(runId, "done"));
+    expect(snapshotLineCount(runId)).toBe(2);
+
+    const runs = await store.loadAll();
+    expect(runs).toHaveLength(1);
+    expect(runs[0]?.state.status).toBe("done");
+    expect(runs[0]?.state.reason).toBe("completed");
+  });
+
+  it("首写永不节流：新 runId 第一次 save 必落盘（loadAll 可发现）", async () => {
+    const store = new FileRunStore({ saveMinIntervalMs: 1000 });
+
+    await store.save(makeRun("wf-throttle-4"));
+    const runs = await store.loadAll();
+    expect(runs).toHaveLength(1);
+    expect(runs[0]?.runId).toBe("wf-throttle-4");
+  });
+
+  it("runId 互不影响：runA 节流窗口内 runB 正常落盘", async () => {
+    const store = new FileRunStore({ saveMinIntervalMs: 1000 });
+
+    await store.save(makeRun("wf-throttle-a"));
+    await store.save(makeRun("wf-throttle-b"));
+    await store.save(makeRun("wf-throttle-a")); // A 窗口内跳过
+    await store.save(makeRun("wf-throttle-b")); // B 窗口内跳过
+
+    expect(snapshotLineCount("wf-throttle-a")).toBe(1);
+    expect(snapshotLineCount("wf-throttle-b")).toBe(1);
+  });
+
+  it("saveMinIntervalMs=0 禁用节流：每次 save 都落盘", async () => {
+    const store = new FileRunStore({ saveMinIntervalMs: 0 });
+    const run = makeRun("wf-throttle-5");
+
+    for (let i = 0; i < 3; i++) {
+      await store.save(run);
+    }
+    expect(snapshotLineCount("wf-throttle-5")).toBe(3);
+  });
+
+  it("默认构造：间隔 = DEFAULT_SAVE_MIN_INTERVAL_MS（60s）", async () => {
+    expect(DEFAULT_SAVE_MIN_INTERVAL_MS).toBe(60_000);
+    const store = new FileRunStore(); // 缺省构造即生产形态
+    const run = makeRun("wf-throttle-6");
+
+    await store.save(run);
+    vi.advanceTimersByTime(DEFAULT_SAVE_MIN_INTERVAL_MS - 1);
+    await store.save(run);
+    expect(snapshotLineCount("wf-throttle-6")).toBe(1);
+
+    vi.advanceTimersByTime(1);
+    await store.save(run);
+    expect(snapshotLineCount("wf-throttle-6")).toBe(2);
+  });
+});