@trazum/cli 1.51.1 → 1.52.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trazum/cli",
3
- "version": "1.51.1",
3
+ "version": "1.52.0",
4
4
  "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
5
5
  "license": "MIT",
6
6
  "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
37
37
  "prepublishOnly": "npm run build && npm test"
38
38
  },
39
39
  "dependencies": {
40
- "@trazum/core": "1.51.1"
40
+ "@trazum/core": "1.52.0"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
@@ -31,9 +31,10 @@
31
31
  * aggregates since 1.42 and standing in the path changes nothing about that.
32
32
  */
33
33
 
34
+ import { once } from 'node:events';
34
35
  import { createServer } from 'node:http';
35
36
  import type { IncomingMessage, Server, ServerResponse } from 'node:http';
36
- import { estimateTokens, gatewayDecision, usageFromResponse } from '@trazum/core';
37
+ import { estimateTokens, gatewayDecision, streamingUsageReader, usageFromResponse } from '@trazum/core';
37
38
  import type { GatewayDecision, GatewayPolicy, GatewayStanding, PricingCatalogue } from '@trazum/core';
38
39
 
39
40
  /** Compiled in. See the module note. */
@@ -67,6 +68,9 @@ export const UPSTREAMS: Readonly<Record<string, { origin: string; path: string }
67
68
  * Headers Trazum adds or removes. Everything else the caller sent is forwarded
68
69
  * verbatim, including their credential, which this never reads.
69
70
  */
71
+ /** Why a forwarded call's cost could not be measured. */
72
+ export type UnmeasuredCause = 'stream-broke' | 'no-usage-event';
73
+
70
74
  const HOP_BY_HOP = new Set([
71
75
  'connection',
72
76
  'keep-alive',
@@ -102,6 +106,26 @@ export interface GatewayContext {
102
106
  cacheWriteTokens: number;
103
107
  substituted: boolean;
104
108
  }) => void;
109
+ /**
110
+ * A call that was forwarded and whose cost could not be measured.
111
+ *
112
+ * The money is spent either way — the provider generated what it generated —
113
+ * and the period's total will be lower than the bill by however much these
114
+ * came to. Naming them is the only honest option: a zero would be a
115
+ * measurement, and inventing an estimate would merge the two halves this
116
+ * product spent an arc separating.
117
+ *
118
+ * Two causes, and the second is not a failure at all:
119
+ *
120
+ * - `stream-broke` — the connection died before the event carrying the
121
+ * counts. Rare, and a real error.
122
+ * - `no-usage-event` — the stream simply carried no counts. On OpenAI that is
123
+ * **every streaming call** unless the caller passed `stream_options:
124
+ * {include_usage: true}`, so this is the common case rather than the
125
+ * exception, and an operator who is not told will read a total that is
126
+ * quietly missing most of their traffic.
127
+ */
128
+ unmeasured?: (cause: UnmeasuredCause) => void;
105
129
  /** A line for the operator's terminal. Never given a body, ever. */
106
130
  note: (line: string) => void;
107
131
  /** Injected so the proxy is testable against a stub upstream. */
@@ -300,33 +324,100 @@ export function buildGateway(context: GatewayContext): Server {
300
324
  return;
301
325
  }
302
326
 
303
- const text = await upstreamResponse.text();
327
+ const back: Record<string, string> = {};
328
+ upstreamResponse.headers.forEach((value, name) => {
329
+ if (!HOP_BY_HOP.has(name.toLowerCase())) back[name] = value;
330
+ });
304
331
 
305
- // Measured at the moment of the call, from the provider's own counts —
306
- // the reason this beats a connector, which reports the runaway after it
307
- // ran. Counts only reach `record`; the body is dropped here.
308
- let measured: unknown;
309
- try {
310
- measured = JSON.parse(text);
311
- } catch {
312
- measured = null;
313
- }
314
- const usage = usageFromResponse(context.provider, measured);
315
- if (usage !== null) {
332
+ /** Counts only ever reach `record`; the body is never kept, either way. */
333
+ const recordUsage = (usage: ReturnType<typeof usageFromResponse>): void => {
334
+ if (usage === null) return;
316
335
  context.record({
317
336
  model: decision.kind === 'substitute' ? decision.to.id : described.model,
318
337
  label: described.label,
319
338
  substituted: decision.kind === 'substitute',
320
339
  ...usage,
321
340
  });
341
+ };
342
+
343
+ /**
344
+ * A streamed answer is relayed as it arrives.
345
+ *
346
+ * Until 1.52 this method read `await upstreamResponse.text()` for every
347
+ * response, which for `"stream": true` — nearly all production traffic —
348
+ * held the entire answer and then delivered it at once. Time to first
349
+ * token became the total generation time. This page argues that reading a
350
+ * budget file per request would put Trazum's latency between the caller
351
+ * and their provider; buffering a stream was a far larger version of that
352
+ * in the same file.
353
+ *
354
+ * The provider decides, not the request: a body asking to stream can
355
+ * still come back whole, and `content-type` is what actually arrived.
356
+ */
357
+ const streaming = (upstreamResponse.headers.get('content-type') ?? '').includes(
358
+ 'text/event-stream',
359
+ );
360
+
361
+ if (!streaming || upstreamResponse.body === null) {
362
+ const text = await upstreamResponse.text();
363
+ let measured: unknown;
364
+ try {
365
+ measured = JSON.parse(text);
366
+ } catch {
367
+ measured = null;
368
+ }
369
+ recordUsage(usageFromResponse(context.provider, measured));
370
+ response.writeHead(upstreamResponse.status, back);
371
+ response.end(text);
372
+ return;
322
373
  }
323
374
 
324
- const back: Record<string, string> = {};
325
- upstreamResponse.headers.forEach((value, name) => {
326
- if (!HOP_BY_HOP.has(name.toLowerCase())) back[name] = value;
327
- });
328
375
  response.writeHead(upstreamResponse.status, back);
329
- response.end(text);
376
+
377
+ const reader = streamingUsageReader(context.provider);
378
+ const decoder = new TextDecoder();
379
+ try {
380
+ for await (const chunk of upstreamResponse.body as AsyncIterable<Uint8Array>) {
381
+ // Counted on the way past, then forwarded unchanged. The bytes the
382
+ // caller receives are the bytes the provider sent.
383
+ reader.push(decoder.decode(chunk, { stream: true }));
384
+ if (!response.write(chunk)) {
385
+ await once(response, 'drain');
386
+ }
387
+ }
388
+ reader.push(decoder.decode());
389
+ } catch (error) {
390
+ /**
391
+ * The stream broke partway. The head is already sent, so there is no
392
+ * status left to change and no refusal to render — destroying the
393
+ * socket is the only way to tell the caller the answer is incomplete
394
+ * rather than short.
395
+ *
396
+ * The money is spent and unmeasured: the provider generated whatever it
397
+ * generated, and the counts ride the event this stream never reached.
398
+ * Recorded as a broken stream rather than as the partial counts, which
399
+ * would be a measurement of the part that arrived and read as the cost.
400
+ */
401
+ context.note(
402
+ `stream broke before its usage event: ${error instanceof Error ? error.message : String(error)} — this call is unmeasured`,
403
+ );
404
+ context.unmeasured?.('stream-broke');
405
+ response.destroy();
406
+ return;
407
+ }
408
+
409
+ const streamed = reader.done();
410
+ if (streamed === null) {
411
+ /**
412
+ * The stream ended cleanly and carried no counts. Not an error, and on
413
+ * OpenAI not even unusual — but the call is still unmeasured, and the
414
+ * operator has to hear it from here rather than infer it from a total
415
+ * that looks too small.
416
+ */
417
+ context.unmeasured?.('no-usage-event');
418
+ }
419
+ recordUsage(streamed);
420
+ response.end();
330
421
  })();
331
422
  });
332
423
  }
package/src/i18n/en.ts CHANGED
@@ -175,7 +175,7 @@ ${bold('OPTIONS FOR commitment')}
175
175
 
176
176
  ${bold('OPTIONS FOR report')}
177
177
  --year <yyyy> Required. Which year to assemble.
178
- --json Also emit the record as JSON.
178
+ --json The record as data.
179
179
 
180
180
  Everything comes from the store and the plans you already keep — nothing is
181
181
  computed that cannot be checked against a document that already exists.
@@ -1265,6 +1265,10 @@ ${bold('EXAMPLES')}
1265
1265
  needsPolicy: (policies) =>
1266
1266
  `--on-cannot-tell is required, and there is no default: ${policies}. When the gateway cannot judge a call — no budget, nothing measured, an unpriced model — one of these happens, and only you know which failure your product can survive. fail-open keeps it working and lets the bill run; fail-closed stops the bill and takes it down with it. Picking one for you would be the most consequential decision in your architecture, made silently at install time.`,
1267
1267
  listening: (where, provider) => `Gateway on ${where}, in front of ${provider}`,
1268
+ unmeasured: (cause, sofar) =>
1269
+ cause === 'stream-broke'
1270
+ ? `unmeasured: the stream broke before its usage event — the provider billed this call and this session cannot see it (${sofar} unmeasured so far)`
1271
+ : `unmeasured: the stream carried no usage event — on OpenAI that is every streaming call without stream_options.include_usage, so the total below is short by these (${sofar} unmeasured so far)`,
1268
1272
  pointYourSdk: (where) =>
1269
1273
  `Point your SDK's base URL at ${where} and change nothing else. It speaks the provider's own wire format, so no code changes and no new client.`,
1270
1274
  credential: () =>
@@ -1304,9 +1308,24 @@ ${bold('EXAMPLES')}
1304
1308
  'Pass a file to check — a usage log, or any document Trazum emits. Use "-" to read from stdin.',
1305
1309
  badContract: (given, known) => `"${given}" is not a contract. Known contracts: ${known}.`,
1306
1310
  unrecognised: (path) => `${path} does not match any contract Trazum knows.`,
1307
- heading: (path, contract) => `${path} reads as a ${contract} document`,
1311
+ /**
1312
+ * The article follows the name's **sound**, not its first letter.
1313
+ *
1314
+ * Every contract that existed when this line was written began with a
1315
+ * consonant letter, so a bare `a` was right every time it ran; then
1316
+ * `outcome-report` and `annual-record` became reachable by name and it
1317
+ * started saying "a outcome-report".
1318
+ *
1319
+ * `u` is excluded on purpose and the first attempt got it wrong: a
1320
+ * letter-only rule turned "a usage-log" into "an usage-log", because
1321
+ * `usage` opens on /juː/. Bounded to the closed set of contract names, all
1322
+ * of which begin `a`, `c`, `h`, `o`, `p`, `u` or `v`, and `contract-article`
1323
+ * in the test suite fails if a new one arrives that this rule cannot judge.
1324
+ */
1325
+ heading: (path, contract) =>
1326
+ `${path} reads as ${/^[aeio]/.test(contract) ? 'an' : 'a'} ${contract} document`,
1308
1327
  headingLog: (path, contract, records) =>
1309
- `${path} reads as a ${contract}: ${records} ${records === 1 ? 'record' : 'records'}`,
1328
+ `${path} reads as ${/^[aeio]/.test(contract) ? 'an' : 'a'} ${contract}: ${records} ${records === 1 ? 'record' : 'records'}`,
1310
1329
  conforms: () => 'It conforms. Every required field is present and the right type.',
1311
1330
  problem: (at, kind, detail) => `${at}: ${detail} (${kind})`,
1312
1331
  moreProblems: (count) => `…and ${count} more. Fix these first; they are often the same mistake.`,
package/src/i18n/es.ts CHANGED
@@ -166,7 +166,7 @@ ${bold('OPCIONES DE commitment')}
166
166
 
167
167
  ${bold('OPCIONES DE report')}
168
168
  --year <yyyy> Obligatorio. Qué año montar.
169
- --json Emite también el registro como JSON.
169
+ --json El registro como datos.
170
170
 
171
171
  Todo sale del almacén y de los planes que ya guardas — no se calcula nada
172
172
  que no se pueda comprobar contra un documento que ya existe. Los meses sin
@@ -1302,6 +1302,10 @@ ${bold('EJEMPLOS')}
1302
1302
  needsPolicy: (policies) =>
1303
1303
  `--on-cannot-tell es obligatorio, y no hay valor por defecto: ${policies}. Cuando la pasarela no puede juzgar una llamada — sin presupuesto, sin nada medido, un modelo sin precio — pasa una de las dos, y solo tú sabes qué fallo puede sobrevivir tu producto. fail-open lo mantiene funcionando y deja correr la factura; fail-closed para la factura y se lo lleva por delante. Elegir por ti sería tomar la decisión más consecuente de tu arquitectura, en silencio, al instalar.`,
1304
1304
  listening: (where, provider) => `Pasarela en ${where}, delante de ${provider}`,
1305
+ unmeasured: (cause, sofar) =>
1306
+ cause === 'stream-broke'
1307
+ ? `sin medir: el stream se rompió antes de su evento de uso — el proveedor facturó esta llamada y esta sesión no puede verla (${sofar} sin medir hasta ahora)`
1308
+ : `sin medir: el stream no llevó evento de uso — en OpenAI eso es toda llamada en streaming sin stream_options.include_usage, así que el total de abajo se queda corto (${sofar} sin medir hasta ahora)`,
1305
1309
  pointYourSdk: (where) =>
1306
1310
  `Apunta la URL base de tu SDK a ${where} y no cambies nada más. Habla el formato del propio proveedor, así que no hay cambios de código ni cliente nuevo.`,
1307
1311
  credential: () =>
package/src/i18n/types.ts CHANGED
@@ -379,6 +379,7 @@ export interface CliMessages {
379
379
  badProvider(given: string, known: string): string;
380
380
  needsPolicy(policies: string): string;
381
381
  listening(where: string, provider: string): string;
382
+ unmeasured(cause: 'stream-broke' | 'no-usage-event', sofar: number): string;
382
383
  pointYourSdk(where: string): string;
383
384
  credential(): string;
384
385
  neverSubstitutes(): string;
package/src/index.ts CHANGED
@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
6
6
  import { gunzipSync } from 'node:zlib';
7
7
 
8
8
  import {
9
+ CONTRACT_NAMES,
9
10
  applyRewrites,
10
11
  BASELINE_FILENAME,
11
12
  BASELINE_VERSION,
@@ -1563,16 +1564,15 @@ const FEEDBACK_REPO = 'https://github.com/Davmunrey/Trazum';
1563
1564
  /** Problems listed before the rest are counted. A wall of them helps nobody. */
1564
1565
  const MAX_CONFORM_PROBLEMS = 20;
1565
1566
 
1566
- /** The contracts `--contract` accepts, so a typo is refused with the list. */
1567
- const CONTRACT_NAMES = [
1568
- 'usage-log',
1569
- 'profile',
1570
- 'plan',
1571
- 'verification',
1572
- 'history',
1573
- 'connected',
1574
- 'cost-answer',
1575
- ];
1567
+ /**
1568
+ * The contracts `--contract` accepts, so a typo is refused with the list.
1569
+ *
1570
+ * Imported, never retyped. This was a hand-written copy of the union in
1571
+ * `conform.ts` and it stopped at `cost-answer`: `outcome-report` (1.50.4) and
1572
+ * `annual-record` (1.51.0) had rules, had cross-rules, and were refused by name
1573
+ * with "is not a contract" — the list telling the caller they had made a typo
1574
+ * when the list was the thing that was wrong.
1575
+ */
1576
1576
 
1577
1577
  /** How many source files, and how large each may be. Both reported when they bite. */
1578
1578
  const INIT_MAX_SOURCE_FILES = 400;
@@ -1978,12 +1978,16 @@ async function commandConform(args: Args, t: CliMessages): Promise<void> {
1978
1978
  if (target === undefined) throw new Error(t.conform.noTarget());
1979
1979
 
1980
1980
  const named = stringFlag(args, 'contract');
1981
- if (named !== undefined && !CONTRACT_NAMES.includes(named)) {
1981
+ // Widened for the membership test only: the array is `as const` so the union
1982
+ // is derived from it, and narrowing back is what `isContract` does below.
1983
+ const isContract = (value: string): value is ContractName =>
1984
+ (CONTRACT_NAMES as readonly string[]).includes(value);
1985
+ if (named !== undefined && !isContract(named)) {
1982
1986
  throw new Error(t.conform.badContract(named, CONTRACT_NAMES.join(', ')));
1983
1987
  }
1984
1988
 
1985
1989
  const text = target === '-' ? await readInput('-', t) : await readUsageLog(target, t);
1986
- const report = conform(text, named === undefined ? {} : { contract: named as ContractName });
1990
+ const report = conform(text, named === undefined ? {} : { contract: named });
1987
1991
 
1988
1992
  if (boolFlag(args, 'json')) {
1989
1993
  console.log(JSON.stringify(report, null, 2));
@@ -2174,6 +2178,14 @@ async function commandGateway(
2174
2178
  };
2175
2179
 
2176
2180
  const measured: { calls: number; usd: number } = { calls: 0, usd: 0 };
2181
+ /**
2182
+ * Forwarded calls whose cost this session cannot see.
2183
+ *
2184
+ * Counted separately and never folded into `measured`: the money was spent,
2185
+ * so the two are not interchangeable, and a total that quietly absorbed them
2186
+ * would be the flattering direction.
2187
+ */
2188
+ let unmeasured = 0;
2177
2189
  const server = buildGateway({
2178
2190
  provider,
2179
2191
  catalogue: pricing,
@@ -2196,6 +2208,10 @@ async function commandGateway(
2196
2208
  ),
2197
2209
  );
2198
2210
  },
2211
+ unmeasured: (cause) => {
2212
+ unmeasured += 1;
2213
+ console.error(c.yellow(` ${t.gateway.unmeasured(cause, unmeasured)}`));
2214
+ },
2199
2215
  note: (line) => {
2200
2216
  console.error(c.yellow(` ${line}`));
2201
2217
  },
@@ -3113,6 +3129,21 @@ async function commandReport(
3113
3129
  .sort((a, b) => a.month.localeCompare(b.month));
3114
3130
 
3115
3131
  const record = annualRecord(year, periods);
3132
+
3133
+ /**
3134
+ * `--json` is the document *instead of* the report, not after it.
3135
+ *
3136
+ * It used to print the human report and then append the JSON, and the help
3137
+ * said "Also emit". That made the one command emitting the `annual-record`
3138
+ * contract the one command whose output no machine can read: `| jq` and
3139
+ * `| trazum conform -` both fail on the prose in front. Every other `--json`
3140
+ * in this CLI returns here rather than adding to what was printed.
3141
+ */
3142
+ if (boolFlag(args, 'json')) {
3143
+ console.log(JSON.stringify(record, null, 2));
3144
+ return;
3145
+ }
3146
+
3116
3147
  const n = (value: number): string => value.toLocaleString(t.numberLocale);
3117
3148
 
3118
3149
  console.log();
@@ -3170,10 +3201,6 @@ async function commandReport(
3170
3201
  console.log();
3171
3202
  console.log(` ${c.dim(wrap(t.annual.noNewData(), 74, ' '))}`);
3172
3203
  console.log();
3173
-
3174
- if (boolFlag(args, 'json')) {
3175
- console.log(JSON.stringify(record, null, 2));
3176
- }
3177
3204
  }
3178
3205
 
3179
3206
  function commandModels(t: CliMessages, pricing: PricingCatalogue): void {