cartethyia 2.7.2 → 2.7.4

package/src/providers/operations/client-versions.ts

@@ -46,6 +46,17 @@ async function traeVersion(response: Response): Promise<string | null> {
       /"insert":"((?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2},\s*\d{4}\s*\([^)]*\))\\n"/g;
     for (const match of text.matchAll(heading)) {
       const window = text.slice(match.index ?? 0, (match.index ?? 0) + 900);
+      // A release line may name a *range* ("TRAE v3.6.1 ~ 3.6.4 are released"),
+      // and the newest entry is the newest build in it. Taking the first number
+      // reported 3.6.1 while 3.6.4 was already shipping — and on an entry whose
+      // heading carried no version at all the old pattern matched nothing, so
+      // discovery fell through to the next (older) entry and the pin drifted
+      // backwards on every refresh.
+      const range = window.match(/(\d+\.\d+\.\d+)\s*[~–-]\s*(\d+\.\d+\.\d+)/);
+      if (range) {
+        const high = range[2] ?? range[1];
+        if (high && isSemverish(high)) return high.trim();
+      }
       const found = window.match(/TraeCode\s+v?(\d+\.\d+\.\d+)|v?(\d+\.\d+\.\d+)\s+is\s+released/i);
       const version = found?.[1] ?? found?.[2];
       if (version && isSemverish(version)) return version.trim();
@@ -221,7 +232,7 @@ const KIRO_NODE_VERSION = "24.18.0";
 export const VERSION_SOURCES = {
   antigravity: {
     key: "antigravity",
-    fallback: "2.24.0",
+    fallback: "2.28.2",
     sources: [
       {
         url: "https://antigravity-hub-auto-updater-974169037036.us-central1.run.app/manifest/latest-arm64-mac.yml",
@@ -231,7 +242,7 @@ export const VERSION_SOURCES = {
   },
   qoder: {
     key: "qoder",
-    fallback: "1.1.74",
+    fallback: "1.1.81",
     sources: [
       {
         url: "https://registry.npmjs.org/@qoder-ai/qodercli/latest",
@@ -243,18 +254,21 @@ export const VERSION_SOURCES = {
     key: "opencode",
     // The v1 package (`opencode-ai`) stopped at 1.18. The v2 line publishes
     // under `@opencode/cli`, and this feed is what its own installer reads.
-    fallback: "2.0.32",
+    fallback: "2.2.2",
     minVersion: "2.0.0",
     sources: [{ url: "https://opencode.ai/update/api/latest/cli/npm" }],
   },
   commandcode: {
     key: "commandcode",
-    fallback: "1.84.0",
+    // npm `command-code` latest as of 2026-10-30. The CLI sends this as
+    // `x-command-code-version`, so a stale fallback presents a client build
+    // the upstream no longer ships — raise it whenever the package moves.
+    fallback: "1.88.2",
     sources: [{ url: "https://registry.npmjs.org/command-code/latest" }],
   },
   grok: {
     key: "grok",
-    fallback: "1.0.62",
+    fallback: "1.0.70",
     sources: [
       { url: "https://storage.googleapis.com/grok-build-public-artifacts/cli/stable" },
       { url: "https://registry.npmjs.org/@xai-official/grok/latest" },
@@ -262,7 +276,7 @@ export const VERSION_SOURCES = {
   },
   clineClient: {
     key: "cline-client",
-    fallback: "4.1.25",
+    fallback: "4.1.26",
     minVersion: "4.1.23",
     sources: [
       {
@@ -273,22 +287,22 @@ export const VERSION_SOURCES = {
   },
   clineSdk: {
     key: "cline-sdk",
-    fallback: "0.0.95",
+    fallback: "0.2.0",
     sources: [{ url: "https://registry.npmjs.org/@cline/sdk/latest", extract: clineSdkVersion }],
   },
   clineCli: {
     key: "cline-cli",
-    fallback: "3.0.73",
+    fallback: "3.0.74",
     sources: [{ url: "https://registry.npmjs.org/cline/latest", extract: clineSdkVersion }],
   },
   codex: {
     key: "codex",
-    fallback: "0.163.0",
+    fallback: "0.166.0",
     sources: [{ url: "https://registry.npmjs.org/@openai/codex/latest" }],
   },
   workbuddyClient: {
     key: "workbuddy-client",
-    fallback: "5.8.4.41366630",
+    fallback: "5.9.4.42593613",
     sources: [
       {
         url: "https://www.workbuddy.ai/v2/update?platform=workbuddy-win32-x64-user",
@@ -302,7 +316,7 @@ export const VERSION_SOURCES = {
   },
   workbuddyCnClient: {
     key: "workbuddy-cn-client",
-    fallback: "5.8.3.41334564",
+    fallback: "5.9.3.42398134",
     sources: [
       {
         url: "https://www.workbuddy.cn/v2/update?platform=workbuddy-win32-x64-user",
@@ -316,7 +330,7 @@ export const VERSION_SOURCES = {
   },
   workbuddyCli: {
     key: "workbuddy",
-    fallback: "2.169.0",
+    fallback: "2.178.1",
     sources: [
       { url: "https://registry.npmjs.org/@tencent-ai/codebuddy-code/latest" },
       { url: "https://registry.npmmirror.com/@tencent-ai/codebuddy-code/latest" },
@@ -329,7 +343,7 @@ export const VERSION_SOURCES = {
   },
   kiro: {
     key: "kiro",
-    fallback: "1.3.11",
+    fallback: "1.4.62",
     sources: [
       {
         // Kiro's downloads page exposes no stable version string. Homebrew
@@ -343,7 +357,7 @@ export const VERSION_SOURCES = {
   },
   codebuddy: {
     key: "codebuddy",
-    fallback: "2.169.0",
+    fallback: "2.178.1",
     sources: [
       { url: "https://registry.npmjs.org/@tencent-ai/codebuddy-code/latest" },
       { url: "https://registry.npmmirror.com/@tencent-ai/codebuddy-code/latest" },
@@ -366,7 +380,7 @@ export const VERSION_SOURCES = {
     // Current `@anthropic-ai/claude-code` release, so the billing
     // `cc_version=` suffix and the `claude-cli/` User-Agent stay on what
     // upstream ships.
-    fallback: "2.1.302",
+    fallback: "2.1.314",
     sources: [{ url: "https://registry.npmjs.org/@anthropic-ai/claude-code/latest" }],
   },
   claudeSdk: {
@@ -393,20 +407,21 @@ export const VERSION_SOURCES = {
   },
   kilo: {
     key: "kilo-code",
-    fallback: "7.8.14",
+    fallback: "7.8.25",
     sources: [{ url: "https://open-vsx.org/api/kilocode/kilo-code" }],
   },
   muse: {
     key: "muse-code",
-    fallback: "1.4.10-R6427.1",
+    fallback: "1.4.14-R7309.1",
     sources: [{ url: "https://api.meta.ai/muse-code/channels/muse-stable" }],
   },
   trae: {
     key: "trae",
-    // Fallback = the donor's last observed client version. Discovery replaces
-    // it within one monitor tick; it is only what a cold process sends before
+    // Fallback = the newest release the changelog names, which is the *high*
+    // end of its newest line ("TRAE v3.6.1 ~ 3.6.4"). Discovery replaces it
+    // within one monitor tick; it is only what a cold process sends before
     // the first successful fetch.
-    fallback: "3.6.2",
+    fallback: "3.6.4",
     sources: [
       {
         url: "https://docs.trae.ai/ide/changelog?_lang=en",
@@ -419,7 +434,7 @@ export const VERSION_SOURCES = {
     // Fallback = the last observed wire version. Discovery replaces it within
     // one monitor tick; it is only what a cold process sends before the first
     // successful fetch.
-    fallback: "cli-2026.10.19-6bbf2c4",
+    fallback: "cli-3.27.22-b1aa50c",
     sources: [
       {
         url: "https://cursor.com/api/download?platform=win32-x64-user&releaseTrack=stable",
@@ -433,7 +448,7 @@ export const VERSION_SOURCES = {
     // comment this replaced claimed no semver existed and pinned a date tag
     // (`v2026.9.24`) as the version — a tag, not a release, and not the
     // identity the client sends.
-    fallback: "0.22.2",
+    fallback: "0.22.5",
     sources: [
       {
         url: "https://api.github.com/repos/NousResearch/hermes-agent/releases/latest",

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

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

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

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

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

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

package/src/providers/provider-contracts.ts

@@ -42,12 +42,56 @@ export function readCredentialSecret(credential: ResolvedCredential, errorMessag
     throw new GatewayError(
       "authentication_failed",
       401,
-      errorMessage ?? "Provider credential secret is missing or empty",
+      `${errorMessage ?? "Provider credential secret is missing or empty"} (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
   return raw;
 }
 
+/**
+ * Asserts a credential is of the required kind, throwing a typed rejection
+ * otherwise. Providers disagree on the kind they accept (`oauth` vs
+ * `api_key` vs `scoped_access_token`), and each hand-rolled its own check +
+ * message. This centralizes the common pattern so a mis-bound credential reads
+ * the same everywhere, preserving the existing `invalid_request`/400 wire
+ * contract.
+ */
+export function assertCredentialKind(
+  credential: ResolvedCredential,
+  expected: CredentialKind | readonly CredentialKind[],
+  providerLabel: string,
+): void {
+  const expectedKinds = Array.isArray(expected) ? expected : [expected];
+  if (expectedKinds.includes(credential.credential_kind)) return;
+  throw new GatewayError(
+    "invalid_request",
+    400,
+    `${providerLabel}: ${expectedKinds.join(" or ")} credential required (got credential_kind=${credential.credential_kind}) (request {requestId}). Wrong key, right door — check the credential 🔑`,
+    { expected_credential_kind: expectedKinds },
+  );
+}
+
+/**
+ * Asserts a candidate's wire family is one of the ones the provider serves,
+ * throwing `capability_unsupported` otherwise. Every provider hand-rolled this
+ * guard with the same shape; this centralizes the pattern so a mis-routed
+ * candidate reads the same everywhere.
+ */
+export function assertWireFamily(
+  candidate: ProviderDispatchTarget,
+  allowed: WireFamily | readonly WireFamily[],
+  providerLabel: string,
+): void {
+  const allowedFamilies = Array.isArray(allowed) ? allowed : [allowed];
+  if (allowedFamilies.includes(candidate.wire_family)) return;
+  throw new GatewayError(
+    "capability_unsupported",
+    400,
+    `${providerLabel} supports ${allowedFamilies.join("/")} only, got ${candidate.wire_family} (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
+    { expected_wire_families: allowedFamilies, got_wire_family: candidate.wire_family },
+  );
+}
+
 /** Fetch capability that validates DNS answers and redirects before each request. */
 export type ValidatedOutboundFetch = (
   input: RequestInfo | URL,
@@ -155,6 +199,14 @@ export interface ProviderDispatchContext {
    * and hold no database handle.
    */
   readonly image_clamp_max_bytes?: number | undefined;
+  /**
+   * Tenant system-prompt text resolved once per request (append/override
+   * injection). The buddy adapters fold it into their fixed system turn after
+   * serialization, wrapped in the gateway's marker prefix/suffix, so the
+   * upstream's channel-identity validation still sees its prompt as the
+   * opener.
+   */
+  readonly tenant_system_prompt?: string | undefined;
   /** Opaque identity shared by retries of one logical gateway request. */
   readonly request_identity?: object | undefined;
   /**
@@ -344,7 +396,7 @@ export interface WebSearchOutcome {
 function normalizeProviderSlug(id: string): string {
   const trimmed = id.trim().toLowerCase();
   if (!/^[a-z][a-z0-9-]{0,63}$/.test(trimmed)) {
-    throw new GatewayError("invalid_request", 400, "Provider ID must be a lowercase slug");
+    throw new GatewayError("invalid_request", 400, "Provider ID must be a lowercase slug (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   return trimmed;
 }
@@ -371,7 +423,7 @@ export function parseCustomProviderId(value: string): CustomProviderId {
     throw new GatewayError(
       "slug_reserved",
       409,
-      "The provider ID is reserved for a builtin provider",
+      "The provider ID is reserved for a builtin provider (request {requestId}). This name's taken — pick another alias ✨",
       { provider_id: normalized },
     );
   }

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

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

package/src/providers/provider-registry.ts

@@ -89,7 +89,7 @@ function assertAdapterIdentity(expected: ProviderId, adapter: ProviderAdapter):
   // error: `invalid_request` would blame the caller and invite a byte-identical
   // retry. `internal_error` (500) says what is true — the gateway is
   // misconfigured and the request never had a chance.
-  throw new GatewayError("internal_error", 500, "Loaded adapter ID does not match registration", {
+  throw new GatewayError("internal_error", 500, "Loaded adapter ID does not match registration (request {requestId}). Even we have bad days — check the registry wiring 🐻", {
     provider_id: expected,
     adapter_id: adapter.provider_id,
   });
@@ -122,12 +122,12 @@ export class ProviderRegistry {
   register(registration: ProviderRegistration): void {
     const providerId = parseProviderId(registration.provider_id);
     if (this.#registrations.has(providerId)) {
-      throw new GatewayError("invalid_request", 409, "Provider is already registered", {
+      throw new GatewayError("invalid_request", 409, "Provider is already registered (request {requestId}). This name's taken — pick another alias ✨", {
         provider_id: providerId,
       });
     }
     if (providerId !== registration.provider_id) {
-      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized", {
+      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized (request {requestId}). Even we have bad days — check the registry wiring 🐻", {
         provider_id: registration.provider_id,
       });
     }
@@ -158,7 +158,7 @@ export class ProviderRegistry {
   upsert(registration: ProviderRegistration): boolean {
     const providerId = parseProviderId(registration.provider_id);
     if (providerId !== registration.provider_id) {
-      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized", {
+      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized (request {requestId}). Even we have bad days — check the registry wiring 🐻", {
         provider_id: registration.provider_id,
       });
     }

package/src/providers/quota/quota-contracts.ts

@@ -58,20 +58,27 @@ export function totalRemainingCredit(
  * independent quota windows, or `null` when neither is reported.
  *
  * Pooled credits are summed before converting to percent, so one exhausted
- * bonus pack cannot hide balance in another. Independent windows keep their
- * own remaining percent and the lowest one gates the account.
+ * bonus pack cannot hide balance in another. A pooled window without a ceiling
+ * (Command Code credits) contributes its absolute remaining to the credit sum
+ * but cannot produce a percent, so it is not counted in the percent ratio.
+ * Independent windows keep their own remaining percent and the lowest one
+ * gates the account.
  */
 export function totalRemainingPercent(
   windows: readonly ProviderQuotaWindow[],
 ): number | null {
   let creditLimit = 0;
   let creditRemaining = 0;
+  let hasPooledLimit = false;
   let independentPercent: number | null = null;
   for (const window of windows) {
     if (window.accounting === "pooled") {
       const balance = creditWindowBalance(window);
       if (balance !== null) {
-        creditLimit += balance.limit;
+        if (balance.limit !== null) {
+          creditLimit += balance.limit;
+          hasPooledLimit = true;
+        }
         creditRemaining += balance.remaining;
       }
       continue;
@@ -85,8 +92,13 @@ export function totalRemainingPercent(
     independentPercent =
       independentPercent === null ? clamped : Math.min(independentPercent, clamped);
   }
-  const creditPercent =
-    creditLimit > 0 ? Math.min(100, Math.max(0, (creditRemaining / creditLimit) * 100)) : null;
+  // A pooled window with a reported ceiling (including a 0 ceiling — a spent
+  // balance) always defines a percent: 0 ceiling means 0% remaining.
+  const creditPercent = hasPooledLimit
+    ? creditLimit > 0
+      ? Math.min(100, Math.max(0, (creditRemaining / creditLimit) * 100))
+      : 0
+    : null;
   if (creditPercent === null) return independentPercent;
   if (independentPercent === null) return creditPercent;
   return Math.min(creditPercent, independentPercent);
@@ -94,20 +106,22 @@ export function totalRemainingPercent(
 
 function creditWindowBalance(
   window: ProviderQuotaWindow,
-): { readonly limit: number; readonly remaining: number } | null {
+): { readonly limit: number | null; readonly remaining: number } | null {
+  // A ceiling of 0 is a spent balance, not an absence of data; only a window
+  // with no remaining figure at all is skipped. `limit` may be null (Command
+  // Code reports credits without a ceiling) — the remaining total still counts.
   const limit =
-    typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit > 0
+    typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit >= 0
       ? window.limit
       : null;
-  if (limit === null) return null;
   let remaining: number | null = null;
   if (typeof window.remaining === "number" && Number.isFinite(window.remaining)) {
     remaining = window.remaining;
-  } else if (typeof window.used === "number" && Number.isFinite(window.used)) {
+  } else if (typeof window.used === "number" && Number.isFinite(window.used) && limit !== null) {
     remaining = limit - window.used;
   }
   if (remaining === null) return null;
-  return { limit, remaining: Math.min(limit, Math.max(0, remaining)) };
+  return { limit, remaining: Math.max(0, remaining) };
 }
 
 const TIMEOUT_MS = 15_000;

package/src/providers/quota/refresh.ts

@@ -16,7 +16,7 @@ import { type FetchLike, type ProviderQuotaResult } from "./quota-contracts";
 import type { ProviderId } from "../provider-contracts";
 import type { ProviderRegistry } from "../provider-registry";
 import { GLOBAL_QUOTA_LENS, setCachedQuota } from "./cache";
-import { record } from "../authentication/oauth-flow-store";
+import { asJsonbRecord } from "../../shared/coerce";
 
 /** Why an account quota refresh failed; `null` means the fetch succeeded. */
 export type QuotaRefreshFailureCode = "missing_credential" | "quota_fetch_failed";
@@ -355,7 +355,7 @@ async function runQuotaRefresh(
         ? (deps.markApiKeyCredential?.(target.providerId, credential) ?? credential)
         : credential;
     try {
-      const authState = record(target.authState);
+      const authState = asJsonbRecord(target.authState);
       quota = await fetchProviderQuota(deps.providerRegistry, target.providerId, marked, fetcher, {
         // Carried so a collector can reuse a reading captured from real
         // traffic rather than spending a request to rediscover it.

package/src/providers/search/search-provider.ts

@@ -53,7 +53,7 @@ function stringField(record: Record<string, unknown> | undefined, key: string):
 export function searchParamsFromBody(body: Record<string, unknown>): SearchParams {
   const query = typeof body.query === "string" ? body.query.trim() : "";
   if (query.length === 0)
-    throw new GatewayError("invalid_request", 400, "search query is required");
+    throw new GatewayError("invalid_request", 400, "search query is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   const rawMax = body.max_results;
   const maxResults =
     typeof rawMax === "number" && Number.isFinite(rawMax)
@@ -90,7 +90,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
       throw new GatewayError(
         "capability_unsupported",
         400,
-        `${spec.provider_id} serves web search, not a chat wire`,
+        `${spec.provider_id} serves web search, not a chat wire (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
       );
     },
     async websearch(
@@ -113,7 +113,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
         throw new GatewayError(
           "platform_unavailable",
           502,
-          `${spec.provider_id} search unreachable: ${error instanceof Error ? error.message : String(error)}`,
+          `${spec.provider_id} search unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
         );
       }
       if (!res.ok) {
@@ -121,7 +121,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
         throw new GatewayError(
           res.status >= 500 ? "platform_unavailable" : "invalid_request",
           res.status,
-          `${spec.provider_id} search error: ${detail.slice(0, 240)}`,
+          `${spec.provider_id} search error (request {requestId}): ${detail.slice(0, 240)}. The upstream came back empty-handed — retry 🌙`,
         );
       }
       const raw = await res.text();
@@ -135,7 +135,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
         throw new GatewayError(
           "platform_unavailable",
           502,
-          `${spec.provider_id} search returned an unparseable body`,
+          `${spec.provider_id} search returned an unparseable body (request {requestId}). The upstream came back empty-handed — retry 🌙`,
         );
       }
       const results = spec.normalize(data);

package/src/security/abuse.ts

@@ -399,7 +399,7 @@ export class IpAbuseProtectionService {
     readonly signal?: AbortSignal;
   }): Promise<void> {
     if (input.signal?.aborted) {
-      throw new GatewayError("admission_unavailable", 503, "The abuse check never ran because the request was already cancelled.", {
+      throw new GatewayError("admission_unavailable", 503, "The abuse check never ran because the request was already cancelled (request {requestId}). Send it again whenever ready 🙃", {
         reason: "admission-unavailable",
       });
     }
@@ -436,7 +436,7 @@ export class IpAbuseProtectionService {
 
       if (outcome.banned) {
         metrics.cartethyia_ip_abuse_refusals_total.inc(1, { reason: "ip-banned" });
-        throw new GatewayError("quota_exceeded", 429, "This address is temporarily banned for too many failed requests. Wait for the ban to lift, then slow down.", {
+        throw new GatewayError("rate_limited", 429, "This address is temporarily banned for too many failed requests (request {requestId}). Wait for the ban to lift, then slow down. You've maxed this window — pace yourself ⏳", {
           // Distinguishes this from the rate-limited 429 below and from an API
           // key's own budget. It used to be "admission-unavailable", which is
           // the label for an *unreachable* store — so every refusal from this
@@ -454,7 +454,7 @@ export class IpAbuseProtectionService {
 
       if (outcome.count > this.maxRequestsPerWindow) {
         metrics.cartethyia_ip_abuse_refusals_total.inc(1, { reason: "ip-rate-limited" });
-        throw new GatewayError("quota_exceeded", 429, "This address is sending requests faster than the abuse limit allows. Back off and retry after the window rolls over.", {
+        throw new GatewayError("rate_limited", 429, "This address is sending requests faster than the abuse limit allows (request {requestId}). Back off and retry after the window rolls over. You've maxed this window — pace yourself ⏳", {
           reason: "ip-rate-limited",
           ip,
           route: input.route,
@@ -464,7 +464,7 @@ export class IpAbuseProtectionService {
       }
     } catch (err) {
       if (err instanceof GatewayError) throw err;
-      throw new GatewayError("admission_unavailable", 503, "The abuse-tracking store is unreachable, so requests from this address cannot be checked. Retry shortly.", {
+      throw new GatewayError("admission_unavailable", 503, "The abuse-tracking store is unreachable, so requests from this address cannot be checked (request {requestId}). Retry shortly. The bouncer stepped out — come back shortly 🚪", {
         reason: "admission-unavailable",
         cause: (err as Error).message,
       });

package/src/security/access-control.ts

@@ -1,5 +1,24 @@
 // Shared authorization primitives: closed scope model and immutable access decisions.
 
+/**
+ * The single identity of "who is speaking" — resolved once at auth and carried
+ * through planning, admission, pool selection, and telemetry so every layer
+ * reasons about the same caller.
+ *
+ * - `apiKeyId` — the credential that authenticated.
+ * - `admissionIdentity` — the quota/concurrency owner (the share parent for a
+ *   child key; otherwise the key itself).
+ * - `tenantId` — the tenant the request runs as.
+ *
+ * Provider/account/model are added by the candidate, not here: the caller
+ * identity is stable regardless of what serves the request.
+ */
+export interface CallerIdentity {
+  readonly apiKeyId: string;
+  readonly admissionIdentity: string;
+  readonly tenantId: string;
+}
+
 /**
  * Closed set of authorization scopes.
  * - `routing:invoke`: May call only /v1/* gateway routes within holder's tenant.