cartethyia 2.7.2 → 2.7.4

package/src/transport/dispatch/retry-policy.ts

@@ -8,9 +8,12 @@
  * than inside it so the loop stays a policy *consumer* — one place decides
  * retryability (`../failure-policy.ts`), one place decides refresh and
  * cooldown eligibility (here).
+ *
+ * The egress-scoped half of the rate-limit decision lives in
+ * `../../network/rate-limit-verdict`; this module keeps only the credential-
+ * scoped predicates.
  */
 import { GatewayError } from "../../protocol/gateway-error";
-import { providerRateLimitIsIpScoped } from "../../providers/provider-metadata";
 
 /**
  * Returns true only when an upstream failure is evidence that the OAuth
@@ -32,69 +35,3 @@ export function isOAuthCredentialInvalidated(error: unknown): error is GatewayEr
   if (/web[ _-]?search|web[ _-]?fetch|x[ _-]?search|tool invocation|search backend/i.test(message)) return false;
   return error.details.credentialEvidence === true;
 }
-
-/**
- * A free-tier IP refusal: the upstream has flagged this egress address, not
- * this request.
- *
- * OpenCode answers a blocked address with `403` and its own
- * `FreeTierError`/`ModelDeprecated`-style body. The request was never read, so
- * retrying it — with the same tools, the same headers, or the same credential —
- * cannot succeed from the same address. Only a different egress can.
- *
- * This is deliberately narrower than "any 403": a content-policy rejection or a
- * licence refusal is also a 403 and must not retire a healthy proxy. The
- * provider must also declare `ipScopedRateLimit`, which is the same fact the
- * 429 path already relies on.
- */
-export function isFreeTierIpBlock(error: unknown, providerId: string): error is GatewayError {
-  if (!(error instanceof GatewayError) || error.origin !== "upstream" || error.status !== 403) {
-    return false;
-  }
-  if (!providerRateLimitIsIpScoped(providerId)) return false;
-  const providerCode = typeof error.details.providerCode === "string" ? error.details.providerCode : "";
-  const raw = String(error.details.raw ?? "");
-  return (
-    /freetier|free.?tier/i.test(providerCode) ||
-    /FreeTierError|free tier can only be used/i.test(`${error.message} ${raw}`)
-  );
-}
-
-/**
- * A provider-scoped 429, on a provider whose limits follow the egress address.
- *
- * Only then is the pool the thing that ran out: the upstream counted requests
- * from this address, so the next attempt must leave by a different one and
- * cooling this pool is the fix. `providerRateLimitIsIpScoped` holds that fact
- * per provider (see the metadata field) rather than inferring it from the
- * response — a 429 states which bucket was exhausted only in the provider's own
- * wording, and every account-keyed provider words it the same way.
- *
- * For an account-keyed provider the 429 belongs to the credential that was
- * dialed. The account health machine already records it and routes the next
- * request to a sibling, so cooling the pool as well only removed healthy
- * accounts from service: every account sharing that egress lost its route for
- * the cooldown window because one of them hit its own limit. A bare 429 with no
- * provider scope stays a request-level limit and never cools the pool.
- *
- * `providerId` is the caller's own candidate, not a field read off the error:
- * the in-stream error frames the protocol modules build carry no `providerId`
- * detail, so reading it from `details` would silently disable the IP-scoped
- * rule on exactly the streaming path it exists for.
- *
- * A type guard on `GatewayError`, so a caller that passes this check can hand
- * the same value to `flagPoolCooldown` without a second narrowing step.
- */
-export function shouldCooldownPool(error: unknown, providerId: string): error is GatewayError {
-  if (
-    !(
-      error instanceof GatewayError &&
-      error.origin === "upstream" &&
-      error.status === 429 &&
-      error.details.rateLimitScope === "provider"
-    )
-  ) {
-    return false;
-  }
-  return providerRateLimitIsIpScoped(providerId);
-}

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

@@ -60,7 +60,7 @@ export function createDispatchStreamEncoder(
   throw new GatewayError(
     "capability_unsupported",
     400,
-    `Unknown surface: ${surface}`,
+    `Unknown surface: ${surface} (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
     { surface },
   );
 }

package/src/transport/dispatch/streaming/finalize.ts

@@ -24,7 +24,7 @@ import type { Reservation } from "../../routing/route-model";
 import { repriceUsage } from "../../../providers/provider-usage";
 import { metrics } from "../../../observability/metrics";
 import { flagPoolBlocked, flagPoolCooldown } from "../../../network/pool-health";
-import { isFreeTierIpBlock, shouldCooldownPool } from "../retry-policy";
+import { classifyEgressFailure } from "../../../network/rate-limit-verdict";
 import { releaseAttemptLeases } from "../leases";
 import type { AttemptLeaseOwnership } from "../leases";
 import { finalizeRequestTelemetry } from "../../guards/error-lifecycle";
@@ -186,7 +186,7 @@ export class StreamFinalizer {
       // origin is the upstream's: labelling it `cartethyia` reported a
       // provider that stopped sending as a gateway defect.
       this.input.state.abortController.abort(
-        new GatewayError("deadline_exceeded", 504, "The upstream stopped sending data mid-stream. Retry; if it keeps happening, the account or pool is unstable.", {}, "upstream"),
+        new GatewayError("deadline_exceeded", 504, "The upstream stopped sending data mid-stream (request {requestId}). Retry; if it keeps happening, the account or pool is unstable. The connection ghosted us — come back in a moment 👻", {}, "upstream"),
       );
     }, timeoutMs);
   }
@@ -363,7 +363,7 @@ export class StreamFinalizer {
     if (drain) return drain;
     if (reason instanceof GatewayError && reason.code === "deadline_exceeded") 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");
     return undefined;
   }
 
@@ -453,7 +453,7 @@ export class StreamFinalizer {
         ? new GatewayError(
             "transport_unavailable",
             502,
-            "The upstream closed the stream before it reported a final result. Retry; if it keeps happening, the account or pool is unstable.",
+            "The upstream closed the stream before it reported a final result (request {requestId}). Retry; if it keeps happening, the account or pool is unstable. The connection ghosted us — come back in a moment 👻",
             {},
             "upstream",
           )
@@ -531,7 +531,7 @@ export class StreamFinalizer {
           ? new GatewayError(
               "deadline_exceeded",
               504,
-              "request deadline exceeded",
+              "request deadline exceeded (request {requestId}). Some things just take longer 🐢",
               {},
               "cartethyia",
             )
@@ -579,10 +579,11 @@ export class StreamFinalizer {
       ...(pipeline.clientResponseText.length > 0 ? { clientResponseText: pipeline.clientResponseText } : {}),
     });
     this.streamSettled = true;
-    if (candidate.networkPoolId && !cancelled && deps.poolSelector) {
-      if (shouldCooldownPool(err, candidate.providerId)) {
+    if (candidate.networkPoolId && !cancelled && deps.poolSelector && err instanceof GatewayError) {
+      const egressVerdict = classifyEgressFailure(err, candidate.providerId);
+      if (egressVerdict.kind === "cooldown") {
         flagPoolCooldown(deps.poolSelector, deps.db, candidate.networkPoolId, candidate.providerId, err);
-      } else if (isFreeTierIpBlock(err, candidate.providerId)) {
+      } else if (egressVerdict.kind === "blocked") {
         flagPoolBlocked(deps.poolSelector, deps.db, candidate.networkPoolId, candidate.providerId, err);
       }
     }

package/src/transport/dispatch/streaming/stream.ts

@@ -50,7 +50,9 @@ import {
   resolveCaptureModeForRequest,
   shouldCaptureProviderBodyForRequest,
 } from "../capture-policy";
-import { resolveTenantImageClampMaxBytes } from "../../request/tenant-preferences";
+import { resolveTenantImageClampMaxBytes, readTenantSystemPromptsForDispatch } from "../../request/tenant-preferences";
+import { resolveTenantSystemPrompt } from "../../request/system-prompt-injection";
+import { isWrappedInjectionProvider } from "../../../console/system-prompt/contracts";
 import { proxySuccessHeaders, buildUpstreamDispatchContext } from "../upstream";
 import type { AttemptLeaseOwnership } from "../leases";
 import type { ProviderContinuationScope } from "../../../providers/provider-contracts";
@@ -217,6 +219,19 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
       ? {}
       : { imageClampMaxBytes: state.imageClampMaxBytes }),
     ...(conversationAffinity ? { conversationAffinity } : {}),
+    // Same wrapped-injection text the non-streaming path carries: providers
+    // whose upstream validates the fixed system prompt as a channel identity
+    // (the buddy family) receive the tenant prompt through dispatch context
+    // so the adapter can fold it into its fixed turn. `override` degrades to
+    // wrapped append there; stripping the identity would be refused outright.
+    ...(await (async () => {
+      if (!isWrappedInjectionProvider(candidate.provider_id)) return {};
+      const text = resolveTenantSystemPrompt(
+        await readTenantSystemPromptsForDispatch(deps.db, prepared.authorization.snapshot.tenant_id),
+        { providerId: candidate.provider_id, modelId: candidate.model_id },
+      )?.text;
+      return text === undefined ? {} : { tenantSystemPrompt: text };
+    })()),
     ...(candidate.user_agent === undefined ? {} : { userAgent: candidate.user_agent }),
     ...(wrappedOutboundFetch ? { outboundFetch: wrappedOutboundFetch } : {}),
     ...(outboundFetch ? { outboundAttachmentFetch: outboundFetch } : {}),

package/src/transport/dispatch/systemone.ts

@@ -33,10 +33,10 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
     const authorization = state.authorization;
     const body = state.ingressBody;
     if (!authorization || body === null || typeof body !== "object" || Array.isArray(body))
-      throw new GatewayError("invalid_request", 400, "systemone request body must be a JSON object");
+      throw new GatewayError("invalid_request", 400, "systemone request body must be a JSON object (request {requestId}). Check the shape of what you sent — then resend 🪞");
     const decision = body as Record<string, unknown>;
     if (typeof decision.model !== "string" || decision.model.trim().length === 0)
-      throw new GatewayError("invalid_request", 400, "model is required");
+      throw new GatewayError("invalid_request", 400, "model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
     // A thinking suffix (`model(high)`) is stripped for the same reason the
     // canonical preparer strips it: the route matches the model name against the
     // allowlist and the route plan, and `(high)` is not part of any registered
@@ -49,14 +49,14 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
     // upstream's to validate. `state` and a `questions` object are what make a
     // System One request a System One request at all.
     if (decision.state === undefined || decision.state === null)
-      throw new GatewayError("invalid_request", 400, "state is required");
+      throw new GatewayError("invalid_request", 400, "state is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
     if (
       decision.questions === undefined ||
       decision.questions === null ||
       typeof decision.questions !== "object" ||
       Array.isArray(decision.questions)
     )
-      throw new GatewayError("invalid_request", 400, "questions must be an object");
+      throw new GatewayError("invalid_request", 400, "questions must be an object (request {requestId}). Check the shape of what you sent — then resend 🪞");
     const prepared = await deps.proxyPreparer.prepareNativeService({
       model: bareModel,
       serviceKind: "systemone",
@@ -80,9 +80,9 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
       // Lenient pool semantics: a missing slot tolerates direct egress.
       strictPoolSelection: false,
       exhaustedError: new GatewayError(
-        "admission_unavailable",
+        "route_unavailable",
         503,
-        "no eligible System One route",
+        "no eligible System One route (request {requestId}). The bouncer stepped out — come back shortly 🚪",
       ),
       prepare: async (candidate) => {
         const credential = candidate.provider_account_id
@@ -103,7 +103,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
           throw new GatewayError(
             "capability_unsupported",
             400,
-            "System One transport unavailable for this provider",
+            "System One transport unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰",
           );
         return { credential, adapter };
       },
@@ -148,7 +148,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
           throw new GatewayError(
             response.status >= 500 ? "platform_unavailable" : "invalid_request",
             response.status,
-            `System One upstream error: ${detail.slice(0, 240)}`,
+            `System One upstream error (request {requestId}): ${detail.slice(0, 240)}`,
           );
         }
         // Prefer the usage the decision endpoint reported; fall back to the

package/src/transport/dispatch/token-count.ts

@@ -57,7 +57,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
       throw new GatewayError(
         "invalid_request",
         400,
-        "The count_tokens body must be a JSON object, the same shape POST /v1/messages accepts.",
+        "The count_tokens body must be a JSON object (request {requestId}), the same shape POST /v1/messages accepts. Check the shape of what you sent — then resend 🪞",
       );
     }
     const countBody = body as Record<string, unknown>;
@@ -66,16 +66,16 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
     // upstream's own required fields, so the gateway does not restate its own
     // narrower rule and risk rejecting a body the provider would accept.
     if (typeof countBody.model !== "string" || countBody.model.trim().length === 0) {
-      throw new GatewayError("invalid_request", 400, "A model is required: it names the provider to count with.");
+      throw new GatewayError("invalid_request", 400, "A model is required (request {requestId}): it names the provider to count with. Check the shape of what you sent — then resend 🪞");
     }
     if (!Array.isArray(countBody.messages)) {
-      throw new GatewayError("invalid_request", 400, "messages must be an array — there is nothing to count without it.");
+      throw new GatewayError("invalid_request", 400, "messages must be an array (request {requestId}) — there is nothing to count without it. Check the shape of what you sent — then resend 🪞");
     }
     if (!authorization.snapshot.scopes?.includes("routing:invoke" as never)) {
       throw new GatewayError(
-        "invalid_request",
+        "policy_rejected",
         403,
-        "token counting not allowed for this key — enable routing:invoke on the API key",
+        "token counting not allowed for this key (request {requestId}) — enable routing:invoke on the API key. Not allowed by policy — no hard feelings 🫂",
       );
     }
 
@@ -111,9 +111,9 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
       tenantId: prepared.authorization.tenantId,
       strictPoolSelection: false,
       exhaustedError: new GatewayError(
-        "admission_unavailable",
+        "route_unavailable",
         503,
-        "no eligible route can count tokens for this model",
+        "no eligible route can count tokens for this model (request {requestId}). The bouncer stepped out — come back shortly 🚪",
       ),
       prepare: async (candidate) => {
         const credential = candidate.provider_account_id
@@ -131,7 +131,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
             };
         const adapter = await deps.resolveProviderAdapter?.(candidate.provider_id);
         if (!adapter) {
-          throw new GatewayError("capability_unsupported", 400, "token counting is unavailable for this provider");
+          throw new GatewayError("capability_unsupported", 400, "token counting is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰");
         }
         return { credential, adapter };
       },
@@ -146,7 +146,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
 
         const adapter = context.adapter;
         if (typeof adapter.dispatchNativeService !== "function") {
-          throw new GatewayError("capability_unsupported", 400, "token counting is unavailable for this provider");
+          throw new GatewayError("capability_unsupported", 400, "token counting is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰");
         }
 
         const target: ProviderDispatchTarget = {

package/src/transport/dispatch/upstream.ts

@@ -61,6 +61,13 @@ export function buildUpstreamDispatchContext(input: {
    * database handle.
    */
   readonly imageClampMaxBytes?: number;
+  /**
+   * Tenant system-prompt text resolved once per request (append/override
+   * injection). Carried through dispatch because the buddy adapters fold it
+   * into their fixed system turn after serialization — the canonical level
+   * cannot reach that turn.
+   */
+  readonly tenantSystemPrompt?: string;
   /** Opaque identity shared by retries of one logical gateway request. */
   readonly requestIdentity?: object;
 }): Record<string, unknown> {
@@ -101,6 +108,9 @@ export function buildUpstreamDispatchContext(input: {
     ...(input.imageClampMaxBytes === undefined
       ? {}
       : { image_clamp_max_bytes: input.imageClampMaxBytes }),
+    ...(input.tenantSystemPrompt === undefined
+      ? {}
+      : { tenant_system_prompt: input.tenantSystemPrompt }),
     ...(input.requestIdentity ? { request_identity: input.requestIdentity } : {}),
   } as Record<string, unknown>;
 }

package/src/transport/dispatch/websearch.ts

@@ -50,10 +50,10 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
     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 search body must be a JSON object. Send one with at least a model and a query.");
+      throw new GatewayError("invalid_request", 400, "The search body must be a JSON object (request {requestId}). Send one with at least a model and a query. Check the shape of what you sent — then resend 🪞");
     const search = body as Record<string, unknown>;
     if (typeof search.model !== "string" || search.model.trim().length === 0)
-      throw new GatewayError("invalid_request", 400, "A model is required: it names the search provider to use.");
+      throw new GatewayError("invalid_request", 400, "A model is required (request {requestId}): it names the search provider to use. Check the shape of what you sent — then resend 🪞");
     // The search "model" names the provider (or an alias/combo of one). A
     // thinking suffix is stripped for the same reason the canonical preparer
     // strips it: it is not part of any registered id.
@@ -61,12 +61,12 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
     const searchBody: Record<string, unknown> =
       bareModel === search.model ? search : { ...search, model: bareModel };
     if (!authorization.snapshot.scopes?.includes("search:invoke" as never)) {
-      throw new GatewayError("invalid_request", 403, "search not allowed for this key — enable search:invoke on the API key");
+      throw new GatewayError("policy_rejected", 403, "search not allowed for this key (request {requestId}) — enable search:invoke on the API key. Not allowed by policy — no hard feelings 🫂");
     }
     // Trust boundary only: the query must be a non-empty string. The adapter
     // validates the remaining shape when it maps the body onto its provider.
     if (typeof search.query !== "string" || search.query.trim().length === 0)
-      throw new GatewayError("invalid_request", 400, "query is required");
+      throw new GatewayError("invalid_request", 400, "query is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
 
     const prepared = await deps.proxyPreparer.prepareNativeService({
       model: bareModel,
@@ -89,7 +89,7 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
       candidates: prepared.candidates,
       tenantId: prepared.authorization.tenantId,
       strictPoolSelection: false,
-      exhaustedError: new GatewayError("admission_unavailable", 503, "no eligible search route"),
+      exhaustedError: new GatewayError("route_unavailable", 503, "no eligible search route (request {requestId}). The bouncer stepped out — come back shortly 🚪"),
       prepare: async (candidate) => {
         const credential = candidate.provider_account_id
           ? await resolveCredentialForAccount(
@@ -109,7 +109,7 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
           throw new GatewayError(
             "capability_unsupported",
             400,
-            "web search is unavailable for this provider",
+            "web search is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰",
           );
         return { credential, adapter };
       },

package/src/transport/drain-endpoint.ts

@@ -55,9 +55,9 @@ export function createDrainHandler(
 ): (context: { request: Request }) => Promise<Response> {
   return async ({ request }) => {
     if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
-      throw new GatewayError("invalid_request", 403, "drain is only available from loopback");
+      throw new GatewayError("policy_rejected", 403, "drain is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂");
     if (!tokenMatches(request.headers.get("x-drain-token"), deps.token))
-      throw new GatewayError("invalid_request", 401, "invalid drain token");
+      throw new GatewayError("authentication_failed", 401, "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑");
     // Acknowledge first, then drain: the response must be on the wire before the
     // shutdown path starts closing sockets, or the caller sees a dropped
     // connection instead of a 202.

package/src/transport/failure-policy.ts

@@ -167,7 +167,7 @@ export function statusToGatewayErrorCode(status: number): GatewayErrorCode {
   if (status === 413) return "request_too_large";
   if (status === 415) return "unsupported_media_type";
   if (status === 422) return "upstream_unprocessable";
-  if (status === 529) return "capacity_exhausted";
+  if (status === 529) return "upstream_overloaded";
   if (status >= 500 && status <= 599) return "platform_unavailable";
   return "invalid_request";
 }
@@ -274,7 +274,9 @@ export function classifyUpstreamFailure(error: unknown): UpstreamFailurePolicy {
         error.code === "capability_unsupported" ||
     error.code === "model_not_found" ||
     error.code === "admission_unavailable" ||
+    error.code === "route_unavailable" ||
     error.code === "capacity_exhausted" ||
+    error.code === "upstream_overloaded" ||
     // A provider max-inflight rejection: the plan's next sibling account may
     // have a free slot, exactly as with an API-key concurrency rejection.
     error.code === "provider_capacity_exhausted" ||
@@ -286,6 +288,7 @@ export function classifyUpstreamFailure(error: unknown): UpstreamFailurePolicy {
     error.code === "accounts_unavailable" ||
     error.code === "accounts_rate_limited" ||
     error.code === "quota_exceeded" ||
+    error.code === "rate_limited" ||
     error.code === "authentication_failed" ||
     error.code === "proxy_auth_required" ||
     error.code === "deadline_exceeded" ||
@@ -427,10 +430,14 @@ const CATEGORY_HTTP_STATUS: Partial<Record<GatewayErrorCode | "unknown_error", n
   // in this process.
   transport_unavailable: 502,
   platform_unavailable: 502,
+  upstream_overloaded: 529,
   deadline_exceeded: 504,
   transport_closed: 499,
   shutting_down: 503,
   overloaded: 529,
+  route_unavailable: 503,
+  model_not_allowed: 403,
+  rate_limited: 429,
   unknown_error: 500,
 };
 
@@ -624,7 +631,7 @@ export function upstreamQueuedError(
     503,
     detail.length > 0
       ? detail
-      : "The upstream has queued this request. Retry after the stated interval.",
+      : "The upstream has queued this request (request {requestId}); retry after the stated interval. You're in line — no cuts 💛",
     {
       providerId,
       reason: "upstream-queued",
@@ -816,7 +823,7 @@ export function classifyUpstreamError(
   }
   if (normalized !== undefined && CAPACITY_ERROR_IDENTIFIERS.has(normalized))
     return {
-      code: "capacity_exhausted",
+      code: "upstream_overloaded",
       status: status === 503 || status === 529 ? status : 529,
       origin: "upstream",
     };
@@ -969,7 +976,7 @@ export async function throwIfHtmlResponse(response: Response): Promise<void> {
   throw new GatewayError(
     "transport_unavailable",
     502,
-    `Upstream returned an HTML error page: ${summary}`.slice(0, 300),
+    `Upstream returned an HTML error page: ${summary} (request {requestId}). The provider's edge is having a moment — hang tight ☕️`.slice(0, 320),
     { upstreamStatus: response.status, contentType, accountScope: true },
     "upstream",
   );
@@ -1011,11 +1018,11 @@ export function fallbackRetryDelayMs(attemptIndex: number): number {
 
 /** Sleeps until the delay expires or the request is aborted. */
 export function sleep(ms: number, signal: AbortSignal): Promise<void> {
-  if (signal.aborted) return Promise.reject(new GatewayError("transport_closed", 499, "request was cancelled"));
+  if (signal.aborted) return Promise.reject(new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃"));
   if (ms <= 0) return Promise.resolve();
   const { promise, resolve, reject } = Promise.withResolvers<void>();
   const timer = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve(); }, ms);
-  const onAbort = () => { clearTimeout(timer); reject(new GatewayError("transport_closed", 499, "request was cancelled")); };
+  const onAbort = () => { clearTimeout(timer); reject(new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃")); };
   signal.addEventListener("abort", onAbort, { once: true });
   return promise;
 }

package/src/transport/guards/auth-guard.ts

@@ -62,9 +62,9 @@ export function createApiKeyAuthenticationMiddleware(deps: {
         safe.name = error instanceof Error ? error.name : "Error";
         log.error("[auth] key lookup failed; treating as unavailable", safe);
         throw new GatewayError(
-          "accounts_unavailable",
+          "admission_unavailable",
           503,
-          "The gateway could not verify this API key because its credential store is unavailable. Retry shortly.",
+          "The gateway could not verify this API key because its credential store is unavailable (request {requestId}). Retry shortly. The bouncer stepped out — come back shortly 🚪",
           {},
           "cartethyia",
         );
@@ -76,7 +76,7 @@ export function createApiKeyAuthenticationMiddleware(deps: {
         scopes: authorization.scopes,
       });
       if (!decision.scopes.includes("routing:invoke"))
-        throw new GatewayError("invalid_request", 403, "This API key is not allowed to invoke routing. Grant it the routing:invoke scope, or use a key that has it.");
+        throw new GatewayError("policy_rejected", 403, "This API key is not allowed to invoke routing (request {requestId}). Grant it the routing:invoke scope, or use a key that has it. Not allowed by policy — no hard feelings 🫂");
       // Kill switch: refuse before any upstream is touched. Distinct from the
       // scope check above, which is a property of the key — this is the tenant
       // having stopped all traffic, and it applies to every key the tenant owns.
@@ -86,7 +86,8 @@ export function createApiKeyAuthenticationMiddleware(deps: {
         throw new GatewayError(
           "platform_unavailable",
           503,
-          "This gateway has invoke switched off. Nothing upstream is being dialed while the switch is off; turn it back on from the dashboard overview to resume routing.",
+          "This gateway has invoke switched off (request {requestId}). Nothing upstream is being dialed while the switch is off; turn it back on from the dashboard overview to resume routing. Flip the switch back on when ready 🔌",
+          { reason: "invoke_switched_off" },
         );
       // A key may refuse a downstream router it has been resold to. This is a
       // policy check on the resolved key, so it belongs with the other
@@ -100,7 +101,7 @@ export function createApiKeyAuthenticationMiddleware(deps: {
         throw new GatewayError(
           "client_router_denied",
           403,
-          "No API invocation access for this client.",
+          "No API invocation access for this client (request {requestId}). This router isn't on the guest list — denied, but politely 🤗",
           { reason: "client_router_denied", clientRouter: denied },
         );
       deps.stateStore.require(request).authorization = authorization;

package/src/transport/guards/body-policy.ts

@@ -77,11 +77,11 @@ export async function readIngressBody(
   const isJsonRoute = isJsonProxyRoute(p);
   const contentType = request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
   if (!contentType) {
-    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, "This endpoint reads JSON, so the request needs a content-type: application/json header.");
+    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, "This endpoint reads JSON, so the request needs a content-type: application/json header (request {requestId}). We speak JSON here — send JSON 💬");
     return undefined;
   }
   if (contentType !== "application/json") {
-    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, `This endpoint reads JSON and cannot parse '${contentType}'. Send content-type: application/json.`);
+    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, `This endpoint reads JSON and cannot parse '${contentType}' (request {requestId}). Send content-type: application/json. We speak JSON here — send JSON 💬`);
     return undefined;
   }
   const maxBytes = options.maxBodyBytes ?? 1_048_576;
@@ -91,7 +91,7 @@ export async function readIngressBody(
     throw bodyTooLargeError(maxBytes);
 
   const reader = request.body?.getReader();
-  if (!reader) throw new GatewayError("invalid_request", 400, "The request body could not be read. Resend it with a JSON body.");
+  if (!reader) throw new GatewayError("invalid_request", 400, "The request body could not be read (request {requestId}). Resend it with a JSON body. Check the shape of what you sent — then resend 🪞");
   // Collect raw chunks then decode once. String `+=` on each chunk reallocates
   // the accumulating UTF-16 string (O(n²) for large Claude Code prompts);
   // Buffer.concat + one TextDecoder pass is linear and allocation-stable.
@@ -126,7 +126,7 @@ export async function readIngressBody(
     return body;
   } catch (error) {
     if (error instanceof GatewayError) throw error;
-    throw new GatewayError("invalid_request", 400, "The request body is not valid JSON. Check for a trailing comma or an unclosed brace.");
+    throw new GatewayError("invalid_request", 400, "The request body is not valid JSON (request {requestId}). Check for a trailing comma or an unclosed brace. Check the shape of what you sent — then resend 🪞");
   }
 }
 

package/src/transport/guards/error-lifecycle.ts

@@ -49,6 +49,18 @@ function retryAfterSeconds(error: GatewayError | undefined): string | undefined
   return undefined;
 }
 
+/**
+ * Ensures a public message carries the request id. Builders write a
+ * `{requestId}` placeholder in the lead (the canonical convention); anything
+ * that predates the convention gets the id appended so every client-visible
+ * message is correlatable to the server log.
+ */
+function applyRequestId(message: string, requestId: string): string {
+  if (message.includes("{requestId}")) return message.replaceAll("{requestId}", requestId);
+  if (message.includes("(request ")) return message;
+  return `${message} (request ${requestId})`;
+}
+
 /**
  * Normalizes every thrown error (from any lifecycle hook or handler, on
  * `/v1/*` or `/console/api/*`) into the stable public `{ error: { code,
@@ -81,7 +93,8 @@ export function createErrorNormalizationMiddleware(deps: {
         gateway?.status ?? builtinStatus ?? (isBuiltinError || isInputError ? 400 : 500);
       const code =
         gateway?.code ?? builtinCode ?? (isBuiltinError || isInputError ? "invalid_request" : "internal_error");
-      const message =
+      const requestId = state?.requestId ?? crypto.randomUUID();
+      const rawMessage =
         gateway !== undefined
           ? explainGatewayError(gateway)
           : isInputError && error instanceof Error
@@ -90,8 +103,9 @@ export function createErrorNormalizationMiddleware(deps: {
                 code,
                 isBuiltinError
                   ? builtin?.message ?? "Unable to process the request as written."
-                  : "The gateway hit an internal error. Retry; if it persists, the server logs carry the request id.",
+                  : "The gateway hit an internal error. Retry; if it persists, quote the request id to support. Even we have bad days — retry, and quote the id if it persists 🐻",
               );
+      const message = applyRequestId(rawMessage, requestId);
       const origin = gateway?.origin ?? "cartethyia";
       // `afterResponse` telemetry hook can enqueue it even when the request
       // never reached canonical parse / auth / preparation.
@@ -108,7 +122,7 @@ export function createErrorNormalizationMiddleware(deps: {
       if (!state?.canonicalRequest && !state?.authorization)
         metrics.proxy_requests_total.inc(1, { status: "rejected" });
       set.headers["cache-control"] = "no-store";
-      set.headers["x-request-id"] = state?.requestId ?? crypto.randomUUID();
+      set.headers["x-request-id"] = requestId;
       Object.assign(set.headers, GATEWAY_SECURITY_HEADERS);
       if (deps.hsts) set.headers["strict-transport-security"] = "max-age=31536000";
       set.status = status;
@@ -128,6 +142,7 @@ export function createErrorNormalizationMiddleware(deps: {
         error: {
           origin,
           code,
+          requestId,
           message,
           ...(gateway
             ? { details: publicGatewayErrorDetails(gateway) }

package/src/transport/guards/guard-errors.ts

@@ -8,15 +8,19 @@ import { GatewayError } from "../../protocol/gateway-error";
 
 /** Thrown when the request's client peer address cannot be established. */
 export function peerAddressUnavailableError(): GatewayError {
-  return new GatewayError("admission_unavailable", 503, "client peer address unavailable");
+  return new GatewayError(
+    "admission_unavailable",
+    503,
+    "client peer address unavailable (request {requestId}). We couldn't see who's knocking — retry 🚪",
+  );
 }
 
 /** Thrown when the request body exceeds the endpoint's byte budget. */
 export function bodyTooLargeError(maxBytes: number): GatewayError {
   return new GatewayError(
-    "invalid_request",
+    "request_too_large",
     413,
-    `The request body is larger than this endpoint accepts (${maxBytes} bytes). Shorten the prompt or split the request.`,
+    `The request body is larger than this endpoint accepts (${maxBytes} bytes) (request {requestId}). Shorten the prompt or split the request. We love long reads, but not that long 📚`,
   );
 }
 

package/src/transport/guards/headroom-guard.ts

@@ -90,7 +90,7 @@ export function createHeadroomGuard(deps: HeadroomGuardDeps): Elysia {
       throw new GatewayError(
         "overloaded",
         503,
-        "The gateway is at capacity; retry shortly.",
+        "The gateway is at capacity (request {requestId}); retry shortly. It's not you, it's us — come back in a few minutes ☕️",
         {
           retryAfterMs: SHED_RETRY_MS,
           minFreeBytes: headroom,