@kunal_dutt/token-lens 0.0.0-stage → 0.2.17

package/types/src/core/advice.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tips that save tokens beyond rewriting the prompt: picking the right model,
+ * capping the answer, pasting less, and handing off long chats. Each tip
+ * depends on the model, the task and the conversation, so they change as the
+ * user switches model or types a different kind of prompt.
+ */
+import type { ContextUsage } from "./budget";
+import type { ModelProfile } from "./models";
+import type { Task, TaskSignals } from "./tasks";
+export interface Tip {
+    id: string;
+    text: string;
+    /** What the tip saves: tokens sent, tokens generated, or hidden reasoning. */
+    saves: "input" | "output" | "reasoning";
+    /** Text the UI can append to the prompt to apply the tip in one click. */
+    append?: string;
+}
+export interface AdviceInput {
+    profile: ModelProfile;
+    task: Task;
+    signals: TaskSignals;
+    promptTokens: number;
+    usage: ContextUsage;
+    /** The prompt, to check for things like XML tags. */
+    text: string;
+}
+export declare function advise(input: AdviceInput): Tip[];

package/types/src/core/budget.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Conversation budget: how full the model's context is, how much each new
+ * message re-reads, and when to hand off to a fresh chat.
+ */
+import type { ModelProfile } from "./models";
+import type { Level } from "./compress";
+import type { Task } from "./tasks";
+export type Zone = "ok" | "warm" | "hot" | "full";
+export interface ContextUsage {
+    conversationTokens: number;
+    promptTokens: number;
+    window: number;
+    /** (conversation + prompt) / window, 0..1+ */
+    ratio: number;
+    zone: Zone;
+    /** Long enough that every new message re-reads a lot, whatever the window. */
+    longChat: boolean;
+}
+/** Past this many tokens a chat is worth handing off even on a huge context window. */
+export declare const LONG_CHAT_TOKENS = 40000;
+export declare function contextUsage(conversationTokens: number, promptTokens: number, profile: ModelProfile, windowOverride?: number): ContextUsage;
+/** "auto" tightens compression as the context fills; an explicit level is respected. */
+export declare function chooseLevel(setting: Level | "auto", usage: ContextUsage): Level;
+/**
+ * A prompt that asks the current model to compress the chat into a brief the
+ * user can paste into a new chat, so the next turns stop re-reading history.
+ */
+export declare function handoffPrompt(task: Task): string;

package/types/src/core/compress.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Rule-based prompt compression that adapts to the model and the task.
+ *
+ * - Only the user's instructions are rewritten. Code, inline code, URLs,
+ *   XML-tagged blocks, quotes, and (for most tasks) material pasted below the
+ *   instruction are left exactly as written.
+ * - Reasoning models get chain-of-thought boilerplate removed; they think anyway.
+ * - Debugging prompts get pasted logs trimmed: repeated lines and library
+ *   stack frames are collapsed.
+ * - The result is only offered when it is shorter in the model's own tokens.
+ */
+import type { ModelProfile } from "./models";
+import { type Task } from "./tasks";
+export type Level = "light" | "balanced" | "aggressive";
+export declare const LEVELS: Level[];
+export interface CompressOptions {
+    profile: ModelProfile;
+    task: Task;
+    level: Level;
+}
+export interface CompressResult {
+    text: string;
+    /** Names of the rules that changed something, in first-applied order. */
+    rules: string[];
+    originalTokens: number;
+    tokens: number;
+    saved: number;
+}
+export declare function compress(text: string, opts: CompressOptions): CompressResult;

package/types/src/core/cost.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cost: what tokens cost, and what a saving is worth, priced for the model in
+ * use. Prices come from the model profile (API list prices by default, or the
+ * user's own), so the same saving is worth more on a pricier model.
+ */
+import type { ModelPricing, ModelProfile } from "./models";
+export type TokenKind = "input" | "output" | "cached";
+export interface Savings {
+    /** Tokens saved per call. */
+    tokens: number;
+    /** USD saved per call; null when the model has no price. */
+    usd: number | null;
+    /** USD saved over 1,000 calls; null when the model has no price. */
+    usdPer1k: number | null;
+}
+/** USD per token of this kind, or null when the model has no price. */
+export declare function perToken(profile: ModelProfile, kind?: TokenKind): number | null;
+/** USD for `tokens` of this kind, or null when the model has no price. */
+export declare function costOf(tokens: number, profile: ModelProfile, kind?: TokenKind): number | null;
+/** What `tokens` fewer input tokens per call are worth. */
+export declare function savingsOf(tokens: number, profile: ModelProfile, kind?: TokenKind): Savings;
+/** What moving `tokens` from full-price input to cached input saves per call. */
+export declare function cachingSavings(tokens: number, profile: ModelProfile): Savings;
+/**
+ * Dollars, with enough digits that small per-prompt amounts don't show as $0.00:
+ * $12.40, $0.84, $0.0031, $0.000042.
+ */
+export declare function formatUsd(usd: number | null | undefined): string;
+/** "$4 in / $20 out per 1M tokens" */
+export declare function describePricing(p: ModelPricing | undefined): string;
+/** One line for a saving: "Saves 1,240 tokens ($0.0050) per call, $4.96 per 1,000 calls". */
+export declare function describeSavings(s: Savings, unit?: string): string;

package/types/src/core/guard.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Meaning guard: a rewrite may drop words, never facts or constraints.
+ * Every number, URL, inline code span, quoted string, negation and hard
+ * constraint word in the original must still be in the rewrite, at least as
+ * often. A rewrite that fails is discarded in favour of the original wording.
+ */
+export interface GuardResult {
+    ok: boolean;
+    /** Anchors the rewrite lost, e.g. "negation:not". */
+    lost: string[];
+}
+/**
+ * `count` (default): every anchor as often as before. `presence`: every anchor
+ * at least once, for comparing texts where exact repeated sentences were removed.
+ */
+export declare function checkMeaning(original: string, rewritten: string, mode?: "count" | "presence"): GuardResult;
+/** Distinct anchors of each kind in the original and how many the rewrite kept, e.g. { number: [3, 3] }. */
+export declare function anchorSummary(original: string, rewritten: string): Record<string, [number, number]>;
+/** Content words of the original that are missing from the rewrite (beyond allowed filler). */
+export declare function lostWords(original: string, rewritten: string): string[];

package/types/src/core/hotspots.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Hotspots: where the tokens go in a prompt, an agent (system prompt, tools,
+ * examples, conversation) or a chat, where they are growing, and the fix for
+ * each spot.
+ *
+ * Every fix is classed by risk to the output:
+ *   safe   keeps the meaning (passes the meaning guard) or doesn't touch what
+ *          the model reads at all (e.g. prompt caching); applied automatically.
+ *   review could change the answer (dropping history, fewer examples, a
+ *          smaller model, a length cap); listed for the user to opt into.
+ */
+import { type Level } from "./compress";
+import { type Savings } from "./cost";
+import { type ModelProfile } from "./models";
+import { type Verification } from "./verify";
+export interface ToolDef {
+    name: string;
+    description?: string;
+    /** JSON schema of the parameters (OpenAI `parameters` / Anthropic `input_schema`). */
+    parameters?: unknown;
+}
+export interface Message {
+    role: "user" | "assistant" | "tool" | "system";
+    content: string;
+    /** Tool calls the assistant made in this message, by tool name. */
+    toolCalls?: string[];
+    /** Token count if the caller already has it (skips recounting). */
+    tokens?: number;
+}
+export interface AgentSpec {
+    system?: string;
+    tools?: ToolDef[];
+    examples?: string[];
+    messages?: Message[];
+    /** The next user message about to be sent. */
+    prompt?: string;
+}
+export type Area = "system" | "tools" | "examples" | "history" | "prompt" | "output";
+export type Risk = "safe" | "review";
+export interface Finding {
+    id: string;
+    area: Area;
+    /** What is happening, in one sentence. */
+    issue: string;
+    /** What to do about it. */
+    fix: string;
+    risk: Risk;
+    /** Tokens saved per call if fixed (estimate). */
+    saves: number;
+    /** USD saved per call at the model's price (caching fixes count the cached-price discount); null without a price. */
+    usd: number | null;
+    /** True when `optimizeAgent` applied it. */
+    applied?: boolean;
+}
+export interface Breakdown {
+    area: Area;
+    label: string;
+    tokens: number;
+}
+export interface HotspotReport {
+    profile: ModelProfile;
+    total: number;
+    /** Input cost of one call at the model's price; null without a price. */
+    costPerCall: number | null;
+    /** Re-sent on every call: system + tools + examples. */
+    fixedOverhead: number;
+    breakdown: Breakdown[];
+    /** Average tokens the conversation grows by per user turn. */
+    growthPerTurn: number;
+    /** User turns left before the context window is full, at the current growth. */
+    turnsLeft: number | null;
+    findings: Finding[];
+}
+export interface LazyTools {
+    /** The two tools to send instead of the full list. */
+    tools: ToolDef[];
+    /** Full definitions by name, for your runtime to return from get_tool_schema. */
+    schemas: Record<string, ToolDef>;
+}
+/**
+ * Load tool definitions on demand (the mcp-compressor pattern): the model sees
+ * a one-line catalog, fetches a tool's full schema with get_tool_schema when it
+ * needs it, and calls it through invoke_tool. Same tools, same model.
+ */
+export declare function lazyTools(tools: ToolDef[]): LazyTools;
+/**
+ * Prompt caching only reuses an identical opening, so a line that changes every
+ * call (a date, an id, the user's name) near the top makes everything after it
+ * full price. Moving those lines to the end keeps the same content, so the
+ * model reads the same facts.
+ */
+export declare function stableFirst(text: string): {
+    text: string;
+    moved: string[];
+};
+/** A strict JSON schema from an example value: every field required, nothing extra. */
+export declare function schemaFromExample(v: unknown): Record<string, unknown>;
+/**
+ * Request settings that make the provider return JSON matching the schema,
+ * so no call is lost to a reply that doesn't parse. The schema comes from the
+ * JSON example in the prompt when there is one.
+ */
+export declare function structuredOutputSetup(spec: AgentSpec, profile: ModelProfile): {
+    fromExample: boolean;
+    setup: Record<string, unknown>;
+};
+export declare function findHotspots(spec: AgentSpec, model: ModelProfile | string): HotspotReport;
+export interface OptimizedAgent {
+    spec: AgentSpec;
+    report: HotspotReport;
+    before: number;
+    after: number;
+    /** Tokens and USD the applied fixes save per call (and per 1,000 calls). */
+    savings: Savings;
+    /** Evidence the optimized agent does the same work: what was compared and whether it held. */
+    verification: Verification;
+}
+/**
+ * Apply every safe fix that rewrites content (wording of the system prompt,
+ * tool descriptions and the next prompt; duplicate history) and return the
+ * new spec. Review fixes and advice-only fixes (caching) are left in the
+ * report for the user to opt into.
+ */
+export declare function optimizeAgent(spec: AgentSpec, model: ModelProfile | string, level?: Level): OptimizedAgent;

package/types/src/core/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Token Lens core: surface-agnostic. The browser extension uses it today; an
+ * API proxy, MCP server or editor plugin can call `analyze` the same way.
+ */
+import { type Tip } from "./advice";
+import { type ContextUsage } from "./budget";
+import { type CompressResult, type Level } from "./compress";
+import { type Savings } from "./cost";
+import { type ModelPricing, type ModelProfile } from "./models";
+import { type TaskInfo } from "./tasks";
+export * from "./advice";
+export * from "./budget";
+export * from "./compress";
+export * from "./cost";
+export * from "./guard";
+export * from "./hotspots";
+export * from "./media";
+export * from "./models";
+export * from "./plans";
+export * from "./redos";
+export * from "./review";
+export * from "./rules";
+export * from "./tasks";
+export * from "./tokens";
+export * from "./verify";
+export interface AnalyzeInput {
+    prompt: string;
+    /** A ModelProfile, or any model label/id to detect one from ("Claude Sonnet 4.5", "gpt-4o"). */
+    model: ModelProfile | string;
+    /** Site or provider id, used when the model label alone is ambiguous. */
+    site?: string;
+    /** Tokens already in the conversation (the history each new message re-reads). */
+    conversationTokens?: number;
+    level?: Level | "auto";
+    contextWindow?: number;
+    /** Your own price for this model (USD per 1M tokens); defaults to the API list price. */
+    pricing?: ModelPricing;
+}
+export interface CostImpact {
+    /** Price used, or undefined when the model has none. */
+    pricing?: ModelPricing;
+    /** Input cost of this prompt alone. */
+    promptUsd: number | null;
+    /** Input cost of sending it: the conversation it re-reads plus the prompt. */
+    sendUsd: number | null;
+    /** What the optimized prompt saves on this send. Later turns re-read the prompt, so it saves that again each turn. */
+    saved: Savings;
+}
+/**
+ * The prompt to paste: asks for the same answer in fewer tokens
+ * (meaning-preserving rewrite). Nothing is added that would change the answer.
+ */
+export interface BestPrompt {
+    text: string;
+    tokens: number;
+    /** What changed, in plain words. */
+    changes: string[];
+    /** What the rewrite was required to keep, e.g. "2/2 numbers, 1/1 negations". */
+    kept: string;
+}
+export interface Analysis {
+    profile: ModelProfile;
+    task: TaskInfo;
+    promptTokens: number;
+    exact: boolean;
+    usage: ContextUsage;
+    level: Level;
+    optimized: CompressResult;
+    tips: Tip[];
+    handoffPrompt: string;
+    cost: CostImpact;
+    best: BestPrompt;
+}
+export declare function analyze(input: AnalyzeInput): Analysis;

package/types/src/core/media.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Images and files: what an attachment costs in tokens before you send it.
+ *
+ * Providers resize images on their side before counting, so a bigger file is
+ * not always more tokens and a smaller file size (JPEG quality) never is. The
+ * count here follows each provider's published rules. Nothing suggests
+ * shrinking an image below what the provider uses, since fewer pixels can
+ * change the answer.
+ */
+import type { ModelProfile } from "./models";
+export interface ImageCost {
+    tokens: number;
+    usd: number | null;
+    /** Size the provider actually counts after its own resizing. */
+    sentAs: {
+        width: number;
+        height: number;
+    };
+}
+export declare function imageCost(width: number, height: number, profile: ModelProfile): ImageCost;
+export interface PdfCost {
+    pages: number;
+    perPage: number;
+    tokens: number;
+    usd: number | null;
+}
+export declare function pdfCost(pages: number, profile: ModelProfile): PdfCost;
+/** Page count of a PDF from its bytes (the page tree's /Count, else /Type /Page objects). */
+export declare function pdfPageCount(bytes: Uint8Array): number;

package/types/src/core/models.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Model profiles: what the plugin knows about each model family, and how it
+ * adapts to it. Profiles are matched from free text (the model picker label a
+ * chat site shows, an API model id, ...), so new versions of a family map to
+ * the right profile without a code change.
+ *
+ * Context windows are approximate defaults for the web apps; they vary by plan
+ * and change often, so users can override them in settings.
+ */
+export type Family = "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "xai" | "other";
+export type TokenizerKind = "o200k" | "heuristic";
+export interface ModelProfile {
+    id: string;
+    label: string;
+    family: Family;
+    /** Approximate context window in tokens. */
+    contextWindow: number;
+    /** Exact tokenizer if one is available offline, otherwise a heuristic. */
+    tokenizer: TokenizerKind;
+    /** Average characters per token on English prose, for the heuristic. */
+    charsPerToken: number;
+    /** Thinks before answering: hidden reasoning tokens, no need for "think step by step". */
+    reasoning: boolean;
+    /** Cheaper/faster sibling to suggest for simple asks, if any. */
+    lighterAlternative?: string;
+    /** Family-specific advice shown alongside the counts. */
+    notes?: string[];
+    /** USD per million tokens, when known. Set for custom or overridden models. */
+    pricing?: ModelPricing;
+}
+export interface ModelPricing {
+    inputPerMTok: number;
+    outputPerMTok: number;
+    cachedInputPerMTok?: number;
+    /** Some models bill the whole request at a higher rate once its input passes a size. */
+    longContext?: {
+        aboveTokens: number;
+        inputPerMTok: number;
+        outputPerMTok: number;
+    };
+}
+export declare const PROFILES: Record<string, ModelProfile>;
+/** The matching rules, for ports of this list (the Python library reads them from a generated file). */
+export declare const MODEL_RULES: ReadonlyArray<readonly [RegExp, string]>;
+/** Fallback profile when a site is known but its model label can't be read. */
+export declare const SITE_DEFAULTS: Record<string, string>;
+/**
+ * A model the built-in list doesn't know, such as a company's own LLM, or a
+ * built-in family overridden with exact numbers (context window, pricing).
+ */
+export interface CustomModel {
+    id: string;
+    label?: string;
+    /**
+     * Model ids or labels this profile applies to. A plain string matches as a
+     * case-insensitive substring ("acme-llm" matches "acme-llm-70b-instruct");
+     * "/.../" is a regular expression.
+     */
+    match?: string[];
+    family?: Family;
+    contextWindow: number;
+    tokenizer?: TokenizerKind;
+    charsPerToken?: number;
+    reasoning?: boolean;
+    lighterAlternative?: string;
+    notes?: string[];
+    pricing?: ModelPricing;
+}
+/**
+ * Add or replace a model profile. Custom models are matched before the
+ * built-in rules, so they can also override a built-in family.
+ */
+export declare function registerModel(model: CustomModel): ModelProfile;
+/** Remove a custom model's matching rules (and its profile, unless it is built in). */
+export declare function unregisterModel(id: string): void;
+/**
+ * Pick the profile for a model label such as "ChatGPT 5 Thinking",
+ * "Claude Opus 4.1" or "2.5 Flash". `siteId` breaks ties when the label alone
+ * doesn't name a family (Gemini's picker just says "2.5 Pro").
+ */
+export declare function detectProfile(hint: string | null | undefined, siteId?: string): ModelProfile;

package/types/src/core/plans.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Subscription plans: how each chat app meters the plan the user is on, and
+ * how to stretch that allowance on the model in use. Never by switching model.
+ *
+ * Apps meter in two ways:
+ *   messages  each send counts once, whatever its length (ChatGPT's per-model
+ *             caps, Gemini's daily prompt limits). Fewer, fuller messages help.
+ *   compute   usage grows with the tokens each message makes the model read
+ *             and write (Claude's 5-hour and weekly limits). Long chats burn
+ *             the allowance fastest, because every message re-reads them.
+ *
+ * Providers rarely publish exact caps. Where a number is known it carries its
+ * source and date and is shown as an estimate; the site's own usage warnings,
+ * when it shows them, take precedence, and users can correct either.
+ */
+import type { ModelProfile } from "./models";
+export type Meter = "messages" | "compute";
+export interface PlanCap {
+    /** Model profile ids the cap covers. */
+    models: string[];
+    messages: number;
+    window: "3h" | "5h" | "day" | "week";
+    source: string;
+    asOf: string;
+}
+export interface Plan {
+    id: string;
+    site: "chatgpt" | "claude" | "gemini" | "other";
+    label: string;
+    meter: Meter;
+    caps: PlanCap[];
+    note?: string;
+}
+export declare const PLANS: Record<string, Plan>;
+/** Plan from the account UI text (sidebar, profile menu), e.g. "Max plan", "Plus", "Google AI Pro". */
+export declare function detectPlan(hint: string, site: string): Plan | null;
+/** What the site itself says about usage: a limit warning, messages left, or percent used. */
+export interface SiteMeter {
+    text: string;
+    messagesLeft?: number;
+    percentUsed?: number;
+    resetsAt?: string;
+    limited: boolean;
+    /** Weekly limit used, when the site reports one separately from the session. */
+    weeklyPercentUsed?: number;
+    /** "account": read from the site's own usage meter for your account; "page": a banner on the page. */
+    source?: "account" | "page";
+}
+/**
+ * Claude's own usage meter for your account (the numbers on Settings > Usage):
+ * the current session and the weekly limit, as percent used.
+ */
+export declare function readClaudeUsage(json: unknown): SiteMeter | null;
+/** Parse a usage banner the site shows ("5 messages remaining until 6 PM", "80% of your weekly limit used"). */
+export declare function readSiteMeter(text: string): SiteMeter | null;
+export interface AllowanceInput {
+    plan: Plan | null;
+    site: string;
+    profile: ModelProfile;
+    /** Tokens already in the chat that this message re-reads. */
+    conversationTokens: number;
+    promptTokens: number;
+    /** Messages sent on this model in each window, counted locally. */
+    sent?: Partial<Record<PlanCap["window"], number>>;
+    siteMeter?: SiteMeter | null;
+}
+export interface Allowance {
+    meter: Meter;
+    plan: Plan | null;
+    /** One line on what this message uses of the allowance. */
+    share: string;
+    /** Model-specific ways to stretch it; none switch the model. */
+    tips: Array<{
+        id: string;
+        text: string;
+        action?: "handoff" | "append";
+        append?: string;
+    }>;
+    cap?: PlanCap & {
+        used: number;
+        left: number;
+    };
+    /** What the site itself shows about usage, if anything. */
+    siteMeter?: SiteMeter | null;
+    /** compute meter: how many times more this message reads than it would in a fresh chat with a handoff brief. */
+    freshChatMultiple?: number;
+}
+export declare function allowance(input: AllowanceInput): Allowance;

package/types/src/core/redos.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Redos: tokens spent on answers that were thrown away, either regenerated
+ * (the site's "2 / 2" arrows) or re-asked ("no, I meant ..."), and the single
+ * prompt that would likely have worked the first time.
+ *
+ * A redo costs a whole turn: the history it re-read plus the reply it
+ * produced. The suggested prompt only joins what the user already said across
+ * the attempts; it adds nothing new.
+ */
+import type { Message } from "./hotspots";
+import type { ModelProfile } from "./models";
+export interface Redo {
+    kind: "regenerate" | "reask";
+    /** Index of the user message whose answer was redone. */
+    index: number;
+    preview: string;
+    /** Extra attempts beyond the first. */
+    extra: number;
+    tokens: number;
+    usd: number | null;
+}
+export interface RedoReport {
+    redos: Redo[];
+    tokens: number;
+    usd: number | null;
+    /** One prompt carrying everything said across the attempts of the costliest re-ask. */
+    firstTimePrompt?: string;
+}
+/**
+ * @param regenerations assistant message index -> how many versions the site shows (e.g. 3 for "3 / 3").
+ */
+export declare function findRedos(messages: Message[], profile: ModelProfile, regenerations?: Record<number, number>): RedoReport;

package/types/src/core/review.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Chat review: looks back over the messages already sent in a conversation and
+ * shows where tokens could have been saved, and what that would have cost.
+ *
+ * A message sent in turn i is re-read as history by every later turn, so a
+ * shorter message saves its difference once when sent plus once per later
+ * turn. Only meaning-preserving rewrites count toward the saving (the same
+ * compress + meaning guard used for new prompts); tips that could change the
+ * answer (length caps, pasting less) are listed separately, never counted.
+ */
+import { type Tip } from "./advice";
+import { type Level } from "./compress";
+import { type Savings } from "./cost";
+import type { Message } from "./hotspots";
+import type { ModelProfile } from "./models";
+import { type Task } from "./tasks";
+export interface ReviewedMessage {
+    /** Position in the conversation (0-based, all roles). */
+    index: number;
+    /** First words of the message. */
+    preview: string;
+    task: Task;
+    tokens: number;
+    /** Tokens the meaning-preserving rewrite saves on one read. */
+    shorterBy: number;
+    rules: string[];
+    /** Later turns that re-read this message. */
+    rereads: number;
+    /** Total saving: shorterBy × (1 + rereads), priced for the model. */
+    saved: Savings;
+    /** What to do differently next time (may change the answer, so never counted). */
+    tips: Tip[];
+}
+export interface ChatReview {
+    messages: ReviewedMessage[];
+    /** Total over all user messages, including re-reads. */
+    saved: Savings;
+    /** User messages reviewed. */
+    reviewed: number;
+}
+export interface ReviewOptions {
+    level?: Level;
+    /** Cache of per-message results keyed by text, so long chats aren't re-analysed every refresh. */
+    cache?: Map<string, Omit<ReviewedMessage, "index" | "rereads" | "saved">>;
+}
+export declare function reviewChat(messages: Message[], profile: ModelProfile, opts?: ReviewOptions): ChatReview;

package/types/src/core/rules.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Coding-agent rule files (CLAUDE.md, AGENTS.md, .cursorrules, copilot
+ * instructions, ...) are re-sent on every turn, so every line costs once per
+ * turn. This audit finds repeated lines (within and across files) and wording
+ * that can be tightened without losing meaning, and flags references to files
+ * that no longer exist.
+ *
+ * Only exact repeats and meaning-preserving wording go into the trimmed files,
+ * so the agent gets the same instructions; stale references are only listed,
+ * since removing an instruction can change what the agent does.
+ */
+import { type Savings } from "./cost";
+import type { ModelProfile } from "./models";
+export interface RuleFile {
+    path: string;
+    content: string;
+}
+export interface RuleFinding {
+    kind: "duplicate" | "stale-path";
+    path: string;
+    line: number;
+    text: string;
+    detail: string;
+    /** Tokens per turn this line costs. */
+    tokens: number;
+    /** True when the trimmed file already drops it. */
+    applied: boolean;
+}
+export interface RuleFileResult {
+    path: string;
+    tokens: number;
+    trimmed: string;
+    trimmedTokens: number;
+}
+export interface RulesAudit {
+    files: RuleFileResult[];
+    findings: RuleFinding[];
+    before: number;
+    after: number;
+    /** Saving per turn from the trimmed files (repeats and wording only). */
+    saved: Savings;
+    /** Tokens per turn on lines that mention missing files (listed, not removed). */
+    stale: number;
+}
+export declare function auditRules(files: RuleFile[], profile: ModelProfile, opts?: {
+    knownPaths?: string[];
+}): RulesAudit;