@trazum/cli 1.28.0 → 1.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.28.0"
+    "@trazum/core": "1.30.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -234,6 +234,10 @@ ${bold('OPTIONS FOR profile')}
                               afternoon a loop burned a quarter of it. A log
                               with no timestamps fails: not measured is not
                               under budget.
+  --max-session-usd <n>       Fail when any single conversation in the log
+                              cost more than this — the unit an agent product
+                              blows up in. A log with no sessions fails: not
+                              measured is not under budget.
   --since <when>              Profile only calls at or after this moment. A UTC
   --until <when>              day (2026-08-14), a full ISO 8601 timestamp, a
                               relative window (7d, 24h) or "now";
@@ -1081,6 +1085,12 @@ ${bold('EXAMPLES')}
       `FAILED — ${day} spent ${usd}, over the --max-day-usd limit of ${max}. A total under budget can hide a single runaway day, which is what this gate exists to catch.`,
     maxDayNoClock: () =>
       'FAILED — --max-day-usd was asked for and no record in this log carries a timestamp, so there are no days to judge. That is not a pass: a bill nobody could measure by day is not a bill that stayed under a daily budget. Add "ts" to the record and the gate arms.',
+    maxSessionOk: (worst, max, sessions) =>
+      `No conversation over budget: the most expensive of ${sessions} cost ${worst}, against --max-session-usd ${max}. A conversation that started before this log is counted only for the turns recorded here, so this is a floor.`,
+    maxSessionFailed: (worst, max, sessions) =>
+      `FAILED — the most expensive of ${sessions} conversations cost ${worst}, over the --max-session-usd limit of ${max}. A month's budget and a day's budget both pass while one conversation loops its way through this; the per-conversation figure is the one that catches it.`,
+    maxSessionNoSessions: () =>
+      'FAILED — --max-session-usd was asked for and no record in this log carries a session, so there are no conversations to judge. That is not a pass. Add "session" (or "conversation_id") to the record and the gate arms; Trazum groups by it and never prints it.',
     maxDayUndated: (calls) =>
       `${calls} calls carry no timestamp, so they are in the bill and in none of the days above — the worst day is a floor by whatever they held. A failure would stand regardless; this pass is over the part that could be dated.`,
     maxCacheLossWorstCase: (calls, worst, max) =>
@@ -1161,6 +1171,23 @@ ${bold('EXAMPLES')}
       `No usage logs in "${directory}". Looked for files ending in ${extensions}. A directory with nothing readable in it is an error rather than an empty report, which would read as "you spent nothing".`,
     sessionCostTail: (ratio) =>
       `The 95th percentile is ${ratio}x the median there: most conversations are cheap and a few are not, which is a tail a quota can catch. Where median and p95 sit close together the workload is simply expensive and there is no tail to hunt.`,
+    sessionSpendOnly: (sessions, max) =>
+      `${sessions} ${sessions === '1' ? 'conversation' : 'conversations'} in this log; the most expensive cost ${max}. Too few per workload for a percentile — a maximum is a fact at any count, and it is the figure --max-session-usd judges.`,
+    maxGrowthCoverageLost: (fields, was, now) =>
+      `FAILED — this log stopped recording ${fields} (${was} of records before, ${now} now), so the comparison cannot be made. That is not a pass: a bill whose growth nobody could measure is not a bill that stayed flat, and every finding that needed the field went quiet for a reason that has nothing to do with spend.`,
+    coverageField: (field) =>
+      ({ label: 'label', session: 'session', ts: 'timestamp', stopReason: 'stop reason' })[field] ?? field,
+    coverageSilenced: (field) =>
+      ({
+        label: 'Gone quiet with it: per-workload spend, the drill-down, and levers that describe a decision rather than a mixture.',
+        session: 'Gone quiet with it: conversation growth, per-conversation cost, repeated turns, truncation retries and the cache-TTL fit.',
+        ts: 'Gone quiet with it: the period, the per-day and per-hour shape, the model mix drift, and the cache-TTL question entirely.',
+        stopReason: 'Gone quiet with it: answers cut off at max_tokens, and the retries billed after them.',
+      })[field] ?? '',
+    coverageDrift: (field, was, now) =>
+      `Coverage moved: ${field} was on ${was} of records and is now on ${now}.`,
+    coverageDriftWhy: () =>
+      'A field the log stopped recording is not a finding that got fixed — every finding that needed it has gone quiet for a reason that has nothing to do with the bill. Reported from a 20-point move in either direction; a field that appeared means this report can see what the previous one could not.',
     againstOverlap: (from, to) =>
       `These two logs both cover ${from} → ${to}, so some of the same calls sit on both sides of this subtraction and part of the change is the same money counted twice. Compare periods that do not overlap — or window both logs with --since/--until.`,
     windowLine: (since, until) =>

package/src/i18n/es.ts

@@ -232,6 +232,10 @@ ${bold('OPCIONES DE profile')}
                               una cuarta parte. Un registro sin marcas de
                               tiempo falla: no medido no es dentro de
                               presupuesto.
+  --max-session-usd <n>       Falla cuando una sola conversación del registro
+                              costó más que esto — la unidad en la que revienta
+                              un producto de agentes. Un registro sin sesiones
+                              falla: no medido no es dentro de presupuesto.
   --since <cuándo>            Perfila solo llamadas desde/hasta ese momento. Un
   --until <cuándo>            día UTC (2026-08-14), una marca ISO 8601 completa,
                               una ventana relativa (7d, 24h) o "now";
@@ -1095,6 +1099,12 @@ ${bold('EJEMPLOS')}
       `FALLO — ${day} gastó ${usd}, por encima del límite --max-day-usd de ${max}. Un total dentro de presupuesto puede esconder un solo día desbocado, que es justo lo que vigila esta puerta.`,
     maxDayNoClock: () =>
       'FALLO — se pidió --max-day-usd y ningún registro de este fichero lleva marca de tiempo, así que no hay días que juzgar. Eso no es un aprobado: una factura que nadie pudo medir por días no es una factura que se mantuvo bajo un presupuesto diario. Añade "ts" al registro y la puerta se arma.',
+    maxSessionOk: (worst, max, sessions) =>
+      `Ninguna conversación por encima del presupuesto: la más cara de ${sessions} costó ${worst}, contra --max-session-usd ${max}. Una conversación que empezó antes de este registro solo cuenta los turnos grabados aquí, así que esto es un suelo.`,
+    maxSessionFailed: (worst, max, sessions) =>
+      `FALLO — la más cara de ${sessions} conversaciones costó ${worst}, por encima del límite --max-session-usd de ${max}. El presupuesto del mes y el del día aprueban mientras una conversación en bucle se come esto; la cifra por conversación es la que lo caza.`,
+    maxSessionNoSessions: () =>
+      'FALLO — se pidió --max-session-usd y ningún registro lleva sesión, así que no hay conversaciones que juzgar. Eso no es un aprobado. Añade "session" (o "conversation_id") al registro y la puerta se arma; Trazum agrupa por ella y nunca la imprime.',
     maxDayUndated: (calls) =>
       `${calls} llamadas no llevan marca de tiempo, así que están en la factura y en ninguno de los días de arriba — el peor día es un suelo por lo que valieran esas llamadas. Un fallo se sostendría igual; este aprobado cubre la parte que se pudo fechar.`,
     maxCacheLossWorstCase: (calls, worst, max) =>
@@ -1176,6 +1186,23 @@ ${bold('EJEMPLOS')}
       `No hay registros de uso en "${directory}". Se buscaron ficheros terminados en ${extensions}. Un directorio sin nada legible es un error, no un informe vacío, que se leería como "no has gastado nada".`,
     sessionCostTail: (ratio) =>
       `El percentil 95 es ${ratio}x la mediana ahí: casi todas las conversaciones son baratas y unas pocas no, y esa es una cola que una cuota puede cazar. Cuando mediana y p95 quedan cerca, la carga es cara sin más y no hay cola que perseguir.`,
+    sessionSpendOnly: (sessions, max) =>
+      `${sessions} ${sessions === '1' ? 'conversación' : 'conversaciones'} en este registro; la más cara costó ${max}. Demasiado pocas por carga para un percentil — un máximo es un hecho con cualquier recuento, y es la cifra que juzga --max-session-usd.`,
+    maxGrowthCoverageLost: (fields, was, now) =>
+      `FALLÓ — este registro dejó de grabar ${fields} (${was} de los registros antes, ${now} ahora), así que la comparación no se puede hacer. Eso no es un aprobado: una factura cuyo crecimiento nadie pudo medir no es una factura que se mantuvo plana, y todo hallazgo que necesitaba ese campo se calló por un motivo que nada tiene que ver con el gasto.`,
+    coverageField: (field) =>
+      ({ label: 'etiqueta', session: 'sesión', ts: 'marca de tiempo', stopReason: 'razón de parada' })[field] ?? field,
+    coverageSilenced: (field) =>
+      ({
+        label: 'Se callaron con él: el gasto por carga, el desglose y unas palancas que describan una decisión y no una mezcla.',
+        session: 'Se callaron con él: el crecimiento de conversación, el coste por conversación, los turnos repetidos, los reintentos por truncado y el ajuste del TTL de caché.',
+        ts: 'Se callaron con él: el periodo, la forma por día y por hora, la deriva de mezcla de modelos y la pregunta del TTL de caché por completo.',
+        stopReason: 'Se callaron con él: las respuestas cortadas en max_tokens y los reintentos facturados después.',
+      })[field] ?? '',
+    coverageDrift: (field, was, now) =>
+      `La cobertura se movió: ${field} estaba en el ${was} de los registros y ahora está en el ${now}.`,
+    coverageDriftWhy: () =>
+      'Un campo que el registro dejó de grabar no es un hallazgo arreglado — todo hallazgo que lo necesitaba se ha callado por un motivo que nada tiene que ver con la factura. Se informa a partir de 20 puntos de movimiento en cualquier dirección; un campo que aparece significa que este informe ve lo que el anterior no podía.',
     againstOverlap: (from, to) =>
       `Estos dos registros cubren ambos ${from} → ${to}, así que algunas de las mismas llamadas están a los dos lados de esta resta y parte del cambio es el mismo dinero contado dos veces. Compara periodos que no se solapen — o acota ambos registros con --since/--until.`,
     windowLine: (since, until) =>

package/src/i18n/types.ts

@@ -730,6 +730,15 @@ export interface CliMessages {
     maxDayFailed(day: string, usd: string, max: string): string;
     maxDayNoClock(): string;
     maxDayUndated(calls: string): string;
+    /**
+     * The per-conversation gate. The single most expensive conversation is
+     * the number a per-conversation policy judges; a log with no sessions
+     * fails, and a conversation that started before the log makes the pass
+     * a floor — said in the pass message. The session key never appears.
+     */
+    maxSessionOk(worst: string, max: string, sessions: string): string;
+    maxSessionFailed(worst: string, max: string, sessions: string): string;
+    maxSessionNoSessions(): string;
     /**
      * The price table behind every dollar in the report, when it is old
      * enough to matter. Unlike a skipped line, staleness does not name its
@@ -760,6 +769,26 @@ export interface CliMessages {
      * money on both sides of the subtraction. Only decidable when both logs
      * carry a clock; unknown stays silent rather than reassuring.
      */
+    /**
+     * What the comparison stopped being able to see. Dollars cannot tell a
+     * fixed finding from a field the log stopped recording; only coverage can,
+     * so the copy names the threshold and states the distinction.
+     */
+    /**
+     * The comparison gate's refusal: the current log stopped recording a field
+     * the previous one carried, so "did not grow" is a claim nobody could
+     * check. "Not measured" is not "did not grow", as everywhere here.
+     */
+    maxGrowthCoverageLost(fields: string, was: string, now: string): string;
+    coverageField(field: string): string;
+    /**
+     * Which findings a collapsed field took with it. Named rather than left as
+     * "some findings": a reader deciding whether to trust this report needs to
+     * know exactly which sections are now silence rather than absence.
+     */
+    coverageSilenced(field: string): string;
+    coverageDrift(field: string, was: string, now: string): string;
+    coverageDriftWhy(): string;
     againstOverlap(from: string, to: string): string;
     /**
      * What one conversation costs — median against p95, never a mean: one
@@ -777,6 +806,13 @@ export interface CliMessages {
     ): string;
     /** Said only when the p95 clears ten times the median — a real tail. */
     sessionCostTail(ratio: string): string;
+    /**
+     * The whole log's conversations when the per-slice percentiles refused:
+     * count and single worst cost, stated because a maximum is a fact at any
+     * count while a percentile over four conversations would be the largest
+     * of four wearing a percentile's name.
+     */
+    sessionSpendOnly(sessions: string, max: string): string;
     /**
      * Per-workload budgets from the config. A budgeted label with no calls in
      * the log is "not measured", never a pass: a workload that did not appear

package/src/index.ts

@@ -20,6 +20,7 @@ import {
   countTokensAnthropic,
   DEFAULT_USAGE,
   detectFromSource,
+  coverageDrift,
   driversBetween,
   estimateTokens,
   evaluate,
@@ -180,6 +181,7 @@ const VALUE_FLAGS = new Set([
   'max-growth-usd',
   'max-cache-loss-usd',
   'max-day-usd',
+  'max-session-usd',
   'csv-out',
   'csv-shape',
   'what-if',
@@ -435,7 +437,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   ],
   check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline'],
   baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
-  profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'label', 'since', 'until'],
+  profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd', 'label', 'since', 'until'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2262,6 +2264,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
       typeof args.flags.get('max-growth-usd') === 'string' ||
       typeof args.flags.get('max-cache-loss-usd') === 'string' ||
       typeof args.flags.get('max-day-usd') === 'string' ||
+      typeof args.flags.get('max-session-usd') === 'string' ||
       config.spend !== undefined;
     if (anyGate) {
       const reasons: string[] = [];
@@ -2318,7 +2321,34 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
     }
     if (typeof args.flags.get('max-growth-usd') === 'string' && againstDelta !== null) {
       const maxGrowth = numberFlag(args, 'max-growth-usd', 0, t);
-      if (againstDelta > maxGrowth) {
+      /**
+       * A comparison that went blind fails before it is judged.
+       *
+       * The dollars can hold flat while the current log stopped recording a
+       * field the previous one carried — and every finding that needed the
+       * field is now silent for a reason that has nothing to do with spend.
+       * A gate passing there would be certifying a comparison it could not
+       * make: "not measured" is not "did not grow", the same refusal
+       * --max-day-usd makes on a clockless log and --max-session-usd on a
+       * sessionless one. Only a collapse fails; a field that appeared means
+       * this side can see more, which is never a reason to refuse.
+       */
+      const blinded = previous !== null
+        ? coverageDrift(previous.fieldCoverage, report.fieldCoverage).filter((d) => d.delta < 0)
+        : [];
+      const worst = blinded[0];
+      if (worst !== undefined) {
+        console.error(
+          c.red(
+            t.profile.maxGrowthCoverageLost(
+              blinded.map((d) => t.profile.coverageField(d.field)).join(', '),
+              pct(worst.was),
+              pct(worst.now),
+            ),
+          ),
+        );
+        process.exitCode = 1;
+      } else if (againstDelta > maxGrowth) {
         console.error(c.red(t.profile.maxGrowthUsdFailed(formatSignedUsd(againstDelta), formatUsd(maxGrowth))));
         process.exitCode = 1;
       }
@@ -2412,6 +2442,38 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
         }
       }
     }
+    /**
+     * The per-conversation gate — the unit an agent product actually blows
+     * up in. A month's budget and a day's budget both pass while one
+     * conversation loops its way through $400; the single most expensive
+     * conversation is the number a per-conversation policy has to judge,
+     * and the log already carries it.
+     *
+     * The refusals it inherits: a log with **no sessions** fails rather
+     * than passes ("not measured" is not "under budget"), and a
+     * conversation that started before this log is counted only for the
+     * turns recorded here — so a pass is a floor, and the pass message says
+     * so. The session key itself is never printed, here or anywhere.
+     */
+    if (typeof args.flags.get('max-session-usd') === 'string' || config.spend?.maxSessionUsd !== undefined) {
+      const maxSession =
+        typeof args.flags.get('max-session-usd') === 'string'
+          ? numberFlag(args, 'max-session-usd', 0, t)
+          : config.spend!.maxSessionUsd!;
+      if (report.sessionSpend === null) {
+        console.error(c.red(t.profile.maxSessionNoSessions()));
+        process.exitCode = 1;
+      } else if (report.sessionSpend.maxUsd > maxSession) {
+        console.error(
+          c.red(t.profile.maxSessionFailed(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))),
+        );
+        process.exitCode = 1;
+      } else {
+        console.error(
+          c.dim(t.profile.maxSessionOk(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))),
+        );
+      }
+    }
   };
 
   /**
@@ -3070,6 +3132,19 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
       );
     }
   }
+  /**
+   * The figure that survives a small log. `sessionCosts` refuses slices too
+   * thin for a percentile, and rightly — but a log of four conversations
+   * still has a most expensive one, and that maximum is a fact at any count.
+   * It is also exactly the number `--max-session-usd` judges, so the report
+   * states it rather than going silent where the gate would speak.
+   */
+  if (report.sessionCosts.length === 0 && report.sessionSpend !== null) {
+    console.log();
+    console.log(
+      `  ${c.dim(wrap(t.profile.sessionSpendOnly(n(report.sessionSpend.sessions), formatUsd(report.sessionSpend.maxUsd)), 74, '  '))}`,
+    );
+  }
 
   /**
    * A total that assumed a cache-write rate is a floor, and says so.
@@ -3596,6 +3671,46 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
           console.log(`  ${d.delta > 0 ? c.yellow(line) : c.dim(line)}`);
         }
       }
+
+      /**
+       * What the comparison stopped being able to see.
+       *
+       * Every figure above is dollars, and dollars cannot tell a finding that
+       * was fixed from a finding whose field the log stopped recording — both
+       * are silence. This is the only section that can, so it is loud: a
+       * collapse in coverage invalidates whichever findings depended on it,
+       * and reading the drop as good news is the specific mistake it exists
+       * to prevent.
+       */
+      const drifts = coverageDrift(previous.fieldCoverage, report.fieldCoverage);
+      if (drifts.length > 0) {
+        console.log();
+        for (const drift of drifts) {
+          const line = t.profile.coverageDrift(
+            t.profile.coverageField(drift.field),
+            pct(drift.was),
+            pct(drift.now),
+          );
+          console.log(
+            drift.delta < 0
+              ? `  ${c.yellow('!')} ${c.bold(wrap(line, 74, '    '))}`
+              : `  ${c.dim(wrap(line, 74, '  '))}`,
+          );
+          /**
+           * Which findings went with it, named. "Some findings are silent" is
+           * not something a reader can act on; knowing that conversation
+           * growth and the cache-TTL fit are now silence rather than absence
+           * tells them exactly which sections of this report to distrust.
+           */
+          if (drift.delta < 0) {
+            const silenced = t.profile.coverageSilenced(drift.field);
+            if (silenced !== '') console.log(`    ${c.dim(wrap(silenced, 72, '    '))}`);
+          }
+        }
+        if (drifts.some((d) => d.delta < 0)) {
+          console.log(`  ${c.dim(wrap(t.profile.coverageDriftWhy(), 74, '    '))}`);
+        }
+      }
     }
   }