cartethyia 2.7.3 → 2.7.4

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,

package/src/transport/guards/pipeline.ts

@@ -1,4 +1,4 @@
-import { Elysia } from "elysia";
+import { Elysia, type AnyElysia } from "elysia";
 import { createIngressPolicyMiddleware } from "./body-policy";
 import {
   createCanonicalRequestMiddleware,
@@ -81,9 +81,9 @@ export interface TransportPipelineContext {
  */
 export interface TransportPipeline {
   /** Applies root-scoped request context and error normalization. */
-  mountRoot(app: Elysia<any, any, any, any, any, any, any, any>): void;
+  mountRoot(app: AnyElysia): void;
   /** Builds the complete `/v1/*` gateway plugin around registered routes. */
-  createGateway(registerRoutes: (routes: Elysia<any, any, any, any, any, any, any, any>) => void): Elysia;
+  createGateway(registerRoutes: (routes: AnyElysia) => void): Elysia;
 }
 
 /**
@@ -129,7 +129,7 @@ export function createTransportPipeline(context: TransportPipelineContext): Tran
       preparer: context.preparer,
     }),
   ];
-  const mountRoot = (app: Elysia<any, any, any, any, any, any, any, any>): void => {
+  const mountRoot = (app: AnyElysia): void => {
     app.use(
       createRequestContextMiddleware({
         stateStore: context.stateStore,
@@ -205,8 +205,8 @@ export function createTransportPipeline(context: TransportPipelineContext): Tran
     }
   };
   const createGateway = (
-    registerRoutes: (routes: Elysia<any, any, any, any, any, any, any, any>) => void,
-  ): Elysia<any, any, any, any, any, any, any, any> => {
+    registerRoutes: (routes: AnyElysia) => void,
+  ): AnyElysia => {
     const gateway = new Elysia({ prefix: "/v1" });
     for (const plugin of stages) gateway.use(plugin);
     // No telemetry/cleanup registration here: the lifecycle is owned by

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

@@ -21,8 +21,22 @@ export function createDependencyReadinessMiddleware(deps: ReadinessMiddlewareDep
         throw new GatewayError(notice.code, 503, notice.message);
       }
       const readiness = await deps.readiness();
-      if (readiness.status !== "ready")
-        throw new GatewayError("platform_unavailable", 503, "The gateway's dependencies are not ready, so no request can be served. Retry shortly; if it persists, check the database and coordination backend.");
+      if (readiness.status !== "ready") {
+        // A probe that timed out under load says nothing about the dependencies —
+        // it could not get a backend in time, usually because the process is
+        // saturated. Surface that as overload, not as a broken dependency. A
+        // hard failure (connection refused, migrations missing) keeps the
+        // dependency message, which tells the operator what to actually fix.
+        if (readiness.reason?.endsWith("timed out")) {
+          throw new GatewayError(
+            "overloaded",
+            503,
+            "The gateway is overloaded (request {requestId}); retry shortly. It's not you, it's us — back in a moment ☕️",
+            { retryAfterMs: 1_000 },
+          );
+        }
+        throw new GatewayError("platform_unavailable", 503, "The gateway's dependencies are not ready, so no request can be served (request {requestId}). Retry shortly; if it persists, check the database and coordination backend. Warming up — back in a moment ☕️");
+      }
     })
     .as("plugin");
 }

package/src/transport/guards/request-context.ts

@@ -159,7 +159,7 @@ export function createCanonicalRequestMiddleware(deps: {
       // literal `null` body) is a valid single-read value and flows to the
       // surface adapter's parse error rather than triggering a second read.
       if (state.ingressBody === undefined)
-        throw new GatewayError("admission_unavailable", 503, "The request body was never read, so this route cannot be served. Resend the request.");
+        throw new GatewayError("route_unavailable", 503, "The request body was never read, so this route cannot be served (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");
       const body = state.ingressBody;
       const headers: Record<string, string> = {};
       request.headers.forEach((value, key) => {
@@ -192,7 +192,7 @@ export function createCanonicalRequestMiddleware(deps: {
         throw new GatewayError(
           "capability_unsupported",
           400,
-          `Surface adapter unavailable: ${detection.surface}`,
+          `Surface adapter unavailable: ${detection.surface} (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
           { surface: detection.surface },
         );
       const ingress = deps.stateStore.require(request);
@@ -224,7 +224,7 @@ export function createProxyRoutePreparationMiddleware(deps: {
       if (!isJsonRoute || path === "/v1/responses/compact" || isOpaqueBodyRoute(path)) return;
       const state = deps.stateStore.require(request);
       if (!state.authorization || !state.canonicalRequest)
-        throw new GatewayError("admission_unavailable", 503, "The request was not authenticated and parsed, so this route cannot be served. Resend the request.");
+        throw new GatewayError("route_unavailable", 503, "The request was not authenticated and parsed, so this route cannot be served (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");
       // The key rides along so a strike is charged to the caller that made it.
       // Without it, one recipient of a shared link could escalate a ban onto
       try {

package/src/transport/request/preparer.ts

@@ -101,7 +101,7 @@ export function resolveContinuationAffinity(
       throw new GatewayError(
         "invalid_request",
         400,
-        "These tool results belong to different Cursor accounts; resend them one account at a time.",
+        "These tool results belong to different Cursor accounts (request {requestId}); resend them one account at a time. The session went cold — reconnect or resend 🔌",
         { callIds: [...ids] },
       );
     }
@@ -189,9 +189,9 @@ export class ProxyRequestPreparer {
   }): Promise<PreparedProxyRequest> {
     const { canonicalRequest: initialRequest, authorization, signal } = input;
     if (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 🙃");
     if (!initialRequest.model || initialRequest.model.trim().length === 0) {
-      throw new GatewayError("invalid_request", 400, "Request requires a non-empty model identifier", {
+      throw new GatewayError("invalid_request", 400, "Request requires a non-empty model identifier (request {requestId}). Check the shape of what you sent — then resend 🪞", {
         field: "model",
       });
     }
@@ -242,13 +242,13 @@ export class ProxyRequestPreparer {
       !allowedForKey
     )
       throw new GatewayError(
-        "model_not_found",
-        404,
-        `This key may only use models starting with '${authorization.modelPrefix}'. Ask for one inside that prefix, or have an operator widen the key.`,
+        "model_not_allowed",
+        403,
+        `This key may only use models starting with '${authorization.modelPrefix}' (request {requestId}). Ask for one inside that prefix, or have an operator widen the key. The door's locked for this one — check the allowlist 🔒`,
         { model: request.model, required_prefix: authorization.modelPrefix },
       );
     if (!allowedForKey) {
-      throw new GatewayError("model_not_found", 404, "model is not allowed for this API key", {
+      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
         model: request.model,
       });
     }
@@ -307,7 +307,7 @@ export class ProxyRequestPreparer {
       throw new GatewayError(
         "capability_unsupported",
         400,
-        "no eligible route supports this request's capabilities",
+        "no eligible route supports this request's capabilities (request {requestId}). Drop the unsupported capability, or route to a model that accepts it. Know your tools — this one just isn't in the box 🧰",
         { model: request.model },
       );
     const policyCandidates = plan.candidates.filter((candidate) =>
@@ -319,7 +319,7 @@ export class ProxyRequestPreparer {
       ),
     );
     if (policyCandidates.length === 0)
-      throw new GatewayError("model_not_found", 404, "model is not allowed for this API key", {
+      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
         model: request.model,
       });
     if (policyCandidates.length !== plan.candidates.length)
@@ -341,7 +341,7 @@ export class ProxyRequestPreparer {
       throw new GatewayError(
         "capability_unsupported",
         400,
-        `this model is not served on a chat wire — it is a '${kind}' service model${route === undefined ? "" : `; call it at POST ${route}`}`,
+        `this model is not served on a chat wire — it is a '${kind}' service model${route === undefined ? "" : `; call it at POST ${route}`} (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
         { model: request.model, service_kind: kind, ...(route === undefined ? {} : { route }) },
       );
     }
@@ -366,7 +366,7 @@ export class ProxyRequestPreparer {
       }
     }
     if (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 🙃");
     const eligible = plan.candidates;
     // The buddy gateway rejects partial tool rounds outright (`11148`) where
     // the generic synthesis policy would insert a placeholder result, so a
@@ -401,7 +401,7 @@ export class ProxyRequestPreparer {
       effectiveRequest = sanitizeRequestToolIds(effectiveRequest);
     }
     if (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 🙃");
     // Project against the chosen candidate, not the intersection of every
     // candidate in the plan. Still required for generation-control stripping
     // even on the no-tools path — keep it, but it is cheap vs message clones.
@@ -448,7 +448,7 @@ export class ProxyRequestPreparer {
     readonly emptyMessage: string;
   }): Promise<PreparedNativeRequest> {
     if (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 🙃");
     const snapshot = await this.deps.snapshotService.getSnapshot();
     const allowCliMappings = allowsCliToolMappings(input.authorization.scopes, {
       ...(input.clientUserAgent === undefined ? {} : { userAgent: input.clientUserAgent }),
@@ -473,13 +473,13 @@ export class ProxyRequestPreparer {
       !allowedForKey
     )
       throw new GatewayError(
-        "model_not_found",
-        404,
-        `This key may only use models starting with '${input.authorization.modelPrefix}'. Ask for one inside that prefix, or have an operator widen the key.`,
+        "model_not_allowed",
+        403,
+        `This key may only use models starting with '${input.authorization.modelPrefix}' (request {requestId}). Ask for one inside that prefix, or have an operator widen the key. The door's locked for this one — check the allowlist 🔒`,
         { model: input.model, required_prefix: input.authorization.modelPrefix },
       );
     if (!allowedForKey)
-      throw new GatewayError("model_not_found", 404, "model is not allowed for this API key", {
+      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
         model: input.model,
       });
     const plan = await this.deps.routingEngine.plan(
@@ -491,7 +491,7 @@ export class ProxyRequestPreparer {
       input.authorization.cliMappingOwnerId ?? input.authorization.id,
     );
     if (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 🙃");
     const policyCandidates = plan.candidates.filter((candidate) =>
       isModelAllowed(
         input.authorization.snapshot,
@@ -501,12 +501,12 @@ export class ProxyRequestPreparer {
       ),
     );
     if (policyCandidates.length === 0)
-      throw new GatewayError("model_not_found", 404, "model is not allowed for this API key", {
+      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
         model: input.model,
       });
     const candidates = policyCandidates.filter(input.eligible);
     if (candidates.length === 0)
-      throw new GatewayError("capability_unsupported", 400, input.emptyMessage, {
+      throw new GatewayError("capability_unsupported", 400, `${input.emptyMessage} (request {requestId}). Know your tools — this one just isn't in the box 🧰`, {
         model: input.model,
       });
     return {

package/src/transport/request/state.ts

@@ -191,15 +191,12 @@ function subscribeInFlightSnapshot(
   store: { inFlightSnapshot(): InFlightSnapshot },
   listener: (snapshot: InFlightSnapshot) => void,
 ): () => void {
-  const timers = new Set<ReturnType<typeof setTimeout>>();
   const push = (): void => listener(store.inFlightSnapshot());
   push();
   const handle = setInterval(push, 1_000);
   (handle as unknown as { unref?: () => void })?.unref?.();
   return () => {
     clearInterval(handle);
-    for (const t of timers) clearTimeout(t);
-    timers.clear();
   };
 }
 
@@ -259,7 +256,7 @@ export class ProxyRequestStateStore {
       try {
         if (controller && !controller.signal.aborted) {
           controller.abort(
-            new GatewayError("deadline_exceeded", 504, "in-flight request exceeded its deadline"),
+            new GatewayError("deadline_exceeded", 504, "in-flight request exceeded its deadline (request {requestId}). Some things just take longer 🐢"),
           );
         }
       } catch {
@@ -292,7 +289,7 @@ export class ProxyRequestStateStore {
     const abortReason =
       reason instanceof Error || reason instanceof DOMException
         ? reason
-        : new GatewayError("shutting_down", 503, "The gateway is shutting down, so this request cannot be served. Retry against a live instance.");
+        : new GatewayError("shutting_down", 503, "The gateway is shutting down, so this request cannot be served (request {requestId}). Retry against a live instance. Maintenance mode — back in a minute 🧘");
     for (const controller of controllers) {
       try {
         if (!controller.signal.aborted) controller.abort(abortReason);
@@ -330,7 +327,7 @@ export class ProxyRequestStateStore {
           new GatewayError(
             "deadline_exceeded",
             504,
-            "request deadline exceeded",
+            "request deadline exceeded (request {requestId}). Some things just take longer 🐢",
             {},
             "cartethyia",
           ),
@@ -418,7 +415,7 @@ export class ProxyRequestStateStore {
   require(request: Request): ProxyRequestState {
     const state = this.states.get(request);
     if (!state)
-      throw new GatewayError("admission_unavailable", 503, "The request was never registered, so it cannot be served. Resend the request.");
+      throw new GatewayError("route_unavailable", 503, "The request was never registered, so it cannot be served (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");
     return state;
   }
 

package/src/transport/routing/route-catalog.ts

@@ -10,6 +10,7 @@ import {
   networkPools,
   poolRoutingSettings,
   providerAccounts,
+  providerPoolAccounts,
   providerRoutingSettings,
   providers,
   tenantDisabledModels,
@@ -372,6 +373,17 @@ const POOL_COLUMNS = {
   weight: networkPools.weight,
 } as const;
 
+const POOL_ACCOUNT_COLUMNS = {
+  id: providerPoolAccounts.id,
+  tenantId: providerPoolAccounts.tenantId,
+  networkPoolId: providerPoolAccounts.networkPoolId,
+  providerId: providerPoolAccounts.providerId,
+  label: providerPoolAccounts.label,
+  status: providerPoolAccounts.status,
+  cooldownUntil: providerPoolAccounts.cooldownUntil,
+  lastErrorCategory: providerPoolAccounts.lastErrorCategory,
+} as const;
+
 const DISABLED_MODEL_COLUMNS = {
   tenantId: tenantDisabledModels.tenantId,
   providerId: tenantDisabledModels.providerId,
@@ -414,7 +426,7 @@ class RouteCatalogRepository {
   constructor(private readonly db: CartethyiaDatabase) {}
 
   async loadRouteCatalogSnapshot(tenantId?: string): Promise<RouteCatalogSnapshotResult> {
-    const [providerRows, modelRows, accountRows, aliasRows, comboRows, routingRows, poolRows, disabledModelRows, cliMappingRows, cliMappingSettingRows, poolSettingRows, settingsRows] =
+    const [providerRows, modelRows, accountRows, aliasRows, comboRows, routingRows, poolRows, poolAccountRows, disabledModelRows, cliMappingRows, cliMappingSettingRows, poolSettingRows, settingsRows] =
       await Promise.all([
         this.db.select(PROVIDER_COLUMNS).from(providers).where(eq(providers.enabled, true)),
         this.db.select(MODEL_COLUMNS).from(models),
@@ -427,6 +439,7 @@ class RouteCatalogRepository {
         this.db.select(COMBO_COLUMNS).from(modelCombos),
         this.db.select(ROUTING_COLUMNS).from(providerRoutingSettings),
         this.db.select(POOL_COLUMNS).from(networkPools),
+        this.db.select(POOL_ACCOUNT_COLUMNS).from(providerPoolAccounts),
         this.db.select(DISABLED_MODEL_COLUMNS).from(tenantDisabledModels),
         this.db.select(CLI_MAPPING_COLUMNS).from(cliToolMappings),
         this.db.select(CLI_MAPPING_SETTING_COLUMNS).from(cliToolSettings),
@@ -500,6 +513,28 @@ class RouteCatalogRepository {
       activePoolsByTenant.set(pool.tenantId, list);
     }
 
+    // Pool-as-account rows, grouped by tenant: one per (pool × ip-scoped
+    // provider). For a credential-less ip-scoped provider these are the
+    // account-equivalent routing entities — a spent egress is excluded from
+    // the plan exactly like a cooling account, and the candidate carries the
+    // pool-account's health (see the public-candidate fan-out below).
+    const poolAccountsByTenant = new Map<
+      string,
+      Array<{
+        id: string;
+        networkPoolId: string;
+        providerId: string;
+        status: string;
+        cooldownUntil: Date | null;
+        lastErrorCategory: string | null;
+      }>
+    >();
+    for (const poolAccount of poolAccountRows) {
+      const list = poolAccountsByTenant.get(poolAccount.tenantId) ?? [];
+      list.push(poolAccount);
+      poolAccountsByTenant.set(poolAccount.tenantId, list);
+    }
+
     // Per-tenant pool selection strategy; an absent row reads as the
     // `least_loaded` default at selection time.
     const poolRouting: Record<string, PoolRoutingSetting> = {};
@@ -657,7 +692,67 @@ class RouteCatalogRepository {
       if (accounts.length === 0) {
         const providerRequiresAccount = requiresAccountById.get(model.providerId) ?? true;
         if (!providerRequiresAccount) {
-          // Public models inherit active pools for each tenant that has active pools
+          // Public models inherit active pools for each tenant that has active pools.
+          // When the provider is ip-scoped (limits follow the egress address), the
+          // tenant's pool-account rows are the account-equivalent routing entities:
+          // one candidate per pool, carrying that pool-account's health, so a spent
+          // egress is excluded from the plan exactly like a cooling account.
+          const ownedTenantIds = [...poolAccountsByTenant.keys()].filter((tid) =>
+            (poolAccountsByTenant.get(tid) ?? []).some((pa) => pa.providerId === model.providerId),
+          );
+          let emittedPoolAccount = false;
+          for (const tenantOwnerId of ownedTenantIds) {
+            const poolAccounts = poolAccountsByTenant.get(tenantOwnerId) ?? [];
+            const tenantPoolAccounts = new Map<string, typeof poolAccounts>();
+            for (const pa of poolAccounts) {
+              if (pa.providerId !== model.providerId) continue;
+              const list = tenantPoolAccounts.get(pa.networkPoolId) ?? [];
+              list.push(pa);
+              tenantPoolAccounts.set(pa.networkPoolId, list);
+            }
+            if (tenantPoolAccounts.size === 0) continue;
+            for (const [poolId, pas] of tenantPoolAccounts) {
+              const first = pas[0];
+              if (!first) continue;
+              const tenantPools = resolveNetworkPools(model.providerId, tenantOwnerId);
+              if (!tenantPools) continue;
+              emittedPoolAccount = true;
+              const tenantCandidate: RouteCandidateWithHealth = {
+                provider_id: model.providerId,
+                model_id: model.modelId,
+                wire_family: model.wireFamily as WireFamily,
+                service_kind: model.serviceKind,
+                endpoint: model.endpointPath,
+                ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
+                capability_profile: capabilityProfile,
+                tenant_id: tenantOwnerId,
+                // Public credential-less candidates have no account to own them.
+                owner_tenant_id: null,
+                requires_account: false as const,
+                network_pool_ids: [poolId],
+                network_pool_required: true,
+                network_pool_limits: tenantPools.limits,
+                network_pool_weights: tenantPools.weights,
+                ...(tenantPools.routing ? { network_pool_routing: tenantPools.routing } : {}),
+                ...providerLimitFor(model.providerId, tenantOwnerId),
+                ...(first.status === "disabled"
+                  ? { health_status: "disabled" as const }
+                  : first.status === "cooldown"
+                    ? {
+                        health_status: "cooldown" as const,
+                        cooldown_kind: hardCooldownCategory(first.lastErrorCategory) ? "hard" : "soft",
+                        ...(first.cooldownUntil && first.cooldownUntil.getTime() > Date.now()
+                          ? { cooldown_until: first.cooldownUntil.getTime() }
+                          : {}),
+                      }
+                    : {}),
+              };
+              if (tenantId === undefined || tenantId === tenantOwnerId) {
+                candidates.push(tenantCandidate);
+              }
+            }
+          }
+          if (emittedPoolAccount) continue;
           for (const tId of configuredPoolTenants) {
             const tenantPools = resolveNetworkPools(model.providerId, tId);
             if (tenantPools) {

package/src/transport/routing/route-model.ts

@@ -358,7 +358,7 @@ export function ambiguousModelError(bare: string, owners: string[]): GatewayErro
   return new GatewayError(
     "ambiguous_model",
     400,
-    `'${bare}' matches more than one provider (${owners.join(", ")}). Qualify it as '${owners[0]}/${bare}', or add an alias to pick one.`,
+    `'${bare}' matches more than one provider (${owners.join(", ")}). Qualify it as '${owners[0]}/${bare}', or add an alias to pick one. Too popular for its own good — qualify it 🧩`,
     {
       model: bare,
       owners,
@@ -380,7 +380,7 @@ export function modelNotFoundError(requested: string, resolved: readonly string[
     404,
     `'${requested}' is not routed${
       targets.length > 0 ? ` — it resolved to ${hint}, which no account serves` : ""
-    }. Enable the model on an account, or point the alias at one that exists.`,
+    } (request {requestId}). Enable the model on an account, or point the alias at one that exists. Try another model — this one's off the menu 📚`,
     {
       model: requested,
       ...(targets.length > 0 ? { resolved_models: targets } : {}),
@@ -392,7 +392,7 @@ export function capabilityUnsupportedError(capability: string): GatewayError {
   return new GatewayError(
     "capability_unsupported",
     400,
-    `No account serving this model supports ${capability}. Drop the ${capability} part of the request, or route to a model that accepts it.`,
+    `No account serving this model supports ${capability} (request {requestId}). Drop the ${capability} part of the request, or route to a model that accepts it. Know your tools — this one just isn't in the box 🧰`,
     { capability },
   );
 }
@@ -424,8 +424,8 @@ export function capacityExhaustedError(context?: {
     "provider_capacity_exhausted",
     429,
     onlyOne
-      ? "The only account routing this model is at its concurrency limit. Retry shortly; if it persists, raise the provider's max-inflight or add another account."
-      : "Every account is at its concurrency limit. Retry shortly; if it persists, raise the provider's max-inflight or add an account.",
+      ? "The only account routing this model is at its concurrency limit (request {requestId}). Retry shortly; if it persists, raise the provider's max-inflight or add another account. Even the machine needs a rest — chill 🦋"
+      : "Every account is at its concurrency limit (request {requestId}). Retry shortly; if it persists, raise the provider's max-inflight or add an account. Even the machine needs a rest — chill 🦋",
     {
       ...(context?.providerId !== undefined ? { providerId: context.providerId } : {}),
       ...(context?.model !== undefined ? { model: context.model } : {}),
@@ -456,7 +456,7 @@ export function accountsUnavailableError(
   return new GatewayError(
     "accounts_unavailable",
     503,
-    `No account in the pool can serve '${requested}' right now (${explainEligibilityReasons(distinct)}). Add an account, or wait for an operator to re-enable one.`,
+    `No account in the pool can serve '${requested}' right now (request {requestId}) (${explainEligibilityReasons(distinct)}). Add an account, or wait for an operator to re-enable one. Every account is on a coffee break — try later ☕️`,
     { model: requested, reasons: distinct, candidate_count: reasons.length, gateway_hint: "no_healthy_account" },
   );
 }
@@ -492,7 +492,7 @@ export function accountsRateLimitedError(
   return new GatewayError(
     "accounts_rate_limited",
     429,
-    `Every account serving '${requested}'${routeNote} is cooling down after hitting upstream limits. The request is fine — retry once the cooldown resets.`,
+    `Every account serving '${requested}'${routeNote} is cooling down after hitting upstream limits (request {requestId}). The request is fine — retry once the cooldown resets. They're resting up 🌸`,
     {
       model: requested,
       routed_model: routed,

package/src/transport/routing/router.ts

@@ -624,7 +624,7 @@ export class RoutingEngine {
       throw new GatewayError(
         "invalid_request",
         400,
-        "This tool result belongs to a Cursor account that is no longer routable. Reconnect the account, or resend the complete conversation.",
+        "This tool result belongs to a Cursor account that is no longer routable (request {requestId}). Reconnect the account, or resend the complete conversation. The session went cold — reconnect or resend 🔌",
         {
           providerId: affinity.providerId,
           accountId: affinity.providerAccountId,
@@ -652,7 +652,7 @@ export class RoutingEngine {
       throw new GatewayError(
         "invalid_request",
         400,
-        "This tool result belongs to an account that is no longer routable. Reconnect the account, or resend the complete conversation.",
+        "This tool result belongs to an account that is no longer routable (request {requestId}). Reconnect the account, or resend the complete conversation. The session went cold — reconnect or resend 🔌",
         {
           providerId: affinity.providerId,
           accountId: affinity.providerAccountId,

package/src/transport/shutdown-notice.ts

@@ -16,8 +16,9 @@
 import { GatewayError, type GatewayErrorCode } from "../protocol/gateway-error";
 
 export interface ShutdownNotice {
-  readonly code: Extract<GatewayErrorCode, "shutting_down" | "restart_for_update">;
+  readonly code: Extract<GatewayErrorCode, "shutting_down">;
   readonly message: string;
+  readonly reason?: string;
 }
 
 /**
@@ -30,9 +31,17 @@ export const UPDATE_SHUTDOWN_REASON = "update";
 
 export function shutdownNotice(reason: string | undefined): ShutdownNotice {
   if (reason === UPDATE_SHUTDOWN_REASON) {
-    return { code: "restart_for_update", message: "system will be back in a minute" };
+    return {
+      code: "shutting_down",
+      message:
+        "Service is shutting down for an update; it will be back in about a minute (request {requestId}). Maintenance mode — back in a minute 🧘",
+      reason: "restart_for_update",
+    };
   }
-  return { code: "shutting_down", message: "Service is shutting down" };
+  return {
+    code: "shutting_down",
+    message: "Service is shutting down (request {requestId}). Come back shortly 🧘",
+  };
 }
 
 /**
@@ -47,7 +56,12 @@ export function shutdownNotice(reason: string | undefined): ShutdownNotice {
  */
 export function shutdownError(reason: string | undefined): GatewayError {
   const notice = shutdownNotice(reason);
-  return new GatewayError(notice.code, 503, notice.message);
+  return new GatewayError(
+    notice.code,
+    503,
+    notice.message,
+    notice.reason === undefined ? {} : { reason: notice.reason },
+  );
 }
 
 /**
@@ -62,7 +76,5 @@ export function shutdownError(reason: string | undefined): GatewayError {
  */
 export function drainAbortReason(reason: unknown): GatewayError | undefined {
   if (!(reason instanceof GatewayError)) return undefined;
-  return reason.code === "shutting_down" || reason.code === "restart_for_update"
-    ? reason
-    : undefined;
+  return reason.code === "shutting_down" ? reason : undefined;
 }

package/src/transport/surface/completion.ts

@@ -166,7 +166,7 @@ export class CompletionAdapter implements SurfaceAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        "completion requests require a non-empty prompt",
+        "completion requests require a non-empty prompt (request {requestId}). Check the shape of what you sent — then resend 🪞",
       );
     const controls: GenerationControls = {};
     for (const field of ["temperature", "top_p", "n", "seed"] as const)