mcp-context-cost 0.3.0 → 0.5.0

package/dist/audit/deferral.js

@@ -0,0 +1,376 @@
+/** Share of the context window at which deferral activates under `auto`. */
+export const TOOL_SEARCH_AUTO_SHARE = 0.1;
+/** The variables that decide whether this machine's Claude Code defers. */
+export const TOOL_SEARCH_VARS = [
+    'ENABLE_TOOL_SEARCH',
+    'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS',
+    'ANTHROPIC_BASE_URL',
+];
+/** Pick the three variables that matter out of a process environment. */
+export function toolSearchEnv(env) {
+    return {
+        ENABLE_TOOL_SEARCH: env.ENABLE_TOOL_SEARCH,
+        CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS,
+        ANTHROPIC_BASE_URL: env.ANTHROPIC_BASE_URL,
+    };
+}
+/** What `source` says for the process environment, which has no path. */
+export const SHELL_SOURCE = '(shell environment)';
+/** A source as it is published: what it sets, by name. */
+export function toolSearchSourceRecord(s) {
+    return {
+        scope: s.scope,
+        source: s.source,
+        state: s.state,
+        sets: TOOL_SEARCH_VARS.filter((n) => (s.vars[n] ?? '').trim() !== ''),
+    };
+}
+/** The one host Claude Code treats as first-party for the tool-search fallback. */
+const FIRST_PARTY_API_HOST = 'api.anthropic.com';
+/** What is printed for a base URL we could not parse — a marker, not the value. */
+const UNREADABLE_BASE_URL = '(unreadable URL)';
+/**
+ * The hostname of a base URL, or null if it does not parse.
+ *
+ * The hostname is the whole of what the mode decision needs, and it is also the
+ * whole of what may leave this function: the rest of the value can carry a
+ * credential. A value that does not parse is not first-party, which is the
+ * reading that says tokens are paid — never the one that says they are free.
+ */
+function baseUrlHost(raw) {
+    try {
+        return new URL(raw).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the tool-search setting out of ONE environment. Values are matched
+ * exactly as documented: an unrecognized value produces `setting-unrecognized`
+ * rather than a guess, because guessing here would print a definite verdict
+ * about tokens the reader may or may not be paying.
+ *
+ * `source` is left null here: this function is given one environment and has no
+ * way to say which of the machine's places it came from. `resolveToolSearchSources`,
+ * which does, fills it in.
+ */
+export function resolveToolSearch(env) {
+    const betas = env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS?.trim();
+    // Read first: documented as not overridable by ENABLE_TOOL_SEARCH.
+    if (betas) {
+        return {
+            mode: 'loads-upfront',
+            thresholdShare: null,
+            variable: 'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS',
+            value: betas,
+            source: null,
+            readFromMachine: true,
+        };
+    }
+    const raw = env.ENABLE_TOOL_SEARCH?.trim();
+    const set = (mode, thresholdShare) => ({
+        mode,
+        thresholdShare,
+        variable: 'ENABLE_TOOL_SEARCH',
+        value: raw ?? null,
+        source: null,
+        readFromMachine: true,
+    });
+    if (raw === undefined || raw === '') {
+        const base = env.ANTHROPIC_BASE_URL?.trim();
+        if (base) {
+            const host = baseUrlHost(base);
+            if (host !== FIRST_PARTY_API_HOST) {
+                return {
+                    mode: 'loads-upfront',
+                    thresholdShare: null,
+                    variable: 'ANTHROPIC_BASE_URL',
+                    // The hostname alone. `base` itself is never carried out of here.
+                    value: host ?? UNREADABLE_BASE_URL,
+                    source: null,
+                    readFromMachine: true,
+                };
+            }
+        }
+        return {
+            mode: 'defers-all',
+            thresholdShare: null,
+            variable: 'ENABLE_TOOL_SEARCH',
+            value: null,
+            source: null,
+            readFromMachine: false,
+        };
+    }
+    if (raw === 'true')
+        return set('defers-all', null);
+    if (raw === 'false')
+        return set('loads-upfront', null);
+    if (raw === 'auto')
+        return set('threshold', TOOL_SEARCH_AUTO_SHARE);
+    const custom = /^auto:(\d{1,3})$/.exec(raw);
+    if (custom) {
+        const pct = Number(custom[1]);
+        if (pct >= 0 && pct <= 100)
+            return set('threshold', pct / 100);
+    }
+    return set('setting-unrecognized', null);
+}
+/**
+ * Read the posture from every place the audited machine can set it.
+ *
+ * Claude Code takes these variables from the shell it was started in AND from
+ * the `env` block of its own settings files, so an audit that reads only the
+ * shell answers the machine's question with someone else's environment. The
+ * case that made this necessary: `~/.claude/settings.json` sets
+ * `ENABLE_TOOL_SEARCH: "false"`, the shell running the audit sets nothing, and
+ * every request on that machine pays for every tool definition while the report
+ * calls it the documented default and says the tokens are not loaded at all.
+ *
+ * Among the settings files the order is Claude Code's documented precedence —
+ * enterprise managed policy, then project-local, then project, then user
+ * (Claude Code settings documentation, §"Settings files", read 2026-08-20) — so
+ * the first of them that sets a variable is the one that would win.
+ *
+ * Between the settings files and the shell there is NO order on record here, so
+ * a disagreement is refused rather than resolved: `setting-unresolved` names the
+ * variable and every place, and no verdict is given. A place that exists and
+ * could not be read is the same refusal for the same reason — what it sets is
+ * unknown, and an unknown that could flip the answer is not a default.
+ *
+ * Not visible from here at all, and so not claimed: a variable set on Claude
+ * Code's own command line.
+ */
+export function resolveToolSearchSources(sources) {
+    const unresolved = (reason, variable) => ({
+        mode: 'setting-unresolved',
+        thresholdShare: null,
+        variable,
+        value: null,
+        source: null,
+        readFromMachine: false,
+        unresolved: reason,
+    });
+    if (sources.some((s) => s.state === 'unreadable'))
+        return unresolved('source-unreadable', null);
+    const settings = sources.filter((s) => s.scope !== 'shell');
+    const shell = sources.find((s) => s.scope === 'shell');
+    /** The value that would win for one variable, or the fact that two places disagree. */
+    const read = (name) => {
+        const winner = settings
+            .map((s) => ({ value: (s.vars[name] ?? '').trim(), source: s.source }))
+            .find((v) => v.value !== '');
+        const shellValue = (shell?.vars[name] ?? '').trim();
+        if (winner && shellValue && winner.value !== shellValue)
+            return 'conflict';
+        if (winner)
+            return winner;
+        if (shellValue && shell)
+            return { value: shellValue, source: shell.source };
+        return null;
+    };
+    // Consulted in the same order `resolveToolSearch` consults them, so a
+    // disagreement over a variable that would not have decided anything —
+    // ANTHROPIC_BASE_URL behind an explicit ENABLE_TOOL_SEARCH — does not refuse
+    // an answer the machine actually gives.
+    const betas = read('CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS');
+    if (betas === 'conflict')
+        return unresolved('sources-disagree', 'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS');
+    if (betas) {
+        return {
+            ...resolveToolSearch({ CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: betas.value }),
+            source: betas.source,
+        };
+    }
+    const enable = read('ENABLE_TOOL_SEARCH');
+    if (enable === 'conflict')
+        return unresolved('sources-disagree', 'ENABLE_TOOL_SEARCH');
+    if (enable) {
+        return { ...resolveToolSearch({ ENABLE_TOOL_SEARCH: enable.value }), source: enable.source };
+    }
+    const base = read('ANTHROPIC_BASE_URL');
+    if (base === 'conflict')
+        return unresolved('sources-disagree', 'ANTHROPIC_BASE_URL');
+    const resolved = resolveToolSearch(base ? { ANTHROPIC_BASE_URL: base.value } : {});
+    return { ...resolved, source: resolved.readFromMachine ? (base?.source ?? null) : null };
+}
+/**
+ * The band as published in this repository's own `results/divergence.json`
+ * (claude-opus-5, 2026-08-19, 20 servers). Used when no divergence run was
+ * supplied; `--claude` recomputes it from the run it fetched.
+ */
+export const PUBLISHED_WIRE_TO_CLIENT_RATIO = {
+    low: 0.2,
+    high: 1.92,
+    servers: 20,
+    source: 'the published claude-opus-5 divergence run',
+};
+/** Derive the band from a supplied divergence run, falling back to the published one. */
+export function wireToClientRatio(run) {
+    if (!run)
+        return PUBLISHED_WIRE_TO_CLIENT_RATIO;
+    let low = Infinity;
+    let high = -Infinity;
+    let servers = 0;
+    for (const row of Object.values(run.servers)) {
+        if (!row || row.error || typeof row.claudeDelta !== 'number' || !(row.o200kFull > 0))
+            continue;
+        const ratio = row.claudeDelta / row.o200kFull;
+        low = Math.min(low, ratio);
+        high = Math.max(high, ratio);
+        servers++;
+    }
+    if (servers === 0)
+        return PUBLISHED_WIRE_TO_CLIENT_RATIO;
+    return { low, high, servers, source: `the ${run.measuredAt} ${run.model} divergence run` };
+}
+/** Clients this tool discovers that have no default deferral on record. */
+const NO_DEFERRAL_ON_RECORD = new Set(['claude-desktop', 'cursor', 'vscode', 'windsurf']);
+/**
+ * Where deferral does not apply even when the machine's setting says it should.
+ * None of these can be read from the config or the environment, so they are
+ * printed as conditions for the reader to check rather than folded into the
+ * verdict.
+ */
+const EXCEPTIONS = [
+    'a Microsoft Foundry deployment hosted on Azure, which rejects tool search server-side',
+    "Google Cloud's Agent Platform on a model earlier than the Claude 4.5 generation",
+    'a model without support for tool_reference blocks (before Sonnet 4.5 / Haiku 4.5 / Opus 4.5)',
+    'a server pinned with "alwaysLoad": true, whose tools load at session start regardless',
+];
+function estimate(servers, ratio) {
+    let low = 0;
+    let high = 0;
+    let exact = 0;
+    let estimated = 0;
+    for (const s of servers) {
+        if (typeof s.claudeTokens === 'number') {
+            // A published Anthropic count for this exact capture. It carries the tool
+            // framework overhead the API charges once per request rather than once
+            // per server, so a multi-server sum leans high by at most that overhead —
+            // far inside the band the converted servers already contribute.
+            low += s.claudeTokens;
+            high += s.claudeTokens;
+            exact++;
+        }
+        else {
+            low += s.tokens * ratio.low;
+            high += s.tokens * ratio.high;
+            estimated++;
+        }
+    }
+    return { low: Math.round(low), high: Math.round(high), exact, estimated };
+}
+/**
+ * Read one session's deferral position. Pure arithmetic over a built scope — no
+ * config file is re-read and no server is launched. The environment is passed
+ * in rather than read here, so the answer is reproducible from its inputs.
+ */
+export function evaluateDeferral(scope, opts) {
+    const wireTokens = scope.servers.reduce((a, s) => a + s.tokens, 0);
+    const isFloor = scope.skippedCount > 0;
+    const sharedMeasurements = scope.sharedMeasurements;
+    // Every field a verdict carries, at its "nothing to say" value. Each mode
+    // below overrides only what it can actually answer.
+    const base = {
+        client: scope.client,
+        sources: scope.sources,
+        wireTokens,
+        isFloor,
+        // Carried by every mode, not just the one that returns early on it below.
+        // That early return withholds `clientTokens` and `crosses`, which only
+        // threshold mode ever computes; the other modes derive nothing from the
+        // total and so have nothing to withhold. What they do all do is PRINT it,
+        // so the caveat belongs in every branch of the report — see
+        // `sharedMeasurementLines` in audit.ts, which every mode calls.
+        sharedMeasurements,
+        mechanism: null,
+        setting: null,
+        thresholdShare: null,
+        thresholdTokens: null,
+        clientTokens: null,
+        ratio: null,
+        distanceTokens: null,
+        crosses: null,
+        exceptions: [],
+    };
+    if (scope.client !== 'claude-code') {
+        return {
+            ...base,
+            mode: NO_DEFERRAL_ON_RECORD.has(scope.client) ? 'no-deferral-on-record' : 'client-unknown',
+        };
+    }
+    // The shell is one place among several, not the machine. Everything Claude
+    // Code would read is resolved together, and a disagreement between them is
+    // refused rather than decided by whichever this happened to open.
+    const sources = [
+        { scope: 'shell', source: SHELL_SOURCE, state: 'read', vars: opts.env ?? {} },
+        ...(opts.settings ?? []),
+    ];
+    const resolved = resolveToolSearchSources(sources);
+    const setting = {
+        variable: resolved.variable,
+        value: resolved.value,
+        source: resolved.source,
+        readFromMachine: resolved.readFromMachine,
+        sources: sources.map(toolSearchSourceRecord),
+        ...(resolved.unresolved ? { unresolved: resolved.unresolved } : {}),
+    };
+    if (resolved.mode !== 'threshold') {
+        return {
+            ...base,
+            mode: resolved.mode,
+            mechanism: 'tool search',
+            setting,
+            // Nothing is deferred in the other two modes, so the conditions under
+            // which deferral fails to apply are not worth printing there.
+            exceptions: resolved.mode === 'defers-all' ? EXCEPTIONS : [],
+        };
+    }
+    const thresholdShare = resolved.thresholdShare ?? TOOL_SEARCH_AUTO_SHARE;
+    const thresholdTokens = Math.round(opts.contextWindow * thresholdShare);
+    if (sharedMeasurements > 0) {
+        // There is a threshold, and no total to hold against it. A shared
+        // measurement is not a floor: a twin can serve more tools than the one that
+        // was launched or fewer, so the sum can be wrong in either direction and
+        // neither side can be ruled out. The same machine has already been seen to
+        // report 13,834 wire tokens or 392 for one stack depending on which twin
+        // the cache happened to hold, and to print a confident — opposite — side
+        // each time. This is the rule `evaluateIncreaseGate` states and `crosses`
+        // already follows: an answer that could not be established fails rather
+        // than resolves. The threshold itself is still reported, because where the
+        // line sits is known even when this stack's distance from it is not.
+        return {
+            ...base,
+            mode: 'threshold',
+            mechanism: 'tool search',
+            setting,
+            thresholdShare,
+            thresholdTokens,
+            exceptions: EXCEPTIONS,
+        };
+    }
+    const ratio = wireToClientRatio(opts.divergence);
+    const clientTokens = estimate(scope.servers, ratio);
+    // At-or-above, on the documented "defers all of them once the definitions
+    // reach 10%". A range that is entirely over is over even if it is a floor:
+    // more unmeasured tokens cannot take it back under.
+    const crosses = clientTokens.low >= thresholdTokens
+        ? true
+        : isFloor || clientTokens.high >= thresholdTokens
+            ? null
+            : false;
+    return {
+        ...base,
+        mode: 'threshold',
+        mechanism: 'tool search',
+        setting,
+        thresholdShare,
+        thresholdTokens,
+        clientTokens,
+        ratio,
+        distanceTokens: { low: clientTokens.low - thresholdTokens, high: clientTokens.high - thresholdTokens },
+        crosses,
+        exceptions: EXCEPTIONS,
+    };
+}

package/dist/audit/diff.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `audit --baseline <report.json>` — what a config change costs every future session.
+ *
+ * `audit` answers "what do my servers cost right now". That is a number a reader
+ * has to have an opinion about. A diff against a stored earlier report answers
+ * the question that needs no opinion at all: *this change adds 17,000 tokens to
+ * every request you will ever send from this client.* Same measurement path,
+ * same per-config discipline — a baseline is just an earlier `audit --json`.
+ *
+ * The trap this file exists to avoid: a server that measured fine before and
+ * fails to start now makes the total go DOWN. Subtracting two totals would
+ * report that as an improvement, which is the flattering reading and the true
+ * one having the same shape. So a server that changed measured-ness is never
+ * given a delta — it is named, its known side is printed, and the direction of
+ * the resulting error is stated ("understates by at least 9,246").
+ */
+import type { AuditConfigResult, AuditReport } from './audit.js';
+export type ServerDeltaKind = 'added' | 'removed' | 'changed' | 'unchanged'
+/** Measured in the baseline, not measurable now — the total understates. */
+ | 'unmeasured-now'
+/** Not measurable in the baseline, measured now — the increase overstates. */
+ | 'unmeasured-before'
+/** Present and unmeasured in both runs — contributes 0 to both totals, but hides cost. */
+ | 'unmeasured-both';
+export interface ServerDelta {
+    name: string;
+    kind: ServerDeltaKind;
+    /** Baseline tokens; `null` when absent from the baseline or unmeasured in it. */
+    before: number | null;
+    /** Current tokens; `null` when gone from the config or unmeasured now. */
+    after: number | null;
+    /** Signed change. `null` whenever the two sides are not the same kind of number. */
+    delta: number | null;
+    /** Why a delta is missing, in a sentence a reader can act on. */
+    note?: string;
+}
+export interface ConfigDiff {
+    client: string;
+    source: string;
+    /** How this config was paired with a baseline config. */
+    matchedBy: 'source' | 'sole-config' | 'unmatched';
+    beforeTotal: number | null;
+    afterTotal: number;
+    /** afterTotal - beforeTotal, or `null` when there is no baseline to subtract. */
+    delta: number | null;
+    beforeShare: number | null;
+    afterShare: number;
+    /**
+     * True when `delta` is the exact change in measured cost. False when a server
+     * crossed the measured/unmeasured line, which moves the total for a reason
+     * that is not a config change.
+     */
+    exact: boolean;
+    /** Tokens the diff is known to be missing, and which way it leans. */
+    understatedBy: number;
+    overstatedBy: number;
+    servers: ServerDelta[];
+}
+export interface AuditDiff {
+    baselineGeneratedAt: string;
+    baselineMethodologyVersion: string;
+    /** False when something makes the two reports incommensurable at all (methodology bump). */
+    comparable: boolean;
+    /** Baseline configs that no current config matched — never silently dropped. */
+    droppedConfigs: {
+        client: string;
+        source: string;
+        totalTokens: number;
+    }[];
+    warnings: string[];
+    configs: ConfigDiff[];
+    /**
+     * The largest per-config increase. Per config, never merged: a context window
+     * belongs to one client session, so a portfolio-wide "total delta" would
+     * describe a session nobody runs. `null` when nothing could be compared.
+     */
+    worstIncrease: {
+        source: string;
+        delta: number;
+    } | null;
+}
+/** Parse and shape-check a stored report. A baseline that cannot be read is never "no change". */
+export declare function parseBaselineReport(text: string): {
+    report: AuditReport | null;
+    problem?: string;
+};
+export declare function diffConfig(before: AuditConfigResult | null, after: AuditConfigResult, matchedBy: ConfigDiff['matchedBy']): ConfigDiff;
+/**
+ * Pair current configs with baseline configs.
+ *
+ * Exact source path first. Then one deliberate fallback: if each side has
+ * exactly one config, they are the same config seen from two machines — the CI
+ * case, where a baseline recorded at /Users/… meets a checkout at /home/runner/….
+ * Anything looser would pair two unrelated clients and call the difference a
+ * change, so everything else stays unmatched and says so.
+ */
+export declare function pairConfigs(before: AuditConfigResult[], after: AuditConfigResult[]): {
+    pairs: {
+        before: AuditConfigResult | null;
+        after: AuditConfigResult;
+        matchedBy: ConfigDiff['matchedBy'];
+    }[];
+    dropped: AuditConfigResult[];
+};
+export declare function buildDiff(baseline: AuditReport, current: AuditReport): AuditDiff;
+export declare function formatDiff(diff: AuditDiff, contextWindow: number): string;
+export interface IncreaseGate {
+    limit: number;
+    pass: boolean;
+    /** The increase the gate measured, when it got far enough to measure one. */
+    increase: number | null;
+    reasons: string[];
+}
+/**
+ * `--max-increase N` — the CI gate. Fails on an increase over the limit, and
+ * equally on any reason the increase could not be established.
+ *
+ * That second half is the point. A gate that passes when a server failed to
+ * start, or when the baseline covered a config this run never found, is a green
+ * check on a question nobody asked. Everything this portfolio has learned says
+ * unchecked must not read as clean, so an inexact diff fails and names why.
+ */
+export declare function evaluateIncreaseGate(diff: AuditDiff, limit: number): IncreaseGate;
+export declare function formatGate(gate: IncreaseGate): string;