@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/orchestration/models/__tests__/trace.test.ts

@@ -1,408 +0,0 @@
-// 测试框架：vitest
-// 运行命令：npx vitest run src/orchestration/models/__tests__/trace.test.ts
-//
-// Trace 首个直接单测（W1TC1-W1TC12，.cw/swf-perf-impl/rt-w1-design.json）：
-// - W1TC1-3/9：byIndex 倒排索引一致性与 no-op 防御语义
-// - W1TC4-8：result.content 裁剪（append/update 入口、8000 边界、patch 缺省、fromArray 原样保留）
-// - W1TC10-11：集成——executeAgentCall 真链路 / jsonl save-load round-trip
-// - W1TC12：重复 stepIndex 违规语义锚定（last-wins + remove 后 desync 孤儿）
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-import { TRACE_RESULT_MAX_CHARS, Trace } from "../trace.js";
-import { AgentCall } from "../agent-call.js";
-import { Budget } from "../budget.js";
-import { WorkflowRun } from "../workflow-run.js";
-import type { ExecutionTraceNode, AgentResult, RunSpec } from "../types.js";
-import type { AgentRunner } from "../ports.js";
-import { executeAgentCall } from "../../execute-agent-call.js";
-import { JsonlRunStore } from "../../jsonl-run-store.js";
-
-// ── 测试辅助 ─────────────────────────────────────────────────
-
-/** 构造最小 ExecutionTraceNode（status 默认 pending，无 result）。 */
-function makeTraceNode(stepIndex: number): ExecutionTraceNode {
-  return {
-    stepIndex,
-    agent: "test-agent",
-    task: "test task",
-    model: "default",
-    status: "pending",
-  };
-}
-
-/** 构造指定长度 content 的 AgentResult（sessionId 等可选字段透传）。 */
-function makeResult(content: string, extras: Partial<AgentResult> = {}): AgentResult {
-  return { content, ...extras };
-}
-
-// ── byIndex 索引一致性 ────────────────────────────────────────
-
-describe("Trace byIndex 索引一致性", () => {
-  it("W1TC1: append/update/remove 后 find 命中且引用共享", () => {
-    const trace = new Trace();
-    const node0 = makeTraceNode(0);
-    const node1 = makeTraceNode(1);
-    const node2 = makeTraceNode(2);
-    trace.append(node0);
-    trace.append(node1);
-    trace.append(node2);
-
-    trace.update(1, { status: "completed" });
-
-    // byIndex 与 nodes 引用共享非拷贝
-    expect(trace.find(0)).toBe(node0);
-    expect(trace.find(1)).toBe(node1);
-    expect(trace.find(2)).toBe(node2);
-    // Map 值是节点引用，update 字段 mutate 可见
-    expect(trace.find(1)!.status).toBe("completed");
-
-    trace.removeByStepIndex(1);
-    expect(trace.find(1)).toBeUndefined();
-    expect(trace.length).toBe(2);
-    // 其余节点不受影响
-    expect(trace.find(0)).toBe(node0);
-    expect(trace.find(2)).toBe(node2);
-  });
-});
-
-// ── remove 后 re-append 同 stepIndex 覆盖 ─────────────────────
-
-describe("Trace remove 后 re-append 同 stepIndex", () => {
-  it("W1TC2: rebuild discard 清理后重跑重发同 callId——旧节点不再可达", () => {
-    const trace = new Trace();
-    const nodeA = makeTraceNode(0);
-    trace.append(nodeA);
-    trace.removeByStepIndex(0);
-
-    const nodeB = makeTraceNode(0);
-    trace.append(nodeB);
-
-    expect(trace.find(0)).toBe(nodeB);
-    expect(trace.toArray()).toHaveLength(1);
-    expect(trace.toArray()[0]).toBe(nodeB);
-  });
-});
-
-// ── 重复 stepIndex 违规语义锚定（W1TC12）──────────────────────
-
-describe("Trace 重复 stepIndex 违规语义锚定（W1TC12）", () => {
-  it("W1TC12: 重复 append find last-wins；重复 append 后 remove 呈 desync 孤儿", () => {
-    // ① 重复 append 同 stepIndex 且未 remove：find 返回第二个节点（Map
-    //    last-wins；旧线性扫 first-match 会返回第一个）
-    const t1 = new Trace();
-    const first = makeTraceNode(0);
-    const second = makeTraceNode(0);
-    t1.append(first);
-    t1.append(second);
-    expect(t1.find(0)).toBe(second);
-    expect(t1.length).toBe(2);
-
-    // ② 重复 append 后 removeByStepIndex：findIndex 命中首个旧节点 splice、
-    //    byIndex.delete 删掉整个键——第二个节点残留为孤儿（find 不可达但
-    //    nodes.length=1）。desync 行为锚定：防未来改回线性扫时静默漂移
-    //    （线性扫实现下 find(0) 会命中残留节点 second，本断言即失败）
-    const t2 = new Trace();
-    const a = makeTraceNode(0);
-    const b = makeTraceNode(0);
-    t2.append(a);
-    t2.append(b);
-    t2.removeByStepIndex(0);
-    expect(t2.find(0)).toBeUndefined();
-    expect(t2.length).toBe(1);
-    expect(t2.toArray()[0]).toBe(b);
-  });
-});
-
-// ── fromArray 重建 ───────────────────────────────────────────
-
-describe("Trace.fromArray 重建", () => {
-  it("W1TC3: 索引全命中 + 防御性拷贝语义保持", () => {
-    const node0 = makeTraceNode(0);
-    const node1 = makeTraceNode(1);
-    const node2 = makeTraceNode(2);
-    const src = [node0, node1, node2];
-
-    const trace = Trace.fromArray(src);
-
-    expect(trace.length).toBe(3);
-    // fromArray push {...node} 副本——find(i) 与 toArray()[i] 同引用（byIndex 命中副本）
-    for (let i = 0; i < 3; i++) {
-      expect(trace.find(i)).toBe(trace.toArray()[i]);
-    }
-
-    // 传入数组后续 mutate 不影响 trace（浅拷贝语义保持）
-    src.push(makeTraceNode(3));
-    expect(trace.length).toBe(3);
-    src[0]!.status = "failed";
-    expect(trace.find(0)!.status).toBe("pending");
-  });
-});
-
-// ── append 入口裁剪 ──────────────────────────────────────────
-
-describe("Trace append 入口超长 result 裁剪", () => {
-  it("W1TC4: 标记含原始长度，节点引用不变，其余字段浅拷贝保留", () => {
-    const content = "x".repeat(10000);
-    const node = {
-      ...makeTraceNode(0),
-      result: makeResult(content, { sessionId: "s1", parsedOutput: { a: 1 } }),
-    };
-
-    const trace = new Trace();
-    trace.append(node);
-
-    const stored = trace.toArray()[0]!;
-    // 节点对象引用不变（mutate result 字段，不 push 副本——D-10 traceNode 引用共享）
-    expect(stored).toBe(node);
-
-    const marker = `\n…[trace result truncated, original 10000 chars]…\n`;
-    expect(stored.result!.content).toBe(content.slice(0, 4000) + marker + content.slice(-4000));
-    // 头尾与标记子串
-    expect(stored.result!.content.startsWith(content.slice(0, 4000))).toBe(true);
-    expect(stored.result!.content.endsWith(content.slice(-4000))).toBe(true);
-    expect(stored.result!.content).toContain("[trace result truncated, original 10000 chars]");
-    // result 其余字段浅拷贝保留
-    expect(stored.result!.sessionId).toBe("s1");
-    expect(stored.result!.parsedOutput).toEqual({ a: 1 });
-  });
-});
-
-// ── update 入口裁剪 ──────────────────────────────────────────
-
-describe("Trace update patch.result 超长裁剪", () => {
-  it("W1TC5: 节点持裁剪副本，patch 原对象不被污染（call.result 保真）", () => {
-    const trace = new Trace();
-    trace.append(makeTraceNode(0));
-
-    const full = makeResult("y".repeat(9000), { sessionId: "s1" });
-    trace.update(0, { result: full });
-
-    const stored = trace.find(0)!.result!;
-    const marker = `\n…[trace result truncated, original 9000 chars]…\n`;
-    expect(stored.content.length).toBe(4000 + marker.length + 4000);
-    expect(stored.content).toContain("original 9000 chars");
-    // 节点持裁剪副本新对象，与 patch.result 脱钩
-    expect(stored).not.toBe(full);
-    // 浅拷贝保留其他字段
-    expect(stored.sessionId).toBe("s1");
-    // AgentCall.result 保真——原对象不被污染（replay 数据源）
-    expect(full.content).toHaveLength(9000);
-  });
-});
-
-// ── 边界：恰好 8000 不裁 / 8001 裁 ────────────────────────────
-
-describe("Trace 裁剪边界（严格大于 TRACE_RESULT_MAX_CHARS）", () => {
-  it("W1TC6: 恰好 8000 引用透传零拷贝；8001 触发裁剪", () => {
-    const trace = new Trace();
-    trace.append(makeTraceNode(0));
-    trace.append(makeTraceNode(1));
-
-    // 恰好 8000：不裁
-    const exact = makeResult("a".repeat(TRACE_RESULT_MAX_CHARS));
-    trace.update(0, { result: exact });
-    expect(trace.find(0)!.result).toBe(exact);
-    expect(trace.find(0)!.result!.content).toHaveLength(8000);
-    expect(trace.find(0)!.result!.content).not.toContain("truncated");
-
-    // 8001：裁剪（head/tail 固定 4000 比例，重叠段属预期）
-    const over = makeResult("b".repeat(TRACE_RESULT_MAX_CHARS + 1));
-    trace.update(1, { result: over });
-    expect(trace.find(1)!.result!.content).toContain("original 8001 chars");
-    expect(trace.find(1)!.result!.content).not.toBe(over.content);
-  });
-});
-
-// ── patch.result 未提供不触发裁剪 ────────────────────────────
-
-describe("Trace update patch.result 缺省", () => {
-  it("W1TC7: 只改 status/completedAt 等字段——已持 result 不被触碰", () => {
-    const origResult = makeResult("keep");
-    const node = { ...makeTraceNode(0), result: origResult };
-    const trace = new Trace();
-    trace.append(node);
-
-    trace.update(0, { status: "completed", completedAt: "2026-08-15T00:00:00Z" });
-    expect(trace.find(0)!.result!.content).toBe("keep");
-    expect(trace.find(0)!.result).toBe(origResult);
-
-    // 其他字段路径同样不影响 result
-    trace.update(0, { sessionId: "s9" });
-    expect(trace.find(0)!.result).toBe(origResult);
-  });
-});
-
-// ── fromArray 原样保留（read 路径不二次裁剪）──────────────────
-
-describe("Trace.fromArray 原样保留", () => {
-  it("W1TC8: 超长 content 不被二次裁剪；已含标记的形态逐字节不变", () => {
-    // 旧版本未裁剪的快照重水合：20000 字符全长保留
-    const long = {
-      ...makeTraceNode(0),
-      result: makeResult("z".repeat(20000)),
-    };
-    const trace = Trace.fromArray([long]);
-    expect(trace.find(0)!.result!.content).toHaveLength(20000);
-    expect(trace.find(0)!.result!.content).not.toContain("truncated");
-
-    // 新快照 round-trip：已裁剪含标记的 content 经 fromArray 后逐字节不变（无标记嵌套）
-    const marker = `\n…[trace result truncated, original 10000 chars]…\n`;
-    const trimmed = "x".repeat(4000) + marker + "x".repeat(4000);
-    const trace2 = Trace.fromArray([{ ...makeTraceNode(0), result: makeResult(trimmed) }]);
-    expect(trace2.find(0)!.result!.content).toBe(trimmed);
-  });
-});
-
-// ── no-op 防御语义回归 ───────────────────────────────────────
-
-describe("Trace no-op 防御语义", () => {
-  it("W1TC9: update/remove 不存在的 stepIndex 不抛错、状态不变", () => {
-    const trace = new Trace();
-    trace.append(makeTraceNode(0));
-
-    expect(() => trace.update(999, { status: "completed" })).not.toThrow();
-    expect(() => trace.removeByStepIndex(999)).not.toThrow();
-    expect(trace.length).toBe(1);
-    expect(trace.find(999)).toBeUndefined();
-  });
-});
-
-// ── 集成：executeAgentCall 真链路（W1TC10）────────────────────
-
-describe("W1TC10: executeAgentCall 真链路——call.result 全量、trace 节点持裁剪副本", () => {
-  it("W1TC10: runner.run 返回 12000 字符 → 两形态并存（AgentCall.result 不裁）", async () => {
-    const content = "w".repeat(12000);
-    const runner: AgentRunner = {
-      run: vi.fn().mockResolvedValue(makeResult(content, { sessionId: "s1" })),
-    };
-
-    const trace = new Trace();
-    const traceNode = makeTraceNode(0);
-    trace.append(traceNode);
-    const call = new AgentCall(0, { prompt: "test task", agent: "worker" }, traceNode);
-
-    await executeAgentCall(call, runner, new Budget(), new AbortController().signal, trace);
-
-    // AgentCall.result 全量（worker cached replay 数据源保真）
-    expect(call.result!.content).toHaveLength(12000);
-    // trace 节点持裁剪副本
-    const stored = trace.find(0)!.result!;
-    const marker = `\n…[trace result truncated, original 12000 chars]…\n`;
-    expect(stored.content).toBe(content.slice(0, 4000) + marker + content.slice(-4000));
-    expect(stored.content.length).toBe(4000 + marker.length + 4000);
-    expect(stored.sessionId).toBe("s1");
-    expect(trace.find(0)!.status).toBe("completed");
-  });
-});
-
-// ── 集成：jsonl save/load round-trip（W1TC11）─────────────────
-
-describe("W1TC11: jsonl save/load round-trip——落盘裁剪形态 + 重水合不二次裁", () => {
-  let tmpDir: string;
-
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-trace-trim-test-"));
-  });
-
-  afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  function makeSpec(): RunSpec {
-    return {
-      scriptSource: "module.exports = async () => {};",
-      args: {},
-      scriptName: "test-script",
-      scriptPath: "/tmp/test.js",
-      description: "test",
-    };
-  }
-
-  /** 构造含 10000 字符 result 已完成 call 的 WorkflowRun（模式对齐 jsonl-run-store-session-file.test.ts）。 */
-  function makeRunWithDoneCall(): WorkflowRun {
-    const trace = new Trace();
-    const node = makeTraceNode(0);
-    trace.append(node);
-    const call = new AgentCall(0, { prompt: "task", agent: "worker" }, node);
-    call.markRunning();
-    // markDone 存全量 result（AgentCall.result 不裁）
-    call.markDone(makeResult("q".repeat(10000), { sessionId: "session-abc" }));
-    call.setSessionId("session-abc");
-    // trace.update 经入口裁剪——节点持裁剪副本
-    trace.update(0, {
-      status: "completed",
-      result: call.result,
-      completedAt: new Date().toISOString(),
-      sessionId: "session-abc",
-    });
-
-    return new WorkflowRun(
-      "run-trim-001",
-      makeSpec(),
-      {
-        status: "done",
-        reason: "completed",
-        budget: new Budget(),
-        calls: new Map([[0, call]]),
-        trace,
-        errorLogs: [],
-      },
-      { startedAt: new Date().toISOString(), completedAt: new Date().toISOString() },
-    );
-  }
-
-  it("W1TC11: save 落盘 trace 裁剪 + calls[].result 全量；loadAll 回读逐字节一致", async () => {
-    const entries: Array<{ type: string; customType?: string; data?: unknown }> = [];
-    const mockPi = {
-      appendEntry: vi.fn((type: string, data: unknown) => {
-        entries.push({ type: "custom", customType: type, data });
-      }),
-    };
-    const mockCtx = {
-      sessionManager: { getEntries: () => entries },
-    };
-    const store = new JsonlRunStore({
-      sessionDir: tmpDir,
-      pi: mockPi as never,
-      ctx: mockCtx as never,
-    });
-
-    const run = makeRunWithDoneCall();
-    await store.save(run);
-
-    // 读磁盘快照验证落盘形态
-    const raw = fs.readFileSync(
-      path.join(tmpDir, "workflow-state", "run-trim-001.jsonl"),
-      "utf8",
-    );
-    const snapshot = JSON.parse(raw.trim()) as {
-      state: {
-        trace: Array<{ result?: { content: string } }>;
-        calls: Array<{ result?: { content: string }; traceNode: { result?: { content: string } } }>;
-      };
-    };
-
-    // trace 投影瘦身生效：trace[0] 含标记
-    expect(snapshot.state.trace[0]!.result!.content).toContain(
-      "[trace result truncated, original 10000 chars]",
-    );
-    // calls[].traceNode 是同一裁剪后节点引用（剥 live 后的 rest），亦含标记
-    expect(snapshot.state.calls[0]!.traceNode.result!.content).toContain(
-      "[trace result truncated, original 10000 chars]",
-    );
-    // 顶层 calls[].result 字段不裁——全量 10000
-    expect(snapshot.state.calls[0]!.result!.content).toHaveLength(10000);
-
-    // loadAll 回读：fromArray 不再裁，与落盘形态逐字节一致（无标记嵌套）
-    const loaded = await store.loadAll();
-    expect(loaded).toHaveLength(1);
-    const restoredContent = loaded[0]!.state.trace.toArray()[0]!.result!.content;
-    expect(restoredContent).toBe(snapshot.state.trace[0]!.result!.content);
-    expect(restoredContent.match(/truncated/g)).toHaveLength(1);
-  });
-});

package/src/orchestration/models/agent-call.ts

@@ -1,83 +0,0 @@
-/**
- * Workflow Extension — AgentCall 实体
- *
- * 单次 agent 调用的数据 + 不变式守卫（D-12）。纯数据，无 execute 上帝方法——
- * 执行编排（重试+预算+stale 检测）在 execute-agent-call.ts 的 free function。
- *
- * - 状态机：pending → running → done（不可逆）
- * - markRunning 进入 running 并 attempts++（每次 retry 前调用）
- * - markDone(result) 进入 done 并记录结果
- * - traceNode 持有引用，但 AgentCall 不直接改其字段——trace 同步由
- * Trace.update 负责（D-10 单一来源），AgentCall 只持有引用供 executeAgentCall 读取
- *
- * 层归属：Engine。
- *
- * 参考：domain-models.md §5（字段/不变式/设计决策）。
- */
-import type { AgentCallOpts, AgentResult, ExecutionTraceNode } from "./types.ts";
-
-/** AgentCall 生命周期状态。pending→running→done，不可逆。 */
-export type AgentCallStatus = "pending" | "running" | "done";
-
-/**
- * AgentCall 实体（在 RunState.calls Map 内）。
- *
- * 不变式：
- * - status 转换严格 pending→running→done，反向抛错
- * - done 时 result 必须已设置（markDone(result) 前置保证）
- * - attempts 反映 dispatch 次数（markRunning 累加，含首次）
- * - **无 execute 方法**（D-12：执行编排由 Engine executeAgentCall 函数承担）
- */
-export class AgentCall {
-  readonly id: number;
-  readonly opts: AgentCallOpts;
-  status: AgentCallStatus = "pending";
-  attempts = 0;
-  result?: AgentResult;
- /** Pi subprocess session ID（uuidv7，G-017 归此）。 */
-  sessionId?: string;
- /** Session JSONL 绝对路径（finalizeCall 后从 result.sessionFile 填入，对齐 sessionId 模式）。 */
-  sessionFile?: string;
- /** 与 Trace 共享的节点引用（D-10 单源）。AgentCall 不直接改其字段。 */
-  readonly traceNode: ExecutionTraceNode;
-
-  constructor(id: number, opts: AgentCallOpts, traceNode: ExecutionTraceNode) {
-    this.id = id;
-    this.opts = opts;
-    this.traceNode = traceNode;
-  }
-
- /**
- * 标记进入 running 状态（dispatch 前）。attempts++（含首次）。
- * @throws 若已 done（不可重启）
- */
-  markRunning(): void {
-    if (this.status === "done") {
-      throw new Error(`AgentCall ${this.id} already done — cannot mark running`);
-    }
-    this.status = "running";
-    this.attempts += 1;
-  }
-
- /**
- * 标记完成（成功或失败均调用——result.error 区分）。
- * @throws 若当前非 running（pending 不能直接跳 done，必须先 markRunning）
- */
-  markDone(result: AgentResult): void {
-    if (this.status !== "running") {
-      throw new Error(`AgentCall ${this.id} must be running to mark done (was ${this.status})`);
-    }
-    this.result = result;
-    this.status = "done";
-  }
-
- /** 记录 pi subprocess session ID（dispatch 成功后）。 */
-  setSessionId(sessionId: string): void {
-    this.sessionId = sessionId;
-  }
-
- /** 记录 session JSONL 绝对路径（finalizeCall 后，对齐 setSessionId 模式）。 */
-  setSessionFile(sessionFile: string): void {
-    this.sessionFile = sessionFile;
-  }
-}

package/src/orchestration/models/budget.ts

@@ -1,148 +0,0 @@
-/**
- * Workflow Extension — Budget 值对象
- *
- * Token / cost 预算值对象（D-12）。纯数据 + 不变式守卫，无副作用。
- *
- * 设计：
- * - 无 onConsume 回调（值对象不应持可变回调）。
- * - soft limit 通知由 lifecycle 层 consume 后查 isSoftLimitReached 发出（职责分离）。
- * - 90% 预警用查询式 isThresholdReached（无状态，可重复查）。
- * - maxTokens===0 视为不限制（守卫，避免首个 agent 完成误判 budget_limited）。
- *
- * 层归属：Engine。
- *
- * 参考：domain-models.md §4（字段/不变式/操作）。
- */
-import type { AgentUsage } from "./types.ts";
-
-/** Soft limit：总调用数超此值发预警（FR-7，从 ConcurrencyGate 迁入）。 */
-export const SOFT_MAX_AGENTS_WARNING = 500;
-
-/**
- * Budget 加权系数（token 口径）。
- *
- * usedTokens 不再是四项原始 token 简单求和，而是加权后的「等效消耗」，
- * 反映不同 token 桶的真实计费/处理开销差异：
- * - input（非缓存新增）：首次见到、需完整处理的新内容，权重 1（基准）
- * - cacheRead（命中缓存）：读取历史，开销极低，按 1/50 折算（权重 0.02）
- * - cacheWrite（首次写入缓存）：本版本不计入 budget（权重 0）
- * - output：模型自回归生成，开销最高，权重 2
- *
- * 这避免了长 session 中 cacheRead 随轮次单调累积导致 budget 被快速烧穿的失真
- * （详见讨论：cacheRead 在 N 轮里被报 N 次，去重上下文只有一份）。
- */
-export const INPUT_WEIGHT = 1;
-export const CACHE_READ_WEIGHT = 0.02;
-export const CACHE_WRITE_WEIGHT = 0;
-export const OUTPUT_WEIGHT = 2;
-
-/**
- * Budget 值对象。
- *
- * 不变式（domain-models.md §4）：
- * - maxTokens > 0 守卫：maxTokens===0 或 undefined 视为不限制
- * - maxCost > 0 守卫：同上
- * - consume 只累加，不减；isExceeded 只读
- * - 无回调字段——所有副作用由调用方在 consume 后查询决定
- */
-export class Budget {
-  readonly maxTokens?: number;
-  readonly maxCost?: number;
-  readonly maxTimeMs?: number;
-  usedTokens = 0;
-  usedCost = 0;
- /** 总调用计数（soft limit 用，从 ConcurrencyGate.totalCallCount 迁入）。 */
-  totalCallCount = 0;
-
-  constructor(opts: {
-    maxTokens?: number;
-    maxCost?: number;
-    maxTimeMs?: number;
-    usedTokens?: number;
-    usedCost?: number;
-    totalCallCount?: number;
-  } = {}) {
-    this.maxTokens = opts.maxTokens;
-    this.maxCost = opts.maxCost;
-    this.maxTimeMs = opts.maxTimeMs;
-    this.usedTokens = opts.usedTokens ?? 0;
-    this.usedCost = opts.usedCost ?? 0;
-    this.totalCallCount = opts.totalCallCount ?? 0;
-  }
-
- /**
- * 累加一次 agent 调用的 usage（加权口径）。
- *
- * 四项 token 按各自权重（INPUT/CACHE_READ/CACHE_WRITE/OUTPUT_WEIGHT）折算后求和，
- * 而非原始 token 数直接相加。retry 间的真实消耗如实记录，避免预算被低估。
- * 详见上方权重常量的口径说明。
- */
-  consume(usage: AgentUsage): void {
-    // NaN 守卫——非有限值当 0 处理，防 usedTokens 变 NaN 导致 isExceeded() 永远 false（预算限制失效）
-    const numOrZero = (v: number | undefined): number =>
-      typeof v === "number" && Number.isFinite(v) ? v : 0;
-    this.usedTokens +=
-      numOrZero(usage.input) * INPUT_WEIGHT +
-      numOrZero(usage.output) * OUTPUT_WEIGHT +
-      numOrZero(usage.cacheRead) * CACHE_READ_WEIGHT +
-      numOrZero(usage.cacheWrite) * CACHE_WRITE_WEIGHT;
-    this.usedCost += numOrZero(usage.cost);
-  }
-
- /** 累加调用计数（每次 agent dispatch 后调用）。 */
-  incrementCallCount(): void {
-    this.totalCallCount += 1;
-  }
-
- /**
- * 是否超 token / cost 预算（FR-3）。
- *
- * maxTokens===0 或 undefined 视为不限制（守卫）；
- * maxCost===0 或 undefined 视为不限制。
- * 时间预算（maxTimeMs）不由本方法判断——它是 wall-clock 约束，需参照 startedAt，
- * 由 lifecycle 层的 scheduleTimeBudget（runWorkflow 内 setTimeout）
- * 独立调度，到期 abortRun(doneReason="time_limited")。
- */
-  isExceeded(): boolean {
-    if (this.maxTokens !== undefined && this.maxTokens > 0 && this.usedTokens >= this.maxTokens) {
-      return true;
-    }
-    return this.maxCost !== undefined && this.maxCost > 0 && this.usedCost >= this.maxCost;
-  }
-
- /**
- * 是否达到 soft limit（FR-7）。
- *
- * totalCallCount > SOFT_MAX_AGENTS_WARNING（500）。
- * 调用方（lifecycle）在 consume/incrementCallCount 后查询，
- * 命中时发通知（无状态——可重复查询）。
- */
-  isSoftLimitReached(): boolean {
-    return this.totalCallCount > SOFT_MAX_AGENTS_WARNING;
-  }
-
- /**
- * 剩余 token 预算。maxTokens 未设或 ≤0 时返回 undefined（视为不限制）。
- *
- * 嵌套 workflow() 调用时由 executeNestedWorkflow 消费：子 run 的 budgetTokens
- * 继承父 run 的剩余预算，实现父子预算隔离下的总量约束。
- */
-  remaining(): number | undefined {
-    if (this.maxTokens === undefined || this.maxTokens <= 0) return undefined;
-    return Math.max(0, this.maxTokens - this.usedTokens);
-  }
-
- /**
- * 是否达到 token 预算的给定比例阈值（如 0.9 = 90% 预警）。
- *
- * 纯查询，无状态——调用方负责去重（旧 _budgetWarningSent 语义由 lifecycle 层用
- * 外部 Set 或 once-listener 实现）。maxTokens 未设或为 0 时返回 false。
- */
-  isThresholdReached(ratio: number): boolean {
-    return (
-      this.maxTokens !== undefined &&
-      this.maxTokens > 0 &&
-      this.usedTokens >= this.maxTokens * ratio
-    );
-  }
-}