@iislee/opencodex 2.11.0 → 2.35.0

package/src/server/responses/collaboration.ts

@@ -2,6 +2,7 @@ import type { Server } from "bun";
 import { bridgeToResponsesSSE, buildResponseJSON, formatErrorResponse, type ResponsesTerminalStatus } from "../../bridge";
 import {
   getConfigPath,
+  loadConfig,
   multiAgentGuidanceEnabled,
   resolveEnvValue,
 } from "../../config";
@@ -10,6 +11,7 @@ import { buildCompactV1Output, COMPACT_PROMPT, decodeCompactionSummary, extractC
 import { FORWARD_HEADERS, sanitizeReasoningInputContent } from "../../adapters/openai-responses";
 import { expandPreviousResponseInput, previousResponseProviderState, rememberResponseState } from "../../responses/state";
 import { routeModel } from "../../router";
+import type { RawEntry } from "../../codex/catalog/parsing";
 import {
   advanceComboAfterFailure,
   comboDefaultEffort,
@@ -26,7 +28,7 @@ import {
 } from "../../combos";
 import { isInjectionDebugEnabled } from "../../lib/debug-settings";
 import { injectionDebugLog } from "../../lib/injection-debug-log";
-import { modelInList, namespacedToolName } from "../../types";
+import { modelInList, namespacedToolName, toolChoiceToolPredicate } from "../../types";
 import type { AdapterEvent, OcxConfig, OcxParsedRequest, OcxProviderConfig, OcxProviderContinuationState, OcxUsage } from "../../types";
 import {
   forceRefreshOAuthAccessSnapshot,
@@ -96,23 +98,37 @@ import {
   sanitizePassthroughHeaders,
 } from "../relay";
 import { hasResponsesItemIdRepair, relaySseWithResponsesItemIdRepair } from "../responses-item-id-repair";
-import type { EffectiveSubagentRoster, SpawnAgentSurface } from "../../codex/catalog";
+import type { EffectiveSubagentModel, EffectiveSubagentRoster, SpawnAgentSurface } from "../../codex/catalog";
 import type { TranslatorBudget } from "../../lib/translator-budget";
 
 
 export function buildToolBridgeMaps(parsed: OcxParsedRequest, budget?: TranslatorBudget): {
-  toolNsMap: Map<string, { namespace: string; name: string }>;
+  toolNsMap: Map<string, { namespace: string; name: string; freeform?: true }>;
+  declaredToolNames: Set<string>;
+  /** Declared parameter schema per request-visible tool name (#1611 integer repair). */
+  toolParameterSchemas: Map<string, Record<string, unknown>>;
   freeformToolNames: Set<string>;
   toolSearchToolNames: Set<string>;
 } {
-  const toolNsMap = new Map<string, { namespace: string; name: string }>();
+  const toolNsMap = new Map<string, { namespace: string; name: string; freeform?: true }>();
+  const declaredToolNames = new Set<string>();
+  const toolParameterSchemas = new Map<string, Record<string, unknown>>();
   const freeformToolNames = new Set<string>();
   const toolSearchToolNames = new Set<string>();
-  for (const t of parsed.context.tools ?? []) {
+  const requestedTools = parsed.context.tools ?? [];
+  const toolAllowed = toolChoiceToolPredicate(parsed.options.toolChoice, requestedTools);
+  const authorizedTools = requestedTools.filter(toolAllowed);
+  for (const t of authorizedTools) {
+    // Upstream output is untrusted: only restore calls for tools the caller authorized.
+    const wireName = namespacedToolName(t.namespace, t.name);
+    budget?.chargeRetained(new TextEncoder().encode(wireName).byteLength, { kind: "retained_collectors" });
+    declaredToolNames.add(wireName);
+    // Retained by reference (the schema is already resident in parsed.context.tools),
+    // so this adds a map entry rather than a copy of every tool's parameters.
+    if (t.parameters && typeof t.parameters === "object") toolParameterSchemas.set(wireName, t.parameters);
     if (t.namespace) {
-      const wireName = namespacedToolName(t.namespace, t.name);
       budget?.chargeRetained(new TextEncoder().encode(JSON.stringify([wireName, t.namespace, t.name])).byteLength, { kind: "retained_collectors" });
-      toolNsMap.set(wireName, { namespace: t.namespace, name: t.name });
+      toolNsMap.set(wireName, { namespace: t.namespace, name: t.name, ...(t.freeform ? { freeform: true } : {}) });
     }
     if (t.freeform) {
       budget?.chargeRetained(new TextEncoder().encode(t.name).byteLength, { kind: "retained_collectors" });
@@ -123,7 +139,30 @@ export function buildToolBridgeMaps(parsed: OcxParsedRequest, budget?: Translato
       toolSearchToolNames.add(t.name);
     }
   }
-  return { toolNsMap, freeformToolNames, toolSearchToolNames };
+  // Some routed providers echo a bare tool_choice selector instead of the flattened catalog
+  // name. Accept only selectors the client actually sent and only when the full request catalog
+  // contains one tool with that logical name.
+  const choice = parsed.options.toolChoice;
+  const bareChoiceNames = new Set(
+    choice && typeof choice === "object"
+      ? ("allowedTools" in choice ? choice.allowedTools : [choice.name])
+      : [],
+  );
+  const bareNameCounts = new Map<string, number>();
+  for (const t of requestedTools) {
+    bareNameCounts.set(t.name, (bareNameCounts.get(t.name) ?? 0) + 1);
+  }
+  for (const t of authorizedTools) {
+    if (!t.namespace || !bareChoiceNames.has(t.name) || bareNameCounts.get(t.name) !== 1 || declaredToolNames.has(t.name)) continue;
+    budget?.chargeRetained(new TextEncoder().encode(t.name).byteLength, { kind: "retained_collectors" });
+    declaredToolNames.add(t.name);
+    budget?.chargeRetained(new TextEncoder().encode(JSON.stringify([t.name, t.namespace, t.name])).byteLength, { kind: "retained_collectors" });
+    toolNsMap.set(t.name, { namespace: t.namespace, name: t.name, ...(t.freeform ? { freeform: true } : {}) });
+    if (t.parameters && typeof t.parameters === "object") {
+      toolParameterSchemas.set(t.name, t.parameters);
+    }
+  }
+  return { toolNsMap, declaredToolNames, toolParameterSchemas, freeformToolNames, toolSearchToolNames };
 }
 
 
@@ -169,6 +208,7 @@ export function collabSurface(parsed: OcxParsedRequest): "v1" | "v2" | null {
 
 export interface MultiAgentGuidanceOptions {
   multiAgentGuidanceEnabled?: boolean;
+  codexAccountNamespace?: string;
   injectionModel?: string;
   injectionEffort?: string;
   subagentModels?: string[];
@@ -183,7 +223,8 @@ export interface MultiAgentGuidanceDeps {
     configuredModels: readonly string[],
     surface: SpawnAgentSurface,
   ) => EffectiveSubagentRoster | Promise<EffectiveSubagentRoster>;
-  collectCatalogState?: () => { state: "fresh" | "stale" | "not_running" | "unknown" };
+  collectCatalogState?: () => { state: "fresh" | "stale" | "not_running" | "unknown" }
+    | Promise<{ state: "fresh" | "stale" | "not_running" | "unknown" }>;
 }
 
 async function defaultCollectCatalogState(): Promise<{ state: "fresh" | "stale" | "not_running" | "unknown" }> {
@@ -193,8 +234,8 @@ async function defaultCollectCatalogState(): Promise<{ state: "fresh" | "stale"
   if (override === "fresh" || override === "stale" || override === "not_running" || override === "unknown") {
     return { state: override };
   }
-  const { collectCodexAppServerCatalogState } = await import("../../codex/app-server-processes");
-  return collectCodexAppServerCatalogState();
+  const { collectCodexAppServerCatalogStateForRequest } = await import("../../codex/app-server-processes");
+  return collectCodexAppServerCatalogStateForRequest();
 }
 
 
@@ -204,7 +245,49 @@ export async function resolveEffectiveSubagentRoster(
   surface: SpawnAgentSurface,
 ): Promise<EffectiveSubagentRoster> {
   const { effectiveSubagentRoster } = await import("../../codex/catalog");
-  return effectiveSubagentRoster(configuredModels, surface);
+  return effectiveSubagentRoster(configuredModels, surface, await freshSubagentCatalogEntries());
+}
+
+/**
+ * The persisted Codex catalog, with native context metadata re-derived from the CURRENT config.
+ *
+ * The subagent roster reads the catalog FILE, which is only as fresh as the last sync. A row
+ * written before the operator widened the native window keeps its old `context_window`, so a
+ * child was planning and compacting against a narrower budget than its parent — measured at
+ * 272,000 x 95% = 258,400 while the request path resolved 922,000 (#2574).
+ *
+ * Re-applying the override is cheap and idempotent: it is the same function the writer uses,
+ * so a fresh catalog is unchanged and a stale one is repaired in memory rather than silently
+ * believed. It does not rewrite the file — the row on disk stays whatever the last sync wrote,
+ * and `ocx sync` remains what refreshes it.
+ */
+async function freshSubagentCatalogEntries(): Promise<RawEntry[]> {
+  const { readCatalog, readCodexCatalogPath, nativeContextLimits } = await import("../../codex/catalog");
+  const { applyNativeOpenAiContextOverride } = await import("../../codex/catalog/parsing");
+  const entries = readCatalog(readCodexCatalogPath())?.models ?? [];
+  if (entries.length === 0) return [];
+  let limits: ReturnType<typeof nativeContextLimits>;
+  try {
+    limits = nativeContextLimits(loadConfig());
+  } catch {
+    // An unreadable config must not cost the caller its roster; serve the file as written.
+    return entries;
+  }
+  return entries.map(entry => {
+    const clone = { ...entry };
+    applyNativeOpenAiContextOverride(clone, limits);
+    return clone;
+  });
+}
+
+/** Reuse one parsed catalog snapshot across every roster projection for this request. */
+async function createRequestScopedSubagentRosterResolver(): Promise<NonNullable<
+  MultiAgentGuidanceDeps["resolveEffectiveSubagentRoster"]
+>> {
+  const { effectiveSubagentRoster } = await import("../../codex/catalog");
+  const catalogEntries = await freshSubagentCatalogEntries();
+  return (configuredModels, surface) =>
+    effectiveSubagentRoster(configuredModels, surface, catalogEntries);
 }
 
 
@@ -218,10 +301,14 @@ export async function multiAgentGuidanceText(
   const {
     injectionModel,
     injectionEffort,
+    codexAccountNamespace,
     subagentModels,
     subagentModelFallback,
     injectionPrompt,
   } = options;
+  const activeAccountNamespace = codexAccountNamespace?.length
+    ? codexAccountNamespace
+    : undefined;
   const surface = collabSurface(parsed);
   if (surface === null) return null;
 
@@ -231,9 +318,24 @@ export async function multiAgentGuidanceText(
     // Codex cannot actually spawn makes spawn_agent reject the override, so
     // suppress positive model claims while the state is stale or unknown.
     const catalogState = await (deps.collectCatalogState ?? defaultCollectCatalogState)();
+    // #1354 / #1395: `collectCodexAppServerCatalogState()` folds every app-server
+    // owned by the current user into ONE global observation, and the inbound
+    // request carries no sender PID or catalog fingerprint. So a stale process A
+    // makes the global state `stale` even when this request came from a fresh
+    // process B, and `unknown` can be reached by a process-enumeration failure
+    // that says nothing about any particular server.
+    //
+    // Emitting "do not set model or reasoning_effort overrides" off that global
+    // observation prohibits options the active `spawn_agent` tool legitimately
+    // advertises, for a request we cannot attribute to the stale process. The
+    // safe behaviour is to withhold OpenCodex's own disk-derived claims —
+    // preferred model, roster, fallback, custom guidance — and stay silent about
+    // overrides, leaving the active tool schema authoritative.
+    //
+    // `fresh` and `not_running` are unchanged: there we can positively describe
+    // the catalog, so the guidance below still applies.
     if (catalogState.state === "stale" || catalogState.state === "unknown") {
-      return "<multi_agent_mode>The model catalog changed after Codex started; do not set "
-        + "model or reasoning_effort overrides until Codex restarts.</multi_agent_mode>";
+      return null;
     }
     // codex-rs supplies the Proactive text on v2; the proxy only adds model-designation
     // guidance, and only when there is something concrete to designate: a configured
@@ -242,15 +344,51 @@ export async function multiAgentGuidanceText(
       ...(subagentModels ?? []),
       ...(injectionModel ? [injectionModel] : []),
     ];
-    const resolveRoster = deps.resolveEffectiveSubagentRoster ?? resolveEffectiveSubagentRoster;
+    const resolveRoster = deps.resolveEffectiveSubagentRoster
+      ?? await createRequestScopedSubagentRosterResolver();
     const effective = await resolveRoster(configuredForGuidance, "v2");
-    const rosterModels = effective.advertised.filter(candidate =>
-      (subagentModels ?? []).some(model => slugsEquivalent(model, candidate.model))
-    );
+    // Resolve the roster and preferred roles independently so a bare native can project onto its
+    // generated account rows without making an unrelated provider/gpt-* row look equivalent.
+    // The intersection keeps both projections inside Codex's one global five-model window.
+    const candidateModels = new Set(effective.candidates.map(candidate => candidate.model));
+    const withinCandidateWindow = (candidate: EffectiveSubagentModel): boolean =>
+      candidateModels.has(candidate.model);
+    const configuredSubagents = subagentModels ?? [];
+    const subagentEffective = configuredSubagents.length > 0
+      ? injectionModel
+        ? await resolveRoster(configuredSubagents, "v2")
+        : effective
+      : undefined;
+    const preferredEffective = injectionModel
+      ? configuredSubagents.length > 0
+        ? await resolveRoster([injectionModel], "v2")
+        : effective
+      : undefined;
+    const explicitlyConfigured = (candidate: EffectiveSubagentModel): boolean =>
+      configuredSubagents.some(model =>
+        model.includes("/") && slugsEquivalent(model, candidate.model)
+      );
+    const allowedForCurrentRoute = (candidate: EffectiveSubagentModel): boolean =>
+      explicitlyConfigured(candidate)
+      || !candidate.model.includes("/")
+      || (activeAccountNamespace !== undefined
+        && candidate.model.startsWith(`${activeAccountNamespace}/`));
+    const rosterModels = (subagentEffective?.advertised ?? [])
+      .filter(withinCandidateWindow)
+      .filter(allowedForCurrentRoute);
     const roster = subagentRosterText(rosterModels);
-    const preferred = injectionModel
-      ? effective.candidates.find(candidate => slugsEquivalent(injectionModel, candidate.model))
+    const preferredCandidates = (preferredEffective?.advertised ?? []).filter(withinCandidateWindow);
+    const soleBarePreferred = preferredCandidates.length === 1
+      && !preferredCandidates[0]!.model.includes("/")
+      ? preferredCandidates[0]
       : undefined;
+    const preferred = injectionModel?.includes("/")
+      ? preferredCandidates[0]
+      : activeAccountNamespace
+        ? preferredCandidates.find(candidate =>
+          candidate.model.startsWith(`${activeAccountNamespace}/`)
+        ) ?? soleBarePreferred
+        : soleBarePreferred;
 
     if (isInjectionDebugEnabled() && effective.excluded.length > 0) {
       injectionDebugLog(`[opencodex] multi-agent guidance excluded: ${effective.excluded
@@ -260,7 +398,11 @@ export async function multiAgentGuidanceText(
     const fallbackGuidance = subagentFallbackGuidanceText({ subagentModelFallback } as OcxConfig);
     if (!injectionModel && roster === "" && fallbackGuidance === "") return null;
     if (injectionPrompt) {
-      return `<multi_agent_mode>${applyInjectionPlaceholders(injectionPrompt, injectionModel, injectionEffort, roster, fallbackGuidance)}</multi_agent_mode>`;
+      // Bare ids must resolve to a unique/current-route candidate. Preserve the legacy raw
+      // fallback only for explicit routed/account-qualified ids.
+      const promptModel = preferred?.model
+        ?? (injectionModel?.includes("/") ? injectionModel : undefined);
+      return `<multi_agent_mode>${applyInjectionPlaceholders(injectionPrompt, promptModel, injectionEffort, roster, fallbackGuidance)}</multi_agent_mode>`;
     }
     if (!preferred && roster === "" && fallbackGuidance === "") return null;
     let text = "When the active spawn_agent tool supports optional \"model\" or \"reasoning_effort\" overrides, "
@@ -323,32 +465,93 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
-function isGeneratedDeveloperItem(item: unknown, text: string): boolean {
-  if (!isRecord(item) || item.type !== "message" || item.role !== "developer") return false;
-  if (!Array.isArray(item.content) || item.content.length !== 1) return false;
+function generatedDeveloperText(item: unknown): string | undefined {
+  if (!isRecord(item) || item.type !== "message" || item.role !== "developer") return undefined;
+  if (!Array.isArray(item.content) || item.content.length !== 1) return undefined;
   const [part] = item.content;
-  return isRecord(part) && part.type === "input_text" && part.text === text;
+  return isRecord(part) && part.type === "input_text" && typeof part.text === "string"
+    ? part.text
+    : undefined;
+}
+
+function isGeneratedDeveloperItem(item: unknown, text: string): boolean {
+  return generatedDeveloperText(item) === text;
+}
+
+function isDeveloperPrefixItem(item: unknown): boolean {
+  if (!isRecord(item)) return false;
+  if (item.type === "additional_tools") return item.role === "developer";
+  const type = item.type ?? (typeof item.role === "string" ? "message" : undefined);
+  return type === "message" && (item.role === "system" || item.role === "developer");
+}
+
+function leadingDeveloperPrefixLength(items: readonly unknown[]): number {
+  let index = 0;
+  while (index < items.length && isDeveloperPrefixItem(items[index])) index += 1;
+  return index;
+}
+
+function isConversationalItem(item: unknown): boolean {
+  if (!isRecord(item)) return false;
+  if (item.type === "agent_message") return true;
+  const type = item.type ?? (typeof item.role === "string" ? "message" : undefined);
+  return type === "message" && (item.role === "user" || item.role === "assistant");
+}
+
+function statefulRawInsertionIndex(items: readonly unknown[], replayPrefixLen: number): number {
+  for (let index = replayPrefixLen; index < items.length; index += 1) {
+    if (isConversationalItem(items[index])) return index;
+  }
+  const last = items[items.length - 1];
+  return isRecord(last) && last.type === "compaction_trigger"
+    ? items.length - 1
+    : items.length;
 }
 
 export function injectDeveloperMessage(parsed: OcxParsedRequest, text: string): void {
   const raw = parsed._rawBody as { input?: unknown } | undefined;
+  const rawInput = raw && Array.isArray(raw.input) ? raw.input : undefined;
+  const replayPrefixLen = rawInput
+    ? Math.min(parsed._replayPrefixLen ?? 0, rawInput.length)
+    : 0;
   const devItem = { type: "message", role: "developer", content: [{ type: "input_text", text }] };
-  if (raw && Array.isArray(raw.input)) {
-    const replayPrefixLen = Math.min(parsed._replayPrefixLen ?? 0, raw.input.length);
-    if (raw.input.slice(0, replayPrefixLen).some(item => isGeneratedDeveloperItem(item, text))) {
+  if (rawInput) {
+    const replayPrefix = rawInput.slice(0, replayPrefixLen);
+    const taggedGuidance = text.startsWith("<multi_agent_mode>") && text.endsWith("</multi_agent_mode>");
+    const lastTaggedGuidance = taggedGuidance
+      ? replayPrefix.map(generatedDeveloperText)
+        .filter(item => item?.startsWith("<multi_agent_mode>") && item.endsWith("</multi_agent_mode>"))
+        .at(-1)
+      : undefined;
+    if (taggedGuidance ? lastTaggedGuidance === text : replayPrefix.some(item => isGeneratedDeveloperItem(item, text))) {
       return;
     }
   }
 
-  parsed.context.messages.push({ role: "developer", content: text, timestamp: Date.now() });
-  if (raw && Array.isArray(raw.input)) {
-    // compaction_trigger must remain the final input item (codex-rs + ChatGPT backend both
-    // validate this). Insert the developer message BEFORE the trigger when present.
-    const last = raw.input[raw.input.length - 1];
-    if (last && typeof last === "object" && (last as { type?: string }).type === "compaction_trigger") {
-      raw.input.splice(raw.input.length - 1, 0, devItem);
+  const statefulContinuation = parsed.previousResponseId !== undefined;
+  const message = { role: "developer" as const, content: text, timestamp: Date.now() };
+  const statefulRawIndex = statefulContinuation && rawInput
+    ? statefulRawInsertionIndex(rawInput, replayPrefixLen)
+    : undefined;
+
+  // A previous_response_id delta can begin with tool/protocol items. Keep those first, then place
+  // changed guidance before the current conversation. Stateless requests keep guidance in the prefix.
+  if (statefulContinuation) {
+    const index = Math.min(
+      parsed._continuationConversationMessageIndex ?? parsed.context.messages.length,
+      parsed.context.messages.length,
+    );
+    parsed.context.messages.splice(index, 0, message);
+  } else {
+    const prefixLen = parsed.context.messages.findIndex(item => item.role !== "developer");
+    parsed.context.messages.splice(prefixLen < 0 ? parsed.context.messages.length : prefixLen, 0, message);
+  }
+
+  if (rawInput) {
+    if (statefulContinuation) {
+      rawInput.splice(statefulRawIndex!, 0, devItem);
     } else {
-      raw.input.push(devItem);
+      rawInput.splice(leadingDeveloperPrefixLength(rawInput), 0, devItem);
     }
   }
 }

package/src/server/responses/combo-stream-preflight.ts

@@ -0,0 +1,178 @@
+import type { ResponsesTerminalStatus } from "../../bridge";
+import type { RequestLogContext } from "../request-log";
+import { createSseInspector } from "../relay";
+import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer";
+
+const COMBO_STREAM_PREFLIGHT_MAX_BYTES = MAX_CLIENT_SSE_FRAME_BYTES;
+// Keep retained object count proportional to the same byte budget used by the
+// shared SSE framer. Tiny or empty upstream reads must not bypass the byte cap.
+const COMBO_STREAM_PREFLIGHT_MAX_CHUNKS = Math.max(
+  1,
+  Math.ceil(COMBO_STREAM_PREFLIGHT_MAX_BYTES / 1024),
+);
+
+const PRE_OUTPUT_CONTROL_EVENTS = new Set([
+  "response.created",
+  "response.in_progress",
+  "response.queued",
+  "response.heartbeat",
+]);
+
+const TERMINAL_EVENTS = new Set([
+  "response.completed",
+  "response.failed",
+  "response.incomplete",
+]);
+
+/**
+ * Decide when replaying the request on another combo target would risk duplicating
+ * client-visible output or a tool-side effect. Unknown event types commit the child
+ * conservatively; only the small Responses lifecycle preamble remains replayable.
+ */
+export function comboStreamPayloadCommitsOutput(payload: unknown): boolean {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return true;
+  const type = (payload as { type?: unknown }).type;
+  if (typeof type !== "string") return true;
+  return !PRE_OUTPUT_CONTROL_EVENTS.has(type) && !TERMINAL_EVENTS.has(type);
+}
+
+function replayBufferedResponse(
+  response: Response,
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  buffered: Uint8Array[],
+): Response {
+  let index = 0;
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      if (index < buffered.length) {
+        controller.enqueue(buffered[index++]!);
+        return;
+      }
+      try {
+        const next = await reader.read();
+        if (next.done) controller.close();
+        else controller.enqueue(next.value);
+      } catch (error) {
+        try { controller.error(error); } catch { /* consumer already closed */ }
+      }
+    },
+    cancel(reason) {
+      reader.cancel(reason).catch(() => undefined);
+    },
+  });
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+function failedTerminalResponse(
+  response: Response,
+  terminalPayload: Record<string, unknown>,
+  logCtx: RequestLogContext,
+): Response {
+  const nested = terminalPayload.response;
+  const terminalResponse = nested && typeof nested === "object" && !Array.isArray(nested)
+    ? nested as Record<string, unknown>
+    : {};
+  const nestedError = terminalResponse.error;
+  const error = nestedError && typeof nestedError === "object" && !Array.isArray(nestedError)
+    ? nestedError as Record<string, unknown>
+    : {
+      type: "upstream_error",
+      code: "upstream_server_error",
+      message: logCtx.upstreamError ?? "Provider stream failed before producing output",
+    };
+  const headers = new Headers(response.headers);
+  headers.set("content-type", "application/json");
+  headers.delete("content-length");
+  headers.delete("content-encoding");
+  const usage = terminalResponse.usage;
+  return new Response(JSON.stringify({
+    error,
+    // The combo classifier needs only the error and optional usage. Do not carry
+    // response ids, provider metadata, or future terminal fields into the client
+    // error envelope merely because they shared the terminal snapshot.
+    response: {
+      error,
+      ...(usage && typeof usage === "object" && !Array.isArray(usage) ? { usage } : {}),
+    },
+  }), {
+    status: logCtx.terminalHttpStatus ?? 502,
+    headers,
+  });
+}
+
+export type ComboStreamPreflightResult =
+  | { kind: "accepted"; response: Response }
+  | { kind: "failed"; response: Response };
+
+/**
+ * Buffer a combo child's downstream SSE only until the request becomes unsafe to
+ * replay or reaches a terminal. This owns exactly one body reader. The aggregate
+ * buffer is capped by bytes and retained chunks; hitting either cap commits the
+ * current target instead of growing memory or guessing that replay is safe.
+ */
+export async function preflightComboStreamResponse(
+  response: Response,
+  logCtx: RequestLogContext,
+): Promise<ComboStreamPreflightResult> {
+  const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+  if (!response.ok || !response.body || !contentType.includes("text/event-stream")) {
+    return { kind: "accepted", response };
+  }
+
+  const reader = response.body.getReader();
+  const buffered: Uint8Array[] = [];
+  let bufferedBytes = 0;
+  let outputCommitted = false;
+  let terminalStatus: ResponsesTerminalStatus | undefined;
+  let failedPayload: Record<string, unknown> | undefined;
+  const inspector = createSseInspector({
+    logCtx,
+    onParsedPayload: payload => {
+      if (comboStreamPayloadCommitsOutput(payload)) outputCommitted = true;
+      if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+      if ((payload as { type?: unknown }).type === "response.failed") {
+        failedPayload = payload as Record<string, unknown>;
+      }
+    },
+    onTerminal: status => { terminalStatus = status; },
+  });
+
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) {
+        inspector.finish();
+      } else {
+        if (bufferedBytes + next.value.byteLength > COMBO_STREAM_PREFLIGHT_MAX_BYTES) {
+          // Keep the cap about memory the preflight allocates. The upstream chunk already exists;
+          // copying it before committing would transiently exceed the boundary for no
+          // replay benefit. Preserve it unsliced behind the already-bounded prefix.
+          return {
+            kind: "accepted",
+            response: replayBufferedResponse(response, reader, [...buffered, next.value]),
+          };
+        }
+        const retained = next.value.slice();
+        buffered.push(retained);
+        bufferedBytes += retained.byteLength;
+        inspector.feed(retained);
+      }
+
+      if (terminalStatus === "failed" && !outputCommitted && failedPayload) {
+        await reader.cancel("retrying zero-output combo stream failure").catch(() => undefined);
+        return { kind: "failed", response: failedTerminalResponse(response, failedPayload, logCtx) };
+      }
+      if (next.done || terminalStatus !== undefined || outputCommitted
+        || bufferedBytes >= COMBO_STREAM_PREFLIGHT_MAX_BYTES
+        || buffered.length >= COMBO_STREAM_PREFLIGHT_MAX_CHUNKS) {
+        return { kind: "accepted", response: replayBufferedResponse(response, reader, buffered) };
+      }
+    }
+  } finally {
+    inspector.dispose();
+  }
+}