@bitkyc08/opencodex 2.46.0 → 2.47.0-preview.20260908

package/src/responses/citation-markers.ts

@@ -42,23 +42,24 @@ export function hasCitationMarker(text: string): boolean {
  */
 export function stripCitationMarkers(text: string): string {
   if (!text.includes(CITATION_MARKER_START)) return text;
-  let out = "";
-  let index = 0;
-  for (;;) {
-    const start = text.indexOf(CITATION_MARKER_START, index);
-    if (start === -1) {
-      out += text.slice(index);
-      return out;
-    }
-    const end = text.indexOf(CITATION_MARKER_END, start + 1);
-    if (end === -1) {
-      // Unterminated: keep the rest verbatim.
-      out += text.slice(index);
-      return out;
-    }
-    out += text.slice(index, start);
-    index = end + 1;
+  // Walk START-delimited segments exactly like the streaming filter below: a START whose
+  // own segment (up to the next START) contains an END within the span bound is a span and
+  // is removed; a START that is superseded by another START before any END, or whose span
+  // exceeds MAX_CITATION_SPAN_LENGTH, is malformed text and stays verbatim. Pairing an
+  // earlier malformed START with a later span's END would delete real answer text and,
+  // worse, disagree with what the streaming deltas already emitted (#3843). The bound is
+  // shared with the streaming filter for the same reason: a span it has already released
+  // as over-bound must not be swallowed here when the END finally arrives.
+  let start = text.indexOf(CITATION_MARKER_START);
+  let out = text.slice(0, start);
+  while (start !== -1) {
+    const nextStart = text.indexOf(CITATION_MARKER_START, start + 1);
+    const segment = text.slice(start, nextStart === -1 ? text.length : nextStart);
+    const end = segment.indexOf(CITATION_MARKER_END, 1);
+    out += end === -1 || end + 1 > MAX_CITATION_SPAN_LENGTH ? segment : segment.slice(end + 1);
+    start = nextStart;
   }
+  return out;
 }
 
 export interface CitationMarkerFilter {
@@ -68,6 +69,18 @@ export interface CitationMarkerFilter {
   flush(): string;
 }
 
+/**
+ * Upper bound on the length of a citation span (START through END inclusive), and therefore
+ * on the text the streaming filter withholds for one unterminated START.
+ *
+ * A real span is `cite` plus a few turn-scoped ids, so it is far under this. Without a
+ * bound, a backend that emits a START and never terminates it makes `held` grow for the
+ * whole response, and every later delta re-scans that accumulated prefix. The whole-string
+ * strip applies the same bound so both paths classify a span identically regardless of how
+ * the text was chunked.
+ */
+const MAX_CITATION_SPAN_LENGTH = 4_096;
+
 /**
  * Streaming filter.
  *
@@ -75,6 +88,9 @@ export interface CitationMarkerFilter {
  * next — so a stateless per-delta strip would emit the tail of a span it never recognized.
  * This holds back the text from an unterminated START and releases it once the END arrives
  * (removed) or the stream ends (verbatim, so nothing the model actually said is lost).
+ *
+ * A span that grows past `MAX_CITATION_SPAN_LENGTH` is malformed ordinary text, so
+ * it is released verbatim instead of withheld; a later START can still open a valid span.
  */
 export function createCitationMarkerFilter(): CitationMarkerFilter {
   // Text from an open START that has not been terminated yet.
@@ -83,13 +99,30 @@ export function createCitationMarkerFilter(): CitationMarkerFilter {
     push(delta: string): string {
       const combined = held + delta;
       held = "";
-      const start = combined.lastIndexOf(CITATION_MARKER_START);
-      if (start === -1) return stripCitationMarkers(combined);
-      const endAfterStart = combined.indexOf(CITATION_MARKER_END, start + 1);
-      if (endAfterStart !== -1) return stripCitationMarkers(combined);
-      // The trailing span is still open: emit everything before it, hold the rest.
-      held = combined.slice(start);
-      return stripCitationMarkers(combined.slice(0, start));
+      let start = combined.indexOf(CITATION_MARKER_START);
+      if (start === -1) return combined;
+      let out = combined.slice(0, start);
+      // Walk START-delimited segments independently so an earlier malformed START is never
+      // paired with a later span's END (the whole-string strip would do exactly that).
+      while (start !== -1) {
+        const nextStart = combined.indexOf(CITATION_MARKER_START, start + 1);
+        const segment = combined.slice(start, nextStart === -1 ? combined.length : nextStart);
+        const end = segment.indexOf(CITATION_MARKER_END, 1);
+        if (end !== -1 && end + 1 <= MAX_CITATION_SPAN_LENGTH) {
+          // A complete span: drop it, keep whatever trails it inside this segment.
+          out += segment.slice(end + 1);
+        } else if (end === -1 && nextStart === -1 && segment.length <= MAX_CITATION_SPAN_LENGTH) {
+          // Only a bounded trailing span can still be completed by a later delta.
+          held = segment;
+        } else {
+          // Superseded by a later START, or over the bound (with or without a late END):
+          // ordinary text, emitted verbatim so neither the retained text nor the per-delta
+          // rescan grows without limit.
+          out += segment;
+        }
+        start = nextStart;
+      }
+      return out;
     },
     flush(): string {
       const rest = held;
@@ -98,4 +131,3 @@ export function createCitationMarkerFilter(): CitationMarkerFilter {
     },
   };
 }
-

package/src/responses/reasoning-envelope.ts

@@ -12,6 +12,9 @@
  * passthrough scrub strips ocxr1 envelopes before native forwarding.
  */
 
+import { createTranslatorBudget, type TranslatorBudget } from "../lib/translator-budget";
+import { jsonUtf8Bytes } from "../lib/json-byte-size";
+
 export const OCX_REASONING_PREFIX = "ocxr1:";
 
 export interface ReasoningEnvelope {
@@ -32,30 +35,61 @@ export interface ReasoningEnvelope {
   krc?: string;
 }
 
-export function encodeReasoningEnvelope(envelope: ReasoningEnvelope): string {
-  return OCX_REASONING_PREFIX + Buffer.from(JSON.stringify(envelope), "utf-8").toString("base64");
+export function encodeReasoningEnvelope(envelope: ReasoningEnvelope, budget?: TranslatorBudget): string {
+  const activeBudget = budget ?? createTranslatorBudget();
+  try {
+    const jsonBytes = jsonUtf8Bytes(envelope);
+    const base64Bytes = 4 * Math.ceil(jsonBytes / 3);
+    // Reserve before materialization: UTF-16 JSON, UTF-8 buffer, base64 string,
+    // and the prefixed result may coexist. Returned-value ownership stays with
+    // callers, whose existing retained accounting must not be charged twice here.
+    const reservation = activeBudget.reserveTransient(
+      Math.max(
+        3 * jsonBytes + 4 * base64Bytes + 2 * OCX_REASONING_PREFIX.length,
+        8 * (OCX_REASONING_PREFIX.length + base64Bytes),
+      ),
+      { kind: "reasoning" },
+    );
+    try {
+      return OCX_REASONING_PREFIX + Buffer.from(JSON.stringify(envelope), "utf-8").toString("base64");
+    } finally {
+      reservation.release();
+    }
+  } finally {
+    if (!budget) activeBudget.dispose();
+  }
 }
 
 /** Decode an ocxr1 envelope; returns null for native (OpenAI-encrypted) blobs or garbage. */
-export function decodeReasoningEnvelope(encryptedContent: string): ReasoningEnvelope | null {
+export function decodeReasoningEnvelope(encryptedContent: string, budget?: TranslatorBudget): ReasoningEnvelope | null {
   if (!encryptedContent.startsWith(OCX_REASONING_PREFIX)) return null;
+  const activeBudget = budget ?? createTranslatorBudget();
   try {
-    const parsed: unknown = JSON.parse(Buffer.from(encryptedContent.slice(OCX_REASONING_PREFIX.length), "base64").toString("utf-8"));
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-    const obj = parsed as { sig?: unknown; red?: unknown };
-    const envelope: ReasoningEnvelope = {};
-    if (typeof obj.sig === "string") envelope.sig = obj.sig;
-    if (Array.isArray(obj.red)) {
-      const red = obj.red.filter((r): r is string => typeof r === "string");
-      if (red.length > 0) envelope.red = red;
+    // Also bound already-encoded replay before slicing, decoding, or parsing it.
+    // Eight bytes per code unit conservatively covers the string/buffer copies.
+    const reservation = activeBudget.reserveTransient(8 * encryptedContent.length, { kind: "reasoning" });
+    try {
+      const parsed: unknown = JSON.parse(Buffer.from(encryptedContent.slice(OCX_REASONING_PREFIX.length), "base64").toString("utf-8"));
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+      const obj = parsed as { sig?: unknown; red?: unknown };
+      const envelope: ReasoningEnvelope = {};
+      if (typeof obj.sig === "string") envelope.sig = obj.sig;
+      if (Array.isArray(obj.red)) {
+        const red = obj.red.filter((r): r is string => typeof r === "string");
+        if (red.length > 0) envelope.red = red;
+      }
+      const txt = (parsed as { txt?: unknown }).txt;
+      const hasTxt = typeof txt === "string";
+      if (hasTxt) envelope.txt = txt;
+      const krc = (parsed as { krc?: unknown }).krc;
+      if (typeof krc === "string" && krc.length > 0) envelope.krc = krc;
+      return envelope.sig || envelope.red || hasTxt || envelope.krc ? envelope : null;
+    } catch {
+      return null;
+    } finally {
+      reservation.release();
     }
-    const txt = (parsed as { txt?: unknown }).txt;
-    const hasTxt = typeof txt === "string";
-    if (hasTxt) envelope.txt = txt;
-    const krc = (parsed as { krc?: unknown }).krc;
-    if (typeof krc === "string" && krc.length > 0) envelope.krc = krc;
-    return envelope.sig || envelope.red || hasTxt || envelope.krc ? envelope : null;
-  } catch {
-    return null;
+  } finally {
+    if (!budget) activeBudget.dispose();
   }
 }

package/src/server/auth-cors.ts

@@ -13,6 +13,7 @@ import {
 import {
   apiKeyTransportConfigError,
   booleanRecordConfigError,
+  providerReasoningPinsConfigError,
   modelAdapterRecordConfigError,
   nonBlankStringArrayConfigError,
   positiveIntegerConfigError,
@@ -581,6 +582,8 @@ export function providerManagementConfigError(name: unknown, provider: unknown):
     return "provider must be a plain object";
   }
   const raw = provider as Record<string, unknown>;
+  const pinsError = providerReasoningPinsConfigError(raw);
+  if (pinsError) return pinsError;
   for (const field of FORBIDDEN_PROVIDER_RUNTIME_FIELDS) {
     if (Object.hasOwn(raw, field)) return `provider ${name} must not include runtime field "${field}"`;
   }
@@ -594,6 +597,9 @@ export function providerManagementConfigError(name: unknown, provider: unknown):
     }
     if (seed) seed.codexAccountMode = raw.codexAccountMode;
     const canonicalCandidate = { ...raw };
+    // Validated operator overlays do not change the canonical auth/transport seed.
+    delete canonicalCandidate.pinnedReasoningEffort;
+    delete canonicalCandidate.modelPinnedReasoningEfforts;
     delete canonicalCandidate.responsesSnapshotRepair;
     // modelCosts is a user-owned display overlay, not part of the canonical
     // forward seed; it is validated separately below (providerModelCostsConfigError).
@@ -829,6 +835,8 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   reasoningEfforts: "editor",
   modelReasoningEfforts: "editor",
   modelDefaultReasoningEfforts: "editor",
+  pinnedReasoningEffort: "editor",
+  modelPinnedReasoningEfforts: "editor",
   modelSupportsReasoningSummaries: "editor",
   modelSupportsVerbosity: "editor",
   supportsVerbosity: "editor",

package/src/server/chat-completions.ts

@@ -25,6 +25,8 @@ import { estimateTokens } from "../lib/token-estimate";
 import { NoEligiblePolicyCandidateError, UnknownRoutingPolicyError, routeModel } from "../router";
 import { evidenceFromBody } from "../routing/request-evidence";
 import { resolveWireProtocolOverride } from "./adapter-resolve";
+import { resolveOpenCodeGoTransport } from "../providers/opencode-go-transport";
+import { normalizeLogConversationId, sessionLaneIdFromRequest } from "./request-log-conversation";
 import type { OcxConfig } from "../types";
 import { readJsonRequestBody } from "./request-decompress";
 import {
@@ -136,6 +138,8 @@ async function handleChatCompletionsWithBudget(
   let chatNativeRoute: ReturnType<typeof routeModel> | null = null;
   try {
     const route = routeModel(config, chatBody.model as string, evidenceFromBody(chatBody));
+    route.provider = resolveOpenCodeGoTransport(route.provider,
+      sessionLaneIdFromRequest(req.headers) ?? normalizeLogConversationId(req.headers.get("x-opencode-session")));
     // Settle the wire once so every branch below reads the adapter this model will
     // actually use, not the provider-wide default (#404).
     route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, "chat");
@@ -237,6 +241,9 @@ async function handleChatCompletionsWithBudget(
     return chatCompletionsErrorResponse(400, CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE, "invalid_request_error");
   }
   const headers = new Headers({ "content-type": "application/json" });
+  // Internal bridge metadata; the Go resolver scopes and hashes it before upstream use.
+  const openCodeSession = req.headers.get("x-opencode-session");
+  if (openCodeSession) headers.set("x-opencode-session", openCodeSession);
   for (const name of FORWARD_HEADERS) {
     if (name === "authorization" && !directRoute) continue;
     const value = req.headers.get(name);

package/src/server/chat-native.ts

@@ -6,6 +6,8 @@ import {
   collectChatCompletion,
   isChatCompletionsStreamError,
 } from "../chat/outbound";
+import { applyChatEffortCap, chatCollabSurface, effortCapAppliesTo, resolvePinnedEffort, supportedLadderFor } from "./effort-policy";
+import { mapReasoningEffort } from "../reasoning-effort";
 import {
   classifyError,
   cyberPolicyErrorType,
@@ -60,6 +62,68 @@ type Rec = Record<string, unknown>;
 const MAX_NATIVE_CHAT_JSON_BYTES = 32 * 1024 * 1024;
 const MAX_NATIVE_CHAT_ERROR_BYTES = 64 * 1024;
 
+const chatEffortSnapshots = new WeakMap<Rec, {
+  inputModel: string;
+  providerName: string;
+  modelId: string;
+  present: boolean;
+  value: unknown;
+  annotation: string | undefined;
+}>();
+
+function normalizePinnedChatEffort(options: HandleNativeChatOptions): void {
+  const { chatBody, route, config, req, logCtx, requestedModel } = options;
+  let snapshot = chatEffortSnapshots.get(chatBody);
+  const inputModel = typeof chatBody.model === "string" ? chatBody.model : requestedModel;
+  let selector = inputModel;
+  if (snapshot) {
+    if (snapshot.providerName === route.providerName && snapshot.modelId === route.modelId) {
+      logCtx.requestedEffort = snapshot.annotation;
+      return;
+    }
+    if (snapshot.present) chatBody.reasoning_effort = snapshot.value;
+    else delete chatBody.reasoning_effort;
+    if (selector === snapshot.inputModel || selector === snapshot.modelId) {
+      selector = `${route.providerName}/${route.modelId}`;
+    }
+  } else {
+    snapshot = {
+      inputModel,
+      providerName: route.providerName,
+      modelId: route.modelId,
+      present: Object.hasOwn(chatBody, "reasoning_effort"),
+      value: chatBody.reasoning_effort,
+      annotation: undefined,
+    };
+    chatEffortSnapshots.set(chatBody, snapshot);
+  }
+  snapshot.inputModel = inputModel;
+  snapshot.providerName = route.providerName;
+  snapshot.modelId = route.modelId;
+  const from = typeof chatBody.reasoning_effort === "string" ? chatBody.reasoning_effort : undefined;
+  logCtx.requestedEffort = from;
+  // Compaction is normally excluded by native-route eligibility; preserve that boundary here too.
+  const pinned = chatBody.compaction_trigger === undefined
+    ? resolvePinnedEffort(route, selector, config)
+    : undefined;
+  if (pinned !== undefined) {
+    logCtx.requestedEffort = from ? `${from}->${pinned}` : pinned;
+    if (pinned === "none") delete chatBody.reasoning_effort;
+    else chatBody.reasoning_effort = pinned;
+    // The native lane historically passes caller effort through, including with caps set.
+    // Only a newly operator-pinned value enters the cap and provider-mapping pipeline.
+    if (effortCapAppliesTo(chatCollabSurface(chatBody), req.headers, config)) {
+      const capped = applyChatEffortCap(chatBody, req.headers, config, supportedLadderFor(route));
+      if (capped) logCtx.requestedEffort = `${logCtx.requestedEffort}->${capped.to}`;
+    }
+    const effort = typeof chatBody.reasoning_effort === "string" ? chatBody.reasoning_effort : undefined;
+    const wireEffort = mapReasoningEffort(route.provider, route.modelId, effort);
+    if (wireEffort === undefined) delete chatBody.reasoning_effort;
+    else chatBody.reasoning_effort = wireEffort;
+  }
+  snapshot.annotation = logCtx.requestedEffort;
+}
+
 function isRec(value: unknown): value is Rec {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -147,9 +211,7 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
     return chatCompletionsErrorResponse(status, safeMessage, type, code);
   };
 
-  logCtx.requestedEffort = typeof options.chatBody.reasoning_effort === "string"
-    ? options.chatBody.reasoning_effort
-    : undefined;
+  normalizePinnedChatEffort(options);
   logCtx.requestedServiceTier = typeof options.chatBody.service_tier === "string"
     ? options.chatBody.service_tier
     : undefined;

package/src/server/claude-messages.ts

@@ -7,6 +7,7 @@
  * unchanged. The Responses output (SSE or JSON) is converted back to Anthropic shape.
  */
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
+import { jsonUtf8Bytes } from "../lib/json-byte-size";
 import { sseFieldValue } from "../lib/sse-decoder";
 import { enforceAnthropicImageLimits, sniffImageDimensions } from "../adapters/anthropic-image-guard";
 import { normalizeAnthropicImages } from "../adapters/anthropic-image-normalize";
@@ -753,13 +754,13 @@ async function handleClaudeMessagesWithBudget(
       };
       delete anthropicBody.thinking;
     }
-    const translation = anthropicToResponsesTranslation(anthropicBody, config.claudeCode);
+    const translation = anthropicToResponsesTranslation(anthropicBody, config.claudeCode, translatorBudget);
     internalBody = translation.body;
     // The Anthropic translator builds its body from model/input/store/stream plus sampling
     // fields only, so the caller intent is applied to the TRANSLATED body rather than the
     // inbound one.
     if (fastRow) internalBody.service_tier = "priority";
-    translatorBudget.chargeRetained(new TextEncoder().encode(JSON.stringify(internalBody)).byteLength, { kind: "request_copies" });
+    translatorBudget.chargeRetained(jsonUtf8Bytes(internalBody), { kind: "request_copies" });
     cacheKeySource = translation.cacheKeySource;
   } catch (err) {
     const overflow = isTranslatorBudgetExceededError(err);
@@ -862,13 +863,26 @@ async function handleClaudeMessagesWithBudget(
       headers.set("session_id", uuidFromHex(internalBody.prompt_cache_key));
     }
   }
-  const internalBodyJson = JSON.stringify(internalBody);
-  translatorBudget.chargeRetained(new TextEncoder().encode(internalBodyJson).byteLength, { kind: "request_copies" });
-  const internalReq = new Request("http://localhost/v1/responses", {
-    method: "POST",
-    headers,
-    body: internalBodyJson,
-  });
+  let internalReq: Request;
+  try {
+    // The UTF-16 JSON string and the Request's UTF-8 body coexist until dispatch.
+    const bodyBytes = jsonUtf8Bytes(internalBody);
+    const reservation = translatorBudget.reserveTransient(3 * bodyBytes, { kind: "request_copies" });
+    try {
+      internalReq = new Request("http://localhost/v1/responses", {
+        method: "POST",
+        headers,
+        body: JSON.stringify(internalBody),
+      });
+    } finally {
+      reservation.release();
+    }
+    translatorBudget.chargeRetained(bodyBytes, { kind: "request_copies" });
+  } catch (err) {
+    if (!isTranslatorBudgetExceededError(err)) throw err;
+    if (logIds) addFinalRequestLog(logIds.requestId, logIds.start, logCtx, 413, { closeReason: "non_stream" });
+    return anthropicErrorResponse(413, "request translation buffer exceeded the safe limit", "request_too_large", "translation_buffer_limit");
+  }
 
   // Request-log wiring mirrors the /v1/responses route: native passthrough finalizes
   // via the terminal callbacks; routed streams get the Responses-vocabulary log tap
@@ -1006,7 +1020,13 @@ async function handleClaudeMessagesWithBudget(
     }
     return anthropicErrorResponse(502, error?.message ?? "upstream request failed", "api_error");
   }
-  const message = responsesJsonToAnthropicMessage(json, requestedModel);
+  let message: Rec;
+  try {
+    message = responsesJsonToAnthropicMessage(json, requestedModel, translatorBudget);
+  } catch (err) {
+    if (!isTranslatorBudgetExceededError(err)) throw err;
+    return anthropicErrorResponse(413, "upstream translation buffer exceeded the safe limit", "request_too_large", "translation_buffer_limit");
+  }
   if ((message as Rec).type === "error") {
     return new Response(JSON.stringify(message), {
       status: 529,

package/src/server/effort-policy.ts

@@ -14,7 +14,7 @@
  */
 import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
 import { modelInList } from "../types";
-import { codexEffortRank, configuredReasoningEfforts, isCodexReasoningEffort, modelRecordValue } from "../reasoning-effort";
+import { codexEffortRank, configuredReasoningEfforts, isCodexReasoningEffort, isDeclaredReasoningEffort, modelRecordValue } from "../reasoning-effort";
 import { catalogModelEfforts } from "../codex/catalog";
 
 /**
@@ -188,3 +188,185 @@ export function applyEffortCap(
   if (raw?.reasoning && typeof raw.reasoning === "object") raw.reasoning.effort = resolved;
   return { from: requested, to: resolved, subagent };
 }
+
+/**
+ * Resolve any pinned reasoning effort configured for this model or provider.
+ * Priority order:
+ * 1. Provider model-specific pinned effort (`provider.modelPinnedReasoningEfforts[modelId]`)
+ * 2. Provider-wide pinned effort (`provider.pinnedReasoningEffort`)
+ * 3. Global config model-specific pinned effort (`config.modelPinnedEfforts[modelId]`)
+ * Global keys try the final pre-namespace selector, provider-qualified destination,
+ * then bare destination, using modelRecordValue's exact/family/case-fold semantics.
+ * The caller removes synthetic effort rows and combo selectors before this boundary.
+ *
+ * Returns undefined when no valid pinned effort tier is configured.
+ */
+export function resolvePinnedEffort(
+  route: { provider: OcxProviderConfig; modelId: string; providerName?: string },
+  parsedModelId?: string,
+  config?: OcxConfig,
+): string | undefined {
+  const prov = route.provider;
+  const rawProvModel = modelRecordValue(prov.modelPinnedReasoningEfforts, route.modelId)
+    ?? (parsedModelId ? modelRecordValue(prov.modelPinnedReasoningEfforts, parsedModelId) : undefined);
+  if (rawProvModel && isDeclaredReasoningEffort(rawProvModel)) {
+    return rawProvModel;
+  }
+  if (prov.pinnedReasoningEffort && isDeclaredReasoningEffort(prov.pinnedReasoningEffort)) {
+    return prov.pinnedReasoningEffort;
+  }
+  if (config?.modelPinnedEfforts) {
+    const rawGlobal = (parsedModelId ? modelRecordValue(config.modelPinnedEfforts, parsedModelId) : undefined)
+      ?? (route.providerName ? modelRecordValue(config.modelPinnedEfforts, `${route.providerName}/${route.modelId}`) : undefined)
+      ?? modelRecordValue(config.modelPinnedEfforts, route.modelId);
+    if (rawGlobal && isDeclaredReasoningEffort(rawGlobal)) {
+      return rawGlobal;
+    }
+  }
+  return undefined;
+}
+
+interface EffortSnapshot {
+  selector: string;
+  providerName: string;
+  modelId: string;
+  reasoningPresent: boolean;
+  reasoning: OcxParsedRequest["options"]["reasoning"];
+  rawEffortPresent: boolean;
+  rawEffort: unknown;
+}
+
+const effortSnapshots = new WeakMap<OcxParsedRequest, EffortSnapshot>();
+
+/** Capture effective synthetic/combo defaults before final model namespace rewriting.
+ * A different destination restores effort alone; intervening summary/options edits survive.
+ * Credential retries do not change the destination and retain their existing decision.
+ */
+export function prepareEffortNormalization(
+  parsed: OcxParsedRequest,
+  route: { providerName: string; modelId: string },
+): string {
+  const raw = parsed._rawBody as { reasoning?: Record<string, unknown> } | undefined;
+  const previous = effortSnapshots.get(parsed);
+  if (!previous) {
+    effortSnapshots.set(parsed, {
+      selector: parsed.modelId,
+      providerName: route.providerName,
+      modelId: route.modelId,
+      reasoningPresent: Object.hasOwn(parsed.options, "reasoning"),
+      reasoning: parsed.options.reasoning,
+      rawEffortPresent: !!raw?.reasoning && Object.hasOwn(raw.reasoning, "effort"),
+      rawEffort: raw?.reasoning?.effort,
+    });
+    return parsed.modelId;
+  }
+  if (previous.providerName === route.providerName && previous.modelId === route.modelId) {
+    return previous.selector;
+  }
+  if (previous.reasoningPresent) parsed.options.reasoning = previous.reasoning;
+  else delete parsed.options.reasoning;
+  if (raw && previous.rawEffortPresent) {
+    if (!raw.reasoning || typeof raw.reasoning !== "object") raw.reasoning = {};
+    raw.reasoning.effort = previous.rawEffort;
+  } else if (raw?.reasoning && typeof raw.reasoning === "object") {
+    delete raw.reasoning.effort;
+  }
+  // An unchanged wire model is the previous destination, not a new requested alias.
+  previous.selector = parsed.modelId === previous.modelId || parsed.modelId === previous.selector
+    ? `${route.providerName}/${route.modelId}`
+    : parsed.modelId;
+  previous.providerName = route.providerName;
+  previous.modelId = route.modelId;
+  return previous.selector;
+}
+
+/**
+ * Detect collaboration surface for a native chat request body.
+ * Mirrors Responses collabSurface behavior across function and custom tool representations.
+ */
+export function chatCollabSurface(chatBody: Record<string, unknown>): "v1" | "v2" | null {
+  if (!Array.isArray(chatBody.tools)) return null;
+  let namespacedSpawn = false;
+  let flatSpawn = false;
+  let v1Only = false;
+  let v2Only = false;
+  for (const raw of chatBody.tools) {
+    if (!raw || typeof raw !== "object") continue;
+    const tool = raw as Record<string, unknown>;
+    let name = "";
+    let namespace: string | undefined = undefined;
+    if (tool.type === "function" && tool.function && typeof tool.function === "object") {
+      const fn = tool.function as Record<string, unknown>;
+      name = typeof fn.name === "string" ? fn.name : "";
+    } else if (tool.type === "custom" && tool.custom && typeof tool.custom === "object") {
+      const cust = tool.custom as Record<string, unknown>;
+      name = typeof cust.name === "string" ? cust.name : "";
+    } else if (typeof tool.name === "string") {
+      name = tool.name;
+    }
+    if (typeof tool.namespace === "string") namespace = tool.namespace;
+    if (name === "spawn_agent") {
+      if (namespace) namespacedSpawn = true;
+      else flatSpawn = true;
+    } else if (name === "send_input" || name === "resume_agent" || name === "close_agent") {
+      v1Only = true;
+    } else if (name === "send_message" || name === "followup_task" || name === "interrupt_agent" || name === "list_agents") {
+      v2Only = true;
+    }
+  }
+  if (!namespacedSpawn && !flatSpawn) return null;
+  if (namespacedSpawn && flatSpawn) return null;
+  if (v1Only && v2Only) return null;
+  if (v1Only) return "v1";
+  if (v2Only) return "v2";
+  return namespacedSpawn ? "v1" : "v2";
+}
+
+/**
+ * Apply effortCap to a native chat completions body when admitted by the collaboration gate.
+ */
+export function applyChatEffortCap(
+  chatBody: Record<string, unknown>,
+  headers: Headers,
+  config: OcxConfig,
+  supported?: readonly string[] | undefined,
+): { from: string; to: string; subagent: boolean } | null {
+  const subagent = isThreadSpawnRequest(headers);
+  const cap = effortCapFor(config, subagent);
+  if (!cap) return null;
+  const resolved = resolveCappedEffort(cap, supported);
+  const requested = typeof chatBody.reasoning_effort === "string" ? chatBody.reasoning_effort : undefined;
+  if (resolved === null) {
+    if (!requested) return null;
+    delete chatBody.reasoning_effort;
+    return { from: requested, to: "none", subagent };
+  }
+  if (!requested || !isCodexReasoningEffort(requested)) return null;
+  if (codexEffortRank(requested) <= codexEffortRank(resolved)) return null;
+  chatBody.reasoning_effort = resolved;
+  return { from: requested, to: resolved, subagent };
+}
+
+export function applyPinnedEffort(
+  parsed: OcxParsedRequest,
+  route: { provider: OcxProviderConfig; modelId: string; providerName?: string },
+  config?: OcxConfig,
+  selector = effortSnapshots.get(parsed)?.selector ?? parsed.modelId,
+): { from: string | undefined; to: string } | null {
+  if (parsed._compactionRequest === true) return null;
+  const pinned = resolvePinnedEffort(route, selector, config);
+  if (!pinned) return null;
+  const requested = parsed.options.reasoning;
+  const raw = parsed._rawBody as { reasoning?: { effort?: string } } | undefined;
+  const targetEffort = pinned === "none" ? undefined : pinned;
+  parsed.options.reasoning = targetEffort;
+  if (targetEffort) {
+    if (raw && typeof raw === "object") {
+      if (!raw.reasoning || typeof raw.reasoning !== "object") raw.reasoning = {};
+      raw.reasoning.effort = targetEffort;
+    }
+  } else if (raw?.reasoning && typeof raw.reasoning === "object") {
+    delete raw.reasoning.effort;
+  }
+  return { from: requested, to: pinned };
+}