cartethyia 2.7.4 → 2.7.6

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

@@ -12,12 +12,12 @@
 import type { CanonicalEvent, SourceSurface, UsageRecord } from "../../../protocol/canonical-model";
 import { canonicalTerminal } from "../../../protocol/codecs";
 import { reasoningTextOf } from "../../../protocol/reasoning-text";
-import { MimoThinkSplitter } from "../../../providers/integrations/xiaomi-mimo/think-stream";
+import { ThinkSplitter } from "../../../protocol/think-split";
 import { createDispatchStreamEncoder, type DispatchStreamEncoder } from "../stream-bridge";
 import { THINKING_LOOP_MARKER, ThinkingLoopDetector } from "./thinking-loop";
 
 /** The terminal event shape every stream settles (or fails to settle) on. */
-export type StreamTerminalEvent = Extract<CanonicalEvent, { type: "terminal" }>;
+type StreamTerminalEvent = Extract<CanonicalEvent, { type: "terminal" }>;
 
 /**
  * SSE comment frame: valid framing on every streamed surface, ignored by
@@ -46,7 +46,7 @@ interface TruncatedEventTranscript {
 }
 
 /** Error-frame input in the shape the dispatch stream encoder accepts. */
-export type StreamErrorFrameInput = Parameters<DispatchStreamEncoder["encodeError"]>[0];
+type StreamErrorFrameInput = Parameters<DispatchStreamEncoder["encodeError"]>[0];
 
 /**
  * Per-event state and framing for one stream. Client framing and protocol
@@ -93,10 +93,11 @@ export class StreamEventPipeline {
    */
   private readonly diagnosticsCaptureMode: "none" | "metadata" | "full";
   private readonly streamEncoder: DispatchStreamEncoder;
-  // One splitter per stream: a thinking tag can straddle two provider chunks,
-  // and the text/idle bookkeeping below must see the split result, not the raw
-  // tagged chunk.
-  private readonly thinkSplitter = new MimoThinkSplitter();
+  // One splitter per stream, kept purely as a feeder for the loop guard: it
+  // reports the content currently inside an open `<think>` span so a runaway
+  // chain-of-thought is caught even when the provider wrote it into the text
+  // stream. It never re-routes the emitted events — text is forwarded verbatim.
+  private readonly thinkSplitter = new ThinkSplitter();
   /**
    * Content-level loop guard. A model that degenerates into a repeated
    * chain-of-thought keeps sending bytes, so the stall timeout — which fires
@@ -259,26 +260,17 @@ export class StreamEventPipeline {
     // `loopDetected`, so this only matters for an event already in flight;
     // dropping it is the alternative to throwing mid-stream.
     if (this.loopDetector.detected) return false;
-    // The one place every surface shares. A provider that writes its reasoning
-    // into the answer as `<think>…</think>` had that text forwarded verbatim:
-    // the chat wire happened to split it in its own decoder, so chat looked
-    // right while messages and responses — and any other provider wire whose
-    // text carries the tags — showed the raw reasoning as the answer.
+    // Text is forwarded verbatim: inline thinking tags are a per-provider
+    // decoder concern, not a universal one. Splitting them here for every
+    // surface misclassified literal `<think>` in an answer as reasoning — the
+    // answer vanished into the thinking pane and the poisoned history stopped
+    // follow-up turns. The loop guard still watches reasoning a provider puts
+    // inside an open `<think>` span, without reclassifying the answer.
     if (event.type === "content_delta" && event.content.kind === "text") {
+      const enqueued = this.enqueueOne(event, controller);
       const split = this.thinkSplitter.push(event.content.text);
-      let enqueued = false;
-      if (split.reasoning.length > 0) {
-        const reasoningEvent: CanonicalEvent = {
-          ...event,
-          content: { kind: "reasoning", payload: null, summary: split.reasoning },
-        };
-        enqueued = this.enqueueOne(reasoningEvent, controller) || enqueued;
-        if (this.guardReasoning(split.reasoning, controller)) return enqueued;
-      }
-      if (split.text.length > 0) {
-        enqueued =
-          this.enqueueOne({ ...event, content: { kind: "text", text: split.text } }, controller) ||
-          enqueued;
+      if (split.pendingReasoning.length > 0) {
+        if (this.guardReasoning(split.pendingReasoning, controller)) return true;
       }
       return enqueued;
     }
@@ -290,31 +282,8 @@ export class StreamEventPipeline {
       this.guardReasoning(reasoningTextOf(event.content) ?? "", controller);
       return enqueued;
     }
-    // Text held back for a tag that never completed must be released *before*
-    // the terminal: a content event after it is rejected by the surface
-    // encoders, and the tail of the answer would be lost instead.
     if (event.type === "terminal") {
-      const rest = this.thinkSplitter.flush();
-      if (rest.reasoning.length > 0) {
-        this.enqueueOne(
-          {
-            type: "content_delta",
-            sequence_number: event.sequence_number,
-            content: { kind: "reasoning", payload: null, summary: rest.reasoning },
-          },
-          controller,
-        );
-      }
-      if (rest.text.length > 0) {
-        this.enqueueOne(
-          {
-            type: "content_delta",
-            sequence_number: event.sequence_number,
-            content: { kind: "text", text: rest.text },
-          },
-          controller,
-        );
-      }
+      return this.enqueueOne(event, controller);
     }
     return this.enqueueOne(event, controller);
   }
@@ -335,29 +304,6 @@ export class StreamEventPipeline {
   ): boolean {
     const reason = text.length > 0 ? this.loopDetector.push(text) : undefined;
     if (reason === undefined) return false;
-    // Flush before the terminal: content after it is rejected by the surface
-    // encoders, and the held-back text would be lost.
-    const rest = this.thinkSplitter.flush();
-    if (rest.reasoning.length > 0) {
-      this.enqueueOne(
-        {
-          type: "content_delta",
-          sequence_number: this.lastSequenceNumber + 1,
-          content: { kind: "reasoning", payload: null, summary: rest.reasoning },
-        },
-        controller,
-      );
-    }
-    if (rest.text.length > 0) {
-      this.enqueueOne(
-        {
-          type: "content_delta",
-          sequence_number: this.lastSequenceNumber + 1,
-          content: { kind: "text", text: rest.text },
-        },
-        controller,
-      );
-    }
     this.enqueueOne(
       canonicalTerminal({
         sequenceNumber: this.lastSequenceNumber + 1,

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

@@ -39,7 +39,7 @@ import {
 import { KEEPALIVE_COMMENT_BYTES, type StreamEventPipeline } from "./encoder";
 
 /** Collaborators the stream tail reads from the dispatch handler. */
-export interface StreamFinalizeDeps {
+interface StreamFinalizeDeps {
   readonly db: CartethyiaDatabase;
   readonly poolSelector?: NetworkPoolSelector | undefined;
   readonly telemetryBuffer?: TelemetryBatchBuffer | undefined;
@@ -56,7 +56,7 @@ export interface StreamCandidateIdentity {
 }
 
 /** What the stream tail needs from the attempt's input. */
-export interface StreamFinalizeInput {
+interface StreamFinalizeInput {
   readonly state: ProxyRequestState;
   readonly deps: StreamFinalizeDeps;
   readonly prepared: PreparedProxyRequest;

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

@@ -64,7 +64,7 @@ import { StreamEventPipeline } from "./encoder";
 import { StreamFinalizer, type StreamCandidateIdentity } from "./finalize";
 
 /** Collaborators the streaming branch reads from the dispatch handler. */
-export interface StreamingDispatchDeps {
+interface StreamingDispatchDeps {
   readonly db: CartethyiaDatabase;
   readonly networkBindingFactory?: ValidatedNetworkBindingFactory | undefined;
   readonly poolSelector?: NetworkPoolSelector | undefined;
@@ -73,7 +73,7 @@ export interface StreamingDispatchDeps {
 }
 
 /** Everything one streamed attempt needs, all resolved by its caller. */
-export interface StreamingDispatchInput {
+interface StreamingDispatchInput {
   readonly state: ProxyRequestState;
   readonly deps: StreamingDispatchDeps;
   readonly prepared: PreparedProxyRequest;
@@ -228,7 +228,11 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
       if (!isWrappedInjectionProvider(candidate.provider_id)) return {};
       const text = resolveTenantSystemPrompt(
         await readTenantSystemPromptsForDispatch(deps.db, prepared.authorization.snapshot.tenant_id),
-        { providerId: candidate.provider_id, modelId: candidate.model_id },
+        {
+          providerId: candidate.provider_id,
+          modelId: candidate.model_id,
+          requestedModel: prepared.plan?.requested_model ?? candidate.model_id,
+        },
       )?.text;
       return text === undefined ? {} : { tenantSystemPrompt: text };
     })()),

package/src/transport/dispatch/streaming/thinking-loop.ts

@@ -70,7 +70,7 @@ const SEGMENT_MIN_CLUSTER = 4;
  *  would hide every later prose paragraph from the heuristics. */
 const CODE_LINE = /^(?:[ \t]*```.*|(?: {2,}|\t)(?![ \t]*(?:[-*+]|\d+[.)])[ \t]).*|.*[{}[\](;,>][ \t]*)$/gm;
 
-export interface ThinkingLoopConfig {
+interface ThinkingLoopConfig {
   readonly enabled?: boolean;
 }
 

package/src/transport/dispatch/systemone.ts

@@ -1,11 +1,15 @@
 import type { ProviderAdapter, ProviderDispatchTarget } from "../../providers/provider-contracts";
 import { GatewayError } from "../../protocol/gateway-error";
-import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
 import { metrics } from "../../observability/metrics";
-import { parseThinkingSuffix } from "../../protocol/translation/thinking";
-import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
-import { repriceUsage, usageFromProvider } from "../../providers/provider-usage";
+import { estimatedUsage, nativeCompletionBase, completeAttempt } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
+import {
+  networkFetchContext,
+  requireRecordBody,
+  resolveAttemptCredential,
+  stripThinkingSuffix,
+  usageFromUpstreamClone,
+} from "./native-shared";
 
 /**
  * The native System One route (`POST /v1/systemone`) and the dependency surface
@@ -20,7 +24,7 @@ import { runAttemptLoop } from "./attempt-loop";
  */
 import type { GatewayHandlerDeps } from "./handler-deps";
 
-export type SystemoneHandlerDeps = GatewayHandlerDeps;
+type SystemoneHandlerDeps = GatewayHandlerDeps;
 
 /** Adapter that can serve a System One decision request. */
 type SystemoneAdapter = ProviderAdapter & {
@@ -31,10 +35,10 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
   return async ({ request }: { request: Request }): Promise<Response> => {
     const state = deps.stateStore.require(request);
     const authorization = state.authorization;
-    const body = state.ingressBody;
-    if (!authorization || body === null || typeof body !== "object" || Array.isArray(body))
-      throw new GatewayError("invalid_request", 400, "systemone request body must be a JSON object (request {requestId}). Check the shape of what you sent — then resend 🪞");
-    const decision = body as Record<string, unknown>;
+    const decision = requireRecordBody(
+      state,
+      "systemone request body must be a JSON object (request {requestId}). Check the shape of what you sent — then resend 🪞",
+    );
     if (typeof decision.model !== "string" || decision.model.trim().length === 0)
       throw new GatewayError("invalid_request", 400, "model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
     // A thinking suffix (`model(high)`) is stripped for the same reason the
@@ -42,9 +46,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
     // allowlist and the route plan, and `(high)` is not part of any registered
     // id. The level itself is dropped — a decision request carries no reasoning
     // effort to shape, and the body is passed upstream verbatim.
-    const { model: bareModel } = parseThinkingSuffix(decision.model);
-    const decisionBody: Record<string, unknown> =
-      bareModel === decision.model ? decision : { ...decision, model: bareModel };
+    const { bareModel, body: decisionBody } = stripThinkingSuffix(decision.model, decision);
     // Trust boundary only: the decision model's own question shapes are
     // upstream's to validate. `state` and a `questions` object are what make a
     // System One request a System One request at all.
@@ -60,7 +62,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
     const prepared = await deps.proxyPreparer.prepareNativeService({
       model: bareModel,
       serviceKind: "systemone",
-      authorization,
+      authorization: authorization!,
       ...(state.abortController.signal ? { signal: state.abortController.signal } : {}),
       ...(state.clientUserAgent === undefined ? {} : { clientUserAgent: state.clientUserAgent }),
     });
@@ -85,19 +87,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
         "no eligible System One route (request {requestId}). The bouncer stepped out — come back shortly 🚪",
       ),
       prepare: async (candidate) => {
-        const credential = candidate.provider_account_id
-          ? await resolveCredentialForAccount(
-              deps.db,
-              candidate.provider_id,
-              candidate.provider_account_id,
-              deps.oauthRefreshService && deps.resolveOAuthRefresher
-                ? { refreshService: deps.oauthRefreshService, resolveRefresher: deps.resolveOAuthRefresher }
-                : undefined,
-            )
-          : {
-              provider_id: candidate.provider_id as ProviderAdapter["provider_id"],
-              credential_kind: "none" as const,
-            };
+        const credential = await resolveAttemptCredential(deps, candidate);
         const adapter = (await deps.resolveProviderAdapter?.(candidate.provider_id)) as SystemoneAdapter | undefined;
         if (!adapter || typeof adapter.systemone !== "function")
           throw new GatewayError(
@@ -131,14 +121,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
           deadline: state.deadlineMs,
           abort_signal: state.abortController.signal,
           ...(candidate.user_agent === undefined ? {} : { user_agent: candidate.user_agent }),
-          ...(deps.networkBindingFactory
-            ? {
-                outbound_fetch: deps.networkBindingFactory.fetch(
-                  leases.proxySlot?.poolId,
-                  authorization.tenantId,
-                ),
-              }
-            : {}),
+          ...networkFetchContext(deps, leases.proxySlot?.poolId, authorization!.tenantId),
         });
         if (!response.ok) {
           // Surface the upstream decision error verbatim: it is the operator's
@@ -154,20 +137,9 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
         // Prefer the usage the decision endpoint reported; fall back to the
         // fixed native estimate. `response.clone()` leaves the body readable
         // for the client.
-        let reportedUsage: ReturnType<typeof usageFromProvider>;
-        try {
-          const parsed: unknown = await response.clone().json();
-          reportedUsage = usageFromProvider(
-            typeof parsed === "object" && parsed !== null
-              ? (parsed as Record<string, unknown>)["usage"]
-              : undefined,
-          );
-        } catch {
-          reportedUsage = undefined;
-        }
-        const usage = repriceUsage(
-          reportedUsage ??
-            estimatedUsage(prepared.estimatedInputTokens, prepared.estimatedOutputTokens),
+        const usage = await usageFromUpstreamClone(
+          response,
+          estimatedUsage(prepared.estimatedInputTokens, prepared.estimatedOutputTokens),
           candidate.provider_id,
           candidate.model_id,
         );

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

@@ -36,31 +36,33 @@
 import type { ProviderAdapter, ProviderDispatchTarget } from "../../providers/provider-contracts";
 import { GatewayError } from "../../protocol/gateway-error";
 import { isRecord } from "../../protocol/codecs";
-import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
 import { metrics } from "../../observability/metrics";
+import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
 import type { ProxyRequestState } from "../request/state";
 import type { PreparedNativeRequest } from "../request/preparer";
 import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
+import { finalizeRequestTelemetry } from "../guards/error-lifecycle";
 import { runAttemptLoop } from "./attempt-loop";
+import { hasScope, networkFetchContext, requireRecordBody, resolveAttemptCredential } from "./native-shared";
 
 import type { GatewayHandlerDeps } from "./handler-deps";
 
-export type TokenCountHandlerDeps = GatewayHandlerDeps;
+type TokenCountHandlerDeps = GatewayHandlerDeps;
 
 /** Builds the `POST /v1/messages/count_tokens` handler. */
 export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
   return async ({ request }: { request: Request }): Promise<Response> => {
     const state = deps.stateStore.require(request);
     const authorization = state.authorization;
-    const body = state.ingressBody;
-    if (!authorization || body === null || typeof body !== "object" || Array.isArray(body)) {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        "The count_tokens body must be a JSON object (request {requestId}), the same shape POST /v1/messages accepts. Check the shape of what you sent — then resend 🪞",
-      );
+    const countBody = requireRecordBody(
+      state,
+      "The count_tokens body must be a JSON object (request {requestId}), the same shape POST /v1/messages accepts. Check the shape of what you sent — then resend 🪞",
+    );
+    // `requireRecordBody` already refused a missing authorization; this guard
+    // exists only to narrow the type for the code below.
+    if (!authorization) {
+      throw new GatewayError("invalid_request", 400, "authentication required (request {requestId})");
     }
-    const countBody = body as Record<string, unknown>;
 
     // `model` names the route and `messages` is what gets counted; both are the
     // upstream's own required fields, so the gateway does not restate its own
@@ -71,7 +73,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
     if (!Array.isArray(countBody.messages)) {
       throw new GatewayError("invalid_request", 400, "messages must be an array (request {requestId}) — there is nothing to count without it. Check the shape of what you sent — then resend 🪞");
     }
-    if (!authorization.snapshot.scopes?.includes("routing:invoke" as never)) {
+    if (!hasScope(authorization?.snapshot.scopes, "routing:invoke")) {
       throw new GatewayError(
         "policy_rejected",
         403,
@@ -93,7 +95,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
       // real 429/503 — a fabricated count would tell the client its context
       // fits when nothing is there to serve the turn that follows.
       if (!(error instanceof GatewayError) || error.code !== "capability_unsupported") throw error;
-      return estimatedCountResponse(state, countBody);
+      return estimatedCountResponse(state, countBody, deps.telemetryBuffer, deps.db);
     }
 
     return runAttemptLoop<Response, ProviderAdapter>({
@@ -116,19 +118,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
         "no eligible route can count tokens for this model (request {requestId}). The bouncer stepped out — come back shortly 🚪",
       ),
       prepare: async (candidate) => {
-        const credential = candidate.provider_account_id
-          ? await resolveCredentialForAccount(
-              deps.db,
-              candidate.provider_id,
-              candidate.provider_account_id,
-              deps.oauthRefreshService && deps.resolveOAuthRefresher
-                ? { refreshService: deps.oauthRefreshService, resolveRefresher: deps.resolveOAuthRefresher }
-                : undefined,
-            )
-          : {
-              provider_id: candidate.provider_id as ProviderAdapter["provider_id"],
-              credential_kind: "none" as const,
-            };
+        const credential = await resolveAttemptCredential(deps, candidate);
         const adapter = await deps.resolveProviderAdapter?.(candidate.provider_id);
         if (!adapter) {
           throw new GatewayError("capability_unsupported", 400, "token counting is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰");
@@ -167,14 +157,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
           deadline: state.deadlineMs,
           abort_signal: state.abortController.signal,
           ...(candidate.user_agent === undefined ? {} : { user_agent: candidate.user_agent }),
-          ...(deps.networkBindingFactory
-            ? {
-                outbound_fetch: deps.networkBindingFactory.fetch(
-                  leases.proxySlot?.poolId,
-                  authorization.tenantId,
-                ),
-              }
-            : {}),
+          ...networkFetchContext(deps, leases.proxySlot?.poolId, authorization.tenantId),
         });
 
         // A count is free and generates nothing, so nothing is reserved or
@@ -221,20 +204,40 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
  *
  * No attempt is finalized: nothing was leased, nothing was sent upstream, and
  * no provider produced this number, so recording it against an account would
- * invent usage the account never served. The request still gets an outcome —
- * without one the `afterResponse` hook finalizes it as a failure, and a count
- * that answered 200 would show up in Console Log as an error.
+ * invent usage the account never served. The request is still finalized through
+ * `finalizeRequestTelemetry` (the early-rejection pattern) — without it the
+ * latency histogram, the `request_complete` console event, and the durable
+ * telemetry row all miss this request — and `state.completed` prevents the
+ * `afterResponse` fallback from finalizing it a second time.
  */
 function estimatedCountResponse(
   state: ProxyRequestState,
   countBody: Record<string, unknown>,
+  telemetryBuffer: TelemetryBatchBuffer | undefined,
+  db: GatewayHandlerDeps["db"],
 ): Response {
   const inputTokens = estimateMessagesInputTokens(countBody);
   const payload = JSON.stringify({ input_tokens: inputTokens });
-  state.outcome = { status: "completed", httpStatus: 200 };
+  // The request still gets an outcome — without one the `afterResponse` hook
+  // would finalize it as a failure, and a count that answered 200 would show up
+  // in Console Log as an error. `usage` is a zero-priced estimate: nothing was
+  // leased and no provider produced this number, so recording a cost against an
+  // account would invent usage the account never served (`estimated_cost: null`).
+  state.outcome = {
+    status: "completed",
+    httpStatus: 200,
+    usage: estimatedUsage(inputTokens, 0),
+  };
   state.completed = true;
   state.clientResponseText = payload;
   metrics.proxy_requests_total.inc(1, { status: "completed" });
+  // Finalize telemetry inline (the early-rejection pattern) instead of routing
+  // through `completeAttempt`: there was no lease and no provider — but the
+  // latency histogram, the `request_complete` console event, and the durable
+  // row must still happen, exactly once. `completed = true` also disables the
+  // `afterResponse` fallback, which is what used to make this request vanish
+  // from telemetry entirely.
+  if (telemetryBuffer) finalizeRequestTelemetry(state, telemetryBuffer, db);
   return new Response(payload, {
     headers: {
       "content-type": "application/json",
@@ -255,7 +258,7 @@ function estimatedCountResponse(
  * `/v1/messages?beta=true/count_tokens` — the counting segment lands inside the
  * query, so the upstream sees the chat path with junk after it and never counts.
  */
-export function joinCountTokensPath(endpoint: string): string {
+function joinCountTokensPath(endpoint: string): string {
   const queryAt = endpoint.indexOf("?");
   const path = queryAt === -1 ? endpoint : endpoint.slice(0, queryAt);
   const query = queryAt === -1 ? "" : endpoint.slice(queryAt);

package/src/transport/dispatch/websearch.ts

@@ -16,51 +16,44 @@
  */
 import type { ProviderAdapter, ProviderDispatchTarget } from "../../providers/provider-contracts";
 import { GatewayError } from "../../protocol/gateway-error";
-import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
 import { metrics } from "../../observability/metrics";
-import { parseThinkingSuffix } from "../../protocol/translation/thinking";
 import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
+import {
+  hasScope,
+  jsonResponse,
+  networkFetchContext,
+  requireRecordBody,
+  resolveAttemptCredential,
+  stripThinkingSuffix,
+} from "./native-shared";
 
 import type { GatewayHandlerDeps } from "./handler-deps";
 
-export type WebsearchHandlerDeps = GatewayHandlerDeps;
-
-
+type WebsearchHandlerDeps = GatewayHandlerDeps;
 
 /** Adapter that can serve a web-search request. */
 type WebsearchAdapter = ProviderAdapter & {
   websearch: NonNullable<ProviderAdapter["websearch"]>;
 };
 
-function jsonResponse(payload: unknown, status: number, requestId: string): Response {
-  return new Response(JSON.stringify(payload), {
-    status,
-    headers: {
-      "content-type": "application/json",
-      "cache-control": "no-store",
-      "x-request-id": requestId,
-    },
-  });
-}
-
 export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
   return async ({ request }: { request: Request }): Promise<Response> => {
     const state = deps.stateStore.require(request);
     const authorization = state.authorization;
-    const body = state.ingressBody;
-    if (!authorization || body === null || typeof body !== "object" || Array.isArray(body))
-      throw new GatewayError("invalid_request", 400, "The search body must be a JSON object (request {requestId}). Send one with at least a model and a query. Check the shape of what you sent — then resend 🪞");
-    const search = body as Record<string, unknown>;
+    const search = requireRecordBody(state, "The search body must be a JSON object (request {requestId}). Send one with at least a model and a query. Check the shape of what you sent — then resend 🪞");
+    // `requireRecordBody` already refused a missing authorization; this guard
+    // exists only to narrow the type for the code below.
+    if (!authorization) {
+      throw new GatewayError("invalid_request", 400, "authentication required (request {requestId})");
+    }
     if (typeof search.model !== "string" || search.model.trim().length === 0)
       throw new GatewayError("invalid_request", 400, "A model is required (request {requestId}): it names the search provider to use. Check the shape of what you sent — then resend 🪞");
     // The search "model" names the provider (or an alias/combo of one). A
     // thinking suffix is stripped for the same reason the canonical preparer
     // strips it: it is not part of any registered id.
-    const { model: bareModel } = parseThinkingSuffix(search.model);
-    const searchBody: Record<string, unknown> =
-      bareModel === search.model ? search : { ...search, model: bareModel };
-    if (!authorization.snapshot.scopes?.includes("search:invoke" as never)) {
+    const { bareModel, body: searchBody } = stripThinkingSuffix(search.model, search);
+    if (!hasScope(authorization?.snapshot.scopes, "search:invoke")) {
       throw new GatewayError("policy_rejected", 403, "search not allowed for this key (request {requestId}) — enable search:invoke on the API key. Not allowed by policy — no hard feelings 🫂");
     }
     // Trust boundary only: the query must be a non-empty string. The adapter
@@ -91,19 +84,7 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
       strictPoolSelection: false,
       exhaustedError: new GatewayError("route_unavailable", 503, "no eligible search route (request {requestId}). The bouncer stepped out — come back shortly 🚪"),
       prepare: async (candidate) => {
-        const credential = candidate.provider_account_id
-          ? await resolveCredentialForAccount(
-              deps.db,
-              candidate.provider_id,
-              candidate.provider_account_id,
-              deps.oauthRefreshService && deps.resolveOAuthRefresher
-                ? { refreshService: deps.oauthRefreshService, resolveRefresher: deps.resolveOAuthRefresher }
-                : undefined,
-            )
-          : {
-              provider_id: candidate.provider_id as ProviderAdapter["provider_id"],
-              credential_kind: "none" as const,
-            };
+        const credential = await resolveAttemptCredential(deps, candidate);
         const adapter = (await deps.resolveProviderAdapter?.(candidate.provider_id)) as WebsearchAdapter | undefined;
         if (!adapter || typeof adapter.websearch !== "function")
           throw new GatewayError(
@@ -132,14 +113,7 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
           deadline: state.deadlineMs,
           abort_signal: state.abortController.signal,
           ...(candidate.user_agent === undefined ? {} : { user_agent: candidate.user_agent }),
-          ...(deps.networkBindingFactory
-            ? {
-                outbound_fetch: deps.networkBindingFactory.fetch(
-                  leases.proxySlot?.poolId,
-                  authorization.tenantId,
-                ),
-              }
-            : {}),
+          ...networkFetchContext(deps, leases.proxySlot?.poolId, authorization.tenantId),
         });
         const payload = {
           provider: candidate.provider_id,

package/src/transport/drain-endpoint.ts

@@ -20,7 +20,7 @@
 import { timingSafeEqual } from "node:crypto";
 import { GatewayError } from "../protocol/gateway-error";
 
-export interface DrainEndpointDeps {
+interface DrainEndpointDeps {
   /** Shared secret; the route is registered only when this is set. */
   readonly token: string;
   /** Begins the graceful drain (the process's own shutdown path). */

package/src/transport/failure-policy.ts

@@ -656,6 +656,12 @@ const QUOTA_ERROR_IDENTIFIERS: ReadonlySet<string> = new Set([
   // it is a spend/limit verdict, never an auth one, so it must classify as
   // quota (a cooldown) instead of `auth_invalidated`.
   "110",
+  // Qoder also reports quota exhaustion as `{"code":116,"error":"quota
+  // exceeded"}` (seen on the IDE model-server surface with a 499/stream
+  // close). The 499 special-case below already treats qoder 499 as quota;
+  // naming the code here makes any status that carries it classify as quota
+  // instead of `invalid_request`/`authentication_failed`.
+  "116",
   // 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
@@ -914,7 +920,21 @@ export async function mapUpstreamHttpError(response: Response, providerId: strin
       ? { code: "context_length_exceeded" as const, status: 413, origin: "upstream" as const }
       : classifyUpstreamError(response.status, identifier);
   const extracted = extractUpstreamMessage(parsedBody ?? text);
-  const message = (extracted.length > 0 ? extracted : text.trim() || `Provider returned HTTP ${response.status}.`).slice(0, MAX_UPSTREAM_ERROR_BYTES).replace(/[\r\n]+/g, " ");
+  let message =
+    extracted.length > 0
+      ? extracted
+      : text.trim() || `Provider returned HTTP ${response.status}.`;
+  // A bare "Provider returned HTTP <5xx>" tells the operator nothing actionable;
+  // platform-unavailable fallbacks get the same human sign-off every other
+  // gateway error carries. The raw upstream body stays in `details.raw` for
+  // diagnostics either way.
+  if (
+    classification.code === "platform_unavailable" &&
+    message === `Provider returned HTTP ${response.status}.`
+  ) {
+    message = `The provider's service is temporarily unavailable (HTTP ${response.status}) (request {requestId}). Your request did not go through — wait a moment and try again. Hold tight ☁️`;
+  }
+  message = message.slice(0, MAX_UPSTREAM_ERROR_BYTES).replace(/[\r\n]+/g, " ");
   const headerWaitMs = parseUpstreamBackoff(response.headers);
   // A queue carries its own interval, which is the one the caller must honour:
   // it is what the upstream promised, while `Retry-After` may be absent or may

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

@@ -20,12 +20,6 @@ import { createAccessDecision } from "../../security/access-control";
 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