UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,288 lines • 66.3 kB
import {
  codexAccountModelRefusal,
  codexAccountModelRefusalPayload,
  envelopeErrorRecord,
  envelopeRecordCode,
  hasConflictingCodexModelRefusalEnvelopes,
  isMalformedResponseFormatRecord,
  isOpenRouterOpaque400EnvelopeRoot,
  isProviderModerationRefusal,
  isProviderIntakeRefusalBody,
  isOpenRouterOpaque400Record,
  type CodexAccountModelRefusal,
} from "../../combos/failover";
import type { ResponsesTerminalStatus } from "../../bridge";
import { comboFailureDecision } from "../../combos";
import { httpStatusFromTerminalError } from "../../lib/errors";
import { hasResponseMediaType } from "../../lib/http-response-semantics";
import type { RequestFailureStage } from "../../lib/request-failure-model";
import type { RequestLogContext } from "../request-log";
import { carryResponseToolOwnership } from "./response-tool-ownership";
import { responsesFrameIsReplayUnsafe } from "./codex-ws-wire";
import { createSseInspector, isNativePassthroughSseResponse } from "../relay";
import { sseDataPayload } from "../sse-payload-rewrite";
import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer";
import { COMBO_DEGENERATE_COMPLETION_CODE, REQUIRED_TOOL_CONTRACT_CODE, responsesCompletionError } from "../../lib/errors";
import { attachComboFailureEvidence, isPausedTurn } from "../../lib/client-error-body";
import { requiredToolReasoningPrelude } from "./combo-required-tool-stream";
import { ProtocolPreOutputEof } from "../../lib/upstream-retry";
import { carryPacedStream, pacedQueuingStrategy } from "../../lib/paced-stream";

const COMBO_STREAM_PREFLIGHT_MAX_BYTES = MAX_CLIENT_SSE_FRAME_BYTES;
// Bound the prelude hold from its first client-visible event, even if upstream goes quiet.
const COMBO_STREAM_PRELUDE_HOLD_MS = 1_000;
const RESET_PREFLIGHT_HEARTBEAT_MS = 15_000;
// 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 PRE_OUTPUT_EVENT_FIELDS = new Set([
  "type", "response", "sequence_number", "replayUnsafe", "error", "last_error",
  "incomplete_details", "status", "output", "item", "delta", "content", "message", "code",
]);

// These are response identity and request-configuration fields, not output carriers.
// Unknown snapshot extensions commit the original instead of guessing whether they hide output.
const PRE_OUTPUT_SNAPSHOT_FIELDS = new Set([
  "id", "object", "created_at", "completed_at", "status", "model", "output", "error", "last_error",
  "incomplete_details", "usage", "background", "instructions", "max_output_tokens", "max_tool_calls",
  "metadata", "parallel_tool_calls", "previous_response_id", "prompt", "prompt_cache_key",
  "prompt_cache_retention", "reasoning", "safety_identifier", "service_tier", "store", "temperature",
  "text", "tool_choice", "tools", "top_p", "top_logprobs", "truncation", "user", "end_turn", "replayUnsafe",
]);

const PRE_OUTPUT_STRING_FIELDS = [
  "id", "object", "model", "prompt_cache_key", "prompt_cache_retention", "safety_identifier",
  "service_tier", "truncation", "user",
] as const;
const PRE_OUTPUT_NUMBER_FIELDS = ["created_at", "max_output_tokens", "max_tool_calls", "temperature", "top_p", "top_logprobs"] as const;

function isRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

function recordWithOnly(value: unknown, fields: readonly string[]): value is Record<string, unknown> {
  return isRecord(value) && Object.keys(value).every(key => fields.includes(key));
}

function safeSnapshotTools(value: unknown, budget: { remaining: number }, depth = 0): boolean {
  if (!Array.isArray(value) || depth > 4) return false;
  return value.every(tool => {
    if (--budget.remaining < 0 || !isRecord(tool)) return false;
    if (tool.type === "function") {
      return recordWithOnly(tool, ["type", "name", "description", "parameters", "strict"])
        && typeof tool.name === "string"
        && (tool.description == null || typeof tool.description === "string")
        && (tool.parameters == null || isRecord(tool.parameters))
        && (tool.strict == null || typeof tool.strict === "boolean");
    }
    if (tool.type === "custom") {
      if (!recordWithOnly(tool, ["type", "name", "description", "format"])
        || typeof tool.name !== "string"
        || (tool.description != null && typeof tool.description !== "string")) return false;
      if (tool.format == null) return true;
      return recordWithOnly(tool.format, ["type", "syntax", "definition"])
        && (tool.format.type === "text" || tool.format.type === "grammar")
        && (tool.format.syntax == null || typeof tool.format.syntax === "string")
        && (tool.format.definition == null || typeof tool.format.definition === "string");
    }
    if (tool.type === "tool_search") {
      return recordWithOnly(tool, ["type", "execution", "description"])
        && tool.execution === "client" && (tool.description == null || typeof tool.description === "string");
    }
    return tool.type === "namespace" && recordWithOnly(tool, ["type", "name", "description", "tools"])
      && typeof tool.name === "string" && (tool.description == null || typeof tool.description === "string")
      && safeSnapshotTools(tool.tools, budget, depth + 1);
  });
}

function safeSnapshotUsage(value: unknown): boolean {
  if (!recordWithOnly(value, ["input_tokens", "output_tokens", "total_tokens", "input_tokens_details", "output_tokens_details"])) return false;
  for (const key of ["input_tokens", "output_tokens", "total_tokens"]) {
    if (value[key] != null && !(typeof value[key] === "number" && Number.isFinite(value[key]) && value[key] >= 0)) return false;
  }
  for (const [key, fields] of [
    ["input_tokens_details", ["cached_tokens"]],
    ["output_tokens_details", ["reasoning_tokens"]],
  ] as const) {
    const detail = value[key];
    if (detail != null && (!recordWithOnly(detail, fields)
      || Object.values(detail).some(count => !(typeof count === "number" && Number.isFinite(count) && count >= 0)))) return false;
  }
  return true;
}

function snapshotMetadataIsSafe(snapshot: Record<string, unknown>): boolean {
  if (PRE_OUTPUT_STRING_FIELDS.some(key => snapshot[key] != null && typeof snapshot[key] !== "string")) return false;
  if (snapshot.object != null && snapshot.object !== "response") return false;
  if (PRE_OUTPUT_NUMBER_FIELDS.some(key => snapshot[key] != null
    && !(typeof snapshot[key] === "number" && Number.isFinite(snapshot[key])))) return false;
  if (snapshot.parallel_tool_calls != null && typeof snapshot.parallel_tool_calls !== "boolean") return false;
  if (snapshot.tools != null && !safeSnapshotTools(snapshot.tools, { remaining: 4096 })) return false;
  if (snapshot.instructions != null && typeof snapshot.instructions !== "string") return false;
  if (snapshot.prompt != null) {
    if (!recordWithOnly(snapshot.prompt, ["id", "version", "variables"])
      || typeof snapshot.prompt.id !== "string"
      || (snapshot.prompt.version != null && typeof snapshot.prompt.version !== "string")
      || (snapshot.prompt.variables != null && (!isRecord(snapshot.prompt.variables)
        || Object.values(snapshot.prompt.variables).some(value => typeof value !== "string")))) return false;
  }
  if (typeof snapshot.tool_choice === "string" && !["none", "auto", "required"].includes(snapshot.tool_choice)) return false;
  if (snapshot.tool_choice != null && typeof snapshot.tool_choice !== "string") {
    if (!recordWithOnly(snapshot.tool_choice, ["type", "name", "namespace", "function"])
      || typeof snapshot.tool_choice.type !== "string"
      || !["function", "custom", "tool_search"].includes(snapshot.tool_choice.type)
      || (snapshot.tool_choice.name != null && typeof snapshot.tool_choice.name !== "string")
      || (snapshot.tool_choice.namespace != null && typeof snapshot.tool_choice.namespace !== "string")) return false;
    const selected = snapshot.tool_choice.function;
    if (selected != null && (!recordWithOnly(selected, ["name"]) || typeof selected.name !== "string")) return false;
  }
  if (snapshot.usage != null && !safeSnapshotUsage(snapshot.usage)) return false;
  if (snapshot.metadata != null && (!isRecord(snapshot.metadata)
    || Object.values(snapshot.metadata).some(value => typeof value !== "string"))) return false;
  if (snapshot.reasoning != null) {
    if (!recordWithOnly(snapshot.reasoning, ["effort", "summary", "generate_summary"])
      || Object.values(snapshot.reasoning).some(value => value != null && typeof value !== "string")) return false;
    if (snapshot.reasoning.effort != null
      && !["none", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(snapshot.reasoning.effort))) return false;
    if ([snapshot.reasoning.summary, snapshot.reasoning.generate_summary].some(value => value != null
      && !["auto", "concise", "detailed"].includes(String(value)))) return false;
  }
  if (snapshot.text != null) {
    if (!recordWithOnly(snapshot.text, ["format", "verbosity"])
      || (snapshot.text.verbosity != null && typeof snapshot.text.verbosity !== "string")) return false;
    const format = snapshot.text.format;
    if (format != null && (!recordWithOnly(format, ["type", "name", "description", "schema", "strict"])
      || typeof format.type !== "string"
      || !["text", "json_object", "json_schema"].includes(format.type)
      || (format.name != null && typeof format.name !== "string")
      || (format.description != null && typeof format.description !== "string")
      || (format.schema != null && !isRecord(format.schema))
      || (format.strict != null && typeof format.strict !== "boolean"))) return false;
  }
  return true;
}

// The Codex WebSocket metadata channel (`codex-ws-metadata.ts`) writes these into the same SSE
// body, typically ahead of `response.created`. They are rebuilt field by field from quota and
// header metadata, so they are neither output nor a terminal. Committing on them made a native
// target that declined before any output (#8107) final for the whole combo. Every other unknown
// type still commits.
const CODEX_METADATA_CONTROL_EVENTS = new Set([
  "codex.rate_limits",
  "codex.response.metadata",
]);

const TERMINAL_EVENTS = new Set([
  "response.completed",
  "response.failed",
  "response.incomplete",
]);

// A failed terminal carrying one of these codes is a contract verdict, not a transient
// upstream failure: another target would spend a request the adapter already refused.
const NON_REPLAYABLE_FAILED_CODES = new Set(["required_tool_not_called"]);

const RETRYABLE_ZERO_OUTPUT_INCOMPLETE_REASONS = new Set([
  "adapter_eof",
  "missing_terminal_event",
  "upstream_stall_timeout",
]);

/** Item-scoped frames that can belong to a commentary-phase message. */
const MESSAGE_CONTENT_EVENTS = new Set([
  "response.content_part.added",
  "response.content_part.done",
  "response.output_text.delta",
  "response.output_text.done",
  "response.output_text.annotation.added",
]);

function recordValue(value: unknown): Record<string, unknown> | undefined {
  return value !== null && typeof value === "object" && !Array.isArray(value)
    ? value as Record<string, unknown>
    : undefined;
}

function hasOnlyPreludeParts(parts: unknown, type: "output_text" | "reasoning_text" | "summary_text"): boolean {
  return parts === undefined || (Array.isArray(parts) && parts.every(part => recordValue(part)?.type === type));
}

function isDegeneratePreludeItem(item: Record<string, unknown>): boolean {
  if (item.type === "reasoning") {
    return hasOnlyPreludeParts(item.content, "reasoning_text") && hasOnlyPreludeParts(item.summary, "summary_text");
  }
  return item.type === "message" && item.phase === "commentary" && hasOnlyPreludeParts(item.content, "output_text");
}

/**
 * Degenerate-completion prelude: reasoning frames and message items explicitly marked
 * `phase: "commentary"` announce work rather than deliver it, so they stay replayable
 * inside the buffer window. `commentaryItemIds` correlates item-scoped content frames
 * (which carry no phase) back to the commentary item that opened them; an unidentified
 * item always commits, so a final answer can never be held by mistake.
 */
function comboStreamDegeneratePrelude(payload: unknown, commentaryItemIds: Set<string>): boolean {
  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
  const event = payload as Record<string, unknown>;
  if (event.type === "response.output_item.added" || event.type === "response.output_item.done") {
    const item = recordValue(event.item);
    if (!item || !isDegeneratePreludeItem(item)) return false;
    if (item.type === "message" && typeof item.id === "string") commentaryItemIds.add(item.id);
    return true;
  }
  if (typeof event.type === "string" && MESSAGE_CONTENT_EVENTS.has(event.type)) {
    if ((event.type === "response.content_part.added" || event.type === "response.content_part.done")
      && recordValue(event.part)?.type !== "output_text") return false;
    return typeof event.item_id === "string" && commentaryItemIds.has(event.item_id);
  }
  return requiredToolReasoningPrelude(payload);
}

function incompleteCarriersVetoReplay(...carriers: Array<Record<string, unknown> | undefined>): boolean {
  return carriers.some(carrier => carrier?.end_turn === false
    || recordValue(carrier?.incomplete_details)?.retryable === false);
}

function classifyIncompleteReplayReason(
  event: Record<string, unknown>,
  response: Record<string, unknown> | undefined,
): "veto" | "output-limit" | "retryable" {
  const reasons = [recordValue(event.incomplete_details)?.reason, recordValue(response?.incomplete_details)?.reason];
  if (reasons.some(reason => reason !== undefined && reason !== "max_output_tokens"
    && (typeof reason !== "string" || !RETRYABLE_ZERO_OUTPUT_INCOMPLETE_REASONS.has(reason)))) return "veto";
  return reasons.includes("max_output_tokens") ? "output-limit" : "retryable";
}

/**
 * A terminal whose entire output is reasoning/commentary prelude delivered nothing the
 * caller can act on: the model announced work and stopped. Verified against the terminal
 * snapshot itself so a final answer or tool call seen only there still commits.
 */
function isDegenerateStreamTerminal(payload: unknown, context?: object): boolean {
  const event = recordValue(payload);
  if (!event || (event.type !== "response.completed" && event.type !== "response.incomplete")) return false;
  const response = recordValue(event.response);
  if (event.error != null || event.last_error != null || response?.error != null || response?.last_error != null) return false;
  // Output limits have a separate zero-output recovery contract. With prelude output they commit.
  if (incompleteCarriersVetoReplay(event, response)
    || classifyIncompleteReplayReason(event, response) !== "retryable"
    || (event.type === "response.incomplete" && isPausedTurn(context))) return false;
  // Both carriers count: an item that exists only at event level is still client-visible
  // output the hop would lose, exactly as retryableZeroOutputTerminal treats it.
  const carriers = [event.output, response?.output].filter(value => value !== undefined);
  if (carriers.length === 0) return false;
  let preludeItems = 0;
  for (const carrier of carriers) {
    if (!Array.isArray(carrier)) return false;
    for (const item of carrier) {
      const record = recordValue(item);
      if (!record) return false;
      if (!isDegeneratePreludeItem(record)) return false;
      preludeItems++;
    }
  }
  return preludeItems > 0;
}

export function explicitErrorEventStatus(payload: unknown): number | undefined {
  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
  const event = payload as Record<string, unknown>;
  const nested = event.error;
  const error = nested && typeof nested === "object" && !Array.isArray(nested)
    ? nested as Record<string, unknown>
    : event;
  return [
    event.status,
    event.status_code,
    event.http_status,
    error.status,
    error.status_code,
    error.http_status,
  ]
    .map(value => typeof value === "number" && Number.isInteger(value)
      ? value
      : typeof value === "string" && /^\d{3}$/.test(value.trim())
        ? Number(value)
        : undefined)
    .find(value => value !== undefined && value >= 400 && value <= 599);
}

function ambiguousSseFrame(frame: string): boolean {
  let event: string | undefined;
  let hasNonComment = false;
  for (const line of frame.split(/\r\n|\r|\n/)) {
    if (!line || line.startsWith(":")) continue;
    hasNonComment = true;
    const colon = line.indexOf(":");
    const field = colon < 0 ? line : line.slice(0, colon);
    if (field === "event") {
      const value = colon < 0 ? "" : line.slice(colon + 1);
      event = value.startsWith(" ") ? value.slice(1) : value;
    }
  }
  const data = sseDataPayload(frame);
  if (data === null || data === "") return hasNonComment;
  if (!event) return false;
  try {
    const payload: unknown = JSON.parse(data);
    return !payload || typeof payload !== "object" || Array.isArray(payload)
      || (payload as { type?: unknown }).type !== event;
  } catch {
    return true;
  }
}

function bareErrorStatus(payload: unknown): number | undefined {
  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
  const event = payload as Record<string, unknown>;
  if (event.type !== "error") return undefined;
  const nested = event.error;
  const error = nested && typeof nested === "object" && !Array.isArray(nested)
    ? nested as Record<string, unknown>
    : event;
  const explicitStatus = explicitErrorEventStatus(payload);
  const rawCode = error.code ?? event.code;
  const code = typeof rawCode === "string"
    ? rawCode
    : typeof rawCode === "number" && Number.isFinite(rawCode)
      ? String(rawCode)
      : null;
  if (explicitStatus === undefined && code === "invalid_request_error") return 400;
  // A structured moderation verdict with no stated status is the request-level 400 the HTTP and
  // native readers judge it as, not an unknown code's 5xx.
  if (explicitStatus === undefined && isProviderModerationRefusal(400, JSON.stringify(event), undefined, true)) {
    return 400;
  }
  // Status is the record's own evidence; whether that record speaks for the envelope is the
  // decision's question, so a root hard stop still reports 400 instead of inventing a 5xx.
  if (explicitStatus === undefined && isOpenRouterOpaque400Record(envelopeErrorRecord(event))) {
    return 400;
  }
  // OpenRouter-style envelopes carry the HTTP status as a bare numeric `code` (e.g. `code: 400`)
  // with no separate status field. `httpStatusFromTerminalError` only understands symbolic codes,
  // so without this the opaque 400 stringifies to "400", reads as unknown, and falls back to 502 —
  // which cools the target on the generic 5xx path instead of taking the intended no-cool hop.
  if (explicitStatus === undefined
    && typeof rawCode === "number" && Number.isInteger(rawCode) && rawCode >= 400 && rawCode <= 599) {
    return rawCode;
  }
  return explicitStatus ?? httpStatusFromTerminalError({
    type: typeof error.type === "string" && error.type !== "error" ? error.type : undefined,
    code,
    message: typeof error.message === "string"
      ? error.message
      : typeof event.message === "string" ? event.message : undefined,
  });
}

/** Match the selected SSE error envelope before projection drops competing fields. */
function terminalModelRefusal(status: number, event: Record<string, unknown>): CodexAccountModelRefusal {
  if (hasConflictingCodexModelRefusalEnvelopes(status, event)) return "ambiguous";
  const outer = codexAccountModelRefusalPayload(status, event);
  if (outer === "ambiguous") return outer;
  const nested = event.response;
  if (event.type !== "error" && nested && typeof nested === "object" && !Array.isArray(nested)) {
    const nestedKind = codexAccountModelRefusalPayload(status, nested);
    if (nestedKind === "ambiguous") return nestedKind;
    const nestedError = (nested as Record<string, unknown>).error;
    if (nestedError && typeof nestedError === "object" && !Array.isArray(nestedError)) {
      return nestedKind;
    }
  }
  if (event.type === "error" && !Object.hasOwn(event, "error") && typeof event.message === "string") {
    return codexAccountModelRefusal(status, event.message, { allowNestedResponse: false });
  }
  return outer;
}

function bareErrorIsRetryable(payload: unknown): boolean {
  const status = bareErrorStatus(payload);
  if (status === undefined || !payload || typeof payload !== "object" || Array.isArray(payload)) {
    return false;
  }
  const event = payload as Record<string, unknown>;
  // The record selection, the opaque verdict and the code conflict rule are shared with the HTTP
  // consumer; only the carrier (one parsed frame here, one body there) differs.
  const record = envelopeErrorRecord(event);
  const error = record ?? event;
  const rootCode = envelopeRecordCode(event);
  const recordCode = envelopeRecordCode(record);
  const message = typeof error.message === "string"
    ? error.message
    : typeof event.message === "string" ? event.message : "";
  const rawRecord = {
    ...(error as Record<string, unknown>),
    ...(typeof event.detail === "string" ? { detail: event.detail } : {}),
  };
  const malformedResponseFormat = status === 400 ? isMalformedResponseFormatRecord(rawRecord, message) : undefined;
  const openRouterOpaque400 = status === 400 ? isOpenRouterOpaque400EnvelopeRoot(event) : undefined;
  // The parsed event is the whole terminal record, so its moderation verdict is not cut short.
  const providerModerationRefusal = status === 400 || status === 422
    ? isProviderModerationRefusal(status, JSON.stringify(event), undefined, true) : undefined;
  // The same whole-event reading for the provider-413 hop (#9017): terminal evidence in a sibling
  // field must keep the turn on this target.
  const providerIntakeRefusal = status === 413 ? isProviderIntakeRefusalBody(JSON.stringify(event)) : undefined;
  // A conflicting root and record code hop only when each would hop on its own, so a root hard
  // stop is never hidden behind a retryable record code (and a retryable pair keeps dev's hop).
  return comboFailureDecision(status, message, {
    code: recordCode ?? rootCode, rootCode,
    codexModelRefusal: terminalModelRefusal(status, event),
    malformedResponseFormat, openRouterOpaque400, providerModerationRefusal, providerIntakeRefusal,
  }) === "hop";
}

/**
 * Only text and reasoning items, which the required-tool guard holds back until it decides. Both the
 * snapshot's and the event's own `output` are read; an absent or empty one contributes nothing.
 */
function heldOnlyOutput(...outputs: unknown[]): boolean {
  const items = outputs.flatMap(output => Array.isArray(output) ? output : []);
  if (outputs.some(output => output !== undefined && !Array.isArray(output))) return false;
  return items.length > 0 && items.every(value => {
    const item = recordValue(value);
    return item?.type === "reasoning" || (item?.type === "message" && Array.isArray(item.content)
      && item.content.every(part => recordValue(part)?.type === "output_text"));
  });
}

function retryableZeroOutputTerminal(payload: unknown, context?: object): boolean {
  const event = recordValue(payload);
  if (!event) return false;
  if (bareErrorIsRetryable(event)) return true;
  const response = recordValue(event.response);
  const target = response ?? event;
  const emptyOutput = (!Array.isArray(event.output) || event.output.length === 0)
    && (!Array.isArray(target.output) || target.output.length === 0);

  if (event.type === "response.failed" || event.status === "failed") {
    const error = recordValue(response?.error ?? event.error);
    const code = error?.code;
    // The required-tool guard synthesizes this terminal over output it held back from the client,
    // so held text and reasoning are not evidence of anything sent; it keeps the retryability it
    // carries. Any other output item (a tool call, an action) still commits it.
    if (code === REQUIRED_TOOL_CONTRACT_CODE) {
      if (response?.error != null && event.error != null) return false;
      if (event.last_error != null || response?.last_error != null) return false;
      return error?.retryable !== false && !incompleteCarriersVetoReplay(event, response)
        && classifyIncompleteReplayReason(event, response) !== "veto"
        && (emptyOutput || heldOnlyOutput(target.output, event.output));
    }
    if (!emptyOutput) return false;
    if (typeof code === "string" && NON_REPLAYABLE_FAILED_CODES.has(code)) return false;
    // A failed terminal that states 413 is judged on the whole frame, as a bare error is: a
    // terminal code or marker beside the record (a root code, metadata) keeps it on this target,
    // because the projection below carries only the error record (#9017).
    return !(explicitErrorEventStatus(event) === 413 && !isProviderIntakeRefusalBody(JSON.stringify(event)));
  }
  const isIncomplete = event.type === "response.incomplete" || event.status === "incomplete";
  if (!isIncomplete) return false;
  if (!emptyOutput) return false;
  // A pause or explicit replay restriction takes precedence even when the reason is absent.
  if (isPausedTurn(context) || incompleteCarriersVetoReplay(event, response)) return false;
  return classifyIncompleteReplayReason(event, response) !== "veto";
}

/**
 * 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 and Codex metadata control frames
 * remain replayable.
 */
export function comboStreamPayloadCommitsOutput(payload: unknown): boolean {
  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return true;
  if (responsesFrameIsReplayUnsafe(payload as Record<string, unknown>)) return true;
  const type = (payload as { type?: unknown }).type;
  if (typeof type !== "string") return true;
  if (PRE_OUTPUT_CONTROL_EVENTS.has(type)) {
    // Lifecycle snapshots may already carry output or an error. Neither can be discarded
    // for a replacement, even if the event name otherwise describes only a prelude.
    const event = payload as Record<string, unknown>;
    const conflictingStatus = (status: unknown) => status != null && status !== "queued" && status !== "in_progress";
    if (Object.keys(event).some(key => !PRE_OUTPUT_EVENT_FIELDS.has(key))) return true;
    if (event.sequence_number !== undefined && !(typeof event.sequence_number === "number"
      && Number.isSafeInteger(event.sequence_number) && event.sequence_number >= 0)) return true;
    if (event.error != null || event.last_error != null || event.incomplete_details != null
      || event.item != null || event.delta != null || event.content != null
      || event.message != null || event.code != null || conflictingStatus(event.status)) return true;
    if (event.output !== undefined && (!Array.isArray(event.output) || event.output.length > 0)) return true;
    const response = event.response;
    if (response != null && (typeof response !== "object" || Array.isArray(response))) return true;
    if (response && typeof response === "object" && !Array.isArray(response)) {
      const snapshot = response as Record<string, unknown>;
      if (Object.keys(snapshot).some(key => !PRE_OUTPUT_SNAPSHOT_FIELDS.has(key))) return true;
      if (!snapshotMetadataIsSafe(snapshot)) return true;
      if (snapshot.output !== undefined && (!Array.isArray(snapshot.output) || snapshot.output.length > 0)) return true;
      if (snapshot.error != null || snapshot.last_error != null || snapshot.incomplete_details != null
        || conflictingStatus(snapshot.status)) return true;
      if (snapshot.completed_at != null || (snapshot.end_turn != null && snapshot.end_turn !== false)
        || (snapshot.background != null && snapshot.background !== false)
        || (snapshot.store != null && snapshot.store !== false) || snapshot.previous_response_id != null) return true;
    }
  }
  if (type === "response.output_text.delta") {
    const delta = (payload as { delta?: unknown }).delta;
    if (delta === undefined || (typeof delta === "string" && delta.length === 0)) return false;
  }
  return !PRE_OUTPUT_CONTROL_EVENTS.has(type) && !CODEX_METADATA_CONTROL_EVENTS.has(type)
    && !TERMINAL_EVENTS.has(type);
}

/**
 * How far this SSE body got, in the vocabulary of src/lib/request-failure-model.ts.
 *
 * The preflight cannot separate `semantic-output` from `side-effect`: it classifies any event
 * that is not a lifecycle control frame as committing, without reading item types. Both stages
 * refuse a resend, so the distinction would change no decision -- it is named here so a later
 * reader does not mistake the collapse for an omission.
 *
 * A terminal that settled carrying no output is `protocol-prelude`, not `terminal`. That is
 * the failure model's own rule: `terminal` means the answer was delivered, and an empty
 * completion delivered none.
 *
 * Only the two nothing-observed stages actually reach a read error today: the loop below hands
 * the body back as `accepted` the moment output commits or a terminal arrives, so a stream
 * that committed anything never reports a stage at all. The committed branches stay because
 * this has to be total for any other caller, and because a later change to that loop must not
 * be able to promote a committed stream into a replaceable one by omission.
 */
function observedResponsesStage(state: {
  readonly outputCommitted: boolean;
  readonly terminalStatus: ResponsesTerminalStatus | undefined;
  readonly responseCreated: boolean;
}): RequestFailureStage {
  if (state.outputCommitted) return "semantic-output";
  if (state.terminalStatus === "completed") return "terminal";
  if (state.responseCreated || state.terminalStatus !== undefined) return "protocol-prelude";
  return "headers-only";
}

/** A released replay slot. */
const EMPTY_CHUNK = new Uint8Array(0);

/** Exported for its regression tests (#8601). */
export function replayBufferedResponse(
  response: Response,
  reader: ReadableStreamDefaultReader<Uint8Array>,
  buffered: Uint8Array[],
  pendingRead?: ReturnType<typeof reader.read>,
): Response {
  let index = 0;
  const body = carryPacedStream(response.body, new ReadableStream<Uint8Array>({
    async pull(controller) {
      if (index < buffered.length) {
        // Hand each replayed chunk over once: the replay keeps no reference to a prefix the client already took (#8601).
        const chunk = buffered[index]!;
        buffered[index++] = EMPTY_CHUNK;
        controller.enqueue(chunk);
        return;
      }
      try {
        const next = await (pendingRead ?? reader.read());
        pendingRead = undefined;
        if (next.done) controller.close();
        else controller.enqueue(next.value);
      } catch (error) {
        try { controller.error(error); } catch { /* consumer already closed */ }
      }
    },
    cancel(reason) {
      buffered.fill(EMPTY_CHUNK);
      reader.cancel(reason).catch(() => undefined);
    },
  }, pacedQueuingStrategy(response.body)));
  return carryResponseToolOwnership(response, new Response(body, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  }));
}

function failedTerminalResponse(
  response: Response,
  terminalPayload: Record<string, unknown>,
  logCtx: RequestLogContext,
  collectUsage: boolean,
): Response {
  const nested = recordValue(terminalPayload.response);
  const terminalResponse = nested ?? terminalPayload;
  const zeroOutputLimit = (terminalPayload.type === "response.incomplete" || terminalPayload.status === "incomplete")
    && classifyIncompleteReplayReason(terminalPayload, nested) === "output-limit";
  const nestedError = nested?.error;
  const topLevelError = terminalPayload.error;
  const error = nestedError && typeof nestedError === "object" && !Array.isArray(nestedError)
    ? nestedError as Record<string, unknown>
    : topLevelError && typeof topLevelError === "object" && !Array.isArray(topLevelError)
      ? topLevelError as Record<string, unknown>
    : isOpenRouterOpaque400Record(terminalPayload)
      ? {
        message: terminalPayload.message,
        code: terminalPayload.code,
        metadata: terminalPayload.metadata,
      }
    : {
      // A caller-validated flat error can carry its identity beside type:error.
      // Retain it when that caller established a 400, rather than discarding the
      // rejection code before the single-shot opaque-state recovery sees it.
      type: terminalPayload.type === "error" && logCtx.terminalHttpStatus === 400
        ? "invalid_request_error" : "upstream_error",
      code: terminalPayload.type === "error" && logCtx.terminalHttpStatus === 400
        ? (typeof terminalPayload.code === "string"
            ? terminalPayload.code
            : typeof terminalPayload.code === "number" && Number.isFinite(terminalPayload.code)
              ? String(terminalPayload.code)
              : null)
        : zeroOutputLimit ? "zero_output_token_limit" : "upstream_server_error",
      message: typeof terminalPayload.message === "string"
        ? terminalPayload.message
        : zeroOutputLimit
          ? "Provider reached its output token limit before producing output"
          : 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 = collectUsage && !logCtx.usageFromBridge && !logCtx.clientResponseUsage
    ? terminalResponse.usage : undefined;
  return new Response(JSON.stringify({
    error,
    ...(typeof terminalPayload.detail === "string" ? { detail: terminalPayload.detail } : {}),
    // 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 } : {}),
    },
  }), {
    // A structured moderation verdict on any carrier (`error` or `response.failed`) is the
    // request-level 400 the HTTP and native readers judge it as. The verdict already vetoes any
    // stated status other than 400/422, so this only replaces a status the log tap inferred (the
    // synthetic 502 for an unrecognized code).
    // An event that states 413 itself (a status field or a numeric code) keeps it when the whole
    // frame reads as a provider intake refusal: the log tap may have inferred 400 from an
    // invalid_request_error type or 429 from rate_limit_exceeded, and either would turn the
    // provider-413 hop (#9017) into a stop or a target cooldown on the outer decision.
    status: (explicitErrorEventStatus(terminalPayload) === 413 || bareErrorStatus(terminalPayload) === 413)
      && isProviderIntakeRefusalBody(JSON.stringify(terminalPayload))
      ? 413
      : (logCtx.terminalHttpStatus !== 400 && logCtx.terminalHttpStatus !== 422
      && isProviderModerationRefusal(400, JSON.stringify(terminalPayload), undefined, true))
      ? 400
      : logCtx.terminalHttpStatus ?? bareErrorStatus(terminalPayload) ?? 502,
    headers,
  });
}

export type ComboStreamPreflightResult =
  | { kind: "accepted"; response: Response }
  | { kind: "failed"; response: Response; codexModelRefusal?: CodexAccountModelRefusal }
  /**
   * The body errored mid-stream and `replayReadErrors` asked for the prefix back rather than
   * a rethrow. `stage` is how far the inspection actually got; whether that permits a
   * replacement is the resend gate's decision, not this function's. Callers that only act on
   * a projected terminal can treat this exactly as `accepted`, which is what it was before
   * the stage became observable.
   */
  | { kind: "read-error"; response: Response; error: unknown; stage: RequestFailureStage }
  /** A clean EOF after control frames, retained for an explicitly opted-in recovery owner. */
  | { kind: "pre-output-eof"; response: Response; error: ProtocolPreOutputEof; stage: RequestFailureStage };

/**
 * Buffer a Responses SSE only until the request becomes unsafe to replay or reaches a
 * terminal. Combo failover and native post-header reset recovery share this protocol
 * boundary, because they are asking the same question about the same bytes. 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,
  retryableTerminal?: (payload: unknown) => boolean,
  options?: {
    allowMissingContentType?: boolean;
    replayReadErrors?: boolean;
    replayCleanEof?: boolean;
    requiredToolPrelude?: boolean;
    degeneratePrelude?: boolean;
    signal?: AbortSignal;
    onUpstreamActivity?: () => void;
  },
): Promise<ComboStreamPreflightResult> {
  const retryableTerminalFor = retryableTerminal ?? ((payload: unknown) => retryableZeroOutputTerminal(payload, logCtx));
  const contentType = response.headers.get("content-type");
  const isEventStream = hasResponseMediaType(response.headers, "text/event-stream")
    || (!contentType && options?.allowMissingContentType === true);
  if (!response.ok || !response.body) {
    return { kind: "accepted", response };
  }
  if (!isEventStream) {
    return { kind: "accepted", response };
  }

  const reader = response.body.getReader();
  const cancelRead = () => { reader.cancel(options?.signal?.reason).catch(() => undefined); };
  if (options?.signal?.aborted) cancelRead();
  else options?.signal?.addEventListener("abort", cancelRead, { once: true });
  const buffered: Uint8Array[] = [];
  let bufferedBytes = 0;
  let outputCommitted = false;
  let responseCreated = false;
  let terminalStatus: ResponsesTerminalStatus | undefined;
  let retryableTerminalPayload: Record<string, unknown> | undefined;
  let degenerateTerminalPayload: Record<string, unknown> | undefined;
  const commentaryItemIds = new Set<string>();
  let holdTimer: ReturnType<typeof setTimeout> | undefined;
  let holdDeadline: Promise<"hold-expired"> | undefined;
  // Native delivery already inspects raw usage; these bytes may contain display estimates.
  const collectUsage = !isNativePassthroughSseResponse(response);
  const inspector = createSseInspector({
    logCtx,
    collectUsage,
    onFrame: frame => {
      if (terminalStatus === undefined && !outputCommitted && !retryableTerminalPayload
        && ambiguousSseFrame(frame)) outputCommitted = true;
    },
    // A payload the inspector could not parse still reached this proxy, and it may be output.
    // Committing on it is what keeps an unreadable frame from reading as an empty prelude.
    onOpaquePayload: () => { outputCommitted = true; },
    onParsedPayload: payload => {
      if (terminalStatus !== undefined || outputCommitted || retryableTerminalPayload) return;
      // A provider verdict commits even when it resembles a retryable zero-output failure.
      if (responsesCompletionError(payload) != null) {
        outputCommitted = true;
        return;
      }
      try {
        const event = payload !== null && typeof payload === "object" && !Array.isArray(payload)
          ? payload as Record<string, unknown> : undefined;
        if (event && responsesFrameIsReplayUnsafe(event)) {
          outputCommitted = true;
          return;
        }
        if (event?.type === "response.created") responseCreated = true;
        const retryable = retryableTerminalFor(payload);
        const matchedBareError = retryable && payload !== null && typeof payload === "object"
          && !Array.isArray(payload) && (payload as { type?: unknown }).type === "error";
        // A zero-output bare error is terminal evidence. Explicit client errors stay
        // committed; unknown and retryable upstream failures may advance the combo.
        const heldReasoning = options?.degeneratePrelude === true
          ? comboStreamDegeneratePrelude(payload, commentaryItemIds)
          : options?.requiredToolPrelude && requiredToolReasoningPrelude(payload);
        if (options?.degeneratePrelude || options?.requiredToolPrelude) holdDeadline ??= new Promise(resolve => {
          holdTimer = setTimeout(() => resolve("hold-expired"), COMBO_STREAM_PRELUDE_HOLD_MS);
        });
        const degenerateTerminal = options?.degeneratePrelude === true
          && isDegenerateStreamTerminal(payload, logCtx);
        if (comboStreamPayloadCommitsOutput(payload) && !matchedBareError && !heldReasoning) outputCommitted = true;
        if (options?.requiredToolPrelude && payload && typeof payload === "object") {
          const event = payload as { type?: unknown; response?: { output?: unknown; error?: { code?: unknown; retryable?: unknown } } };
          const output = event.response?.output;
          const contractFailure = event.type === "response.failed" && event.response?.error?.code === REQUIRED_TOOL_CONTRACT_CODE
            && event.response.error.retryable !== false && Array.isArray(output) && output.every(item =>
              item !== null && typeof item === "object" && !Array.isArray(item)
              && ["message", "reasoning"].includes((item as { type: string }).type));
          // Other lifecycle/terminal snapshots can hide effects too. Only our checked contract
          // failure may discard a terminal-only text snapshot that was held in its entirety.
          if (output !== undefined && (!Array.isArray(output) || output.length > 0) && !contractFailure && !degenerateTerminal) outputCommitted = true;
        }
        if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
        if (retryable) retryableTerminalPayload = payload as Record<string, unknown>;
        if (degenerateTerminal && !degenerateTerminalPayload) {
          const response = recordValue((payload as Record<string, unknown>).response);
          degenerateTerminalPayload = {
            ...(payload as Record<string, unknown>),
            response: {
              ...(response ?? {}),
              error: {
                type: "upstream_error",
                code: COMBO_DEGENERATE_COMPLETION_CODE,
                message: "Combo target ended the turn with only reasoning/commentary prelude — no tool call or final answer",
              },
            },
          };
        }
      } catch {
        // The generic inspector swallows observer errors. Replay requires a successful proof
        // of no effects, so a failed classification keeps this attempt and its original bytes.
        outputCommitted = true;
        retryableTerminalPayload = undefined;
        degenerateTerminalPayload = undefined;
      }
    },
    onTerminal: status => { terminalStatus = status; },
  });

  try {
    for (;;) {
      options?.signal?.throwIfAborted();
      let next: Awaited<ReturnType<typeof reader.read>>;
      try {
        const pendingRead = reader.read();
        const observed = await (holdDeadline ? Promise.race([pendingRead, holdDeadline]) : pendingRead);
        options?.signal?.throwIfAborted();
        if (observed === "hold-expired") {
          // Expiry commits this child. Hand the in-flight read to the relay so its
          // eventual chunk/error is delivered exactly once, never lost to the race.
          return { kind: "accepted", response: replayBufferedResponse(response, reader, buffered, pendingRead) };
        }
        next = observed;
      } catch (error) {
        if (!options?.replayReadErrors) throw error;
        // A rejected read can leave an output, terminal or opaque frame buffered
        // in the inspector. Flush it before deciding whether recovery is safe.
        inspector.finish();
        // The native relay still owns post-header transport failures. Preserve
        // the bounded prefix and the errored reader; cancelling it here would
        // erase the failure before either client relay or inspection sees it.
        const replay = replayBufferedResponse(response, reader, buffered);
        if (outputCommitted || terminalStatus !== undefined || retryableTerminalPayload) {
          return { kind: "accepted", response: replay };
        }
        const stage = observedResponsesStage({ outputCommitted, terminalStatus, responseCreated });
        return { kind: "read-error", response: replay, error, stage };
      }
      if (next.done) {
        inspector.finish();
        if (options?.replayCleanEof && !outputCommitted && terminalStatus === undefined) {
          return {
            kind: "pre-output-eof",
            response: replayBufferedResponse(response, reader, buffered),
            error: new ProtocolPreOutputEof(),
            stage: observedResponsesStage({ outputCommitted, terminalStatus, responseCreated }),
          };
        }
      } else {
        if (next.value.byteLength > 0) options?.onUpstreamActivity?.();
        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);
      }

      // A bare error event is not a protocol terminal (terminalStatus stays undefined),
      // so its retryable classification doubles as the terminal evidence. A degenerate
      // terminal carries the same hop evidence: its buffered prelude never reached the
      // client, so discarding it cannot duplicate anything the caller already saw.
      const hopEvidence = retryableTerminalPayload ?? degenerateTerminalPayload;
      if ((terminalStatus === "failed" || terminalStatus === "incomplete"
        || hopEvidence?.type === "error" || degenerateTerminalPayload !== undefined)
        && !outputCommitted && hopEvidence !== undefined) {
        await reader.cancel("retrying zero-output combo stream terminal").catch(() => undefined);
        const failed = failedTerminalResponse(response, hopEvidence, logCtx, collectUsage);
        // The rebuilt envelope keeps only the record. When either the whole frame or that slim
        // envelope reads as a moderation verdict, the combo loop must judge the whole frame: a
        // verdict needs the evidence the envelope dropped (a root code, an innererror), and a veto
        // the envelope dropped (a root verdict, a nested hard code) must not turn into a hop.
        if (failed.status === 400 || failed.status === 422) {
          const whole = JSON.stringify(hopEvidence);
          if (isProviderModerationRefusal(failed.status, whole, undefined, true)
            || isProviderModerationRefusal(failed.status, await failed.clone().text(), undefined, true)) {
            attachComboFailureEvidence(failed, whole);
          }
        }
        return { kind: "failed", response: failed,
          ...(failed.status === 400
            ? { codexModelRefusal: terminalModelRefusal(failed.status, hopEvidence) } : {}) };
      }
      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 {
    if (holdTimer !== undefined) clearTimeout(holdTimer);
    options?.signal?.removeEventListener("abort", cancelRead);
    inspector.dispose();
  }
}

/** Produce a replacement body for a mid-stream failure at `stage`, or null to keep the error. */
export type ProtocolSafeResetRecovery = (
  error: unknown,
  stage: RequestFailureStage,
  signal: AbortSignal,
  /** Whether the selection can still publish this candidate; it narrows once a head is committed. */
  accepts: (candidate: Response) => boolean,
) => Promise<Response | null>;

/**
 * The headers a committed head promises about the body that follows it.
 *
 * A replacement never sends its own head: the client already has the original one, so only what
 * the client reads to interpret the swapped body can matter here. Comparing the whole header set
 * refused every real recovery, because origins vary `date`, `x-request-id`, `cf-ray`,
 * `server-timing`, the quota headers and `content-length` per attempt; those describe the
 * attempt that answered, not the response identity, and the client already holds the original's
 * values. Hop-by-hop headers are listed for the same reason: the connection is the proxy's.
 *
 * What is left is the identity a mismatched body would corrupt:
 * - `openai-model` is the model the origin actually served. A body produced by a different
 *   served model behind a head that advertised the first one mislabels the turn for the client's
 *   follow-ups and for usage attribution.
 * - `x-codex-turn-state` is this proxy's own handle, bound at issuance to the caller, provider
 *   and outbound account and redeemed back to the upstream turn token only at the physical send
 *   of a matching request (`src/server/turn-state-handles.ts`). Publishing a replacement body
 *   under the original handle would redeem the client's next turn against a different turn state
 *   than the one that produced the body, which is exactly the conversation corruption the handle
 *   exists to prevent.
 *
 * Everything else is ignored on purpose: `date`, `x-request-id`, `request-id`, `cf-ray`,
 * `server-timing`, `x-ratelimit-*`, `openai-processing-ms`, `content-length`,
 * `transfer-encoding`, `connection` and `keep-alive`, plus any provider header the client
 * never interprets.
 */
const DEFERRED_IDENTITY_HEADERS: readonly string[] = ["openai-model", "x-codex-turn-state"];

const headerMediaType = (headers: Headers): string =>
  headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() ?? "";

/**
 * Whether a replacement body may be published behind an already committed head on the clean
 * pre-output EOF path. A deferred body cannot change the head, so it must at least agree on the
 * identity subset above.
 */
export function sameDeferredResponseIdentity(original: Response, replacement: Response): boolean {
  if (original.status !== replacement.status || original.statusText !== replacement.statusText) return false;
  if (headerMediaType(original.headers) !== headerMediaType(replacement.headers)) return false;
  return DEFERRED_IDENTITY_HEADERS.every(name => (original.headers.get(name) ?? "") === (replacement.headers.get(name) ?? ""));
}

export interface DeferredResetRecoveryOptions {
  allowMissingContentType?: boolean;
  heartbeatIntervalMs?: number;
  /**
   * `periodic` comments a waiting client once per heartbeat. `upstream-activity` comments only when
   * the upstream reads non-empty bytes or a replacement head lands behind a committed head, for a
   * consumer whose silence clock sees only delivered bytes; its owner still bounds real silence.
   */
  keepalive?: "periodic" | "upstream-activity" | "none";
}

/** Which physical attempt produced the head a reset selection published. */
export type ResetSelectionOwner = "original" | "replacement";

export interface ResetSelectionOptions extends DeferredResetRecoveryOptions {
  /** Upper bound on the pre-head wait. The wait never exceeds one heartbeat interval either. */
  maxSelectionMs?: number;
  /**
   * Upper bound on how long the original's own inspection may hold the head. When it expires
   * before the original settles, the original head is committed and inspection continues behind
   * it. A replacement requested after the original failed inside this window is still bounded by
   * `maxSelectionMs`, because no healthy source is waiting behind that head.
   */
  inspectionWindowMs?: number;
  /** Ends the selection, the committed hold and an in-flight replacement without awaiting cleanup. */
  signal?: AbortSignal;
  /** Called once, synchronously, before the caller receives the published response. */
  onCommit?: (published: Response, owner: ResetSelectionOwner) => void;
}

const positiveMs = (value: number | undefined): number | undefined =>
  value !== undefined && Number.isFinite(value) && value > 0 ? value : undefined;

// A fresh chunk per enqueue: a consumer may transfer the buffer it receives.
const resetPreflightKeepalive = (): Uint8Array => new TextEncoder().encode(": keepalive\n\n");

/**
 * One protocol preflight and at most one replacement for a native SSE body, behind a head that is
 * either still open (`early`) or already committed. While the head is open, any replacement the
 * caller's recovery accepts can be published with its own status and headers. Once a head is
 * committed, acceptance depends on how the stream ended: a read error keeps the permissive
 * replacement behaviour the reset lane has always had, while a clean pre-output EOF must agree on
 * the deferred identity subset. The original keeps its bytes and error when nothing is accepted.
 */
function createResetSelection(
  response: Response,
  logCtx: RequestLogContext,
  recover: ProtocolSafeResetRecovery,
  options: ResetSelectionOptions | undefined,
  early: boolean,
): { held: Response; selected?: Promise<Response> } {
  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
  let selection: { response: Response; owner: ResetSelectionOwner } | undefined;
  let initialization: Promise<void> | undefined;
  let initializationResult: { kind: "ready" } | { kind: "failed"; error: unknown } | undefined;
  let notifyInitialization: (() => void) | undefined;
  let commitEarly: ((published: Response, owner: ResetSelectionOwner) => void) | undefined;
  let inspectionTimer: ReturnType<typeof setTimeout> | undefined;
  const endInspectionWindow = (): void => {
    if (inspectionTimer !== undefined) clearTimeout(inspectionTimer);
    inspectionTimer = undefined;
  };
  let activityPending = false;
  // A replacement head behind a committed head is upstream activity the held stream must report.
  let replacementHeadPending = false;
  let heartbeatDue = false;
  let closed = false;
  let headCommitted = !early;
  let output!: ReadableStreamDefaultController<Uint8Array>;
  const preflightAbort = new AbortController();
  const heartbeatMs = positiveMs(options?.heartbeatIntervalMs) ?? RESET_PREFLIGHT_HEARTBEAT_MS;
  const keepalive = options?.keepalive ?? "periodic";
  const signal = options?.signal;
  /**
   * Acceptance narrows with the failure, not with the selection alone.
   *
   * A read error is the reset the recovery lane has always served: the transport died, the
   * upstream attempt is over, and whatever a fresh attempt produced stands in for it. Nothing
   * about the replacement's metadata can be inferred from the original's, because a real origin
   * varies `date`, request ids and quota headers on every attempt, so requiring equality made
   * the recovery unreachable.
   *
   * A clean pre-output EOF is different: the origin closed a healthy stream after its lifecycle
   * events, so the bytes that follow are a different attempt's answer to the same turn. Behind a
   * committed head it still has to agree on the identity subset that describes what the client
   * will read.
   */
  const acceptsFor = (kind: "read-error" | "pre-output-eof"): ((candidate: Response) => boolean) =>
    kind === "pre-output-eof"
      ? (candidate: Response) => !headCommitted || sameDeferredResponseIdentity(response, candidate)
      : () => true;

  const cancelBody = (body: ReadableStream<Uint8Array> | null, reason?: unknown): void => {
    try { void body?.cancel(reason).catch(() => {}); } catch { /* already locked or closed */ }
  };
  const initialize = async (): Promise<void> => {
    const preflight = await preflightComboStreamResponse(
      response,
      logCtx,
      () => false,
      { allowMissingContentType: options?.allowMissingContentType === true, replayReadErrors: true,
        replayCleanEof: true, signal: preflightAbort.signal,
        onUpstreamActivity: keepalive === "upstream-activity" ? () => {
          activityPending = true;
          notifyInitialization?.();
        } : undefined },
    );
    // The original settled, so it no longer holds the head; only a replacement can from here.
    endInspectionWindow();
    let chosen: { response: Response; owner: ResetSelectionOwner } = { response: preflight.response, owner: "original" };
    if (!closed && (preflight.kind === "read-error" || preflight.kind === "pre-output-eof")) {
      const accepts = acceptsFor(preflight.kind);
      const replacement = await recover(preflight.error, preflight.stage, preflightAbort.signal, accepts);
      if (replacement) {
        // Checked again here: the head may have been committed while the replacement was in flight.
        if (!closed && accepts(replacement)) {
          cancelBody(chosen.response.body, "using protocol-safe replacement stream");
          chosen = { response: replacement, owner: "replacement" };
          replacementHeadPending = headCommitted && keepalive === "upstream-activity";
        } else {
          cancelBody(replacement.body, "declining protocol-safe replacement stream");
          if (!closed) console.warn("[upstream-retry] replacement response metadata differs from the committed head; preserving original stream");
        }
      }
    }
    if (closed) {
      cancelBody(chosen.response.body, "downstream cancelled before protocol preflight completed");
      return;
    }
    selection = chosen;
  };
  const start = (): Promise<void> => initialization ??= initialize().then(
    () => { initializationResult = { kind: "ready" }; notifyInitialization?.(); },
    error => { initializationResult = { kind: "failed", error }; notifyInitialization?.(); },
  );
  const detach = (): void => signal?.removeEventListener("abort", onAbort);
  const release = (reason: unknown): boolean => {
    if (closed) return false;
    closed = true;
    detach();
    preflightAbort.abort(reason);
    notifyInitialization?.();
    if (reader) {
      try { void reader.cancel(reason).catch(() => {}); } catch { /* already closed */ }
      try { reader.releaseLock(); } catch { /* already released */ }
      reader = undefined;
    } else if (selection) {
      cancelBody(selection.response.body, reason);
    } else if (initialization === undefined) {
      // Nothing has read the upstream yet, so this body is still ours to cancel.
      cancelBody(response.body, reason);
    }
    // Otherwise aborting cancels the preflight's locked reader or the in-flight replacement, and
    // initialization releases whichever body it ends up choosing. Nothing here awaits cleanup.
    return true;
  };
  function onAbort(): void {
    const reason = signal?.reason;
    if (release(reason)) {
      try { output.error(reason); } catch { /* already closed */ }
    }
    commitEarly?.(held, "original");
  }

  const body = new ReadableStream<Uint8Array>({
    start(controller) { output = controller; },
    async pull(controller) {
      try {
        void start();
        // Keep only one waiter on the initialization; racing it afresh for every heartbeat
        // would retain one promise callback per interval until a quiet upstream settles.
        if (initializationResult === undefined && !heartbeatDue && !(keepalive === "upstream-activity" && activityPending)) {
          await new Promise<void>(resolve => {
            const timer = keepalive === "periodic"
              ? setTimeout(() => { notifyInitialization = undefined; resolve(); }, heartbeatMs)
              : undefined;
            notifyInitialization = () => { if (timer !== undefined) clearTimeout(timer); notifyInitialization = undefined; resolve(); };
          });
        }
        if (closed) return;
        if (initializationResult === undefined) {
          activityPending = false;
          heartbeatDue = false;
          controller.enqueue(resetPreflightKeepalive());
          return;
        }
        if (initializationResult.kind === "failed") throw initializationResult.error;
        if (replacementHeadPending) {
          // A buffered consumer's silence clock sees only delivered bytes. Without this, a quiet
          // replacement would inherit the original's last activity and be cut short.
          replacementHeadPending = false;
          controller.enqueue(resetPreflightKeepalive());
          return;
        }
        reader ??= selection?.response.body?.getReader();
        if (!reader) {
          closed = true;
          detach();
          controller.close();
          return;
        }
        const next = await reader.read();
        if (closed) return;
        if (next.done) {
          closed = true;
          detach();
          try { reader.releaseLock(); } catch { /* already released */ }
          reader = undefined;
          controller.close();
          return;
        }
        controller.enqueue(next.value);
      } catch (error) {
        if (closed) return;
        closed = true;
        detach();
        try { reader?.releaseLock(); } catch { /* errored reader */ }
        reader = undefined;
        controller.error(error);
      }
    },
    cancel(reason) {
      release(reason);
    },
  }, { highWaterMark: 0 });
  const held = carryResponseToolOwnership(response, new Response(body, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  }));

  if (!early) {
    if (signal?.aborted) onAbort();
    else signal?.addEventListener("abort", onAbort, { once: true });
    return { held };
  }
  const selected = new Promise<Response>(resolve => {
    let deadline: ReturnType<typeof setTimeout> | undefined;
    commitEarly = (published, owner) => {
      commitEarly = undefined;
      headCommitted = true;
      if (deadline !== undefined) clearTimeout(deadline);
      endInspectionWindow();
      // A published selection owns its own body; the hold and its abort hook are finished.
      if (published !== held) detach();
      try { options?.onCommit?.(published, owner); } finally { resolve(published); }
    };
    if (signal?.aborted) {
      onAbort();
      return;
    }
    signal?.addEventListener("abort", onAbort, { once: true });
    const deadlineMs = Math.min(heartbeatMs, positiveMs(options?.maxSelectionMs) ?? Infinity);
    deadline = setTimeout(() => {
      // The client has waited one heartbeat interval for a head; its first read gets a keepalive.
      if (keepalive === "periodic") heartbeatDue = true;
      commitEarly?.(held, "original");
    }, deadlineMs);
    const inspectionMs = positiveMs(options?.inspectionWindowMs);
    // A quiet original is a healthy slow response as often as a dying one; its head goes out now.
    // Bun's server writes a head only with the first body bytes, so the held body owes a comment.
    if (inspectionMs !== undefined && inspectionMs < deadlineMs) {
      inspectionTimer = setTimeout(() => {
        inspectionTimer = undefined;
        if (keepalive === "periodic") heartbeatDue = true;
        commitEarly?.(held, "original");
      }, inspectionMs);
    }
    void start().then(() => {
      if (selection && !closed) commitEarly?.(selection.response, selection.owner);
      else commitEarly?.(held, "original");
    });
  });
  return { held, selected };
}

/**
 * Defer protocol inspection behind a head the caller has already committed.
 *
 * The inspection starts at the first pull. A replacement behind the committed head is published
 * for a read error (the reset lane's long-standing behaviour) and, for a clean pre-output EOF,
 * only when it agrees on the deferred identity subset (status, status text, media type,
 * `openai-model`, `x-codex-turn-state`).
 */
export function deferProtocolSafeResetRecovery(
  response: Response,
  logCtx: RequestLogContext,
  recover: ProtocolSafeResetRecovery,
  options?: DeferredResetRecoveryOptions,
): Response {
  if (!response.body) return response;
  return createResetSelection(response, logCtx, recover, options, false).held;
}

/**
 * Choose the native response before its head is committed, within one heartbeat interval or the
 * shorter `inspectionWindowMs` while the original itself is still being inspected.
 *
 * Inspection starts immediately. If selection finishes first, the caller receives the selected
 * response, a replacement included, with its own status and headers. If the deadline wins, the
 * caller receives the original head and the same preflight continues behind it, where a read
 * error's replacement is accepted and a clean EOF's must agree on the identity subset.
 * `onCommit` names which attempt owns the published head.
 */
export function selectProtocolSafeResetResponse(
  response: Response,
  logCtx: RequestLogContext,
  recover: ProtocolSafeResetRecovery,
  options: ResetSelectionOptions = {},
): Promise<Response> {
  if (!response.body) {
    options.onCommit?.(response, "original");
    return Promise.resolve(response);
  }
  return createResetSelection(response, logCtx, recover, options, true).selected!;
}