mcp-baggage 0.1.0

package/dist/mcp.js

@@ -0,0 +1,288 @@
+/**
+ * A minimal MCP client — enough to ask a server what it carries, and no more.
+ *
+ * The official SDK would do this, and would also pull a dependency tree into a
+ * tool whose whole subject is weight. What is needed here is four messages:
+ * `initialize`, the `initialized` notification, and then the three listings.
+ * No tool is ever called, nothing is written, and the connection is closed as
+ * soon as the listing is in hand.
+ *
+ * Both transports are spoken because both are in people's configs: stdio,
+ * where the server is a process this spawns, and streamable HTTP, where it is
+ * a URL. A server that fails is reported as a failed row rather than taken as
+ * a reason to stop — one broken entry in a config should not cost the run.
+ */
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+/** The version this announces. Servers negotiate down; none of them refuse a listing. */
+const PROTOCOL = '2025-06-18';
+const CLIENT = { name: 'mcp-baggage', version: '0.1.0' };
+/** How long one server gets, all in, before it is written off. */
+export const DEFAULT_TIMEOUT = 20_000;
+const asArray = (v) => (Array.isArray(v) ? v : []);
+/** Tool entries, defensively: a server that sends nonsense loses that entry, not the row. */
+function toTools(raw) {
+    return asArray(raw)
+        .map((t) => (t && typeof t === 'object' ? t : {}))
+        .filter((t) => typeof t['name'] === 'string')
+        .map((t) => ({
+        name: t['name'],
+        description: typeof t['description'] === 'string' ? t['description'] : undefined,
+        inputSchema: t['inputSchema'] ?? t['input_schema'],
+        outputSchema: t['outputSchema'],
+        annotations: t['annotations'],
+    }));
+}
+/**
+ * How to start the process.
+ *
+ * Almost every server in a config is `npx` or `uvx`, which on Windows are
+ * `.cmd` shims that `CreateProcess` will not run — the shell has to. So on
+ * Windows the whole thing becomes one quoted command line handed to `cmd`,
+ * rather than a command plus an argument array: passing both is what Node
+ * deprecated, because the arguments would be concatenated unescaped.
+ */
+export function stdioOptions(spec) {
+    const args = spec.args ?? [];
+    if (process.platform !== 'win32')
+        return { command: spec.command, args, shell: false };
+    const quote = (s) => (s === '' || /[\s"&|<>^()]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
+    return { command: [spec.command, ...args].map(quote).join(' '), args: [], shell: true };
+}
+function openStdio(spec) {
+    const { command, args, shell } = stdioOptions(spec);
+    const child = spawn(command, args, {
+        shell,
+        cwd: spec.cwd ?? process.cwd(),
+        env: { ...process.env, ...spec.env },
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    const pending = new Map();
+    let nextId = 1;
+    let stderr = '';
+    child.stderr.on('data', (chunk) => {
+        // Kept only to explain a failure; a chatty server must not fill memory.
+        stderr = (stderr + chunk.toString()).slice(-2000);
+    });
+    const lines = createInterface({ input: child.stdout });
+    lines.on('line', (line) => {
+        if (!line.trim().startsWith('{'))
+            return; // servers that log to stdout anyway
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof message.id !== 'number')
+            return;
+        const waiter = pending.get(message.id);
+        if (!waiter)
+            return;
+        pending.delete(message.id);
+        if (message.error)
+            waiter.reject(new Error(message.error.message ?? 'server returned an error'));
+        else
+            waiter.resolve(message.result);
+    });
+    const fail = (reason) => {
+        const error = new Error(stderr.trim() ? `${reason}: ${stderr.trim().split('\n').slice(-1)[0]}` : reason);
+        for (const waiter of pending.values())
+            waiter.reject(error);
+        pending.clear();
+    };
+    child.on('error', (e) => fail(e.message));
+    child.on('exit', (code) => fail(`server exited (${code ?? 'signal'})`));
+    const send = (payload) => {
+        child.stdin.write(`${JSON.stringify(payload)}\n`);
+    };
+    return {
+        request: (method, params) => new Promise((resolve, reject) => {
+            const id = nextId++;
+            pending.set(id, { resolve, reject });
+            send({ jsonrpc: '2.0', id, method, params: params ?? {} });
+        }),
+        notify: async (method, params) => {
+            send({ jsonrpc: '2.0', method, params: params ?? {} });
+        },
+        close: () => {
+            lines.close();
+            child.stdin.end();
+            child.kill();
+        },
+    };
+}
+/**
+ * Streamable HTTP.
+ *
+ * The answer to a POST is either a JSON body or an SSE stream carrying the
+ * same object, and the spec allows a server to choose per request, so both are
+ * read. The session id the server hands back on `initialize` has to ride along
+ * on everything after it.
+ */
+function openHttp(spec, signal) {
+    const url = spec.url;
+    let sessionId;
+    let nextId = 1;
+    const post = async (payload) => fetch(url, {
+        method: 'POST',
+        signal,
+        headers: {
+            'content-type': 'application/json',
+            accept: 'application/json, text/event-stream',
+            'mcp-protocol-version': PROTOCOL,
+            ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+            ...spec.headers,
+        },
+        body: JSON.stringify(payload),
+    });
+    /** An SSE body, reduced to the one JSON-RPC object that was asked for. */
+    const fromStream = (text, id) => {
+        for (const line of text.split(/\r?\n/)) {
+            if (!line.startsWith('data:'))
+                continue;
+            try {
+                const message = JSON.parse(line.slice(5).trim());
+                if (message.id === id)
+                    return message;
+            }
+            catch {
+                // A comment or a keep-alive; the next line may still be the answer.
+            }
+        }
+        return undefined;
+    };
+    return {
+        request: async (method, params) => {
+            const id = nextId++;
+            const response = await post({ jsonrpc: '2.0', id, method, params: params ?? {} });
+            const handed = response.headers.get('mcp-session-id');
+            if (handed)
+                sessionId = handed;
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status} ${response.statusText}`.trim());
+            const text = await response.text();
+            const message = response.headers.get('content-type')?.includes('text/event-stream')
+                ? fromStream(text, id)
+                : JSON.parse(text);
+            if (!message)
+                throw new Error('no answer in the stream');
+            if (message.error)
+                throw new Error(message.error.message ?? 'server returned an error');
+            return message.result;
+        },
+        notify: async (method, params) => {
+            await post({ jsonrpc: '2.0', method, params: params ?? {} });
+        },
+        close: () => { },
+    };
+}
+/** Lists that come back a page at a time; a server with 200 tools sends several. */
+async function listAll(session, method, field) {
+    const items = [];
+    let cursor;
+    for (let page = 0; page < 20; page++) {
+        const result = (await session.request(method, cursor ? { cursor } : {}));
+        if (!result)
+            break;
+        items.push(...asArray(result[field]));
+        cursor = typeof result['nextCursor'] === 'string' ? result['nextCursor'] : undefined;
+        if (!cursor)
+            break;
+    }
+    return items;
+}
+/** A listing a server does not support is an empty listing, not a failure. */
+async function listOrNone(session, method, field) {
+    try {
+        return await listAll(session, method, field);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Ask one server what it carries.
+ *
+ * Never throws: a server that cannot be reached comes back as an inventory
+ * with an `error` and no tools, which is a row in the report like any other.
+ */
+export async function inspect(spec, timeout = DEFAULT_TIMEOUT) {
+    const started = Date.now();
+    const empty = { server: spec, tools: [], prompts: [], resources: [] };
+    if (spec.transport === 'stdio' && !spec.command) {
+        return { ...empty, ms: 0, error: 'no command in the config' };
+    }
+    const controller = new AbortController();
+    const session = spec.transport === 'stdio' ? openStdio(spec) : openHttp(spec, controller.signal);
+    const expiry = setTimeout(() => controller.abort(), timeout);
+    const giveUp = new Promise((_, reject) => {
+        controller.signal.addEventListener('abort', () => reject(new Error(`no answer in ${Math.round(timeout / 1000)}s`)));
+    });
+    try {
+        const handshake = (await Promise.race([
+            session.request('initialize', {
+                protocolVersion: PROTOCOL,
+                capabilities: {},
+                clientInfo: CLIENT,
+            }),
+            giveUp,
+        ]));
+        await session.notify('notifications/initialized');
+        const info = (handshake?.['serverInfo'] ?? {});
+        const name = typeof info['name'] === 'string' ? info['name'] : undefined;
+        const version = typeof info['version'] === 'string' ? info['version'] : undefined;
+        const [tools, prompts, resources] = (await Promise.race([
+            Promise.all([
+                listOrNone(session, 'tools/list', 'tools'),
+                listOrNone(session, 'prompts/list', 'prompts'),
+                listOrNone(session, 'resources/list', 'resources'),
+            ]),
+            giveUp,
+        ]));
+        return {
+            server: spec,
+            title: name ? (version ? `${name} ${version}` : name) : undefined,
+            tools: toTools(tools),
+            prompts: prompts,
+            resources: resources,
+            ms: Date.now() - started,
+        };
+    }
+    catch (e) {
+        return { ...empty, ms: Date.now() - started, error: e instanceof Error ? e.message : String(e) };
+    }
+    finally {
+        clearTimeout(expiry);
+        controller.abort();
+        session.close();
+    }
+}
+/**
+ * Every server, a few at a time.
+ *
+ * Each one is a process to spawn, so they are not all started at once; four in
+ * flight keeps a machine with a dozen servers responsive and still finishes in
+ * about the time the slowest handful take.
+ */
+export async function inspectAll(specs, options = {}) {
+    const lanes = Math.max(1, options.lanes ?? 4);
+    const out = new Array(specs.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = next++;
+            const spec = specs[index];
+            if (!spec)
+                return;
+            const inv = await inspect(spec, options.timeout);
+            out[index] = inv;
+            options.onDone?.(inv);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(lanes, specs.length) }, worker));
+    return out;
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/report.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The report, as lines of text.  [PURE]
+ *
+ * One table, then the sentence the table is for. The table is the evidence and
+ * the sentence is the point: a number nobody reads changes nothing, and what
+ * this has to say is short enough to fit in one — *every request carries this
+ * much, and this much of it has never been used*.
+ *
+ * Lines rather than console calls, so the same report can be printed, written
+ * to a file or asserted on in a test.
+ */
+import type { ServerSpec, WeighedServer, WeighedTool } from './types.ts';
+/** The context window a share is measured against, when none is given. */
+export declare const DEFAULT_WINDOW = 200000;
+/** `412`, `12.4k`, `1.2M` — a token count that fits a column. */
+export declare function compact(n: number): string;
+/** A path with the home directory put back as `~`, so a line fits a terminal. */
+export declare function shorten(path: string, home?: string): string;
+/** Where a server came from, in as few words as the reader needs. */
+export declare function origin(spec: ServerSpec): string;
+/**
+ * What is being paid for and not used, split two ways.
+ *
+ * A server where nothing at all has been called is one decision — switch the
+ * server off — and naming its forty tools one by one buries that decision in a
+ * list. A server that is half used is the opposite: the server stays, and the
+ * only thing worth printing is which of its tools are dead weight. So whole
+ * dead servers are reported as servers, and loose tools only from the servers
+ * that survive.
+ */
+export declare function idleness(servers: readonly WeighedServer[]): {
+    servers: WeighedServer[];
+    tools: WeighedTool[];
+    tokens: number;
+};
+/**
+ * The whole report.
+ *
+ * `exact` is carried through to the wording rather than hidden: a figure that
+ * came from a heuristic and one that came from the API's own counter should
+ * not read identically.
+ */
+export declare function report(servers: readonly WeighedServer[], options?: {
+    window?: number;
+    days?: number | null;
+    exact?: boolean;
+    home?: string;
+}): string[];
+/** Every tool of every server, heaviest first — the long form, behind a flag. */
+export declare function breakdown(servers: readonly WeighedServer[]): string[];
+/** The same figures, for a script rather than a person. */
+export declare function asJson(servers: readonly WeighedServer[], window: number, exact: boolean): unknown;

package/dist/report.js

@@ -0,0 +1,166 @@
+/**
+ * The report, as lines of text.  [PURE]
+ *
+ * One table, then the sentence the table is for. The table is the evidence and
+ * the sentence is the point: a number nobody reads changes nothing, and what
+ * this has to say is short enough to fit in one — *every request carries this
+ * much, and this much of it has never been used*.
+ *
+ * Lines rather than console calls, so the same report can be printed, written
+ * to a file or asserted on in a test.
+ */
+import { totalTokens } from "./weigh.js";
+/** The context window a share is measured against, when none is given. */
+export const DEFAULT_WINDOW = 200_000;
+/** How many individual tools to name before the list stops earning its space. */
+const TOOL_LIST = 8;
+/** `412`, `12.4k`, `1.2M` — a token count that fits a column. */
+export function compact(n) {
+    if (n < 1000)
+        return String(Math.round(n));
+    if (n < 100_000)
+        return `${Math.round(n / 100) / 10}k`;
+    if (n < 1_000_000)
+        return `${Math.round(n / 1000)}k`;
+    return `${Math.round(n / 100_000) / 10}M`;
+}
+const share = (n, window) => `${((n / window) * 100).toFixed(1)}%`;
+/** A path with the home directory put back as `~`, so a line fits a terminal. */
+export function shorten(path, home) {
+    if (!home)
+        return path;
+    const same = (a) => a.replace(/\\/g, '/').toLowerCase();
+    return same(path).startsWith(same(home)) ? `~${path.slice(home.length)}` : path;
+}
+/** Where a server came from, in as few words as the reader needs. */
+export function origin(spec) {
+    const clients = spec.carriedBy.join(', ');
+    return spec.scope === 'project' ? `${clients} (project)` : clients;
+}
+const NAME_WIDTH = 20;
+function row(s, window) {
+    const name = s.server.name.padEnd(NAME_WIDTH).slice(0, NAME_WIDTH);
+    if (s.error)
+        return `  ${name} ${'—'.padStart(5)} ${'—'.padStart(8)} ${'—'.padStart(7)} ${'—'.padStart(7)}  ${s.error}`;
+    const used = s.tools.filter((t) => (t.calls ?? 0) > 0).length;
+    const known = s.tools.some((t) => t.calls !== null);
+    const usage = known ? `${used}/${s.tools.length}` : '—';
+    const idle = known && used === 0 && s.tools.length > 0 ? '  never called' : '';
+    const off = s.server.enabled ? '' : '  (switched off)';
+    return (`  ${name}` +
+        ` ${String(s.tools.length).padStart(5)}` +
+        ` ${compact(s.tokens).padStart(8)}` +
+        ` ${share(s.tokens, window).padStart(7)}` +
+        ` ${usage.padStart(7)}` +
+        idle +
+        off);
+}
+const HEAD = `  ${'server'.padEnd(NAME_WIDTH)} ${'tools'.padStart(5)} ${'tokens'.padStart(8)} ${'of ctx'.padStart(7)} ${'used'.padStart(7)}`;
+/**
+ * What is being paid for and not used, split two ways.
+ *
+ * A server where nothing at all has been called is one decision — switch the
+ * server off — and naming its forty tools one by one buries that decision in a
+ * list. A server that is half used is the opposite: the server stays, and the
+ * only thing worth printing is which of its tools are dead weight. So whole
+ * dead servers are reported as servers, and loose tools only from the servers
+ * that survive.
+ */
+export function idleness(servers) {
+    const dead = servers.filter((s) => !s.error && s.tools.length > 0 && s.tools.every((t) => t.calls === 0));
+    const deadNames = new Set(dead.map((s) => s.server.name));
+    const tools = servers
+        .filter((s) => !s.error && !deadNames.has(s.server.name))
+        .flatMap((s) => s.tools)
+        .filter((t) => t.calls === 0)
+        .sort((a, b) => b.tokens - a.tokens);
+    return {
+        servers: dead,
+        tools,
+        tokens: totalTokens(dead) + tools.reduce((n, t) => n + t.tokens, 0),
+    };
+}
+/**
+ * The whole report.
+ *
+ * `exact` is carried through to the wording rather than hidden: a figure that
+ * came from a heuristic and one that came from the API's own counter should
+ * not read identically.
+ */
+export function report(servers, options = {}) {
+    if (servers.length === 0)
+        return ['no MCP servers found in any config on this machine'];
+    const window = options.window ?? DEFAULT_WINDOW;
+    const live = servers.filter((s) => !s.error);
+    const total = totalTokens(live);
+    const toolCount = live.reduce((n, s) => n + s.tools.length, 0);
+    const lines = [HEAD, ''];
+    for (const s of servers)
+        lines.push(row(s, window));
+    lines.push('', `  ${'total'.padEnd(NAME_WIDTH)} ${String(toolCount).padStart(5)} ${compact(total).padStart(8)} ${share(total, window).padStart(7)}`, '', `every request carries ${compact(total)} tokens of tool definitions — ${share(total, window)} of a ${compact(window)} window,`, `before a line of your own code is read. (${options.exact ? 'counted by the API' : 'estimated — --exact counts'})`);
+    if (options.days) {
+        const idle = idleness(servers);
+        if (idle.tokens > 0) {
+            const portion = total > 0 ? Math.round((idle.tokens / total) * 100) : 100;
+            lines.push('', `${compact(idle.tokens)} of it — ${portion}% — has not been called in ${options.days} days.`);
+        }
+        if (idle.servers.length > 0) {
+            lines.push('', 'nothing at all has been called from:', '');
+            for (const s of idle.servers) {
+                lines.push(`  ${s.server.name.padEnd(NAME_WIDTH)} ${compact(s.tokens).padStart(8)}  ${shorten(s.server.source, options.home)}`);
+            }
+        }
+        if (idle.tools.length > 0) {
+            lines.push('', 'and these tools, in servers you do use:', '');
+            for (const t of idle.tools.slice(0, TOOL_LIST)) {
+                lines.push(`  ${t.qualified.padEnd(44).slice(0, 44)} ${compact(t.tokens).padStart(7)}`);
+            }
+            if (idle.tools.length > TOOL_LIST)
+                lines.push(`  … and ${idle.tools.length - TOOL_LIST} more`);
+        }
+    }
+    const failed = servers.filter((s) => s.error);
+    if (failed.length > 0) {
+        const s = failed.length === 1;
+        lines.push('', `${failed.length} server${s ? '' : 's'} could not be reached and ${s ? 'is' : 'are'} not in the total.`);
+    }
+    return lines;
+}
+/** Every tool of every server, heaviest first — the long form, behind a flag. */
+export function breakdown(servers) {
+    const lines = [];
+    for (const s of servers) {
+        if (s.error)
+            continue;
+        lines.push('', `${s.server.name}${s.title ? `  (${s.title})` : ''}  ·  ${compact(s.tokens)}  ·  ${origin(s.server)}`);
+        for (const t of s.tools) {
+            const calls = t.calls === null ? '' : t.calls === 0 ? '   never called' : `   ${t.calls} call${t.calls === 1 ? '' : 's'}`;
+            lines.push(`  ${t.name.padEnd(40).slice(0, 40)} ${compact(t.tokens).padStart(7)}${calls}`);
+        }
+    }
+    return lines;
+}
+/** The same figures, for a script rather than a person. */
+export function asJson(servers, window, exact) {
+    return {
+        window,
+        exact,
+        total: totalTokens(servers.filter((s) => !s.error)),
+        servers: servers.map((s) => ({
+            name: s.server.name,
+            client: s.server.client,
+            carriedBy: s.server.carriedBy,
+            source: s.server.source,
+            transport: s.server.transport,
+            enabled: s.server.enabled,
+            title: s.title,
+            tokens: s.tokens,
+            tools: s.tools,
+            prompts: s.prompts,
+            resources: s.resources,
+            ms: s.ms,
+            error: s.error,
+        })),
+    };
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"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"}

package/dist/tokens.d.ts

@@ -0,0 +1,31 @@
+/**
+ * How many tokens a piece of text is worth.  [PURE]
+ *
+ * There is no public tokenizer for Claude, so this is an estimate and says so
+ * everywhere it is shown. It is not `length / 4`: tool definitions are JSON,
+ * and JSON is mostly punctuation, indentation and short identifiers, which
+ * that ratio gets wrong in both directions at once — it under-counts braces
+ * and over-counts indentation.
+ *
+ * Instead the text is cut into runs of one kind of character and each run is
+ * priced the way a byte-pair tokenizer is known to treat it: words in pieces
+ * of about five characters, digits in threes, adjacent punctuation paired up,
+ * a leading space absorbed into the word after it.
+ *
+ * That is a model of a tokenizer, not the tokenizer, and it has not been
+ * calibrated against the real one — so it is called an estimate everywhere it
+ * is shown, and it is good for the question it is for: which of these servers
+ * is the big one. When the figure itself has to be right, `--exact` asks the
+ * API (see `exact.ts`) and nothing in this file is used.
+ */
+/** The estimate, for any text. */
+export declare function estimate(text: string): number;
+/**
+ * What a client adds around each tool definition it sends.
+ *
+ * The name and schema are counted from the text itself; this is the framing
+ * that does not appear in the JSON — the wrapper the API puts each tool in.
+ * It is small and flat, and it is here as a named constant rather than buried
+ * in an expression so that it can be argued with.
+ */
+export declare const TOOL_FRAMING = 8;

package/dist/tokens.js

@@ -0,0 +1,67 @@
+/**
+ * How many tokens a piece of text is worth.  [PURE]
+ *
+ * There is no public tokenizer for Claude, so this is an estimate and says so
+ * everywhere it is shown. It is not `length / 4`: tool definitions are JSON,
+ * and JSON is mostly punctuation, indentation and short identifiers, which
+ * that ratio gets wrong in both directions at once — it under-counts braces
+ * and over-counts indentation.
+ *
+ * Instead the text is cut into runs of one kind of character and each run is
+ * priced the way a byte-pair tokenizer is known to treat it: words in pieces
+ * of about five characters, digits in threes, adjacent punctuation paired up,
+ * a leading space absorbed into the word after it.
+ *
+ * That is a model of a tokenizer, not the tokenizer, and it has not been
+ * calibrated against the real one — so it is called an estimate everywhere it
+ * is shown, and it is good for the question it is for: which of these servers
+ * is the big one. When the figure itself has to be right, `--exact` asks the
+ * API (see `exact.ts`) and nothing in this file is used.
+ */
+/** Letters, digits, whitespace, everything else — each in runs. */
+const RUNS = /[A-Za-z]+|[0-9]+|\s+|[^\sA-Za-z0-9]+/g;
+/**
+ * One run's worth of tokens.
+ *
+ * - Letters: common words and identifiers come out around five characters a
+ *   token once `camelCase` boundaries and word-piece splits are averaged in.
+ * - Digits: tokenizers group them in threes.
+ * - Whitespace: a lone space is absorbed into the word that follows it and is
+ *   free; a newline is its own token, and the indentation after it packs into
+ *   roughly four characters a token.
+ * - Punctuation: adjacent marks pair up — `{"`, `":`, `",` are each one token —
+ *   so a run costs about half its length, never less than one.
+ */
+function runTokens(run) {
+    const first = run[0];
+    if (/\s/.test(first)) {
+        const newlines = (run.match(/\n/g) ?? []).length;
+        if (newlines === 0)
+            return run.length === 1 ? 0 : Math.ceil(run.length / 4);
+        return newlines + Math.ceil((run.length - newlines) / 4);
+    }
+    if (first >= '0' && first <= '9')
+        return Math.ceil(run.length / 3);
+    if (/[A-Za-z]/.test(first))
+        return Math.max(1, Math.round(run.length / 5));
+    return Math.max(1, Math.ceil(run.length / 2));
+}
+/** The estimate, for any text. */
+export function estimate(text) {
+    if (!text)
+        return 0;
+    let total = 0;
+    for (const run of text.match(RUNS) ?? [])
+        total += runTokens(run);
+    return total;
+}
+/**
+ * What a client adds around each tool definition it sends.
+ *
+ * The name and schema are counted from the text itself; this is the framing
+ * that does not appear in the JSON — the wrapper the API puts each tool in.
+ * It is small and flat, and it is here as a named constant rather than buried
+ * in an expression so that it can be argued with.
+ */
+export const TOOL_FRAMING = 8;
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mEAAmE;AACnE,MAAM,IAAI,GAAG,uCAAuC,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,SAAS,SAAS,CAAC,GAAW;IAC5B,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,CAAW,CAAC;IAE/B,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACjD,IAAI,QAAQ,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC5E,OAAO,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACnE,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3E,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC;IAClE,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC"}

package/dist/toml.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Just enough TOML to read Codex's config.  [PURE]
+ *
+ * Codex keeps its servers in `~/.codex/config.toml`, and a dependency would be
+ * a poor trade for the handful of shapes that file actually uses: table
+ * headers, strings, integers, booleans, string arrays and inline tables. What
+ * this cannot parse it skips rather than guesses at, and an unreadable file
+ * costs one client, not the run.
+ */
+/** The whole file, as nested plain objects. Arrays of tables are not supported. */
+export declare function parseToml(text: string): Record<string, unknown>;