cartethyia 2.7.3 → 2.7.4

package/src/providers/integrations/cloudflareai/cloudflareai.ts

@@ -16,6 +16,7 @@
  *    protocol at the `/anthropic` path suffix, including `thinking_delta`
  *    blocks, so the Messages leg is built directly.
  */
+import { assertWireFamily } from "../../provider-contracts";
 import type {
   ProviderAdapter,
   ProviderDispatchContext,
@@ -57,7 +58,7 @@ function cloudflareEnvelope(context: ProviderDispatchContext): {
 } {
   const secret = context.credential.secret;
   if (secret === undefined || secret.length === 0) {
-    throw new GatewayError("invalid_request", 400, "cloudflareai: credential is missing a secret value");
+    throw new GatewayError("invalid_request", 400, "cloudflareai: credential is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑");
   }
   let envelope: ReturnType<typeof decodeCloudflareAiGatewayCredential>;
   try {
@@ -66,7 +67,7 @@ function cloudflareEnvelope(context: ProviderDispatchContext): {
     throw new GatewayError(
       "invalid_request",
       400,
-      `cloudflareai: ${error instanceof Error ? error.message : "stored credential is not a Cloudflare envelope"}`,
+      `cloudflareai: ${error instanceof Error ? error.message : "stored credential is not a Cloudflare envelope"} (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
   return { token: envelope.token, baseUrl: cloudflareBaseUrl(envelope.accountId, envelope.gatewayId) };
@@ -93,11 +94,7 @@ class CloudflareAiGatewayAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "messages") {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        `cloudflareai supports messages only, got ${candidate.wire_family}`,
-      );
+      assertWireFamily(candidate, "messages", "cloudflareai");
     }
     const { token, baseUrl } = cloudflareEnvelope(context);
     const outbound = buildClaudeMessagesRequest({

package/src/providers/integrations/codex/codex-errors.ts

@@ -167,7 +167,7 @@ export async function mapCodexErrorResponse(res: Response): Promise<never> {
   throw new GatewayError(
     classification.code,
     classification.status,
-    friendlyMessage ?? sanitized,
+    `${friendlyMessage ?? sanitized} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
     details,
     classification.origin,
   );

package/src/providers/integrations/codex/codex.ts

@@ -22,7 +22,7 @@
  * OpenAI-compatible factory's reach — stays bespoke, never re-audit.
  */
 import type { CanonicalEvent, CanonicalRequest } from "../../../protocol/canonical-model";
-import { GatewayError, capabilityUnsupported } from "../../../protocol/gateway-error";
+import { GatewayError } from "../../../protocol/gateway-error";
 import { getCodexVersion } from "../../operations/client-versions";
 import { buildCodexUserAgent } from "../../operations/cli-platform";
 import { randomUUID } from "node:crypto";
@@ -54,6 +54,7 @@ export function _setCodexRateLimitSleepForTesting(
 function sleep(ms: number, signal: AbortSignal): Promise<void> {
   return rateLimitSleep(ms, signal);
 }
+import { assertWireFamily } from "../../provider-contracts";
 import type { ImageGenerationOutcome, ProviderDispatchTarget, ProviderAdapter, ProviderDispatchContext, ResolvedCredential, WebSearchOutcome, WebSearchResult } from "../../provider-contracts";
 import type { FetchLike } from "../../quota/quota-contracts";
 import { boundedUpstreamArray, boundedUpstreamNumber, sanitizeUpstreamLabel } from "../../provider-sanitize";
@@ -199,7 +200,7 @@ export function assertCodexOAuthCredential(
     throw new GatewayError(
       "invalid_request",
       400,
-      `codex: ChatGPT OAuth credential required (got credential_kind=${credential.credential_kind})`,
+      `codex: ChatGPT OAuth credential required (got credential_kind=${credential.credential_kind}) (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
 }
@@ -361,7 +362,7 @@ function authHeadersForCodex(
     throw new GatewayError(
       "invalid_request",
       400,
-      "codex: OAuth credential is missing a bearer token",
+      "codex: OAuth credential is missing a bearer token (request {requestId}). Wrong key, right door — check the credential 🔑",
     );
   }
   const token = new TextDecoder().decode(credential.secret);
@@ -748,7 +749,7 @@ export function createCodexAdapter(
       context: ProviderDispatchContext,
     ): Promise<WebSearchOutcome> {
       const query = typeof body.query === "string" ? body.query.trim() : "";
-      if (!query) throw new GatewayError("invalid_request", 400, "search query is required");
+      if (!query) throw new GatewayError("invalid_request", 400, "search query is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
       const requested = typeof body.model === "string" ? body.model.trim() : "";
       const model = requested.length > 0 && requested !== "codex" ? requested : CODEX_SEARCH_DEFAULT_MODEL;
       const request: CanonicalRequest = {
@@ -779,7 +780,7 @@ export function createCodexAdapter(
       }
       const results = normalizeCodexSearchCitations(citations, answerText);
       if (results.length === 0)
-        throw new GatewayError("platform_unavailable", 502, "Codex search returned no citations");
+        throw new GatewayError("platform_unavailable", 502, "Codex search returned no citations (request {requestId}). The upstream came back empty-handed — retry 🌙");
       const rawMax = body.max_results;
       const maxResults =
         typeof rawMax === "number" && Number.isFinite(rawMax)
@@ -796,7 +797,7 @@ export function createCodexAdapter(
       const prompt = imagePrompt(body);
       const requested =
         candidate.model_id.length > 0 ? candidate.model_id : typeof body.model === "string" ? body.model : "";
-      if (requested.length === 0) throw new GatewayError("invalid_request", 400, "model is required");
+      if (requested.length === 0) throw new GatewayError("invalid_request", 400, "model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
       // A `-image` id is the chat model with the suffix removed. Dedicated
       // image tools still need a chat carrier, and the account's visible 5.6
       // models are the current ones.
@@ -868,7 +869,7 @@ export function createCodexAdapter(
           try {
             parsed = JSON.parse(data);
           } catch {
-            throw new GatewayError("platform_unavailable", 502, "Codex image stream returned malformed JSON", {}, "upstream");
+            throw new GatewayError("platform_unavailable", 502, "Codex image stream returned malformed JSON (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
           }
           if (isRecord(parsed) && (parsed.type === "error" || parsed.type === "response.failed")) {
             const message = isRecord(parsed.error) && typeof parsed.error.message === "string"
@@ -876,7 +877,7 @@ export function createCodexAdapter(
               : isRecord(parsed.response) && isRecord(parsed.response.error) && typeof parsed.response.error.message === "string"
                 ? parsed.response.error.message
                 : "Codex image generation failed";
-            throw new GatewayError("platform_unavailable", 502, message, {}, "upstream");
+            throw new GatewayError("platform_unavailable", 502, `${message} (request {requestId}). The upstream came back empty-handed — retry 🌙`, {}, "upstream");
           }
           image = responsesImageResult(parsed) ?? image;
         }
@@ -903,19 +904,17 @@ export function createCodexAdapter(
         throw new GatewayError(
           "invalid_request",
           400,
-          "codex adapter received non-codex candidate",
+          "codex adapter received non-codex candidate (request {requestId}). Even we have bad days — check the registry wiring 🐻",
         );
       }
       if (candidate.wire_family !== "responses") {
-        throw capabilityUnsupported("responses", {
-          wire_family: candidate.wire_family,
-        });
+        assertWireFamily(candidate, "responses", "codex");
       }
       if (request.model.includes("?")) {
         throw new GatewayError(
           "invalid_request",
           400,
-          "model must not contain query string",
+          "model must not contain query string (request {requestId}). Check the shape of what you sent — then resend 🪞",
         );
       }
 
@@ -1181,8 +1180,8 @@ export function createCodexAdapter(
               "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/providers/integrations/commandcode/commandcode.ts

@@ -527,7 +527,7 @@ export function transformLine(line: string, state: StreamState, seqBase: number)
     const message =
       extractUpstreamMessage(raw) ||
       extractUpstreamMessage(event) ||
-      "Command Code stream error";
+      "Command Code stream error (request {requestId}). The upstream came back empty-handed — retry 🌙";
     throw new GatewayError(
       classification.code,
       classification.status,
@@ -558,11 +558,11 @@ export async function* transformNdjson(body: ReadableStream<Uint8Array>, signal:
   yield { type: "response_start", sequence_number: seq++, model: "commandcode" } as CanonicalEvent;
 
   const readWithAbort = (): Promise<{ done: boolean; value?: Uint8Array }> => {
-    if (signal.aborted) throw new GatewayError("transport_closed", 499, "Command Code stream aborted");
+    if (signal.aborted) throw new GatewayError("transport_closed", 499, "Command Code stream aborted (request {requestId}). Send it again whenever ready 🙃");
     const { promise, resolve, reject } = Promise.withResolvers<{ done: boolean; value?: Uint8Array }>() as unknown as { promise: Promise<{ done: boolean; value?: Uint8Array }>; resolve: (v: unknown) => void; reject: (e: unknown) => void };
     const onAbort = (): void => {
-      if (signal.aborted) reject(new GatewayError("transport_closed", 499, "Command Code stream aborted"));
-      else reject(new GatewayError("platform_unavailable", 502, "Command Code stream error", {}, "upstream"));
+      if (signal.aborted) reject(new GatewayError("transport_closed", 499, "Command Code stream aborted (request {requestId}). Send it again whenever ready 🙃"));
+      else reject(new GatewayError("platform_unavailable", 502, "Command Code stream error (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream"));
     };
     signal.addEventListener("abort", onAbort, { once: true });
     void reader.read().then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));

package/src/providers/integrations/commandcode/quota.ts

@@ -72,7 +72,11 @@ function creditWindow(credits: Record<string, unknown>): ProviderQuotaWindow | n
   return {
     kind: "credits",
     label: "Credits",
-    accounting: "independent",
+    // These are credits in one unit that can be spent interchangeably, so
+    // they are pooled like Qoder's plan/granted balances — not independent
+    // rate-limit lanes. The account-row pill and the Quota page both sum
+    // pooled windows, so this must be `pooled` or the balance never renders.
+    accounting: "pooled",
     usedPercent: null,
     remainingPercent: null,
     resetsAt: null,

package/src/providers/integrations/cursor/cursor-http2.ts

@@ -46,7 +46,7 @@ function connectErrorEnvelope(payload: Uint8Array): GatewayError | undefined {
     return new GatewayError(
       "quota_exceeded",
       429,
-      `Cursor refused the Run: ${detail}`,
+      `Cursor refused the Run: ${detail} (request {requestId}). You've maxed this window — pace yourself ⏳`,
       { providerId: "cursor", upstreamCode: code },
       "upstream",
     );
@@ -54,7 +54,7 @@ function connectErrorEnvelope(payload: Uint8Array): GatewayError | undefined {
   return new GatewayError(
     "platform_unavailable",
     502,
-    `Cursor refused the Run: ${detail}`,
+    `Cursor refused the Run: ${detail} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
     { providerId: "cursor", upstreamCode: code },
     "upstream",
   );
@@ -126,7 +126,7 @@ export async function openCursorRun(input: {
     throw new GatewayError(
       "invalid_request",
       400,
-      "Cursor Run requires an allowlisted Cursor agent origin",
+      "Cursor Run requires an allowlisted Cursor agent origin (request {requestId}). All roads blocked — time to find a new route 🗺️",
       { origin: input.origin },
     );
   }
@@ -153,7 +153,7 @@ function grpcError(status: string, message: string | undefined): GatewayError {
     return new GatewayError(
       "authentication_failed",
       401,
-      `Cursor refused the credential${detail}`,
+      `Cursor refused the credential${detail} (request {requestId}). Wrong key, right door — check the credential 🔑`,
       { grpcStatus: status },
       "upstream",
     );
@@ -162,7 +162,7 @@ function grpcError(status: string, message: string | undefined): GatewayError {
     return new GatewayError(
       "quota_exceeded",
       429,
-      `Cursor refused the Run${detail}`,
+      `Cursor refused the Run${detail} (request {requestId}). You've maxed this window — pace yourself ⏳`,
       { grpcStatus: status },
       "upstream",
     );
@@ -171,7 +171,7 @@ function grpcError(status: string, message: string | undefined): GatewayError {
     return new GatewayError(
       "deadline_exceeded",
       504,
-      `Cursor Run ended before it finished${detail}`,
+      `Cursor Run ended before it finished${detail} (request {requestId}). Some things just take longer 🐢`,
       { grpcStatus: status },
       "upstream",
     );
@@ -179,7 +179,7 @@ function grpcError(status: string, message: string | undefined): GatewayError {
   return new GatewayError(
     "platform_unavailable",
     502,
-    `Cursor Run failed (gRPC ${status})${detail}`,
+    `Cursor Run failed (gRPC ${status})${detail} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
     { grpcStatus: status },
     "upstream",
   );
@@ -205,7 +205,7 @@ export function cursorRunTerminationError(input: {
       : new GatewayError(
           "transport_unavailable",
           502,
-          `Cursor Run transport interrupted: ${input.reason.error.message}`,
+          `Cursor Run transport interrupted: ${input.reason.error.message} (request {requestId}). The connection ghosted us — come back in a moment 👻`,
           {},
           "network",
         );
@@ -216,7 +216,7 @@ export function cursorRunTerminationError(input: {
     return new GatewayError(
       status === 401 || status === 403 ? "authentication_failed" : "platform_unavailable",
       status === 401 || status === 403 ? 401 : 502,
-      `Cursor Run failed by remote: ${status}`,
+      `Cursor Run failed by remote: ${status} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
       { httpStatus: status, ...(message === undefined ? {} : { upstreamMessage: message }) },
       "upstream",
     );
@@ -229,7 +229,7 @@ export function cursorRunTerminationError(input: {
   return new GatewayError(
     "platform_unavailable",
     502,
-    "Cursor Run ended before turn_ended",
+    "Cursor Run ended before turn_ended (request {requestId}). The upstream came back empty-handed — retry 🌙",
     {},
     "upstream",
   );
@@ -253,7 +253,7 @@ export async function* decodeServerMessages(
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "Cursor Run exceeded the frame buffer bound",
+        "Cursor Run exceeded the frame buffer bound (request {requestId}). The upstream sent more than we can hold — retry 🌙",
         {},
         "upstream",
       );

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

@@ -152,14 +152,14 @@ function finishImage(bytes: Uint8Array): CursorImageInput {
     throw new GatewayError(
       "invalid_request",
       400,
-      "Cursor accepts PNG, JPEG, WebP and GIF image input only",
+      "Cursor accepts PNG, JPEG, WebP and GIF image input only (request {requestId}). Check the shape of what you sent — then resend 🪞",
     );
   }
   if (bytes.byteLength > MAX_IMAGE_BYTES) {
     throw new GatewayError(
       "invalid_request",
       400,
-      `Cursor image input exceeds the ${MAX_IMAGE_BYTES}-byte limit`,
+      `Cursor image input exceeds the ${MAX_IMAGE_BYTES}-byte limit (request {requestId}). We love long reads, but not that long 📚`,
     );
   }
   return { data: bytes, mimeType };
@@ -183,7 +183,7 @@ async function resolveImageInput(
   if (dataUrl !== undefined) {
     const bytes = base64ToBytes(dataUrl.data);
     if (bytes === undefined) {
-      throw new GatewayError("invalid_request", 400, "Cursor image attachment is not valid base64");
+      throw new GatewayError("invalid_request", 400, "Cursor image attachment is not valid base64 (request {requestId}). Check the shape of what you sent — then resend 🪞");
     }
     return finishImage(bytes);
   }
@@ -192,7 +192,7 @@ async function resolveImageInput(
     throw new GatewayError(
       "invalid_request",
       400,
-      "Cursor image URLs must be HTTPS; private and non-TLS sources are not fetched",
+      "Cursor image URLs must be HTTPS; private and non-TLS sources are not fetched (request {requestId}). Check the shape of what you sent — then resend 🪞",
     );
   }
   const fetcher = context.outbound_attachment_fetch;
@@ -200,7 +200,7 @@ async function resolveImageInput(
     throw new GatewayError(
       "invalid_request",
       400,
-      "Cursor has no validated egress to fetch this image URL",
+      "Cursor has no validated egress to fetch this image URL (request {requestId}). All roads blocked — time to find a new route 🗺️",
     );
   }
   // Redirects are not followed: reject the response rather than letting a
@@ -222,7 +222,7 @@ async function resolveImageInput(
     throw new GatewayError(
       "invalid_request",
       400,
-      `Cursor image input exceeds the ${MAX_IMAGE_BYTES}-byte limit`,
+      `Cursor image input exceeds the ${MAX_IMAGE_BYTES}-byte limit (request {requestId}). We love long reads, but not that long 📚`,
     );
   }
   return finishImage(body);
@@ -503,7 +503,7 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        "This tool result cannot be matched to a live Cursor Run; resend the complete conversation.",
+        "This tool result cannot be matched to a live Cursor Run (request {requestId}); resend the complete conversation. The session went cold — reconnect or resend 🔌",
       );
     }
     const resolvedAll = pending.map((item) => cursorRunSessions.resolveCall(item.callId, scope));
@@ -530,7 +530,7 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        "This tool result refers to a Cursor tool call that is no longer pending. Resend the complete conversation.",
+        "This tool result refers to a Cursor tool call that is no longer pending (request {requestId}). Resend the complete conversation. The session went cold — reconnect or resend 🔌",
         { callIds: pending.map((item) => item.callId) },
       );
     }
@@ -538,12 +538,12 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        "These tool results belong to different Cursor Runs; resend them one Run at a time.",
+        "These tool results belong to different Cursor Runs (request {requestId}); resend them one Run at a time. The session went cold — reconnect or resend 🔌",
       );
     }
     const session = cursorRunSessions.get(runId);
     if (session === undefined) {
-      throw new GatewayError("invalid_request", 400, "Cursor Run is no longer live");
+      throw new GatewayError("invalid_request", 400, "Cursor Run is no longer live (request {requestId}). The session went cold — reconnect or resend 🔌");
     }
     const handle = this.#handles.get(runId);
     if (handle === undefined) {
@@ -605,7 +605,7 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "admission_unavailable",
         503,
-        "Cursor requires validated HTTP/2 egress; none is configured for this route",
+        "Cursor requires validated HTTP/2 egress (request {requestId}); none is configured for this route. No bridge to cross — configure a pool first 🏗️",
         { providerId: CURSOR_PROVIDER_ID },
       );
     }
@@ -784,7 +784,7 @@ class CursorAdapter implements ProviderAdapter {
             : new GatewayError(
                 "platform_unavailable",
                 502,
-                `Cursor Run failed: ${error instanceof Error ? error.message : String(error)}`,
+                `Cursor Run failed (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The upstream came back empty-handed — retry 🌙`,
                 { providerId: CURSOR_PROVIDER_ID },
                 "upstream",
               );
@@ -828,7 +828,7 @@ class CursorAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        `Cursor Run origin could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+        `Cursor Run origin could not be resolved (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
         { providerId: CURSOR_PROVIDER_ID },
         "upstream",
       );
@@ -890,7 +890,7 @@ class CursorAdapter implements ProviderAdapter {
         }
         const message = item;
         if (context.abort_signal.aborted) {
-          failure = new GatewayError("transport_closed", 499, "request was cancelled");
+          failure = new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
           break;
         }
         const execServer = recordOf(message["exec_server_message"]);
@@ -994,7 +994,7 @@ class CursorAdapter implements ProviderAdapter {
           : new GatewayError(
               "platform_unavailable",
               502,
-              `Cursor Run failed: ${error instanceof Error ? error.message : String(error)}`,
+              `Cursor Run failed (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The upstream came back empty-handed — retry 🌙`,
               { providerId: CURSOR_PROVIDER_ID },
               "upstream",
             );

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

@@ -270,7 +270,7 @@ export function factoryRegionUnavailable(modelId: string, region: string): Gatew
   return new GatewayError(
     "capability_unsupported",
     400,
-    `factory: ${modelId} is unavailable in this account region (${region})`,
+    `factory: ${modelId} is unavailable in this account region (${region}) (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
     { model: modelId, region, reason: "Factory Droid model is unavailable in this account region." },
   );
 }
@@ -351,7 +351,7 @@ export function factoryRoutingHeaders(
 function factoryEnvelope(context: ProviderDispatchContext): { token: string; orgId: string } {
   const secret = context.credential.secret;
   if (secret === undefined || secret.length === 0) {
-    throw new GatewayError("invalid_request", 400, "factory: credential is missing a secret value");
+    throw new GatewayError("invalid_request", 400, "factory: credential is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑");
   }
   try {
     const envelope = decodeFactoryDroidCredential(secret);
@@ -360,7 +360,7 @@ function factoryEnvelope(context: ProviderDispatchContext): { token: string; org
     throw new GatewayError(
       "invalid_request",
       400,
-      `factory: ${error instanceof Error ? error.message : "stored credential is not a Factory Droid envelope"}`,
+      `factory: ${error instanceof Error ? error.message : "stored credential is not a Factory Droid envelope"} (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
 }
@@ -523,7 +523,7 @@ class FactoryDroidAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        "factory gemini returned empty stream",
+        "factory gemini returned empty stream (request {requestId}). The upstream came back empty-handed — retry 🌙",
         {},
         "upstream",
       );

package/src/providers/integrations/gemini.ts

@@ -6,7 +6,7 @@ import { mapUpstreamHttpError } from "../../transport/failure-policy";
 import type { CanonicalEvent, CanonicalRequest, CanonicalStopReason } from "../../protocol/canonical-model";
 import { decodeSseEvents } from "../../protocol/sse-decoder";
 import { usageFromProvider } from "../provider-usage";
-import { readCredentialSecret, type ImageGenerationOutcome, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext, type WebSearchOutcome, type WebSearchResult } from "../provider-contracts";
+import { readCredentialSecret, assertWireFamily, type ImageGenerationOutcome, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext, type WebSearchOutcome, type WebSearchResult } from "../provider-contracts";
 import type { ModelDefinition } from "../provider-model-definition";
 import { fetchOpenAICompatibleModels } from "../discovery/openai-model-discovery";
 import { isRecord } from "../../protocol/codecs";
@@ -181,7 +181,7 @@ class GeminiAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "chat" && candidate.wire_family !== "responses" && candidate.wire_family !== "messages") {
-      throw new GatewayError("capability_unsupported", 400, `gemini supports chat/responses/messages, got ${candidate.wire_family}`);
+      assertWireFamily(candidate, ["chat", "responses", "messages"], "gemini");
     }
     const apiKey = readCredentialSecret(context.credential, "Gemini API key is required");
 
@@ -262,7 +262,7 @@ class GeminiAdapter implements ProviderAdapter {
         return;
       }
 
-      if (!response.body) throw new GatewayError("platform_unavailable", 502, "Gemini returned empty stream", {}, "upstream");
+      if (!response.body) throw new GatewayError("platform_unavailable", 502, "Gemini returned empty stream (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       let seq = 1;
       yield { type: "response_start", sequence_number: seq++, model: request.model } as CanonicalEvent;
       const state = { started: true, stopped: false, activeCalls: new Set<string>() };
@@ -339,7 +339,7 @@ class GeminiAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): Promise<WebSearchOutcome> {
     const query = typeof body.query === "string" ? body.query.trim() : "";
-    if (!query) throw new GatewayError("invalid_request", 400, "search query is required");
+    if (!query) 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)
@@ -368,7 +368,7 @@ class GeminiAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        `Gemini search unreachable: ${error instanceof Error ? error.message : String(error)}`,
+        `Gemini search unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
       );
     }
     if (!response.ok) throw await mapUpstreamHttpError(response, "gemini search");
@@ -376,11 +376,11 @@ class GeminiAdapter implements ProviderAdapter {
     try {
       data = await response.json();
     } catch {
-      throw new GatewayError("platform_unavailable", 502, "Gemini search returned invalid JSON");
+      throw new GatewayError("platform_unavailable", 502, "Gemini search returned invalid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙");
     }
     const results = normalizeGroundingResults(data, maxResults);
     if (results.length === 0)
-      throw new GatewayError("platform_unavailable", 502, "Gemini search returned no grounded results");
+      throw new GatewayError("platform_unavailable", 502, "Gemini search returned no grounded results (request {requestId}). The upstream came back empty-handed — retry 🌙");
     return { results, total_results: results.length };
   }
 
@@ -391,7 +391,7 @@ class GeminiAdapter implements ProviderAdapter {
   ): Promise<ImageGenerationOutcome> {
     const prompt = imagePrompt(body);
     const model = candidate.model_id.length > 0 ? candidate.model_id : typeof body.model === "string" ? body.model : "";
-    if (model.length === 0) throw new GatewayError("invalid_request", 400, "model is required");
+    if (model.length === 0) throw new GatewayError("invalid_request", 400, "model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
     const apiKey = readCredentialSecret(context.credential, "Gemini API key is required");
     const outboundFetch = context.outbound_fetch ?? this.fetchFn;
     const lifecycle = createUpstreamDeadlineLifecycle(context);
@@ -418,7 +418,7 @@ class GeminiAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        `Gemini image generation unreachable: ${error instanceof Error ? error.message : String(error)}`,
+        `Gemini image generation unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
         {},
         "upstream",
       );
@@ -430,11 +430,11 @@ class GeminiAdapter implements ProviderAdapter {
     try {
       data = await response.json();
     } catch {
-      throw new GatewayError("platform_unavailable", 502, "Gemini image generation returned invalid JSON", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "Gemini image generation returned invalid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     const images = geminiInlineImages(data);
     if (images.length === 0) {
-      throw new GatewayError("platform_unavailable", 502, "Gemini image generation returned no image", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "Gemini image generation returned no image (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     return { created: imageCreatedSeconds(), data: images };
   }

package/src/providers/integrations/github/github.ts

@@ -411,7 +411,7 @@ class GithubAdapter extends OpenAICompatibleAdapter {
 
     const secret = context.credential.secret;
     if (secret === undefined || secret.length === 0) {
-      throw new GatewayError("authentication_failed", 401, "GitHub Copilot credential is missing");
+      throw new GatewayError("authentication_failed", 401, "GitHub Copilot credential is missing (request {requestId}). Wrong key, right door — check the credential 🔑");
     }
     const credential = new TextDecoder().decode(secret);
     const autoInput = autoPrompt(request);
@@ -424,7 +424,7 @@ class GithubAdapter extends OpenAICompatibleAdapter {
       : this.#getCachedAutoDecision(cacheKey, autoInput.hasImage);
     if (autoDecision === undefined) {
       if (autoInput.prompt.length === 0) {
-        throw new GatewayError("invalid_request", 400, "Copilot Auto requires a text prompt");
+        throw new GatewayError("invalid_request", 400, "Copilot Auto requires a text prompt (request {requestId}). Check the shape of what you sent — then resend 🪞");
       }
       autoDecision = await this.#selectAutoModel(
         autoInput.prompt,
@@ -462,7 +462,7 @@ class GithubAdapter extends OpenAICompatibleAdapter {
       throw new GatewayError(
         "upstream_unprocessable",
         502,
-        "Copilot Auto selected a model without a discovered inference endpoint",
+        "Copilot Auto selected a model without a discovered inference endpoint (request {requestId}). The upstream came back empty-handed — retry 🌙",
         { selected_model: selectedModelId },
         "upstream",
       );
@@ -498,7 +498,7 @@ class GithubAdapter extends OpenAICompatibleAdapter {
       ? undefined
       : parseGithubCredential(new TextDecoder().decode(context.credential.secret));
     if (credential === undefined) {
-      throw new GatewayError("authentication_failed", 401, "GitHub Copilot credential is missing");
+      throw new GatewayError("authentication_failed", 401, "GitHub Copilot credential is missing (request {requestId}). Wrong key, right door — check the credential 🔑");
     }
     const payload: Record<string, unknown> = { prompt, tier };
     if (hasImage) payload.has_image = true;
@@ -522,7 +522,7 @@ class GithubAdapter extends OpenAICompatibleAdapter {
       throw new GatewayError(
         "upstream_unprocessable",
         502,
-        "Copilot Auto returned an invalid routing response",
+        "Copilot Auto returned an invalid routing response (request {requestId}). The upstream came back empty-handed — retry 🌙",
         {},
         "upstream",
       );
@@ -545,7 +545,7 @@ class GithubAdapter extends OpenAICompatibleAdapter {
       throw new GatewayError(
         "upstream_unprocessable",
         502,
-        "Copilot Auto did not return a selected model",
+        "Copilot Auto did not return a selected model (request {requestId}). The upstream came back empty-handed — retry 🌙",
         {},
         "upstream",
       );

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

@@ -9,12 +9,12 @@
  * OpenAI-compatible adapter.
  */
 import { randomBytes, randomUUID } from "node:crypto";
-import { GatewayError } from "../../../protocol/gateway-error";
 import type { CanonicalEvent, CanonicalRequest } from "../../../protocol/canonical-model";
 import {
   OpenAICompatibleAdapter,
   withBearerAuthentication,
 } from "../../adapters/compatible-adapter";
+import { assertCredentialKind } from "../../provider-contracts";
 import type { ProviderAdapter, ProviderDispatchTarget, ProviderDispatchContext } from "../../provider-contracts";
 import { providerBaseUrl } from "../../provider-metadata";
 import { boundedUpstreamArray, boundedUpstreamNumber, sanitizeUpstreamLabel } from "../../provider-sanitize";
@@ -526,11 +526,7 @@ class GrokAdapter extends OpenAICompatibleAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (context.credential.credential_kind !== "oauth") {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        "grok requires an xAI OAuth device credential",
-      );
+      assertCredentialKind(context.credential, "oauth", "grok");
     }
     yield* super.dispatch(request, candidate, context);
   }