cartethyia 2.7.0 → 2.7.2

package/src/transport/failure-policy.ts

@@ -1,184 +1,27 @@
 import { GatewayError, type GatewayErrorCode, type GatewayErrorOrigin } from "../protocol/gateway-error";
 import { isRecord } from "../protocol/codecs";
 import { resolveFallbackRetryBaseMs, resolveFallbackRetryCapMs } from "../config/timeouts";
-
-const MAX_UPSTREAM_ERROR_BYTES = 500;
-const MAX_COOLDOWN_MS = 24 * 3600 * 1000;
-
-/** Parses Retry-After seconds or an HTTP date, bounded to one day. */
-export function parseRetryAfter(value: string | null | undefined): number | null {
-  if (!value) return null;
-  const trimmed = value.trim();
-  const numeric = Number(trimmed);
-  if (Number.isFinite(numeric) && numeric > 0) return Math.min(MAX_COOLDOWN_MS, numeric * 1000);
-  const parsed = Date.parse(trimmed);
-  if (!Number.isFinite(parsed)) return null;
-  const delay = parsed - Date.now();
-  return delay > 0 ? Math.min(MAX_COOLDOWN_MS, delay) : null;
-}
+import { parseUpstreamBackoff } from "../protocol/upstream-parsing";
+import { resolveAccountQuotaCooldownMs } from "../config/cooldowns";
 
 /**
- * Parses x-ratelimit-reset as epoch seconds or a relative delay.
+ * How much of the upstream's error body is kept and surfaced.
  *
- * Returns `null` — not `0` — when the instant has already passed. This matters
- * because `parseUpstreamBackoff` chains these parsers with `??`, which falls
- * through only on null: a `0` from an elapsed `x-ratelimit-reset` (a cached error
- * body, clock skew, a stale edge response) stopped the chain before the
- * lower-priority headers that carried the real wait. The `0` was then written to
- * `details.retryAfterMs` and read by `classifyAccountError` as `headerCooldown`,
- * which outranks the provider's own message text — so both were discarded and the
- * account fell back to the generic default cooldown while the provider had parked
- * it for the rest of the window.
- *
- * `parseRetryAfter` above already returns `null` for an elapsed date; matching it
- * is what removes the asymmetry.
- */
-export function parseRateLimitReset(value: string | null | undefined): number | null {
-  if (!value) return null;
-  const numeric = Number(value.trim());
-  if (!Number.isFinite(numeric) || numeric <= 0) return null;
-  const target = numeric >= 1_000_000_000 ? numeric * 1000 : Date.now() + numeric * 1000;
-  const remaining = target - Date.now();
-  return remaining > 0 ? Math.min(MAX_COOLDOWN_MS, remaining) : null;
-}
-
-/** Parses a millisecond-denominated reset header (`retry-after-ms`, `x-ratelimit-reset-ms`). */
-export function parseResetAfterMs(value: string | null | undefined): number | null {
-  if (!value) return null;
-  const numeric = Number(value.trim());
-  if (!Number.isFinite(numeric) || numeric <= 0) return null;
-  return Math.min(MAX_COOLDOWN_MS, Math.round(numeric));
-}
-
-/**
- * Reads upstream backoff evidence in reference priority order: millisecond
- * variants first (`retry-after-ms`, then `x-ratelimit-reset-ms`), then the
- * classic `retry-after` / `x-ratelimit-reset` pair.
+ * 500 bytes cut the CodeBuddy envelope mid-`extError`: the operator saw
+ * "request illegal" with none of the `displayMsg` prose that names the actual
+ * condition — "prompt is too long: 1048788 tokens > 1048576 maximum" — so a
+ * context overflow was indistinguishable from a policy refusal. The envelope
+ * runs a few KB; 4000 keeps the whole thing while bounding a hostile body.
  */
-export function parseUpstreamBackoff(headers: {
-  get(name: string): string | null;
-}): number | null {
-  return (
-    parseResetAfterMs(headers.get("retry-after-ms")) ??
-    parseRetryAfter(headers.get("retry-after")) ??
-    parseResetAfterMs(headers.get("x-ratelimit-reset-ms")) ??
-    parseRateLimitReset(headers.get("x-ratelimit-reset")) ??
-    parseRateLimitReset(headers.get("x-ratelimit-reset-requests")) ??
-    parseRateLimitReset(headers.get("retry-after"))
-  );
-}
-
-/**
- * Extracts bounded reset durations from provider messages when headers omit
- * them.
- *
- * Two shapes are recognized, because providers state resets both ways:
- *
- *   - **Relative** — "quota will reset in 3 hours", "try again in 30s".
- *   - **Absolute** — "your usage will reset at 2026-09-24 02:12:51 UTC+8"
- *     (WorkBuddy/CodeBuddy `6004`). An absolute stamp is *not* a duration, and
- *     the relative-only pattern silently missed it, so the account fell back to
- *     the generic 15-minute default while the provider had actually parked it
- *     for the rest of the window — the account kept re-entering rotation and
- *     failing every request inside the stated reset window.
- */
-/**
- * One `amount unit` pair of a duration phrase: `4h`, `13m`, `2 hours`, `30s`.
- *
- * The unit ends on `(?![a-z])`, not `\b`: a compact compound like `2h30m` puts
- * a digit straight after `h`, which is a word character, so a `\b` would refuse
- * to end the pair and the whole phrase would parse as null. `m(?!s|o)` is what
- * stops a bare `m` from swallowing `ms` (milliseconds) or `mo` (months),
- * neither of which is a reset duration.
- */
-const DURATION_PAIR_SOURCE = String.raw`(\d+(?:\.\d+)?)[\s-]*(hours?|hrs?|h|minutes?|mins?|m(?!s|o)|seconds?|secs?|s)(?![a-z])`;
-
-function durationUnitMs(unit: string): number {
-  const first = unit.toLowerCase()[0];
-  return first === "h" ? 3600_000 : first === "m" ? 60_000 : 1_000;
-}
-
-/**
- * Sums the `amount unit` pairs at the head of a duration phrase.
- *
- * Providers state a reset as one compound duration at least as often as a
- * single unit: a daily-limit 429 reads "Try again in 4h 13m". A single-pair
- * parser read only `4h` and dropped the 13 minutes, so the stored retry
- * deadline was earlier than the window the provider had actually stated and the
- * account re-entered rotation before it. Pairs are accepted only while they
- * continue the phrase — separated by whitespace, a comma, or `and` — so a
- * number that merely follows later in the sentence cannot be absorbed.
- */
-function parseCompoundDuration(text: string): number | null {
-  const pairs = new RegExp(DURATION_PAIR_SOURCE, "gi");
-  let totalMs = 0;
-  let lastEnd = 0;
-  let matched = false;
-  for (let pair = pairs.exec(text); pair !== null; pair = pairs.exec(text)) {
-    const gap = text.slice(lastEnd, pair.index);
-    const continues = matched ? /^[\s,]*(?:and\s+)?$/i.test(gap) : /^\s*$/.test(gap);
-    if (!continues) break;
-    const amount = Number(pair[1]);
-    if (!Number.isFinite(amount) || amount <= 0) break;
-    totalMs += amount * durationUnitMs(pair[2] ?? "");
-    matched = true;
-    lastEnd = pair.index + pair[0].length;
-  }
-  return matched ? Math.round(totalMs) : null;
-}
-
-export function parseProviderResetDuration(message: string): number | null {
-  const trigger =
-    /(?:quota will reset|resets?|try again|retry(?:ing)?)\s+(?:in|after|over)\s+(?:a\s+)?(?:rolling\s+)?/i.exec(
-      message,
-    );
-  if (trigger) {
-    const parsed = parseCompoundDuration(message.slice(trigger.index + trigger[0].length));
-    if (parsed !== null) return Math.min(MAX_COOLDOWN_MS, parsed);
-  }
-  return parseAbsoluteResetTimestamp(message);
-}
-
-/**
- * Reads an absolute reset instant out of a provider message, e.g.
- * `will reset at 2026-09-24 02:12:51 UTC+8`. Returns the delay from now,
- * bounded to one day, or null when no future timestamp is present.
- *
- * `Date.parse` cannot read the space-separated `YYYY-MM-DD HH:MM:SS` form with
- * a bare `UTC±H` offset, so the parts are normalized explicitly rather than
- * relying on engine-specific leniency.
- */
-export function parseAbsoluteResetTimestamp(message: string): number | null {
-  const match = /(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})\s*(?:UTC|GMT)?\s*([+-]\d{1,2})?(?::?(\d{2}))?/i.exec(
-    message,
-  );
-  if (!match) return null;
-  const [, year, month, day, hour, minute, second, offsetHours, offsetMinutes] = match;
-  if (!year || !month || !day || !hour || !minute || !second) return null;
-  // A bare `UTC+8` means a whole-hour offset; `+08:30`-style halves are rare
-  // but cheap to honor. No offset at all is read as UTC (providers that omit
-  // it always label the stamp "UTC" in practice).
-  const sign = offsetHours?.startsWith("-") ? -1 : 1;
-  const offsetTotalMinutes =
-    offsetHours === undefined
-      ? 0
-      : sign * (Math.abs(Number(offsetHours)) * 60 + Number(offsetMinutes ?? 0));
-  const utcMs = Date.UTC(
-    Number(year),
-    Number(month) - 1,
-    Number(day),
-    Number(hour),
-    Number(minute),
-    Number(second),
-  );
-  if (!Number.isFinite(utcMs)) return null;
-  const targetMs = utcMs - offsetTotalMinutes * 60_000;
-  const delay = targetMs - Date.now();
-  // A past stamp is not a usable reset (clock skew, stale cached error); fall
-  // through to the caller's default instead of returning a negative delay.
-  if (!Number.isFinite(delay) || delay <= 0) return null;
-  return Math.min(MAX_COOLDOWN_MS, Math.round(delay));
-}
+const MAX_UPSTREAM_ERROR_BYTES = 4000;
+export {
+  parseRetryAfter,
+  parseRateLimitReset,
+  parseResetAfterMs,
+  parseUpstreamBackoff,
+  parseProviderResetDuration,
+  parseAbsoluteResetTimestamp,
+} from "../protocol/upstream-parsing";
 /** Extracts a bounded, newline-free provider message from any error envelope. */
 export function extractUpstreamMessage(body: unknown): string {
   let raw = "";
@@ -390,6 +233,31 @@ export function classifyUpstreamFailure(error: unknown): UpstreamFailurePolicy {
   // DNS failure. Failing the client request instead of failing over is the wrong
   // outcome for a whole class the table already names as platform-wide.
   const statusCode = error.status;
+  // Qoder answers an exhausted quota by closing the stream with an upstream 499
+  // (nginx client-close style). That is a refusal from the upstream — the
+  // gateway's own aborts are `transport_closed`, produced locally, and never
+  // carry a qoder providerId — so a 499 scoped to qoder is quota, not a
+  // malformed request. Without this it fell through to `invalid_request`
+  // (non-retryable, no cooldown) and the account was re-dialled on every
+  // request inside the exhausted window until a late 429 finally classified it.
+  if (
+    error.origin === "upstream" &&
+    statusCode === 499 &&
+    (providerId === "qoder" || providerId === "qodercn")
+  ) {
+    const cooldownMs = resolveAccountQuotaCooldownMs();
+    return {
+      retryable: true,
+      mutatesAccount: true,
+      category: "quota_exceeded",
+      scope: "account",
+      origin: error.origin,
+      ...(providerCode ? { providerCode } : {}),
+      ...(providerId ? { providerId } : {}),
+      cooldownMs,
+      statusCode,
+    };
+  }
   const retryableByStatus =
     statusCode === 401 ||
     statusCode === 403 ||
@@ -544,7 +412,27 @@ export interface TerminalOutcome {
   readonly status: "cancelled" | "failed";
   readonly errorCategory: GatewayErrorCode | "unknown_error";
   readonly errorOrigin: GatewayErrorOrigin;
-}
+  /**
+   * The HTTP status the row should carry. `undefined` means the caller has a
+   * better one (the wire status of an actual response) and should keep it;
+   * a raw error has none, and the caller's own fallback was 500 — which
+   * read as a gateway fault for what was an upstream transport drop.
+   */
+  readonly httpStatus?: number;
+}
+
+/** The HTTP status each classifier-derived category carries when no wire response named one. */
+const CATEGORY_HTTP_STATUS: Partial<Record<GatewayErrorCode | "unknown_error", number>> = {
+  // The upstream's transport died mid-response: a bad gateway, not a fault
+  // in this process.
+  transport_unavailable: 502,
+  platform_unavailable: 502,
+  deadline_exceeded: 504,
+  transport_closed: 499,
+  shutting_down: 503,
+  overloaded: 529,
+  unknown_error: 500,
+};
 
 /**
  * Derives a failed attempt's status, error category, and error origin **from
@@ -559,11 +447,24 @@ export interface TerminalOutcome {
  * outcome carries the real code and origin.
  */
 export function classifyTerminalOutcome(error: unknown, signal: AbortSignal): TerminalOutcome {
+  const category = classifyTerminalCategory(error, signal);
+  const gateway = error instanceof GatewayError ? error : signal.reason instanceof GatewayError ? signal.reason : undefined;
   return {
     status: isClientCancellation(error, signal) ? "cancelled" : "failed",
-    errorCategory: classifyTerminalCategory(error, signal),
-    // A non-GatewayError outcome has no upstream origin to claim: it is ours.
-    errorOrigin: error instanceof GatewayError ? error.origin : "cartethyia",
+    errorCategory: category,
+    // The classifier owns the blame. An upstream socket drop arrives as a
+    // raw runtime error — no `GatewayError` wraps it — and calling that ours
+    // made the row accuse the gateway for an upstream failure.
+    errorOrigin: gateway
+      ? gateway.origin
+      : category === "transport_unavailable"
+        ? "upstream"
+        : "cartethyia",
+    // A `GatewayError` carries its own status; a raw error takes the
+    // category's, so an upstream drop is 502 rather than the 500 fallback.
+    ...(gateway || CATEGORY_HTTP_STATUS[category] !== undefined
+      ? { httpStatus: gateway ? gateway.status : CATEGORY_HTTP_STATUS[category] }
+      : {}),
   };
 }
 
@@ -584,6 +485,13 @@ const CONTEXT_LENGTH_CODES: ReadonlySet<string> = new Set([
   "model_context_window_exceeded",
   // InferHub's spelling for the same condition.
   "context_too_long",
+  // Trae answers an overflow on its streaming surface with the bare numeric
+  // code `4026` and the prose "We're sorry, your context length has exceeded
+  // the maximum limit." — no HTTP status, no symbolic code (verified live
+  // 2026-10: `event:error data:{"code":4026,"message":"..."}`). Without it
+  // the frame fell to the 502 `platform_unavailable` fallback and the client
+  // never saw the 413 it compacts on.
+  "4026",
 ]);
 
 /**
@@ -735,6 +643,12 @@ const QUOTA_ERROR_IDENTIFIERS: ReadonlySet<string> = new Set([
   "usage_not_included",
   "subscription:free-usage-exhausted",
   "resource_exhausted",
+  // Qoder answers an exhausted daily billing allowance with a bare numeric
+  // code: `{"code":"110","message":"Billing daily count exceeded"}`. The 403
+  // wrapper made the old status-only fallback read it as a credential fault;
+  // it is a spend/limit verdict, never an auth one, so it must classify as
+  // quota (a cooldown) instead of `auth_invalidated`.
+  "110",
   // InferHub publishes its own vocabulary in `error.code`. The two 403s below
   // are deliberate absences: `account_blocked` means the account was blocked
   // (an auth/entitlement verdict, not a spend limit) and

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

@@ -69,6 +69,16 @@ export function createIpAbuseProtectionMiddleware(deps: {
       throw peerAddressUnavailableError();
     const address = resolveClientIdentity(request, deps.trustedProxyBoundary, peer);
     const state = deps.stateStore.get(request);
+    // The identity middleware runs later in the plugin chain and resolves the
+    // same value from the same boundary; stashing it here means the request
+    // pays for one resolveClientIdentity instead of two, and the middleware can
+    // skip its own when it finds the stash.
+    if (state !== undefined) {
+      state.clientIdentity ??= {
+        address,
+        source: address === peer ? "tcp-peer" : "trusted-forwarded-header",
+      };
+    }
     try {
       await deps.ipAbuseProtection.checkBeforeAccess({
         identity: {

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

@@ -1,109 +1,109 @@
-import { log } from "../../observability/logger";
-// API-key authentication guard for `/v1/*`: token resolution, scope check,
-// client-router denylist, and the model-abuse ban gate.
-import { Elysia } from "elysia";
-import { GatewayError } from "../../protocol/gateway-error";
-import type { ProxyRequestStateStore } from "../request/state";
-import { fastPathname } from "../pathname";
-import type { CartethyiaDatabase } from "../../persistence/db-handle";
-import { requestToken, resolveApiKeyAuthorization, unknownApiKeyError } from "../../security/api-key-auth";
-import {
-  deniedClientRouter,
-  detectClientRouter,
-} from "../../security/client-router-fingerprint";
-import { createAccessDecision } from "../../security/access-control";
-
-/**
- * Stateless Elysia `beforeHandle` gateway check: API-key authentication,
- * wired into the middleware chain in `app.ts`.
- */
-export function createApiKeyAuthenticationMiddleware(deps: {
-  readonly db: CartethyiaDatabase;
-  readonly stateStore: ProxyRequestStateStore;
-  /**
-   * Model-abuse ban gate. A banned IP or key is refused here, before the
-   * canonical parse and route preparation, and before `state.authorization` is
-   * assigned — so a banned caller's attempts produce no telemetry row and no
-   * console error, which is exactly the noise this layer exists to stop.
-   */
-  /**
-   * Tenant invoke kill switch. Checked after the key resolves, because the
-   * tenant is a property of the key: the same gateway serves several tenants
-   * and one switching itself off must not stop the others.
-   */
-  readonly isInvokeDisabled?: (tenantId: string) => Promise<boolean | undefined>;
-}): Elysia {
-  // Single policy for every `/v1/*` gateway route: authenticated, scoped to
-  // `routing:invoke`, and tenant-bound (the snapshot's tenant is the only
-  // tenant this key may address). The check is inline rather than routed
-  // through a per-route policy table: Elysia's router already owns which
-  // paths exist, so a per-route table only added a second place to keep in
-  // sync.
-  return new Elysia()
-    .beforeHandle(async ({ request }) => {
-      const pathname = fastPathname(request.url);
-      if (!pathname.startsWith("/v1/")) return;
-      const token = requestToken(request.headers);
-      // A database failure here is not "the key is bad". Left to propagate it
-      // surfaced as a 500 whose log line carried the whole statement and its
-      // bound parameters — including the key hash — once per request. Under an
-      // overloaded database that is a credential leak written at request rate.
-      //
-      // It is also the wrong answer: the caller cannot fix it by sending a
-      // different key, so it is a capacity signal, not an auth one.
-      const authorization = await resolveApiKeyAuthorization(deps.db, token).catch((error: unknown) => {
-        // Only the error's identity is logged, never its message: a drizzle
-        // query error carries the full statement and its bound parameters, and
-        // on this path one of those parameters is the key hash.
-        // A sanitized stand-in, not the original: a drizzle query error's
-        // message is the statement plus its bound parameters, and one of those
-        // parameters is the key hash.
-        const safe = new Error("[redacted: credential-store query failed]");
-        safe.name = error instanceof Error ? error.name : "Error";
-        log.error("[auth] key lookup failed; treating as unavailable", safe);
-        throw new GatewayError(
-          "accounts_unavailable",
-          503,
-          "The gateway could not verify this API key because its credential store is unavailable. Retry shortly.",
-          {},
-          "cartethyia",
-        );
-      });
-      if (!authorization) throw unknownApiKeyError();
-      const decision = createAccessDecision({
-        id: authorization.id,
-        tenantId: authorization.tenantId,
-        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.");
-      // 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.
-      // 503 rather than 403: nothing about the request is invalid, and the
-      // caller should retry later instead of "fixing" a request that is fine.
-      if ((await deps.isInvokeDisabled?.(authorization.tenantId)) === true)
-        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.",
-        );
-      // 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
-      // authorization decisions rather than in routing: the request is refused
-      // before a route is planned or an upstream is touched.
-      const denied = deniedClientRouter(
-        authorization.snapshot.client_router_denylist,
-        detectClientRouter({ headers: request.headers }),
-      );
-      if (denied !== null)
-        throw new GatewayError(
-          "client_router_denied",
-          403,
-          "No API invocation access for this client.",
-          { reason: "client_router_denied", clientRouter: denied },
-        );
-      deps.stateStore.require(request).authorization = authorization;
-    })
-    .as("plugin");
-}
+import { log } from "../../observability/logger";
+// API-key authentication guard for `/v1/*`: token resolution, scope check,
+// client-router denylist, and the model-abuse ban gate.
+import { Elysia } from "elysia";
+import { GatewayError } from "../../protocol/gateway-error";
+import type { ProxyRequestStateStore } from "../request/state";
+import { fastPathname } from "../pathname";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { requestToken, resolveApiKeyAuthorization, unknownApiKeyError } from "../../security/api-key-auth";
+import {
+  deniedClientRouter,
+  detectClientRouter,
+} from "../../security/client-router-fingerprint";
+import { createAccessDecision } from "../../security/access-control";
+
+/**
+ * Stateless Elysia `beforeHandle` gateway check: API-key authentication,
+ * wired into the middleware chain in `app.ts`.
+ */
+export function createApiKeyAuthenticationMiddleware(deps: {
+  readonly db: CartethyiaDatabase;
+  readonly stateStore: ProxyRequestStateStore;
+  /**
+   * Model-abuse ban gate. A banned IP or key is refused here, before the
+   * canonical parse and route preparation, and before `state.authorization` is
+   * assigned — so a banned caller's attempts produce no telemetry row and no
+   * console error, which is exactly the noise this layer exists to stop.
+   */
+  /**
+   * Tenant invoke kill switch. Checked after the key resolves, because the
+   * tenant is a property of the key: the same gateway serves several tenants
+   * and one switching itself off must not stop the others.
+   */
+  readonly isInvokeDisabled?: (tenantId: string) => Promise<boolean | undefined>;
+}): Elysia {
+  // Single policy for every `/v1/*` gateway route: authenticated, scoped to
+  // `routing:invoke`, and tenant-bound (the snapshot's tenant is the only
+  // tenant this key may address). The check is inline rather than routed
+  // through a per-route policy table: Elysia's router already owns which
+  // paths exist, so a per-route table only added a second place to keep in
+  // sync.
+  return new Elysia()
+    .beforeHandle(async ({ request }) => {
+      const pathname = fastPathname(request.url);
+      if (!pathname.startsWith("/v1/")) return;
+      const token = requestToken(request.headers);
+      // A database failure here is not "the key is bad". Left to propagate it
+      // surfaced as a 500 whose log line carried the whole statement and its
+      // bound parameters — including the key hash — once per request. Under an
+      // overloaded database that is a credential leak written at request rate.
+      //
+      // It is also the wrong answer: the caller cannot fix it by sending a
+      // different key, so it is a capacity signal, not an auth one.
+      const authorization = await resolveApiKeyAuthorization(deps.db, token).catch((error: unknown) => {
+        // Only the error's identity is logged, never its message: a drizzle
+        // query error carries the full statement and its bound parameters, and
+        // on this path one of those parameters is the key hash.
+        // A sanitized stand-in, not the original: a drizzle query error's
+        // message is the statement plus its bound parameters, and one of those
+        // parameters is the key hash.
+        const safe = new Error("[redacted: credential-store query failed]");
+        safe.name = error instanceof Error ? error.name : "Error";
+        log.error("[auth] key lookup failed; treating as unavailable", safe);
+        throw new GatewayError(
+          "accounts_unavailable",
+          503,
+          "The gateway could not verify this API key because its credential store is unavailable. Retry shortly.",
+          {},
+          "cartethyia",
+        );
+      });
+      if (!authorization) throw unknownApiKeyError();
+      const decision = createAccessDecision({
+        id: authorization.id,
+        tenantId: authorization.tenantId,
+        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.");
+      // 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.
+      // 503 rather than 403: nothing about the request is invalid, and the
+      // caller should retry later instead of "fixing" a request that is fine.
+      if ((await deps.isInvokeDisabled?.(authorization.tenantId)) === true)
+        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.",
+        );
+      // 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
+      // authorization decisions rather than in routing: the request is refused
+      // before a route is planned or an upstream is touched.
+      const denied = deniedClientRouter(
+        authorization.snapshot.client_router_denylist,
+        detectClientRouter({ headers: request.headers }),
+      );
+      if (denied !== null)
+        throw new GatewayError(
+          "client_router_denied",
+          403,
+          "No API invocation access for this client.",
+          { reason: "client_router_denied", clientRouter: denied },
+        );
+      deps.stateStore.require(request).authorization = authorization;
+    })
+    .as("plugin");
+}

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

@@ -7,7 +7,7 @@ import type { TelemetryBatchBuffer, TelemetryEventInput } from "../../observabil
 import type { TelemetryPayloadCapture } from "../../observability/payload-capture";
 import { captureEarlyRejectionPayload } from "./early-rejection-capture";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
-import { reasoningEffortFromIntent } from "../../providers/provider-reasoning";
+import { reasoningEffortFromIntent } from "../../protocol/reasoning";
 import { metrics } from "../../observability/metrics";
 import { computeTokensPerSec } from "../../observability/token-speed";
 import { pushStructuredConsoleLog } from "../../observability/log-ring";