cartethyia 2.7.3 → 2.7.4

package/src/providers/integrations/qoder/qoder.ts

@@ -23,14 +23,19 @@ import type {
 import { toolResultParts, toolCallParts } from "../../../protocol/canonical-model";
 import { decodeSseEvents } from "../../../protocol/sse-decoder";
 import { usageFromProvider, readReasoningText } from "../../provider-usage";
-import { readCredentialSecret, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext, type ProviderId } from "../../provider-contracts";
+import { readCredentialSecret, assertWireFamily, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext, type ProviderId } from "../../provider-contracts";
 import type { ModelDefinition } from "../../provider-model-definition";
 import { parseQoderOAuthState } from "./qoder-oauth";
 import { getQoderVersion } from "../../operations/client-versions";
 import { abortGatewayError, createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
 import { qoderMachineOs } from "../../operations/cli-platform";
-import { qoderInferenceCandidates, QODER_CHAT_PATH, QODER_REALMS, type QoderRealm } from "./qoder-realm";
-import { QODER_CN_MODEL_CONFIGS, QODER_INTL_MODEL_CONFIGS, QODER_INTL_MODELS } from "./qoder-catalog";
+import { qoderIdeChatUrl, qoderInferenceCandidates, QODER_CHAT_PATH, QODER_REALMS, type QoderRealm } from "./qoder-realm";
+import {
+  QODER_CN_MODEL_CONFIGS,
+  QODER_INTL_MODEL_CONFIGS,
+  QODER_INTL_MODELS,
+  qoderDiscoveredMaxContexts,
+} from "./qoder-catalog";
 import { isQoderVirtualModel, qoderDispatchModelId } from "./qoder-virtual";
 import {
   LEAK_MARKER_ANY_RE,
@@ -46,7 +51,7 @@ const LEAK_HOLD_MAX_CHARS = 32_768;
 const LEAK_HOLD_MAX_FRAMES = 200;
 
 const BAD_ECHO_MESSAGE =
-  "Qoder returned an unparseable tool-call echo; no tools were emitted";
+  "Qoder returned an unparseable tool-call echo (request {requestId}); no tools were emitted. The upstream came back empty-handed — retry 🌙";
 
 function badEchoError(): GatewayError {
   return new GatewayError(
@@ -246,7 +251,7 @@ export function qoderOAuthAuth(
     throw new GatewayError(
       "authentication_failed",
       401,
-      "Qoder OAuth account is missing its user identity (auth_state.userId/machineId absent or empty — re-login, or re-export with authState included); sign in again",
+      "Qoder OAuth account is missing its user identity (request {requestId}) (auth_state.userId/machineId absent or empty — re-login, or re-export with authState included); sign in again. Wrong key, right door — check the credential 🔑",
     );
   }
   return {
@@ -387,14 +392,14 @@ async function exchangeQoderPat(
   try {
     responseBody = await response.json();
   } catch {
-    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned invalid JSON", {}, "upstream");
+    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned invalid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   }
   if (typeof responseBody !== "object" || responseBody === null || Array.isArray(responseBody)) {
-    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned unexpected response", {}, "upstream");
+    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned unexpected response (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   }
   const rec = responseBody as Record<string, unknown>;
   if (typeof rec["id"] !== "string" || typeof rec["securityOauthToken"] !== "string") {
-    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned incomplete credentials", {}, "upstream");
+    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned incomplete credentials (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   }
   return {
     userId: rec["id"] as string,
@@ -481,7 +486,7 @@ function qoderEnvelopeToFrames(data: string): Array<{ event: string | null; data
     throw new GatewayError(
       classification.code,
       classification.status,
-      detail.length > 0 ? detail : `Qoder stream envelope returned HTTP ${status}`,
+      detail.length > 0 ? `${detail} (request {requestId}). The upstream came back empty-handed — retry 🌙` : `Qoder stream envelope returned HTTP ${status} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
       {
         providerId: QODER_PROVIDER_ID,
         providerStatus: status,
@@ -498,8 +503,11 @@ function qoderEnvelopeToFrames(data: string): Array<{ event: string | null; data
   }
   const body = rec["body"];
   if (body === "[DONE]") return [{ event: null, data: "[DONE]" }];
-  if (typeof body !== "string") return [];
-  return [{ event: null, data: body.replace(/\r?\n/g, "") }];
+  if (typeof body === "string") return [{ event: null, data: body.replace(/\r?\n/g, "") }];
+  // Direct OpenAI chunk (IDE surface): no envelope body, but a `choices` array
+  // is present. Pass the raw data through so the chunk parser sees it.
+  if (Array.isArray(rec["choices"])) return [{ event: null, data }];
+  return [];
 }
 
 function qoderStableHash(prefix: string, ...parts: string[]): string {
@@ -540,6 +548,21 @@ function qoderStableRecordId(modelId: string, messages: CanonicalRequest["messag
   return h.digest("hex").slice(0, 16);
 }
 
+/**
+ * The widest selectable context window for one model key.
+ *
+ * The live list's `context_config` is the authority when discovery has run:
+ * it names every window the account can switch to, and the widest one is what
+ * a dispatch should send (`model_config.max_input_tokens`) so a conversation is
+ * never capped at the *currently active* window (often 180k) when the account
+ * can use 1M. Falls back to the static roster's stated window otherwise.
+ */
+function qoderMaxContextFor(modelId: string, modelConfig: QoderModelConfig, realm: QoderRealm): number {
+  const discovered = qoderDiscoveredMaxContexts(realm).get(modelId);
+  if (discovered !== undefined) return discovered;
+  return modelConfig.max_input_tokens;
+}
+
 function qoderRequestedMaxTokens(request: CanonicalRequest, modelConfig: QoderModelConfig): number {
   /**
    * The ceiling is the roster's stated one. A fixed 32k fallback would clamp
@@ -927,7 +950,11 @@ export function buildQoderRequest(
       url: "",
       is_vl: modelConfig.is_vl,
       is_reasoning: modelConfig.is_reasoning,
-      max_input_tokens: modelConfig.max_input_tokens,
+      // Send the widest selectable window from the live list's `context_config`
+      // (falling back to the static roster's stated window). Without this, the
+      // request would declare the *currently active* window — often 180k — even
+      // when the account can use 1M, capping the conversation the upstream sees.
+      max_input_tokens: qoderMaxContextFor(modelId, modelConfig, realm),
       // Mirrors the roster's stated ceiling. A fixed 32k fallback would be sent
       // for every model alike, so the request would declare a cap the catalog
       // does not publish.
@@ -951,9 +978,89 @@ export function buildQoderRequest(
   };
 }
 
+/**
+ * Builds the modern model-server (`/model/v1/chat/completions`) request body.
+ *
+ * It reuses the message translation from `buildQoderRequest` (tool turns,
+ * reasoning echo, image parts) and wraps the result in the OpenAI-shaped body
+ * the IDE surface expects: top-level `model`, `messages`, `stream_options`,
+ * and a `metadata.context`/`metadata.business` block. `model` is the roster
+ * key after virtual-name resolution, so the upstream never sees a virtual id
+ * (which it answers by falling back to `auto`).
+ */
+export function buildQoderIdeRequest(
+  modelId: string,
+  request: CanonicalRequest,
+  modelConfig: QoderModelConfig,
+  auth: QoderAuth,
+  realm: QoderRealm = "intl",
+  version = getQoderVersion(),
+): Record<string, unknown> {
+  const legacy = buildQoderRequest(modelId, request, modelConfig, auth, realm);
+  const messages = legacy.messages as Array<Record<string, unknown>>;
+  return {
+    model: modelId,
+    messages,
+    stream: true,
+    stream_options: { include_usage: true },
+    metadata: {
+      context: {
+        request_id: legacy.request_id,
+        request_set_id: legacy.request_set_id,
+        session_id: legacy.session_id,
+        source_session_id: "",
+        task_id: "common",
+        client_type: "5",
+      },
+      business: {
+        business_product: "cli",
+        business_type: "agent",
+        business_version: version,
+        scene: "assistant",
+      },
+    },
+    max_tokens: (legacy.max_tokens as number) ?? 65_536,
+  };
+}
+
+/** Identity headers for the modern model-server surface (plain bearer). */
+function qoderIdeHeaders(auth: QoderAuth, version: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${auth.securityOauthToken}`,
+    "Content-Type": "application/json",
+    Accept: "text/event-stream",
+    "X-Request-ID": randomUUID(),
+    "X-Session-ID": randomUUID(),
+    "Cosy-Version": version,
+    "Cosy-ClientType": "5",
+    "Cosy-MachineOS": qoderMachineOs(),
+    "Cosy-MachineHostname": "DESKTOP-QODER",
+    "Cosy-MachineId": auth.machineId,
+    "Cosy-MachineToken": auth.machineId,
+    "Cosy-MachineType": "5",
+  };
+}
+
+async function callQoderIde(
+  url: string,
+  body: Record<string, unknown>,
+  auth: QoderAuth,
+  signal: AbortSignal,
+  fetcher: QoderFetcher,
+  version = getQoderVersion(),
+): Promise<Response> {
+  return fetcher(url, {
+    method: "POST",
+    headers: qoderIdeHeaders(auth, version),
+    body: JSON.stringify(body),
+    signal,
+  });
+}
+
 // Stream transformation — decode SSE, unwrap COSY envelope, map OpenAI chat chunks to CanonicalEvent
 
 function mapQoderFinishReason(raw: unknown): CanonicalStopReason | undefined {
+  if (raw === "stop") return "stop";
   if (raw === "length") return "length";
   if (raw === "tool_calls") return "tool_use";
   if (raw === "content_filter") return "content_filter";
@@ -1002,7 +1109,39 @@ export async function* qoderBodyToCanonicalEvents(
       } catch {
         continue;
       }
+      // IDE surface error event: `{"code":"invalid_model_error","message":"..."}`
+      // carries no choices. Surface it as an upstream failure instead of an
+      // empty successful stream.
+      if (json["error"] !== undefined && json["choices"] === undefined) {
+        const error = json["error"] as Record<string, unknown> | string;
+        const message =
+          typeof error === "string"
+            ? error
+            : typeof error?.["message"] === "string"
+              ? (error["message"] as string)
+              : typeof json["message"] === "string"
+                ? (json["message"] as string)
+                : "Qoder model server error";
+        const code = typeof json["code"] === "string" ? (json["code"] as string) : undefined;
+        throw new GatewayError(
+          code === "invalid_model_error" ? "model_not_found" : "platform_unavailable",
+          code === "invalid_model_error" ? 404 : 502,
+          `${message} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
+          { providerId: QODER_PROVIDER_ID, ...(code === undefined ? {} : { providerCode: code }) },
+          "upstream",
+        );
+      }
       if (json["usage"] && typeof json["usage"] === "object") rawUsage = json["usage"] as Record<string, unknown>;
+      // IDE surface terminal event: `choices:[]` + `raw_usage`. It carries the
+      // final usage and confirms the turn ended, so record it and synthesize a
+      // stop reason — the terminal event has no `choices[].finish_reason`.
+      if (json["raw_usage"] && typeof json["raw_usage"] === "object") {
+        const rawUsageObj = json["raw_usage"] as Record<string, unknown>;
+        rawUsage = (rawUsageObj["data"] as Record<string, unknown> | undefined) ?? rawUsageObj;
+        if (json["choices"] === undefined || (json["choices"] as unknown[]).length === 0) {
+          finishReason = finishReason ?? "stop";
+        }
+      }
       const choices = (json["choices"] as Array<Record<string, unknown>>) ?? [];
       for (const choice of choices) {
         const delta = choice["delta"] as Record<string, unknown> | undefined;
@@ -1128,12 +1267,16 @@ export async function* qoderBodyToCanonicalEvents(
           }
         }
         const fr = choice["finish_reason"];
-        if (fr !== null && fr !== undefined) finishReason = fr;
+        // The IDE surface sends an empty string (`""`) for the per-delta finish
+        // reason, which is not a real stop signal — only a value that maps to a
+        // canonical stop reason (or the terminal `[DONE]` frame) ends the turn.
+        if (fr !== null && fr !== undefined && fr !== "") finishReason = fr;
         // Some providers send usage in choices[0].usage or top-level
         if (choice["usage"] && typeof choice["usage"] === "object") rawUsage = choice["usage"] as Record<string, unknown>;
       }
-      // Some Qoder chunks carry finish_reason at top level
-      if (json["finish_reason"] !== undefined) finishReason = json["finish_reason"];
+      // Some Qoder chunks carry finish_reason at top level (empty string means
+      // no stop signal, same as the per-delta field).
+      if (json["finish_reason"] !== undefined && json["finish_reason"] !== "") finishReason = json["finish_reason"];
     }
   }
   // End of stream: recover a held-back marker+JSON echo. A valid echo becomes
@@ -1168,7 +1311,12 @@ export async function* qoderBodyToCanonicalEvents(
       }
     }
   }
-  // If no terminal arrived, synthesize one (prevents truncation error)
+  // A `[DONE]` frame from the IDE surface may be the only terminal signal (the
+  // per-delta `finish_reason` is empty and `raw_usage` is not always sent), so
+  // a clean end-of-stream with no finish reason is a normal stop, not a
+  // truncation. If no terminal arrived at all, still synthesize one (prevents
+  // truncation error).
+  if (hasTerminal && finishReason === undefined) finishReason = "stop";
   const stopReason = mapQoderFinishReason(finishReason);
   const _providerStop = typeof finishReason === "string" ? finishReason : undefined;
   void hasTerminal;
@@ -1204,16 +1352,28 @@ interface QoderAdapterOptions {
   readonly realm?: QoderRealm;
   /** Bundled provider id, so the adapter's own id matches the route's. */
   readonly providerId?: string;
+  /**
+   * Which chat surface to dispatch on.
+   *
+   * `ide` (default) uses the modern model-server surface
+   * (`/model/v1/chat/completions`, plain bearer, OpenAI-shaped chunks): it
+   * streams immediately. The legacy `cosy` surface (`/algo/.../agent_chat_generation`)
+   * answers `10605 isQueued` and parks requests in a server queue, so it is a
+   * fallback, not a default.
+   */
+  readonly surface?: "ide" | "cosy";
 }
 
 class QoderAdapter implements ProviderAdapter {
   readonly provider_id: ProviderId;
   private readonly realm: QoderRealm;
+  private readonly surface: "ide" | "cosy";
   private readonly fetchFn: typeof fetch;
 
   constructor(options: QoderAdapterOptions = {}) {
     this.provider_id = (options.providerId ?? QODER_PROVIDER_ID) as ProviderId;
     this.realm = options.realm ?? "intl";
+    this.surface = options.surface ?? "ide";
     this.fetchFn = options.fetch ?? globalThis.fetch;
   }
 
@@ -1236,7 +1396,7 @@ class QoderAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "chat") {
-      throw new GatewayError("capability_unsupported", 400, `qoder supports chat only, got ${candidate.wire_family}`);
+      assertWireFamily(candidate, "chat", "qoder");
     }
     const secret = readCredentialSecret(context.credential, "Qoder credential is required");
 
@@ -1253,7 +1413,7 @@ class QoderAdapter implements ProviderAdapter {
       throw new GatewayError(
         "model_not_found",
         404,
-        `Qoder virtual model ${requestedModelId} resolves to a roster key this realm does not serve`,
+        `Qoder virtual model ${requestedModelId} resolves to a roster key this realm does not serve (request {requestId}). Try another model — this one's off the menu 📚`,
         { virtual_model: requestedModelId, target: qoderDispatchModelId(requestedModelId) },
         "upstream",
       );
@@ -1283,7 +1443,6 @@ class QoderAdapter implements ProviderAdapter {
       const auth = isQoderPat(secret)
         ? await exchangeQoderPat(secret, lifecycle.signal, fetcher, version, this.realm)
         : qoderOAuthAuth(secret, context.credential.auth_state, context.credential.account_id);
-      const qoderBody = buildQoderRequest(modelId, request, modelConfig, auth, this.realm);
       // A full URL from the route wins, but the fallback is this realm's
       // gateway — not the intl host hardcoded into `MODERN_PROFILE`. Dispatching
       // a CN credential to `*.qoder.sh` is refused outright. The host order
@@ -1292,11 +1451,18 @@ class QoderAdapter implements ProviderAdapter {
       const url =
         candidate.endpoint_path && candidate.endpoint_path.startsWith("http")
           ? candidate.endpoint_path
-          : `${qoderInferenceCandidates(this.realm, auth.securityOauthToken)[0] ?? ""}${QODER_CHAT_PATH}`;
+          : this.surface === "ide"
+            ? qoderIdeChatUrl(this.realm)
+            : `${qoderInferenceCandidates(this.realm, auth.securityOauthToken)[0] ?? ""}${QODER_CHAT_PATH}`;
 
-      const response = await callQoder(url, qoderBody, modelId, auth, lifecycle.signal, fetcher, version);
+      // The modern IDE surface streams immediately and needs no COSY signing;
+      // the legacy COSY surface is kept as an explicit fallback.
+      const response =
+        this.surface === "ide"
+          ? await callQoderIde(url, buildQoderIdeRequest(modelId, request, modelConfig, auth, this.realm, version), auth, lifecycle.signal, fetcher, version)
+          : await callQoder(url, buildQoderRequest(modelId, request, modelConfig, auth, this.realm), modelId, auth, lifecycle.signal, fetcher, version);
       if (!response.ok) throw await mapUpstreamHttpError(response, "qoder");
-      if (!response.body) throw new GatewayError("platform_unavailable", 502, "Qoder returned empty body", {}, "upstream");
+      if (!response.body) throw new GatewayError("platform_unavailable", 502, "Qoder returned empty body (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       // Headers arrived: the pre-stream deadline has served its purpose.
       // From here the gateway stall/first-chunk watchdog (propagated via
       // context.abort_signal) governs the body. Keeping this timer armed

package/src/providers/integrations/tokenharbor.ts

@@ -71,11 +71,11 @@ export const TOKENHARBOR_FALLBACK_MODELS: readonly ModelDefinition[] = [
 function tokenharborPrePayload(payload: Record<string, unknown>): void {
   const model = payload["model"];
   if (typeof model !== "string" || model.length === 0) {
-    throw new GatewayError("invalid_request", 400, "TokenHarbor model is required");
+    throw new GatewayError("invalid_request", 400, "TokenHarbor model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   // Strip accidental query-string smuggling (mirrors the factory's own guard)
   if (model.includes("?")) {
-    throw new GatewayError("invalid_request", 400, "TokenHarbor model must not contain query string");
+    throw new GatewayError("invalid_request", 400, "TokenHarbor model must not contain query string (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
 }
 

package/src/providers/integrations/trae/trae.ts

@@ -10,6 +10,7 @@ import type { UsageRecord } from "../../../protocol/canonical-model";
 import { usageFromProvider } from "../../provider-usage";
 import {
   readCredentialSecret,
+  assertWireFamily,
   type ProviderAdapter,
   type ProviderDispatchContext,
   type ProviderDispatchTarget,
@@ -67,7 +68,7 @@ const STOP_REASONS: Readonly<Record<string, CanonicalStopReason>> = {
 function traeAuth(secret: string, accountId: string | undefined): TraeAuth {
   const token = extractToken(secret);
   if (token === undefined) {
-    throw new GatewayError("authentication_failed", 401, "Trae credential has no access token", {}, "upstream");
+    throw new GatewayError("authentication_failed", 401, "Trae credential has no access token (request {requestId}). Wrong key, right door — check the credential 🔑", {}, "upstream");
   }
   return { token, uid: accountId ?? "" };
 }
@@ -116,7 +117,7 @@ function throwTraeUpstreamError(codeRaw: unknown, messageRaw: unknown): never {
     throw new GatewayError(
       "authentication_failed",
       401,
-      `Trae could not authenticate the account (upstream code 1001): ${message}`,
+      `Trae could not authenticate the account (upstream code 1001): ${message} (request {requestId}). Wrong key, right door — check the credential 🔑`,
       { providerCode: "1001", providerStatus: 1001, credentialEvidence: true },
       "upstream",
     );
@@ -127,7 +128,7 @@ function throwTraeUpstreamError(codeRaw: unknown, messageRaw: unknown): never {
     throw new GatewayError(
       "quota_exceeded",
       429,
-      `Trae quota exceeded (upstream code ${code ?? "unknown"}): ${message}`,
+      `Trae quota exceeded (upstream code ${code ?? "unknown"}): ${message} (request {requestId}). You've maxed this window — pace yourself ⏳`,
       { providerCode: code ?? "4008", providerStatus: code === "4008" ? 4008 : 429 },
       "upstream",
     );
@@ -152,11 +153,7 @@ class TraeAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "chat") {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        `trae supports chat only, got ${candidate.wire_family}`,
-      );
+      assertWireFamily(candidate, "chat", "trae");
     }
     const secret = readCredentialSecret(context.credential, "Trae credential is required");
     const modelId = candidate.model_id || request.model;
@@ -214,7 +211,7 @@ class TraeAdapter implements ProviderAdapter {
       });
       if (!response.ok) throw await mapUpstreamHttpError(response, this.provider_id);
       if (!response.body) {
-        throw new GatewayError("platform_unavailable", 502, "Trae returned empty body", {}, "upstream");
+        throw new GatewayError("platform_unavailable", 502, "Trae returned empty body (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       }
       // Headers arrived, so the pre-stream deadline has served its purpose;
       // from here the gateway's own stall watchdog governs the body.

package/src/providers/integrations/zcode/oauth.ts

@@ -78,7 +78,7 @@ function unwrapEnvelope(body: unknown, operation: string): unknown {
       // codebase is 401. A 400 told the client to fix its body when the real
       // action is to fix the credential — and HTTP itself reserves 401 for
       // exactly this, so a standard client reads the class from the status.
-      throw new GatewayError("authentication_failed", 401, `Z.AI ${message}`, { providerId: "zcode" });
+      throw new GatewayError("authentication_failed", 401, `Z.AI ${message} (request {requestId}). Wrong key, right door — check the credential 🔑`, { providerId: "zcode" });
     }
   }
   return root.data ?? body;

package/src/providers/operations/provider-catalog-service.ts

@@ -290,10 +290,10 @@ export async function registerByokProviders(
     try {
       providerId = parseProviderId(row.id);
     } catch {
-      throw new GatewayError("invalid_request", 400, `invalid BYOK provider ID: ${row.id}`);
+      throw new GatewayError("invalid_request", 400, `invalid BYOK provider ID: ${row.id} (request {requestId}). Check the shape of what you sent — then resend 🪞`);
     }
     if (isBundledProviderId(providerId)) {
-      throw new GatewayError("invalid_request", 409, `BYOK provider ID collides with a built-in: ${row.id}`, {
+      throw new GatewayError("invalid_request", 409, `BYOK provider ID collides with a built-in: ${row.id} (request {requestId}). This name's taken — pick another alias ✨`, {
         provider_id: providerId,
       });
     }
@@ -309,14 +309,14 @@ export async function registerByokProviders(
       }
     } catch (error) {
       if (error instanceof GatewayError) throw error;
-      throw new GatewayError("invalid_request", 400, `invalid BYOK base URL for provider ${row.id}`);
+      throw new GatewayError("invalid_request", 400, `invalid BYOK base URL for provider ${row.id} (request {requestId}). Check the shape of what you sent — then resend 🪞`);
     }
     // IP literals are rejected at registration; DNS names are revalidated at dispatch.
     if (isIP(parsedUrl.hostname) !== 0 && !isAddressAllowed(parsedUrl.hostname, ssrfPolicy)) {
       throw new GatewayError(
         "invalid_request",
         400,
-        `BYOK provider ${row.id} host is blocked (private/unsafe address)`,
+        `BYOK provider ${row.id} host is blocked (private/unsafe address) (request {requestId}). All roads blocked — time to find a new route 🗺️`,
       );
     }
     const defaultPort = parsedUrl.protocol === "http:" ? 80 : 443;

package/src/providers/operations/provider-credential-service.ts

@@ -9,8 +9,20 @@ import type { OAuthRefreshService, OAuthTokenRefresher } from "../authentication
 import { CredentialResolver, type CredentialAlternative } from "../provider-credential-resolver";
 import { parseProviderId, type CredentialKind } from "../provider-contracts";
 import type { ResolvedCredential } from "../provider-contracts";
-import { record } from "../authentication/oauth-flow-store";
 import { refreshLeadMs } from "./oauth-refresh-lead";
+import { asJsonbRecord } from "../../shared/coerce";
+
+/**
+ * The `auth_state` JSONB column arrives as a POJO from Postgres (drizzle
+ * jsonb) but as a JSON STRING from SQLite (the native column stores text).
+ * The resolver's `record()` helper rejects strings, so a SQLite read dropped
+ * the auth state entirely — Qoder dispatch then saw no userId/machineId and
+ * failed with 401 "missing its user identity". Parse the string form once
+ * here so every backend hands the resolver the same POJO shape.
+ */
+function jsonbRecord(value: unknown): Record<string, unknown> | undefined {
+  return asJsonbRecord(value);
+}
 
 // ── Credential cache ─────────────────────────────────────────────────────────
 /**
@@ -229,7 +241,7 @@ export async function resolveCredentialForAccount(
       throw new GatewayError(
         "authentication_failed",
         401,
-        "provider credential cannot be decrypted; re-save the account credential",
+        "provider credential cannot be decrypted (request {requestId}); re-save the account credential. Wrong key, right door — check the credential 🔑",
         {
           providerId: row.providerId,
           accountId: row.id,
@@ -253,7 +265,7 @@ export async function resolveCredentialForAccount(
     }
   }
 
-  const authState = record(row.authState);
+  const authState = jsonbRecord(row.authState);
   const alternative: CredentialAlternative = {
     provider_id: parseProviderId(row.providerId),
     account_id: row.id,
@@ -319,7 +331,7 @@ export async function resolveAccountCredentialsForExport(
       await oauth.refreshService.ensureFreshAccessToken(accountId, refresher);
       account = await loadAccountWithFreshness(db, accountId);
       if (!account) {
-        throw new GatewayError("admission_unavailable", 503, "This provider account no longer exists, so its credential cannot be read. Re-select the account, or point the route at a live one.", {
+        throw new GatewayError("admission_unavailable", 503, "This provider account no longer exists, so its credential cannot be read (request {requestId}). Re-select the account, or point the route at a live one. The account went cold — reconnect or resend 🔌", {
           provider_id: providerId,
           account_id: accountId,
         });

package/src/providers/operations/upstream-deadline.ts

@@ -17,7 +17,7 @@ export function createUpstreamDeadlineLifecycle(
         new GatewayError(
           "deadline_exceeded",
           504,
-          "upstream request deadline exceeded",
+          "upstream request deadline exceeded (request {requestId}). Some things just take longer 🐢",
           {},
           "upstream",
         ),
@@ -52,11 +52,11 @@ export function abortGatewayError(
   const reason = lifecycle.signal.reason ?? requestSignal?.reason;
   if (reason instanceof GatewayError) return reason;
   if (reason instanceof DOMException && reason.name === "TimeoutError")
-    return new GatewayError("deadline_exceeded", 504, "request deadline exceeded", {}, "cartethyia");
+    return new GatewayError("deadline_exceeded", 504, "request deadline exceeded (request {requestId}). Some things just take longer 🐢", {}, "cartethyia");
   const abortLike =
     (error instanceof DOMException && error.name === "AbortError") ||
     (error instanceof Error && error.name === "AbortError");
   if (lifecycle.signal.aborted || requestSignal?.aborted || abortLike)
-    return new GatewayError("transport_closed", 499, "request was cancelled");
+    return new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
   return undefined;
 }

package/src/providers/provider-contracts.ts

@@ -42,12 +42,56 @@ export function readCredentialSecret(credential: ResolvedCredential, errorMessag
     throw new GatewayError(
       "authentication_failed",
       401,
-      errorMessage ?? "Provider credential secret is missing or empty",
+      `${errorMessage ?? "Provider credential secret is missing or empty"} (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
   return raw;
 }
 
+/**
+ * Asserts a credential is of the required kind, throwing a typed rejection
+ * otherwise. Providers disagree on the kind they accept (`oauth` vs
+ * `api_key` vs `scoped_access_token`), and each hand-rolled its own check +
+ * message. This centralizes the common pattern so a mis-bound credential reads
+ * the same everywhere, preserving the existing `invalid_request`/400 wire
+ * contract.
+ */
+export function assertCredentialKind(
+  credential: ResolvedCredential,
+  expected: CredentialKind | readonly CredentialKind[],
+  providerLabel: string,
+): void {
+  const expectedKinds = Array.isArray(expected) ? expected : [expected];
+  if (expectedKinds.includes(credential.credential_kind)) return;
+  throw new GatewayError(
+    "invalid_request",
+    400,
+    `${providerLabel}: ${expectedKinds.join(" or ")} credential required (got credential_kind=${credential.credential_kind}) (request {requestId}). Wrong key, right door — check the credential 🔑`,
+    { expected_credential_kind: expectedKinds },
+  );
+}
+
+/**
+ * Asserts a candidate's wire family is one of the ones the provider serves,
+ * throwing `capability_unsupported` otherwise. Every provider hand-rolled this
+ * guard with the same shape; this centralizes the pattern so a mis-routed
+ * candidate reads the same everywhere.
+ */
+export function assertWireFamily(
+  candidate: ProviderDispatchTarget,
+  allowed: WireFamily | readonly WireFamily[],
+  providerLabel: string,
+): void {
+  const allowedFamilies = Array.isArray(allowed) ? allowed : [allowed];
+  if (allowedFamilies.includes(candidate.wire_family)) return;
+  throw new GatewayError(
+    "capability_unsupported",
+    400,
+    `${providerLabel} supports ${allowedFamilies.join("/")} only, got ${candidate.wire_family} (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
+    { expected_wire_families: allowedFamilies, got_wire_family: candidate.wire_family },
+  );
+}
+
 /** Fetch capability that validates DNS answers and redirects before each request. */
 export type ValidatedOutboundFetch = (
   input: RequestInfo | URL,
@@ -352,7 +396,7 @@ export interface WebSearchOutcome {
 function normalizeProviderSlug(id: string): string {
   const trimmed = id.trim().toLowerCase();
   if (!/^[a-z][a-z0-9-]{0,63}$/.test(trimmed)) {
-    throw new GatewayError("invalid_request", 400, "Provider ID must be a lowercase slug");
+    throw new GatewayError("invalid_request", 400, "Provider ID must be a lowercase slug (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   return trimmed;
 }
@@ -379,7 +423,7 @@ export function parseCustomProviderId(value: string): CustomProviderId {
     throw new GatewayError(
       "slug_reserved",
       409,
-      "The provider ID is reserved for a builtin provider",
+      "The provider ID is reserved for a builtin provider (request {requestId}). This name's taken — pick another alias ✨",
       { provider_id: normalized },
     );
   }

package/src/providers/provider-credential-resolver.ts

@@ -68,7 +68,7 @@ export class CredentialResolver {
     throw new GatewayError(
       "invalid_request",
       401,
-      "No usable upstream credential is configured for the selected provider",
+      "No usable upstream credential is configured for the selected provider (request {requestId}). Wrong key, right door — check the credential 🔑",
       { provider_id: providerId },
     );
   }