@bitkyc08/opencodex 2.57.0 → 2.58.0

package/src/server/responses/native-steering.ts

@@ -0,0 +1,400 @@
+import { isSteeringMutableSetting, validSteeringSettings } from "./native-steering-settings";
+import type { NativeSteeringReplayObserver } from "./native-steering-replay";
+import { createHash } from "node:crypto";
+import { CODEX_WS_ID_MAX_BYTES, CodexWsCorrelation } from "./codex-ws-correlation";
+import { codexWsCreateFrameExceedsLimit } from "./codex-ws-wire";
+
+export const MAX_NATIVE_STEERS = 32;
+export const MAX_NATIVE_STEERING_RESPONSES = 128;
+export const NATIVE_STEERING_WAIT_MS = 90_000;
+export const NATIVE_STEERING_TOOL_WAIT_MS = 30 * 60_000;
+
+type Frame = Record<string, unknown>;
+type Send = (frame: Frame) => void;
+
+/** Narrow JSON object envelopes while excluding arrays and null. */
+function record(value: unknown): value is Frame {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Require a bounded, nonempty protocol identity without control characters. */
+function validId(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && Buffer.byteLength(value) <= CODEX_WS_ID_MAX_BYTES
+    && !/[\u0000-\u001f\u007f]/.test(value);
+}
+/** Serialize JSON settings deterministically so key order cannot change equality. */
+function stable(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  if (record(value)) return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stable(value[key])}`).join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+/** Retain only a digest of pinned settings instead of their request payloads. */
+function fingerprint(value: unknown): string { return createHash("sha256").update(stable(value)).digest("hex"); }
+
+/** Typed, content-free local protocol rejection. */
+export class NativeSteeringError extends Error {
+  /** Create a content-free protocol error with a stable downstream rejection code. */
+  constructor(readonly code: string, message: string) { super(message); this.name = "NativeSteeringError"; }
+}
+
+/** Validate the narrow public steer envelope, not the much wider create schema. */
+export function validateSteeringFrame(frame: Frame): void {
+  const fail = () => { throw new NativeSteeringError("invalid_input", "Steering requires user-only input and a previous_response_id; extra envelope fields are not supported."); };
+  if (frame.type !== "response.steer" || !validId(frame.previous_response_id)
+    || Object.keys(frame).some(key => !["type", "previous_response_id", "input"].includes(key))) fail();
+  if (typeof frame.input === "string") return;
+  if (!Array.isArray(frame.input) || !frame.input.length) { fail(); return; }
+  for (const item of frame.input) {
+    if (!record(item) || item.role !== "user" || (item.type !== undefined && item.type !== "message")
+      || Object.keys(item).some(key => !["type", "role", "content"].includes(key))) { fail(); return; }
+    if (typeof item.content === "string") continue;
+    if (!Array.isArray(item.content) || !item.content.length) { fail(); return; }
+    for (const part of item.content) {
+      if (!record(part) || !["input_text", "input_image", "input_file"].includes(String(part.type))
+        || (part.type === "input_text" && typeof part.text !== "string")) fail();
+    }
+  }
+}
+
+type Parent = {
+  unacknowledged: Array<{ deadline: number }>;
+  accepted: Set<string>;
+  ended: boolean;
+  successorDeadline?: number;
+  toolDeadline?: number;
+};
+
+/** Only client-owned results can use the early-continuation path. */
+function outputRequirement(item: unknown): Frame | undefined {
+  if (!record(item) || typeof item.type !== "string") return;
+  if (item.type === "mcp_approval_request") {
+    if (!validId(item.id)) throw new Error("Native steering approval identity is invalid");
+    return { type: "mcp_approval_response", approval_request_id: item.id };
+  }
+  const types: Record<string, string> = {
+    function_call: "function_call_output", custom_tool_call: "custom_tool_call_output",
+    local_shell_call: "local_shell_call_output", shell_call: "shell_call_output",
+    computer_call: "computer_call_output", apply_patch_call: "apply_patch_call_output",
+  };
+  const type = Object.hasOwn(types, item.type) ? types[item.type] : undefined;
+  if (!type) return;
+  if (!validId(item.call_id)) throw new Error("Native steering tool-call identity is invalid");
+  return { type, call_id: item.call_id };
+}
+
+/** Match a saved result to its required stub, allowing an omitted optional name. */
+function matchesRequirement(item: Frame, stub: Frame): boolean {
+  // The wire may label a required result with its tool name, but the ordinary
+  // function/custom output schema identifies the result by call_id, not name.
+  return Object.entries(stub).every(([key, value]) =>
+    key === "name" && item[key] === undefined || stable(item[key]) === stable(value));
+}
+
+/**
+ * One downstream turn owns one dedicated native upstream socket, including all
+ * automatic successors and required-input continuations. Never registered by a
+ * caller-supplied response ID in global state; never lent to another account.
+ *
+ * Opt-in single-lane implementation. Continuations may supply saved tool results and new user messages
+ * and validated generation overrides, but cannot change routing or tools. General new turns still use normal dispatch.
+ */
+export class NativeSteeringChannel {
+  readonly kind = "steering" as const;
+  normalizeContinuation?: (frame: Frame) => Frame;
+  relayActive = false;
+  replayFactory?: () => NativeSteeringReplayObserver;
+  private replay?: NativeSteeringReplayObserver;
+  private send?: Send;
+  private onFailure?: (error: Error) => void;
+  private timer?: ReturnType<typeof setTimeout>;
+  private timerDeadline?: number;
+  private idleDeadline?: number;
+  private continuationDeadline?: number;
+  private readonly parents = new Map<string, Parent>();
+  private readonly settings = new Map<string, string>();
+  private currentId?: string;
+  private correlation?: CodexWsCorrelation;
+  private pendingParent?: string;
+  private continuationSent = false;
+  private lane: unknown;
+  private finished = false;
+  private everAttached = false;
+  private required: Frame[] = [];
+  private readonly advertised = new Map<string, Frame>();
+  private advertisedBytes = 0;
+
+  /** Pin the initial lane and setting digests without opening a transport. */
+  constructor(initial: Frame, private readonly idleMs = 300_000) {
+    if (record(initial.multi_agent) && initial.multi_agent.enabled === true) {
+      throw new NativeSteeringError("native_control_mode_mismatch", "Multi-agent responses cannot use the single-agent steering channel.");
+    }
+    this.lane = initial.stream_id;
+    for (const [key, value] of Object.entries(initial)) {
+      if (!["type", "input", "previous_response_id", "stream", "stream_id"].includes(key)) this.settings.set(key, fingerprint(value));
+    }
+  }
+  /** Report whether native dispatch ever bound a physical connection to this owner. */
+  get attached(): boolean { return this.everAttached; }
+  /** Report whether ordered terminal handling has finished the native chain. */
+  get ended(): boolean { return this.finished; }
+  /** Count unacknowledged or accepted submissions that still own the response chain. */
+  get hasOutstanding(): boolean {
+    return [...this.parents.values()].some(parent => parent.unacknowledged.length > 0 || parent.accepted.size > 0);
+  }
+  /** Report whether the server has requested a saved-result continuation. */
+  get awaitingContinuation(): boolean { return this.pendingParent !== undefined; }
+
+  /** Bind only after native credentials have been selected and admission passed. */
+  attach(send: Send, onFailure: (error: Error) => void): () => void {
+    if (this.send || this.currentId) throw new Error("native steering transport already owned");
+    this.replay = this.replayFactory?.();
+    this.everAttached = true;
+    this.finished = false;
+    this.send = send;
+    this.onFailure = onFailure;
+    return () => {
+      if (this.send !== send) return;
+      this.send = undefined;
+      this.onFailure = undefined;
+      this.clearTimer();
+      this.idleDeadline = undefined;
+      this.continuationDeadline = undefined;
+      this.correlation?.finish();
+      this.correlation = undefined;
+      this.parents.clear();
+      this.required = [];
+      this.advertised.clear();
+      this.advertisedBytes = 0;
+      this.replay?.dispose();
+      this.replay = undefined;
+    };
+  }
+
+  /** Drop the physical timer without altering any protocol-stage deadline. */
+  private clearTimer(): void {
+    clearTimeout(this.timer);
+    this.timer = undefined;
+    this.timerDeadline = undefined;
+  }
+
+  /** Earliest absolute control deadline wins, independently of ordinary stream activity. */
+  private nextDeadline(): number | undefined {
+    let deadline: number | undefined;
+    const include = (value: number | undefined) => {
+      if (value !== undefined) deadline = deadline === undefined ? value : Math.min(deadline, value);
+    };
+    for (const [id, parent] of this.parents) {
+      include(parent.unacknowledged[0]?.deadline);
+      if (parent.ended && (parent.accepted.size || parent.unacknowledged.length)) {
+        if (id === this.currentId && this.continuationSent) continue;
+        include(this.pendingParent === id ? parent.toolDeadline : parent.successorDeadline);
+      }
+    }
+    if (this.continuationSent) include(this.continuationDeadline);
+    if (this.currentId && !this.parents.get(this.currentId)?.ended) include(this.idleDeadline);
+    return deadline;
+  }
+
+  /** Settle once as unknown delivery; expiry never retries or invents a server rejection. */
+  private expire(): Error {
+    const error = new Error("Native steering continuation timed out; queued-input delivery is unknown. Do not automatically replay tools or steering input.");
+    if (!this.finished) {
+      this.finished = true;
+      this.clearTimer();
+      this.replay?.dispose();
+      this.onFailure?.(error);
+    }
+    return error;
+  }
+
+  /** Late wire activity must not win a race with an expired but not-yet-fired timer. */
+  private assertTimely(): void {
+    const deadline = this.nextDeadline();
+    if (this.finished || (deadline !== undefined && performance.now() >= deadline)) throw this.expire();
+  }
+
+  /** Arm one unrefed timer for the existing deadline, never for now plus a fresh wait. */
+  private armTimer(): void {
+    const deadline = this.finished || !this.send ? undefined : this.nextDeadline();
+    if (deadline === this.timerDeadline) return;
+    this.clearTimer();
+    if (deadline === undefined) return;
+    this.timerDeadline = deadline;
+    this.timer = setTimeout(() => {
+      this.clearTimer();
+      if (this.finished || !this.send) return;
+      const next = this.nextDeadline();
+      if (next !== undefined && performance.now() >= next) this.expire();
+      else this.armTimer(); // Early callbacks cannot shorten the monotonic bound.
+    }, Math.max(0, deadline - performance.now()));
+    this.timer.unref?.();
+  }
+  /** Check the live owner and byte limit before journaling and sending one control. */
+  private liveSend(frame: Frame): void {
+    if (!this.send || this.finished) throw new NativeSteeringError("steering_not_supported", "No active native WebSocket steering transport; this route may be disabled or using HTTP fallback.");
+    if (codexWsCreateFrameExceedsLimit(JSON.stringify(frame))) throw new NativeSteeringError("invalid_input", "Native steering frame exceeds the upstream byte limit.");
+    const rollback = this.replay?.submitted(frame);
+    try { this.send(frame); } catch (error) { rollback?.(); throw error; }
+  }
+
+  /** Send user-only input to this connection's active response under the pending cap. */
+  steer(frame: Frame): void {
+    validateSteeringFrame(frame);
+    if (!this.send || this.finished) { this.liveSend(frame); return; }
+    this.assertTimely();
+    const target = this.parents.get(frame.previous_response_id as string);
+    if (!target || frame.previous_response_id !== this.currentId || target.ended) {
+      throw new NativeSteeringError("response_not_active", "The target response is not active on this connection.");
+    }
+    if ([...this.parents.values()].reduce((n, p) => n + p.unacknowledged.length + p.accepted.size, 0) >= MAX_NATIVE_STEERS) {
+      throw new NativeSteeringError("too_many_pending_steers", "The native steering pending-submission limit was reached.");
+    }
+    // Count before send: fake transports, and some runtimes, deliver synchronously.
+    const submission = { deadline: performance.now() + NATIVE_STEERING_WAIT_MS };
+    target.unacknowledged.push(submission);
+    this.armTimer();
+    try { this.liveSend(frame); } catch (error) {
+      const index = target.unacknowledged.indexOf(submission);
+      if (index >= 0) target.unacknowledged.splice(index, 1);
+      this.armTimer();
+      throw error;
+    }
+  }
+
+  /** Retain bounded call or approval identities that authorize early saved results. */
+  private advertise(item: unknown): void {
+    const stub = outputRequirement(item);
+    if (!stub) return;
+    const key = JSON.stringify(stub);
+    if (this.advertised.has(key)) return;
+    const bytes = Buffer.byteLength(key);
+    if (this.advertised.size >= 1024 || this.advertisedBytes + bytes > 256 * 1024) {
+      throw new Error("Native steering advertised-input budget exceeded");
+    }
+    this.advertised.set(key, stub);
+    this.advertisedBytes += bytes;
+  }
+
+  /** Returns false only when an ordinary create may use normal dispatch. */
+  continue(frame: Frame): boolean {
+    if (this.finished || !this.send) return false;
+    this.assertTimely();
+    const parent = this.currentId ? this.parents.get(this.currentId) : undefined;
+    if (!parent?.ended || !this.currentId || frame.previous_response_id !== this.currentId) {
+      if (this.hasOutstanding || this.continuationSent) throw new NativeSteeringError("steering_continuation_required", "Queued steering owns this connection; wait for the successor or send the required-input continuation, or explicitly stop the turn.");
+      return false;
+    }
+    if (this.continuationSent) throw new NativeSteeringError("duplicate_continuation", "A required-input continuation was already sent for this parent.");
+    // The client is allowed to return saved results before response.steer.pending.
+    // In that case only calls actually advertised by this response authorize it.
+    const required = this.pendingParent ? this.required : [...this.advertised.values()];
+    if (!required.length) throw new NativeSteeringError("steering_continuation_required", "Wait for the automatic successor or server-identified required input.");
+    if (frame.stream_id !== this.lane || frame.generate === false) throw new NativeSteeringError("invalid_input", "The continuation must use the same WebSocket lane and generate a response.");
+    for (const [key, value] of Object.entries(frame)) {
+      if (["type", "input", "previous_response_id", "stream", "stream_id"].includes(key)) continue;
+      if (!isSteeringMutableSetting(key) && this.settings.get(key) !== fingerprint(value)) throw new NativeSteeringError("steering_settings_changed", "The native steering continuation cannot change routing, tools or non-generation settings; start a separate turn instead.");
+    }
+    if (!validSteeringSettings(frame)) throw new NativeSteeringError("invalid_input", "Invalid or oversized native steering generation settings.");
+    const input = frame.input;
+    if (!Array.isArray(input) || !input.length) throw new NativeSteeringError("invalid_input", "Supply the saved results for the required_input stubs exactly once; do not resend steering text.");
+    const used = new Set<number>();
+    for (const item of input) {
+      // An explicit continuation may carry new user input after its saved results.
+      // Reuse the narrow user-only validator so privileged roles cannot bypass routing.
+      if (record(item) && item.role === "user") {
+        validateSteeringFrame({ type: "response.steer", previous_response_id: this.currentId, input: [item] });
+        continue;
+      }
+      const match = record(item) ? required.findIndex((stub, i) => !used.has(i) && matchesRequirement(item, stub)) : -1;
+      if (match < 0) throw new NativeSteeringError("invalid_input", "Continuation input must match the pending tool-output or approval stubs.");
+      used.add(match);
+    }
+    if (used.size !== required.length) throw new NativeSteeringError("invalid_input", "Every required tool output or approval must be supplied exactly once.");
+    // Snapshot before asynchronous pacing; later caller mutation must not alter the authorized frame.
+    frame = structuredClone(frame);
+    if (this.normalizeContinuation) frame = this.normalizeContinuation(frame);
+    this.continuationSent = true;
+    this.continuationDeadline = performance.now() + NATIVE_STEERING_WAIT_MS;
+    this.armTimer();
+    try { this.liveSend(frame); } catch (error) {
+      this.continuationSent = false;
+      this.continuationDeadline = undefined;
+      this.armTimer();
+      throw error;
+    }
+    return true;
+  }
+
+  /** Called on the ordered upstream wire, BEFORE the event is published to SSE. */
+  observe(event: Frame): boolean {
+    this.assertTimely();
+    const type = event.type;
+    if (!(type === "error" && event.stream_id == null) && (event.stream_id ?? undefined) !== (this.lane ?? undefined)) throw new Error("native steering WebSocket lane mismatch");
+    const response = record(event.response) ? event.response : undefined;
+    if (type === "response.created") {
+      const id = response?.id;
+      if (!validId(id) || this.parents.has(id) || this.parents.size >= MAX_NATIVE_STEERING_RESPONSES) throw new Error("native steering response identity or chain limit violated");
+      if (this.currentId) {
+        const parent = this.parents.get(this.currentId)!;
+        if (!parent.ended || (!parent.accepted.size && !this.continuationSent)) throw new Error("unexpected native steering successor");
+        if (response?.previous_response_id != null && response.previous_response_id !== this.currentId) throw new Error("native steering successor parent mismatch");
+        parent.accepted.clear(); // response.created, not accepted, is the commit point.
+      }
+      this.currentId = id;
+      this.parents.set(id, { unacknowledged: [], accepted: new Set(), ended: false });
+      this.pendingParent = undefined;
+      this.required = [];
+      this.advertised.clear();
+      this.advertisedBytes = 0;
+      this.continuationSent = false;
+      this.continuationDeadline = undefined;
+      this.correlation?.finish();
+      this.correlation = new CodexWsCorrelation(true, () => false);
+    }
+    if (typeof type === "string" && type.startsWith("response.steer.")) {
+      const steer = record(event.steer) ? event.steer : undefined;
+      const parent = typeof steer?.previous_response_id === "string" ? this.parents.get(steer.previous_response_id) : undefined;
+      if (!parent) throw new Error("native steering acknowledgement has an unknown parent");
+      if (type === "response.steer.accepted") {
+        if (!validId(steer?.id) || parent.unacknowledged.length < 1 || parent.accepted.has(steer.id)) throw new Error("unexpected native steering acceptance");
+        parent.unacknowledged.shift();
+        parent.accepted.add(steer.id);
+      } else if (type === "response.steer.failed") {
+        if (steer?.id !== undefined) {
+          if (!validId(steer.id) || !parent.accepted.delete(steer.id)) throw new Error("unexpected native steering failure");
+        } else {
+          if (parent.unacknowledged.length < 1) throw new Error("unexpected native steering rejection");
+          parent.unacknowledged.shift();
+        }
+      } else if (type === "response.steer.pending") {
+        if (!validId(steer?.id) || !parent.accepted.has(steer.id) || !parent.ended
+          || steer.previous_response_id !== this.currentId) throw new Error("unexpected native steering pending event");
+        if (event.reason === "waiting_for_required_input") {
+          if (!Array.isArray(event.required_input) || !event.required_input.length || event.required_input.length > 1024
+            || event.required_input.some(item => !record(item) || typeof item.type !== "string" || item.type === "message")
+            || Buffer.byteLength(JSON.stringify(event.required_input)) > 256 * 1024) throw new Error("native steering required-input budget or schema violated");
+          if (this.pendingParent && stable(this.required) !== stable(event.required_input)) throw new Error("native steering required-input stubs changed");
+          parent.toolDeadline ??= performance.now() + NATIVE_STEERING_TOOL_WAIT_MS;
+          this.pendingParent = this.currentId;
+          this.required = event.required_input as Frame[];
+        }
+        // Unknown reasons are preserved, not converted into a create or success.
+      } else throw new Error("unsupported native steering control event");
+    } else {
+      this.correlation?.accept({ ...event, stream_id: undefined });
+      if (type === "response.output_item.done") this.advertise(event.item);
+      if (type === "response.completed" || type === "response.failed" || type === "response.incomplete") {
+        if (!this.currentId || response?.id !== this.currentId) throw new Error("native steering terminal identity mismatch");
+        const parent = this.parents.get(this.currentId)!;
+        parent.ended = true;
+        parent.successorDeadline ??= performance.now() + NATIVE_STEERING_WAIT_MS;
+        if (Array.isArray(response.output)) for (const item of response.output) this.advertise(item);
+      }
+    }
+    if (type === "error") this.finished = true;
+    else this.finished = this.currentId !== undefined && this.parents.get(this.currentId)!.ended && !this.hasOutstanding && !this.continuationSent;
+    if (this.currentId && !this.parents.get(this.currentId)!.ended) this.idleDeadline = performance.now() + this.idleMs;
+    this.armTimer();
+    this.replay?.observe(event);
+    return this.finished;
+  }
+}

package/src/server/responses/native-tool-results.ts

@@ -0,0 +1,130 @@
+import {
+  injectionError, injectionFingerprint, injectionId, injectionRecord as record,
+  MAX_NATIVE_INJECTION_CALLS, type InjectionFrame as Frame,
+} from "./native-injection-protocol";
+
+export type NativeToolOutput = string | Frame[];
+export type NativeToolResult = {
+  type: "function_call_output" | "custom_tool_call_output";
+  call_id: string;
+  output: NativeToolOutput;
+  id?: string;
+  caller?: Frame | null;
+};
+export type NativeApprovalResult = {
+  type: "mcp_approval_response";
+  approval_request_id: string;
+  approve: boolean;
+  reason?: string | null;
+  id?: string;
+};
+export type NativeSavedResult = NativeToolResult | NativeApprovalResult;
+export type NativeToolRequirement = { key: string; type: NativeSavedResult["type"]; identity: string; caller: string };
+export const MAX_NATIVE_RESULT_PARTS = 1024;
+
+/** Fixed diagnostics deliberately exclude caller identifiers and saved result bodies. */
+function invalid(): never {
+  return injectionError("invalid_injection", "Invalid saved tool result, content part, caller or approval decision.");
+}
+/** Reject unknown fields rather than silently discarding them or widening the wire schema. */
+function keys(value: Frame, allowed: string[]): void {
+  if (Object.keys(value).some(key => !allowed.includes(key))) invalid();
+}
+/** References remain opaque: no local file reads, URL downloads or cross-account uploads. */
+function source(value: unknown): boolean {
+  return typeof value === "string" && value.length > 0;
+}
+/** Validate a supplied caller while treating absent and explicit direct callers alike. */
+function caller(value: unknown): string {
+  if (value == null) return injectionFingerprint({ type: "direct" });
+  if (!record(value)) return invalid();
+  if (value.type === "direct") keys(value, ["type"]);
+  else if (value.type === "program" && injectionId(value.caller_id)) keys(value, ["type", "caller_id"]);
+  else return invalid();
+  return injectionFingerprint(value);
+}
+/** Bound rich result shape without coercing it to text or fetching its content. */
+function output(value: unknown): void {
+  if (typeof value === "string") return;
+  if (!Array.isArray(value) || value.length > MAX_NATIVE_RESULT_PARTS) invalid();
+  for (const part of value) {
+    if (!record(part)) invalid();
+    if (part.prompt_cache_breakpoint !== undefined) {
+      if (!record(part.prompt_cache_breakpoint) || part.prompt_cache_breakpoint.mode !== "explicit") invalid();
+      keys(part.prompt_cache_breakpoint, ["mode"]);
+    }
+    if (part.type === "input_text") {
+      keys(part, ["type", "text", "prompt_cache_breakpoint"]);
+      if (typeof part.text !== "string") invalid();
+    } else if (part.type === "input_image") {
+      keys(part, ["type", "image_url", "file_id", "detail", "prompt_cache_breakpoint"]);
+      if (!["auto", "low", "high", "original"].includes(String(part.detail))) invalid();
+      if (Number(source(part.image_url)) + Number(source(part.file_id)) !== 1) invalid();
+      for (const key of ["image_url", "file_id"]) if (part[key] != null && !source(part[key])) invalid();
+      if (part.file_id != null && !injectionId(part.file_id)) invalid();
+    } else if (part.type === "input_file") {
+      keys(part, ["type", "file_id", "file_url", "file_data", "filename", "detail", "prompt_cache_breakpoint"]);
+      if ([part.file_id, part.file_url, part.file_data].filter(source).length !== 1) invalid();
+      for (const key of ["file_id", "file_url", "file_data", "filename"]) if (part[key] != null && !source(part[key])) invalid();
+      if (part.file_id != null && !injectionId(part.file_id)) invalid();
+      if (part.file_data != null && !source(part.filename)) invalid();
+      if (part.detail !== undefined && !["auto", "low", "high"].includes(String(part.detail))) invalid();
+    } else invalid();
+  }
+}
+/** Separate call IDs from approval IDs so identical spellings cannot authorize each other. */
+export function nativeResultKey(value: NativeSavedResult): string {
+  return JSON.stringify([value.type === "mcp_approval_response" ? "approval" : "call",
+    value.type === "mcp_approval_response" ? value.approval_request_id : value.call_id]);
+}
+/** Parse the wider continuation schema; this does NOT grant response.inject support. */
+export function nativeSavedResults(value: unknown): NativeSavedResult[] {
+  if (!Array.isArray(value) || !value.length || value.length > MAX_NATIVE_INJECTION_CALLS) invalid();
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (!record(item) || (item.id !== undefined && !injectionId(item.id))) invalid();
+    if (item.type === "mcp_approval_response") {
+      keys(item, ["type", "approval_request_id", "approve", "reason", "id"]);
+      if (!injectionId(item.approval_request_id) || typeof item.approve !== "boolean"
+        || (item.reason != null && typeof item.reason !== "string")) invalid();
+    } else {
+      keys(item, ["type", "call_id", "output", "caller", "id"]);
+      if (!["function_call_output", "custom_tool_call_output"].includes(String(item.type)) || !injectionId(item.call_id)) invalid();
+      output(item.output); caller(item.caller);
+    }
+    const key = nativeResultKey(item as NativeSavedResult);
+    if (seen.has(key)) injectionError("duplicate_injection", "Each saved result or approval must occur exactly once.");
+    seen.add(key);
+  }
+  return value as NativeSavedResult[];
+}
+/** Bind a client-owned call or approval to its type, caller and server-supplied identity. */
+export function nativeToolRequirement(item: unknown): NativeToolRequirement | undefined {
+  if (!record(item)) return;
+  let type: NativeSavedResult["type"];
+  let key: string;
+  if (item.type === "mcp_approval_request") {
+    if (!injectionId(item.id)) invalid();
+    type = "mcp_approval_response"; key = JSON.stringify(["approval", item.id]);
+  } else {
+    if (item.type !== "function_call" && item.type !== "custom_tool_call") return;
+    if (!injectionId(item.call_id) || (item.id !== undefined && !injectionId(item.id))) invalid();
+    type = item.type === "function_call" ? "function_call_output" : "custom_tool_call_output";
+    key = JSON.stringify(["call", item.call_id]);
+  }
+  const origin = caller(item.caller);
+  // Retain only a bounded digest of provenance, never another copy of the call body.
+  return { key, type, caller: origin, identity: injectionFingerprint({ type, id: item.id, name: item.name,
+    server_label: item.server_label, arguments: item.arguments, input: item.input, caller: origin, agent: item.agent }) };
+}
+/** Approval decisions must be supplied by the caller; no default or synthetic approval exists. */
+export function nativeResultMatches(item: NativeSavedResult, required: NativeToolRequirement): boolean {
+  return nativeResultKey(item) === required.key && item.type === required.type
+    && (item.type === "mcp_approval_response" || caller(item.caller) === required.caller);
+}
+/** Compare content rather than object identity; retain content-array order and caller identity. */
+export function nativeResultFingerprint(item: NativeSavedResult): string {
+  return injectionFingerprint(item.type === "mcp_approval_response"
+    ? { type: item.type, approval_request_id: item.approval_request_id, approve: item.approve, reason: item.reason }
+    : { type: item.type, call_id: item.call_id, output: item.output, caller: caller(item.caller) });
+}

package/src/server/responses/passthrough-delivery.ts

@@ -1,3 +1,4 @@
+import { isNativeControlResponse } from "./native-response-control";
 import type { ResponsesRequestContext, ResponsesAdmissionState } from "./core-options";
 import type { PreparedResponsesRequest } from "./request-prepare";
 import type { ResponsesTransport } from "./request-transport";
@@ -312,6 +313,16 @@ export async function deliverPassthroughResponse(
       });
     }
 
+    if (options.nativeControl && isNativeControlResponse(upstreamResponse) && upstreamResponse.body) {
+      // A native chain carries several response terminals. Ordinary SSE repair,
+      // cancellation-on-terminal and local previous-response replay are single-response
+      // contracts and would truncate it. Keep the bounded upstream as the sole reader.
+      options.nativeControl.relayActive = true;
+      commitReasoningReplayServingRoute(nativeExchange.request.headers);
+      const body = trackStreamLifetime(upstreamResponse.body, upstream, undefined, options.turnAdmissionLease);
+      return new Response(body, { status: upstreamResponse.status, headers });
+    }
+
     // Bun#32111 workaround: passthrough SSE uses tee()+native relay to avoid the
     // async-pull segfault on Windows. Branch[0] goes directly to the Response (Bun
     // native relay, never enters JS Sink.write); branch[1] is consumed in the

package/src/server/responses/passthrough-dispatch.ts

@@ -1,3 +1,7 @@
+import { createSteeringSettingsNormalizer } from "./native-steering-policy";
+import { nativeResponseControlEligible } from "./native-response-control";
+import { NativeInjectionReplay } from "./native-injection-replay";
+import { NativeSteeringReplay } from "./native-steering-replay";
 import type {
   ResponsesRequestContext,
   ResponsesAdmissionState,
@@ -10,7 +14,7 @@ import type { ResponsesSendBudget } from "./request-send-budget";
 import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
 import { codexSafetyBufferingFilterOptions, terminalStatusFromParsed } from "../relay";
 import { imageGenToolCallAliases } from "../responses-image-gen-repair";
-import { rememberResponseState } from "../../responses/state";
+import { rememberResponseState, isBodyNonPersistable } from "../../responses/state";
 import {
   currentTurnWireToolCatalogBody,
   hasExplicitWireToolCatalog,
@@ -251,6 +255,19 @@ export async function preparePassthroughExchange(
       ? (response: { id?: unknown; output?: unknown; status?: unknown }) =>
         rememberResponseState(parsed._rawBody, response, undefined, responseStateOptions(true))
       : undefined;
+    if (options.nativeControl && nativeResponseControlEligible(route.provider, options.nativeControl)
+      && options.inboundTransport === "websocket" && !options.comboAttempt) {
+      const body = parsed._rawBody as Record<string, unknown>;
+      if (options.nativeControl.kind === "steering") {
+        options.nativeControl.normalizeContinuation = createSteeringSettingsNormalizer(parsed, route, config, req.headers);
+      }
+      const Replay = options.nativeControl.kind === "injection" ? NativeInjectionReplay : NativeSteeringReplay;
+      options.nativeControl.replayFactory = () => new Replay(body.input, (input, response) => {
+        if (passthroughRecordEligible && !isBodyNonPersistable(body)) {
+          rememberResponseState({ ...body, input }, response, undefined, responseStateOptions(true));
+        }
+      });
+    }
     if (parsed.previousResponseId && !parsed._previousResponseInputExpanded) {
       console.warn(
         `[responses] previous_response_id ${parsed.previousResponseId} not found in local replay state `
@@ -772,6 +789,9 @@ export async function preparePassthroughExchange(
             body: request.body,
           }, recovery), upstream.signal, connectMs, parsed.stream,
             providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+              nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
+                && responseEffects.plaintextV2AgentMessageToolNames.size === 0
+                ? options.nativeControl : undefined,
               dispatchOverride: oauthDispatch(request),
               providerName: route.providerName,
               modelId: route.modelId,
@@ -868,6 +888,9 @@ export async function preparePassthroughExchange(
               body: request.body,
             }, innerRecovery), upstream.signal, connectMs, parsed.stream,
               providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+              nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
+                && responseEffects.plaintextV2AgentMessageToolNames.size === 0
+                ? options.nativeControl : undefined,
               dispatchOverride: oauthDispatch(request),
                 providerName: route.providerName,
                 modelId: route.modelId,
@@ -974,6 +997,9 @@ export async function preparePassthroughExchange(
           // here on is a genuine transport attempt.
           storedPoolReplayDispatchNotifier(
             providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+              nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
+                && responseEffects.plaintextV2AgentMessageToolNames.size === 0
+                ? options.nativeControl : undefined,
               dispatchOverride: oauthDispatch(request),
               providerName: route.providerName,
               modelId: route.modelId,
@@ -1095,6 +1121,9 @@ export async function preparePassthroughExchange(
               body: request.body,
             }, recovery), upstream.signal, connectMs, parsed.stream,
               providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+              nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
+                && responseEffects.plaintextV2AgentMessageToolNames.size === 0
+                ? options.nativeControl : undefined,
               dispatchOverride: oauthDispatch(request),
                 providerName: route.providerName,
                 modelId: route.modelId,
@@ -1217,6 +1246,9 @@ export async function preparePassthroughExchange(
               body: request.body,
             }, recovery), upstream.signal, connectMs, parsed.stream,
               providerFetch(route.provider, options.codexWsRuntimeIdentity, {
+              nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
+                && responseEffects.plaintextV2AgentMessageToolNames.size === 0
+                ? options.nativeControl : undefined,
               dispatchOverride: oauthDispatch(request),
                 providerName: route.providerName,
                 modelId: route.modelId,