cartethyia 2.7.3 → 2.7.4

package/src/providers/discovery/probing-service.ts

@@ -304,7 +304,7 @@ export class ProviderProbingService {
             throw new GatewayError(
               "capability_unsupported",
               400,
-              `Provider ${providerId} has no web search transport`,
+              `Provider ${providerId} has no web search transport (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
             );
           }
           const searchProbeQuery = request.prompt?.trim() || "Cartethyia gateway probe";
@@ -325,14 +325,14 @@ export class ProviderProbingService {
             snippet: hit.snippet,
           }));
           if (!response.results || response.results.length === 0) {
-            dispatchError = new GatewayError("platform_unavailable", 502, "web search returned no results");
+            dispatchError = new GatewayError("platform_unavailable", 502, "web search returned no results (request {requestId}). The upstream came back empty-handed — retry 🌙");
           }
         } else if (serviceKind === "systemone") {
           if (typeof adapter.systemone !== "function") {
             throw new GatewayError(
               "capability_unsupported",
               400,
-              `Provider ${providerId} has no System One transport`,
+              `Provider ${providerId} has no System One transport (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
             );
           }
           const response = await adapter.systemone(
@@ -360,14 +360,14 @@ export class ProviderProbingService {
             dispatchError = new GatewayError(
               response.status >= 500 ? "platform_unavailable" : "invalid_request",
               response.status,
-              `System One upstream error: ${raw.slice(0, 240)}`,
+              `System One upstream error (request {requestId}): ${raw.slice(0, 240)}`,
             );
           } else {
             let parsed: unknown;
             try {
               parsed = raw ? JSON.parse(raw) : null;
             } catch {
-              dispatchError = new GatewayError("platform_unavailable", 502, "System One returned invalid JSON");
+              dispatchError = new GatewayError("platform_unavailable", 502, "System One returned invalid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙");
             }
             if (parsed !== null && parsed !== undefined) {
               const answers =
@@ -381,7 +381,7 @@ export class ProviderProbingService {
                 dispatchError = new GatewayError(
                   "platform_unavailable",
                   502,
-                  "System One returned no answers",
+                  "System One returned no answers (request {requestId}). The upstream came back empty-handed — retry 🌙",
                 );
               }
             }
@@ -709,7 +709,7 @@ export class ProviderProbingService {
           throw new GatewayError(
             "transport_unavailable",
             502,
-            `Model discovery failed for ${providerId}: ${error instanceof Error ? error.message : "unknown error"}`,
+            `Model discovery failed for ${providerId}: ${error instanceof Error ? error.message : "unknown error"} (request {requestId}). The connection ghosted us — come back in a moment 👻`,
             {},
             "upstream",
           );
@@ -718,7 +718,7 @@ export class ProviderProbingService {
           throw new GatewayError(
             "transport_unavailable",
             502,
-            `Model discovery failed for ${providerId}: endpoint returned no usable models`,
+            `Model discovery failed for ${providerId}: endpoint returned no usable models (request {requestId}). The upstream came back empty-handed — retry 🌙`,
             {},
             "upstream",
           );
@@ -764,7 +764,7 @@ export class ProviderProbingService {
             throw new GatewayError(
               "transport_unavailable",
               502,
-              `Model discovery failed for ${providerId}: ${error instanceof Error ? error.message : "unknown error"}`,
+              `Model discovery failed for ${providerId}: ${error instanceof Error ? error.message : "unknown error"} (request {requestId}). The connection ghosted us — come back in a moment 👻`,
               {},
               "upstream",
             );
@@ -799,7 +799,7 @@ export class ProviderProbingService {
         throw new GatewayError(
           "invalid_request",
           400,
-          `Add an account for ${providerId} first — model listing needs a credential.`,
+          `Add an account for ${providerId} first — model listing needs a credential (request {requestId}). Wrong key, right door — check the credential 🔑`,
           {},
           "cartethyia",
         );
@@ -811,7 +811,7 @@ export class ProviderProbingService {
         throw new GatewayError(
           "invalid_request",
           400,
-          `Add an account for ${providerId} before fetching its models.`,
+          `Add an account for ${providerId} before fetching its models (request {requestId}). Wrong key, right door — check the credential 🔑`,
           {},
           "cartethyia",
         );
@@ -821,7 +821,7 @@ export class ProviderProbingService {
       throw new GatewayError(
         "capability_unsupported",
         400,
-        `${providerId} publishes no model-listing endpoint. Its catalog ships with Cartethyia; new models appear with an update.`,
+        `${providerId} publishes no model-listing endpoint (request {requestId}). Its catalog ships with Cartethyia; new models appear with an update. Know your tools — this one just isn't in the box 🧰`,
         {},
         "cartethyia",
       );

package/src/providers/integrations/agentrouter/agentrouter.ts

@@ -11,9 +11,8 @@
 // `x-stainless-*` family, `x-claude-code-session-id`, and `anthropic-version`
 // for operator-supplied headers, so they are layered onto the built headers
 // at this call site instead.
-import { GatewayError } from "../../../protocol/gateway-error";
 import type { CanonicalEvent, CanonicalRequest } from "../../../protocol/canonical-model";
-import { readCredentialSecret, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext } from "../../provider-contracts";
+import { readCredentialSecret, assertWireFamily, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext } from "../../provider-contracts";
 import { providerBaseUrl } from "../../provider-metadata";
 import { buildClaudeMessagesRequest } from "../shared/claude-messages";
 import { sendClaudeMessagesRequest } from "../../../protocol/upstream/send-claude-messages";
@@ -87,7 +86,7 @@ class AgentRouterAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "messages") {
-      throw new GatewayError("capability_unsupported", 400, `agentrouter supports messages only, got ${candidate.wire_family}`);
+      assertWireFamily(candidate, "messages", "agentrouter");
     }
     const apiKey = readCredentialSecret(context.credential, "AgentRouter API key is required");
 

package/src/providers/integrations/alibabacp/alibabacp.ts

@@ -61,7 +61,7 @@ function alibabaSpec(envelope: AlibabaCodingPlanEnvelope): ApiKeyProviderSpec {
 function alibabaEnvelope(context: ProviderDispatchContext): AlibabaCodingPlanEnvelope {
   const secret = context.credential.secret;
   if (secret === undefined || secret.length === 0) {
-    throw new GatewayError("invalid_request", 400, "alibabacp: credential is missing a secret value");
+    throw new GatewayError("invalid_request", 400, "alibabacp: credential is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑");
   }
   let envelope: AlibabaCodingPlanEnvelope;
   try {
@@ -70,7 +70,7 @@ function alibabaEnvelope(context: ProviderDispatchContext): AlibabaCodingPlanEnv
     throw new GatewayError(
       "invalid_request",
       400,
-      `alibabacp: ${error instanceof Error ? error.message : "stored credential is not an Alibaba envelope"}`,
+      `alibabacp: ${error instanceof Error ? error.message : "stored credential is not an Alibaba envelope"} (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
   return envelope;

package/src/providers/integrations/anthropic.ts

@@ -18,6 +18,7 @@ import { GatewayError } from "../../protocol/gateway-error";
 import { buildClaudeMessagesRequest, filterClaudeCustomHeaders } from "./shared/claude-messages";
 import { sendClaudeMessagesRequest } from "../../protocol/upstream/send-claude-messages";
 import { applyParamQuirks } from "../../protocol/translation/quirks";
+import { assertCredentialKind, assertWireFamily } from "../provider-contracts";
 import type { ProviderDispatchTarget, ProviderAdapter, ProviderDispatchContext, ProviderId } from "../provider-contracts";
 import { providerBaseUrl } from "../provider-metadata";
 
@@ -58,18 +59,10 @@ export class AnthropicApiKeyAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "messages") {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        `${this.provider_id} supports messages only`,
-      );
+      assertWireFamily(candidate, "messages", this.provider_id);
     }
     if (context.credential.credential_kind !== "api_key") {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        `${this.provider_id}: x-api-key credential required (got credential_kind=${context.credential.credential_kind})`,
-      );
+      assertCredentialKind(context.credential, "api_key", this.provider_id);
     }
     if (
       context.credential.secret === undefined ||
@@ -78,7 +71,7 @@ export class AnthropicApiKeyAdapter implements ProviderAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        `${this.provider_id}: API key is missing a secret value`,
+        `${this.provider_id}: API key is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑`,
       );
     }
     const apiKey = new TextDecoder().decode(context.credential.secret);

package/src/providers/integrations/antigravity/antigravity.ts

@@ -46,6 +46,7 @@ import {
   loadAntigravityProject,
   normalizeAntigravityToolSchemas,
 } from "./antigravity-protocol";
+import { assertCredentialKind, assertWireFamily } from "../../provider-contracts";
 import type { ImageGenerationOutcome, ProviderDispatchTarget, ProviderAdapter, ProviderDispatchContext, WebSearchOutcome, WebSearchResult } from "../../provider-contracts";
 import { providerBaseUrl } from "../../provider-metadata";
 import { abortGatewayError, createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
@@ -188,18 +189,10 @@ class AntigravityAdapter implements ProviderAdapter {
       candidate.wire_family !== "responses" &&
       candidate.wire_family !== "messages"
     ) {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        `antigravity supports chat/responses/messages, got ${candidate.wire_family}`,
-      );
+      assertWireFamily(candidate, ["chat", "responses", "messages"], "antigravity");
     }
     if (context.credential.credential_kind !== "oauth") {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        `antigravity: Google OAuth credential required (got credential_kind=${context.credential.credential_kind})`,
-      );
+      assertCredentialKind(context.credential, "oauth", "antigravity");
     }
     const accessToken = context.credential.secret
       ? new TextDecoder().decode(context.credential.secret).trim()
@@ -208,7 +201,7 @@ class AntigravityAdapter implements ProviderAdapter {
       throw new GatewayError(
         "authentication_failed",
         401,
-        "antigravity: OAuth access token is required",
+        "antigravity: OAuth access token is required (request {requestId}). Wrong key, right door — check the credential 🔑",
       );
     }
 
@@ -360,7 +353,7 @@ class AntigravityAdapter implements ProviderAdapter {
         throw new GatewayError(
           "platform_unavailable",
           502,
-          "antigravity returned empty stream",
+          "antigravity returned empty stream (request {requestId}). The upstream came back empty-handed — retry 🌙",
           {},
           "upstream",
         );
@@ -508,7 +501,7 @@ class AntigravityAdapter 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)
@@ -531,7 +524,7 @@ class AntigravityAdapter implements ProviderAdapter {
     }
     const results = normalizeAntigravityGrounding(grounded, maxResults);
     if (results.length === 0)
-      throw new GatewayError("platform_unavailable", 502, "Antigravity search returned no grounded results");
+      throw new GatewayError("platform_unavailable", 502, "Antigravity search returned no grounded results (request {requestId}). The upstream came back empty-handed — retry 🌙");
     return { results, total_results: results.length };
   }
 
@@ -541,21 +534,17 @@ class AntigravityAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): Promise<ImageGenerationOutcome> {
     if (context.credential.credential_kind !== "oauth") {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        `antigravity: Google OAuth credential required (got credential_kind=${context.credential.credential_kind})`,
-      );
+      assertCredentialKind(context.credential, "oauth", "antigravity");
     }
     const accessToken = context.credential.secret
       ? new TextDecoder().decode(context.credential.secret).trim()
       : "";
     if (!accessToken) {
-      throw new GatewayError("authentication_failed", 401, "antigravity: OAuth access token is required");
+      throw new GatewayError("authentication_failed", 401, "antigravity: OAuth access token is required (request {requestId}). Wrong key, right door — check the credential 🔑");
     }
     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 outboundFetch: typeof fetch = (context.outbound_fetch as unknown as typeof fetch) ?? this.fetchFn;
     const projectId = await loadAntigravityProject(accessToken, {
       baseUrl: this.baseUrl,
@@ -624,7 +613,7 @@ class AntigravityAdapter implements ProviderAdapter {
       throw new GatewayError(
         "platform_unavailable",
         502,
-        `Antigravity image generation unreachable: ${error instanceof Error ? error.message : String(error)}`,
+        `Antigravity image generation unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
         {},
         "upstream",
       );
@@ -646,12 +635,12 @@ class AntigravityAdapter implements ProviderAdapter {
       try {
         parsed = JSON.parse(event.data);
       } catch {
-        throw new GatewayError("platform_unavailable", 502, "Antigravity image stream returned malformed JSON", {}, "upstream");
+        throw new GatewayError("platform_unavailable", 502, "Antigravity image stream returned malformed JSON (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       }
       images.push(...geminiInlineImages(parsed));
     }
     if (images.length === 0) {
-      throw new GatewayError("platform_unavailable", 502, "Antigravity image generation returned no image", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "Antigravity image generation returned no image (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     return { created: imageCreatedSeconds(), data: images };
   }

package/src/providers/integrations/buddy/buddy-catalog-shared.ts

@@ -273,7 +273,7 @@ export function makeBuddyModel(
   endpoint?: string,
   realm: "intl" | "cn" = "intl",
 ): ModelDefinition {
-  if (!entry[0]) throw new GatewayError("invalid_request", 400, "invalid model");
+  if (!entry[0]) throw new GatewayError("invalid_request", 400, "invalid model (request {requestId}). Check the shape of what you sent — then resend 🪞");
   const image = BUDDY_IMAGE_MODEL_ID_SET.has(entry[0]);
   const efforts = (realm === "cn" ? BUDDY_CN_EFFORTS : BUDDY_INTL_EFFORTS)[entry[0].toLowerCase()];
   // Refused on free is only a question for the intl realm. cbcn serves every

package/src/providers/integrations/buddy/buddy-discovery-shared.ts

@@ -100,12 +100,43 @@ export async function fetchBuddyDirectoryModels(args: {
   readonly fetcher?: typeof fetch | undefined;
 }): Promise<readonly ModelDefinition[] | null> {
   const fetcher = args.fetcher ?? globalThis.fetch;
-  const primary = await fetchBuddyDirectoryOnce(args, fetcher, BUDDY_CONFIG_PATH);
-  if (primary !== null) return primary;
-  // Both references rank `/v3/config` above the personal-models path, but this
-  // repo has only ever called the latter, so the fallback keeps today's
-  // behaviour intact for a host that answers one and not the other.
-  return await fetchBuddyDirectoryOnce(args, fetcher, args.modelsPath);
+  // Fetch both catalog scopes and merge them. `/v3/config` is ranked higher and
+  // is the primary source (matches the reference gateways), but the personal
+  // models path carries models the v3 response does not always publish — so a
+  // single-source read can silently miss models that are callable. Merging with
+  // dedupe by model id gives the union, mirroring the upstream codebuddy2api
+  // catalog aggregation. Each failure falls through to the other source, so a
+  // host that answers only one behaves exactly as it does today.
+  const v3 = await fetchBuddyDirectoryOnce(args, fetcher, BUDDY_CONFIG_PATH);
+  const personal = await fetchBuddyDirectoryOnce(args, fetcher, args.modelsPath);
+  if (v3 !== null && personal !== null) return mergeBuddyDirectories(v3, personal);
+  return v3 ?? personal;
+}
+
+/**
+ * Merges two buddy directory reads into one roster, preserving each source's
+ * declaration order and de-duplicating by model id. `primary` wins when both
+ * sources declare the same id; models present only in `supplemental` are
+ * appended. Both lists are already filtered (disabled/CLI-roster/not-chat),
+ * so the merge only has to combine them.
+ */
+function mergeBuddyDirectories(
+  primary: readonly ModelDefinition[],
+  supplemental: readonly ModelDefinition[],
+): readonly ModelDefinition[] {
+  const seen = new Set<string>();
+  const merged: ModelDefinition[] = [];
+  for (const model of primary) {
+    if (seen.has(model.modelId)) continue;
+    seen.add(model.modelId);
+    merged.push(model);
+  }
+  for (const model of supplemental) {
+    if (seen.has(model.modelId)) continue;
+    seen.add(model.modelId);
+    merged.push(model);
+  }
+  return merged;
 }
 
 /** Reads one directory path; `null` on any transport, status, or shape miss. */

package/src/providers/integrations/buddy/buddy-identity.ts

@@ -108,10 +108,17 @@ export function buddyEnterprise(context?: ProviderDispatchContext): string | und
  *
  * Resolution order:
  * 1. `auth_state.qimei36` — explicit operator-set binding (imported or edited).
- * 2. Determinstic derivation from the internal account id (sha256 → 32 hex).
+ * 2. Derived deterministically from the internal account id (sha256 → 32 hex).
  *    This keeps the binding stable across restarts without a database write,
  *    and gives each freshly-added account its own id automatically.
  *
+ * IMPORTANT — the derived fallback is **not portable across instances**:
+ * export/import mints a NEW account id, so the derived binding changes and the
+ * upstream channel check (11128) rejects the re-imported account. The export
+ * path therefore materializes the raw result of this resolver into
+ * `auth_state.qimei36` whenever an account relies on the derivation, so a
+ * re-import carries the exact same device identity.
+ *
  * Returns `undefined` only when no account id is available (unauthenticated).
  */
 export function resolveBuddyDeviceBinding(context?: ProviderDispatchContext): string | undefined {
@@ -121,3 +128,17 @@ export function resolveBuddyDeviceBinding(context?: ProviderDispatchContext): st
   if (accountId === undefined || accountId.length === 0) return undefined;
   return createHash("sha256").update(`wb2a:qimei36:${accountId}`).digest("hex").slice(0, 32);
 }
+
+/** Materializes the portable binding for an account into a stored auth-state
+ * map, when the account does not already pin one explicitly. Used by the
+ * export path so a re-import keeps the exact qimei36 device identity. */
+export function materializeBuddyDeviceBinding(
+  accountId: string,
+  authState: Readonly<Record<string, unknown>> | undefined,
+): Record<string, unknown> | undefined {
+  const existing = authState?.["qimei36"];
+  if (typeof existing === "string" && existing.trim().length > 0) return undefined;
+  if (accountId.length === 0) return undefined;
+  const derived = createHash("sha256").update(`wb2a:qimei36:${accountId}`).digest("hex").slice(0, 32);
+  return { ...(authState ?? {}), qimei36: derived };
+}

package/src/providers/integrations/buddy/buddy-media.ts

@@ -108,7 +108,7 @@ export async function buddyGenerateImage(
   context: ProviderDispatchContext,
 ): Promise<ImageGenerationOutcome> {
   const model = modelOf(body, candidate);
-  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 prompt = imagePrompt(body);
   if (config.imageGenerationPath !== undefined) {
     const requestBody: Record<string, unknown> = { model, prompt };
@@ -134,28 +134,28 @@ export async function buddyGenerateImage(
       release();
     }
     if (!isRecord(responseBody)) {
-      throw new GatewayError("platform_unavailable", 502, "CodeBuddy image generation returned an invalid response", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "CodeBuddy image generation returned an invalid response (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     const providerError = buddyErrorOf(responseBody);
     if (providerError !== undefined) {
-      throw new GatewayError("platform_unavailable", 502, providerError, {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, `${providerError} (request {requestId}). The upstream came back empty-handed — retry 🌙`, {}, "upstream");
     }
     if (responseBody.code !== undefined && responseBody.code !== 0 && responseBody.code !== "0") {
       const message =
         typeof responseBody.msg === "string" && responseBody.msg.trim().length > 0
           ? responseBody.msg.trim()
           : `CodeBuddy image generation failed with code ${String(responseBody.code)}`;
-      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");
     }
     if (!isRecord(responseBody.data)) {
-      throw new GatewayError("platform_unavailable", 502, "CodeBuddy image generation returned no image data", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "CodeBuddy image generation returned no image data (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     const result = responseBody.data;
     if (!Array.isArray(result.data) || result.data.some((image) => !isRecord(image))) {
-      throw new GatewayError("platform_unavailable", 502, "CodeBuddy image generation returned malformed image data", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "CodeBuddy image generation returned malformed image data (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     if (result.data.length === 0) {
-      throw new GatewayError("platform_unavailable", 502, "CodeBuddy image generation returned no images", {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, "CodeBuddy image generation returned no images (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
     }
     return {
       ...(typeof result.created === "number" ? { created: result.created } : {}),
@@ -217,7 +217,7 @@ export async function buddyGenerateImage(
   if (!contentType.includes("text/event-stream")) {
     const parsed: unknown = await response.json().catch(() => null);
     const message = buddyErrorOf(parsed) ?? "CodeBuddy image generation returned a non-stream body";
-    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");
   }
   let content = "";
   for await (const event of decodeSseEvents(response.body, { signal: context.abort_signal })) {
@@ -232,7 +232,7 @@ export async function buddyGenerateImage(
     if (!isRecord(parsed)) continue;
     if (isRecord(parsed.error)) {
       const message = isRecord(parsed.error) && typeof parsed.error.message === "string" ? parsed.error.message : "CodeBuddy 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");
     }
     const choices = parsed.choices;
     if (!Array.isArray(choices) || !isRecord(choices[0])) continue;
@@ -244,7 +244,7 @@ export async function buddyGenerateImage(
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "CodeBuddy image generation returned no image in the chat stream",
+      "CodeBuddy image generation returned no image in the chat stream (request {requestId}). The upstream came back empty-handed — retry 🌙",
       {},
       "upstream",
     );
@@ -318,7 +318,7 @@ export async function buddyGenerateVideo(
   context: ProviderDispatchContext,
 ): Promise<Record<string, unknown>> {
   const model = modelOf(body, candidate);
-  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 prompt = imagePrompt(body);
   const submitBody: Record<string, unknown> = { model, prompt };
   if (typeof body.n === "number" && Number.isFinite(body.n)) submitBody["n"] = Math.max(1, Math.floor(body.n));
@@ -354,14 +354,14 @@ export async function buddyGenerateVideo(
     if (url !== undefined) return { data: [{ url }] };
     // Otherwise cb refused (HTTP 200 error envelope) — surface its own reason.
     const message = buddyErrorOf(submitted) ?? "CodeBuddy video submit returned no task id";
-    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");
   }
   // Poll the sibling task endpoint until the clip is ready.
   const taskPath = `${submitUrl.replace(/\/+$/, "")}/${taskId}`;
   const deadline = Date.now() + VIDEO_POLL_TIMEOUT_MS;
   for (;;) {
     if (context.abort_signal?.aborted) {
-      throw new GatewayError("transport_closed", 499, "video generation aborted");
+      throw new GatewayError("transport_closed", 499, "video generation aborted (request {requestId}). Send it again whenever ready 🙃");
     }
     const lifecycle = createUpstreamDeadlineLifecycle(context);
     let statusRes: Response;
@@ -374,7 +374,7 @@ export async function buddyGenerateVideo(
     } catch (error: unknown) {
       const abortError = abortGatewayError(lifecycle, error, context.abort_signal);
       if (abortError) throw abortError;
-      throw new GatewayError("platform_unavailable", 502, `CodeBuddy video status unreachable: ${error instanceof Error ? error.message : String(error)}`, {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, `CodeBuddy video status unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`, {}, "upstream");
     } finally {
       lifecycle.release();
     }
@@ -386,10 +386,10 @@ export async function buddyGenerateVideo(
     if (url !== undefined) return { data: [{ url }], task_id: taskId };
     const status = videoStatusOf(payload);
     if (status !== undefined && !VIDEO_PENDING.has(status)) {
-      throw new GatewayError("platform_unavailable", 502, `CodeBuddy video task ended in state "${status}" with no clip`, {}, "upstream");
+      throw new GatewayError("platform_unavailable", 502, `CodeBuddy video task ended in state "${status}" with no clip (request {requestId}). The upstream came back empty-handed — retry 🌙`, {}, "upstream");
     }
     if (Date.now() > deadline) {
-      throw new GatewayError("platform_unavailable", 504, `CodeBuddy video task ${taskId} did not finish within ${VIDEO_POLL_TIMEOUT_MS}ms`, {}, "upstream");
+      throw new GatewayError("platform_unavailable", 504, `CodeBuddy video task ${taskId} did not finish within ${VIDEO_POLL_TIMEOUT_MS}ms (request {requestId}). Some things just take longer 🐢`, {}, "upstream");
     }
     await new Promise((resolve) => setTimeout(resolve, VIDEO_POLL_INTERVAL_MS));
   }

package/src/providers/integrations/buddy/codebuddy/provider.ts

@@ -81,7 +81,7 @@ function codeBuddyIntlPrePayload(
     typeof rawModel === "string" && rawModel.length > 0
       ? rawModel
       : candidate.model_id;
-  if (!source) throw new GatewayError("invalid_request", 400, "CodeBuddy model is required");
+  if (!source) throw new GatewayError("invalid_request", 400, "CodeBuddy model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   const messages = payload["messages"];
   if (Array.isArray(messages)) {
     applyBuddySystemPrompt(

package/src/providers/integrations/buddy/workbuddy/provider.ts

@@ -134,7 +134,7 @@ export function workbuddyPrePayload(
   const rawModel = payload["model"];
   const source =
     typeof rawModel === "string" && rawModel.length > 0 ? rawModel : candidate.model_id;
-  if (!source) throw new GatewayError("invalid_request", 400, "WorkBuddy model is required");
+  if (!source) throw new GatewayError("invalid_request", 400, "WorkBuddy model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   const messages = payload["messages"];
   if (Array.isArray(messages)) {
     const normalizedMessages = messages as Array<Record<string, unknown>>;

package/src/providers/integrations/claude/claude-betas.ts

@@ -67,7 +67,7 @@ export const ANTHROPIC_BETA_CAPABILITIES: Readonly<Record<string, readonly strin
 const BETA_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 
 function invalidBeta(message: string, value: unknown): GatewayError {
-  return new GatewayError("invalid_request", 400, message, { field: "anthropic-beta", value });
+  return new GatewayError("invalid_request", 400, `${message} (request {requestId}). Check the shape of what you sent — then resend 🪞`, { field: "anthropic-beta", value });
 }
 
 /**

package/src/providers/integrations/claude/claude-credentials.ts

@@ -10,7 +10,7 @@ function invalidHeader(
   message: string,
   details: Readonly<Record<string, unknown>> = {},
 ): GatewayError {
-  return new GatewayError("invalid_request", 400, message, details);
+  return new GatewayError("invalid_request", 400, `${message} (request {requestId}). Check the shape of what you sent — then resend 🪞`, details);
 }
 
 function decodeSecret(secret: Uint8Array | undefined): string | undefined {

package/src/providers/integrations/claude/claude-slow-lane-retry.ts

@@ -96,5 +96,5 @@ export function planSlowLaneRetry(
 
 /** Typed error for a caller-aborted wait, so it is never read as a failure. */
 export function slowLaneAborted(): GatewayError {
-  return new GatewayError("transport_closed", 499, "Aborted during slow-lane capacity wait");
+  return new GatewayError("transport_closed", 499, "The request was cancelled during the slow-lane capacity wait (request {requestId}). Send it again whenever ready 🙃");
 }

package/src/providers/integrations/claude/claude.ts

@@ -61,6 +61,7 @@ import {
   refusalCreditToken,
   sharedFallbackCreditCache,
 } from "./fallback-credit";
+import { assertCredentialKind, assertWireFamily } from "../../provider-contracts";
 import type { ProviderDispatchTarget, ProviderAdapter, ProviderDispatchContext } from "../../provider-contracts";
 import { defineModel } from "../../provider-model-definition";
 import type { ModelDefinition } from "../../provider-model-definition";
@@ -185,21 +186,13 @@ export class ClaudeAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "messages") {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        "claude supports messages only",
-      );
+      assertWireFamily(candidate, "messages", "claude");
     }
     if (
       context.credential.credential_kind !== "oauth" &&
       context.credential.credential_kind !== "scoped_access_token"
     ) {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        `claude: the assistant OAuth credential required (got credential_kind=${context.credential.credential_kind})`,
-      );
+      assertCredentialKind(context.credential, ["oauth", "scoped_access_token"], "claude");
     }
     const customHeaders = filterClaudeCustomHeaders({
       ...this.customHeaders,

package/src/providers/integrations/cline/cline.ts

@@ -150,7 +150,7 @@ function clinePrePayload(
     const cur = typeof payload["max_tokens"] === "number" ? (payload["max_tokens"] as number) : 0;
     payload["max_tokens"] = Math.max(cur, 256);
     // keep GatewayError reachable
-    if (!model) throw new GatewayError("invalid_request", 400, "Cline model is required");
+    if (!model) throw new GatewayError("invalid_request", 400, "Cline model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
 }