@trazum/cli 1.80.1 → 1.81.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trazum/cli",
3
- "version": "1.80.1",
3
+ "version": "1.81.0",
4
4
  "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
5
5
  "license": "MIT",
6
6
  "author": "David Mu\u00f1oz Rey",
@@ -41,7 +41,7 @@
41
41
  "prepublishOnly": "npm run build && npm test"
42
42
  },
43
43
  "dependencies": {
44
- "@trazum/core": "1.80.1"
44
+ "@trazum/core": "1.81.0"
45
45
  },
46
46
  "devDependencies": {
47
47
  "@types/node": "^26.2.0",
@@ -89,10 +89,62 @@ export interface Upstream {
89
89
  * in the path was for.
90
90
  */
91
91
  modelIn?: 'path';
92
+ /**
93
+ * Paths that spend no tokens, forwarded without a budget decision.
94
+ *
95
+ * **Refusing these would be the wrong answer, not a stricter one.**
96
+ * `count_tokens` is the call you make to find out whether you can afford the
97
+ * other one; answering it with a 402 blinds a caller at exactly the moment
98
+ * they are trying to behave. And a budget refusal only means something when
99
+ * there is money on the line: a call that spends nothing has nothing to
100
+ * judge, so judging it would be theatre with a real cost.
101
+ *
102
+ * **What this does and does not widen.** The origin is still compiled in, so
103
+ * the credential can still only ever reach one host. What grows is the set
104
+ * of *operations* somebody who can reach the loopback port may perform with
105
+ * it, and that is why the list is literal strings only, enumerated here, and
106
+ * why each entry has to be written into `docs/gateway.md` before a guard
107
+ * will let it exist. A pattern here would be a widening with no budget check
108
+ * behind it, which is the general-proxy shape this gateway is built to
109
+ * refuse.
110
+ *
111
+ * Nothing that spends belongs here. `/v1/messages/batches` is the near miss:
112
+ * it looks administrative and it bills.
113
+ */
114
+ free?: readonly FreePath[];
115
+ }
116
+
117
+ /** One path that costs nothing, and the method it answers on. */
118
+ export interface FreePath {
119
+ method: 'GET' | 'POST';
120
+ path: string;
92
121
  }
93
122
 
94
123
  export const UPSTREAMS: Readonly<Record<string, Upstream>> = {
95
- anthropic: { origin: 'https://api.anthropic.com', path: '/v1/messages' },
124
+ anthropic: {
125
+ origin: 'https://api.anthropic.com',
126
+ path: '/v1/messages',
127
+ /**
128
+ * The two an agent asks for beside the call itself.
129
+ *
130
+ * `POST /v1/messages/count_tokens` returns a token count and bills nothing:
131
+ * `packages/core/src/tokenizer.ts` has called it for `--exact-tokens` since
132
+ * the band harness needed a ground truth, and this repository documents it
133
+ * as free in the same breath every time it suggests using it.
134
+ *
135
+ * `GET /v1/models` lists what the account may call. It carries no body,
136
+ * spends nothing, and is the call a client makes on startup to find out
137
+ * what exists.
138
+ *
139
+ * Both are here because a coding agent pointed at this gateway hits them
140
+ * within its first second and got a 404 from a proxy that was otherwise
141
+ * working, which reads as the gateway being broken rather than narrow.
142
+ */
143
+ free: [
144
+ { method: 'POST', path: '/v1/messages/count_tokens' },
145
+ { method: 'GET', path: '/v1/models' },
146
+ ],
147
+ },
96
148
  openai: { origin: 'https://api.openai.com', path: '/v1/chat/completions' },
97
149
  /**
98
150
  * DeepSeek's host is not a new fact: `scripts/measure-token-band.mjs` has
@@ -137,6 +189,17 @@ export function forwards(upstream: Upstream): string {
137
189
  return typeof upstream.path === 'string' ? upstream.path : '/v1beta/models/{model}:generateContent';
138
190
  }
139
191
 
192
+ /**
193
+ * The paths this gateway forwards without judging, as a person reads them.
194
+ *
195
+ * Same reason `forwards` exists: the refusal body, the documentation guard and
196
+ * the page itself have to render this from one place, or they drift into three
197
+ * different accounts of what is actually reachable.
198
+ */
199
+ export function alsoForwards(upstream: Upstream): readonly string[] {
200
+ return (upstream.free ?? []).map((entry) => `${entry.method} ${entry.path}`);
201
+ }
202
+
140
203
  /**
141
204
  * Whether this request is the one call this gateway speaks for, and the model
142
205
  * the path named if it named one.
@@ -147,10 +210,28 @@ export function forwards(upstream: Upstream): string {
147
210
  * except the compiled-in origin and a path assembled from a model id that has
148
211
  * already been restricted to `[A-Za-z0-9._-]`.
149
212
  */
150
- export function route(upstream: Upstream, url: string | undefined): { path: string; model: string | null } | null {
213
+ export function route(
214
+ upstream: Upstream,
215
+ method: string | undefined,
216
+ url: string | undefined,
217
+ ): { path: string; model: string | null; spends: boolean } | null {
151
218
  if (url === undefined) return null;
219
+
220
+ /**
221
+ * The free paths are checked first and compared as whole strings, method
222
+ * included. A `startsWith` here would forward `/v1/models/../messages` and
223
+ * anything else a caller could suffix onto a prefix that looked harmless.
224
+ */
225
+ for (const entry of upstream.free ?? []) {
226
+ if (method === entry.method && url === entry.path) {
227
+ return { path: entry.path, model: null, spends: false };
228
+ }
229
+ }
230
+
231
+ // Everything below spends, and only POST spends.
232
+ if (method !== 'POST') return null;
152
233
  if (typeof upstream.path === 'string') {
153
- return url === upstream.path ? { path: upstream.path, model: null } : null;
234
+ return url === upstream.path ? { path: upstream.path, model: null, spends: true } : null;
154
235
  }
155
236
  const matched = upstream.path.exec(url);
156
237
  const model = matched?.[1];
@@ -158,7 +239,7 @@ export function route(upstream: Upstream, url: string | undefined): { path: stri
158
239
  // containing the word `undefined` and forward it. Refusing is the only
159
240
  // answer: there is no model, so there is nothing to price the call against.
160
241
  if (model === undefined) return null;
161
- return { path: `/v1beta/models/${model}:generateContent`, model };
242
+ return { path: `/v1beta/models/${model}:generateContent`, model, spends: true };
162
243
  }
163
244
 
164
245
  /**
@@ -379,22 +460,78 @@ export function buildGateway(context: GatewayContext): Server {
379
460
  response.end(`${JSON.stringify({ error: 'no upstream configured for this provider' })}\n`);
380
461
  return;
381
462
  }
382
- const routed = request.method === 'POST' ? route(upstream, request.url) : null;
463
+ const routed = route(upstream, request.method, request.url);
383
464
  if (routed === null) {
384
- // Only the one path that spends tokens. A gateway forwarding anything
385
- // else is a general proxy for somebody's API key.
465
+ // The one path that spends tokens, plus the short list that spends
466
+ // nothing. A gateway forwarding anything else is a general proxy for
467
+ // somebody's API key.
386
468
  response.writeHead(404, { 'content-type': 'application/json' });
387
469
  response.end(
388
- // A refusal never arrives bare: the one thing it does forward, said
389
- // from the upstream table rather than written out again here.
470
+ // A refusal never arrives bare: what it does forward, said from the
471
+ // upstream table rather than written out again here.
390
472
  `${JSON.stringify({
391
473
  error: 'not a path this gateway forwards',
392
474
  forwards: `POST ${forwards(upstream)}`,
475
+ ...(alsoForwards(upstream).length === 0 ? {} : { alsoForwards: alsoForwards(upstream) }),
393
476
  })}\n`,
394
477
  );
395
478
  return;
396
479
  }
397
480
 
481
+ /**
482
+ * A path that spends nothing is forwarded and nothing else happens to it.
483
+ *
484
+ * **Deliberately the dumbest branch in this file.** It reaches no
485
+ * decision, records no usage and never substitutes a model, because
486
+ * there is no money to judge, no counts to keep and nothing to swap. Any
487
+ * of those would be a figure invented about a call that cost nothing,
488
+ * which is worse than the 404 this replaces.
489
+ *
490
+ * It is placed before `readBody`'s model check on purpose: `GET
491
+ * /v1/models` has no body and no model, and running it through machinery
492
+ * that exists to price a call would refuse it with "could not read a
493
+ * model out of this request", which is true and useless.
494
+ */
495
+ if (!routed.spends) {
496
+ const passthrough = new Headers();
497
+ for (const [name, value] of Object.entries(request.headers)) {
498
+ if (HOP_BY_HOP.has(name.toLowerCase()) || value === undefined) continue;
499
+ passthrough.set(name, Array.isArray(value) ? value.join(', ') : value);
500
+ }
501
+ const sent = request.method === 'GET' ? '' : await readBody(request);
502
+ if (sent === null && request.method === 'POST') {
503
+ response.writeHead(413, { 'content-type': 'application/json' });
504
+ response.end(`${JSON.stringify({ error: 'request body too large' })}\n`);
505
+ return;
506
+ }
507
+ let free: Response;
508
+ try {
509
+ free = await doFetch(`${upstream.origin}${routed.path}`, {
510
+ method: request.method === 'GET' ? 'GET' : 'POST',
511
+ headers: passthrough,
512
+ ...(request.method === 'GET' ? {} : { body: sent ?? '' }),
513
+ });
514
+ } catch (error) {
515
+ response.writeHead(502, { 'content-type': 'application/json' });
516
+ response.end(
517
+ `${JSON.stringify({
518
+ error: {
519
+ type: 'trazum_upstream_unreachable',
520
+ message: error instanceof Error ? error.message : String(error),
521
+ },
522
+ })}\n`,
523
+ );
524
+ return;
525
+ }
526
+ const headers: Record<string, string> = {};
527
+ free.headers.forEach((value, name) => {
528
+ if (!HOP_BY_HOP.has(name.toLowerCase())) headers[name] = value;
529
+ });
530
+ response.writeHead(free.status, headers);
531
+ response.end(Buffer.from(await free.arrayBuffer()));
532
+ return;
533
+ }
534
+
398
535
  const body = await readBody(request);
399
536
  if (body === null) {
400
537
  response.writeHead(413, { 'content-type': 'application/json' });