@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

package/src/responses/state.ts

@@ -6,16 +6,23 @@ import { windowsSecretAclApplies } from "../lib/windows-secret-acl";
 import type { OcxProviderContinuationState } from "../types";
 import {
   deleteResponseSpill,
+  inspectResponseSpillDir,
   noteStubSwapForTest,
   readResponseSpill,
   recoverOrphanedResponseSpills,
+  resetPeriodicSpillSweepCursorForTests,
   responseSpillDirectory,
   responseSpillPayloadCap,
+  sweepOrphanedResponseSpillsPeriodically,
+  type ResponseSpillDirInspection,
   type ResponseSpillRef,
   writeResponseSpillDurably,
 } from "./spill-store";
+import { collectReferencedSpillFileNames, snapshotReferencedSpillFileNames } from "./state/spill-inspect";
+import { selectSnapshotEntries } from "./state/snapshot-select";
 import { clientCarriedPrefixLength, providerIssuedIdentity } from "./state/replay-fingerprint";
 export type { ResponseStateTempRecoveryResult, ResponseStateTempRecoveryOptions } from "./state/temp-recovery";
+export type { ResponseSpillDirInspection } from "./spill-store";
 export { recoverStaleResponseStateTemps, reclaimAbandonedResponseStateTemps, inspectAbandonedResponseStateTemps, sweepAbandonedResponseStateTemps } from "./state/temp-recovery";
 import { recoverStaleResponseStateTemps } from "./state/temp-recovery";
 export type { ResponseSpillWriteFailureCode, ResponseSpillWriteStatus, ResponseSpillWriteFailureOrigin } from "./state/spill-failure";
@@ -36,6 +43,7 @@ import {
   spillQueueAccounting,
   spillQueueHoldsResidentCandidate,
   spillQueuePendingBytes,
+  spillQueueReferencedSpillFileNames,
   spillQueueResidentCandidates,
   spillQueueSupersededSpillFor,
 } from "./state/spill-queue";
@@ -144,6 +152,7 @@ let residentResponseBytes = 0;
 let oldestResidentId: string | undefined;
 let oldestResidentAt: number | null = null;
 let byteCapOverride: number | null = null;
+let snapshotTotalCapOverride: number | null = null;
 let stateRevision = 0;
 /** Byte length and digest of the last snapshot actually written, for the
  *  identical-payload skip and the size-scaled debounce. The payload itself is not
@@ -215,6 +224,15 @@ export function setResponseStateByteCapForTests(bytes: number | null): void {
   byteCapOverride = bytes;
 }
 
+function snapshotTotalBytes(): number {
+  return snapshotTotalCapOverride ?? SNAPSHOT_TOTAL_MAX_BYTES;
+}
+
+/** Test-only: lower/restore the durable snapshot byte budget (null restores the default). */
+export function setResponseStateSnapshotByteCapForTests(bytes: number | null): void {
+  snapshotTotalCapOverride = bytes;
+}
+
 /** Test-only: current in-memory byte accounting (proves evictions release their bytes). */
 export function getStoredResponseBytesForTests(): number {
   return storedResponseBytes;
@@ -655,14 +673,27 @@ function ensureLoaded(): void {
   } catch {
     /* missing/corrupt snapshot: start empty */
   }
-  const referenced = new Set<string>();
-  for (const state of states.values()) {
-    if (state.kind === "spill") referenced.add(state.spill.fileName);
-  }
-  try { recoverOrphanedResponseSpills(referenced); } catch { /* best effort */ }
+  try { recoverOrphanedResponseSpills(ownedSpillFileNames()); } catch { /* best effort */ }
   pruneResponses();
 }
 
+/** Every file name the process still needs: live stubs, deferred unlinks, and queued publications. */
+function ownedSpillFileNames(): Set<string> {
+  const referenced = collectReferencedSpillFileNames(states.values(), pendingSpillUnlinks);
+  for (const name of spillQueueReferencedSpillFileNames()) referenced.add(name);
+  return referenced;
+}
+
+/** Liveness-tick counterpart of the orphan GC in ensureLoaded; a no-op until first load. */
+export function sweepOrphanedResponseSpills(): number {
+  if (!loaded) return 0;
+  try {
+    return sweepOrphanedResponseSpillsPeriodically(ownedSpillFileNames()).removed;
+  } catch {
+    return 0;
+  }
+}
+
 type SnapshotWriteOutcome = "stable" | "unstable" | "failed";
 
 async function writeBoundedSnapshot(path: string, attemptLimit: number): Promise<SnapshotWriteOutcome> {
@@ -674,28 +705,7 @@ async function writeBoundedSnapshot(path: string, attemptLimit: number): Promise
   try {
     for (let attempt = 0; attempt < attemptLimit; attempt += 1) {
       const revision = stateRevision;
-      const entries: Array<[string, unknown]> = [];
-      let total = 0;
-      // Newest-first so the most recent chains survive both legacy snapshot caps.
-      for (const [id, state] of [...states].reverse()) {
-        let persistable: unknown;
-        if (state.kind === "resident") {
-          const { sizeBytes: _sizeBytes, kind: _kind, ...resident } = state;
-          persistable = resident;
-        } else {
-          const { sizeBytes: _sizeBytes, ...smallState } = state;
-          persistable = smallState;
-        }
-        const persistEntry: [string, unknown] = [id, persistable];
-        // UTF-8 bytes, not UTF-16 code units: multibyte items otherwise slip
-        // past both snapshot caps at up to 2x the intended size.
-        const size = Buffer.byteLength(JSON.stringify(persistEntry), "utf8");
-        if (state.kind === "resident" && size > SNAPSHOT_ENTRY_MAX_BYTES) continue;
-        if (total + size > SNAPSHOT_TOTAL_MAX_BYTES) break;
-        total += size;
-        entries.push(persistEntry);
-      }
-      entries.reverse();
+      const entries = selectSnapshotEntries(states, snapshotTotalBytes(), SNAPSHOT_ENTRY_MAX_BYTES);
       const payload = JSON.stringify({ version: 2, states: entries });
       const payloadBytes = Buffer.byteLength(payload, "utf8");
       const payloadDigest = Bun.hash(payload).toString(36);
@@ -1226,6 +1236,19 @@ export function responseStateMetrics(): ResponseStateMetrics {
   };
 }
 
+/**
+ * Read-only spill report for `ocx doctor` and /api/system/memory. Owned = live
+ * stubs, deferred unlinks, queued publications, and snapshot references (what a
+ * restart re-owns). Shares the reclaim's orphan predicate; never unlinks.
+ */
+export function inspectResponseSpillStorage(): ResponseSpillDirInspection {
+  const referenced = ownedSpillFileNames();
+  for (const name of snapshotReferencedSpillFileNames(snapshotPath(), SNAPSHOT_FILE_MAX_BYTES)) {
+    referenced.add(name);
+  }
+  return inspectResponseSpillDir(referenced);
+}
+
 /**
  * Cache completed output and max_output_tokens partial output for previous_response_id replay.
  * Content-filtered incomplete and failed output are not authoritative replay history.
@@ -1307,6 +1330,7 @@ export function clearResponseStateMemoryForTests(): void {
   }
   pendingPersistPath = null;
   resetSpillQueueForTests();
+  resetPeriodicSpillSweepCursorForTests();
   states.clear();
   storedResponseBytes = 0;
   residentResponseBytes = 0;

package/src/server/audio-client.ts

@@ -2,7 +2,7 @@ import { createHash, timingSafeEqual } from "node:crypto";
 import { formatErrorResponse } from "../bridge";
 import type { OcxConfig } from "../types";
 import { captureExplicitOpenAiCallerAuth, selectOpenAiImagesProvider } from "../providers/openai-sidecar";
-import { isProxyAdmissionSecret, type DataPlaneAdmission } from "./auth-cors";
+import { isProxyAdmissionSecret, type DataPlaneAdmission, type DataPlaneAdmissionOptions } from "./auth-cors";
 import { resolveAudioAdmission } from "./audio-upstream";
 
 export const AUDIO_WEBSOCKET_PROTOCOL = "opencodex-audio";
@@ -16,7 +16,12 @@ export interface AudioClient {
 }
 
 /** Browser protocols are an audio-only credential carrier; only the public marker is echoed. */
-export function resolveAudioClient(req: Request, config: OcxConfig, required = false): AudioClient | Response | null {
+export function resolveAudioClient(
+  req: Request,
+  config: OcxConfig,
+  required = false,
+  options: DataPlaneAdmissionOptions = {},
+): AudioClient | Response | null {
   const headers = new Headers(req.headers);
   let protocol: string | undefined;
   let carrier = false;
@@ -43,7 +48,7 @@ export function resolveAudioClient(req: Request, config: OcxConfig, required = f
       }
     }
   }
-  const admission = resolveAudioAdmission(headers, config);
+  const admission = resolveAudioAdmission(headers, config, options);
   if (!admission) {
     const bearer = /^Bearer\s+([^\s,]+)$/i.exec(headers.get("authorization") ?? "")?.[1];
     const platformKey = selectOpenAiImagesProvider(config).keyed?.apiKey;

package/src/server/audio-upstream.ts

@@ -20,6 +20,7 @@ import {
   resolveDataPlaneAdmissionSecret,
   validateForwardAdmissionCredential,
   type DataPlaneAdmission,
+  type DataPlaneAdmissionOptions,
 } from "./auth-cors";
 import { codexAccountSelectionForTurn } from "./lifecycle";
 import type { RequestLogContext } from "./request-log";
@@ -28,16 +29,20 @@ export const TRANSCRIPTION_MODEL = "gpt-4o-transcribe";
 export const LIVE_AUDIO_MODEL = "gpt-live-1-codex";
 
 /** Audio keys remain identifiable even on the otherwise unauthenticated local listener. */
-export function resolveAudioAdmission(headers: Headers, config: OcxConfig): DataPlaneAdmission | null {
+export function resolveAudioAdmission(
+  headers: Headers,
+  config: OcxConfig,
+  options: DataPlaneAdmissionOptions = {},
+): DataPlaneAdmission | null {
   const dedicated = headers.get("x-opencodex-api-key")?.trim();
-  if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated");
+  if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated", options);
   const authorization = headers.get("authorization")?.trim();
   if (authorization) {
     const token = /^Bearer\s+([^\s,]+)$/i.exec(authorization)?.[1];
-    return token ? resolveDataPlaneAdmissionSecret(token, config, "bearer") : null;
+    return token ? resolveDataPlaneAdmissionSecret(token, config, "bearer", options) : null;
   }
   const key = headers.get("x-api-key")?.trim();
-  return key ? resolveDataPlaneAdmissionSecret(key, config, "x-api-key") : null;
+  return key ? resolveDataPlaneAdmissionSecret(key, config, "x-api-key", options) : null;
 }
 
 export interface AudioUpstream {

package/src/server/auth-cors.ts

@@ -312,14 +312,29 @@ export function isApiAuthRequired(config: Pick<OcxConfig, "hostname">): boolean
  * So this type is deliberately narrow: it cannot masquerade as a business config, and a policy
  * view that leaks into a routing path fails to typecheck rather than silently taking effect.
  */
-export type RequestPolicyView = Pick<OcxConfig, "hostname" | "corsAllowOrigins" | "apiKeys">;
+export interface LinkIngressPolicy {
+  allowedKeyIds: ReadonlySet<string>;
+}
+
+export type RequestPolicyView = Pick<OcxConfig, "hostname" | "corsAllowOrigins" | "apiKeys"> & {
+  linkIngress?: LinkIngressPolicy;
+};
+
+export type DataPlaneAdmissionOptions = {
+  linkIngress?: ReadonlySet<string>;
+};
 
 /** Derive the per-request policy view for a listener. Cheap enough to build per request. */
-export function requestPolicyView(config: OcxConfig, bindHostname: string): RequestPolicyView {
+export function requestPolicyView(
+  config: OcxConfig,
+  bindHostname: string,
+  linkIngress?: LinkIngressPolicy,
+): RequestPolicyView {
   return {
     hostname: bindHostname,
     ...(config.corsAllowOrigins ? { corsAllowOrigins: config.corsAllowOrigins } : {}),
     ...(config.apiKeys ? { apiKeys: config.apiKeys } : {}),
+    ...(linkIngress ? { linkIngress } : {}),
   };
 }
 
@@ -398,13 +413,15 @@ export function resolveDataPlaneAdmissionSecret(
   token: string,
   config: Pick<OcxConfig, "apiKeys">,
   source: DataPlaneAdmissionSource = "dedicated",
+  options: DataPlaneAdmissionOptions = {},
 ): DataPlaneAdmission | null {
   const actual = token.trim();
   if (!actual) return null;
-  if (secretEquals(actual, configuredApiAuthToken(config))) {
+  if (!options.linkIngress && secretEquals(actual, configuredApiAuthToken(config))) {
     return { kind: "environment", source, contextPrincipalId: mintContextPrincipal("environment", "", actual) };
   }
   for (const k of config.apiKeys ?? []) {
+    if (options.linkIngress && !options.linkIngress.has(k.id)) continue;
     if (secretEquals(actual, k.key)) {
       return { kind: "configured", keyId: k.id, source, contextPrincipalId: mintContextPrincipal("configured", k.id, actual) };
     }
@@ -555,12 +572,12 @@ export function resolveApiAuth(req: Request, config: RequestPolicyView): DataPla
   // A loopback bind never reads a token at all, so there is no key to name.
   if (!isApiAuthRequired(config)) return { kind: "loopback", source: "loopback" };
   const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
-  if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated");
+  if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated", { linkIngress: config.linkIngress?.allowedKeyIds });
   const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
-  if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer");
+  if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer", { linkIngress: config.linkIngress?.allowedKeyIds });
   // Anthropic-SDK clients (Claude Code with ANTHROPIC_API_KEY) authenticate via x-api-key.
   const apiKey = req.headers.get("x-api-key")?.trim();
-  if (apiKey) return resolveDataPlaneAdmissionSecret(apiKey, config, "x-api-key");
+  if (apiKey) return resolveDataPlaneAdmissionSecret(apiKey, config, "x-api-key", { linkIngress: config.linkIngress?.allowedKeyIds });
   return null;
 }
 
@@ -582,14 +599,14 @@ export function resolveResponsesApiAuth(req: Request, config: RequestPolicyView)
   if (!isApiAuthRequired(config)) return { kind: "loopback", source: "loopback" };
   // The dedicated header still WINS, because it is unambiguous.
   const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
-  if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated");
+  if (dedicated) return resolveDataPlaneAdmissionSecret(dedicated, config, "dedicated", { linkIngress: config.linkIngress?.allowedKeyIds });
   // #1686: a bearer may also be one of OUR admission secrets. Rejecting it outright meant a
   // Codex client configured with `env_key` could not reach Direct at all. Admitting it is only
   // safe because the upstream credential is then SUBSTITUTED rather than forwarded -- see
   // materializeCodexUpstreamAuth. A bearer that is NOT our secret stays unadmitted here and
   // remains Codex Direct passthrough, so the two bearer domains still never mix.
   const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
-  if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer");
+  if (bearer) return resolveDataPlaneAdmissionSecret(bearer, config, "bearer", { linkIngress: config.linkIngress?.allowedKeyIds });
   // `x-api-key` is deliberately NOT accepted on this transport.
   return null;
 }

package/src/server/chat-completions.ts

@@ -9,8 +9,8 @@ import { FORWARD_HEADERS } from "../adapters/openai-responses";
 import {
   assertChatCompletionsRoutingBody,
   ChatCompletionsRequestError,
-  chatCompletionsToResponsesBody,
 } from "../chat/inbound";
+import { chatToResponsesBody } from "../protocols/codecs/chat";
 import { normalizeChatImageParts } from "../chat/image-parts";
 import {
   chatCompletionsErrorResponse,
@@ -47,8 +47,10 @@ import {
   httpStatusForRequestLogTerminal,
   recordFirstOutput,
   type RequestLogContext,
-  type RequestLogEntry,
 } from "./request-log";
+import { createFinalRequestLog } from "./inference/final-log";
+import { clientWireLogOf, clientWireOf } from "./inference/client-wire";
+import { directEncodersApply } from "./inference/client-encoder-delivery";
 import { responseWithDeferredRequestLog } from "./relay";
 import { handleResponses } from "./responses";
 import { providerConsumesCallerAuthorization } from "../providers/caller-authorization";
@@ -69,7 +71,15 @@ import {
   isTranslatorBudgetExceededError,
   type TranslatorBudget,
 } from "../lib/translator-budget";
-import { handleNativeChatCompletions, isNativeChatRouteEligible } from "./chat-native";
+import { createNativeChatComboSource, handleNativeChatCompletions, nativeChatDeclineReason } from "./chat-native";
+import { upstreamWireForAdapter, type ProtocolReasonCode } from "../protocols/contract";
+import { createProtocolEnvelope } from "../protocols/envelope";
+import { featuresFromChatBody } from "../protocols/features";
+import { checkRepresentable, unrepresentableMessage } from "../protocols/guard";
+import { requestPathForLane } from "../protocols/path";
+import { resolveProtocolSettings } from "../protocols/settings";
+import { markProtocolBlocked, markProtocolEntry } from "../protocols/trace";
+import { recordProtocolShadowPlan } from "../protocols/shadow-plan";
 import { jsonCompletionSse } from "./chat-native-sse";
 import { parseRequestEffortRowId } from "./effort-row";
 import { parseSyntheticRowId } from "./fast-row";
@@ -163,6 +173,8 @@ async function handleChatCompletionsWithBudget(
   let routeMayChangeCredentialDomain = false;
   let settledRoute: ReturnType<typeof routeModel> | null = null;
   let chatNativeRoute: ReturnType<typeof routeModel> | null = null;
+  // Why the native Chat lane was not taken; stays `unknown-model` when routing threw.
+  let nativeDecline: ProtocolReasonCode | undefined = "unknown-model";
   try {
     const route = routeModel(config, chatBody.model as string, evidenceFromBody(chatBody));
     // The native Chat lane sends without re-entering the Responses path, so it
@@ -199,7 +211,10 @@ async function handleChatCompletionsWithBudget(
     }
     // Combos must enter the Responses routing path so child selection, forced default
     // effort, failover, and per-attempt telemetry run before any native Chat send.
-    if (!route.combo && !effortRow && isNativeChatRouteEligible(route, chatBody, config)) {
+    nativeDecline = route.combo ? "combo-or-policy-route"
+      : effortRow ? "effort-row"
+      : nativeChatDeclineReason(route, chatBody, config);
+    if (nativeDecline === undefined) {
       chatNativeRoute = route;
       // Reserve an input estimate for spend without recording it as usage: native Chat attempts
       // keep the provider-reported counts, as they did before the reservation existed.
@@ -232,6 +247,39 @@ async function handleChatCompletionsWithBudget(
     /* unknown model: let handleResponses shape the 404 */
   }
 
+  // Off by default: under the legacy policy with `nativeChatCombos` off nothing below is built
+  // and the request is unchanged. An effort row keeps its effort on the Responses body only, so
+  // its combo stays on the bridge.
+  const protocolSettings = resolveProtocolSettings(config);
+  const nativeChatCombos = protocolSettings.rollout.nativeChatCombos
+    && settledRoute?.combo !== undefined && !effortRow;
+  const envelope = protocolSettings.unrepresentable === "reject" || nativeChatCombos
+    ? createProtocolEnvelope({ inbound: "chat", body: chatBody, translatorBudget })
+    : undefined;
+  // Combo and policy children are judged per candidate (PF-07); an unknown model has no route.
+  if (envelope && settledRoute && !settledRoute.combo && settledRoute.routeKind !== "policy") {
+    const verdict = checkRepresentable({
+      inbound: "chat",
+      requestPath: chatNativeRoute
+        ? requestPathForLane("chat", "native", "chat")
+        : requestPathForLane("chat", "bridge", upstreamWireForAdapter(settledRoute.provider.adapter)),
+      features: envelope.features(),
+      policy: "reject",
+    });
+    if (!verdict.ok) {
+      markProtocolBlocked(logCtx, { inbound: "chat", reasonCodes: verdict.reasonCodes, features: verdict.features });
+      logCtx.errorCode = "unsupported_feature";
+      if (logIds) addFinalRequestLog(logIds.requestId, logIds.start, logCtx, 400, { closeReason: "non_stream" });
+      return chatCompletionsErrorResponse(400, unrepresentableMessage(verdict.features), "invalid_request_error", "unsupported_feature");
+    }
+  }
+  markProtocolEntry(logCtx, {
+    inbound: "chat",
+    lane: chatNativeRoute ? "native" : "bridge",
+    reasonCodes: !chatNativeRoute && nativeDecline ? [nativeDecline] : [],
+    features: envelope ? () => envelope.features() : () => featuresFromChatBody(chatBody),
+  });
+  recordProtocolShadowPlan(logCtx, config, { inbound: "chat", model: requestedModel });
   if (chatNativeRoute) {
     return handleNativeChatCompletions({
       req,
@@ -250,7 +298,7 @@ async function handleChatCompletionsWithBudget(
   try {
     // Validate the full Chat boundary after routing. Native Chat keeps `chatBody` as
     // its wire source; this Responses projection is used only by the fallback path.
-    internalBody = chatCompletionsToResponsesBody(chatBody);
+    internalBody = chatToResponsesBody(chatBody);
     if (effortRow) {
       internalBody.reasoning = {
         ...(isRec(internalBody.reasoning) ? internalBody.reasoning : {}),
@@ -373,12 +421,7 @@ async function handleChatCompletionsWithBudget(
   });
   linkRequestSessionLane(req, internalReq);
 
-  let nativeLogged = false;
-  const finalizeNativeLog = (status: number, meta: { terminalStatus?: RequestLogEntry["terminalStatus"]; closeReason: "terminal" | "client_cancel" | "non_stream" }) => {
-    if (!logIds || nativeLogged) return;
-    nativeLogged = true;
-    addFinalRequestLog(logIds.requestId, logIds.start, logCtx, status, meta);
-  };
+  const finalizeNativeLog = createFinalRequestLog(logIds, logCtx).finish;
   const upstream = await handleResponses(internalReq, config, logCtx, {
     openAiSidecarAuth,
     allowStoredOpenAiSidecarAuth: !!(callerAuthorizationRoute && settledRoute
@@ -392,6 +435,12 @@ async function handleChatCompletionsWithBudget(
     abortSignal: req.signal,
     // Body is Responses-shaped by now, but the client spoke Chat Completions.
     inboundWire: "chat",
+    // PF-07: the combo sends eligible candidates natively from this envelope.
+    ...(envelope && nativeChatCombos ? {
+      protocolSource: createNativeChatComboSource({
+        req, config, envelope, requestedModel, requestedStream: stream, translatorBudget,
+      }),
+    } : {}),
     // Terminal vision-describe marker (roadmap 180): the bridge rebuilds
     // headers from the FORWARD_HEADERS allowlist, which would drop the raw
     // header — so the fact is detected here and carried as an option flag.
@@ -400,7 +449,18 @@ async function handleChatCompletionsWithBudget(
     ...(logIds ? { onFirstOutput: () => recordFirstOutput(logCtx, logIds.start) } : {}),
     onNativePassthroughTerminal: status => finalizeNativeLog(httpStatusForRequestLogTerminal(status, logCtx), { terminalStatus: status, closeReason: "terminal" }),
     onNativePassthroughCancel: () => finalizeNativeLog(499, { closeReason: "client_cancel" }),
+    ...(directEncodersApply(config, settledRoute)
+      ? { clientEncoder: { protocol: "chat" as const, stream, model: requestedModel } }
+      : {}),
   });
+  // Already in the Chat wire: no conversion. A direct-encoder body (PF-09) reports its own log
+  // facts to the deferred request log. A native combo child (PF-07) carries none: its row is
+  // written by the terminal callbacks above, and the deferred log's Responses-shaped inspector
+  // would misread a Chat stream, so of those only a refusal is wrapped.
+  if (clientWireOf(upstream) === "chat") {
+    if (!logIds || (upstream.ok && !clientWireLogOf(upstream))) return upstream;
+    return responseWithDeferredRequestLog(upstream, logIds.requestId, logIds.start, logCtx);
+  }
 
   // Rewrite non-2xx before deferred logging so /api/logs records the client-facing status
   // (e.g. cyber_policy remapped from a passthrough 5xx to HTTP 400).

package/src/server/chat-native-eligibility.ts

@@ -0,0 +1,74 @@
+import { chatBodyCarriesImage, chatBodyCarriesToolResultImage } from "../chat/image-parts";
+import type { ProtocolReasonCode } from "../protocols/contract";
+import type { RouteResult } from "../router";
+import type { OcxConfig } from "../types";
+import { isModelTextOnly, requiresVisionPreprocessing } from "../vision";
+
+type Rec = Record<string, unknown>;
+
+function isRec(value: unknown): value is Rec {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Why the native Chat lane declines a route, as a protocol reason code. */
+export type NativeChatDeclineReason = Extract<
+  ProtocolReasonCode,
+  | "cross-wire-ir"
+  | "auth-mode-not-native"
+  | "combo-or-policy-route"
+  | "responses-only-feature"
+  | "tool-result-image"
+  | "vision-preprocessing"
+  | "hosted-tool"
+>;
+
+/**
+ * The first rule that keeps a Chat request off the native Chat lane, or `undefined` when the
+ * route is eligible. The order is the order the checks always ran in, so the reason reported is
+ * the one that actually decided.
+ */
+export function nativeChatDeclineReason(
+  route: RouteResult,
+  rawBody: Rec,
+  config?: OcxConfig,
+): NativeChatDeclineReason | undefined {
+  const provider = route.provider;
+  if (provider.adapter !== "openai-chat") return "cross-wire-ir";
+  if (provider.authMode !== undefined && provider.authMode !== "key" && provider.authMode !== "local") return "auth-mode-not-native";
+  // Combo and policy execution own multi-candidate retries in the Responses pipeline.
+  if (route.combo || route.routeKind === "combo" || route.routeKind === "policy") return "combo-or-policy-route";
+  if (rawBody.store === true || rawBody.background === true) return "responses-only-feature";
+  if (typeof rawBody.previous_response_id === "string" && rawBody.previous_response_id.length > 0) return "responses-only-feature";
+  if (rawBody.compaction_trigger !== undefined) return "responses-only-feature";
+  // A standard Chat tool message accepts a string or text parts, not image_url, so
+  // normalizing a Pi/Anthropic tool image into image_url is not enough on its own —
+  // the part is still inside a tool message. The translated adapter already places
+  // tool-result images in a following user carrier after the complete paired batch
+  // (flushToolResultImages), so divert these requests there. Ordinary user images and
+  // text-only tool results keep the native fast path.
+  if (chatBodyCarriesToolResultImage(rawBody)) return "tool-result-image";
+  // Vision sidecar coverage (roadmap 180): a text-only routed model with an
+  // image-bearing body must go through the Responses pipeline, whose plan
+  // site describes or strips the image. The native fast path has no vision
+  // handling, so letting it keep such a request forwards raw pixels to a
+  // model the operator declared blind.
+  if (chatBodyCarriesImage(rawBody)) {
+    const needsVision = config
+      ? requiresVisionPreprocessing(config, provider, route.modelId, route.providerName)
+      : isModelTextOnly(provider, route.modelId);
+    if (needsVision) return "vision-preprocessing";
+  }
+  if (Array.isArray(rawBody.tools)) {
+    for (const tool of rawBody.tools) {
+      if (!isRec(tool)) continue;
+      if (tool.type === "web_search" || tool.type === "web_search_preview" || tool.type === "image_generation") {
+        return "hosted-tool";
+      }
+    }
+  }
+  return undefined;
+}
+
+export function isNativeChatRouteEligible(route: RouteResult, rawBody: Rec, config?: OcxConfig): boolean {
+  return nativeChatDeclineReason(route, rawBody, config) === undefined;
+}