cartethyia 2.5.2 → 2.5.4

package/src/providers/integrations/cursor/protocol/messages.ts

@@ -1503,6 +1503,27 @@ export function createMessageTypes(): protobuf.Root {
     { id: 1, name: "request_context", type: "RequestContextPayload" },
   ])
 
+  // Allowlist prechecks (exec #41/#42/#43): Cursor asks whether a shell
+  // command / MCP tool / web fetch would be permitted before it emits the
+  // real call. Without an args frame this is decodable, but its exec id is
+  // then stranded — the server waits forever for the matching result.
+  addType(root, "ShellAllowlistPrecheckArgs", [
+    { id: 1, name: "command", type: "string" },
+    { id: 2, name: "working_directory", type: "string" },
+    { id: 3, name: "parsing_result", type: "bytes" },
+    { id: 4, name: "classifier_result", type: "bytes" },
+    { id: 5, name: "tool_call_id", type: "string" },
+  ])
+  addType(root, "McpAllowlistPrecheckArgs", [
+    { id: 1, name: "provider_identifier", type: "string" },
+    { id: 2, name: "tool_name", type: "string" },
+    { id: 3, name: "tool_call_id", type: "string" },
+  ])
+  addType(root, "WebFetchAllowlistPrecheckArgs", [
+    { id: 1, name: "url", type: "string" },
+    { id: 2, name: "tool_call_id", type: "string" },
+  ])
+
   addType(root, "RequestContextResult", [
     { id: 1, name: "success", type: "RequestContextSuccess" },
   ])
@@ -1568,6 +1589,9 @@ export function createMessageTypes(): protobuf.Root {
       { id: 18, name: "read_mcp_resource_exec_args", type: "ReadMcpResourceExecArgs" },
       { id: 28, name: "subagent_args", type: "SubagentArgs" },
       { id: 36, name: "mcp_state_exec_args", type: "McpStateExecArgs" },
+      { id: 41, name: "shell_allowlist_precheck_args", type: "ShellAllowlistPrecheckArgs" },
+      { id: 42, name: "mcp_allowlist_precheck_args", type: "McpAllowlistPrecheckArgs" },
+      { id: 43, name: "web_fetch_allowlist_precheck_args", type: "WebFetchAllowlistPrecheckArgs" },
       { id: 44, name: "git_diff_request", type: "GetDiffRequest" },
       { id: 45, name: "pi_read_args", type: "PiReadToolArgs" },
       { id: 46, name: "pi_bash_args", type: "PiBashToolArgs" },
@@ -1582,6 +1606,7 @@ export function createMessageTypes(): protobuf.Root {
       "shell_args", "write_args", "delete_args", "grep_args", "read_args", "ls_args",
       "request_context_args", "mcp_args", "shell_stream_args", "background_shell_spawn_args",
       "list_mcp_resources_exec_args", "read_mcp_resource_exec_args", "mcp_state_exec_args",
+      "shell_allowlist_precheck_args", "mcp_allowlist_precheck_args", "web_fetch_allowlist_precheck_args",
       "subagent_args", "git_diff_request",
       "pi_read_args", "pi_bash_args", "pi_edit_args", "pi_write_args",
       "pi_grep_args", "pi_find_args", "pi_ls_args",

package/src/providers/integrations/factory/factory.ts

@@ -496,7 +496,14 @@ class FactoryDroidAdapter implements ProviderAdapter {
       response = await outboundFetch(url, {
         method: "POST",
         headers,
-        body: JSON.stringify(buildGeminiPayload(request)),
+        body: JSON.stringify(
+          buildGeminiPayload(
+            request,
+            ...(context.image_clamp_max_bytes === undefined
+              ? []
+              : [{ maxBytesOverride: context.image_clamp_max_bytes }]),
+          ),
+        ),
         signal: lifecycle.signal,
       });
     } catch (error: unknown) {

package/src/providers/integrations/gemini.ts

@@ -189,7 +189,12 @@ class GeminiAdapter implements ProviderAdapter {
     const action = request.stream ? "streamGenerateContent?alt=sse" : "generateContent";
     const url = geminiModelUrl(this.baseUrl, model, action);
 
-    const payload = buildGeminiPayload(request);
+    const payload = buildGeminiPayload(
+      request,
+      ...(context.image_clamp_max_bytes === undefined
+        ? []
+        : [{ maxBytesOverride: context.image_clamp_max_bytes }]),
+    );
     if (
       request.tools?.some(
         (tool) =>

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

@@ -1,177 +1,279 @@
-import type { FetchLike, ProviderQuotaResult, ProviderQuotaWindow } from "../../quota/quota-contracts";
-import { isoDate, number, percentWindow, record, text } from "../../quota/quota-contracts";
-import { buildGrokAuthUserAgent, getGrokVersion } from "../../operations/client-versions";
-import { decodeGrokCreditsFrame } from "./grok-quota-frame";
-
-const BILLING_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
-const BILLING_SOURCE = "cli-chat-proxy.grok.com/v1/billing";
-const USER_URL = "https://cli-chat-proxy.grok.com/v1/user?include=subscription";
-const GRPC_CREDITS_URL = "https://grok.com/grok_api_v2.GrokBuildBilling/GetGrokCreditsConfig";
-const GRPC_EMPTY_FRAME = new Uint8Array([0, 0, 0, 0, 0]);
-
-/**
- * Auth headers shared by every xAI billing/userinfo call: bearer token plus
- * the CLI client identity the gateway gates on.
- */
-function xaiHeaders(accessToken: string): Record<string, string> {
-  const version = getGrokVersion();
-  return {
-    authorization: `Bearer ${accessToken}`,
-    "x-xai-token-auth": "xai-grok-cli",
-    "x-grok-client-version": version,
-    "user-agent": buildGrokAuthUserAgent(version),
-  };
-}
-interface XaiBillingPayload {
-  currentPeriod?: unknown;
-  creditUsagePercent?: unknown;
-  productUsage?: unknown;
-  onDemandCap?: unknown;
-  onDemandUsed?: unknown;
-  billingPeriodStart?: unknown;
-  billingPeriodEnd?: unknown;
-  monthlyLimit?: unknown;
-  used?: unknown;
-  subscriptionTier?: unknown;
-  user?: unknown;
-}
-
-function parsePayload(value: string): XaiBillingPayload {
-  const payload: unknown = JSON.parse(value);
-  // Live billing wraps usage in a `config` envelope (free-tier shape);
-  // paid shapes may carry the fields top-level — read the envelope first.
-  const parsed = record(payload);
-  return ((parsed && record(parsed.config)) ?? parsed ?? {}) as XaiBillingPayload;
-}
-
-function billingNumber(value: unknown): number | null {
-  const nested = record(value);
-  return number(nested?.val ?? value);
-}
-
-function period(raw: unknown): { start: string; end: string } | undefined {
-  const value = record(raw);
-  const type = text(value?.type);
-  if (type !== null && !type.toUpperCase().includes("WEEK")) return undefined;
-  const start = isoDate(value?.start);
-  const end = isoDate(value?.end);
-  return start && end && Date.parse(end) > Date.parse(start) ? { start, end } : undefined;
-}
-
-function buildWeeklyWindows(payload: XaiBillingPayload): ProviderQuotaWindow[] {
-  const current = period(payload.currentPeriod);
-  const creditPercent = billingNumber(payload.creditUsagePercent);
-  if (!current) return [];
-  if (creditPercent === null || creditPercent < 0 || creditPercent > 100) {
-    // Free-tier billing states the period but no usage percent: emit the
-    // window with the reset date and null percents (the dashboard renders
-    // the countdown without inventing a number) instead of empty windows.
-    return [percentWindow("1w", "SuperGrok Weekly Credits", null, current.end, null, null, "independent")];
-  }
-  const windows: ProviderQuotaWindow[] = [
-    percentWindow("1w", "SuperGrok Weekly Credits", creditPercent, current.end, creditPercent, 100, "independent"),
-  ];
-  if (Array.isArray(payload.productUsage)) {
-    for (const entry of payload.productUsage) {
-      const value = record(entry);
-      const product = text(value?.product);
-      const percent = billingNumber(value?.usagePercent);
-      windows.push(percentWindow(`product:${product}:1w`, `${product} (Weekly)`, percent, current.end, percent, 100, "independent"));
-    }
-  }
-  return windows;
-}
-
-function buildMonthlyWindows(payload: XaiBillingPayload): ProviderQuotaWindow[] {
-  const start = isoDate(payload.billingPeriodStart);
-  const end = isoDate(payload.billingPeriodEnd);
-  const limit = billingNumber(payload.monthlyLimit);
-  const used = billingNumber(payload.used);
-  if (!start || !end || limit === null || limit <= 0 || used === null || used < 0) return [];
-  const usedPercent = Math.min(100, (used / limit) * 100);
-  return [percentWindow("1mo", "SuperGrok Monthly Included", usedPercent, end, used, limit, "independent")];
-}
-
-function addOnDemandWindow(windows: ProviderQuotaWindow[], payload: XaiBillingPayload): void {
-  const cap = billingNumber(payload.onDemandCap);
-  const used = billingNumber(payload.onDemandUsed);
-  if (cap === null || cap <= 0 || used === null || used < 0) return;
-  windows.push(percentWindow("on-demand", "On-demand", Math.min(100, (used / cap) * 100), null, used, cap, "independent"));
-}
-
-async function fetchGrpcCredits(
-  accessToken: string,
-  fetcher: FetchLike,
-): Promise<{ percentUsed: number; resetAt: string | null } | null> {
-  try {
-    const response = await fetcher(GRPC_CREDITS_URL, {
-      method: "POST",
-      headers: {
-        ...xaiHeaders(accessToken),
-        "content-type": "application/grpc-web+proto",
-        "x-grpc-web": "1",
-      },
-      body: GRPC_EMPTY_FRAME,
-      signal: AbortSignal.timeout(8_000),
-    });
-    if (!response.ok) return null;
-    const arrayBuffer = await response.arrayBuffer();
-    return decodeGrokCreditsFrame(new Uint8Array(arrayBuffer));
-  } catch {
-    return null;
-  }
-}
-
-async function fetchUser(
-  accessToken: string,
-  fetcher: FetchLike,
-): Promise<Record<string, unknown> | null> {
-  try {
-    const response = await fetcher(USER_URL, {
-      headers: { ...xaiHeaders(accessToken), accept: "application/json" },
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (!response.ok) return null;
-    return record((await response.json()) as unknown);
-  } catch {
-    return null;
-  }
-}
-
-/** Fetches Grok Build subscription billing, including weekly and unified-monthly fallbacks. */
-export async function fetchGrokQuota(
-  credential: string,
-  fetcher: FetchLike,
-): Promise<ProviderQuotaResult> {
-  const accessToken = credential.trim();
-  if (!accessToken) throw new Error("grok quota requires an OAuth access token");
-  const response = await fetcher(BILLING_URL, {
-    headers: { ...xaiHeaders(accessToken), accept: "application/json" },
-    signal: AbortSignal.timeout(15_000),
-  });
-  const raw = await response.text();
-  if (!response.ok) throw new Error(`Grok Build billing request failed (${response.status}): ${raw.slice(0, 500)}`);
-  const payload = parsePayload(raw);
-  const windows = buildWeeklyWindows(payload);
-  if (windows.length === 0 || windows.every((w) => w.usedPercent === null)) {
-    const grpc = await fetchGrpcCredits(accessToken, fetcher);
-    if (grpc) {
-      const idx = windows.findIndex((w) => w.label.includes("Weekly"));
-      const grpcWindow = percentWindow("1w", "SuperGrok Weekly Credits", grpc.percentUsed, grpc.resetAt, grpc.percentUsed, 100, "independent");
-      if (idx >= 0) windows[idx] = grpcWindow;
-      else windows.unshift(grpcWindow);
-    }
-  }
-  if (windows.length === 0) windows.push(...buildMonthlyWindows(payload));
-  addOnDemandWindow(windows, payload);
-  const user = await fetchUser(accessToken, fetcher);
-  const userRecord = record(user?.user);
-  const plan =
-    text(user?.subscriptionTier) ??
-    text(payload.subscriptionTier) ??
-    text(userRecord?.subscriptionTier) ??
-    "SuperGrok";
-  return { source: "grok", plan, windows, error: null };
-}
-
-export { BILLING_SOURCE as GROK_BILLING_SOURCE };
+import type { FetchLike, ProviderQuotaResult, ProviderQuotaWindow } from "../../quota/quota-contracts";
+import { isoDate, number, percentWindow, record, text } from "../../quota/quota-contracts";
+import { buildGrokAuthUserAgent, getGrokVersion } from "../../operations/client-versions";
+import { decodeGrokCreditsFrame } from "./grok-quota-frame";
+import {
+  grokAuthoritativeWindow,
+  grokHeaderRequestsWindow,
+  grokHeaderWindow,
+  GROK_FREE_USAGE_EXHAUSTED,
+  parseGrokFreeUsageVerdict,
+  readGrokRateLimitHeaders,
+} from "./grok-ratelimit";
+import type { GrokRateLimitProbe } from "./grok-ratelimit";
+import { storedGrokRateLimit } from "./grok-ratelimit-store";
+import type { QuotaCollectionContext } from "../../quota/quota-support";
+
+const BILLING_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+const BILLING_SOURCE = "cli-chat-proxy.grok.com/v1/billing";
+const USER_URL = "https://cli-chat-proxy.grok.com/v1/user?include=subscription";
+const GRPC_CREDITS_URL = "https://grok.com/grok_api_v2.GrokBuildBilling/GetGrokCreditsConfig";
+const GRPC_EMPTY_FRAME = new Uint8Array([0, 0, 0, 0, 0]);
+
+/**
+ * The cheapest request that still returns the rate-limit headers.
+ *
+ * There is no dedicated quota endpoint — `grok.com/rest/*` does not expose one
+ * and `/v1/models` carries no rate-limit headers — so reading the bucket costs
+ * one real request. At ~360-480 tokens against a 1M allowance that is a few
+ * thousand readings per account, which is affordable; a larger cap would not
+ * be.
+ */
+const PROBE_URL = "https://cli-chat-proxy.grok.com/v1/responses";
+const PROBE_BODY = {
+  model: "grok-4.6",
+  stream: false,
+  max_output_tokens: 1,
+  input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] }],
+};
+
+/**
+ * Auth headers shared by every xAI billing/userinfo call: bearer token plus
+ * the CLI client identity the gateway gates on.
+ */
+function xaiHeaders(accessToken: string): Record<string, string> {
+  const version = getGrokVersion();
+  return {
+    authorization: `Bearer ${accessToken}`,
+    "x-xai-token-auth": "xai-grok-cli",
+    "x-grok-client-version": version,
+    "user-agent": buildGrokAuthUserAgent(version),
+  };
+}
+interface XaiBillingPayload {
+  currentPeriod?: unknown;
+  creditUsagePercent?: unknown;
+  productUsage?: unknown;
+  onDemandCap?: unknown;
+  onDemandUsed?: unknown;
+  billingPeriodStart?: unknown;
+  billingPeriodEnd?: unknown;
+  monthlyLimit?: unknown;
+  used?: unknown;
+  subscriptionTier?: unknown;
+  user?: unknown;
+}
+
+function parsePayload(value: string): XaiBillingPayload {
+  const payload: unknown = JSON.parse(value);
+  // Live billing wraps usage in a `config` envelope (free-tier shape);
+  // paid shapes may carry the fields top-level — read the envelope first.
+  const parsed = record(payload);
+  return ((parsed && record(parsed.config)) ?? parsed ?? {}) as XaiBillingPayload;
+}
+
+function billingNumber(value: unknown): number | null {
+  const nested = record(value);
+  return number(nested?.val ?? value);
+}
+
+function period(raw: unknown): { start: string; end: string } | undefined {
+  const value = record(raw);
+  const type = text(value?.type);
+  if (type !== null && !type.toUpperCase().includes("WEEK")) return undefined;
+  const start = isoDate(value?.start);
+  const end = isoDate(value?.end);
+  return start && end && Date.parse(end) > Date.parse(start) ? { start, end } : undefined;
+}
+
+function buildWeeklyWindows(payload: XaiBillingPayload): ProviderQuotaWindow[] {
+  const current = period(payload.currentPeriod);
+  const creditPercent = billingNumber(payload.creditUsagePercent);
+  if (!current) return [];
+  if (creditPercent === null || creditPercent < 0 || creditPercent > 100) {
+    // Free-tier billing states the period but no usage percent: emit the
+    // window with the reset date and null percents (the dashboard renders
+    // the countdown without inventing a number) instead of empty windows.
+    return [percentWindow("1w", "SuperGrok Weekly Credits", null, current.end, null, null, "independent")];
+  }
+  const windows: ProviderQuotaWindow[] = [
+    percentWindow("1w", "SuperGrok Weekly Credits", creditPercent, current.end, creditPercent, 100, "independent"),
+  ];
+  if (Array.isArray(payload.productUsage)) {
+    for (const entry of payload.productUsage) {
+      const value = record(entry);
+      const product = text(value?.product);
+      const percent = billingNumber(value?.usagePercent);
+      windows.push(percentWindow(`product:${product}:1w`, `${product} (Weekly)`, percent, current.end, percent, 100, "independent"));
+    }
+  }
+  return windows;
+}
+
+function buildMonthlyWindows(payload: XaiBillingPayload): ProviderQuotaWindow[] {
+  const start = isoDate(payload.billingPeriodStart);
+  const end = isoDate(payload.billingPeriodEnd);
+  const limit = billingNumber(payload.monthlyLimit);
+  const used = billingNumber(payload.used);
+  if (!start || !end || limit === null || limit <= 0 || used === null || used < 0) return [];
+  const usedPercent = Math.min(100, (used / limit) * 100);
+  return [percentWindow("1mo", "SuperGrok Monthly Included", usedPercent, end, used, limit, "independent")];
+}
+
+function addOnDemandWindow(windows: ProviderQuotaWindow[], payload: XaiBillingPayload): void {
+  const cap = billingNumber(payload.onDemandCap);
+  const used = billingNumber(payload.onDemandUsed);
+  if (cap === null || cap <= 0 || used === null || used < 0) return;
+  windows.push(percentWindow("on-demand", "On-demand", Math.min(100, (used / cap) * 100), null, used, cap, "independent"));
+}
+
+async function fetchGrpcCredits(
+  accessToken: string,
+  fetcher: FetchLike,
+): Promise<{ percentUsed: number; resetAt: string | null } | null> {
+  try {
+    const response = await fetcher(GRPC_CREDITS_URL, {
+      method: "POST",
+      headers: {
+        ...xaiHeaders(accessToken),
+        "content-type": "application/grpc-web+proto",
+        "x-grpc-web": "1",
+      },
+      body: GRPC_EMPTY_FRAME,
+      signal: AbortSignal.timeout(8_000),
+    });
+    if (!response.ok) return null;
+    const arrayBuffer = await response.arrayBuffer();
+    return decodeGrokCreditsFrame(new Uint8Array(arrayBuffer));
+  } catch {
+    return null;
+  }
+}
+
+async function fetchUser(
+  accessToken: string,
+  fetcher: FetchLike,
+): Promise<Record<string, unknown> | null> {
+  try {
+    const response = await fetcher(USER_URL, {
+      headers: { ...xaiHeaders(accessToken), accept: "application/json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return null;
+    return record((await response.json()) as unknown);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One cheap request, read for its rate-limit headers — and, when the account is
+ * being refused, for the authoritative allowance in the 429 body.
+ *
+ * A refusal is not a failure of the probe: it is the only moment upstream
+ * states the real free allowance, so the body is parsed before anything is
+ * discarded. A transport failure is the opposite — it says nothing about the
+ * account, so it yields no reading rather than a zero.
+ */
+async function probeRateLimit(
+  accessToken: string,
+  fetcher: FetchLike,
+): Promise<GrokRateLimitProbe> {
+  try {
+    const response = await fetcher(PROBE_URL, {
+      method: "POST",
+      headers: { ...xaiHeaders(accessToken), "content-type": "application/json" },
+      body: JSON.stringify(PROBE_BODY),
+      signal: AbortSignal.timeout(30_000),
+    });
+    const reading = readGrokRateLimitHeaders(response.headers);
+    let authoritative = null;
+    let note: string | null = null;
+    if (response.status === 429) {
+      const body = await response.text();
+      const verdict = parseGrokFreeUsageVerdict(parsePayload(body), body);
+      authoritative = verdict ? grokAuthoritativeWindow(verdict) : null;
+      note = GROK_FREE_USAGE_EXHAUSTED;
+    } else if (!response.ok) {
+      // Drain so the connection is reusable, then report nothing: an unrelated
+      // failure must not read as an exhausted allowance.
+      await response.text();
+    }
+    return {
+      header: grokHeaderWindow(reading),
+      requests: grokHeaderRequestsWindow(reading),
+      authoritative,
+      refusal: response.status === 429,
+      note,
+    };
+  } catch {
+    return { header: null, requests: null, authoritative: null, refusal: false, note: null };
+  }
+}
+
+/** Fetches Grok Build subscription billing, including weekly and unified-monthly fallbacks. */
+export async function fetchGrokQuota(
+  credential: string,
+  fetcher: FetchLike,
+  context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  const accessToken = credential.trim();
+  if (!accessToken) throw new Error("grok quota requires an OAuth access token");
+  const response = await fetcher(BILLING_URL, {
+    headers: { ...xaiHeaders(accessToken), accept: "application/json" },
+    signal: AbortSignal.timeout(15_000),
+  });
+  const raw = await response.text();
+  if (!response.ok) throw new Error(`Grok Build billing request failed (${response.status}): ${raw.slice(0, 500)}`);
+  const payload = parsePayload(raw);
+  const windows = buildWeeklyWindows(payload);
+  if (windows.length === 0 || windows.every((w) => w.usedPercent === null)) {
+    const grpc = await fetchGrpcCredits(accessToken, fetcher);
+    if (grpc) {
+      const idx = windows.findIndex((w) => w.label.includes("Weekly"));
+      const grpcWindow = percentWindow("1w", "SuperGrok Weekly Credits", grpc.percentUsed, grpc.resetAt, grpc.percentUsed, 100, "independent");
+      if (idx >= 0) windows[idx] = grpcWindow;
+      else windows.unshift(grpcWindow);
+    }
+  }
+  if (windows.length === 0) windows.push(...buildMonthlyWindows(payload));
+  addOnDemandWindow(windows, payload);
+  const user = await fetchUser(accessToken, fetcher);
+  const userRecord = record(user?.user);
+  const plan =
+    text(user?.subscriptionTier) ??
+    text(payload.subscriptionTier) ??
+    text(userRecord?.subscriptionTier) ??
+    "SuperGrok";
+  // The billing windows are the subscription's own accounting; the two CLI
+  // readings say something different — what this account can still *serve* —
+  // so they are prepended and appended around it rather than merged in.
+  //
+  // Header first: it is what a caller sees every day and it never goes stale
+  // into "unknown". Authoritative last: it only exists once upstream has
+  // refused, and it is the number that decides the account, so it sits beneath
+  // the indicator it overrides.
+  // A reading captured from real traffic costs nothing, so it is preferred
+  // whenever one is fresh. The probe is the fallback for the first read after a
+  // start — never the routine path, or every console refresh would spend a
+  // request.
+  const stored = context?.accountId === undefined
+    ? null
+    : storedGrokRateLimit(context.accountId);
+  const probe = stored ? null : await probeRateLimit(accessToken, fetcher);
+  const ordered: ProviderQuotaWindow[] = [];
+  if (stored) ordered.push(...stored);
+  else if (probe) {
+    if (probe.header) ordered.push(probe.header);
+    if (probe.requests) ordered.push(probe.requests);
+  }
+  ordered.push(...windows);
+  if (probe?.authoritative) ordered.push(probe.authoritative);
+  // Deliberately not `probe.note` in `error`: a refusal here is the probe's own
+  // doing and says the account is out of free usage, which is *account state*,
+  // not a read failure. Reporting it as an error would make a healthy read look
+  // broken; the authoritative window below is what carries the verdict.
+  return { source: "grok", plan, windows: ordered, error: null };
+}
+
+export { BILLING_SOURCE as GROK_BILLING_SOURCE };

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

@@ -0,0 +1,73 @@
+// Where a Grok rate-limit reading lives between dispatch and display.
+//
+// The bucket headers come back on **every** upstream response, so the cheap
+// place to learn them is the traffic the gateway is already sending — not a
+// probe of its own. A dispatch that reads and stores them costs nothing extra;
+// a probe costs a request every time quota is shown.
+//
+// So this store is fed by dispatch (manual test or automatic routing alike) and
+// read by the quota collector. The collector only probes when there is nothing
+// stored, which is the first read after a start and never after that.
+//
+// Keyed by account id: two Grok accounts carry different buckets, and a reading
+// filed against the wrong one is worse than no reading at all.
+
+import type { ProviderQuotaWindow } from "../../quota/quota-contracts";
+import { grokHeaderRequestsWindow, grokHeaderWindow, type GrokRateLimitReading } from "./grok-ratelimit";
+
+/**
+ * How long a stored reading stays useful.
+ *
+ * The header is eventually consistent, so a fresh value is not meaningfully
+ * better than one from a few minutes ago — but a value from last week says
+ * nothing about now. Five minutes is short enough to follow real traffic and
+ * long enough that a burst of console refreshes costs no requests.
+ */
+const SNAPSHOT_TTL_MS = 5 * 60 * 1000;
+
+interface Snapshot {
+  readonly windows: readonly ProviderQuotaWindow[];
+  readonly capturedAt: number;
+}
+
+const snapshots = new Map<string, Snapshot>();
+
+/** Files a reading captured from a real dispatch against one account. */
+export function rememberGrokRateLimit(
+  accountId: string,
+  reading: GrokRateLimitReading,
+  now = Date.now(),
+): void {
+  const windows = [grokHeaderWindow(reading), grokHeaderRequestsWindow(reading)].filter(
+    (value): value is ProviderQuotaWindow => value !== null,
+  );
+  if (windows.length === 0) return;
+  snapshots.set(accountId, { windows, capturedAt: now });
+  if (snapshots.size > 4096) {
+    // Bounded: an unbounded map keyed by account is a leak dressed as a cache.
+    for (const [key, value] of snapshots) {
+      if (now - value.capturedAt > SNAPSHOT_TTL_MS) snapshots.delete(key);
+    }
+  }
+}
+
+/** The stored window for one account, or `null` when none is fresh enough. */
+export function storedGrokRateLimit(accountId: string, now = Date.now()): readonly ProviderQuotaWindow[] | null {
+  const snapshot = snapshots.get(accountId);
+  if (!snapshot) return null;
+  if (now - snapshot.capturedAt > SNAPSHOT_TTL_MS) {
+    snapshots.delete(accountId);
+    return null;
+  }
+  return snapshot.windows;
+}
+
+/** Whether a fresh reading exists, so the collector can skip its probe. */
+export function hasFreshGrokRateLimit(accountId: string, now = Date.now()): boolean {
+  return storedGrokRateLimit(accountId, now) !== null;
+}
+
+/** Test seam. */
+export function clearGrokRateLimitSnapshots(): void {
+  snapshots.clear();
+}