cartethyia 2.7.3 → 2.7.5

package/src/transport/dispatch/empty-stream.ts

@@ -52,13 +52,13 @@ export type EmptyStreamFetch = (
  * unjittered, so a provider returning 200-with-no-events could drive an
  * unbounded wait, and concurrent clients could resynchronize their retries.
  */
-export interface EmptyStreamPolicy {
+interface EmptyStreamPolicy {
   readonly maxEmptyReplays?: number;
   readonly firstEventTimeoutMs?: number;
   readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
 }
 
-export interface EmptyStreamResult {
+interface EmptyStreamResult {
   readonly response: Response;
   readonly tally: StreamTally;
   readonly endpoint: string;
@@ -107,18 +107,17 @@ export async function fetchWithEmptyStreamRecovery(
   const sleep = deps.policy?.sleep ?? abortableSleep;
 
   if (endpoints.length === 0) {
-    throw new GatewayError("platform_unavailable", 502, "No endpoints available", {}, "upstream");
+    throw new GatewayError("platform_unavailable", 502, "No endpoints available (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   }
 
   for (let endpointIndex = 0; endpointIndex < endpoints.length; endpointIndex++) {
     const endpoint = endpoints[endpointIndex]!;
-    const isLastEndpoint = endpointIndex === endpoints.length - 1;
-    const replaysAllowed = isLastEndpoint ? maxReplays : maxReplays;
+    const replaysAllowed = maxReplays;
 
     for (let replay = 0; replay <= replaysAllowed; replay++) {
       // Check abort before each fetch
       if (deps.signal.aborted) {
-        throw new GatewayError("transport_closed", 499, "Aborted");
+        throw new GatewayError("transport_closed", 499, "The request was aborted (request {requestId}). Send it again whenever ready 🙃");
       }
 
       // Check deadline floor
@@ -128,7 +127,7 @@ export async function fetchWithEmptyStreamRecovery(
         throw new GatewayError(
           "platform_unavailable",
           502,
-          "Deadline exhausted before empty-stream replay",
+          "Deadline exhausted before empty-stream replay (request {requestId}). Some things just take longer 🐢",
           {},
           "upstream",
         );
@@ -167,12 +166,7 @@ export async function fetchWithEmptyStreamRecovery(
       // Empty — replay if we haven't exhausted this endpoint's budget
       if (replay < replaysAllowed) {
         const delay = fallbackRetryDelayMs(replay);
-        try {
-          await sleep(delay, deps.signal);
-        } catch (error) {
-          if (error instanceof GatewayError) throw error;
-          throw error;
-        }
+        await sleep(delay, deps.signal);
       }
     }
   }
@@ -181,7 +175,7 @@ export async function fetchWithEmptyStreamRecovery(
   throw new GatewayError(
     "platform_unavailable",
     502,
-    "All endpoints returned empty streams",
+    "All endpoints returned empty streams (request {requestId}). The upstream came back empty-handed — retry 🌙",
     {},
     "upstream",
   );
@@ -196,29 +190,38 @@ async function fetchWithTimeout(
   signal: AbortSignal,
   timeoutMs: number,
 ): Promise<Response> {
-  // Race the fetch against a first-event timeout
+  // Race the fetch against a first-event timeout. The timer and the abort
+  // listener are both cleaned up once the race settles, so a successful fetch
+  // leaves neither behind.
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const onAbort = (): void => {
+    if (timer !== undefined) clearTimeout(timer);
+    // A client cancellation is the caller's signal; the fetch already races the
+    // same abort signal, so rejecting here only surfaces the 499 envelope.
+    timeoutPromiseReject(
+      new GatewayError("transport_closed", 499, "The request was aborted (request {requestId}). Send it again whenever ready 🙃"),
+    );
+  };
+  let timeoutPromiseReject!: (reason: unknown) => void;
   const timeoutPromise = new Promise<never>((_, reject) => {
-    const timer = setTimeout(() => {
+    timeoutPromiseReject = reject;
+    timer = setTimeout(() => {
       // A first-event timeout is the gateway waiting on a silent upstream (e.g.
       // a provider that holds the request in a queue), not the client leaving.
       // It must surface as a deadline failure, never as a `transport_closed`
       // 499 — that code is reserved for genuine client cancellations and would
       // otherwise hide a real upstream wait behind "cancelled by client".
-      reject(new GatewayError("deadline_exceeded", 504, "First event timeout", {}, "upstream"));
+      reject(new GatewayError("deadline_exceeded", 504, "First event timeout (request {requestId}). Some things just take longer 🐢", {}, "upstream"));
     }, timeoutMs);
-    signal.addEventListener("abort", () => {
-      clearTimeout(timer);
-      reject(new GatewayError("transport_closed", 499, "Aborted"));
-    }, { once: true });
   });
-
+  signal.addEventListener("abort", onAbort, { once: true });
   try {
     return await Promise.race([
       fetch(url, { headers: request.headers, body: request.body, signal }),
       timeoutPromise,
     ]);
-  } catch (error) {
-    if (error instanceof GatewayError) throw error;
-    throw error;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    signal.removeEventListener("abort", onAbort);
   }
 }

package/src/transport/dispatch/generation.ts

@@ -20,20 +20,26 @@
  */
 import type { ImageGenerationOutcome, ProviderAdapter, ProviderDispatchTarget } from "../../providers/provider-contracts";
 import { GatewayError } from "../../protocol/gateway-error";
-import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
 import type { ServiceKind } from "../../protocol/canonical-model";
 import { metrics } from "../../observability/metrics";
 import type { ProxyRequestState } from "../request/state";
 import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
 import { captureProviderRateLimit } from "./ratelimit-capture";
+import {
+  hasScope,
+  jsonResponse,
+  networkFetchContext,
+  requireRecordBody,
+  resolveAttemptCredential,
+} from "./native-shared";
 
 import type { GatewayHandlerDeps } from "./handler-deps";
 
-export type GenerationHandlerDeps = GatewayHandlerDeps;
+type GenerationHandlerDeps = GatewayHandlerDeps;
 
 /** Which surface a handler serves. Drives candidate filtering and error copy. */
-export type GenerationKind = Extract<ServiceKind, "imageGeneration" | "videoGeneration">;
+type GenerationKind = Extract<ServiceKind, "imageGeneration" | "videoGeneration">;
 
 /**
  * Surfaces the gateway routes but does not model.
@@ -44,7 +50,7 @@ export type GenerationKind = Extract<ServiceKind, "imageGeneration" | "videoGene
  * is the whole feature: routing, admission, failover, and accounting still
  * apply, and the upstream's own bytes come back untouched.
  */
-export type PassthroughKind = Extract<ServiceKind, "embedding" | "audioTranscription" | "audioSpeech">;
+type PassthroughKind = Extract<ServiceKind, "embedding" | "audioTranscription" | "audioSpeech">;
 
 /** Error-copy noun per surface, so a refusal names what the caller asked for. */
 const SURFACE_NOUNS: Record<GenerationKind | PassthroughKind, string> = {
@@ -74,13 +80,6 @@ function isMediaKind(kind: GenerationKind | PassthroughKind): kind is Generation
  */
 const MAX_ITEMS_PER_REQUEST = 10;
 
-function jsonResponse(payload: unknown, status: number, requestId: string): Response {
-  return new Response(JSON.stringify(payload), {
-    status,
-    headers: { "content-type": "application/json", "x-request-id": requestId },
-  });
-}
-
 /**
  * Forwards a streaming upstream response to the client and accounts for it.
  *
@@ -145,12 +144,12 @@ async function passThrough(
 }
 
 /** Builds the handler for one generation surface. */
-export function createGenerationHandler(kind: GenerationKind, deps: GenerationHandlerDeps) {
+function createGenerationHandler(kind: GenerationKind, deps: GenerationHandlerDeps) {
   return createNativeSurfaceHandler(kind, deps);
 }
 
 /** Builds the handler for one routed surface, media or passthrough. */
-export function createNativeSurfaceHandler(
+function createNativeSurfaceHandler(
   kind: GenerationKind | PassthroughKind,
   deps: GenerationHandlerDeps,
 ) {
@@ -158,23 +157,18 @@ export function createNativeSurfaceHandler(
   return async ({ request }: { request: Request }): Promise<Response> => {
     const state = deps.stateStore.require(request);
     const authorization = state.authorization;
-    const body = state.ingressBody;
-    if (!authorization || body === null || typeof body !== "object" || Array.isArray(body)) {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        `The ${noun} body must be a JSON object. Send one with at least a model and a prompt.`,
-      );
-    }
-    const generation = body as Record<string, unknown>;
+    const generation = requireRecordBody(
+      state,
+      `The ${noun} body must be a JSON object (request {requestId}). Send one with at least a model and a prompt. Check the shape of what you sent — then resend 🪞`,
+    );
     if (typeof generation.model !== "string" || generation.model.trim().length === 0) {
-      throw new GatewayError("invalid_request", 400, `A model is required: it names the ${noun} provider to use.`);
+      throw new GatewayError("invalid_request", 400, `A model is required (request {requestId}): it names the ${noun} provider to use. Check the shape of what you sent — then resend 🪞`);
     }
-    if (!authorization.snapshot.scopes?.includes("routing:invoke" as never)) {
+    if (!hasScope(authorization?.snapshot.scopes, "routing:invoke")) {
       throw new GatewayError(
-        "invalid_request",
+        "policy_rejected",
         403,
-        `${noun} generation not allowed for this key — enable routing:invoke on the API key`,
+        `${noun} generation not allowed for this key (request {requestId}) — enable routing:invoke on the API key. Not allowed by policy — no hard feelings 🫂`,
       );
     }
     // Trust boundary only. Keep accepting `messages` for chat-backed providers
@@ -183,7 +177,7 @@ export function createNativeSurfaceHandler(
       const hasPrompt = typeof generation.prompt === "string" && generation.prompt.trim().length > 0;
       const hasMessages = Array.isArray(generation.messages) && generation.messages.length > 0;
       if (!hasPrompt && !hasMessages) {
-        throw new GatewayError("invalid_request", 400, "prompt is required");
+        throw new GatewayError("invalid_request", 400, "prompt is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
       }
       if (generation.n !== undefined) {
         const n = generation.n;
@@ -191,7 +185,7 @@ export function createNativeSurfaceHandler(
           throw new GatewayError(
             "invalid_request",
             400,
-            `n must be an integer between 1 and ${MAX_ITEMS_PER_REQUEST}`,
+            `n must be an integer between 1 and ${MAX_ITEMS_PER_REQUEST} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
           );
         }
       }
@@ -200,10 +194,15 @@ export function createNativeSurfaceHandler(
     const prepared = await deps.proxyPreparer.prepareNativeService({
       model: generation.model,
       serviceKind: kind,
-      authorization,
+      // `requireRecordBody` already refused a missing authorization; this guard
+      // exists only to narrow the type for the code below.
+      authorization: authorization!,
       ...(state.abortController.signal ? { signal: state.abortController.signal } : {}),
       ...(state.clientUserAgent === undefined ? {} : { clientUserAgent: state.clientUserAgent }),
     });
+    if (!authorization) {
+      throw new GatewayError("invalid_request", 400, "authentication required (request {requestId})");
+    }
 
     return runAttemptLoop<Response, ProviderAdapter>({
       state,
@@ -219,27 +218,15 @@ export function createNativeSurfaceHandler(
       candidates: prepared.candidates,
       tenantId: prepared.authorization.tenantId,
       strictPoolSelection: false,
-      exhaustedError: new GatewayError("admission_unavailable", 503, `no eligible ${noun} generation route`),
+      exhaustedError: new GatewayError("route_unavailable", 503, `no eligible ${noun} generation route (request {requestId}). The bouncer stepped out — come back shortly 🚪`),
       prepare: async (candidate) => {
-        const credential = candidate.provider_account_id
-          ? await resolveCredentialForAccount(
-              deps.db,
-              candidate.provider_id,
-              candidate.provider_account_id,
-              deps.oauthRefreshService && deps.resolveOAuthRefresher
-                ? { refreshService: deps.oauthRefreshService, resolveRefresher: deps.resolveOAuthRefresher }
-                : undefined,
-            )
-          : {
-              provider_id: candidate.provider_id as ProviderAdapter["provider_id"],
-              credential_kind: "none" as const,
-            };
+        const credential = await resolveAttemptCredential(deps, candidate);
         const adapter = await deps.resolveProviderAdapter?.(candidate.provider_id);
         if (!adapter) {
           throw new GatewayError(
             "capability_unsupported",
             400,
-            `${noun} generation is unavailable for this provider`,
+            `${noun} generation is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
           );
         }
         return { credential, adapter };
@@ -309,14 +296,7 @@ export function createNativeSurfaceHandler(
           abort_signal: state.abortController.signal,
           request_headers: inboundHeaders,
           ...(candidate.user_agent === undefined ? {} : { user_agent: candidate.user_agent }),
-          ...(deps.networkBindingFactory
-            ? {
-                outbound_fetch: deps.networkBindingFactory.fetch(
-                  leases.proxySlot?.poolId,
-                  authorization.tenantId,
-                ),
-              }
-            : {}),
+          ...networkFetchContext(deps, leases.proxySlot?.poolId, authorization.tenantId),
         };
         // Prefer the provider's own method for this kind; otherwise post the
         // body to the candidate's endpoint through the adapter, which owns the
@@ -344,7 +324,7 @@ export function createNativeSurfaceHandler(
                   new GatewayError(
                     "capability_unsupported",
                     400,
-                    `${noun} generation is unavailable for this provider`,
+                    `${noun} generation is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
                   ),
                 )
               : adapter

package/src/transport/dispatch/leases.ts

@@ -141,7 +141,7 @@ async function acquirePoolSlot(
       throw new GatewayError(
         "proxy_pool_unhealthy",
         503,
-        "Every proxy pool this route requires is unhealthy or disabled. Repair a pool, or relax the route's pool requirement.",
+        "Every proxy pool this route requires is unhealthy or disabled (request {requestId}). Repair a pool, or relax the route's pool requirement. This bridge looks shaky — repair or reroute 🔧",
         { reason: "no_healthy_pool" },
         "network",
       );
@@ -172,7 +172,7 @@ async function acquirePoolSlot(
     throw new GatewayError(
       "proxy_pool_unavailable",
       503,
-      "No active proxy pool is available because coordination is unavailable.",
+      "No active proxy pool is available because coordination is unavailable (request {requestId}). The bouncer stepped out — come back shortly 🚪",
       { reason: "coordination_unavailable" },
       "network",
     );
@@ -219,14 +219,14 @@ async function acquirePoolSlot(
     failure.reason === "at_capacity" || failure.reason === "provider_at_capacity" ? 429 : 503;
   const message =
     failure.reason === "at_capacity"
-      ? "Every proxy pool for this provider is at its concurrency limit. Retry shortly, or add a pool or raise its capacity."
+      ? "Every proxy pool for this provider is at its concurrency limit (request {requestId}). Retry shortly, or add a pool or raise its capacity. The pools are full right now — chill 🌊"
       : failure.reason === "provider_at_capacity"
-        ? "Every proxy pool has reached this provider's per-proxy concurrency limit. Retry shortly, raise the limit in the provider's routing settings, or add a pool."
+        ? "Every proxy pool has reached this provider's per-proxy concurrency limit (request {requestId}). Retry shortly, raise the limit in the provider's routing settings, or add a pool. The proxies are working overtime — hang tight ⚡️"
         : failure.reason === "blocked"
-          ? "All proxy pools are saturated for this provider: the upstream refuses every egress configured for it. Replace a blocked proxy, or add one the upstream has not flagged."
+          ? "All proxy pools are saturated for this provider (request {requestId}): the upstream refuses every egress configured for it. Replace a blocked proxy, or add one the upstream has not flagged. All roads blocked — time to find a new route 🗺️"
           : failure.reason === "cooldown"
-            ? "Every proxy pool for this provider is cooling down after upstream failures. Retry once the cooldown resets."
-            : "No active proxy pool is configured for this tenant and provider. Add one, or route this provider through direct egress.";
+            ? "Every proxy pool for this provider is cooling down after upstream failures (request {requestId}). Retry once the cooldown resets. The proxies are catching their breath — zzz 💤"
+            : "No active proxy pool is configured for this tenant and provider (request {requestId}). Add one, or route this provider through direct egress. No bridge to cross — configure a pool first 🏗️";
   throw new GatewayError(code, status, message, {
     pools: failure.pools,
     // Only measured evidence: a cooldown's real reset instant. The
@@ -279,7 +279,7 @@ export async function acquireAttemptLeases(
       : await acquirePoolSlot(candidate, source, input.poolSelector, input.strictPoolSelection);
     if (slot) partial.proxySlot = slot;
     if (input.strictPoolSelection && input.signal.aborted)
-      throw new GatewayError("transport_closed", 499, "request was cancelled");
+      throw new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
     partial.reservation = await source.routingEngine.reserve({
       ...source.plan,
       candidates: [candidate],

package/src/transport/dispatch/native-shared.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared helpers for the native dispatch handlers (web search, token count,
+ * System One, responses-compact, generation). The handlers previously spelled
+ * the same credential-resolution, outbound-fetch, body-validation, thinking-
+ * suffix, response-serialization, and usage-clone blocks by hand, and the
+ * copies could drift (generation's `jsonResponse` lost the `cache-control`
+ * header). One home here keeps them in step.
+ */
+import { GatewayError } from "../../protocol/gateway-error";
+import type { ProviderId, ResolvedCredential, ValidatedOutboundFetch } from "../../providers/provider-contracts";
+import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
+import { repriceUsage, usageFromProvider } from "../../providers/provider-usage";
+import type { UsageRecord } from "../../protocol/canonical-model";
+import { parseThinkingSuffix } from "../../protocol/translation/thinking";
+import type { GatewayHandlerDeps } from "./handler-deps";
+
+/**
+ * Whether a scope list contains the named scope. The native handlers used to
+ * force `scopes?.includes(name as never)` — a type-loop hole that bypassed
+ * the `AccessScope` union only to compare runtime strings. The check is the
+ * same, with a real `readonly string[]` receiver.
+ */
+export function hasScope(scopes: readonly string[] | undefined, name: string): boolean {
+  return scopes?.includes(name) === true;
+}
+
+/**
+ * Resolves the credential for one candidate: a real account credential when
+ * the candidate carries an account, otherwise the credential-less `"none"`
+ * credential. Shared by every native handler's `prepare`.
+ */
+export async function resolveAttemptCredential(
+  deps: Pick<GatewayHandlerDeps, "db" | "oauthRefreshService" | "resolveOAuthRefresher">,
+  candidate: { readonly provider_id: string; readonly provider_account_id?: string },
+): Promise<ResolvedCredential> {
+  if (!candidate.provider_account_id) {
+    return {
+      provider_id: candidate.provider_id as ProviderId,
+      credential_kind: "none" as const,
+    };
+  }
+  return resolveCredentialForAccount(
+    deps.db,
+    candidate.provider_id,
+    candidate.provider_account_id,
+    deps.oauthRefreshService && deps.resolveOAuthRefresher
+      ? { refreshService: deps.oauthRefreshService, resolveRefresher: deps.resolveOAuthRefresher }
+      : undefined,
+  );
+}
+
+/** The outbound-fetch context fragment native handlers spread into the dispatch context. */
+export function networkFetchContext(
+  deps: { readonly networkBindingFactory?: GatewayHandlerDeps["networkBindingFactory"] },
+  poolId: string | undefined,
+  tenantId: string | null,
+): { outbound_fetch?: ValidatedOutboundFetch } {
+  if (!deps.networkBindingFactory) return {};
+  return { outbound_fetch: deps.networkBindingFactory.fetch(poolId, tenantId ?? undefined) };
+}
+
+/** Serializes a JSON payload with the shared native-response header set. */
+export function jsonResponse(payload: unknown, status: number, requestId: string): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+      "x-request-id": requestId,
+    },
+  });
+}
+
+/**
+ * Strips a thinking suffix (`model(high)`) from the model name and rebuilds
+ * the body with the bare model when it changed. Returns the bare model and
+ * the body to forward upstream.
+ */
+export function stripThinkingSuffix(
+  model: string,
+  body: Record<string, unknown>,
+): { bareModel: string; body: Record<string, unknown> } {
+  const { model: bareModel } = parseThinkingSuffix(model);
+  return { bareModel, body: bareModel === model ? body : { ...body, model: bareModel } };
+}
+
+/**
+ * Validates the ingress body is a non-null object and returns it as a record.
+ * Throws the standard `invalid_request` with the caller's message (kept
+ * per-route so the wire text is unchanged).
+ */
+export function requireRecordBody(
+  state: { readonly authorization?: unknown; readonly ingressBody?: unknown },
+  message: string,
+): Record<string, unknown> {
+  const { authorization, ingressBody } = state;
+  if (!authorization || ingressBody === null || typeof ingressBody !== "object" || Array.isArray(ingressBody))
+    throw new GatewayError("invalid_request", 400, message);
+  return ingressBody as Record<string, unknown>;
+}
+
+/**
+ * Reads usage from an upstream response clone, repricing the reported value (or
+ * the caller's estimate) for the routed provider/model. Shared by the native
+ * handlers that proxy an upstream JSON body verbatim.
+ */
+export async function usageFromUpstreamClone(
+  response: Response,
+  estimate: UsageRecord,
+  providerId: string,
+  modelId: string,
+): Promise<UsageRecord> {
+  let reportedUsage: ReturnType<typeof usageFromProvider>;
+  try {
+    const parsed: unknown = await response.clone().json();
+    reportedUsage = usageFromProvider(
+      typeof parsed === "object" && parsed !== null
+        ? (parsed as Record<string, unknown>)["usage"]
+        : undefined,
+    );
+  } catch {
+    reportedUsage = undefined;
+  }
+  return repriceUsage(reportedUsage ?? estimate, providerId, modelId);
+}
+
+

package/src/transport/dispatch/proxy-request.ts

@@ -41,7 +41,7 @@ import type { PreparedProxyRequest } from "../request/preparer";
 
 import type { GatewayHandlerDeps } from "./handler-deps";
 
-export type ProviderProxyHandlerDeps = GatewayHandlerDeps & {
+type ProviderProxyHandlerDeps = GatewayHandlerDeps & {
   /** Live lookup of a provider's SSRF-validated upstream host. */
   readonly byokUpstreamHosts?: { readonly get: (providerId: string) => ByokUpstreamHost | undefined };
 };
@@ -116,7 +116,7 @@ export async function handleProviderProxyRequest(
   const state = deps.stateStore.require(request);
   const prepared = state.preparedRequest;
   if (!prepared)
-    throw new GatewayError("admission_unavailable", 503, "The request was not prepared, so no route can be dialed. Resend the request.");
+    throw new GatewayError("route_unavailable", 503, "The request was not prepared, so no route can be dialed (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");
   const canonicalRequest = await applyTenantPreferences(prepared, deps.db);
   // Tenant system-prompt injection, resolved once per request. For providers
   // whose upstream validates the fixed system prompt as a channel identity
@@ -135,6 +135,7 @@ export async function handleProviderProxyRequest(
         {
           providerId: candidateForPrompt.provider_id,
           modelId: candidateForPrompt.model_id,
+          requestedModel: prepared.plan?.requested_model ?? candidateForPrompt.model_id,
         },
       )?.text
     : undefined;
@@ -188,13 +189,13 @@ export async function handleProviderProxyRequest(
     tenantId: prepared.authorization.tenantId,
     strictPoolSelection: true,
     resolveHost: (candidate) => deps.byokUpstreamHosts?.get(candidate.provider_id),
-    exhaustedError: new GatewayError("admission_unavailable", 503, "No account could be leased for this request. Retry shortly; if it persists, add an account or check that one is healthy."),
+    exhaustedError: new GatewayError("route_unavailable", 503, "No account could be leased for this request (request {requestId}). Retry shortly; if it persists, add an account or check that one is healthy. The bouncer stepped out — come back shortly 🚪"),
     prepare: async (candidate) => {
       if (!candidate.provider_account_id && candidate.requires_account !== false)
         throw new GatewayError(
-          "admission_unavailable",
+          "route_unavailable",
           503,
-          "This route has no usable credential. Save one on the account, or route to a provider whose account is configured.",
+          "This route has no usable credential (request {requestId}). Save one on the account, or route to a provider whose account is configured. Wrong key, right door — check the credential 🔑",
         );
       const credential = candidate.provider_account_id
         ? await resolveCredentialForAccount(
@@ -211,13 +212,13 @@ export async function handleProviderProxyRequest(
           };
       const adapter = await deps.resolveProviderAdapter?.(candidate.provider_id);
       if (!adapter)
-        throw new GatewayError("admission_unavailable", 503, "provider adapter not registered");
+        throw new GatewayError("route_unavailable", 503, "provider adapter not registered (request {requestId}). Even we have bad days — check the registry wiring 🐻");
       if (!isBundledProviderId(candidate.provider_id)) {
         if (!deps.byokUpstreamHosts?.get(candidate.provider_id) || !deps.networkBindingFactory)
           throw new GatewayError(
-            "admission_unavailable",
+            "route_unavailable",
             503,
-            "validated network binding is required for configurable upstreams",
+            "validated network binding is required for configurable upstreams (request {requestId}). No bridge to cross — configure a pool first 🏗️",
           );
       }
       return { credential, adapter };
@@ -239,6 +240,7 @@ export async function handleProviderProxyRequest(
         ...(candidate.output_limit == null ? {} : { output_limit: candidate.output_limit }),
         capabilities: candidate.capability_profile,
         user_agent: candidate.user_agent,
+        ...(candidate.dialect === undefined ? {} : { dialect: candidate.dialect }),
       };
       const candidateRequest =
         candidate.model_id === dispatchRequest.model