context-doctor 0.13.1 → 0.13.3

package/README.md

@@ -383,6 +383,8 @@ npm publish              # prompts for the npm 2FA code
 git push --follow-tags
 ```
 
+**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.
 
 Also keep the MCP server version in `src/mcp.ts` in sync with `package.json`, and remember `dist/` is committed — run `npm run build` before committing so the CI dist-sync check passes.

package/dist/cursor.js

@@ -114,7 +114,12 @@ export function listCursorChats(limit = 20) {
             rows = queryRows(dbPath, "SELECT key, json_extract(value, '$.name') AS name, " +
                 "COALESCE(json_array_length(value, '$.fullConversationHeadersOnly'), " +
                 "json_array_length(value, '$.conversation'), 0) AS n " +
-                "FROM cursorDiskKV WHERE key LIKE 'composerData:%'");
+                // json_valid is not optional: SQLite's JSON functions raise on
+                // malformed input, and one non-JSON row under a composerData: key
+                // aborts the WHOLE query. cursorDiskKV is a general-purpose store,
+                // so that row exists sooner or later — and the user then sees
+                // "No Cursor chats found" with every real chat sitting right there.
+                "FROM cursorDiskKV WHERE key LIKE 'composerData:%' AND json_valid(value)");
         }
         catch {
             continue; // no composer table (older Cursor) or no SQLite — skip

package/dist/doctor.js

@@ -50,6 +50,23 @@ function checkMcpEntry(appName, configPath) {
         return { label: appName, status: "fail", detail: `${configPath} is not valid JSON (${e.message})` };
     }
 }
+/**
+ * For a hook command, the path that must exist for it to run — or null when it
+ * resolves through PATH (`node`, `npx`) and there is nothing to check here.
+ *
+ * Forms written by install: `node "<cli.js>" hook`, `"<binary>" hook`,
+ * `npx -y context-doctor hook`.
+ */
+function hookBinaryMissing(command) {
+    const quoted = [...command.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+    const first = command.trim().split(/\s+/)[0]?.replace(/^"|"$/g, "") ?? "";
+    const candidates = quoted.length > 0 ? quoted : /[\\/]/.test(first) ? [first] : [];
+    for (const path of candidates) {
+        if (!existsSync(path))
+            return path;
+    }
+    return null;
+}
 /** Spawn our own MCP server and run the initialize handshake over stdio. */
 function checkMcpHandshake() {
     const label = "MCP server handshake";
@@ -96,10 +113,20 @@ export async function runDoctor() {
     if (existsSync(settingsPath)) {
         try {
             const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
-            const registered = JSON.stringify(settings.hooks?.UserPromptSubmit ?? []).includes("context-doctor");
-            checks.push(registered
-                ? { label: "Every-prompt hook", status: "ok", detail: "registered in ~/.claude/settings.json" }
-                : { label: "Every-prompt hook", status: "fail", detail: "not registered — run: context-doctor install" });
+            const entries = settings.hooks?.UserPromptSubmit ?? [];
+            const ours = entries.map((e) => e.hooks?.[0]?.command ?? "").find((c) => /context-doctor|cli\.js"?\s+hook/.test(c));
+            if (!ours) {
+                checks.push({ label: "Every-prompt hook", status: "fail", detail: "not registered — run: context-doctor install" });
+            }
+            else {
+                // "Registered" is not "working": a hook whose binary has been deleted
+                // (an npx cache sweep, a Node upgrade) fails silently on every prompt,
+                // and this check used to report it as fine.
+                const missing = hookBinaryMissing(ours);
+                checks.push(missing
+                    ? { label: "Every-prompt hook", status: "fail", detail: `registered, but ${missing} no longer exists — re-run: context-doctor install` }
+                    : { label: "Every-prompt hook", status: "ok", detail: "registered in ~/.claude/settings.json; command resolves" });
+            }
         }
         catch (e) {
             checks.push({ label: "Every-prompt hook", status: "fail", detail: `settings.json unreadable (${e.message})` });

package/dist/install.js

@@ -89,6 +89,13 @@ function binOnPath(name) {
     for (const dir of (process.env.PATH ?? "").split(delimiter)) {
         if (!dir)
             continue;
+        // npx prepends its OWN cache's .bin to PATH while it runs the command. So
+        // during `npx -y context-doctor install`, the first "global binary" on
+        // PATH is inside _npx — the garbage-collected directory this lookup exists
+        // to avoid. That hole put a cache path in the hook of every user who
+        // followed the README's headline command.
+        if (isEphemeralPath(dir))
+            continue;
         for (const ext of exts) {
             const candidate = join(dir, name + ext);
             if (existsSync(candidate))
@@ -97,6 +104,10 @@ function binOnPath(name) {
     }
     return null;
 }
+/** Paths npm may delete at any time: the npx cache and the npm cache itself. */
+function isEphemeralPath(path) {
+    return /[\\/]_npx[\\/]/.test(path) || /[\\/]\.npm[\\/]/.test(path) || /[\\/]npm-cache[\\/]/i.test(path);
+}
 /**
  * Shell command used for the Claude Code every-prompt hook.
  *
@@ -113,8 +124,7 @@ function binOnPath(name) {
 function hookCommand() {
     const selfDir = dirname(fileURLToPath(import.meta.url));
     const localCli = join(selfDir, "cli.js");
-    const ephemeral = selfDir.includes("_npx");
-    if (!ephemeral && existsSync(localCli))
+    if (!isEphemeralPath(selfDir + sep) && existsSync(localCli))
         return `node "${localCli}" hook`;
     const global = binOnPath("context-doctor");
     if (global)

package/dist/mcp.js

@@ -37,7 +37,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.13.1" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.13.3" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown by category, largest messages, and actionable findings about wasted context (duplicates, oversized tool results, base64 blobs, cache-unfriendly ordering). Accepts OpenAI/Anthropic conversation JSON or raw text. Call this immediately whenever the user asks about token usage, context size, LLM cost, or latency — and proactively offer it once a conversation grows long or accumulates large pasted content.", {
         conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text"),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),
@@ -120,6 +120,24 @@ const BEST_PRACTICES = {
         "Use max_completion_tokens headroom math: input + output must fit the window together.",
     ],
 };
+/**
+ * Set a header on a Node request so every downstream reader sees it.
+ *
+ * `req.headers` is a parsed convenience copy; the MCP transport reconstructs a
+ * Web Request from `req.rawHeaders`, so a header written to only one of them is
+ * invisible to the other.
+ */
+function setHeader(req, name, value) {
+    req.headers[name] = value;
+    const raw = req.rawHeaders;
+    for (let i = 0; i < raw.length; i += 2) {
+        if (raw[i].toLowerCase() === name) {
+            raw[i + 1] = value;
+            return;
+        }
+    }
+    raw.push(name, value);
+}
 // -- Transport dispatch --------------------------------------------------------
 // Default: stdio (Claude Desktop, Claude Code, Cursor spawn us as a child).
 // --http [--port N] [--host H]: streamable-HTTP endpoint at /mcp for clients
@@ -154,9 +172,26 @@ if (argv.includes("--http")) {
                 res.end(JSON.stringify({ error: "Stateless server: POST /mcp only" }));
                 return;
             }
+            // The streamable-HTTP spec says a client MUST accept both
+            // application/json and text/event-stream, and the SDK answers anything
+            // else with a 406. Plenty of real callers send only application/json, or
+            // `*/*`, or no Accept at all — and to them a 406 looks like the server
+            // being broken. Our replies are single JSON-RPC responses with nothing to
+            // stream, so those clients get a plain JSON body instead of a refusal.
+            const accept = String(req.headers.accept ?? "");
+            const askedForSse = accept.includes("text/event-stream");
+            if (!askedForSse || !accept.includes("application/json")) {
+                // The transport rebuilds the request from rawHeaders (via Hono), so
+                // setting req.headers alone changes nothing it will ever look at.
+                setHeader(req, "accept", "application/json, text/event-stream");
+            }
             // Fresh server + transport per request (stateless — nothing shared).
             const server = createServer();
-            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                // A client that never asked for a stream gets plain JSON back.
+                enableJsonResponse: !askedForSse,
+            });
             res.on("close", () => {
                 void transport.close();
                 void server.close();

package/dist/optimize.js

@@ -129,6 +129,34 @@ function truncateToTokens(text, maxTokens) {
     const omitted = text.length - approxChars;
     return `${head}\n…[context-doctor: trimmed ${omitted} chars of stale tool output]`;
 }
+/**
+ * Remove tool_result blocks whose matching tool_use is not in the same slice.
+ *
+ * Anthropic and OpenAI both reject a conversation where a tool result refers to
+ * a call that is not present, so anything that drops earlier turns has to clean
+ * up after itself. A message emptied by this keeps a short note rather than
+ * becoming an empty content array, which is also rejected.
+ */
+function dropOrphanedToolResults(kept) {
+    const availableCalls = new Set();
+    for (const m of kept) {
+        if (!Array.isArray(m?.content))
+            continue;
+        for (const b of m.content)
+            if (b?.type === "tool_use" && b.id)
+                availableCalls.add(b.id);
+    }
+    for (const m of kept) {
+        if (!Array.isArray(m?.content))
+            continue;
+        const surviving = m.content.filter((b) => b?.type !== "tool_result" || (b.tool_use_id && availableCalls.has(b.tool_use_id)));
+        if (surviving.length === m.content.length)
+            continue;
+        m.content = surviving.length > 0
+            ? surviving
+            : [{ type: "text", text: "[context-doctor: earlier tool result dropped with the pruned history]" }];
+    }
+}
 function isToolResultMessage(m) {
     if (m?.role === "tool")
         return true;
@@ -222,6 +250,11 @@ export function optimizeConversation(input, options = {}) {
             if (before <= opts.maxToolResultTokens)
                 return;
             const trimmed = truncateToTokens(text, opts.maxToolResultTokens);
+            // The truncation notice has a length of its own, so a result only just
+            // over the budget can come back LARGER than it went in. Measured on a
+            // real session: 2,941 tokens "optimized" to 2,947.
+            if (estimateTokens(trimmed) >= before)
+                return;
             m.content = replaceText(m.content, trimmed);
             applied.push({
                 strategy: "trim-tool-results",
@@ -246,8 +279,13 @@ export function optimizeConversation(input, options = {}) {
                     const before = estimateTokens(JSON.stringify(b.input));
                     if (before <= opts.maxToolResultTokens)
                         continue;
-                    b.input = trimCallArguments(b.input, opts.maxToolResultTokens);
-                    saved += before - estimateTokens(JSON.stringify(b.input));
+                    const trimmedInput = trimCallArguments(b.input, opts.maxToolResultTokens);
+                    // Same trap as tool results: the marker can outweigh what it replaces.
+                    const after = estimateTokens(JSON.stringify(trimmedInput));
+                    if (after >= before)
+                        continue;
+                    b.input = trimmedInput;
+                    saved += before - after;
                 }
             }
             // OpenAI shape: tool_calls[].function.arguments is a JSON string.
@@ -285,6 +323,11 @@ export function optimizeConversation(input, options = {}) {
         // Boundary adjustment may leave too little tail to be worth keeping —
         // in that case skip pruning entirely rather than gutting the conversation.
         if (messages.length - keepFrom >= 2) {
+            // Advancing past LEADING tool results is not enough: a tool_result can
+            // sit deeper in the kept tail while its tool_use was pruned, and both
+            // APIs reject a conversation containing an orphan. Measured on a real
+            // 1,011-message session, which pruned to 7 messages with one orphan.
+            dropOrphanedToolResults(messages.slice(keepFrom));
             const pruned = messages.slice(0, keepFrom);
             const prunedTokens = pruned.reduce((s, m) => s + estimateTokens(textOf(m.content)), 0);
             // Digest: first ~200 chars of each pruned turn — enough for a host LLM to

package/dist/pricing.js

@@ -42,6 +42,9 @@ export function estimatedTtftSeconds(inputTokens) {
     return inputTokens / 25_000;
 }
 export function formatUsd(amount) {
+    // Same reasoning as formatTokens: "$NaN" is worse than "$0.00".
+    if (!Number.isFinite(amount))
+        return "$0.00";
     if (amount >= 1)
         return `$${amount.toFixed(2)}`;
     if (amount >= 0.01)

package/dist/session.js

@@ -12,6 +12,17 @@ import { readdirSync, readFileSync, statSync, existsSync, openSync, readSync, cl
 import { StringDecoder } from "node:string_decoder";
 import { homedir } from "node:os";
 import { join } from "node:path";
+/**
+ * Read one usage field defensively.
+ *
+ * A numeric string plainly means that number, and discarding it would throw
+ * away ground truth and silently fall back to the heuristic — so it is parsed.
+ * Anything else unusable (objects, null, "abc", negatives) counts as nothing.
+ */
+function usageNumber(value) {
+    const n = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : Number.NaN;
+    return Number.isFinite(n) && n >= 0 ? Math.round(n) : 0;
+}
 function projectsDir() {
     return join(homedir(), ".claude", "projects");
 }
@@ -45,6 +56,21 @@ export function listSessions(limit = 20) {
  * conversations.json is an array of conversations, each holding a `mapping`
  * tree of nodes. We profile the most recently updated conversation.
  */
+/**
+ * A stand-in for a non-text export part.
+ *
+ * The bytes are not in the export, so the exact token cost is unknowable; what
+ * matters is that the turn stops being invisible and keeps its place in the
+ * conversation.
+ */
+function chatGptAttachmentLabel(part) {
+    const kind = part?.content_type;
+    if (typeof kind === "string")
+        return `[${kind}]`;
+    if (part?.asset_pointer)
+        return "[image]";
+    return "[attachment]";
+}
 function parseChatGPTExport(data, path) {
     const conversations = data
         .filter((c) => c && typeof c.mapping === "object")
@@ -58,12 +84,21 @@ function parseChatGPTExport(data, path) {
         if (!m?.author?.role || !["user", "assistant", "system"].includes(m.author.role))
             return false;
         const parts = m.content?.parts;
-        return Array.isArray(parts) && parts.some((p) => typeof p === "string" && p.length > 0);
+        if (!Array.isArray(parts))
+            return false;
+        // A turn containing an image is exported as multimodal_text, with the
+        // picture as an object among the string parts. Requiring a non-empty
+        // string dropped those turns entirely, so an image-heavy conversation
+        // profiled as smaller than it is.
+        return parts.some((p) => (typeof p === "string" && p.length > 0) || (p && typeof p === "object"));
     })
         .sort((a, b) => (a.message.create_time ?? 0) - (b.message.create_time ?? 0));
     const messages = nodes.map((n) => ({
         role: n.message.author.role,
-        content: n.message.content.parts.filter((p) => typeof p === "string").join("\n"),
+        content: n.message.content.parts
+            .map((p) => (typeof p === "string" ? p : chatGptAttachmentLabel(p)))
+            .filter((p) => p.length > 0)
+            .join("\n"),
     }));
     return {
         conversationJson: JSON.stringify({ messages }),
@@ -170,7 +205,13 @@ export function parseSessionFile(path) {
             model = message.model;
         const usage = message.usage;
         if (entry.type === "assistant" && usage) {
-            const total = (usage.input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0);
+            // Coerce, do not trust: a transcript whose usage numbers are STRINGS
+            // turned `1200 + 300` into "12003000" through JavaScript concatenation,
+            // an 8000x overstatement that drives the hook, the cost figures and the
+            // window percentage. Anything not a finite non-negative number is 0.
+            const total = usageNumber(usage.input_tokens) +
+                usageNumber(usage.cache_read_input_tokens) +
+                usageNumber(usage.cache_creation_input_tokens);
             if (total > 0) {
                 reportedInputTokens = total;
                 usageSamples.push({ index: messages.length, input: total });

package/dist/tokens.js

@@ -50,6 +50,10 @@ function symbolDensity(text) {
     return (symbols?.length ?? 0) / text.length;
 }
 export function estimateTokens(text) {
+    // Public API: callers outside this package pass whatever they have, and a
+    // TypeError from a token estimator is never the useful answer.
+    if (typeof text !== "string")
+        text = String(text ?? "");
     if (!text)
         return 0;
     // Denser tokenization for code/JSON-like content, lighter for plain prose.
@@ -60,6 +64,10 @@ export function estimateTokens(text) {
 /** Per-message structural overhead (role markers, delimiters) is roughly constant. */
 export const MESSAGE_OVERHEAD_TOKENS = 4;
 export function formatTokens(n) {
+    // A NaN reaching a report renders literally as "NaN tokens"; show nothing
+    // rather than something false.
+    if (!Number.isFinite(n))
+        return "0";
     if (n >= 1_000_000)
         return `${(n / 1_000_000).toFixed(1)}M`;
     if (n >= 10_000)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Profile and optimize LLM context windows. See what's eating your tokens and fix it — works with Claude, GPT, Gemini, and any MCP-capable AI app.",
   "keywords": [
     "llm",
@@ -40,7 +40,7 @@
   },
   "scripts": {
     "build": "tsc && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm test",
     "dev": "tsc --watch",
     "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/proxy-abort.test.js dist/test/hook.test.js dist/test/mcp-http.test.js dist/test/doctor.test.js dist/test/watch.test.js dist/test/chatgpt-export.test.js dist/test/config.test.js dist/test/dashboard.test.js dist/test/cursor.test.js dist/test/cache.test.js dist/test/session.test.js dist/test/accuracy.test.js dist/test/cache-stability.test.js dist/test/ledger.test.js"
   },