@trazum/cli 1.43.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.43.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.43.0"
+    "@trazum/core": "1.44.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -45,6 +45,7 @@ ${bold('USAGE')}
   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]
@@ -322,6 +323,29 @@ ${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.
@@ -1536,6 +1560,19 @@ ${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.',

package/src/i18n/es.ts

@@ -32,6 +32,7 @@ ${bold('USO')}
   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]
@@ -329,6 +330,32 @@ ${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
@@ -1563,6 +1590,19 @@ ${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.',

package/src/i18n/types.ts

@@ -1072,6 +1072,23 @@ export interface CliMessages {
     wrote(path: string): string;
   };
 
+  /**
+   * `trazum serve` — the answer given before the call is sent.
+   *
+   * The copy states the two things a reader must not have to infer: that this
+   * listens on loopback and nowhere else, and that the measured half is read
+   * once rather than being current to the second.
+   */
+  serve: {
+    listening(where: string): string;
+    /** Why there is no --host, and why that is not an omission. */
+    loopbackOnly(): string;
+    measuredFrom(usd: string): string;
+    nothingMeasured(dir: string): string;
+    noBudget(): string;
+    badPort(value: string): string;
+  };
+
   /**
    * `trazum watch` — the gates, evaluated as the money moves.
    *

package/src/index.ts

@@ -148,6 +148,7 @@ import {
 import type { Revision } from './git.js';
 import { fetchProviderUsage } from './connect.js';
 import { STORE_DIR, appendRecords, readStore, rewriteStore } from './store-fs.js';
+import { DEFAULT_PORT, buildServer, listen } from './serve.js';
 import {
   WATCH_STATE_VERSION,
   checkWebhook,
@@ -207,6 +208,8 @@ const VALUE_FLAGS = new Set([
   'keep',
   'interval',
   'webhook',
+  'port',
+  'socket',
   // `route` takes a path here, and the flag is deliberately not `--prompt`:
   // everywhere else in this tool `--prompt` names a marked prompt *inside* a
   // source file, and reusing it for a path would be a trap laid for the reader.
@@ -513,6 +516,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   connect: ['since', 'until', 'payload', 'store', 'json', 'out', 'markdown-out', 'pricing', 'pricing-live', 'dry-run'],
   store: ['prune', 'keep', 'json', 'pricing', 'pricing-live', 'dry-run'],
   watch: ['once', 'interval', 'since', 'payload', 'webhook', 'json', 'pricing', 'pricing-live'],
+  serve: ['port', 'socket', 'pricing', 'pricing-live'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2294,6 +2298,78 @@ function parseWhen(
   throw new Error(t.profile.badWhen(flag, value));
 }
 
+/**
+ * `trazum serve` — the answer in milliseconds.
+ *
+ * The measured position is read once at start rather than per request: the
+ * whole promise is a single-digit-millisecond answer, and a file read in the
+ * hot path cannot make it. That staleness is real, so every answer carries the
+ * window its measurement covers instead of implying it is current to the
+ * second.
+ */
+async function commandServe(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const root = process.cwd();
+  const limitUsd = config.spend?.maxUsd;
+
+  const { resolved } = await readStore(root);
+  const measured = resolved.records.length > 0;
+  /**
+   * The window the measurement covers, carried into every answer.
+   *
+   * The position is read once at start, so a caller has to be able to see how
+   * old it is. A null window here would let a figure from last month read as
+   * current, which is the staleness this endpoint is otherwise honest about.
+   */
+  const window = measured
+    ? {
+        fromMs: Math.min(...resolved.records.map((record) => record.fromMs)),
+        toMs: Math.max(...resolved.records.map((record) => record.toMs)),
+      }
+    : null;
+  const report = bucketedProfile(
+    {
+      provider: 'store',
+      granularity: 'bucketed',
+      buckets: bucketsFromRecords(resolved.records),
+      window,
+      gaps: [],
+      unavailable: [],
+    },
+    { catalogue: pricing },
+  );
+
+  const server = buildServer({
+    catalogue: pricing,
+    position: () => ({
+      consumedUsd: measured ? report.total.totalUsd : undefined,
+      limitUsd,
+      window: report.span,
+    }),
+  });
+
+  const socket = stringFlag(args, 'socket');
+  const portRaw = stringFlag(args, 'port');
+  const port = portRaw === undefined ? DEFAULT_PORT : Number(portRaw);
+  if (socket === undefined && (!Number.isInteger(port) || port < 0 || port > 65_535)) {
+    throw new Error(t.serve.badPort(String(portRaw)));
+  }
+
+  const where = await listen(server, socket !== undefined ? { socket } : { port });
+  console.log(c.bold(t.serve.listening(where)));
+  console.log(`  ${c.dim(wrap(t.serve.loopbackOnly(), 74, '    '))}`);
+  console.log(
+    `  ${c.dim(wrap(measured ? t.serve.measuredFrom(formatUsd(report.total.totalUsd)) : t.serve.nothingMeasured(STORE_DIR), 74, '    '))}`,
+  );
+  if (limitUsd === undefined) {
+    console.log(`  ${c.dim(wrap(t.serve.noBudget(), 74, '    '))}`);
+  }
+}
+
 /**
  * `trazum watch` — the afternoon it happened, said that afternoon.
  *
@@ -7088,6 +7164,9 @@ async function main(): Promise<void> {
     case 'watch':
       await commandWatch(args, config, pricing, t);
       break;
+    case 'serve':
+      await commandServe(args, config, pricing, t);
+      break;
     case 'route':
       await commandRoute(args, pricing, t);
       break;

package/src/serve.ts

@@ -0,0 +1,149 @@
+/**
+ * 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 type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { answerCost } from '@trazum/core';
+import type { CostAnswer, PricingCatalogue } 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;
+
+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 };
+}
+
+async function readBody(request: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  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 as Buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+const send = (response: ServerResponse, status: number, body: unknown): void => {
+  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: ServeContext): Server {
+  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: Record<string, unknown>;
+      try {
+        const raw = await readBody(request);
+        payload = raw.trim() === '' ? {} : (JSON.parse(raw) as Record<string, unknown>);
+      } 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: CostAnswer = 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 interface ListenTarget {
+  /** A Unix socket path, when the caller would rather not use a port. */
+  socket?: string;
+  port?: number;
+}
+
+export function listen(server: Server, target: ListenTarget): Promise<string> {
+  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));
+    });
+  });
+}