context-doctor 0.2.0

package/dist/mcp.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * context-doctor MCP server (stdio).
+ *
+ * Plug into Claude Desktop, ChatGPT desktop (developer mode), Cursor, or any
+ * MCP client:
+ *
+ *   { "mcpServers": { "context-doctor": { "command": "npx", "args": ["-y", "context-doctor-mcp"] } } }
+ *
+ * Tools:
+ *   profile_context   — analyze a conversation/prompt, report token breakdown + findings
+ *   optimize_context  — apply safe strategies, return the slimmed conversation
+ *   context_best_practices — curated checklist for a given provider/use case
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { parseConversation } from "./parse.js";
+import { profileConversation } from "./profile.js";
+import { optimizeConversation } from "./optimize.js";
+import { renderProfile } from "./report.js";
+import { formatTokens } from "./tokens.js";
+const server = new McpServer({ name: "context-doctor", version: "0.2.0" });
+const STRATEGY_IDS = ["dedupe", "trim-tool-results", "strip-base64", "prune-history"];
+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.", {
+    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"),
+}, async ({ conversation, model }) => {
+    const profile = profileConversation(parseConversation(conversation), model);
+    return { content: [{ type: "text", text: renderProfile(profile) }] };
+});
+server.tool("optimize_context", "Rewrite a conversation to reclaim tokens using deterministic strategies: dedupe repeated content, trim stale tool results, strip base64 blobs, optionally prune old history. Returns the slimmed conversation JSON plus a savings summary. No LLM calls — safe and inspectable.", {
+    conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array)"),
+    strategies: z.array(z.enum(STRATEGY_IDS)).optional()
+        .describe("Strategies to apply. Default: dedupe, trim-tool-results, strip-base64. Add prune-history for lossy compaction of old turns."),
+    keep_recent: z.number().int().positive().optional().describe("Messages at the tail to leave untouched (default 6)"),
+    max_tool_result_tokens: z.number().int().positive().optional().describe("Token budget for trimmed tool results (default 300)"),
+}, async ({ conversation, strategies, keep_recent, max_tool_result_tokens }) => {
+    const result = optimizeConversation(conversation, {
+        strategies: strategies,
+        keepRecent: keep_recent,
+        maxToolResultTokens: max_tool_result_tokens,
+    });
+    const saved = result.tokensBefore - result.tokensAfter;
+    const summary = `Saved ~${formatTokens(saved)} tokens (${formatTokens(result.tokensBefore)} → ${formatTokens(result.tokensAfter)}) ` +
+        `via ${result.applied.length} change(s):\n` +
+        result.applied.map((c) => `- [${c.strategy}] message #${c.messageIndex}: ${c.note} (~${formatTokens(c.tokensSaved)})`).join("\n");
+    const content = [
+        { type: "text", text: summary },
+        { type: "text", text: JSON.stringify(result.conversation, null, 2) },
+    ];
+    // Host-model summarization: instead of calling an LLM ourselves (which would
+    // need an API key), hand the pruned material to the model that invoked this
+    // tool and ask IT to write the summary.
+    if (result.prunedDigest) {
+        content.push({
+            type: "text",
+            text: "ACTION REQUIRED (you, the assistant calling this tool): the pruned turns are digested below. " +
+                "Write a dense factual summary of them (≤150 tokens: decisions, current state, open items, key identifiers) " +
+                "and replace the '[context-doctor: ... pruned]' stub message in the conversation above with your summary " +
+                "before presenting the result.\n\nPRUNED TURNS DIGEST:\n" + result.prunedDigest,
+        });
+    }
+    return { content };
+});
+const BEST_PRACTICES = {
+    general: [
+        "Put stable content first (system prompt, tool definitions, reference docs) and volatile content last — prompt caches match byte-identical prefixes only.",
+        "Truncate or summarize tool results before they enter history; keep only what the model actually needs downstream.",
+        "Never inline base64/binary data in text content — use file/image APIs.",
+        "Summarize and drop conversation history past ~30-40 turns; models lose the middle of long contexts well before the hard limit.",
+        "Deduplicate: if the same document/result appears twice, replace later copies with a reference.",
+        "Measure before optimizing — profile the conversation to find the actual heavy hitters.",
+    ],
+    anthropic: [
+        "Use prompt caching with cache_control breakpoints after your stable prefix — cached reads cost ~10% of base input price.",
+        "Claude models have a 200k window, but quality degrades under heavy fill; aim to stay under ~70%.",
+        "For agents: prefer compact tool-result summaries in history and re-fetch details on demand.",
+    ],
+    openai: [
+        "Prefix caching is automatic for prompts >1024 tokens — but only on byte-identical prefixes, so keep the front of your prompt stable.",
+        "Use max_completion_tokens headroom math: input + output must fit the window together.",
+    ],
+};
+server.tool("context_best_practices", "Get a curated checklist of context-management best practices, optionally specialized for a provider (anthropic, openai).", {
+    provider: z.enum(["general", "anthropic", "openai"]).optional().describe("Provider to specialize tips for (default: general)"),
+}, async ({ provider }) => {
+    const tips = [...BEST_PRACTICES.general, ...(provider && provider !== "general" ? BEST_PRACTICES[provider] : [])];
+    return { content: [{ type: "text", text: tips.map((t, i) => `${i + 1}. ${t}`).join("\n") }] };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/optimize.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The optimizer: deterministic, lossless-first strategies that rewrite a
+ * conversation's message array to reclaim tokens. No LLM calls — everything
+ * here is safe to run offline and inspect before use.
+ *
+ * Strategies operate on the ORIGINAL JSON structure (not the normalized view)
+ * so the output is a drop-in replacement for the input conversation.
+ */
+export type StrategyId = "dedupe" | "trim-tool-results" | "prune-history" | "strip-base64";
+export interface OptimizeOptions {
+    strategies?: StrategyId[];
+    /** Tool results older than this many messages from the end get trimmed. */
+    keepRecent?: number;
+    /** Max tokens a trimmed tool result keeps. */
+    maxToolResultTokens?: number;
+}
+export interface AppliedChange {
+    strategy: StrategyId;
+    messageIndex: number;
+    tokensSaved: number;
+    note: string;
+}
+export interface OptimizeResult {
+    /** The rewritten conversation, same shape as the input. */
+    conversation: unknown;
+    tokensBefore: number;
+    tokensAfter: number;
+    applied: AppliedChange[];
+    /**
+     * When prune-history ran: a compact digest of the pruned turns. A host LLM
+     * (e.g. the model running in Claude Desktop via MCP) can summarize this and
+     * replace the stub message — summarization without any API key.
+     */
+    prunedDigest?: string;
+}
+export declare function optimizeConversation(input: string, options?: OptimizeOptions): OptimizeResult;

package/dist/optimize.js

@@ -0,0 +1,189 @@
+/**
+ * The optimizer: deterministic, lossless-first strategies that rewrite a
+ * conversation's message array to reclaim tokens. No LLM calls — everything
+ * here is safe to run offline and inspect before use.
+ *
+ * Strategies operate on the ORIGINAL JSON structure (not the normalized view)
+ * so the output is a drop-in replacement for the input conversation.
+ */
+import { createHash } from "node:crypto";
+import { estimateTokens } from "./tokens.js";
+const DEFAULTS = {
+    strategies: ["dedupe", "trim-tool-results", "strip-base64"],
+    keepRecent: 6,
+    maxToolResultTokens: 300,
+};
+const BASE64_RE = /(?:data:[\w/+.-]+;base64,)?[A-Za-z0-9+/]{500,}={0,2}/g;
+function hash(text) {
+    return createHash("sha1").update(text.replace(/\s+/g, " ").trim()).digest("hex");
+}
+/** Extract all text from a message content value (string or block array). */
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return JSON.stringify(content ?? "");
+    return content
+        .map((b) => {
+        if (typeof b === "string")
+            return b;
+        if (b?.type === "text")
+            return b.text ?? "";
+        if (b?.type === "tool_result")
+            return textOf(b.content);
+        if (b?.type === "tool_use")
+            return JSON.stringify(b.input ?? {});
+        return "";
+    })
+        .join("\n");
+}
+/**
+ * Replace the text of a message content value, preserving block structure.
+ * tool_result blocks must keep their type and tool_use_id — the Anthropic API
+ * rejects conversations where a tool_use has no matching tool_result — so the
+ * replacement text goes INSIDE the first tool_result/text block rather than
+ * replacing the block itself. Later text blocks are dropped; other block types
+ * (tool_use, image) pass through untouched.
+ */
+function replaceText(content, newText) {
+    if (typeof content === "string" || !Array.isArray(content))
+        return newText;
+    let placed = false;
+    const out = content
+        .map((b) => {
+        if (b?.type === "tool_result") {
+            const replaced = { ...b, content: placed ? "[removed]" : newText };
+            placed = true;
+            return replaced;
+        }
+        if (b?.type === "text") {
+            if (placed)
+                return null;
+            placed = true;
+            return { ...b, text: newText };
+        }
+        return b;
+    })
+        .filter(Boolean);
+    if (!placed)
+        out.push({ type: "text", text: newText });
+    return out;
+}
+function truncateToTokens(text, maxTokens) {
+    const approxChars = maxTokens * 4;
+    if (text.length <= approxChars)
+        return text;
+    const head = text.slice(0, approxChars);
+    const omitted = text.length - approxChars;
+    return `${head}\n…[context-doctor: trimmed ${omitted} chars of stale tool output]`;
+}
+function isToolResultMessage(m) {
+    if (m?.role === "tool")
+        return true;
+    if (Array.isArray(m?.content))
+        return m.content.some((b) => b?.type === "tool_result");
+    return false;
+}
+export function optimizeConversation(input, options = {}) {
+    // ?? per field (not object spread) so an explicit `undefined` from a caller
+    // still falls back to the default.
+    const opts = {
+        strategies: options.strategies ?? DEFAULTS.strategies,
+        keepRecent: options.keepRecent ?? DEFAULTS.keepRecent,
+        maxToolResultTokens: options.maxToolResultTokens ?? DEFAULTS.maxToolResultTokens,
+    };
+    let data;
+    try {
+        data = JSON.parse(input);
+    }
+    catch {
+        throw new Error("optimize requires a JSON conversation (message array, or object with a `messages` field)");
+    }
+    const messages = Array.isArray(data) ? data : data.messages;
+    if (!Array.isArray(messages)) {
+        throw new Error("No `messages` array found in input");
+    }
+    const tokensBefore = messages.reduce((s, m) => s + estimateTokens(textOf(m.content)), 0);
+    const applied = [];
+    // -- strip-base64: replace inline blobs with a placeholder --------------------
+    if (opts.strategies.includes("strip-base64")) {
+        messages.forEach((m, i) => {
+            const text = textOf(m.content);
+            if (!BASE64_RE.test(text))
+                return;
+            BASE64_RE.lastIndex = 0;
+            const before = estimateTokens(text);
+            const cleaned = text.replace(BASE64_RE, "[context-doctor: base64 blob removed — use file/image APIs instead]");
+            const saved = before - estimateTokens(cleaned);
+            if (saved > 50) {
+                m.content = replaceText(m.content, cleaned);
+                applied.push({ strategy: "strip-base64", messageIndex: i, tokensSaved: saved, note: "Removed inline base64 data" });
+            }
+        });
+    }
+    // -- dedupe: identical content beyond the first occurrence --------------------
+    if (opts.strategies.includes("dedupe")) {
+        const seen = new Map();
+        messages.forEach((m, i) => {
+            const text = textOf(m.content);
+            if (text.length < 300)
+                return;
+            const h = hash(text);
+            const first = seen.get(h);
+            if (first === undefined) {
+                seen.set(h, i);
+                return;
+            }
+            const saved = estimateTokens(text);
+            m.content = replaceText(m.content, `[context-doctor: identical to message #${first} — content removed]`);
+            applied.push({ strategy: "dedupe", messageIndex: i, tokensSaved: saved, note: `Duplicate of message #${first}` });
+        });
+    }
+    // -- trim-tool-results: shrink stale tool output ------------------------------
+    if (opts.strategies.includes("trim-tool-results")) {
+        const cutoff = messages.length - opts.keepRecent;
+        messages.forEach((m, i) => {
+            if (i >= cutoff || !isToolResultMessage(m))
+                return;
+            const text = textOf(m.content);
+            const before = estimateTokens(text);
+            if (before <= opts.maxToolResultTokens)
+                return;
+            const trimmed = truncateToTokens(text, opts.maxToolResultTokens);
+            m.content = replaceText(m.content, trimmed);
+            applied.push({
+                strategy: "trim-tool-results",
+                messageIndex: i,
+                tokensSaved: before - estimateTokens(trimmed),
+                note: "Stale tool result truncated",
+            });
+        });
+    }
+    // -- prune-history: replace the older half with a stub ------------------------
+    // Opt-in only: it is lossy, so it is not in the default strategy set.
+    let prunedDigest;
+    if (opts.strategies.includes("prune-history") && messages.length > opts.keepRecent * 2) {
+        const keepFrom = messages.length - opts.keepRecent;
+        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
+        // write a faithful summary, small enough not to defeat the pruning.
+        prunedDigest = pruned
+            .map((m, i) => `[${i}:${m.role}] ${textOf(m.content).replace(/\s+/g, " ").slice(0, 200)}`)
+            .join("\n");
+        const stub = {
+            role: "user",
+            content: `[context-doctor: ${pruned.length} earlier messages (~${prunedTokens} tokens) pruned. ` +
+                `Replace this stub with an LLM-written summary of those turns for best results.]`,
+        };
+        messages.splice(0, keepFrom, stub);
+        applied.push({
+            strategy: "prune-history",
+            messageIndex: 0,
+            tokensSaved: prunedTokens - estimateTokens(stub.content),
+            note: `Pruned ${pruned.length} old messages`,
+        });
+    }
+    const tokensAfter = messages.reduce((s, m) => s + estimateTokens(textOf(m.content)), 0);
+    return { conversation: data, tokensBefore, tokensAfter, applied, prunedDigest };
+}

package/dist/parse.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Normalize conversations from different providers into one shape.
+ *
+ * Accepted inputs:
+ *  - OpenAI chat format:    { messages: [{ role, content, tool_calls?, tool_call_id? }] }
+ *  - Anthropic format:      { system?, messages: [{ role, content: string | Block[] }] }
+ *    where Block = { type: "text" | "tool_use" | "tool_result" | "image", ... }
+ *  - Bare message array:    [{ role, content }, ...]
+ *  - Raw text:              treated as a single user message (last-resort fallback)
+ */
+export type MessageKind = "system" | "user" | "assistant" | "tool_call" | "tool_result" | "image" | "other";
+export interface NormalizedMessage {
+    /** Index in the original message array (-1 for extracted system prompt). */
+    index: number;
+    role: string;
+    kind: MessageKind;
+    /** Flattened text content used for token estimation and analysis. */
+    text: string;
+    /** Tool name when kind is tool_call/tool_result and it is known. */
+    toolName?: string;
+    /** Just the tool-call portion (name + args), for repeat-call detection. */
+    toolCallText?: string;
+    /** True when the content contained non-text blocks (images, documents). */
+    hasBinary: boolean;
+}
+export interface NormalizedConversation {
+    messages: NormalizedMessage[];
+    /** Format detected, for reporting. */
+    sourceFormat: "openai" | "anthropic" | "array" | "text";
+}
+export declare function parseConversation(input: string): NormalizedConversation;

package/dist/parse.js

@@ -0,0 +1,118 @@
+/**
+ * Normalize conversations from different providers into one shape.
+ *
+ * Accepted inputs:
+ *  - OpenAI chat format:    { messages: [{ role, content, tool_calls?, tool_call_id? }] }
+ *  - Anthropic format:      { system?, messages: [{ role, content: string | Block[] }] }
+ *    where Block = { type: "text" | "tool_use" | "tool_result" | "image", ... }
+ *  - Bare message array:    [{ role, content }, ...]
+ *  - Raw text:              treated as a single user message (last-resort fallback)
+ */
+function flattenContent(content) {
+    if (typeof content === "string")
+        return { text: content, hasBinary: false };
+    if (!Array.isArray(content))
+        return { text: JSON.stringify(content ?? ""), hasBinary: false };
+    let text = "";
+    let hasBinary = false;
+    let toolName;
+    let kind;
+    let toolCallText = "";
+    for (const block of content) {
+        if (block == null || typeof block !== "object") {
+            text += String(block ?? "");
+            continue;
+        }
+        const b = block;
+        switch (b.type) {
+            case "text":
+                text += b.text ?? "";
+                break;
+            case "tool_use": {
+                kind = "tool_call";
+                toolName = b.name ?? toolName;
+                const call = `[tool call: ${b.name}] ${JSON.stringify(b.input ?? {})}`;
+                text += call;
+                toolCallText += call;
+                break;
+            }
+            case "tool_result": {
+                kind = "tool_result";
+                const inner = flattenContent(b.content);
+                hasBinary = hasBinary || inner.hasBinary;
+                text += inner.text;
+                break;
+            }
+            case "image":
+            case "document":
+                hasBinary = true;
+                text += `[${b.type}]`;
+                break;
+            case "thinking":
+                // Count the thinking text but NOT the signature — it is an opaque
+                // base64 blob the API requires, not something the user can trim.
+                text += b.thinking ?? "";
+                break;
+            case "redacted_thinking":
+                text += "[redacted thinking]";
+                break;
+            default:
+                text += JSON.stringify(b);
+        }
+    }
+    return { text, hasBinary, toolName, kind, toolCallText: toolCallText || undefined };
+}
+function normalizeMessage(raw, index) {
+    const role = String(raw.role ?? "user");
+    const flat = flattenContent(raw.content);
+    let kind = flat.kind ?? (["system", "user", "assistant"].includes(role) ? role : "other");
+    let toolName = flat.toolName;
+    let text = flat.text;
+    let toolCallText = flat.toolCallText;
+    // OpenAI-style tool plumbing lives outside `content`.
+    if (role === "tool") {
+        kind = "tool_result";
+    }
+    const toolCalls = raw.tool_calls;
+    if (Array.isArray(toolCalls) && toolCalls.length > 0) {
+        kind = "tool_call";
+        toolName = toolCalls[0]?.function?.name ?? toolCalls[0]?.name;
+        const calls = toolCalls
+            .map((tc) => `[tool call: ${tc.function?.name ?? tc.name}] ${tc.function?.arguments ?? JSON.stringify(tc.input ?? {})}`)
+            .join("\n");
+        text += calls;
+        toolCallText = (toolCallText ?? "") + calls;
+    }
+    return { index, role, kind, text, toolName, toolCallText, hasBinary: flat.hasBinary };
+}
+export function parseConversation(input) {
+    let data;
+    try {
+        data = JSON.parse(input);
+    }
+    catch {
+        // Not JSON — treat the whole thing as one user message so profiling still works.
+        return {
+            sourceFormat: "text",
+            messages: [{ index: 0, role: "user", kind: "user", text: input, hasBinary: false }],
+        };
+    }
+    if (Array.isArray(data)) {
+        return {
+            sourceFormat: "array",
+            messages: data.map((m, i) => normalizeMessage(m, i)),
+        };
+    }
+    const obj = data;
+    const rawMessages = obj.messages ?? [];
+    const messages = [];
+    // Anthropic keeps the system prompt outside the messages array.
+    if (obj.system != null) {
+        const flat = flattenContent(obj.system);
+        messages.push({ index: -1, role: "system", kind: "system", text: flat.text, hasBinary: flat.hasBinary });
+    }
+    messages.push(...rawMessages.map((m, i) => normalizeMessage(m, i)));
+    const isAnthropic = obj.system != null ||
+        rawMessages.some((m) => Array.isArray(m.content) && m.content.some((b) => b?.type === "tool_use" || b?.type === "tool_result"));
+    return { sourceFormat: isAnthropic ? "anthropic" : "openai", messages };
+}

package/dist/pricing.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-model pricing for cost estimation, USD per million tokens.
+ *
+ * Anthropic prices are current as of mid-2026 (first-party API list rates).
+ * OpenAI/Google figures are approximate public list prices and drift over
+ * time — all cost output is labeled as an estimate. One table, one file,
+ * easy to update: PRs welcome when prices change.
+ */
+export interface ModelPricing {
+    /** USD per 1M input tokens. */
+    inputPerM: number;
+    /** USD per 1M output tokens (unused by the profiler, kept for reference). */
+    outputPerM: number;
+    /** USD per 1M cached input tokens read (≈10% of input for Claude/OpenAI). */
+    cacheReadPerM: number;
+}
+export declare function pricingFor(model?: string): ModelPricing | undefined;
+export declare function inputCostUsd(tokens: number, pricing: ModelPricing): number;
+/**
+ * Rough time-to-first-token impact of input size. Prompt processing on major
+ * providers runs on the order of tens of thousands of tokens per second;
+ * ~25k tok/s is a serviceable cross-provider planning number, so every 10k
+ * input tokens costs roughly 0.4s of TTFT (much less on cache hits).
+ */
+export declare function estimatedTtftSeconds(inputTokens: number): number;
+export declare function formatUsd(amount: number): string;

package/dist/pricing.js

@@ -0,0 +1,48 @@
+/**
+ * Per-model pricing for cost estimation, USD per million tokens.
+ *
+ * Anthropic prices are current as of mid-2026 (first-party API list rates).
+ * OpenAI/Google figures are approximate public list prices and drift over
+ * time — all cost output is labeled as an estimate. One table, one file,
+ * easy to update: PRs welcome when prices change.
+ */
+const PRICING = [
+    [/claude.*fable|claude.*mythos/i, { inputPerM: 10, outputPerM: 50, cacheReadPerM: 1 }],
+    [/claude.*opus/i, { inputPerM: 5, outputPerM: 25, cacheReadPerM: 0.5 }],
+    [/claude.*sonnet/i, { inputPerM: 3, outputPerM: 15, cacheReadPerM: 0.3 }],
+    [/claude.*haiku/i, { inputPerM: 1, outputPerM: 5, cacheReadPerM: 0.1 }],
+    [/gpt-4o-mini/i, { inputPerM: 0.15, outputPerM: 0.6, cacheReadPerM: 0.075 }],
+    [/gpt-4o|gpt-4\.1/i, { inputPerM: 2.5, outputPerM: 10, cacheReadPerM: 1.25 }],
+    [/gpt-4-turbo/i, { inputPerM: 10, outputPerM: 30, cacheReadPerM: 10 }],
+    [/o[13](-|$)/i, { inputPerM: 2, outputPerM: 8, cacheReadPerM: 1 }],
+    [/gemini.*flash/i, { inputPerM: 0.1, outputPerM: 0.4, cacheReadPerM: 0.025 }],
+    [/gemini.*pro/i, { inputPerM: 1.25, outputPerM: 5, cacheReadPerM: 0.31 }],
+];
+export function pricingFor(model) {
+    if (!model)
+        return undefined;
+    for (const [pattern, pricing] of PRICING) {
+        if (pattern.test(model))
+            return pricing;
+    }
+    return undefined;
+}
+export function inputCostUsd(tokens, pricing) {
+    return (tokens / 1_000_000) * pricing.inputPerM;
+}
+/**
+ * Rough time-to-first-token impact of input size. Prompt processing on major
+ * providers runs on the order of tens of thousands of tokens per second;
+ * ~25k tok/s is a serviceable cross-provider planning number, so every 10k
+ * input tokens costs roughly 0.4s of TTFT (much less on cache hits).
+ */
+export function estimatedTtftSeconds(inputTokens) {
+    return inputTokens / 25_000;
+}
+export function formatUsd(amount) {
+    if (amount >= 1)
+        return `$${amount.toFixed(2)}`;
+    if (amount >= 0.01)
+        return `$${amount.toFixed(3)}`;
+    return `$${amount.toFixed(4)}`;
+}

package/dist/profile.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The profiler: turns a normalized conversation into a breakdown of where
+ * tokens go, plus a list of actionable findings ("what's eating my window").
+ */
+import { NormalizedConversation } from "./parse.js";
+export type Category = "system" | "user" | "assistant" | "tool_calls" | "tool_results" | "other";
+export interface MessageProfile {
+    index: number;
+    role: string;
+    kind: string;
+    tokens: number;
+    preview: string;
+    toolName?: string;
+}
+export type FindingId = "large_tool_result" | "duplicate_content" | "repeated_tool_call" | "base64_blob" | "long_history" | "large_system_prompt" | "cache_ordering" | "near_window_limit";
+export interface Finding {
+    id: FindingId;
+    severity: "info" | "warn" | "high";
+    /** Estimated tokens recoverable by acting on this finding (0 = advisory). */
+    estSavings: number;
+    message: string;
+    suggestion: string;
+    /** Message indexes involved. */
+    messages: number[];
+}
+export interface CostEstimate {
+    /** Input cost of sending this context once, USD (estimate). */
+    perCallUsd: number;
+    /** Input cost over 1,000 calls — the number that makes people act. */
+    per1kCallsUsd: number;
+    /** USD recoverable per call if all savings findings are applied. */
+    savingsPerCallUsd: number;
+    /** Same, over 1,000 calls. */
+    savingsPer1kCallsUsd: number;
+    /** Estimated seconds of time-to-first-token attributable to this input size. */
+    ttftSeconds: number;
+    /** TTFT seconds saved per call if savings are applied. */
+    ttftSavedSeconds: number;
+}
+export interface ContextProfile {
+    totalTokens: number;
+    model?: string;
+    contextWindow?: number;
+    usagePct?: number;
+    messageCount: number;
+    categories: Record<Category, number>;
+    largestMessages: MessageProfile[];
+    findings: Finding[];
+    /** Total estimated savings if all findings with savings are acted on. */
+    totalEstSavings: number;
+    /** Present when the model has a known price. All figures are estimates. */
+    cost?: CostEstimate;
+    sourceFormat: string;
+}
+export declare function profileConversation(conv: NormalizedConversation, model?: string): ContextProfile;