@trazum/cli 2.5.1 → 2.5.2

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.
Files changed (63) hide show
  1. package/README.md +75 -6
  2. package/dist/filter.d.ts +2 -0
  3. package/dist/filter.d.ts.map +1 -0
  4. package/dist/filter.js +151 -0
  5. package/dist/filter.js.map +1 -0
  6. package/dist/gateway-server.d.ts +2 -0
  7. package/dist/gateway-server.d.ts.map +1 -1
  8. package/dist/gateway-server.js +49 -9
  9. package/dist/gateway-server.js.map +1 -1
  10. package/dist/gateway-spend.d.ts +32 -0
  11. package/dist/gateway-spend.d.ts.map +1 -0
  12. package/dist/gateway-spend.js +116 -0
  13. package/dist/gateway-spend.js.map +1 -0
  14. package/dist/html.d.ts.map +1 -1
  15. package/dist/html.js +22 -1
  16. package/dist/html.js.map +1 -1
  17. package/dist/i18n/en.d.ts.map +1 -1
  18. package/dist/i18n/en.js +29 -3
  19. package/dist/i18n/en.js.map +1 -1
  20. package/dist/i18n/es.d.ts.map +1 -1
  21. package/dist/i18n/es.js +29 -3
  22. package/dist/i18n/es.js.map +1 -1
  23. package/dist/i18n/types.d.ts +13 -1
  24. package/dist/i18n/types.d.ts.map +1 -1
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js +118 -61
  27. package/dist/index.js.map +1 -1
  28. package/dist/markdown.d.ts.map +1 -1
  29. package/dist/markdown.js +19 -1
  30. package/dist/markdown.js.map +1 -1
  31. package/dist/pdf.d.ts.map +1 -1
  32. package/dist/pdf.js +38 -1
  33. package/dist/pdf.js.map +1 -1
  34. package/dist/serve-savings-schema.d.ts +65 -0
  35. package/dist/serve-savings-schema.d.ts.map +1 -0
  36. package/dist/serve-savings-schema.js +54 -0
  37. package/dist/serve-savings-schema.js.map +1 -0
  38. package/dist/serve-savings.d.ts +55 -0
  39. package/dist/serve-savings.d.ts.map +1 -0
  40. package/dist/serve-savings.js +144 -0
  41. package/dist/serve-savings.js.map +1 -0
  42. package/dist/serve-schema.d.ts +536 -0
  43. package/dist/serve-schema.d.ts.map +1 -0
  44. package/dist/serve-schema.js +143 -0
  45. package/dist/serve-schema.js.map +1 -0
  46. package/dist/serve.d.ts.map +1 -1
  47. package/dist/serve.js +30 -5
  48. package/dist/serve.js.map +1 -1
  49. package/package.json +2 -2
  50. package/src/filter.ts +114 -0
  51. package/src/gateway-server.ts +46 -10
  52. package/src/gateway-spend.ts +120 -0
  53. package/src/html.ts +25 -1
  54. package/src/i18n/en.ts +31 -4
  55. package/src/i18n/es.ts +31 -4
  56. package/src/i18n/types.ts +14 -1
  57. package/src/index.ts +108 -63
  58. package/src/markdown.ts +20 -1
  59. package/src/pdf.ts +36 -1
  60. package/src/serve-savings-schema.ts +53 -0
  61. package/src/serve-savings.ts +140 -0
  62. package/src/serve-schema.ts +147 -0
  63. package/src/serve.ts +31 -5
package/src/index.ts CHANGED
@@ -114,6 +114,8 @@ import {
114
114
  parseUsageLine,
115
115
  plannedCalls,
116
116
  claudeCodeRecords,
117
+ codexRecords,
118
+ looksLikeCodexTranscript,
117
119
  type CwdLabel,
118
120
  type WorkspaceLabel,
119
121
  type ProjectLabel,
@@ -165,6 +167,7 @@ import {
165
167
  RULES,
166
168
  sharedPrefixes,
167
169
  sharesOf,
170
+ spendByMonth,
168
171
  isOffered,
169
172
  SOURCE_EXTENSIONS,
170
173
  suggestRewrites,
@@ -321,6 +324,7 @@ interface Args {
321
324
  }
322
325
 
323
326
  const VALUE_FLAGS = new Set([
327
+ 'recovery-dir',
324
328
  'answers',
325
329
  'label-by-cwd',
326
330
  'label-by-workspace',
@@ -733,6 +737,7 @@ function disabledRules(args: Args, config: TrazumConfig): RuleId[] | undefined {
733
737
  */
734
738
  const GLOBAL_FLAGS = ['help', 'h', 'version', 'v', 'locale', 'json', 'config', 'pricing', 'pricing-live', 'max-input'];
735
739
  const COMMAND_FLAGS: Record<string, string[]> = {
740
+ filter: ['recovery-dir'],
736
741
  optimize: [
737
742
  'level', 'model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch',
738
743
  'disable', 'llm', 'exact-tokens', 'diff', 'reorder', 'out', 'o',
@@ -761,6 +766,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
761
766
  rollup: ['json', 'html-out'],
762
767
  position: ['json', 'html-out', 'pricing', 'pricing-live'],
763
768
  receipt: ['out', 'o', 'stamp', 'pricing', 'pricing-live', 'since', 'until'],
769
+ 'from-codex': ['label', 'out', 'o'],
764
770
  'from-claude-code': ['label', 'label-by-cwd', 'label-from-project', 'out', 'o', 'state'],
765
771
  'from-otel': ['label-from-service', 'out', 'o'],
766
772
  'from-litellm': ['out', 'o'],
@@ -1340,6 +1346,11 @@ function printMoney(
1340
1346
  * a measurable one, and it is the honest answer to "what did I gain" on a plan
1341
1347
  * that costs the same either way.
1342
1348
  */
1349
+ /** A conservative display default, never evidence of a payment arrangement. */
1350
+ function prefersTokenReport(host: HostEnvironment): boolean {
1351
+ return ['claude-code', 'codex', 'cursor'].includes(host.id);
1352
+ }
1353
+
1343
1354
  function printTokensOnly(
1344
1355
  result: OptimizationResult,
1345
1356
  host: HostEnvironment,
@@ -1353,15 +1364,10 @@ function printTokensOnly(
1353
1364
 
1354
1365
  console.log();
1355
1366
  console.log(sectionHeading(t.report.tokensOnlyHeading(host.displayName)));
1356
- // Only claim the host bills by subscription when it does. Forced with the
1357
- // flag on GitHub Actions, the first version said "GitHub Actions bills by
1358
- // subscription", which is simply false.
1359
1367
  console.log(
1360
- ` ${
1361
- host.billing === 'subscription'
1362
- ? t.report.tokensOnlyWhy(host.displayName)
1363
- : t.report.tokensOnlyAsked()
1364
- }`,
1368
+ ` ${prefersTokenReport(host)
1369
+ ? t.report.tokensOnlyWhy(host.displayName)
1370
+ : t.report.tokensOnlyAsked()}`,
1365
1371
  );
1366
1372
  console.log();
1367
1373
  console.log(` ${c.green(t.report.tokensSaved(n(saved)))}`);
@@ -1671,12 +1677,7 @@ async function commandWhere(
1671
1677
  console.log(
1672
1678
  ` ${host.displayName}${host.evidence ? c.dim(` (${host.evidence})`) : ''}`,
1673
1679
  );
1674
- // The reason this is worth printing at all. Inside a flat plan the monthly
1675
- // figure Trazum computes is arithmetic about tokens, not money anybody gets
1676
- // back, and saying so is more useful than saying nothing.
1677
- if (host.billing === 'subscription') {
1678
- console.log(` ${c.yellow(t.where.subscription(host.displayName))}`);
1679
- }
1680
+ console.log(` ${c.dim(t.where.billingUnknown(host.displayName))}`);
1680
1681
 
1681
1682
  const target = args.positional[0];
1682
1683
  if (target === undefined) {
@@ -1856,9 +1857,7 @@ function renderInit(proposal: InitProposal, ctx: InitRenderContext): void {
1856
1857
 
1857
1858
  // 1. Where this is running.
1858
1859
  console.log(` ${t.init.host(ctx.host.displayName)}`);
1859
- if (ctx.host.billing === 'subscription') {
1860
- console.log(` ${c.yellow(t.where.subscription(ctx.host.displayName))}`);
1861
- }
1860
+ console.log(` ${c.dim(t.where.billingUnknown(ctx.host.displayName))}`);
1862
1861
 
1863
1862
  // 2. The prompts.
1864
1863
  console.log(
@@ -3431,6 +3430,7 @@ function printReceiptSummary(document: ReceiptDocument, t: CliMessages): void {
3431
3430
  /** The shapes `bill` can tell apart from a file's own text. */
3432
3431
  type UsageSource =
3433
3432
  | 'claude-code'
3433
+ | 'codex'
3434
3434
  | 'otel'
3435
3435
  | 'litellm'
3436
3436
  | 'helicone'
@@ -3447,6 +3447,7 @@ type UsageSource =
3447
3447
  */
3448
3448
  function usageSourcesOf(text: string): UsageSource[] {
3449
3449
  const claims: UsageSource[] = [];
3450
+ if (looksLikeCodexTranscript(text)) claims.push('codex');
3450
3451
  if (looksLikeClaudeCodeTranscript(text)) claims.push('claude-code');
3451
3452
  if (looksLikeOtel(text)) claims.push('otel');
3452
3453
  if (looksLikeAnthropicUsage(text)) claims.push('anthropic-usage');
@@ -3555,6 +3556,8 @@ async function commandBill(args: Args, pricing: PricingCatalogue, t: CliMessages
3555
3556
  let labelledByProject = 0;
3556
3557
  /* Claude Code transcripts read: their money is an API-rate equivalent. */
3557
3558
  let claudeCodeFiles = 0;
3559
+ let codexFiles = 0;
3560
+ const codexEvidence = { source: 'codex', basis: 'api-equivalent-telemetry', files: 0, duplicates: 0, missingModel: 0, unsupported: 0, unparseable: 0 };
3558
3561
  const lines: string[] = [];
3559
3562
  let sources = 0;
3560
3563
  /*
@@ -3588,6 +3591,19 @@ async function commandBill(args: Args, pricing: PricingCatalogue, t: CliMessages
3588
3591
  let records: unknown[] = [];
3589
3592
  let leftOut = 0;
3590
3593
  switch (shape) {
3594
+ case 'codex': {
3595
+ codexFiles += 1;
3596
+ const c = codexRecords(text, withLabel);
3597
+ codexEvidence.files += 1;
3598
+ codexEvidence.duplicates += c.duplicates;
3599
+ codexEvidence.missingModel += c.missingModel;
3600
+ codexEvidence.unsupported += c.unsupported;
3601
+ codexEvidence.unparseable += c.unparseable;
3602
+ records = c.records;
3603
+ leftOut = c.missingModel + c.unsupported + c.unparseable;
3604
+ if (leftOut > 0) console.error(t.fromCodex.gaps(c.missingModel, c.unsupported, c.unparseable));
3605
+ break;
3606
+ }
3591
3607
  case 'claude-code': {
3592
3608
  claudeCodeFiles += 1;
3593
3609
  const project =
@@ -3676,7 +3692,11 @@ async function commandBill(args: Args, pricing: PricingCatalogue, t: CliMessages
3676
3692
  });
3677
3693
  refuseEmptyPeriod(text, report, period, pricing, t);
3678
3694
  const document = receiptFrom(report, pricing, boolFlag(args, 'stamp') ? { emittedAt: new Date() } : {});
3679
- const json = JSON.stringify(document, null, 2);
3695
+ const billDocument = codexFiles === 0 ? document : {
3696
+ ...document,
3697
+ importEvidence: [{ ...codexEvidence, complete: codexEvidence.missingModel + codexEvidence.unsupported + codexEvidence.unparseable === 0 }],
3698
+ };
3699
+ const json = JSON.stringify(billDocument, null, 2);
3680
3700
 
3681
3701
  /*
3682
3702
  A terminal gets a statement a person can read; a pipe gets the receipt.
@@ -3697,8 +3717,8 @@ async function commandBill(args: Args, pricing: PricingCatalogue, t: CliMessages
3697
3717
  }
3698
3718
  console.error(t.bill.sources(sources, files.length));
3699
3719
  printReceiptSummary(document, t);
3700
- if (statement) printBillStatement(report, labelledByProject > 0, t, period.words, claudeCodeFiles > 0);
3701
- await writeBillSideFiles(args, report, pricing, csvShape, t, period.words, claudeCodeFiles > 0);
3720
+ if (statement) printBillStatement(report, labelledByProject > 0, t, period.words, claudeCodeFiles + codexFiles > 0);
3721
+ await writeBillSideFiles(args, report, pricing, csvShape, t, period.words, claudeCodeFiles + codexFiles > 0);
3702
3722
 
3703
3723
  /*
3704
3724
  A slug with a slash in it is how OpenRouter names a model, and the bundled
@@ -3827,36 +3847,20 @@ function printBillStatement(
3827
3847
  report's own days, oldest first, newest kept when there are many; shown
3828
3848
  only once the bill spans two calendar months, since one month is the total.
3829
3849
  */
3830
- const months = new Map<string, { calls: number; usd: number }>();
3831
- for (const day of report.spendByDay) {
3832
- const month = months.get(day.day.slice(0, 7)) ?? { calls: 0, usd: 0 };
3833
- month.calls += day.calls;
3834
- month.usd += day.usd;
3835
- months.set(day.day.slice(0, 7), month);
3836
- }
3837
- if (months.size >= 2) {
3838
- const ordered = [...months.entries()].sort(([a], [b]) => a.localeCompare(b));
3839
- const shown = ordered.slice(-LIMIT).map(([name, { calls, usd }]) => {
3850
+ const { months, undated } = spendByMonth(report);
3851
+ if (months.length >= 2) {
3852
+ const shown = months.slice(-LIMIT).map(({ month, calls, usd }) => {
3840
3853
  const share = total > 0 ? usd / total : 0;
3841
- return [name, n(calls), formatUsd(usd), `${bar(share)} ${pct(share)}`];
3854
+ return [month, n(calls), formatUsd(usd), `${bar(share)} ${pct(share)}`];
3842
3855
  });
3843
- if (ordered.length > LIMIT) shown.unshift([c.dim(t.bill.earlierMonths(ordered.length - LIMIT)), '', '', '']);
3856
+ if (months.length > LIMIT) shown.unshift([c.dim(t.bill.earlierMonths(months.length - LIMIT)), '', '', '']);
3844
3857
  console.log();
3845
3858
  for (const line of table(columns(t.bill.colMonth()), shown)) console.log(line);
3846
- const dated = ordered.reduce((sum, [, month]) => ({ calls: sum.calls + month.calls, usd: sum.usd + month.usd }), {
3847
- calls: 0,
3848
- usd: 0,
3849
- });
3850
- const undatedCalls = report.total.calls - dated.calls;
3851
- if (undatedCalls > 0) {
3852
- console.log(c.dim(` ${wrap(t.bill.monthsUndated(undatedCalls, formatUsd(total - dated.usd)), 74, ' ')}`));
3853
- }
3854
- const newest = ordered[ordered.length - 1]?.[0];
3855
- if (newest !== undefined) {
3856
- const [year, month] = newest.split('-').map(Number);
3857
- const lastDay = new Date(Date.UTC(year ?? 1970, month ?? 1, 0)).toISOString().slice(0, 10);
3858
- console.log(c.dim(` ${t.bill.monthHint(`${newest}-01`, lastDay)}`));
3859
+ if (undated.calls > 0) {
3860
+ console.log(c.dim(` ${wrap(t.bill.monthsUndated(undated.calls, formatUsd(undated.usd)), 74, ' ')}`));
3859
3861
  }
3862
+ const newest = months[months.length - 1]!;
3863
+ console.log(c.dim(` ${t.bill.monthHint(newest.firstDay, newest.lastDay)}`));
3860
3864
  }
3861
3865
 
3862
3866
  console.log();
@@ -4083,6 +4087,48 @@ function commandOwnrate(args: Args, t: CliMessages): void {
4083
4087
  console.log(JSON.stringify(snippet, null, 2));
4084
4088
  }
4085
4089
 
4090
+ /** Explicit paths only: Codex histories are not discovered from the user's home. */
4091
+ async function commandFromCodex(args: Args, t: CliMessages): Promise<void> {
4092
+ const target = args.positional[0];
4093
+ if (target === undefined) throw new Error(t.fromCodex.noPath());
4094
+ let info;
4095
+ try { info = await stat(target); } catch { throw new Error(t.fromCodex.notFound(target)); }
4096
+ const files = info.isDirectory()
4097
+ ? (await readdir(target, { recursive: true, withFileTypes: true }))
4098
+ .filter((entry) => entry.isFile() && /\.(jsonl|ndjson)$/i.test(entry.name))
4099
+ .map((entry) => join(entry.parentPath, entry.name)).sort()
4100
+ : [target];
4101
+ if (files.length === 0) throw new Error(t.fromCodex.noFiles(target));
4102
+ const label = stringFlag(args, 'label');
4103
+ const lines: string[] = [];
4104
+ let duplicates = 0;
4105
+ let missingModel = 0;
4106
+ let unsupported = 0;
4107
+ let unparseable = 0;
4108
+ for (const file of files) {
4109
+ const text = await readFile(file, 'utf8');
4110
+ if (!looksLikeCodexTranscript(text)) { unsupported++; continue; }
4111
+ const conversion = codexRecords(text, label === undefined ? {} : { label });
4112
+ for (const record of conversion.records) lines.push(JSON.stringify(record));
4113
+ duplicates += conversion.duplicates;
4114
+ missingModel += conversion.missingModel;
4115
+ unsupported += conversion.unsupported;
4116
+ unparseable += conversion.unparseable;
4117
+ }
4118
+ console.error(t.fromCodex.summary(files.length, lines.length, duplicates));
4119
+ if (missingModel + unsupported + unparseable > 0) {
4120
+ console.error(t.fromCodex.gaps(missingModel, unsupported, unparseable));
4121
+ }
4122
+ console.error(t.fromCodex.caveat());
4123
+ if (lines.length === 0) throw new Error(t.fromCodex.noUsage());
4124
+ const out = stringFlag(args, 'out') ?? stringFlag(args, 'o');
4125
+ const text = lines.join('\n') + '\n';
4126
+ if (out !== undefined) {
4127
+ await writeFile(out, text, 'utf8');
4128
+ console.error(t.fromCodex.written(out));
4129
+ } else console.log(text.trimEnd());
4130
+ }
4131
+
4086
4132
  async function commandFromOtel(args: Args, t: CliMessages): Promise<void> {
4087
4133
  const target = args.positional[0];
4088
4134
  if (target === undefined) throw new Error(t.fromOtel.noPath());
@@ -5302,12 +5348,13 @@ async function commandGateway(
5302
5348
  const position = budget.positions[0] ?? null;
5303
5349
 
5304
5350
  /**
5305
- * Read once at start, like `serve`'s.
5351
+ * Read the baseline once at start. The gateway adds its own completed
5352
+ * usage and reserves in-flight estimates in memory via `liveBudget`.
5306
5353
  *
5307
5354
  * A file read in the request path would put Trazum's own latency between a
5308
5355
  * caller and their provider on every call, which is a cost this product
5309
- * would otherwise be reporting on somebody else. The staleness is real, so a
5310
- * refusal carries `asOfMs` and says what it rested on.
5356
+ * would otherwise be reporting on somebody else. External spend is still
5357
+ * stale, so a refusal carries the baseline's `asOfMs`.
5311
5358
  */
5312
5359
  const standing: GatewayStanding | null =
5313
5360
  position === null || position.coverage === 'none'
@@ -5332,6 +5379,7 @@ async function commandGateway(
5332
5379
  */
5333
5380
  let unmeasured = 0;
5334
5381
  const server = buildGateway({
5382
+ liveBudget: true,
5335
5383
  provider,
5336
5384
  catalogue: pricing,
5337
5385
  policy: {
@@ -7096,24 +7144,12 @@ async function commandOptimize(
7096
7144
  return;
7097
7145
  }
7098
7146
 
7099
- // Tokens-only when the host bills by subscription: there is no bill to
7100
- // reduce, so a monthly figure would be arithmetic about tokens dressed as
7101
- // money. Either flag overrides it, because the host says where *Trazum* runs
7102
- // and not where the prompt goes — somebody editing a production prompt inside
7103
- // Cursor wants the dollars, and they should not have to leave the editor to
7104
- // see them.
7147
+ // Agent harnesses default to token context; their identity does not establish
7148
+ // billing. Explicit API-cost requests and usage-log scenarios retain pricing.
7105
7149
  const host = detectHost();
7106
- /**
7107
- * `--from-log` implies `--cost`, and the reasoning is different from the
7108
- * `--calls` case documented below: `--calls` is a typed scenario parameter,
7109
- * but a usage log with billed token counts is *evidence* — proof this
7110
- * prompt's traffic goes to a metered API, whatever the terminal running
7111
- * the command bills like. Withholding the money there would suppress
7112
- * exactly the figures the person measured in order to see.
7113
- */
7114
7150
  const tokensOnly = boolFlag(args, 'cost') || measured !== null
7115
7151
  ? false
7116
- : boolFlag(args, 'tokens-only') || host.billing === 'subscription';
7152
+ : boolFlag(args, 'tokens-only') || prefersTokenReport(host);
7117
7153
  /**
7118
7154
  * Whether they named a scenario while the money was being withheld.
7119
7155
  *
@@ -13471,6 +13507,12 @@ function printRank(
13471
13507
 
13472
13508
  async function main(): Promise<void> {
13473
13509
  const argv = process.argv.slice(2);
13510
+ // The stdin display filter has its own small grammar and no project config.
13511
+ if (argv[0] === 'filter') {
13512
+ const { runFilter } = await import('./filter.js');
13513
+ await runFilter(argv.slice(1));
13514
+ return;
13515
+ }
13474
13516
  let locale = localeFromArgv(argv);
13475
13517
  let t = getCliMessages(locale);
13476
13518
  const args = parseArgs(argv, t);
@@ -13682,6 +13724,9 @@ async function main(): Promise<void> {
13682
13724
  case 'reconcile':
13683
13725
  await commandReconcile(args, t);
13684
13726
  break;
13727
+ case 'from-codex':
13728
+ await commandFromCodex(args, t);
13729
+ break;
13685
13730
  case 'from-otel':
13686
13731
  await commandFromOtel(args, t);
13687
13732
  break;
package/src/markdown.ts CHANGED
@@ -8,7 +8,7 @@ import type {
8
8
  PromptProfile,
9
9
  RuleLevel,
10
10
  } from '@trazum/core';
11
- import { UNLABELLED, formatSignedUsd, formatUsd, getMessages, getModel, sharesOf } from '@trazum/core';
11
+ import { UNLABELLED, formatSignedUsd, formatUsd, getMessages, getModel, sharesOf, spendByMonth } from '@trazum/core';
12
12
  import { dayOf, formatGap, median, spanDays } from './time.js';
13
13
  import type { AgainstDriver, BillLevers, CacheEconomics, ContextPressure, RepriceReport, UsageProfileReport } from '@trazum/core';
14
14
 
@@ -981,6 +981,25 @@ export function renderProfileMarkdown(input: ProfileMarkdownInput): string {
981
981
  lines.push('');
982
982
  }
983
983
 
984
+ // By month, once the report spans two, every month and the undated part
985
+ // said under it — the same rows as the HTML and PDF doors.
986
+ const { months, undated } = spendByMonth(report);
987
+ if (months.length >= 2) {
988
+ lines.push(`#### ${t.html.byMonthHeading()}`);
989
+ lines.push('');
990
+ lines.push(`| ${t.bill.colMonth()} | ${t.html.colCalls()} | USD | % |`);
991
+ lines.push('|---|---:|---:|---:|');
992
+ for (const { month, calls, usd } of months) {
993
+ const share = report.total.totalUsd > 0 ? pct(usd / report.total.totalUsd) : '—';
994
+ lines.push(`| ${month} | ${n(calls)} | ${formatUsd(usd)} | ${share} |`);
995
+ }
996
+ lines.push('');
997
+ if (undated.calls > 0) {
998
+ lines.push(`_${mdText(t.bill.monthsUndated(undated.calls, formatUsd(undated.usd)))}_`);
999
+ lines.push('');
1000
+ }
1001
+ }
1002
+
984
1003
  // The most expensive day against the median day, loud past twice it — the
985
1004
  // same sentence and the same yardstick the terminal prints.
986
1005
  if (report.spendByDay.length >= 2) {
package/src/pdf.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { PdfDocument, UNLABELLED, formatUsd, pdfFit, pdfWrap, sharesOf } from '@trazum/core';
1
+ import { PdfDocument, UNLABELLED, formatUsd, pdfFit, pdfWrap, sharesOf, spendByMonth } from '@trazum/core';
2
2
  import type { PdfColor, PdfFont, UsageBreakdown } from '@trazum/core';
3
3
  import { tierCeilingCaveat } from './markdown.js';
4
4
  import type { ProfileMarkdownInput } from './markdown.js';
@@ -259,6 +259,41 @@ export function renderProfilePdf(input: ProfileMarkdownInput, options: ProfilePd
259
259
  t.html.colModel(),
260
260
  );
261
261
 
262
+ // By month, every month, as in the HTML door: a page has the room.
263
+ const { months, undated } = spendByMonth(report);
264
+ if (months.length >= 2) {
265
+ heading(t.html.byMonthHeading());
266
+ const size = 7.5;
267
+ const rowHeight = 13;
268
+ const figureWidth = 70;
269
+ const columns = [t.html.colCalls(), 'USD', '%'];
270
+ const nameWidth = width - figureWidth * columns.length;
271
+ const right = (column: number): number => MARGIN + nameWidth + figureWidth * (column + 1) - 4;
272
+ const header = (): void => {
273
+ doc.text(MARGIN + 4, y + 9, pdfFit(t.bill.colMonth(), 'bold', size, nameWidth - 8), { font: 'bold', size, color: INK });
274
+ columns.forEach((column, i) => {
275
+ doc.textRight(right(i), y + 9, pdfFit(column, 'bold', size, figureWidth - 6), { font: 'bold', size, color: INK });
276
+ });
277
+ y += rowHeight;
278
+ doc.line(MARGIN, y, MARGIN + width, y, { color: RULE, width: 1.25 });
279
+ y += 2;
280
+ };
281
+ need(rowHeight * 3);
282
+ header();
283
+ months.forEach(({ month, calls, usd }, index) => {
284
+ if (need(rowHeight)) header();
285
+ if (index % 2 === 1) doc.rect(MARGIN, y, width, rowHeight, { fill: ZEBRA });
286
+ const share = report.total.totalUsd > 0 ? pct(usd / report.total.totalUsd) : '—';
287
+ doc.text(MARGIN + 4, y + 9, month, { size, color: INK });
288
+ [n(calls), formatUsd(usd), share].forEach((cell, i) => {
289
+ doc.textRight(right(i), y + 9, pdfFit(cell, 'regular', size, figureWidth - 6), { size, color: INK });
290
+ });
291
+ y += rowHeight;
292
+ });
293
+ y += 6;
294
+ if (undated.calls > 0) paragraph(t.bill.monthsUndated(undated.calls, formatUsd(undated.usd)), 'regular', 9, MUTED);
295
+ }
296
+
262
297
  // The findings, as the sentences the terminal says.
263
298
  const findings: string[] = [];
264
299
  for (const lever of levers.slices.slice(0, 5)) {
@@ -0,0 +1,53 @@
1
+ /** OpenAPI 3.1 schemas for the text-only savings lifecycle. */
2
+ const ref = (name: string) => ({ $ref: `#/components/schemas/${name}` });
3
+ const nullable = (schema: object) => ({ anyOf: [schema, { type: 'null' }] });
4
+ const object = (properties: Record<string, unknown>, required = Object.keys(properties)) => ({
5
+ type: 'object', properties, required, additionalProperties: false,
6
+ });
7
+ const amount = { type: 'number', minimum: 0 };
8
+ const text = { type: 'string' };
9
+ const count = { type: 'integer', minimum: 0 };
10
+ const log = { type: 'string', minLength: 1, maxLength: 1_000_000, description: 'Non-whitespace normalized usage JSONL text, never a path. Whole request is limited to 1,000,000 UTF-8 bytes.' };
11
+ const pair = object({ before: amount, after: amount });
12
+ export const SAVINGS_SCHEMAS = {
13
+ SavingsPlanRequest: object({ log }),
14
+ SavingsVerifyRequest: object({ log, plan: { ...log, description: 'Serialized Trazum PlanDocument JSON text, never a path or response envelope. Subject to defensive nested validation and the shared whole-body byte cap.' } }),
15
+ SavingsEvidence: object({
16
+ basis: text, pricedCalls: count, pricedUsd: amount, unpricedCalls: count,
17
+ unpricedModels: { type: 'array', items: text }, skippedLines: { type: 'array', items: { type: 'integer', minimum: 1 } },
18
+ span: nullable(ref('Window')), pricingLastReviewed: text, pricingOverlay: { type: 'boolean' },
19
+ complete: { type: 'boolean', description: 'No unpriced calls or skipped lines; not proof of a complete invoice, comparable periods or task quality.' },
20
+ }),
21
+ SavingsAssumption: { oneOf: [
22
+ object({ kind: { const: 'model-capability' }, model: text }),
23
+ object({ kind: { enum: ['batch-window', 'retry-pattern-real', 'max-tokens-fits', 'traffic-pattern-holds'] } }),
24
+ ] },
25
+ SavingsAction: object({
26
+ kind: { enum: ['route', 'batch', 'route+batch', 'fix-truncation', 'fix-caching'] }, label: text, model: text,
27
+ savingUsd: nullable(amount), stakeUsd: nullable(amount), assumes: { type: 'array', items: ref('SavingsAssumption') },
28
+ check: nullable(text), detail: object({
29
+ routeTo: object({ id: text, displayName: text }),
30
+ measured: { type: 'object', additionalProperties: amount },
31
+ baseline: object({ calls: amount, usd: amount, inputPerCallTokens: amount, outputPerCallTokens: amount }),
32
+ }, []),
33
+ }),
34
+ SavingsPlan: object({
35
+ schemaVersion: { const: 1 }, span: nullable(ref('Window')), pricingLastReviewed: text,
36
+ actions: { type: 'array', items: ref('SavingsAction') }, projectedSavingUsd: amount, measuredStakeUsd: amount, totalUsd: amount,
37
+ createdAt: text,
38
+ }, ['schemaVersion', 'span', 'pricingLastReviewed', 'actions', 'projectedSavingUsd', 'measuredStakeUsd', 'totalUsd']),
39
+ SavingsVerifiedAction: object({
40
+ action: ref('SavingsAction'), outcome: { enum: ['arrived', 'not-arrived', 'cannot-tell'] },
41
+ reason: { enum: ['workload-vanished', 'fields-stopped', 'tier-not-recorded', null] },
42
+ observed: { type: 'object', additionalProperties: { type: ['number', 'string', 'null'] } },
43
+ attribution: nullable(object({ calls: pair, inputPerCallTokens: pair, outputPerCallTokens: pair }, [])),
44
+ gateFailing: { type: 'boolean' },
45
+ }),
46
+ SavingsVerification: object({
47
+ schemaVersion: { const: 1 }, planCreatedAt: nullable(text), planPricing: text, currentPricing: text,
48
+ pricesChanged: { type: 'boolean' }, actions: { type: 'array', items: ref('SavingsVerifiedAction') },
49
+ arrived: count, notArrived: count, cannotTell: count, gateFailures: count,
50
+ }),
51
+ SavingsPlanAnswer: object({ schemaVersion: { const: 1 }, plan: ref('SavingsPlan'), evidence: ref('SavingsEvidence'), limitations: { type: 'array', items: text } }),
52
+ SavingsVerifyAnswer: object({ schemaVersion: { const: 1 }, verification: ref('SavingsVerification'), evidence: ref('SavingsEvidence'), limitations: { type: 'array', items: text } }),
53
+ };
@@ -0,0 +1,140 @@
1
+ /** Pure HTTP savings handlers. Text only; never paths, provider calls or writes. */
2
+ import { BUNDLED_CATALOGUE, profileUsage, billLevers, buildPlan, parsePlanDocument, verifyPlan } from '@trazum/core';
3
+ import type { PricingCatalogue } from '@trazum/core';
4
+
5
+ export class SavingsInputError extends Error {}
6
+ export interface SavingsPlanPayload { log: string }
7
+ export interface SavingsVerifyPayload extends SavingsPlanPayload { plan: string }
8
+
9
+ export function validateSavingsPayload(value: unknown, verify: false): asserts value is SavingsPlanPayload;
10
+ export function validateSavingsPayload(value: unknown, verify: true): asserts value is SavingsVerifyPayload;
11
+ export function validateSavingsPayload(value: unknown, verify: boolean): asserts value is SavingsPlanPayload | SavingsVerifyPayload;
12
+ export function validateSavingsPayload(value: unknown, verify: boolean): void {
13
+ if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new SavingsInputError('The body must be a JSON object.');
14
+ const payload = value as Record<string, unknown>;
15
+ const fields = verify ? ['log', 'plan'] : ['log'];
16
+ if (Object.keys(payload).some((key) => !fields.includes(key))) throw new SavingsInputError('Unknown properties are not accepted for savings requests.');
17
+ for (const key of fields) {
18
+ if (typeof payload[key] !== 'string' || payload[key].trim() === '') throw new SavingsInputError(`${key} must be non-empty text, not a file path.`);
19
+ }
20
+ }
21
+
22
+ function savingsReport(log: string, catalogue: PricingCatalogue) {
23
+ const report = profileUsage(log, { catalogue });
24
+ if (report.total.calls + report.unpriced.calls === 0) {
25
+ throw new SavingsInputError('log contains no readable usage records; pass normalized JSONL text with model and token counts');
26
+ }
27
+ if (!Number.isFinite(report.total.totalUsd)) throw new SavingsInputError('log totals exceed finite pricing bounds');
28
+ return report;
29
+ }
30
+
31
+ function savingsEvidence(report: ReturnType<typeof profileUsage>, catalogue: PricingCatalogue) {
32
+ return {
33
+ basis: 'Recorded token counts priced with the selected catalogue; not a reconciled provider invoice.',
34
+ pricedCalls: report.total.calls,
35
+ pricedUsd: report.total.totalUsd,
36
+ unpricedCalls: report.unpriced.calls,
37
+ unpricedModels: report.unpricedModels,
38
+ skippedLines: report.skippedLines,
39
+ span: report.span,
40
+ pricingLastReviewed: catalogue.lastReviewed,
41
+ pricingOverlay: catalogue !== BUNDLED_CATALOGUE,
42
+ complete: report.unpriced.calls === 0 && report.skippedLines.length === 0,
43
+ };
44
+ }
45
+
46
+ /** The shared parser accepts older plans. Check the nested fields verification dereferences too. */
47
+ function savingsPlan(text: string) {
48
+ const parsed = parsePlanDocument(text);
49
+ if (!parsed.ok) {
50
+ const detail = parsed.why.kind === 'action-malformed'
51
+ ? ` at action ${parsed.why.index}: ${parsed.why.because}` : '';
52
+ throw new SavingsInputError(`plan is not a valid Trazum plan: ${parsed.why.kind}${detail}`);
53
+ }
54
+ const plan = parsed.plan;
55
+ const finite = (value: unknown): value is number =>
56
+ typeof value === 'number' && Number.isFinite(value) && value >= 0;
57
+ const object = (value: unknown): value is Record<string, unknown> =>
58
+ typeof value === 'object' && value !== null && !Array.isArray(value);
59
+ const keys = (value: object, allowed: readonly string[], field: string) => {
60
+ if (Object.keys(value).some((key) => !allowed.includes(key))) throw new SavingsInputError(`${field} has unknown properties`);
61
+ };
62
+ keys(plan, ['schemaVersion', 'span', 'pricingLastReviewed', 'actions', 'projectedSavingUsd', 'measuredStakeUsd', 'totalUsd', 'createdAt'], 'plan');
63
+ if (typeof plan.pricingLastReviewed !== 'string' || plan.pricingLastReviewed.trim() === '' ||
64
+ !finite(plan.projectedSavingUsd) || !finite(plan.measuredStakeUsd) || !finite(plan.totalUsd)) {
65
+ throw new SavingsInputError('plan needs pricingLastReviewed and finite non-negative projectedSavingUsd, measuredStakeUsd and totalUsd');
66
+ }
67
+ if (plan.span !== null && (!object(plan.span) || !finite(plan.span.fromMs) || !finite(plan.span.toMs) || plan.span.fromMs > plan.span.toMs)) {
68
+ throw new SavingsInputError('plan.span must be null or an ordered fromMs/toMs window');
69
+ }
70
+ if (plan.span !== null) keys(plan.span, ['fromMs', 'toMs'], 'plan.span');
71
+ if (plan.createdAt !== undefined && (typeof plan.createdAt !== 'string' || !Number.isFinite(Date.parse(plan.createdAt)))) {
72
+ throw new SavingsInputError('plan.createdAt must be an ISO date when supplied');
73
+ }
74
+ for (const [index, action] of plan.actions.entries()) {
75
+ const fail = (why: string): never => { throw new SavingsInputError(`plan action ${index}: ${why}`); };
76
+ keys(action, ['kind', 'label', 'model', 'savingUsd', 'stakeUsd', 'assumes', 'check', 'detail'], `plan action ${index}`);
77
+ if (!object(action.detail)) fail('detail must be an object');
78
+ keys(action.detail, ['routeTo', 'measured', 'baseline'], `plan action ${index} detail`);
79
+ if (!Array.isArray(action.assumes)) fail('assumes must be a list');
80
+ for (const assumption of action.assumes) {
81
+ if (!object(assumption) || !['model-capability', 'batch-window', 'retry-pattern-real', 'max-tokens-fits', 'traffic-pattern-holds'].includes(assumption.kind as string)) fail('unknown assumption');
82
+ keys(assumption, assumption.kind === 'model-capability' ? ['kind', 'model'] : ['kind'], `plan action ${index} assumption`);
83
+ if (assumption.kind === 'model-capability' && typeof assumption.model !== 'string') fail('model-capability needs a model');
84
+ }
85
+ if (action.check !== null && typeof action.check !== 'string') fail('check must be text or null');
86
+ if (action.savingUsd !== null && !finite(action.savingUsd)) fail('savingUsd must be a non-negative number or null');
87
+ if (action.stakeUsd !== null && !finite(action.stakeUsd)) fail('stakeUsd must be a non-negative number or null');
88
+ const projected = ['route', 'batch', 'route+batch'].includes(action.kind);
89
+ if (projected ? action.savingUsd === null || action.stakeUsd !== null : action.stakeUsd === null || action.savingUsd !== null) {
90
+ fail('projected savings and measured stakes must remain separate');
91
+ }
92
+ if (action.kind === 'route' || action.kind === 'route+batch') {
93
+ const target = action.detail.routeTo;
94
+ if (!object(target) || typeof target.id !== 'string' || target.id.length === 0 || typeof target.displayName !== 'string') fail('routeTo needs an id and displayName');
95
+ }
96
+ if (action.detail.routeTo !== undefined) {
97
+ const target = action.detail.routeTo;
98
+ if (!object(target) || typeof target.id !== 'string' || typeof target.displayName !== 'string') fail('routeTo must contain text id and displayName');
99
+ keys(target, ['id', 'displayName'], `plan action ${index} routeTo`);
100
+ }
101
+ const baseline = action.detail.baseline;
102
+ if (baseline !== undefined && (!object(baseline) ||
103
+ !(['calls', 'usd', 'inputPerCallTokens', 'outputPerCallTokens'] as const).every((key) => finite(baseline[key])))) fail('baseline needs finite non-negative counts and costs');
104
+ if (baseline !== undefined) keys(baseline, ['calls', 'usd', 'inputPerCallTokens', 'outputPerCallTokens'], `plan action ${index} baseline`);
105
+ const measured = action.detail.measured;
106
+ if (measured !== undefined && (!object(measured) || !Object.values(measured).every(finite))) fail('measured values must be finite non-negative numbers');
107
+ }
108
+ return plan;
109
+ }
110
+
111
+
112
+ export function planSavings(payload: SavingsPlanPayload, catalogue: PricingCatalogue) {
113
+ const report = savingsReport(payload.log, catalogue);
114
+ return {
115
+ schemaVersion: 1 as const,
116
+ plan: buildPlan(report, billLevers(report, { catalogue }), catalogue.lastReviewed),
117
+ evidence: savingsEvidence(report, catalogue),
118
+ limitations: [
119
+ 'Projected savings are not measured savings. Do not add projectedSavingUsd to measuredStakeUsd.',
120
+ 'Model capability, batch latency and other action assumptions require independent validation.',
121
+ 'Missing or unpriced records are excluded from priced totals, not free usage.',
122
+ ],
123
+ };
124
+ }
125
+
126
+ export function verifySavings(payload: SavingsVerifyPayload, catalogue: PricingCatalogue) {
127
+ const plan = savingsPlan(payload.plan);
128
+ const report = savingsReport(payload.log, catalogue);
129
+ return {
130
+ schemaVersion: 1 as const,
131
+ verification: verifyPlan(plan, report, { currentPricingLastReviewed: catalogue.lastReviewed }),
132
+ evidence: savingsEvidence(report, catalogue),
133
+ limitations: [
134
+ 'Arrived describes the observable action, not proof of equal answer quality or realized net savings.',
135
+ 'A route+batch action only verifies routing; batch billing is not observable from token counts.',
136
+ 'Use matching workloads and comparable periods. Missing, skipped and unpriced data limit verification.',
137
+ 'Use the same pricing overlay for both runs; matching review dates do not prove identical custom rates.',
138
+ ],
139
+ };
140
+ }