cartethyia 2.7.0 → 2.7.2

package/src/providers/operations/account-reset-service.ts

@@ -642,6 +642,7 @@ async function recordResetActivity(
       })
       .where(eq(providerAccounts.id, accountId));
     await db.insert(healthEvents).values({
+      id: randomUUID(),
       entityKind: "account",
       accountId,
       fromStatus: currentStatus,
@@ -655,6 +656,7 @@ async function recordResetActivity(
   }
 
   await db.insert(healthEvents).values({
+    id: randomUUID(),
     entityKind: "account",
     accountId,
     fromStatus: currentStatus,

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

@@ -338,7 +338,17 @@ export async function registerByokProviders(
           provider_id: providerId,
           base_url: baseUrl,
           authentication_header_shape: wireProfile.authHeaderShape,
-          buildExtraHeaders: (_context, _request, candidate) => {
+          buildExtraHeaders: (context, _request, candidate) => {
+            // An operator-set route identity wins over both auto modes: Routing
+            // Strategy now serves custom providers too, and its value (including
+            // the empty "None" choice) must be honored verbatim.
+            const routeAgent = context.user_agent;
+            if (routeAgent !== undefined) {
+              return {
+                ...(routeAgent.length > 0 ? { "user-agent": routeAgent } : {}),
+                ...(compatibilityProfile?.extra_headers ?? {}),
+              };
+            }
             // Explicit gateway identity wins over CLI cloaking, and Codex /
             // Claude-Code-shaped traffic can never take this path: this hook
             // only runs for BYOK custom rows, never bundled first-party

package/src/providers/provider-contracts.ts

@@ -134,11 +134,13 @@ export interface ProviderDispatchContext {
   readonly outbound_fetch?: ValidatedOutboundFetch | undefined;
   /** Validated image/attachment egress; deliberately excluded from payload capture. */
   readonly outbound_attachment_fetch?: ValidatedOutboundFetch | undefined;
-  /** Validated WSS egress bound to the same selected network pool as HTTP. */
-  readonly outbound_websocket?: ValidatedOutboundWebSocket | undefined;
   /** Validated bidirectional HTTP/2 egress bound to the same selected network pool. */
   readonly outbound_http2?: ValidatedOutboundHttp2Bidi | undefined;
-  /** Built-in API-key route-selected fallback User-Agent; custom providers leave this unset. */
+  /**
+   * Route-selected fallback User-Agent from Routing Strategy; set when the
+   * operator configured one (bundled API-key providers default to the Claude
+   * CLI identity). Empty means the operator chose "None".
+   */
   readonly user_agent?: string | undefined;
   /** Gateway request id, stable across provider retries for one logical request. */
   readonly request_id?: string | undefined;
@@ -190,7 +192,8 @@ export function applyRouteUserAgent(
   if (
     credential.credential_kind === "oauth" ||
     credential.credential_kind === "scoped_access_token" ||
-    userAgent === undefined
+    userAgent === undefined ||
+    userAgent.trim().length === 0
   ) {
     return;
   }

package/src/providers/provider-metadata.ts

@@ -15,6 +15,15 @@ export interface CompatibilityProfile {
   }>;
   /** Whether requests to OpenAI/Anthropic-compatible upstream should send official CLI headers. Defaults to true. */
   readonly cli_identity?: boolean;
+  /**
+   * Direct egress for this provider uses the runtime-native fetch instead of
+   * the Node-stack pinned agent. Some upstreams meter per client transport
+   * fingerprint — OpenCode's anonymous free tier refuses the Node agent with
+   * 429 FreeUsageLimitError while accepting the native fetch byte-for-byte
+   * (verified live). The SSRF resolve/validate pass still runs for every hop;
+   * only the socket-level address pin is traded away.
+   */
+  readonly preferNativeFetch?: boolean;
   /**
    * Opts this provider into the gateway identity (`user-agent:
    * `Cartethyia/<version>`) instead of official CLI cloaking. Explicit only:
@@ -322,6 +331,14 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     hasAdapterUserAgent: true,
   },
   { id: "bai", displayName: "B.AI", baseUrl: "https://api.b.ai/v1", credentialUrl: "https://b.ai" },
+  {
+    id: "inception",
+    displayName: "Inception Labs",
+    // Version-rooted: the chat wire lives below the `/v1` root, so the
+    // declared path is `/chat/completions` (same rule as Groq/DeepInfra).
+    baseUrl: "https://api.inceptionlabs.ai/v1",
+    credentialUrl: "https://platform.inceptionlabs.ai/dashboard/api-keys",
+  },
   {
     id: "larprouter",
     displayName: "LarRouter",
@@ -630,16 +647,20 @@ export function providerBaseUrl(providerId: string): string {
 export const PROVIDER_COMPATIBILITY_PROFILES: Record<string, CompatibilityProfile> = {
   opencode: {
     endpoint_paths_by_wire_family: {
-      chat: "/inference/v1/chat/completions",
-      responses: "/inference/v1/responses",
+      chat: "/inference/openai/v1/chat/completions",
+      responses: "/inference/openai/v1/responses",
     },
+    // Direct egress must use the native fetch: the anonymous free tier refuses
+    // the Node-stack agent with 429 FreeUsageLimitError (verified live).
+    preferNativeFetch: true,
     model_wire_families: [{ pattern: "^muse-spark", wire_family: "responses" }],
   },
   "opencode-zen": {
     endpoint_paths_by_wire_family: {
-      chat: "/inference/v1/chat/completions",
-      responses: "/inference/v1/responses",
+      chat: "/inference/openai/v1/chat/completions",
+      responses: "/inference/openai/v1/responses",
     },
+    preferNativeFetch: true,
     model_wire_families: [{ pattern: "^muse-spark", wire_family: "responses" }],
   },
   "opencode-go": {

package/src/providers/provider-probe.ts

@@ -110,13 +110,13 @@ export async function buildProviderProbeRequest(
       provider_id: providerId,
       model_id: PROBE_MODEL,
       wire_family: "chat",
-      endpoint_path: "/inference/v1/chat/completions",
+      endpoint_path: "/inference/openai/v1/chat/completions",
       capabilities: {},
     } as ProviderDispatchTarget,
   );
   const headers = (await spec.buildExtraHeaders?.(probeContext(providerId), source)) ?? {};
   return {
-    url: `${providerBaseUrl(providerId).replace(/\/+$/, "")}/inference/v1/chat/completions`,
+    url: `${providerBaseUrl(providerId).replace(/\/+$/, "")}/inference/openai/v1/chat/completions`,
     headers: { "content-type": "application/json", ...headers },
     body: payload,
   };

package/src/{console → providers}/quota/cache.ts

@@ -6,7 +6,7 @@
 // Reads the pre-envelope bare result and v2-v4 envelopes during upgrade;
 // writes use v5, which records attempt time, retained-refresh errors, and
 // forces a one-time refresh for required quota accounting metadata.
-import type { ProviderQuotaResult } from "../../providers/quota/quota-contracts";
+import type { ProviderQuotaResult } from "./quota-contracts";
 import type { RedisClient } from "../../persistence/redis";
 import { TtlCache } from "../../persistence/ttl-cache";
 import { log } from "../../observability/logger";

package/src/{console → providers}/quota/refresh.ts

@@ -11,12 +11,12 @@ import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { providerAccounts } from "../../persistence/schema";
 import type { RedisClient } from "../../persistence/redis";
 import { log } from "../../observability/logger";
-import { fetchProviderQuota } from "../../providers/quota/quota-support";
-import { type FetchLike, type ProviderQuotaResult } from "../../providers/quota/quota-contracts";
-import type { ProviderId } from "../../providers/provider-contracts";
-import type { ProviderRegistry } from "../../providers/provider-registry";
+import { fetchProviderQuota } from "./quota-support";
+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 "../../providers/authentication/oauth-flow-store";
+import { record } from "../authentication/oauth-flow-store";
 
 /** Why an account quota refresh failed; `null` means the fetch succeeded. */
 export type QuotaRefreshFailureCode = "missing_credential" | "quota_fetch_failed";

package/src/security/cli-client-fingerprint.ts

@@ -50,13 +50,20 @@ const REMOTE_CLI_TOOL_UA: ReadonlyArray<{
   // filtering; MCP traffic uses `claude-code/<version>` instead.
   { toolId: "claude", pattern: /(^|[^a-z0-9])claude-cli\//i },
   { toolId: "claude", pattern: /(^|[^a-z0-9])claude-code\//i },
+  // Codex CLI (TUI/CLI builds) — the Guardian auto-review agent sends a
+  // `codex-auto-review` model that is only useful when the gateway can
+  // remap it to a serving provider. `codex-tui`, `codex-cli`, and the
+  // desktop agent's `opencode`-ish UAs all carry this prefix.
+  { toolId: "codex", pattern: /(^|[^a-z0-9])codex-(tui|cli)\//i },
 ];
 
 /**
  * Returns the remote CLI tool id recognised from the probe, or `null` when
  * the caller is not a remote-mapping client. Ordinary SDKs, curl, and local
- * mapping tools (Codex, …) stay unlabelled so their model ids resolve
- * through ordinary aliases / allowlists.
+ * mapping tools stay unlabelled so their model ids resolve through ordinary
+ * aliases / allowlists. Codex is labelled because its Guardian auto-review
+ * agent sends the hardcoded `codex-auto-review` model, which must be remapable
+ * to a serving provider for approval reviews to work at all.
  */
 export function detectRemoteCliToolId(probe: CliClientProbe): string | null {
   const userAgent = readUserAgent(probe);

package/src/transport/dispatch/attempt-finalize.ts

@@ -13,7 +13,7 @@ import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer"
 import type { ProxyRequestOutcome, ProxyRequestState } from "../request/state";
 import type { PayloadCaptureState } from "../../observability/payload-capture";
 import { finalizeRequestTelemetry } from "../guards/error-lifecycle";
-import { debitCachedQuota, quotaLens } from "../../console/quota/cache";
+import { debitCachedQuota, quotaLens } from "../../providers/quota/cache";
 import { BUDDY_PROVIDER_IDS } from "../../providers/provider-metadata";
 import { log } from "../../observability/logger";
 import {
@@ -195,6 +195,43 @@ export function providerRequestMetadataOnly(request: unknown): unknown {
   return Object.keys(metadata).length === 0 ? null : metadata;
 }
 
+/**
+ * Captures one provider request body into the stored provider-request panel.
+ *
+ * Providers send bodies in several shapes: a plain string (the common case), a
+ * `Uint8Array`/Buffer (Qoder's custom cosy encoding), or another BodyInit
+ * type (URLSearchParams, Blob, FormData) that cannot be sliced safely here.
+ * Strings and byte arrays are decoded and stored; anything else is recorded as
+ * present-but-opaque, same as the metadata path.
+ */
+function captureRequestBodyBody(
+  body: BodyInit,
+  maxBytes: number,
+): { body: unknown } | { body_present: true; body_bytes: number } {
+  if (typeof body === "string") {
+    return { body: parseCapturedBody(truncateUtf8(body, maxBytes)) };
+  }
+  if (body instanceof Uint8Array) {
+    return { body: parseCapturedBody(truncateUtf8(new TextDecoder().decode(body), maxBytes)) };
+  }
+  return { body_present: true, body_bytes: capturedBodyByteLength(body) };
+}
+
+/** Byte length of a request body in whatever shape the provider sent it. */
+function capturedBodyByteLength(body: BodyInit): number {
+  if (typeof body === "string") return Buffer.byteLength(body, "utf8");
+  if (body instanceof Uint8Array) return body.byteLength;
+  if (typeof body === "object" && body !== null && "size" in body) {
+    const size = (body as { size?: unknown }).size;
+    if (typeof size === "number" && Number.isFinite(size)) return Math.round(size);
+  }
+  if (typeof body === "object" && body !== null && "byteLength" in body) {
+    const byteLength = (body as { byteLength?: unknown }).byteLength;
+    if (typeof byteLength === "number" && Number.isFinite(byteLength)) return Math.round(byteLength);
+  }
+  return 0;
+}
+
 /**
  * Wraps a validated outbound fetch to tee the provider request/response.
  *
@@ -216,7 +253,7 @@ export function captureProviderExchange(
         : input instanceof URL
           ? input.toString()
           : input.url;
-    const rawBody = typeof init?.body === "string" ? init.body : null;
+    const rawBody = init?.body;
     const headers = selectCapturedHeaders(init);
     sink.request = {
       method: init?.method ?? "GET",
@@ -227,11 +264,11 @@ export function captureProviderExchange(
       // shape sliced up to `maxBytes` of the translated body and ran it through
       // `JSON.parse` for every attempt — content a metadata-mode tenant had
       // explicitly declined to retain, paid on every dispatch.
-      ...(rawBody === null
+      ...(rawBody === null || rawBody === undefined
         ? {}
         : captureBody
-          ? { body: parseCapturedBody(truncateUtf8(rawBody, maxBytes)) }
-          : { body_present: true, body_bytes: Buffer.byteLength(rawBody, "utf8") }),
+          ? captureRequestBodyBody(rawBody, maxBytes)
+          : { body_present: true, body_bytes: capturedBodyByteLength(rawBody) }),
     };
     const response = await inner(input, init);
     sink.response =
@@ -463,6 +500,13 @@ export function estimatedUsage(inputTokens: number, outputTokens: number): Usage
 export interface AttemptCompletion extends ProxyRequestOutcome {
   readonly modelId?: string;
   readonly error?: unknown;
+  /**
+   * The HTTP status the terminal classifier derived for a raw (non-GatewayError)
+   * failure — an upstream socket drop is 502, not the 500 the fallback implied.
+   * Only consulted when the error carries no status of its own and no wire
+   * response named one.
+   */
+  readonly terminalHttpStatus?: number;
   readonly lease?: AdmissionLease;
   /** Usage to reconcile, or undefined when this attempt consumed nothing billable. */
   readonly commitUsage?: UsageRecord;
@@ -538,6 +582,63 @@ export function completionContext(input: {
   };
 }
 
+/**
+ * The terminal-completion base the native routes (generation, responses
+ * compact, system one, web search, token count) all assemble. The proxy and
+ * streaming paths use `completionContext`; these routes previously spelled
+ * the same twelve fields by hand in six places. Callers spread this and add
+ * only what differs: status, response body, error classification.
+ */
+export function nativeCompletionBase(input: {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly tenantId: string | null;
+  readonly ingressBody: unknown;
+  readonly accountId?: string;
+  readonly accountLabel?: string;
+  readonly networkPoolId?: string;
+  readonly lease?: AdmissionLease;
+  readonly db: CartethyiaDatabase;
+  readonly telemetryBuffer?: TelemetryBatchBuffer;
+  readonly snapshotService?: { invalidate(): unknown };
+  readonly providerCapture?: ProviderExchangeCapture;
+  readonly usage?: AttemptCompletion["usage"];
+  readonly commitUsage?: AttemptCompletion["commitUsage"];
+}): Omit<
+  AttemptCompletion,
+  | "status"
+  | "responseBody"
+  | "httpStatus"
+  | "terminalHttpStatus"
+  | "error"
+  | "clientResponseText"
+  | "firstContentDeltaAtMs"
+  | "lastEventAtMs"
+  | "reportedModel"
+  | "errorCategory"
+  | "errorOrigin"
+  | "ttfbMs"
+  | "tokensPerSec"
+> {
+  return {
+    providerId: input.providerId,
+    modelId: input.modelId,
+    tenantId: input.tenantId,
+    ingressBody: input.ingressBody,
+    terminal: true,
+    ...(input.accountId === undefined ? {} : { accountId: input.accountId }),
+    ...(input.accountLabel === undefined ? {} : { accountLabel: input.accountLabel }),
+    ...(input.networkPoolId === undefined ? {} : { networkPoolId: input.networkPoolId }),
+    ...(input.lease === undefined ? {} : { lease: input.lease }),
+    db: input.db,
+    ...(input.telemetryBuffer === undefined ? {} : { telemetryBuffer: input.telemetryBuffer }),
+    ...(input.snapshotService === undefined ? {} : { snapshotService: input.snapshotService }),
+    ...(input.providerCapture === undefined ? {} : { providerCapture: input.providerCapture }),
+    ...(input.usage === undefined ? {} : { usage: input.usage }),
+    ...(input.commitUsage === undefined ? {} : { commitUsage: input.commitUsage }),
+  };
+}
+
 /**
  * Decides whether a failed attempt proves *the pool* is unusable, and which
  * HTTP status that verdict rests on.
@@ -639,13 +740,14 @@ export async function completeAttempt(
       completion.httpStatus ??
       (completion.error instanceof GatewayError
         ? completion.error.status
-        : completion.status === "completed"
-          ? 200
-          : completion.status === "cancelled"
-            ? 499
-            : completion.status === "truncated"
-              ? 502
-              : 500),
+        : completion.terminalHttpStatus ??
+          (completion.status === "completed"
+            ? 200
+            : completion.status === "cancelled"
+              ? 499
+              : completion.status === "truncated"
+                ? 502
+                : 500)),
     ...(completion.providerId === undefined ? {} : { providerId: completion.providerId }),
     ...(completion.accountId === undefined ? {} : { accountId: completion.accountId }),
     ...(completion.accountLabel === undefined ? {} : { accountLabel: completion.accountLabel }),

package/src/transport/dispatch/attempt-loop.ts

@@ -288,6 +288,7 @@ export async function runAttemptLoop<TResult, TAdapter>(
             status: terminal.status,
             errorCategory: terminal.errorCategory,
             errorOrigin: terminal.errorOrigin,
+            ...(terminal.httpStatus === undefined ? {} : { terminalHttpStatus: terminal.httpStatus }),
             error: lastError,
             tenantId: input.tenantId,
             terminal: true,
@@ -419,6 +420,7 @@ export async function runAttemptLoop<TResult, TAdapter>(
         status: terminal.status,
         errorCategory: terminal.errorCategory,
         errorOrigin: terminal.errorOrigin,
+        ...(terminal.httpStatus === undefined ? {} : { terminalHttpStatus: terminal.httpStatus }),
         error,
         tenantId: input.tenantId,
         terminal: terminalAttempt,
@@ -539,6 +541,7 @@ export async function runAttemptLoop<TResult, TAdapter>(
       status: terminal.status,
       errorCategory: terminal.errorCategory,
       errorOrigin: terminal.errorOrigin,
+      ...(terminal.httpStatus === undefined ? {} : { terminalHttpStatus: terminal.httpStatus }),
       error: lastError,
       terminal: true,
       tenantId: input.tenantId,

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

@@ -87,7 +87,9 @@ export function isEmptyStream(tally: StreamTally): boolean {
  * failing over across ordered endpoints pre-start.
  *
  * Throws GatewayError (platform_unavailable, 502, upstream) on exhaustion,
- * GatewayError (transport_closed, 499) on abort.
+ * GatewayError (deadline_exceeded, 504, upstream) when a first event never
+ * arrives within the window, and GatewayError (transport_closed, 499) on
+ * client abort.
  */
 export async function fetchWithEmptyStreamRecovery(
   endpoints: readonly string[],
@@ -197,7 +199,12 @@ async function fetchWithTimeout(
   // Race the fetch against a first-event timeout
   const timeoutPromise = new Promise<never>((_, reject) => {
     const timer = setTimeout(() => {
-      reject(new GatewayError("transport_closed", 499, "First event timeout", {}, "upstream"));
+      // A first-event timeout is the gateway waiting on a silent upstream (e.g.
+      // a provider that holds the request in a queue), not the client leaving.
+      // It must surface as a deadline failure, never as a `transport_closed`
+      // 499 — that code is reserved for genuine client cancellations and would
+      // otherwise hide a real upstream wait behind "cancelled by client".
+      reject(new GatewayError("deadline_exceeded", 504, "First event timeout", {}, "upstream"));
     }, timeoutMs);
     signal.addEventListener("abort", () => {
       clearTimeout(timer);

package/src/transport/dispatch/generation.ts

@@ -21,34 +21,16 @@
 import type { ImageGenerationOutcome, ProviderAdapter, ProviderDispatchTarget } from "../../providers/provider-contracts";
 import { GatewayError } from "../../protocol/gateway-error";
 import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
-import type { OAuthTokenRefresher, OAuthRefreshService } from "../../providers/authentication/oauth-refresh-service";
-import type { ValidatedNetworkBindingFactory } from "../../network/pool/resolver";
-import type { CartethyiaDatabase } from "../../persistence/db-handle";
-import type { RouteSnapshotService } from "../routing/route-model";
 import type { ServiceKind } from "../../protocol/canonical-model";
 import { metrics } from "../../observability/metrics";
-import type { NetworkPoolSelector } from "../../network/pool/selector";
-import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
 import type { ProxyRequestState } from "../request/state";
-import { ProxyRequestStateStore } from "../request/state";
-import { ProxyRequestPreparer } from "../request/preparer";
-import { completeAttempt, estimatedUsage } from "./attempt-finalize";
+import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
 import { captureProviderRateLimit } from "./ratelimit-capture";
 
-export interface GenerationHandlerDeps {
-  readonly db: CartethyiaDatabase;
-  readonly providerAdapters: ReadonlyMap<string, ProviderAdapter>;
-  readonly resolveProviderAdapter?: (providerId: string) => Promise<ProviderAdapter | undefined>;
-  readonly proxyPreparer: ProxyRequestPreparer;
-  readonly stateStore: ProxyRequestStateStore;
-  readonly poolSelector?: NetworkPoolSelector;
-  readonly networkBindingFactory?: ValidatedNetworkBindingFactory;
-  readonly snapshotService?: RouteSnapshotService;
-  readonly telemetryBuffer?: TelemetryBatchBuffer;
-  readonly resolveOAuthRefresher?: (providerId: string) => Promise<OAuthTokenRefresher | undefined>;
-  readonly oauthRefreshService?: OAuthRefreshService;
-}
+import type { GatewayHandlerDeps } from "./handler-deps";
+
+export type GenerationHandlerDeps = GatewayHandlerDeps;
 
 /** Which surface a handler serves. Drives candidate filtering and error copy. */
 export type GenerationKind = Extract<ServiceKind, "imageGeneration" | "videoGeneration">;
@@ -133,22 +115,23 @@ async function passThrough(
   captureProviderRateLimit(args.candidate.provider_id, args.candidate.provider_account_id, upstream.headers);
   await completeAttempt(state, {
     status: "completed",
-    providerId: args.candidate.provider_id,
-    ...(args.candidate.provider_account_id ? { accountId: args.candidate.provider_account_id } : {}),
-    ...(args.candidate.provider_account_label ? { accountLabel: args.candidate.provider_account_label } : {}),
-    ...(args.networkPoolId ? { networkPoolId: args.networkPoolId } : {}),
-    usage,
-    modelId: args.candidate.model_id,
-    lease: args.lease as never,
-    commitUsage: usage,
-    terminal: true,
-    tenantId: args.tenantId,
-    ingressBody: state.ingressBody,
+    ...nativeCompletionBase({
+      providerId: args.candidate.provider_id,
+      ...(args.candidate.provider_account_id ? { accountId: args.candidate.provider_account_id } : {}),
+      ...(args.candidate.provider_account_label ? { accountLabel: args.candidate.provider_account_label } : {}),
+      ...(args.networkPoolId ? { networkPoolId: args.networkPoolId } : {}),
+      usage,
+      modelId: args.candidate.model_id,
+      lease: args.lease as never,
+      commitUsage: usage,
+      tenantId: args.tenantId,
+      ingressBody: state.ingressBody,
+      providerCapture: args.providerCapture as never,
+      db: args.deps.db,
+      ...(args.deps.telemetryBuffer ? { telemetryBuffer: args.deps.telemetryBuffer } : {}),
+      ...(args.deps.snapshotService ? { snapshotService: args.deps.snapshotService } : {}),
+    }),
     responseBody: null,
-    providerCapture: args.providerCapture as never,
-    db: args.deps.db,
-    ...(args.deps.telemetryBuffer ? { telemetryBuffer: args.deps.telemetryBuffer } : {}),
-    ...(args.deps.snapshotService ? { snapshotService: args.deps.snapshotService } : {}),
   });
   metrics.proxy_requests_total.inc(1, { status: "completed" });
   return new Response(upstream.body, {
@@ -251,9 +234,7 @@ export function createNativeSurfaceHandler(
               provider_id: candidate.provider_id as ProviderAdapter["provider_id"],
               credential_kind: "none" as const,
             };
-        const adapter = deps.resolveProviderAdapter
-          ? await deps.resolveProviderAdapter(candidate.provider_id)
-          : deps.providerAdapters.get(candidate.provider_id);
+        const adapter = await deps.resolveProviderAdapter?.(candidate.provider_id);
         if (!adapter) {
           throw new GatewayError(
             "capability_unsupported",
@@ -292,22 +273,23 @@ export function createNativeSurfaceHandler(
           const usage = estimatedUsage(0, 0);
           await completeAttempt(state, {
             status: "completed",
-            providerId: candidate.provider_id,
-            ...(candidate.provider_account_id ? { accountId: candidate.provider_account_id } : {}),
-            ...(candidate.provider_account_label ? { accountLabel: candidate.provider_account_label } : {}),
-            ...(leases.proxySlot ? { networkPoolId: leases.proxySlot.poolId } : {}),
-            usage,
-            modelId: candidate.model_id,
-            lease: leases.lease,
-            commitUsage: usage,
-            terminal: true,
-            tenantId: prepared.authorization.tenantId,
-            ingressBody: state.ingressBody,
+            ...nativeCompletionBase({
+              providerId: candidate.provider_id,
+              ...(candidate.provider_account_id ? { accountId: candidate.provider_account_id } : {}),
+              ...(candidate.provider_account_label ? { accountLabel: candidate.provider_account_label } : {}),
+              ...(leases.proxySlot ? { networkPoolId: leases.proxySlot.poolId } : {}),
+              usage,
+              modelId: candidate.model_id,
+              lease: leases.lease,
+              commitUsage: usage,
+              tenantId: prepared.authorization.tenantId,
+              ingressBody: state.ingressBody,
+              providerCapture,
+              db: deps.db,
+              ...(deps.telemetryBuffer ? { telemetryBuffer: deps.telemetryBuffer } : {}),
+              ...(deps.snapshotService ? { snapshotService: deps.snapshotService } : {}),
+            }),
             responseBody: payload,
-            providerCapture,
-            db: deps.db,
-            ...(deps.telemetryBuffer ? { telemetryBuffer: deps.telemetryBuffer } : {}),
-            ...(deps.snapshotService ? { snapshotService: deps.snapshotService } : {}),
           });
           metrics.proxy_requests_total.inc(1, { status: "completed" });
           return jsonResponse(payload, 200, state.requestId);

package/src/transport/dispatch/handler-deps.ts

@@ -0,0 +1,32 @@
+/**
+ * The one dependency shape every gateway route handler takes.
+ *
+ * Proxy, generation, responses-compact, system one, web search, and token
+ * count all receive the same wiring. Before this module each handler spelled
+ * its own near-identical interface and `app.ts` spelled the same object five
+ * times — a new handler dep had to be added to five interfaces and five
+ * literals to reach the runtime. One shape means one place to grow.
+ */
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import type { ProviderAdapter } from "../../providers/provider-contracts";
+import type { OAuthRefreshService, OAuthTokenRefresher } from "../../providers/authentication/oauth-refresh-service";
+import type { NetworkPoolSelector } from "../../network/pool/selector";
+import type { ValidatedNetworkBindingFactory } from "../../network/pool/resolver";
+import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
+import type { ProxyRequestPreparer } from "../request/preparer";
+import type { ProxyRequestStateStore } from "../request/state";
+import type { RouteSnapshotService } from "../routing/route-model";
+
+export interface GatewayHandlerDeps {
+  readonly db: CartethyiaDatabase;
+  /** Preferred over a static map: resolves an adapter on demand and caches it. */
+  readonly resolveProviderAdapter?: (providerId: string) => Promise<ProviderAdapter | undefined>;
+  readonly proxyPreparer: ProxyRequestPreparer;
+  readonly stateStore: ProxyRequestStateStore;
+  readonly poolSelector?: NetworkPoolSelector;
+  readonly networkBindingFactory?: ValidatedNetworkBindingFactory;
+  readonly snapshotService?: RouteSnapshotService;
+  readonly telemetryBuffer?: TelemetryBatchBuffer;
+  readonly resolveOAuthRefresher?: (providerId: string) => Promise<OAuthTokenRefresher | undefined>;
+  readonly oauthRefreshService?: OAuthRefreshService;
+}

package/src/transport/dispatch/leases.ts

@@ -124,11 +124,16 @@ async function acquirePoolSlot(
     }
   }
   // Round-robin rotation rides the strategy the snapshot attached to the
-  // candidate (the pool-owning tenant scopes the cursor); absent strategy or
-  // `least_loaded` keeps the default weighted least-loaded scan.
+  // candidate (the pool-owning tenant scopes the cursor); `random` scatters
+  // each selection across eligible pools. Absent strategy or `least_loaded`
+  // keeps the default weighted least-loaded scan.
   const rotation: PoolRotation | undefined =
-    routing?.strategy === "round_robin"
-      ? { key: routing.tenantId, rotateCount: routing.rotateCount }
+    routing?.strategy === "round_robin" || routing?.strategy === "random"
+      ? {
+          key: routing.tenantId,
+          rotateCount: routing.rotateCount,
+          strategy: routing.strategy,
+        }
       : undefined;
 
   if (!poolIds?.length || !poolSelector) {