cartethyia 2.7.3 → 2.7.5

package/src/providers/provider-model-definition.ts

@@ -9,6 +9,7 @@
  * back to the prebuilt base catalog; capability does not — see `defineModel`.
  */
 import type { ServiceKind, WireFamily } from "../protocol/canonical-model";
+import type { DialectId } from "../protocol/translation/dialect/types";
 import { modelsDevCatalog } from "./discovery/models-dev-catalog";
 
 /** Billing metadata for one provider model. */
@@ -53,8 +54,22 @@ export interface ModelDefinition {
   readonly reasoning: boolean;
   /** Explicitly supported reasoning effort scale (e.g. `["minimal", "low", "medium", "high", "xhigh"]`). */
   readonly reasoningEfforts?: readonly string[];
+  /**
+   * Optional thinking/effort override for this row. When present, the ladder
+   * resolver prefers these efforts and transport mode over the rule table.
+   * Compile-time only — no DB column (see `thinking-ladder.ts`).
+   */
+  readonly thinking?: {
+    readonly efforts?: readonly string[];
+    readonly mode?: "effort" | "budget" | "anthropic-adaptive" | "google-level";
+  };
   readonly toolCall: boolean;
   readonly cost: ModelCostDefinition;
+  /**
+   * Explicit wire dialect for this row. Absent = resolver fallback (heuristic
+   * + family default) — see `src/protocol/translation/dialect/`.
+   */
+  readonly dialect?: DialectId;
   /**
    * Whether the provider serves this row on a free plan tier.
    *
@@ -85,7 +100,7 @@ export interface ModelDefinition {
    * on a free account while `gpt-5.6-luna` bills `x0.14` and is refused. The
    * only signal is the refusal itself: `11158 "model [X] is not allowed for
    * user type [personal_free_user]"`. See
-   * `.skills/cartethyia-reverse-engineering/references/codebuddy-dispatch-headers.md`.
+   * `documentation/research/codebuddy/2026-10-19-codebuddy-chat-dispatch-headers.md`.
    *
    * Optional, and absence is "tier unknown" rather than "served on free". Read
    * it as `=== true`; a UI that shows a tier must treat undefined as unknown,
@@ -168,6 +183,8 @@ export interface ModelHelperRow {
   readonly output?: readonly ModelDefinition["modalities"]["output"][number][];
   /** Explicitly supported reasoning effort scale. */
   readonly reasoningEfforts?: readonly string[];
+  /** Optional thinking/effort override; see `ModelDefinition.thinking`. */
+  readonly thinking?: ModelDefinition["thinking"];
   readonly toolCall?: boolean;
   /**
    * Marks a row served by a free plan tier. Such rows bill zero per token
@@ -186,6 +203,8 @@ export interface ModelHelperRow {
   readonly freeTier?: boolean;
   /** Whether the provider refuses this row on a free plan. See `ModelDefinition.proOnly`. */
   readonly proOnly?: boolean;
+  /** Explicit wire dialect override for this row. See `ModelDefinition.dialect`. */
+  readonly dialect?: DialectId;
 }
 
 function defaultEndpoint(wireFamily: ModelDefinition["wireFamily"]): string {
@@ -283,10 +302,12 @@ export function defineModel(row: ModelHelperRow): ModelDefinition {
     },
     reasoning: row.reasoning ?? false,
     ...(row.reasoningEfforts !== undefined ? { reasoningEfforts: row.reasoningEfforts } : {}),
+    ...(row.thinking === undefined ? {} : { thinking: row.thinking }),
     toolCall: row.toolCall ?? true,
     cost,
     ...(row.freeTier === undefined ? {} : { freeTier: row.freeTier }),
     ...(row.proOnly === undefined ? {} : { proOnly: row.proOnly }),
+    ...(row.dialect === undefined ? {} : { dialect: row.dialect }),
     ...(limitsEstimated ? { limitsEstimated: true } : {}),
   };
 }

package/src/providers/provider-probe.ts

@@ -12,6 +12,7 @@
  * report a pool as refused for a reason replacing the proxy cannot fix.
  */
 import { encodeWireRequest } from "../protocol/registry";
+import { resolveDialect } from "../protocol/translation/dialect/resolver";
 import type { CanonicalRequest } from "../protocol/canonical-model";
 import type { ProviderDispatchContext } from "./provider-contracts";
 import { providerBaseUrl, providerRateLimitIsIpScoped } from "./provider-metadata";
@@ -60,7 +61,7 @@ function probeRequest(): CanonicalRequest {
     stream: true,
     source_surface: "chat",
     generation_controls: {},
-  } as unknown as CanonicalRequest;
+  };
 }
 
 /**
@@ -98,6 +99,7 @@ export async function buildProviderProbeRequest(
     ...(spec.chatTokenLimitField === undefined
       ? {}
       : { chatTokenLimitField: spec.chatTokenLimitField }),
+    dialectPolicy: resolveDialect(PROBE_MODEL, providerId, "chat"),
   });
   // The adapter's own hooks build the wire body; without running them the
   // probe would omit the agent-tool fingerprint and be refused on a healthy
@@ -116,7 +118,7 @@ export async function buildProviderProbeRequest(
   );
   const headers = (await spec.buildExtraHeaders?.(probeContext(providerId), source)) ?? {};
   return {
-    url: `${providerBaseUrl(providerId).replace(/\/+$/, "")}/inference/openai/v1/chat/completions`,
+    url: `${providerBaseUrl(providerId)}/inference/openai/v1/chat/completions`,
     headers: { "content-type": "application/json", ...headers },
     body: payload,
   };

package/src/providers/provider-registry.ts

@@ -89,7 +89,7 @@ function assertAdapterIdentity(expected: ProviderId, adapter: ProviderAdapter):
   // error: `invalid_request` would blame the caller and invite a byte-identical
   // retry. `internal_error` (500) says what is true — the gateway is
   // misconfigured and the request never had a chance.
-  throw new GatewayError("internal_error", 500, "Loaded adapter ID does not match registration", {
+  throw new GatewayError("internal_error", 500, "Loaded adapter ID does not match registration (request {requestId}). Even we have bad days — check the registry wiring 🐻", {
     provider_id: expected,
     adapter_id: adapter.provider_id,
   });
@@ -122,12 +122,12 @@ export class ProviderRegistry {
   register(registration: ProviderRegistration): void {
     const providerId = parseProviderId(registration.provider_id);
     if (this.#registrations.has(providerId)) {
-      throw new GatewayError("invalid_request", 409, "Provider is already registered", {
+      throw new GatewayError("invalid_request", 409, "Provider is already registered (request {requestId}). This name's taken — pick another alias ✨", {
         provider_id: providerId,
       });
     }
     if (providerId !== registration.provider_id) {
-      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized", {
+      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized (request {requestId}). Even we have bad days — check the registry wiring 🐻", {
         provider_id: registration.provider_id,
       });
     }
@@ -158,7 +158,7 @@ export class ProviderRegistry {
   upsert(registration: ProviderRegistration): boolean {
     const providerId = parseProviderId(registration.provider_id);
     if (providerId !== registration.provider_id) {
-      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized", {
+      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized (request {requestId}). Even we have bad days — check the registry wiring 🐻", {
         provider_id: registration.provider_id,
       });
     }

package/src/providers/provider-usage.ts

@@ -11,6 +11,7 @@ export interface OpenAiUsage {
   };
 }
 import { modelsDevCatalog } from "./discovery/models-dev-catalog";
+import { resolveCacheMode } from "../config/providers";
 
 /**
  * Extract cost multipliers from catalog model cost JSONB.
@@ -125,6 +126,36 @@ export function repriceUsage(
     : { ...usage, estimated_cost: estimatedCost };
 }
 
+/**
+ * Simplified cache accounting: when the provider reported a cache hit, the
+ * whole prompt counts as cached — request input ber-cache = cache-eligible →
+ * input = cache. The cache-write volume is already inside the all-in input
+ * total on cache-aware shapes, so it stays separate and is not double-counted
+ * as a hit. A reported `0` or an absent report stay a cache miss. In `real`
+ * mode the provider's reported split is kept as-is.
+ *
+ * Exported so the hand-built record producers (Cursor, Kiro) apply the same
+ * rule as `normalizeUsage`.
+ */
+export function applyCacheMode(usage: UsageRecord): UsageRecord {
+  if (resolveCacheMode() !== "simplified") return usage;
+  if (
+    typeof usage.cached_input_tokens === "number" &&
+    usage.cached_input_tokens > 0 &&
+    usage.input_tokens > 0
+  ) {
+    const writes =
+      typeof usage.cache_write_tokens === "number" ? Math.max(0, usage.cache_write_tokens) : 0;
+    const cached = Math.min(usage.input_tokens, Math.max(0, usage.input_tokens - writes));
+    return {
+      ...usage,
+      cached_input_tokens: cached,
+      uncached_input_tokens: 0,
+    };
+  }
+  return usage;
+}
+
 /**
  * Normalize provider-specific usage data into canonical UsageRecord.
  * Handles Anthropic (cache_read_input_tokens, cache_creation_input_tokens, output_tokens_details.thinking_tokens)
@@ -250,6 +281,21 @@ export function normalizeUsage(input: Record<string, unknown>): UsageRecord {
     input_tokens += cache_write_tokens;
   }
 
+  // Simplified cache accounting: a reported hit makes the whole prompt count as
+  // cached — request input ber-cache = cache-eligible → input = cache. The
+  // cache-write volume is already inside the all-in input total on cache-aware
+  // shapes, so it stays separate and is not double-counted as a hit. Applied
+  // before pricing so the estimated cost reads the same simplified split as the
+  // record.
+  if (typeof cached_input_tokens === "number" && cached_input_tokens > 0 && input_tokens > 0) {
+    if (resolveCacheMode() === "simplified") {
+      const writes =
+        typeof cache_write_tokens === "number" ? Math.max(0, cache_write_tokens) : 0;
+      cached_input_tokens = Math.min(input_tokens, Math.max(0, input_tokens - writes));
+      uncached_input_tokens = 0;
+    }
+  }
+
   // Handle reasoning tokens: Anthropic and OpenAI both use output_tokens_details
   let reasoning_tokens: number | "unavailable" = "unavailable";
   const details: NonNullable<UsageRecord["details"]> = {};
@@ -436,28 +482,47 @@ export function usageToMessagesWire(usage: UsageRecord | undefined): Record<stri
  * and event shapes — only the key lookup lives here, so a new upstream key
  * is added once and every reader picks it up.
  */
-export const REASONING_TEXT_KEYS: readonly string[] = ["reasoning_content", "reasoning"];
+export const REASONING_TEXT_KEYS: readonly string[] = [
+  "reasoning_content",
+  "reasoning",
+  "reasoning_summary",
+  "reasoning_summary_text",
+  "reasoning_text",
+];
+
+/**
+ * Extracts readable text from one reasoning value. Accepts a plain string and
+ * the object shapes upstreams use for reasoning deltas: `{text}`,
+ * `{summary}`, `{delta}` (Responses-style), or an array of parts.
+ */
+function reasoningTextValue(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    let text = "";
+    for (const part of value) {
+      const piece = reasoningTextValue(part);
+      if (piece !== undefined) text += piece;
+    }
+    return text.length > 0 ? text : undefined;
+  }
+  if (typeof value !== "object" || value === null) return undefined;
+  const rec = value as Record<string, unknown>;
+  for (const key of ["text", "summary", "delta", "content"]) {
+    const piece = reasoningTextValue(rec[key]);
+    if (piece !== undefined) return piece;
+  }
+  return undefined;
+}
 
 /** First string found under a known reasoning-text key, or undefined. */
 export function readReasoningText(source: Record<string, unknown>): string | undefined {
   for (const key of REASONING_TEXT_KEYS) {
-    const value = source[key];
-    if (typeof value === "string") return value;
+    const text = reasoningTextValue(source[key]);
+    if (text !== undefined) return text;
   }
   // Qwen/MiniMax-family `reasoning_details[]` parts carrying text fragments.
-  const details = source["reasoning_details"];
-  if (Array.isArray(details)) {
-    const text = details
-      .map((part) =>
-        typeof part === "string"
-          ? part
-          : typeof (part as Record<string, unknown>)?.["text"] === "string"
-            ? ((part as Record<string, unknown>)["text"] as string)
-            : "",
-      )
-      .join("");
-    if (text.length > 0) return text;
-  }
+  const details = reasoningTextValue(source["reasoning_details"]);
+  if (details !== undefined) return details;
   return undefined;
 }
 

package/src/providers/quota/cache.ts

@@ -318,6 +318,35 @@ export async function invalidateQuotaCache(
   }
 }
 
+/**
+ * Drops many accounts from one lens in a single pass.
+ *
+ * The batch-delete route clears several accounts' quota caches at once. The
+ * in-process tier is swept once (one `keys()` pass), and Redis is cleared with
+ * one pipeline, so the cost does not scale with per-account round trips.
+ */
+export async function invalidateQuotaCaches(
+  lens: string,
+  accountIds: readonly string[],
+  redis: RedisClient | undefined,
+): Promise<void> {
+  if (accountIds.length === 0) return;
+  const keys = accountIds.map((accountId) => quotaKey(lens, accountId));
+  const keySet = new Set(keys);
+  for (const key of inMemoryQuotaCache.keys()) {
+    if (keySet.has(key)) inMemoryQuotaCache.delete(key);
+  }
+  if (redis === undefined) return;
+  try {
+    const pipeline = redis.pipeline();
+    for (const key of keys) pipeline.del(key);
+    await pipeline.exec().catch(() => undefined);
+  } catch (error) {
+    metrics.quota_cache_invalidate_failed.inc(1);
+    log.warn("quota cache batch invalidate failed", { lens, error: String(error) });
+  }
+}
+
 /**
  * Drops one account from EVERY cache lens. Global accounts are shared, but a
  * release-N writer may have written the same account under a per-tenant lens,

package/src/providers/quota/quota-contracts.ts

@@ -18,6 +18,10 @@ export interface ProviderQuotaWindow {
   readonly remaining?: number | null;
   /** False means the timestamp is a hard expiry rather than a recurring reset. */
   readonly recurring?: boolean;
+  /** Exact routing model IDs this grant serves; absent means account-wide. */
+  readonly modelIds?: readonly string[];
+  /** Activation instant: future grants remain visible but cannot fund requests. */
+  readonly startsAt?: string | null;
 }
 
 export interface ProviderQuotaResult {
@@ -58,20 +62,27 @@ export function totalRemainingCredit(
  * independent quota windows, or `null` when neither is reported.
  *
  * Pooled credits are summed before converting to percent, so one exhausted
- * bonus pack cannot hide balance in another. Independent windows keep their
- * own remaining percent and the lowest one gates the account.
+ * bonus pack cannot hide balance in another. A pooled window without a ceiling
+ * (Command Code credits) contributes its absolute remaining to the credit sum
+ * but cannot produce a percent, so it is not counted in the percent ratio.
+ * Independent windows keep their own remaining percent and the lowest one
+ * gates the account.
  */
 export function totalRemainingPercent(
   windows: readonly ProviderQuotaWindow[],
 ): number | null {
   let creditLimit = 0;
   let creditRemaining = 0;
+  let hasPooledLimit = false;
   let independentPercent: number | null = null;
   for (const window of windows) {
     if (window.accounting === "pooled") {
       const balance = creditWindowBalance(window);
       if (balance !== null) {
-        creditLimit += balance.limit;
+        if (balance.limit !== null) {
+          creditLimit += balance.limit;
+          hasPooledLimit = true;
+        }
         creditRemaining += balance.remaining;
       }
       continue;
@@ -85,8 +96,13 @@ export function totalRemainingPercent(
     independentPercent =
       independentPercent === null ? clamped : Math.min(independentPercent, clamped);
   }
-  const creditPercent =
-    creditLimit > 0 ? Math.min(100, Math.max(0, (creditRemaining / creditLimit) * 100)) : null;
+  // A pooled window with a reported ceiling (including a 0 ceiling — a spent
+  // balance) always defines a percent: 0 ceiling means 0% remaining.
+  const creditPercent = hasPooledLimit
+    ? creditLimit > 0
+      ? Math.min(100, Math.max(0, (creditRemaining / creditLimit) * 100))
+      : 0
+    : null;
   if (creditPercent === null) return independentPercent;
   if (independentPercent === null) return creditPercent;
   return Math.min(creditPercent, independentPercent);
@@ -94,20 +110,22 @@ export function totalRemainingPercent(
 
 function creditWindowBalance(
   window: ProviderQuotaWindow,
-): { readonly limit: number; readonly remaining: number } | null {
+): { readonly limit: number | null; readonly remaining: number } | null {
+  // A ceiling of 0 is a spent balance, not an absence of data; only a window
+  // with no remaining figure at all is skipped. `limit` may be null (Command
+  // Code reports credits without a ceiling) — the remaining total still counts.
   const limit =
-    typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit > 0
+    typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit >= 0
       ? window.limit
       : null;
-  if (limit === null) return null;
   let remaining: number | null = null;
   if (typeof window.remaining === "number" && Number.isFinite(window.remaining)) {
     remaining = window.remaining;
-  } else if (typeof window.used === "number" && Number.isFinite(window.used)) {
+  } else if (typeof window.used === "number" && Number.isFinite(window.used) && limit !== null) {
     remaining = limit - window.used;
   }
   if (remaining === null) return null;
-  return { limit, remaining: Math.min(limit, Math.max(0, remaining)) };
+  return { limit, remaining: Math.max(0, remaining) };
 }
 
 const TIMEOUT_MS = 15_000;

package/src/providers/quota/refresh.ts

@@ -15,8 +15,21 @@ import { fetchProviderQuota } from "./quota-support";
 import { type FetchLike, type ProviderQuotaResult } from "./quota-contracts";
 import type { ProviderId } from "../provider-contracts";
 import type { ProviderRegistry } from "../provider-registry";
-import { GLOBAL_QUOTA_LENS, setCachedQuota } from "./cache";
-import { record } from "../authentication/oauth-flow-store";
+import { quotaLens, setCachedQuota } from "./cache";
+import { persistQuotaSnapshot } from "./snapshot";
+import { asJsonbRecord } from "../../shared/coerce";
+import { KIRO_DEFAULT_LABELS } from "../integrations/kiro/kiro-oauth";
+
+/**
+ * The stock Kiro fallback labels as a SQL literal list. Built once from the
+ * canonical set (`KIRO_DEFAULT_LABELS`) and escaped for the single-quote SQL
+ * literal; the values are compile-time constants, so this fragment is static.
+ */
+const KIRO_DEFAULT_LABEL_IN = sql.raw(
+  [...KIRO_DEFAULT_LABELS]
+    .map((label) => `'${label.replace(/'/g, "''")}'`)
+    .join(", "),
+);
 
 /** Why an account quota refresh failed; `null` means the fetch succeeded. */
 export type QuotaRefreshFailureCode = "missing_credential" | "quota_fetch_failed";
@@ -52,7 +65,7 @@ export interface QuotaRefreshDeps {
    */
   readonly resolveCredential: (providerId: ProviderId, accountId: string) => Promise<string>;
   /** Marks a stored api_key credential with the upstream-distinguishable envelope. */
-  readonly markApiKeyCredential?: (providerId: string, credential: string) => string;
+  readonly markApiKeyCredential?: (providerId: string, credential: string) => Promise<string>;
   /** Invalidates the route snapshot when a stamped figure may exclude an account. */
   readonly snapshotInvalidator?: { invalidate(): unknown } | undefined;
 }
@@ -219,7 +232,7 @@ export interface QuotaRefreshTarget {
 
 /** Cache lens an account's quota belongs under. */
 export function targetLens(target: QuotaRefreshTarget): string {
-  return target.tenantId ?? GLOBAL_QUOTA_LENS;
+  return quotaLens(target.tenantId);
 }
 
 const TARGET_COLUMNS = {
@@ -352,10 +365,10 @@ async function runQuotaRefresh(
     // collector to the key-only probe, and OAuth credentials carry no key.
     const marked =
       target.credentialKind === "api_key"
-        ? (deps.markApiKeyCredential?.(target.providerId, credential) ?? credential)
+        ? (await deps.markApiKeyCredential?.(target.providerId, credential) ?? credential)
         : credential;
     try {
-      const authState = record(target.authState);
+      const authState = asJsonbRecord(target.authState);
       quota = await fetchProviderQuota(deps.providerRegistry, target.providerId, marked, fetcher, {
         // Carried so a collector can reuse a reading captured from real
         // traffic rather than spending a request to rediscover it.
@@ -399,6 +412,15 @@ async function runQuotaRefresh(
       log.warn(`[quota] failed to record plan for account=${target.accountId}`, error as Error);
     }
   }
+  // Persist the whole successful read, not just the plan. The row survives a
+  // restart that empties the in-process cache, so a cold console open renders
+  // the last known balance instead of nothing (and the sweep refreshes it). A
+  // failed fetch leaves the previous snapshot in place — same reasoning as the
+  // plan column: failure is evidence about the network/credential, not that
+  // the account's balance changed.
+  if (quota.error === null) {
+    await persistQuotaSnapshot(deps.db, target.accountId, quota);
+  }
   // A quota surface that names the account adopts the identity — but only over
   // a default label. An operator's custom rename is never overwritten, and the
   // CASE keeps the read and the write in one statement so a concurrent rename
@@ -416,6 +438,7 @@ async function runQuotaRefresh(
           label: sql`CASE
             WHEN lower(trim(${providerAccounts.label})) = lower(trim(${providerAccounts.providerId})) THEN ${quota.accountLabel}
             WHEN ${providerAccounts.label} LIKE '%|%' THEN ${quota.accountLabel}
+            WHEN ${providerAccounts.label} IN (${KIRO_DEFAULT_LABEL_IN}) THEN ${quota.accountLabel}
             ELSE ${providerAccounts.label}
           END`,
         })

package/src/providers/quota/snapshot.ts

@@ -0,0 +1,94 @@
+/**
+ * Persisted quota snapshots.
+ *
+ * The in-process quota cache is a short TTL and empty on a cold start, so
+ * right after a restart the console would render no balance for every account
+ * until the sweep re-reads them — while Buddy's usage snapshots survived via a
+ * table. This is the generic counterpart: every provider's last successful
+ * quota read is persisted on the account row, and the console falls back to it
+ * when the cache is cold. A failed fetch leaves the previous snapshot in place,
+ * mirroring `quota_plan`.
+ */
+import { eq, inArray } from "drizzle-orm";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { providerAccounts, type ProviderQuotaResultSnapshot } from "../../persistence/schema";
+import type { ProviderQuotaResult } from "./quota-contracts";
+
+/**
+ * Parses the `quota_snapshot` column. Postgres' jsonb arrives as an object;
+ * SQLite's text-backed column arrives as a JSON string — accept both.
+ */
+function parseSnapshot(value: unknown): ProviderQuotaResultSnapshot | null {
+  if (value === null || value === undefined) return null;
+  let root: unknown = value;
+  if (typeof value === "string") {
+    try {
+      root = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (typeof root !== "object" || root === null || Array.isArray(root)) return null;
+  const rec = root as Record<string, unknown>;
+  const { quota, fetchedAt } = rec;
+  if (typeof quota !== "object" || quota === null || typeof fetchedAt !== "string") return null;
+  return { quota: quota as ProviderQuotaResult, fetchedAt };
+}
+
+/** Stores one successful quota read on the account row. Never throws. */
+export async function persistQuotaSnapshot(
+  db: CartethyiaDatabase,
+  accountId: string,
+  quota: ProviderQuotaResult,
+  fetchedAt: Date = new Date(),
+): Promise<void> {
+  try {
+    await db
+      .update(providerAccounts)
+      .set({ quotaSnapshot: { quota, fetchedAt: fetchedAt.toISOString() } })
+      .where(eq(providerAccounts.id, accountId));
+  } catch {
+    // A snapshot that cannot be stored is a stale display, not an error the
+    // caller must handle.
+  }
+}
+
+/** Reads one account's last successful quota snapshot, if any. */
+export async function readQuotaSnapshot(
+  db: CartethyiaDatabase,
+  accountId: string,
+): Promise<ProviderQuotaResultSnapshot | null> {
+  try {
+    const rows = await db
+      .select({ quotaSnapshot: providerAccounts.quotaSnapshot })
+      .from(providerAccounts)
+      .where(eq(providerAccounts.id, accountId))
+      .limit(1);
+    return parseSnapshot(rows[0]?.quotaSnapshot);
+  } catch {
+    return null;
+  }
+}
+
+/** Batch read for one page render: one query for every account. */
+export async function readQuotaSnapshots(
+  db: CartethyiaDatabase,
+  accountIds: readonly string[],
+): Promise<Map<string, ProviderQuotaResultSnapshot>> {
+  const found = new Map<string, ProviderQuotaResultSnapshot>();
+  if (accountIds.length === 0) return found;
+  try {
+    const rows = await db
+      .select({ id: providerAccounts.id, quotaSnapshot: providerAccounts.quotaSnapshot })
+      .from(providerAccounts)
+      .where(inArray(providerAccounts.id, [...accountIds]));
+    for (const row of rows) {
+      const snapshot = parseSnapshot(row.quotaSnapshot);
+      if (snapshot) found.set(row.id, snapshot);
+    }
+  } catch {
+    // A read failure yields a partial map; callers already treat a missing
+    // entry as "no snapshot".
+  }
+  return found;
+}

package/src/providers/search/search-provider.ts

@@ -1,5 +1,3 @@
-import { asRecord } from "../../shared/coerce";
-
 /**
  * Declarative web-search provider adapters.
  *
@@ -53,7 +51,7 @@ function stringField(record: Record<string, unknown> | undefined, key: string):
 export function searchParamsFromBody(body: Record<string, unknown>): SearchParams {
   const query = typeof body.query === "string" ? body.query.trim() : "";
   if (query.length === 0)
-    throw new GatewayError("invalid_request", 400, "search query is required");
+    throw new GatewayError("invalid_request", 400, "search query is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   const rawMax = body.max_results;
   const maxResults =
     typeof rawMax === "number" && Number.isFinite(rawMax)
@@ -90,7 +88,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
       throw new GatewayError(
         "capability_unsupported",
         400,
-        `${spec.provider_id} serves web search, not a chat wire`,
+        `${spec.provider_id} serves web search, not a chat wire (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
       );
     },
     async websearch(
@@ -113,7 +111,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
         throw new GatewayError(
           "platform_unavailable",
           502,
-          `${spec.provider_id} search unreachable: ${error instanceof Error ? error.message : String(error)}`,
+          `${spec.provider_id} search unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
         );
       }
       if (!res.ok) {
@@ -121,7 +119,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
         throw new GatewayError(
           res.status >= 500 ? "platform_unavailable" : "invalid_request",
           res.status,
-          `${spec.provider_id} search error: ${detail.slice(0, 240)}`,
+          `${spec.provider_id} search error (request {requestId}): ${detail.slice(0, 240)}. The upstream came back empty-handed — retry 🌙`,
         );
       }
       const raw = await res.text();
@@ -135,7 +133,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
         throw new GatewayError(
           "platform_unavailable",
           502,
-          `${spec.provider_id} search returned an unparseable body`,
+          `${spec.provider_id} search returned an unparseable body (request {requestId}). The upstream came back empty-handed — retry 🌙`,
         );
       }
       const results = spec.normalize(data);
@@ -161,4 +159,4 @@ function jsonFromEventStream(raw: string): unknown {
 
 }
 
-export { asRecord, stringField };
+export { stringField };

package/src/providers/search/search-providers.ts

@@ -9,7 +9,8 @@
  * normalization, which is what makes a provider's wire local to one spec.
  */
 import type { SearchParams, SearchProviderSpec, SearchRequestInit } from "./search-provider";
-import { asRecord, stringField } from "./search-provider";
+import { stringField } from "./search-provider";
+import { asRecord } from "../../shared/coerce";
 
 function domainFilterParams(filter: readonly string[] | undefined): {
   includes: string[];