@bitkyc08/opencodex 2.55.0-preview.20260914 → 2.56.0

package/src/server/responses/core-errors.ts

@@ -0,0 +1,152 @@
+import { readBoundedResponseBody } from "../../lib/bounded-body";
+import { redactSecretString } from "../../lib/redact";
+import { isCyberPolicyMessage, isCyberPolicyCode } from "../../lib/errors";
+import { isTranslatorBudgetExceededError } from "../../lib/translator-budget";
+import { formatErrorResponse } from "../../bridge";
+import {
+  UnsupportedContentEncodingError,
+  DecompressedBodyTooLargeError,
+  describeInboundBodyRefusal,
+} from "../request-decompress";
+import { comboCooldownRetryAfterSeconds } from "../../combos";
+import type { AgentTaskRecoveryFailureReason } from "./agent-task-recovery";
+
+/**
+ * Materialize an upstream error body only when the bounded reader observed a complete,
+ * display-safe payload. Partial timeout and over-limit prefixes are attacker-controlled,
+ * so callers keep their existing status-only fallback instead.
+ */
+export async function readDisplaySafeErrorText(
+  response: Response,
+  signal: AbortSignal,
+  fallback: string,
+): Promise<string> {
+  try {
+    const body = await readBoundedResponseBody(response, { signal });
+    return body.displaySafe ? body.text : fallback;
+  } catch {
+    // Preserve the former Response.text().catch(fallback) contract. Request-abort
+    // classification remains owned by the surrounding response pipeline.
+    return fallback;
+  }
+}
+
+
+export interface NormalizedUpstreamErrorText {
+  safeText: string;
+  message?: string;
+  type?: string;
+  code?: string;
+  cyberPolicy: boolean;
+}
+
+
+/**
+ * Extract the structured provider error envelope without making `error.type` authoritative.
+ * Policy identity comes from the dedicated code (or the legacy message fallback); a credible
+ * upstream type is only carried through so callers do not erase provider diagnostics.
+ */
+export function normalizeUpstreamErrorText(text: string, fallback: string): NormalizedUpstreamErrorText {
+  const safeText = redactSecretString(text).slice(0, 500).trim() || fallback;
+  let message: string | undefined;
+  let type: string | undefined;
+  let code: string | undefined;
+  try {
+    const parsed = JSON.parse(text) as Record<string, unknown>;
+    const response = parsed.response && typeof parsed.response === "object" && !Array.isArray(parsed.response)
+      ? parsed.response as Record<string, unknown>
+      : undefined;
+    const candidates = [parsed.error, response?.error, response?.last_error, parsed.last_error, parsed];
+    const source = candidates.find((candidate): candidate is Record<string, unknown> => {
+      if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) return false;
+      const record = candidate as Record<string, unknown>;
+      return [record.message, record.type, record.code].some(value => typeof value === "string");
+    });
+    if (!source) return { safeText, cyberPolicy: isCyberPolicyMessage(safeText) };
+    if (typeof source.message === "string" && source.message.trim()) {
+      message = redactSecretString(source.message.trim()).slice(0, 500);
+    }
+    if (typeof source.type === "string" && source.type.trim()) type = source.type.trim();
+    if (typeof source.code === "string" && source.code.trim()) code = source.code.trim();
+  } catch {
+    /* non-JSON upstream body — retain the bounded display-safe text */
+  }
+  const cyberPolicy = isCyberPolicyCode(code) || isCyberPolicyMessage(message ?? safeText);
+  return { safeText, message, type, code, cyberPolicy };
+}
+
+
+
+
+export function decodeRequestErrorResponse(err: unknown, label: string): Response {
+  if (isTranslatorBudgetExceededError(err)) {
+    return formatErrorResponse(413, "request_too_large", "request translation buffer exceeded the safe limit", {
+      code: "translation_buffer_limit",
+    });
+  }
+  if (err instanceof UnsupportedContentEncodingError) {
+    return formatErrorResponse(415, "invalid_request_error", err.message);
+  }
+  if (err instanceof DecompressedBodyTooLargeError) {
+    return formatErrorResponse(413, "inbound_body_too_large", describeInboundBodyRefusal(err));
+  }
+  console.warn(`[${label}] request body decode/parse failed: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`);
+  return formatErrorResponse(400, "invalid_request_error", "Invalid JSON body");
+}
+
+
+
+
+export function comboUnavailableResponse(
+  message: string,
+  options?: { retryAfter?: string | null },
+): Response {
+  const headers = new Headers({ "Content-Type": "application/json" });
+  const retryAfter = options?.retryAfter?.trim();
+  if (retryAfter && retryAfter.length > 0 && retryAfter.length <= 128) {
+    headers.set("Retry-After", retryAfter);
+  }
+  return new Response(
+    JSON.stringify({
+      error: { message, type: "server_error", code: "combo_unavailable" },
+    }),
+    { status: 503, headers },
+  );
+}
+
+
+export function comboUnavailable(comboId: string, now = Date.now()): Response {
+  return comboUnavailableResponse(`No available targets for combo: ${comboId}`, {
+    retryAfter: comboCooldownRetryAfterSeconds(comboId, now),
+  });
+}
+
+
+
+
+/**
+ * Build the 499 JSON error the proxy returns when the client disconnects before the
+ * response completes (`client_cancelled`).
+ */
+export function clientCancelledResponse(): Response {
+  return formatErrorResponse(499, "client_cancelled", "Client cancelled request");
+}
+
+
+export const UNREADABLE_ENCRYPTED_AGENT_TASK_MESSAGE =
+  "Routed V2 worker task is encrypted for the native ChatGPT backend and cannot be read by the selected provider. Use plaintext V2 agent-message delivery or select a native ChatGPT model.";
+
+
+export function unreadableEncryptedAgentTaskResponse(reason?: AgentTaskRecoveryFailureReason): Response {
+  return new Response(
+    JSON.stringify({
+      error: {
+        message: UNREADABLE_ENCRYPTED_AGENT_TASK_MESSAGE,
+        type: "invalid_request_error",
+        code: "unreadable_encrypted_agent_task",
+        ...(reason === undefined ? {} : { recovery_reason: reason }),
+      },
+    }),
+    { status: 400, headers: { "Content-Type": "application/json" } },
+  );
+}

package/src/server/responses/core-lifetime.ts

@@ -0,0 +1,95 @@
+import type { TranslatorBudget } from "../../lib/translator-budget";
+import {
+  isNativePassthroughSseResponse,
+  markNativePassthroughSseResponse,
+  isEagerRelaySseResponse,
+  markEagerRelaySseResponse,
+} from "../relay";
+
+// runTurn adapters own an event queue and perform their combo preflight before
+// bridging. A second byte-stream reader would reinterpret that transport's
+// already-committed event boundary and can replay custom adapter work.
+export const runTurnAdapterSseResponses = new WeakSet<Response>();
+
+
+// Whole-body policy for non-streaming upstream JSON responses (see the application/json
+// branch of the passthrough return path). 32 MiB matches the continuation snapshot read
+// bound and is far above any legitimate non-streaming completion, including base64 image
+// payloads. The stall deadlines only govern the body transfer — generation time before
+// the response headers is untouched. Generation after early/chunked headers but before
+// the first body byte previously used the 30-second inactivity deadline; this call site
+// gives it the full body deadline instead.
+export const MAX_UPSTREAM_JSON_BODY_BYTES = 32 * 1024 * 1024;
+
+export const UPSTREAM_JSON_BODY_TOTAL_TIMEOUT_MS = 180_000;
+
+export const UPSTREAM_JSON_BODY_INACTIVITY_TIMEOUT_MS = 30_000;
+
+export const UPSTREAM_JSON_BODY_READ_OPTIONS = {
+  maxBytes: MAX_UPSTREAM_JSON_BODY_BYTES,
+  totalTimeoutMs: UPSTREAM_JSON_BODY_TOTAL_TIMEOUT_MS,
+  inactivityTimeoutMs: UPSTREAM_JSON_BODY_INACTIVITY_TIMEOUT_MS,
+  firstByteTimeoutMs: UPSTREAM_JSON_BODY_TOTAL_TIMEOUT_MS,
+};
+
+
+
+
+export function finalizeOwnedTranslatorBudget(response: Response, budget: TranslatorBudget): Response {
+  if (!response.body) {
+    budget.dispose();
+    return response;
+  }
+  const reader = response.body.getReader();
+  let finalized = false;
+  const finalize = () => {
+    if (finalized) return;
+    finalized = true;
+    budget.dispose();
+  };
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          finalize();
+          controller.close();
+        } else {
+          controller.enqueue(result.value);
+        }
+      } catch (error) {
+        finalize();
+        controller.error(error);
+      }
+    },
+    async cancel(reason) {
+      try { await reader.cancel(reason); } finally { finalize(); }
+    },
+  });
+  const finalizedResponse = new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+  if (isNativePassthroughSseResponse(response)) {
+    markNativePassthroughSseResponse(finalizedResponse);
+  }
+  if (isEagerRelaySseResponse(response)) {
+    markEagerRelaySseResponse(finalizedResponse);
+  }
+  return finalizedResponse;
+}
+
+
+
+
+export function linkAbortSignal(upstream: AbortController, signal?: AbortSignal): () => void {
+  if (!signal) return () => {};
+  if (signal.aborted) {
+    upstream.abort(signal.reason);
+    return () => {};
+  }
+  const onAbort = () => upstream.abort(signal.reason);
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}

package/src/server/responses/core-normalize.ts

@@ -0,0 +1,350 @@
+import { sanitizeLogMetadataString } from "../../lib/redact";
+import type { RouteResult } from "../../router";
+import type { InboundWire } from "../../providers/registry";
+import { resolveWireProtocolOverride } from "../adapter-resolve";
+import type { OcxConfig, OcxParsedRequest, OcxProviderConfig, TierDecision } from "../../types";
+import {
+  resolveCodexModelEntitlements,
+  entitledCodexAccountIdsForModel,
+} from "../../codex/model-entitlements";
+import type { SubagentModelEligibleAccountIds } from "../../codex/subagent-model-fallback";
+import { subagentFallbackNeedsModelEntitlements } from "../../codex/subagent-model-fallback";
+import { MAIN_CODEX_ACCOUNT_ID } from "../../codex/main-account";
+import type { RequestLogContext } from "../request-log";
+import type { HandleResponsesOptions } from "./core-options";
+import { prepareEffortNormalization } from "../effort-policy";
+import { providerModelResponsesUpstreamStreaming } from "../../providers/registry";
+import { resolveOpenCodeGoTransport } from "../../providers/opencode-go-transport";
+import { getOrAllocateRequestSessionLane } from "../request-log-conversation";
+import { shouldPreparePlaintextV2AgentMessages } from "../../responses/plaintext-v2-agent-messages";
+import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
+import { applyOpenAiVirtualModel } from "../../providers/openai-virtual-models";
+import {
+  fastPolicyForModel,
+  serviceTierSupportFromPolicy,
+  SERVICE_TIER_ADAPTERS,
+} from "../../providers/service-tier";
+import {
+  tierObservationContext,
+  decideTier,
+  tierValueAfterDecision,
+  canonicalFastTierMarker,
+} from "../../providers/fastwire";
+import { multiAgentGuidanceText, injectDeveloperMessage, collabSurface } from "./collaboration";
+import { multiAgentGuidanceEnabled } from "../../config";
+import { isInjectionDebugEnabled } from "../../lib/debug-settings";
+import { injectionDebugLog } from "../../lib/injection-debug-log";
+import { recordAttemptRequestedEffort } from "../request-log";
+import type { ResolvedFastPolicy } from "../../providers/fastwire";
+
+export const MAX_FAST_WIRE_CAPABILITY_WARNINGS = 256;
+
+export const warnedFastWireCapabilityGaps = new Set<string>();
+
+
+export function warnFastWireCapabilityGap(providerName: string, modelId: string): void {
+  const safeProvider = sanitizeLogMetadataString(providerName) ?? "unknown";
+  const safeModel = sanitizeLogMetadataString(modelId) ?? "unknown";
+  const key = `${safeProvider}\0${safeModel}`;
+  if (warnedFastWireCapabilityGaps.has(key)) return;
+  if (warnedFastWireCapabilityGaps.size >= MAX_FAST_WIRE_CAPABILITY_WARNINGS) {
+    const oldest = warnedFastWireCapabilityGaps.values().next().value;
+    if (oldest !== undefined) warnedFastWireCapabilityGaps.delete(oldest);
+  }
+  warnedFastWireCapabilityGaps.add(key);
+  console.warn(
+    `[opencodex] Fast policy for ${safeProvider}/${safeModel} has service-tier capability but no Fast wire; preserving only caller-permitted tier behavior`,
+  );
+}
+
+
+/**
+ * Keep this trust boundary deliberately narrow: only a key-auth Responses route may consume
+ * opaque child-task ciphertext, and the model's final wire override must still be Responses.
+ * Callers keep combo attempts on their existing native-only recovery/fail-closed behavior.
+ */
+export function canPassThroughEncryptedV2AgentTask(
+  route: RouteResult,
+  inboundWire: InboundWire,
+): boolean {
+  if (route.combo !== undefined) return false;
+  const provider = route.provider;
+  if (
+    inboundWire !== "responses"
+    || provider.allowEncryptedV2AgentTasks !== true
+    || (provider.authMode ?? "key") !== "key"
+  ) return false;
+
+  return resolveWireProtocolOverride(
+    route.providerName,
+    route.modelId,
+    provider,
+    inboundWire,
+  ).adapter === "openai-responses";
+}
+
+
+export async function resolveSubagentFallbackModelEligibility(args: {
+  config: OcxConfig;
+  fallbackChain: readonly string[] | null;
+  nativeMainReadsForbidden: boolean;
+  resolver: typeof resolveCodexModelEntitlements;
+}): Promise<SubagentModelEligibleAccountIds | undefined> {
+  if (!subagentFallbackNeedsModelEntitlements(args.fallbackChain, args.config)) return undefined;
+  const excludeAccountIds = args.nativeMainReadsForbidden
+    ? new Set([MAIN_CODEX_ACCOUNT_ID])
+    : undefined;
+  const snapshot = await args.resolver(args.config, { excludeAccountIds });
+  return (modelId) => {
+    const entitledAccountIds = entitledCodexAccountIdsForModel(snapshot, modelId);
+    return entitledAccountIds
+      ? new Set([...entitledAccountIds].filter(accountId => !excludeAccountIds?.has(accountId)))
+      : undefined;
+  };
+}
+
+
+/**
+ * Apply every route-dependent request mutation against the final selected route.
+ * Must run only after subagent fallback has settled the model/provider.
+ */
+export async function applyFinalRouteRequestNormalization(args: {
+  parsed: OcxParsedRequest;
+  route: RouteResult;
+  config: OcxConfig;
+  req: Request;
+  logCtx: RequestLogContext;
+  inboundWire: InboundWire;
+  inboundTransport?: "websocket";
+  claudeGoAffinity?: HandleResponsesOptions["claudeGoAffinity"];
+}): Promise<void> {
+  const { parsed, route, config, req, logCtx, inboundWire, inboundTransport } = args;
+  const effortSelector = prepareEffortNormalization(parsed, route);
+
+  // Only Anthropic message routes retain the Codex-facing selector. Other providers must keep
+  // their existing response.model contract even when their public and wire model ids differ.
+  const responseModelId = parsed.modelId;
+  const preserveAnthropicResponseModel = route.providerName === "anthropic"
+    || route.provider.adapter === "anthropic";
+
+  // Apply the routed model id upstream: routing may strip a "<provider>/" namespace.
+  if (route.modelId !== parsed.modelId) {
+    if (parsed._rawBody && typeof parsed._rawBody === "object") {
+      (parsed._rawBody as { model?: string }).model = route.modelId;
+    }
+    parsed.modelId = route.modelId;
+  }
+  // Transport-neutral reliability policy (#875): applies to any Responses
+  // upstream whose final adapter is openai-responses, not only WS turns.
+  const responsesUpstreamStreaming = providerModelResponsesUpstreamStreaming(
+    route.providerName,
+    route.provider,
+    route.modelId,
+  );
+
+  // Settle the wire once so logging, fast-mode, auth, and sidecars read the adapter
+  // this request will actually use (#404).
+  route.provider = resolveOpenCodeGoTransport(route.provider,
+    args.claudeGoAffinity ? args.claudeGoAffinity.sessionLane : getOrAllocateRequestSessionLane(req));
+  route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire);
+  parsed._plaintextV2AgentMessages = shouldPreparePlaintextV2AgentMessages({
+    enabled: config.plaintextV2AgentMessages === true,
+    inboundWire,
+    canonicalChatGpt: isCanonicalOpenAiForwardProvider(route.provider),
+    requestBody: parsed._rawBody,
+  });
+  // Recompute from the original wire preference on every route, including fallback.
+  // A provider default never converts raw reasoning into a summary.
+  if (inboundWire === "responses" && parsed._rawBody) {
+    const summary = (parsed._rawBody as { reasoning?: { summary?: unknown } }).reasoning?.summary;
+    parsed.options.hideThinkingSummary = summary === "none"
+      || (!summary && route.provider.showThinkingSummary !== true);
+  }
+  if (preserveAnthropicResponseModel) parsed._responseModelId = responseModelId;
+  logCtx.model = route.modelId;
+  logCtx.provider = route.providerName;
+  logCtx.providerAdapter = route.provider.adapter;
+  logCtx.routeDecision = route.routeDecision;
+  if (route.routeReason === "model-alias" || route.modelId !== responseModelId && responseModelId.includes("/")) logCtx.requestedAlias = responseModelId;
+
+  if (responsesUpstreamStreaming === false && route.provider.adapter === "openai-responses") {
+    parsed.stream = false;
+    if (parsed._rawBody && typeof parsed._rawBody === "object") {
+      (parsed._rawBody as Record<string, unknown>).stream = false;
+    }
+  }
+
+  // Generic Responses clients (e.g. AI-SDK apps) omit `store`, but the canonical
+  // forward Codex backend rejects a native request without an explicit store:false.
+  // Default it only there — every other Responses upstream (key-auth providers and
+  // custom forward gateways) intentionally keeps the omitted-store server-side
+  // default for previous_response_id reuse — and never override an explicit value.
+  if (
+    isCanonicalOpenAiForwardProvider(route.provider)
+    && parsed._rawBody && typeof parsed._rawBody === "object"
+    && (parsed._rawBody as Record<string, unknown>).store === undefined
+  ) {
+    (parsed._rawBody as Record<string, unknown>).store = false;
+  }
+
+  // Final selected model before virtual wire-model rewriting (Pro aliases).
+  const finalSelectedModelId = route.modelId;
+
+  // Virtual model rewriting: Pro aliases → base model + reasoning.mode="pro".
+  applyOpenAiVirtualModel(parsed, route, logCtx);
+  if (parsed._responseModelId !== undefined && parsed._responseModelId !== parsed.modelId) {
+    logCtx.resolvedModel = route.modelId;
+    logCtx.preserveResolvedModelFromRoute = true;
+  }
+
+  // Resolve Fast policy after the final route/wire settles. A1 records the decision on parsed
+  // options; the Responses adapter owns the final outbound body write.
+  const fastPolicy = fastPolicyForModel(
+    route.provider,
+    route.modelId,
+    route.providerName,
+    inboundWire,
+    config.providers[route.providerName],
+  );
+  const modelServiceTierSupport = serviceTierSupportFromPolicy(fastPolicy);
+  const callerTier = parsed.options.serviceTier;
+  // The ChatGPT-internal Codex backend echoes `service_tier: "default"` even on turns it
+  // scheduled as priority, so its echo cannot confirm OR deny Fast. Believing it reported every
+  // Fast request as `response-declined` (#2558). The public API's echo stays authoritative.
+  parsed.options.tierObservation = tierObservationContext(
+    fastPolicy,
+    config.fastMode,
+    callerTier,
+    isCanonicalOpenAiForwardProvider(route.provider) ? false : undefined,
+  );
+  parsed.options.tierDecision = decideTier(fastPolicy, config.fastMode, callerTier);
+  parsed.options.serviceTier = tierValueAfterDecision(parsed.options.tierDecision, callerTier);
+  if (fastPolicy.capability === true && fastPolicy.fastWire === null) {
+    warnFastWireCapabilityGap(route.providerName, route.modelId);
+  }
+  applyServiceTierGate(
+    route.provider,
+    parsed._rawBody,
+    parsed.options,
+    route.modelId,
+    route.providerName,
+    inboundWire,
+    fastPolicy,
+  );
+  if (modelServiceTierSupport === false) {
+    logCtx.requestedServiceTier = undefined;
+    logCtx.requestedSpeedLabel = undefined;
+  }
+
+  {
+    const guidance = await multiAgentGuidanceText(parsed, {
+      multiAgentGuidanceEnabled: config.multiAgentGuidanceEnabled,
+      codexAccountNamespace: route.codexAccountNamespace,
+      injectionModel: config.injectionModel,
+      injectionEffort: config.injectionEffort,
+      subagentModels: config.subagentModels,
+      subagentModelFallback: config.subagentModelFallback,
+      injectionPrompt: config.injectionPrompt,
+    });
+    if (guidance) {
+      injectDeveloperMessage(parsed, guidance);
+      if (isInjectionDebugEnabled()) {
+        injectionDebugLog(`[opencodex] ${route.modelId}: multi-agent guidance injected (surface=${collabSurface(parsed)}, guidanceEnabled=${multiAgentGuidanceEnabled(config)}, ${guidance.length} chars)`);
+      }
+    } else if (isInjectionDebugEnabled() && collabSurface(parsed) !== null) {
+      injectionDebugLog(`[opencodex] ${route.modelId}: collab surface=${collabSurface(parsed)}, guidance silent (effort=${parsed.options.reasoning ?? "unset"}, injectionModel=${config.injectionModel ?? "unset"})`);
+    }
+  }
+
+  {
+    const { applyPinnedEffort } = await import("../effort-policy");
+    const pinned = applyPinnedEffort(parsed, route, config, effortSelector);
+    if (pinned) {
+      logCtx.requestedEffort = pinned.from ? `${pinned.from}->${pinned.to}` : pinned.to;
+      if (isInjectionDebugEnabled()) {
+        injectionDebugLog(`[opencodex] ${route.modelId}: pinned reasoning effort applied (${pinned.from ?? "none"} -> ${pinned.to})`);
+      }
+    }
+  }
+
+  {
+    const { applyEffortCap, effortCapAppliesTo, supportedLadderFor } = await import("../effort-policy");
+    const surface = collabSurface(parsed);
+    if (effortCapAppliesTo(surface, req.headers, config, parsed._compactionRequest === true)) {
+      const capped = applyEffortCap(parsed, req.headers, config, supportedLadderFor(route));
+      if (capped) {
+        logCtx.requestedEffort = `${capped.from}->${capped.to}`;
+        if (isInjectionDebugEnabled()) {
+          injectionDebugLog(`[opencodex] ${route.modelId}: effort cap applied (${capped.from} -> ${capped.to}, ${capped.subagent ? "sub-agent" : "main"} turn)`);
+        }
+      }
+    } else if (isInjectionDebugEnabled() && (config.effortCap || config.subagentEffortCap)) {
+      injectionDebugLog(`[opencodex] ${route.modelId}: effort cap skipped (surface=${surface ?? "none"}, v2 feature only)`);
+    }
+  }
+
+  {
+    const { nativeEffortClamp, shouldApplyNativeEffortClamp } = await import("../../codex/catalog");
+    const clamped = shouldApplyNativeEffortClamp(route.providerName, route.provider, finalSelectedModelId)
+      ? nativeEffortClamp(route.modelId, parsed.options.reasoning)
+      : null;
+    if (clamped) {
+      parsed.options.reasoning = clamped;
+      const raw = parsed._rawBody as { reasoning?: { effort?: string } } | undefined;
+      if (raw?.reasoning && typeof raw.reasoning === "object") raw.reasoning.effort = clamped;
+      logCtx.requestedEffort = `${logCtx.requestedEffort ?? "max"}->${clamped}`;
+    }
+  }
+  recordAttemptRequestedEffort(logCtx);
+  logCtx.modelSupportsServiceTier = SERVICE_TIER_ADAPTERS.has(route.provider.adapter)
+    ? modelServiceTierSupport
+    : undefined;
+}
+
+
+/**
+ * Service-tier capability gate, applied after the final route/wire is settled. A
+ * provider explicitly documented as NOT supporting `service_tier` must never
+ * receive it: strip the field and clear the logging value even when the caller
+ * supplied one (fail closed). A policy-produced canonical Fast decision has
+ * already passed capability validation and cannot be vetoed by Chat's caller
+ * forwarding permission. On unclassified routes every caller tier remains subject
+ * to `forwardCallerTier`.
+ */
+export function applyServiceTierGate(
+  provider: OcxProviderConfig,
+  rawBody: unknown,
+  options: { serviceTier?: string; tierDecision?: TierDecision },
+  modelId?: string,
+  providerName?: string,
+  inbound: InboundWire = "responses",
+  resolvedPolicy?: ResolvedFastPolicy,
+): void {
+  // A direct unit caller without a model id retains the historical tri-state behavior for
+  // adapters outside the OpenAI service-tier family. Once a model is known, resolve the final
+  // model adapter as well: an explicit override to Anthropic (or another non-OpenAI wire) must
+  // not carry a caller-supplied `service_tier` through a route that cannot forward it.
+  if (modelId === undefined && !SERVICE_TIER_ADAPTERS.has(provider.adapter)) return;
+  const policy = modelId === undefined
+    ? undefined
+    : resolvedPolicy ?? fastPolicyForModel(provider, modelId, providerName, inbound);
+  const forwardCallerTier = modelId === undefined
+    ? provider.supportsServiceTier !== false
+    : policy!.forwardCallerTier;
+  const rawTier = rawBody && typeof rawBody === "object"
+    ? (rawBody as Record<string, unknown>).service_tier
+    : undefined;
+  const canonicalDecision = options.tierDecision?.kind === "set";
+  const callerTierIsForeign = rawTier !== undefined
+    && (typeof rawTier !== "string" || canonicalFastTierMarker(rawTier) === undefined);
+  const dropForeignCallerTier = policy?.capability === true
+    && policy.fastWire?.kind === "service-tier"
+    && policy.fastWire?.foreignCallerTiers === "drop"
+    && callerTierIsForeign;
+  if (policy && policy.capability !== false && canonicalDecision) return;
+  if (forwardCallerTier && !dropForeignCallerTier) return;
+  if (rawBody && typeof rawBody === "object") {
+    delete (rawBody as Record<string, unknown>).service_tier;
+  }
+  options.serviceTier = undefined;
+}