cartethyia 2.7.3 → 2.7.4

package/src/persistence/stores/api-key-store.ts

@@ -1,6 +1,6 @@
 // Persisted API-key store: the console API-key domain and gateway authentication both consume this boundary.
 
-import { and, asc, count, desc, eq, inArray, isNotNull, isNull, sql } from "drizzle-orm";
+import { and, asc, count, desc, eq, inArray, isNotNull, isNull, lte, or, sql, type SQL } from "drizzle-orm";
 import { nextSortIndex, reorderSortIndex, type SortOrderDb } from "../sort-order";
 import { getDbHandle } from "../boot";
 import type { CartethyiaDatabase } from "../db-handle";
@@ -34,6 +34,18 @@ export interface SharedChildrenPage {
   readonly consumed: number;
 }
 
+/**
+ * SQL predicate: the key is not under an active ban. A ban is active while
+ * `banned_at` is set AND either `banned_until` is null (permanent) or still in
+ * the future — so a timed ban lapses on its own without a sweep.
+ */
+function notBannedSql(): SQL {
+  return or(
+    isNull(apiKeys.bannedAt),
+    and(isNotNull(apiKeys.bannedUntil), lte(apiKeys.bannedUntil, new Date())),
+  ) as SQL;
+}
+
 /** Persisted API key. Only its one-way hash authenticates; plaintext is never stored. */
 export interface ApiKeyRecord {
   readonly id: string;
@@ -75,6 +87,11 @@ export interface ApiKeyRecord {
   readonly clientRouterDenylist?: readonly string[];
   readonly createdAt: Date;
   readonly revokedAt?: Date;
+  /** Ban state; see the schema column for the contract. */
+  readonly bannedAt?: Date;
+  readonly banReason?: string;
+  /** When the ban lifts on its own; null means permanent. */
+  readonly bannedUntil?: Date;
   readonly tokensConsumed: number;
 }
 
@@ -128,6 +145,9 @@ export interface ApiKeyPatch
     | "lifetimeTokenBudget"
     | "maxConcurrentRequests"
     | "maxChildren"
+    | "bannedAt"
+    | "banReason"
+    | "bannedUntil"
   > {
   readonly keyHash?: string | null;
   readonly keyEncrypted?: Buffer | null;
@@ -147,6 +167,11 @@ export interface ApiKeyPatch
   readonly lifetimeTokenBudget?: number | null;
   readonly maxConcurrentRequests?: number | null;
   readonly maxChildren?: number | null;
+  /** Ban state; a ban also disables the key, unban clears both columns entirely. */
+  readonly bannedAt?: Date | null;
+  readonly banReason?: string | null;
+  /** When the ban lifts on its own; null (explicit) means permanent. */
+  readonly bannedUntil?: Date | null;
 }
 
 interface PopupFields {
@@ -247,6 +272,20 @@ export interface ApiKeyStore {
   reorder(tenantId: string, keyIds: readonly string[]): Promise<void>;
   update(tenantId: string, keyId: string, patch: ApiKeyPatch): Promise<ApiKeyRecord | undefined>;
   revoke(tenantId: string, keyId: string, revokedAt: Date): Promise<boolean>;
+  /**
+   * Bans a key: records the operator's reason and (optionally) an expiry.
+   * `bannedUntil` null means permanent; absent defaults the the caller's
+   * choice. Returns false when the key is already revoked (a revoke is
+   * terminal).
+   */
+  ban(
+    tenantId: string,
+    keyId: string,
+    reason: string,
+    bannedUntil?: Date | null,
+  ): Promise<boolean>;
+  /** Unbans a key: clears the ban columns entirely — no metadata remains. */
+  unban(tenantId: string, keyId: string): Promise<boolean>;
   remove(tenantId: string, keyId: string): Promise<boolean>;
   findActiveByHash?(hash: string): Promise<typeof apiKeys.$inferSelect | undefined>;
   findActiveById?(keyId: string): Promise<typeof apiKeys.$inferSelect | undefined>;
@@ -314,6 +353,9 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
         : { clientRouterDenylist: row.clientRouterDenylist as string[] }),
       createdAt: row.createdAt,
       ...(row.revokedAt ? { revokedAt: row.revokedAt } : {}),
+      ...(row.bannedAt ? { bannedAt: row.bannedAt } : {}),
+      ...(row.banReason ? { banReason: row.banReason } : {}),
+      ...(row.bannedUntil ? { bannedUntil: row.bannedUntil } : {}),
       tokensConsumed: row.lifetimeTokensConsumed,
     };
   }
@@ -586,6 +628,8 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
           // silently dropped — a grant like `routing:cli_mapping` can be
           // turned on and never stick.
           ...(patch.scopes === undefined ? {} : { scopes: patch.scopes }),
+          ...(patch.bannedAt !== undefined ? { bannedAt: patch.bannedAt } : {}),
+          ...(patch.banReason !== undefined ? { banReason: patch.banReason } : {}),
         })
         .where(and(eq(apiKeys.tenantId, tenantId), eq(apiKeys.id, keyId)))
         .returning();
@@ -622,6 +666,55 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       return true;
     });
   }
+
+  async ban(
+    tenantId: string,
+    keyId: string,
+    reason: string,
+    bannedUntil?: Date | null,
+  ): Promise<boolean> {
+    return this.db.transaction(async (tx) => {
+      const rows = await tx
+        .update(apiKeys)
+        .set({
+          bannedAt: new Date(),
+          banReason: reason,
+          // `banned_until` null = permanent. The key stays `enabled` as-is:
+          // the auth path refuses a banned key while `banned_at` is set and
+          // `banned_until` is null or future, so a timed ban lapses on its own
+          // without a sweep flipping `enabled` back.
+          ...(bannedUntil === undefined ? {} : { bannedUntil }),
+        })
+        .where(
+          and(
+            eq(apiKeys.tenantId, tenantId),
+            eq(apiKeys.id, keyId),
+            isNull(apiKeys.revokedAt),
+          ),
+        )
+        .returning({ id: apiKeys.id });
+      return rows.length > 0;
+    });
+  }
+
+  async unban(tenantId: string, keyId: string): Promise<boolean> {
+    return this.db.transaction(async (tx) => {
+      // Unban clears all three ban columns entirely — no tombstone, no leftover
+      // reason, no stale expiry. The key returns to its prior enabled state.
+      const rows = await tx
+        .update(apiKeys)
+        .set({ bannedAt: null, banReason: null, bannedUntil: null, enabled: true })
+        .where(
+          and(
+            eq(apiKeys.tenantId, tenantId),
+            eq(apiKeys.id, keyId),
+            isNull(apiKeys.revokedAt),
+          ),
+        )
+        .returning({ id: apiKeys.id });
+      return rows.length > 0;
+    });
+  }
   async remove(tenantId: string, keyId: string): Promise<boolean> {
     return this.db.transaction(async (tx) => {
       const rows = await tx
@@ -647,7 +740,7 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
     const rows = await this.db
       .select()
       .from(apiKeys)
-      .where(and(eq(apiKeys.keyHash, hash), eq(apiKeys.enabled, true), isNull(apiKeys.revokedAt)))
+      .where(and(eq(apiKeys.keyHash, hash), eq(apiKeys.enabled, true), isNull(apiKeys.revokedAt), notBannedSql()))
       .limit(1);
     return rows[0];
   }
@@ -658,7 +751,7 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
     const rows = await this.db
       .select()
       .from(apiKeys)
-      .where(and(eq(apiKeys.id, keyId), eq(apiKeys.enabled, true), isNull(apiKeys.revokedAt)))
+      .where(and(eq(apiKeys.id, keyId), eq(apiKeys.enabled, true), isNull(apiKeys.revokedAt), notBannedSql()))
       .limit(1);
     return rows[0];
   }
@@ -716,6 +809,9 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       createdAt: date("created_at") ?? new Date(0),
       enabled: flag("enabled"),
       revokedAt: date("revoked_at"),
+      bannedAt: date("banned_at"),
+      banReason: text("ban_reason"),
+      bannedUntil: date("banned_until"),
       keyPrefix: text("key_prefix"),
       keyEncrypted: raw["key_encrypted"] ?? null,
       notesTitle: text("notes_title"),

package/src/persistence/stores/telemetry-store.ts

@@ -55,7 +55,7 @@ function addUsageDelta(
   delta.outputTokens += row.outputTokens ?? 0;
 }
 
-function aggregateUsage(rows: readonly (typeof telemetryEvents.$inferInsert)[]) {
+export function aggregateUsage(rows: readonly (typeof telemetryEvents.$inferInsert)[]) {
   const deltas = new Map<string, UsageTotalDelta>();
   for (const row of rows) {
     addUsageDelta(deltas, row, "account", row.accountId);

package/src/protocol/codecs.ts

@@ -480,7 +480,7 @@ export function assertBoundedJsonDepth(value: unknown): void {
 
 function assertBoundedDepthWalk(value: unknown, depth: number): void {
   if (depth > MAX_JSON_DEPTH)
-    throw new GatewayError("invalid_request", 400, `The request body is nested deeper than this endpoint accepts (${MAX_JSON_DEPTH} levels). Flatten the payload.`);
+    throw new GatewayError("invalid_request", 400, `The request body is nested deeper than this endpoint accepts (${MAX_JSON_DEPTH} levels) (request {requestId}). Flatten the payload. Check the shape of what you sent — then resend 🪞`);
   if (Array.isArray(value)) {
     for (const item of value) assertBoundedDepthWalk(item, depth + 1);
     return;
@@ -1038,7 +1038,7 @@ export function filterProviderCustomHeaders(
   for (const [rawName, rawValue] of Object.entries(input)) {
     const name = rawName.toLowerCase();
     if (!HEADER_TOKEN.test(name)) {
-      throw new GatewayError("invalid_request", 400, `invalid custom header name: ${rawName}`, {
+      throw new GatewayError("invalid_request", 400, `invalid custom header name: ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`, {
         header: rawName,
       });
     }
@@ -1047,7 +1047,7 @@ export function filterProviderCustomHeaders(
       extraReserved.has(name) ||
       name.startsWith("x-forwarded-")
     ) {
-      throw new GatewayError("invalid_request", 400, `custom header is protected: ${rawName}`, {
+      throw new GatewayError("invalid_request", 400, `custom header is protected: ${rawName} (request {requestId}). Not allowed by policy — no hard feelings 🫂`, {
         header: rawName,
       });
     }
@@ -1055,7 +1055,7 @@ export function filterProviderCustomHeaders(
       throw new GatewayError(
         "invalid_request",
         400,
-        `custom header value must be a string: ${rawName}`,
+        `custom header value must be a string: ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         { header: rawName },
       );
     }
@@ -1063,7 +1063,7 @@ export function filterProviderCustomHeaders(
       throw new GatewayError(
         "invalid_request",
         400,
-        `custom header value exceeds 4KiB: ${rawName}`,
+        `custom header value exceeds 4KiB: ${rawName} (request {requestId}). We love long reads, but not that long 📚`,
         { header: rawName },
       );
     }
@@ -1071,7 +1071,7 @@ export function filterProviderCustomHeaders(
       throw new GatewayError(
         "invalid_request",
         400,
-        `custom header value contains control characters: ${rawName}`,
+        `custom header value contains control characters: ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         { header: rawName },
       );
     }

package/src/protocol/gateway-error.ts

@@ -6,12 +6,14 @@ export type GatewayErrorCode =
   | "capability_unsupported"
   | "ambiguous_model"
   | "model_not_found"
+  | "model_not_allowed"
   | "upstream_not_found"
   | "context_length_exceeded"
   | "request_too_large"
   | "accounts_unavailable"
   | "accounts_rate_limited"
   | "capacity_exhausted"
+  | "upstream_overloaded"
   | "provider_capacity_exhausted"
   | "upstream_queued"
   | "proxy_pool_capacity_exceeded"
@@ -22,8 +24,10 @@ export type GatewayErrorCode =
   | "proxy_pool_unhealthy"
   | "invalid_pool_limits"
   | "admission_unavailable"
+  | "route_unavailable"
   | "slug_reserved"
   | "quota_exceeded"
+  | "rate_limited"
   | "authentication_failed"
   | "policy_rejected"
   | "invalid_request"
@@ -52,8 +56,7 @@ export type GatewayErrorCode =
   | "proxy_unreachable"
   | "tool_call_loop_detected"
   | "client_router_denied"
-  | "shutting_down"
-  | "restart_for_update";
+  | "shutting_down";
 
 /** Identifies which boundary produced a safe public error. */
 export type GatewayErrorOrigin = "cartethyia" | "upstream" | "network";
@@ -226,7 +229,7 @@ export function capabilityUnsupported(
   return new GatewayError(
     "capability_unsupported",
     400,
-    `The selected route does not support capability: ${capability}`,
+    `The selected route does not support capability: ${capability} (request {requestId}). Drop the ${capability} part of the request, or route to a model that accepts it. Know your tools — this one just isn't in the box 🧰`,
     { capability, ...details },
   );
 }

package/src/protocol/image-generation.ts

@@ -22,7 +22,7 @@ const OPENAI_ASPECT_RATIOS: Readonly<Record<string, string>> = {
 export function imagePrompt(body: Record<string, unknown>): string {
   if (typeof body.prompt === "string" && body.prompt.trim().length > 0) return body.prompt;
   if (!Array.isArray(body.messages)) {
-    throw new GatewayError("invalid_request", 400, "prompt is required");
+    throw new GatewayError("invalid_request", 400, "prompt is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   const texts: string[] = [];
   for (const message of body.messages) {
@@ -41,7 +41,7 @@ export function imagePrompt(body: Record<string, unknown>): string {
     }
   }
   const prompt = texts.join("\n").trim();
-  if (prompt.length === 0) throw new GatewayError("invalid_request", 400, "prompt is required");
+  if (prompt.length === 0) throw new GatewayError("invalid_request", 400, "prompt is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   return prompt;
 }
 

package/src/protocol/response/chat.ts

@@ -472,8 +472,8 @@ export async function* decodeChatSseStream(
         "platform_unavailable",
         502,
         error instanceof Error
-          ? `Malformed SSE event: ${error.message}`
-          : "Malformed SSE event",
+          ? `Malformed SSE event: ${error.message} (request {requestId}). The upstream sent something we can't read — retry 🌙`
+          : `Malformed SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙`,
         {},
         "upstream",
       );

package/src/protocol/response/codex.ts

@@ -364,7 +364,7 @@ export class CodexStreamFrameProcessor {
       throw new GatewayError(
         "tool_call_loop_detected",
         502,
-        "Codex whitespace-loop guard tripped: tool call emitted only whitespace argument deltas past the safety threshold",
+        "Codex whitespace-loop guard tripped (request {requestId}): tool call emitted only whitespace argument deltas past the safety threshold. Caught in a loop — breaking the cycle 🔁",
         { call_key: key, event_count: next.count, char_count: next.chars },
       );
     }

package/src/protocol/response/gemini.ts

@@ -124,7 +124,7 @@ export function decodeGeminiStreamEvent(
     throw new GatewayError(
       "platform_unavailable",
       502,
-      error instanceof Error ? `Malformed SSE event: ${error.message}` : "Malformed SSE event",
+      error instanceof Error ? `Malformed SSE event: ${error.message} (request {requestId}). The upstream sent something we can't read — retry 🌙` : `Malformed SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙`,
       {},
       "upstream",
     );

package/src/protocol/response/messages.ts

@@ -51,7 +51,7 @@ export function parseClaudeContent(value: unknown, isOAuth = false): ContentPart
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Claude response tool_use is missing id or name",
+        "Claude response tool_use is missing id or name (request {requestId}). The upstream came back empty-handed — retry 🌙",
         {},
         "upstream",
       );
@@ -69,7 +69,7 @@ export function parseClaudeContent(value: unknown, isOAuth = false): ContentPart
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Claude response tool_result is missing tool_use_id",
+        "Claude response tool_result is missing tool_use_id (request {requestId}). The upstream came back empty-handed — retry 🌙",
         {},
         "upstream",
       );
@@ -467,7 +467,7 @@ export async function* parseClaudeSseStream(
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Malformed Claude SSE event",
+        "Malformed Claude SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙",
         {},
         "upstream",
       );
@@ -476,7 +476,7 @@ export async function* parseClaudeSseStream(
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Invalid Claude SSE event",
+        "Invalid Claude SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙",
         {},
         "upstream",
       );
@@ -492,7 +492,7 @@ export async function* parseClaudeSseStream(
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "Claude stream ended before message_stop",
+      "Claude stream ended before message_stop (request {requestId}). The upstream came back empty-handed — retry 🌙",
       {},
       "upstream",
     );

package/src/protocol/response/responses.ts

@@ -336,8 +336,8 @@ export async function* decodeResponsesSseStream(
         "platform_unavailable",
         502,
         error instanceof Error
-          ? `Malformed SSE event: ${error.message}`
-          : "Malformed SSE event",
+          ? `Malformed SSE event: ${error.message} (request {requestId}). The upstream sent something we can't read — retry 🌙`
+          : `Malformed SSE event (request {requestId}). The upstream sent something we can't read — retry 🌙`,
         {},
         "upstream",
       );

package/src/protocol/sse-decoder.ts

@@ -57,14 +57,14 @@ const DEFAULT_MAX_EVENT_BYTES = 4 * 1024 * 1024;
 // `upstream` origin keeps the public envelope from prefixing it
 // a gateway-branded message, which blamed the gateway for the provider's bytes.
 function oversized(what: string): GatewayError {
-  return new GatewayError("platform_unavailable", 502, `SSE ${what} exceeds size bound`, {}, "upstream");
+  return new GatewayError("platform_unavailable", 502, `SSE ${what} exceeds size bound (request {requestId}). The upstream sent more than we can hold — retry 🌙`, {}, "upstream");
 }
 
 export async function* decodeSseEvents(
   body: ReadableStream<Uint8Array> | null,
   opts: SseDecodeOptions = {},
 ): AsyncIterable<SseEvent> {
-  if (body === null) throw new GatewayError("platform_unavailable", 502, "SSE response has no body", {}, "upstream");
+  if (body === null) throw new GatewayError("platform_unavailable", 502, "SSE response has no body (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   const maxEventBytes = opts.maxEventBytes ?? DEFAULT_MAX_EVENT_BYTES;
   const maxLineBytes = opts.maxLineBytes ?? maxEventBytes;
   const signal = opts.signal;
@@ -163,7 +163,18 @@ export async function* decodeSseEvents(
     // not 502 the request: only `event:`/`data:` carry payload, the rest is
     // heartbeat/metadata. Unknown colon-prefixed fields are ignored.
     if (/^[a-zA-Z0-9_-]+:/.test(line)) return;
-    throw new GatewayError("platform_unavailable", 502, "Malformed SSE line", {}, "upstream");
+    // Some vendors (Qoder IDE /model/v1) emit a single `data:` event whose JSON
+    // payload contains literal newlines, so the event arrives as several lines:
+    // the first has the `data:` prefix, the rest are bare continuations. Treat
+    // a bare line as a continuation of the open `data:` event rather than a
+    // malformed stream. A bare line with no open data is still an error.
+    if (dataLines.length > 0) {
+      dataLines.push(line);
+      eventBytes += line.length;
+      if (eventBytes > maxEventBytes) throw oversized("event");
+      return;
+    }
+    throw new GatewayError("platform_unavailable", 502, "Malformed SSE line (request {requestId}). The upstream sent something we can't read — retry 🌙", {}, "upstream");
   }
 
   try {

package/src/protocol/translation/capabilities.ts

@@ -259,7 +259,7 @@ export function ensureMaxTokensForThinking(
     throw new GatewayError(
       "invalid_request",
       400,
-      `Anthropic thinking budget requires max_tokens greater than ${buffer}; got ${currentMax} with budget ${budget}`,
+      `Anthropic thinking budget requires max_tokens greater than ${buffer}; got ${currentMax} with budget ${budget} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
       { budget_tokens: budget, max_tokens: currentMax },
     );
   }
@@ -364,7 +364,7 @@ function validateCacheBreakpoints(hint: CacheHint | undefined): void {
     throw new GatewayError(
       "invalid_request",
       400,
-      `cache_hint declares ${hint.list.length} breakpoints; at most ${MAX_CACHE_BREAKPOINTS} are supported`,
+      `cache_hint declares ${hint.list.length} breakpoints; at most ${MAX_CACHE_BREAKPOINTS} are supported (request {requestId}). Check the shape of what you sent — then resend 🪞`,
       { breakpoint_count: hint.list.length, max_breakpoints: MAX_CACHE_BREAKPOINTS },
     );
   }

package/src/protocol/upstream/send-claude-messages.ts

@@ -55,7 +55,7 @@ export async function* sendClaudeMessagesRequest(
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Claude response has no stream body",
+        "Claude response has no stream body (request {requestId}). The upstream came back empty-handed — retry 🌙",
         {},
         "upstream",
       );
@@ -70,7 +70,7 @@ export async function* sendClaudeMessagesRequest(
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "Claude response is not valid JSON",
+      "Claude response is not valid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙",
       {},
       "upstream",
     );
@@ -79,7 +79,7 @@ export async function* sendClaudeMessagesRequest(
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "Claude response must be an object",
+      "Claude response must be an object (request {requestId}). The upstream came back empty-handed — retry 🌙",
       {},
       "upstream",
     );

package/src/providers/adapters/base-adapter.ts

@@ -25,7 +25,7 @@ export abstract class BaseProviderAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (request.model.includes("?")) {
-      throw new GatewayError("invalid_request", 400, "model must not contain query string");
+      throw new GatewayError("invalid_request", 400, "model must not contain query string (request {requestId}). Check the shape of what you sent — then resend 🪞");
     }
     const headers = await this.prepareHeaders(context, request, target);
     const payload = await this.preparePayload(request, target, context);

package/src/providers/adapters/compatible-adapter.ts

@@ -351,7 +351,7 @@ export class OpenAICompatibleAdapter extends BaseProviderAdapter {
         throw new GatewayError(
           "platform_unavailable",
           502,
-          wireFamily === "responses" ? "Responses returned empty stream" : "Chat returned empty stream",
+          `${wireFamily === "responses" ? "Responses returned empty stream" : "Chat returned empty stream"} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
           {},
           "upstream",
         );
@@ -379,7 +379,7 @@ export class OpenAICompatibleAdapter extends BaseProviderAdapter {
         throw new GatewayError(
           "transport_unavailable",
           502,
-          `Upstream returned a non-JSON response: ${summary}`.slice(0, 300),
+          `Upstream returned a non-JSON response: ${summary} (request {requestId}). The connection ghosted us — come back in a moment 👻`.slice(0, 320),
           { upstreamStatus: res.status, contentType },
           "upstream",
         );

package/src/providers/authentication/oauth-refresh-service.ts

@@ -28,7 +28,7 @@ import { providerAccounts, providerOauthStates } from "../../persistence/schema"
 import { decryptCredentialToString, encryptCredential } from "../../security/crypto";
 import { invalidateCredentialCache } from "../operations/provider-credential-service";
 import { resolveAccountDisabledRecoveryMs } from "../../config/cooldowns";
-import { record } from "./oauth-flow-store";
+import { asJsonbRecord } from "../../shared/coerce";
 import {
   loadAccountWithFreshness,
   type AccountWithFreshnessRow,
@@ -224,7 +224,7 @@ async function persistRefreshed(
  * never reach into the database.
  */
 function buildRefreshContext(row: AccountRow, includeAccessToken: boolean): OAuthRefreshContext {
-  const authState = record(row.authState);
+  const authState = asJsonbRecord(row.authState);
   return {
     account_id: row.id,
     ...(authState === undefined ? {} : { auth_state: authState }),

package/src/providers/configured-provider.ts

@@ -11,7 +11,7 @@ export function ensurePayloadModel(
 ): string {
   const value = payload["model"];
   const model = typeof value === "string" && value.trim() ? value.trim() : candidate.model_id.trim();
-  if (!model) throw new GatewayError("invalid_request", 400, `${providerName} model is required`);
+  if (!model) throw new GatewayError("invalid_request", 400, `${providerName} model is required (request {requestId}). Check the shape of what you sent — then resend 🪞`);
   payload["model"] = model;
   return model;
 }

package/src/providers/discovery/probe-phases.ts

@@ -109,7 +109,7 @@ export function grok407ProbeFailure(args: {
   return new GatewayError(
     "quota_exceeded",
     429,
-    detail,
+    `${detail} (request {requestId}). You've maxed this window — pace yourself ⏳`,
     {
       ...priorDetails,
       providerCode: "subscription:free-usage-exhausted",
@@ -289,7 +289,7 @@ export async function resolveProbeTarget(args: {
           throw new GatewayError(
             "model_not_found",
             404,
-            `No ${requestedServiceKind} model ${modelId} is registered for provider ${providerId}`,
+            `No ${requestedServiceKind} model ${modelId} is registered for provider ${providerId} (request {requestId}). Try another model — this one's off the menu 📚`,
           );
         }
         const ctx = wireContextFrom(providerWireRow);