context-doctor 0.18.0 → 0.20.0

package/dist/autoclear.js

@@ -0,0 +1,295 @@
+/**
+ * Autopilot: clear stale tool output from agent requests in flight, without
+ * ever costing more than it saves.
+ *
+ * Why this and not the proxy's general strategies: replayed over 33 real
+ * Claude Code sessions with prompt-cache pricing, the general trim saved 6.7%
+ * overall but made one session 13% MORE expensive, because every change to
+ * history the cache already holds re-bills everything after it at the write
+ * rate. Most of the bill sits in long sessions (94% of input cost came from
+ * requests above 200k tokens), so the win is real, but only if each change
+ * pays for its cache rewrite.
+ *
+ * The rules, modelled on the microcompact logic Claude Code ships (and keeps
+ * switched off by a server flag), tightened for "never worse":
+ *
+ *  1. Only output of read-only, re-runnable tools is eligible (file reads,
+ *     shell, search, web fetch). Answers the user gave, subagent reports and
+ *     MCP results are never touched.
+ *  2. The most recent `keepRecent` tool results always stay.
+ *  3. Clearing happens in batches of at least `minClearTokens`, so each cache
+ *     rewrite buys a lot.
+ *  4. A cleared result stays cleared on every later request (ids are
+ *     remembered, across restarts), so the prefix is byte-stable between
+ *     batches and the cache keeps hitting.
+ *  5. By default a batch is taken ONLY when the cache is cold anyway (idle
+ *     longer than the request's own cache TTL), because the whole prompt is
+ *     re-written on that request regardless, so clearing costs nothing and
+ *     every later request is smaller. That makes it never-worse by
+ *     construction, and measured: replaying every Claude Code session on the
+ *     author's machine through this class, with real timestamps and cache
+ *     pricing, it saved 9.8% of cache-weighted input cost (9.2% of raw input
+ *     tokens, up to 37.7% in one long session) and made no session worse.
+ *     Clearing on a warm cache when the saving "should" repay the rewrite
+ *     (`paybackSafety` > 0) added 0.1% and made one session 0.13% worse: the
+ *     future is not knowable, so it is off unless asked for.
+ *
+ * The model sees a one-line note in place of the output and can simply re-run
+ * the tool; the file, command or URL is still in the tool call.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { estimateTokens } from "./tokens.js";
+/** Tools whose output can be regenerated by calling them again (read-only or re-runnable). */
+export const CLEARABLE_TOOLS = new Set([
+    // Claude Code
+    "Read", "Bash", "BashOutput", "Grep", "Glob", "LS", "WebFetch", "WebSearch", "NotebookRead",
+    // Codex and other OpenAI-API agents
+    "shell", "exec_command", "local_shell", "read_file", "list_dir", "grep_search", "file_search", "web_search",
+    // Cursor's agent
+    "Shell", "ReadFile", "rg", "run_terminal_cmd", "codebase_search",
+]);
+/** Tokens billed for one image inside a tool result (a full-size screenshot is ~1.6k on Claude). */
+const IMAGE_TOKENS = 1600;
+const HOUR = 3_600_000;
+export function clearedNote(tokens) {
+    return `[context-doctor: old tool output cleared to keep context lean (~${tokens} tokens). Run the tool again if you need it.]`;
+}
+function resultTokens(content, model) {
+    if (typeof content === "string")
+        return estimateTokens(content, model);
+    if (!Array.isArray(content))
+        return estimateTokens(JSON.stringify(content ?? ""), model);
+    let n = 0;
+    for (const part of content) {
+        if (part?.type === "image" || part?.type === "image_url" || part?.type === "input_image")
+            n += IMAGE_TOKENS;
+        else if (typeof part?.text === "string")
+            n += estimateTokens(part.text, model);
+        else
+            n += estimateTokens(JSON.stringify(part ?? ""), model);
+    }
+    return n;
+}
+/**
+ * How long the provider may keep this prompt cached, taking the LONGER
+ * possibility when unsure: calling a warm cache cold would pay a rewrite,
+ * calling a cold one warm only delays a free clearing.
+ *  - Anthropic: the request's own cache_control, "1h" or the 5-minute default.
+ *  - OpenAI: caches live up to an hour (in-memory retention), or 24 hours when
+ *    the request sets prompt_cache_retention "24h".
+ */
+export function requestTtlMs(body) {
+    const openai = Array.isArray(body.input) || (Array.isArray(body.messages) && isOpenAIChat(body.messages));
+    if (openai)
+        return body.prompt_cache_retention === "24h" ? 24 * HOUR : HOUR;
+    const json = JSON.stringify(body.system ?? "") + JSON.stringify(body.tools ?? "") + JSON.stringify(body.messages?.slice(-3) ?? "");
+    return /"ttl"\s*:\s*"1h"/.test(json) ? HOUR : 300_000;
+}
+function isOpenAIChat(messages) {
+    return messages.some((m) => m?.role === "tool" || (m?.role === "assistant" && Array.isArray(m.tool_calls)) || m?.role === "system" || m?.role === "developer");
+}
+export function viewOf(body) {
+    const toolName = new Map();
+    const results = [];
+    let firstToolId = "";
+    if (Array.isArray(body.input)) {
+        const units = body.input;
+        units.forEach((it, i) => {
+            const t = it?.type;
+            if ((t === "function_call" || t === "custom_tool_call" || t === "local_shell_call") && typeof it.call_id === "string") {
+                toolName.set(it.call_id, t === "local_shell_call" ? "shell" : String(it.name ?? ""));
+                firstToolId ||= it.call_id;
+            }
+            else if ((t === "function_call_output" || t === "custom_tool_call_output" || t === "local_shell_call_output") && typeof it.call_id === "string") {
+                results.push({ unit: i, id: it.call_id, content: it.output, set: (note) => { units[i] = { ...it, output: note }; } });
+            }
+        });
+        const firstUser = units.find((u) => u?.role === "user")?.content;
+        return { format: "openai-responses", units, toolName, results, firstUser, firstToolId, ttlMs: requestTtlMs(body) };
+    }
+    const messages = body.messages;
+    if (!Array.isArray(messages) || messages.length === 0)
+        return undefined;
+    const firstUser = messages.find((m) => m?.role === "user")?.content;
+    if (isOpenAIChat(messages)) {
+        messages.forEach((m, i) => {
+            if (m?.role === "assistant" && Array.isArray(m.tool_calls)) {
+                for (const c of m.tool_calls) {
+                    if (typeof c?.id !== "string")
+                        continue;
+                    toolName.set(c.id, String(c.function?.name ?? c.name ?? ""));
+                    firstToolId ||= c.id;
+                }
+            }
+            else if (m?.role === "tool" && typeof m.tool_call_id === "string") {
+                results.push({ unit: i, id: m.tool_call_id, content: m.content, set: (note) => { messages[i] = { ...m, content: note }; } });
+            }
+        });
+        return { format: "openai-chat", units: messages, toolName, results, firstUser, firstToolId, ttlMs: requestTtlMs(body) };
+    }
+    messages.forEach((m, i) => {
+        if (!Array.isArray(m?.content))
+            return;
+        const blocks = m.content;
+        blocks.forEach((b, j) => {
+            if (m.role === "assistant" && b?.type === "tool_use" && typeof b.id === "string") {
+                toolName.set(b.id, String(b.name ?? ""));
+                firstToolId ||= b.id;
+            }
+            else if (m.role === "user" && b?.type === "tool_result" && typeof b.tool_use_id === "string") {
+                results.push({ unit: i, id: b.tool_use_id, content: b.content, set: (note) => { blocks[j] = { ...b, content: note }; } });
+            }
+        });
+    });
+    return { format: "anthropic", units: messages, toolName, results, firstUser, firstToolId, ttlMs: requestTtlMs(body) };
+}
+/**
+ * A conversation's identity: its first user message plus its first tool call
+ * id. The message alone can repeat across sessions (the same project context
+ * opens every session in a folder); tool call ids are unique per session.
+ * The model is left out on purpose: switching models mid-session keeps the
+ * conversation (and the cleared set) but not the cache, which the TTL check
+ * cannot see, so a model switch is treated as warm, the safe direction.
+ */
+function conversationKey(view) {
+    return createHash("sha1").update(JSON.stringify(view.firstUser ?? "").slice(0, 4000)).update(view.firstToolId).digest("hex");
+}
+export class AutoClearer {
+    cleared = new Map();
+    /** Tool results never change once sent, so their size is computed once per id. */
+    sizes = new Map();
+    convs = new Map();
+    opts;
+    dirty = false;
+    constructor(options = {}) {
+        this.opts = {
+            keepRecent: options.keepRecent ?? 3,
+            minClearTokens: options.minClearTokens ?? 20_000,
+            paybackSafety: options.paybackSafety ?? 0,
+            statePath: options.statePath,
+        };
+        this.load();
+    }
+    /**
+     * Rewrite `body` in place: an Anthropic Messages, OpenAI Chat Completions or
+     * OpenAI Responses request. Never throws; anything unrecognised is left alone.
+     */
+    apply(body, now = Date.now()) {
+        const none = (reason, cold = false) => ({ changed: false, newlyCleared: 0, tokensRemoved: 0, cold, reason, firstChanged: -1 });
+        try {
+            const view = viewOf(body);
+            if (!view)
+                return none("no messages");
+            const model = typeof body.model === "string" ? body.model : undefined;
+            const key = conversationKey(view);
+            const conv = this.convs.get(key);
+            const cold = !conv || now - conv.last > view.ttlMs;
+            this.convs.set(key, { last: now, requests: (conv?.requests ?? 0) + 1 });
+            if (this.convs.size > 2000)
+                this.convs.delete(this.convs.keys().next().value);
+            const results = view.results.map((r) => {
+                let tokens = this.sizes.get(r.id);
+                if (tokens === undefined) {
+                    tokens = resultTokens(r.content, model);
+                    this.sizes.set(r.id, tokens);
+                    if (this.sizes.size > 100_000)
+                        this.sizes.delete(this.sizes.keys().next().value);
+                }
+                return { ...r, tokens };
+            });
+            const eligible = results.slice(0, Math.max(0, results.length - this.opts.keepRecent))
+                .filter((r) => CLEARABLE_TOOLS.has(view.toolName.get(r.id) ?? ""));
+            const pending = eligible.filter((r) => !this.cleared.has(r.id) && r.tokens > 200);
+            const pendingTokens = pending.reduce((n, r) => n + r.tokens, 0);
+            let reason = "nothing to clear";
+            let taken = [];
+            if (pendingTokens >= this.opts.minClearTokens) {
+                if (cold) {
+                    taken = pending;
+                    reason = "cache cold: cleared for free";
+                }
+                else if (this.opts.paybackSafety > 0 && this.shouldClearWarm(view.units, pending, pendingTokens, model, (conv?.requests ?? 0) + 1)) {
+                    taken = pending;
+                    reason = "cache warm: saving repays the rewrite";
+                }
+                else {
+                    reason = "cache warm: waiting, rewrite would not pay back yet";
+                }
+            }
+            else if (pendingTokens > 0) {
+                reason = `waiting for a ${Math.round(this.opts.minClearTokens / 1000)}k batch`;
+            }
+            for (const r of taken)
+                this.cleared.set(r.id, r.tokens);
+            if (taken.length)
+                this.dirty = true;
+            // Apply every clearing ever decided for this conversation, so the
+            // prefix is identical to what was sent last time.
+            let removed = 0;
+            let changed = false;
+            let firstChanged = -1;
+            for (const r of results) {
+                if (!this.cleared.has(r.id))
+                    continue;
+                const note = clearedNote(this.cleared.get(r.id));
+                if (r.content === note)
+                    continue;
+                removed += Math.max(0, r.tokens - estimateTokens(note, model));
+                r.set(note);
+                changed = true;
+                if (firstChanged === -1 || r.unit < firstChanged)
+                    firstChanged = r.unit;
+            }
+            this.save();
+            return { changed, newlyCleared: taken.length, tokensRemoved: removed, cold, reason, firstChanged };
+        }
+        catch {
+            return none("error: request forwarded unchanged");
+        }
+    }
+    /**
+     * Warm cache: clearing rewrites everything after the first cleared result
+     * at the write rate (1.25x instead of 0.1x: 1.15x extra, once), and saves
+     * the cleared tokens at the read rate (0.1x) on every later request.
+     * Later requests are estimated as the number made so far (a conversation's
+     * age is the best predictor of how long it keeps going), and the saving must
+     * cover the rewrite `paybackSafety` times over.
+     */
+    shouldClearWarm(messages, pending, pendingTokens, model, requestsSoFar) {
+        const first = Math.min(...pending.map((r) => r.unit));
+        let suffix = -pendingTokens;
+        for (let i = first; i < messages.length; i++)
+            suffix += estimateTokens(JSON.stringify(messages[i]), model);
+        const rewriteCost = 1.15 * Math.max(0, suffix);
+        const saving = 0.1 * pendingTokens * requestsSoFar;
+        return saving >= this.opts.paybackSafety * rewriteCost;
+    }
+    load() {
+        if (!this.opts.statePath || !existsSync(this.opts.statePath))
+            return;
+        try {
+            const data = JSON.parse(readFileSync(this.opts.statePath, "utf8"));
+            for (const [id, tokens] of data.cleared ?? [])
+                this.cleared.set(id, tokens);
+        }
+        catch {
+            /* a corrupt state file only means results may be re-cleared once */
+        }
+    }
+    save() {
+        if (!this.dirty || !this.opts.statePath)
+            return;
+        this.dirty = false;
+        try {
+            // Newest 50k ids: far more than any live session holds.
+            const entries = [...this.cleared.entries()].slice(-50_000);
+            mkdirSync(dirname(this.opts.statePath), { recursive: true });
+            writeFileSync(this.opts.statePath, JSON.stringify({ cleared: entries }));
+        }
+        catch {
+            /* persistence is best effort */
+        }
+    }
+}

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);
+}