@bitkyc08/opencodex 2.56.0 → 2.58.0

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

@@ -10,7 +10,13 @@
  * catches the pathological case and stays out of the way otherwise. Every uncertainty
  * resolves toward admitting.
  */
-import { nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, type NativeContextLimitsInput } from "../../codex/catalog/metadata";
+import {
+  nativeOpenAiContextWindow,
+  nativeOpenAiMaxInputTokens,
+  nativeOpenAiMaxOutputTokens,
+  type NativeContextLimitsInput,
+} from "../../codex/catalog/metadata";
+import { getModelMetadata } from "../../generated/model-metadata";
 import { estimateTokens } from "../../lib/token-estimate";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
 import { modelRecordValue } from "../../reasoning-effort";
@@ -54,6 +60,8 @@ export interface InputAdmissionResult {
   estimatedTokens: number;
   /** Resolved ceiling, or null when nothing could be resolved (=> always admitted). */
   ceiling: number | null;
+  /** Output space reserved by the combo preflight; absent on the loose direct gate. */
+  requiredOutputHeadroom?: number;
 }
 
 function positive(value: unknown): number | null {
@@ -135,14 +143,19 @@ export function estimateInputTokens(parsed: OcxParsedRequest, modelId: string):
  * reject a user-defined provider that merely shares a built-in name using limits that
  * belong to a different service.
  */
-export function resolveInputCeiling(
+interface ResolvedContextLimits {
+  /** The target's total context window: input and output share it. */
+  window: number | null;
+  /** Largest admissible input, which input-only caps may tighten below the window. */
+  ceiling: number | null;
+}
+
+function resolveContextLimits(
   provider: OcxProviderConfig,
   providerName: string,
   modelId: string,
-  // Operator cap for the canonical native provider. Passed in rather than read from a
-  // config here so this stays pure: no filesystem, no catalog, no registry scan.
   nativeContextCap?: NativeContextLimitsInput,
-): number | null {
+): ResolvedContextLimits {
   // `modelRecordValue`, not a bare lookup: the catalog resolves these same two maps that
   // way, so a `gpt-oss` entry covers `gpt-oss:120b`. Reading raw here made the gate fall
   // back to the provider-wide window and refuse turns the model can plainly hold.
@@ -168,13 +181,120 @@ export function resolveInputCeiling(
     : null;
   const nativeMaxInput = canonicalNativeBare ? positive(nativeOpenAiMaxInputTokens(modelId, nativeLimits)) : null;
 
-  const window = canonicalNativeBare ? native : configured;
+  const window = canonicalNativeBare ? (native ?? generatedNativeWindow(modelId, configured, nativeContextCap)) : configured;
   // modelMaxInputTokens is an input-only cap, so it can only tighten the window.
   const configuredMaxInput = positive(modelRecordValue(provider.modelMaxInputTokens, modelId));
   const limits = [window, configuredMaxInput, nativeMaxInput].filter((v): v is number => v !== null);
+  return { window, ceiling: limits.length === 0 ? null : Math.min(...limits) };
+}
+
+/**
+ * Generated-catalog keys, not routing provider names. `OPENAI_CODEX_PROVIDER_ID` is the string
+ * `"openai"` -- the canonical Codex forward route -- so using it to index the generated bundle
+ * would silently skip the native Codex rows and read the public API rows instead.
+ */
+const NATIVE_METADATA_CATALOGS = ["openai-codex", "openai"] as const;
+
+/**
+ * Static in-tree metadata for a canonical native slug the narrower override and pinned-native
+ * tables do not carry. Falling through to null made input admission completely blind for
+ * exactly those models, which is how a 128k target accepted a turn it could not finish.
+ *
+ * This deliberately covers slugs that are no longer offered in the picker: a retired slug is
+ * still dispatchable when an operator names it explicitly in a combo target, and that is the
+ * configuration where the gate was inert. This is a generated bundle compiled into the binary,
+ * not a live catalog read, so it adds no I/O. Explicit provider and operator caps may only
+ * narrow the result, never widen it.
+ */
+function generatedNativeWindow(
+  modelId: string,
+  configured: number | null,
+  nativeContextCap: NativeContextLimitsInput | undefined,
+): number | null {
+  let generated: number | null = null;
+  for (const catalog of NATIVE_METADATA_CATALOGS) {
+    generated = positive(getModelMetadata(catalog, modelId)?.contextWindow);
+    if (generated !== null) break;
+  }
+  if (generated === null) return null;
+  const cap = typeof nativeContextCap === "number"
+    ? positive(nativeContextCap)
+    : positive(nativeContextCap?.cap);
+  return Math.min(generated, configured ?? generated, cap ?? generated);
+}
+
+export function resolveInputCeiling(
+  provider: OcxProviderConfig,
+  providerName: string,
+  modelId: string,
+  // Operator cap for the canonical native provider. Passed in rather than read from a
+  // config here so this stays pure: no filesystem, no catalog, no registry scan.
+  nativeContextCap?: NativeContextLimitsInput,
+): number | null {
+  return resolveContextLimits(provider, providerName, modelId, nativeContextCap).ceiling;
+}
+
+/**
+ * Largest output the concrete target can emit. Used only to avoid reserving MORE than the
+ * target could ever produce when a client asks for a bigger allowance than the model has.
+ * Unknown stays unknown rather than inventing a capability.
+ */
+export function resolveOutputCeiling(
+  provider: OcxProviderConfig,
+  providerName: string,
+  modelId: string,
+): number | null {
+  const configured = positive(modelRecordValue(provider.modelMaxOutputTokens, modelId))
+    ?? positive(provider.defaultMaxOutputTokens);
+  const canonicalNativeBare = providerName === OPENAI_CODEX_PROVIDER_ID
+    && isCanonicalOpenAiForwardProvider(provider)
+    && !modelId.includes("/");
+  const native = canonicalNativeBare ? positive(nativeOpenAiMaxOutputTokens(modelId)) : null;
+  const limits = [configured, native].filter((v): v is number => v !== null);
   return limits.length === 0 ? null : Math.min(...limits);
 }
 
+/**
+ * Combo-only admission. A fallback must be able to satisfy the caller's declared output
+ * allowance inside its OWN context window. Otherwise it returns 200, emits a few hundred
+ * tokens, and terminates on `finish_reason: length` — which the Anthropic surface renders as
+ * "response exceeded the output token maximum" even though the real cause was the total
+ * window. By then the next target cannot be tried, because output has already committed.
+ *
+ * Two budgets are checked separately so the reserve is counted exactly once. `ceiling` is an
+ * input-only budget once `modelMaxInputTokens` tightens it below the window, so the output
+ * reserve belongs against `window`, not against `ceiling`.
+ *
+ * Direct and single-target requests keep the deliberately loose 2.5x pathological-input gate.
+ * This stricter rule applies only to synthetic combo children, where skipping one known-small
+ * target is safe and the ladder continues before any upstream bytes are sent. Unknown context
+ * stays fail-open, and a caller that declared no output allowance is unaffected.
+ */
+export function checkComboTargetInputAdmission(
+  parsed: OcxParsedRequest,
+  provider: OcxProviderConfig,
+  providerName: string,
+  modelId: string,
+  nativeContextCap?: NativeContextLimitsInput,
+): InputAdmissionResult {
+  const { window, ceiling } = resolveContextLimits(provider, providerName, modelId, nativeContextCap);
+  const requestedOutput = positive(parsed.options.maxOutputTokens);
+  if (window === null || ceiling === null || requestedOutput === null) {
+    return checkInputAdmission(parsed, provider, providerName, modelId, nativeContextCap);
+  }
+  const targetOutput = resolveOutputCeiling(provider, providerName, modelId);
+  const requiredOutputHeadroom = targetOutput === null
+    ? requestedOutput
+    : Math.min(requestedOutput, targetOutput);
+  const estimatedTokens = estimateInputTokens(parsed, modelId);
+  return {
+    admitted: estimatedTokens <= ceiling && estimatedTokens + requiredOutputHeadroom <= window,
+    estimatedTokens,
+    ceiling,
+    requiredOutputHeadroom,
+  };
+}
+
 /**
  * Fail-open when no ceiling is known; refuse only past `ceiling * ADMISSION_TOLERANCE`.
  *

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");
+}