@bitbaum/ai-kit 1.5.0 → 1.6.0

package/dist/index.d.ts

@@ -58,7 +58,7 @@ export { type ChatMessage, type ContentPart, type ToolCall, type CompleteOptions
 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 { type QuotaScope, type QuotaWindow, type QuotaReading, type HeaderBag, readQuota, readingFromRefusal, readingFromRefusalBody, parseResetAt, answersRemaining, } from "./meter.js";
 export { type ParsedToolCall, TEXT_TOOL_PROTOCOL_HINT, parseTextToolCalls, stripToolCallLines, safeJsonObject, toolNamesFrom, } from "./tool-protocol.js";
 export { type PoolId, type RungId, type TierPolicy, type AiPolicy, type UserState, type WallOption, type Wall, type Decision, DEFAULT_LADDER, decide, shouldSurface, nextUtcReset, } from "./policy.js";
 export { DAY_SECONDS, DEFAULT_BURST, type ShareInput, type ShareReason, type ShareDecision, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";

package/dist/index.js

@@ -61,7 +61,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 { readQuota, readingFromRefusal, readingFromRefusalBody, parseResetAt, answersRemaining, } from "./meter.js";
 export { TEXT_TOOL_PROTOCOL_HINT, parseTextToolCalls, stripToolCallLines, safeJsonObject, toolNamesFrom, } from "./tool-protocol.js";
 export { DEFAULT_LADDER, decide, shouldSurface, nextUtcReset, } from "./policy.js";
 export { DAY_SECONDS, DEFAULT_BURST, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";

package/dist/meter.d.ts

@@ -102,6 +102,7 @@ export declare function readQuota(headers: HeaderBag, link: Link, now?: number):
  * disagreeing with it.
  */
 export declare function readingFromRefusal(link: Link, retryAfterSec: number | null, scope?: QuotaScope, now?: number): QuotaReading;
+export declare function readingFromRefusalBody(link: Link, body: string, retryAfterSec?: number | null, now?: number): QuotaReading | null;
 /**
  * Turn a remaining-token count into the unit a person thinks in.
  *

package/dist/meter.js

@@ -196,6 +196,64 @@ export function readingFromRefusal(link, retryAfterSec, scope = "requests", now
         observedAt: now,
     };
 }
+/**
+ * The counter a vendor discloses ONLY when it refuses.
+ *
+ * ── WHY A BODY PARSER EARNS ITS KEEP ─────────────────────────────────────────
+ *
+ * Headers do not describe every limit a vendor enforces. Groq publishes its
+ * per-minute token window and its per-day REQUEST count as headers, and meters
+ * a third limit — tokens per DAY — that appears in no header at all. It is
+ * stated once, in prose, in the body of the 429 that enforces it:
+ *
+ *   Rate limit reached for model `openai/gpt-oss-20b` in organization `org_…`
+ *   service tier `on_demand` on tokens per day (TPD): Limit 200000,
+ *   Used 199773, Requested 571. Please try again in 2m28.608s.
+ *
+ * Observed on production 2026-09-13. Every header the same response carried
+ * looked healthy — 2,672 of 8,000 tokens left this minute, 999 of 1,000
+ * requests left today — while the account was locked out of the model for the
+ * rest of the day. A dashboard fed only by headers therefore reported a
+ * working provider throughout an outage, which is precisely the failure the
+ * top of this file exists to prevent, arriving through a door it left open.
+ *
+ * ── STILL NEVER INVENTS ──────────────────────────────────────────────────────
+ *
+ * Returns null unless the body states the numbers. An unparsed refusal is the
+ * "did not say" state, and the caller should fall back to `readingFromRefusal`,
+ * which records the one fact a 429 always carries: spent, now.
+ */
+const REFUSAL_COUNTER = /on\s+(tokens|requests)\s+per\s+(minute|day)\s*\([^)]*\)\s*:\s*Limit\s+(\d+)\s*,\s*Used\s+(\d+)/i;
+export function readingFromRefusalBody(link, body, retryAfterSec = null, now = Date.now()) {
+    const m = REFUSAL_COUNTER.exec(body);
+    if (!m)
+        return null;
+    const [, rawScope, rawWindow, rawLimit, rawUsed] = m;
+    if (!rawScope || !rawWindow || !rawLimit || !rawUsed)
+        return null;
+    const scope = rawScope.toLowerCase();
+    const window = rawWindow.toLowerCase();
+    const limit = Number(rawLimit);
+    const used = Number(rawUsed);
+    if (!Number.isFinite(limit) || !Number.isFinite(used))
+        return null;
+    return {
+        provider: link.provider.id,
+        model: link.model,
+        scope,
+        // Straight from the vendor's own sentence, so unlike a header name this
+        // window is not a guess and must not be overridden by the provider profile.
+        window,
+        limit,
+        // The refusal names what was consumed, not what is left. Clamped because a
+        // vendor counting a rejected request against the total would otherwise
+        // produce a negative "remaining" and a dashboard that renders nonsense.
+        remaining: Math.max(0, limit - used),
+        resetAt: retryAfterSec === null ? null : now + retryAfterSec * 1000,
+        source: "429-body",
+        observedAt: now,
+    };
+}
 /**
  * Turn a remaining-token count into the unit a person thinks in.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "license": "MIT",
   "author": "Mao Nakamoto",
   "homepage": "https://github.com/bitbaum/ai-kit#readme",

package/src/index.ts

@@ -141,6 +141,7 @@ export {
   type HeaderBag,
   readQuota,
   readingFromRefusal,
+  readingFromRefusalBody,
   parseResetAt,
   answersRemaining,
 } from "./meter.js";

package/src/meter.ts

@@ -248,6 +248,72 @@ export function readingFromRefusal(
   };
 }
 
+/**
+ * The counter a vendor discloses ONLY when it refuses.
+ *
+ * ── WHY A BODY PARSER EARNS ITS KEEP ─────────────────────────────────────────
+ *
+ * Headers do not describe every limit a vendor enforces. Groq publishes its
+ * per-minute token window and its per-day REQUEST count as headers, and meters
+ * a third limit — tokens per DAY — that appears in no header at all. It is
+ * stated once, in prose, in the body of the 429 that enforces it:
+ *
+ *   Rate limit reached for model `openai/gpt-oss-20b` in organization `org_…`
+ *   service tier `on_demand` on tokens per day (TPD): Limit 200000,
+ *   Used 199773, Requested 571. Please try again in 2m28.608s.
+ *
+ * Observed on production 2026-09-13. Every header the same response carried
+ * looked healthy — 2,672 of 8,000 tokens left this minute, 999 of 1,000
+ * requests left today — while the account was locked out of the model for the
+ * rest of the day. A dashboard fed only by headers therefore reported a
+ * working provider throughout an outage, which is precisely the failure the
+ * top of this file exists to prevent, arriving through a door it left open.
+ *
+ * ── STILL NEVER INVENTS ──────────────────────────────────────────────────────
+ *
+ * Returns null unless the body states the numbers. An unparsed refusal is the
+ * "did not say" state, and the caller should fall back to `readingFromRefusal`,
+ * which records the one fact a 429 always carries: spent, now.
+ */
+const REFUSAL_COUNTER =
+  /on\s+(tokens|requests)\s+per\s+(minute|day)\s*\([^)]*\)\s*:\s*Limit\s+(\d+)\s*,\s*Used\s+(\d+)/i;
+
+export function readingFromRefusalBody(
+  link: Link,
+  body: string,
+  retryAfterSec: number | null = null,
+  now = Date.now(),
+): QuotaReading | null {
+  const m = REFUSAL_COUNTER.exec(body);
+  if (!m) return null;
+
+  const [, rawScope, rawWindow, rawLimit, rawUsed] = m;
+  if (!rawScope || !rawWindow || !rawLimit || !rawUsed) return null;
+
+  const scope = rawScope.toLowerCase() as QuotaScope;
+  const window = rawWindow.toLowerCase() as QuotaWindow;
+  const limit = Number(rawLimit);
+  const used = Number(rawUsed);
+  if (!Number.isFinite(limit) || !Number.isFinite(used)) return null;
+
+  return {
+    provider: link.provider.id,
+    model: link.model,
+    scope,
+    // Straight from the vendor's own sentence, so unlike a header name this
+    // window is not a guess and must not be overridden by the provider profile.
+    window,
+    limit,
+    // The refusal names what was consumed, not what is left. Clamped because a
+    // vendor counting a rejected request against the total would otherwise
+    // produce a negative "remaining" and a dashboard that renders nonsense.
+    remaining: Math.max(0, limit - used),
+    resetAt: retryAfterSec === null ? null : now + retryAfterSec * 1000,
+    source: "429-body",
+    observedAt: now,
+  };
+}
+
 /**
  * Turn a remaining-token count into the unit a person thinks in.
  *