@trazum/cli 1.42.0 → 1.44.0

package/dist/serve.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The endpoint that answers before the call is sent.
+ *
+ * **Loopback only, and the address is not a flag.** A cost oracle listening on
+ * a network interface is an attack surface with a very small upside: it holds
+ * a company's spend, its model mix and its budgets, and it answers anybody who
+ * asks. `checkedEndpoint` has guarded Trazum's *outbound* requests since 1.14
+ * on the principle that a caller selects an endpoint rather than naming one;
+ * this is the inbound counterpart, and it is enforced the same way — by there
+ * being no way to say otherwise. `127.0.0.1` is compiled in. A Unix socket is
+ * offered for callers that would rather not use a port at all.
+ *
+ * **No auth, on purpose.** Anything reachable only from the machine it runs on
+ * is already behind the operating system's own boundary, and a token checked
+ * over loopback is theatre: whoever can reach the socket can read the token
+ * out of the process that holds it. The honest posture is a surface small
+ * enough not to need one.
+ *
+ * **It degrades rather than failing.** With no store and no budget the
+ * endpoint still prices the call from the bundled catalogue and says the
+ * budget half is unknown. Offline is a mode, not an error, and an oracle that
+ * refuses to speak when half its inputs are missing is an oracle nobody wires
+ * into a hot path.
+ */
+import type { Server } from 'node:http';
+import type { PricingCatalogue } from '@trazum/core';
+/** Compiled in. See the module note: this is the inbound SSRF posture. */
+export declare const BIND_HOST = "127.0.0.1";
+export declare const DEFAULT_PORT = 7317;
+/**
+ * Bodies larger than this are refused unread.
+ *
+ * A prompt is text and text is unbounded; a hot-path oracle that will buffer
+ * whatever it is handed is a memory exhaustion away from taking the caller
+ * down with it — and the caller was asking how to spend *less*.
+ */
+export declare const MAX_BODY_BYTES = 1000000;
+export interface ServeContext {
+    catalogue: PricingCatalogue;
+    /**
+     * Measured spend and the budget it is judged against, read once at start
+     * and refreshed by the caller.
+     *
+     * Read once because the whole promise here is single-digit milliseconds,
+     * and a file read in the request path cannot make that promise. The staleness
+     * is a real cost, so the answer carries the window its measurement covers
+     * rather than implying it is current to the second.
+     */
+    position: () => {
+        consumedUsd?: number;
+        limitUsd?: number;
+        window?: {
+            fromMs: number;
+            toMs: number;
+        } | null;
+    };
+}
+export declare function buildServer(context: ServeContext): Server;
+export interface ListenTarget {
+    /** A Unix socket path, when the caller would rather not use a port. */
+    socket?: string;
+    port?: number;
+}
+export declare function listen(server: Server, target: ListenTarget): Promise<string>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAmB,MAAM,EAAkB,MAAM,WAAW,CAAC;AAEzE,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEjE,0EAA0E;AAC1E,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,UAAY,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/G;AAyBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CA8CzD;AAED,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAa5E"}

package/dist/serve.js

@@ -0,0 +1,115 @@
+/**
+ * The endpoint that answers before the call is sent.
+ *
+ * **Loopback only, and the address is not a flag.** A cost oracle listening on
+ * a network interface is an attack surface with a very small upside: it holds
+ * a company's spend, its model mix and its budgets, and it answers anybody who
+ * asks. `checkedEndpoint` has guarded Trazum's *outbound* requests since 1.14
+ * on the principle that a caller selects an endpoint rather than naming one;
+ * this is the inbound counterpart, and it is enforced the same way — by there
+ * being no way to say otherwise. `127.0.0.1` is compiled in. A Unix socket is
+ * offered for callers that would rather not use a port at all.
+ *
+ * **No auth, on purpose.** Anything reachable only from the machine it runs on
+ * is already behind the operating system's own boundary, and a token checked
+ * over loopback is theatre: whoever can reach the socket can read the token
+ * out of the process that holds it. The honest posture is a surface small
+ * enough not to need one.
+ *
+ * **It degrades rather than failing.** With no store and no budget the
+ * endpoint still prices the call from the bundled catalogue and says the
+ * budget half is unknown. Offline is a mode, not an error, and an oracle that
+ * refuses to speak when half its inputs are missing is an oracle nobody wires
+ * into a hot path.
+ */
+import { createServer } from 'node:http';
+import { answerCost } from '@trazum/core';
+/** Compiled in. See the module note: this is the inbound SSRF posture. */
+export const BIND_HOST = '127.0.0.1';
+export const DEFAULT_PORT = 7317;
+/**
+ * Bodies larger than this are refused unread.
+ *
+ * A prompt is text and text is unbounded; a hot-path oracle that will buffer
+ * whatever it is handed is a memory exhaustion away from taking the caller
+ * down with it — and the caller was asking how to spend *less*.
+ */
+export const MAX_BODY_BYTES = 1_000_000;
+async function readBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error('body too large');
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+const send = (response, status, body) => {
+    const text = JSON.stringify(body);
+    response.writeHead(status, {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(text),
+        // Nothing here is for a browser to read across origins, and saying so
+        // costs one header.
+        'cache-control': 'no-store',
+    });
+    response.end(text);
+};
+export function buildServer(context) {
+    return createServer((request, response) => {
+        void (async () => {
+            const url = new URL(request.url ?? '/', `http://${BIND_HOST}`);
+            if (request.method === 'GET' && url.pathname === '/health') {
+                send(response, 200, { ok: true, schemaVersion: 1 });
+                return;
+            }
+            if (request.method !== 'POST' || url.pathname !== '/cost') {
+                send(response, 404, {
+                    error: 'not-found',
+                    detail: 'POST /cost, or GET /health.',
+                });
+                return;
+            }
+            let payload;
+            try {
+                const raw = await readBody(request);
+                payload = raw.trim() === '' ? {} : JSON.parse(raw);
+            }
+            catch (error) {
+                send(response, 400, {
+                    error: 'bad-request',
+                    detail: error instanceof Error && error.message === 'body too large'
+                        ? `A request body may be at most ${MAX_BODY_BYTES} bytes.`
+                        : 'The body must be JSON.',
+                });
+                return;
+            }
+            const position = context.position();
+            const answer = answerCost({
+                model: typeof payload.model === 'string' ? payload.model : undefined,
+                inputTokens: typeof payload.inputTokens === 'number' ? payload.inputTokens : undefined,
+                outputTokens: typeof payload.outputTokens === 'number' ? payload.outputTokens : undefined,
+                basis: payload.basis === 'heuristic' ? 'heuristic' : 'token-count',
+                ...position,
+            }, { catalogue: context.catalogue });
+            send(response, 200, answer);
+        })();
+    });
+}
+export function listen(server, target) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        if (target.socket !== undefined) {
+            server.listen(target.socket, () => resolve(target.socket));
+            return;
+        }
+        // The host is not a parameter. See the module note.
+        server.listen(target.port ?? DEFAULT_PORT, BIND_HOST, () => {
+            const address = server.address();
+            resolve(typeof address === 'object' && address !== null ? `${BIND_HOST}:${address.port}` : String(address));
+        });
+    });
+}
+//# sourceMappingURL=serve.js.map

package/dist/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"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"}

package/dist/watch-run.d.ts

@@ -0,0 +1,69 @@
+/**
+ * One cycle of watching, and the state that survives a restart.
+ *
+ * `--once` is the primitive: pull the window, keep it, evaluate the gates,
+ * emit what crossed, save state. A cron entry runs exactly that, and so does
+ * every test. The foreground loop is this function in a timer, so there is one
+ * code path and no daemon-only behaviour that nobody exercises.
+ *
+ * **The state file is what makes a restart honest.** Without it a resumed
+ * watcher re-alerts on yesterday's crossing (noise nobody reads) and implies
+ * it was watching the whole time (a claim it cannot make). With it, the
+ * crossing stays quiet and the unwatched stretch gets named once.
+ */
+import type { WatchCrossing } from '@trazum/core';
+export declare const WATCH_STATE_FILE = ".trazum/watch.json";
+export declare const WATCH_STATE_VERSION = 1;
+export interface WatchState {
+    v: number;
+    /** When the last cycle ran, so a long silence can be told from a first run. */
+    lastCycleMs: number;
+    /** How far the measurements reached, for the coverage gap. */
+    lastCoveredToMs: number | null;
+    /** Gate keys already alerted on, so a restart is not amnesia. */
+    fired: Record<string, number>;
+}
+export declare function readWatchState(root: string): Promise<WatchState | null>;
+export declare function writeWatchState(root: string, state: WatchState): Promise<void>;
+/**
+ * Whether a webhook URL is one this tool will post to.
+ *
+ * **This is not the SSRF case and the difference matters.** `checkedEndpoint`
+ * exists because a *request body* must never name a host: an anonymous caller
+ * pointing a shared server at an internal address is somebody else's machine
+ * reaching somewhere it was never meant to. Here the URL is in the operator's
+ * own config, on their own machine, and pointing it at their own alerting
+ * daemon on loopback is the ordinary case rather than the attack.
+ *
+ * So loopback is allowed and plain http is allowed *only* there, while two
+ * rules stay absolute: no credentials embedded in the URL, because a URL ends
+ * up in logs and shell history; and https everywhere else, because an alert
+ * carries spend figures across a network.
+ */
+export type WebhookRejection = 'invalid-url' | 'credentials-in-url' | 'insecure-scheme';
+export declare function checkWebhook(raw: string): {
+    ok: true;
+    url: URL;
+} | {
+    ok: false;
+    reason: WebhookRejection;
+};
+/**
+ * The alert payload.
+ *
+ * Figures and gate names, never prompt text — the store has never held any and
+ * neither does this. Every crossing carries its own provenance, so a receiver
+ * that fans these into a dashboard cannot lose track of what kind of number it
+ * is holding.
+ */
+export interface WatchAlert {
+    schemaVersion: 1;
+    firedAtMs: number;
+    crossings: WatchCrossing[];
+}
+export declare function postWebhook(url: URL, alert: WatchAlert, fetchImpl?: typeof fetch): Promise<{
+    ok: boolean;
+    status: number | null;
+    error: string | null;
+}>;
+//# sourceMappingURL=watch-run.d.ts.map

package/dist/watch-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-run.d.ts","sourceRoot":"","sources":["../src/watch-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAErD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAU7E;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,oBAAoB,GAAG,iBAAiB,CAAC;AAExF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAkB1G;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,CAAC,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,wBAAsB,WAAW,CAC/B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,UAAU,EACjB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAmBvE"}

package/dist/watch-run.js

@@ -0,0 +1,79 @@
+/**
+ * One cycle of watching, and the state that survives a restart.
+ *
+ * `--once` is the primitive: pull the window, keep it, evaluate the gates,
+ * emit what crossed, save state. A cron entry runs exactly that, and so does
+ * every test. The foreground loop is this function in a timer, so there is one
+ * code path and no daemon-only behaviour that nobody exercises.
+ *
+ * **The state file is what makes a restart honest.** Without it a resumed
+ * watcher re-alerts on yesterday's crossing (noise nobody reads) and implies
+ * it was watching the whole time (a claim it cannot make). With it, the
+ * crossing stays quiet and the unwatched stretch gets named once.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { SAFE_FETCH_INIT } from '@trazum/core/node';
+export const WATCH_STATE_FILE = '.trazum/watch.json';
+export const WATCH_STATE_VERSION = 1;
+export async function readWatchState(root) {
+    try {
+        const parsed = JSON.parse(await readFile(join(root, WATCH_STATE_FILE), 'utf8'));
+        if (parsed?.v !== WATCH_STATE_VERSION)
+            return null;
+        return parsed;
+    }
+    catch {
+        // No state, or state this version cannot read: a first cycle either way,
+        // which is a state the caller reports rather than an error.
+        return null;
+    }
+}
+export async function writeWatchState(root, state) {
+    const path = join(root, WATCH_STATE_FILE);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}
+export function checkWebhook(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { ok: false, reason: 'invalid-url' };
+    }
+    if (url.username !== '' || url.password !== '') {
+        return { ok: false, reason: 'credentials-in-url' };
+    }
+    const loopback = url.hostname === 'localhost' ||
+        url.hostname === '127.0.0.1' ||
+        url.hostname === '[::1]' ||
+        url.hostname === '::1';
+    if (url.protocol === 'https:')
+        return { ok: true, url };
+    if (url.protocol === 'http:' && loopback)
+        return { ok: true, url };
+    return { ok: false, reason: 'insecure-scheme' };
+}
+export async function postWebhook(url, alert, fetchImpl = fetch) {
+    try {
+        const response = await fetchImpl(url.toString(), {
+            ...SAFE_FETCH_INIT,
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(alert),
+            signal: AbortSignal.timeout(10_000),
+        });
+        return { ok: response.ok, status: response.status, error: null };
+    }
+    catch (error) {
+        /**
+         * A webhook that will not deliver must not take the alert down with it.
+         * The exit code and the stdout event have already carried the crossing;
+         * losing those because a receiver is down would make the quietest failure
+         * the loudest one.
+         */
+        return { ok: false, status: null, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+//# sourceMappingURL=watch-run.js.map

package/dist/watch-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-run.js","sourceRoot":"","sources":["../src/watch-run.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.42.0",
+  "version": "1.44.0",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.42.0"
+    "@trazum/core": "1.44.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -44,6 +44,8 @@ ${bold('USAGE')}
   trazum history <dir-of-stored-reports> [options]
   trazum connect <anthropic|openai> [options]
   trazum store [--prune] [options]
+  trazum watch [--once | --interval 15m] [options]
+  trazum serve [--port <n> | --socket <path>]
   trazum diff <before> <after> [options]
   trazum diff --all <dir> <dir> [options]
   trazum rank <dir> [options]
@@ -321,6 +323,58 @@ ${bold('OPTIONS FOR plan')}
   a plan that hides its assumptions is advice pretending to be arithmetic.
   Projected savings and money already spent are separate totals throughout.
 
+${bold('OPTIONS FOR serve')}
+  --port <n>                  Port on 127.0.0.1. Default: 7317.
+  --socket <path>             Listen on a Unix socket instead of a port.
+
+  Answers the two questions that matter at call time — what will this cost,
+  and is there budget left — in single-digit milliseconds, so an agent or a
+  wrapper can ask before it spends rather than reading a report afterwards.
+
+  POST /cost with {"model": "...", "inputTokens": n, "outputTokens": n};
+  GET /health says it is up. Every answer keeps the measured half and the
+  estimated half apart: the budget consumed comes from the provider's billed
+  counts, the cost of the call being asked about is an estimate of something
+  that has not happened, and the verdict says which of the two it rests on.
+
+  It listens on 127.0.0.1 and nowhere else, and there is no flag to change
+  that: a cost oracle on a network interface holds a company's spend, its
+  model mix and its budgets, and answers whoever asks. There is no auth for
+  the same reason there is no --host — a token checked over loopback is
+  theatre, and the honest posture is a surface small enough not to need one.
+
+  With no store and no budget it still prices the call and says the budget
+  half is unknown. Offline is a mode, not a failure.
+
+${bold('OPTIONS FOR watch')}
+  --once                      One cycle: measure, keep, evaluate, emit,
+                              remember. What a cron entry runs. The default.
+  --interval <n>m|h           Stay in the foreground and repeat. Minimum five
+                              minutes: usage APIs are rate limited, and a tight
+                              loop is a way to get your own key throttled.
+  --webhook <url>             POST the crossings somewhere. https only, except
+                              loopback; a URL carrying credentials is refused,
+                              because URLs end up in logs and shell history.
+  --payload <file>            Evaluate a usage payload you already have,
+                              instead of the store.
+  --json                      The cycle as data: crossings, abstentions, gap.
+
+  Evaluates the spend gates from your config — maxUsd, maxDayUsd,
+  maxCacheLossUsd — against what has been measured, and tells you the
+  afternoon it happens rather than three weeks later. Exits 1 when something
+  crossed, so cron mails it and CI fails.
+
+  An alert fires on a measured crossing and never on a projection: "you have
+  spent $412 of a $400 budget" is a fact and "you will exceed" is a forecast,
+  which this tool does not make at any window length. A day still being
+  measured is reported as not yet judgeable rather than passed — but a day
+  already over budget fires whatever the hour, because it does not become less
+  over budget at midnight.
+
+  A restart does not re-alert on a crossing already reported, and names the
+  stretch it was not watching, because a watcher that resumes in silence
+  implies coverage it did not have.
+
 ${bold('OPTIONS FOR store')}
   --prune                     Drop measurements older than the retention
                               policy, and compact the append log to what the
@@ -1506,6 +1560,62 @@ ${bold('EXAMPLES')}
       `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
   },
 
+  serve: {
+    listening: (where) => `Answering on ${where}`,
+    loopbackOnly: () =>
+      'Loopback only, and there is no flag to change that: this holds your spend, your model mix and your budgets, and would answer whoever asked. There is no auth for the same reason — a token checked over loopback is theatre.',
+    measuredFrom: (usd) =>
+      `Budget answers are measured against ${usd} from the store, read once at start. Every answer carries the window that figure covers rather than implying it is current to the second — restart to refresh it.`,
+    nothingMeasured: (dir) =>
+      `Nothing is measured yet (the store at ${dir} is empty), so the budget half of every answer will say so. The cost half still answers from the catalogue: offline is a mode, not a failure.`,
+    noBudget: () =>
+      'No spend.maxUsd is configured, so "is there budget left" has no subject and every answer says so rather than guessing one.',
+    badPort: (value) => `"${value}" is not a port. Give a whole number from 0 to 65535, or use --socket.`,
+  },
+
+  watch: {
+    noThresholds: () =>
+      'Watching needs something to watch for. Set spend.maxUsd, spend.maxDayUsd or spend.maxCacheLossUsd in trazum.config.json — a watcher with no threshold is a green light nobody earned.',
+    nothingToWatch: (dir) =>
+      `Nothing has been measured yet: the store at ${dir} is empty. Fill it with "trazum connect <provider> --store" first — watching nothing would report that everything is fine.`,
+    intervalTooTight: () =>
+      '--interval must be at least 5m. Usage APIs are rate limited, and a tight loop is a way to get your own key throttled by a tool that exists to save you money.',
+    badWebhook: (reason) =>
+      reason === 'credentials-in-url'
+        ? 'That webhook URL carries credentials. URLs end up in logs, shell history and error messages, so this one is refused — put the secret in a header your receiver checks, or in the receiver itself.'
+        : reason === 'insecure-scheme'
+          ? 'A webhook must be https, except on loopback. An alert carries your spend figures, and sending them in the clear across a network is a leak you did not ask for.'
+          : 'That webhook is not a URL this tool can parse.',
+    crossed: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'Total spend'
+          : gate === 'maxDayUsd'
+            ? `Spend on ${day}`
+            : 'Money lost to caching';
+      return `CROSSED — ${what} is ${measured} against a limit of ${limit}. Measured, not projected.`;
+    },
+    stillOver: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'Total spend'
+          : gate === 'maxDayUsd'
+            ? `Spend on ${day}`
+            : 'Money lost to caching';
+      return `STILL OVER — ${what} is ${measured} against a limit of ${limit}, and was already reported. Quiet is not clean.`;
+    },
+    notJudgeable: (gate, reason, covered) =>
+      reason === 'window-too-short'
+        ? `${gate} cannot be judged yet: this period is ${covered ?? 'partly'} measured, and a threshold over part of a day is a threshold over something else. Not a pass — it will be judged when the day is in.`
+        : `${gate} cannot be judged on this source, which does not serve what the gate is written against. Not a pass: a gate silently skipped reads exactly like a gate that keeps passing.`,
+    gap: (from, to) =>
+      `Nothing was watching between ${from} and ${to}. Whatever crossed in that stretch was not seen, and this line exists so a resumed watcher does not imply coverage it did not have.`,
+    allWithin: (gates) => `Within every threshold: ${gates} gates evaluated against measured spend.`,
+    webhookFailed: (status) =>
+      `The webhook did not deliver (${status}). The crossing is still in the exit code and in the output above — a receiver being down must not be the quietest failure in the room.`,
+    watching: (minutes) => `Watching every ${minutes} minutes. Ctrl-C stops it.`,
+  },
+
   store: {
     appended: (count, dir) => `Kept ${count} measurements in ${dir}.`,
     empty: (dir) =>

package/src/i18n/es.ts

@@ -31,6 +31,8 @@ ${bold('USO')}
   trazum history <dir-de-informes-guardados> [opciones]
   trazum connect <anthropic|openai> [opciones]
   trazum store [--prune] [opciones]
+  trazum watch [--once | --interval 15m] [opciones]
+  trazum serve [--port <n> | --socket <ruta>]
   trazum diff <antes> <después> [opciones]
   trazum diff --all <dir> <dir> [opciones]
   trazum rank <dir> [opciones]
@@ -328,6 +330,63 @@ ${bold('OPCIONES DE plan')}
   consejo haciéndose pasar por aritmética. El ahorro proyectado y el dinero ya
   gastado son totales separados en todas partes.
 
+${bold('OPCIONES DE serve')}
+  --port <n>                  Puerto en 127.0.0.1. Por defecto: 7317.
+  --socket <ruta>             Escucha en un socket Unix en vez de un puerto.
+
+  Responde las dos preguntas que importan en el momento de la llamada — cuánto
+  va a costar esto y si queda presupuesto — en milisegundos de un solo dígito,
+  para que un agente o un envoltorio pueda preguntar antes de gastar en vez de
+  leer un informe después.
+
+  POST /cost con {"model": "...", "inputTokens": n, "outputTokens": n};
+  GET /health dice que está en pie. Cada respuesta mantiene separada la mitad
+  medida de la estimada: el presupuesto consumido viene de los recuentos que
+  facturó el proveedor, el coste de la llamada por la que preguntas es una
+  estimación de algo que no ha pasado, y el veredicto dice en cuál de las dos
+  se apoya.
+
+  Escucha en 127.0.0.1 y en ningún otro sitio, y no hay flag para cambiarlo:
+  un oráculo de costes en una interfaz de red guarda el gasto de una empresa,
+  su mezcla de modelos y sus presupuestos, y le responde a quien pregunte. No
+  hay autenticación por la misma razón por la que no hay --host — un token
+  comprobado sobre loopback es teatro, y la postura honesta es una superficie
+  lo bastante pequeña como para no necesitarlo.
+
+  Sin almacén y sin presupuesto sigue tasando la llamada y dice que la mitad
+  del presupuesto es desconocida. Sin conexión es un modo, no un fallo.
+
+${bold('OPCIONES DE watch')}
+  --once                      Una vuelta: medir, guardar, evaluar, emitir,
+                              recordar. Lo que ejecuta una entrada de cron. Es
+                              lo que se hace por defecto.
+  --interval <n>m|h           Se queda en primer plano y repite. Mínimo cinco
+                              minutos: las APIs de uso están limitadas por
+                              tasa, y un bucle apretado es una forma de que te
+                              estrangulen tu propia clave.
+  --webhook <url>             Envía los cruces por POST. Solo https, salvo en
+                              loopback; una URL con credenciales se rechaza,
+                              porque las URLs acaban en logs e historiales.
+  --payload <fichero>         Evalúa un payload de uso que ya tengas, en vez
+                              del almacén.
+  --json                      La vuelta como datos: cruces, abstenciones, hueco.
+
+  Evalúa los gates de gasto de tu configuración — maxUsd, maxDayUsd,
+  maxCacheLossUsd — contra lo que se ha medido, y te lo dice la tarde en que
+  pasa en vez de tres semanas después. Sale con 1 cuando algo cruzó, así que
+  cron te lo manda y CI falla.
+
+  Una alerta salta por un cruce medido y nunca por una proyección: "has
+  gastado $412 de un presupuesto de $400" es un hecho y "vas a excederte" es un
+  pronóstico, que esta herramienta no hace a ninguna escala de ventana. Un día
+  que todavía se está midiendo se reporta como aún no juzgable en vez de
+  aprobarse — pero un día que ya se pasó del presupuesto salta a cualquier
+  hora, porque no se pasa menos a medianoche.
+
+  Un reinicio no vuelve a avisar de un cruce ya reportado, y nombra el tramo
+  que no estuvo vigilando, porque un vigilante que se reanuda en silencio
+  insinúa una cobertura que no tuvo.
+
 ${bold('OPCIONES DE store')}
   --prune                     Borra las mediciones más antiguas que la política
                               de retención y compacta el log a lo que el
@@ -1531,6 +1590,62 @@ ${bold('EJEMPLOS')}
       `Plan escrito en ${path}, con fecha. Guárdalo: una predicción que nadie apuntó es una predicción que no se le puede exigir a nadie.`,
   },
 
+  serve: {
+    listening: (where) => `Respondiendo en ${where}`,
+    loopbackOnly: () =>
+      'Solo loopback, y no hay flag para cambiarlo: esto guarda tu gasto, tu mezcla de modelos y tus presupuestos, y le respondería a quien preguntara. No hay autenticación por la misma razón — un token comprobado sobre loopback es teatro.',
+    measuredFrom: (usd) =>
+      `Las respuestas de presupuesto se miden contra ${usd} del almacén, leídos una vez al arrancar. Cada respuesta lleva el período que cubre esa cifra en vez de insinuar que está al segundo — reinicia para refrescarla.`,
+    nothingMeasured: (dir) =>
+      `Todavía no hay nada medido (el almacén de ${dir} está vacío), así que la mitad de presupuesto de cada respuesta lo dirá. La mitad del coste sigue respondiendo desde el catálogo: sin conexión es un modo, no un fallo.`,
+    noBudget: () =>
+      'No hay spend.maxUsd configurado, así que "queda presupuesto" no tiene sujeto y cada respuesta lo dice en vez de inventarse uno.',
+    badPort: (value) => `"${value}" no es un puerto. Da un número entero de 0 a 65535, o usa --socket.`,
+  },
+
+  watch: {
+    noThresholds: () =>
+      'Vigilar necesita algo que vigilar. Define spend.maxUsd, spend.maxDayUsd o spend.maxCacheLossUsd en trazum.config.json — un vigilante sin umbral es una luz verde que nadie se ha ganado.',
+    nothingToWatch: (dir) =>
+      `Todavía no se ha medido nada: el almacén de ${dir} está vacío. Llénalo primero con "trazum connect <proveedor> --store" — vigilar la nada reportaría que todo está bien.`,
+    intervalTooTight: () =>
+      '--interval tiene que ser de al menos 5m. Las APIs de uso están limitadas por tasa, y un bucle apretado es una forma de que una herramienta que existe para ahorrarte dinero acabe estrangulando tu propia clave.',
+    badWebhook: (reason) =>
+      reason === 'credentials-in-url'
+        ? 'Esa URL de webhook lleva credenciales. Las URLs acaban en logs, historiales de shell y mensajes de error, así que se rechaza — pon el secreto en una cabecera que tu receptor compruebe, o en el propio receptor.'
+        : reason === 'insecure-scheme'
+          ? 'Un webhook tiene que ser https, salvo en loopback. Una alerta lleva tus cifras de gasto, y mandarlas en claro por una red es una fuga que no pediste.'
+          : 'Ese webhook no es una URL que esta herramienta pueda parsear.',
+    crossed: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'El gasto total'
+          : gate === 'maxDayUsd'
+            ? `El gasto del ${day}`
+            : 'El dinero perdido con la caché';
+      return `CRUZADO — ${what} es ${measured} contra un límite de ${limit}. Medido, no proyectado.`;
+    },
+    stillOver: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'El gasto total'
+          : gate === 'maxDayUsd'
+            ? `El gasto del ${day}`
+            : 'El dinero perdido con la caché';
+      return `SIGUE POR ENCIMA — ${what} es ${measured} contra un límite de ${limit}, y ya se avisó. Callado no es limpio.`;
+    },
+    notJudgeable: (gate, reason, covered) =>
+      reason === 'window-too-short'
+        ? `${gate} todavía no se puede juzgar: este período está medido al ${covered ?? 'parcialmente'}, y un umbral sobre parte de un día es un umbral sobre otra cosa. No es un aprobado — se juzgará cuando el día esté completo.`
+        : `${gate} no se puede juzgar en esta fuente, que no sirve aquello sobre lo que está escrito el gate. No es un aprobado: un gate saltado en silencio se lee exactamente igual que un gate que lleva tiempo pasando.`,
+    gap: (from, to) =>
+      `Nada estuvo vigilando entre ${from} y ${to}. Lo que cruzara en ese tramo no se vio, y esta línea existe para que un vigilante reanudado no insinúe una cobertura que no tuvo.`,
+    allWithin: (gates) => `Dentro de todos los umbrales: ${gates} gates evaluados contra gasto medido.`,
+    webhookFailed: (status) =>
+      `El webhook no se entregó (${status}). El cruce sigue en el código de salida y en la salida de arriba — que un receptor esté caído no puede ser el fallo más silencioso de la sala.`,
+    watching: (minutes) => `Vigilando cada ${minutes} minutos. Ctrl-C lo para.`,
+  },
+
   store: {
     appended: (count, dir) => `Guardadas ${count} mediciones en ${dir}.`,
     empty: (dir) =>