context-doctor 0.13.5 → 0.14.2

package/dist/experiment.js

@@ -0,0 +1,214 @@
+/**
+ * `context-doctor experiment` — the fresh-vs-existing session harness.
+ *
+ * Everything else in this tool measures what is IN the context. None of it can
+ * say whether the task succeeded, so a smaller transcript can be a cheaper
+ * failure. This runs the same task twice against the same starting commit —
+ * once in a fresh session, once forked from an existing one — with the same
+ * model and tools, records what each was billed and how long it took, runs the
+ * same check command against each result, and puts the two side by side.
+ *
+ * It spends the user's Claude budget, so it refuses to start on a dirty tree,
+ * caps spend per arm, forks the existing session rather than mutating it, and
+ * resets the tree between arms only because it verified the tree was clean.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseSessionFile } from "./session.js";
+import { formatTokens } from "./tokens.js";
+import { formatUsd } from "./pricing.js";
+/** Where a test can point at a stub instead of the real CLI. */
+function claudeBinary() {
+    return process.env.CONTEXT_DOCTOR_CLAUDE_BIN ?? "claude";
+}
+function git(cwd, ...args) {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+/** Build the argv for one arm — exported so the dry run and the tests see exactly what runs. */
+export function claudeArgs(opts, arm) {
+    const args = ["-p", opts.task, "--output-format", "json", "--permission-mode", "acceptEdits"];
+    if (opts.model)
+        args.push("--model", opts.model);
+    args.push("--max-budget-usd", String(opts.budgetUsd ?? 1));
+    if (arm === "existing" && opts.existing)
+        args.push("--resume", opts.existing, "--fork-session");
+    return args;
+}
+function findTranscript(sessionId, cwd) {
+    // Claude Code keys project dirs by the cwd with separators replaced.
+    const projectDir = join(homedir(), ".claude", "projects", cwd.replace(/[\\/:]/g, "-"));
+    const candidate = join(projectDir, `${sessionId}.jsonl`);
+    return existsSync(candidate) ? candidate : undefined;
+}
+function runArm(opts, arm, cwd) {
+    const started = Date.now();
+    const proc = spawnSync(claudeBinary(), claudeArgs(opts, arm), {
+        cwd,
+        encoding: "utf8",
+        env: { ...process.env, CLAUDECODE: undefined },
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const base = {
+        arm, costUsd: 0, durationMs: Date.now() - started, turns: 0,
+        inputTokens: 0, cacheRead: 0, cacheWrite: 0, outputTokens: 0,
+    };
+    if (proc.error)
+        return { ...base, error: `could not run ${claudeBinary()}: ${proc.error.message}` };
+    let parsed;
+    try {
+        parsed = JSON.parse(proc.stdout);
+    }
+    catch {
+        return { ...base, error: `claude did not return JSON (exit ${proc.status}): ${(proc.stderr || proc.stdout).slice(0, 300)}` };
+    }
+    const usage = parsed.usage ?? {};
+    const result = {
+        ...base,
+        sessionId: parsed.session_id,
+        costUsd: num(parsed.total_cost_usd),
+        durationMs: num(parsed.duration_ms) || base.durationMs,
+        turns: num(parsed.num_turns),
+        inputTokens: num(usage.input_tokens),
+        cacheRead: num(usage.cache_read_input_tokens),
+        cacheWrite: num(usage.cache_creation_input_tokens),
+        outputTokens: num(usage.output_tokens),
+        error: parsed.is_error ? `claude reported an error: ${String(parsed.result ?? "").slice(0, 300)}` : undefined,
+    };
+    if (parsed.session_id) {
+        const transcript = findTranscript(parsed.session_id, cwd);
+        if (transcript) {
+            try {
+                result.liveContextTokens = parseSessionFile(transcript).reportedInputTokens;
+            }
+            catch {
+                /* the numbers above stand on their own */
+            }
+        }
+    }
+    if (opts.check) {
+        const check = spawnSync(opts.check, { cwd, shell: true, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        result.check = { command: opts.check, passed: check.status === 0, exitCode: check.status ?? -1 };
+    }
+    try {
+        result.diffStat = git(cwd, "diff", "--stat") || "(no changes)";
+    }
+    catch {
+        /* not a git repo after all; the arm still ran */
+    }
+    return result;
+}
+export function runExperiment(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    if (process.env.CLAUDECODE && !opts.dryRun) {
+        return { arms: [], refused: "This runs the claude CLI, which refuses to start inside another Claude Code session. Run the experiment from a regular terminal." };
+    }
+    let startCommit;
+    let clean = false;
+    try {
+        startCommit = git(cwd, "rev-parse", "HEAD");
+        clean = git(cwd, "status", "--porcelain") === "";
+    }
+    catch {
+        return { arms: [], refused: `${cwd} is not a git repository. The experiment needs a commit to reset to between arms.` };
+    }
+    // A dry run touches nothing, so a dirty tree only needs mentioning.
+    if (opts.dryRun)
+        return { arms: [], startCommit, treeClean: clean };
+    if (!clean && !opts.allowDirty) {
+        return { arms: [], refused: "Working tree has uncommitted changes. Both arms must start from the same commit, and the tree is reset between them — commit or stash first (or pass --allow-dirty to accept losing those changes)." };
+    }
+    const arms = [];
+    const reset = () => {
+        // Safe only because the tree was verified clean (or the user opted in).
+        git(cwd, "reset", "--hard", startCommit);
+        git(cwd, "clean", "-fd");
+    };
+    arms.push(runArm(opts, "fresh", cwd));
+    reset();
+    if (opts.existing) {
+        arms.push(runArm(opts, "existing", cwd));
+        reset();
+    }
+    return { arms, startCommit };
+}
+export function renderExperiment(result, opts) {
+    const lines = [];
+    lines.push("CONTEXT DOCTOR — fresh vs existing session");
+    lines.push("═".repeat(56));
+    if (result.refused) {
+        lines.push(`Refused: ${result.refused}`);
+        return lines.join("\n");
+    }
+    lines.push(`task:    ${opts.task}`);
+    if (result.startCommit)
+        lines.push(`commit:  ${result.startCommit.slice(0, 12)} (both arms start here)`);
+    if (opts.model)
+        lines.push(`model:   ${opts.model}`);
+    if (opts.check)
+        lines.push(`check:   ${opts.check}`);
+    lines.push(`budget:  ${formatUsd(opts.budgetUsd ?? 1)} per arm`);
+    if (opts.dryRun) {
+        lines.push("");
+        lines.push("Dry run. Commands that would execute:");
+        lines.push(`  fresh:    claude ${claudeArgs(opts, "fresh").map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ")}`);
+        if (opts.existing)
+            lines.push(`  existing: claude ${claudeArgs(opts, "existing").map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ")}`);
+        lines.push("  (tree is reset to the start commit after each arm)");
+        if (result.treeClean === false)
+            lines.push("  NOTE: the tree is dirty right now; a real run would refuse unless you commit, stash, or pass --allow-dirty.");
+        return lines.join("\n");
+    }
+    lines.push("");
+    const col = (s, w = 14) => s.padStart(w);
+    const header = `${"".padEnd(22)}${col("fresh")}${opts.existing ? col("existing") : ""}`;
+    lines.push(header);
+    lines.push("─".repeat(header.length));
+    const row = (label, pick) => {
+        lines.push(`${label.padEnd(22)}${result.arms.map((a) => col(pick(a))).join("")}`);
+    };
+    row("billed input", (a) => formatTokens(a.inputTokens + a.cacheRead + a.cacheWrite));
+    row("  of which cache read", (a) => formatTokens(a.cacheRead));
+    row("  of which cache write", (a) => formatTokens(a.cacheWrite));
+    row("output tokens", (a) => formatTokens(a.outputTokens));
+    row("cost", (a) => formatUsd(a.costUsd));
+    row("wall clock", (a) => `${(a.durationMs / 1000).toFixed(0)}s`);
+    row("turns", (a) => String(a.turns));
+    if (result.arms.some((a) => a.liveContextTokens))
+        row("live context (last)", (a) => (a.liveContextTokens ? formatTokens(a.liveContextTokens) : "—"));
+    if (opts.check)
+        row("check", (a) => (a.check ? (a.check.passed ? "PASS" : `FAIL (${a.check.exitCode})`) : "—"));
+    lines.push("");
+    for (const a of result.arms) {
+        if (a.error)
+            lines.push(`${a.arm}: ${a.error}`);
+        if (a.diffStat && a.diffStat !== "(no changes)")
+            lines.push(`${a.arm} changed:\n${a.diffStat.split("\n").map((l) => "  " + l).join("\n")}`);
+    }
+    // The verdict is the whole point: cheaper is only better if it also passed.
+    if (opts.existing && result.arms.length === 2 && opts.check) {
+        const [fresh, existing] = result.arms;
+        const cheaper = fresh.costUsd <= existing.costUsd ? fresh : existing;
+        const other = cheaper === fresh ? existing : fresh;
+        if (cheaper.check?.passed && !other.check?.passed) {
+            lines.push(`Verdict: ${cheaper.arm} was cheaper AND passed; ${other.arm} failed the check. Clear win for ${cheaper.arm}.`);
+        }
+        else if (cheaper.check?.passed && other.check?.passed) {
+            lines.push(`Verdict: both passed; ${cheaper.arm} was cheaper by ${formatUsd(Math.abs(fresh.costUsd - existing.costUsd))}.`);
+        }
+        else if (!cheaper.check?.passed && other.check?.passed) {
+            lines.push(`Verdict: ${cheaper.arm} was cheaper but FAILED the check. A smaller bill for a wrong answer is not a saving; ${other.arm} wins.`);
+        }
+        else {
+            lines.push("Verdict: neither arm passed the check. Cost comparison is moot until one does.");
+        }
+    }
+    else if (opts.check) {
+        lines.push("One arm only. Pass --existing <session-id> to compare against a forked existing session.");
+    }
+    return lines.join("\n");
+}

package/dist/install.d.ts

@@ -20,6 +20,13 @@ export declare function npxLauncher(platformName: string): {
     command: string;
     args: string[];
 };
+/**
+ * Claude Code's status bar: a `statusLine` command whose stdout is shown while
+ * the user types. Opt-in, because there is only one status line and it may
+ * already be someone's own — this never overwrites a statusLine that is not
+ * ours. Returns what happened so install can print the truth.
+ */
+export declare function installStatusLine(): "installed" | "already" | "kept-foreign" | "no-claude-code";
 /** Outcome of an install run, so the CLI can set a truthful exit code. */
 export interface InstallResult {
     /** Detected targets that could not be configured, with the reason. */
@@ -35,5 +42,7 @@ export interface InstallResult {
  * failed target is a lie that surfaces later as "the tools never showed up".
  * So: keep going, summarize, and return the failures for a non-zero exit.
  */
-export declare function runInstall(): InstallResult;
+export declare function runInstall(options?: {
+    statusLine?: boolean;
+}): InstallResult;
 export declare function runUninstall(): void;

package/dist/install.js

@@ -122,14 +122,54 @@ function isEphemeralPath(path) {
  * prompt. `node` (not process.execPath) keeps it alive across Node upgrades.
  */
 function hookCommand() {
+    return cliCommand("hook");
+}
+/** The same durable command resolution, for any subcommand Claude Code runs for us. */
+function cliCommand(subcommand) {
     const selfDir = dirname(fileURLToPath(import.meta.url));
     const localCli = join(selfDir, "cli.js");
     if (!isEphemeralPath(selfDir + sep) && existsSync(localCli))
-        return `node "${localCli}" hook`;
+        return `node "${localCli}" ${subcommand}`;
     const global = binOnPath("context-doctor");
     if (global)
-        return `"${global}" hook`;
-    return "npx -y context-doctor hook";
+        return `"${global}" ${subcommand}`;
+    return `npx -y context-doctor ${subcommand}`;
+}
+/**
+ * Claude Code's status bar: a `statusLine` command whose stdout is shown while
+ * the user types. Opt-in, because there is only one status line and it may
+ * already be someone's own — this never overwrites a statusLine that is not
+ * ours. Returns what happened so install can print the truth.
+ */
+export function installStatusLine() {
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    if (!existsSync(join(homedir(), ".claude")))
+        return "no-claude-code";
+    const settings = readJson(settingsPath);
+    const want = cliCommand("statusline");
+    const current = settings.statusLine?.command;
+    if (current === want)
+        return "already";
+    if (current && !isOurStatusLine(current))
+        return "kept-foreign";
+    settings.statusLine = { type: "command", command: want };
+    writeJsonWithBackup(settingsPath, settings);
+    return "installed";
+}
+function isOurStatusLine(command) {
+    return /context-doctor|cli\.js"?\s+statusline\s*$/.test(command);
+}
+function uninstallStatusLine() {
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    if (!existsSync(settingsPath))
+        return;
+    const settings = readJson(settingsPath);
+    const current = settings.statusLine?.command;
+    if (current && isOurStatusLine(current)) {
+        delete settings.statusLine;
+        writeJsonWithBackup(settingsPath, settings);
+        console.log("✓ Claude Code status line removed");
+    }
 }
 /** True when the hook had to fall back to npx — worth telling the user. */
 function hookUsesNpx() {
@@ -224,7 +264,7 @@ function installSkill() {
  * failed target is a lie that surfaces later as "the tools never showed up".
  * So: keep going, summarize, and return the failures for a non-zero exit.
  */
-export function runInstall() {
+export function runInstall(options = {}) {
     const entry = serverEntry();
     const found = targets().filter((t) => t.detect());
     if (found.length === 0) {
@@ -274,6 +314,28 @@ export function runInstall() {
         console.error(`✗ Claude Code every-prompt hook: ${e.message}`);
         failures.push("Claude Code hook");
     }
+    if (options.statusLine) {
+        try {
+            switch (installStatusLine()) {
+                case "installed":
+                    console.log("✓ Claude Code status line installed — live context size, cache share and cost while you type");
+                    break;
+                case "already":
+                    console.log("✓ Claude Code status line already installed");
+                    break;
+                case "kept-foreign":
+                    console.log("– Claude Code status line left alone: you already have your own statusLine command. Remove it first if you want ours.");
+                    break;
+                case "no-claude-code":
+                    console.log("– status line skipped: Claude Code not detected");
+                    break;
+            }
+        }
+        catch (e) {
+            console.error(`✗ Claude Code status line: ${e.message}`);
+            failures.push("Claude Code status line");
+        }
+    }
     if (failures.length > 0) {
         console.log(`\nDone with ${failures.length} problem(s): ${failures.join(", ")}. See the ✗ lines above.`);
         console.log("Everything else was installed. Exit code is 1 so scripts can tell; fix the file(s) and re-run install.");
@@ -306,6 +368,7 @@ export function runUninstall() {
         console.log("✓ Agent Skill removed");
     }
     uninstallHook();
+    uninstallStatusLine();
     // Remove our bookkeeping files too — uninstall means gone.
     for (const file of [".context-doctor-hook-state.json", ".context-doctor-ledger.jsonl"]) {
         const p = join(homedir(), ".claude", file);

package/dist/mcp.js

@@ -37,7 +37,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.13.5" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.14.2" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown by category, largest messages, and actionable findings about wasted context (duplicates, oversized tool results, base64 blobs, cache-unfriendly ordering). Accepts OpenAI/Anthropic conversation JSON or raw text. Call this immediately whenever the user asks about token usage, context size, LLM cost, or latency — and proactively offer it once a conversation grows long or accumulates large pasted content.", {
         conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text"),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),

package/dist/optimize.d.ts

@@ -13,6 +13,15 @@ export interface OptimizeOptions {
     keepRecent?: number;
     /** Max tokens a trimmed tool result — or tool-call argument set — keeps. */
     maxToolResultTokens?: number;
+    /**
+     * How many messages the trim boundary moves at a time. Bigger steps keep the
+     * prompt cache alive longer but leave stale results in place longer.
+     * Measured on a growing agent session: at 400 turns a step of 10 invalidated
+     * the cache on 21% of turns with ~2 stale results waiting on average; 20
+     * gave 12% and ~4; 40 gave 10% and ~9. Adaptive steps were worse everywhere,
+     * because a step that changes size moves the boundary by itself. Default 10.
+     */
+    trimBoundaryStep?: number;
 }
 export interface AppliedChange {
     strategy: StrategyId;

package/dist/optimize.js

@@ -9,10 +9,12 @@
 import { createHash } from "node:crypto";
 import { estimateTokens } from "./tokens.js";
 import { hasBase64Blob, stripBase64Blobs } from "./blob.js";
+const TRIM_BOUNDARY_STEP = 10;
 const DEFAULTS = {
     strategies: ["dedupe", "trim-tool-results", "strip-base64"],
     keepRecent: 6,
     maxToolResultTokens: 300,
+    trimBoundaryStep: TRIM_BOUNDARY_STEP,
 };
 /**
  * Shrink the arguments of a tool call that has already run.
@@ -25,6 +27,42 @@ const DEFAULTS = {
  * Keys are preserved (so the call still reads as itself) and only long string
  * values are cut, with an explicit marker so nothing looks silently complete.
  */
+/** The file a Write-like call creates, or null for anything else. */
+function writtenPath(block) {
+    if (block?.name === "Write" && typeof block.input?.file_path === "string")
+        return block.input.file_path;
+    const cmd = block?.name === "Bash" ? String(block.input?.command ?? "") : "";
+    const heredoc = /(?:cat|tee)\s*>+\s*([^\s<]+)\s*<</.exec(cmd);
+    return heredoc ? heredoc[1] : null;
+}
+/**
+ * Does the model later Edit this file without Reading it first? If so it is
+ * relying on the Write input still being in context, and trimming that input
+ * would break the Edit.
+ */
+function editedLaterWithoutRead(messages, writeIndex, path) {
+    if (!path)
+        return false;
+    for (let j = writeIndex + 1; j < messages.length; j++) {
+        const content = messages[j]?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const b of content) {
+            if (b?.type !== "tool_use")
+                continue;
+            const target = b.input?.file_path;
+            const cmd = b.name === "Bash" ? String(b.input?.command ?? "") : "";
+            const touchesPath = target === path || cmd.includes(path);
+            if (!touchesPath)
+                continue;
+            if (b.name === "Read" || /\b(cat|head|tail|sed|less)\b/.test(cmd))
+                return false; // it re-read: safe
+            if (b.name === "Edit" || b.name === "MultiEdit")
+                return true; // edited blind: keep the Write
+        }
+    }
+    return false;
+}
 function trimCallArguments(input, maxTokens) {
     const budgetChars = maxTokens * 4;
     const out = {};
@@ -54,17 +92,16 @@ function trimCallArguments(input, maxTokens) {
  * STEP turns instead of once per turn. Older content is trimmed slightly later
  * than it otherwise would be; that is much cheaper than losing the cache.
  */
-const TRIM_BOUNDARY_STEP = 10;
-function stableCutoff(messageCount, keepRecent) {
+function stableCutoff(messageCount, keepRecent, step = TRIM_BOUNDARY_STEP) {
     const raw = messageCount - keepRecent;
     if (raw <= 0)
         return 0;
     // Below one step there is nothing to quantize to except zero, which would
     // silently disable trimming on every short conversation. Such a conversation
     // has no long stable prefix worth protecting anyway.
-    if (raw < TRIM_BOUNDARY_STEP)
+    if (raw < step)
         return raw;
-    return Math.floor(raw / TRIM_BOUNDARY_STEP) * TRIM_BOUNDARY_STEP;
+    return Math.floor(raw / step) * step;
 }
 function hash(text) {
     return createHash("sha1").update(text.replace(/\s+/g, " ").trim()).digest("hex");
@@ -171,6 +208,7 @@ export function optimizeConversation(input, options = {}) {
         strategies: options.strategies ?? DEFAULTS.strategies,
         keepRecent: options.keepRecent ?? DEFAULTS.keepRecent,
         maxToolResultTokens: options.maxToolResultTokens ?? DEFAULTS.maxToolResultTokens,
+        trimBoundaryStep: options.trimBoundaryStep && options.trimBoundaryStep > 0 ? Math.floor(options.trimBoundaryStep) : DEFAULTS.trimBoundaryStep,
     };
     let data;
     try {
@@ -216,7 +254,7 @@ export function optimizeConversation(input, options = {}) {
         // their CURRENT question swapped for a pointer to a message ten turns back,
         // and just sees a worse answer with no explanation. Older copies are fair
         // game; the live turn is not.
-        const cutoff = stableCutoff(messages.length, opts.keepRecent);
+        const cutoff = stableCutoff(messages.length, opts.keepRecent, opts.trimBoundaryStep);
         const seen = new Map();
         messages.forEach((m, i) => {
             const text = textOf(m.content);
@@ -241,7 +279,7 @@ export function optimizeConversation(input, options = {}) {
     }
     // -- trim-tool-results: shrink stale tool output ------------------------------
     if (opts.strategies.includes("trim-tool-results")) {
-        const cutoff = stableCutoff(messages.length, opts.keepRecent);
+        const cutoff = stableCutoff(messages.length, opts.keepRecent, opts.trimBoundaryStep);
         messages.forEach((m, i) => {
             if (i >= cutoff || !isToolResultMessage(m))
                 return;
@@ -266,7 +304,7 @@ export function optimizeConversation(input, options = {}) {
     }
     // -- trim-tool-calls: shrink the arguments of calls that already ran ----------
     if (opts.strategies.includes("trim-tool-calls")) {
-        const cutoff = stableCutoff(messages.length, opts.keepRecent);
+        const cutoff = stableCutoff(messages.length, opts.keepRecent, opts.trimBoundaryStep);
         messages.forEach((m, i) => {
             if (i >= cutoff)
                 return;
@@ -276,6 +314,14 @@ export function optimizeConversation(input, options = {}) {
                 for (const b of m.content) {
                     if (b?.type !== "tool_use" || b.input == null || typeof b.input !== "object")
                         continue;
+                    // Measured across 42 real sessions: of 73 large Writes, 18 were later
+                    // Edited and 16 of those Edits had no Read in between — the model
+                    // built old_string from its own Write input, at a median distance of
+                    // 43 messages. Trimming such a Write turns that Edit into a failure
+                    // plus a recovery Read. Offline we can see the future, so leave
+                    // those alone; the 63% never touched again are still pure gain.
+                    if (editedLaterWithoutRead(messages, i, writtenPath(b)))
+                        continue;
                     const before = estimateTokens(JSON.stringify(b.input));
                     if (before <= opts.maxToolResultTokens)
                         continue;

package/dist/profile.d.ts

@@ -51,6 +51,14 @@ export interface ContextProfile {
     /** Present when the model has a known price. All figures are estimates. */
     cost?: CostEstimate;
     sourceFormat: string;
+    /**
+     * Present when estimates were scaled by a factor learned from this machine's
+     * own `--exact` counts for this model family. Absent means raw heuristic.
+     */
+    calibration?: {
+        factor: number;
+        samples: number;
+    };
     /** Propagated from parsing: input could not be read as a conversation. */
     parseWarning?: string;
 }

package/dist/profile.js

@@ -6,6 +6,7 @@ import { createHash } from "node:crypto";
 import { contextWindowFor, estimateTokens, MESSAGE_OVERHEAD_TOKENS, providerFor } from "./tokens.js";
 import { estimatedTtftSeconds, inputCostUsd, pricingFor } from "./pricing.js";
 import { hasBase64Blob } from "./blob.js";
+import { calibrationFor } from "./calibration.js";
 function categoryOf(m) {
     switch (m.kind) {
         case "system": return "system";
@@ -145,9 +146,11 @@ function filesReadBy(toolName, toolCallText) {
     return [...paths];
 }
 export function profileConversation(conv, model) {
+    // Learned from the user's own exact counts, if they ever fetched any.
+    const calibration = calibrationFor(model);
     const perMessage = conv.messages.map((m) => ({
         msg: m,
-        tokens: estimateTokens(m.text) + MESSAGE_OVERHEAD_TOKENS,
+        tokens: Math.round(estimateTokens(m.text) * calibration.factor) + MESSAGE_OVERHEAD_TOKENS,
     }));
     const totalTokens = perMessage.reduce((sum, p) => sum + p.tokens, 0);
     const categories = {
@@ -445,6 +448,7 @@ export function profileConversation(conv, model) {
         totalEstSavings,
         cost,
         sourceFormat: conv.sourceFormat,
+        calibration: calibration.samples > 0 ? calibration : undefined,
         parseWarning: conv.parseWarning,
     };
 }

package/dist/proxy.js

@@ -66,6 +66,8 @@ export function startProxy(opts = {}) {
     };
     /** Last stable-prefix fingerprint per model, for cache-invalidation advice. */
     const prefixFingerprints = new Map();
+    /** Per-message fingerprints of the previous request per model, for breakpoint placement. */
+    const messageFingerprints = new Map();
     const advise = (msg) => {
         if (stats.advice.includes(msg) || stats.advice.length >= 10)
             return;
@@ -117,14 +119,24 @@ export function startProxy(opts = {}) {
                                 strategies: route.strategies ?? opts.strategies,
                                 keepRecent: route.keepRecent ?? opts.keepRecent,
                                 maxToolResultTokens: route.maxToolResultTokens ?? opts.maxToolResultTokens,
+                                trimBoundaryStep: opts.trimBoundaryStep,
                             };
                         }
                         // Prompt-cache advisor (Anthropic requests): the proxy sees real
                         // sequences, so cache-hostile patterns are observable facts here.
                         if (url.startsWith("/v1/messages") && requestModel) {
                             const stablePrefix = JSON.stringify(parsedBody.tools ?? null) + JSON.stringify(parsedBody.system ?? null);
-                            if (stablePrefix.length > 4000 && !body.includes("cache_control")) {
-                                advise(`~${Math.round(stablePrefix.length / 4)}+ tokens of stable system/tools on ${requestModel} without cache_control — adding a breakpoint would cut those to ~10% cost per call`);
+                            const hasBreakpoint = body.includes("cache_control");
+                            if (stablePrefix.length > 4000 && !hasBreakpoint) {
+                                // Say WHERE, not just that. A breakpoint caches everything up
+                                // to and including the block it sits on, so it belongs on the
+                                // LAST stable block: the final tool definition if there are
+                                // tools, otherwise the final system block.
+                                const where = Array.isArray(parsedBody.tools) && parsedBody.tools.length > 0
+                                    ? `the last entry in "tools" (tools come before system in the cached prefix)`
+                                    : `the last block of "system"`;
+                                advise(`~${Math.round(stablePrefix.length / 4)}+ tokens of stable system/tools on ${requestModel} without cache_control. ` +
+                                    `Add {"cache_control":{"type":"ephemeral"}} to ${where}; everything before it then bills at ~10% on every call`);
                             }
                             const fp = fnv1a(stablePrefix);
                             const prev = prefixFingerprints.get(requestModel);
@@ -132,6 +144,31 @@ export function startProxy(opts = {}) {
                                 advise(`system/tools prefix changed between ${requestModel} requests — every change re-bills the whole cached prefix; keep it byte-stable`);
                             }
                             prefixFingerprints.set(requestModel, fp);
+                            // Second breakpoint: the conversation itself. Between two
+                            // consecutive requests the older messages are usually identical;
+                            // that run is cacheable too, and it is what re-bills every turn
+                            // when nothing marks it. Find the longest message prefix that
+                            // survived from the previous request and point at its last message.
+                            const msgs = Array.isArray(parsedBody.messages)
+                                ? parsedBody.messages
+                                : [];
+                            const hashes = msgs.map((m) => fnv1a(JSON.stringify(m)));
+                            const prevHashes = messageFingerprints.get(requestModel);
+                            if (prevHashes && !hasBreakpoint) {
+                                let stable = 0;
+                                while (stable < hashes.length && stable < prevHashes.length && hashes[stable] === prevHashes[stable])
+                                    stable++;
+                                if (stable >= 2) {
+                                    const stableChars = msgs.slice(0, stable).reduce((n, m) => n + JSON.stringify(m).length, 0);
+                                    const stableTokens = Math.round(stableChars / 4);
+                                    // Anthropic will not cache a prefix under ~1024 tokens (2048 on Haiku).
+                                    if (stableTokens >= 1024) {
+                                        advise(`messages #0-#${stable - 1} (~${stableTokens} tokens) were identical to the previous ${requestModel} request and carry no cache_control. ` +
+                                            `Put {"cache_control":{"type":"ephemeral"}} on the last content block of message #${stable - 1}; that run then reads from cache instead of re-billing each turn`);
+                                    }
+                                }
+                            }
+                            messageFingerprints.set(requestModel, hashes);
                         }
                     }
                     catch {

package/dist/report.js

@@ -37,6 +37,11 @@ export function renderProfile(profile, options = {}) {
         lines.push("");
     }
     lines.push(`Total: ~${formatTokens(p.totalTokens)} tokens across ${p.messageCount} messages (${p.sourceFormat} format)`);
+    if (p.calibration) {
+        // Scaled numbers must say so, or they read as the raw heuristic.
+        const pct = Math.round((p.calibration.factor - 1) * 100);
+        lines.push(`       estimates calibrated ${pct >= 0 ? "+" : ""}${pct}% from ${p.calibration.samples} exact count(s) you ran on this machine (analyze --exact)`);
+    }
     if (p.model) {
         const windowNote = p.contextWindow
             ? ` of ${formatTokens(p.contextWindow)} window (${p.usagePct.toFixed(1)}%)`

package/dist/session.d.ts

@@ -72,4 +72,16 @@ export interface ParsedSession {
 }
 /** All session transcripts on this machine, newest first. */
 export declare function listSessions(limit?: number): SessionInfo[];
+/**
+ * Read a JSONL transcript line by line without ever materializing the whole
+ * file as one string.
+ *
+ * Agent sessions with large tool results reach hundreds of MB, and those are
+ * exactly the sessions that most need analysis — but V8 refuses to build a
+ * string past ~512MB, so readFileSync would throw on them (and in the hook,
+ * throw *silently*). Streaming has no such ceiling and keeps peak memory at
+ * one chunk. StringDecoder carries partial UTF-8 sequences across chunk
+ * boundaries so multi-byte characters are never corrupted.
+ */
+export declare function forEachLine(path: string, onLine: (line: string) => void): void;
 export declare function parseSessionFile(path: string): ParsedSession;

package/dist/session.js

@@ -119,7 +119,7 @@ function parseChatGPTExport(data, path) {
  * one chunk. StringDecoder carries partial UTF-8 sequences across chunk
  * boundaries so multi-byte characters are never corrupted.
  */
-function forEachLine(path, onLine) {
+export function forEachLine(path, onLine) {
     const fd = openSync(path, "r");
     const decoder = new StringDecoder("utf8");
     const buf = Buffer.allocUnsafe(4 * 1024 * 1024);