@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/server/responses/fetch-helpers.ts

@@ -1,3 +1,4 @@
+import type { NativeResponseControl } from "./native-response-control";
 import type { Server } from "bun";
 import {
   codexWsUpstreamFetch,
@@ -10,6 +11,7 @@ import type { WsData } from "../ws-bridge";
 import { waitForProviderRequestSlot } from "../../providers/request-pacing";
 import { withUpstreamHttpVersion } from "../../lib/upstream-http-version";
 import type { CodexWsQuotaObserver } from "./codex-ws-metadata";
+import { configuredOutboundFetch } from "../../lib/proxy-env";
 
 export { withUpstreamHttpVersion };
 
@@ -43,6 +45,31 @@ export function safeOriginLabel(url: string): string {
   }
 }
 
+/**
+ * Check whether a target host should bypass Bun's keep-alive pool reuse.
+ * Configured via the `OCX_FRESH_CONNECTION_HOSTS` environment variable (comma-separated).
+ */
+export function wantsFreshConnection(
+  input: Parameters<typeof globalThis.fetch>[0],
+  hostsEnv = process.env.OCX_FRESH_CONNECTION_HOSTS,
+): boolean {
+  if (!hostsEnv) return false;
+  try {
+    const rawUrl = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const host = new URL(rawUrl).hostname.toLowerCase();
+    const targets = hostsEnv
+      .split(",")
+      .map(h => h.trim().toLowerCase().replace(/^\.+/, ""))
+      .filter(Boolean);
+    for (const target of targets) {
+      if (host === target || host.endsWith(`.${target}`)) return true;
+    }
+  } catch {
+    /* unparseable target URL keeps default connection behavior */
+  }
+  return false;
+}
+
 
 
 export interface PaceAwareFetch {
@@ -52,7 +79,40 @@ export interface PaceAwareFetch {
 
 export type ProviderFetch = typeof globalThis.fetch & PaceAwareFetch;
 
+/**
+ * Apply the physical-send connection policy to whichever fetch actually performs the send.
+ *
+ * The executor `providerFetch` builds is not the only physical boundary. A `dispatchOverride`
+ * that revalidates credentials re-reads `route.provider.fetch` at send time -- reselection can
+ * install a different provider transport after this wrapper was constructed -- and then calls
+ * that fetch directly instead of the supplied executor. Keeping the policy inside the executor
+ * alone therefore left every provider-scoped transport reusing a pooled socket for a host the
+ * operator had named in `OCX_FRESH_CONNECTION_HOSTS` (#4992). The policy belongs around the
+ * selected fetch so it follows the selection rather than the construction.
+ *
+ * Idempotent on purpose: an override that hands the send back to the supplied executor passes
+ * through here twice, and both passes derive the same headers from the same wire URL.
+ */
+export function sendWithConnectionPolicy(
+  physicalFetch: typeof globalThis.fetch,
+  input: Parameters<typeof globalThis.fetch>[0],
+  init?: RequestInit,
+): Promise<Response> {
+  const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+  const fresh = wantsFreshConnection(input);
+  if (fresh) {
+    headers.set("Connection", "close");
+  }
+  return physicalFetch(input, {
+    ...init,
+    headers,
+    redirect: "manual",
+    ...(fresh ? { keepalive: false } : {}),
+  });
+}
+
 export interface ProviderFetchOptions {
+  nativeControl?: NativeResponseControl;
   providerName?: string;
   modelId?: string;
   /** One pacing slot was acquired immediately before this fetch wrapper was created. */
@@ -70,7 +130,11 @@ export function providerFetch(
   runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
   options: ProviderFetchOptions = {},
 ): ProviderFetch {
-  const base = (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? globalThis.fetch;
+  const configuredFetch = Object.assign(
+    (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => configuredOutboundFetch(input, init),
+    { preconnect: globalThis.fetch.preconnect?.bind(globalThis.fetch) },
+  ) as typeof globalThis.fetch;
+  const base = (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? configuredFetch;
   const preconnect = (...args: Parameters<typeof globalThis.fetch.preconnect>): void => {
     base.preconnect?.(...args);
   };
@@ -78,11 +142,15 @@ export function providerFetch(
   // Return the original 3xx so the response owner retains its retry/health/relay contract.
   const dispatch = Object.assign(
     (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) =>
-      base(input, { ...init, redirect: "manual" }),
+      sendWithConnectionPolicy(base, input, init),
     { preconnect },
   ) as typeof globalThis.fetch;
   const httpFetch = Object.assign(
     async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
+      // The hook inspects the outgoing headers and refuses the send by throwing; it is not a
+      // mutator, and the copy it receives is deliberately not threaded onward. `Connection`
+      // is decided inside `dispatch`, which runs after this, so the fresh-connection policy
+      // wins regardless of what any caller or hook put in the header.
       options.beforeDispatch?.(new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined)));
       const dispatchInit = { ...withUpstreamHttpVersion(input, init, provider), timeout: 0 };
       return options.dispatchOverride
@@ -101,7 +169,8 @@ export function providerFetch(
       // used, protocol pin included: a WS turn that falls back is serving the
       // request over HTTP, and dropping the provider's `upstreamHttpVersion`
       // there would silently negotiate a transport the operator ruled out.
-      return codexWsUpstreamFetch(input, init, httpFetch, runtime, options.onCodexWsQuota, options.beforeDispatch);
+      return codexWsUpstreamFetch(input, init, httpFetch, runtime, options.onCodexWsQuota, options.beforeDispatch, options.nativeControl,
+        () => waitForPacing(init.signal ?? undefined));
     }
     return httpFetch(input, init);
   };

package/src/server/responses/native-injection-protocol.ts

@@ -0,0 +1,42 @@
+import { nativeResponseRecord as injectionRecord } from "./native-response-json";
+export { nativeResponseRecord as injectionRecord, nativeResponseFingerprint as injectionFingerprint } from "./native-response-json";
+import { CODEX_WS_ID_MAX_BYTES } from "./codex-ws-correlation";
+import { NativeSteeringError } from "./native-steering";
+
+export type InjectionFrame = Record<string, unknown>;
+export type FunctionResult = { type: "function_call_output"; call_id: string; output: string };
+export const MAX_NATIVE_INJECTIONS = 32;
+export const MAX_NATIVE_INJECTION_BYTES = 8 * 1024 * 1024;
+export const MAX_NATIVE_INJECTION_CALLS = 1024;
+export const NATIVE_INJECTION_ACK_MS = 90_000;
+export const NATIVE_INJECTION_TOOL_MS = 30 * 60_000;
+
+/** Bound identities and exclude control characters, without changing their spelling. */
+export function injectionId(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);
+}
+/** Throw only fixed, content-free errors, never tool output or caller identifiers. */
+export function injectionError(code: string, message: string): never {
+  throw new NativeSteeringError(code, message);
+}
+/** First-version contract: nonempty arrays of string-valued, client-owned function results. */
+export function injectionResults(value: unknown): FunctionResult[] {
+  if (!Array.isArray(value) || !value.length || value.length > MAX_NATIVE_INJECTION_CALLS) {
+    injectionError("invalid_injection", "Supply a bounded, nonempty array of saved function results.");
+  }
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (!injectionRecord(item) || item.type !== "function_call_output" || !injectionId(item.call_id)
+      || typeof item.output !== "string" || Object.keys(item).some(key => !["type", "call_id", "output"].includes(key))) {
+      injectionError("invalid_injection", "Only function_call_output with call_id and string output is supported; no messages or hosted-tool results.");
+    }
+    if (seen.has(item.call_id)) injectionError("duplicate_injection", "A function result must occur exactly once.");
+    seen.add(item.call_id);
+  }
+  return value as FunctionResult[];
+}
+/** Detect explicit multi-agent opt-in without inferring it from the model name. */
+export function isInjectionRequest(frame: InjectionFrame): boolean {
+  return injectionRecord(frame.multi_agent) && frame.multi_agent.enabled === true;
+}

package/src/server/responses/native-injection-replay.ts

@@ -0,0 +1,105 @@
+import { MAX_NATIVE_STEERING_REPLAY_BYTES, type NativeSteeringReplayObserver } from "./native-steering-replay";
+import { injectionRecord as record, type InjectionFrame as Frame, type FunctionResult } from "./native-injection-protocol";
+
+import { nativeResultFingerprint } from "./native-tool-results";
+import { nativeResponseOutput } from "./native-response-output";
+
+/** A bounded journal of accepted tool results, independent of user steering history. */
+export class NativeInjectionReplay implements NativeSteeringReplayObserver {
+  private prefix: unknown[];
+  private bytes = 0;
+  private current?: string;
+  private output = new Map<number, Frame>();
+  private accepted = new Map<string, FunctionResult>();
+  private pending?: FunctionResult[];
+  private pendingBytes = 0;
+  private acceptedBatchBytes: number[] = [];
+  private explicit: unknown[] = [];
+  private previous: unknown[] = [];
+
+  /** Capture a private initial prefix; existing persistence eligibility is checked by the caller. */
+  constructor(input: unknown, private readonly remember: (input: unknown[], response: Frame) => void) {
+    this.prefix = typeof input === "string"
+      ? [{ type: "message", role: "user", content: [{ type: "input_text", text: input }] }]
+      : Array.isArray(input) ? [...input] : [];
+    this.reserve(this.prefix);
+  }
+  /** Charge serialized bytes, refusing rather than truncating an over-budget transcript. */
+  private reserve(value: unknown): number {
+    const bytes = Buffer.byteLength(JSON.stringify(value));
+    if (this.bytes + bytes > MAX_NATIVE_STEERING_REPLAY_BYTES) throw new Error("Native injection replay exceeded its history budget.");
+    this.bytes += bytes;
+    return bytes;
+  }
+  /** Journal before physical send, with rollback usable only for a known unsent frame. */
+  submitted(frame: Frame): () => void {
+    const input = Array.isArray(frame.input) ? structuredClone(frame.input) : [];
+    const bytes = this.reserve(input);
+    if (frame.type === "response.inject") { this.pending = input as FunctionResult[]; this.pendingBytes = bytes; }
+    else this.explicit = input;
+    return () => {
+      if (frame.type === "response.inject") { this.pending = undefined; this.pendingBytes = 0; }
+      else this.explicit = [];
+      this.bytes -= bytes;
+    };
+  }
+  /** Keep wire output order and insert each accepted result after its owning function call. */
+  private completedOutput(response: Frame): unknown[] {
+    const output = nativeResponseOutput(this.output, response.output);
+    const echoed = new Set<string>();
+    for (const item of output) {
+      if (!record(item) || item.type !== "function_call_output" || typeof item.call_id !== "string") continue;
+      const accepted = this.accepted.get(item.call_id);
+      if (accepted) {
+        if (echoed.has(item.call_id) || nativeResultFingerprint(item as FunctionResult) !== nativeResultFingerprint(accepted)) throw new Error("Native injection replay result mismatch.");
+        echoed.add(item.call_id);
+      }
+    }
+    const merged: unknown[] = [];
+    const found = new Set(echoed);
+    for (const item of output) {
+      merged.push(item);
+      if (!record(item) || item.type !== "function_call" || typeof item.call_id !== "string") continue;
+      const accepted = this.accepted.get(item.call_id);
+      if (accepted && !found.has(item.call_id)) { merged.push(accepted); found.add(item.call_id); }
+    }
+    if (found.size !== this.accepted.size) throw new Error("Native injection replay is missing an accepted result's call.");
+    return merged;
+  }
+  /** Terminals are supplied by the owner only after all injection acknowledgements settle. */
+  observe(frame: Frame): void {
+    if (frame.type === "response.created") {
+      if (this.current) {
+        for (const item of this.previous) this.prefix.push(item);
+        for (const item of this.explicit) this.prefix.push(item);
+      }
+      this.current = String(record(frame.response) ? frame.response.id : "");
+      this.output.clear(); this.accepted.clear(); this.acceptedBatchBytes = []; this.explicit = []; this.previous = [];
+    } else if (frame.type === "response.inject.created" || frame.type === "response.inject.failed") {
+      if (!this.pending) throw new Error("Native injection replay acknowledgement has no pending input.");
+      if (frame.type === "response.inject.created") {
+        for (const item of this.pending) this.accepted.set(item.call_id, item);
+        this.acceptedBatchBytes.push(this.pendingBytes);
+      } else this.bytes -= this.pendingBytes;
+      this.pending = undefined; this.pendingBytes = 0;
+    } else if (frame.type === "response.output_item.done") {
+      if (!Number.isSafeInteger(frame.output_index) || (frame.output_index as number) < 0
+        || (frame.output_index as number) > 10_000 || !record(frame.item)) throw new Error("Native injection replay output identity is invalid.");
+      const old = this.output.get(frame.output_index as number);
+      if (old) this.bytes -= Buffer.byteLength(JSON.stringify(old));
+      this.reserve(frame.item); this.output.set(frame.output_index as number, structuredClone(frame.item));
+    } else if (record(frame.response) && ["response.completed", "response.failed", "response.incomplete"].includes(String(frame.type))) {
+      if (this.pending) throw new Error("Native injection replay cannot commit an unacknowledged result.");
+      const output = this.completedOutput(frame.response);
+      for (const item of this.output.values()) this.bytes -= Buffer.byteLength(JSON.stringify(item));
+      for (const bytes of this.acceptedBatchBytes) this.bytes -= bytes;
+      this.reserve(output); this.output.clear(); this.accepted.clear(); this.acceptedBatchBytes = []; this.previous = output;
+      if (frame.type === "response.completed") this.remember(this.prefix, { ...frame.response, output });
+    }
+  }
+  /** Drop all retained bodies at cancellation, connection teardown or unknown delivery. */
+  dispose(): void {
+    this.prefix = []; this.output.clear(); this.accepted.clear(); this.pending = undefined; this.pendingBytes = 0; this.acceptedBatchBytes = [];
+    this.explicit = []; this.previous = []; this.bytes = 0;
+  }
+}

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

@@ -0,0 +1,242 @@
+import { CodexWsCorrelation } from "./codex-ws-correlation";
+import type { NativeResponseControl } from "./native-response-control";
+import type { NativeSteeringReplayObserver } from "./native-steering-replay";
+import {
+  injectionError, injectionFingerprint, injectionId, injectionRecord as record, injectionResults,
+  isInjectionRequest, MAX_NATIVE_INJECTIONS, MAX_NATIVE_INJECTION_BYTES, MAX_NATIVE_INJECTION_CALLS,
+  NATIVE_INJECTION_ACK_MS, NATIVE_INJECTION_TOOL_MS,
+  type FunctionResult, type InjectionFrame as Frame,
+} from "./native-injection-protocol";
+
+import { nativeResultKey, nativeResultMatches, nativeResultFingerprint, nativeSavedResults, nativeToolRequirement,
+  type NativeToolRequirement } from "./native-tool-results";
+
+type Call = { requirement: NativeToolRequirement; state: "available" | "queued" | "accepted" | "failed"; result?: string; recoverable?: boolean };
+type Submission = { frame: Frame; results: FunctionResult[]; bytes: number };
+const ENVELOPE = new Set(["type", "input", "previous_response_id", "stream", "stream_id"]);
+
+/**
+ * Injection-only multi-agent owner. Exactly one injection is on the physical wire
+ * at a time because created acknowledgements contain a response ID, not a request
+ * ID. Queued submissions, terminal delivery and caller-owned recovery are distinct.
+ */
+export class NativeInjectionChannel implements NativeResponseControl {
+  readonly kind = "injection" as const;
+  relayActive = false;
+  replayFactory?: () => NativeSteeringReplayObserver;
+  private replay?: NativeSteeringReplayObserver;
+  private send?: (frame: Frame) => void;
+  private onFailure?: (error: Error) => void;
+  private currentId?: string;
+  private correlation?: CodexWsCorrelation;
+  private terminal?: Frame;
+  private terminalRecorded = false;
+  private continuationSent = false;
+  private finished = false;
+  private everAttached = false;
+  private readonly seen = new Set<string>();
+  private readonly calls = new Map<string, Call>();
+  private callBytes = 0;
+  private readonly queue: Submission[] = [];
+  private queueBytes = 0;
+  private inFlight?: Submission;
+  private lastAckSequence = -1;
+  private ackTimer?: ReturnType<typeof setTimeout>;
+  private idleTimer?: ReturnType<typeof setTimeout>;
+  private readonly settings = new Map<string, string>();
+  private readonly lane: unknown;
+
+  /** Pin the original settings and lane; construction never opens a connection. */
+  constructor(initial: Frame, private readonly idleMs = 300_000,
+    private readonly deadlines = { ackMs: NATIVE_INJECTION_ACK_MS, toolMs: NATIVE_INJECTION_TOOL_MS }) {
+    if (!isInjectionRequest(initial)) injectionError("injection_not_supported", "Native injection requires explicit multi_agent.enabled.");
+    this.lane = initial.stream_id ?? undefined;
+    for (const [key, value] of Object.entries(initial)) if (!ENVELOPE.has(key)) this.settings.set(key, injectionFingerprint(value));
+  }
+  /** Report that the real dispatch boundary has selected this owner. */
+  get attached(): boolean { return this.everAttached; }
+  /** A terminal is not final until submitted results have acknowledgements. */
+  get ended(): boolean { return this.finished; }
+
+  /** Attach once, after routing/auth/admission, retaining no global response-ID lookup. */
+  attach(send: (frame: Frame) => void, fail: (error: Error) => void): () => void {
+    if (this.everAttached) throw new Error("Native injection transport is already owned.");
+    this.replay = this.replayFactory?.();
+    this.send = send; this.onFailure = fail; this.everAttached = true;
+    return () => {
+      if (this.send !== send) return;
+      this.send = undefined; this.onFailure = undefined; this.finished = true;
+      clearTimeout(this.ackTimer); clearTimeout(this.idleTimer);
+      this.correlation?.finish(); this.calls.clear(); this.seen.clear(); this.queue.length = 0;
+      this.inFlight = undefined; this.queueBytes = 0; this.callBytes = 0; this.terminal = undefined;
+      this.replay?.dispose(); this.replay = undefined;
+    };
+  }
+  /** Never reinterpret user steering as a function result, or silently mix beta modes. */
+  steer(_frame: Frame): never {
+    return injectionError("native_control_mode_mismatch", "This multi-agent turn owns an injection-only channel; start a separate turn for steering.");
+  }
+  /** Abort unknown-delivery state without HTTP fallback, resends or invented acceptance. */
+  private fail(): void {
+    this.finished = true;
+    clearTimeout(this.ackTimer); clearTimeout(this.idleTimer);
+    this.onFailure?.(new Error("Native injection transport failed or timed out; delivery is unknown. Do not automatically resend or rerun tools."));
+  }
+  /** Require the same live owner; an unbound or detached channel cannot authorize a send. */
+  private live(): void {
+    if (!this.send || this.finished) injectionError("injection_not_supported", "No live native injection transport is available on this route.");
+  }
+  /** Advertise client-owned function/custom calls and approvals, never hosted execution. */
+  private advertise(item: unknown): void {
+    const requirement = nativeToolRequirement(item);
+    if (!requirement) return;
+    const old = this.calls.get(requirement.key);
+    if (old) {
+      if (old.requirement.identity !== requirement.identity) throw new Error("Native result call identity was reused.");
+      return;
+    }
+    const bytes = Buffer.byteLength(JSON.stringify(requirement));
+    if (this.calls.size >= MAX_NATIVE_INJECTION_CALLS || this.callBytes + bytes > 256 * 1024) throw new Error("Native injection call budget exceeded.");
+    this.calls.set(requirement.key, { requirement, state: "available" }); this.callBytes += bytes;
+  }
+  /** Queue validated saved results; reserve each call before any possibly synchronous send. */
+  inject(frame: Frame): void {
+    this.live();
+    if (frame.type !== "response.inject" || !injectionId(frame.response_id)
+      || Object.keys(frame).some(key => !["type", "response_id", "input", "stream_id"].includes(key))) {
+      injectionError("invalid_injection", "Invalid native injection envelope.");
+    }
+    if (frame.response_id !== this.currentId || (frame.stream_id ?? undefined) !== this.lane || this.continuationSent) {
+      injectionError("injection_response_mismatch", "Injection must target the current response and lane on this connection.");
+    }
+    const results = injectionResults(frame.input);
+    for (const item of results) {
+      const call = this.calls.get(nativeResultKey(item));
+      if (!call || !nativeResultMatches(item, call.requirement)) injectionError("injection_call_not_found", "The result does not match a completed function call on this connection.");
+      if (call.state !== "available") injectionError("duplicate_injection", "This function result was already submitted; do not replay it.");
+    }
+    const text = JSON.stringify(frame);
+    const bytes = Buffer.byteLength(text);
+    if (this.queue.length >= MAX_NATIVE_INJECTIONS || bytes + this.queueBytes > MAX_NATIVE_INJECTION_BYTES) {
+      injectionError("injection_queue_full", "Native injection queue count or byte limit reached; no result was sent.");
+    }
+    // Detach from caller-owned objects before keeping data across asynchronous callbacks.
+    const copy = JSON.parse(text) as Frame;
+    const submission = { frame: copy, results: copy.input as FunctionResult[], bytes };
+    for (const item of results) this.calls.get(nativeResultKey(item))!.state = "queued";
+    this.queue.push(submission); this.queueBytes += bytes;
+    this.pump();
+  }
+  /** Dispatch one queued frame; unrelated output cannot reset its acknowledgement deadline. */
+  private pump(): void {
+    if (this.inFlight || !this.queue.length || this.finished) return;
+    this.live();
+    const submission = this.queue[0];
+    this.inFlight = submission;
+    this.ackTimer = setTimeout(() => this.fail(), this.deadlines.ackMs);
+    this.ackTimer.unref?.();
+    try {
+      this.replay?.submitted(submission.frame);
+      this.send!(submission.frame);
+    } catch {
+      this.fail();
+      injectionError("injection_delivery_unknown", "Injection dispatch failed; do not automatically resend or rerun tools.");
+    }
+  }
+  /** Match an acknowledgement to the sole in-flight frame, before releasing the next send. */
+  private acknowledge(event: Frame): void {
+    const pending = this.inFlight;
+    if (!pending || event.response_id !== this.currentId || !Number.isSafeInteger(event.sequence_number)
+      || (event.sequence_number as number) <= this.lastAckSequence) throw new Error("Native injection acknowledgement identity mismatch.");
+    const failed = event.type === "response.inject.failed";
+    if (failed && (!record(event.error) || typeof event.error.code !== "string"
+      || injectionFingerprint(event.input) !== injectionFingerprint(pending.results))) throw new Error("Native injection rejection does not match submitted results.");
+    this.replay?.observe(event);
+    this.lastAckSequence = event.sequence_number as number;
+    for (const item of pending.results) {
+      const call = this.calls.get(nativeResultKey(item))!;
+      call.state = failed ? "failed" : "accepted";
+      // Retain a digest, not another result body, for an explicitly rejected continuation.
+      call.recoverable = failed && record(event.error) && event.error.code === "response_already_completed";
+      if (call.recoverable) call.result = nativeResultFingerprint(item);
+    }
+    clearTimeout(this.ackTimer); this.ackTimer = undefined;
+    this.inFlight = undefined; this.queue.shift(); this.queueBytes -= pending.bytes;
+    // Do not let a synchronous fake peer publish the next ack before this event is relayed.
+    if (this.queue.length) queueMicrotask(() => { try { this.pump(); } catch { this.fail(); } });
+  }
+  /** Commit terminal replay only when no submitted injection can change its accepted inputs. */
+  private recordTerminal(): void {
+    if (this.terminal && !this.terminalRecorded) { this.replay?.observe(this.terminal); this.terminalRecorded = true; }
+  }
+  /** Recover saved, explicitly rejected results on the same socket only when the client asks. */
+  continue(frame: Frame): boolean {
+    if (!this.send || this.finished) return false;
+    if (this.queue.length || this.continuationSent) injectionError("injection_pending", "Wait for every injection acknowledgement before creating another response.");
+    if (!this.terminal && frame.previous_response_id === this.currentId) {
+      injectionError("injection_pending", "Wait for the response terminal before sending saved-result continuations.");
+    }
+    if (!this.terminal || frame.previous_response_id !== this.currentId) return false;
+    if (this.terminal.type !== "response.completed") injectionError("injection_response_failed", "The parent response did not complete successfully.");
+    if ((frame.stream_id ?? undefined) !== this.lane || frame.generate === false) injectionError("invalid_injection", "Use the same lane for an injection continuation.");
+    for (const [key, value] of Object.entries(frame)) {
+      if (!ENVELOPE.has(key) && this.settings.get(key) !== injectionFingerprint(value)) injectionError("injection_settings_changed", "A native injection continuation cannot change the pinned model or settings.");
+    }
+    for (const key of this.settings.keys()) {
+      if (!Object.hasOwn(frame, key)) injectionError("injection_settings_changed", "A native injection continuation cannot change the pinned model or settings.");
+    }
+    const results = nativeSavedResults(frame.input);
+    const required = [...this.calls.entries()].filter(([, call]) => call.state !== "accepted");
+    if (!required.length || results.length !== required.length) injectionError("invalid_injection", "Supply every outstanding saved tool result exactly once.");
+    for (const item of results) {
+      const call = this.calls.get(nativeResultKey(item));
+      if (!call || !nativeResultMatches(item, call.requirement) || call.state === "accepted" || call.state === "queued"
+        || (call.state === "failed" && (!call.recoverable || call.result !== nativeResultFingerprint(item)))) {
+        injectionError("invalid_injection", "Continuation input must match unsent or explicitly completion-rejected tool results.");
+      }
+    }
+    if (Buffer.byteLength(JSON.stringify(frame)) > MAX_NATIVE_INJECTION_BYTES) injectionError("invalid_injection", "Native injection continuation exceeds its byte limit.");
+    this.continuationSent = true;
+    try { this.recordTerminal(); const copy = JSON.parse(JSON.stringify(frame)) as Frame; this.replay?.submitted(copy); this.send(copy); }
+    catch { this.fail(); injectionError("injection_delivery_unknown", "Continuation delivery is unknown; do not automatically resend results."); }
+    if (!this.finished) this.armIdle(this.deadlines.ackMs);
+    return true;
+  }
+  /** Manage response/tool liveness independently of the non-resettable acknowledgement timer. */
+  private armIdle(ms: number): void {
+    clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => this.fail(), ms); this.idleTimer.unref?.();
+  }
+  /** Validate ordered upstream events while allowing acknowledgements after a response terminal. */
+  observe(event: Frame): boolean {
+    if ((event.stream_id ?? undefined) !== this.lane && !(event.type === "error" && event.stream_id == null)) throw new Error("Native injection lane mismatch.");
+    const type = event.type;
+    if (type === "error") { this.finished = true; return true; }
+    if (type === "response.inject.created" || type === "response.inject.failed") this.acknowledge(event);
+    else {
+      if (typeof type === "string" && (type.startsWith("response.inject.") || type.startsWith("response.steer."))) throw new Error("Unsupported native injection control event.");
+      const response = record(event.response) ? event.response : undefined;
+      if (type === "response.created") {
+        if (!injectionId(response?.id) || this.seen.has(response.id) || this.seen.size >= 128) throw new Error("Native injection response identity or chain limit violated.");
+        if (this.currentId && (!this.continuationSent || !this.terminal || this.queue.length
+          || (response.previous_response_id != null && response.previous_response_id !== this.currentId))) throw new Error("Unexpected native injection successor.");
+        this.currentId = response.id; this.seen.add(response.id); this.calls.clear(); this.callBytes = 0;
+        this.terminal = undefined; this.terminalRecorded = false; this.continuationSent = false; this.lastAckSequence = -1;
+        this.correlation?.finish(); this.correlation = new CodexWsCorrelation(true, () => false);
+      } else if (!this.currentId || this.terminal) throw new Error("Unexpected native injection event outside an active response.");
+      this.correlation?.accept({ ...event, stream_id: undefined });
+      if (type === "response.output_item.done") this.advertise(event.item);
+      if (["response.completed", "response.failed", "response.incomplete"].includes(String(type))) {
+        if (!this.currentId || response?.id !== this.currentId) throw new Error("Native injection terminal identity mismatch.");
+        this.terminal = event;
+        if (Array.isArray(response.output)) for (const item of response.output) this.advertise(item);
+      } else this.replay?.observe(event);
+    }
+    const unresolved = [...this.calls.values()].some(call => call.state !== "accepted");
+    this.finished = Boolean(this.terminal && !this.queue.length && !this.continuationSent
+      && (this.terminal.type !== "response.completed" || !unresolved));
+    if (this.finished) { this.recordTerminal(); clearTimeout(this.idleTimer); }
+    else this.armIdle(this.continuationSent ? this.deadlines.ackMs : unresolved ? this.deadlines.toolMs : this.idleMs);
+    return this.finished;
+  }
+}

package/src/server/responses/native-response-control.ts

@@ -0,0 +1,56 @@
+import type { OcxProviderConfig } from "../../types";
+import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
+import type { NativeSteeringReplayObserver } from "./native-steering-replay";
+
+import { isInjectionRequest } from "./native-injection-protocol";
+
+/** Shared transport ownership, not a shared steer/inject protocol state machine. */
+export interface NativeResponseControl {
+  readonly kind?: "steering" | "injection";
+  relayActive: boolean;
+  normalizeContinuation?: (frame: Record<string, unknown>) => Record<string, unknown>;
+  replayFactory?: () => NativeSteeringReplayObserver;
+  readonly attached: boolean;
+  readonly ended: boolean;
+  attach(send: (frame: Record<string, unknown>) => void, fail: (error: Error) => void): () => void;
+  observe(frame: Record<string, unknown>): boolean;
+  steer(frame: Record<string, unknown>): void;
+  inject?(frame: Record<string, unknown>): void;
+  continue(frame: Record<string, unknown>): boolean;
+}
+
+export const OPENAI_API_RESPONSES_URL = "https://api.openai.com/v1/responses";
+
+const nativeControlResponses = new WeakSet<Response>();
+/** Mark the exact response for multi-response delivery without serializing a wire field. */
+export function markNativeControlResponse(response: Response): Response { nativeControlResponses.add(response); return response; }
+/** Recognize a marked native response by identity, not by caller-controlled content. */
+export function isNativeControlResponse(response: Response): boolean { return nativeControlResponses.has(response); }
+
+/** Preserve canonical ChatGPT eligibility; public API controls require an explicit provider WebSocket opt-in. */
+export function nativeResponseControlEligible(provider: OcxProviderConfig, control?: NativeResponseControl): boolean {
+  if (isCanonicalOpenAiForwardProvider(provider)) return true;
+  return (control?.kind === "injection" || control?.kind === "steering") && provider.adapter === "openai-responses"
+    && provider.upstreamWebsocket === true && provider.authMode !== "forward"
+    && provider.baseUrl?.replace(/\/+$/, "") === "https://api.openai.com/v1";
+}
+
+/** Select by execution mode, never model name; a multi-agent request cannot acquire steering. */
+export function nativeResponseControlMode(frame: Record<string, unknown>, flags: {
+  codexNativeInjection?: boolean; codexNativeSteering?: boolean;
+}): "injection" | "steering" | undefined {
+  if (isInjectionRequest(frame)) return flags.codexNativeInjection === true ? "injection" : undefined;
+  return nativeSteeringUnavailableReason(frame, flags.codexNativeSteering) === undefined ? "steering" : undefined;
+}
+
+/** Explain documented execution-mode exclusions without claiming model entitlement. */
+export function nativeSteeringUnavailableReason(frame: Record<string, unknown>, enabled?: boolean): string | undefined {
+  if (enabled !== true) return "Native steering is disabled; enable codexNativeSteering and WebSockets for a supported route.";
+  if (isInjectionRequest(frame)) return "Multi-agent execution does not support single-agent response.steer; use a later client request.";
+  if (frame.conversation != null) return "Conversation-bound responses do not support native steering.";
+  if (Array.isArray(frame.context_management) && frame.context_management.some(item =>
+    item && typeof item === "object" && (item as Record<string, unknown>).type === "compaction")) {
+    return "Automatic API compaction and native steering cannot share an active response.";
+  }
+  return undefined;
+}

package/src/server/responses/native-response-json.ts

@@ -0,0 +1,14 @@
+import { createHash } from "node:crypto";
+
+/** Narrow JSON object envelopes independently of either native control owner. */
+export function nativeResponseRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Compare JSON content by value: object-key order is irrelevant, array order is not. */
+export function nativeResponseFingerprint(value: unknown): string {
+  const canonical = (item: unknown): string => Array.isArray(item) ? `[${item.map(canonical).join(",")}]`
+    : nativeResponseRecord(item) ? `{${Object.keys(item).sort().map(key => `${JSON.stringify(key)}:${canonical(item[key])}`).join(",")}}`
+    : JSON.stringify(item) ?? "null";
+  return createHash("sha256").update(canonical(value)).digest("hex");
+}

package/src/server/responses/native-response-output.ts

@@ -0,0 +1,37 @@
+import { nativeResponseFingerprint as injectionFingerprint, nativeResponseRecord as record } from "./native-response-json";
+type Frame = Record<string, unknown>;
+
+/**
+ * Preserve completed wire items missing from a sparse terminal, including hosted
+ * tool results and encrypted agent messages. Shared IDs must retain content and
+ * relative order; conflicting transcripts fail instead of silently losing data.
+ */
+export function nativeResponseOutput(done: ReadonlyMap<number, Frame>, terminal: unknown): Frame[] {
+  const observed = [...done.entries()].sort((a, b) => a[0] - b[0]).map(([, item]) => item);
+  if (terminal == null || (Array.isArray(terminal) && !terminal.length)) return observed;
+  if (!Array.isArray(terminal) || terminal.some(item => !record(item))) throw new Error("Invalid native response output.");
+  const identity = (item: Frame) => typeof item.id === "string" ? `id:${item.id}` : `body:${injectionFingerprint(item)}`;
+  const positions = new Map<string, number>();
+  observed.forEach((item, index) => {
+    const key = identity(item);
+    if (positions.has(key)) throw new Error("Duplicate native completed output identity.");
+    positions.set(key, index);
+  });
+  const result: Frame[] = [];
+  const seen = new Set<string>();
+  let cursor = 0;
+  for (const item of terminal as Frame[]) {
+    const key = identity(item);
+    if (seen.has(key)) throw new Error("Duplicate native terminal output identity.");
+    seen.add(key);
+    const position = positions.get(key);
+    if (position === undefined) { result.push(item); continue; }
+    if (position < cursor || injectionFingerprint(item) !== injectionFingerprint(observed[position])) {
+      throw new Error("Native terminal output contradicts completed wire items.");
+    }
+    while (cursor < position) result.push(observed[cursor++]);
+    result.push(item); cursor++;
+  }
+  while (cursor < observed.length) result.push(observed[cursor++]);
+  return result;
+}