@trazum/cli 2.5.1 → 2.6.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/README.md +75 -6
- package/dist/filter.d.ts +2 -0
- package/dist/filter.d.ts.map +1 -0
- package/dist/filter.js +187 -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 +45 -3
- package/dist/i18n/en.js.map +1 -1
- package/dist/i18n/es.d.ts.map +1 -1
- package/dist/i18n/es.js +45 -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 +125 -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-import-schema.d.ts +34 -0
- package/dist/serve-import-schema.d.ts.map +1 -0
- package/dist/serve-import-schema.js +31 -0
- package/dist/serve-import-schema.js.map +1 -0
- package/dist/serve-import.d.ts +43 -0
- package/dist/serve-import.d.ts.map +1 -0
- package/dist/serve-import.js +49 -0
- package/dist/serve-import.js.map +1 -0
- 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 +606 -0
- package/dist/serve-schema.d.ts.map +1 -0
- package/dist/serve-schema.js +151 -0
- package/dist/serve-schema.js.map +1 -0
- package/dist/serve.d.ts.map +1 -1
- package/dist/serve.js +37 -5
- package/dist/serve.js.map +1 -1
- package/dist/task-files.d.ts +9 -0
- package/dist/task-files.d.ts.map +1 -0
- package/dist/task-files.js +136 -0
- package/dist/task-files.js.map +1 -0
- package/dist/task.d.ts +2 -0
- package/dist/task.d.ts.map +1 -0
- package/dist/task.js +137 -0
- package/dist/task.js.map +1 -0
- package/package.json +2 -2
- package/src/filter.ts +150 -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 +47 -4
- package/src/i18n/es.ts +47 -4
- package/src/i18n/types.ts +14 -1
- package/src/index.ts +115 -63
- package/src/markdown.ts +20 -1
- package/src/pdf.ts +36 -1
- package/src/serve-import-schema.ts +31 -0
- package/src/serve-import.ts +57 -0
- package/src/serve-savings-schema.ts +53 -0
- package/src/serve-savings.ts +140 -0
- package/src/serve-schema.ts +155 -0
- package/src/serve.ts +38 -5
- package/src/task-files.ts +114 -0
- package/src/task.ts +119 -0
package/src/filter.ts
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
/** Opt-in stdin log filter. No subprocess execution and no provider access. */
|
|
2
|
+
import { constants } from 'node:fs';
|
|
3
|
+
import { mkdir, lstat, open } from 'node:fs/promises';
|
|
4
|
+
import { createHash } from 'node:crypto';
|
|
5
|
+
import { resolve, join } from 'node:path';
|
|
6
|
+
import { once } from 'node:events';
|
|
7
|
+
import { compactToolOutput, EFFICIENT_OUTPUT_INSTRUCTIONS, type ToolOutputView } from '@trazum/core';
|
|
8
|
+
|
|
9
|
+
const MAX_BYTES = 1024 * 1024;
|
|
10
|
+
const HELP = `Usage:
|
|
11
|
+
trazum filter compact --recovery-dir <private-directory> [--stats]
|
|
12
|
+
trazum filter restore <sha256> --recovery-dir <private-directory>
|
|
13
|
+
trazum filter instructions print optional output guidance
|
|
14
|
+
|
|
15
|
+
Experimental, opt-in display filter. Only consecutive repeated log lines are
|
|
16
|
+
compacted. Errors and unique lines are kept. Not for source files or data pipes.
|
|
17
|
+
Use Bash pipefail to preserve the producing command's failure status.
|
|
18
|
+
Original logs may contain sensitive data: --recovery-dir explicitly opts into local
|
|
19
|
+
retention. Delete that directory when the originals are no longer needed.
|
|
20
|
+
Token counts are estimates, not billing or subscription-quota measurements.
|
|
21
|
+
--stats writes one JSON record to stderr, without log content or recovery paths.
|
|
22
|
+
`;
|
|
23
|
+
|
|
24
|
+
/** Report only the view actually emitted, including recovery-instruction overhead. */
|
|
25
|
+
function reportStats(inputBytes: number, outputBytes: number, view: ToolOutputView | null,
|
|
26
|
+
reason: string, applied = false): void {
|
|
27
|
+
const before = view?.estimatedTokensBefore ?? null;
|
|
28
|
+
const after = applied ? view?.estimatedTokensAfter ?? null : before;
|
|
29
|
+
const saved = before === null || after === null ? null : before - after;
|
|
30
|
+
process.stderr.write(`${JSON.stringify({
|
|
31
|
+
schemaVersion: 1, kind: 'trazum-tool-filter', estimateOnly: true, applied, reason,
|
|
32
|
+
inputBytes, outputBytes, estimatedTokensBefore: before, estimatedTokensAfter: after,
|
|
33
|
+
estimatedTokensSaved: saved,
|
|
34
|
+
estimatedReductionPercent: saved === null || before === null ? null
|
|
35
|
+
: before === 0 ? 0 : Math.round(saved / before * 10000) / 100,
|
|
36
|
+
repeatedLines: applied ? view?.repeatedLines ?? 0 : 0,
|
|
37
|
+
})}\n`);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const digest = (bytes: Buffer) => createHash('sha256').update(bytes).digest('hex');
|
|
41
|
+
const quote = (text: string) => `'${text.replaceAll("'", "'\\''")}'`;
|
|
42
|
+
async function emit(bytes: Buffer | string): Promise<void> {
|
|
43
|
+
if (!process.stdout.write(bytes)) await once(process.stdout, 'drain');
|
|
44
|
+
}
|
|
45
|
+
async function privateDirectory(path: string, create: boolean): Promise<void> {
|
|
46
|
+
if (create) await mkdir(path, { recursive: true, mode: 0o700 });
|
|
47
|
+
const stat = await lstat(path);
|
|
48
|
+
if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('Store must be a real directory.');
|
|
49
|
+
if (process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())) {
|
|
50
|
+
throw new Error('Store must be owned by you and have mode 0700.');
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
async function readOriginal(store: string, key: string): Promise<Buffer> {
|
|
54
|
+
// Opening a FIFO must not block before the regular-file check can reject it.
|
|
55
|
+
const file = await open(join(store, `${key}.log`), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
|
|
56
|
+
try {
|
|
57
|
+
const stat = await file.stat();
|
|
58
|
+
if (!stat.isFile() || stat.size > MAX_BYTES) throw new Error('Invalid recovery file.');
|
|
59
|
+
const bytes = await file.readFile();
|
|
60
|
+
if (bytes.length > MAX_BYTES || digest(bytes) !== key) throw new Error('Recovery integrity check failed.');
|
|
61
|
+
return bytes;
|
|
62
|
+
} finally { await file.close(); }
|
|
63
|
+
}
|
|
64
|
+
async function saveOriginal(store: string, key: string, bytes: Buffer): Promise<void> {
|
|
65
|
+
await privateDirectory(store, true);
|
|
66
|
+
let file;
|
|
67
|
+
try { file = await open(join(store, `${key}.log`), 'wx', 0o600); }
|
|
68
|
+
catch (error) {
|
|
69
|
+
if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
|
|
70
|
+
const existing = await readOriginal(store, key);
|
|
71
|
+
if (!existing.equals(bytes)) throw new Error('Recovery integrity check failed.');
|
|
72
|
+
return;
|
|
73
|
+
}
|
|
74
|
+
try { await file.writeFile(bytes); await file.sync(); }
|
|
75
|
+
finally { await file.close(); }
|
|
76
|
+
}
|
|
77
|
+
async function compact(store: string, stats: boolean): Promise<void> {
|
|
78
|
+
const chunks: Buffer[] = [];
|
|
79
|
+
let size = 0;
|
|
80
|
+
let passthrough = false;
|
|
81
|
+
for await (const value of process.stdin) {
|
|
82
|
+
const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
|
|
83
|
+
size += chunk.length;
|
|
84
|
+
if (passthrough) { await emit(chunk); continue; }
|
|
85
|
+
if (size > MAX_BYTES) {
|
|
86
|
+
passthrough = true;
|
|
87
|
+
for (const buffered of chunks) await emit(buffered);
|
|
88
|
+
chunks.length = 0;
|
|
89
|
+
await emit(chunk);
|
|
90
|
+
} else { chunks.push(chunk); }
|
|
91
|
+
}
|
|
92
|
+
if (passthrough) {
|
|
93
|
+
if (stats) reportStats(size, size, null, 'stream-limit');
|
|
94
|
+
return;
|
|
95
|
+
}
|
|
96
|
+
const bytes = Buffer.concat(chunks);
|
|
97
|
+
const input = bytes.toString('utf8');
|
|
98
|
+
// Invalid UTF-8 must pass byte-for-byte rather than acquire replacement chars.
|
|
99
|
+
if (!Buffer.from(input).equals(bytes)) {
|
|
100
|
+
await emit(bytes);
|
|
101
|
+
if (stats) reportStats(size, size, null, 'invalid-utf8');
|
|
102
|
+
return;
|
|
103
|
+
}
|
|
104
|
+
const key = digest(bytes);
|
|
105
|
+
const view = compactToolOutput(input, `trazum filter restore ${key} --recovery-dir ${quote(store)}`);
|
|
106
|
+
if (!view.applied) {
|
|
107
|
+
await emit(bytes);
|
|
108
|
+
if (stats) reportStats(size, size, view, view.reason);
|
|
109
|
+
return;
|
|
110
|
+
}
|
|
111
|
+
try { await saveOriginal(store, key, bytes); }
|
|
112
|
+
catch {
|
|
113
|
+
// A filter must not swallow a tool's output because local persistence failed.
|
|
114
|
+
if (!stats) process.stderr.write('Trazum: original could not be retained; passing log through unchanged.\n');
|
|
115
|
+
await emit(bytes);
|
|
116
|
+
if (stats) reportStats(size, size, view, 'storage-failed');
|
|
117
|
+
return;
|
|
118
|
+
}
|
|
119
|
+
await emit(view.text);
|
|
120
|
+
if (stats) reportStats(size, Buffer.byteLength(view.text), view, view.reason, true);
|
|
121
|
+
}
|
|
122
|
+
export async function runFilter(args: string[]): Promise<void> {
|
|
123
|
+
let stats = false;
|
|
124
|
+
if (args[0] === 'compact' && args.length === 4) {
|
|
125
|
+
const index = args[1] === '--stats' ? 1 : args[3] === '--stats' ? 3 : -1;
|
|
126
|
+
if (index !== -1) { stats = true; args = args.filter((_, i) => i !== index); }
|
|
127
|
+
}
|
|
128
|
+
if (args.length === 0 || (args.length === 1 && ['--help', '-h'].includes(args[0]!))) {
|
|
129
|
+
await emit(HELP); return;
|
|
130
|
+
}
|
|
131
|
+
if (args.length === 1 && args[0] === 'instructions') {
|
|
132
|
+
await emit(`${EFFICIENT_OUTPUT_INSTRUCTIONS}\n`); return;
|
|
133
|
+
}
|
|
134
|
+
const restoring = args[0] === 'restore';
|
|
135
|
+
const offset = restoring ? 2 : 1;
|
|
136
|
+
if ((!restoring && args[0] !== 'compact') || args.length !== offset + 2 ||
|
|
137
|
+
args[offset] !== '--recovery-dir' || !args[offset + 1] || /[\r\n]/.test(args[offset + 1]!)) {
|
|
138
|
+
throw new Error('Invalid arguments. Run trazum filter --help.');
|
|
139
|
+
}
|
|
140
|
+
const store = resolve(args[offset + 1]!);
|
|
141
|
+
if (restoring) {
|
|
142
|
+
const key = args[1]!;
|
|
143
|
+
if (!/^[a-f0-9]{64}$/.test(key)) throw new Error('Expected a SHA-256 recovery identifier.');
|
|
144
|
+
await privateDirectory(store, false);
|
|
145
|
+
await emit(await readOriginal(store, key));
|
|
146
|
+
} else {
|
|
147
|
+
if (process.stdin.isTTY) throw new Error('Pipe a tool log into stdin; interactive tools are not supported.');
|
|
148
|
+
await compact(store, stats);
|
|
149
|
+
}
|
|
150
|
+
}
|
package/src/gateway-server.ts
CHANGED
|
@@ -35,6 +35,7 @@ import { once } from 'node:events';
|
|
|
35
35
|
import { createServer } from 'node:http';
|
|
36
36
|
import type { IncomingMessage, Server, ServerResponse } from 'node:http';
|
|
37
37
|
import { estimateTokens, gatewayDecision, streamingUsageReader, usageFromResponse } from '@trazum/core';
|
|
38
|
+
import { GatewaySpend } from './gateway-spend.js';
|
|
38
39
|
import type {
|
|
39
40
|
GatewayDecision,
|
|
40
41
|
GatewayPolicy,
|
|
@@ -277,6 +278,8 @@ const HOP_BY_HOP = new Set([
|
|
|
277
278
|
]);
|
|
278
279
|
|
|
279
280
|
export interface GatewayContext {
|
|
281
|
+
/** Add this process's usage and in-flight reservations to startup snapshots. */
|
|
282
|
+
liveBudget?: boolean;
|
|
280
283
|
provider: string;
|
|
281
284
|
catalogue: PricingCatalogue;
|
|
282
285
|
policy: GatewayPolicy;
|
|
@@ -466,8 +469,10 @@ function refusalBody(decision: Extract<GatewayDecision, { kind: 'refuse' }>): st
|
|
|
466
469
|
export function buildGateway(context: GatewayContext): Server {
|
|
467
470
|
const upstream = UPSTREAMS[context.provider];
|
|
468
471
|
const doFetch = context.fetchImpl ?? fetch;
|
|
472
|
+
const spend = context.liveBudget ? new GatewaySpend(context.catalogue) : null;
|
|
469
473
|
|
|
470
474
|
return createServer((request: IncomingMessage, response: ServerResponse) => {
|
|
475
|
+
let ticket: symbol | undefined;
|
|
471
476
|
void (async () => {
|
|
472
477
|
if (upstream === undefined) {
|
|
473
478
|
response.writeHead(500, { 'content-type': 'application/json' });
|
|
@@ -560,21 +565,25 @@ export function buildGateway(context: GatewayContext): Server {
|
|
|
560
565
|
return;
|
|
561
566
|
}
|
|
562
567
|
|
|
568
|
+
const call = { provider: context.provider, ...described };
|
|
569
|
+
const baseStanding = context.standing();
|
|
570
|
+
const standing = spend === null ? baseStanding : spend.standing(baseStanding);
|
|
571
|
+
const basePosition = context.position?.({
|
|
572
|
+
...(described.label === null ? {} : { label: described.label }),
|
|
573
|
+
...(described.session === null ? {} : { session: described.session }),
|
|
574
|
+
});
|
|
563
575
|
const decision = gatewayDecision(
|
|
564
|
-
|
|
565
|
-
|
|
576
|
+
call,
|
|
577
|
+
standing,
|
|
566
578
|
{
|
|
567
579
|
catalogue: context.catalogue,
|
|
568
580
|
policy: context.policy,
|
|
569
581
|
...(context.limits === undefined ? {} : { limits: context.limits }),
|
|
570
582
|
...(context.waivers === undefined ? {} : { waivers: context.waivers }),
|
|
571
|
-
...(
|
|
583
|
+
...(basePosition === undefined
|
|
572
584
|
? {}
|
|
573
585
|
: {
|
|
574
|
-
position:
|
|
575
|
-
...(described.label === null ? {} : { label: described.label }),
|
|
576
|
-
...(described.session === null ? {} : { session: described.session }),
|
|
577
|
-
}),
|
|
586
|
+
position: spend === null ? basePosition : spend.position(basePosition, call),
|
|
578
587
|
}),
|
|
579
588
|
},
|
|
580
589
|
);
|
|
@@ -595,6 +604,16 @@ export function buildGateway(context: GatewayContext): Server {
|
|
|
595
604
|
return;
|
|
596
605
|
}
|
|
597
606
|
|
|
607
|
+
if (spend !== null) {
|
|
608
|
+
const admission = spend.reserve(call, decision, standing, context.policy.onCannotTell === 'fail-closed');
|
|
609
|
+
if (admission.refusal !== undefined) {
|
|
610
|
+
response.writeHead(402, { 'content-type': 'application/json' });
|
|
611
|
+
response.end(`${JSON.stringify(admission.refusal)}\n`);
|
|
612
|
+
return;
|
|
613
|
+
}
|
|
614
|
+
ticket = admission.ticket;
|
|
615
|
+
}
|
|
616
|
+
|
|
598
617
|
const outgoing = new Headers();
|
|
599
618
|
for (const [name, value] of Object.entries(request.headers)) {
|
|
600
619
|
if (HOP_BY_HOP.has(name.toLowerCase()) || value === undefined) continue;
|
|
@@ -624,6 +643,8 @@ export function buildGateway(context: GatewayContext): Server {
|
|
|
624
643
|
body: forwarded,
|
|
625
644
|
});
|
|
626
645
|
} catch (error) {
|
|
646
|
+
// A transport failure does not prove the provider did no billable work.
|
|
647
|
+
if (ticket !== undefined) spend?.settle(ticket, described.model, null);
|
|
627
648
|
/**
|
|
628
649
|
* The upstream is unreachable. This is **not** a budget refusal and
|
|
629
650
|
* must not look like one: the caller needs to tell "your provider is
|
|
@@ -646,6 +667,13 @@ export function buildGateway(context: GatewayContext): Server {
|
|
|
646
667
|
|
|
647
668
|
/** Counts only ever reach `record`; the body is never kept, either way. */
|
|
648
669
|
const recordUsage = (usage: ReturnType<typeof usageFromResponse>): void => {
|
|
670
|
+
if (ticket !== undefined) {
|
|
671
|
+
// Only explicit request/auth/rate-limit rejections establish no generation.
|
|
672
|
+
// Server errors and timeouts may arrive after billable work.
|
|
673
|
+
const rejectedBeforeGeneration = [400, 401, 403, 404, 405, 413, 415, 422, 429].includes(upstreamResponse.status);
|
|
674
|
+
if (rejectedBeforeGeneration && usage === null) spend?.release(ticket);
|
|
675
|
+
else spend?.settle(ticket, decision.kind === 'substitute' ? decision.to.id : described.model, usage);
|
|
676
|
+
}
|
|
649
677
|
if (usage === null) return;
|
|
650
678
|
context.record({
|
|
651
679
|
model: decision.kind === 'substitute' ? decision.to.id : described.model,
|
|
@@ -681,7 +709,7 @@ export function buildGateway(context: GatewayContext): Server {
|
|
|
681
709
|
} catch {
|
|
682
710
|
measured = null;
|
|
683
711
|
}
|
|
684
|
-
const buffered = usageFromResponse(context.provider, measured);
|
|
712
|
+
const buffered = usageFromResponse(context.provider, measured, { requireComplete: context.liveBudget === true });
|
|
685
713
|
/**
|
|
686
714
|
* The buffered path was the silent one.
|
|
687
715
|
*
|
|
@@ -712,7 +740,7 @@ export function buildGateway(context: GatewayContext): Server {
|
|
|
712
740
|
|
|
713
741
|
response.writeHead(upstreamResponse.status, back);
|
|
714
742
|
|
|
715
|
-
const reader = streamingUsageReader(context.provider);
|
|
743
|
+
const reader = streamingUsageReader(context.provider, { requireComplete: context.liveBudget === true });
|
|
716
744
|
const decoder = new TextDecoder();
|
|
717
745
|
try {
|
|
718
746
|
for await (const chunk of upstreamResponse.body as AsyncIterable<Uint8Array>) {
|
|
@@ -725,6 +753,7 @@ export function buildGateway(context: GatewayContext): Server {
|
|
|
725
753
|
}
|
|
726
754
|
reader.push(decoder.decode());
|
|
727
755
|
} catch (error) {
|
|
756
|
+
if (ticket !== undefined) spend?.settle(ticket, described.model, null);
|
|
728
757
|
/**
|
|
729
758
|
* The stream broke partway. The head is already sent, so there is no
|
|
730
759
|
* status left to change and no refusal to render — destroying the
|
|
@@ -756,7 +785,14 @@ export function buildGateway(context: GatewayContext): Server {
|
|
|
756
785
|
}
|
|
757
786
|
recordUsage(streamed);
|
|
758
787
|
response.end();
|
|
759
|
-
})()
|
|
788
|
+
})().catch(() => {
|
|
789
|
+
if (ticket !== undefined) spend?.settle(ticket, 'unknown', null);
|
|
790
|
+
if (response.headersSent) response.destroy();
|
|
791
|
+
else {
|
|
792
|
+
response.writeHead(502, { 'content-type': 'application/json' });
|
|
793
|
+
response.end(`${JSON.stringify({ error: { type: 'trazum_gateway_error', message: 'The gateway could not complete this call.' } })}\n`);
|
|
794
|
+
}
|
|
795
|
+
}).finally(() => { if (ticket !== undefined) spend?.release(ticket); });
|
|
760
796
|
});
|
|
761
797
|
}
|
|
762
798
|
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { indexUsage, parseUsageLine, usageFromResponse } from '@trazum/core';
|
|
2
|
+
import type { GatewayCall, GatewayDecision, GatewayStanding, MeasuredPosition, PricingCatalogue } from '@trazum/core';
|
|
3
|
+
|
|
4
|
+
type GatewayUsage = NonNullable<ReturnType<typeof usageFromResponse>>;
|
|
5
|
+
|
|
6
|
+
type Admitted = Exclude<GatewayDecision, { kind: 'refuse' }>;
|
|
7
|
+
const DAY_MS = 86_400_000;
|
|
8
|
+
const empty = (): MeasuredPosition => ({ dayUsd: null, sessionUsd: null, labelUsd: null });
|
|
9
|
+
|
|
10
|
+
/** Process-local additions to a startup snapshot. Reservations are never measured spend. */
|
|
11
|
+
export class GatewaySpend {
|
|
12
|
+
private usd = 0;
|
|
13
|
+
private unknown = false;
|
|
14
|
+
private days = new Map<number, number>();
|
|
15
|
+
private labels = new Map<string, number>();
|
|
16
|
+
private sessions = new Map<string, number>();
|
|
17
|
+
private pending = new Map<symbol, { call: GatewayCall; usd: number | null }>();
|
|
18
|
+
private started = Date.now();
|
|
19
|
+
|
|
20
|
+
constructor(private catalogue: PricingCatalogue) {}
|
|
21
|
+
|
|
22
|
+
standing(base: GatewayStanding | null): GatewayStanding | null {
|
|
23
|
+
// A new month's imported balance is unknown until the operator reloads it.
|
|
24
|
+
const start = new Date(this.started);
|
|
25
|
+
const now = new Date();
|
|
26
|
+
if (this.unknown || start.getUTCMonth() !== now.getUTCMonth() || start.getUTCFullYear() !== now.getUTCFullYear()) return null;
|
|
27
|
+
return base === null ? null : { ...base, consumedUsd: base.consumedUsd + this.usd };
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
position(base: MeasuredPosition, call: GatewayCall): MeasuredPosition {
|
|
31
|
+
if (this.unknown) return empty();
|
|
32
|
+
const day = Math.floor(Date.now() / DAY_MS) * DAY_MS;
|
|
33
|
+
const add = (base: number | null, delta: number): number | null => base === null ? null : base + delta;
|
|
34
|
+
// Do not carry yesterday's spend into today's daily allowance.
|
|
35
|
+
const dayBase = base.dayWindow && base.dayWindow.toMs <= day ? 0 : base.dayUsd;
|
|
36
|
+
return {
|
|
37
|
+
...base,
|
|
38
|
+
dayUsd: add(dayBase, this.days.get(day) ?? 0),
|
|
39
|
+
dayWindow: dayBase === null ? null : { fromMs: day, toMs: day + DAY_MS },
|
|
40
|
+
labelUsd: add(base.labelUsd, call.label === null ? 0 : this.labels.get(call.label) ?? 0),
|
|
41
|
+
sessionUsd: add(base.sessionUsd, call.session === null ? 0 : this.sessions.get(call.session) ?? 0),
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Synchronous check + reservation: no await can admit two calls against the same remainder. */
|
|
46
|
+
reserve(call: GatewayCall, decision: Admitted, standing: GatewayStanding | null, failClosed: boolean):
|
|
47
|
+
{ ticket: symbol; refusal?: never } | { ticket?: never; refusal: Record<string, unknown> } {
|
|
48
|
+
const pending = [...this.pending.values()];
|
|
49
|
+
const unknown = pending.some((entry) => entry.usd === null);
|
|
50
|
+
const estimate = decision.estimatedUsd;
|
|
51
|
+
const unbounded = estimate === null || !Number.isFinite(estimate) || estimate < 0 ||
|
|
52
|
+
call.maxOutputTokens === null || !Number.isFinite(call.maxOutputTokens) || call.maxOutputTokens < 0;
|
|
53
|
+
const sum = (matches: (entry: typeof pending[number]) => boolean): number =>
|
|
54
|
+
pending.filter(matches).reduce((total, entry) => total + (entry.usd ?? 0), 0);
|
|
55
|
+
const reservedUsd = sum(() => true);
|
|
56
|
+
// Configured substitution explicitly permits continued spending past the monthly cap.
|
|
57
|
+
const globalOver = decision.kind !== 'substitute' && standing !== null && estimate !== null &&
|
|
58
|
+
standing.consumedUsd + reservedUsd + estimate > standing.limitUsd;
|
|
59
|
+
const scopeOver = decision.policy.judgements.some((entry) => {
|
|
60
|
+
if (entry.waived !== null || entry.measuredUsd === null || estimate === null) return false;
|
|
61
|
+
const reserved = sum((pending) => entry.scope === 'day' ||
|
|
62
|
+
(entry.scope === 'label' ? pending.call.label === call.label : pending.call.session === call.session));
|
|
63
|
+
return entry.measuredUsd + reserved + estimate > entry.limitUsd;
|
|
64
|
+
});
|
|
65
|
+
if (((unknown || unbounded) && failClosed) || globalOver || scopeOver) {
|
|
66
|
+
return { refusal: {
|
|
67
|
+
schemaVersion: 1,
|
|
68
|
+
error: { type: 'trazum_budget_refusal', message: unbounded
|
|
69
|
+
? 'This call has no bounded cost; provide a valid output-token limit before spending.'
|
|
70
|
+
: unknown
|
|
71
|
+
? 'An in-flight call has no bounded cost; wait for its usage before spending again.'
|
|
72
|
+
: 'In-flight calls have reserved the remaining budget.' },
|
|
73
|
+
reason: unbounded ? 'call-unbounded' : unknown ? 'in-flight-unmeasured' : 'budget-reserved',
|
|
74
|
+
standing, reservedUsd, estimatedUsd: estimate, policy: decision.policy,
|
|
75
|
+
} };
|
|
76
|
+
}
|
|
77
|
+
const ticket = Symbol();
|
|
78
|
+
this.pending.set(ticket, { call, usd: unbounded ? null : estimate });
|
|
79
|
+
return { ticket };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
settle(ticket: symbol, model: string, usage: GatewayUsage | null): void {
|
|
83
|
+
const pending = this.pending.get(ticket);
|
|
84
|
+
if (pending === undefined) return;
|
|
85
|
+
this.pending.delete(ticket);
|
|
86
|
+
const writesKnown = usage !== null && (usage.cacheWriteTokens === 0 ||
|
|
87
|
+
(usage.cacheWrite5mTokens !== undefined && usage.cacheWrite1hTokens !== undefined &&
|
|
88
|
+
usage.cacheWrite5mTokens + usage.cacheWrite1hTokens === usage.cacheWriteTokens));
|
|
89
|
+
if (usage === null || !writesKnown ||
|
|
90
|
+
Object.values(usage).some((value) => !Number.isFinite(value) || value < 0)) {
|
|
91
|
+
// A flat write count has no TTL. Assuming 5m undercharges a 1h write.
|
|
92
|
+
this.unknown = true;
|
|
93
|
+
return;
|
|
94
|
+
}
|
|
95
|
+
const now = Date.now();
|
|
96
|
+
const record = parseUsageLine(JSON.stringify({
|
|
97
|
+
model, ts: new Date(now).toISOString(),
|
|
98
|
+
input_tokens: usage.inputTokens, output_tokens: usage.outputTokens,
|
|
99
|
+
cache_read_input_tokens: usage.cacheReadTokens,
|
|
100
|
+
cache_creation_input_tokens: usage.cacheWriteTokens,
|
|
101
|
+
cache_creation: {
|
|
102
|
+
ephemeral_5m_input_tokens: usage.cacheWrite5mTokens ?? 0,
|
|
103
|
+
ephemeral_1h_input_tokens: usage.cacheWrite1hTokens ?? 0,
|
|
104
|
+
},
|
|
105
|
+
}));
|
|
106
|
+
const index = record === null ? null : indexUsage([record], { catalogue: this.catalogue, on: new Date(now) });
|
|
107
|
+
if (index === null || index.unpriced > 0 || index.dayUsd === null) {
|
|
108
|
+
this.unknown = true;
|
|
109
|
+
return;
|
|
110
|
+
}
|
|
111
|
+
const usd = index.dayUsd;
|
|
112
|
+
this.usd += usd;
|
|
113
|
+
const day = Math.floor(now / DAY_MS) * DAY_MS;
|
|
114
|
+
this.days.set(day, (this.days.get(day) ?? 0) + usd);
|
|
115
|
+
if (pending.call.label !== null) this.labels.set(pending.call.label, (this.labels.get(pending.call.label) ?? 0) + usd);
|
|
116
|
+
if (pending.call.session !== null) this.sessions.set(pending.call.session, (this.sessions.get(pending.call.session) ?? 0) + usd);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
release(ticket: symbol): void { this.pending.delete(ticket); }
|
|
120
|
+
}
|
package/src/html.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { UNLABELLED, formatUsd, sharesOf } from '@trazum/core';
|
|
1
|
+
import { UNLABELLED, formatUsd, sharesOf, spendByMonth } from '@trazum/core';
|
|
2
2
|
import type { PositionDocument, RollupDocument, UsageBreakdown } from '@trazum/core';
|
|
3
3
|
import type { CliMessages } from './i18n/index.js';
|
|
4
4
|
import { tierCeilingCaveat } from './markdown.js';
|
|
@@ -187,6 +187,30 @@ export function renderProfileHtml(input: ProfileMarkdownInput): string {
|
|
|
187
187
|
),
|
|
188
188
|
);
|
|
189
189
|
|
|
190
|
+
/*
|
|
191
|
+
* By month, once the report spans two: a document handed to whoever pays
|
|
192
|
+
* for a year of use answers which month cost what. Every month, oldest
|
|
193
|
+
* first, since a page has room the terminal's twelve rows do not; and the
|
|
194
|
+
* part with no clock said under it, so the rows do not add up short of the
|
|
195
|
+
* total in silence.
|
|
196
|
+
*/
|
|
197
|
+
const { months, undated } = spendByMonth(report);
|
|
198
|
+
if (months.length >= 2) {
|
|
199
|
+
parts.push(`<h2>${esc(t.html.byMonthHeading())}</h2>`);
|
|
200
|
+
const body = months
|
|
201
|
+
.map(({ month, calls, usd }) => {
|
|
202
|
+
const share = report.total.totalUsd > 0 ? pct(usd / report.total.totalUsd) : '—';
|
|
203
|
+
return `<tr><td>${esc(month)}</td><td class="n">${n(calls)}</td><td class="n">${esc(formatUsd(usd))}</td><td class="n">${share}</td></tr>`;
|
|
204
|
+
})
|
|
205
|
+
.join('\n');
|
|
206
|
+
parts.push(
|
|
207
|
+
`<table><thead><tr><th>${esc(t.bill.colMonth())}</th><th class="n">${esc(t.html.colCalls())}</th><th class="n">USD</th><th class="n">%</th></tr></thead><tbody>\n${body}\n</tbody></table>`,
|
|
208
|
+
);
|
|
209
|
+
if (undated.calls > 0) {
|
|
210
|
+
parts.push(`<p class="muted">${esc(t.bill.monthsUndated(undated.calls, formatUsd(undated.usd)))}</p>`);
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
|
|
190
214
|
// The findings, as the sentences the terminal already says — the copy is
|
|
191
215
|
// the product's, not this file's, so the two surfaces cannot drift apart.
|
|
192
216
|
const findings: string[] = [];
|
package/src/i18n/en.ts
CHANGED
|
@@ -63,6 +63,7 @@ ${bold('USAGE')}
|
|
|
63
63
|
trazum bill [<file|dir>...] [--label <name>] [--no-label-from-project] [--receipt|--table] [--stamp] [-o <file>]
|
|
64
64
|
[--since <when>] [--until <when>] [--pdf-out|--html-out|--markdown-out|--csv-out <file>]
|
|
65
65
|
trazum from-claude-code <file|dir> [--label <name>] [-o <file>]
|
|
66
|
+
trazum from-codex <file|dir> [--label <name>] [-o <file>]
|
|
66
67
|
trazum from-otel <file|dir> [--label-from-service] [-o <file>]
|
|
67
68
|
trazum from-litellm <file|dir> [-o <file>]
|
|
68
69
|
trazum from-anthropic <usage.json> [--label <name>] [--label-by-workspace <file>] [-o <file>]
|
|
@@ -87,6 +88,8 @@ ${bold('USAGE')}
|
|
|
87
88
|
trazum owners <log>
|
|
88
89
|
trazum ladder <log>
|
|
89
90
|
trazum feedback
|
|
91
|
+
trazum filter compact|restore|instructions [--recovery-dir <directory>]
|
|
92
|
+
trazum task analyze|policy|apply|revert|compare [--help]
|
|
90
93
|
trazum --version
|
|
91
94
|
|
|
92
95
|
${bold('OPTIONS FOR init')}
|
|
@@ -305,6 +308,15 @@ ${bold('OPTIONS FOR from-otel')}
|
|
|
305
308
|
verdicts read "cannot tell" rather than a guessed one. Non-LLM spans are
|
|
306
309
|
counted and skipped, said on stderr.
|
|
307
310
|
|
|
311
|
+
${bold('OPTIONS FOR from-codex')}
|
|
312
|
+
--label <name> Stamp every record with one label.
|
|
313
|
+
-o, --out <file> Write normalized usage instead of stdout.
|
|
314
|
+
|
|
315
|
+
Read an explicit Codex rollout file or directory, locally. Corroborated
|
|
316
|
+
counters only: replayed snapshots collapse, ambiguous usage is excluded.
|
|
317
|
+
Conversion gaps are reported on stderr. Prices are API equivalents,
|
|
318
|
+
never your subscription invoice. Prompt content is discarded.
|
|
319
|
+
|
|
308
320
|
${bold('OPTIONS FOR from-claude-code')}
|
|
309
321
|
--label <name> Stamp every record with one label.
|
|
310
322
|
--label-from-project Label each record with its transcript's project
|
|
@@ -417,6 +429,25 @@ ${bold('OPTIONS FOR rules')}
|
|
|
417
429
|
"Inert" is always said about the corpus. A rule that finds nothing in these
|
|
418
430
|
files has not been shown to find nothing anywhere.
|
|
419
431
|
|
|
432
|
+
${bold('OPTIONS FOR task')}
|
|
433
|
+
--id <id> --type <type> Identify a task and its comparable task type.
|
|
434
|
+
--criterion <text> Declare the acceptance criterion before a change.
|
|
435
|
+
--claude-code <file> Add an explicit Claude Code task transcript; repeatable.
|
|
436
|
+
--codex <file> Add an explicit Codex task transcript; repeatable.
|
|
437
|
+
--outcome <value> accepted, rejected or unknown (default unknown).
|
|
438
|
+
--assessor <label> Required for a declared accepted or rejected outcome.
|
|
439
|
+
--policy <id> baseline (default) or repeat-review-v1.
|
|
440
|
+
--instructions <file> Existing local instruction file for apply or revert.
|
|
441
|
+
-o, --out <new-file> Create a private report or policy; never overwrite.
|
|
442
|
+
--json Reports and comparisons are already JSON by default.
|
|
443
|
+
Run task --help for analyze, policy, apply, revert and compare syntax.
|
|
444
|
+
Sources total at most 400,000 characters. Task success is never inferred.
|
|
445
|
+
|
|
446
|
+
${bold('OPTIONS FOR filter')}
|
|
447
|
+
--recovery-dir <directory> Private recovery directory; required for compact/restore.
|
|
448
|
+
--stats Compact only: emit net estimated savings as JSON on stderr.
|
|
449
|
+
Run trazum filter --help for the opt-in stdin log-filter workflow.
|
|
450
|
+
|
|
420
451
|
${bold('OPTIONS FOR feedback')}
|
|
421
452
|
(none)
|
|
422
453
|
|
|
@@ -1311,7 +1342,7 @@ ${bold('EXAMPLES')}
|
|
|
1311
1342
|
diff: () => 'Diff',
|
|
1312
1343
|
tokensOnlyHeading: (host) => `What this buys on ${host}`,
|
|
1313
1344
|
tokensOnlyWhy: (host) =>
|
|
1314
|
-
`${host}
|
|
1345
|
+
`${host} identifies the tool, not your payment mode. Tokens are shown by default; invoice savings are unknown.`,
|
|
1315
1346
|
tokensOnlyAsked: () => 'Costs hidden because you asked for tokens only.',
|
|
1316
1347
|
// `tokens` arrives already formatted for the locale, so the singular is
|
|
1317
1348
|
// decided on the string rather than on a number that is no longer here.
|
|
@@ -1892,6 +1923,17 @@ ${bold('EXAMPLES')}
|
|
|
1892
1923
|
nothingToBill: () => 'Nothing in this log could be priced, so the receipt has no lines.',
|
|
1893
1924
|
},
|
|
1894
1925
|
|
|
1926
|
+
fromCodex: {
|
|
1927
|
+
noPath: () => 'from-codex needs an explicit rollout file or directory: trazum from-codex ./sessions',
|
|
1928
|
+
notFound: (path) => `Cannot read ${path}`,
|
|
1929
|
+
noFiles: (path) => `No JSONL rollout files in ${path}`,
|
|
1930
|
+
noUsage: () => 'No attributable Codex usage. Inspect the named gaps; no zero-cost log was written.',
|
|
1931
|
+
summary: (files, records, duplicates) => `${files} Codex file(s), ${records} corroborated usage record(s), ${duplicates} repeated snapshot(s) collapsed.`,
|
|
1932
|
+
gaps: (missingModel, unsupported, unparseable) => `Codex gaps: ${missingModel} without model context, ${unsupported} unsupported or uncorroborated snapshots, ${unparseable} unreadable lines. These are not zero-cost calls.`,
|
|
1933
|
+
caveat: () => 'Codex telemetry is priced at catalogue API rates, not your subscription invoice. Restored totals, counter resets and ambiguous deltas are excluded, not guessed.',
|
|
1934
|
+
written: (file) => `Wrote normalized usage to ${file}`,
|
|
1935
|
+
},
|
|
1936
|
+
|
|
1895
1937
|
fromOtel: {
|
|
1896
1938
|
noPath: () => 'from-otel needs an OTLP file or directory: trazum from-otel spans.json',
|
|
1897
1939
|
notFound: (path) => `${path}: not found`,
|
|
@@ -2056,7 +2098,7 @@ ${bold('EXAMPLES')}
|
|
|
2056
2098
|
pricingLiveHint: (count) =>
|
|
2057
2099
|
`${count} unpriced model id(s) carry a provider prefix, the way OpenRouter and LiteLLM name models, and the bundled catalogue does not carry those. Run again with --pricing-live to price OpenRouter's slugs from its own list.`,
|
|
2058
2100
|
apiEquivalent: () =>
|
|
2059
|
-
'Claude Code transcripts are priced at
|
|
2101
|
+
'Claude Code and Codex transcripts are priced at catalogue API rates. On a subscription you paid the plan, not this API-equivalent estimate; missing telemetry and custom rates can change the result.',
|
|
2060
2102
|
prefixedKnown: (ids) =>
|
|
2061
2103
|
`${ids}: the model after the slash is priced here under its own name. The prefix is not stripped for you, because the same model through a router can bill differently. If those calls went straight to the provider, log the model without the prefix.`,
|
|
2062
2104
|
windowMatchesNothing: (from, to) =>
|
|
@@ -2249,6 +2291,7 @@ ${bold('EXAMPLES')}
|
|
|
2249
2291
|
noSessions: () => 'No record carried a session, so conversation growth and per-conversation costs are not in this report.',
|
|
2250
2292
|
byLabelHeading: () => 'By workload',
|
|
2251
2293
|
byModelHeading: () => 'By model',
|
|
2294
|
+
byMonthHeading: () => 'By month',
|
|
2252
2295
|
findingsHeading: () => 'What would move this bill',
|
|
2253
2296
|
colLabel: () => 'workload',
|
|
2254
2297
|
colModel: () => 'model',
|
|
@@ -2308,8 +2351,8 @@ ${bold('EXAMPLES')}
|
|
|
2308
2351
|
|
|
2309
2352
|
where: {
|
|
2310
2353
|
hostHeading: () => 'Running inside',
|
|
2311
|
-
|
|
2312
|
-
`${host}
|
|
2354
|
+
billingUnknown: (host) =>
|
|
2355
|
+
`${host} identifies the execution host only. Payment mode is unknown; token prices do not establish invoice savings.`,
|
|
2313
2356
|
noTarget: () => 'Pass a source file to see which provider its prompts are sent to.',
|
|
2314
2357
|
sourceHeading: (path) => `Prompts in ${path} go to`,
|
|
2315
2358
|
conflict: () => 'Cannot tell: the file names more than one provider.',
|