@trazum/cli 1.28.0 → 1.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.28.0",
+  "version": "1.29.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.29.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,8 @@ ${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.`,
     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,8 @@ ${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.`,
     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
@@ -777,6 +786,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

@@ -180,6 +180,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 +436,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 +2263,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[] = [];
@@ -2412,6 +2414,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 +3104,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.