Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
ask: build-time file sizes → tokens-saved estimate in --source; auto-inject spans + savings via prompt hook + statusline total
anirudhkumar-nanonetsa1ddabcbb81c
diff --git a/bench/token-ab.ts b/bench/token-ab.tsnew file mode 100644index 00000000..99f2c6eb--- /dev/null+++ b/bench/token-ab.ts@@ -0,0 +1,297 @@+/**+ * token-ab.ts — a manual A/B harness to see whether graft saves an agent tokens.+ *+ * Same question, same model, two arms:+ * COLD — the agent gets only `search` + `read_file` tools and must explore+ * the repo itself (what a normal coding agent does).+ * GRAFT — the agent gets the SAME tools, but the `graft ask --source` pack is+ * pasted into its context up front, so it can answer without exploring.+ *+ * It prints a side-by-side metrics table (tokens, LLM round-trips, tool calls,+ * files opened, wall-clock) and BOTH final answers, so you judge equivalence.+ *+ * Prereqs:+ * 1. OPENROUTER_API_KEY in context-engine/.env (already there).+ * 2. graft built in the target repo: cd <REPO> && graft build+ *+ * Run: npx tsx bench/token-ab.ts+ * Tune: edit the CONFIG block, or override via env (REPO, QUESTION, MODEL, MAX_STEPS).+ */+import "dotenv/config";+import OpenAI from "openai";+import { execFileSync } from "node:child_process";+import { readFileSync, existsSync } from "node:fs";+import { resolve, relative, isAbsolute } from "node:path";++// ─────────────────────────── CONFIG (edit freely) ───────────────────────────+const CONFIG = {+ REPO: process.env.REPO ?? "/Users/anirudh/Documents/assign/frontend",+ QUESTION:+ process.env.QUESTION ??+ "When a user sends a message to an agent in the chat UI, trace the full path end to end: " ++ "which component handles the submit, how the message reaches the backend API, how the optimistic " ++ "update and the polling query stay in sync via the React Query cache key, where the agent is " ++ "resolved from the route, and where a quota/402 billing error is handled. " ++ "List the specific files and functions in order.",+ MODEL: process.env.MODEL ?? "openai/gpt-4o-mini",+ MAX_STEPS: Number(process.env.MAX_STEPS ?? 14), // cap on agent tool-loop round-trips+ SEARCH_MAX_LINES: 60, // cap rows returned per search+ READ_MAX_LINES: 400, // cap lines returned per read_file+ READ_MAX_CHARS: 12_000, // hard char cap per read_file+ // Optional cost estimate: set $ per 1M tokens for your model to see a $ column.+ PRICE_IN_PER_M: Number(process.env.PRICE_IN_PER_M ?? 0),+ PRICE_OUT_PER_M: Number(process.env.PRICE_OUT_PER_M ?? 0),+};+// ─────────────────────────────────────────────────────────────────────────────++const KEY = process.env.OPENROUTER_API_KEY;+if (!KEY) {+ console.error("✗ OPENROUTER_API_KEY not set (expected in context-engine/.env).");+ process.exit(1);+}+if (!existsSync(CONFIG.REPO)) {+ console.error(`✗ REPO not found: ${CONFIG.REPO}`);+ process.exit(1);+}++const client = new OpenAI({ apiKey: KEY, baseURL: "https://openrouter.ai/api/v1" });++interface Metrics {+ arm: string;+ llmCalls: number;+ promptTokens: number;+ completionTokens: number;+ toolCalls: number;+ filesRead: Set<string>;+ ms: number;+ answer: string;+}++const SYSTEM =+ "You are a senior engineer answering a question about an unfamiliar codebase. " ++ "Be accurate and cite specific files and functions. When you have enough to answer, " ++ "STOP calling tools and write the final answer as prose. Do not pad.";++const TOOLS: OpenAI.Chat.Completions.ChatCompletionTool[] = [+ {+ type: "function",+ function: {+ name: "search",+ description:+ "Regex search across the repo's source (ripgrep). Returns matching file:line: text rows.",+ parameters: {+ type: "object",+ properties: { pattern: { type: "string", description: "regex or literal to search for" } },+ required: ["pattern"],+ },+ },+ },+ {+ type: "function",+ function: {+ name: "read_file",+ description: "Read a source file (optionally a line range) relative to the repo root.",+ parameters: {+ type: "object",+ properties: {+ path: { type: "string", description: "repo-relative path, e.g. src/components/chat/TaskFeed.tsx" },+ start_line: { type: "number", description: "1-based start line (optional)" },+ end_line: { type: "number", description: "1-based end line (optional)" },+ },+ required: ["path"],+ },+ },+ },+];++// ── tool implementations (sandboxed to REPO) ────────────────────────────────+function runSearch(pattern: string): string {+ const args = [+ "--no-heading", "-n", "-S", "--max-count", "40",+ "-g", "*.ts", "-g", "*.tsx", "-g", "!node_modules",+ pattern, CONFIG.REPO,+ ];+ let out = "";+ try {+ out = execFileSync("rg", args, { encoding: "utf8", maxBuffer: 8 << 20 });+ } catch (e: any) {+ // rg exits 1 on "no matches"; also handle rg-not-installed by falling back to grep.+ if (e?.code === "ENOENT") {+ try {+ out = execFileSync(+ "grep",+ ["-rniE", "--include=*.ts", "--include=*.tsx", "--exclude-dir=node_modules", pattern, CONFIG.REPO],+ { encoding: "utf8", maxBuffer: 8 << 20 },+ );+ } catch (g: any) {+ out = g?.stdout?.toString() ?? "";+ }+ } else {+ out = e?.stdout?.toString() ?? "";+ }+ }+ const lines = out.split("\n").filter(Boolean).map((l) => l.replace(CONFIG.REPO + "/", ""));+ if (lines.length === 0) return "(no matches)";+ const clipped = lines.slice(0, CONFIG.SEARCH_MAX_LINES);+ const note = lines.length > clipped.length ? `\n… ${lines.length - clipped.length} more rows omitted` : "";+ return clipped.join("\n") + note;+}++function runRead(path: string, start?: number, end?: number): { text: string; resolved: string } {+ const abs = isAbsolute(path) ? resolve(path) : resolve(CONFIG.REPO, path);+ const rel = relative(CONFIG.REPO, abs);+ if (rel.startsWith("..") || isAbsolute(rel)) return { text: `(refused: ${path} is outside the repo)`, resolved: rel };+ if (!existsSync(abs)) return { text: `(not found: ${rel})`, resolved: rel };+ let content = readFileSync(abs, "utf8");+ const allLines = content.split("\n");+ let lines = allLines;+ if (start || end) {+ const s = Math.max(1, start ?? 1);+ const e = Math.min(allLines.length, end ?? allLines.length);+ lines = allLines.slice(s - 1, e).map((l, i) => `${s + i}\t${l}`);+ }+ if (lines.length > CONFIG.READ_MAX_LINES) lines = lines.slice(0, CONFIG.READ_MAX_LINES);+ let text = lines.join("\n");+ if (text.length > CONFIG.READ_MAX_CHARS) text = text.slice(0, CONFIG.READ_MAX_CHARS) + "\n… (truncated)";+ return { text, resolved: rel };+}++// ── the agent loop, shared by both arms ──────────────────────────────────────+async function runAgent(arm: string, extraContext: string | null): Promise<Metrics> {+ const m: Metrics = {+ arm, llmCalls: 0, promptTokens: 0, completionTokens: 0, toolCalls: 0,+ filesRead: new Set(), ms: 0, answer: "",+ };+ const t0 = Date.now();++ const userParts = [`QUESTION:\n${CONFIG.QUESTION}`];+ if (extraContext) {+ userParts.push(+ "\nYou have been given a pre-computed context pack from a code-graph tool below. " ++ "Prefer it; only use the search/read_file tools if it is genuinely insufficient.\n\n" ++ "=== CONTEXT PACK ===\n" + extraContext,+ );+ }+ const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [+ { role: "system", content: SYSTEM },+ { role: "user", content: userParts.join("\n") },+ ];++ for (let step = 0; step < CONFIG.MAX_STEPS; step++) {+ const resp = await client.chat.completions.create({+ model: CONFIG.MODEL,+ temperature: 0,+ messages,+ tools: TOOLS,+ tool_choice: "auto",+ });+ m.llmCalls++;+ m.promptTokens += resp.usage?.prompt_tokens ?? 0;+ m.completionTokens += resp.usage?.completion_tokens ?? 0;++ const msg = resp.choices[0].message;+ messages.push(msg as OpenAI.Chat.Completions.ChatCompletionMessageParam);++ const calls = msg.tool_calls ?? [];+ if (calls.length === 0) {+ m.answer = msg.content ?? "(empty)";+ break;+ }++ for (const call of calls) {+ if (call.type !== "function") continue;+ m.toolCalls++;+ let result = "";+ try {+ const args = JSON.parse(call.function.arguments || "{}");+ if (call.function.name === "search") {+ result = runSearch(String(args.pattern ?? ""));+ } else if (call.function.name === "read_file") {+ const r = runRead(String(args.path ?? ""), args.start_line, args.end_line);+ if (existsSync(resolve(CONFIG.REPO, String(args.path ?? "")))) m.filesRead.add(r.resolved);+ result = r.text;+ } else {+ result = `(unknown tool ${call.function.name})`;+ }+ } catch (e: any) {+ result = `(tool error: ${e?.message ?? e})`;+ }+ messages.push({ role: "tool", tool_call_id: call.id, content: result });+ }+ if (step === CONFIG.MAX_STEPS - 1) m.answer = "(hit MAX_STEPS without a final answer)";+ }++ m.ms = Date.now() - t0;+ return m;+}++// ── graft pack for the GRAFT arm ─────────────────────────────────────────────+function graftPack(): { pack: string; ms: number } {+ const t0 = Date.now();+ if (!existsSync(resolve(CONFIG.REPO, "graft"))) {+ console.error(`✗ no graft/ index in ${CONFIG.REPO}. Run: cd ${CONFIG.REPO} && graft build`);+ process.exit(1);+ }+ const pack = execFileSync("graft", ["ask", CONFIG.QUESTION, CONFIG.REPO, "--source"], {+ encoding: "utf8",+ maxBuffer: 16 << 20,+ });+ return { pack, ms: Date.now() - t0 };+}++function cost(m: Metrics): string {+ if (!CONFIG.PRICE_IN_PER_M && !CONFIG.PRICE_OUT_PER_M) return "—";+ const c = (m.promptTokens / 1e6) * CONFIG.PRICE_IN_PER_M + (m.completionTokens / 1e6) * CONFIG.PRICE_OUT_PER_M;+ return "$" + c.toFixed(4);+}++function row(label: string, a: string | number, b: string | number): string {+ return `${label.padEnd(22)} ${String(a).padStart(14)} ${String(b).padStart(14)}`;+}++async function main() {+ console.log(`\nREPO: ${CONFIG.REPO}`);+ console.log(`MODEL: ${CONFIG.MODEL}`);+ console.log(`QUESTION: ${CONFIG.QUESTION.slice(0, 100)}…\n`);++ console.log("→ generating graft pack (graft ask --source)…");+ const { pack, ms: graftMs } = graftPack();+ const packTokEst = Math.round(pack.length / 4); // rough: ~4 chars/token+ console.log(` pack: ${pack.length} chars (~${packTokEst} tok), produced in ${graftMs}ms ($0, local)\n`);++ console.log("→ running COLD arm (agent explores the repo itself)…");+ const cold = await runAgent("COLD", null);+ console.log(` done in ${cold.ms}ms, ${cold.llmCalls} LLM calls\n`);++ console.log("→ running GRAFT arm (agent handed the pack up front)…");+ const graft = await runAgent("GRAFT", pack);+ console.log(` done in ${graft.ms}ms, ${graft.llmCalls} LLM calls\n`);++ const totC = cold.promptTokens + cold.completionTokens;+ const totG = graft.promptTokens + graft.completionTokens;+ const pct = (a: number, b: number) => (a === 0 ? "—" : `${Math.round((1 - b / a) * 100)}%`);++ console.log("═".repeat(54));+ console.log(row("metric", "COLD", "GRAFT"));+ console.log("─".repeat(54));+ console.log(row("prompt tokens", cold.promptTokens, graft.promptTokens));+ console.log(row("completion tokens", cold.completionTokens, graft.completionTokens));+ console.log(row("TOTAL tokens", totC, totG));+ console.log(row("LLM round-trips", cold.llmCalls, graft.llmCalls));+ console.log(row("tool calls", cold.toolCalls, graft.toolCalls));+ console.log(row("files opened", cold.filesRead.size, graft.filesRead.size));+ console.log(row("wall-clock (ms)", cold.ms, graft.ms));+ console.log(row("est. cost", cost(cold), cost(graft)));+ console.log("─".repeat(54));+ console.log(`token saving with graft: ${pct(totC, totG)} (COLD→GRAFT)`);+ console.log("═".repeat(54));++ console.log("\n──────── COLD answer ────────\n" + cold.answer);+ console.log("\n──────── GRAFT answer ────────\n" + graft.answer);+ console.log("\n(Judge the two answers yourself — the point is equal quality at fewer tokens.)");+}++main().catch((e) => {+ console.error(e);+ process.exit(1);+});diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex 1ea98941..f5cbf4e8 100644--- a/src/ask/ask.ts+++ b/src/ask/ask.ts@@ -46,6 +46,10 @@ export interface AskResult {subject?: string;hits: AskHit[];note?: string;+ /** Token-saving estimate, set only in `--source` (retriever) mode: the whole+ * size of the distinct files these hits point into, i.e. the baseline cost of+ * reading them instead of this pack. Computed from file sizes stored at build. */+ saved?: { files: number; baselineChars: number };}const STOP = new Set([@@ -286,6 +290,39 @@ function inlineSource(root: string, hits: AskHit[]): void {}}+/** Every repo-relative file path a set of hits points into (dedup). A symbol+ * pointer is `path:span`; a concept pointer is a comma-joined path list. */+function hitFiles(hits: AskHit[]): Set<string> {+ const files = new Set<string>();+ for (const h of hits) {+ const span = parseSpan(h.pointer);+ if (span) { files.add(span.path); continue; }+ for (const p of h.pointer.split(",").map((s) => s.trim()))+ if (p && !p.includes(" ")) files.add(p);+ }+ return files;+}++/** Baseline = whole size of the files these hits cover, read from the sizes the+ * build stored on each file node. Zero when the graph predates the `chars` field+ * (a pre-upgrade index) — the caller then just omits the estimate. */+function baselineFor(hits: AskHit[], graph: GraphV1 | null): AskResult["saved"] | undefined {+ if (!graph) return undefined;+ const size = new Map<string, number>();+ for (const n of graph.nodes)+ if (n.kind === "file" && typeof n.chars === "number") size.set(n.path, n.chars);++ let baselineChars = 0;+ let files = 0;+ for (const path of hitFiles(hits)) {+ const c = size.get(path);+ if (c === undefined) continue;+ baselineChars += c;+ files++;+ }+ return files > 0 ? { files, baselineChars } : undefined;+}+/** Answer a query from the graft/ graph at `dir`. Deterministic, $0. */export function ask(dir: string, query: string, opts: AskOptions = {}): AskResult {const root = resolve(dir);@@ -300,10 +337,20 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResul} else {result = lexical(query, corpus, limit);}- if (opts.source) inlineSource(root, result.hits);+ if (opts.source) {+ inlineSource(root, result.hits);+ // The pack is truly substitutive only in retriever mode (spans inlined), so+ // the "vs reading whole files" estimate is only honest here.+ result.saved = baselineFor(result.hits, corpus.graph);+ }return result;}+/** Rough tokens for a byte length (≈ 4 chars/token; good enough for an estimate). */+function toTokens(chars: number): number {+ return Math.round(chars / 4);+}+/** Render an {@link AskResult} as a compact markdown context pack. */export function formatAsk(r: AskResult): string {const head = `graft ask — "${r.query}" (${r.mode}${r.note ? `: ${r.note}` : ""})`;@@ -327,5 +374,23 @@ export function formatAsk(r: AskResult): string {lines.push("");});}- return lines.join("\n").trimEnd() + "\n";+ const body = lines.join("\n").trimEnd();+ return body + savingsFooter(r, body) + "\n";+}++/** The one-line token-saving estimate `ask` appends in retriever mode, so the+ * agent gets the number for free in the tool output — no extra work on its end.+ * `packChars` is measured from the rendered body: exactly what the agent reads. */+function savingsFooter(r: AskResult, body: string): string {+ if (!r.saved || r.saved.baselineChars <= 0) return "";+ const pack = toTokens(body.length);+ const base = toTokens(r.saved.baselineChars);+ if (base <= pack) return ""; // no saving to claim (tiny files); stay quiet+ const saved = base - pack;+ const pct = Math.round((saved / base) * 100);+ return (+ `\n\n[graft] tokens saved ≈ ${saved.toLocaleString()} (${pct}%) — this pack ≈ ` ++ `${pack.toLocaleString()} tok vs reading the ${r.saved.files} source file(s) whole ≈ ` ++ `${base.toLocaleString()} tok. Estimate (baseline = those files read in full).`+ );}diff --git a/src/claude/format.ts b/src/claude/format.tsindex fb4db79a..0fe852b4 100644--- a/src/claude/format.ts+++ b/src/claude/format.ts@@ -25,7 +25,7 @@ export function freshnessSegment(s: Stats): string {export function renderStatusline(stats: Stats | null,- _session: SessionState | null,+ session: SessionState | null,ctx: { ctxPct: number | null },): string[] {if (!stats || stats.nodeCount === 0) {@@ -35,6 +35,8 @@ export function renderStatusline(const enr = enrichedSegment(stats);if (enr) top.push(enr);top.push(freshnessSegment(stats));+ const saved = session?.savedTokens ?? 0;+ if (saved > 0) top.push(C.indigo(`~${saved.toLocaleString()} tok saved`));const bottom: string[] = [];if (typeof ctx.ctxPct === 'number') bottom.push(C.text(`ctx ${ctx.ctxPct}%`));@@ -74,18 +76,50 @@ export function formatBlastRadius(w: GraphV1, filePath: string, cap = 8): stringexport interface AskJson {query: string; mode: string;- hits: { kind: string; title: string; pointer: string; snippet: string; score: number }[];+ hits: { kind: string; title: string; pointer: string; snippet: string; score: number; code?: string }[];+ /** Set by `ask --source`: whole size of the files these hits cover (baseline). */+ saved?: { files: number; baselineChars: number };}-export function formatRetrieval(ask: AskJson, cap = 5): string | null {- const hits = (ask.hits ?? []).slice(0, cap);- if (!hits.length) return null;- const lines = hits.map((h) => {+function tokensOf(chars: number): number { return Math.round(chars / 4); }++/** The retrieval pack body — pointers, snippets, and (in --source mode) the+ * actual code span for each hit, so the agent reads it here instead of opening+ * the file. Kept separate so the tokens-saved math can measure this exact text. */+function retrievalBody(hits: AskJson['hits']): string {+ const blocks = hits.map((h, i) => {const ptr = (h.pointer ?? '').split(',')[0].trim();const snip = (h.snippet ?? '').replace(/\s+/g, ' ').trim().slice(0, 140);- return ` • ${h.title} — ${ptr} — ${snip}`;+ let b = ` ${i + 1}. ${h.title} — ${ptr}`;+ if (snip) b += `\n ${snip}`;+ if (h.code) b += `\n\`\`\`\n${h.code}\n\`\`\``;+ return b;});- return `[graft] relevant context for this prompt:\n${lines.join('\n')}`;+ return `[graft] retrieved context — read these spans, do not re-open the files:\n${blocks.join('\n')}`;+}++/** Tokens saved (baseline − this pack), or 0 when no honest estimate applies. */+export function retrievalTokensSaved(ask: AskJson, cap = 5): number {+ const hits = (ask.hits ?? []).slice(0, cap);+ if (!hits.length || !ask.saved || ask.saved.baselineChars <= 0) return 0;+ const pack = tokensOf(retrievalBody(hits).length);+ const base = tokensOf(ask.saved.baselineChars);+ return base > pack ? base - pack : 0;+}++export function formatRetrieval(ask: AskJson, cap = 5): string | null {+ const hits = (ask.hits ?? []).slice(0, cap);+ if (!hits.length) return null;+ const body = retrievalBody(hits);+ const saved = retrievalTokensSaved(ask, cap);+ if (saved <= 0) return body;+ const base = tokensOf(ask.saved!.baselineChars);+ const pct = Math.round((saved / base) * 100);+ return (+ `${body}\n[graft] tokens saved ≈ ${saved.toLocaleString()} (${pct}%) — this pack ≈ ` ++ `${tokensOf(body.length).toLocaleString()} tok vs reading the ${ask.saved!.files} file(s) whole ≈ ` ++ `${base.toLocaleString()} tok (estimate).`+ );}export function formatOrientation(indexMd: string, budgetBytes = 1500): string {diff --git a/src/claude/hooks.ts b/src/claude/hooks.tsindex ab800382..1da86cd3 100644--- a/src/claude/hooks.ts+++ b/src/claude/hooks.ts@@ -1,8 +1,8 @@-import { readFileSync } from 'node:fs';+import { readFileSync, existsSync } from 'node:fs';import { execFileSync, spawn } from 'node:child_process';import { join, basename } from 'node:path';import { readWiring } from './stats.js';-import { formatBlastRadius, formatRetrieval, formatOrientation } from './format.js';+import { formatBlastRadius, formatRetrieval, retrievalTokensSaved, formatOrientation } from './format.js';import { patchStats, readStats, acquireLock, readSession, writeSession } from './state.js';function readStdin(): any {@@ -19,9 +19,16 @@ export function underGraft(dir: string, file: string): boolean {const rel = file.startsWith(dir) ? file.slice(dir.length) : file;return rel.replace(/^[/\\]+/, '').replace(/\\/g, '/').startsWith('graft/');}+/** Resolve the graft CLI: the repo's own build when present (graft self-hosting),+ * else the globally-installed `graft` on PATH (any other repo using graft). */+function graftCli(dir: string): { cmd: string; pre: string[] } {+ const local = join(dir, 'dist', 'cli.js');+ return existsSync(local) ? { cmd: process.execPath, pre: [local] } : { cmd: 'graft', pre: [] };+}function graftJson(dir: string, args: string[]): any | null {+ const { cmd, pre } = graftCli(dir);try {- const out = execFileSync(process.execPath, [join(dir, 'dist', 'cli.js'), ...args],+ const out = execFileSync(cmd, [...pre, ...args],{ cwd: dir, encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] });return JSON.parse(out);} catch (e: any) {@@ -64,11 +71,15 @@ export async function main(event: string): Promise<void> {}if (event === 'stop') {+ // Auto-sync needs graft's own build (sync-run.js). Only graft's self-hosted+ // repo has it; in any other repo skip rather than spawn a missing script and+ // get wedged on syncing:true (those repos regen via their own build/CI).+ const syncRun = join(dir, 'dist', 'claude', 'sync-run.js');+ if (!existsSync(syncRun)) return;const stats = readStats(dir);if (stats?.dirty && acquireLock(dir)) {patchStats(dir, { syncing: true });- const child = spawn(process.execPath, [join(dir, 'dist', 'claude', 'sync-run.js'), dir],- { detached: true, stdio: 'ignore' });+ const child = spawn(process.execPath, [syncRun, dir], { detached: true, stdio: 'ignore' });child.unref();}return;@@ -77,7 +88,10 @@ export async function main(event: string): Promise<void> {if (event === 'prompt') {const prompt = String(input?.prompt ?? '').trim();if (prompt.length < 8) return;- const ask = graftJson(dir, ['ask', prompt, '.', '--json', '-n', '5']);+ // --source: inline the actual code spans so the injected pack is substitutive+ // (the agent reads the span here instead of opening the file), and so `ask`+ // returns the `saved` baseline used for the tokens-saved line.+ const ask = graftJson(dir, ['ask', prompt, '.', '--json', '--source', '-n', '5']);if (!ask) return;const txt = formatRetrieval(ask);if (!txt) return;@@ -85,6 +99,10 @@ export async function main(event: string): Promise<void> {const id = input.session_id || 'default';const s = readSession(dir, id);s.lastQuery = prompt;+ // Accumulate tokens saved this session (baseline − pack), so the statusline+ // can show a running total. Guarded: only when `ask` returned a baseline.+ const saved = retrievalTokensSaved(ask);+ if (saved > 0) s.savedTokens = (s.savedTokens ?? 0) + saved;const agent = input?.agent?.name;if (agent) s.perAgentQuery[agent] = prompt;writeSession(dir, id, s);diff --git a/src/claude/state.ts b/src/claude/state.tsindex 41374554..363e14e4 100644--- a/src/claude/state.ts+++ b/src/claude/state.ts@@ -11,6 +11,8 @@ export interface SessionState {lastQuery: string | null;perAgentQuery: Record<string, string>;graftReads: number; sourceReads: number;+ /** Cumulative tokens saved this session via `ask --source` retrieval (est.). */+ savedTokens: number;}export const LOCK_STALE_MS = 300000;@@ -20,7 +22,7 @@ export function emptyStats(): Stats {staleCount: 0, dirty: false, syncing: false, syncedAt: null, lastFile: null };}function emptySession(): SessionState {- return { lastQuery: null, perAgentQuery: {}, graftReads: 0, sourceReads: 0 };+ return { lastQuery: null, perAgentQuery: {}, graftReads: 0, sourceReads: 0, savedTokens: 0 };}export function cacheDir(projectDir: string): string { return join(projectDir, 'graft', '.cache'); }diff --git a/src/graph/extract.ts b/src/graph/extract.tsindex 029f06ed..ead49ba7 100644--- a/src/graph/extract.ts+++ b/src/graph/extract.ts@@ -106,6 +106,7 @@ export function extractFile(rel: string, source: string, lang: Language): Extracexported: true,origin: "ast",body_hash: contentHash(source),+ chars: source.length,summary_state: "pending",summary: null,crux: null,diff --git a/src/graph/types.ts b/src/graph/types.tsindex 39cc33db..fd17bfb9 100644--- a/src/graph/types.ts+++ b/src/graph/types.ts@@ -47,6 +47,8 @@ export interface NodeV1 {exported: boolean;origin: "ast";body_hash: string; // sha256 of the definition text; the Tier-2 re-run trigger+ chars?: number; // byte length of the WHOLE file (file nodes only); the baseline+ // `ask` uses to estimate tokens saved vs reading the file whole// meaning (Tier-2, one LLM call)summary_state: SummaryState;diff --git a/test/claude-format.test.ts b/test/claude-format.test.tsindex 7d938b87..3366d1d1 100644--- a/test/claude-format.test.ts+++ b/test/claude-format.test.ts@@ -68,11 +68,20 @@ test('formatRetrieval renders top hits, trims snippet, first pointer only', () ={ kind: 'concept', title: 'PKCE', pointer: 'src/pkce.ts, src/client.ts', snippet: 'Validates the challenge.', score: 1 },] } as any;const txt = strip(formatRetrieval(ask)!);- assert.match(txt, /relevant context/);- assert.match(txt, /PKCE — src\/pkce\.ts — Validates the challenge\./);+ assert.match(txt, /retrieved context/);+ assert.match(txt, /PKCE — src\/pkce\.ts/);+ assert.match(txt, /Validates the challenge\./); // snippet trimmed, own lineassert.doesNotMatch(txt, /client\.ts/); // only the first pointer segment});+test('formatRetrieval appends a tokens-saved line when ask reports a baseline', () => {+ const ask = { query: 'pkce', mode: 'lexical', saved: { files: 1, baselineChars: 8000 }, hits: [+ { kind: 'symbol', title: 'verify', pointer: 'src/pkce.ts:L1-L4', snippet: 's', score: 1, code: 'a\nb' },+ ] } as any;+ const txt = strip(formatRetrieval(ask)!);+ assert.match(txt, /tokens saved ≈ [\d,]+ \(\d+%\)/);+});+test('formatRetrieval returns null for no hits', () => {assert.equal(formatRetrieval({ query: 'x', mode: 'empty', hits: [] } as any), null);});diff --git a/test/claude-state.test.ts b/test/claude-state.test.tsindex 397ff1f0..23e7607f 100644--- a/test/claude-state.test.ts+++ b/test/claude-state.test.ts@@ -24,7 +24,7 @@ test('stats round-trip and patch merge', () => {test('session defaults and round-trip', () => {const d = fresh();const s = readSession(d, 'abc');- assert.deepEqual(s, { lastQuery: null, perAgentQuery: {}, graftReads: 0, sourceReads: 0 });+ assert.deepEqual(s, { lastQuery: null, perAgentQuery: {}, graftReads: 0, sourceReads: 0, savedTokens: 0 });s.lastQuery = 'pkce'; s.graftReads = 2;writeSession(d, 'abc', s);assert.equal(readSession(d, 'abc').lastQuery, 'pkce');