context-doctor 0.19.0 → 0.20.1

package/README.md

@@ -1,15 +1,30 @@
 # context-doctor 🩺
 
-[![CI](https://github.com/KushalP1/context-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/KushalP1/context-doctor/actions) [![npm](https://img.shields.io/npm/v/context-doctor)](https://www.npmjs.com/package/context-doctor)
+[![CI](https://github.com/KushalP1/context-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/KushalP1/context-doctor/actions) [![npm](https://img.shields.io/npm/v/context-doctor)](https://www.npmjs.com/package/context-doctor) [![npm downloads](https://img.shields.io/npm/dm/context-doctor)](https://www.npmjs.com/package/context-doctor) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE) ![macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
 
-**See what's eating your LLM context window — and fix it.**
+**Keep every AI session's context lean, automatically, without ever making it more expensive.**
 
-Every long-running LLM conversation slowly fills up with junk: duplicated documents, 10k-token tool outputs nobody reads again, base64 blobs, stale history. You pay for those tokens on **every single call**, and model quality drops as the window fills.
+Long agent sessions fill up with tool output nobody reads again: file dumps, shell logs, search results, screenshots. You pay for all of it on every request, the model gets slower, and it drifts as the window fills. `context-doctor` measures that, and with **autopilot** it removes it from every Claude Code (and GPT API) request on your machine, only at moments when doing so costs nothing extra.
 
-`context-doctor` is a zero-config profiler + optimizer for LLM contexts. It works with **Claude, GPT, Gemini** message formats, and plugs into **Claude Desktop, ChatGPT (developer mode), Cursor, Claude Code** — any MCP-capable app — or runs standalone from the terminal.
+- **9.8% less input cost, no session worse.** Replaying 130 days of the author's real Claude Code use (43 sessions) through the shipped code: **3.8 billion input tokens not sent, $4,694 saved at API list price, about $1,080 a month**, and not one session more expensive. Up to 37.7% on a long session. [What it saves →](#what-it-saves)
+- **Counts Claude correctly.** Current Claude models pack 2.75 characters per token, not the 4 most tools assume; estimates built on 4 undercount Claude by about 40%. The ratios here were measured from the API's own counts, and `context-doctor accuracy` re-checks them on yours. [How →](#why-token-counts-are--and-where-they-are-exact)
+- **Works where you work:** Claude Code, Cursor, Codex, Claude Desktop, any Anthropic or OpenAI API app, VS Code, CI. macOS, Linux and Windows, Node 20+.
+- **Local and keyless.** No account, no telemetry, no API key. Your own login passes through untouched. MIT.
 
 Built and maintained by [gAI Ventures](https://gai.ventures).
 
+## Quick start
+
+```bash
+npm install -g context-doctor
+context-doctor install          # hooks, MCP server and skill in every AI app it finds
+context-doctor autopilot on     # every new Claude Code session keeps its context lean
+```
+
+Then start a new Claude Code session and work as usual. `context-doctor autopilot status` shows what it did; `context-doctor doctor` checks the whole setup. Everything is reversible: `context-doctor autopilot off`, `context-doctor uninstall`.
+
+Just want a look first? `npx context-doctor session` profiles your latest Claude Code or Codex session in place, no install.
+
 ```
 Where the tokens go
 ────────────────────────────────────────────────────────
@@ -26,35 +41,67 @@ Findings (4)
    → Truncate or summarize large tool outputs before they enter history.
 ```
 
-## Quick start (30 seconds)
+## What it saves
 
-**One command sets up everything** — detects Claude Desktop, Claude Code, and Cursor on your machine, wires in the MCP server, installs the Agent Skill, and registers the Claude Code every-prompt hook:
+Measured, not modelled: every Claude Code session on the author's machine from 18 May to 25 September 2026 (43 sessions, 130 days, mostly Opus 5 and Fable 5 with the 1M window) was replayed request by request through the shipped autopilot code, with the real timestamps, and priced the way the prompt cache bills it (cached reads 0.1x, writes 1.25x). Run it on your own history with `node scripts/replay-autopilot.mjs`.
 
-```bash
-npx context-doctor install
-```
+| | Without autopilot | With autopilot | Saved |
+|---|---|---|---|
+| Input tokens sent | 41.4 billion | 37.6 billion | **3.8 billion (9.2%)** |
+| Input cost at API list price | $48,962 | $44,268 | **$4,694 (9.8%)** |
+| Per 30 days | | | **~875 million tokens, ~$1,080** |
+| Sessions made more expensive | | | **0 of 43** |
 
-`install` configures every app it detects and does not stop at the first problem: a corrupt Claude Desktop config still gets you Claude Code and Cursor. It does not pretend either. Any target that failed is named with a ✗ line, the summary reads "Done with N problem(s)" instead of "Done.", and the **exit code is 1**, so dotfiles and onboarding scripts can react. A broken config file is never overwritten; fix it and re-run.
+How it spreads: the median session saves 1.9%, the best 37.7%. Short sessions barely change, because they rarely pile up 20k tokens of stale tool output before they end. Long sessions are where the money is: on this machine 94% of input cost came from requests above 200k tokens, and those are the requests autopilot makes smaller. Savings scale with how long your sessions run and how much they read, so a lighter user saves proportionally less, and never pays more.
 
-That single command is also all it takes to **set up context-doctor on anyone else's machine**. Prefer a global install, or want the unreleased `main`? Both work (Node 20+):
+On a Claude subscription you do not pay list price; the same tokens come out of your usage limit instead. Anthropic does not publish how limits weight cached tokens, so read the dollar column as the size of the effect, not as your bill. The token column holds either way, and every request that is 9% smaller is also faster to first token and further from auto-compaction.
 
-```bash
-npm install -g context-doctor && context-doctor install
-```
+What is not counted here: the proxy's full optimizer for your own API apps, the hook's guidance to the model, and fixes you make from `session` findings. Those save more on top, but they depend on what the model or you do with the advice, so they are not in this table.
+
+## What happens on each platform
+
+| Where you work | Automatic, every request | What you get on top |
+|---|---|---|
+| **Claude Code** (terminal, VS Code, JetBrains, desktop app's Code tab) | **Autopilot** clears stale tool output (cold cache only, never more expensive). **Hook** on every prompt warns the model with the real context size and its largest waste | Status bar context meter, `/context-doctor` skill, `session`, `watch`, `report`, dashboard |
+| **Cursor** (agent) | Cursor runs Claude Code's hooks, so the same every-prompt check fires inside Cursor | MCP tools, editor status bar extension, `cursor` profiler. With your own OpenAI key, autopilot too via a tokened tunnel ([how](#putting-the-proxy-on-a-public-url-cursor-with-your-own-openai-key-remote-apps)) |
+| **Codex** (ChatGPT app's Codex tab, IDE extension, CLI) | Every-prompt hook with the API's own token counts | MCP tools, skill, `session` reads Codex rollouts. On an API key, autopilot too (`OPENAI_BASE_URL`) |
+| **Your own apps on the Anthropic or OpenAI API** | Autopilot on `/v1/messages`, `/v1/chat/completions` and `/v1/responses` (`ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL`), or the full optimizing proxy | Exact usage and cache hit rates in `/stats`, prompt-cache placement advice |
+| **Claude Desktop chat** | Standing context rules in every chat; one cheap `profile_context` call the model makes past ~30 turns or on any cost question | One-click `.mcpb` install, `context_checkup` prompt |
+| **claude.ai, ChatGPT, the phone apps** | Your account's standing preferences (`context-doctor instructions --copy`) | Profile an exported chat with `analyze` |
+| **CI** | `analyze --fail-over-budget` fails a build whose prompts outgrow a budget | `.contextdoctorrc` budgets and presets |
+
+Not claimed, because no process on your machine sends those requests: trimming inside Claude Desktop chat, claude.ai, ChatGPT, Cursor's own subscription models, or Codex signed in with ChatGPT. Those get the rules and the measurements above, not autopilot.
+
+## What's new
+
+- **0.20 Autopilot**: stale tool output cleared from every Claude Code request, only when the prompt cache is cold, so it cannot cost more (measured: 9.8% less input cost, ~$1,080 a month on the author's usage, no session worse); runs as a login service on macOS, Linux and Windows; now also for GPT via OpenAI's Chat Completions and Responses APIs.
+- **0.20.1 Releases that finish themselves**: one tag publishes to npm and creates a GitHub release with the Claude Desktop bundle (signed when a certificate is configured); the editor extension is ready for the VS Code Marketplace and Open VSX.
+- **0.19 Measured Claude tokenizer**: estimates were 40% low for Claude; fixed from the API's own counts, with a per-model check in `accuracy`.
+- **0.18** `proxy --token` for putting the proxy on a public URL safely. **0.17** Claude Desktop: a `profile_context` the model can afford to call from chat, `.mcpb` bundle, standing preferences for web and mobile. **0.16** Codex. **0.15** Cursor.
+
+Full history with the measurements behind each change: [ROADMAP.md](./ROADMAP.md).
+
+## Setup details
+
+`install` configures every app it detects and does not stop at the first problem: a corrupt Claude Desktop config still gets you Claude Code and Cursor. It does not pretend either. Any target that failed is named with a ✗ line, the summary reads "Done with N problem(s)" instead of "Done.", and the **exit code is 1**, so dotfiles and onboarding scripts can react. A broken config file is never overwritten; fix it and re-run.
 
-Restart your apps, then just ask Claude: *"what's eating my context?"* (`npx context-doctor uninstall` reverses it.)
+`npx context-doctor install` works too, but autopilot needs the global install: a background service cannot point into npx's cache, which npm deletes at will.
 
 **No API keys, ever.** Everything is deterministic local code; when an LLM is needed (summarizing pruned history), the model already running in your app does it. The proxy forwards *your app's* credentials untouched — context-doctor itself holds nothing.
 
 ## What `install` actually does — and what happens in every session after
 
-One run of `npx context-doctor install` writes five things (each config edit makes a `.backup` first; `uninstall` reverses all of it):
+One run of `context-doctor install` writes these (each config edit makes a `.backup` first; `uninstall` reverses all of it):
 
 1. **Claude Desktop config** (`claude_desktop_config.json`) — registers the MCP server
 2. **Claude Code config** (`~/.claude.json`) — registers the MCP server
 3. **Cursor config** (`~/.cursor/mcp.json`) — registers the MCP server
 4. **Agent Skill** → `~/.claude/skills/context-doctor/` — context-hygiene playbook for Claude Code
-5. **Every-prompt hook** → `~/.claude/settings.json` — the per-query context check for Claude Code
+5. **Every-prompt hook** → `~/.claude/settings.json` — the per-query context check for Claude Code (Cursor runs it too)
+6. **Codex**, when present: MCP server in `~/.codex/config.toml`, the hook in `~/.codex/hooks.json`, the skill in `~/.codex/skills/`
+7. With `--statusline`: live context size, cache share and cost in Claude Code's status bar
+
+`context-doctor autopilot on` is separate and opt-in: it adds the background proxy service and one line (`env.ANTHROPIC_BASE_URL`) to `~/.claude/settings.json`, after the proxy has answered a health check.
 
 **In every chat afterward (Claude Desktop, Cursor):** when the conversation starts, the app launches the MCP server, which hands the model standing instructions that stay in force for the whole chat:
 
@@ -72,11 +119,12 @@ One run of `npx context-doctor install` writes five things (each config edit mak
 
 ## Do you need MCP? Only sometimes — all the ways to use context-doctor
 
-MCP is just one of six delivery mechanisms. It's only required when you want the AI **inside a chat app** to run the tools itself. Everything else works without it:
+MCP is just one of seven delivery mechanisms. It's only required when you want the AI **inside a chat app** to run the tools itself. Everything else works without it:
 
 | How you use it | MCP needed? | What it requires |
 |---|---|---|
 | **CLI** — `analyze`, `optimize`, `session` on files/transcripts | ❌ No | Nothing but `npx` — works in any terminal, scripts, CI |
+| **Autopilot** — every Claude Code session, and GPT API apps | ❌ No | `context-doctor autopilot on` (a login service + one line in `~/.claude/settings.json`) |
 | **Proxy** — always-on optimization of your API apps | ❌ No | `context-doctor proxy` + one env var in your app |
 | **Claude Code every-prompt hook** | ❌ No | Written by `install`; Claude Code invokes it directly |
 | **Agent Skill** — hygiene behavior in Claude Code / claude.ai | ❌ No | A markdown file; `install` places it (or upload to claude.ai) |
@@ -90,6 +138,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | Command | What it does |
 |---|---|
 | `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor/Codex, the Agent Skill, the every-prompt hook |
+| `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: measured 9.8% less input cost, no session worse |
 | `context-doctor instructions [--copy]` | The ~180-token standing rules (~120 on GPT) for claude.ai / ChatGPT preferences, for web and phones where no server runs |
 | `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates. `--fail-over-budget` exits 1 on a breach, for CI |
 | `context-doctor optimize <file>` | Apply the safe fixes; add `--strategy trim-tool-calls` for big inline file writes, `--strategy prune-history` for consented lossy compaction |
@@ -112,14 +161,13 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 
 | Where you run LLMs | Mechanism | Guarantee |
 |---|---|---|
-| Your own apps/agents (API) | `context-doctor proxy` rewrites every request in flight | **Every call, automatic** |
+| Claude Code sessions, with autopilot on | The login-service proxy clears stale tool output from every request, only when the cache is cold | **Every request; never more expensive (measured)** |
+| Your own apps/agents (API) | `context-doctor proxy` rewrites every request in flight, or `proxy --autopilot` for the cache-safe mode | **Every call, automatic** |
 | Claude Code / Cowork sessions | `install` registers a **UserPromptSubmit hook**: every query measures the session; heavy sessions get injected hygiene guidance (silent when lean, rate-limited, never blocks a prompt) | **Every query checked** |
 | Claude Desktop chat / Cursor | **MCP server instructions** — standing hygiene directives injected into every conversation where the server is enabled, plus prescriptive tool triggers | **Every conversation carries the rules** |
-| claude.ai (web) / ChatGPT app | Upload `skills/context-doctor/SKILL.md` in the app's Skills settings for the same standing behavior | Manual one-time upload |
-
-Nothing runs in the background for the Claude apps — the hook, skill, MCP server, and its instructions are all delivered by the app itself at the right moment. The proxy is the only long-running piece, and only your API-calling apps need it.
+| claude.ai (web) / ChatGPT / phone apps | `context-doctor instructions --copy`, pasted once into the account's preferences (or upload `skills/context-doctor/SKILL.md` as a skill) | Every chat on that account carries the rules |
 
-Optional belt-and-braces for any chat app: add one line to your profile preferences — *"Practice context hygiene: summarize large content instead of re-quoting it, and use context-doctor's tools when conversations get heavy."*
+Without autopilot nothing runs in the background: the hook, skill, MCP server and its instructions are delivered by the apps themselves at the right moment. With autopilot, one small proxy runs as a login service (launchd / systemd user service / logon task) and is restarted by the service or by the next prompt's hook if it ever stops.
 
 Or use the CLI directly, no install needed:
 
@@ -150,6 +198,35 @@ npx context-doctor session --list    # browse sessions
 
 Parses the transcripts Claude Code writes locally and answers "where did my tokens go today?" — it will happily tell you that one giant skill load is 67% of your context.
 
+## Autopilot: every Claude Code session keeps its own context lean
+
+```bash
+context-doctor autopilot on        # once; survives reboots
+context-doctor autopilot status    # what it has done
+context-doctor autopilot pause     # instant passthrough, nothing restarts
+context-doctor autopilot off       # remove it
+```
+
+`autopilot on` runs the local proxy as a background service (launchd on macOS, a systemd user service on Linux, a logon task on Windows), waits until it answers, and only then points Claude Code at it through `env.ANTHROPIC_BASE_URL` in `~/.claude/settings.json`. Every Claude Code session started afterwards, in the terminal, an IDE, or the desktop app's Code tab, sends its requests through it. Your login (subscription or API key) passes through untouched.
+
+**What it does to each request:** once old tool output adds up to 20k+ tokens (file reads, shell output, search and web results, screenshots inside them), it replaces that output with a one-line note, keeping the 3 most recent results. The tool call stays in the history, so the model can simply run it again if it needs the output. Your messages, its answers, answers you gave to its questions, subagent reports and MCP results are never touched.
+
+**Why it cannot make a session more expensive.** A prompt cache matches a byte-identical prefix, and changing old history re-bills everything after the change at the write rate (1.25x instead of 0.1x). So autopilot changes history only when the cache is cold anyway: after an idle gap longer than the cache lifetime the request itself declares (1 hour for Claude Code on a subscription, 5 minutes otherwise), when the whole prompt is re-written regardless. Once cleared, an output stays cleared on every later request, so the prefix is identical between clearings and the cache keeps hitting.
+
+**Measured before it shipped**, by replaying every Claude Code session on the author's machine (43 sessions, 130 days) request by request through the shipped code, priced as the cache bills it, with real timestamps: 3.8 billion input tokens not sent and $4,694 at list price, ~$1,080 a month ([details](#what-it-saves)). `scripts/replay-autopilot.mjs` does this on yours:
+
+| Policy | Input cost saved | Worst session |
+|---|---|---|
+| **Autopilot: clear only when the cache is cold (default)** | **9.8%** (9.2% of raw input tokens; best session 37.7%) | **0.00%, no session worse** |
+| Also clear on a warm cache when the saving "should" repay the rewrite | 9.9% | −0.13% (one session worse) |
+| The proxy's general strategies (dedupe, trim, strip-base64) | 6.7% | −13% (one session worse) |
+
+94% of input cost on that machine came from requests above 200k tokens, which is where the clearing lands. Smaller requests also mean later auto-compaction and a faster first token.
+
+**Never in the way:** anything it cannot parse is forwarded unchanged; only Anthropic `/v1/messages` requests are touched. It adds about 7 ms to a 2.9 MB (~1M token) request. If the proxy dies, the service restarts it within seconds, and the every-prompt hook checks it before each prompt and starts it if needed (measured: 0.6 s once, when it had to). `pause` turns it into a passthrough without restarting anything; `off` removes the setting before stopping the service, and sessions started while it was on need a restart.
+
+**What it cannot reach** (no process on your machine sends those requests): Claude Desktop's chat tab and claude.ai, which use the standing instructions and the `profile_context` sketch instead; Cursor's own models (Cursor's servers call the model; with your own OpenAI key, see the tunnel section below); and Codex signed in with ChatGPT, where the every-prompt hook still reports context size.
+
 ## Always-on: optimize every request automatically
 
 Run the proxy and every Anthropic/OpenAI API call your apps make gets optimized in flight — no code changes:
@@ -504,14 +581,27 @@ Contributions welcome — this project is small on purpose. Open an issue before
 
 ## Releasing (maintainers)
 
+**One-time setup.** Each row switches on one channel; any that is missing is skipped with a notice, never a failed run. Secrets go in the repo's Settings > Secrets and variables > Actions:
+
+| Secret | Turns on | Where to get it |
+|---|---|---|
+| *(no secret: npm trusted publishing)* | `npm publish` on every `v*` tag, with provenance | npmjs.com > package `context-doctor` > Settings > Trusted Publisher > GitHub Actions: owner `KushalP1`, repository `context-doctor`, workflow `publish.yml`. npm is phasing out publish tokens that bypass 2FA; an `NPM_TOKEN` secret still works as a fallback |
+| `MCPB_CERT`, `MCPB_KEY` (+ `MCPB_INTERMEDIATE`) | A signed Claude Desktop bundle, no install warning | A code-signing certificate from a trusted CA; paste the PEM text. `mcpb verify` must pass in CI or the release stops |
+| `VSCE_PAT` | VS Code Marketplace on `vscode-v*` tags | Azure DevOps PAT, scope Marketplace > Manage, for the `gai-ventures` publisher |
+| `OVSX_PAT` | Open VSX (where Cursor installs from) | open-vsx.org > Settings > Access Tokens |
+
+**Each release:**
+
 ```bash
-npm version patch        # or minor/major — bumps package.json + git tag
-npm test                 # 131 tests must pass; CI runs the same on 3 OSes x Node 20/22/24
-npm publish              # prompts for the npm 2FA code
-git push --follow-tags
-npm run build:mcpb       # context-doctor-<version>.mcpb for Claude Desktop; attach it to the GitHub release
+npm version minor        # or patch/major: bumps package.json and tags vX.Y.Z
+npm test                 # the full suite; CI runs it on 3 OSes x Node 20/22/24
+git push --follow-tags   # npm publish + GitHub release with the .mcpb attached
 ```
 
+For the editor extension: bump `vscode/package.json`, add a `vscode/CHANGELOG.md` entry, then `git tag vscode-vX.Y.Z && git push --tags`. The `.vsix` is attached to a GitHub release either way.
+
+Locally, `npm run build:mcpb` builds the bundle (`MCPB_SELF_SIGNED=1` exercises the signing path with a throwaway certificate; Desktop still warns for those).
+
 **What the npm download number measures.** `install` writes `npx -y context-doctor-mcp` into MCP configs, and npx re-fetches the tarball whenever a new version exists. So every release is downloaded once by every active install within about a day, and the daily count is almost entirely those refreshes: on this package, release days run ~170 downloads and non-release days ~27. Read it as "size of the active installed base × number of releases", not as new users — a quiet week with no releases will look like a decline while nothing has changed. Two corollaries: the release-day figure is a live count of machines running context-doctor, and a broken release reaches all of them automatically, which is why `prepublishOnly` runs the full test suite. npm's stats also lag by several days and occasionally record a day as zero; a zero on a release day is a gap in their pipeline, not in usage.
 
 Known gotcha: if `npm publish` fails with **`404 Not Found - PUT …/context-doctor`** on a package that clearly exists, the real cause is an **expired npm login token** — npm reports unauthenticated publishes as a 404, not a 401. Check with `npm whoami`; if that errors, run `npm login` and publish again.

package/dist/autoclear.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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.
+ */
+/** Tools whose output can be regenerated by calling them again (read-only or re-runnable). */
+export declare const CLEARABLE_TOOLS: Set<string>;
+export interface AutoClearOptions {
+    /** Most recent tool results that always stay. Default 3. */
+    keepRecent?: number;
+    /** Smallest batch worth a cache rewrite. Default 20,000 tokens. */
+    minClearTokens?: number;
+    /**
+     * Warm-cache rule: clear only if the saving over the requests still to come
+     * repays the rewrite this many times over. Requests still to come are
+     * estimated as the number already made in this conversation. Default 0:
+     * warm clearing off, cold cache only (the never-worse setting).
+     */
+    paybackSafety?: number;
+    /** Where cleared ids persist so a restart does not un-clear (and re-bill) them. */
+    statePath?: string;
+}
+export interface AutoClearResult {
+    changed: boolean;
+    /** Results cleared by this request's new batch (0 when none was taken). */
+    newlyCleared: number;
+    /** Tokens removed from this request, old batches included. */
+    tokensRemoved: number;
+    cold: boolean;
+    reason: string;
+    /** Index of the first message rewritten on this request (the cache breaks from here), or -1. */
+    firstChanged: number;
+}
+interface Found {
+    /** Index of the message / input item that holds the result (cache breaks from here). */
+    unit: number;
+    id: string;
+    tokens: number;
+    content: unknown;
+    set: (note: string) => void;
+}
+/**
+ * One request, whatever its API: the units that make up history, tool names
+ * by call id, the tool results in order, and the cache lifetime to assume.
+ * Anthropic Messages (Claude Code, Anthropic SDKs), OpenAI Chat Completions
+ * (role "tool" messages) and OpenAI Responses (function_call_output items,
+ * as Codex with an API key sends).
+ */
+interface View {
+    format: "anthropic" | "openai-chat" | "openai-responses";
+    units: Array<Record<string, unknown>>;
+    toolName: Map<string, string>;
+    results: Array<Omit<Found, "tokens">>;
+    firstUser: unknown;
+    firstToolId: string;
+    ttlMs: number;
+}
+export declare function clearedNote(tokens: number): string;
+/**
+ * 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 declare function requestTtlMs(body: Record<string, unknown>): number;
+export declare function viewOf(body: Record<string, unknown>): View | undefined;
+export declare class AutoClearer {
+    private cleared;
+    /** Tool results never change once sent, so their size is computed once per id. */
+    private sizes;
+    private convs;
+    private opts;
+    private dirty;
+    constructor(options?: AutoClearOptions);
+    /**
+     * Rewrite `body` in place: an Anthropic Messages, OpenAI Chat Completions or
+     * OpenAI Responses request. Never throws; anything unrecognised is left alone.
+     */
+    apply(body: Record<string, unknown>, now?: number): AutoClearResult;
+    /**
+     * 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.
+     */
+    private shouldClearWarm;
+    private load;
+    private save;
+}
+export {};