llm-relay 0.37.0 → 0.38.0

package/README.md

@@ -49,7 +49,8 @@ at login.
 - **Both API fronts** — Anthropic `/v1/messages` plus OpenAI `/v1/chat/completions` and
   `/v1/responses`, translated in either direction, streaming included.
 - **Local analytics dashboard** — `llm-relay dashboard` opens bounded request/attempt, token,
-  latency, provider/model/client/credential, quota, and cooldown views. Unknown or unavailable
+  spend, latency, provider/model/client/credential, quota, and cooldown views (spend priced only
+  from published prices; `llm-relay cost` rolls it up in a terminal). Unknown or unavailable
   accounting remains explicit; the dashboard never guesses a value or starts provider probes.
 - **Honest metadata** — per-deployment limits and prices with provenance, capability scores
   synced from four leaderboards, metadata-only logging, loopback-only binding.

package/config.example.json

@@ -5,7 +5,7 @@
       "base": "https://integrate.api.nvidia.com/v1",
       "kind": "openai",
       "credentials": [
-        { "label": "personal", "authEnv": "NVIDIA_API_KEY" },
+        { "label": "personal", "authEnv": "NVIDIA_API_KEY", "limits": { "rpm": 40, "rpd": 1000, "tpd": 150000 } },
         { "label": "work", "authEnv": "NVIDIA_WORK_API_KEY" }
       ],
       "tierType": "free"
@@ -81,6 +81,7 @@
       "claude": { "enabled": false, "scope": "subagents" },
       "codex": { "enabled": false, "scope": "subagents" }
     },
+    "quota": { "enforce": true },
     "sticky": false
   },
   "mode": "repair",

package/dist/accounting-store-schema.d.ts

@@ -1,4 +1,15 @@
-/** The persisted accounting format is deliberately separate from the dashboard wire format. */
+/**
+ * The persisted accounting format is deliberately separate from the dashboard wire format.
+ *
+ * SCHEMA NOTE (2026-08-22, Stage 4 spend): `spend` grew from a hard-typed `null` into real
+ * aggregate cells, and `requestSpend`/`partiallyPricedRequests` were added beside it as an
+ * optional pair. This is an ADDITIVE change and the schema constant stays `accounting.day.v1`:
+ * the guards below accept BOTH shapes — a pre-spend shard's `spend: null` loads as empty cells
+ * rather than quarantining a day of real traffic. Nothing rewrites old shards on read: the
+ * guards tolerate absence and every reader defaults it (`?? 0`, `mergeSpend(undefined)`), so a
+ * legacy shard reads correctly and gains the new fields only when new facts fold into it. A
+ * bump would have discarded every existing day shard for no gain.
+ */
 export declare const ACCOUNTING_STORE_VERSION: 1;
 export declare const ACCOUNTING_DAY_SCHEMA: "accounting.day.v1";
 export declare const ACCOUNTING_MINUTE_SCHEMA: "accounting.minute.v1";
@@ -71,6 +82,63 @@ export interface AccountingMetricCellV1 {
     readonly samplesDropped: number;
     readonly observedAt: string | null;
 }
+/**
+ * PER-MILLION prices actually used to compute one spend figure, carried so every
+ * amount stays re-derivable from its own record. Dollars-per-million-tokens equals
+ * micro-dollars-per-token, so `tokens x perMillionIn` IS the micro-USD amount.
+ */
+export interface AccountingSpendPricesV1 {
+    readonly perMillionIn: number | null;
+    readonly perMillionOut: number | null;
+}
+/**
+ * Coverage of ONE priced spend: which token kinds went into the amount and which
+ * rode beside it unpriced.
+ * - "full": every reported token kind was priced at a published price.
+ * - "input_only": estimated-basis pricing — estimated OUTPUT has no producer today,
+ *   so the amount covers input alone BY CONSTRUCTION and says so.
+ * - "partial": at least one present token kind was left out (cache kinds, or one of
+ *   in/out unpublished). The amount is a lower bound.
+ */
+export type AccountingSpendCoverage = "full" | "input_only" | "partial";
+/** Token kinds observed but NOT priced, per kind; null when the kind itself was absent. */
+export interface AccountingUnpricedTokensV1 {
+    readonly cacheRead: number | null;
+    readonly cacheCreation: number | null;
+    readonly cachedInput: number | null;
+}
+/**
+ * One attempt's spend in exact integer micro-USD with full provenance. `null` spend
+ * means UNPRICED (no published price resolved, or nothing to price) — never $0.
+ * Amounts are integer micro-USD, rounded half-up once per token kind, summed as
+ * integers, so no floating-point error can accumulate across requests.
+ */
+export interface AccountingSpendV1 {
+    readonly amountMicrousd: number;
+    readonly priceSource: "provider_published" | "reference";
+    readonly tokenBasis: "reported" | "estimated";
+    readonly source: "provider_reported" | "relay_estimated";
+    readonly coverage: AccountingSpendCoverage;
+    readonly unpricedTokens: AccountingUnpricedTokensV1;
+    readonly pricesUsed: AccountingSpendPricesV1;
+    readonly observedAt: string;
+}
+/** Summing accumulator behind one wire spend cell inside an aggregate. */
+export interface AccountingAggregateSpendCellV1 {
+    /** Sum of integer micro-USD contributions; null once any contributor is uncertain or it overflows. */
+    readonly amountMicrousd: number | null;
+    /** How many spends were summed into this cell. */
+    readonly known: number;
+    /** Latest observation across contributors; non-null exactly when known > 0. */
+    readonly observedAt: string | null;
+}
+/** The four price-source x token-basis cells one aggregate carries for its scope. */
+export interface AccountingAggregateSpendV1 {
+    readonly providerPublishedReported: AccountingAggregateSpendCellV1;
+    readonly providerPublishedEstimated: AccountingAggregateSpendCellV1;
+    readonly referenceReported: AccountingAggregateSpendCellV1;
+    readonly referenceEstimated: AccountingAggregateSpendCellV1;
+}
 export interface AccountingAggregateV1 {
     readonly requests: number;
     readonly attempts: number;
@@ -82,8 +150,26 @@ export interface AccountingAggregateV1 {
     readonly requestTokens: AccountingAggregateTokenTotalsV1;
     readonly latency: AccountingMetricCellV1;
     readonly commit: AccountingMetricCellV1;
-    /** Pricing is intentionally not guessed by the accounting layer. */
-    readonly spend: null;
+    /**
+     * Attempt-side spend cells: every completed attempt priced at PUBLISHED prices,
+     * summed as integers. `null` is the LEGACY pre-spend shape, tolerated on read and
+     * defaulted to empty cells by readers — it never means "zero spend".
+     */
+    readonly spend: AccountingAggregateSpendV1 | null;
+    /**
+     * Request-side spend cells (winning serve attempt only), kept apart from
+     * `spend` for the same reason `requestTokens` is kept apart from `tokens`:
+     * a retried-elsewhere request must not double-count its failed attempts.
+     * Absent entirely on legacy shards.
+     */
+    readonly requestSpend?: AccountingAggregateSpendV1 | null;
+    /**
+     * Requests whose spend figure exists but left present token kinds unpriced
+     * (cache kinds, or one of in/out unpublished) — i.e. every amount above is a
+     * lower bound while this is > 0. Absent (= 0) on legacy shards.
+     */
+    readonly partiallyPricedRequests?: number;
+    /** Requests with NO spend figure at all: unserved, or a deployment publishing no price. */
     readonly unpricedRequests: number;
 }
 interface AccountingDimensionRowBaseV1 extends AccountingAggregateV1 {
@@ -198,7 +284,8 @@ export interface AccountingAttemptPacketV1 {
     readonly model: string | null;
     readonly credentialId: string | null;
     readonly tokens: AccountingAggregateTokenTotalsV1;
-    readonly spend: null;
+    /** This attempt's priced spend, or LEGACY/absent. `null` = unpriced, never $0. */
+    readonly spend: AccountingSpendV1 | null;
 }
 export type AccountingAttemptPacket = AccountingAttemptPacketV1;
 export interface AccountingDetailAttemptMetadataV1 {
@@ -224,7 +311,12 @@ export interface AccountingRequestPacketV1 {
     readonly model: string | null;
     readonly credentialId: string | null;
     readonly tokens: AccountingAggregateTokenTotalsV1;
-    readonly spend: null;
+    /**
+     * The WINNING SERVE attempt's spend, mirroring `tokens`. Repair spend stays on
+     * its own attempt rows (C1) so a later `--include-repair` roll-up can add it
+     * back without double-counting the serve.
+     */
+    readonly spend: AccountingSpendV1 | null;
     readonly attempts: readonly AccountingAttemptPacketV1[];
     readonly attemptMetadata: AccountingDetailAttemptMetadataV1;
 }
@@ -284,6 +376,14 @@ export declare const parseAccountingRequestPacket: (value: unknown) => Accountin
 export declare const parseAccountingRecent: (value: unknown) => AccountingParseResult<AccountingRecentV1>;
 /** Checked addition for counters. null means the exact safe-integer domain overflowed. */
 export declare function checkedAddAccountingCounter(left: number, right: number): number | null;
+/**
+ * Sum two aggregate SPEND cells: integer micro-USD amounts, contributor counts,
+ * latest observation. Amounts stay null once any side is uncertain (overflow),
+ * mirroring how token cells degrade — a lost sum is never silently re-guessed.
+ */
+export declare function mergeAccountingSpendCells(left: AccountingAggregateSpendCellV1, right: AccountingAggregateSpendCellV1): AccountingAggregateSpendCellV1 | null;
+export declare function emptyAccountingSpendCell(): AccountingAggregateSpendCellV1;
+export declare function emptyAccountingAggregateSpend(): AccountingAggregateSpendV1;
 export declare function mergeAccountingTokenCells(left: AccountingAggregateTokenCellV1, right: AccountingAggregateTokenCellV1): AccountingAggregateTokenCellV1 | null;
 export declare function mergeAccountingEstimatedTokenCells(left: AccountingEstimatedTokenCellV1, right: AccountingEstimatedTokenCellV1): AccountingEstimatedTokenCellV1 | null;
 export declare function mergeAccountingMetricCells(left: AccountingMetricCellV1, right: AccountingMetricCellV1): AccountingMetricCellV1 | null;

package/dist/accounting-store-schema.js

@@ -1,5 +1,16 @@
 import { DASHBOARD_ATTEMPT_ID_MAX_BYTES, DASHBOARD_MAX_DETAIL_ATTEMPTS, DASHBOARD_REQUEST_ID_PATTERN, isDashboardAttemptId, isDashboardSafeId, isDashboardUtcTimestamp, } from "./dashboard-contract.js";
-/** The persisted accounting format is deliberately separate from the dashboard wire format. */
+/**
+ * The persisted accounting format is deliberately separate from the dashboard wire format.
+ *
+ * SCHEMA NOTE (2026-08-22, Stage 4 spend): `spend` grew from a hard-typed `null` into real
+ * aggregate cells, and `requestSpend`/`partiallyPricedRequests` were added beside it as an
+ * optional pair. This is an ADDITIVE change and the schema constant stays `accounting.day.v1`:
+ * the guards below accept BOTH shapes — a pre-spend shard's `spend: null` loads as empty cells
+ * rather than quarantining a day of real traffic. Nothing rewrites old shards on read: the
+ * guards tolerate absence and every reader defaults it (`?? 0`, `mergeSpend(undefined)`), so a
+ * legacy shard reads correctly and gains the new fields only when new facts fold into it. A
+ * bump would have discarded every existing day shard for no gain.
+ */
 export const ACCOUNTING_STORE_VERSION = 1;
 export const ACCOUNTING_DAY_SCHEMA = "accounting.day.v1";
 export const ACCOUNTING_MINUTE_SCHEMA = "accounting.minute.v1";
@@ -61,6 +72,28 @@ function hasExactArray(value, max, guard) {
     }
     return true;
 }
+/**
+ * Exact-key check tolerating a CLOSED set of optional keys, used by every owner of
+ * an aggregate: pre-spend shards carry neither `requestSpend` nor
+ * `partiallyPricedRequests`, and quarantining a whole day of real traffic over
+ * their absence would trade one additive field for the ledger itself.
+ */
+function hasExactKeysWithOptional(value, keys, optional) {
+    if (!isPlainRecord(value) || Object.getOwnPropertySymbols(value).length !== 0)
+        return false;
+    const names = Object.getOwnPropertyNames(value);
+    const enumerableNames = Object.keys(value);
+    if (names.length !== enumerableNames.length)
+        return false;
+    // Any SUBSET of the closed optional set is accepted, not only all-or-none: a
+    // fully-priced request attaches `requestSpend` without ever creating
+    // `partiallyPricedRequests`, and a writer may legitimately persist either
+    // alone. Unknown names are still rejected.
+    if (names.length < keys.length || names.length > keys.length + optional.length)
+        return false;
+    return keys.every((key) => Object.prototype.hasOwnProperty.call(value, key))
+        && names.every((name) => keys.includes(name) || optional.includes(name));
+}
 function hasOnlyEnumerableStringKeys(value) {
     return Object.getOwnPropertySymbols(value).length === 0 && Object.getOwnPropertyNames(value).length === Object.keys(value).length;
 }
@@ -279,6 +312,39 @@ function isMetric(value) {
         return false;
     return true;
 }
+/**
+ * One summed spend cell inside an aggregate. `known === 0` ⇔ amount and timestamp are
+ * null; an amount can be null with known > 0 only when a contributor overflowed, which
+ * marks the owning aggregate partial through its own coverage path.
+ */
+function isAggregateSpendCell(value) {
+    return (hasExactKeys(value, ["amountMicrousd", "known", "observedAt"]) &&
+        isNullableCounter(value.amountMicrousd) &&
+        isCounter(value.known) &&
+        isNullableTimestamp(value.observedAt) &&
+        ((value.known === 0 && value.amountMicrousd === null && value.observedAt === null) ||
+            (value.known > 0 && value.observedAt !== null)));
+}
+const SPEND_CELL_KEYS = Object.freeze(["providerPublishedReported", "providerPublishedEstimated", "referenceReported", "referenceEstimated"]);
+function isAggregateSpend(value) {
+    if (!hasExactKeys(value, SPEND_CELL_KEYS))
+        return false;
+    for (const key of SPEND_CELL_KEYS) {
+        const cell = value[key];
+        // hasExactKeys guarantees every key present; the undefined case cannot occur,
+        // but the guard keeps the record access total.
+        if (cell === undefined || !isAggregateSpendCell(cell))
+            return false;
+    }
+    return true;
+}
+/** The legacy pre-spend shape (`spend: null`) is accepted beside the full cells. */
+function isAggregateSpendOrNull(value) {
+    return value === null || isAggregateSpend(value);
+}
+function isEmptyAggregateSpendCell(cell) {
+    return cell.known === 0 && cell.amountMicrousd === null && cell.observedAt === null;
+}
 function isAggregateFields(value, owner = "general") {
     if (!isCounter(value.requests) ||
         !isCounter(value.attempts) ||
@@ -289,7 +355,9 @@ function isAggregateFields(value, owner = "general") {
         !isAggregateTokens(value.requestTokens) ||
         !isMetric(value.latency) ||
         !isMetric(value.commit) ||
-        value.spend !== null ||
+        !isAggregateSpendOrNull(value.spend) ||
+        !(value.requestSpend === undefined || isAggregateSpendOrNull(value.requestSpend)) ||
+        !(value.partiallyPricedRequests === undefined || isCounter(value.partiallyPricedRequests)) ||
         !isCounter(value.unpricedRequests))
         return false;
     if (owner === "request") {
@@ -297,12 +365,17 @@ function isAggregateFields(value, owner = "general") {
             return false;
         if (value.served + value.errored + value.cancelled > value.requests)
             return false;
+        if (value.spend !== null && !isEmptyAggregateSpend(value.spend))
+            return false;
     }
     else if (owner === "attempt") {
         if (value.requests !== 0 || !isEmptyAggregateTokens(value.requestTokens))
             return false;
         if (value.served + value.errored + value.cancelled > value.attempts)
             return false;
+        // Attempt-side rows carry no REQUEST-scoped facts.
+        if (value.requestSpend !== undefined || value.partiallyPricedRequests !== undefined)
+            return false;
     }
     else {
         if (value.served + value.errored + value.cancelled > value.requests)
@@ -321,46 +394,41 @@ function isAggregateFields(value, owner = "general") {
         if (value.outcome === "unknown" && (value.served !== 0 || value.errored !== 0 || value.cancelled !== 0))
             return false;
     }
-    return value.unpricedRequests <= value.requests;
+    return (value.unpricedRequests <= value.requests &&
+        (value.partiallyPricedRequests ?? 0) <= value.requests &&
+        (value.unpricedRequests + (value.partiallyPricedRequests ?? 0) <= value.requests));
+}
+function isEmptyAggregateSpend(spend) {
+    return (typeof spend === "object" &&
+        spend !== null &&
+        SPEND_CELL_KEYS.every((key) => {
+            const cell = spend[key];
+            return cell !== undefined && typeof cell === "object" && cell !== null && isEmptyAggregateSpendCell(cell);
+        }));
 }
+/** Aggregate keys; `requestSpend`/`partiallyPricedRequests` are the additive optional pair. */
+const AGGREGATE_KEYS = Object.freeze([
+    "requests",
+    "attempts",
+    "served",
+    "errored",
+    "cancelled",
+    "tokens",
+    "requestTokens",
+    "latency",
+    "commit",
+    "spend",
+    "unpricedRequests",
+]);
+const AGGREGATE_OPTIONAL_KEYS = Object.freeze(["requestSpend", "partiallyPricedRequests"]);
 function isAggregate(value) {
-    return (hasExactKeys(value, [
-        "requests",
-        "attempts",
-        "served",
-        "errored",
-        "cancelled",
-        "tokens",
-        "requestTokens",
-        "latency",
-        "commit",
-        "spend",
-        "unpricedRequests",
-    ]) && isAggregateFields(value));
+    return (hasExactKeysWithOptional(value, AGGREGATE_KEYS, AGGREGATE_OPTIONAL_KEYS) &&
+        isAggregateFields(value));
 }
 function isDimensionRow(value) {
-    if (!hasExactKeys(value, [
-        "requests",
-        "attempts",
-        "served",
-        "errored",
-        "cancelled",
-        "tokens",
-        "requestTokens",
-        "latency",
-        "commit",
-        "spend",
-        "unpricedRequests",
-        "kind",
-        "role",
-        "provider",
-        "model",
-        "client",
-        "credentialId",
-        "attribution",
-        "outcome",
-        "failureKind",
-    ]) ||
+    const keys = [...AGGREGATE_KEYS, "kind", "role", "provider", "model", "client", "credentialId", "attribution", "outcome", "failureKind"];
+    const optional = [...AGGREGATE_OPTIONAL_KEYS];
+    if (!hasExactKeysWithOptional(value, keys, optional) ||
         (value.kind !== "request" && value.kind !== "attempt") ||
         (value.kind === "request" && value.role !== "request") ||
         (value.kind === "attempt" && !isRole(value.role)) ||
@@ -373,9 +441,7 @@ function isDimensionRow(value) {
         (value.failureKind !== null && !isFailure(value.failureKind)) ||
         !isFailureCoherent(value.outcome, value.failureKind))
         return false;
-    if (!isAggregateFields(value, value.kind === "request" ? "request" : "attempt"))
-        return false;
-    return true;
+    return isAggregateFields(value, value.kind === "request" ? "request" : "attempt");
 }
 function isLossMarker(value) {
     return (hasExactKeys(value, ["kind", "count", "field"]) &&
@@ -513,6 +579,36 @@ function isLifetime(value) {
         return false;
     return withinFileCeiling(value);
 }
+/** One attempt's priced spend, or LEGACY `null`. Guards every provenance field. */
+function isSpend(value) {
+    return (hasExactKeys(value, [
+        "amountMicrousd",
+        "priceSource",
+        "tokenBasis",
+        "source",
+        "coverage",
+        "unpricedTokens",
+        "pricesUsed",
+        "observedAt",
+    ]) &&
+        isCounter(value.amountMicrousd) &&
+        (value.priceSource === "provider_published" || value.priceSource === "reference") &&
+        (value.tokenBasis === "reported" || value.tokenBasis === "estimated") &&
+        (value.source === "provider_reported" || value.source === "relay_estimated") &&
+        (value.coverage === "full" || value.coverage === "input_only" || value.coverage === "partial") &&
+        hasExactKeys(value.unpricedTokens, ["cacheRead", "cacheCreation", "cachedInput"]) &&
+        isNullableCounter(value.unpricedTokens.cacheRead) &&
+        isNullableCounter(value.unpricedTokens.cacheCreation) &&
+        isNullableCounter(value.unpricedTokens.cachedInput) &&
+        hasExactKeys(value.pricesUsed, ["perMillionIn", "perMillionOut"]) &&
+        isNullableNumber(value.pricesUsed.perMillionIn) &&
+        isNullableNumber(value.pricesUsed.perMillionOut) &&
+        isTimestamp(value.observedAt));
+}
+/** A finite non-negative number; prices are per-token decimals, not counters. */
+function isNullableNumber(value) {
+    return value === null || (typeof value === "number" && Number.isFinite(value) && value >= 0);
+}
 function isAttemptPacket(value) {
     if (!hasExactKeys(value, [
         "requestId",
@@ -547,7 +643,7 @@ function isAttemptPacket(value) {
         !isNullableId(value.model) ||
         !isNullableId(value.credentialId) ||
         !isAggregateTokens(value.tokens) ||
-        value.spend !== null)
+        !(value.spend === null || isSpend(value.spend)))
         return false;
     if (value.commitMs !== null && value.role !== "serve")
         return false;
@@ -601,7 +697,7 @@ function isRequestPacket(value) {
         !isNullableId(value.model) ||
         !isNullableId(value.credentialId) ||
         !isAggregateTokens(value.tokens) ||
-        value.spend !== null ||
+        !(value.spend === null || isSpend(value.spend)) ||
         !hasExactArray(value.attempts, ACCOUNTING_MAX_DETAIL_ATTEMPTS, isAttemptPacket) ||
         !isAttemptMetadata(value.attemptMetadata))
         return false;
@@ -885,6 +981,38 @@ export function checkedAddAccountingCounter(left, right) {
         return null;
     return left + right;
 }
+/**
+ * Sum two aggregate SPEND cells: integer micro-USD amounts, contributor counts,
+ * latest observation. Amounts stay null once any side is uncertain (overflow),
+ * mirroring how token cells degrade — a lost sum is never silently re-guessed.
+ */
+export function mergeAccountingSpendCells(left, right) {
+    const known = checkedAddAccountingCounter(left.known, right.known);
+    if (known === null)
+        return null;
+    let amountMicrousd = null;
+    if (left.amountMicrousd !== null &&
+        right.amountMicrousd !== null &&
+        left.amountMicrousd <= ACCOUNTING_MAX_COUNTER - right.amountMicrousd) {
+        amountMicrousd = left.amountMicrousd + right.amountMicrousd;
+    }
+    return freezeDeep({
+        amountMicrousd: known > 0 ? amountMicrousd : null,
+        known,
+        observedAt: latestTimestamp(left.observedAt, right.observedAt),
+    });
+}
+export function emptyAccountingSpendCell() {
+    return { amountMicrousd: null, known: 0, observedAt: null };
+}
+export function emptyAccountingAggregateSpend() {
+    return {
+        providerPublishedReported: emptyAccountingSpendCell(),
+        providerPublishedEstimated: emptyAccountingSpendCell(),
+        referenceReported: emptyAccountingSpendCell(),
+        referenceEstimated: emptyAccountingSpendCell(),
+    };
+}
 function latestTimestamp(a, b) {
     if (a === null)
         return b;