@trazum/cli 3.0.1 → 3.0.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 +4 -1
- package/assets/trazum-statusline.sh +45 -0
- package/dist/base-cost.d.ts +173 -0
- package/dist/base-cost.d.ts.map +1 -0
- package/dist/base-cost.js +244 -0
- package/dist/base-cost.js.map +1 -0
- package/dist/bill-range.d.ts +118 -0
- package/dist/bill-range.d.ts.map +1 -0
- package/dist/bill-range.js +122 -0
- package/dist/bill-range.js.map +1 -0
- package/dist/command-help.d.ts +17 -0
- package/dist/command-help.d.ts.map +1 -0
- package/dist/command-help.js +69 -0
- package/dist/command-help.js.map +1 -0
- package/dist/filter.d.ts +7 -1
- package/dist/filter.d.ts.map +1 -1
- package/dist/filter.js +10 -18
- package/dist/filter.js.map +1 -1
- package/dist/gateway-metrics.d.ts +83 -0
- package/dist/gateway-metrics.d.ts.map +1 -0
- package/dist/gateway-metrics.js +181 -0
- package/dist/gateway-metrics.js.map +1 -0
- package/dist/gateway-server.d.ts +23 -5
- package/dist/gateway-server.d.ts.map +1 -1
- package/dist/gateway-server.js +26 -1
- package/dist/gateway-server.js.map +1 -1
- package/dist/gateway-spend.d.ts +11 -1
- package/dist/gateway-spend.d.ts.map +1 -1
- package/dist/gateway-spend.js +44 -32
- package/dist/gateway-spend.js.map +1 -1
- package/dist/git.d.ts +70 -0
- package/dist/git.d.ts.map +1 -1
- package/dist/git.js +145 -0
- package/dist/git.js.map +1 -1
- package/dist/i18n/en.d.ts.map +1 -1
- package/dist/i18n/en.js +358 -6
- package/dist/i18n/en.js.map +1 -1
- package/dist/i18n/es.d.ts +0 -1
- package/dist/i18n/es.d.ts.map +1 -1
- package/dist/i18n/es.js +456 -35
- package/dist/i18n/es.js.map +1 -1
- package/dist/i18n/types.d.ts +205 -0
- package/dist/i18n/types.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +942 -59
- package/dist/index.js.map +1 -1
- package/dist/loopback-guard.d.ts +37 -0
- package/dist/loopback-guard.d.ts.map +1 -0
- package/dist/loopback-guard.js +65 -0
- package/dist/loopback-guard.js.map +1 -0
- package/dist/markdown.d.ts +23 -0
- package/dist/markdown.d.ts.map +1 -1
- package/dist/markdown.js +105 -0
- package/dist/markdown.js.map +1 -1
- package/dist/plan-edits.d.ts +63 -0
- package/dist/plan-edits.d.ts.map +1 -0
- package/dist/plan-edits.js +96 -0
- package/dist/plan-edits.js.map +1 -0
- package/dist/proactive.d.ts +17 -2
- package/dist/proactive.d.ts.map +1 -1
- package/dist/proactive.js +16 -9
- package/dist/proactive.js.map +1 -1
- package/dist/receipt-send.d.ts +44 -0
- package/dist/receipt-send.d.ts.map +1 -0
- package/dist/receipt-send.js +71 -0
- package/dist/receipt-send.js.map +1 -0
- package/dist/serve.d.ts +7 -0
- package/dist/serve.d.ts.map +1 -1
- package/dist/serve.js +22 -1
- package/dist/serve.js.map +1 -1
- package/dist/session-guard.d.ts +210 -0
- package/dist/session-guard.d.ts.map +1 -0
- package/dist/session-guard.js +463 -0
- package/dist/session-guard.js.map +1 -0
- package/dist/task.d.ts +7 -1
- package/dist/task.d.ts.map +1 -1
- package/dist/task.js +7 -26
- package/dist/task.js.map +1 -1
- package/dist/waste.d.ts +25 -0
- package/dist/waste.d.ts.map +1 -0
- package/dist/waste.js +39 -0
- package/dist/waste.js.map +1 -0
- package/dist/zone.d.ts +27 -0
- package/dist/zone.d.ts.map +1 -0
- package/dist/zone.js +96 -0
- package/dist/zone.js.map +1 -0
- package/package.json +2 -2
- package/src/base-cost.ts +384 -0
- package/src/bill-range.ts +206 -0
- package/src/command-help.ts +65 -0
- package/src/filter.ts +11 -18
- package/src/gateway-metrics.ts +209 -0
- package/src/gateway-server.ts +43 -6
- package/src/gateway-spend.ts +45 -33
- package/src/git.ts +158 -0
- package/src/i18n/en.ts +424 -6
- package/src/i18n/es.ts +542 -35
- package/src/i18n/types.ts +208 -0
- package/src/index.ts +952 -58
- package/src/loopback-guard.ts +74 -0
- package/src/markdown.ts +117 -0
- package/src/plan-edits.ts +120 -0
- package/src/proactive.ts +22 -13
- package/src/receipt-send.ts +89 -0
- package/src/serve.ts +23 -1
- package/src/session-guard.ts +541 -0
- package/src/task.ts +8 -26
- package/src/waste.ts +42 -0
- package/src/zone.ts +95 -0
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
import { profileUsage } from '@trazum/core';
|
|
2
|
+
import type { PricingCatalogue } from '@trazum/core';
|
|
3
|
+
|
|
4
|
+
import type { CommitTimes } from './git.js';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* `trazum bill --git-range`: what was spent in this repository's sessions
|
|
8
|
+
* between the first and the last commit of a range (#777).
|
|
9
|
+
*
|
|
10
|
+
* It is a narrower claim than "what the change cost", and the narrowing is the
|
|
11
|
+
* point. The transcripts say when each call was made and which session made it.
|
|
12
|
+
* They do not say which commit the work was for, and nothing here asks them to.
|
|
13
|
+
* What is measured is **everything recorded in this repository's project during
|
|
14
|
+
* the span**: a morning spent on something else in the same repository is in it,
|
|
15
|
+
* and work for the change done on another machine is not.
|
|
16
|
+
*
|
|
17
|
+
* **How "this repository's project" is told, without reading a branch or a path
|
|
18
|
+
* out of a transcript.** Claude Code keeps one folder per project and names it
|
|
19
|
+
* by the project's absolute path with every character that is not a letter or a
|
|
20
|
+
* digit written as `-`. That encoding cannot be undone (see `projectLabelFor`
|
|
21
|
+
* in `index.ts`), but it can be *done*: git says where this repository's root
|
|
22
|
+
* is, the same encoding is applied to that path here, and the folder is this
|
|
23
|
+
* repository's when the two names are equal. Nothing is decoded and nothing in
|
|
24
|
+
* a transcript is read for it: the label every record already carries came from
|
|
25
|
+
* the name of the folder the file was found in, and the root comes from git.
|
|
26
|
+
* A session started in a subdirectory, or in a worktree of the repository, sits
|
|
27
|
+
* in a folder of another name and is not matched; that is a miss named in the
|
|
28
|
+
* documentation, not a guess.
|
|
29
|
+
*
|
|
30
|
+
* **Sessions that cross an edge are not added in.** A session is inside when its
|
|
31
|
+
* first and last call both fall in the window, outside when neither does, and
|
|
32
|
+
* straddling when it began before the first commit or went on after the last.
|
|
33
|
+
* The figure is the sessions inside. Each straddling session is named, with the
|
|
34
|
+
* part of it inside the window and the part outside, and none of it is added to
|
|
35
|
+
* the figure, because half a session says nothing about which half the change
|
|
36
|
+
* needed. The reader adds what they judge to belong.
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
/** The span of a range of commits: the earliest time any of them was written to the latest it was committed. */
|
|
40
|
+
export interface RangeWindow {
|
|
41
|
+
fromMs: number;
|
|
42
|
+
toMs: number;
|
|
43
|
+
commits: number;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* The span from the earliest author or commit time to the latest.
|
|
48
|
+
*
|
|
49
|
+
* Both times, because they differ exactly when it matters: a commit rebased
|
|
50
|
+
* onto `main` yesterday was written last week, and the work happened last week.
|
|
51
|
+
* `null` for an empty range, which has no span.
|
|
52
|
+
*/
|
|
53
|
+
export function windowOf(times: readonly CommitTimes[]): RangeWindow | null {
|
|
54
|
+
if (times.length === 0) return null;
|
|
55
|
+
const all = times.flatMap((t) => [t.authorMs, t.committerMs]);
|
|
56
|
+
return { fromMs: Math.min(...all), toMs: Math.max(...all), commits: times.length };
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The name Claude Code gives a project folder for a repository at `root`, less
|
|
61
|
+
* the leading dashes the label shows without (see `projectLabelFor`). It is an
|
|
62
|
+
* encoding of a path that git supplied; it is never decoded back.
|
|
63
|
+
*/
|
|
64
|
+
export function projectLabelOfRoot(root: string): string {
|
|
65
|
+
const encoded = root.replace(/[^A-Za-z0-9]/g, '-');
|
|
66
|
+
const trimmed = encoded.replace(/^-+/, '');
|
|
67
|
+
return trimmed !== '' ? trimmed : encoded;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** One session that began before the window or went on after it, with what each side cost. */
|
|
71
|
+
export interface StraddlingSession {
|
|
72
|
+
session: string;
|
|
73
|
+
firstMs: number;
|
|
74
|
+
lastMs: number;
|
|
75
|
+
insideUsd: number;
|
|
76
|
+
insideCalls: number;
|
|
77
|
+
outsideUsd: number;
|
|
78
|
+
outsideCalls: number;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export interface RangeBill {
|
|
82
|
+
window: RangeWindow;
|
|
83
|
+
/** Records of this project's folder, dated or not: none means nothing was matched at all. */
|
|
84
|
+
projectRecords: number;
|
|
85
|
+
/** Sessions whose every call is inside the window: the figure. */
|
|
86
|
+
inside: { usd: number; calls: number; sessions: number; unpricedCalls: number };
|
|
87
|
+
straddling: StraddlingSession[];
|
|
88
|
+
/** Calls of sessions that were wholly before or after the window, not counted. */
|
|
89
|
+
outsideCalls: number;
|
|
90
|
+
/** What was read and could not be placed in this project or in this window. */
|
|
91
|
+
leftOut: { otherProjects: number; otherSources: number; undated: number };
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
interface Rec {
|
|
95
|
+
line: string;
|
|
96
|
+
ms: number;
|
|
97
|
+
session: string;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
const priced = (lines: readonly string[], catalogue: PricingCatalogue): { usd: number; calls: number; unpriced: number } => {
|
|
101
|
+
if (lines.length === 0) return { usd: 0, calls: 0, unpriced: 0 };
|
|
102
|
+
const report = profileUsage(lines.join('\n'), { catalogue });
|
|
103
|
+
return { usd: report.total.totalUsd, calls: report.total.calls, unpriced: report.unpriced.calls };
|
|
104
|
+
};
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* Splits the records of one project against the window and prices each part.
|
|
108
|
+
*
|
|
109
|
+
* `claudeCodeLines` are the usage-log records of the Claude Code transcripts,
|
|
110
|
+
* each carrying the label of its project folder. A record whose label is not
|
|
111
|
+
* `project` is another project's and is counted out, not read further.
|
|
112
|
+
* `otherSources` is how many records came from anywhere else (Codex, Gemini
|
|
113
|
+
* CLI, a log): they carry no project folder this can match, so they are named
|
|
114
|
+
* as left out and never guessed at.
|
|
115
|
+
*/
|
|
116
|
+
export function billRange(input: {
|
|
117
|
+
claudeCodeLines: readonly string[];
|
|
118
|
+
otherSources: number;
|
|
119
|
+
project: string;
|
|
120
|
+
window: RangeWindow;
|
|
121
|
+
catalogue: PricingCatalogue;
|
|
122
|
+
}): RangeBill {
|
|
123
|
+
const { window, catalogue } = input;
|
|
124
|
+
const leftOut = { otherProjects: 0, otherSources: input.otherSources, undated: 0 };
|
|
125
|
+
|
|
126
|
+
const bySession = new Map<string, Rec[]>();
|
|
127
|
+
let anonymous = 0;
|
|
128
|
+
let projectRecords = 0;
|
|
129
|
+
for (const line of input.claudeCodeLines) {
|
|
130
|
+
let record: { ts?: unknown; session?: unknown; label?: unknown };
|
|
131
|
+
try {
|
|
132
|
+
record = JSON.parse(line) as typeof record;
|
|
133
|
+
} catch {
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
if (record.label !== input.project) {
|
|
137
|
+
leftOut.otherProjects += 1;
|
|
138
|
+
continue;
|
|
139
|
+
}
|
|
140
|
+
projectRecords += 1;
|
|
141
|
+
const ms = typeof record.ts === 'string' ? Date.parse(record.ts) : Number.NaN;
|
|
142
|
+
if (Number.isNaN(ms)) {
|
|
143
|
+
leftOut.undated += 1;
|
|
144
|
+
continue;
|
|
145
|
+
}
|
|
146
|
+
/* A call that names no session is a session of one call: it cannot cross an edge. */
|
|
147
|
+
const session = typeof record.session === 'string' && record.session !== '' ? record.session : `\u0000${anonymous++}`;
|
|
148
|
+
const own = bySession.get(session) ?? [];
|
|
149
|
+
own.push({ line, ms, session });
|
|
150
|
+
bySession.set(session, own);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
const insideLines: string[] = [];
|
|
154
|
+
let insideSessions = 0;
|
|
155
|
+
let outsideCalls = 0;
|
|
156
|
+
const straddling: StraddlingSession[] = [];
|
|
157
|
+
const within = (ms: number): boolean => ms >= window.fromMs && ms <= window.toMs;
|
|
158
|
+
|
|
159
|
+
for (const [session, records] of bySession) {
|
|
160
|
+
const firstMs = Math.min(...records.map((r) => r.ms));
|
|
161
|
+
const lastMs = Math.max(...records.map((r) => r.ms));
|
|
162
|
+
if (within(firstMs) && within(lastMs)) {
|
|
163
|
+
insideSessions += 1;
|
|
164
|
+
for (const r of records) insideLines.push(r.line);
|
|
165
|
+
} else if (lastMs < window.fromMs || firstMs > window.toMs) {
|
|
166
|
+
outsideCalls += records.length;
|
|
167
|
+
} else {
|
|
168
|
+
const inside = priced(records.filter((r) => within(r.ms)).map((r) => r.line), catalogue);
|
|
169
|
+
const outside = priced(records.filter((r) => !within(r.ms)).map((r) => r.line), catalogue);
|
|
170
|
+
straddling.push({
|
|
171
|
+
session,
|
|
172
|
+
firstMs,
|
|
173
|
+
lastMs,
|
|
174
|
+
insideUsd: inside.usd,
|
|
175
|
+
insideCalls: inside.calls + inside.unpriced,
|
|
176
|
+
outsideUsd: outside.usd,
|
|
177
|
+
outsideCalls: outside.calls + outside.unpriced,
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
straddling.sort((a, b) => a.firstMs - b.firstMs || (a.session < b.session ? -1 : 1));
|
|
182
|
+
|
|
183
|
+
const total = priced(insideLines, catalogue);
|
|
184
|
+
return {
|
|
185
|
+
window,
|
|
186
|
+
projectRecords,
|
|
187
|
+
inside: { usd: total.usd, calls: total.calls, sessions: insideSessions, unpricedCalls: total.unpriced },
|
|
188
|
+
straddling,
|
|
189
|
+
outsideCalls,
|
|
190
|
+
leftOut,
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* The recorded figure divided by each delivery count (#825): the arithmetic and
|
|
196
|
+
* nothing else. `null` where the count is zero, so a figure is never divided by
|
|
197
|
+
* nothing and never printed as $0. It is an average over the span: it says
|
|
198
|
+
* nothing about what any one commit, pull request or day was worth or cost.
|
|
199
|
+
*/
|
|
200
|
+
export function perDelivery(
|
|
201
|
+
usd: number,
|
|
202
|
+
delivery: { commits: number; pullRequests: number; days: number },
|
|
203
|
+
): { perCommit: number | null; perPullRequest: number | null; perDay: number | null } {
|
|
204
|
+
const per = (count: number): number | null => (count > 0 ? usd / count : null);
|
|
205
|
+
return { perCommit: per(delivery.commits), perPullRequest: per(delivery.pullRequests), perDay: per(delivery.days) };
|
|
206
|
+
}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The help for one command, cut from the help for all of them (#865).
|
|
3
|
+
*
|
|
4
|
+
* The README promises that `trazum <command> --help` explains that command's
|
|
5
|
+
* flags. It printed the whole help, 1,332 lines, for every command but `task`.
|
|
6
|
+
* The help already carries each command's flags in a section of its own
|
|
7
|
+
* ("OPTIONS FOR bill", "OPCIONES DE bill"), so the answer is cut from it
|
|
8
|
+
* rather than written a second time: one text, in every language, and a
|
|
9
|
+
* section that cannot drift from the full help because it is the full help.
|
|
10
|
+
*
|
|
11
|
+
* What is cut: the command's lines from the usage section (with the lines that
|
|
12
|
+
* continue them), every section whose heading ends in the command's name, and
|
|
13
|
+
* a closing line saying where the rest is. A command that appears in neither
|
|
14
|
+
* gets `undefined`, and the caller prints the whole help as before.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/** A heading starts at column 0; everything under it is indented. */
|
|
18
|
+
const isHeading = (line: string): boolean => line.length > 0 && !/^\s/.test(line);
|
|
19
|
+
|
|
20
|
+
export function commandHelp(rendered: string, plain: string, command: string, more: string): string | undefined {
|
|
21
|
+
const lines = plain.split('\n');
|
|
22
|
+
const shown = rendered.split('\n');
|
|
23
|
+
// Rendering only wraps words in escape codes, so the two have the same lines.
|
|
24
|
+
if (lines.length !== shown.length) return undefined;
|
|
25
|
+
|
|
26
|
+
// A section runs from its heading to the next heading, or to the end.
|
|
27
|
+
const headings = lines.flatMap((line, index) => (isHeading(line) ? [index] : []));
|
|
28
|
+
const sections = headings.map((start, k) => ({ start, end: headings.at(k + 1) ?? lines.length }));
|
|
29
|
+
|
|
30
|
+
const opensWith = (line: string) => line === ` trazum ${command}` || line.startsWith(` trazum ${command} `);
|
|
31
|
+
// The usage section is the one with the most lines that open with `trazum`.
|
|
32
|
+
const usage = sections.reduce<{ start: number; end: number } | undefined>((best, section) => {
|
|
33
|
+
const count = (s: { start: number; end: number }) => lines.slice(s.start + 1, s.end).filter((line) => line.startsWith(' trazum ')).length;
|
|
34
|
+
return best === undefined || count(section) > count(best) ? section : best;
|
|
35
|
+
}, undefined);
|
|
36
|
+
|
|
37
|
+
const out: string[] = [];
|
|
38
|
+
if (usage !== undefined) {
|
|
39
|
+
const picked: string[] = [];
|
|
40
|
+
const shownBody = shown.slice(usage.start + 1, usage.end);
|
|
41
|
+
let taking = false;
|
|
42
|
+
lines.slice(usage.start + 1, usage.end).forEach((line, index) => {
|
|
43
|
+
// A long usage line continues on lines indented past the command: three
|
|
44
|
+
// spaces or more, then text. Said without a regular expression, which a
|
|
45
|
+
// scanner reads as one a visitor's input could make slow.
|
|
46
|
+
if (opensWith(line)) taking = true;
|
|
47
|
+
else if (!(line.startsWith(' ') && line.trim().length > 0)) taking = false;
|
|
48
|
+
if (taking) picked.push(shownBody.at(index) ?? '');
|
|
49
|
+
});
|
|
50
|
+
if (picked.length > 0) out.push(shown.at(usage.start) ?? '', ...picked);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
for (const section of sections) {
|
|
54
|
+
if (section === usage) continue;
|
|
55
|
+
const heading = lines.at(section.start) ?? '';
|
|
56
|
+
if (!(heading.endsWith(` ${command}`) || heading === `trazum ${command}`)) continue;
|
|
57
|
+
const body = shown.slice(section.start, section.end);
|
|
58
|
+
while (body.length > 0 && (body.at(-1) ?? '').trim() === '') body.pop();
|
|
59
|
+
if (out.length > 0) out.push('');
|
|
60
|
+
out.push(...body);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
if (out.length === 0) return undefined;
|
|
64
|
+
return [...out, '', more].join('\n');
|
|
65
|
+
}
|
package/src/filter.ts
CHANGED
|
@@ -5,21 +5,9 @@ import { createHash } from 'node:crypto';
|
|
|
5
5
|
import { resolve, join } from 'node:path';
|
|
6
6
|
import { once } from 'node:events';
|
|
7
7
|
import { compactToolOutput, EFFICIENT_OUTPUT_INSTRUCTIONS, type ToolOutputView } from '@trazum/core';
|
|
8
|
+
import type { CliMessages } from './i18n/types.js';
|
|
8
9
|
|
|
9
10
|
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
11
|
|
|
24
12
|
/** Report only the view actually emitted, including recovery-instruction overhead. */
|
|
25
13
|
function reportStats(inputBytes: number, outputBytes: number, view: ToolOutputView | null,
|
|
@@ -74,7 +62,7 @@ async function saveOriginal(store: string, key: string, bytes: Buffer): Promise<
|
|
|
74
62
|
try { await file.writeFile(bytes); await file.sync(); }
|
|
75
63
|
finally { await file.close(); }
|
|
76
64
|
}
|
|
77
|
-
async function compact(store: string, stats: boolean): Promise<void> {
|
|
65
|
+
async function compact(store: string, stats: boolean, messages: CliMessages['taskFilter']): Promise<void> {
|
|
78
66
|
const chunks: Buffer[] = [];
|
|
79
67
|
let size = 0;
|
|
80
68
|
let passthrough = false;
|
|
@@ -111,7 +99,7 @@ async function compact(store: string, stats: boolean): Promise<void> {
|
|
|
111
99
|
try { await saveOriginal(store, key, bytes); }
|
|
112
100
|
catch {
|
|
113
101
|
// 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
|
|
102
|
+
if (!stats) process.stderr.write(`${messages.say('Trazum: original could not be retained; passing log through unchanged.')}\n`);
|
|
115
103
|
await emit(bytes);
|
|
116
104
|
if (stats) reportStats(size, size, view, 'storage-failed');
|
|
117
105
|
return;
|
|
@@ -119,14 +107,19 @@ async function compact(store: string, stats: boolean): Promise<void> {
|
|
|
119
107
|
await emit(view.text);
|
|
120
108
|
if (stats) reportStats(size, Buffer.byteLength(view.text), view, view.reason, true);
|
|
121
109
|
}
|
|
122
|
-
|
|
110
|
+
/**
|
|
111
|
+
* `trazum filter`. Its help comes from the reader's catalogue; its errors are
|
|
112
|
+
* raised in English and said in the reader's language where `main` reports
|
|
113
|
+
* them (#871).
|
|
114
|
+
*/
|
|
115
|
+
export async function runFilter(args: string[], messages: CliMessages['taskFilter']): Promise<void> {
|
|
123
116
|
let stats = false;
|
|
124
117
|
if (args[0] === 'compact' && args.length === 4) {
|
|
125
118
|
const index = args[1] === '--stats' ? 1 : args[3] === '--stats' ? 3 : -1;
|
|
126
119
|
if (index !== -1) { stats = true; args = args.filter((_, i) => i !== index); }
|
|
127
120
|
}
|
|
128
121
|
if (args.length === 0 || (args.length === 1 && ['--help', '-h'].includes(args[0]!))) {
|
|
129
|
-
await emit(
|
|
122
|
+
await emit(messages.filterHelp); return;
|
|
130
123
|
}
|
|
131
124
|
if (args.length === 1 && args[0] === 'instructions') {
|
|
132
125
|
await emit(`${EFFICIENT_OUTPUT_INSTRUCTIONS}\n`); return;
|
|
@@ -145,6 +138,6 @@ export async function runFilter(args: string[]): Promise<void> {
|
|
|
145
138
|
await emit(await readOriginal(store, key));
|
|
146
139
|
} else {
|
|
147
140
|
if (process.stdin.isTTY) throw new Error('Pipe a tool log into stdin; interactive tools are not supported.');
|
|
148
|
-
await compact(store, stats);
|
|
141
|
+
await compact(store, stats, messages);
|
|
149
142
|
}
|
|
150
143
|
}
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the gateway has counted since it started, for Prometheus to scrape.
|
|
3
|
+
*
|
|
4
|
+
* **A second port, not a path on the first.** The proxy's port answers the
|
|
5
|
+
* paths `UPSTREAMS` names and nothing else, and `route` is the one reader of a
|
|
6
|
+
* caller's URL there. A `/metrics` beside `/v1/messages` would be a second
|
|
7
|
+
* opinion about what that port does. So the counts are served on their own
|
|
8
|
+
* loopback port, given with `--metrics-port`, and that port forwards nothing:
|
|
9
|
+
* it has no upstream, no `fetch` and no credential in reach.
|
|
10
|
+
*
|
|
11
|
+
* **Counts only.** Every value here is a number the gateway already had: the
|
|
12
|
+
* provider's own token counts, a call's cost at the catalogue's list rates, and
|
|
13
|
+
* how many calls were refused, substituted, forwarded free or left unmeasured.
|
|
14
|
+
* The labels are the provider, the model, the caller's own `trazum_label`, a
|
|
15
|
+
* refusal's reason and an unmeasured call's cause. No prompt, no response and
|
|
16
|
+
* no session reach this module: `trazum_session` is used to judge and is never
|
|
17
|
+
* recorded, and it is not recorded here either.
|
|
18
|
+
*
|
|
19
|
+
* **Counters reset when the gateway restarts.** They are this process's, as
|
|
20
|
+
* the live budget is. Prometheus reads a fall in a counter as a reset, and
|
|
21
|
+
* `trazum_gateway_start_time_seconds` says when this process began.
|
|
22
|
+
*
|
|
23
|
+
* **The label set is bounded.** A model name and a `trazum_label` are both the
|
|
24
|
+
* caller's text, so a caller sending a new one on every call would grow the
|
|
25
|
+
* series without limit, in this process and in Prometheus. Past
|
|
26
|
+
* `MAX_SERIES_KEYS` distinct model and label pairs, and as many substitution
|
|
27
|
+
* pairs, a call with a new one is left out of every figure whole and counted in
|
|
28
|
+
* `trazum_gateway_calls_dropped_total` instead, so the totals say they are
|
|
29
|
+
* short rather than look complete.
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
import { createServer } from 'node:http';
|
|
33
|
+
import type { IncomingMessage, Server, ServerResponse } from 'node:http';
|
|
34
|
+
import { prometheusLabelValue } from '@trazum/core';
|
|
35
|
+
import { refuseHost } from './loopback-guard.js';
|
|
36
|
+
import type { GatewayCount, UnmeasuredCause } from './gateway-server.js';
|
|
37
|
+
|
|
38
|
+
/** Distinct model and label pairs kept, and as many substitution pairs, before a call with a new one is left out. */
|
|
39
|
+
export const MAX_SERIES_KEYS = 1000;
|
|
40
|
+
|
|
41
|
+
/** What every cost sample says about itself: the list rates, not an invoice. */
|
|
42
|
+
export const COST_BASIS = 'api-equivalent';
|
|
43
|
+
|
|
44
|
+
const UNMEASURED_CAUSES: readonly UnmeasuredCause[] = ['stream-broke', 'no-usage-event', 'no-usage-in-body'];
|
|
45
|
+
|
|
46
|
+
/** A call the gateway forwarded and measured, as `record` receives it: counts, no text. */
|
|
47
|
+
export interface MeasuredCall {
|
|
48
|
+
model: string;
|
|
49
|
+
label: string | null;
|
|
50
|
+
inputTokens: number;
|
|
51
|
+
outputTokens: number;
|
|
52
|
+
cacheReadTokens: number;
|
|
53
|
+
cacheWriteTokens: number;
|
|
54
|
+
substituted: boolean;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
type Labels = Readonly<Record<string, string>>;
|
|
58
|
+
|
|
59
|
+
/** One counter: a value per label set. The bound is `GatewayMetrics.admit`'s. */
|
|
60
|
+
class Counter {
|
|
61
|
+
private values = new Map<string, { labels: Labels; value: number }>();
|
|
62
|
+
|
|
63
|
+
readonly name: string;
|
|
64
|
+
readonly help: string;
|
|
65
|
+
|
|
66
|
+
constructor(name: string, help: string) {
|
|
67
|
+
this.name = name;
|
|
68
|
+
this.help = help;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
add(labels: Labels, by: number): void {
|
|
72
|
+
const key = JSON.stringify(labels);
|
|
73
|
+
const entry = this.values.get(key);
|
|
74
|
+
if (entry === undefined) this.values.set(key, { labels, value: by });
|
|
75
|
+
else entry.value += by;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
lines(): string[] {
|
|
79
|
+
const out = [`# HELP ${this.name} ${this.help}`, `# TYPE ${this.name} counter`];
|
|
80
|
+
for (const { labels, value } of this.values.values()) out.push(`${this.name}${render(labels)} ${value}`);
|
|
81
|
+
return out;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
const render = (labels: Labels): string => {
|
|
86
|
+
const pairs = Object.entries(labels);
|
|
87
|
+
return pairs.length === 0 ? '' : `{${pairs.map(([key, value]) => `${key}="${prometheusLabelValue(value)}"`).join(',')}}`;
|
|
88
|
+
};
|
|
89
|
+
|
|
90
|
+
export class GatewayMetrics {
|
|
91
|
+
private dropped = 0;
|
|
92
|
+
private readonly seen = new Set<string>();
|
|
93
|
+
private readonly swaps = new Set<string>();
|
|
94
|
+
private readonly calls = new Counter('trazum_gateway_calls_measured_total', 'Calls forwarded whose usage the provider reported.');
|
|
95
|
+
private readonly tokens = new Counter('trazum_gateway_tokens_total', 'Tokens the provider reported, by kind.');
|
|
96
|
+
private readonly cost = new Counter('trazum_gateway_cost_usd_total', 'Cost of measured calls at the catalogue list rates (API-equivalent), in USD.');
|
|
97
|
+
private readonly unpriced = new Counter('trazum_gateway_calls_unpriced_total', 'Measured calls that could not be priced at list rates (a model the catalogue does not carry, or counts it cannot price); in no cost sample.');
|
|
98
|
+
private readonly unmeasuredCalls = new Counter('trazum_gateway_calls_unmeasured_total', 'Calls forwarded whose cost could not be measured, by cause. Spent, and in no other figure.');
|
|
99
|
+
private readonly refused = new Counter('trazum_gateway_calls_refused_total', 'Calls answered 402 and not forwarded, by reason.');
|
|
100
|
+
private readonly substituted = new Counter('trazum_gateway_calls_substituted_total', 'Calls forwarded with the model the config substitutes.');
|
|
101
|
+
private readonly free = new Counter('trazum_gateway_calls_free_total', 'Calls to a path that spends nothing, forwarded without a budget decision.');
|
|
102
|
+
private readonly unreachable = new Counter('trazum_gateway_upstream_unreachable_total', 'Calls the provider could not be reached for, answered 502.');
|
|
103
|
+
|
|
104
|
+
private readonly provider: string;
|
|
105
|
+
private readonly startedMs: number;
|
|
106
|
+
|
|
107
|
+
constructor(provider: string, startedMs: number) {
|
|
108
|
+
this.provider = provider;
|
|
109
|
+
this.startedMs = startedMs;
|
|
110
|
+
// Present at zero: nothing went wrong and nothing was counted are different statements.
|
|
111
|
+
for (const cause of UNMEASURED_CAUSES) this.unmeasuredCalls.add({ trazum_provider: provider, cause }, 0);
|
|
112
|
+
this.unreachable.add({ trazum_provider: provider }, 0);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Whether a call with this key may be counted: a key already held, or room
|
|
117
|
+
* for a new one. A call refused here is counted only as dropped.
|
|
118
|
+
*/
|
|
119
|
+
private admit(keys: Set<string>, key: string): boolean {
|
|
120
|
+
if (keys.has(key)) return true;
|
|
121
|
+
if (keys.size >= MAX_SERIES_KEYS) {
|
|
122
|
+
this.dropped += 1;
|
|
123
|
+
return false;
|
|
124
|
+
}
|
|
125
|
+
keys.add(key);
|
|
126
|
+
return true;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** A measured call, and its cost at list rates, or `null` when the catalogue does not price it. */
|
|
130
|
+
measured(call: MeasuredCall, usd: number | null): void {
|
|
131
|
+
const series = { trazum_provider: this.provider, trazum_model: call.model, trazum_label: call.label ?? '' };
|
|
132
|
+
if (!this.admit(this.seen, JSON.stringify([call.model, call.label]))) return;
|
|
133
|
+
this.calls.add({ ...series, substituted: String(call.substituted) }, 1);
|
|
134
|
+
const kinds: Array<[string, number]> = [
|
|
135
|
+
['input', call.inputTokens],
|
|
136
|
+
['output', call.outputTokens],
|
|
137
|
+
['cache_read', call.cacheReadTokens],
|
|
138
|
+
['cache_write', call.cacheWriteTokens],
|
|
139
|
+
];
|
|
140
|
+
for (const [kind, count] of kinds) this.tokens.add({ ...series, kind }, count);
|
|
141
|
+
if (usd === null) this.unpriced.add(series, 1);
|
|
142
|
+
else this.cost.add({ ...series, trazum_cost_basis: COST_BASIS }, usd);
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
unmeasured(cause: UnmeasuredCause): void {
|
|
146
|
+
this.unmeasuredCalls.add({ trazum_provider: this.provider, cause }, 1);
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
count(event: GatewayCount): void {
|
|
150
|
+
const provider = { trazum_provider: this.provider };
|
|
151
|
+
if (event.kind === 'refused') this.refused.add({ ...provider, reason: event.reason }, 1);
|
|
152
|
+
else if (event.kind === 'substituted') {
|
|
153
|
+
if (this.admit(this.swaps, JSON.stringify([event.from, event.to]))) {
|
|
154
|
+
this.substituted.add({ ...provider, from_model: event.from, to_model: event.to }, 1);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
else if (event.kind === 'free') this.free.add({ ...provider, path: event.path }, 1);
|
|
158
|
+
else this.unreachable.add(provider, 1);
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** The Prometheus text exposition, ending with a line break as the format requires. */
|
|
162
|
+
text(): string {
|
|
163
|
+
const counters = [
|
|
164
|
+
this.calls, this.tokens, this.cost, this.unpriced, this.unmeasuredCalls,
|
|
165
|
+
this.refused, this.substituted, this.free, this.unreachable,
|
|
166
|
+
];
|
|
167
|
+
const out = counters.flatMap((counter) => counter.lines());
|
|
168
|
+
out.push(
|
|
169
|
+
'# HELP trazum_gateway_calls_dropped_total Calls left out of every other figure here because they named a new model, label or substitution past the limit.',
|
|
170
|
+
'# TYPE trazum_gateway_calls_dropped_total counter',
|
|
171
|
+
`trazum_gateway_calls_dropped_total${render({ trazum_provider: this.provider })} ${this.dropped}`,
|
|
172
|
+
'# HELP trazum_gateway_start_time_seconds When this gateway process started; every counter here begins there.',
|
|
173
|
+
'# TYPE trazum_gateway_start_time_seconds gauge',
|
|
174
|
+
`trazum_gateway_start_time_seconds${render({ trazum_provider: this.provider })} ${this.startedMs / 1000}`,
|
|
175
|
+
);
|
|
176
|
+
return `${out.join('\n')}\n`;
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* The scrape server: `GET /metrics` and nothing else.
|
|
182
|
+
*
|
|
183
|
+
* Behind the same host and origin guard as the proxy and `serve`, so a page
|
|
184
|
+
* that rebound its own hostname to 127.0.0.1 cannot read which models and
|
|
185
|
+
* labels this gateway has seen.
|
|
186
|
+
*/
|
|
187
|
+
export function buildMetricsServer(metrics: GatewayMetrics): Server {
|
|
188
|
+
const server: Server = createServer((request: IncomingMessage, response: ServerResponse) => {
|
|
189
|
+
const refused = refuseHost(server, request);
|
|
190
|
+
if (refused !== null) {
|
|
191
|
+
response.writeHead(refused.status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
|
|
192
|
+
response.end(`${JSON.stringify({ error: refused.error, detail: refused.detail })}\n`);
|
|
193
|
+
return;
|
|
194
|
+
}
|
|
195
|
+
if (request.url !== '/metrics') {
|
|
196
|
+
response.writeHead(404, { 'content-type': 'application/json' });
|
|
197
|
+
response.end(`${JSON.stringify({ error: 'this port serves GET /metrics and nothing else' })}\n`);
|
|
198
|
+
return;
|
|
199
|
+
}
|
|
200
|
+
if (request.method !== 'GET' && request.method !== 'HEAD') {
|
|
201
|
+
response.writeHead(405, { 'content-type': 'application/json', allow: 'GET, HEAD' });
|
|
202
|
+
response.end(`${JSON.stringify({ error: 'this port serves GET /metrics and nothing else' })}\n`);
|
|
203
|
+
return;
|
|
204
|
+
}
|
|
205
|
+
response.writeHead(200, { 'content-type': 'text/plain; version=0.0.4; charset=utf-8', 'cache-control': 'no-store' });
|
|
206
|
+
response.end(request.method === 'HEAD' ? undefined : metrics.text());
|
|
207
|
+
});
|
|
208
|
+
return server;
|
|
209
|
+
}
|