@bitbaum/ai-kit 1.0.0 → 1.1.0

package/README.md

@@ -361,6 +361,50 @@ locally.
 anything to do with AI. An app that throttles its login form should not install a
 model catalogue to do it.
 
+## Knowing what is left
+
+```ts
+const result = await complete({
+  messages,
+  onQuota: (readings) => void recordQuota(readings), // your table, your call
+});
+```
+
+Every vendor answer carries what it was willing to disclose about your remaining
+allowance, and this hands it to you on success **and on refusal**. No extra
+request: the number arrives on the exchange you were making anyway.
+
+**Do not poll a vendor's usage endpoint instead.** Measured on one live key,
+within the same second:
+
+```
+GET  /api/v1/key         →  limit_remaining: null,  usage_daily: 0
+POST /chat/completions   →  429, x-ratelimit-remaining: 0 of 50,
+                            "Rate limit exceeded: free-models-per-day"
+```
+
+Both are OpenRouter, about the same account, and the account was locked out. The
+usage endpoint tracks money; free models cost nothing; the limit that actually
+binds is a request count it never reports. A dashboard built on the first line
+shows a full tank during a total outage.
+
+Three things this will not do, each deliberate:
+
+- **It never invents a reading.** A vendor that sends no headers produces none.
+  Absent is a third state next to known and empty — render it as *unknown*,
+  because drawing it full repeats the bug above and drawing it empty invents an
+  outage.
+- **It never guesses a window.** `x-ratelimit-remaining-requests` counts a day at
+  Groq and a minute elsewhere, so the window comes from a verified per-provider
+  profile or from the header's own name, and is otherwise reported as unknown.
+- **It never stores anything.** Persisting is the app's job, which is why this is
+  a callback. The package has no database and should not grow one.
+
+`answersRemaining(reading, tokensPerTurn)` converts a token count into the unit a
+person actually thinks in. Nobody has an intuition for a token; "about 40 more
+answers" is actionable, and "7,927 tokens" is a sum the reader has to do and will
+get wrong.
+
 ## Versioning
 
 **This package is 1.x, and that is a functional decision rather than a

package/dist/complete.d.ts

@@ -58,6 +58,7 @@
 import { type Env, type Link, type Provider } from "./chain.js";
 import type { HealthTracker } from "./health.js";
 import { type RateLimitKind } from "./limits.js";
+import { type QuotaReading } from "./meter.js";
 /** One message in the OpenAI chat-completions shape every provider here speaks. */
 export interface ChatMessage {
     role: "system" | "user" | "assistant" | "tool";
@@ -156,6 +157,23 @@ export interface CompleteOptions {
     extraHeaders?: Record<string, string>;
     /** Called on each link's failure before moving on — e.g. to log which id rotted. */
     onLinkFailure?: (link: Link, error: Error) => void;
+    /**
+     * Called with every remaining-quota figure the vendor disclosed, on success
+     * AND on refusal. This is how an app learns what is left without spending a
+     * request to ask.
+     *
+     * It fires on 429s too, and those are the most valuable readings of all: a
+     * refusal is the vendor correcting a local counter that had drifted
+     * optimistic. See `meter.ts` for why polling a vendor's usage endpoint
+     * instead is the wrong design — one of them reports an untouched allowance
+     * while the key is locked out.
+     *
+     * Keep it cheap and never let it throw: it runs inside the response path, and
+     * an exception here would turn a good answer into a link failure. Persisting
+     * is the app's job, which is why this is a callback and not a store — the
+     * package stays free of a database.
+     */
+    onQuota?: (readings: QuotaReading[]) => void;
     /** Injected for tests. Defaults to global `fetch`. */
     fetchImpl?: typeof fetch;
 }

package/dist/complete.js

@@ -58,6 +58,7 @@
 import { chainFrom, freeChain, usableChain } from "./chain.js";
 import { ChainExhaustedError } from "./attempt.js";
 import { classifyRateLimit, retryAfterSeconds } from "./limits.js";
+import { readQuota, readingFromRefusal } from "./meter.js";
 /**
  * A link failed in a way that says something about the WALK, not just this link.
  *
@@ -220,10 +221,32 @@ async function callLink(link, options, key) {
         deadline.dispose();
     }
     const text = await res.text();
+    // Read the tank before interpreting the answer, so a refusal still reports
+    // what it disclosed. A caller's hook must never turn a good response into a
+    // failure, so it is isolated — an app's logging bug is not a vendor outage.
+    const report = (readings) => {
+        if (readings.length === 0 || !options.onQuota)
+            return;
+        try {
+            options.onQuota(readings);
+        }
+        catch {
+            /* the caller's sink is the caller's problem */
+        }
+    };
+    report(readQuota(res.headers, link));
     if (!res.ok) {
         if (res.status === 429) {
             const kind = classifyRateLimit(text);
             const retryAfter = retryAfterSeconds(text);
+            // The most reliable reading there is: the vendor itself saying "spent".
+            // Recorded even when no header carried a number, because it corrects a
+            // local counter that had drifted optimistic. `size` is excluded — that
+            // 429 means this one prompt was too big, not that the allowance is gone,
+            // and recording it as empty would take a working vendor out of service.
+            if (kind !== "size") {
+                report([readingFromRefusal(link, retryAfter)]);
+            }
             throw new LinkFailure(link, `${linkId(link)}: 429 ${kind} — ${excerpt(text)}`, {
                 status: 429,
                 kind,

package/dist/index.d.ts

@@ -56,4 +56,5 @@ export { type ChatMessage, type ToolCall, type CompleteOptions, type CompleteRes
 export { type HealthStatus, type Health, type HealthTrackerOptions, type HealthTracker, createHealthTracker, } from "./health.js";
 export { type LivenessResult, type LivenessOptions, type LivenessProbe, type AiHealthHandlerOptions, createLivenessProbe, createAiHealthHandler, } from "./liveness.js";
 export { type RateLimitKind, classifyRateLimit, retryAfterSeconds, humanizeWait, rateLimitMessage, } from "./limits.js";
+export { type QuotaScope, type QuotaWindow, type QuotaReading, type HeaderBag, readQuota, readingFromRefusal, parseResetAt, answersRemaining, } from "./meter.js";
 export { DAY_SECONDS, DEFAULT_BURST, type ShareInput, type ShareReason, type ShareDecision, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";

package/dist/index.js

@@ -56,6 +56,7 @@ export { LinkFailure, complete, linkId, } from "./complete.js";
 export { createHealthTracker, } from "./health.js";
 export { createLivenessProbe, createAiHealthHandler, } from "./liveness.js";
 export { classifyRateLimit, retryAfterSeconds, humanizeWait, rateLimitMessage, } from "./limits.js";
+export { readQuota, readingFromRefusal, parseResetAt, answersRemaining, } from "./meter.js";
 export { DAY_SECONDS, DEFAULT_BURST, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";
 // Form filling lives at `ai-kit/forms`, NOT here.
 //

package/dist/meter.d.ts

@@ -0,0 +1,117 @@
+/**
+ * What is left at the vendor, read from the answer you already got.
+ *
+ * ── WHY THIS IS NOT A POLLER ─────────────────────────────────────────────────
+ *
+ * The obvious design is to ask each provider how much quota remains. That
+ * design is wrong, and it is wrong in the direction that hurts: it reports a
+ * full tank during an outage.
+ *
+ * Measured on 2026-09-11, on one live key, within the same second:
+ *
+ *   GET /api/v1/key        →  limit_remaining: null,  usage_daily: 0
+ *   POST /chat/completions →  429, x-ratelimit-remaining: 0 of 50,
+ *                             "Rate limit exceeded: free-models-per-day"
+ *
+ * Both answers are from OpenRouter about the same account. The account was
+ * locked out. The usage endpoint tracks money, free models cost nothing, and
+ * the limit that actually binds is a REQUEST count that endpoint never reports.
+ * A dashboard built on the first line would have shown an untouched allowance
+ * while every call was failing.
+ *
+ * So the meter reads the headers on calls you were making anyway. No extra
+ * request, no extra quota spent to find out how much quota is left, and the
+ * number comes from the same exchange that either worked or did not.
+ *
+ * ── THE THREE STATES ─────────────────────────────────────────────────────────
+ *
+ * A provider you have not called today reports NOTHING, and that is a third
+ * state — not zero, not full. This module never invents a reading: no header,
+ * no `QuotaReading`. Callers must render the absence as "unknown", because
+ * drawing it as full repeats the bug above and drawing it as empty invents an
+ * outage.
+ *
+ * ── VENDORS DISAGREE ABOUT WHAT THEIR OWN HEADERS MEAN ───────────────────────
+ *
+ * `x-ratelimit-remaining-requests` is a per-DAY count at Groq and a per-MINUTE
+ * count elsewhere. The window is therefore read from a per-provider profile
+ * where one is known, from the header name where it says so (`...-day`), and
+ * otherwise reported as "unknown" rather than guessed. A confident wrong window
+ * turns "you have 900 requests left today" into "…this minute", which is the
+ * kind of error nobody catches until the dashboard has been trusted for a week.
+ */
+import type { Link } from "./chain.js";
+/** What is being counted. */
+export type QuotaScope = "requests" | "tokens";
+/** The period the count refreshes over. `unknown` is a real answer. */
+export type QuotaWindow = "minute" | "day" | "unknown";
+/** One observation of one vendor counter, at one moment. */
+export interface QuotaReading {
+    /** Provider id, e.g. "groq". */
+    provider: string;
+    /** The model the call named — Groq meters per model, so this matters. */
+    model: string;
+    scope: QuotaScope;
+    window: QuotaWindow;
+    /** The ceiling, when the vendor states it. */
+    limit: number | null;
+    /** What is left. The number this module exists to obtain. */
+    remaining: number;
+    /** When the counter refills, epoch ms. Null when the vendor did not say. */
+    resetAt: number | null;
+    /** The header (or body) this came from — so a wrong number is traceable. */
+    source: string;
+    /** Epoch ms. A reading is evidence about a moment, not a standing fact. */
+    observedAt: number;
+}
+/** Anything header-shaped. Keeps this module free of a DOM/undici dependency. */
+export interface HeaderBag {
+    get(name: string): string | null;
+}
+/**
+ * Parse a reset value into epoch milliseconds.
+ *
+ * Vendors encode this three incompatible ways and none of them say which:
+ *
+ *   "1789171200000"  OpenRouter — epoch MILLISECONDS (a Sept 2026 date)
+ *   "1m26.4s"        Groq — a duration, compound, fractional
+ *   "547ms"          Groq — a duration under a second
+ *   "60"             several — seconds from now
+ *
+ * The discriminator is magnitude, not format: a value past the year 2001 in
+ * milliseconds cannot be a duration anyone would wait. Returns null rather than
+ * guessing when nothing parses, because a wrong reset time tells the operator
+ * to come back at the wrong hour.
+ */
+export declare function parseResetAt(raw: string | null, now?: number): number | null;
+/**
+ * Every remaining-count this response disclosed.
+ *
+ * Returns an empty array when the vendor said nothing, which is the common case
+ * — Gemini sends no rate-limit headers at all, and several others only meter
+ * server-side. An empty array means "did not say", never "nothing left".
+ */
+export declare function readQuota(headers: HeaderBag, link: Link, now?: number): QuotaReading[];
+/**
+ * A refusal is the most reliable reading there is.
+ *
+ * A 429 states the one fact a dashboard most needs and most often has stale:
+ * this vendor is spent. It is worth recording even when the response carried no
+ * usable headers, because it corrects a local counter that had drifted
+ * optimistic — the counter is a model of the vendor, and this is the vendor
+ * disagreeing with it.
+ */
+export declare function readingFromRefusal(link: Link, retryAfterSec: number | null, scope?: QuotaScope, now?: number): QuotaReading;
+/**
+ * Turn a remaining-token count into the unit a person thinks in.
+ *
+ * Nobody has an intuition for a token. "About 40 more answers" is actionable;
+ * "7,927 tokens" is a number the reader has to convert before it means
+ * anything, and they will convert it wrongly.
+ *
+ * `tokensPerTurn` is the caller's measured average, because it is a property of
+ * their prompts, not of this package. Returns null when the reading cannot
+ * support the translation, so the caller shows the raw figure rather than a
+ * fabricated one.
+ */
+export declare function answersRemaining(reading: QuotaReading, tokensPerTurn: number): number | null;

package/dist/meter.js

@@ -0,0 +1,217 @@
+/**
+ * What is left at the vendor, read from the answer you already got.
+ *
+ * ── WHY THIS IS NOT A POLLER ─────────────────────────────────────────────────
+ *
+ * The obvious design is to ask each provider how much quota remains. That
+ * design is wrong, and it is wrong in the direction that hurts: it reports a
+ * full tank during an outage.
+ *
+ * Measured on 2026-09-11, on one live key, within the same second:
+ *
+ *   GET /api/v1/key        →  limit_remaining: null,  usage_daily: 0
+ *   POST /chat/completions →  429, x-ratelimit-remaining: 0 of 50,
+ *                             "Rate limit exceeded: free-models-per-day"
+ *
+ * Both answers are from OpenRouter about the same account. The account was
+ * locked out. The usage endpoint tracks money, free models cost nothing, and
+ * the limit that actually binds is a REQUEST count that endpoint never reports.
+ * A dashboard built on the first line would have shown an untouched allowance
+ * while every call was failing.
+ *
+ * So the meter reads the headers on calls you were making anyway. No extra
+ * request, no extra quota spent to find out how much quota is left, and the
+ * number comes from the same exchange that either worked or did not.
+ *
+ * ── THE THREE STATES ─────────────────────────────────────────────────────────
+ *
+ * A provider you have not called today reports NOTHING, and that is a third
+ * state — not zero, not full. This module never invents a reading: no header,
+ * no `QuotaReading`. Callers must render the absence as "unknown", because
+ * drawing it as full repeats the bug above and drawing it as empty invents an
+ * outage.
+ *
+ * ── VENDORS DISAGREE ABOUT WHAT THEIR OWN HEADERS MEAN ───────────────────────
+ *
+ * `x-ratelimit-remaining-requests` is a per-DAY count at Groq and a per-MINUTE
+ * count elsewhere. The window is therefore read from a per-provider profile
+ * where one is known, from the header name where it says so (`...-day`), and
+ * otherwise reported as "unknown" rather than guessed. A confident wrong window
+ * turns "you have 900 requests left today" into "…this minute", which is the
+ * kind of error nobody catches until the dashboard has been trusted for a week.
+ */
+/**
+ * Per-provider correction for headers whose name does not state their window.
+ *
+ * Only entries verified against the vendor's own documentation or a live
+ * response belong here. An unlisted provider yields `unknown`, which is the
+ * honest answer and renders as such.
+ */
+const PROVIDER_WINDOWS = {
+    // Verified live 2026-09-11: `x-ratelimit-remaining-requests` counts the DAY
+    // (1,000 per day), while `-tokens` counts the minute (8,000 per minute).
+    // Reading both as per-minute understates the day by three orders of
+    // magnitude; reading both as daily hides the limit that actually throttles.
+    groq: { requests: "day", tokens: "minute" },
+    // Verified live 2026-09-11: the unpaid tier is 50 REQUESTS per day, and the
+    // bare `x-ratelimit-remaining` on the chat response is that counter.
+    openrouter: { requests: "day" },
+    // Documented per-minute, with separate `-day` twins this parser reads by name.
+    sambanova: { requests: "minute" },
+    ovh: { requests: "minute" },
+    mistral: { requests: "minute" },
+};
+/**
+ * Header names carrying a remaining count, most specific first.
+ *
+ * Order matters: `...-requests-day` must be tested before `...-requests`, or
+ * the day counter is read as the minute counter under the shorter name.
+ */
+const REMAINING_HEADERS = [
+    { name: "x-ratelimit-remaining-requests-day", scope: "requests", window: "day" },
+    { name: "x-ratelimit-remaining-tokens-day", scope: "tokens", window: "day" },
+    { name: "x-ratelimit-remaining-requests-minute", scope: "requests", window: "minute" },
+    { name: "x-ratelimit-remaining-minute", scope: "requests", window: "minute" },
+    { name: "x-ratelimit-remaining-requests", scope: "requests" },
+    { name: "x-ratelimit-remaining-tokens", scope: "tokens" },
+    // Bare forms. OpenRouter uses `x-ratelimit-remaining`; OVHcloud drops the
+    // `x-` prefix entirely. Both count requests.
+    { name: "x-ratelimit-remaining", scope: "requests" },
+    { name: "ratelimit-remaining", scope: "requests" },
+];
+/** The limit header paired with a remaining header, by substitution. */
+function limitNameFor(remainingName) {
+    return remainingName.replace("remaining", "limit");
+}
+/** The reset header paired with a remaining header, by substitution. */
+function resetNameFor(remainingName) {
+    return remainingName.replace("remaining", "reset");
+}
+/**
+ * Parse a reset value into epoch milliseconds.
+ *
+ * Vendors encode this three incompatible ways and none of them say which:
+ *
+ *   "1789171200000"  OpenRouter — epoch MILLISECONDS (a Sept 2026 date)
+ *   "1m26.4s"        Groq — a duration, compound, fractional
+ *   "547ms"          Groq — a duration under a second
+ *   "60"             several — seconds from now
+ *
+ * The discriminator is magnitude, not format: a value past the year 2001 in
+ * milliseconds cannot be a duration anyone would wait. Returns null rather than
+ * guessing when nothing parses, because a wrong reset time tells the operator
+ * to come back at the wrong hour.
+ */
+export function parseResetAt(raw, now = Date.now()) {
+    if (!raw)
+        return null;
+    const value = raw.trim();
+    if (value === "")
+        return null;
+    // Bare digits: epoch ms if implausibly large to be a wait, else seconds.
+    if (/^\d+$/.test(value)) {
+        const n = Number(value);
+        // 10^12 ms ≈ 2001. No vendor asks you to wait thirty years.
+        return n > 1e12 ? n : now + n * 1000;
+    }
+    // Duration forms: 1h2m3.4s, 56m26.88s, 547ms, 3.6s.
+    const ms = /^(\d+(?:\.\d+)?)ms$/.exec(value);
+    if (ms)
+        return now + Number(ms[1]);
+    const parts = /^(?:(\d+(?:\.\d+)?)h)?(?:(\d+(?:\.\d+)?)m(?!s))?(?:(\d+(?:\.\d+)?)s)?$/.exec(value);
+    if (parts && (parts[1] || parts[2] || parts[3])) {
+        const hours = Number(parts[1] ?? 0);
+        const mins = Number(parts[2] ?? 0);
+        const secs = Number(parts[3] ?? 0);
+        return now + (hours * 3600 + mins * 60 + secs) * 1000;
+    }
+    return null;
+}
+/** Resolve the window for a header that did not name one. */
+function windowFor(providerId, scope, stated) {
+    if (stated)
+        return stated;
+    return PROVIDER_WINDOWS[providerId]?.[scope] ?? "unknown";
+}
+/**
+ * Every remaining-count this response disclosed.
+ *
+ * Returns an empty array when the vendor said nothing, which is the common case
+ * — Gemini sends no rate-limit headers at all, and several others only meter
+ * server-side. An empty array means "did not say", never "nothing left".
+ */
+export function readQuota(headers, link, now = Date.now()) {
+    const readings = [];
+    const seen = new Set();
+    for (const entry of REMAINING_HEADERS) {
+        const raw = headers.get(entry.name);
+        if (raw === null || raw.trim() === "")
+            continue;
+        const remaining = Number(raw);
+        if (!Number.isFinite(remaining))
+            continue;
+        const window = windowFor(link.provider.id, entry.scope, entry.window);
+        // A shorter header name must not overwrite the more specific one it is a
+        // prefix of: once requests/day is known, a bare requests header is the same
+        // counter reported less precisely.
+        const key = `${entry.scope}:${window}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const limitRaw = headers.get(limitNameFor(entry.name));
+        const limit = limitRaw === null ? null : Number(limitRaw);
+        readings.push({
+            provider: link.provider.id,
+            model: link.model,
+            scope: entry.scope,
+            window,
+            limit: limit !== null && Number.isFinite(limit) ? limit : null,
+            remaining,
+            resetAt: parseResetAt(headers.get(resetNameFor(entry.name)), now),
+            source: entry.name,
+            observedAt: now,
+        });
+    }
+    return readings;
+}
+/**
+ * A refusal is the most reliable reading there is.
+ *
+ * A 429 states the one fact a dashboard most needs and most often has stale:
+ * this vendor is spent. It is worth recording even when the response carried no
+ * usable headers, because it corrects a local counter that had drifted
+ * optimistic — the counter is a model of the vendor, and this is the vendor
+ * disagreeing with it.
+ */
+export function readingFromRefusal(link, retryAfterSec, scope = "requests", now = Date.now()) {
+    return {
+        provider: link.provider.id,
+        model: link.model,
+        scope,
+        window: windowFor(link.provider.id, scope),
+        limit: null,
+        remaining: 0,
+        resetAt: retryAfterSec === null ? null : now + retryAfterSec * 1000,
+        source: "429",
+        observedAt: now,
+    };
+}
+/**
+ * Turn a remaining-token count into the unit a person thinks in.
+ *
+ * Nobody has an intuition for a token. "About 40 more answers" is actionable;
+ * "7,927 tokens" is a number the reader has to convert before it means
+ * anything, and they will convert it wrongly.
+ *
+ * `tokensPerTurn` is the caller's measured average, because it is a property of
+ * their prompts, not of this package. Returns null when the reading cannot
+ * support the translation, so the caller shows the raw figure rather than a
+ * fabricated one.
+ */
+export function answersRemaining(reading, tokensPerTurn) {
+    if (reading.scope === "requests")
+        return Math.max(0, Math.floor(reading.remaining));
+    if (!Number.isFinite(tokensPerTurn) || tokensPerTurn <= 0)
+        return null;
+    return Math.max(0, Math.floor(reading.remaining / tokensPerTurn));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "One install for the AI layer of an app: which model to call, what to do when the vendor retires it, how to walk the fallback chain and know when none of it worked, how to read the three kinds of 429, a fair daily budget across users, headless AI form filling \u2014 and now the model registry (one SSOT for every callable id, with the paid/free boundary as a field) and the grounding harness (facts, contract, deterministic fabrication check).",
   "license": "MIT",
   "author": "Mao Nakamoto",

package/src/complete.ts

@@ -60,6 +60,7 @@ import { type Env, type Link, type Provider, chainFrom, freeChain, usableChain }
 import { ChainExhaustedError, type ChainAttemptFailure } from "./attempt.js";
 import type { HealthTracker } from "./health.js";
 import { classifyRateLimit, retryAfterSeconds, type RateLimitKind } from "./limits.js";
+import { readQuota, readingFromRefusal, type QuotaReading } from "./meter.js";
 
 /** One message in the OpenAI chat-completions shape every provider here speaks. */
 export interface ChatMessage {
@@ -161,6 +162,23 @@ export interface CompleteOptions {
   extraHeaders?: Record<string, string>;
   /** Called on each link's failure before moving on — e.g. to log which id rotted. */
   onLinkFailure?: (link: Link, error: Error) => void;
+  /**
+   * Called with every remaining-quota figure the vendor disclosed, on success
+   * AND on refusal. This is how an app learns what is left without spending a
+   * request to ask.
+   *
+   * It fires on 429s too, and those are the most valuable readings of all: a
+   * refusal is the vendor correcting a local counter that had drifted
+   * optimistic. See `meter.ts` for why polling a vendor's usage endpoint
+   * instead is the wrong design — one of them reports an untouched allowance
+   * while the key is locked out.
+   *
+   * Keep it cheap and never let it throw: it runs inside the response path, and
+   * an exception here would turn a good answer into a link failure. Persisting
+   * is the app's job, which is why this is a callback and not a store — the
+   * package stays free of a database.
+   */
+  onQuota?: (readings: QuotaReading[]) => void;
   /** Injected for tests. Defaults to global `fetch`. */
   fetchImpl?: typeof fetch;
 }
@@ -367,10 +385,31 @@ async function callLink(
 
   const text = await res.text();
 
+  // Read the tank before interpreting the answer, so a refusal still reports
+  // what it disclosed. A caller's hook must never turn a good response into a
+  // failure, so it is isolated — an app's logging bug is not a vendor outage.
+  const report = (readings: QuotaReading[]) => {
+    if (readings.length === 0 || !options.onQuota) return;
+    try {
+      options.onQuota(readings);
+    } catch {
+      /* the caller's sink is the caller's problem */
+    }
+  };
+  report(readQuota(res.headers, link));
+
   if (!res.ok) {
     if (res.status === 429) {
       const kind = classifyRateLimit(text);
       const retryAfter = retryAfterSeconds(text);
+      // The most reliable reading there is: the vendor itself saying "spent".
+      // Recorded even when no header carried a number, because it corrects a
+      // local counter that had drifted optimistic. `size` is excluded — that
+      // 429 means this one prompt was too big, not that the allowance is gone,
+      // and recording it as empty would take a working vendor out of service.
+      if (kind !== "size") {
+        report([readingFromRefusal(link, retryAfter)]);
+      }
       throw new LinkFailure(link, `${linkId(link)}: 429 ${kind} — ${excerpt(text)}`, {
         status: 429,
         kind,

package/src/index.ts

@@ -117,6 +117,17 @@ export {
   rateLimitMessage,
 } from "./limits.js";
 
+export {
+  type QuotaScope,
+  type QuotaWindow,
+  type QuotaReading,
+  type HeaderBag,
+  readQuota,
+  readingFromRefusal,
+  parseResetAt,
+  answersRemaining,
+} from "./meter.js";
+
 export {
   DAY_SECONDS,
   DEFAULT_BURST,

package/src/meter.ts

@@ -0,0 +1,267 @@
+/**
+ * What is left at the vendor, read from the answer you already got.
+ *
+ * ── WHY THIS IS NOT A POLLER ─────────────────────────────────────────────────
+ *
+ * The obvious design is to ask each provider how much quota remains. That
+ * design is wrong, and it is wrong in the direction that hurts: it reports a
+ * full tank during an outage.
+ *
+ * Measured on 2026-09-11, on one live key, within the same second:
+ *
+ *   GET /api/v1/key        →  limit_remaining: null,  usage_daily: 0
+ *   POST /chat/completions →  429, x-ratelimit-remaining: 0 of 50,
+ *                             "Rate limit exceeded: free-models-per-day"
+ *
+ * Both answers are from OpenRouter about the same account. The account was
+ * locked out. The usage endpoint tracks money, free models cost nothing, and
+ * the limit that actually binds is a REQUEST count that endpoint never reports.
+ * A dashboard built on the first line would have shown an untouched allowance
+ * while every call was failing.
+ *
+ * So the meter reads the headers on calls you were making anyway. No extra
+ * request, no extra quota spent to find out how much quota is left, and the
+ * number comes from the same exchange that either worked or did not.
+ *
+ * ── THE THREE STATES ─────────────────────────────────────────────────────────
+ *
+ * A provider you have not called today reports NOTHING, and that is a third
+ * state — not zero, not full. This module never invents a reading: no header,
+ * no `QuotaReading`. Callers must render the absence as "unknown", because
+ * drawing it as full repeats the bug above and drawing it as empty invents an
+ * outage.
+ *
+ * ── VENDORS DISAGREE ABOUT WHAT THEIR OWN HEADERS MEAN ───────────────────────
+ *
+ * `x-ratelimit-remaining-requests` is a per-DAY count at Groq and a per-MINUTE
+ * count elsewhere. The window is therefore read from a per-provider profile
+ * where one is known, from the header name where it says so (`...-day`), and
+ * otherwise reported as "unknown" rather than guessed. A confident wrong window
+ * turns "you have 900 requests left today" into "…this minute", which is the
+ * kind of error nobody catches until the dashboard has been trusted for a week.
+ */
+
+import type { Link } from "./chain.js";
+
+/** What is being counted. */
+export type QuotaScope = "requests" | "tokens";
+
+/** The period the count refreshes over. `unknown` is a real answer. */
+export type QuotaWindow = "minute" | "day" | "unknown";
+
+/** One observation of one vendor counter, at one moment. */
+export interface QuotaReading {
+  /** Provider id, e.g. "groq". */
+  provider: string;
+  /** The model the call named — Groq meters per model, so this matters. */
+  model: string;
+  scope: QuotaScope;
+  window: QuotaWindow;
+  /** The ceiling, when the vendor states it. */
+  limit: number | null;
+  /** What is left. The number this module exists to obtain. */
+  remaining: number;
+  /** When the counter refills, epoch ms. Null when the vendor did not say. */
+  resetAt: number | null;
+  /** The header (or body) this came from — so a wrong number is traceable. */
+  source: string;
+  /** Epoch ms. A reading is evidence about a moment, not a standing fact. */
+  observedAt: number;
+}
+
+/** Anything header-shaped. Keeps this module free of a DOM/undici dependency. */
+export interface HeaderBag {
+  get(name: string): string | null;
+}
+
+/**
+ * Per-provider correction for headers whose name does not state their window.
+ *
+ * Only entries verified against the vendor's own documentation or a live
+ * response belong here. An unlisted provider yields `unknown`, which is the
+ * honest answer and renders as such.
+ */
+const PROVIDER_WINDOWS: Record<string, Partial<Record<QuotaScope, QuotaWindow>>> = {
+  // Verified live 2026-09-11: `x-ratelimit-remaining-requests` counts the DAY
+  // (1,000 per day), while `-tokens` counts the minute (8,000 per minute).
+  // Reading both as per-minute understates the day by three orders of
+  // magnitude; reading both as daily hides the limit that actually throttles.
+  groq: { requests: "day", tokens: "minute" },
+  // Verified live 2026-09-11: the unpaid tier is 50 REQUESTS per day, and the
+  // bare `x-ratelimit-remaining` on the chat response is that counter.
+  openrouter: { requests: "day" },
+  // Documented per-minute, with separate `-day` twins this parser reads by name.
+  sambanova: { requests: "minute" },
+  ovh: { requests: "minute" },
+  mistral: { requests: "minute" },
+};
+
+/**
+ * Header names carrying a remaining count, most specific first.
+ *
+ * Order matters: `...-requests-day` must be tested before `...-requests`, or
+ * the day counter is read as the minute counter under the shorter name.
+ */
+const REMAINING_HEADERS: Array<{ name: string; scope: QuotaScope; window?: QuotaWindow }> = [
+  { name: "x-ratelimit-remaining-requests-day", scope: "requests", window: "day" },
+  { name: "x-ratelimit-remaining-tokens-day", scope: "tokens", window: "day" },
+  { name: "x-ratelimit-remaining-requests-minute", scope: "requests", window: "minute" },
+  { name: "x-ratelimit-remaining-minute", scope: "requests", window: "minute" },
+  { name: "x-ratelimit-remaining-requests", scope: "requests" },
+  { name: "x-ratelimit-remaining-tokens", scope: "tokens" },
+  // Bare forms. OpenRouter uses `x-ratelimit-remaining`; OVHcloud drops the
+  // `x-` prefix entirely. Both count requests.
+  { name: "x-ratelimit-remaining", scope: "requests" },
+  { name: "ratelimit-remaining", scope: "requests" },
+];
+
+/** The limit header paired with a remaining header, by substitution. */
+function limitNameFor(remainingName: string): string {
+  return remainingName.replace("remaining", "limit");
+}
+
+/** The reset header paired with a remaining header, by substitution. */
+function resetNameFor(remainingName: string): string {
+  return remainingName.replace("remaining", "reset");
+}
+
+/**
+ * Parse a reset value into epoch milliseconds.
+ *
+ * Vendors encode this three incompatible ways and none of them say which:
+ *
+ *   "1789171200000"  OpenRouter — epoch MILLISECONDS (a Sept 2026 date)
+ *   "1m26.4s"        Groq — a duration, compound, fractional
+ *   "547ms"          Groq — a duration under a second
+ *   "60"             several — seconds from now
+ *
+ * The discriminator is magnitude, not format: a value past the year 2001 in
+ * milliseconds cannot be a duration anyone would wait. Returns null rather than
+ * guessing when nothing parses, because a wrong reset time tells the operator
+ * to come back at the wrong hour.
+ */
+export function parseResetAt(raw: string | null, now = Date.now()): number | null {
+  if (!raw) return null;
+  const value = raw.trim();
+  if (value === "") return null;
+
+  // Bare digits: epoch ms if implausibly large to be a wait, else seconds.
+  if (/^\d+$/.test(value)) {
+    const n = Number(value);
+    // 10^12 ms ≈ 2001. No vendor asks you to wait thirty years.
+    return n > 1e12 ? n : now + n * 1000;
+  }
+
+  // Duration forms: 1h2m3.4s, 56m26.88s, 547ms, 3.6s.
+  const ms = /^(\d+(?:\.\d+)?)ms$/.exec(value);
+  if (ms) return now + Number(ms[1]);
+
+  const parts = /^(?:(\d+(?:\.\d+)?)h)?(?:(\d+(?:\.\d+)?)m(?!s))?(?:(\d+(?:\.\d+)?)s)?$/.exec(
+    value,
+  );
+  if (parts && (parts[1] || parts[2] || parts[3])) {
+    const hours = Number(parts[1] ?? 0);
+    const mins = Number(parts[2] ?? 0);
+    const secs = Number(parts[3] ?? 0);
+    return now + (hours * 3600 + mins * 60 + secs) * 1000;
+  }
+
+  return null;
+}
+
+/** Resolve the window for a header that did not name one. */
+function windowFor(providerId: string, scope: QuotaScope, stated?: QuotaWindow): QuotaWindow {
+  if (stated) return stated;
+  return PROVIDER_WINDOWS[providerId]?.[scope] ?? "unknown";
+}
+
+/**
+ * Every remaining-count this response disclosed.
+ *
+ * Returns an empty array when the vendor said nothing, which is the common case
+ * — Gemini sends no rate-limit headers at all, and several others only meter
+ * server-side. An empty array means "did not say", never "nothing left".
+ */
+export function readQuota(headers: HeaderBag, link: Link, now = Date.now()): QuotaReading[] {
+  const readings: QuotaReading[] = [];
+  const seen = new Set<string>();
+
+  for (const entry of REMAINING_HEADERS) {
+    const raw = headers.get(entry.name);
+    if (raw === null || raw.trim() === "") continue;
+
+    const remaining = Number(raw);
+    if (!Number.isFinite(remaining)) continue;
+
+    const window = windowFor(link.provider.id, entry.scope, entry.window);
+    // A shorter header name must not overwrite the more specific one it is a
+    // prefix of: once requests/day is known, a bare requests header is the same
+    // counter reported less precisely.
+    const key = `${entry.scope}:${window}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const limitRaw = headers.get(limitNameFor(entry.name));
+    const limit = limitRaw === null ? null : Number(limitRaw);
+
+    readings.push({
+      provider: link.provider.id,
+      model: link.model,
+      scope: entry.scope,
+      window,
+      limit: limit !== null && Number.isFinite(limit) ? limit : null,
+      remaining,
+      resetAt: parseResetAt(headers.get(resetNameFor(entry.name)), now),
+      source: entry.name,
+      observedAt: now,
+    });
+  }
+
+  return readings;
+}
+
+/**
+ * A refusal is the most reliable reading there is.
+ *
+ * A 429 states the one fact a dashboard most needs and most often has stale:
+ * this vendor is spent. It is worth recording even when the response carried no
+ * usable headers, because it corrects a local counter that had drifted
+ * optimistic — the counter is a model of the vendor, and this is the vendor
+ * disagreeing with it.
+ */
+export function readingFromRefusal(
+  link: Link,
+  retryAfterSec: number | null,
+  scope: QuotaScope = "requests",
+  now = Date.now(),
+): QuotaReading {
+  return {
+    provider: link.provider.id,
+    model: link.model,
+    scope,
+    window: windowFor(link.provider.id, scope),
+    limit: null,
+    remaining: 0,
+    resetAt: retryAfterSec === null ? null : now + retryAfterSec * 1000,
+    source: "429",
+    observedAt: now,
+  };
+}
+
+/**
+ * Turn a remaining-token count into the unit a person thinks in.
+ *
+ * Nobody has an intuition for a token. "About 40 more answers" is actionable;
+ * "7,927 tokens" is a number the reader has to convert before it means
+ * anything, and they will convert it wrongly.
+ *
+ * `tokensPerTurn` is the caller's measured average, because it is a property of
+ * their prompts, not of this package. Returns null when the reading cannot
+ * support the translation, so the caller shows the raw figure rather than a
+ * fabricated one.
+ */
+export function answersRemaining(reading: QuotaReading, tokensPerTurn: number): number | null {
+  if (reading.scope === "requests") return Math.max(0, Math.floor(reading.remaining));
+  if (!Number.isFinite(tokensPerTurn) || tokensPerTurn <= 0) return null;
+  return Math.max(0, Math.floor(reading.remaining / tokensPerTurn));
+}