codegraph/scripts/agent-eval/parse-bench-readme.mjs

#!/usr/bin/env node
// Aggregate the README A/B (bench-readme.sh output): per repo, median of N runs
// per arm → time, tool calls, tokens, cost, % saved, and RESIDUAL CONTEXT
// OCCUPANCY. Plus an average row.
//
// Tokens = SUM of per-turn assistant `usage` (input + output + cache read +
// cache creation) — the cumulative "total tokens processed". NOTE: `result.usage`
// is last-turn-only in some Claude Code versions, so reading it alone can
// under-count badly; parseSession() sums per-segment and dedupes assistant
// events by message.id (Claude Code emits one event per content block, each
// carrying the same usage — summing per EVENT double-counts).
//
// The occupancy table answers the question "tokens processed" cannot: how much
// of the window each arm's tool output STILL OCCUPIES when the run ends. Under
// multi-turn rows that residual is charged against every following turn.
//
// Usage: node parse-bench-readme.mjs [/tmp/ab-readme]
import { existsSync, readdirSync } from 'fs';
import { join } from 'path';
import { parseSession, SUFFICIENCY } from './parse-run.mjs';

const ROOT = process.argv[2] || '/tmp/ab-readme';
const REPOS = ['vscode', 'excalidraw', 'django', 'tokio', 'okhttp', 'gin', 'alamofire'];

/** All segment files of one arm's session, in turn order (t1, t2, t3, …). */
function segments(dir, label) {
  const first = join(dir, `run-${label}.jsonl`);
  if (!existsSync(first)) return null;
  const rest = readdirSync(dir)
    .map((f) => [f, new RegExp(`^run-${label}\\.t(\\d+)\\.jsonl$`).exec(f)])
    .filter(([, m]) => m)
    .sort((a, b) => Number(a[1][1]) - Number(b[1][1]))
    .map(([f]) => join(dir, f));
  return [first, ...rest];
}

function parse(dir, label) {
  const files = segments(dir, label);
  if (!files) return null;
  const s = parseSession(files);
  if (!s.ok) return null;
  const o = s.occupancy;
  return {
    dur: s.dur, tools: s.tools, reads: s.reads, grep: s.grep, cg: s.cg,
    bash: s.counts.Bash || 0, cliCalls: s.cliCalls, cliContaminated: s.cliContaminated,
    tokens: s.processed, cost: s.cost, raced: s.raced, turns: s.turns,
    segments: files.length,
    ctx: o.ctxFinal,
    ctxBase: o.ctxBase,
    occCg: o.residual.codegraph,
    occFile: o.residualFileAccess,
    // The arm's own retrieval residual: codegraph in the with-arm, Read/Grep/Bash
    // in the without-arm. Comparing these is the apples-to-apples pair.
    occSelf: o.residual.codegraph + o.residualFileAccess,
    occShareCtx: o.ctxFinal > 0 ? ((o.residual.codegraph + o.residualFileAccess) / o.ctxFinal) * 100 : 0,
    occShareWin: ((o.residual.codegraph + o.residualFileAccess) / o.windowTokens) * 100,
    window: o.windowTokens,
    // The other two feedback metrics, carried per run so the campaign can pool
    // them. Both are with-arm-only in practice — a without-arm makes no explore
    // calls, so it has nothing to be sufficient about and no bytes to allocate.
    suffAnswered: s.sufficiency.answered,
    suffCounts: s.sufficiency.counts,
    // Byte-weighted, so a run with no explore contributes NOTHING rather than a
    // zero; a zero would drag a repo toward "wasteful" for never spending a byte.
    allocUsed: s.allocation.envelope ? s.allocation.used : 0,
    allocEnvelope: s.allocation.envelope,
    allocCalls: s.allocation.calls.length,
  };
}

const median = (arr) => { const v = [...arr].sort((a, b) => a - b); const n = v.length; return n === 0 ? 0 : n % 2 ? v[(n - 1) / 2] : (v[n / 2 - 1] + v[n / 2]) / 2; };
const fmtTime = (s) => s >= 60 ? `${Math.floor(s / 60)}m ${Math.round(s % 60)}s` : `${Math.round(s)}s`;
const fmtTok = (t) => t >= 1e6 ? `${(t / 1e6).toFixed(1)}M` : `${Math.round(t / 1000)}k`;
const pct = (w, wo) => wo > 0 ? Math.round((1 - w / wo) * 100) : 0;

// Exclude MCP-cold-start-raced WITH runs by default — they measure a startup
// race, not steady-state value. `CG_INCLUDE_RACED=1` keeps them (to see the raw
// distribution). The WITHOUT arm has no MCP, so it's never raced.
const includeRaced = process.env.CG_INCLUDE_RACED === '1';
// A without-arm run that shelled out to the codegraph CLI measured
// codegraph-over-CLI, not codegraph-absent. Drop it unless asked otherwise.
const includeContaminated = process.env.CG_INCLUDE_CONTAMINATED === '1';
const rows = [];
let contaminated = 0;
for (const repo of REPOS) {
  const dir = join(ROOT, repo);
  const runDirs = existsSync(dir) ? readdirSync(dir).filter(d => /^run\d+$/.test(d)).sort() : [];
  const W = [], WO = []; let racedExcluded = 0;
  for (const rd of runDirs) {
    const w = parse(join(dir, rd), 'headless-with');
    if (w) { if (w.raced && !includeRaced) racedExcluded++; else W.push(w); }
    const wo = parse(join(dir, rd), 'headless-without');
    if (wo) {
      if (wo.cliContaminated && !includeContaminated) { contaminated++; console.error(`[excluded] ${repo}/${rd} without-arm got codegraph CLI output ${wo.cliContaminated}x`); }
      else WO.push(wo);
    }
  }
  rows.push({ repo, W, WO, racedExcluded });
}
if (contaminated) console.error(`[excluded] ${contaminated} contaminated without-arm run(s); CG_INCLUDE_CONTAMINATED=1 keeps them\n`);

// ---- Table 1: the existing throughput view. --------------------------------
console.log('repo        n(w/wo)  time WITH→WITHOUT      tools W→WO   tokens W→WO (saved)     cost W→WO (saved)');
const savings = { cost: [], tokens: [], time: [], tools: [] };
for (const { repo, W, WO, racedExcluded } of rows) {
  if (!W.length || !WO.length) { console.log(`${repo.padEnd(11)} (incomplete: w=${W.length} wo=${WO.length})`); continue; }
  const m = (arr, k) => median(arr.map(x => x[k]));
  const wT = m(W, 'dur'), woT = m(WO, 'dur'), wTok = m(W, 'tokens'), woTok = m(WO, 'tokens');
  const wC = m(W, 'cost'), woC = m(WO, 'cost'), wTl = m(W, 'tools'), woTl = m(WO, 'tools');
  savings.time.push(pct(wT, woT)); savings.tokens.push(pct(wTok, woTok)); savings.cost.push(pct(wC, woC)); savings.tools.push(pct(wTl, woTl));
  console.log(
    `${repo.padEnd(11)} ${W.length}/${WO.length}      ` +
    `${(fmtTime(wT) + '→' + fmtTime(woT)).padEnd(22)}` +
    `${(Math.round(wTl) + '→' + Math.round(woTl)).padEnd(12)}` +
    `${(fmtTok(wTok) + '→' + fmtTok(woTok) + ' (' + pct(wTok, woTok) + '%)').padEnd(24)}` +
    `$${wC.toFixed(2)}→$${woC.toFixed(2)} (${pct(wC, woC)}%)` +
    (racedExcluded ? `  [${racedExcluded} raced run${racedExcluded === 1 ? '' : 's'} excluded]` : '')
  );
}
const avg = (a) => a.length ? Math.round(a.reduce((s, x) => s + x, 0) / a.length) : 0;
console.log(`\nAVERAGE saved:  cost ${avg(savings.cost)}%  ·  tokens ${avg(savings.tokens)}%  ·  time ${avg(savings.time)}%  ·  tool calls ${avg(savings.tools)}%`);

// ---- Table 2: residual context occupancy. ----------------------------------
// WITH's retrieval residual is codegraph's tool output; WITHOUT's is Read +
// Grep/Glob + Bash. Same question, same window — so the pair is comparable.
const anyMulti = rows.some(({ W, WO }) => [...W, ...WO].some(r => r.segments > 1));
console.log(`\n\nRESIDUAL CONTEXT OCCUPANCY — retrieval tokens still in the window at end of run`);
console.log(`(WITH = codegraph responses · WITHOUT = Read + Grep/Glob + Bash responses)`);
console.log(`${anyMulti ? 'multi-turn sessions' : 'SINGLE-TURN sessions — see the caveat below'}\n`);
console.log('repo        turns   final ctx W→WO        residual W→WO         % of ctx W→WO     % of window W→WO');
const occ = { resid: [], shareCtx: [], fixed: [] };
for (const { repo, W, WO } of rows) {
  if (!W.length || !WO.length) { console.log(`${repo.padEnd(11)} (incomplete)`); continue; }
  const m = (arr, k) => median(arr.map(x => x[k]));
  occ.fixed.push(m(W, 'ctxBase') - m(WO, 'ctxBase'));
  const wR = m(W, 'occSelf'), woR = m(WO, 'occSelf');
  const wCtx = m(W, 'ctx'), woCtx = m(WO, 'ctx');
  const wSc = m(W, 'occShareCtx'), woSc = m(WO, 'occShareCtx');
  const wSw = m(W, 'occShareWin'), woSw = m(WO, 'occShareWin');
  occ.resid.push(pct(wR, woR)); occ.shareCtx.push(pct(wSc, woSc));
  console.log(
    `${repo.padEnd(11)} ${String(median(W.map(x => x.turns)) + '/' + median(WO.map(x => x.turns))).padEnd(7)} ` +
    `${(fmtTok(wCtx) + '→' + fmtTok(woCtx)).padEnd(21)}` +
    `${(fmtTok(wR) + '→' + fmtTok(woR) + ' (' + pct(wR, woR) + '%)').padEnd(22)}` +
    `${(wSc.toFixed(1) + '%→' + woSc.toFixed(1) + '%').padEnd(18)}` +
    `${wSw.toFixed(1)}%→${woSw.toFixed(1)}%`
  );
}
// Direction must follow the SIGN, not the hope. `pct(w, wo)` is the reduction
// going with→without, so a NEGATIVE value means the with-arm's residual is
// LARGER. Hardcoding "lower" printed "-82% lower with codegraph" for the case
// where codegraph in fact occupies 82% MORE — a double negative that reads as a
// win and inverts the headline. Say which way it went, in words.
const dir = (v) => (v < 0 ? 'HIGHER' : 'lower');
const magn = (v) => Math.abs(v);
console.log(
  `\nAVERAGE: retrieval residual ${magn(avg(occ.resid))}% ${dir(avg(occ.resid))} with codegraph` +
  `  ·  share-of-context ${magn(avg(occ.shareCtx))}% ${dir(avg(occ.shareCtx))}`
);
if (avg(occ.resid) < 0) {
  console.log(
    `  ^ codegraph front-loads one large verbatim payload that STAYS resident, where Read/Grep\n` +
    `    churn many small results that evict. Read alongside the cost/token table above: fewer\n` +
    `    total tokens processed can coexist with a larger persistent footprint. This is the axis\n` +
    `    issue #1500 reported.`
  );
}

console.log(
  `FIXED overhead: codegraph's tool schema + MCP instructions cost ${avg(occ.fixed) >= 0 ? '+' : ''}${avg(occ.fixed)} tok\n` +
  `  of context before any tool is called (median WITH ctxBase - median WITHOUT ctxBase, averaged\n` +
  `  over repos). It is paid whether or not the agent ever calls codegraph.`
);

// Per-run detail. Medians over 2-3 runs hide swings big enough to flip a repo's
// sign — the agent's tool mix is the variable, and a with-arm run that reads
// files ON TOP of calling explore pays for both. Show every run.
console.log('\nper run (retrieval residual · tool mix — cg=explore rd=Read gr=Grep bs=Bash):');
for (const { repo, W, WO } of rows) {
  if (!W.length && !WO.length) continue;
  const one = (r) => `${fmtTok(r.occSelf)}${r.cg ? ` cg${r.cg}` : ''}${r.reads ? ` rd${r.reads}` : ''}${r.grep ? ` gr${r.grep}` : ''}${r.bash ? ` bs${r.bash}` : ''}`;
  console.log(`  ${repo.padEnd(11)} W: ${W.map(one).join(' | ').padEnd(46)} WO: ${WO.map(one).join(' | ')}`);
}
if (!anyMulti) {
  console.log(
    `\nCAVEAT: every row is a SINGLE-turn session, so the residual is measured at the\n` +
    `moment the one question is answered. Occupancy is a cost that compounds over the turns\n` +
    `that FOLLOW; a single-turn number does not settle it. Re-run with "||"-separated\n` +
    `follow-ups (see run-all.sh) to measure the regime this metric is actually about.`
  );
}

// ---- Table 3: sufficiency + allocation, WITH arm only. ---------------------
// Occupancy says what a response COST; these two say whether it was enough and
// whether it spent its bytes on the right files. A campaign that reports only
// occupancy cannot tell a tighter response from a worse one.
//
// Pooled per repo, not median-of-runs: both are per-CALL quantities (sufficiency
// counts explores, allocation weights by bytes), and a repo contributes 2-15
// calls across its runs. Median-of-run-percentages would weight a 1-call run the
// same as a 5-call one.
console.log(`\n\nEXPLORE SUFFICIENCY + ALLOCATION EFFICIENCY — with-arm only, pooled over runs`);
console.log(`(sufficiency = what the agent did NEXT · allocation = share of returned bytes the answer cited)\n`);
console.log('repo        calls   again  read-ret  read-miss  grep   MOVED ON     alloc eff   envelope');
const totals = { answered: 0, counts: Object.fromEntries(SUFFICIENCY.map(([k]) => [k, 0])), used: 0, env: 0, calls: 0 };
for (const { repo, W } of rows) {
  if (!W.length) { console.log(`${repo.padEnd(11)} (no with-arm runs)`); continue; }
  const answered = W.reduce((s, r) => s + r.suffAnswered, 0);
  const cnt = (k) => W.reduce((s, r) => s + r.suffCounts[k], 0);
  const env = W.reduce((s, r) => s + r.allocEnvelope, 0);
  const used = W.reduce((s, r) => s + r.allocUsed, 0);
  totals.answered += answered; totals.used += used; totals.env += env;
  totals.calls += W.reduce((s, r) => s + r.allocCalls, 0);
  for (const [k] of SUFFICIENCY) totals.counts[k] += cnt(k);
  const cell = (k) => (answered ? `${cnt(k)} ${Math.round((cnt(k) / answered) * 100)}%` : '—').padEnd(9);
  console.log(
    `${repo.padEnd(11)} ${String(answered).padEnd(7)} ` +
    `${cell('explore_again')}${cell('read_returned')}${cell('read_missed')}${cell('search')}` +
    `${(answered ? `${cnt('sufficient')} ${Math.round((cnt('sufficient') / answered) * 100)}%` : '—').padEnd(13)}` +
    `${(env ? `${((used / env) * 100).toFixed(1)}%` : '—').padEnd(12)}${fmtTok(env)}`
  );
}
const tp = (k) => totals.answered ? `${totals.counts[k]} (${Math.round((totals.counts[k] / totals.answered) * 100)}%)` : '—';
console.log(
  `\nPOOLED (${totals.answered} answered explore calls): ` +
  SUFFICIENCY.map(([k, label]) => `${label} ${tp(k)}`).join(' · ')
);
console.log(
  `POOLED allocation efficiency: ${totals.env ? ((totals.used / totals.env) * 100).toFixed(1) + '%' : '—'} ` +
  `over ${totals.calls} calls / ${fmtTok(totals.env)} chars`
);
console.log(
  `\nHOW TO READ: "read-ret" (Read a file we RETURNED) is an allocation miss — right file,\n` +
  `wrong bytes; "read-miss" and "grep" are recall misses. "again" is ambiguous by construction.\n` +
  `Allocation efficiency is RELATIVE — attribution is by citation, so it compares BUILDS on the\n` +
  `same questions and is not a claim that codegraph wasted the remainder. Full guidance:\n` +
  `docs/benchmarks/agent-eval-feedback-metrics.md`
);