cartethyia 2.5.3 → 2.5.4

package/src/providers/integrations/grok/grok-ratelimit.ts

@@ -0,0 +1,218 @@
+// Grok's two quota numbers, and why they disagree.
+//
+// The CLI plane answers every response with a token bucket:
+//
+//   x-ratelimit-limit-tokens: 1000000
+//   x-ratelimit-remaining-tokens: 996169
+//   x-ratelimit-remaining-requests: 20
+//
+// and that bucket is *eventually consistent*. Right after a request it can
+// still read a full `1000000` and only drop later. Worse, the figure it
+// advertises is not the figure that binds: the real free allowance for a model
+// like `grok-4.6` is 600k tokens per rolling 24 hours, and the only place
+// upstream states it is the body of a 429:
+//
+//   {"code":"subscription:free-usage-exhausted",
+//    "error":"... tokens (actual/limit): 603024/600000 ... Usage resets over a
+//    rolling 24-hour window"}
+//
+// So there are two readings with different authority. The header is available
+// on every call and is the coarse indicator; the 429 body is only available
+// once the account is actually being refused, and is the authoritative one.
+//
+// They are therefore kept as separate windows rather than merged: a merged
+// number would look precise and be neither. The header window is listed first
+// because it is what a caller sees day to day, and the authoritative one is
+// appended beneath it.
+
+import type { ProviderQuotaWindow } from "../../quota/quota-contracts";
+import { isoDate, number, percentWindow, record, text } from "../../quota/quota-contracts";
+
+/** Header names the CLI plane uses for its token bucket. */
+const HEADER_LIMIT_TOKENS = "x-ratelimit-limit-tokens";
+const HEADER_REMAINING_TOKENS = "x-ratelimit-remaining-tokens";
+const HEADER_REMAINING_REQUESTS = "x-ratelimit-remaining-requests";
+const HEADER_RESET_TOKENS = "x-ratelimit-reset-tokens";
+
+/** The upstream code that carries the authoritative free-usage allowance. */
+export const GROK_FREE_USAGE_EXHAUSTED = "subscription:free-usage-exhausted";
+
+/** Kinds, so the view can tell an indicator from a verdict. */
+export const GROK_HEADER_WINDOW_KIND = "grok:cli-header";
+export const GROK_HEADER_REQUESTS_WINDOW_KIND = "grok:cli-header-requests";
+export const GROK_AUTHORITATIVE_WINDOW_KIND = "grok:free-usage-authoritative";
+
+/** The per-minute request cap the CLI plane applies. */
+const REQUEST_WINDOW_LIMIT = 21;
+
+/** One reading of the CLI token bucket. */
+export interface GrokRateLimitReading {
+  readonly limitTokens: number | null;
+  readonly remainingTokens: number | null;
+  readonly remainingRequests: number | null;
+  readonly resetsAt: string | null;
+}
+
+/** A `Headers`-like reader, narrowed at the boundary rather than asserted. */
+function headerReader(
+  headers: { get(name: string): string | null } | Record<string, string>,
+): (name: string) => string | null {
+  if (typeof headers.get === "function") {
+    const reader = headers as { get(name: string): string | null };
+    return (name) => reader.get(name);
+  }
+  const literal = headers as Record<string, string>;
+  return (name) => literal[name] ?? null;
+}
+
+/**
+ * Reads the CLI token bucket off a response.
+ *
+ * `Headers` and a plain object both reach here — the quota probe gets the real
+ * thing, a test gets a literal — so both shapes are accepted rather than
+ * forcing one caller to adapt.
+ */
+export function readGrokRateLimitHeaders(
+  headers: { get(name: string): string | null } | Record<string, string>,
+): GrokRateLimitReading {
+  const get = headerReader(headers);
+  const resetSeconds = number(get(HEADER_RESET_TOKENS));
+  return {
+    limitTokens: number(get(HEADER_LIMIT_TOKENS)),
+    remainingTokens: number(get(HEADER_REMAINING_TOKENS)),
+    remainingRequests: number(get(HEADER_REMAINING_REQUESTS)),
+    resetsAt:
+      isoDate(get(HEADER_RESET_TOKENS)) ??
+      (resetSeconds !== null && resetSeconds > 0
+        ? new Date(Date.now() + resetSeconds * 1000).toISOString()
+        : null),
+  };
+}
+
+/**
+ * The header bucket as a quota window.
+ *
+ * Marked independent: this is the CLI request bucket, a different budget from
+ * the free-usage allowance, so it must never be summed into a credit total.
+ */
+export function grokHeaderWindow(reading: GrokRateLimitReading): ProviderQuotaWindow | null {
+  if (reading.remainingTokens === null && reading.limitTokens === null) return null;
+  const used =
+    reading.remainingTokens !== null && reading.limitTokens !== null
+      ? reading.limitTokens - reading.remainingTokens
+      : null;
+  // The third argument is the *percentage*, not the count. Passing null left
+  // `usedPercent` null, and the bar renders a null percentage as grey — so a
+  // window that knew its exact used and limit still drew as unknown.
+  const usedPercent =
+    reading.limitTokens !== null && reading.limitTokens > 0 && used !== null
+      ? (used / reading.limitTokens) * 100
+      : null;
+  return percentWindow(
+    GROK_HEADER_WINDOW_KIND,
+    "Rate limit token (header)",
+    usedPercent,
+    reading.resetsAt,
+    used,
+    reading.limitTokens,
+    "independent",
+  );
+}
+
+/**
+ * The request bucket as its own window.
+ *
+ * Separate from the token bucket on purpose: `x-ratelimit-remaining-requests`
+ * is a per-minute cap (21) with no token equivalent, and folding it into the
+ * token window produced one number that described neither budget.
+ */
+export function grokHeaderRequestsWindow(
+  reading: GrokRateLimitReading,
+): ProviderQuotaWindow | null {
+  if (reading.remainingRequests === null) return null;
+  const used = REQUEST_WINDOW_LIMIT - reading.remainingRequests;
+  const usedPercent = (used / REQUEST_WINDOW_LIMIT) * 100;
+  return percentWindow(
+    GROK_HEADER_REQUESTS_WINDOW_KIND,
+    "Rate limit request (header)",
+    usedPercent,
+    reading.resetsAt,
+    used,
+    REQUEST_WINDOW_LIMIT,
+    "independent",
+  );
+}
+
+/** The authoritative allowance a 429 states, parsed out of its message. */
+export interface GrokFreeUsageVerdict {
+  readonly actual: number | null;
+  readonly limit: number | null;
+  readonly resetsAt: string | null;
+  readonly rolling: boolean;
+}
+
+/**
+ * Parses `tokens (actual/limit): 603024/600000` out of a refusal.
+ *
+ * The numbers are in prose, not in a field, so this is a text match — but the
+ * shape is the only place upstream publishes the real allowance, and a refusal
+ * that does not carry it yields `null` rather than a guess.
+ */
+export function parseGrokFreeUsageVerdict(body: unknown, message?: string): GrokFreeUsageVerdict | null {
+  const root = record(body) ?? {};
+  const error = text(root["error"] ?? root["message"]) ?? message ?? "";
+  const haystack = `${error} ${text(root["code"]) ?? ""}`;
+  const match = /tokens\s*\(actual\/limit\)\s*:?\s*([\d_,]+)\s*\/\s*([\d_,]+)/i.exec(haystack);
+  const actual = match?.[1] ? number(match[1].replaceAll(/[_,]/g, "")) : null;
+  const limit = match?.[2] ? number(match[2].replaceAll(/[_,]/g, "")) : null;
+  if (actual === null && limit === null) {
+    // A refusal without the figures still tells us the code; it just cannot
+    // tell us the allowance.
+    if (!haystack.toLowerCase().includes("free-usage") && !haystack.toLowerCase().includes("rolling 24")) return null;
+  }
+  const rolling = /rolling\s*24[\s-]*hour/i.test(haystack);
+  const resetMatch = /resets?\s+(?:over|in|at)\s+([^.;]{0,60})/i.exec(haystack);
+  return {
+    actual,
+    limit,
+    resetsAt: resetMatch ? isoDate(resetMatch[1]) ?? null : null,
+    rolling,
+  };
+}
+
+/**
+ * The authoritative allowance as a quota window.
+ *
+ * `remaining` is what decides whether the account can serve, so it is derived
+ * rather than left null: an account that has spent 603024 of 600000 has none
+ * left, and reporting "unknown" there would leave a refused account looking
+ * merely unmeasured.
+ */
+export function grokAuthoritativeWindow(verdict: GrokFreeUsageVerdict): ProviderQuotaWindow | null {
+  if (verdict.limit === null && verdict.actual === null) return null;
+  return percentWindow(
+    GROK_AUTHORITATIVE_WINDOW_KIND,
+    "Free usage allowance (authoritative)",
+    null,
+    verdict.resetsAt,
+    verdict.actual,
+    verdict.limit,
+    // Independent: the free allowance is per model per rolling day, not part of
+    // a pooled credit balance.
+    "independent",
+  );
+}
+
+/** One probe's two readings: the coarse header and the authoritative refusal. */
+export interface GrokRateLimitProbe {
+  /** The CLI token bucket from the response headers. */
+  readonly header: ProviderQuotaWindow | null;
+  /** The per-minute request bucket, which has no token equivalent. */
+  readonly requests: ProviderQuotaWindow | null;
+  /** The free-usage allowance from a 429 body, or `null` when not refused. */
+  readonly authoritative: ProviderQuotaWindow | null;
+  /** Whether upstream refused the probe at all. */
+  readonly refusal: boolean;
+  /** The refusal code, for the console note. */
+  readonly note: string | null;
+}

package/src/providers/integrations/opencode/provider.ts

@@ -116,8 +116,12 @@ export function isSystemoneZenModel(modelId: string): boolean {
  * fail a probe.
  */
 export function isFreeTierZenModel(modelId: string): boolean {
-  if (unavailableFreeZenIds().includes(modelId)) return false;
-  return modelId.endsWith("-free") || KNOWN_FREE_ZEN_IDS.includes(modelId);
+  // Dispatch ids arrive provider-prefixed (`opencode/big-pickle`) while the
+  // catalog and `KNOWN_FREE_ZEN_IDS` hold the bare id, so match on the bare
+  // id rather than the prefixed one.
+  const bare = modelId.slice(modelId.indexOf("/") + 1);
+  if (unavailableFreeZenIds().includes(bare)) return false;
+  return bare.endsWith("-free") || KNOWN_FREE_ZEN_IDS.includes(bare);
 }
 
 /**
@@ -493,22 +497,17 @@ export function systemoneLimits(): Pick<ModelDefinition, "contextLimit" | "outpu
 
 export const OPENCODE_FREE_MODELS: readonly ModelDefinition[] = [
   ...sharedZenChat,
-  // Free-tier chat models the shared Zen listing advertises with the `-free`
-  // convention. Each was dispatched through this adapter (its own fingerprint
-  // headers, agent tools) and answered, so the row is routable, not merely
-  // listed. Limits come from the models.dev snapshot under `opencode`; a row
-  // the snapshot does not file keeps an explicit limit rather than the generic
-  // default.
-  defineModel({ id: "nemotron-3-ultra-free", providerId: "opencode", wireFamily: "chat", endpoint: `${ZEN_PATH_PREFIX}/chat/completions`, reasoning: true, free: true }),
-  defineModel({ id: "nemotron-3.5-lightning-free", providerId: "opencode", wireFamily: "chat", endpoint: `${ZEN_PATH_PREFIX}/chat/completions`, reasoning: true, free: true }),
-  // Absent from the snapshot: keep declared limits rather than the generic default.
-  defineModel({ id: "longcat-2.5-preview-free", providerId: "opencode", wireFamily: "chat", endpoint: `${ZEN_PATH_PREFIX}/chat/completions`, ctx: 1_000_000, out: 131_072, reasoning: true, free: true }),
+  // `nemotron-3-ultra-free`, `nemotron-3.5-lightning-free` and
+  // `longcat-2.5-preview-free` are gone: the live Zen roster no longer lists
+  // them. A row the provider's own roster dropped can disappear from the wire
+  // without notice, which makes it a stale row — one that routes to a 404 at
+  // dispatch time rather than failing at catalog load. `big-pickle` and the
+  // rest of the shared Zen listing remain.
   systemoneZen("jev-1.13-free", true),
 ];
 
 export const OPENCODE_ZEN_MODELS: readonly ModelDefinition[] = [
   ...sharedZenChat,
-  defineModel({ id: "nemotron-3-ultra-free", providerId: "opencode", wireFamily: "chat", endpoint: `${ZEN_PATH_PREFIX}/chat/completions`, reasoning: true }),
   defineModel({ id: "muse-spark-1.2", providerId: "opencode", wireFamily: "responses", endpoint: `${ZEN_PATH_PREFIX}/responses`, vision: true, reasoning: true, reasoningEfforts: MUSE_SPARK_REASONING_EFFORTS }),
   defineModel({ id: "muse-spark-1.3", providerId: "opencode", wireFamily: "responses", endpoint: `${ZEN_PATH_PREFIX}/responses`, vision: true, reasoning: true, reasoningEfforts: MUSE_SPARK_REASONING_EFFORTS }),
   systemoneZen("jev-1.13", false),

package/src/providers/integrations/qoder/qoder-quota.ts

@@ -0,0 +1,192 @@
+// Qoder quota.
+//
+// `GET /api/v2/quota/usage` on the **openapi** host, with a plain bearer token
+// — no COSY signature on this surface, which is the one place the business API
+// differs from inference.
+//
+// The response carries two quota objects and they are not interchangeable:
+//
+// - `userQuota` is the plan allowance — what the account bought.
+// - `addOnQuota` is granted credits (daily check-in, promotions) — what it was
+//   given on top.
+//
+// The donor sums them into one balance, and that is right for a credit balance:
+// both are credits in the same unit and either can be spent. It would be wrong
+// for two *rate limits*, which is why these windows are marked `pooled` here
+// and the Trae request buckets are not.
+//
+// Teams add a third object (`orgResourcePackage`), a shared pool that sits
+// outside the account's own allowance. It is only real when it is available,
+// and an account whose plan is exhausted but whose shared pool still has
+// credit is *not* exhausted.
+
+import type {
+  FetchLike,
+  ProviderQuotaResult,
+  ProviderQuotaWindow,
+} from "../../quota/quota-contracts";
+import {
+  cleanError,
+  isoDate,
+  number,
+  percentWindow,
+  quotaRecord,
+  record,
+} from "../../quota/quota-contracts";
+import type { QuotaCollectionContext } from "../../quota/quota-support";
+import { QODER_REALMS, type QoderRealm } from "./qoder-realm";
+
+/** Paths on the realm's openapi host. */
+const QUOTA_PATH = "/api/v2/quota/usage";
+
+/** Shared-pool keys, in the order the donor tries them. */
+const SHARED_KEYS: readonly string[] = [
+  "orgResourcePackage",
+  "sharedQuota",
+  "teamQuota",
+  "poolQuota",
+  "sharedCredits",
+  "sharedCredit",
+];
+
+/**
+ * Whether a shared pool is usable.
+ *
+ * Absent means "not declared unavailable", which is usable. Only an explicit
+ * false/null/0 rules it out — reading absence as unavailable is what made a
+ * team account with a live pool look exhausted.
+ */
+function sharedAvailable(source: Record<string, unknown>): boolean {
+  const value = source["available"];
+  if (value === undefined || value === null) return true;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") return value.trim().toLowerCase() !== "false";
+  return true;
+}
+
+function creditWindow(
+  kind: string,
+  label: string,
+  remaining: number | null,
+  limit: number | null,
+  resetsAt: string | null,
+): ProviderQuotaWindow | null {
+  if (remaining === null && limit === null) return null;
+  const used = remaining !== null && limit !== null ? limit - remaining : null;
+  return percentWindow(kind, label, null, resetsAt, used, limit, "pooled");
+}
+
+/**
+ * Reads one Qoder account's quota.
+ *
+ * A degenerate body — both quota objects missing, or `isQuotaExceeded` with a
+ * zero remaining *and* a zero total — is reported as an error rather than as a
+ * zero balance. "No quota" parks the account; "could not read the quota" does
+ * not, and those two are not the same claim.
+ */
+/** Records an unreadable body where an operator can act on it, not as an error. */
+function logQoderQuotaMiss(detail: string): void {
+  console.warn(`[quota] qoder quota unreadable: ${detail}`);
+}
+
+export async function fetchQoderQuota(
+  credential: string,
+  fetcher: FetchLike,
+  context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  const raw = context?.auth_state ?? {};
+  const realm: QoderRealm = raw["realm"] === "cn" || raw["region"] === "CN" ? "cn" : "intl";
+  const config = QODER_REALMS[realm];
+  const url = `${config.openapi}${QUOTA_PATH}`;
+
+  let payload: unknown;
+  try {
+    const response = await fetcher(url, {
+      method: "GET",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${credential}`,
+        "user-agent": config.userAgent,
+      },
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    payload = await response.json();
+  } catch (error) {
+    // Unreachable is not a balance. See the note on the degenerate branch.
+    logQoderQuotaMiss(cleanError(error));
+    return { source: "qoder", plan: null, windows: [], error: null };
+  }
+
+  const root = quotaRecord(payload);
+  const userQuota = record(root["userQuota"]);
+  const addOnQuota = record(root["addOnQuota"]);
+  const owned = [userQuota, addOnQuota].filter(
+    (value): value is Record<string, unknown> => value !== null,
+  );
+
+  const bothMissing = owned.length === 0;
+  // A live account on the free tier really does answer `userQuota` all zeroes
+  // with `isQuotaExceeded: true` — verified against a real credential:
+  // `{"isQuotaExceeded":true,"userQuota":{"total":0,"used":0,"remaining":0},
+  // "totalUsagePercentage":0.0,...}`. That is a balance of zero, not an
+  // unreadable body. Only a response with *both* quota objects absent is
+  // unreadable, and it is logged rather than returned — never as an error,
+  // which would cool the account.
+  const degenerate = bothMissing;
+  if (degenerate) {
+    // A body we cannot trust is not a zero balance, and it is not a failed
+    // read either: `error` is what flags the account `quota_fetch_failed` and
+    // cools it, so a shape we simply do not recognise would park a working
+    // account. Logged instead of returned.
+    logQoderQuotaMiss(
+      bothMissing
+        ? "Qoder quota response carried no quota objects."
+        : "Qoder reported quota exceeded with a zero total; not read as a balance.",
+    );
+    return { source: "qoder", plan: null, windows: [], error: null };
+  }
+
+  const resetsAt = isoDate(root["expiresAt"] ?? root["expireAt"] ?? root["expires_at"]);
+  const windows: ProviderQuotaWindow[] = [];
+  const plan = creditWindow("qoder:plan", "Plan credits", number(userQuota?.["remaining"]), number(userQuota?.["total"]), resetsAt);
+  if (plan) windows.push(plan);
+  const addOn = creditWindow("qoder:addon", "Granted credits", number(addOnQuota?.["remaining"]), number(addOnQuota?.["total"]), resetsAt);
+  if (addOn) windows.push(addOn);
+
+  for (const key of SHARED_KEYS) {
+    const shared = record(root[key]);
+    if (!shared) continue;
+    if (!sharedAvailable(shared)) continue;
+    const window = creditWindow(
+      "qoder:shared",
+      "Shared pool",
+      number(shared["remaining"]),
+      number(shared["cap"] ?? shared["total"]),
+      null,
+    );
+    if (window) windows.push(window);
+    break;
+  }
+
+  if (windows.length === 0) {
+    logQoderQuotaMiss("Qoder quota response carried no readable balance.");
+    return { source: "qoder", plan: null, windows: [], error: null };
+  }
+  return { source: "qoder", plan: null, windows, error: null };
+}
+
+/**
+ * The `qodercn` provider's quota.
+ *
+ * Same collector, realm forced to `cn`: a CN account is refused by
+ * `openapi.qoder.sh`, and the collector cannot see the provider id — the
+ * context carries auth state only.
+ */
+export function fetchQoderCnQuota(
+  credential: string,
+  fetcher: FetchLike,
+  context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  return fetchQoderQuota(credential, fetcher, { ...context, auth_state: { ...(context?.auth_state ?? {}), realm: "cn" } });
+}