@bitkyc08/opencodex 2.26.0 → 2.28.0

package/src/server/responses/core.ts

@@ -109,6 +109,12 @@ import {
   stripCodexRuntimeProviderFields,
   type CodexAuthContext,
 } from "../../codex/auth-context";
+import {
+  entitledCodexAccountIdsForModel,
+  invalidateCodexModelEntitlementsForAccount,
+  resolveCodexModelEntitlements,
+} from "../../codex/model-entitlements";
+import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "../../codex/catalog/native-models";
 import {
   computeQuotaCooldown,
   formatCodexProviderForLog,
@@ -267,6 +273,8 @@ import {
 } from "../sse-payload-rewrite";
 import { restoreRoutedCustomCallsInJson } from "../../responses/custom-tool-compat";
 import { createRoutedCustomToolRestoreBlockRewrite } from "../responses-custom-tool-repair";
+import { restoreRoutedToolSearchCallsInJson } from "../../responses/tool-search-compat";
+import { createRoutedToolSearchRestoreBlockRewrite } from "../responses-tool-search-repair";
 import {
   collectDeclaredWireToolNames,
   createUndeclaredToolCallGuardBlockRewrite,
@@ -307,7 +315,7 @@ export function sidecarOutcomeRecorder(
 
 
 
-import { isShadowSourceModel, shouldInterceptShadowCall } from "../../lib/shadow-call";
+import { isShadowSourceModel, shadowSourceModelPrefix, shouldInterceptShadowCall } from "../../lib/shadow-call";
 
 export { DEFAULT_SHADOW_SOURCE_MODELS, isShadowSourceModel, shadowSourceModels } from "../../lib/shadow-call";
 
@@ -530,6 +538,39 @@ type CodexPoolAccountRetryResult =
     authCtx: Extract<CodexAuthContext, { kind: "pool" | "main-pool" }>;
   };
 
+const CODEX_ACCOUNT_GATED_CANONICAL_WIRE_MODELS: ReadonlyMap<string, string> = new Map([
+  // The authenticated catalog currently advertises Daybreak Blue, while successful responses
+  // identify the serving model as gpt-5.6-sol. Sending the selector itself is shard-dependent:
+  // live traffic can receive the exact unsupported-model 400 repeatedly from the same entitled
+  // account. Keep Daybreak as the admission/catalog identity, but use the stable serving id on
+  // the credential-bearing wire after entitlement selection has completed.
+  ["gpt-daybreak-blue-latest", "gpt-5.6-sol"],
+]);
+
+export function codexAccountGatedCanonicalWireModel(modelId: string): string | undefined {
+  const exact = CODEX_ACCOUNT_GATED_CANONICAL_WIRE_MODELS.get(modelId);
+  if (exact) return exact;
+  for (const [selector, wireModel] of CODEX_ACCOUNT_GATED_CANONICAL_WIRE_MODELS) {
+    if (slugsEquivalent(modelId, selector)) return wireModel;
+  }
+  return undefined;
+}
+
+function applyCodexAccountGatedWireNormalization(parsed: OcxParsedRequest, route: RouteResult): void {
+  if (!isCanonicalOpenAiForwardProvider(route.provider)) return;
+  const wireModel = codexAccountGatedCanonicalWireModel(route.modelId);
+  if (!wireModel) return;
+
+  parsed.modelId = wireModel;
+  if (!parsed._rawBody || typeof parsed._rawBody !== "object") return;
+  const raw = parsed._rawBody as Record<string, unknown>;
+  raw.model = wireModel;
+  // Daybreak's authenticated catalog does not advertise retention support, and the upstream
+  // rejects this optional Codex hint before model execution. Removing it preserves request
+  // semantics while avoiding an otherwise terminal pre-stream 400.
+  delete raw.prompt_cache_retention;
+}
+
 /**
  * Workspace-denial evidence for a 403, read from the upstream body.
  *
@@ -580,22 +621,32 @@ async function retryCodexPoolOnAlternateAccount(
     req, config, route, parsed, logCtx, options, firstAuthCtx, firstResponse,
     outcomeStatus, upstream, connectMs, passthroughEstimate, stream,
   } = args;
-  // Defense in depth: exact account selectors must never reach alternate-account resolution,
-  // even if a future caller forgets to guard this helper.
-  if (firstAuthCtx.fixedAccount) return { kind: "no-alternate" };
   const inboundWire = options.inboundWire ?? "responses";
   let retryAuthCtx: CodexAuthContext | undefined;
+  if (outcomeStatus === 400 && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(route.modelId)) {
+    invalidateCodexModelEntitlementsForAccount(firstAuthCtx.accountId);
+    const refreshed = await resolveCodexModelEntitlements(config);
+    if (entitledCodexAccountIdsForModel(refreshed, route.modelId)?.has(firstAuthCtx.accountId)) {
+      // The authenticated roster still grants this exact model. Retry on the same account:
+      // upstream shards can briefly disagree during a gated-model rollout, but a pre-stream 400
+      // proves no output was committed and keeps this replay bounded.
+      retryAuthCtx = firstAuthCtx;
+    }
+  }
+  // Exact account selectors may retry the same confirmed account above, but must never resolve
+  // an alternate. Quota failures and a refreshed entitlement miss remain terminal.
+  if (!retryAuthCtx && firstAuthCtx.fixedAccount) return { kind: "no-alternate" };
   try {
-    retryAuthCtx = await resolveCodexAuthContext(
-      req.headers,
-      config,
-      "pool",
-      {
-        excludeAccountId: firstAuthCtx.accountId,
-        modelId: route.modelId,
-        beginCodexAccountSelection: codexAccountSelectionForTurn(options.turnAdmissionLease),
-      },
-    );
+    retryAuthCtx ??= await resolveCodexAuthContext(
+        req.headers,
+        config,
+        "pool",
+        {
+          excludeAccountId: firstAuthCtx.accountId,
+          modelId: route.modelId,
+          beginCodexAccountSelection: codexAccountSelectionForTurn(options.turnAdmissionLease),
+        },
+      );
   } catch (error) {
     if (
       !(error instanceof CodexPoolAuthenticationError)
@@ -677,27 +728,50 @@ async function retryCodexPoolOnAlternateAccount(
     logCtx.accountLogLabel,
   );
 
-  noteAttemptSend(logCtx.activeAttempt, passthroughEstimate);
+  const retrySameConfirmedAccount = outcomeStatus === 400
+    && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(route.modelId)
+    && retryAuthCtx.accountId === firstAuthCtx.accountId;
+  // Live Daybreak traffic has produced long runs of unsupported-model 400s from different
+  // upstream shards even while the authenticated roster continues to grant the model. Permit
+  // seven additional same-account sends (eight total including the original), re-checking the
+  // exact allow-listed body and fresh entitlement before every later send. Alternate-account and
+  // quota recovery retain their historical one-send bound.
+  const maxRetrySends = retrySameConfirmedAccount ? 7 : 1;
+  let retrySendCount = 0;
   let upstreamResponse: Response;
   try {
-    upstreamResponse = await fetchWithHeaderTimeout(
-      request.url,
-      {
-        method: request.method,
-        headers: request.headers,
-        body: request.body,
-      },
-      upstream.signal,
-      connectMs,
-      stream,
-      providerFetch(route.provider, options.codexWsRuntimeIdentity, {
-        providerName: route.providerName,
-        modelId: route.modelId,
-      }),
-      // Credential-bearing forward send: never follow a redirect into a
-      // dead-host rejection after the credential was seen (#914).
-      route.provider.authMode === "forward",
-    );
+    while (true) {
+      noteAttemptSend(logCtx.activeAttempt, passthroughEstimate);
+      upstreamResponse = await fetchWithHeaderTimeout(
+        request.url,
+        {
+          method: request.method,
+          headers: request.headers,
+          body: request.body,
+        },
+        upstream.signal,
+        connectMs,
+        stream,
+        providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+          providerName: route.providerName,
+          modelId: route.modelId,
+        }),
+        // Credential-bearing forward send: never follow a redirect into a
+        // dead-host rejection after the credential was seen (#914).
+        route.provider.authMode === "forward",
+      );
+      retrySendCount += 1;
+      if (!retrySameConfirmedAccount || retrySendCount >= maxRetrySends) break;
+      if (!await shouldRetryCodexPoolAccountModel400(
+        upstreamResponse,
+        route.modelId,
+        options.abortSignal,
+      )) break;
+      invalidateCodexModelEntitlementsForAccount(retryAuthCtx.accountId);
+      const refreshed = await resolveCodexModelEntitlements(config);
+      if (!entitledCodexAccountIdsForModel(refreshed, route.modelId)?.has(retryAuthCtx.accountId)) break;
+      await upstreamResponse.body?.cancel().catch(() => undefined);
+    }
   } catch (error) {
     // Attribute the transport failure to the alternate account (already selected).
     return { kind: "transport", error, authCtx: retryAuthCtx };
@@ -1085,7 +1159,25 @@ async function resolveResponsesCodexAuth(
     // Refusing it here is what made the codex-cli `env_key` contract unusable against Direct.
     // Admitting it is only safe because the stored main credential is substituted below, so
     // the admission secret still never leaves this process.
-    const substituteMainCredential = options.admission?.source === "bearer";
+    //
+    // #2132: substitution answers "does THIS ROUTE need our stored ChatGPT credential", not
+    // "how did the caller authenticate". Only a native Codex route reaches the ChatGPT backend
+    // and can consume that credential; a key-authenticated routed provider carries its own and
+    // never touches it. Keying on the caller alone made an install that deliberately never
+    // logged into ChatGPT fail every routed request with "No usable Codex main credential".
+    //
+    // But ask that question the way the ADAPTER asks it. `codexAccountMode` is derived from the
+    // provider NAME (`providerCodexAccountMode`), while the passthrough adapter decides whether
+    // to forward caller credentials from the TRANSPORT — adapter, auth mode, and base URL
+    // (`isCanonicalOpenAiForwardProvider`). A row the operator named anything other than
+    // `openai`, pointed at the canonical ChatGPT backend with `authMode: "forward"`, satisfies
+    // the adapter's test and fails this one, so substitution was skipped and the adapter then
+    // forwarded our own admission secret upstream. Two predicates answering one question is the
+    // bug; the transport is the authority, because the transport is what actually carries the
+    // header. A key-authenticated routed provider is still not canonical-forward, so #2132's
+    // no-ChatGPT-login install keeps working.
+    const substituteMainCredential = options.admission?.source === "bearer"
+      && (route.codexAccountMode !== undefined || isCanonicalOpenAiForwardProvider(route.provider));
     if (route.codexAccountMode === "direct" && !substituteMainCredential) {
       validateForwardAdmissionCredential(req.headers, config);
     }
@@ -1094,6 +1186,7 @@ async function resolveResponsesCodexAuth(
       authCtx = await resolveCodexAuthContext(req.headers, config, route.codexAccountMode, {
         accountId: route.codexAccountId,
         modelId: route.modelId,
+        substituteMainCredentialForDirect: substituteMainCredential,
         beginCodexAccountSelection: codexAccountSelectionForTurn(options.turnAdmissionLease),
       });
       options.onCodexAuthContextResolved?.(authCtx);
@@ -1238,6 +1331,7 @@ async function applyFinalRouteRequestNormalization(args: {
     route.modelId,
     route.providerName,
     inboundWire,
+    config.providers[route.providerName],
   );
   const modelServiceTierSupport = serviceTierSupportFromPolicy(fastPolicy);
   const callerTier = parsed.options.serviceTier;
@@ -1837,7 +1931,14 @@ async function handleResponsesInner(
     if (parsed._rawBody && typeof parsed._rawBody === "object") {
       (parsed._rawBody as Record<string, unknown>).reasoning = { effort: "low" };
     }
-    (logCtx as unknown as Record<string, unknown>).shadowCallRewrittenFrom = _sciOriginal;
+    // Record the operator-configured prefix that matched, NOT the caller's raw model string.
+    // Matching is by prefix, so a caller can append arbitrary text and still intercept; that
+    // raw value would then land in usage.jsonl and /api/logs behind a pattern-based redactor
+    // that does not recognize every credential family. The prefix is a value the operator
+    // configured, so no caller-controlled string is persisted.
+    logCtx.shadowCallRewrittenFrom = sanitizeLogMetadataString(
+      shadowSourceModelPrefix(_sciOriginal, _sci.sourceModels),
+    );
     // Helpers must not resume/append into the parent thread's Cursor conversation.
     parsed._cursorIsolateConversation = true;
   }
@@ -2124,6 +2225,7 @@ async function handleResponsesInner(
   }
 
   route.provider = applyCodexAuthContextToProvider(route.provider, authCtx, route.codexAccountMode);
+  applyCodexAccountGatedWireNormalization(parsed, route);
   logCtx.provider = route.codexAccountNamespace
     ? `${route.providerName}-${route.codexAccountNamespace}`
     : formatCodexProviderForLog(route.providerName, codexLogAccountId(authCtx), config);
@@ -2398,6 +2500,7 @@ async function handleResponsesInner(
       ? new Map<string, { namespace: string; name: string }>()
       : imageGenToolCallAliases(toolBridgeMaps.toolNsMap, parsed._rawBody, translatorBudget);
     const routedCustomToolNames = new Set<string>();
+    const routedToolSearchNames = new Set<string>();
     // Local continuation cache for the ChatGPT passthrough. Codex WS turns chain with
     // previous_response_id, ocx converts them to internal HTTP requests, and the ChatGPT Codex
     // REST backend rejects the parameter — the adapter strips it in forward mode, so the ONLY
@@ -2431,6 +2534,12 @@ async function handleResponsesInner(
         if (toolBridgeMaps.freeformToolNames.has(name)) routedCustomToolNames.add(name);
       }
     }
+    for (const name of request.convertedRoutedToolSearchNames ?? []) {
+      // The adapter already keeps this set empty when tool_choice forbids the private search.
+      // Its wire name may be collision-aliased, so comparing it to the caller-facing name here
+      // would incorrectly disable restoration for the exact ambiguous-name case the alias fixes.
+      routedToolSearchNames.add(name);
+    }
     // #1700: the bridged paths refuse a call to a tool the request never declared
     // (`declaredToolNames`, src/bridge.ts). The passthrough had no equivalent, so a routed
     // provider's top-level `apply_patch` — which under Codex code mode exists only as a nested
@@ -2621,6 +2730,98 @@ async function handleResponsesInner(
       request.releaseBodyObservation?.();
     }
 
+    // Native Responses providers return before the generic adapter recovery loop below. Keep
+    // their OAuth contract identical: one pre-stream 401 forces a credential refresh and one
+    // rebuilt replay. xAI's current subscription models use this branch now that their official
+    // Grok CLI catalog declares the Responses backend.
+    if (upstreamResponse.status === 401 && isOAuth401ReplayProvider && sentOAuthSnapshot) {
+      try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }
+      let refreshed: OAuthAccessSnapshot;
+      try {
+        refreshed = await forceRefreshOAuthAccessSnapshot(sentOAuthSnapshot);
+      } catch (err) {
+        upstream.abort();
+        releaseCodexAuthContextProbeLease(authCtx);
+        return formatErrorResponse(401, "authentication_error", publicOAuthAuthenticationErrorMessage(err));
+      }
+      sentOAuthSnapshot = refreshed;
+      replayOAuthCredentialSnapshot = {
+        accountId: refreshed.accountId,
+        generation: refreshed.generation,
+      };
+      if (route.providerName === "kiro") {
+        parsed._kiroAuthContext = { ...(refreshed.kiro ?? {}) };
+      }
+      const refreshedProvider = resolveProviderTransport(
+        route.providerName,
+        { ...route.provider, apiKey: refreshed.accessToken },
+        parsed.options.promptCacheKey,
+        route.providerName === "github-copilot" ? getOAuthCredentialApiBaseUrl(route.providerName) : undefined,
+      );
+      route.provider = refreshedProvider;
+      const refreshedAdapter = resolveAdapter(
+        resolveWireProtocolOverride(route.providerName, route.modelId, refreshedProvider, inboundWire),
+        config.cacheRetention,
+      );
+      if (!("passthrough" in refreshedAdapter) || !refreshedAdapter.passthrough) {
+        upstream.abort();
+        return formatErrorResponse(502, "upstream_error", "OAuth refresh changed the provider wire unexpectedly");
+      }
+      bindRouteReasoningReplayScope({
+        parsed,
+        providerName: route.providerName,
+        provider: refreshedProvider,
+        adapterName: refreshedAdapter.name,
+        oauthCredentialSnapshot: replayOAuthCredentialSnapshot,
+      });
+      logCtx.providerAdapter = refreshedAdapter.name;
+      sealRequestAttemptIdentity(
+        logCtx.activeAttempt,
+        logCtx.provider,
+        refreshedAdapter.name,
+        logCtx.accountLogLabel,
+      );
+      try {
+        request = await refreshedAdapter.buildRequest(parsed, {
+          headers: selectedForwardHeaders,
+          translatorBudget,
+        });
+        recordAdapterReasoning(logCtx, request);
+        recordAdapterTier(logCtx, request);
+      } catch (err) {
+        upstream.abort();
+        if (options.abortSignal?.aborted) return clientCancelledResponse();
+        const msg = err instanceof Error ? err.message : String(err);
+        return formatErrorResponse(400, "invalid_request_error", redactSecretString(msg));
+      }
+      try {
+        upstreamResponse = await fetchWithTransientRetry(
+          recovery => {
+            noteAttemptSend(logCtx.activeAttempt, passthroughEstimate, recovery ?? "oauth-401");
+            return fetchWithHeaderTimeout(request.url, applyUpstreamRecoveryInit({
+              method: request.method,
+              headers: request.headers,
+              body: request.body,
+            }, recovery), upstream.signal, connectMs, parsed.stream,
+              providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+                providerName: route.providerName,
+                modelId: route.modelId,
+              }),
+              route.provider.authMode === "forward")
+              .then(res => {
+                settleObservedHostResponse();
+                return res;
+              });
+          },
+          { abortSignal: upstream.signal, label: safeHostLabel(request.url) },
+        );
+      } catch (err) {
+        return transportFailureResponse(err);
+      } finally {
+        request.releaseBodyObservation?.();
+      }
+    }
+
     // Same-target 429 wait-and-retry (opt-in `retryOn429`) for key-auth providers on the
     // passthrough wire. This branch returns before the recovery loop below, so Responses-shaped
     // key-auth gateways (e.g. the built-in DeepSeek preset) would otherwise surface 429
@@ -2683,7 +2884,7 @@ async function handleResponsesInner(
       }
     }
 
-    if (usesCodexForwardPoolAuth(authCtx, route.provider) && !authCtx.fixedAccount) {
+    if (usesCodexForwardPoolAuth(authCtx, route.provider)) {
       let poolRetryOutcome: number | undefined;
       if (await shouldRetryCodexPoolAccountModel400(
         upstreamResponse,
@@ -2691,7 +2892,7 @@ async function handleResponsesInner(
         options.abortSignal,
       )) {
         poolRetryOutcome = 400;
-      } else if (shouldRetryCodexPoolAccountQuota(upstreamResponse)) {
+      } else if (!authCtx.fixedAccount && shouldRetryCodexPoolAccountQuota(upstreamResponse)) {
         // Pre-stream only: once SSE has begun, mid-stream quota stays terminal.
         poolRetryOutcome = upstreamResponse.status;
       }
@@ -2893,6 +3094,9 @@ async function handleResponsesInner(
         routedCustomToolNames.size > 0
           ? createRoutedCustomToolRestoreBlockRewrite(routedCustomToolNames, translatorBudget)
           : undefined,
+        routedToolSearchNames.size > 0
+          ? createRoutedToolSearchRestoreBlockRewrite(routedToolSearchNames, translatorBudget)
+          : undefined,
         githubCopilotRepairEnabled
           ? createGithubCopilotResponsesBlockRewrite(translatorBudget)
           : undefined,
@@ -3090,9 +3294,13 @@ async function handleResponsesInner(
           restoreImageGenCallsInJson(text, imageGenCallAliases),
           routedCustomToolNames,
         );
+        const restoredToolSearch = restoreRoutedToolSearchCallsInJson(
+          restored,
+          routedToolSearchNames,
+        );
         const repaired = hasResponsesSnapshotRepair(route.provider.responsesSnapshotRepair)
-          ? repairResponsesSnapshotJson(restored, outboundRequestBody)
-          : restored;
+          ? repairResponsesSnapshotJson(restoredToolSearch, outboundRequestBody)
+          : restoredToolSearch;
         const modelRewritten = parsed._responseModelId !== undefined && parsed._responseModelId !== parsed.modelId
           ? rewriteResponsesModelJson(backfillResponsesFieldsJson(repaired), parsed._responseModelId)
           : backfillResponsesFieldsJson(repaired);
@@ -4348,9 +4556,9 @@ async function handleResponsesInner(
       const detachContinuationBodyGuard = cancelBodyOnAbort(response.body, upstream.signal);
       try {
         if (nextParsed.stream) {
-          yield* activeAdapter.parseStream(response, translatorBudget);
+          yield* activeAdapter.parseStream(response, translatorBudget, logCtx.activeTierMetadata);
         } else if (activeAdapter.parseResponse) {
-          yield* await activeAdapter.parseResponse(response, translatorBudget);
+          yield* await activeAdapter.parseResponse(response, translatorBudget, logCtx.activeTierMetadata);
         } else {
           yield { type: "error", message: "Provider continuation does not support response parsing" };
         }
@@ -4380,7 +4588,11 @@ async function handleResponsesInner(
   };
 
   if (parsed.stream) {
-    const initialEventStream = activeAdapter.parseStream(upstreamResponse, translatorBudget);
+    const initialEventStream = activeAdapter.parseStream(
+      upstreamResponse,
+      translatorBudget,
+      logCtx.activeTierMetadata,
+    );
     const eventStream = terminalGuardEnabled
       ? guardTerminalEventStream({
           parsed,
@@ -4448,7 +4660,11 @@ async function handleResponsesInner(
   if (activeAdapter.parseResponse) {
     let events: AdapterEvent[];
     try {
-      const initialEvents = await activeAdapter.parseResponse(upstreamResponse, translatorBudget);
+      const initialEvents = await activeAdapter.parseResponse(
+        upstreamResponse,
+        translatorBudget,
+        logCtx.activeTierMetadata,
+      );
       let guardedEvents: AdapterEvent[];
       if (terminalGuardEnabled) {
         guardedEvents = [];

package/src/server/responses/input-admission.ts

@@ -13,6 +13,7 @@
 import { nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, type NativeContextLimitsInput } from "../../codex/catalog/metadata";
 import { estimateTokens } from "../../lib/token-estimate";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
+import { modelRecordValue } from "../../reasoning-effort";
 import type { OcxContentPart, OcxParsedRequest, OcxProviderConfig } from "../../types";
 
 /**
@@ -133,7 +134,11 @@ export function resolveInputCeiling(
   // config here so this stays pure: no filesystem, no catalog, no registry scan.
   nativeContextCap?: NativeContextLimitsInput,
 ): number | null {
-  const configured = positive(provider.modelContextWindows?.[modelId]) ?? positive(provider.contextWindow);
+  // `modelRecordValue`, not a bare lookup: the catalog resolves these same two maps that
+  // way, so a `gpt-oss` entry covers `gpt-oss:120b`. Reading raw here made the gate fall
+  // back to the provider-wide window and refuse turns the model can plainly hold.
+  const configured = positive(modelRecordValue(provider.modelContextWindows, modelId))
+    ?? positive(provider.contextWindow);
 
   // The canonical `openai` registry entry declares no context fields, so without this the
   // gate would be inert on the default Codex route. All three clauses are load-bearing: a
@@ -156,7 +161,7 @@ export function resolveInputCeiling(
 
   const window = canonicalNativeBare ? native : configured;
   // modelMaxInputTokens is an input-only cap, so it can only tighten the window.
-  const configuredMaxInput = positive(provider.modelMaxInputTokens?.[modelId]);
+  const configuredMaxInput = positive(modelRecordValue(provider.modelMaxInputTokens, modelId));
   const limits = [window, configuredMaxInput, nativeMaxInput].filter((v): v is number => v !== null);
   return limits.length === 0 ? null : Math.min(...limits);
 }

package/src/server/responses/responses-field-backfill.ts

@@ -29,6 +29,67 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+/** Wire prefixes for Responses output item ids, matching OpenAI's id shapes. */
+const ITEM_ID_PREFIXES: Readonly<Record<string, string>> = {
+  message: "msg_",
+  reasoning: "rs_",
+  function_call: "fc_",
+  custom_tool_call: "ctc_",
+  // A routed tool_search lowering is restored to `tool_search_call` without an id, so this
+  // backfill is what names it. The generic `item_` fallback is not merely cosmetic here:
+  // `stripInvalidItemIds` in the Responses adapter deletes any id whose prefix does not match
+  // the type, so an `item_`-named tool_search_call silently loses its id on the NEXT turn and
+  // the client sees an item it cannot correlate. The prefixes here must stay a superset of the
+  // ones that serializer enforces.
+  tool_search_call: "tsc_",
+  web_search_call: "ws_",
+  file_search_call: "fs_",
+  code_interpreter_call: "ci_",
+  computer_call: "cc_",
+  // The Responses wire type is `image_generation_call`; `image_gen_call` is kept only so a
+  // relay that emits the short spelling is not silently demoted to the generic `item_`.
+  image_generation_call: "ig_",
+  image_gen_call: "ig_",
+};
+
+/**
+ * Backfill a required id on an output item when absent. Strict Responses
+ * decoders (e.g. grok-build serde types) fail with "missing field id" when a
+ * message or reasoning item has no id, which some upstream relays omit. The
+ * generated id is deterministic per (type, output index) so it stays stable
+ * across streaming events that reference the same item.
+ */
+function backfillItemId(item: Record<string, unknown>, slot: ItemIdSlot): Record<string, unknown> {
+  if (typeof item.id === "string" && item.id.length > 0) return item;
+  const type = typeof item.type === "string" ? item.type : "";
+  const prefix = Object.prototype.hasOwnProperty.call(ITEM_ID_PREFIXES, type) ? ITEM_ID_PREFIXES[type] : "item_";
+  return { ...item, id: prefix + "ocx_" + (slot.kind === "index" ? String(slot.index) : "fallback_" + slot.ordinal) };
+}
+
+/**
+ * Which namespace a synthesized id comes from.
+ *
+ * Keeping the fallback counter in the SAME numeric namespace as real output indexes only
+ * pushed the collision out of reach rather than removing it: a response whose real index
+ * happened to be 1_000_001 would produce the same id as the first malformed-index fallback,
+ * and a duplicate id is exactly what this backfill exists to prevent. The namespaces are now
+ * lexically disjoint, so no index value can ever collide with a fallback.
+ */
+type ItemIdSlot = { kind: "index"; index: number } | { kind: "fallback"; ordinal: number };
+
+/**
+ * Monotonic ordinal for an event whose `output_index` is absent or malformed.
+ *
+ * Process-global rather than per-response because this module is stateless by design and the
+ * value only has to be unique, not meaningful. It carries its own `fallback_` namespace, so
+ * uniqueness no longer depends on a real index never reaching some arbitrary ceiling.
+ */
+let syntheticItemOrdinal = 0;
+function nextSyntheticItemSlot(): ItemIdSlot {
+  syntheticItemOrdinal += 1;
+  return { kind: "fallback", ordinal: syntheticItemOrdinal };
+}
+
 /**
  * Backfill annotations: [] on an output_text content part if missing.
  * Returns the same object reference if no change is needed.
@@ -58,16 +119,29 @@ function backfillContentArray(content: unknown): unknown {
   return changed ? repaired : content;
 }
 
+/**
+ * Item types that are NOT Responses output items and must be returned byte-for-byte.
+ *
+ * `compaction` is the `/v1/responses/compact` wire format, not a Responses output item. It has
+ * no `id` in that contract, so synthesizing one changes a response body the client compares
+ * exactly. The backfill exists to satisfy strict Responses decoders; a shape those decoders
+ * never see is outside its remit.
+ */
+const NON_RESPONSES_ITEM_TYPES: ReadonlySet<string> = new Set(["compaction"]);
+
 /**
  * Walk an output item and backfill output_text parts in its content.
+ * Also backfills a missing required id on the item itself.
  * Returns the same object reference if nothing changed.
  */
-function backfillOutputItem(item: unknown): unknown {
+function backfillOutputItem(item: unknown, slot: ItemIdSlot): unknown {
   if (!isPlainObject(item)) return item;
+  if (typeof item.type === "string" && NON_RESPONSES_ITEM_TYPES.has(item.type)) return item;
   const content = item.content;
   const repaired = backfillContentArray(content);
-  if (repaired === content) return item;
-  return { ...item, content: repaired };
+  const withId = backfillItemId(item, slot);
+  if (repaired === content && withId === item) return item;
+  return { ...withId, ...(repaired === content ? {} : { content: repaired }) };
 }
 
 /**
@@ -79,9 +153,9 @@ function backfillResponseOutput(response: unknown): unknown {
   const output = response.output;
   if (!Array.isArray(output)) return response;
   let changed = false;
-  const repaired = output.map((item) => {
+  const repaired = output.map((item, idx) => {
     if (!isPlainObject(item)) return item;
-    const next = backfillOutputItem(item);
+    const next = backfillOutputItem(item, { kind: "index", index: idx });
     if (next !== item) changed = true;
     return next;
   });
@@ -100,7 +174,15 @@ function rewriteEvent(event: Record<string, unknown>): Record<string, unknown> {
   // output_item.added / output_item.done: item.content[] -> output_text parts
   if ((type === "response.output_item.added" || type === "response.output_item.done")
     && isPlainObject(event.item)) {
-    const item = backfillOutputItem(event.item);
+    const rawIndex = event.output_index;
+    // A malformed or absent `output_index` must not collapse to 0: two such events would then
+    // both synthesize `msg_ocx_0`, and duplicate ids are the very thing this backfill exists to
+    // prevent. Fall back to a per-process counter so the synthesized id stays unique. Position
+    // is not recoverable in that case, but a unique id is what strict decoders require, and a
+    // well-formed stream still gets the stable index-derived id.
+    const item = typeof rawIndex === "number" && Number.isInteger(rawIndex) && rawIndex >= 0
+      ? backfillOutputItem(event.item, { kind: "index", index: rawIndex })
+      : backfillOutputItem(event.item, nextSyntheticItemSlot());
     if (item !== event.item) {
       next = { ...next, item };
       changed = true;

package/src/server/responses/terminal-guard.ts

@@ -193,6 +193,16 @@ export async function* guardTerminalEventStream(options: GuardedEventStreamOptio
     const seen: AdapterEvent[] = [];
     let terminalSeen = false;
     for await (const event of source) {
+      // A heartbeat is adapter liveness, not turn content: it exists so the bridge watchdog
+      // can tell a buffering adapter from a hung one. Retaining it here would put an
+      // unbounded number of empty markers into `seen`, which feeds both the continuation
+      // analysis and the rebuilt request — and the openai-chat adapter now emits one per
+      // tool-call delta, so a long argument payload alone could grow this array without
+      // limit. The empty-completion guard already passes them through unretained; match it.
+      if (event.type === "heartbeat") {
+        yield event;
+        continue;
+      }
       if (event.type === "done") {
         terminalSeen = true;
         const analysis = (options.adapterName === "anthropic" || options.adapterName === "openai-chat")