@bounded-sh/observe 0.1.0

package/dist/intercept/http.js

@@ -0,0 +1,262 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// intercept/http.ts -- http/https.request + .get interception (SPEC §3.1a).
+//
+// Same invariants as the fetch interceptor: the original call ALWAYS goes
+// through with its original semantics; observation failures are swallowed;
+// X-Bounded-* headers are stripped from egress (options.headers in place —
+// they must not leave the process — plus a setHeader guard on the returned
+// ClientRequest); ingest self-traffic is skipped.
+//
+// Notes (documented): status/duration are recorded at response-HEADERS time;
+// bytes.o comes from Content-Length (0 when chunked). Response bodies are
+// never read on this path (no token counts via http/https — fetch-based SDKs
+// get those), so recognized-field extraction here covers request bodies only.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchHttp = patchHttp;
+exports.unpatchHttp = unpatchHttp;
+const context_1 = require("../context");
+const state_1 = require("../state");
+const BOUNDED_HEADER_RE = /^x-bounded-/i;
+const BODY_CAP = 32 * 1024;
+const patchedModules = [];
+function aliasHost(host) {
+    return state_1.state.config?.aliasHosts?.[host] ?? host;
+}
+function noteBoundedHeader(acc, name, value) {
+    const n = name.toLowerCase();
+    const v = Array.isArray(value) ? String(value[0]) : String(value);
+    if (n === "x-bounded-actor")
+        acc.id = v;
+    else if (n === "x-bounded-actor-kind")
+        acc.kind = v;
+    else if (n === "x-bounded-on-behalf-of")
+        acc.onBehalfOf = v;
+}
+function headerActorToContext(acc) {
+    if (!acc.id)
+        return undefined;
+    const kind = acc.kind === "human" || acc.kind === "agent" || acc.kind === "service" ? acc.kind : "unknown";
+    const ctx = { id: acc.id.slice(0, 256), kind };
+    if (acc.onBehalfOf)
+        ctx.onBehalfOf = acc.onBehalfOf.slice(0, 256);
+    return ctx;
+}
+/** Strip X-Bounded-* from an options.headers object IN PLACE (must not egress). */
+function stripOptionHeaders(headers, acc) {
+    if (!headers || typeof headers !== "object")
+        return;
+    for (const k of Object.keys(headers)) {
+        if (BOUNDED_HEADER_RE.test(k)) {
+            noteBoundedHeader(acc, k, headers[k]);
+            delete headers[k];
+        }
+    }
+}
+function headerLookup(headers, name) {
+    if (!headers)
+        return undefined;
+    for (const k of Object.keys(headers)) {
+        if (k.toLowerCase() === name) {
+            const v = headers[k];
+            return Array.isArray(v) ? String(v[0]) : String(v);
+        }
+    }
+    return undefined;
+}
+/** Normalize http.request's polymorphic args into capture metadata. */
+function preprocess(args, defaultProtocol) {
+    let url;
+    let options;
+    const a0 = args[0];
+    if (typeof a0 === "string")
+        url = new URL(a0);
+    else if (a0 instanceof URL)
+        url = a0;
+    else if (a0 && typeof a0 === "object")
+        options = a0;
+    if (url && args[1] && typeof args[1] === "object" && typeof args[1] !== "function") {
+        options = args[1];
+    }
+    // Host resolution: options override url parts (Node merge semantics).
+    const hostname = options?.hostname ??
+        options?.host?.split(":")[0] ??
+        url?.hostname ??
+        "localhost";
+    const protocol = (options?.protocol ?? url?.protocol ?? defaultProtocol).toLowerCase();
+    const defaultPort = protocol === "https:" ? "443" : "80";
+    const port = String(options?.port ?? url?.port ?? "") || defaultPort;
+    const rawHost = port === defaultPort ? hostname : `${hostname}:${port}`;
+    const host = aliasHost(rawHost);
+    if (rawHost === state_1.state.ingestHost || host === state_1.state.ingestHost)
+        return undefined;
+    const fullPath = options?.path ?? (url ? url.pathname + url.search : "/");
+    const qIdx = fullPath.indexOf("?");
+    const path = qIdx === -1 ? fullPath : fullPath.slice(0, qIdx);
+    let queryNames;
+    if (qIdx !== -1) {
+        try {
+            queryNames = [...new URLSearchParams(fullPath.slice(qIdx + 1)).keys()].slice(0, 64);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const method = (options?.method ?? "GET").toUpperCase();
+    const acc = {};
+    const headers = options?.headers;
+    stripOptionHeaders(headers, acc);
+    const contentLength = Number(headerLookup(headers, "content-length"));
+    return {
+        host,
+        path,
+        queryNames,
+        method,
+        actor: (0, context_1.currentActor)() ?? headerActorToContext(acc),
+        contentType: headerLookup(headers, "content-type"),
+        bytesInHeader: Number.isFinite(contentLength) && contentLength > 0 ? contentLength : 0,
+        captureBody: method !== "GET" && method !== "HEAD" && state_1.state.manifest.captureHosts.has(host),
+        ts: Date.now(),
+    };
+}
+function instrument(req, meta) {
+    const start = performance.now();
+    let bodyText = "";
+    let bodyBytes = 0;
+    let finalized = false;
+    const chunkText = (chunk) => {
+        try {
+            if (typeof chunk === "string") {
+                bodyBytes += Buffer.byteLength(chunk);
+                if (meta.captureBody && bodyText.length < BODY_CAP)
+                    bodyText += chunk.slice(0, BODY_CAP - bodyText.length);
+            }
+            else if (chunk instanceof Uint8Array) {
+                bodyBytes += chunk.byteLength;
+                if (meta.captureBody && bodyText.length < BODY_CAP) {
+                    bodyText += Buffer.from(chunk.buffer, chunk.byteOffset, Math.min(chunk.byteLength, BODY_CAP - bodyText.length)).toString("utf8");
+                }
+            }
+        }
+        catch {
+            /* body capture is best-effort */
+        }
+    };
+    // Wrap write/end to observe body bytes; pass EVERYTHING through untouched.
+    const origWrite = req.write.bind(req);
+    const origEnd = req.end.bind(req);
+    req.write = function boundedWrite(chunk, ...rest) {
+        chunkText(chunk);
+        return origWrite(chunk, ...rest);
+    };
+    req.end = function boundedEnd(chunk, ...rest) {
+        if (chunk !== undefined && typeof chunk !== "function")
+            chunkText(chunk);
+        return origEnd(chunk, ...rest);
+    };
+    // Late header injection guard: X-Bounded-* set after creation never egress
+    // (still used for attribution fallback).
+    const origSetHeader = req.setHeader.bind(req);
+    const lateActor = {};
+    req.setHeader = function boundedSetHeader(name, value) {
+        if (typeof name === "string" && BOUNDED_HEADER_RE.test(name)) {
+            noteBoundedHeader(lateActor, name, value);
+            if (!meta.actor)
+                meta.actor = headerActorToContext(lateActor);
+            return req;
+        }
+        return origSetHeader(name, value);
+    };
+    const finalize = (status, bytesOut) => {
+        if (finalized)
+            return;
+        finalized = true;
+        try {
+            const raw = {
+                ts: meta.ts,
+                host: meta.host,
+                path: meta.path,
+                queryNames: meta.queryNames,
+                method: meta.method,
+                status,
+                durMs: performance.now() - start,
+                bytesIn: meta.bytesInHeader > 0 ? meta.bytesInHeader : bodyBytes,
+                bytesOut,
+                actor: meta.actor,
+                reqBodyText: meta.captureBody && bodyText.length > 0 ? bodyText : undefined,
+                reqContentType: meta.contentType,
+            };
+            state_1.state.pipeline?.enqueueRaw(raw);
+        }
+        catch (err) {
+            (0, state_1.noteInternalError)("http.finalize", err);
+        }
+    };
+    req.on("response", (res) => {
+        try {
+            const cl = Number(res.headers["content-length"]);
+            finalize(res.statusCode ?? 0, Number.isFinite(cl) && cl > 0 ? cl : 0);
+        }
+        catch (err) {
+            (0, state_1.noteInternalError)("http.response", err);
+        }
+    });
+    req.on("error", () => finalize(0, 0));
+}
+function patchModule(mod, defaultProtocol) {
+    const asAny = mod;
+    if (asAny.__boundedPatched)
+        return;
+    const origRequest = mod.request;
+    const origGet = mod.get;
+    patchedModules.push({ mod, origRequest, origGet });
+    const patchedRequest = function boundedRequest(...args) {
+        if (!state_1.state.enabled)
+            return origRequest.apply(this, args);
+        let meta;
+        try {
+            meta = preprocess(args, defaultProtocol);
+        }
+        catch (err) {
+            (0, state_1.noteInternalError)("http.preprocess", err);
+            meta = undefined;
+        }
+        const req = origRequest.apply(this, args);
+        if (meta) {
+            try {
+                instrument(req, meta);
+            }
+            catch (err) {
+                (0, state_1.noteInternalError)("http.instrument", err);
+            }
+        }
+        return req;
+    };
+    // Node's http.get calls the module-local request, so it must be patched too.
+    const patchedGet = function boundedGet(...args) {
+        const req = patchedRequest.apply(this, args);
+        req.end();
+        return req;
+    };
+    asAny.request = patchedRequest;
+    asAny.get = patchedGet;
+    asAny.__boundedPatched = true;
+}
+function patchHttp() {
+    // Lazy require so the module graph stays clean for fetch-only runtimes.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const http = require("node:http");
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const https = require("node:https");
+    patchModule(http, "http:");
+    patchModule(https, "https:");
+}
+function unpatchHttp() {
+    for (const p of patchedModules.splice(0)) {
+        const asAny = p.mod;
+        asAny.request = p.origRequest;
+        asAny.get = p.origGet;
+        delete asAny.__boundedPatched;
+    }
+}

package/dist/llm-prices.d.ts

@@ -0,0 +1,136 @@
+/** Bump on ANY edit to MODEL_PRICES OR the estimate formula (content version,
+ * mirrored byte-identically in org-api rails/llm-gateway.ts). */
+export declare const PRICE_TABLE_VERSION = "llm-prices-2026-07-05b";
+export interface ModelPrice {
+    /** USD per 1M input tokens. */
+    inputPerMTok: number;
+    /** USD per 1M output tokens. */
+    outputPerMTok: number;
+    /** Model max output tokens — the fallback ceiling when a request omits a cap. */
+    maxOutputTokens: number;
+}
+/**
+ * Per-model prices in USD per 1M tokens. Anthropic numbers are verified against
+ * the claude-api reference (cached 2026-05-26). OpenAI numbers are VERSIONED
+ * DATA present so a known OpenAI model resolves — OpenAI prices change often; do
+ * not trust them from memory, verify before prod. Any model NOT in this table
+ * resolves to the conservative ceiling (see resolveModelPrice) so estCents is
+ * always a real upper bound, never $0.
+ */
+export declare const MODEL_PRICES: Record<string, ModelPrice>;
+/** The conservative ceiling used for an unrecognized model (fail-closed, T9). */
+export declare const CEILING_PRICE: ModelPrice;
+/** Coarse chars-per-token used to estimate INPUT tokens from the request body
+ * BYTE length only (never its content). Deliberately low so the estimate leans
+ * high (conservative). Output cost — the dominant, 5×-priced component — is
+ * hard-bounded by the request's own max-tokens cap, so the input coarseness is
+ * a minor fraction of the reservation. */
+export declare const CHARS_PER_TOKEN = 3.5;
+/** Floor for the coarse INPUT-token estimate: even a tiny request body reserves
+ * at least this many input tokens (a real call always carries a system prompt,
+ * tool schemas, and JSON framing the byte heuristic undercounts). Conservative —
+ * it only ever RAISES the estimate, never lowers it. */
+export declare const MIN_INPUT_TOKENS = 512;
+/** Prompt-cache WRITE multiplier applied to the ESTIMATE's input tokens: the most
+ * expensive way the actual input can be billed (cache creation ~1.25× base). So
+ * estCents stays an upper bound even when the call opts into cache writes. */
+export declare const INPUT_CACHE_WRITE_MULT = 1.25;
+export interface ResolvedPrice {
+    /** The table key matched (or the raw model when it fell through to ceiling). */
+    key: string;
+    price: ModelPrice;
+    /** false ⇒ unrecognized model, priced at the ceiling. */
+    known: boolean;
+}
+/**
+ * Resolve a model id to a price. Exact match wins; otherwise the LONGEST table
+ * key the model starts with (so "gpt-4o-2024-08-06" → "gpt-4o", a dated
+ * Anthropic snapshot → its base). Unrecognized ⇒ the conservative ceiling.
+ */
+export declare function resolveModelPrice(model: string | undefined): ResolvedPrice;
+/** Cost in cents for `tokens` at `usdPerMTok` (USD/1M → cents): t·price/10000. */
+export declare function centsForTokens(tokens: number, usdPerMTok: number): number;
+export interface UpperBoundInput {
+    model: string | undefined;
+    /** The request's output-token cap; when absent/0 the model ceiling is used. */
+    maxTokensReq?: number;
+    /** Coarse input-token estimate (from body byte length). */
+    approxInputTokens?: number;
+    /** openai `n` / `best_of` — the provider bills output for EACH sampled
+     *  completion, so the estimate multiplies the OUTPUT component by
+     *  max(n, best_of, 1). Absent ⇒ 1 (anthropic messages has no such knob). */
+    n?: number;
+}
+export interface UpperBoundResult {
+    estCents: number;
+    /** Resolved table key (or the raw model when priced at the ceiling). */
+    model: string;
+    modelKnown: boolean;
+    /** The output-token count the estimate was priced against (per completion). */
+    outputTokensBound: number;
+    /** Completions the output cost was multiplied by (max(n, best_of, 1)). */
+    completions: number;
+    /** "known" (model priced from the table) or "ceiling" (unknown → conservative). */
+    basis: "known" | "ceiling";
+    /** Set when the model was unrecognized and priced at the ceiling (fail-closed). */
+    estFlag?: "unknown_model";
+}
+/**
+ * estCents = UPPER BOUND on the call's cost at verdict time. Composition:
+ *   output = cap (or model ceiling) × max(n, best_of, 1) × output rate   [HARD bound]
+ *   input  = max(bodyBytes÷3.5, MIN_INPUT_TOKENS) × 1.25 × input rate    [heuristic]
+ * Math.ceil so it never rounds below a plausible actual; never < 1 cent for a
+ * real call (unknown model ⇒ ceiling, fail-closed). See the file header for
+ * exactly which inputs bound the estimate and which do not.
+ */
+export declare function estimateUpperBoundCents(input: UpperBoundInput): UpperBoundResult;
+export interface UsageInput {
+    model: string | undefined;
+    inputTokens?: number;
+    outputTokens?: number;
+    /** Anthropic prompt-cache write tokens (billed ~1.25× input). */
+    cacheCreationInputTokens?: number;
+    /** Anthropic/OpenAI prompt-cache read tokens (billed ~0.1× input). */
+    cacheReadInputTokens?: number;
+}
+export interface ActualResult {
+    actualCents: number;
+    model: string;
+    modelKnown: boolean;
+}
+/**
+ * Read a provider RESPONSE body (OpenAI chat/completions or Anthropic messages
+ * shape) into a UsageInput for settle-time actual-cost. Model comes from the
+ * response's own `model` echo (both providers include it); when absent the
+ * actual is priced at the ceiling (conservative — org-api then keeps the lower
+ * reservation). Byte-for-byte mirror of org-api rails/llm-gateway.ts readUsage's
+ * token mapping. Returns undefined when there is no usage to price. */
+export declare function usageFromResponse(body: unknown): UsageInput | undefined;
+/**
+ * ACTUAL (settle-time) cost from a response's usage. Accounts for prompt-cache
+ * write (~1.25×) and read (~0.1×) tokens when present. Uses Math.round; for the
+ * common no-cache case actualCents ≤ estimateUpperBoundCents when the usage's
+ * tokens are within the verdict-time bounds (see the monotonicity test).
+ */
+export declare function actualCentsFromUsage(u: UsageInput): ActualResult;
+/** Read the output-token cap for a route action from a parsed request body.
+ * OpenAI's cap is optional and inconsistently named; Anthropic requires it. */
+export declare function extractMaxTokensReq(body: Record<string, unknown>, action: string): number | undefined;
+/** Coarse INPUT-token estimate from the request body BYTE length (not content). */
+export declare function approxInputTokensFromBody(bodyText: string | undefined): number;
+/** Completion count the provider will bill output for: openai `n` (choices) and
+ * legacy `best_of` (samples). max(n, best_of, 1). Anthropic messages has no such
+ * knob → 1. Read from the request the app ALREADY built (metadata only). */
+export declare function extractCompletions(body: Record<string, unknown>, action: string): number;
+export interface LlmIntentFields {
+    model: string;
+    maxTokensReq: number;
+    estCents: number;
+}
+/**
+ * Build the llm-gateway intent fields {model, maxTokensReq, estCents} from the
+ * request the app ALREADY built (metadata only). Called by the shim escort at
+ * verdict time (escort.ts buildIntentFields) for rail === "llm-gateway".
+ * Returns undefined when there is no usable model (no spend to reserve).
+ */
+export declare function buildLlmIntentFields(body: Record<string, unknown> | undefined, action: string, bodyText: string | undefined): LlmIntentFields | undefined;

package/dist/llm-prices.js

@@ -0,0 +1,240 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// llm-prices.ts -- the shim-side static price table + spend estimator for the
+// llm-gateway rail (SPEC §4.3 V1 rail; Track C).
+//
+// This is a VERSIONED, content-addressed artifact (like a policyVersion): every
+// edit MUST bump PRICE_TABLE_VERSION. A mirror copy lives in the enforcement
+// worker at packages/cdk/cloudflare/bounded-org-api/src/rails/llm-gateway.ts —
+// the two tables MUST stay byte-identical (same models, same numbers, same
+// version string). Drift is a bug: the shim reserves estCents at verdict time
+// and the worker reports actual usage-cents at settle; if the tables disagree,
+// the settle "decrease" could become an increase.
+//
+// Determinism: pure integer/float math, no wall clock, no LLM (T3). The shim
+// NEVER reads message content. What the estimate reads from the request the app
+// ALREADY built: `model`, the output-token cap (max_tokens /
+// max_completion_tokens / max_output_tokens), the completion count (openai
+// `n` / `best_of`), and a COARSE input-token estimate from the request body
+// BYTE LENGTH (never its content).
+//
+// WHAT estCents BOUNDS (be honest — SPEC T9):
+//   • OUTPUT cost is HARD-BOUNDED: cap (or the model's max-output ceiling when the
+//     request omits one) × max(n, best_of, 1) × the model's output rate. The
+//     provider cannot bill more output than the cap it was handed, per completion.
+//     This is the dominant, up-to-5×-priced component.
+//   • INPUT cost is a HEURISTIC upper estimate, NOT a hard bound: body-bytes ÷ 3.5
+//     (chars/token leans high), floored at MIN_INPUT_TOKENS so a tiny body still
+//     reserves realistic input, then priced at 1.25× the input rate (the prompt-
+//     cache WRITE worst case). This bounds the tokens IMPLIED BY THE REQUEST BODY;
+//     it does NOT bound input the provider adds server-side that is not in the body
+//     (e.g. a gateway-injected system prompt or retrieved tool results appended
+//     downstream). In the common case the reservation is dominated by the hard
+//     output bound.
+//   • Unknown model → the table CEILING (max rate across the table) + estFlag
+//     "unknown_model"; never $0 (fail-closed).
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INPUT_CACHE_WRITE_MULT = exports.MIN_INPUT_TOKENS = exports.CHARS_PER_TOKEN = exports.CEILING_PRICE = exports.MODEL_PRICES = exports.PRICE_TABLE_VERSION = void 0;
+exports.resolveModelPrice = resolveModelPrice;
+exports.centsForTokens = centsForTokens;
+exports.estimateUpperBoundCents = estimateUpperBoundCents;
+exports.usageFromResponse = usageFromResponse;
+exports.actualCentsFromUsage = actualCentsFromUsage;
+exports.extractMaxTokensReq = extractMaxTokensReq;
+exports.approxInputTokensFromBody = approxInputTokensFromBody;
+exports.extractCompletions = extractCompletions;
+exports.buildLlmIntentFields = buildLlmIntentFields;
+/** Bump on ANY edit to MODEL_PRICES OR the estimate formula (content version,
+ * mirrored byte-identically in org-api rails/llm-gateway.ts). */
+exports.PRICE_TABLE_VERSION = "llm-prices-2026-07-05b";
+/**
+ * Per-model prices in USD per 1M tokens. Anthropic numbers are verified against
+ * the claude-api reference (cached 2026-05-26). OpenAI numbers are VERSIONED
+ * DATA present so a known OpenAI model resolves — OpenAI prices change often; do
+ * not trust them from memory, verify before prod. Any model NOT in this table
+ * resolves to the conservative ceiling (see resolveModelPrice) so estCents is
+ * always a real upper bound, never $0.
+ */
+exports.MODEL_PRICES = {
+    // ── Anthropic (api.anthropic.com/v1/messages) ─────────────────────────────
+    "claude-fable-5": { inputPerMTok: 10, outputPerMTok: 50, maxOutputTokens: 128_000 },
+    "claude-opus-4-8": { inputPerMTok: 5, outputPerMTok: 25, maxOutputTokens: 128_000 },
+    "claude-opus-4-7": { inputPerMTok: 5, outputPerMTok: 25, maxOutputTokens: 128_000 },
+    "claude-opus-4-6": { inputPerMTok: 5, outputPerMTok: 25, maxOutputTokens: 128_000 },
+    "claude-opus-4-5": { inputPerMTok: 5, outputPerMTok: 25, maxOutputTokens: 64_000 },
+    "claude-sonnet-4-6": { inputPerMTok: 3, outputPerMTok: 15, maxOutputTokens: 64_000 },
+    "claude-haiku-4-5": { inputPerMTok: 1, outputPerMTok: 5, maxOutputTokens: 64_000 },
+    // ── OpenAI (api.openai.com) — VERSIONED DATA, verify before prod ───────────
+    "gpt-4o": { inputPerMTok: 2.5, outputPerMTok: 10, maxOutputTokens: 16_384 },
+    "gpt-4o-mini": { inputPerMTok: 0.15, outputPerMTok: 0.6, maxOutputTokens: 16_384 },
+    "gpt-4.1": { inputPerMTok: 2, outputPerMTok: 8, maxOutputTokens: 32_768 },
+    "gpt-4.1-mini": { inputPerMTok: 0.4, outputPerMTok: 1.6, maxOutputTokens: 32_768 },
+};
+/** The conservative ceiling used for an unrecognized model (fail-closed, T9). */
+exports.CEILING_PRICE = {
+    inputPerMTok: Math.max(...Object.values(exports.MODEL_PRICES).map((p) => p.inputPerMTok)),
+    outputPerMTok: Math.max(...Object.values(exports.MODEL_PRICES).map((p) => p.outputPerMTok)),
+    maxOutputTokens: Math.max(...Object.values(exports.MODEL_PRICES).map((p) => p.maxOutputTokens)),
+};
+/** Coarse chars-per-token used to estimate INPUT tokens from the request body
+ * BYTE length only (never its content). Deliberately low so the estimate leans
+ * high (conservative). Output cost — the dominant, 5×-priced component — is
+ * hard-bounded by the request's own max-tokens cap, so the input coarseness is
+ * a minor fraction of the reservation. */
+exports.CHARS_PER_TOKEN = 3.5;
+/** Floor for the coarse INPUT-token estimate: even a tiny request body reserves
+ * at least this many input tokens (a real call always carries a system prompt,
+ * tool schemas, and JSON framing the byte heuristic undercounts). Conservative —
+ * it only ever RAISES the estimate, never lowers it. */
+exports.MIN_INPUT_TOKENS = 512;
+/** Prompt-cache WRITE multiplier applied to the ESTIMATE's input tokens: the most
+ * expensive way the actual input can be billed (cache creation ~1.25× base). So
+ * estCents stays an upper bound even when the call opts into cache writes. */
+exports.INPUT_CACHE_WRITE_MULT = 1.25;
+/**
+ * Resolve a model id to a price. Exact match wins; otherwise the LONGEST table
+ * key the model starts with (so "gpt-4o-2024-08-06" → "gpt-4o", a dated
+ * Anthropic snapshot → its base). Unrecognized ⇒ the conservative ceiling.
+ */
+function resolveModelPrice(model) {
+    const m = (model || "").trim();
+    if (m && Object.prototype.hasOwnProperty.call(exports.MODEL_PRICES, m)) {
+        return { key: m, price: exports.MODEL_PRICES[m], known: true };
+    }
+    let best = null;
+    for (const key of Object.keys(exports.MODEL_PRICES)) {
+        if (m.startsWith(key) && (best === null || key.length > best.length))
+            best = key;
+    }
+    if (best)
+        return { key: best, price: exports.MODEL_PRICES[best], known: true };
+    return { key: m || "unknown", price: exports.CEILING_PRICE, known: false };
+}
+/** Cost in cents for `tokens` at `usdPerMTok` (USD/1M → cents): t·price/10000. */
+function centsForTokens(tokens, usdPerMTok) {
+    if (!Number.isFinite(tokens) || tokens <= 0)
+        return 0;
+    return (tokens * usdPerMTok) / 10_000;
+}
+/**
+ * estCents = UPPER BOUND on the call's cost at verdict time. Composition:
+ *   output = cap (or model ceiling) × max(n, best_of, 1) × output rate   [HARD bound]
+ *   input  = max(bodyBytes÷3.5, MIN_INPUT_TOKENS) × 1.25 × input rate    [heuristic]
+ * Math.ceil so it never rounds below a plausible actual; never < 1 cent for a
+ * real call (unknown model ⇒ ceiling, fail-closed). See the file header for
+ * exactly which inputs bound the estimate and which do not.
+ */
+function estimateUpperBoundCents(input) {
+    const { key, price, known } = resolveModelPrice(input.model);
+    const cap = input.maxTokensReq && input.maxTokensReq > 0 ? Math.round(input.maxTokensReq) : price.maxOutputTokens;
+    // Coarse input estimate, floored so a tiny body still reserves realistic input.
+    const approx = input.approxInputTokens && input.approxInputTokens > 0 ? Math.round(input.approxInputTokens) : 0;
+    const inTokens = Math.max(approx, exports.MIN_INPUT_TOKENS);
+    // Output bills per sampled completion (openai n / best_of); >= 1.
+    const completions = Math.max(1, Math.round(input.n && input.n > 0 ? input.n : 1));
+    const cents = centsForTokens(inTokens, price.inputPerMTok * exports.INPUT_CACHE_WRITE_MULT) +
+        centsForTokens(cap, price.outputPerMTok) * completions;
+    const estCents = Math.max(1, Math.ceil(cents));
+    return {
+        estCents,
+        model: key,
+        modelKnown: known,
+        outputTokensBound: cap,
+        completions,
+        basis: known ? "known" : "ceiling",
+        ...(known ? {} : { estFlag: "unknown_model" }),
+    };
+}
+/**
+ * Read a provider RESPONSE body (OpenAI chat/completions or Anthropic messages
+ * shape) into a UsageInput for settle-time actual-cost. Model comes from the
+ * response's own `model` echo (both providers include it); when absent the
+ * actual is priced at the ceiling (conservative — org-api then keeps the lower
+ * reservation). Byte-for-byte mirror of org-api rails/llm-gateway.ts readUsage's
+ * token mapping. Returns undefined when there is no usage to price. */
+function usageFromResponse(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    const b = body;
+    const u = b.usage && typeof b.usage === "object" ? b.usage : undefined;
+    if (!u)
+        return undefined;
+    const n = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+    const details = (v) => v && typeof v === "object" ? n(v.cached_tokens) : undefined;
+    return {
+        model: typeof b.model === "string" ? b.model : undefined,
+        // Anthropic: input_tokens/output_tokens; OpenAI: prompt_tokens/completion_tokens.
+        inputTokens: n(u.input_tokens) ?? n(u.prompt_tokens),
+        outputTokens: n(u.output_tokens) ?? n(u.completion_tokens),
+        cacheCreationInputTokens: n(u.cache_creation_input_tokens),
+        cacheReadInputTokens: n(u.cache_read_input_tokens) ?? details(u.prompt_tokens_details) ?? details(u.input_tokens_details),
+    };
+}
+/**
+ * ACTUAL (settle-time) cost from a response's usage. Accounts for prompt-cache
+ * write (~1.25×) and read (~0.1×) tokens when present. Uses Math.round; for the
+ * common no-cache case actualCents ≤ estimateUpperBoundCents when the usage's
+ * tokens are within the verdict-time bounds (see the monotonicity test).
+ */
+function actualCentsFromUsage(u) {
+    const { key, price, known } = resolveModelPrice(u.model);
+    const inCents = centsForTokens(u.inputTokens ?? 0, price.inputPerMTok) +
+        centsForTokens(u.cacheCreationInputTokens ?? 0, price.inputPerMTok * 1.25) +
+        centsForTokens(u.cacheReadInputTokens ?? 0, price.inputPerMTok * 0.1);
+    const outCents = centsForTokens(u.outputTokens ?? 0, price.outputPerMTok);
+    return { actualCents: Math.max(0, Math.round(inCents + outCents)), model: key, modelKnown: known };
+}
+/** Read the output-token cap for a route action from a parsed request body.
+ * OpenAI's cap is optional and inconsistently named; Anthropic requires it. */
+function extractMaxTokensReq(body, action) {
+    const a = (action || "").toLowerCase();
+    const num = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.round(v) : undefined;
+    if (a.startsWith("anthropic."))
+        return num(body["max_tokens"]);
+    if (a === "openai.responses.create")
+        return num(body["max_output_tokens"]);
+    if (a === "openai.chat.completions.create")
+        return num(body["max_completion_tokens"]) ?? num(body["max_tokens"]);
+    // openai.completions.create (legacy), and any other openai.* fallback.
+    return num(body["max_tokens"]) ?? num(body["max_completion_tokens"]) ?? num(body["max_output_tokens"]);
+}
+/** Coarse INPUT-token estimate from the request body BYTE length (not content). */
+function approxInputTokensFromBody(bodyText) {
+    if (!bodyText)
+        return 0;
+    return Math.ceil(bodyText.length / exports.CHARS_PER_TOKEN);
+}
+/** Completion count the provider will bill output for: openai `n` (choices) and
+ * legacy `best_of` (samples). max(n, best_of, 1). Anthropic messages has no such
+ * knob → 1. Read from the request the app ALREADY built (metadata only). */
+function extractCompletions(body, action) {
+    const a = (action || "").toLowerCase();
+    if (a.startsWith("anthropic."))
+        return 1;
+    const num = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.round(v) : 1;
+    return Math.max(num(body["n"]), num(body["best_of"]), 1);
+}
+/**
+ * Build the llm-gateway intent fields {model, maxTokensReq, estCents} from the
+ * request the app ALREADY built (metadata only). Called by the shim escort at
+ * verdict time (escort.ts buildIntentFields) for rail === "llm-gateway".
+ * Returns undefined when there is no usable model (no spend to reserve).
+ */
+function buildLlmIntentFields(body, action, bodyText) {
+    if (!body)
+        return undefined;
+    const model = typeof body["model"] === "string" ? body["model"].slice(0, 128) : "";
+    if (!model)
+        return undefined;
+    const maxTokensReq = extractMaxTokensReq(body, action);
+    const approxInputTokens = approxInputTokensFromBody(bodyText);
+    const n = extractCompletions(body, action);
+    const est = estimateUpperBoundCents({ model, maxTokensReq, approxInputTokens, n });
+    return {
+        model,
+        // 0 signals "capped at the model ceiling" (request omitted a limit).
+        maxTokensReq: maxTokensReq ?? 0,
+        estCents: est.estCents,
+    };
+}