@trazum/mcp 1.9.0 → 1.25.0

package/dist/tools.js

@@ -1,4 +1,4 @@
-import { BUNDLED_CATALOGUE, PRICING_LAST_REVIEWED, formatUsd, listModels, optimize, } from '@trazum/core';
+import { BUNDLED_CATALOGUE, PRICING_LAST_REVIEWED, UNLABELLED, billLevers, cacheEconomics, cacheHitRate, driversBetween, formatUsd, reviewAgeDays, listModels, optimize, profileUsage, repriceProfile, } from '@trazum/core';
 import { InvalidArguments } from './rpc.js';
 /**
  * The tools, kept in one file so the whole surface an agent can reach reads in one
@@ -29,7 +29,7 @@ import { InvalidArguments } from './rpc.js';
  */
 export const MAX_PROMPT_CHARS = 400_000;
 /** Every figure this server prints descends from the estimator, so it says so. */
-const BAND_NOTE = 'token counts are estimates (±15% on prose, calibrated on Claude); prices reviewed '
+const BAND_NOTE = 'token counts are estimates (±10% on prose, calibrated on Claude); prices reviewed '
     + PRICING_LAST_REVIEWED;
 function promptFrom(args) {
     const prompt = args.prompt;
@@ -182,7 +182,7 @@ const CHECK = {
                     + ` is ${result.tokensAfter}: content has to be cut.`;
         return [
             verdict,
-            'token counts are estimates (±15% on prose, calibrated on Claude), so a prompt within'
+            'token counts are estimates (±10% on prose, calibrated on Claude), so a prompt within'
                 + ' a few percent of its budget should be treated as uncertain',
         ].join('\n');
     },
@@ -208,6 +208,618 @@ const MODELS = {
         ].join('\n');
     },
 };
+/**
+ * Larger than the prompt cap because a usage log is a different object: a month
+ * of calls at one JSON line each. Two million characters is a few MB of log —
+ * far beyond what an agent realistically holds in context, so the cap exists to
+ * refuse the accident, not to invite the maximum.
+ */
+export const MAX_LOG_CHARS = 2_000_000;
+/** `<1%` for a real but sub-half-percent share, never a rounded-to-zero "0%". */
+const pct = (fraction) => fraction > 0 && fraction < 0.005 ? '<1%' : `${(fraction * 100).toFixed(0)}%`;
+const count = (n, word) => `${n.toLocaleString('en-US')} ${n === 1 ? word : `${word}s`}`;
+const PROFILE = {
+    name: 'profile_usage',
+    title: 'Where the money went, from a usage log',
+    description: 'Reads a usage log — one JSON object per line, each with a "model" and the "usage" object '
+        + 'the API returned — and says where the money went: the spend split, per label and per '
+        + 'model, whether caching paid for itself, and which levers would actually move the bill. '
+        + 'These are the provider\'s own billed token counts, not estimates. Pass the log text '
+        + 'itself: this server never reads files. Add "label", "session" and "ts" fields to the '
+        + 'records to unlock the per-workload findings, conversation growth, the period the log '
+        + 'covers, and whether the cache TTL fits how fast the turns arrive; the session key is '
+        + 'grouped by and never shown.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            log: {
+                type: 'string',
+                minLength: 1,
+                maxLength: MAX_LOG_CHARS,
+                description: 'The usage log text, one JSON object per line. Never a file path.',
+            },
+            label: {
+                type: 'string',
+                minLength: 1,
+                description: 'Profile only the calls carrying this label — the drill-down once the full report '
+                    + 'named a suspect. A label matching nothing is an error naming the labels that exist.',
+            },
+            since: {
+                type: 'string',
+                minLength: 1,
+                description: 'Profile only calls at or after this moment: a UTC day (2026-08-14) or a full ISO '
+                    + '8601 timestamp. Calls with no "ts" cannot be placed and are excluded, counted out '
+                    + 'loud — never dropped silently.',
+            },
+            until: {
+                type: 'string',
+                minLength: 1,
+                description: 'Profile only calls up to this moment; a bare date includes that whole UTC day. '
+                    + 'A window matching nothing is an error naming what the log does cover.',
+            },
+            previous_log: {
+                type: 'string',
+                minLength: 1,
+                maxLength: MAX_LOG_CHARS,
+                description: 'A previous usage log to compare against, as text — never a file path. Positive '
+                    + 'means the bill grew. Drivers of the change are named per label and per model, '
+                    + 'appeared and vanished workloads included; label/since/until filter both logs, '
+                    + 'so the comparison stays one workload and one period.',
+            },
+            what_if: {
+                type: 'string',
+                minLength: 1,
+                description: 'Price these exact calls on another model id. The same token counts at a different '
+                    + 'rate card — multiplication, not advice: it says nothing about whether that model '
+                    + 'could do the work. Calls larger than that model\'s context window are named as '
+                    + 'impossible rather than priced as cheap, and spend already on that model stays out '
+                    + 'of the difference. An id this catalogue cannot price is an error, never silence.',
+            },
+        },
+        required: ['log'],
+        additionalProperties: false,
+    },
+    run: (args) => {
+        const log = args.log;
+        if (typeof log !== 'string')
+            throw new InvalidArguments('log must be a string');
+        if (log.length === 0)
+            throw new InvalidArguments('log is empty');
+        if (log.length > MAX_LOG_CHARS) {
+            throw new InvalidArguments(`log is ${log.length} characters, over the ${MAX_LOG_CHARS} limit`);
+        }
+        const onlyLabel = args.label;
+        if (onlyLabel !== undefined && typeof onlyLabel !== 'string') {
+            throw new InvalidArguments('label must be a string');
+        }
+        /**
+         * The window, under the CLI's rules: a bare day is that whole UTC day —
+         * since its first instant, until its last — and the window is half-open
+         * `[since, until)` internally, so adjacent windows share no record.
+         */
+        const parseWhen = (key) => {
+            const value = args[key];
+            if (value === undefined)
+                return undefined;
+            if (typeof value !== 'string')
+                throw new InvalidArguments(`${key} must be a string`);
+            if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+                const midnight = Date.parse(`${value}T00:00:00Z`);
+                if (Number.isFinite(midnight))
+                    return key === 'until' ? midnight + 86_400_000 : midnight;
+            }
+            const exact = Date.parse(value);
+            if (Number.isFinite(exact))
+                return exact;
+            throw new InvalidArguments(`${key} could not be read: "${value}". Pass a UTC day (2026-08-14) or a full ISO 8601 timestamp.`);
+        };
+        const sinceMs = parseWhen('since');
+        const untilMs = parseWhen('until');
+        if (sinceMs !== undefined && untilMs !== undefined && sinceMs >= untilMs) {
+            throw new InvalidArguments('since is at or after until, so the window contains no time at all');
+        }
+        const windowed = sinceMs !== undefined || untilMs !== undefined;
+        const report = profileUsage(log, { catalogue: BUNDLED_CATALOGUE, label: onlyLabel, sinceMs, untilMs });
+        /**
+         * The drill-downs' one rule, same as the CLI: a filter matching nothing is
+         * an error naming what exists, never a silent report over zero calls that
+         * an agent would read as "this workload is free" or "this period is free".
+         */
+        if ((onlyLabel !== undefined || windowed) && report.total.calls === 0 && report.unpriced.calls === 0) {
+            const unfiltered = profileUsage(log, { catalogue: BUNDLED_CATALOGUE });
+            if (unfiltered.total.calls > 0 || unfiltered.unpriced.calls > 0) {
+                if (onlyLabel !== undefined && !unfiltered.byLabel.some((e) => e.label === onlyLabel)) {
+                    const available = unfiltered.byLabel
+                        .map((e) => (e.label === UNLABELLED ? '(no label)' : e.label))
+                        .join(', ');
+                    throw new InvalidArguments(`no call in this log carries the label "${onlyLabel}". The labels here are: ${available || '—'}`);
+                }
+                if (windowed) {
+                    if (unfiltered.span === null) {
+                        throw new InvalidArguments('no record in this log carries a timestamp, so since/until have nothing to filter by. '
+                            + 'Add "ts" to the records.');
+                    }
+                    const day = (ms) => new Date(ms).toISOString().slice(0, 10);
+                    throw new InvalidArguments(`no record falls inside this window. The log covers ${day(unfiltered.span.fromMs)} → ${day(unfiltered.span.toMs)}.`);
+                }
+            }
+        }
+        const { total } = report;
+        const lines = [];
+        const gaps = () => {
+            if (report.unpricedModels.length > 0) {
+                lines.push(`${count(report.unpriced.calls, 'call')} are not in these totals — the pricing `
+                    + `catalogue does not know: ${report.unpricedModels.join(', ')}. The CLI can price `
+                    + 'them with a pricing overlay (trazum profile --pricing).');
+            }
+            if (report.skippedLines.length > 0) {
+                const shown = report.skippedLines.slice(0, 10).join(', ');
+                const more = report.skippedLines.length > 10 ? ', …' : '';
+                lines.push(`${count(report.skippedLines.length, 'line')} could not be read and`
+                    + ` ${report.skippedLines.length === 1 ? 'was' : 'were'} left out`
+                    + ` (line${report.skippedLines.length === 1 ? '' : 's'} ${shown}${more}).`);
+            }
+        };
+        if (total.calls === 0) {
+            lines.push(report.unpriced.calls > 0
+                ? 'None of the models in that log are in the pricing catalogue, so there is no bill '
+                    + 'to report.'
+                : 'No usage records in that log.');
+            gaps();
+            return lines.join('\n');
+        }
+        // The one Trazum surface whose figures are NOT estimates, said out loud
+        // because every sibling tool here carries the ±10% band.
+        lines.push(`${count(total.calls, 'call')} · ${formatUsd(total.totalUsd)} — exact billed token`
+            + ` counts from the log, not estimates; prices reviewed ${PRICING_LAST_REVIEWED}.`);
+        /**
+         * Said only when old enough to matter, and loud then: a stale table
+         * qualifies every dollar above, and unlike a skipped line it does not
+         * name its own size — the error is exactly whatever the provider changed.
+         */
+        const pricingAge = reviewAgeDays(PRICING_LAST_REVIEWED, new Date());
+        if (pricingAge !== null && pricingAge > 45) {
+            lines.push(`That review was ${pricingAge} days ago, past the 45 this tool considers current. If the`
+                + ' provider changed prices since, every figure here is off by exactly that change —'
+                + ' the CLI can fetch current prices (trazum profile --pricing-live).');
+        }
+        if (report.span !== null) {
+            const day = (ms) => new Date(ms).toISOString().slice(0, 10);
+            const days = ((report.span.toMs - report.span.fromMs) / 86_400_000).toFixed(1);
+            const parsed = total.calls + report.unpriced.calls;
+            const partial = report.span.calls < parsed
+                ? ` Only ${count(report.span.calls, 'call')} of ${parsed} carry a timestamp; the span describes those.`
+                : '';
+            lines.push(`This log covers ${day(report.span.fromMs)} → ${day(report.span.toMs)} (${days} days).`
+                + ' The span is stated, never extrapolated — the monthly arithmetic is yours to do.'
+                + partial);
+        }
+        else {
+            lines.push('Figures are "on this bill" — the log carries no timestamps, so no period is known'
+                + ' and nothing here is per-month. Add "ts" to the record and the span is stated.');
+        }
+        // The window before any figure is trusted as "the log", with the undated
+        // count said out loud: those calls' spend is in the log and not here.
+        if (report.timeWindow !== null) {
+            lines.push('Everything below describes the since/until window, not the whole log.');
+            if (report.timeWindow.undatedExcluded > 0) {
+                lines.push(`${count(report.timeWindow.undatedExcluded, 'call')} carry no timestamp and cannot be`
+                    + ' placed inside or outside the window, so they were left out. The window\'s figures'
+                    + ' are a floor on the period.');
+            }
+        }
+        lines.push(`input ${formatUsd(total.inputUsd)} · cache reads ${formatUsd(total.cacheReadUsd)}`
+            + ` · cache writes ${formatUsd(total.cacheWriteUsd)}`
+            + ` · output ${formatUsd(total.outputUsd)} (${pct(total.outputUsd / total.totalUsd)})`);
+        const name = (label) => (label === UNLABELLED ? '(no label)' : label);
+        const table = (heading, rows) => {
+            lines.push('', `--- ${heading} ---`);
+            for (const row of rows.slice(0, 10)) {
+                lines.push(`${formatUsd(row.usd).padStart(11)}  ${pct(row.usd / total.totalUsd).padStart(4)}`
+                    + `  ${row.key}  (${count(row.calls, 'call')})`);
+            }
+            if (rows.length > 10)
+                lines.push(`…and ${rows.length - 10} more.`);
+        };
+        table('by label', report.byLabel.map((e) => ({
+            key: name(e.label), usd: e.breakdown.totalUsd, calls: e.breakdown.calls,
+        })));
+        table('by model', report.byModel.map((e) => ({
+            key: e.model, usd: e.breakdown.totalUsd, calls: e.breakdown.calls,
+        })));
+        lines.push('', '--- did caching pay for itself? ---');
+        const cache = cacheEconomics(total);
+        /**
+         * The verdict is unsettled when the TTL assumption alone flips it: neither
+         * end may be stated as the answer, and the flattering half least of all.
+         * Same gate as the CLI and the web viewer.
+         */
+        const unsettled = cache.worstCaseVerdict !== cache.verdict && total.assumedWriteTtlCalls > 0;
+        if (unsettled) {
+            lines.push(`This log cannot say whether caching paid for itself. ${count(total.assumedWriteTtlCalls, 'call')}`
+                + ' did not record which cache-write TTL was used: at the 5-minute rate caching took'
+                + ` ${formatUsd(Math.abs(cache.deltaUsd))} off this bill, and at the 1-hour rate the`
+                + ` same calls added ${formatUsd(Math.abs(cache.worstCaseDeltaUsd))} to it. Neither is`
+                + ' the answer. Record the "cache_creation" object the API returns and this settles itself.');
+        }
+        else if (cache.verdict === 'not-attempted') {
+            lines.push('Caching was never used on these calls. If any prefix repeats, that is the largest '
+                + 'saving available.');
+        }
+        else if (cache.verdict === 'unpriced') {
+            lines.push('Cache tokens exist on models the catalogue cannot price; no comparison to make.');
+        }
+        else if (cache.verdict === 'lost-money') {
+            lines.push(`Caching added ${formatUsd(cache.deltaUsd)} to this bill instead of taking it off — a`
+                + ' write costs 1.25x plain input (2x at the 1-hour TTL), so a prefix that changes'
+                + ' faster than it is reused pays that premium for nothing.');
+        }
+        else if (cache.verdict === 'paid-off') {
+            lines.push(`Caching took ${formatUsd(Math.abs(cache.deltaUsd))} off this bill, against the same`
+                + ' tokens uncached.');
+        }
+        else {
+            lines.push('Caching came out level: it charged what the same tokens cost as plain input.');
+        }
+        if (!unsettled && total.assumedWriteTtlCalls > 0) {
+            lines.push(`That figure is a bound, not a measurement: ${count(total.assumedWriteTtlCalls, 'call')}`
+                + ' did not record a cache-write TTL.');
+        }
+        const losing = report.byLabel.filter((e) => cacheEconomics(e.breakdown).verdict === 'lost-money');
+        if (cache.verdict !== 'lost-money' && losing.length > 0) {
+            lines.push(`The total hides a loss: caching loses money on ${losing.map((e) => name(e.label)).join(', ')}.`);
+        }
+        const hit = cacheHitRate(total);
+        if (hit !== null)
+            lines.push(`Cache hit rate ${pct(hit)} of billable input.`);
+        /**
+         * Whether the TTL fits how fast the turns arrive — the mechanism behind the
+         * verdict above. Four verdicts plus "could not be measured": the same
+         * three-state discipline as truncation, because for an agent acting on this
+         * report "no data" and "fits" are different instructions.
+         */
+        const gapOf = (ms) => {
+            if (ms < 90_000)
+                return `${Math.round(ms / 1000)}s`;
+            if (ms < 90 * 60_000)
+                return `${Math.round(ms / 60_000)}m`;
+            return `${(ms / 3_600_000).toFixed(1)}h`;
+        };
+        for (const fit of report.cacheTtlFit.slice(0, 3)) {
+            const who = `${name(fit.label)} on ${fit.modelName}`;
+            const gap = gapOf(fit.medianGapMs);
+            if (fit.verdict === 'expires-before-reuse') {
+                lines.push(`${who}: turns arrive a median of ${gap} apart and the cache entry is gone by then —`
+                    + ' writes expire before the next turn reads them. Use the 1-hour TTL if it survives'
+                    + ' these gaps, or turn caching off here.');
+            }
+            else if (fit.verdict === 'overlong-ttl') {
+                lines.push(`${who}: turns arrive a median of ${gap} apart — inside the 5-minute window — and these`
+                    + ` writes pay the 1-hour rate (2x input) for endurance they never use. The same writes`
+                    + ` at the 5-minute TTL are ${formatUsd(fit.overpayUsd)} cheaper on this log, exactly.`);
+            }
+            else if (fit.verdict === 'unsettled') {
+                lines.push(`${who}: median gap ${gap} — a 5-minute entry is gone by then, a 1-hour one survives,`
+                    + ' and the log did not record which these writes were. Record the "cache_creation"'
+                    + ' object and this settles itself.');
+            }
+            else {
+                lines.push(`${who}: median gap ${gap}, inside the lifetime these writes use. The TTL fits.`);
+            }
+        }
+        if (total.cacheWriteTokens > 0 && report.cacheTtlFit.length === 0) {
+            lines.push('Whether the cache TTL fits how fast the turns arrive could not be measured — it needs'
+                + ' both "session" and "ts" on the record.');
+        }
+        /**
+         * Conversations that never came back. The same two-claim split as the CLI:
+         * a fact when the slice recorded zero cache reads (nothing read those
+         * writes at all), a ceiling named as one otherwise — the provider's cache
+         * is keyed by prefix, and the log cannot see whose write a read hit.
+         */
+        const readsBySlice = new Map(report.byLabelAndModel.map((e) => [`${e.label}\n${e.model}`, e.breakdown.cacheReadTokens]));
+        for (const row of report.singleTurnCacheWrites.slice(0, 3)) {
+            const who = `${name(row.label)} on ${row.modelName}`;
+            const opening = `${who}: ${count(row.singleTurnSessions, 'conversation')} of ${row.sessions} ended after`
+                + ` the first turn and spent ${formatUsd(row.singleTurnWriteUsd)} on cache writes their`
+                + ' own conversation never read back.';
+            if ((readsBySlice.get(`${row.label}\n${row.model}`) ?? 0) === 0) {
+                lines.push(`${opening} Nothing in this log ever read this slice's cache at all, so those writes`
+                    + ' bought nothing — stop marking one-shot calls with cache_control.');
+            }
+            else {
+                lines.push(`${opening} Another conversation sharing the same prefix within the TTL could have read`
+                    + ' them; the log cannot see whose write a read hit, so that figure is a ceiling on'
+                    + ' the waste, not a bill.');
+            }
+        }
+        lines.push('', '--- what would actually move this bill ---');
+        const levers = billLevers(report, { catalogue: BUNDLED_CATALOGUE });
+        if (report.byLabel.length === 1 && report.byLabel[0].label === UNLABELLED) {
+            lines.push('None of these calls carried a label, so this is every workload in one row. Add "label" '
+                + 'to the record and the levers split by workload, the grouping a decision is made at.');
+        }
+        if (levers.slices.length === 0) {
+            lines.push('Nothing here clears 1% of the bill: these calls are already on the cheapest model of '
+                + 'their family, or their provider has no batch API. A real answer, not an empty section.');
+        }
+        for (const slice of levers.slices.slice(0, 5)) {
+            lines.push(`${name(slice.label)} on ${slice.modelName} — up to ${formatUsd(slice.combinedUsd)}`
+                + ` (${pct(slice.shareOfBill)}); ${count(slice.calls, 'call')}, ${formatUsd(slice.spentUsd)} spent`);
+            if (slice.route !== null) {
+                lines.push(`  route to ${slice.route.candidate.displayName}: ${formatUsd(slice.route.savingUsd)}`
+                    + ' — an evaluation question, not arithmetic; the CLI measures it: trazum route');
+            }
+            if (slice.batch !== null) {
+                lines.push(`  batch API: ${formatUsd(slice.batch.savingUsd)}`);
+            }
+        }
+        lines.push(`For comparison, shortening prompt text can touch ${formatUsd(levers.promptCeilingUsd)}`
+            + ` at the very most (${pct(levers.promptCeilingShare)}) — a ceiling, and the real figure`
+            + ' is far below it: most input tokens are context, history and tool results no prompt'
+            + ' file contains.');
+        lines.push('', '--- conversations ---');
+        if (!report.hasSessions) {
+            lines.push('No call carried a session, so re-sending-the-conversation costs could not be measured '
+                + '— usually the largest line on a chat or agent bill. Add "session" to the record; '
+                + 'it is grouped by and never shown.');
+        }
+        for (const growth of report.conversations.slice(0, 3)) {
+            lines.push(`${name(growth.label)} on ${growth.modelName}: at most ${formatUsd(growth.growthUsd)}`
+                + ` of this bill is conversation growth (${pct(growth.shareOfBill)}) — a ceiling, not a`
+                + " saving; part is the user's own new messages. Input runs"
+                + ` ${Math.round(growth.minTurnTokens).toLocaleString('en-US')} to`
+                + ` ${Math.round(growth.maxTurnTokens).toLocaleString('en-US')} tokens per turn over`
+                + ` conversations up to ${growth.longestSession} turns.`);
+        }
+        /**
+         * What one conversation costs — median against p95, the figure a per-seat
+         * price or a quota is set from. A mean is refused for the reason it is
+         * refused everywhere: one runaway loop hides the ordinary case.
+         */
+        for (const shape of report.sessionCosts.slice(0, 3)) {
+            lines.push(`${name(shape.label)} on ${shape.modelName}: across ${shape.sessions} conversations the`
+                + ` median costs ${formatUsd(shape.medianUsd)} over ${shape.medianTurns} turns, 95% come`
+                + ` in under ${formatUsd(shape.p95Usd)}, the dearest was ${formatUsd(shape.maxUsd)}.`
+                + ' Exact billed counts per conversation; one that started before this log or continues'
+                + ' after it counts only for the turns recorded here.');
+            if (shape.medianUsd > 0 && shape.p95Usd > 10 * shape.medianUsd) {
+                lines.push(`That p95 is ${(shape.p95Usd / shape.medianUsd).toFixed(0)}x the median — a tail a quota`
+                    + ' can catch, rather than a workload that is uniformly expensive.');
+            }
+        }
+        lines.push('', '--- truncation ---');
+        if (total.stopReasonCalls === 0) {
+            lines.push('Whether any answers were cut off could not be measured — no call carries a stop '
+                + 'reason. Add "stop_reason" (Anthropic) or "finish_reason" (OpenAI) to the record.');
+        }
+        else if (total.truncatedCalls > 0) {
+            lines.push(`${count(total.truncatedCalls, 'call')} hit the max_tokens ceiling:`
+                + ` ${formatUsd(total.truncatedOutputUsd)} of output`
+                + ` (${pct(total.outputUsd > 0 ? total.truncatedOutputUsd / total.outputUsd : 0)})`
+                + ' bought answers cut off mid-generation — paid in full and frequently retried.');
+            /**
+             * Which workloads pay for it, at a rate over calls that **recorded a
+             * stop reason** — never over every call, because a workload logging
+             * the field half the time is not one whose other half completed.
+             */
+            const truncating = report.byLabel
+                .filter((entry) => entry.breakdown.truncatedCalls > 0)
+                .sort((a, b) => b.breakdown.truncatedOutputUsd - a.breakdown.truncatedOutputUsd);
+            if (truncating.length > 0 && report.byLabel.length > 1) {
+                for (const entry of truncating.slice(0, 3)) {
+                    lines.push(`${name(entry.label)}: ${entry.breakdown.truncatedCalls} of`
+                        + ` ${entry.breakdown.stopReasonCalls} calls that recorded a stop reason were cut off`
+                        + ` (${pct(entry.breakdown.truncatedCalls / entry.breakdown.stopReasonCalls)}),`
+                        + ` ${formatUsd(entry.breakdown.truncatedOutputUsd)} of output. The denominator is`
+                        + ' the calls that measured, not every call.');
+                }
+            }
+            const ceiling = report.outputShapes.find((shape) => shape.p95WithinTokens !== null);
+            if (ceiling !== undefined) {
+                lines.push(`95% of the answers that finished fit within ${ceiling.p95WithinTokens} output tokens —`
+                    + ' the number a max_tokens cap wants. Measured on these calls, promised for nothing.');
+            }
+        }
+        else {
+            lines.push('Stop reasons were recorded, and no answer hit the max_tokens ceiling.');
+        }
+        /**
+         * This bill against the previous one. The same section the CLI prints,
+         * over the same shared `driversBetween` — appeared and vanished workloads
+         * named, the model split only when more than one model is involved, and a
+         * previous log with nothing priced reported as its own answer rather than
+         * as zero growth.
+         */
+        const previousLog = args.previous_log;
+        if (previousLog !== undefined) {
+            if (typeof previousLog !== 'string')
+                throw new InvalidArguments('previous_log must be a string');
+            if (previousLog.length > MAX_LOG_CHARS) {
+                throw new InvalidArguments(`previous_log is ${previousLog.length} characters, over the ${MAX_LOG_CHARS} limit`);
+            }
+            // The same filters on both sides: a windowed or drilled-down bill
+            // against the whole previous log would call every sibling workload a
+            // vanished saving.
+            const previous = profileUsage(previousLog, {
+                catalogue: BUNDLED_CATALOGUE,
+                label: onlyLabel,
+                sinceMs,
+                untilMs,
+            });
+            lines.push('', '--- against the previous log ---');
+            if (previous.total.calls === 0) {
+                lines.push('The previous log has nothing the pricing catalogue knows (under the same filters), '
+                    + 'so there is no comparison to make — a different answer from zero growth.');
+            }
+            else {
+                const delta = total.totalUsd - previous.total.totalUsd;
+                const growthPct = previous.total.totalUsd > 0
+                    ? ` (${delta >= 0 ? '+' : ''}${((delta / previous.total.totalUsd) * 100).toFixed(1)}%)`
+                    : '';
+                lines.push(`Positive means the bill grew. ${formatUsd(previous.total.totalUsd)} → `
+                    + `${formatUsd(total.totalUsd)}: ${delta >= 0 ? '+' : '-'}${formatUsd(Math.abs(delta))}${growthPct}, `
+                    + `over ${count(previous.total.calls, 'call')} then and ${count(total.calls, 'call')} now `
+                    + '— judge the call counts before the money.');
+                const describe = (d, shown) => d.was === null
+                    ? `${d.delta >= 0 ? '+' : '-'}${formatUsd(Math.abs(d.delta))} ${shown} (new since the previous log)`
+                    : d.now === null
+                        ? `${d.delta >= 0 ? '+' : '-'}${formatUsd(Math.abs(d.delta))} ${shown} (gone since the previous log)`
+                        : `${d.delta >= 0 ? '+' : '-'}${formatUsd(Math.abs(d.delta))} ${shown} (${formatUsd(d.was)} → ${formatUsd(d.now)})`;
+                for (const d of driversBetween(previous.byLabel.map((e) => ({ key: e.label, usd: e.breakdown.totalUsd })), report.byLabel.map((e) => ({ key: e.label, usd: e.breakdown.totalUsd }))).slice(0, 5)) {
+                    lines.push(describe(d, name(d.key)));
+                }
+                const modelsInvolved = new Set([
+                    ...previous.byModel.map((e) => e.model),
+                    ...report.byModel.map((e) => e.model),
+                ]);
+                const modelDrivers = driversBetween(previous.byModel.map((e) => ({ key: e.model, usd: e.breakdown.totalUsd })), report.byModel.map((e) => ({ key: e.model, usd: e.breakdown.totalUsd })));
+                if (modelDrivers.length > 0 && modelsInvolved.size > 1) {
+                    lines.push('The same change, by model — where the mix moved:');
+                    for (const d of modelDrivers.slice(0, 3))
+                        lines.push(describe(d, d.key));
+                }
+            }
+        }
+        /**
+         * The same request sent again a moment later — the pattern an agent
+         * harness produces when a step retries or loops. Named as a pattern:
+         * this reads counts and cannot see content.
+         */
+        if (report.repeatedTurns.length > 0) {
+            lines.push('');
+            lines.push('The same request, sent again:');
+            for (const row of report.repeatedTurns.slice(0, 3)) {
+                const shown = row.label === UNLABELLED ? 'unlabelled' : row.label;
+                lines.push(`  ${shown} on ${row.model}: ${row.repeats} of ${row.checkedCalls} calls re-sent the `
+                    + `previous call's exact input size within ${Math.round(row.withinMs / 1000)} seconds, `
+                    + `in the same conversation, costing ${formatUsd(row.usd)}. A conversation's input `
+                    + 'grows with every turn, so that is usually a retry, an agent step repeating, or a '
+                    + 'loop — the log cannot see content, so the pattern is the claim and not the cause.');
+            }
+        }
+        /**
+         * How big the calls are, and how uneven that is.
+         *
+         * The agent asking "why is input 63% of this bill" needs the shape, not
+         * the share: an even slice wants a shorter prompt and a skewed one wants
+         * a cap on whatever is growing. Both figures are bucket ceilings, so the
+         * ratio is stated as approximate.
+         */
+        if (report.inputShapes.length > 0) {
+            lines.push('');
+            lines.push('How big these calls are:');
+            for (const shape of report.inputShapes.slice(0, 3)) {
+                const shown = shape.label === UNLABELLED ? 'unlabelled' : shape.label;
+                if (shape.medianWithinTokens === null || shape.p95WithinTokens === null || shape.p95OverMedian === null) {
+                    lines.push(`  ${shown} on ${shape.model}: every call is larger than this tool measures precisely `
+                        + `(${formatUsd(shape.inputUsd)} of input spend). That size is itself the finding.`);
+                    continue;
+                }
+                const cached = `${Math.round(shape.cachedShare * 100)}% of those tokens were cache reads`;
+                lines.push(`  ${shown} on ${shape.model}: half its calls fit within `
+                    + `${shape.medianWithinTokens.toLocaleString('en-US')} input tokens and 95% within `
+                    + `${shape.p95WithinTokens.toLocaleString('en-US')} — about `
+                    + `${shape.p95OverMedian.toFixed(1)}x the ordinary call, over `
+                    + `${formatUsd(shape.inputUsd)} of input spend. ${cached}.`);
+                lines.push(shape.p95OverMedian >= 4
+                    ? '    Past four times the median the ordinary call is fine and something is growing on '
+                        + 'top of it — a conversation nobody truncates, a retrieval with no cap. The fix is a '
+                        + 'limit on the large calls, not a rewrite of the prompt every call sends.'
+                    : '    The large calls are not much larger than the ordinary one, so there is no tail to '
+                        + 'cap: the prompt is simply big.');
+            }
+        }
+        /**
+         * `what_if`: the same tokens at another model's rates.
+         *
+         * The caveat leads, because an agent relaying only the dollar figure would
+         * turn multiplication into a recommendation. What cannot move is stated
+         * next to what would: calls over the target's context window would fail
+         * rather than cost less, and money already on the target is not a saving.
+         */
+        const whatIfModel = args.what_if;
+        if (whatIfModel !== undefined) {
+            if (typeof whatIfModel !== 'string')
+                throw new InvalidArguments('what_if must be a string');
+            const whatIf = repriceProfile(report, whatIfModel, BUNDLED_CATALOGUE);
+            if (whatIf === null) {
+                throw new InvalidArguments(`what_if names a model this catalogue cannot price: "${whatIfModel}". Priced models: `
+                    + BUNDLED_CATALOGUE.models.map((m) => m.id).join(', '));
+            }
+            lines.push('');
+            lines.push(`These exact calls on ${whatIf.target.displayName}. This is multiplication, not advice: `
+                + 'the same token counts at another rate card. It says nothing about whether that '
+                + 'model could do the work, and a model that answers at greater length or gets '
+                + 'retried would not send these counts at all.');
+            if (whatIf.slices.length === 0) {
+                lines.push('Nothing to compare: every priced call is already on that model, or too large for '
+                    + 'its context window.');
+            }
+            else {
+                const direction = whatIf.deltaUsd < 0 ? 'less' : 'more';
+                lines.push(`${formatUsd(whatIf.currentUsd)} of movable spend would have been `
+                    + `${formatUsd(whatIf.targetUsd)} — ${formatUsd(Math.abs(whatIf.deltaUsd))} ${direction}.`);
+                for (const slice of whatIf.slices.slice(0, 5)) {
+                    const shown = slice.label === UNLABELLED ? 'unlabelled' : slice.label;
+                    lines.push(`  ${shown} on ${slice.model}: ${formatUsd(slice.currentUsd)} → ${formatUsd(slice.targetUsd)}`);
+                }
+            }
+            for (const slice of whatIf.overContext.slice(0, 3)) {
+                const shown = slice.label === UNLABELLED ? 'unlabelled' : slice.label;
+                lines.push(`${shown} cannot move: its largest call carries ${slice.maxCallInputTokens.toLocaleString('en-US')} `
+                    + `input tokens and that model's window is ${whatIf.target.contextWindow.toLocaleString('en-US')}. `
+                    + `Those calls would fail, not cost less, so their ${formatUsd(slice.currentUsd)} is excluded above.`);
+            }
+            if (whatIf.alreadyOnTarget.calls > 0) {
+                lines.push(`Already on that model: ${whatIf.alreadyOnTarget.calls} calls worth `
+                    + `${formatUsd(whatIf.alreadyOnTarget.usd)}, left out of the figures above — money that `
+                    + 'cannot move would make the difference look smaller than it is.');
+            }
+            if (whatIf.unpricedCalls > 0) {
+                lines.push(`Excluded: ${whatIf.unpricedCalls} calls whose model has no price here `
+                    + `(${whatIf.unpricedModels.join(', ')}). Their cost on the target is knowable; the `
+                    + 'difference is not, because there is no current figure to subtract from.');
+            }
+        }
+        /**
+         * What this log cannot answer yet — the fields that unlock the findings
+         * an agent would otherwise ask for and not receive. Counts rather than
+         * booleans: twelve labelled records out of forty thousand is not a
+         * labelled log, and an agent told "labelled" would stop asking.
+         */
+        const coverage = report.fieldCoverage;
+        if (coverage.parsed > 0) {
+            const missing = [];
+            const seen = (count_) => `${count_}/${coverage.parsed}`;
+            if (coverage.label < coverage.parsed) {
+                missing.push(`"label" on ${seen(coverage.label)} records — per-workload spend and the drill-down`);
+            }
+            if (coverage.session < coverage.parsed) {
+                missing.push(`"session" on ${seen(coverage.session)} records — conversation growth, per-conversation cost, cache-TTL fit (grouped by, never shown)`);
+            }
+            if (coverage.ts < coverage.parsed) {
+                missing.push(`"ts" on ${seen(coverage.ts)} records — the period, the per-day and per-hour shape, and the cache-TTL question`);
+            }
+            if (coverage.stopReason < coverage.parsed) {
+                missing.push(`"stop_reason"/"finish_reason" on ${seen(coverage.stopReason)} records — answers cut off at max_tokens`);
+            }
+            if (coverage.cacheWrites > 0 && coverage.cacheTtl < coverage.cacheWrites) {
+                missing.push(`the "cache_creation" object on ${coverage.cacheTtl}/${coverage.cacheWrites} of the records that wrote to the cache — otherwise the cheaper rate is assumed and those totals are a floor`);
+            }
+            if (missing.length > 0) {
+                lines.push('', '--- what this log cannot answer yet ---');
+                for (const line of missing)
+                    lines.push(line);
+            }
+        }
+        if (report.unpricedModels.length > 0 || report.skippedLines.length > 0) {
+            lines.push('', '--- gaps ---');
+            gaps();
+        }
+        return lines.join('\n');
+    },
+};
 /** The whole surface. An exact list, asserted as one by the tests. */
-export const TOOLS = [OPTIMIZE, CHECK, MODELS];
+export const TOOLS = [OPTIMIZE, CHECK, MODELS, PROFILE];
 //# sourceMappingURL=tools.js.map