minimal-agent 0.13.0 → 0.14.0

package/plugins/workflow-runner/test/apiConcurrencyGate.test.ts

@@ -0,0 +1,104 @@
+/**
+ * plugins/workflow-runner/test/apiConcurrencyGate.test.ts —— llm() 与 agent()
+ * 共用进程级模型调度器
+ *
+ * `generate()`、`agent()`、`skill()` 都必须进入同一个进程级 model pool；测试从
+ * 统一配置读取边界，不能再复制一个常量，否则环境配置和测试会悄悄分叉。
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { LoopEvent } from '../../../src/plugin-sdk.js';
+import { createWorkflowContext } from '../src/runtime/context.js';
+import { Journal } from '../src/journal.js';
+import { readWorkflowRuntimeConfig } from '../src/runtime/config.js';
+import type { RunContext } from '../src/types.js';
+import { WorkflowState } from '../src/workflowState.js';
+
+const dirs: string[] = [];
+const MODEL_LIMIT = readWorkflowRuntimeConfig({} as NodeJS.ProcessEnv)
+  .modelConcurrency;
+afterEach(() => {
+  for (const d of dirs.splice(0)) {
+    try {
+      rmSync(d, { recursive: true, force: true, maxRetries: 3 });
+    } catch {
+      /* Windows 偶发 EBUSY；清理失败不影响断言 */
+    }
+  }
+});
+
+/** 造一套最小可跑的注入环境，chat stub 会记录任意时刻的实际并发数峰值。 */
+async function harness() {
+  const wd = mkdtempSync(join(tmpdir(), 'wf-gate-'));
+  dirs.push(wd);
+  const state = new WorkflowState(wd, 'demo', 's1');
+  await state.init({ goal: '测试目标' }, 'hash-v1', []);
+  const journal = new Journal(state.journalPath, { bundleHash: 'test', rootRunId: 'test-root' });
+  await journal.load();
+
+  let active = 0;
+  let peak = 0;
+  const chat: NonNullable<RunContext['chat']> = async function* () {
+    active++;
+    peak = Math.max(peak, active);
+    try {
+      // 强制重叠：没有这个延迟，调用可能快到彼此从不同时在场，测不出并发峰值。
+      await new Promise((r) => setTimeout(r, 15));
+      yield { type: 'text_delta' as const, delta: 'ok' };
+    } finally {
+      active--;
+    }
+  };
+
+  const events: LoopEvent[] = [];
+  const ctx = {
+    provider: { name: 'test' },
+    history: [{ role: 'system', content: 'sys' }],
+    cwd: wd,
+    tools: [],
+    chat,
+  } as unknown as RunContext;
+
+  const globals = createWorkflowContext({
+    ctx,
+    state,
+    journal,
+    emit: (ev) => events.push(ev),
+    args: {},
+    workflowName: 'demo',
+    session: 's1',
+    task: state.taskId,
+  });
+
+  return { globals, peakConcurrency: () => peak };
+}
+
+describe('generate()/agent() 共用进程级模型调度器', () => {
+  test(`★ 混合扇出 ${MODEL_LIMIT * 2} 个 generate()+agent() 调用，实际并发峰值不超过 ${MODEL_LIMIT}`, async () => {
+    const h = await harness();
+    const N = MODEL_LIMIT * 2;
+    await Promise.all(
+      Array.from({ length: N }, (_, i) =>
+        i % 2 === 0 ? h.globals.model.generate(`任务 ${i}`) : h.globals.model.agent(`任务 ${i}`),
+      ),
+    );
+    expect(h.peakConcurrency()).toBeLessThanOrEqual(MODEL_LIMIT);
+  });
+
+  test('★ 纯 llm() 扇出同样受同一把闸约束（不是只有 agent() 受限）', async () => {
+    const h = await harness();
+    const N = MODEL_LIMIT * 2;
+    await Promise.all(
+      Array.from({ length: N }, (_, i) => h.globals.model.generate(`任务 ${i}`)),
+    );
+    expect(h.peakConcurrency()).toBeLessThanOrEqual(MODEL_LIMIT);
+    // 扇出规模显著大于闸门上限时，峰值应当明显叠起来、接近上限（否则上面的
+    // 断言可能只是因为并发压根没叠起来，同样是假绿）。账本落盘等异步开销会让
+    // 各调用起跑时间略有错开，所以不强求刚好等于上限，只要求足够接近。
+    expect(h.peakConcurrency()).toBeGreaterThanOrEqual(MODEL_LIMIT - 2);
+  });
+});

package/plugins/workflow-runner/test/apiEcho.test.ts

@@ -0,0 +1,210 @@
+/**
+ * plugins/workflow-runner/test/apiEcho.test.ts —— echo() 必须真正进对话历史
+ *
+ * 这是实测出来的行为缺陷，不是理论风险：
+ *
+ * 宿主把 `text` 事件当**流式预览**——TUI 累进 LiveArea、Desktop 累进
+ * `streamingText`——而预览在 `turn_done` 时被 `clearLive()` 清掉。只有
+ * `assistant_message` 才会落进 `history` / `setMessages`。
+ *
+ * 于是一条纯确定性工作流（只有 echo、没有 llm/agent）跑完之后，对话历史里只剩
+ * 用户那句 `/workflow xxx`，助手侧一片空白 —— 用户完全看不出发生过什么。
+ * 有 llm 的工作流更糟：中间 agent 的碎话留下了，`echo()` 写的最终结论反而没了。
+ *
+ * 更早的 `echo` 注释白纸黑字写着「进 MessageList」，而实现只发 `text` ——
+ * 注释宣称了、实现没做到，正是最容易再次退化的那类。这个文件把它钉死。
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { LoopEvent, Message } from '../../../src/plugin-sdk.js';
+import { createWorkflowContext } from '../src/runtime/context.js';
+import { Journal } from '../src/journal.js';
+import type { RunContext } from '../src/types.js';
+import { WorkflowState } from '../src/workflowState.js';
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) {
+    try {
+      rmSync(d, { recursive: true, force: true, maxRetries: 3 });
+    } catch {
+      /* Windows 偶发 EBUSY；清理失败不影响断言 */
+    }
+  }
+});
+
+async function harness() {
+  const wd = mkdtempSync(join(tmpdir(), 'wf-echo-'));
+  dirs.push(wd);
+  const state = new WorkflowState(wd, 'demo', 's1');
+  await state.init({ goal: '测试目标' }, 'hash-v1', []);
+  const journal = new Journal(state.journalPath, { bundleHash: 'test', rootRunId: 'test-root' });
+  await journal.load();
+
+  const events: LoopEvent[] = [];
+  const history: Message[] = [{ role: 'system', content: 'sys' }];
+  const ctx = {
+    provider: { name: 'test' },
+    history,
+    cwd: wd,
+    tools: [],
+  } as unknown as RunContext;
+
+  const globals = createWorkflowContext({
+    ctx,
+    state,
+    journal,
+    emit: (ev) => events.push(ev),
+    args: {},
+    workflowName: 'demo',
+    session: 's1',
+    task: state.taskId,
+  });
+
+  return { globals, events, history };
+}
+
+describe('echo() 进历史', () => {
+  test('★ 发 assistant_message，而不只是流式 text', async () => {
+    const h = await harness();
+    h.globals.output.message('✅ 冒烟通过：2 行');
+
+    const committed = h.events.filter((e) => e.type === 'assistant_message');
+    expect(committed).toHaveLength(1);
+    expect(
+      (committed[0] as Extract<LoopEvent, { type: 'assistant_message' }>).message
+        .content,
+    ).toBe('✅ 冒烟通过：2 行');
+  });
+
+  test('★ push 进 ctx.history —— 这才是跨会话不丢的原因', async () => {
+    // Desktop 重开会话是从 history 加载的；只 emit 事件、不进 history 的话
+    // 当场看得见，一刷新就没了。
+    const h = await harness();
+    h.globals.output.message('结论 A');
+    h.globals.output.message('结论 B');
+
+    const assistant = h.history.filter((m) => m.role === 'assistant');
+    expect(assistant.map((m) => m.content)).toEqual(['结论 A', '结论 B']);
+  });
+
+  test('每条消息都有 id（宿主拿它做 React key / 去重）', async () => {
+    const h = await harness();
+    h.globals.output.message('一');
+    h.globals.output.message('二');
+
+    const ids = h.history
+      .filter((m) => m.role === 'assistant')
+      .map((m) => (m as { id?: string }).id);
+    expect(ids.every((id) => typeof id === 'string' && id.length > 0)).toBe(true);
+    expect(new Set(ids).size).toBe(2); // 不能是同一个 id
+  });
+
+  test('★ text 事件照发不误 —— -p 的 result 累的是它', async () => {
+    // print.ts 的 result 累 text delta；assistant_message 只计 num_turns、
+    // 不进 result buffer。两者并存不会重复，去掉 text 反而会让 -p 拿到空 result。
+    const h = await harness();
+    h.globals.output.message('给宿主的结论');
+
+    const texts = h.events
+      .filter((e): e is Extract<LoopEvent, { type: 'text' }> => e.type === 'text')
+      .map((e) => e.delta)
+      .join('');
+    expect(texts).toContain('给宿主的结论');
+  });
+
+  test('log() 不进历史 —— 它是状态行旁白，不是给用户的结论', async () => {
+    const h = await harness();
+    h.globals.output.progress({
+      phase: 'test',
+      status: 'update',
+      message: '正在扫描目录…',
+    });
+
+    expect(h.history.filter((m) => m.role === 'assistant')).toHaveLength(0);
+    expect(h.events.some((e) => e.type === 'assistant_message')).toBe(false);
+    expect(h.events.some((e) => e.type === 'workflow_progress')).toBe(true);
+  });
+});
+
+describe('断点续跑：快进段不得重复入历史', () => {
+  test('★ 重放前缀里的 echo 只发 text，不再 push（history 已从会话文件带着它）', async () => {
+    const wd = mkdtempSync(join(tmpdir(), 'wf-echo-resume-'));
+    dirs.push(wd);
+    const state = new WorkflowState(wd, 'demo', 's1');
+    await state.init({ goal: '测试目标' }, 'hash-v1', []);
+
+    // 第一轮：跑两个 journaled 调用，账本落两条
+    const j1 = new Journal(state.journalPath, { bundleHash: 'test', rootRunId: 'test-root' });
+    await j1.load();
+    await j1.step('tool', { a: 1 }, async () => 'r1');
+    await j1.step('tool', { a: 2 }, async () => 'r2');
+
+    // 第二轮 resume：重新载入账本，此刻处在重放前缀
+    const j2 = new Journal(state.journalPath, { bundleHash: 'test', rootRunId: 'test-root' });
+    await j2.load();
+
+    const events: LoopEvent[] = [];
+    // resume 的 history 里已经有上一轮那条 echo（会话文件带过来的）
+    const history: Message[] = [
+      { role: 'system', content: 'sys' },
+      { role: 'assistant', content: '上一轮的结论' },
+    ];
+    const globals = createWorkflowContext({
+      ctx: { provider: { name: 'test' }, history, cwd: wd, tools: [] } as unknown as RunContext,
+      state,
+      journal: j2,
+      emit: (ev) => events.push(ev),
+      args: {},
+      workflowName: 'demo',
+      session: 's1',
+      task: state.taskId,
+    });
+
+    expect(j2.replaying).toBe(true);
+    globals.output.message('上一轮的结论'); // 脚本重跑到同一行
+
+    // 文本照发（用户看得到叙述），但不再重复 push
+    expect(events.some((e) => e.type === 'text')).toBe(true);
+    expect(events.some((e) => e.type === 'assistant_message')).toBe(false);
+    expect(history.filter((m) => m.role === 'assistant')).toHaveLength(1);
+  });
+
+  test('★ 分叉之后（实跑段）恢复 push', async () => {
+    const wd = mkdtempSync(join(tmpdir(), 'wf-echo-diverge-'));
+    dirs.push(wd);
+    const state = new WorkflowState(wd, 'demo', 's1');
+    await state.init({ goal: '测试目标' }, 'hash-v1', []);
+
+    const j1 = new Journal(state.journalPath, { bundleHash: 'test', rootRunId: 'test-root' });
+    await j1.load();
+    await j1.step('tool', { a: 1 }, async () => 'r1');
+
+    const j2 = new Journal(state.journalPath, { bundleHash: 'test', rootRunId: 'test-root' });
+    await j2.load();
+    // 指纹失配 → 分叉
+    await j2.step('tool', { a: 999 }, async () => 'other');
+    expect(j2.replaying).toBe(false);
+
+    const events: LoopEvent[] = [];
+    const history: Message[] = [{ role: 'system', content: 'sys' }];
+    const globals = createWorkflowContext({
+      ctx: { provider: { name: 'test' }, history, cwd: wd, tools: [] } as unknown as RunContext,
+      state,
+      journal: j2,
+      emit: (ev) => events.push(ev),
+      args: {},
+      workflowName: 'demo',
+      session: 's1',
+      task: state.taskId,
+    });
+
+    globals.output.message('新的结论');
+    expect(events.some((e) => e.type === 'assistant_message')).toBe(true);
+    expect(history.filter((m) => m.role === 'assistant')).toHaveLength(1);
+  });
+});

package/plugins/workflow-runner/test/apiReadText.test.ts

@@ -0,0 +1,178 @@
+/**
+ * plugins/workflow-runner/test/apiReadText.test.ts —— readText / readJson
+ *
+ * 钉死一个只有端到端才暴露的 bug，根因比表面深两层：
+ *
+ *  表面：`readJson()` 对一个**完全合法**的 JSON 文件返回 `null`，
+ *       下游报「JSON 格式错误或数组为空」，而手工 `cat` + `python -m json.tool` 都没问题。
+ *
+ *  第一层：`Read` 工具的输出是**给模型看**的，每行带 `<行号><TAB>` 前缀 ——
+ *       `JSON.parse` 必然失败。（剥离正则一度还写成了箭头 `→` 而不是 TAB。）
+ *
+ *  第二层（真根因）：`Read` 在**重复读同一文件**时，会在开头插一句
+ *       「⚠️ 重复读取空转：该区间未变化，前一次 Read 结果仍然有效。」
+ *       这条只在**第二次**出现，于是同一段代码时对时错。真实触发路径：
+ *       research 阶段2 的 agent 写完 branches.json 后自己 Read 校验了一遍，
+ *       脚本随后 readJson() 就命中提示 → 解析失败 → null。
+ *
+ * 修法不是去剥这些前缀（那是在追着「给模型看的格式」跑），而是让脚本的
+ * 确定性读取**根本不走那条通道** —— 直接读文件。下面第一组就是钉这条的。
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createWorkflowContext } from '../src/runtime/context.js';
+import { Journal } from '../src/journal.js';
+import type { RunContext } from '../src/types.js';
+import type { WorkflowState } from '../src/workflowState.js';
+import type { WorkflowContext } from '../src/workflowContext.js';
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) {
+    try {
+      rmSync(d, { recursive: true, force: true, maxRetries: 3 });
+    } catch {
+      /* Windows 偶发 EBUSY，清理失败不影响断言 */
+    }
+  }
+});
+
+function workdir(): string {
+  const d = mkdtempSync(join(tmpdir(), 'wf-readtext-'));
+  dirs.push(d);
+  return d;
+}
+
+/** 造一份最小 globals，cwd 指向临时目录。 */
+function makeGlobals(cwd: string, workflowDir?: string) {
+  const ctx = {
+    provider: { name: 'test' },
+    cwd,
+    history: [],
+    tools: [],
+  } as unknown as RunContext;
+
+  return createWorkflowContext({
+    ctx,
+    state: {
+      appendProgress: async () => undefined,
+    } as unknown as WorkflowState,
+    journal: new Journal(join(cwd, 'journal.jsonl'), { bundleHash: 'test', rootRunId: 'test-root' }),
+    emit: () => undefined,
+    args: {},
+    workflowName: 'demo',
+    session: 's',
+    task: 't',
+    workflowDir,
+  });
+}
+
+const readTextOf = (g: WorkflowContext) =>
+  g.fs.readText as (p: string) => Promise<string | null>;
+const readJsonOf = (g: WorkflowContext) =>
+  g.fs.readJson as (p: string) => Promise<unknown>;
+
+describe('readText', () => {
+  test('返回**纯**文件内容 —— 没有行号、没有任何提示前缀', async () => {
+    const wd = workdir();
+    writeFileSync(join(wd, 'a.txt'), 'hello\nworld\n', 'utf8');
+    expect(await readTextOf(makeGlobals(wd))('a.txt')).toBe('hello\nworld\n');
+  });
+
+  test('★ 连读三次内容完全一致 —— 「重复读取」提示绝不能混进来', async () => {
+    // 这是真根因那一条。走 Read 工具的话，第二次开头会多一句
+    // 「⚠️ 重复读取空转…」，于是第一次能 parse、第二次就 null。
+    const wd = workdir();
+    writeFileSync(join(wd, 'x.json'), '{"a":1}', 'utf8');
+    const readText = readTextOf(makeGlobals(wd));
+    const a = await readText('x.json');
+    const b = await readText('x.json');
+    const c = await readText('x.json');
+    expect(a).toBe('{"a":1}');
+    expect(b).toBe(a);
+    expect(c).toBe(a);
+  });
+
+  test('相对路径基于工作流 cwd 解析', async () => {
+    const wd = workdir();
+    mkdirSync(join(wd, 'sub'), { recursive: true });
+    writeFileSync(join(wd, 'sub', 'p.md'), '内容', 'utf8');
+    expect(await readTextOf(makeGlobals(wd))('sub/p.md')).toBe('内容');
+  });
+
+  test('绝对路径原样使用', async () => {
+    const wd = workdir();
+    const abs = join(wd, 'abs.txt');
+    writeFileSync(abs, 'ok', 'utf8');
+    expect(await readTextOf(makeGlobals(workdir()))(abs)).toBe('ok');
+  });
+
+  test('Desktop 工作目录不在包内时仍能读取工作流随附资源', async () => {
+    const cwd = workdir();
+    const packageRoot = workdir();
+    const workflowDir = join(packageRoot, 'workflows', 'demo');
+    mkdirSync(join(workflowDir, 'prompts'), { recursive: true });
+    writeFileSync(join(workflowDir, 'prompts', 'step.md'), 'bundled prompt', 'utf8');
+    const readText = readTextOf(makeGlobals(cwd, workflowDir));
+    expect(await readText('workflows/demo/prompts/step.md')).toBe('bundled prompt');
+  });
+
+  test('读不到返回 null，不抛', async () => {
+    expect(await readTextOf(makeGlobals(workdir()))('nope.txt')).toBeNull();
+  });
+});
+
+describe('readJson', () => {
+  test('合法 JSON 解析成功', async () => {
+    const wd = workdir();
+    writeFileSync(join(wd, 'b.json'), '[{"a":1},{"b":2}]', 'utf8');
+    expect(await readJsonOf(makeGlobals(wd))('b.json')).toEqual([
+      { a: 1 },
+      { b: 2 },
+    ]);
+  });
+
+  test('★ 连读三次都解析成功 —— 端到端炸在这里', async () => {
+    // research 的真实失败：阶段2 的 agent 自己 Read 过 branches.json，
+    // 脚本再 readJson 就成了「第二次」，静默返回 null。
+    const wd = workdir();
+    writeFileSync(
+      join(wd, 'branches.json'),
+      '[{"name":"甲"},{"name":"乙"}]',
+      'utf8',
+    );
+    const readJson = readJsonOf(makeGlobals(wd));
+    for (let i = 1; i <= 3; i++) {
+      const v = (await readJson('branches.json')) as unknown[];
+      expect(Array.isArray(v)).toBe(true);
+      expect(v).toHaveLength(2);
+    }
+  });
+
+  test('多行带缩进的 JSON（真实文件的样子）', async () => {
+    const wd = workdir();
+    writeFileSync(
+      join(wd, 'c.json'),
+      '[\n  {\n    "name": "js-yaml（默认推荐）",\n    "safe_name": "js-yaml"\n  }\n]\n',
+      'utf8',
+    );
+    const v = (await readJsonOf(makeGlobals(wd))('c.json')) as {
+      name: string;
+    }[];
+    expect(v[0].name).toBe('js-yaml（默认推荐）');
+  });
+
+  test('内容不是 JSON → null（不抛，让脚本自己决定怎么办）', async () => {
+    const wd = workdir();
+    writeFileSync(join(wd, 'd.json'), '这不是 JSON', 'utf8');
+    expect(await readJsonOf(makeGlobals(wd))('d.json')).toBeNull();
+  });
+
+  test('读不到 → null', async () => {
+    expect(await readJsonOf(makeGlobals(workdir()))('nope.json')).toBeNull();
+  });
+});

package/plugins/workflow-runner/test/apiResourceLedger.test.ts

@@ -0,0 +1,184 @@
+/**
+ * plugins/workflow-runner/test/apiResourceLedger.test.ts —— 资源账本与重放安全
+ *
+ * 守两件事：
+ *  1. 每次 `agent()` / `llm()` 的用量真的记进 `ctx.resourceLedger`（预算闸的刻度）。
+ *  2. **断点续跑重放时不重复记账** —— 这是最容易写错、也最难发现的一条：
+ *     记账代码若挪到 `journaled()` 回调外面，每 resume 一次就把历史用量再加一遍，
+ *     跑几次之后预算凭空耗尽，而现场看起来一切正常。
+ *
+ * 用 DI 注入 chat stub（本仓库纪律：不用 mock.module，它会全局泄漏）。
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { LoopEvent } from '../../../src/plugin-sdk.js';
+import { createWorkflowContext } from '../src/runtime/context.js';
+import { Journal } from '../src/journal.js';
+import type { RunContext } from '../src/types.js';
+import { WorkflowState } from '../src/workflowState.js';
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) {
+    try {
+      rmSync(d, { recursive: true, force: true, maxRetries: 3 });
+    } catch {
+      /* Windows 偶发 EBUSY */
+    }
+  }
+});
+
+/** 每次调用都回报固定用量的 chat stub。 */
+function chatReporting(inputTokens: number, outputTokens: number) {
+  return async function* () {
+    yield { type: 'text_delta' as const, delta: '做完了' };
+    yield { type: 'done' as const, stopReason: 'stop' as const, promptTokens: inputTokens, outputTokens };
+  };
+}
+
+/** 完全不回报 usage 的 chat stub（很多兼容 provider 就是这样）。 */
+function chatSilent() {
+  return async function* () {
+    yield { type: 'text_delta' as const, delta: '做完了' };
+    yield { type: 'done' as const, stopReason: 'stop' as const };
+  };
+}
+
+async function harness(chat: RunContext['chat'], opts: { workDir?: string } = {}) {
+  const wd = opts.workDir ?? mkdtempSync(join(tmpdir(), 'wf-ledger-'));
+  if (!opts.workDir) dirs.push(wd);
+  const state = new WorkflowState(wd, 'demo', 's1');
+  await state.init({ goal: '账本测试' }, 'hash-v1', []);
+  const journal = new Journal(state.journalPath, { bundleHash: 'test', rootRunId: 'test-root' });
+  await journal.load();
+
+  const events: LoopEvent[] = [];
+  const ctx = {
+    provider: { name: 'test' },
+    history: [{ role: 'system', content: 'sys' }],
+    cwd: wd,
+    tools: [],
+    chat,
+  } as unknown as RunContext;
+
+  const globals = createWorkflowContext({
+    ctx, state, journal,
+    emit: (ev) => events.push(ev),
+    args: {}, workflowName: 'demo', session: 's1', task: state.taskId,
+  });
+
+  return { globals, ctx, events, workDir: wd };
+}
+
+describe('资源账本', () => {
+  test('★ agent() 的用量记进 ctx.resourceLedger', async () => {
+    const h = await harness(chatReporting(500, 60));
+    await h.globals.model.agent('干点什么');
+
+    expect(h.ctx.resourceLedger?.inputTokens).toBe(500);
+    expect(h.ctx.resourceLedger?.outputTokens).toBe(60);
+    expect(h.ctx.resourceLedger?.trustworthy).toBe(true);
+  });
+
+  test('★ 多次调用累计', async () => {
+    const h = await harness(chatReporting(100, 10));
+    await h.globals.model.agent('第一件事');
+    await h.globals.model.agent('第二件事');
+    await h.globals.model.generate('顺便总结一下');
+
+    expect(h.ctx.resourceLedger?.inputTokens).toBe(300);
+    expect(h.ctx.resourceLedger?.outputTokens).toBe(30);
+  });
+
+  test('★ provider 不报 usage → trustworthy 拉黑，而不是假装花了 0', async () => {
+    const h = await harness(chatSilent());
+    await h.globals.model.agent('干点什么');
+
+    // 记 0 是事实（不知道），但必须让消费方知道这份账偏低 ——
+    // 否则预算闸会拿着一份永远为 0 的账本一路放行。
+    expect(h.ctx.resourceLedger?.trustworthy).toBe(false);
+  });
+
+  test('★★ 重放不重复记账 —— 记账必须待在 journaled 回调内部', async () => {
+    // 第一次跑：真实执行，写账本 + 记用量。
+    const first = await harness(chatReporting(1_000, 100));
+    await first.globals.model.agent('唯一的一次调用');
+    expect(first.ctx.resourceLedger?.inputTokens).toBe(1_000);
+
+    // 第二次跑：**同一个工作目录**，账本命中重放。
+    // journal.step 命中时直接 return prev.result，根本不调 run() ——
+    // 所以只要记账在回调内部，重放就天然不会重复计。
+    const second = await harness(chatReporting(1_000, 100), { workDir: first.workDir });
+    await second.globals.model.agent('唯一的一次调用');
+
+    // 重放这一次没有真的发请求，也就不该记账。
+    // 若把 recordCallUsage 挪到 journaled 外面，这里会变成 1_000（重复计一遍）。
+    expect(second.ctx.resourceLedger?.inputTokens ?? 0).toBe(0);
+  });
+
+  test('重放之后新增的调用照常记账 —— 不能因为重放过就整体哑火', async () => {
+    const first = await harness(chatReporting(200, 20));
+    await first.globals.model.agent('第一步');
+
+    const second = await harness(chatReporting(200, 20), { workDir: first.workDir });
+    await second.globals.model.agent('第一步');   // 命中重放，不记
+    await second.globals.model.agent('第二步');   // 新调用，真跑，要记
+
+    expect(second.ctx.resourceLedger?.inputTokens).toBe(200);
+  });
+});
+
+/**
+ * ── 预算闸的语义边界（用户决策的硬约束）───────────────────────────────
+ *
+ * 产品决策原话：「一轮对话一旦开始，过程中即使到额度了只要 TAOR 循环不结束
+ * 也不停止不检查预算…比起严格限制预算，我更重视让 agent 把一次对话完成不打断，
+ * 至少做完到一个节点。」
+ *
+ * 所以这里既要证明 `budget()` 能报数，也要**反证**它不会打断执行 ——
+ * 后者是容易在后续重构中被「顺手加个检查」破坏的那一半。
+ */
+describe('budget() 的语义边界', () => {
+  test('没设上限时 remaining 是 Infinity、exhausted 为 false', async () => {
+    const h = await harness(chatReporting(10_000, 1_000));
+    await h.globals.model.agent('花点钱');
+    const b = (await h.globals.state.budget()) as Record<string, unknown>;
+
+    // ⚠️ 用 0 表示「无限」会让没设预算的运行被判成「一开始就超了」，一轮都跑不了。
+    expect(b.limit).toBeNull();
+    expect(b.remaining).toBe(Number.POSITIVE_INFINITY);
+    expect(b.exhausted).toBe(false);
+    expect(b.used).toBe(11_000);
+  });
+
+  test('★ 反证：超预算**不会**中断进行中的 TAOR 循环', async () => {
+    // 造一个「一轮里连调两次」的场景。即使第一次就把预算花超，
+    // 第二次调用照样必须完成 —— 引擎内核不做任何预算检查，
+    // 停不停由脚本在**下一轮开头**自己决定。
+    const h = await harness(chatReporting(1_000_000, 1_000_000));
+    h.ctx.resourceLedger = {
+      inputTokens: 0, outputTokens: 0, limit: 1, trustworthy: true,
+    };
+
+    await h.globals.model.agent('第一次调用，一次就爆预算');
+    const mid = (await h.globals.state.budget()) as Record<string, unknown>;
+    expect(mid.exhausted).toBe(true);
+
+    // 关键断言：已经 exhausted 了，agent() 仍然正常执行并返回，不抛不挂。
+    const out = await h.globals.model.agent('第二次调用，预算已爆但必须跑完');
+    expect(typeof out).toBe('string');
+    expect(out).toContain('做完了');
+  });
+
+  test('trustworthy 会跟着账本一起透出，供脚本如实告知用户', async () => {
+    const h = await harness(chatSilent());
+    await h.globals.model.agent('provider 不报 usage');
+    const b = (await h.globals.state.budget()) as Record<string, unknown>;
+
+    expect(b.trustworthy).toBe(false);
+  });
+});