@bitkyc08/opencodex 2.57.0 → 2.59.0

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