cartethyia 2.5.3 → 2.5.6

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/grok/grok.ts

@@ -373,11 +373,10 @@ function normalizeTools(payload: Record<string, unknown>): void {
       normalized.push(tool);
       continue;
     }
-    // Tools arrive factory-normalized (flat `{type:"function",name,parameters}`;
-    // canonical tools are flat, so the legacy nested `function.*` resolution
-    // duplicated the factory payload path and is deleted). Only grok wire
-    // strictness stays here: trimmed names, empty-name drop, parameters
-    // fallback, custom-tool synthesis.
+    // Tools arrive factory-normalized (flat `{type:"function",name,parameters}`
+    // — canonical tools are flat, so there is no nested `function.*` payload to
+    // resolve). Only grok wire strictness stays here: trimmed names,
+    // empty-name drop, parameters fallback, custom-tool synthesis.
     const name = typeof tool.name === "string" ? tool.name : "";
     if (!name.trim()) continue;
     const parameters =
@@ -413,8 +412,8 @@ function normalizeTools(payload: Record<string, unknown>): void {
     if (type === "function" || type === "custom") {
       // Unlike `tools`, `tool_choice` genuinely arrives nested: the chat
       // encoder writes `{type:"function", function:{name}}` and
-      // `{type:"custom", custom:{name}}`, so these reads are not a legacy
-      // leftover even though the tools loop above dropped its own nested path.
+      // `{type:"custom", custom:{name}}`, so these nested reads are required
+      // even though the tools loop above has no nested path.
       const fn = value.function;
       const nested = fn && typeof fn === "object" && !Array.isArray(fn) ? fn as Record<string, unknown> : undefined;
       const custom = value.custom;

package/src/providers/integrations/hermes.ts

@@ -28,17 +28,15 @@ const HERMES_PROVIDER_ID = "hermes" as const;
  * (`agent/portal_tags.py` in `NousResearch/hermes-agent`). Neither is required
  * for dispatch — a request carrying only `user=` answers 200 — but they are
  * sent because they are the client's real attribution and cost nothing. The
- * client version tracks the released tag `v2026.9.24`, which is date-based:
- * Hermes does not publish a semver, so the `0.13.0` this used to claim was not
- * a version Hermes ever had.
+ * client version is read from `getHermesVersion()` and sent in the shape the
+ * released tags use (`v<version>`): Hermes does not publish a semver, so its
+ * versions are date-based release tags.
  */
 /**
  * Builds the portal tags for one dispatch.
  *
- * `client=` carries the version in the shape the released tag used
- * (`v<version>`), but the version itself is now the resolved one: the previous
- * constant named a date tag (`v2026.9.24`) that was neither a release nor the
- * version the project publishes. `getHermesVersion()` tracks the real release.
+ * `client=` carries the resolved version in the shape the released tags use
+ * (`v<version>`); `getHermesVersion()` tracks the real release.
  */
 function hermesPortalTags(): readonly string[] {
   return [
@@ -66,25 +64,23 @@ import type { ModelDefinition } from "../provider-model-definition";
  *
  * `loadModelDiscovery` supersedes this list whenever `/v1/models` answers, so
  * these numbers are only read by a fetch that failed. They are the upstream's
- * own `context_length` and `top_provider.max_completion_tokens` — the previous
- * values were a uniform `8192` output for every row, which understated every
- * one of them.
+ * own `context_length` and `top_provider.max_completion_tokens`, stated per row
+ * because they differ per row.
  *
- * Two ids that used to live here are gone because upstream no longer carries
- * them: `tencent/hy3:free` (absent from the catalog entirely) and
- * `upstage/solar-pro4:free` (only the billed `upstage/solar-pro4` and the free
- * `upstage/solar-mini4:free` exist).
+ * Two ids upstream no longer carries are absent: `tencent/hy3:free` (missing
+ * from the catalog entirely) and `upstage/solar-pro4:free` (only the billed
+ * `upstage/solar-pro4` and the free `upstage/solar-mini4:free` exist).
  */
 export const HERMES_MODELS: readonly ModelDefinition[] = [
   // The live `/models` free rows, with the limits the catalog states. Verified
   // against the API: every id here answers 200.
   //
-  // `meituan/longcat-2.0:free` is gone: the catalog still lists the id, but
-  // dispatching it answers 404 "This model is no longer free", so keeping it
+  // `meituan/longcat-2.0:free` is excluded: the catalog still lists the id, but
+  // dispatching it answers 404 "This model is no longer free", so listing it
   // would be a card that can only ever fail. `meituan/longcat-2.5-preview:free`
-  // replaces it and answers 200.
+  // is listed instead and answers 200.
   //
-  // `stepfun/step-5-preview:free` is gone: it is absent from the live catalog
+  // `stepfun/step-5-preview:free` is excluded: it is absent from the live catalog
   // entirely and dispatching it answers 404 "This model's free period has
   // ended" — a retired row, not a capacity blip, so it cannot be left in.
   //

package/src/providers/integrations/kiro/kiro-discovery.ts

@@ -31,7 +31,7 @@ const MAX_DISCOVERED_MODELS = 500;
 const KIRO_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
 
 /**
- * Ids the seed catalog deliberately no longer carries.
+ * Ids the seed catalog deliberately excludes.
  *
  * Discovery adds every id the upstream lists, so without this a retired row
  * comes back the moment an account fetches its models. The seed is the owner

package/src/providers/integrations/kiro/kiro.ts

@@ -8,7 +8,7 @@
 // Two upstream behaviours drive the header and endpoint logic:
 //
 //  * There is exactly one generation surface, `q.{region}.amazonaws.com`. The
-//    legacy `codewhisperer.*` host and the vendor's own path-style gateway are
+//    `codewhisperer.*` host and the vendor's own path-style gateway are
 //    not what the real client talks to, and reaching for them is actively
 //    harmful: an account that has just been refused would immediately probe two
 //    other service entries with the same token, which is the shape of credential

package/src/providers/integrations/mistral.ts

@@ -6,12 +6,12 @@ const MISTRAL_PROVIDER_ID = "mistral" as const;
 /**
  * Mistral's own current generalist tiers.
  *
- * The provider is registered as a generic OpenAI-compatible API-key provider, so
- * it carried no catalog at all and every model it serves was absent until a
- * discovery run happened to fetch them. These are the two `latest` aliases
- * Mistral keeps pointed at its current generalist models — `mistral-large-latest`
- * (Large 4) and `mistral-medium-latest` (Medium 3.5), per the Mistral model
- * overview.
+ * The provider is registered as a generic OpenAI-compatible API-key provider,
+ * which carries no catalog of its own: without this list, every model it serves
+ * stays absent until a discovery run happens to fetch them. These are the two
+ * `latest` aliases Mistral keeps pointed at its current generalist models —
+ * `mistral-large-latest` (Large 4) and `mistral-medium-latest` (Medium 3.5),
+ * per the Mistral model overview.
  *
  * Limits and pricing come from the base catalog via `providerId`: `defineModel`
  * resolves `mistral:<id>` and falls back to the majority row, so no number is

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

@@ -23,11 +23,11 @@ const SESSION_COUNTER_MAX = 63;
  * `ses_` + 12-char hex (bitwise inverted millisecond timestamp * 4096 + seq) + 14-char base62.
  *
  * The counter is capped rather than left to grow. Sixty-four dispatches inside
- * one millisecond used to emit ids the gate refuses, so a burst — exactly what
- * a proxy pool produces — 403'd on its own headers while every other field was
+ * one millisecond emit ids the gate refuses, so a burst — exactly what a proxy
+ * pool produces — would 403 on its own headers while every other field was
  * correct. On overflow the timestamp advances by one millisecond instead: the
  * id stays inside the window, and the only cost is that ids minted in the same
- * real millisecond no longer sort as the client's would.
+ * real millisecond do not sort as the client's would.
  */
 export function generateOpenCodeSessionId(now = Date.now()): string {
   if (now !== lastTimestamp) {

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

@@ -79,7 +79,7 @@ const UNAVAILABLE_FREE_ZEN_IDS: readonly string[] = [
  * `CARTETHYIA_OPENCODE_UNAVAILABLE_FREE` lets an operator correct that
  * immediately: a comma-separated list that *replaces* the bundled one, or the
  * single token `none` to trust the listing completely. The bundled ids remain
- * the default so an unconfigured install behaves exactly as it does today.
+ * the default so an unconfigured install keeps these refusals.
  */
 function unavailableFreeZenIds(): readonly string[] {
   const override = resolveOpenCodeUnavailableFree();
@@ -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);
 }
 
 /**
@@ -159,11 +163,11 @@ function opencodeDesktopHeaders(
     // The free-tier gate refuses non-streaming dispatches with 403
     // FreeTierError, so free models always advertise SSE regardless of the
     // client's own Accept; billed models keep the JSON default. The value is
-    // what OpenCode 2.x's AI SDK sends, not the narrower
-    // `text/event-stream` we used to claim — the gate always accepted the
-    // narrow one, so this is alignment with the real client rather than a
-    // fix for a live failure. It costs nothing: `stream: true` is forced on
-    // the body either way, so the upstream answers SSE regardless.
+    // what OpenCode 2.x's AI SDK sends — a broader Accept than the narrower
+    // `text/event-stream` the gate is known to accept, so this is alignment
+    // with the real client rather than a fix for a live failure. It costs
+    // nothing: `stream: true` is forced on the body either way, so the upstream
+    // answers SSE regardless.
     ...(freeModel ? { accept: FREE_TIER_ACCEPT } : {}),
   };
 }
@@ -493,29 +497,24 @@ 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 excluded: the live Zen roster does not list
+  // 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),
 ];
 
 export const OPENCODE_GO_MODELS: readonly ModelDefinition[] = [
-  // `muse-spark-1.2` is retired upstream; the catalog files
+  // `muse-spark-1.2` is not served upstream; the catalog files
   // `muse-spark-1.2-contributor` at 1048576/131072, which is what this row
   // serves.
   defineModel({ id: "muse-spark-1.2-contributor", providerId: "opencode-go", wireFamily: "responses", endpoint: `${GO_PATH_PREFIX}/responses`, ctx: 1048576, out: 131072, vision: true, reasoning: true }),