@trazum/core 1.9.0 → 1.10.0

package/dist/usage.js

@@ -0,0 +1,274 @@
+import { effectivePricing, multipliersFor } from './pricing.js';
+const EMPTY = () => ({
+    calls: 0,
+    inputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    outputTokens: 0,
+    assumedWriteTtlCalls: 0,
+    inputUsd: 0,
+    cacheReadUsd: 0,
+    cacheWriteUsd: 0,
+    outputUsd: 0,
+    totalUsd: 0,
+});
+const OK = (value) => ({ kind: 'ok', value });
+function readCount(...candidates) {
+    let sawCorrupt = false;
+    for (const value of candidates) {
+        if (value === undefined)
+            continue;
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+            return OK(value);
+        // Present and unusable: a string, a null, a negative, a NaN.
+        sawCorrupt = true;
+    }
+    return sawCorrupt ? { kind: 'corrupt' } : { kind: 'absent' };
+}
+/** Zero for an absent count. Callers reject corrupt ones before reaching this. */
+const valueOf = (count) => (count.kind === 'ok' ? count.value : 0);
+/**
+ * One line of a usage log, or `null` when it is not one.
+ *
+ * Accepts the Anthropic shape and the OpenAI one, because those are the two
+ * things people actually have. The alternative — a Trazum-specific schema — asks
+ * for a transformation step before the tool will read anything, and a tool with a
+ * setup cost that exceeds its payoff does not get run twice.
+ *
+ * `null` in three cases, and the third is the one that was wrong:
+ *
+ * 1. Not JSON, or not an object, or no `model`.
+ * 2. **No** token counts at all — counting it would inflate the call count while
+ *    contributing nothing, which lowers every per-call figure.
+ * 3. **Any** count present but unreadable. A field that is there and unusable is
+ *    corruption, and a corrupt line belongs in `skippedLines` where the report
+ *    names it, not in the totals as a silent zero.
+ */
+export function parseUsageLine(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return null;
+    const record = raw;
+    // Anthropic nests usage on a response; a hand-rolled log usually flattens it.
+    const usage = typeof record.usage === 'object' && record.usage !== null
+        ? record.usage
+        : record;
+    const model = typeof record.model === 'string' ? record.model : null;
+    if (!model)
+        return null;
+    /**
+     * OpenAI reports cached tokens inside `prompt_tokens_details` **and counts them
+     * in `prompt_tokens`**, while Anthropic reports them separately and does not.
+     * Subtracting in one case and not the other is the difference between a correct
+     * bill and one that charges the cached half twice.
+     */
+    const details = typeof usage.prompt_tokens_details === 'object' && usage.prompt_tokens_details !== null
+        ? usage.prompt_tokens_details
+        : null;
+    const openAiCached = details ? readCount(details.cached_tokens) : { kind: 'absent' };
+    /**
+     * Anthropic splits cache writes by time-to-live, and the two cost different
+     * amounts: 1.25x input for the 5-minute entry, **2x** for the 1-hour one.
+     *
+     * Reading only the flat `cache_creation_input_tokens` threw that distinction
+     * away and then priced everything at the cheaper rate — a 1-hour workload
+     * reported 37.5% under, silently, on its largest line. The split is in the log
+     * whenever the recording recipe in the README is followed, because it is part of
+     * the `usage` object the API returns.
+     */
+    const creation = typeof usage.cache_creation === 'object' && usage.cache_creation !== null
+        ? usage.cache_creation
+        : null;
+    const write5m = creation ? readCount(creation.ephemeral_5m_input_tokens) : { kind: 'absent' };
+    const write1h = creation ? readCount(creation.ephemeral_1h_input_tokens) : { kind: 'absent' };
+    const counts = {
+        input: readCount(usage.input_tokens, usage.inputTokens, usage.prompt_tokens),
+        output: readCount(usage.output_tokens, usage.outputTokens, usage.completion_tokens),
+        cacheRead: readCount(usage.cache_read_input_tokens, usage.cacheReadTokens),
+        cacheWrite: readCount(usage.cache_creation_input_tokens, usage.cacheWriteTokens),
+        openAiCached,
+        write5m,
+        write1h,
+    };
+    // Any field present and unreadable rejects the line. See `readCount`.
+    if (Object.values(counts).some((c) => c.kind === 'corrupt'))
+        return null;
+    // Nothing to count at all.
+    if (Object.values(counts).every((c) => c.kind === 'absent'))
+        return null;
+    const cached = valueOf(counts.openAiCached);
+    const flatWrite = valueOf(counts.cacheWrite);
+    const split5m = valueOf(counts.write5m);
+    const split1h = valueOf(counts.write1h);
+    const hasSplit = counts.write5m.kind === 'ok' || counts.write1h.kind === 'ok';
+    return {
+        model,
+        inputTokens: Math.max(0, valueOf(counts.input) - cached),
+        cacheReadTokens: counts.cacheRead.kind === 'ok' ? counts.cacheRead.value : cached,
+        /**
+         * The split when the log carries it, the flat number otherwise — and
+         * `writeTtlKnown` says which, so the report can admit that a rate was assumed
+         * rather than quietly choosing the cheaper one.
+         */
+        cacheWrite5mTokens: hasSplit ? split5m : flatWrite,
+        cacheWrite1hTokens: hasSplit ? split1h : 0,
+        writeTtlKnown: hasSplit || flatWrite === 0,
+        outputTokens: valueOf(counts.output),
+        label: typeof record.label === 'string' && record.label.trim() !== ''
+            ? record.label.trim()
+            : null,
+    };
+}
+/** The bucket unlabelled calls land in, named so a report can say so. */
+export const UNLABELLED = 'unlabelled';
+/** Token counts only. Used for both halves, because both need them. */
+function countInto(into, record) {
+    into.calls += 1;
+    into.inputTokens += record.inputTokens;
+    into.cacheReadTokens += record.cacheReadTokens;
+    into.cacheWriteTokens += record.cacheWrite5mTokens + record.cacheWrite1hTokens;
+    if (!record.writeTtlKnown)
+        into.assumedWriteTtlCalls += 1;
+    into.outputTokens += record.outputTokens;
+}
+function add(into, record, catalogue, on) {
+    /**
+     * Looked up directly rather than through `modelFrom`, which **throws** on an id
+     * it does not know. A usage log is somebody's production traffic and will
+     * contain models this catalogue has never heard of — a fine-tune, a preview, a
+     * competitor. Throwing means one unfamiliar id destroys the whole profile;
+     * naming it separately means the report is honest about what it could not price
+     * and useful about everything else.
+     *
+     * **Priced first, counted second.** The other order was the bug: counts landed
+     * before the lookup could fail, so an unpriced call contributed tokens to a
+     * total whose dollars excluded it.
+     */
+    const model = catalogue.byId.get(record.model);
+    if (!model)
+        return false;
+    countInto(into, record);
+    const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
+    const rates = multipliersFor(model);
+    const per = (tokens, rate) => (tokens / 1_000_000) * rate;
+    into.inputUsd += per(record.inputTokens, inputPerMTok);
+    into.cacheReadUsd += per(record.cacheReadTokens, inputPerMTok * rates.cacheRead);
+    /**
+     * Each TTL at its own rate. Anthropic charges 1.25x input for a 5-minute entry
+     * and 2x for a 1-hour one, and the first version applied 1.25x to both — 37.5%
+     * under on a 1-hour workload, on the largest line, with nothing on screen
+     * saying a rate had been chosen.
+     */
+    into.cacheWriteUsd += per(record.cacheWrite5mTokens, inputPerMTok * rates.cacheWrite5m);
+    into.cacheWriteUsd += per(record.cacheWrite1hTokens, inputPerMTok * rates.cacheWrite1h);
+    into.outputUsd += per(record.outputTokens, outputPerMTok);
+    into.totalUsd =
+        into.inputUsd + into.cacheReadUsd + into.cacheWriteUsd + into.outputUsd;
+    return true;
+}
+/**
+ * Reads a usage log and says where the money went.
+ *
+ * Takes the whole text rather than a stream: a usage log is measured in megabytes
+ * and this package imports no Node builtins, so streaming would mean an interface
+ * the browser build cannot satisfy. `@trazum/core/node` is where file reading
+ * lives, and it can chunk if it ever needs to.
+ */
+export function profileUsage(text, options) {
+    const { catalogue, on = new Date() } = options;
+    const total = EMPTY();
+    const unpriced = EMPTY();
+    const byLabel = new Map();
+    const byModel = new Map();
+    const unpricedModels = new Set();
+    const skippedLines = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (line === '')
+            continue;
+        const record = parseUsageLine(line);
+        if (!record) {
+            skippedLines.push(i + 1);
+            continue;
+        }
+        if (!add(total, record, catalogue, on)) {
+            unpricedModels.add(record.model);
+            countInto(unpriced, record);
+            // Still grouped by model, so the reader can see which unknown id is costing
+            // them attention — but with zero dollars, which the grouping makes obvious.
+            if (!byModel.has(record.model))
+                byModel.set(record.model, EMPTY());
+            countInto(byModel.get(record.model), record);
+            continue;
+        }
+        const labelKey = record.label ?? UNLABELLED;
+        if (!byLabel.has(labelKey))
+            byLabel.set(labelKey, EMPTY());
+        add(byLabel.get(labelKey), record, catalogue, on);
+        if (!byModel.has(record.model))
+            byModel.set(record.model, EMPTY());
+        add(byModel.get(record.model), record, catalogue, on);
+    }
+    const sorted = (map, key) => [...map.entries()]
+        .sort((a, b) => b[1].totalUsd - a[1].totalUsd || a[0].localeCompare(b[0]))
+        .map(([name, breakdown]) => ({ [key]: name, breakdown }));
+    return {
+        total,
+        byLabel: sorted(byLabel, 'label'),
+        byModel: sorted(byModel, 'model'),
+        unpricedModels: [...unpricedModels].sort(),
+        unpriced,
+        skippedLines,
+    };
+}
+/**
+ * What share of the bill each part is.
+ *
+ * The point of the whole module in one function: a caller can print "output is
+ * 87% of this" without doing arithmetic that would drift from the arithmetic
+ * here.
+ *
+ * All zeroes when nothing was spent, rather than `NaN`. A profile of an empty log
+ * is a legitimate result — no calls yet — and a report full of `NaN%` is a bug
+ * report from somebody who did nothing wrong.
+ */
+export function sharesOf(breakdown) {
+    const { totalUsd } = breakdown;
+    if (totalUsd <= 0)
+        return { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
+    return {
+        input: breakdown.inputUsd / totalUsd,
+        cacheRead: breakdown.cacheReadUsd / totalUsd,
+        cacheWrite: breakdown.cacheWriteUsd / totalUsd,
+        output: breakdown.outputUsd / totalUsd,
+    };
+}
+/**
+ * How much of the input that could have been cached was.
+ *
+ * `null` when nothing was cacheable-looking at all — no reads and no writes —
+ * because a hit rate over zero attempts is not zero, it is undefined, and
+ * printing "0% cache hit rate" for somebody who never turned caching on is a
+ * finding about nothing.
+ *
+ * Reads against reads-plus-full-price-input, deliberately. Cache *writes* are
+ * excluded from the denominator: a write is the cost of establishing an entry,
+ * not a missed read, and counting it as a miss makes a healthy cache look broken
+ * on the day it warms.
+ */
+export function cacheHitRate(breakdown) {
+    const attempts = breakdown.cacheReadTokens + breakdown.inputTokens;
+    if (breakdown.cacheReadTokens === 0 && breakdown.cacheWriteTokens === 0)
+        return null;
+    if (attempts === 0)
+        return null;
+    return breakdown.cacheReadTokens / attempts;
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",

package/src/advisories.ts

@@ -125,7 +125,25 @@ export function buildAdvisories(
   const monthlyOutputUsd =
     (usage.avgOutputTokens / 1_000_000) * outputPerMTok * usage.callsPerMonth * batchFactor;
 
-  // --- Context window ---
+  /**
+   * --- Context window ---
+   *
+   * The third place an estimate was compared against a hard threshold and the
+   * answer stated as fact, after `cache-prefix-reorder` and `prompt-caching`. This
+   * one has no dollar figure and is the most absolute of the three: **"The call
+   * will fail."**
+   *
+   * With a ±10% band it fails in both directions. An estimated 1,050,000 tokens
+   * against a 1,000,000 window can truly be 945,000 — the call succeeds and the
+   * reader has been sent to split a prompt that fitted. And an estimated 990,000
+   * can truly be 1,089,000, which does not fit, and nothing said anything at all.
+   *
+   * The silent direction is the worse one. A prompt over the window fails
+   * outright rather than degrading, so there is no partial result to notice.
+   */
+  const estimated = count === estimateTokens;
+  const band = ESTIMATE_ERROR_BAND_PCT / 100;
+
   if (tokensAfter > model.contextWindow) {
     advisories.push({
       id: 'context-overflow',
@@ -134,6 +152,20 @@ export function buildAdvisories(
         tokens: tokensAfter,
         modelName: model.displayName,
         contextWindow: model.contextWindow,
+        // Only an estimate can be uncertain. A caller who counted exactly is told
+        // the call fails, because it does.
+        uncertain: estimated && tokensAfter * (1 - band) <= model.contextWindow,
+      }),
+      estimatedMonthlyUsd: null,
+    });
+  } else if (estimated && tokensAfter * (1 + band) > model.contextWindow) {
+    advisories.push({
+      id: 'context-near-limit',
+      severity: 'warning',
+      ...t.advisories.contextNearLimit({
+        tokens: tokensAfter,
+        modelName: model.displayName,
+        contextWindow: model.contextWindow,
       }),
       estimatedMonthlyUsd: null,
     });
@@ -185,6 +217,22 @@ export function buildAdvisories(
             readPct: Math.round(rates.cacheRead * 100),
             writePct: Math.round(rates.cacheWrite5m * 100),
             explicit: (model.caching ?? 'explicit') === 'explicit',
+            /**
+             * The mirror of `couldReachMinimum` on `below-cache-minimum`, and the
+             * asymmetry between them was a real gap: that one hedged an estimate
+             * landing just *under* the threshold, while this one promised money on
+             * an estimate landing just *over* it. With a ±10% band an estimated
+             * 528-token prefix can truly be 475, and then nothing caches at all.
+             *
+             * The cautionary direction is the one that needed it, because this is
+             * the side with a dollar figure attached. Only when the number is an
+             * estimate: a caller who supplied their own counter has an
+             * authoritative prefix and hedging it would push them toward a check
+             * they have already done.
+             */
+            nearMinimum:
+              count === estimateTokens &&
+              cache.stablePrefixTokens * (1 - ESTIMATE_ERROR_BAND_PCT / 100) < minTokens,
           }),
           estimatedMonthlyUsd: saving,
         });
@@ -223,12 +271,49 @@ export function buildAdvisories(
       });
     }
 
-    // Stable content placed AFTER the first placeholder: never cached today,
-    // but moving it in front would make it cacheable.
+    /**
+     * Stable content placed AFTER the first placeholder: never cached today, and
+     * cacheable if it moves in front.
+     *
+     * **The prefix it would produce has to clear the minimum, and it did not used
+     * to be checked.** That was a money figure in the flattering direction, which
+     * is the one fault this file exists to avoid. On a 306-token support prompt
+     * against Claude Opus 5's 512-token minimum, the best prefix a rearrangement
+     * can build is 302 — so nothing caches, and the advisory offered $48.67 a
+     * month that cannot be collected.
+     *
+     * Worse, it said so in the same report as `below-cache-minimum`, which was
+     * telling the reader caching would not work here at all. Two advisories
+     * contradicting each other, and the one with a dollar sign winning the
+     * argument.
+     *
+     * `reorderForCache` already refused these prompts for exactly this reason, so
+     * the tool's advice and its action disagreed: follow the advice, run
+     * `--reorder`, and watch nothing happen.
+     */
+    /**
+     * The best prefix any rearrangement could build, compared strictly.
+     *
+     * **No band hedge here, and that was tried first.** Widening the comparison by
+     * ±10% — on the same reasoning that makes `below-cache-minimum` hedge near the
+     * line — opened a window between 466 and 512 tokens where this advisory
+     * offered a saving and `reorderForCache` refused to perform it. That is the
+     * fault being fixed, reintroduced one layer up, and a test caught it.
+     *
+     * The near-the-line case is already handled and in the right place:
+     * `below-cache-minimum` says the estimate is close to the threshold and names
+     * `--exact-tokens`. Settle the number and both this advisory and the command
+     * work from the same certainty. Two components disagreeing is worse than one
+     * of them being briefly quiet.
+     */
+    const reorderedPrefix = cache.stablePrefixTokens + cache.staticTokensAfter;
+    const reachableAfterReorder = reorderedPrefix >= minTokens;
+
     if (
       cache.firstPlaceholder &&
       cache.staticTokensAfter >= 200 &&
-      cache.staticTokensAfter >= tokensAfter * 0.3
+      cache.staticTokensAfter >= tokensAfter * 0.3 &&
+      reachableAfterReorder
     ) {
       const movableShare = tokensAfter > 0 ? cache.staticTokensAfter / tokensAfter : 0;
       const saving = monthlyInputUsd * movableShare * Math.max(0, 1 - factor);
@@ -239,6 +324,13 @@ export function buildAdvisories(
           staticTokensAfter: cache.staticTokensAfter,
           sharePct: Math.round(movableShare * 100),
           placeholder: cache.firstPlaceholder,
+          /**
+           * Trazum can do this, and until now it told you to do it by hand.
+           * `reorderForCache` moves whole blocks, refuses any block carrying a
+           * backward reference, and refuses everything after one — so the command
+           * is the safe way to attempt what the prose was describing.
+           */
+          command: 'trazum optimize <file> --reorder',
         }),
         estimatedMonthlyUsd: saving > 0 ? saving : null,
       });

package/src/i18n/en.ts

@@ -91,9 +91,18 @@ export const en: CoreMessages = {
   },
 
   advisories: {
-    contextOverflow: ({ tokens, modelName, contextWindow }) => ({
-      title: 'The prompt does not fit in the context window',
-      detail: `The optimised prompt is ~${n(tokens)} tokens and ${modelName} accepts ${n(contextWindow)}. The call will fail: split the content or move to a model with a larger window.`,
+    contextOverflow: ({ tokens, modelName, contextWindow, uncertain }) => ({
+      title: uncertain
+        ? 'The prompt probably does not fit in the context window'
+        : 'The prompt does not fit in the context window',
+      detail: uncertain
+        ? `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}. That count is an estimate and it is close to the line, so the call will probably fail but might not — settle it with --exact-tokens before rewriting anything. The counting endpoint is free. If it does exceed the window, split the content or move to a model with a larger one.`
+        : `The optimised prompt is ~${n(tokens)} tokens and ${modelName} accepts ${n(contextWindow)}. The call will fail: split the content or move to a model with a larger window.`,
+    }),
+
+    contextNearLimit: ({ tokens, modelName, contextWindow }) => ({
+      title: 'The prompt may not fit in the context window',
+      detail: `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}, which fits — but that count is an estimate and its error range reaches past the window, so the real prompt may not. A call that exceeds the window fails outright rather than degrading, and nothing else here warns about it. Confirm with --exact-tokens; the counting endpoint is free.`,
     }),
 
     promptCaching: ({
@@ -106,6 +115,7 @@ export const en: CoreMessages = {
       readPct,
       writePct,
       explicit,
+      nearMinimum,
     }) => {
       const scope = placeholder
         ? `The stable prefix — everything before the first placeholder ${placeholder} — is ~${n(prefixTokens)} of the prompt's ${n(totalTokens)} tokens, and clears ${modelName}'s ${n(minTokens)}-token cacheable minimum.`
@@ -113,9 +123,12 @@ export const en: CoreMessages = {
       const how = explicit
         ? 'Put the cache marker at the end of the stable prefix: any byte that changes before the cut invalidates everything after it.'
         : `${modelName} caches automatically above its minimum, so there is nothing to set — but the same rule applies: any byte that changes before the cut invalidates everything after it.`;
+      const hedge = nearMinimum
+        ? ` One caveat on the figure: that prefix count is an estimate and it is close to the line, so the real one may be below the ${n(minTokens)}-token minimum — in which case nothing caches and this saving is not there. Settle it with --exact-tokens before budgeting from it. The counting endpoint is free.`
+        : '';
       return {
         title: 'Turn on prompt caching for the stable prefix',
-        detail: `${scope} At a ${hitRatePct}% hit rate, a cache read costs ${readPct}% of the input price and a write costs ${writePct}%. ${how}`,
+        detail: `${scope} At a ${hitRatePct}% hit rate, a cache read costs ${readPct}% of the input price and a write costs ${writePct}%. ${how}${hedge}`,
       };
     },
 
@@ -150,9 +163,9 @@ export const en: CoreMessages = {
       };
     },
 
-    cachePrefixReorder: ({ staticTokensAfter, sharePct, placeholder }) => ({
+    cachePrefixReorder: ({ staticTokensAfter, sharePct, placeholder, command }) => ({
       title: 'Move the stable instructions ahead of the first placeholder',
-      detail: `About ~${n(staticTokensAfter)} tokens of stable content (${sharePct}% of the prompt) sit after the first variable placeholder ${placeholder}, so today they never get cached. Reorder the template — fixed instructions and context first, placeholders last — and that content starts being read from cache at 10% of the price. Check that reordering does not change what the prompt asks for.`,
+      detail: `About ~${n(staticTokensAfter)} tokens of stable content (${sharePct}% of the prompt) sit after the first variable placeholder ${placeholder}, so today they never get cached. Fixed instructions and context first, placeholders last, and that content starts being read from cache at 10% of the price. Run \`${command}\` to attempt it: whole blocks only, and it refuses to move anything that refers back to earlier text. Read the diff — order carries meaning, and "summarise the text above" is nonsense in front of the text it points at.`,
     }),
 
     batchApi: () => ({

package/src/i18n/es.ts

@@ -91,9 +91,18 @@ export const es: CoreMessages = {
   },
 
   advisories: {
-    contextOverflow: ({ tokens, modelName, contextWindow }) => ({
-      title: 'El prompt no cabe en la ventana de contexto',
-      detail: `El prompt optimizado ocupa ~${n(tokens)} tokens y ${modelName} admite ${n(contextWindow)}. La llamada fallará: divide el contenido o cambia a un modelo con ventana mayor.`,
+    contextOverflow: ({ tokens, modelName, contextWindow, uncertain }) => ({
+      title: uncertain
+        ? 'El prompt probablemente no cabe en la ventana de contexto'
+        : 'El prompt no cabe en la ventana de contexto',
+      detail: uncertain
+        ? `El prompt optimizado ocupa ~${n(tokens)} tokens frente a los ${n(contextWindow)} de ${modelName}. Ese recuento es una estimación y está cerca del límite, así que la llamada fallará probablemente, pero puede que no —confírmalo con --exact-tokens antes de reescribir nada. El endpoint de conteo es gratis. Si de verdad se pasa, divide el contenido o cambia a un modelo con ventana mayor.`
+        : `El prompt optimizado ocupa ~${n(tokens)} tokens y ${modelName} admite ${n(contextWindow)}. La llamada fallará: divide el contenido o cambia a un modelo con ventana mayor.`,
+    }),
+
+    contextNearLimit: ({ tokens, modelName, contextWindow }) => ({
+      title: 'El prompt puede no caber en la ventana de contexto',
+      detail: `El prompt optimizado ocupa ~${n(tokens)} tokens frente a los ${n(contextWindow)} de ${modelName}, así que cabe —pero ese recuento es una estimación y su margen de error se pasa de la ventana, así que el prompt real puede no caber. Una llamada que excede la ventana falla del todo en lugar de degradarse, y nada más aquí avisa de eso. Confírmalo con --exact-tokens; el endpoint de conteo es gratis.`,
     }),
 
     promptCaching: ({
@@ -106,6 +115,7 @@ export const es: CoreMessages = {
       readPct,
       writePct,
       explicit,
+      nearMinimum,
     }) => {
       const scope = placeholder
         ? `El prefijo estable —lo anterior al primer marcador ${placeholder}— son ~${n(prefixTokens)} de los ${n(totalTokens)} tokens del prompt, y supera el mínimo cacheable de ${n(minTokens)} de ${modelName}.`
@@ -113,9 +123,12 @@ export const es: CoreMessages = {
       const how = explicit
         ? 'Coloca el marcador de caché al final del prefijo estable: cualquier byte que cambie antes del corte invalida todo lo que va detrás.'
         : `${modelName} cachea automáticamente por encima de su mínimo, así que no hay nada que activar; pero la regla es la misma: cualquier byte que cambie antes del corte invalida todo lo que va detrás.`;
+      const hedge = nearMinimum
+        ? ` Un aviso sobre la cifra: ese recuento del prefijo es una estimación y está cerca del límite, así que el real puede quedar por debajo del mínimo de ${n(minTokens)} tokens —y entonces no se cachea nada y este ahorro no existe. Confírmalo con --exact-tokens antes de presupuestar sobre él. El endpoint de conteo es gratis.`
+        : '';
       return {
         title: 'Activa prompt caching en el prefijo estable',
-        detail: `${scope} Con una tasa de acierto del ${hitRatePct}%, la lectura de caché cuesta un ${readPct}% del precio de entrada y la escritura un ${writePct}%. ${how}`,
+        detail: `${scope} Con una tasa de acierto del ${hitRatePct}%, la lectura de caché cuesta un ${readPct}% del precio de entrada y la escritura un ${writePct}%. ${how}${hedge}`,
       };
     },
 
@@ -150,9 +163,9 @@ export const es: CoreMessages = {
       };
     },
 
-    cachePrefixReorder: ({ staticTokensAfter, sharePct, placeholder }) => ({
+    cachePrefixReorder: ({ staticTokensAfter, sharePct, placeholder, command }) => ({
       title: 'Mueve las instrucciones estables antes del primer marcador',
-      detail: `Unos ~${n(staticTokensAfter)} tokens de contenido estable (el ${sharePct}% del prompt) están después del primer marcador variable ${placeholder}, así que hoy no se cachean nunca. Reordena la plantilla —instrucciones y contexto fijos primero, marcadores al final— y ese contenido pasa a leerse de caché al 10% del precio. Revisa que la reordenación no cambie el sentido del prompt.`,
+      detail: `Unos ~${n(staticTokensAfter)} tokens de contenido estable (el ${sharePct}% del prompt) están después del primer marcador variable ${placeholder}, así que hoy no se cachean nunca. Instrucciones y contexto fijos primero, marcadores al final, y ese contenido empieza a leerse de caché al 10% del precio. Ejecuta \`${command}\` para intentarlo: solo mueve bloques completos y se niega a mover cualquiera que se refiera a texto anterior. Lee el diff —el orden significa algo, y «resume el texto de arriba» no tiene sentido delante del texto al que apunta.`,
     }),
 
     batchApi: () => ({

package/src/i18n/types.ts

@@ -51,6 +51,17 @@ export interface RuleCopy {
 // --------------------------------------------------------------------------
 
 export interface ContextOverflowParams {
+  /**
+   * The count is an estimate and its band reaches back under the window, so
+   * "the call will fail" is a prediction rather than a fact.
+   */
+  uncertain: boolean;
+  tokens: number;
+  modelName: string;
+  contextWindow: number;
+}
+
+export interface ContextNearLimitParams {
   tokens: number;
   modelName: string;
   contextWindow: number;
@@ -60,6 +71,20 @@ export interface PromptCachingParams {
   /** First template placeholder, or `null` when the prompt has none. */
   placeholder: string | null;
   prefixTokens: number;
+  /**
+   * The prefix is an estimate and the band reaches below the minimum, so the
+   * saving may not be collectable at all.
+   *
+   * The mirror of `BelowCacheMinimumParams.couldReachMinimum`, and the asymmetry
+   * was a real gap: that one hedged an estimate landing just *under* a hard
+   * threshold, while this one promised money on an estimate landing just *over*
+   * it. With a ±10% band an estimated 528-token prefix can truly be 475, in which
+   * case nothing caches and the figure beside this advisory is uncollectable.
+   *
+   * The cautionary direction matters more than the encouraging one, because this
+   * is the side with a dollar sign attached.
+   */
+  nearMinimum: boolean;
   totalTokens: number;
   minTokens: number;
   modelName: string;
@@ -93,7 +118,7 @@ export interface BelowCacheMinimumParams {
    * count could be above it.
    *
    * Without this the advisory asserts "caching will not work here" from a number
-   * measured to ±15%, and on a prefix near the threshold that is not an imprecise
+   * measured to ±10%, and on a prefix near the threshold that is not an imprecise
    * figure — it is wrong advice, and it costs the reader the largest saving
    * Trazum offers.
    */
@@ -104,6 +129,8 @@ export interface CachePrefixReorderParams {
   staticTokensAfter: number;
   sharePct: number;
   placeholder: string;
+  /** The command that attempts it, because Trazum can do this itself. */
+  command: string;
 }
 
 export interface ModelDowngradeParams {
@@ -193,6 +220,7 @@ export interface CoreMessages {
   suggest: SuggestMessages;
   advisories: {
     contextOverflow(p: ContextOverflowParams): LocalizedMessage;
+    contextNearLimit(p: ContextNearLimitParams): LocalizedMessage;
     promptCaching(p: PromptCachingParams): LocalizedMessage;
     promptCachingNotWorthIt(): LocalizedMessage;
     belowCacheMinimum(p: BelowCacheMinimumParams): LocalizedMessage;

package/src/index.ts

@@ -1,5 +1,19 @@
 export * from './types.js';
 export { ESTIMATE_ERROR_BAND_PCT, estimateTokens, countTokensAnthropic } from './tokenizer.js';
+export {
+  UNLABELLED,
+  cacheHitRate,
+  parseUsageLine,
+  profileUsage,
+  sharesOf,
+} from './usage.js';
+export type {
+  UsageProfileOptions,
+  UsageBreakdown,
+  UsageProfileReport,
+  UsageRecord,
+  UsageShares,
+} from './usage.js';
 export { DETECTABLE_LANGUAGES, detectTextLanguage } from './language.js';
 export { countSentences, profilePrompt } from './profile.js';
 export { PHRASE_LANGUAGES } from './phrases.js';