@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.
- package/README.md +75 -6
- package/dist/filter.d.ts +2 -0
- package/dist/filter.d.ts.map +1 -0
- package/dist/filter.js +151 -0
- package/dist/filter.js.map +1 -0
- package/dist/gateway-server.d.ts +2 -0
- package/dist/gateway-server.d.ts.map +1 -1
- package/dist/gateway-server.js +49 -9
- package/dist/gateway-server.js.map +1 -1
- package/dist/gateway-spend.d.ts +32 -0
- package/dist/gateway-spend.d.ts.map +1 -0
- package/dist/gateway-spend.js +116 -0
- package/dist/gateway-spend.js.map +1 -0
- package/dist/html.d.ts.map +1 -1
- package/dist/html.js +22 -1
- package/dist/html.js.map +1 -1
- package/dist/i18n/en.d.ts.map +1 -1
- package/dist/i18n/en.js +29 -3
- package/dist/i18n/en.js.map +1 -1
- package/dist/i18n/es.d.ts.map +1 -1
- package/dist/i18n/es.js +29 -3
- package/dist/i18n/es.js.map +1 -1
- package/dist/i18n/types.d.ts +13 -1
- package/dist/i18n/types.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +118 -61
- package/dist/index.js.map +1 -1
- package/dist/markdown.d.ts.map +1 -1
- package/dist/markdown.js +19 -1
- package/dist/markdown.js.map +1 -1
- package/dist/pdf.d.ts.map +1 -1
- package/dist/pdf.js +38 -1
- package/dist/pdf.js.map +1 -1
- package/dist/serve-savings-schema.d.ts +65 -0
- package/dist/serve-savings-schema.d.ts.map +1 -0
- package/dist/serve-savings-schema.js +54 -0
- package/dist/serve-savings-schema.js.map +1 -0
- package/dist/serve-savings.d.ts +55 -0
- package/dist/serve-savings.d.ts.map +1 -0
- package/dist/serve-savings.js +144 -0
- package/dist/serve-savings.js.map +1 -0
- package/dist/serve-schema.d.ts +536 -0
- package/dist/serve-schema.d.ts.map +1 -0
- package/dist/serve-schema.js +143 -0
- package/dist/serve-schema.js.map +1 -0
- package/dist/serve.d.ts.map +1 -1
- package/dist/serve.js +30 -5
- package/dist/serve.js.map +1 -1
- package/package.json +2 -2
- package/src/filter.ts +114 -0
- package/src/gateway-server.ts +46 -10
- package/src/gateway-spend.ts +120 -0
- package/src/html.ts +25 -1
- package/src/i18n/en.ts +31 -4
- package/src/i18n/es.ts +31 -4
- package/src/i18n/types.ts +14 -1
- package/src/index.ts +108 -63
- package/src/markdown.ts +20 -1
- package/src/pdf.ts +36 -1
- package/src/serve-savings-schema.ts +53 -0
- package/src/serve-savings.ts +140 -0
- package/src/serve-schema.ts +147 -0
- 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.
|
|
1362
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
3831
|
-
|
|
3832
|
-
const
|
|
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 [
|
|
3854
|
+
return [month, n(calls), formatUsd(usd), `${bar(share)} ${pct(share)}`];
|
|
3842
3855
|
});
|
|
3843
|
-
if (
|
|
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
|
-
|
|
3847
|
-
calls
|
|
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
|
|
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.
|
|
5310
|
-
*
|
|
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
|
-
//
|
|
7100
|
-
//
|
|
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
|
|
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
|
+
}
|