@bitkyc08/opencodex 2.57.0 → 2.58.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;
+}

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

@@ -0,0 +1,44 @@
+import { inspectResponseLogSsePayload, usageFromResponsesPayload, type RequestLogContext } from "../request-log";
+import type { OcxUsage } from "../../types";
+import { MAX_NATIVE_STEERING_RESPONSES } from "./native-steering";
+
+/** Count every terminal once. Control frames may echo user input: never sample them. */
+export function createNativeSteeringLogObserver(logCtx: RequestLogContext, onFirstOutput?: () => void): (payload: string) => void {
+  let outputSeen = false;
+  const usages = new Map<string, OcxUsage>();
+  return payload => {
+    let event: { type?: string; delta?: unknown; response?: { id?: string; usage?: unknown; incomplete_details?: { reason?: string } } };
+    try { event = JSON.parse(payload); } catch { return; }
+    if (event.type?.startsWith("response.steer.") || event.type?.startsWith("response.inject.")) return;
+    if (!outputSeen && event.type?.endsWith(".delta") && typeof event.delta === "string" && event.delta.length) {
+      outputSeen = true; onFirstOutput?.();
+    }
+    // A steered parent is not a failed logical turn. Keep its usage, but never
+    // label an eventual successful successor as an upstream failure.
+    if (!(event.type === "response.incomplete" && event.response?.incomplete_details?.reason === "steered")) {
+      inspectResponseLogSsePayload(logCtx, payload);
+    }
+    const terminal = ["response.completed", "response.failed", "response.incomplete"].includes(event.type ?? "");
+    if (terminal && typeof event.response?.id === "string") {
+      const usage = usageFromResponsesPayload(event.response.usage);
+      if (usage && (usages.has(event.response.id) || usages.size < MAX_NATIVE_STEERING_RESPONSES)) {
+        // Retain numeric counters only, never arbitrary rawUsage metadata.
+        const counters: OcxUsage = { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens };
+        for (const key of ["totalTokens", "cachedInputTokens", "cacheReadInputTokens", "cacheCreationInputTokens", "reasoningOutputTokens"] as const) {
+          if (typeof usage[key] === "number") counters[key] = usage[key];
+        }
+        usages.set(event.response.id, counters);
+      }
+    }
+    if (!usages.size) return;
+    const total: OcxUsage = { inputTokens: 0, outputTokens: 0 };
+    for (const usage of usages.values()) {
+      for (const key of ["inputTokens", "outputTokens", "totalTokens", "cachedInputTokens", "cacheReadInputTokens", "cacheCreationInputTokens", "reasoningOutputTokens"] as const) {
+        const value = usage[key];
+        if (typeof value === "number" && Number.isFinite(value)) total[key] = (total[key] ?? 0) + value;
+      }
+    }
+    logCtx.usage = total;
+    if (logCtx.activeAttempt) logCtx.activeAttempt.usage = total;
+  };
+}

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

@@ -0,0 +1,49 @@
+import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../../types";
+import { nativeEffortClamp, shouldApplyNativeEffortClamp } from "../../codex/catalog";
+import { applyEffortCap, applyPinnedEffort, effortCapAppliesTo, prepareEffortNormalization, stripEmptyLadderEffort, supportedLadderFor } from "../effort-policy";
+import { collabSurface } from "./collaboration";
+import { mapRoutedResponsesReasoningEffort, normalizeConfiguredReasoningSummaryDelivery,
+  stripDisabledReasoningSummaries, stripDisabledVerbosity, stripUnsupportedReasoningSummaryDelivery } from "../../adapters/openai-responses/reasoning";
+import { NativeSteeringError } from "./native-steering";
+import { nativeResponseRecord as record } from "./native-response-json";
+import { STEERING_MUTABLE_SETTINGS } from "./native-steering-settings";
+
+type Frame = Record<string, unknown>;
+
+/** Reuse normal route-specific policy on a private override, never reroute or rebuild saved tool results. */
+export function createSteeringSettingsNormalizer(
+  parsed: OcxParsedRequest,
+  route: { provider: OcxProviderConfig; providerName: string; modelId: string },
+  config: OcxConfig,
+  headers: Headers,
+): (frame: Frame) => Frame {
+  const selector = prepareEffortNormalization(parsed, route);
+  const surface = collabSurface(parsed);
+  return (frame: Frame): Frame => {
+    if (route.provider.authMode === "forward" && Object.hasOwn(frame, "max_output_tokens")) {
+      throw new NativeSteeringError("steering_settings_unsupported", "This subscription route does not accept max_output_tokens; omit that override.");
+    }
+    // The frame is cloned by the channel. Policy receives only generation keys,
+    // not saved results, tool declarations, credentials or caller response IDs.
+    let body: Frame = Object.fromEntries(STEERING_MUTABLE_SETTINGS.filter(key => Object.hasOwn(frame, key)).map(key => [key, frame[key]]));
+    if (Object.hasOwn(body, "reasoning")) {
+      const candidate = { ...parsed, options: { ...parsed.options,
+        reasoning: record(body.reasoning) && typeof body.reasoning.effort === "string" ? body.reasoning.effort : undefined }, _rawBody: body };
+      applyPinnedEffort(candidate, route, config, selector);
+      if (effortCapAppliesTo(surface, headers, config, parsed._compactionRequest === true)) {
+        applyEffortCap(candidate, headers, config, supportedLadderFor(route));
+      }
+      const clamp = shouldApplyNativeEffortClamp(route.providerName, route.provider, route.modelId)
+        ? nativeEffortClamp(route.modelId, candidate.options.reasoning) : null;
+      if (clamp && record(body.reasoning)) body.reasoning.effort = clamp;
+      body = mapRoutedResponsesReasoningEffort(body, route.provider, route.modelId) as Frame;
+      body.reasoning = stripEmptyLadderEffort(body.reasoning, supportedLadderFor(route));
+    }
+    body = stripDisabledVerbosity(stripDisabledReasoningSummaries(
+      normalizeConfiguredReasoningSummaryDelivery(stripUnsupportedReasoningSummaryDelivery(body, route.modelId), route.provider, route.modelId),
+      route.provider, route.modelId), route.provider, route.modelId) as Frame;
+    const next = { ...frame };
+    for (const key of STEERING_MUTABLE_SETTINGS) if (Object.hasOwn(frame, key)) next[key] = body[key];
+    return next;
+  };
+}

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

@@ -0,0 +1,126 @@
+import { nativeResponseOutput } from "./native-response-output";
+
+/**
+ * Connection-local replay journal. Only input committed by response.created enters
+ * a successor's prefix. Uncommitted/rejected steering never enters the shared
+ * continuation cache. Bodies are bounded and discarded at connection teardown.
+ */
+export const MAX_NATIVE_STEERING_REPLAY_BYTES = 32 * 1024 * 1024;
+type Frame = Record<string, unknown>;
+/** Accept JSON object envelopes without treating arrays as records. */
+function record(value: unknown): value is Frame {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Normalize string input to one user message while preserving array order. */
+function inputItems(input: unknown): unknown[] {
+  if (typeof input === "string") return [{ type: "message", role: "user", content: [{ type: "input_text", text: input }] }];
+  return Array.isArray(input) ? input : [];
+}
+export interface NativeSteeringReplayObserver {
+  submitted(frame: Frame): () => void;
+  observe(frame: Frame): void;
+  dispose(): void;
+}
+
+/** Keep bounded, connection-local input until a validated successor commits it. */
+export class NativeSteeringReplay implements NativeSteeringReplayObserver {
+  private prefix: unknown[];
+  private bytes: number;
+  private current?: string;
+  private previousOutput: unknown[] = [];
+  private outputItems = new Map<number, Frame>();
+  private submissions: Array<{ parent: string; input: unknown[]; id?: string; bytes: number }> = [];
+  private explicitInput: unknown[] = [];
+  private explicitBytes = 0;
+
+  /** Capture the initial prefix and reject over-budget history before dispatch. */
+  constructor(input: unknown, private readonly remember: (input: unknown[], response: Frame) => void) {
+    this.prefix = [...inputItems(input)];
+    this.bytes = Buffer.byteLength(JSON.stringify(this.prefix));
+    this.check();
+  }
+  /** Reject overflow rather than silently truncating retained conversation input. */
+  private check(): void {
+    if (this.bytes > MAX_NATIVE_STEERING_REPLAY_BYTES) throw new Error("Native steering replay exceeded its bounded history budget; input was not silently truncated.");
+  }
+  /** Reserve replay bytes before send and return a rollback for synchronous failure. */
+  submitted(frame: Frame): () => void {
+    const input = inputItems(frame.input);
+    const bytes = Buffer.byteLength(JSON.stringify(input));
+    this.bytes += bytes;
+    try { this.check(); } catch (error) { this.bytes -= bytes; throw error; }
+    if (frame.type === "response.steer") {
+      const submission = { parent: String(frame.previous_response_id), input, bytes };
+      this.submissions.push(submission);
+      return () => {
+        const index = this.submissions.indexOf(submission);
+        if (index >= 0) { this.submissions.splice(index, 1); this.bytes -= bytes; }
+      };
+    }
+    this.explicitInput = input;
+    this.explicitBytes = bytes;
+    return () => { this.explicitInput = []; this.bytes -= this.explicitBytes; this.explicitBytes = 0; };
+  }
+  /** Apply ordered upstream events; only created successors commit queued input. */
+  observe(frame: Frame): void {
+    const response = record(frame.response) ? frame.response : undefined;
+    const steer = record(frame.steer) ? frame.steer : undefined;
+    if (frame.type === "response.steer.accepted") {
+      const first = this.submissions.find(item => item.parent === steer?.previous_response_id && item.id === undefined);
+      if (!first || typeof steer?.id !== "string") throw new Error("Native steering replay acceptance does not match submitted input");
+      first.id = steer.id;
+    } else if (frame.type === "response.steer.failed") {
+      const index = this.submissions.findIndex(item => steer?.id !== undefined
+        ? item.id === steer.id
+        : item.parent === steer?.previous_response_id && item.id === undefined);
+      if (index >= 0) {
+        const [failed] = this.submissions.splice(index, 1);
+        this.bytes -= failed.bytes;
+      }
+    } else if (frame.type === "response.created") {
+      if (this.current) {
+        const committed = this.submissions.filter(item => item.parent === this.current && item.id !== undefined);
+        // Byte-valid histories may exceed the runtime's positional-argument limit.
+        for (const item of this.previousOutput) this.prefix.push(item);
+        for (const submission of committed) {
+          for (const item of submission.input) this.prefix.push(item);
+        }
+        for (const item of this.explicitInput) this.prefix.push(item);
+        this.submissions = this.submissions.filter(item => !committed.includes(item));
+      }
+      this.explicitInput = [];
+      this.explicitBytes = 0;
+      this.previousOutput = [];
+      this.outputItems.clear();
+      this.current = String(response?.id);
+    } else if (frame.type === "response.output_item.done") {
+      const index = frame.output_index as number;
+      if (!Number.isSafeInteger(index) || index < 0 || index > 10_000 || !record(frame.item)) throw new Error("Native steering replay output identity is invalid");
+      const previous = this.outputItems.get(index);
+      if (previous !== undefined) this.bytes -= Buffer.byteLength(JSON.stringify(previous));
+      this.bytes += Buffer.byteLength(JSON.stringify(frame.item));
+      this.check();
+      this.outputItems.set(index, frame.item);
+    } else if (response && ["response.completed", "response.incomplete", "response.failed"].includes(String(frame.type))) {
+      const doneItems = [...this.outputItems.entries()].sort((a, b) => a[0] - b[0]).map(([, item]) => item);
+      const output = nativeResponseOutput(this.outputItems, response.output);
+      for (const item of doneItems) this.bytes -= Buffer.byteLength(JSON.stringify(item));
+      this.bytes += Buffer.byteLength(JSON.stringify(output));
+      this.check();
+      this.outputItems.clear();
+      this.previousOutput = output;
+      // Failed and steered parents are never presented to shared state as completed.
+      // Their output is used only when a validated successor commits that prefix.
+      if (frame.type === "response.completed") this.remember(this.prefix, { ...response, output });
+    }
+  }
+  /** Release retained input, output and queued submissions when the owner detaches. */
+  dispose(): void {
+    this.prefix = [];
+    this.previousOutput = [];
+    this.submissions = [];
+    this.explicitInput = [];
+    this.outputItems.clear();
+    this.bytes = 0;
+  }
+}

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

@@ -0,0 +1,76 @@
+import { REASONING_SUMMARY_DELIVERY_VALUES } from "../../types/wire";
+import { nativeResponseRecord as record } from "./native-response-json";
+
+type Frame = Record<string, unknown>;
+/** Only generation settings may change without selecting a new route or tool surface. */
+export const STEERING_MUTABLE_SETTINGS = ["reasoning", "text", "max_output_tokens", "stream_options"] as const;
+export const isSteeringMutableSetting = (key: string): boolean =>
+  (STEERING_MUTABLE_SETTINGS as readonly string[]).includes(key);
+
+/** Bound nested structured-output schemas before fingerprinting or copying them. */
+function boundedJson(value: unknown): boolean {
+  const pending = [{ value, depth: 0 }];
+  let nodes = 0;
+  while (pending.length) {
+    const current = pending.pop()!;
+    if (++nodes > 20_000 || current.depth > 64) return false;
+    if (current.value && typeof current.value === "object") {
+      for (const value of Object.values(current.value)) pending.push({ value, depth: current.depth + 1 });
+    }
+  }
+  return true;
+}
+const only = (value: Frame, keys: readonly string[]) => Object.keys(value).every(key => keys.includes(key));
+const optionalEnum = (value: unknown, choices: readonly string[]) => value === undefined || value === null
+  || (typeof value === "string" && choices.includes(value));
+
+/** Reject malformed overrides rather than treating them as omitted settings. */
+export function validSteeringSettings(frame: Frame): boolean {
+  for (const key of STEERING_MUTABLE_SETTINGS) {
+    if (!Object.hasOwn(frame, key)) continue;
+    const value = frame[key];
+    if (!boundedJson(value)) return false;
+    if (value === null) continue;
+    if (key === "max_output_tokens") {
+      if (!Number.isSafeInteger(value) || (value as number) < 1) return false;
+      continue;
+    }
+    if (!record(value)) return false;
+    if (key === "reasoning") {
+      if (!only(value, ["effort", "summary", "generate_summary"])
+        || !optionalEnum(value.effort, ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"])
+        || !optionalEnum(value.summary, ["auto", "concise", "detailed", "none"])
+        || !optionalEnum(value.generate_summary, ["auto", "concise", "detailed", "none"])) return false;
+    } else if (key === "stream_options") {
+      if (!only(value, ["reasoning_summary_delivery", "include_usage", "include_obfuscation"])
+        || !optionalEnum(value.reasoning_summary_delivery, REASONING_SUMMARY_DELIVERY_VALUES)
+        || [value.include_usage, value.include_obfuscation].some(item => item !== undefined && typeof item !== "boolean")) return false;
+    } else {
+      if (!only(value, ["format", "verbosity"]) || !optionalEnum(value.verbosity, ["low", "medium", "high"])) return false;
+      if (value.format === undefined || value.format === null) continue;
+      const format = value.format;
+      if (!record(format)) return false;
+      if (format.type === "text" || format.type === "json_object") {
+        if (!only(format, ["type"])) return false;
+      } else if (format.type === "json_schema") {
+        if (!only(format, ["type", "name", "schema", "strict", "description"])
+          || typeof format.name !== "string" || !/^[a-zA-Z0-9_-]{1,64}$/.test(format.name)
+          || !record(format.schema)
+          || (format.strict != null && typeof format.strict !== "boolean")
+          || (format.description !== undefined && typeof format.description !== "string")) return false;
+      } else return false;
+    }
+  }
+  return true;
+}
+
+/** Overlay only validated generation keys on the current, already authorized wire settings. */
+export function mergeSteeringContinuation(base: Frame, frame: Frame): Frame {
+  const outgoing: Frame = { ...base, input: frame.input, previous_response_id: frame.previous_response_id };
+  for (const key of STEERING_MUTABLE_SETTINGS) {
+    if (!Object.hasOwn(frame, key)) continue;
+    if (frame[key] === undefined) delete outgoing[key];
+    else outgoing[key] = frame[key];
+  }
+  return outgoing;
+}