context-doctor 0.19.0 → 0.20.0

package/dist/autopilot.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `context-doctor autopilot on|off|pause|resume|status`
+ *
+ * Puts the proxy, in autopilot mode, in front of every Claude Code session on
+ * this machine, as a background service that starts at login and restarts if
+ * it dies, then points Claude Code at it through ~/.claude/settings.json.
+ *
+ * Order matters, because a base URL pointing at a dead port breaks every new
+ * session: the service is installed and must answer /health BEFORE settings
+ * are touched, and `off` removes the setting BEFORE stopping the service.
+ * `pause` leaves everything wired and makes the proxy a pure passthrough,
+ * which is the way to switch autopilot off without breaking sessions that
+ * are already running against it.
+ *
+ * What this cannot reach, stated rather than implied: Claude Desktop's chat
+ * tab and claude.ai (their requests leave from Anthropic's app, not from a
+ * process that reads settings.json), Cursor's own models (sent from Cursor's
+ * servers), and Codex signed in with ChatGPT (its traffic goes to ChatGPT's
+ * backend, not an API base URL).
+ */
+export declare const DEFAULT_AUTOPILOT_PORT = 8787;
+export interface AutopilotPaths {
+    settings: string;
+    config: string;
+    pauseFile: string;
+    statePath: string;
+    log: string;
+}
+export declare function autopilotPaths(home?: string): AutopilotPaths;
+export declare function proxyUrl(port: number): string;
+/** The command the service runs. Absolute paths: services start with an empty PATH. */
+export declare function serviceCommand(node: string, cli: string, port: number, paths: AutopilotPaths): string[];
+export declare function launchdPlist(args: string[], log: string): string;
+export declare function systemdUnit(args: string[], log: string): string;
+export declare function windowsTaskCommand(args: string[]): string;
+export declare function startDetached(args: string[], log: string): void;
+export interface Health {
+    ok: boolean;
+    autopilot?: boolean;
+    version?: string;
+}
+export declare function health(port: number, timeoutMs?: number): Promise<Health>;
+export declare function currentCli(): string;
+export declare function autopilotOn(port?: number, paths?: AutopilotPaths): Promise<{
+    ok: boolean;
+    lines: string[];
+}>;
+export declare function autopilotOff(paths?: AutopilotPaths): Promise<string[]>;
+export declare function autopilotPause(paused: boolean, paths?: AutopilotPaths): string;
+export declare function autopilotStatus(paths?: AutopilotPaths): Promise<string[]>;
+/**
+ * Called by the every-prompt hook: if autopilot is on and the proxy is down,
+ * start it before the prompt's request goes out. Returns quickly either way.
+ */
+export declare function ensureProxyUp(paths?: AutopilotPaths): Promise<void>;

package/dist/autopilot.js

@@ -0,0 +1,325 @@
+/**
+ * `context-doctor autopilot on|off|pause|resume|status`
+ *
+ * Puts the proxy, in autopilot mode, in front of every Claude Code session on
+ * this machine, as a background service that starts at login and restarts if
+ * it dies, then points Claude Code at it through ~/.claude/settings.json.
+ *
+ * Order matters, because a base URL pointing at a dead port breaks every new
+ * session: the service is installed and must answer /health BEFORE settings
+ * are touched, and `off` removes the setting BEFORE stopping the service.
+ * `pause` leaves everything wired and makes the proxy a pure passthrough,
+ * which is the way to switch autopilot off without breaking sessions that
+ * are already running against it.
+ *
+ * What this cannot reach, stated rather than implied: Claude Desktop's chat
+ * tab and claude.ai (their requests leave from Anthropic's app, not from a
+ * process that reads settings.json), Cursor's own models (sent from Cursor's
+ * servers), and Codex signed in with ChatGPT (its traffic goes to ChatGPT's
+ * backend, not an API base URL).
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEphemeralPath, readJson, writeJsonWithBackup } from "./install.js";
+import { formatTokens } from "./tokens.js";
+export const DEFAULT_AUTOPILOT_PORT = 8787;
+const LABEL = "com.gai-ventures.context-doctor.proxy";
+export function autopilotPaths(home = homedir()) {
+    const dir = join(home, ".claude");
+    return {
+        settings: join(dir, "settings.json"),
+        config: join(dir, ".context-doctor-autopilot.json"),
+        pauseFile: join(dir, ".context-doctor-autopilot-paused"),
+        statePath: join(dir, ".context-doctor-autopilot-cleared.json"),
+        log: join(dir, ".context-doctor-proxy.log"),
+    };
+}
+export function proxyUrl(port) {
+    return `http://127.0.0.1:${port}`;
+}
+/** The command the service runs. Absolute paths: services start with an empty PATH. */
+export function serviceCommand(node, cli, port, paths) {
+    return [node, cli, "proxy", "--autopilot", "--port", String(port), "--autopilot-state", paths.statePath, "--autopilot-pause-file", paths.pauseFile];
+}
+export function launchdPlist(args, log) {
+    const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args.map((a) => `    <string>${esc(a)}</string>`).join("\n")}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>5</integer>
+  <key>StandardOutPath</key><string>${esc(log)}</string>
+  <key>StandardErrorPath</key><string>${esc(log)}</string>
+</dict>
+</plist>
+`;
+}
+export function systemdUnit(args, log) {
+    const q = (s) => (/[\s"\\]/.test(s) ? `"${s.replace(/(["\\])/g, "\\$1")}"` : s);
+    return `[Unit]
+Description=context-doctor proxy (autopilot)
+
+[Service]
+ExecStart=${args.map(q).join(" ")}
+Restart=always
+RestartSec=2
+StandardOutput=append:${log}
+StandardError=append:${log}
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function windowsTaskCommand(args) {
+    return args.map((a) => `"${a}"`).join(" ");
+}
+function servicePaths(home = homedir()) {
+    return {
+        plist: join(home, "Library", "LaunchAgents", `${LABEL}.plist`),
+        unit: join(home, ".config", "systemd", "user", "context-doctor-proxy.service"),
+    };
+}
+function uid() {
+    return String(process.getuid?.() ?? "");
+}
+function run(cmd, args) {
+    execFileSync(cmd, args, { stdio: "ignore" });
+}
+function tryRun(cmd, args) {
+    try {
+        run(cmd, args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Install and start the background service for this platform. */
+function installService(args, log) {
+    const os = platform();
+    const sp = servicePaths();
+    if (os === "darwin") {
+        mkdirSync(dirname(sp.plist), { recursive: true });
+        writeFileSync(sp.plist, launchdPlist(args, log));
+        tryRun("launchctl", ["bootout", `gui/${uid()}`, sp.plist]);
+        run("launchctl", ["bootstrap", `gui/${uid()}`, sp.plist]);
+        return `launchd agent ${sp.plist}`;
+    }
+    if (os === "linux") {
+        mkdirSync(dirname(sp.unit), { recursive: true });
+        writeFileSync(sp.unit, systemdUnit(args, log));
+        if (tryRun("systemctl", ["--user", "daemon-reload"]) && tryRun("systemctl", ["--user", "enable", "--now", "context-doctor-proxy.service"])) {
+            tryRun("systemctl", ["--user", "restart", "context-doctor-proxy.service"]);
+            return `systemd user service ${sp.unit}`;
+        }
+        startDetached(args, log);
+        return "detached process (systemd --user unavailable; the every-prompt hook restarts it if it stops)";
+    }
+    if (os === "win32") {
+        tryRun("schtasks", ["/Create", "/F", "/SC", "ONLOGON", "/TN", "context-doctor-proxy", "/TR", windowsTaskCommand(args)]);
+        startDetached(args, log);
+        return "logon task context-doctor-proxy + detached process now";
+    }
+    startDetached(args, log);
+    return "detached process";
+}
+function removeService() {
+    const os = platform();
+    const sp = servicePaths();
+    if (os === "darwin") {
+        tryRun("launchctl", ["bootout", `gui/${uid()}`, sp.plist]);
+        if (existsSync(sp.plist))
+            rmSync(sp.plist);
+    }
+    else if (os === "linux") {
+        tryRun("systemctl", ["--user", "disable", "--now", "context-doctor-proxy.service"]);
+        if (existsSync(sp.unit))
+            rmSync(sp.unit);
+        tryRun("systemctl", ["--user", "daemon-reload"]);
+    }
+    else if (os === "win32") {
+        tryRun("schtasks", ["/Delete", "/F", "/TN", "context-doctor-proxy"]);
+    }
+}
+export function startDetached(args, log) {
+    mkdirSync(dirname(log), { recursive: true });
+    const out = openSync(log, "a");
+    const child = spawn(args[0], args.slice(1), { detached: true, stdio: ["ignore", out, out], windowsHide: true });
+    child.unref();
+}
+export async function health(port, timeoutMs = 800) {
+    try {
+        const r = await fetch(`${proxyUrl(port)}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+        const j = (await r.json());
+        return { ok: Boolean(j.ok && j.service === "context-doctor-proxy"), autopilot: j.autopilot, version: j.version };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+async function waitHealthy(port, ms) {
+    const end = Date.now() + ms;
+    for (;;) {
+        const h = await health(port);
+        if (h.ok && h.autopilot)
+            return h;
+        if (Date.now() > end)
+            return h;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}
+function readConfig(paths) {
+    try {
+        return readJson(paths.config);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function currentCli() {
+    return join(dirname(fileURLToPath(import.meta.url)), "cli.js");
+}
+export async function autopilotOn(port = DEFAULT_AUTOPILOT_PORT, paths = autopilotPaths()) {
+    const lines = [];
+    const cli = currentCli();
+    if (isEphemeralPath(cli)) {
+        return {
+            ok: false,
+            lines: [
+                "✗ Running from the npx cache, which npm deletes at will; a background service cannot point there.",
+                "  Install it once, then re-run:  npm install -g context-doctor && context-doctor autopilot on",
+            ],
+        };
+    }
+    const existing = await health(port);
+    if (existing.ok && !existing.autopilot) {
+        return { ok: false, lines: [`✗ A context-doctor proxy without autopilot is already on port ${port}. Stop it, or pass --port.`] };
+    }
+    if (!existing.ok) {
+        // Something that is not us on the port would receive Claude Code's traffic.
+        try {
+            await fetch(proxyUrl(port), { signal: AbortSignal.timeout(500) });
+            return { ok: false, lines: [`✗ Port ${port} is taken by another program. Pass --port <free port>.`] };
+        }
+        catch {
+            /* nothing listening: good */
+        }
+    }
+    const args = serviceCommand(process.execPath, cli, port, paths);
+    const how = installService(args, paths.log);
+    const h = await waitHealthy(port, 15_000);
+    if (!h.ok || !h.autopilot) {
+        removeService();
+        return { ok: false, lines: [`✗ The proxy did not come up on port ${port} (log: ${paths.log}). Nothing was changed in Claude Code's settings.`] };
+    }
+    lines.push(`✓ Proxy running with autopilot on ${proxyUrl(port)} (${how})`);
+    const settings = readJson(paths.settings);
+    const env = (settings.env ??= {});
+    const prev = readConfig(paths);
+    const previousBaseUrl = prev?.previousBaseUrl !== undefined ? prev.previousBaseUrl : (env.ANTHROPIC_BASE_URL ?? null);
+    if (previousBaseUrl && previousBaseUrl !== proxyUrl(port)) {
+        lines.push(`! settings.json already routed Claude Code to ${previousBaseUrl}; autopilot forwards to api.anthropic.com instead. \`autopilot off\` restores it.`);
+    }
+    env.ANTHROPIC_BASE_URL = proxyUrl(port);
+    writeJsonWithBackup(paths.settings, settings);
+    writeFileSync(paths.config, JSON.stringify({ port, previousBaseUrl, node: process.execPath, cli }, null, 2));
+    if (existsSync(paths.pauseFile))
+        rmSync(paths.pauseFile);
+    lines.push(`✓ Claude Code routed through it (env.ANTHROPIC_BASE_URL in ${paths.settings})`);
+    lines.push("  Applies to Claude Code sessions started from now on (CLI, IDE, and the desktop app's Code tab).");
+    lines.push("  Sessions already open keep their old route until restarted.");
+    lines.push(`  GPT apps on your own OpenAI key get the same: export OPENAI_BASE_URL=${proxyUrl(port)}/v1`);
+    return { ok: true, lines };
+}
+export async function autopilotOff(paths = autopilotPaths()) {
+    const lines = [];
+    const cfg = readConfig(paths);
+    const settings = readJson(paths.settings);
+    const env = settings.env;
+    if (env?.ANTHROPIC_BASE_URL && cfg && env.ANTHROPIC_BASE_URL === proxyUrl(cfg.port)) {
+        if (cfg.previousBaseUrl)
+            env.ANTHROPIC_BASE_URL = cfg.previousBaseUrl;
+        else
+            delete env.ANTHROPIC_BASE_URL;
+        if (Object.keys(env).length === 0)
+            delete settings.env;
+        writeJsonWithBackup(paths.settings, settings);
+        lines.push("✓ Claude Code no longer routed through the proxy (new sessions)");
+    }
+    removeService();
+    if (existsSync(paths.config))
+        rmSync(paths.config);
+    if (existsSync(paths.pauseFile))
+        rmSync(paths.pauseFile);
+    lines.push("✓ Background service removed");
+    lines.push("  Sessions started while autopilot was on still point at the proxy: restart them.");
+    lines.push("  To switch off without restarting anything, use `autopilot pause` instead.");
+    return lines;
+}
+export function autopilotPause(paused, paths = autopilotPaths()) {
+    if (paused) {
+        writeFileSync(paths.pauseFile, new Date().toISOString());
+        return "✓ Paused: the proxy now forwards every request unchanged. `autopilot resume` turns it back on.";
+    }
+    if (existsSync(paths.pauseFile))
+        rmSync(paths.pauseFile);
+    return "✓ Resumed: stale tool output is cleared again.";
+}
+export async function autopilotStatus(paths = autopilotPaths()) {
+    const cfg = readConfig(paths);
+    if (!cfg)
+        return ["Autopilot is off. `context-doctor autopilot on` turns it on for every new Claude Code session."];
+    const lines = [];
+    const h = await health(cfg.port);
+    const env = (readJson(paths.settings).env ?? {});
+    lines.push(`${h.ok ? "✓" : "✗"} Proxy ${proxyUrl(cfg.port)} ${h.ok ? `up (v${h.version ?? "?"})` : "NOT RESPONDING (the next Claude Code prompt restarts it via the hook)"}`);
+    lines.push(`${env.ANTHROPIC_BASE_URL === proxyUrl(cfg.port) ? "✓" : "✗"} Claude Code routed through it`);
+    if (existsSync(paths.pauseFile))
+        lines.push("! Paused: requests pass through unchanged");
+    if (h.ok) {
+        try {
+            const s = (await fetch(`${proxyUrl(cfg.port)}/stats`, { signal: AbortSignal.timeout(1000) }).then((r) => r.json()));
+            const a = s.autopilot;
+            if (a) {
+                lines.push("");
+                lines.push(`Since ${s.startedAt.slice(0, 16).replace("T", " ")} UTC: ${a.requests} requests, ${a.changedRequests} sent lighter`);
+                lines.push(`  ${a.resultsCleared} stale tool outputs cleared in ${a.batches} batches (${a.coldBatches} while the cache was cold anyway)`);
+                lines.push(`  ~${formatTokens(a.tokensRemoved)} tokens not sent`);
+                const billed = s.upstreamInputTokens + s.upstreamCacheReadTokens + s.upstreamCacheWriteTokens;
+                if (billed > 0)
+                    lines.push(`  Billed input: ${formatTokens(billed)} (${Math.round((s.upstreamCacheReadTokens / billed) * 100)}% cache reads)`);
+                if (a.lastReason)
+                    lines.push(`  Last decision: ${a.lastReason}`);
+            }
+        }
+        catch {
+            /* stats are informational */
+        }
+    }
+    return lines;
+}
+/**
+ * Called by the every-prompt hook: if autopilot is on and the proxy is down,
+ * start it before the prompt's request goes out. Returns quickly either way.
+ */
+export async function ensureProxyUp(paths = autopilotPaths()) {
+    const cfg = readConfig(paths);
+    if (!cfg)
+        return;
+    if ((await health(cfg.port, 300)).ok)
+        return;
+    if (!existsSync(cfg.node) || !existsSync(cfg.cli))
+        return;
+    startDetached(serviceCommand(cfg.node, cfg.cli, cfg.port, paths), paths.log);
+    await waitHealthy(cfg.port, 2500);
+}

package/dist/cli.js

@@ -21,6 +21,7 @@ import { listSessions, parseSessionFile } from "./session.js";
 import { runHook } from "./hook.js";
 import { buildImpactReport } from "./impact.js";
 import { measureTokenizer, renderTokenizer } from "./tokenizer-measure.js";
+import { autopilotOff, autopilotOn, autopilotPause, autopilotStatus, DEFAULT_AUTOPILOT_PORT } from "./autopilot.js";
 import { renderPreferences, copyToClipboard, CHAT_PREFERENCES } from "./preferences.js";
 import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
@@ -48,6 +49,10 @@ Usage:
   context-doctor install                        Wire the MCP server + skill into Claude Desktop,
                                                 Claude Code, and Cursor automatically
   context-doctor uninstall                      Undo install
+  context-doctor autopilot on|off|pause|resume|status
+                                                Every new Claude Code session goes through the
+                                                local proxy, which clears stale tool output only
+                                                when the prompt cache is cold (never costs more)
   context-doctor instructions [--copy]          Standing context rules to paste into claude.ai or
                                                 ChatGPT preferences (works on web and mobile too)
   context-doctor session [file]                 Profile a Claude Code session transcript or a
@@ -206,6 +211,15 @@ function parseArgs(argv) {
             case "--token":
                 args.token = argv[++i];
                 break;
+            case "--autopilot":
+                args.autopilot = true;
+                break;
+            case "--autopilot-state":
+                args.autopilotState = argv[++i];
+                break;
+            case "--autopilot-pause-file":
+                args.autopilotPauseFile = argv[++i];
+                break;
             case "--config":
                 args.config = argv[++i];
                 break;
@@ -252,7 +266,7 @@ function readInput(file) {
         return readFileSync(0, "utf8");
     return readFileSync(file, "utf8");
 }
-function main() {
+async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.command === "hook") {
         void runHook();
@@ -445,6 +459,30 @@ function main() {
             process.exitCode = 1;
         return;
     }
+    if (args.command === "autopilot") {
+        const sub = args.file ?? "status";
+        const port = args.port ?? DEFAULT_AUTOPILOT_PORT;
+        if (sub === "on") {
+            const r = await autopilotOn(port);
+            console.log(r.lines.join("\n"));
+            if (!r.ok)
+                process.exitCode = 1;
+        }
+        else if (sub === "off") {
+            console.log((await autopilotOff()).join("\n"));
+        }
+        else if (sub === "pause" || sub === "resume") {
+            console.log(autopilotPause(sub === "pause"));
+        }
+        else if (sub === "status") {
+            console.log((await autopilotStatus()).join("\n"));
+        }
+        else {
+            console.error("Usage: context-doctor autopilot on|off|pause|resume|status [--port n]");
+            process.exitCode = 1;
+        }
+        return;
+    }
     if (args.command === "instructions") {
         console.log(renderPreferences(args.copy ? copyToClipboard(CHAT_PREFERENCES) : undefined));
         return;
@@ -470,6 +508,9 @@ function main() {
             port: args.port,
             host: args.host,
             token: args.token ?? process.env.CONTEXT_DOCTOR_PROXY_TOKEN,
+            autopilot: args.autopilot,
+            autopilotStatePath: args.autopilotState,
+            autopilotPauseFile: args.autopilotPauseFile,
             anthropicUpstream: args.upstreamAnthropic,
             openaiUpstream: args.upstreamOpenai,
             strategies: args.strategies.length > 0 ? args.strategies : loadedRc.config.strategies,
@@ -556,4 +597,4 @@ function main() {
     console.log(HELP);
     process.exit(1);
 }
-main();
+void main();

package/dist/doctor.js

@@ -5,6 +5,7 @@
  * check, so "it doesn't work" becomes a single pasteable diagnosis. Always
  * exits 0 — absence of an app is a note, not a failure.
  */
+import { autopilotPaths, health, proxyUrl } from "./autopilot.js";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
@@ -209,6 +210,27 @@ export async function runDoctor() {
         checks.push({ label: "Project config", status: "skip", detail: "no .contextdoctorrc (optional; create one with: context-doctor init <preset>)" });
     }
     checks.push(await checkMcpHandshake());
+    // Autopilot: optional, so "off" is a skip, not a failure. When it is on, a
+    // dead proxy or a settings file pointing elsewhere is a real problem.
+    {
+        const paths = autopilotPaths();
+        if (!existsSync(paths.config)) {
+            checks.push({ label: "Autopilot", status: "skip", detail: "off (context-doctor autopilot on: clears stale tool output in every new Claude Code session)" });
+        }
+        else {
+            const cfg = JSON.parse(readFileSync(paths.config, "utf8"));
+            const h = await health(cfg.port);
+            let routed = false;
+            try {
+                routed = JSON.parse(readFileSync(paths.settings, "utf8"))?.env?.ANTHROPIC_BASE_URL === proxyUrl(cfg.port);
+            }
+            catch { /* reported below */ }
+            const paused = existsSync(paths.pauseFile);
+            checks.push(h.ok && h.autopilot && routed
+                ? { label: "Autopilot", status: "ok", detail: `proxy up on ${proxyUrl(cfg.port)}, Claude Code routed through it${paused ? " (PAUSED: passthrough)" : ""}` }
+                : { label: "Autopilot", status: "fail", detail: !h.ok ? `proxy not answering on ${proxyUrl(cfg.port)}: the next Claude Code prompt restarts it; or run: context-doctor autopilot on` : "settings.json no longer routes Claude Code to the proxy: run context-doctor autopilot on" });
+        }
+    }
     const mark = { ok: "✓", fail: "✗", skip: "–" };
     console.log("CONTEXT DOCTOR — self-check");
     console.log("═".repeat(56));

package/dist/hook.js

@@ -18,6 +18,7 @@ import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
 import { formatTokens, CHARS_PER_TOKEN } from "./tokens.js";
+import { ensureProxyUp } from "./autopilot.js";
 import { formatUsd } from "./pricing.js";
 import { checkBudget, loadConfig } from "./config.js";
 /** Default nudge threshold; a project budget or env var can lower/raise it. */
@@ -121,7 +122,12 @@ async function readStdin() {
 export async function runHook() {
     // A hook must never break the user's prompt: any failure exits silently.
     try {
+        // Autopilot self-heal: this prompt's request is about to go to the proxy,
+        // so if the proxy died, start it now. One existsSync when autopilot is
+        // off; a ~1ms localhost health check when it is on and healthy.
+        const heal = ensureProxyUp().catch(() => undefined);
         const input = JSON.parse(await readStdin());
+        await heal;
         const transcriptPath = input.transcript_path;
         if (!transcriptPath || !existsSync(transcriptPath))
             return;

package/dist/index.d.ts

@@ -21,3 +21,5 @@ export { renderStatusLine, tailUsage } from "./statusline.js";
 export * from "./sketch.js";
 export * from "./preferences.js";
 export * from "./tokenizer-measure.js";
+export * from "./autoclear.js";
+export * from "./autopilot.js";

package/dist/index.js

@@ -16,3 +16,5 @@ export { renderStatusLine, tailUsage } from "./statusline.js";
 export * from "./sketch.js";
 export * from "./preferences.js";
 export * from "./tokenizer-measure.js";
+export * from "./autoclear.js";
+export * from "./autopilot.js";

package/dist/install.d.ts

@@ -20,6 +20,10 @@ export declare function npxLauncher(platformName: string): {
     command: string;
     args: string[];
 };
+export declare function readJson(path: string): Record<string, any>;
+export declare function writeJsonWithBackup(path: string, data: Record<string, any>): void;
+/** Paths npm may delete at any time: the npx cache and the npm cache itself. */
+export declare function isEphemeralPath(path: string): boolean;
 /**
  * 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

package/dist/install.js

@@ -63,7 +63,7 @@ export function npxLauncher(platformName) {
         ? { command: "cmd", args: ["/c", "npx", "-y", "context-doctor-mcp"] }
         : { command: "npx", args: ["-y", "context-doctor-mcp"] };
 }
-function readJson(path) {
+export function readJson(path) {
     if (!existsSync(path))
         return {};
     try {
@@ -73,7 +73,7 @@ function readJson(path) {
         throw new Error(`${path} exists but is not valid JSON — fix or remove it first (${e.message})`);
     }
 }
-function writeJsonWithBackup(path, data) {
+export function writeJsonWithBackup(path, data) {
     mkdirSync(dirname(path), { recursive: true });
     if (existsSync(path))
         copyFileSync(path, path + ".context-doctor.backup");
@@ -105,7 +105,7 @@ function binOnPath(name) {
     return null;
 }
 /** Paths npm may delete at any time: the npx cache and the npm cache itself. */
-function isEphemeralPath(path) {
+export function isEphemeralPath(path) {
     return /[\\/]_npx[\\/]/.test(path) || /[\\/]\.npm[\\/]/.test(path) || /[\\/]npm-cache[\\/]/i.test(path);
 }
 /**

package/dist/mcp.js

@@ -49,7 +49,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.19.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.20.0" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown, largest blocks, and actionable findings about wasted context (duplicates, oversized pastes or tool results, base64 blobs, long history). Two inputs, pass ONE: `conversation` (full OpenAI/Anthropic JSON or raw text, for agents, files and proxies) or `sketch` (for chat apps such as Claude Desktop or ChatGPT where you cannot export the conversation: the turn count plus the few blocks that matter, ~120 tokens to write). Call it whenever the user asks about token usage, context size, cost, speed or limits, and on your own once the conversation passes ~30 turns or holds 3+ large pastes. Act on the top finding in your reply.", {
         conversation: z.string().optional().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text. Omit in chat apps and pass `sketch`."),
         sketch: z.object({

package/dist/proxy.d.ts

@@ -32,9 +32,22 @@ export interface ProxyOptions extends OptimizeOptions {
      * constant time; a wrong or missing prefix gets 401 and no upstream call.
      */
     token?: string;
+    /**
+     * Autopilot: instead of the general strategies, run only the cache-aware
+     * stale-tool-output clearing (autoclear.ts), which replays of real sessions
+     * showed never costs more than it saves. Anthropic Messages, OpenAI Chat
+     * Completions and OpenAI Responses requests; everything else passes through.
+     */
+    autopilot?: boolean;
+    /** Where autopilot remembers cleared tool results across restarts. */
+    autopilotStatePath?: string;
+    /** While this file exists, autopilot forwards every request unchanged (instant, restart-free off switch). */
+    autopilotPauseFile?: string;
     anthropicUpstream?: string;
     openaiUpstream?: string;
 }
+/** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
+export declare const PROXY_VERSION = "0.20.0";
 /**
  * Remove a leading `/t/<token>` from a request path, or return undefined when
  * the prefix is absent or the token differs. The comparison is constant time
@@ -55,6 +68,21 @@ export interface ProxyStats {
     upstreamOutputTokens: number;
     /** Prompt-cache advisories observed on live traffic (unique, capped). */
     advice: string[];
+    /** Cache reads/writes reported upstream (Anthropic), so autopilot's effect on the cache is visible. */
+    upstreamCacheReadTokens: number;
+    upstreamCacheWriteTokens: number;
+    autopilot?: {
+        enabled: boolean;
+        paused: boolean;
+        requests: number;
+        changedRequests: number;
+        batches: number;
+        coldBatches: number;
+        resultsCleared: number;
+        /** Tokens removed from requests, summed over requests (what was not sent). */
+        tokensRemoved: number;
+        lastReason: string;
+    };
 }
 /** Per-model-prefix strategy overrides for the proxy (`--config`). */
 export interface RouteConfig {