@bitkyc08/opencodex 2.52.0-preview.20260911 → 2.52.0

package/src/router.ts

@@ -349,6 +349,7 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
   const noTemperatureModels = mergeStringArray(registryEntry.noTemperatureModels, provider.noTemperatureModels);
   const noTopPModels = mergeStringArray(registryEntry.noTopPModels, provider.noTopPModels);
   const noPenaltyModels = mergeStringArray(registryEntry.noPenaltyModels, provider.noPenaltyModels);
+  const noJsonSchemaModels = mergeStringArray(registryEntry.noJsonSchemaModels, provider.noJsonSchemaModels);
   const autoToolChoiceOnlyModels = mergeStringArray(registryEntry.autoToolChoiceOnlyModels, provider.autoToolChoiceOnlyModels);
   const preserveReasoningContentModels = mergeStringArray(registryEntry.preserveReasoningContentModels, provider.preserveReasoningContentModels);
   const requiresReasoningPlaceholderModels = mergeStringArray(registryEntry.requiresReasoningPlaceholderModels, provider.requiresReasoningPlaceholderModels);
@@ -376,6 +377,9 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(provider.responsesPath === undefined && registryEntry.responsesPath !== undefined
       ? { responsesPath: registryEntry.responsesPath }
       : {}),
+    ...(provider.chatCompletionsPath === undefined && registryEntry.chatCompletionsPath !== undefined
+      ? { chatCompletionsPath: registryEntry.chatCompletionsPath }
+      : {}),
     ...(provider.requiresAdjacentResponsesToolResults === undefined
       && registryEntry.requiresAdjacentResponsesToolResults !== undefined
       ? { requiresAdjacentResponsesToolResults: registryEntry.requiresAdjacentResponsesToolResults }
@@ -473,6 +477,7 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(noTemperatureModels ? { noTemperatureModels } : {}),
     ...(noTopPModels ? { noTopPModels } : {}),
     ...(noPenaltyModels ? { noPenaltyModels } : {}),
+    ...(noJsonSchemaModels ? { noJsonSchemaModels } : {}),
     ...(autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels } : {}),
     ...(preserveReasoningContentModels ? { preserveReasoningContentModels } : {}),
     ...(requiresReasoningPlaceholderModels ? { requiresReasoningPlaceholderModels } : {}),
@@ -681,7 +686,7 @@ function routeModelInternal(
     }
   }
 
-  // 0. Explicit "<provider>/<model>" namespace (e.g. "opencode-go/deepseek-v4-pro").
+  // 0. Explicit "<provider>/<model>" namespace (e.g. "opencode-go/deepseek-v4.1-flash").
   //    Only triggers when the prefix matches a CONFIGURED provider, so genuine
   //    slash-containing model ids (e.g. "anthropic/claude-...") fall through when
   //    no such provider exists.

package/src/routing/compatibility/behavior.ts

@@ -14,6 +14,8 @@ export function upstreamProtocolForAdapter(adapter: string): string {
     case "openai-chat":
     case "command-code":
     case "cursor":
+    case "devin-cli":
+    case "devin":
     case "azure":
     case "azure-openai":
     case "kiro":
@@ -147,6 +149,7 @@ export function resolveProductionBehaviorValues(
     "wire.adapter": behaviorRow("provider_config", adapter),
     "wire.upstreamProtocol": behaviorRow("provider_config", upstreamProtocol),
     "wire.responsesPath": behaviorRow("provider_config", effective.responsesPath ?? null),
+    "wire.chatCompletionsPath": behaviorRow("provider_config", effective.chatCompletionsPath ?? null),
     "wire.commandCodeVersion": behaviorRow("provider_config", effective.commandCodeVersion ?? null),
     "wire.modelSuffixMode": behaviorRow(
       "provider_config",

package/src/server/adapter-resolve.ts

@@ -48,6 +48,10 @@ export function resolveWireProtocolOverride(
 }
 
 /** Build the provider adapter for a resolved provider config. */
-export function resolveAdapter(providerConfig: OcxProviderConfig, cacheRetention?: "none" | "short" | "long") {
-  return createRegisteredAdapter(providerConfig, { cacheRetention });
+export function resolveAdapter(
+  providerConfig: OcxProviderConfig,
+  cacheRetention?: "none" | "short" | "long",
+  providerId?: string,
+) {
+  return createRegisteredAdapter(providerConfig, { cacheRetention, ...(providerId ? { providerId } : {}) });
 }

package/src/server/auth-cors.ts

@@ -1,4 +1,4 @@
-import { timingSafeEqual } from "node:crypto";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { initialModelSelection } from "../providers/initial-model-selection";
 import { extractAccountId } from "../oauth/chatgpt";
 import { formatErrorResponse } from "../bridge";
@@ -353,9 +353,29 @@ function secretEquals(actual: string, expected: string | undefined): boolean {
  */
 export type DataPlaneAdmissionSource = "loopback" | "dedicated" | "bearer" | "x-api-key";
 
+/**
+ * Process-local, salted identity of the admission secret that was actually matched.
+ *
+ * Context-relay ownership is partitioned by this value, so two operators holding different
+ * keys cannot reach each other's sessions even when both resolve to the same upstream
+ * workspace. `source` is deliberately excluded: the same key arriving as a bearer or in the
+ * dedicated header is one principal. Rotating or replacing a secret mints a new principal and
+ * drops continuity, which is the safe direction — a reused key id or a replaced environment
+ * secret must not inherit the previous holder's sessions. Loopback admission carries no caller
+ * identity and mints nothing, so the relay refuses it rather than treating every local process
+ * as one user.
+ */
+const CONTEXT_PRINCIPAL_SALT = randomBytes(32);
+
+function mintContextPrincipal(kind: string, keyId: string, credential: string): string {
+  return createHmac("sha256", CONTEXT_PRINCIPAL_SALT)
+    .update(kind).update("\0").update(keyId).update("\0").update(credential)
+    .digest("hex");
+}
+
 export type DataPlaneAdmission =
-  | { kind: "configured"; keyId: string; source: DataPlaneAdmissionSource }
-  | { kind: "environment"; source: DataPlaneAdmissionSource }
+  | { kind: "configured"; keyId: string; source: DataPlaneAdmissionSource; contextPrincipalId?: string }
+  | { kind: "environment"; source: DataPlaneAdmissionSource; contextPrincipalId?: string }
   | { kind: "loopback"; source: "loopback" };
 
 /**
@@ -374,17 +394,52 @@ export function resolveDataPlaneAdmissionSecret(
 ): DataPlaneAdmission | null {
   const actual = token.trim();
   if (!actual) return null;
-  if (secretEquals(actual, configuredApiAuthToken(config))) return { kind: "environment", source };
+  if (secretEquals(actual, configuredApiAuthToken(config))) {
+    return { kind: "environment", source, contextPrincipalId: mintContextPrincipal("environment", "", actual) };
+  }
   for (const k of config.apiKeys ?? []) {
-    if (secretEquals(actual, k.key)) return { kind: "configured", keyId: k.id, source };
+    if (secretEquals(actual, k.key)) {
+      return { kind: "configured", keyId: k.id, source, contextPrincipalId: mintContextPrincipal("configured", k.id, actual) };
+    }
     const pending = k.pendingRotation;
     if (pending && Date.parse(pending.expiresAt) > Date.now() && secretEquals(actual, pending.key)) {
-      return { kind: "configured", keyId: k.id, source };
+      return { kind: "configured", keyId: k.id, source, contextPrincipalId: mintContextPrincipal("configured", k.id, pending.key) };
     }
   }
   return null;
 }
 
+/** The principal an authenticated admission belongs to, or undefined for loopback. */
+export function contextPrincipalIdOf(admission: DataPlaneAdmission | undefined): string | undefined {
+  return admission && "contextPrincipalId" in admission ? admission.contextPrincipalId : undefined;
+}
+
+/**
+ * The caller principal for a context-relay request, which is a stricter question than admission.
+ *
+ * The default bind is loopback, where admission deliberately never reads a token, so an admitted
+ * request carries no caller identity. History ownership needs one, so the relay asks separately:
+ * a caller that presents a real opencodex API key gets that key’s principal even on loopback,
+ * and a caller that presents none gets nothing and is refused. This adds identity where the caller
+ * volunteered it; it does not admit anyone who was not already admitted, and it does not change
+ * which credential goes upstream.
+ */
+export function resolveContextPrincipal(req: Request, config: OcxConfig, admission: DataPlaneAdmission | undefined): string | undefined {
+  const named = contextPrincipalIdOf(admission);
+  if (named) return named;
+  if (admission?.kind !== "loopback") return undefined;
+  const dedicated = req.headers.get("x-opencodex-api-key")?.trim();
+  const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  const apiKey = req.headers.get("x-api-key")?.trim();
+  for (const [token, source] of [[dedicated, "dedicated"], [bearer, "bearer"], [apiKey, "x-api-key"]] as const) {
+    if (!token) continue;
+    const resolved = resolveDataPlaneAdmissionSecret(token, config, source);
+    const principal = contextPrincipalIdOf(resolved ?? undefined);
+    if (principal) return principal;
+  }
+  return undefined;
+}
+
 /** Whether `token` is a data-plane admission secret. */
 export function isDataPlaneAdmissionSecret(token: string, config: OcxConfig): boolean {
   return resolveDataPlaneAdmissionSecret(token, config) !== null;
@@ -712,6 +767,11 @@ export function providerManagementConfigError(name: unknown, provider: unknown):
     "noStructuredOutputModels",
   );
   if (structuredOutputOptOutError) return `provider ${name} ${structuredOutputOptOutError}`;
+  const jsonSchemaOptOutError = nonBlankStringArrayConfigError(
+    raw.noJsonSchemaModels,
+    "noJsonSchemaModels",
+  );
+  if (jsonSchemaOptOutError) return `provider ${name} ${jsonSchemaOptOutError}`;
   const retainModelsError = nonBlankStringArrayConfigError(raw.retainModels, "retainModels");
   if (retainModelsError) return `provider ${name} ${retainModelsError}`;
   const toolReasoningOptOutError = nonBlankStringArrayConfigError(
@@ -794,6 +854,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   fastWire: "editor",
   baseUrl: "editor",
   responsesPath: "editor",
+  chatCompletionsPath: "editor",
   commandCodeVersion: "editor",
   statelessResponses: "editor",
   requiresAdjacentResponsesToolResults: "editor",
@@ -812,6 +873,8 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   apiKey: "redacted",
   apiKeyTransport: "editor",
   apiKeyPool: "redacted",
+  // Ordering preference only; it names no key material, so an editor may read and set it.
+  apiKeyPoolStrategy: "editor",
   apiKeySelectionRevision: "runtime",
   _apiKeyAttempt: "runtime",
   defaultModel: "editor",
@@ -855,6 +918,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   supportsOpenAiWebSearchToolFields: "editor",
   xaiResponsesXSearch: "editor",
   xaiResponsesDefaultVersion: "runtime",
+  zaiResponsesDefaultVersion: "runtime",
   supportsResponsesCustomTools: "editor",
   responsesSnapshotRepair: "editor",
   webSearchBridge: "editor",
@@ -866,6 +930,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   noTopPModels: "editor",
   noPenaltyModels: "editor",
   noStructuredOutputModels: "editor",
+  noJsonSchemaModels: "editor",
   omitReasoningEffortWithToolsModels: "editor",
   parallelToolCalls: "editor",
   pinParallelToolCallsFalse: "editor",

package/src/server/chat-completions.ts

@@ -260,9 +260,9 @@ async function handleChatCompletionsWithBudget(
     const value = req.headers.get(name);
     if (value) headers.set(name, value);
   }
-  // A noncanonical caller-auth route can use stored main auth only through a sidecar snapshot.
-  // Later shadow/thread rewrites strip primary credentials at the actual Responses boundary.
-  if (!callerAuthorizationRoute || (settledRoute && !isCanonicalOpenAiForwardProvider(settledRoute.provider))) {
+  // Existing primary enrichment stays on non-caller-auth routes. Caller-auth routes defer
+  // optional stored sidecar auth until the final helper plan actually needs it.
+  if (!callerAuthorizationRoute) {
     // This enrichment is optional for routed/non-main providers. If native main
     // is fenced, omit it and let auth-context reject only a final physical-main
     // selection while healthy pool/provider routes continue.
@@ -317,6 +317,8 @@ async function handleChatCompletionsWithBudget(
   };
   const upstream = await handleResponses(internalReq, config, logCtx, {
     openAiSidecarAuth,
+    allowStoredOpenAiSidecarAuth: !!(callerAuthorizationRoute && settledRoute
+      && !isCanonicalOpenAiForwardProvider(settledRoute.provider)),
     nativeCallerAuth,
     callerDirectAuth,
     ...(logIds?.turnAdmissionLease ? { turnAdmissionLease: logIds.turnAdmissionLease } : {}),

package/src/server/chat-native.ts

@@ -33,6 +33,7 @@ import {
 } from "../lib/translator-budget";
 import {
   hasKeyPoolFailover,
+  selectProactiveApiKeyTransport,
   rateLimitRetryDelayMs,
   rateLimitRetryPolicyFor,
   rotateProviderTransportOn429,
@@ -235,6 +236,14 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
     unregisterTurn(upstream);
   };
   const connectMs = config.connectTimeoutMs ?? 200_000;
+  // Native chat is its own entry path -- chat-completions.ts routes here directly and never
+  // through the Responses core -- so the pre-dispatch key preference is applied again here
+  // rather than inherited. Assigned before the adapter binds below, for the same reason it is
+  // assigned before the transport pin in core.ts.
+  // Transport variant: the bare picker answers with the persisted row, which for a built-in
+  // provider carries no adapter id or base URL until routedProviderConfig backfills it.
+  const proactiveKeyProvider = selectProactiveApiKeyTransport(config, route.providerName, route.provider);
+  if (proactiveKeyProvider) route.provider = proactiveKeyProvider;
   let activeProvider: OcxProviderConfig = route.provider;
   let activeAdapter: ProviderAdapter = createOpenAIChatAdapter(activeProvider);
   let activeRequest: AdapterRequest;

package/src/server/claude-messages.ts

@@ -30,7 +30,6 @@ import {
 import { clearableDeadline, idleDeadline } from "../lib/abort";
 import { estimateTokens } from "../lib/token-estimate";
 import { NoEligiblePolicyCandidateError, UnknownRoutingPolicyError, routeModel } from "../router";
-import { registryEntryForProviderDestination } from "../providers/registry";
 import { evidenceFromBody } from "../routing/request-evidence";
 import { resolveWireProtocolOverride } from "./adapter-resolve";
 import type { OcxConfig } from "../types";
@@ -38,6 +37,7 @@ import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-dec
 import { addFinalRequestLog, httpStatusForRequestLogTerminal, recordFirstOutput, type RequestLogContext, type RequestLogEntry } from "./request-log";
 import {
   conversationIdFromClaudeMetadata,
+  getOrAllocateRequestSessionLane,
   linkRequestSessionLane,
   normalizeLogConversationId,
   sessionLaneIdFromRequest,
@@ -637,6 +637,12 @@ export async function handleClaudeMessages(
   }
 }
 
+/**
+ * Translate a Claude Messages request, route it through the Responses pipeline,
+ * and translate the reply back. Runs under a translator budget owned by the
+ * caller; Go session affinity is derived here and handed to the final Go
+ * transport out of band rather than through replay headers.
+ */
 async function handleClaudeMessagesWithBudget(
   req: Request,
   config: OcxConfig,
@@ -791,19 +797,13 @@ async function handleClaudeMessagesWithBudget(
   // Native ChatGPT passthrough (openai-responses forward) accepts only Codex-shaped
   // bodies: it 400s on sampling params ("Unsupported parameter: max_output_tokens",
   // verified live 2026-07-11). Strip them for that route; routed providers keep them.
-  let nativeRoute = false;
-  let opencodeGoRoute = false;
   try {
     const route = routeModel(config, internalBody.model as string, evidenceFromBody(internalBody));
-    // Match the fixed key-auth destination before per-model wire overrides, including
-    // renamed Go providers without treating custom or lookalike URLs as Go.
-    opencodeGoRoute = registryEntryForProviderDestination(route.provider)?.id === "opencode-go";
     // Settle the wire once so the sampling decision below reads the effective
     // adapter rather than the provider-wide default (#404).
     route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, "anthropic");
     logCtx.routeDecision = route.routeDecision;
     if (route.provider.adapter === "openai-responses") {
-      nativeRoute = true;
       delete internalBody.max_output_tokens;
       delete internalBody.temperature;
       delete internalBody.top_p;
@@ -867,30 +867,23 @@ async function handleClaudeMessagesWithBudget(
       };
     }
   }
-  if (opencodeGoRoute) {
-    const session = req.headers.get("x-opencode-session");
-    if (session) headers.set("x-opencode-session", session);
-  }
-  const hasExplicitGoSession = opencodeGoRoute
-    && (sessionLaneIdFromRequest(headers) !== undefined
-      || normalizeLogConversationId(headers.get("x-opencode-session")) !== undefined);
-  const synthesizeGoSession = opencodeGoRoute && !hasExplicitGoSession
+  // Carry Go identity out of band: a combo's preflight target may differ from its
+  // actual dispatch/fallback target. Never add Go-only identity to replay headers.
+  const claudeNativeSessionId = cacheKeySource === "metadata"
+    && typeof internalBody.prompt_cache_key === "string"
     && isRec(anthropicBody)
-    && conversationIdFromClaudeMetadata(isRec(anthropicBody.metadata) ? anthropicBody.metadata : undefined) !== undefined;
-  // Go can also use the Responses adapter; its eligibility gate must win on both wires.
-  if (opencodeGoRoute ? synthesizeGoSession : nativeRoute) {
-    // ChatGPT-backend prompt-cache affinity rides the session_id HEADER (codex
-    // clients always send their session uuid; devlog 090 follow-up: body-level
-    // prompt_cache_key alone still yielded cached_tokens:0). Claude Code never sends
-    // the header, so synthesize a stable per-session uuid from the same cache key.
-    // Routed Go requests need this lane too for their x-opencode-session affinity —
-    // but ONLY for a real per-session key (metadata.user_id). The system-hash fallback
-    // key is shared across Desktop conversations, and a shared session_id's backend
-    // semantics are unproven (audit 133 R2#3): body prompt_cache_key only there.
-    if (cacheKeySource === "metadata" && (synthesizeGoSession || !headers.has("session_id")) && typeof internalBody.prompt_cache_key === "string") {
-      headers.set("session_id", uuidFromHex(internalBody.prompt_cache_key));
-    }
-  }
+    && conversationIdFromClaudeMetadata(isRec(anthropicBody.metadata) ? anthropicBody.metadata : undefined) !== undefined
+    ? uuidFromHex(internalBody.prompt_cache_key)
+    : undefined;
+  const metadataGoLane = normalizeLogConversationId(claudeNativeSessionId);
+  // Without any valid conversation identity, fall back to the request-scoped lane
+  // allocated on the admitted client request (#4172): stable across retries and
+  // route reconstruction, distinct per request, and never derived from a shared
+  // system-prompt cache key or from a later synthesized native session_id header.
+  const claudeGoSessionLane = sessionLaneIdFromRequest(headers)
+    ?? normalizeLogConversationId(req.headers.get("x-opencode-session"))
+    ?? metadataGoLane
+    ?? getOrAllocateRequestSessionLane(req);
   let internalReq: Request;
   try {
     // The UTF-16 JSON string and the Request's UTF-8 body coexist until dispatch.
@@ -934,6 +927,8 @@ async function handleClaudeMessagesWithBudget(
     // Without this the replay would look native and a Responses-scoped wire default
     // would fire, disagreeing with the pre-flight decision above.
     inboundWire: "anthropic",
+    claudeGoAffinity: { sessionLane: claudeGoSessionLane },
+    claudeNativeSessionId,
     stripClaudeMainAuthForNoncanonicalForward: true,
     ...(trustedClaudeMainAuth ? { trustedClaudeMainAuth } : {}),
     // Claude's internal stored-main enrichment is not an original caller credential.

package/src/server/context-history.ts

@@ -0,0 +1,207 @@
+/** Native history/notes JSON relay. No interpretation of encrypted tool arguments or retries. */
+import { formatErrorResponse } from "../bridge";
+import {
+  CodexAccountCooldownError, CodexAuthContextError, CodexMainProfileDrainingError, CodexDirectAuthenticationError,
+  CodexPoolAuthenticationError, CodexThreadAffinityExpiredError, CodexMainSubstitutionUnavailableError,
+  codexMainProfileDrainingResponse, cooldownErrorResponse,
+  materializeCodexUpstreamAuth, isCodexAuthContextUsable, resolveCodexAuthContext, releaseCodexAuthContextProbeLease,
+} from "../codex/auth-context";
+import { getContextSessionOwner, contextSessionOwnerMatches } from "../codex/context-owner";
+import { contextEndpoint, contextRelayActivated } from "../codex/context-compat";
+import { formatCodexProviderForLog } from "../codex/routing";
+import { listOpenAiForwardSidecarCandidates } from "../providers/openai-sidecar";
+import { clearableDeadline, type ClearableDeadline } from "../lib/abort";
+import { readBoundedResponseBytes } from "../lib/bounded-body";
+import type { AdmissionLease } from "../lib/admission";
+import type { OcxConfig } from "../types";
+import { resolveContextPrincipal, ForwardAdmissionCredentialError, validateForwardAdmissionCredential, type DataPlaneAdmission } from "./auth-cors";
+import { readBoundedJsonRequestBody } from "./request-decompress";
+import { codexLogAccountId, decodeRequestErrorResponse } from "./responses";
+import { codexAccountSelectionForTurn } from "./lifecycle";
+import type { RequestLogContext } from "./request-log";
+
+const PROTOCOL_HEADERS = ["x-openai-encrypted-tool-arguments", "x-openai-tool-output-truncation-policy"];
+const RESPONSE_HEADERS = ["content-type", "retry-after", "x-request-id", "openai-processing-ms", ...PROTOCOL_HEADERS];
+const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+const MAX_REQUEST_BYTES = 16 * 1024 * 1024;
+const RELAY_DEADLINE_MS = 35_000;
+
+export function contextSelectionHeaders(headers: Headers, sessionId: string): Headers {
+  const result = new Headers(headers);
+  // Codex history tools carry root session_id in JSON, unlike Responses' HTTP headers.
+  // Root model requests use (session-id=root, thread-id=root); don't fabricate a parent key.
+  if (!result.has("x-codex-parent-thread-id") && !result.has("session-id") && !result.has("thread-id")) {
+    result.set("session-id", sessionId);
+    result.set("thread-id", sessionId);
+  }
+  return result;
+}
+
+/**
+ * One deadline covers the whole operation, starting before the body is read.
+ *
+ * Reading the body and selecting a credential are both waits a caller controls, and this route
+ * holds an admitted turn slot for their duration. A deadline that started at dispatch would let
+ * an unfinished body or a stalled refresh hold that slot with no bound at all.
+ */
+export async function handleContextHistory(
+  req: Request, config: OcxConfig, logCtx: RequestLogContext,
+  endpoint: string, turnAdmissionLease?: AdmissionLease, admission?: DataPlaneAdmission,
+  revalidateAdmission?: () => DataPlaneAdmission | null,
+): Promise<Response> {
+  const deadline = clearableDeadline(RELAY_DEADLINE_MS, req.signal);
+  try {
+    return await relayContextHistory(req, config, logCtx, endpoint, deadline, turnAdmissionLease,
+      admission, revalidateAdmission);
+  } finally {
+    deadline.clear();
+  }
+}
+
+async function relayContextHistory(
+  req: Request, config: OcxConfig, logCtx: RequestLogContext,
+  endpoint: string, deadline: ClearableDeadline,
+  turnAdmissionLease?: AdmissionLease, admission?: DataPlaneAdmission,
+  revalidateAdmission?: () => DataPlaneAdmission | null,
+): Promise<Response> {
+  // The feature is opt-in, and the opt-in has to hold here rather than only where the injected
+  // base URL is rewritten: a caller that can reach the data plane can POST these paths directly.
+  // While it is off the endpoints do not exist, which is also what a disabled route should look
+  // like from outside.
+  if (!contextEndpoint("/v1/" + endpoint) || req.method !== "POST" || !contextRelayActivated()) {
+    return formatErrorResponse(404, "not_found", "Unknown context endpoint");
+  }
+  // Only a trusted listener admission authorizes replacing a proxy bearer with Codex auth.
+  const substituteMainCredential = admission?.source === "bearer";
+  try { if (!substituteMainCredential) validateForwardAdmissionCredential(req.headers, config); }
+  catch (err) {
+    if (err instanceof ForwardAdmissionCredentialError) return formatErrorResponse(401, "authentication_error", err.message);
+    throw err;
+  }
+  // A workspace is not a person and a local socket is not a caller. Ownership is keyed by the
+  // admission secret that was actually matched, so an admission that carries no principal —
+  // loopback — cannot own or reach a session.
+  const principalId = resolveContextPrincipal(req, config, admission);
+  if (!principalId) {
+    return formatErrorResponse(403, "context_principal_required",
+      "Context history requires an opencodex API key on the request; admission alone carries no caller identity");
+  }
+  let body: unknown;
+  try { body = await readBoundedJsonRequestBody(req, MAX_REQUEST_BYTES, undefined, { signal: deadline.signal }); }
+  catch (err) {
+    const cancelled = cancellationResponse(req, deadline);
+    if (cancelled) return cancelled;
+    return decodeRequestErrorResponse(err, "context_history");
+  }
+  const sessionId = (body as {context?: {session_id?: unknown}} | null)?.context?.session_id;
+  if (typeof sessionId !== "string" || !/^[A-Za-z0-9._:-]{1,512}$/.test(sessionId)) {
+    return formatErrorResponse(400, "invalid_request_error", "context.session_id must be a bounded nonempty string");
+  }
+  const candidate = listOpenAiForwardSidecarCandidates(config)[0];
+  if (!candidate) return formatErrorResponse(400, "invalid_request_error", "History and notes require the native ChatGPT forward provider");
+  const rootHeader = req.headers.get("x-codex-parent-thread-id")?.trim() || req.headers.get("session-id")?.trim();
+  if (rootHeader && rootHeader !== sessionId) {
+    return formatErrorResponse(409, "context_account_unavailable", "Context root does not match this request");
+  }
+  const owner = getContextSessionOwner(principalId, sessionId, candidate.provider.baseUrl);
+  if (!owner || owner.ambiguous || (owner.kind === "caller" && substituteMainCredential)) {
+    return formatErrorResponse(409, "context_account_unavailable",
+      "Context account ownership is unavailable; start a new session and preserve needed state before resetting context");
+  }
+  let authContext: Awaited<ReturnType<typeof resolveCodexAuthContext>>;
+  const headers = new Headers(candidate.provider.headers);
+  try {
+    authContext = await resolveCodexAuthContext(contextSelectionHeaders(req.headers, sessionId), config, owner.kind === "stored" ? "pool" : "direct", {
+      // The same deadline bounds credential selection and refresh waits.
+      signal: deadline.signal,
+      // Resolve the proven physical owner as an explicit account. Context operations
+      // never create affinity, rotate on quota, or inspect file-main for a caller owner.
+      modelId: "context_history",
+      ...(owner.kind === "stored" ? { accountId: owner.accountId } : { requestScopedMainCredential: true }),
+      admission,
+      substituteMainCredentialForDirect: substituteMainCredential,
+      beginCodexAccountSelection: codexAccountSelectionForTurn(turnAdmissionLease),
+    });
+    if (authContext.kind !== "main" && authContext.probeLeaseId) {
+      // History traffic must not occupy or settle the model's quota-recovery probe.
+      releaseCodexAuthContextProbeLease(authContext);
+      return formatErrorResponse(503, "upstream_error", "Model quota recovery is pending; retry context operation later");
+    }
+    if (!isCodexAuthContextUsable(authContext, config)) throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+    logCtx.provider = formatCodexProviderForLog(candidate.providerName, codexLogAccountId(authContext), config);
+    // Materialization rechecks the current account policy after async selection.
+    // Synthetic lane IDs are local selection metadata, never upstream headers.
+    for (const [key, value] of materializeCodexUpstreamAuth(req.headers, authContext, {
+      config, modelId: "context_history", admission, substituteMainCredential,
+    })) {
+      headers.set(key, value);
+    }
+    // Check the assembled outbound headers, including configured provider headers.
+    validateForwardAdmissionCredential(headers, config);
+    // Recheck actual wire identity after async selection/materialization. A replaced
+    // account slot or login must not receive another physical account's history.
+    const currentOwner = getContextSessionOwner(principalId, sessionId, candidate.provider.baseUrl);
+    if (!currentOwner || currentOwner.kind !== owner.kind
+      || !contextSessionOwnerMatches(owner, headers) || !contextSessionOwnerMatches(currentOwner, headers)) {
+      return formatErrorResponse(409, "context_account_unavailable", "Context account identity changed; start a new session");
+    }
+  } catch (err) {
+    const cancelled = cancellationResponse(req, deadline);
+    if (cancelled) return cancelled;
+    if (err instanceof CodexAccountCooldownError) return cooldownErrorResponse(err);
+    if (err instanceof CodexMainProfileDrainingError) return codexMainProfileDrainingResponse();
+    if (err instanceof CodexThreadAffinityExpiredError) return formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
+    if (err instanceof CodexAuthContextError || err instanceof CodexPoolAuthenticationError || err instanceof CodexDirectAuthenticationError
+      || err instanceof CodexMainSubstitutionUnavailableError || err instanceof ForwardAdmissionCredentialError) {
+      return formatErrorResponse(401, "authentication_error", "Selected Codex account is unavailable or needs reauthentication");
+    }
+    throw err;
+  }
+  headers.set("content-type", "application/json");
+  for (const key of PROTOCOL_HEADERS) {
+    const value = req.headers.get(key); if (value !== null) headers.set(key, value);
+  }
+  // Nothing is dispatched after cancellation; a notes write is not replayable.
+  const cancelledBeforeDispatch = cancellationResponse(req, deadline);
+  if (cancelledBeforeDispatch) return cancelledBeforeDispatch;
+  // Body reading and credential selection are both waits, and a key can be revoked, rotated or
+  // replaced during them. Re-resolve admission against the receiving listener policy and require
+  // the same principal, so a withdrawn key cannot dispatch on a snapshot taken minutes earlier.
+  if (revalidateAdmission && resolveContextPrincipal(req, config, revalidateAdmission() ?? undefined) !== principalId) {
+    return formatErrorResponse(401, "authentication_error",
+      "opencodex API key changed during this request; retry with current credentials");
+  }
+  // The operator may disable the feature while body or credential IO is pending.
+  if (!contextRelayActivated()) return formatErrorResponse(404, "not_found", "Unknown context endpoint");
+  let response: Response | undefined;
+  try {
+    response = await fetch(`${candidate.provider.baseUrl}/${endpoint}`, {
+      method: "POST", headers, body: JSON.stringify(body), signal: deadline.signal, redirect: "manual",
+    });
+    const result = await readBoundedResponseBytes(response, {maxBytes: MAX_RESPONSE_BYTES, signal: deadline.signal});
+    if (result.oversized) return formatErrorResponse(502, "upstream_error", "Context response exceeded 16 MiB");
+    const outputHeaders = new Headers();
+    for (const key of RESPONSE_HEADERS) {
+      const value = response.headers.get(key); if (value !== null) outputHeaders.set(key, value);
+    }
+    // A context 403 is not evidence that the model credential is invalid. Don't mutate pool
+    // health/quota or retry writes; preserve the real upstream result for the caller.
+    return new Response([204,205,304].includes(response.status) ? null : result.bytes, {status:response.status, headers:outputHeaders});
+  } catch {
+    return cancellationResponse(req, deadline)
+      ?? formatErrorResponse(502, "upstream_error", "Context upstream connection failed");
+  } finally {
+    if (response?.body && !response.body.locked) void response.body.cancel().catch(() => undefined);
+  }
+}
+
+/** Client cancellation and deadline expiry are different outcomes and must not share a status. */
+function cancellationResponse(req: Request, deadline: ClearableDeadline): Response | undefined {
+  if (req.signal.aborted) {
+    return formatErrorResponse(499, "client_closed_request", "Context request canceled by client");
+  }
+  if (deadline.didExpire()) {
+    return formatErrorResponse(504, "upstream_error", "Context operation exceeded its deadline");
+  }
+  return undefined;
+}

package/src/server/images.ts

@@ -28,6 +28,7 @@ import { readBoundedResponseBytes, type BoundedBytesResult } from "../lib/bounde
 import { sidecarEnter } from "../lib/sidecar-tracker";
 import type { OcxConfig } from "../types";
 import { resolveFirstUsableOpenAiSidecar, selectImagesProvider } from "../providers/openai-sidecar";
+import { selectProactiveApiKeyTransport } from "../providers/key-failover";
 import { getProviderRegistryEntry } from "../providers/registry";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-decompress";
 import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "./auth-cors";
@@ -698,7 +699,33 @@ export async function handleImages(
     // Do not hide a broken/expired pool behind separately billed API-key image generation.
     return forwardAuthError;
   } else if (candidates.keyed) {
-    const { provider, apiKey, providerName } = candidates.keyed;
+    const { providerName } = candidates.keyed;
+    // The keyed image path builds its own URL and Authorization header and never enters
+    // handleResponses, so the pre-dispatch key pick happens here.
+    //
+    // Two things about the placement. It stays INSIDE this branch because higher up it would
+    // also run for requests ChatGPT forward goes on to serve, spending a rotation on a path
+    // that never used the key. And the header is rebuilt from the returned route rather than
+    // from candidates.keyed.apiKey, which is a snapshot resolved earlier: reusing it would
+    // send the OLD key while the picker had already persisted the new one.
+    //
+    // Transport variant: this branch reads `provider.baseUrl` and `provider.headers` to build
+    // the URL and the request, and it comes back with the credential already resolved.
+    const warmKeyProvider = selectProactiveApiKeyTransport(config, providerName, candidates.keyed.provider);
+    const provider = warmKeyProvider ?? candidates.keyed.provider;
+    // No fall back to the earlier snapshot once a pick has happened. The picker COMMITS its
+    // choice before returning, so if the chosen reference will not resolve -- revoked keychain
+    // entry, unset env var -- sending the previous key would authenticate a non-idempotent
+    // POST with a credential the config no longer considers active, and the previous key is
+    // the one that was cooling. Fail loudly instead.
+    if (warmKeyProvider && !warmKeyProvider.apiKey?.trim()) {
+      return formatErrorResponse(
+        500,
+        "configuration_error",
+        `image generation selected an API key for "${providerName}" that cannot be resolved`,
+      );
+    }
+    const apiKey = warmKeyProvider?.apiKey ?? candidates.keyed.apiKey;
     if (provider.headers) Object.assign(headers, provider.headers);
     headers["authorization"] = `Bearer ${apiKey}`;
     logCtx.provider = providerName;