Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

40.7 KB
Raw Blame
import { describe, expect, it } from 'vitest';

import { ToolLoopGuard, classifyToolContractError, type ToolLoopGuardVerdict } from './loop-guard.js';

/** 喂一次完整 tool_use → tool_result, 返回 guard 判定。id 唯一即可。 */
function feed(
  guard: ToolLoopGuard,
  id: string,
  name: string,
  input: unknown,
  output: string,
  isError = false,
  toolResultBatchId?: string,
): ToolLoopGuardVerdict {
  guard.onToolUse(id, name, input);
  return guard.onToolResult(id, output, isError, toolResultBatchId);
}

describe('ToolLoopGuard', () => {
  it.each([6, 20])('detects long stable read rotations with %i distinct calls', (distinct) => {
    const guard = new ToolLoopGuard();
    for (let i = 0; i < 128; i++) {
      const position = i % distinct;
      const verdict = feed(guard, String(i), 'grep', { pattern: `symbol-${position}` }, `file-${position}: match`);
      expect(verdict.kind).toBe(i === 127 ? 'hard' : 'ok');
      if (i === 127) expect(verdict).toMatchObject({ reason: 'rotation', count: 128 });
    }
  });

  it('does not treat changed read results or intervening writes as a stable rotation', () => {
    for (const mode of ['changing-output', 'write', 'new-input'] as const) {
      const guard = new ToolLoopGuard();
      for (let i = 0; i < 512; i++) {
        if (mode === 'write' && i % 64 === 0) {
          expect(feed(guard, `write-${i}`, 'edit', { file: `file-${i}` }, 'updated').kind).toBe('ok');
        }
        const input = { pattern: `symbol-${mode === 'new-input' ? i : i % 20}` };
        const output = `match-${mode === 'changing-output' ? i : i % 20}`;
        expect(feed(guard, `read-${i}`, 'grep', input, output).kind).toBe('ok');
      }
    }
  });

  it('detects a stale search cycle despite occasional output reordering', () => {
    const guard = new ToolLoopGuard();
    let verdict: ToolLoopGuardVerdict = { kind: 'ok' };
    for (let i = 0; i < 128; i++) {
      verdict = feed(guard, String(i), 'find', { pattern: `file-${i % 20}` },
        i % 25 === 0 ? `reordered-${i}` : `match-${i % 20}`);
    }
    expect(verdict).toMatchObject({ kind: 'hard', reason: 'rotation', count: 128 });
  });

  it('does not interrupt investigations regularly discovering new inputs', () => {
    const guard = new ToolLoopGuard();
    for (let i = 0; i < 512; i++) {
      const position = i % 8 === 0 ? `new-${i}` : `known-${i % 20}`;
      expect(feed(guard, String(i), 'grep', { pattern: position }, position).kind).toBe('ok');
    }
  });

  it.each(['write_stdin', 'wait', 'sleep', 'subagent', 'collab:wait'])('keeps %s polling out of loop fingerprints', (name) => {
    const guard = new ToolLoopGuard();
    for (let i = 0; i < 150; i++) {
      expect(feed(guard, String(i), name, { action: 'status' }, 'running').kind).toBe('ok');
    }
  });

  it('does not let collab waits erase ordinary repeated calls', () => {
    const guard = new ToolLoopGuard();
    for (let i = 0; i < 4; i++) {
      expect(feed(guard, `wait-${i}`, 'collab:wait', {
        senderThreadId: 'parent', receiverThreadIds: [],
      }, 'completed')).toEqual({ kind: 'ok' });
      const verdict = feed(guard, `read-${i}`, 'read', { path: 'same.ts' }, 'unchanged');
      if (i < 3) expect(verdict.kind).toBe('ok');
      else expect(verdict).toMatchObject({ kind: 'hard', reason: 'consecutive', count: 4 });
    }
  });

  it.each(['collab:spawnAgent', 'collab:sendInput', 'collab:resumeAgent', 'collab:closeAgent'])(
    'still detects repeated non-wait collaboration calls: %s', (name) => {
      const guard = new ToolLoopGuard();
      let verdict: ToolLoopGuardVerdict = { kind: 'ok' };
      for (let i = 0; i < 4; i++) {
        verdict = feed(guard, String(i), name, { senderThreadId: 'parent', receiverThreadIds: ['child'] }, 'completed');
      }
      expect(verdict).toMatchObject({ kind: 'hard', reason: 'consecutive', count: 4 });
    },
  );

  it('resets long read evidence on a new turn', () => {
    const guard = new ToolLoopGuard();
    for (let turn = 0; turn < 3; turn++) {
      guard.resetTurn();
      for (let i = 0; i < 100; i++) {
        expect(feed(guard, `${turn}-${i}`, 'find', { pattern: `file-${i % 20}` }, `file-${i % 20}`).kind).toBe('ok');
      }
    }
  });

  it.each(['exec', 'Bash', 'bash'])('keeps successful log-tail polling alive through %s', (name) => {
    const guard = new ToolLoopGuard();
    const script = 'tail -8 /tmp/unit-gate.log; tail -5 /tmp/publish-gate.log';
    // Sanitized shape from a completed quota-fix task waiting on the unit gate.
    const command = name === 'exec' ? `/bin/zsh -lc '${script}'` : script;
    for (let i = 0; i < 150; i++) {
      expect(feed(guard, String(i), name, { command }, 'another unit gate is running').kind).toBe('ok');
    }
  });

  it.each([
    ['powershell', String.raw`Get-Content -Tail 8 C:\logs\gate.log`],
    ['powershell', String.raw`Get-Content -LiteralPath 'C:\Build Logs\gate.log' -Tail 8`],
    ['exec', String.raw`Get-Content -Tail 8 -Path C:\logs\gate.log; Get-Content C:\logs\other.log -Tail 5`],
    ['exec', String.raw`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -Command "Get-Content -Tail 8 C:\logs\gate.log"`],
    ['exec', String.raw`"C:\Program Files\PowerShell\7\pwsh.exe" -Command "get-content -literalpath C:\logs\gate.log -tail 8"`],
  ])('keeps Windows log polling alive through %s', (name, command) => {
    const guard = new ToolLoopGuard();
    for (let i = 0; i < 150; i++) {
      expect(feed(guard, String(i), name, { command }, 'waiting for test gate').kind).toBe('ok');
    }
  });

  it.each([
    String.raw`Get-Content C:\src\source.ts -Tail 8`,
    String.raw`Get-Content C:\logs\gate.log`,
    String.raw`Get-Content C:\logs\gate.log -Tail 8; npm test`,
    String.raw`Get-Content C:\logs\gate.log -Tail 8 > C:\logs\out.log`,
    String.raw`Get-Content "$env:TEMP\gate.log" -Tail 8`,
    String.raw`Get-Content C:\logs\gate.log -Tail 8 | Select-String failed`,
  ])('does not exempt ambiguous or mixed PowerShell: %s', (command) => {
    const guard = new ToolLoopGuard();
    let verdict: ToolLoopGuardVerdict = { kind: 'ok' };
    for (let i = 0; i < 4; i++) verdict = feed(guard, String(i), 'powershell', { command }, 'unchanged');
    expect(verdict.kind).toBe('hard');
  });

  it('keeps failing PowerShell log reads in the repeat detector', () => {
    const guard = new ToolLoopGuard();
    let verdict: ToolLoopGuardVerdict = { kind: 'ok' };
    for (let i = 0; i < 4; i++) verdict = feed(guard, String(i), 'powershell',
      { command: String.raw`Get-Content C:\logs\gate.log -Tail 8` }, 'file not found', true);
    expect(verdict.kind).toBe('hard');
  });

  it.each([
    'tail -8 source.ts',
    'tail -8 /tmp/gate.log; npm test',
    'tail -8 /tmp/gate.log > /tmp/output.log',
    'tail -8 $(pwd)/gate.log',
    'tail -8 /tmp/gate.log | grep failed',
  ])('does not exempt an ambiguous or mixed shell command: %s', (command) => {
    const guard = new ToolLoopGuard();
    let verdict: ToolLoopGuardVerdict = { kind: 'ok' };
    for (let i = 0; i < 4; i++) verdict = feed(guard, String(i), 'exec', { command }, 'unchanged');
    expect(verdict.kind).toBe('hard');
  });

  it('does not exempt failing log polls or erase ordinary loops between successful polls', () => {
    const failed = new ToolLoopGuard();
    const ordinary = new ToolLoopGuard();
    for (let i = 0; i < 4; i++) {
      const failure = feed(failed, String(i), 'bash', { command: 'tail -8 /tmp/gate.log' }, 'not found', true);
      const read = feed(ordinary, `read-${i}`, 'read', { path: 'source.ts' }, 'same source');
      expect(failure.kind).toBe(i === 3 ? 'hard' : 'ok');
      expect(read.kind).toBe(i === 3 ? 'hard' : 'ok');
      expect(feed(ordinary, `poll-${i}`, 'exec', { command: 'tail -8 /tmp/gate.log' }, 'waiting').kind).toBe('ok');
    }
  });

  // ── 第 1 层: 连续 name+input+output 完全相同 ──────────────────────────────
  it('在连续完全相同达到阈值时判 consecutive', () => {
    const g = new ToolLoopGuard(); // consecutiveLimit 默认 4
    for (let i = 0; i < 3; i += 1) {
      expect(feed(g, `id${i}`, 'Bash', { cmd: 'ls' }, 'out').kind).toBe('ok');
    }
    expect(feed(g, 'id3', 'Bash', { cmd: 'ls' }, 'out')).toMatchObject({
      kind: 'hard',
      reason: 'consecutive',
      toolName: 'Bash',
      count: 4,
    });
  });

  it('output 每次都变时不算 consecutive(窗口未满前放行)', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 5; i += 1) {
      expect(feed(g, `id${i}`, 'Bash', { cmd: 'date' }, `out-${i}`).kind).toBe('ok');
    }
  });

  // ── 第 2 层: name+input 滑动窗口多样性坍缩 ────────────────────────────────
  it('同 name+input 但 output 一直变, 窗口填满后判 pingpong(对应图里输出易变的重复)', () => {
    const g = new ToolLoopGuard(); // windowSize 12, distinct<=2
    for (let i = 0; i < 12; i += 1) {
      const v = feed(g, `id${i}`, 'Bash', { cmd: 'p4 status' }, `changelist-${i}`);
      if (i < 11) expect(v.kind).toBe('ok');
      else expect(v).toMatchObject({ kind: 'hard', reason: 'pingpong', count: 12 });
    }
  });

  it('ABAB 交替调用(两种 name+input 来回打转)判 pingpong', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 12; i += 1) {
      const isA = i % 2 === 0;
      const v = feed(
        g,
        `id${i}`,
        'Bash',
        isA ? { cmd: 'python run.py' } : { cmd: 'p4 sync' },
        `o${i}`,
      );
      if (i < 11) expect(v.kind).toBe('ok');
      else expect(v).toMatchObject({ kind: 'hard', reason: 'pingpong' });
    }
  });

  // ── 第 3 层: 长窗口轮转(ABCD…) ───────────────────────────────────────────
  it('4 个不同调用轮转(ABCDABCD…)在轮转窗口填满时判 rotation(对应 grok 4-Grep 实锤)', () => {
    const g = new ToolLoopGuard(); // rotationWindowSize 16, rotationDistinct<=4
    const cmds = ['grep -R a', 'grep -R b', 'grep -R c', 'grep -R d'];
    for (let i = 0; i < 16; i += 1) {
      const v = feed(g, `id${i}`, 'Grep', { pattern: cmds[i % 4] }, `hits-${i}`);
      if (i < 15) expect(v.kind).toBe('ok');
      else expect(v).toMatchObject({ kind: 'hard', reason: 'rotation', count: 16, toolName: 'Grep' });
    }
  });

  it('3 个不同调用轮转同样被 rotation 层捕获', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 16; i += 1) {
      const v = feed(g, `id${i}`, 'Bash', { cmd: `check-${i % 3}` }, `o${i}`);
      if (i < 15) expect(v.kind).toBe('ok');
      else expect(v).toMatchObject({ kind: 'hard', reason: 'rotation' });
    }
  });

  it('5 个不同调用轮转不判 rotation(distinct 超过上限,留给更长证据)', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 40; i += 1) {
      expect(feed(g, `id${i}`, 'Bash', { cmd: `probe-${i % 5}` }, `o${i}`).kind).toBe('ok');
    }
  });

  it('轮转中途出现新调用会把窗口 distinct 顶出上限,不误判', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 48; i += 1) {
      // 每 8 次插入一个全新 input:任何 16 连续窗口 distinct ≥ 5
      const input = i % 8 === 7 ? { cmd: `novel-${i}` } : { cmd: `fix-${i % 4}` };
      expect(feed(g, `id${i}`, 'Bash', input, `o${i}`).kind).toBe('ok');
    }
  });

  // ── 合法长 turn / 原生轮询工具 ───────────────────────────────────────────
  it('TaskOutput 状态长期不变仍放行,不会被通用重复判据中断', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 250; i += 1) {
      expect(
        feed(
          g,
          `id${i}`,
          'TaskOutput',
          { task_id: 'task-1', block: true, timeout: 30_000 },
          'still running',
        ).kind,
      ).toBe('ok');
    }
  });

  it('TaskOutput 不会隐藏穿插在轮询之间的连续普通工具循环', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 4; i += 1) {
      const ordinary = feed(g, `bash-${i}`, 'Bash', { cmd: 'ls' }, 'same');
      if (i < 3) expect(ordinary.kind).toBe('ok');
      else expect(ordinary).toMatchObject({ kind: 'hard', reason: 'consecutive' });

      expect(
        feed(
          g,
          `poll-${i}`,
          'TaskOutput',
          { task_id: 'task-1', block: true, timeout: 30_000 },
          'still running',
        ).kind,
      ).toBe('ok');
    }
  });

  it('TaskOutput 不会隐藏穿插在轮询之间的 ABAB 普通工具循环', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 12; i += 1) {
      const ordinary = feed(
        g,
        `ordinary-${i}`,
        'Bash',
        i % 2 === 0 ? { cmd: 'python run.py' } : { cmd: 'p4 sync' },
        `output-${i}`,
      );
      if (i < 11) expect(ordinary.kind).toBe('ok');
      else expect(ordinary).toMatchObject({ kind: 'hard', reason: 'pingpong' });

      expect(
        feed(
          g,
          `poll-${i}`,
          'TaskOutput',
          { task_id: 'task-1', block: true, timeout: 30_000 },
          'still running',
        ).kind,
      ).toBe('ok');
    }
  });

  it('三十三项固定序列不会被有限窗口冒充为通用硬上限', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 198; i += 1) {
      const position = i % 33;
      expect(
        feed(
          g,
          `id${i}`,
          'Read',
          { file: `project-${position}.json` },
          `stable-${position}`,
        ).kind,
      ).toBe('ok');
    }
  });

  it('参数持续变化时即使结果高度重复也不判 hard', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 250; i += 1) {
      expect(feed(g, `id${i}`, 'Read', { file: `missing-${i}.ts` }, 'not found').kind).toBe('ok');
    }
  });

  it('参数持续变化且结果为空或纯空白时也不判 hard', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 250; i += 1) {
      const output = i % 2 === 0 ? '' : '   ';
      expect(feed(g, `id${i}`, 'Write', { file: `f${i}.ts` }, output).kind).toBe('ok');
    }
  });

  // ── 配对 / 放行 ───────────────────────────────────────────────────────────
  it('没配到 tool_use 的孤立 result 直接放行', () => {
    const g = new ToolLoopGuard();
    expect(g.onToolResult('orphan', 'out').kind).toBe('ok');
  });

  it('半信息 tool_use(name 非 string)不缓存, result 配不到即放行', () => {
    const g = new ToolLoopGuard({ consecutiveLimit: 2 });
    for (let i = 0; i < 5; i += 1) {
      g.onToolUse(`id${i}`, undefined, { cmd: 'ls' });
      expect(g.onToolResult(`id${i}`, 'out').kind).toBe('ok');
    }
  });

  // ── reset ─────────────────────────────────────────────────────────────────
  it('resetTurn 清空全部计数', () => {
    const g = new ToolLoopGuard({ consecutiveLimit: 3 });
    feed(g, 'a0', 'Bash', { cmd: 'ls' }, 'o');
    feed(g, 'a1', 'Bash', { cmd: 'ls' }, 'o'); // streak 到 2

    g.resetTurn();

    expect(feed(g, 'b0', 'Bash', { cmd: 'ls' }, 'o').kind).toBe('ok'); // streak 重新从 1
    expect(feed(g, 'b1', 'Bash', { cmd: 'ls' }, 'o').kind).toBe('ok'); // 2
    expect(feed(g, 'b2', 'Bash', { cmd: 'ls' }, 'o')).toMatchObject({
      kind: 'hard',
      reason: 'consecutive',
    });
  });

  // ── 第 4 层: 同类契约错误 streak(input 各不相同也计) ─────────────────────
  const MISSING = 'InputValidationError: Edit failed due to the following issue: The required parameter `file_path` is missing';

  it('同工具连续 3 次同类契约错误判 contract,input 各不相同也计(对应 grok 16 次 Edit 缺 file_path 实锤)', () => {
    const g = new ToolLoopGuard();
    expect(feed(g, 'e0', 'Edit', { old_string: 'a', new_string: 'b' }, MISSING, true).kind).toBe('ok');
    expect(feed(g, 'e1', 'Edit', { old_string: 'c', new_string: 'd' }, MISSING, true).kind).toBe('ok');
    expect(feed(g, 'e2', 'Edit', { old_string: 'e', new_string: 'f' }, MISSING, true)).toMatchObject({
      kind: 'hard',
      reason: 'contract',
      count: 3,
      toolName: 'Edit',
      contractCategory: 'missing_required_field',
    });
  });

  it('中间插入成功结果打断契约错误的"连续"', () => {
    const g = new ToolLoopGuard();
    feed(g, 'e0', 'Edit', { old_string: 'a' }, MISSING, true);
    feed(g, 'e1', 'Edit', { old_string: 'b' }, MISSING, true);
    // 成功输出重置 streak
    expect(feed(g, 'ok', 'Edit', { file_path: '/f', old_string: 'x', new_string: 'y' }, 'The file /f has been updated.').kind).toBe('ok');
    expect(feed(g, 'e2', 'Edit', { old_string: 'c' }, MISSING, true).kind).toBe('ok'); // 重新从 1 计
    expect(feed(g, 'e3', 'Edit', { old_string: 'd' }, MISSING, true).kind).toBe('ok'); // 2
    expect(feed(g, 'e4', 'Edit', { old_string: 'e' }, MISSING, true)).toMatchObject({ kind: 'hard', reason: 'contract' });
  });

  it('交替类别不判 contract(stale / ambiguous 各自重新计数)', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 12; i += 1) {
      const output = i % 2 === 0
        ? 'String to replace not found in file.'
        : 'Found 2 matches of the string to replace, but replace_all is false.';
      // 类别交替 → 每次键都换,streak 恒为 1;但第 2/3 层若命中(input 相同)与本层无关,
      // 这里让 input 每次都不同,隔离只测第 4 层。
      expect(feed(g, `alt-${i}`, 'Edit', { old_string: `s-${i}` }, output).kind).toBe('ok');
    }
  });

  it('同类别跨不同工具不累计(键含工具名)', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 12; i += 1) {
      const tool = i % 2 === 0 ? 'Edit' : 'Write';
      expect(feed(g, `x-${i}`, tool, { n: i }, MISSING.replace('Edit', tool), true).kind).toBe('ok');
    }
  });

  it('未识别的错误(other)永不触发熔断', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 50; i += 1) {
      expect(feed(g, `u-${i}`, 'Bash', { cmd: `c-${i}` }, `Error: something odd happened (${i})`).kind).toBe('ok');
    }
  });

  it('TaskOutput 轮询穿插在契约错误之间不重置 streak,也不隐藏它', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 3; i += 1) {
      const v = feed(g, `e-${i}`, 'Edit', { old_string: `s-${i}` }, MISSING, true);
      if (i < 2) expect(v.kind).toBe('ok');
      else expect(v).toMatchObject({ kind: 'hard', reason: 'contract', count: 3 });

      expect(
        feed(g, `poll-${i}`, 'TaskOutput', { task_id: 't', block: true, timeout: 30_000 }, 'still running').kind,
      ).toBe('ok');
    }
  });

  it('成功输出恰好包含错误文案短语时被长度门挡在分类外(编辑含文案的测试文件)', () => {
    const g = new ToolLoopGuard();
    const longEcho = `The file /repo/loop-guard.test.ts has been updated. Here is a snippet:\n${'x'.repeat(700)}\nString to replace not found in file.`;
    for (let i = 0; i < 10; i += 1) {
      expect(feed(g, `echo-${i}`, 'Edit', { old_string: `s-${i}` }, longEcho, false).kind).toBe('ok');
    }
  });

  it('成功结果即使包含短错误文案也不会进入契约错误熔断', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 6; i += 1) {
      expect(
        feed(g, `read-${i}`, 'Read', { file_path: `fixture-${i}.txt` }, 'The pages must be numbered', false).kind,
      ).toBe('ok');
    }
  });

  it('resetTurn 同样清空契约错误计数', () => {
    const g = new ToolLoopGuard();
    feed(g, 'c0', 'Edit', { old_string: 'a' }, MISSING, true);
    feed(g, 'c1', 'Edit', { old_string: 'b' }, MISSING, true); // streak 2

    g.resetTurn();

    expect(feed(g, 'd0', 'Edit', { old_string: 'c' }, MISSING, true).kind).toBe('ok'); // 重新从 1
    expect(feed(g, 'd1', 'Edit', { old_string: 'd' }, MISSING, true).kind).toBe('ok'); // 2
    expect(feed(g, 'd2', 'Edit', { old_string: 'e' }, MISSING, true)).toMatchObject({ kind: 'hard', reason: 'contract' });
  });

  it('同一 assistant 批次的多个同类失败只计一次,模型仍有机会看到第一批错误', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 3; i += 1) {
      expect(
        feed(g, `batch-a-${i}`, 'Edit', { old_string: `a-${i}` }, MISSING, true, 'batch-a').kind,
      ).toBe('ok');
    }

    expect(feed(g, 'batch-b-0', 'Edit', { old_string: 'b-0' }, MISSING, true, 'batch-b').kind).toBe('ok');
    expect(feed(g, 'batch-c-0', 'Edit', { old_string: 'c-0' }, MISSING, true, 'batch-c')).toMatchObject({
      kind: 'hard',
      reason: 'contract',
      count: 3,
      toolName: 'Edit',
      contractCategory: 'missing_required_field',
    });
  });

  it('同一批次去重仍要求 is_error=true', () => {
    const g = new ToolLoopGuard();
    for (let i = 0; i < 4; i += 1) {
      expect(feed(g, `success-${i}`, 'Edit', { old_string: `s-${i}` }, MISSING, false, 'same-batch').kind).toBe('ok');
    }
    expect(feed(g, 'failed', 'Edit', { old_string: 'failed' }, MISSING, true, 'next-batch').kind).toBe('ok');
  });

  it('同批次无关成功结果不清零契约 streak,下一批次才继续累计', () => {
    const g = new ToolLoopGuard();

    expect(feed(g, 'bad-a', 'Edit', { old_string: 'a' }, MISSING, true, 'batch-a').kind).toBe('ok');
    // 结果顺序若为 malformed Edit → successful Read, 不应把第一批失败抹掉。
    expect(feed(g, 'read-a', 'Read', { file_path: 'context.txt' }, 'read ok', false, 'batch-a').kind).toBe('ok');

    expect(feed(g, 'bad-b', 'Edit', { old_string: 'b' }, MISSING, true, 'batch-b').kind).toBe('ok');
    expect(feed(g, 'read-b', 'Read', { file_path: 'context.txt' }, 'read ok', false, 'batch-b').kind).toBe('ok');

    expect(feed(g, 'bad-c', 'Edit', { old_string: 'c' }, MISSING, true, 'batch-c')).toMatchObject({
      kind: 'hard',
      reason: 'contract',
      count: 3,
      contractCategory: 'missing_required_field',
    });
  });

  it('同批次成功结果先到也不清零契约 streak,结果顺序不影响跨批次计数', () => {
    const g = new ToolLoopGuard();

    for (const [index, batchId] of ['batch-a', 'batch-b'].entries()) {
      expect(
        feed(g, `read-${index}`, 'Read', { file_path: 'context.txt' }, 'read ok', false, batchId).kind,
      ).toBe('ok');
      expect(
        feed(g, `bad-${index}`, 'Edit', { old_string: `s-${index}` }, MISSING, true, batchId).kind,
      ).toBe('ok');
    }

    expect(feed(g, 'read-c', 'Read', { file_path: 'context.txt' }, 'read ok', false, 'batch-c').kind).toBe('ok');
    expect(feed(g, 'bad-c', 'Edit', { old_string: 'c' }, MISSING, true, 'batch-c')).toMatchObject({
      kind: 'hard',
      reason: 'contract',
      count: 3,
      contractCategory: 'missing_required_field',
    });
  });

  it('同批次其它契约类别先到也不清零目标类别 streak', () => {
    const g = new ToolLoopGuard();
    const stale = 'String to replace not found in file.';

    expect(feed(g, 'missing-a', 'Edit', { old_string: 'a' }, MISSING, true, 'batch-a').kind).toBe('ok');
    expect(feed(g, 'stale-b', 'Edit', { old_string: 'b' }, stale, true, 'batch-b').kind).toBe('ok');
    expect(feed(g, 'missing-b', 'Edit', { old_string: 'b' }, MISSING, true, 'batch-b').kind).toBe('ok');
    expect(feed(g, 'missing-c', 'Edit', { old_string: 'c' }, MISSING, true, 'batch-c')).toMatchObject({
      kind: 'hard',
      reason: 'contract',
      count: 3,
      contractCategory: 'missing_required_field',
    });
  });

  it('批次标识流与旧版无批次调用不串用契约 streak', () => {
    const g = new ToolLoopGuard();

    expect(feed(g, 'legacy-a', 'Edit', { old_string: 'a' }, MISSING, true).kind).toBe('ok');
    expect(feed(g, 'legacy-b', 'Edit', { old_string: 'b' }, MISSING, true).kind).toBe('ok');

    expect(feed(g, 'batch-a', 'Edit', { old_string: 'c' }, MISSING, true, 'batch-a').kind).toBe('ok');
    expect(feed(g, 'batch-b', 'Edit', { old_string: 'd' }, MISSING, true, 'batch-b').kind).toBe('ok');

    // Switching back to the legacy callback shape starts a fresh streak rather
    // than inheriting the two legacy failures from before the batch stream.
    expect(feed(g, 'legacy-c', 'Edit', { old_string: 'e' }, MISSING, true).kind).toBe('ok');
    expect(feed(g, 'legacy-d', 'Edit', { old_string: 'f' }, MISSING, true).kind).toBe('ok');
    expect(feed(g, 'legacy-e', 'Edit', { old_string: 'g' }, MISSING, true)).toMatchObject({
      kind: 'hard',
      reason: 'contract',
      count: 3,
    });
  });
});

describe('ToolLoopGuard pacing and final limits', () => {
  const ci = { cmd: 'gh api repos/o/r/actions/jobs/1 --jq .status' };
  const minute = 60_000;

  function clockGuard(options: ConstructorParameters<typeof ToolLoopGuard>[0] = {}) {
    let now = 0;
    const guard = new ToolLoopGuard({ now: () => now, ...options });
    return { guard, advance: (ms: number) => { now += ms; } };
  }

  it('does not count CI polling separated by real waits (2026-10 PR #18 false positive)', () => {
    const { guard, advance } = clockGuard();
    for (let i = 0; i < 40; i++) {
      // Codex 先 sleep 55s 再查同一个 job;结果长时间不变是正常等待。
      expect(feed(guard, `sleep-${i}`, 'mcp:clock:sleep', { duration_ms: 55_000 }, 'Sleep completed.').kind).toBe('ok');
      advance(66_000);
      expect(feed(guard, `poll-${i}`, 'exec', ci, '{"status":"in_progress"}').kind).toBe('ok');
    }
  });

  it('treats a command with a built-in wait as paced polling', () => {
    const { guard, advance } = clockGuard();
    for (let i = 0; i < 20; i++) {
      guard.onToolUse(String(i), 'exec', { cmd: 'sleep 45 && gh run view 1' });
      advance(46_000);
      expect(guard.onToolResult(String(i), 'in_progress').kind).toBe('ok');
    }
  });

  it('treats waits issued together and run one by one as paced (2026-10 gate polling false positive)', () => {
    const { guard, advance } = clockGuard();
    const wait = (i: number) => ({ command: `sleep 58; grep GATE_EXIT gate.log # ${i % 2}` });
    let id = 0;
    // 模型一次发出 3-6 条等待命令,工具逐条排队执行:发出时刻相差 1 秒,结果每分钟到一个。
    for (const batch of [6, 6, 3, 3, 6]) {
      const ids: string[] = [];
      for (let i = 0; i < batch; i++) {
        advance(1_000);
        ids.push(String(id));
        guard.onToolUse(String(id), 'Bash', wait(id));
        id += 1;
      }
      for (const toolUseId of ids) {
        advance(minute);
        expect(guard.onToolResult(toolUseId, `11:${toolUseId} waiting`).kind).toBe('ok');
      }
    }
  });

  it('still counts identical fast calls issued together and finished together', () => {
    const { guard, advance } = clockGuard();
    const verdicts: ToolLoopGuardVerdict[] = [];
    for (let i = 0; i < 4; i++) guard.onToolUse(String(i), 'read', { path: 'same.ts' });
    advance(minute);
    for (let i = 0; i < 4; i++) verdicts.push(guard.onToolResult(String(i), 'unchanged'));
    expect(verdicts[3]).toMatchObject({ kind: 'hard', reason: 'consecutive', count: 4, final: false });
  });

  it('stops identical paced polling after one hour without review', () => {
    const { guard, advance } = clockGuard();
    let verdict: ToolLoopGuardVerdict = { kind: 'ok' };
    let polls = 0;
    while (verdict.kind === 'ok' && polls < 200) {
      verdict = feed(guard, String(polls), 'exec', ci, 'in_progress');
      polls += 1;
      advance(minute);
    }
    // 首次调用在 t=0,第 61 次在 t=60min 时达到时长上限。
    expect(polls).toBe(61);
    expect(verdict).toMatchObject({ kind: 'hard', reason: 'consecutive', count: 61, final: true });
  });

  it('starts the one-hour limit when the first identical result arrives', () => {
    const { guard, advance } = clockGuard();
    guard.onToolUse('slow', 'exec', ci);
    advance(61 * minute);
    expect(guard.onToolResult('slow', 'done').kind).toBe('ok');
    // 第一次快速调用距慢调用开始已超过 30 秒,按节奏不计数;之后三次计数到 4。
    // 相同结果才持续几秒,只能是待复核的疑似,不因首次调用耗时长而直接判定。
    for (let i = 0; i < 4; i++) {
      advance(1_000);
      const verdict = feed(guard, String(i), 'exec', ci, 'done');
      if (i < 3) expect(verdict.kind).toBe('ok');
      else expect(verdict).toMatchObject({ kind: 'hard', reason: 'consecutive', count: 4, final: false });
    }
  });

  it('keeps paced polling alive while the observed state changes', () => {
    const { guard, advance } = clockGuard();
    for (let i = 0; i < 150; i++) {
      expect(feed(guard, String(i), 'exec', ci, `step-${Math.floor(i / 10)}`).kind).toBe('ok');
      advance(minute);
    }
  });

  it('marks fast repetition as suspected and lets review grant a grace window', () => {
    const { guard, advance } = clockGuard();
    const call = (i: number) => {
      advance(1_000);
      return feed(guard, String(i), 'read', { path: 'same.ts' }, 'unchanged');
    };
    for (let i = 1; i <= 3; i++) expect(call(i).kind).toBe('ok');
    expect(call(4)).toMatchObject({ kind: 'hard', reason: 'consecutive', count: 4, final: false });

    guard.acceptCurrentPattern(20);
    for (let i = 5; i <= 24; i++) expect(call(i).kind).toBe('ok');
    expect(call(25)).toMatchObject({ kind: 'hard', count: 25, final: false });
    for (let i = 26; i <= 29; i++) expect(call(i)).toMatchObject({ final: false });
    // 快速完全相同调用的最终上限不受复核放行影响。
    expect(call(30)).toMatchObject({ kind: 'hard', reason: 'consecutive', count: 30, final: true });
  });

  it('consumes the review grace window with paced polls too', () => {
    const { guard, advance } = clockGuard();
    const fast = (i: number) => {
      advance(1_000);
      return feed(guard, `fast-${i}`, 'read', { path: 'same.ts' }, 'unchanged');
    };
    for (let i = 1; i <= 4; i++) fast(i);
    guard.acceptCurrentPattern(20);
    for (let i = 0; i < 20; i++) {
      advance(minute);
      expect(feed(guard, `poll-${i}`, 'exec', ci, 'in_progress').kind).toBe('ok');
    }
    // 放行额度已被节奏轮询用完,新的快速重复照常报疑似。
    for (let i = 5; i <= 7; i++) expect(fast(i).kind).toBe('ok');
    expect(fast(8)).toMatchObject({ kind: 'hard', reason: 'consecutive', count: 4, final: false });
  });

  it('does not let one paced call hide surrounding fast repetitions', () => {
    const { guard, advance } = clockGuard();
    const verdicts: ToolLoopGuardVerdict[] = [];
    for (const gap of [1_000, 1_000, 1_000, 40_000, 1_000]) {
      advance(gap);
      verdicts.push(feed(guard, String(verdicts.length), 'read', { path: 'same.ts' }, 'unchanged'));
    }
    expect(verdicts.slice(0, 4).every((verdict) => verdict.kind === 'ok')).toBe(true);
    expect(verdicts[4]).toMatchObject({ kind: 'hard', reason: 'consecutive', count: 4, final: false });
  });

  it('lets a paced command break the long read window', () => {
    const { guard, advance } = clockGuard();
    for (let i = 0; i < 127; i++) {
      advance(1_000);
      expect(feed(guard, `read-${i}`, 'grep', { pattern: `symbol-${i % 6}` }, `file-${i % 6}: match`).kind).toBe('ok');
    }
    advance(40_000);
    expect(feed(guard, 'build', 'exec', { cmd: 'pnpm build' }, 'done').kind).toBe('ok');
    advance(1_000);
    expect(feed(guard, 'read-127', 'grep', { pattern: 'symbol-1' }, 'file-1: match').kind).toBe('ok');
  });

  it('marks long stable read rotations as final', () => {
    const guard = new ToolLoopGuard();
    let verdict: ToolLoopGuardVerdict = { kind: 'ok' };
    for (let i = 0; i < 128; i++) {
      verdict = feed(guard, String(i), 'grep', { pattern: `symbol-${i % 6}` }, `file-${i % 6}: match`);
    }
    expect(verdict).toMatchObject({ kind: 'hard', reason: 'rotation', count: 128, final: true });
  });

  it('keeps the latest captured calls as review evidence and clears them per turn', () => {
    const { guard, advance } = clockGuard();
    for (let i = 0; i < 15; i++) {
      guard.onToolUse(String(i), 'exec', { cmd: `step ${i}` });
      advance(2_000);
      guard.onToolResult(String(i), i === 14 ? 'x'.repeat(5_000) : `out ${i}`, i === 13);
    }
    const evidence = guard.recentEvidence();
    expect(evidence).toHaveLength(12);
    expect(evidence[0]).toMatchObject({ toolName: 'exec', input: { cmd: 'step 3' }, output: 'out 3' });
    expect(evidence[10]).toMatchObject({ isError: true, startedAt: 26_000, finishedAt: 28_000 });
    // 只为限制内存截取未脱敏原文;脱敏与发送截断由发送方负责。
    // 截取点落在连续串中间:整段连续串一起丢掉,不留残缺前缀。
    expect(evidence[11]?.output).toBe('…(+5000 chars)');
    guard.resetTurn();
    expect(guard.recentEvidence()).toEqual([]);
  });

  it('drops a token fragment cut by the capture limit but keeps earlier context', () => {
    const guard = new ToolLoopGuard();
    // 3990 字符的普通内容之后紧跟一个跨越 4000 截取点的长连续串(形同令牌)。
    const output = `${'ok '.repeat(1330)}${'Z'.repeat(60)} tail`;
    feed(guard, '1', 'exec', { cmd: 'env' }, output);
    const captured = guard.recentEvidence()[0]?.output ?? '';
    expect(captured).toBe(`${'ok '.repeat(1330)}…(+${output.length - 3990} chars)`);
  });

  it('drops the whole line cut by the capture limit, including quoted values', () => {
    const guard = new ToolLoopGuard();
    const head = `${'ok '.repeat(1320)}\n`;
    const output = `${head}tool login --token "correct horse battery staple and more words"\nnext line`;
    feed(guard, '1', 'exec', { cmd: 'env' }, output);
    expect(guard.recentEvidence()[0]?.output).toBe(`${head}…(+${output.length - head.length} chars)`);
  });

  it('drops an unterminated quoted value when the cut has no newline', () => {
    const guard = new ToolLoopGuard();
    const head = `${'ok '.repeat(1320)}tool login --token `;
    const output = `${head}"correct horse battery staple and more words"`;
    feed(guard, '1', 'exec', { cmd: 'env' }, output);
    const captured = guard.recentEvidence()[0]?.output ?? '';
    expect(captured).not.toContain('horse');
    expect(captured).not.toContain('correct');
    expect(captured).toBe(`${head}…(+${output.length - head.length} chars)`);
  });

  it('keeps structured input as a bounded copy instead of serializing it', () => {
    const guard = new ToolLoopGuard();
    const input = { cmd: 'tool login --token "tok live value"', body: 'y'.repeat(5_000), nested: { a: [1, { b: 'c' }] } };
    feed(guard, '1', 'exec', input, 'ok');
    const captured = guard.recentEvidence()[0]?.input as Record<string, unknown>;
    expect(captured.cmd).toBe('tool login --token "tok live value"');
    expect(captured.body).toBe('…(+5000 chars)');
    expect(captured.nested).toEqual({ a: [1, { b: 'c' }] });
    expect(captured).not.toBe(input);
  });

  // 2026-10-18 误报:脚本里同一调用在突发里重复(0.8s 一次)不是模型逐次重复;
  // 隔着采样时间的重复仍须计数。
  it('ignores a call repeated in a burst but counts it once sampling gaps separate it', () => {
    const { guard, advance } = clockGuard({ burstRepeatGapMs: 2_000 });
    for (let i = 0; i < 30; i++) {
      expect(feed(guard, `burst-${i}`, 'browser', { action: 'snapshot' }, 'saving').kind).toBe('ok');
      advance(800);
    }
    let last: ToolLoopGuardVerdict = { kind: 'ok' };
    for (let i = 0; i < 4; i++) {
      advance(3_000);
      last = feed(guard, `model-${i}`, 'browser', { action: 'snapshot' }, 'saving');
    }
    expect(last).toMatchObject({ kind: 'hard', reason: 'consecutive' });
  });

  // codex P1(#6388):判据只看该调用自己的开始时间。后台脚本以其它调用持续快速返回结果,
  // 不能让隔着采样时间的模型重复被当作突发而永远不计数;完成顺序、并发也不影响。
  it('counts model repeats even while a script keeps returning unrelated results quickly', () => {
    const { guard, advance } = clockGuard({ burstRepeatGapMs: 2_000 });
    let last: ToolLoopGuardVerdict = { kind: 'ok' };
    for (let round = 0; round < 6; round++) {
      guard.onToolUse(`model-${round}`, 'read', { path: 'a' });
      guard.onToolUse(`script-a-${round}`, 'read', { path: 'b' });
      advance(500);
      guard.onToolResult(`script-a-${round}`, 'same');
      guard.onToolUse(`script-b-${round}`, 'read', { path: 'b' });
      advance(500);
      last = guard.onToolResult(`model-${round}`, 'same');
      guard.onToolResult(`script-b-${round}`, 'same');
      advance(8_500);
    }
    expect(last).toMatchObject({ kind: 'hard', reason: 'pingpong', count: 12 });
  });

  // codex P1/P2(#6388):突发关系在调用开始时确定,并发的相邻调用无论按什么顺序返回都不影响;
  // 结果到达时才看会漏掉尚未返回的邻居,或被迟到的旧调用覆盖。
  it('decides burst repeats at call start, whatever order overlapping calls complete in', () => {
    const { guard, advance } = clockGuard({ burstRepeatGapMs: 2_000 });
    const verdicts: ToolLoopGuardVerdict[] = [];
    for (let group = 0; group < 6; group++) {
      guard.onToolUse(`a-${group}`, 'browser', { action: 'snapshot' });
      advance(1_500);
      guard.onToolUse(`b-${group}`, 'browser', { action: 'snapshot' });
      advance(1_500);
      guard.onToolUse(`c-${group}`, 'browser', { action: 'snapshot' });
      advance(100);
      for (const id of ['a', 'c', 'b']) verdicts.push(guard.onToolResult(`${id}-${group}`, 'saving'));
      advance(1_400);
    }
    expect(verdicts.filter((verdict) => verdict.kind === 'hard')).toEqual([]);
  });

  // codex P2(#6388):突发结果不参与判定,也不能消耗复核放行额度。
  it('does not spend the review grace window on burst repeats', () => {
    const { guard, advance } = clockGuard({ burstRepeatGapMs: 2_000 });
    guard.acceptCurrentPattern(4);
    for (let i = 0; i < 10; i++) {
      feed(guard, `burst-${i}`, 'browser', { action: 'snapshot' }, 'same');
      advance(500);
    }
    let last: ToolLoopGuardVerdict = { kind: 'ok' };
    for (let i = 0; i < 3; i++) {
      advance(3_000);
      last = feed(guard, `model-${i}`, 'browser', { action: 'snapshot' }, 'same');
    }
    expect(last.kind).toBe('ok');
  });

  // codex P1(#6388):突发重复只有续接了当前连续段才评估时长上限,
  // 否则早已陈旧的连续段会被算到无关的突发调用头上。
  it('does not apply the duration cap of a stale streak to an unrelated burst result', () => {
    const { guard, advance } = clockGuard({ burstRepeatGapMs: 2_000, finalStreakMs: 20_000 });
    const verdicts: ToolLoopGuardVerdict[] = [];
    for (let tick = 0; tick < 40; tick++) {
      advance(1_000);
      // A script polls once a second (a burst after the first), with a different result each time.
      guard.onToolUse(`x-${tick}`, 'browser', { action: 'poll' });
      verdicts.push(guard.onToolResult(`x-${tick}`, `busy ${tick}`));
      // The model repeats one call four times, three seconds apart, then stops.
      if (tick % 3 === 0 && tick < 12) verdicts.push(feed(guard, `a-${tick}`, 'browser', { action: 'snapshot' }, 'same'));
    }
    expect(verdicts.filter((verdict) => verdict.kind === 'hard' && verdict.final)).toEqual([]);
  });
});

describe('classifyToolContractError', () => {
  it('逐类别识别稳定错误文案', () => {
    expect(classifyToolContractError('Edit', 'The required parameter `file_path` is missing')).toBe('missing_required_field');
    expect(classifyToolContractError('Write', 'missing required parameter "content"')).toBe('missing_required_field');
    expect(classifyToolContractError('Read', 'Invalid pages parameter: "abc"')).toBe('invalid_pages');
    expect(classifyToolContractError('Read', 'The `pages` parameter is only applicable to PDF files')).toBe('invalid_pages');
    expect(classifyToolContractError('Edit', 'String to replace not found in file.')).toBe('stale_locator');
    expect(classifyToolContractError('Edit', 'Found 2 matches of the string to replace, but replace_all is false.')).toBe('ambiguous_locator');
    expect(classifyToolContractError('Edit', 'No changes to make: old_string and new_string are exactly the same.')).toBe('no_changes');
  });

  it('工具限定:Edit 专属类别不套在别的工具上;pages 只认 Read', () => {
    expect(classifyToolContractError('Bash', 'String to replace not found in file.')).toBe(null);
    expect(classifyToolContractError('Grep', 'invalid pages')).toBe(null);
  });

  it('Bash 转发的 CLI "missing required parameter" 不算契约错误(用户脚本报错不熔断)', () => {
    expect(classifyToolContractError('Bash', 'mycli: missing required parameter --env')).toBe(null);
    expect(classifyToolContractError('Bash', 'Error: required parameter "--token" is missing')).toBe(null);
  });

  it('空输出 / 超长输出 / 未知错误返回 null', () => {
    expect(classifyToolContractError('Edit', '')).toBe(null);
    expect(classifyToolContractError('Edit', `${'x'.repeat(700)} String to replace not found`)).toBe(null);
    expect(classifyToolContractError('Edit', 'Error: disk full')).toBe(null);
  });
});