mixdog 0.9.32 → 0.9.34

package/src/runtime/agent/orchestrator/providers/openai-transport-policy.mjs

@@ -0,0 +1,131 @@
+/*
+ * openai-transport-policy.mjs — single source of truth for the shared
+ * Responses-API transport policy switch (OpenAI OAuth/direct + xAI/compat).
+ *
+ * One env knob, MIXDOG_OAI_TRANSPORT, selects among the transport modes:
+ *   - 'ws-delta'  (DEFAULT): WS transport, refs-compatible delta ON.
+ *   - 'ws-full'   WS transport, delta OFF (always full frames).
+ *   - 'http-sse'  force the HTTP/SSE transport directly (delta is WS-only, so
+ *                 it stays off).
+ *   - 'auto'      compatibility spelling for the default ws-delta route.
+ *
+ * No mode performs an implicit HTTP fallback: explicit modes pin their
+ * transport. Delta is selected solely via MIXDOG_OAI_TRANSPORT=ws-delta
+ * (or by leaving the env unset).
+ */
+
+// Normalize the transport mode token. Underscores/spaces and a few common
+// spellings collapse to the canonical modes. Unknown/empty → null so the
+// caller falls back to the default 'ws-delta'.
+export function _normalizeTransportMode(raw) {
+    const v = String(raw || '').trim().toLowerCase().replace(/[\s_]+/g, '-');
+    switch (v) {
+        case 'ws-full': case 'wsfull': case 'full': case 'ws': case 'websocket-full':
+            return 'ws-full';
+        case 'ws-delta': case 'wsdelta': case 'delta': case 'websocket-delta':
+            return 'ws-delta';
+        case 'http-sse': case 'httpsse': case 'http': case 'sse': case 'http/sse':
+            return 'http-sse';
+        case 'auto':
+            return 'ws-delta';
+        default:
+            return null;
+    }
+}
+
+const DELTA_OFF = Object.freeze({ force: false, refs: false, optIn: false });
+const DELTA_REFS = Object.freeze({ force: false, refs: true, optIn: true });
+
+// Per-provider transport capabilities for the shared Responses policy. Every
+// Responses backend can speak WS and HTTP/SSE, and the WS *delta* continuation
+// (previous_response_id + incremental input in openai-ws-delta.mjs) is enabled
+// for BOTH OpenAI and xAI/Grok — but they use it for different reasons and
+// with different risk profiles:
+//   - OpenAI/codex: delta is the prefix-stripping optimization that is only
+//     fully cache-safe with the x-codex-turn-state sticky token; the refs-mode
+//     structural guards (openai-ws-delta.mjs) exist to bound that risk.
+//   - xAI/Grok: the official xAI Responses WebSocket guide *documents*
+//     previous_response_id + incremental input as the standard continuation
+//     shape (no Codex turn-state, no prefix-strip caveat). Enabling delta here
+//     mirrors that guidance rather than a codex-only hack, so 'ws-delta' drives
+//     the official continuation instead of collapsing to 'ws-full'.
+// Unknown providers get the permissive full-capability default.
+export const FULL_RESPONSES_TRANSPORT_CAPS = Object.freeze({ ws: true, http: true, delta: true });
+export const RESPONSES_TRANSPORT_CAPABILITIES = Object.freeze({
+    'openai-oauth': Object.freeze({ ws: true, http: true, delta: true }),
+    'openai':       Object.freeze({ ws: true, http: true, delta: true }), // direct
+    'xai':          Object.freeze({ ws: true, http: true, delta: true }), // official WS continuation
+});
+
+// Down-shift a requested mode to the nearest mode the provider actually
+// supports. Pure/idempotent: full-capability providers pass every mode through
+// unchanged, so the OpenAI OAuth/direct resolution stays byte-identical.
+export function _gateTransportMode(mode, caps) {
+    let m = mode;
+    // Delta unsupported → keep WS transport but force full frames.
+    if (m === 'ws-delta' && !caps.delta) m = 'ws-full';
+    // WS unsupported → prefer HTTP, else defer to auto.
+    if ((m === 'ws-full' || m === 'ws-delta') && !caps.ws) m = caps.http ? 'http-sse' : 'ws-delta';
+    // HTTP unsupported → prefer full-frame WS, else defer to auto.
+    if (m === 'http-sse' && !caps.http) m = caps.ws ? 'ws-full' : 'auto';
+    return m;
+}
+
+/**
+ * Resolve the shared Responses transport policy from the environment, gated by
+ * per-provider capabilities.
+ * @param {Record<string,string|undefined>} [env=process.env]
+ * @param {{ws?:boolean,http?:boolean,delta?:boolean}} [capabilities=FULL_RESPONSES_TRANSPORT_CAPS]
+ * @returns {{ mode: 'ws-full'|'ws-delta'|'http-sse',
+ *             requestedMode: 'ws-full'|'ws-delta'|'http-sse',
+ *             transport: 'auto'|'ws'|'http',
+ *             allowHttpFallback: boolean,
+ *             delta: { force: boolean, refs: boolean, optIn: boolean },
+ *             capabilities: {ws:boolean,http:boolean,delta:boolean} }}
+ */
+export function resolveResponsesTransportPolicy(env = process.env, capabilities = FULL_RESPONSES_TRANSPORT_CAPS) {
+    const caps = { ...FULL_RESPONSES_TRANSPORT_CAPS, ...(capabilities || {}) };
+    const requestedMode = _normalizeTransportMode(env?.MIXDOG_OAI_TRANSPORT) || 'ws-delta';
+    const mode = _gateTransportMode(requestedMode, caps);
+    let transport;
+    let delta;
+    switch (mode) {
+        case 'http-sse':
+            transport = 'http';
+            delta = DELTA_OFF;      // delta is a WS-only optimization
+            break;
+        case 'ws-full':
+            transport = 'ws';
+            delta = DELTA_OFF;      // explicit full frames
+            break;
+        case 'ws-delta':
+            transport = 'ws';
+            // Reachable only when caps.delta is true (else gated to ws-full).
+            delta = caps.delta ? DELTA_REFS : DELTA_OFF;
+            break;
+        default:
+            transport = 'ws';
+            delta = caps.delta ? DELTA_REFS : DELTA_OFF;
+            break;
+    }
+    return {
+        mode,
+        requestedMode,
+        transport,
+        // No mode performs an implicit HTTP fallback; explicit http-sse pins the
+        // HTTP transport instead. Kept as a field so existing callers gate off.
+        allowHttpFallback: false,
+        delta,
+        capabilities: caps,
+    };
+}
+
+/**
+ * Backward-compatible OpenAI OAuth/direct resolver — a thin full-capability
+ * wrapper over the shared policy so existing callers (openai-oauth/openai-ws/
+ * openai-ws-delta) and their tests keep byte-identical behavior.
+ * @param {Record<string,string|undefined>} [env=process.env]
+ */
+export function resolveOpenAiTransportPolicy(env = process.env) {
+    return resolveResponsesTransportPolicy(env, FULL_RESPONSES_TRANSPORT_CAPS);
+}

package/src/runtime/agent/orchestrator/providers/openai-ws-delta.mjs

@@ -10,11 +10,25 @@
  * (openai-oauth-ws.mjs et al) resolve unchanged.
  */
 
+import {
+    resolveResponsesTransportPolicy,
+    RESPONSES_TRANSPORT_CAPABILITIES,
+    FULL_RESPONSES_TRANSPORT_CAPS,
+} from './openai-transport-policy.mjs';
+
 // If the cached request (sans input) matches the current one and the current
 // input starts with the cached input, return only the tail. Otherwise return
 // the full input (fresh turn).
 export function _sansInput(body) {
-    const { input: _ignored, previous_response_id: _prevIgnored, ...rest } = body;
+    const { input: _ignored, previous_response_id: _prevIgnored, generate, ...rest } = body;
+    // Warmup/prewarm frames carry generate:false on the wire (codex prewarm
+    // marker, openai-oauth.mjs warmupBody). That flag must NOT count as a
+    // request-property change on the warmup->first-real comparison, or the
+    // first real turn always retreats to a full frame. Normalize away ONLY the
+    // warmup-only generate:false; any other generate value stays in the
+    // comparison snapshot so genuine differences still break the delta. The
+    // wire body is untouched — frames are built from the raw body, not this.
+    if (generate !== false && generate !== undefined) rest.generate = generate;
     return rest;
 }
 
@@ -170,59 +184,121 @@ export function _stripResponseItemsFromHead(items, responseItems) {
     return { ok: true, reason: null, tail: tail.slice(cursor), stripped, skipped };
 }
 
-export function _computeDelta({ entry, body }) {
+// Official OpenAI Responses WebSocket guide: response.create WS frames mirror
+// the Responses body EXCEPT the transport-only fields `stream`/`background`,
+// which the socket carries implicitly and the guide says to omit. This set is
+// stripped from a frame (any build shape) only when omitTransportFields is on.
+const TRANSPORT_ONLY_FRAME_FIELDS = new Set(['stream', 'background']);
+
+// Canonical response.create frame builder. Every WS send (warmup, main
+// full-frame, and delta) routes through this so the serialized key order is
+// identical byte-for-byte: `type` always leads, then the body's codex
+// struct-order keys follow verbatim. A delta send passes previousResponseId
+// (inserted immediately before `input`, matching codex's refs position) and
+// inputOverride (the stripped tail); an empty instructions string is dropped
+// in that case because the server resolves it from previous_response_id.
+// Full/warmup frames pass the body unchanged and keep every key in place.
+// omitTransportFields is used by wire-parity/prewarm helpers to drop stream/background.
+export function _buildResponseCreateFrame(body, { previousResponseId = null, inputOverride, omitTransportFields = false } = {}) {
+    const src = body && typeof body === 'object' ? body : {};
+    if (previousResponseId == null && inputOverride === undefined) {
+        if (!omitTransportFields) return { type: 'response.create', ...src };
+        const frame = { type: 'response.create' };
+        for (const key of Object.keys(src)) {
+            if (TRANSPORT_ONLY_FRAME_FIELDS.has(key)) continue;
+            frame[key] = src[key];
+        }
+        return frame;
+    }
+    const frame = { type: 'response.create' };
+    for (const key of Object.keys(src)) {
+        if (omitTransportFields && TRANSPORT_ONLY_FRAME_FIELDS.has(key)) continue;
+        if (key === 'instructions') {
+            const instr = src.instructions;
+            if (typeof instr === 'string' && instr.length) frame.instructions = instr;
+            continue;
+        }
+        if (key === 'input') {
+            if (previousResponseId != null) frame.previous_response_id = previousResponseId;
+            frame.input = inputOverride === undefined ? src.input : inputOverride;
+            continue;
+        }
+        frame[key] = src[key];
+    }
+    if (!('input' in frame) && inputOverride !== undefined) {
+        if (previousResponseId != null) frame.previous_response_id = previousResponseId;
+        frame.input = inputOverride;
+    }
+    return frame;
+}
+
+export function _computeDelta({ entry, body, traceProvider }) {
     // DEFAULT: full-frame sends. codex's delta path is only cache-safe with
     // the x-codex-turn-state sticky-routing token, which the backend issues to
     // codex but never to us (R11-R14 2026-07-03: zero turn-state events across
     // 200+ calls despite UA/version/beta-features/client_metadata parity;
     // delta measured 18-28% warm miss vs full-frame 0.0%). Without the sticky
     // token, previous_response_id requests hop cache nodes and only the first
-    // prefix blocks hit. Re-enable delta explicitly via MIXDOG_OAI_WS_DELTA=1
-    // for future probes if the backend starts issuing turn-state.
-    const deltaMode = String(process.env.MIXDOG_OAI_WS_DELTA || '').trim().toLowerCase();
-    const deltaForce = ['force', 'unsafe', 'always'].includes(deltaMode);
-    const deltaOptIn = deltaForce || ['1', 'true', 'yes', 'on'].includes(deltaMode);
+    // prefix blocks hit. Re-enable delta explicitly via
+    // Delta gating flows through the single transport-policy switch
+    // (MIXDOG_OAI_TRANSPORT: ws-full | ws-delta | http-sse). Default ws-delta
+    // selects the refs-compatible safe delta; 'ws-full'/'http-sse' force full
+    // frames.
+    // refs-compatible mode actively uses previous_response_id without demanding
+    // the x-codex-turn-state token, but KEEPS every structural safety check
+    // (anchor present, request-props unchanged, input-prefix match, response
+    // items strip clean). Any of those failing still retreats to a full frame.
+    // Resolve the transport policy under the caller's provider capabilities so
+    // the delta gate honors per-provider limits instead of always assuming full
+    // OpenAI caps. xAI's WS path now carries delta capability (caps.delta=true),
+    // so 'ws-delta' builds the OFFICIAL xAI continuation frame
+    // (previous_response_id + incremental input tail) documented by the xAI
+    // Responses WebSocket guide — NOT the codex prefix-strip hack: no
+    // x-codex-turn-state token is required or fabricated for xAI, and the
+    // structural refs guards below still bound any prefix mismatch. openai-oauth/
+    // direct keep full capabilities, so their resolution stays byte-identical.
+    const caps = traceProvider === 'xai'
+        ? RESPONSES_TRANSPORT_CAPABILITIES.xai
+        : FULL_RESPONSES_TRANSPORT_CAPS;
+    const { delta } = resolveResponsesTransportPolicy(process.env, caps);
+    const deltaForce = delta.force;
+    const deltaRefs = delta.refs;
+    const deltaOptIn = delta.optIn;
+    const buildFrame = (b, opts) => _buildResponseCreateFrame(b, opts || {});
     if (!deltaOptIn) {
-        return { mode: 'full', reason: 'full_default', frame: { type: 'response.create', ...body } };
+        return { mode: 'full', reason: 'full_default', frame: buildFrame(body) };
     }
     if (!entry || !entry.lastRequestSansInput || !entry.lastResponseId) {
-        return { mode: 'full', reason: 'no_anchor', frame: { type: 'response.create', ...body } };
+        return { mode: 'full', reason: 'no_anchor', frame: buildFrame(body) };
     }
-    if (!deltaForce && !entry.turnState) {
-        return { mode: 'full', reason: 'delta_missing_turn_state', frame: { type: 'response.create', ...body } };
+    if (!deltaForce && !deltaRefs && !entry.turnState) {
+        return { mode: 'full', reason: 'delta_missing_turn_state', frame: buildFrame(body) };
     }
     if (!Array.isArray(entry.lastRequestInput)) {
-        return { mode: 'full', reason: 'no_input_snapshot', frame: { type: 'response.create', ...body } };
+        return { mode: 'full', reason: 'no_input_snapshot', frame: buildFrame(body) };
     }
     const curSans = _stableStringify(_sansInput(body));
     if (curSans !== entry.lastRequestSansInput) {
-        return { mode: 'full', reason: 'request_properties_changed', frame: { type: 'response.create', ...body } };
+        return { mode: 'full', reason: 'request_properties_changed', frame: buildFrame(body) };
     }
     const curInput = Array.isArray(body.input) ? body.input : [];
     const afterPreviousInput = _stripRequestPrefix(curInput, entry.lastRequestInput);
     if (!afterPreviousInput) {
-        return { mode: 'full', reason: 'input_prefix_mismatch', frame: { type: 'response.create', ...body } };
+        return { mode: 'full', reason: 'input_prefix_mismatch', frame: buildFrame(body) };
     }
     const stripped = _stripResponseItemsFromHead(afterPreviousInput, entry.lastResponseItems);
     if (!stripped.ok) {
-        return { mode: 'full', reason: stripped.reason, frame: { type: 'response.create', ...body } };
+        return { mode: 'full', reason: stripped.reason, frame: buildFrame(body) };
     }
     return {
         mode: 'delta',
         reason: null,
         strippedResponseItems: stripped.stripped,
         skippedResponseItems: stripped.skipped,
-        frame: (() => {
-            const { model, instructions, input: _input, ...rest } = body;
-            return {
-                type: 'response.create',
-                model,
-                ...(typeof instructions === 'string' && instructions.length ? { instructions } : {}),
-                previous_response_id: entry.lastResponseId,
-                input: stripped.tail,
-                ...rest,
-            };
-        })(),
+        frame: buildFrame(body, {
+            previousResponseId: entry.lastResponseId,
+            inputOverride: stripped.tail,
+        }),
     };
 }
 

package/src/runtime/agent/orchestrator/providers/openai-ws-pool.mjs

@@ -9,8 +9,9 @@
 import WebSocket from 'ws';
 import { errText } from '../../../shared/err-text.mjs';
 import { createHash, randomBytes } from 'crypto';
-import { appendFileSync } from 'node:fs';
-import { codexUserAgent, codexVersionHeader } from './codex-client-meta.mjs';
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { codexOriginator, codexUserAgent, codexVersionHeader } from './codex-client-meta.mjs';
 import {
     PROVIDER_WS_ACQUIRE_TIMEOUT_MS,
     PROVIDER_WS_HANDSHAKE_TIMEOUT_MS,
@@ -26,7 +27,6 @@ export function _wsErrLabel(p) {
 }
 
 const CODEX_WS_URL = 'wss://chatgpt.com/backend-api/codex/responses';
-const CODEX_OAUTH_ORIGINATOR = 'codex_cli_rs';
 const OPENAI_WS_URL = 'wss://api.openai.com/v1/responses';
 const XAI_WS_URL = 'wss://api.x.ai/v1/responses';
 export const WS_IDLE_MS = resolveTimeoutMs(
@@ -73,6 +73,158 @@ function _envOn(name) {
     return ['1', 'true', 'yes', 'on'].includes(v);
 }
 
+// --- Opt-in Codex fingerprint/id parity knobs ------------------------------
+// All default OFF; unset envs leave the winning combo
+// (MIXDOG_OAI_CODEX_WIRE_PARITY=1 + ws-delta + underscore session_id) exactly
+// as-is. These add EXTRA parity dimensions for backend fingerprint probes.
+
+// codex sends dashed RFC-4122 UUIDs as session-id/thread-id (client.rs:1033-
+// 1057); we key those dashed handshake headers off the underscore cacheKey by
+// default. Opt in with MIXDOG_OAI_CODEX_WIRE_PARITY_UUID_IDS to reshape ONLY
+// the dashed pair (session-id/thread-id/x-client-request-id) into codex's UUID
+// format. The value is derived deterministically from the id so it stays
+// stable per cache key (prefix-cache continuity preserved), and the underscore
+// `session_id` header (the backend prefix-dedupe key) is left untouched.
+function _codexUuidIdParity() {
+    const v = String(process.env.MIXDOG_OAI_CODEX_WIRE_PARITY_UUID_IDS || '').trim().toLowerCase();
+    return ['1', 'true', 'yes', 'on', 'uuid', 'dashed'].includes(v);
+}
+
+function _codexDashedId(value) {
+    const h = createHash('sha256').update(String(value)).digest();
+    const b = Buffer.from(h.subarray(0, 16));
+    b[6] = (b[6] & 0x0f) | 0x50; // version 5 nibble
+    b[8] = (b[8] & 0x3f) | 0x80; // RFC-4122 variant
+    const hex = b.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+// Opt-in turn-state gate experiment bundle (MIXDOG_OAI_CODEX_TURN_STATE_GATE).
+// The debugger's working hypothesis for what gates x-codex-turn-state issuance
+// is a specific wire shape: Codex-shaped UUIDv7 session/thread ids + dashed-only
+// handshake headers (drop the underscore session_id) + NO duplicated
+// x-client-request-id + a parent-thread header (added in openai-oauth-ws.mjs).
+// This env ties those dimensions together as ONE experiment so operators can
+// A/B the whole gate shape without hand-composing four flags. Default OFF; it
+// leaves MIXDOG_OAI_CODEX_WIRE_PARITY_UUID_IDS / _SESSION_ID and every existing
+// flag intact and only reshapes the wire when explicitly enabled.
+function _codexTurnStateGate() {
+    const v = String(process.env.MIXDOG_OAI_CODEX_TURN_STATE_GATE || '').trim().toLowerCase();
+    return ['1', 'true', 'yes', 'on'].includes(v);
+}
+
+// Same derivation as _codexDashedId but stamps the version-7 nibble so the
+// dashed pair reads as a Codex-shaped UUIDv7. Deterministic per id (prefix
+// cache continuity preserved); only used under the turn-state gate bundle.
+function _codexDashedIdV7(value) {
+    const h = createHash('sha256').update(String(value)).digest();
+    const b = Buffer.from(h.subarray(0, 16));
+    b[6] = (b[6] & 0x0f) | 0x70; // version 7 nibble
+    b[8] = (b[8] & 0x3f) | 0x80; // RFC-4122 variant
+    const hex = b.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+// codex advertises enabled beta features on the WS handshake; the backend
+// plausibly gates x-codex-turn-state issuance on that list (see the
+// x-codex-beta-features comment below). MIXDOG_CODEX_BETA_FEATURES replaces the
+// whole list; MIXDOG_OAI_CODEX_TURN_STATE_FEATURES is a safe ADD-ONLY opt-in
+// that appends turn-state-gating feature token(s) (comma-separated, de-duped)
+// without dropping the default `remote_compaction_v2`. Unset = default list.
+function _codexBetaFeatures() {
+    const base = process.env.MIXDOG_CODEX_BETA_FEATURES || 'remote_compaction_v2';
+    const extra = String(process.env.MIXDOG_OAI_CODEX_TURN_STATE_FEATURES || '').trim();
+    if (!extra) return base;
+    const seen = new Set();
+    const out = [];
+    for (const tok of `${base},${extra}`.split(',').map((s) => s.trim()).filter(Boolean)) {
+        if (seen.has(tok)) continue;
+        seen.add(tok);
+        out.push(tok);
+    }
+    return out.join(',');
+}
+
+// --- Opt-in raw WS capture for byte-diff against codex-rs -------------------
+// Enabled ONLY when MIXDOG_OAI_WS_DUMP_DIR names a directory. Persists the
+// (redacted) handshake header metadata and the exact serialized
+// response.create frame bytes so our wire format can be byte-diffed against
+// codex. Secrets (Authorization / Cookie / account-id / routing tokens) are
+// hashed, never written in clear. When the env is unset both helpers are
+// no-ops, so there is no default behavior change.
+const _WS_DUMP_SECRET_RE = /^(authorization|proxy-authorization|cookie|set-cookie|chatgpt-account-id|x-codex-turn-state|session_id|session-id|thread-id|x-codex-parent-thread-id|x-client-request-id|x-session-affinity)$/i;
+
+function _wsDumpDir() {
+    const dir = String(process.env.MIXDOG_OAI_WS_DUMP_DIR || '').trim();
+    return dir || null;
+}
+
+function _redactHeaderValue(key, value) {
+    const v = String(value ?? '');
+    if (_WS_DUMP_SECRET_RE.test(String(key))) {
+        if (!v) return '';
+        return `<redacted:sha256:${createHash('sha256').update(v).digest('hex').slice(0, 12)}:len${v.length}>`;
+    }
+    return v;
+}
+
+function _redactDumpUrl(url) {
+    try {
+        const parsed = new URL(String(url));
+        for (const [key, value] of parsed.searchParams.entries()) {
+            if (_WS_DUMP_SECRET_RE.test(String(key))) {
+                parsed.searchParams.set(key, _redactHeaderValue(key, value));
+            }
+        }
+        return parsed.toString();
+    } catch {
+        return String(url || '');
+    }
+}
+
+function _dumpHandshakeHeaders(url, headers) {
+    const dir = _wsDumpDir();
+    if (!dir) return;
+    try {
+        mkdirSync(dir, { recursive: true });
+        const redacted = {};
+        for (const [k, v] of Object.entries(headers || {})) redacted[k] = _redactHeaderValue(k, v);
+        const rec = {
+            ts: new Date().toISOString(),
+            kind: 'ws_handshake',
+            url: _redactDumpUrl(url),
+            // Header order matters for the codex byte-diff; keep it explicit.
+            headerOrder: Object.keys(headers || {}),
+            headers: redacted,
+        };
+        const stamp = `${Date.now()}-${randomBytes(4).toString('hex')}`;
+        writeFileSync(join(dir, `handshake-${stamp}.json`), JSON.stringify(rec, null, 2));
+    } catch {}
+}
+
+function _dumpFrame(payload) {
+    const dir = _wsDumpDir();
+    if (!dir) return;
+    try {
+        mkdirSync(dir, { recursive: true });
+        const stamp = `${Date.now()}-${randomBytes(4).toString('hex')}`;
+        // Persist the serialized response.create bytes for codex byte-diff,
+        // but never dump x-codex-turn-state in clear. That token is a
+        // per-turn credential-like routing secret; header dumps already hash
+        // it, so frame dumps must do the same when client_metadata carries it.
+        let out = payload;
+        try {
+            const frame = JSON.parse(String(payload));
+            const meta = frame?.client_metadata;
+            if (meta && typeof meta === 'object' && typeof meta['x-codex-turn-state'] === 'string') {
+                meta['x-codex-turn-state'] = _redactHeaderValue('x-codex-turn-state', meta['x-codex-turn-state']);
+                out = JSON.stringify(frame);
+            }
+        } catch {}
+        writeFileSync(join(dir, `frame-${stamp}.json`), out);
+    } catch {}
+}
+
 function _cfCookieAccountKey(auth) {
     return String(auth?.account_id || auth?.apiKey || 'default');
 }
@@ -166,6 +318,7 @@ export function _sendFrame(entry, frame) {
             reject(err);
             return;
         }
+        _dumpFrame(payload);
         try {
             // Do NOT await the send callback: on a wedged-but-OPEN socket the
             // ws write callback may never fire, which would hang this Promise
@@ -199,7 +352,7 @@ function _buildHandshakeHeaders({ auth, sessionToken, turnState, cacheKey: _cach
         : {
             'Authorization': `Bearer ${auth.access_token}`,
             'chatgpt-account-id': auth.account_id || '',
-            'originator': CODEX_OAUTH_ORIGINATOR,
+            'originator': codexOriginator(),
             'OpenAI-Beta': 'responses_websockets=2026-02-06',
             // codex-rs merges provider http_headers ("version") plus
             // default_headers (User-Agent) into the WS handshake
@@ -215,7 +368,7 @@ function _buildHandshakeHeaders({ auth, sessionToken, turnState, cacheKey: _cach
             // exactly "remote_compaction_v2" (features/src/lib.rs: the only
             // always-advertised Stable default-on feature). Servers gate
             // behavior (plausibly incl. x-codex-turn-state issuance) on it.
-            'x-codex-beta-features': process.env.MIXDOG_CODEX_BETA_FEATURES || 'remote_compaction_v2',
+            'x-codex-beta-features': _codexBetaFeatures(),
         };
     const isOpenAiOauth = auth.type !== 'xai' && auth.type !== 'openai-direct';
     // codex-rs sends only the dashed session-id/thread-id pair
@@ -224,15 +377,35 @@ function _buildHandshakeHeaders({ auth, sessionToken, turnState, cacheKey: _cach
     // its in-memory prefix state by the underscore session_id handshake
     // header, and the only 0.0%-miss full-frame rounds (R7/R8, R15 regressed
     // to 13% after this header was dropped) all had it present. Send both.
-    if (sessionToken) {
+    // The underscore session_id is the backend prefix-dedupe key (2026-04-19
+    // probes; R15 regressed to 13% miss when it was dropped). Codex parity
+    // (client.rs:1033-1057) sends ONLY the dashed pair, but dropping this
+    // header is a KNOWN cache-unsafe change — so the general parity flag no
+    // longer silently drops it. Keep it unless an operator EXPLICITLY opts
+    // into the codex-exact dashed-only wire via
+    // MIXDOG_OAI_CODEX_WIRE_PARITY_SESSION_ID=dashed.
+    // The gate bundle implies the dashed-only wire (drop the underscore
+    // session_id) on top of the standalone opt-in.
+    const gate = _codexTurnStateGate();
+    const dropUnderscoreSessionId = process.env.MIXDOG_OAI_CODEX_WIRE_PARITY_SESSION_ID === 'dashed' || gate;
+    if (sessionToken && !dropUnderscoreSessionId) {
         headers['session_id'] = String(sessionToken);
     }
     if (isOpenAiOauth && (sessionToken || _cacheKey)) {
-        const threadId = String(_cacheKey || sessionToken);
-        const sessionId = String(sessionToken || _cacheKey);
+        // Gate bundle forces Codex-shaped UUIDv7 ids; the standalone parity flag
+        // keeps its v5-derived shape.
+        const uuidIds = _codexUuidIdParity() || gate;
+        const shapeId = gate ? _codexDashedIdV7 : _codexDashedId;
+        // Underscore `session_id` above is left as-is (backend prefix-dedupe
+        // key); only the dashed codex pair is reshaped under the opt-in.
+        const threadId = uuidIds ? shapeId(String(_cacheKey || sessionToken)) : String(_cacheKey || sessionToken);
+        const sessionId = uuidIds ? shapeId(String(sessionToken || _cacheKey)) : String(sessionToken || _cacheKey);
         headers['session-id'] = sessionId;
         headers['thread-id'] = threadId;
-        headers['x-client-request-id'] = threadId;
+        // Default/parity wire duplicates the dashed thread-id here. The gate
+        // hypothesis is that a duplicated x-client-request-id suppresses
+        // turn-state issuance, so omit it entirely under the bundle.
+        if (!gate) headers['x-client-request-id'] = threadId;
         if (codexHeaders && typeof codexHeaders === 'object') {
             for (const [key, value] of Object.entries(codexHeaders)) {
                 if (typeof key === 'string' && typeof value === 'string' && value) {
@@ -240,6 +413,17 @@ function _buildHandshakeHeaders({ auth, sessionToken, turnState, cacheKey: _cach
                 }
             }
         }
+        // Gate-only: the wire thread-id above is reshaped to a Codex UUIDv7
+        // (shapeId), but _codexWsCompatibilityHeaders derives
+        // x-codex-parent-thread-id from the RAW dashed thread_id, so the merged
+        // codexHeaders carry a parent-thread id that no longer matches the
+        // thread-id on the same handshake. Realign it to the reshaped thread-id
+        // (single source of truth: the pool owns the wire id shape) so the
+        // gate handshake is internally consistent. Non-gate / standalone
+        // parity paths keep codex's raw value untouched.
+        if (gate && headers['x-codex-parent-thread-id']) {
+            headers['x-codex-parent-thread-id'] = threadId;
+        }
     } else {
         // xAI/direct keep a per-request value so their server-side traces stay
         // distinguishable across reconnects.
@@ -290,6 +474,7 @@ function _openSocket({ auth, sessionToken, turnState, externalSignal, cacheKey,
     const url = baseUrl + (sessionToken && process.env.MIXDOG_OAI_WS_URL_SESSION === '1'
         ? `?session_id=${encodeURIComponent(String(sessionToken))}`
         : '');
+    _dumpHandshakeHeaders(url, headers);
     return new Promise((resolve, reject) => {
         let settled = false;
         let abortListener = null;

package/src/runtime/agent/orchestrator/providers/openai-ws-stream.mjs

@@ -38,6 +38,7 @@ import {
     _stripResponseItemsFromHead,
     _computeDelta,
     _estimateFrameTokens,
+    _buildResponseCreateFrame,
 } from './openai-ws-delta.mjs';
 import {
     _combineUsageWithWarmup,
@@ -59,6 +60,7 @@ export {
     _stripResponseItemsFromHead,
     _computeDelta,
     _estimateFrameTokens,
+    _buildResponseCreateFrame,
     _combineUsageWithWarmup,
 };
 
@@ -126,13 +128,22 @@ function _hasHeaderKey(headers, name) {
     return _headerKeys(headers).includes(wanted);
 }
 
-function _captureTurnStateFromEvent(entry, event) {
+export function _captureTurnStateFromEvent(entry, event) {
     if (!entry || entry.turnState || !event || typeof event !== 'object') return;
     const turnState = _headerString(event.headers, X_CODEX_TURN_STATE_HEADER)
         || _headerString(event.response?.headers, X_CODEX_TURN_STATE_HEADER)
         || _headerString(event.response?.metadata?.headers, X_CODEX_TURN_STATE_HEADER)
         || _headerString(event.metadata?.headers, X_CODEX_TURN_STATE_HEADER);
-    if (turnState) entry.turnState = turnState;
+    if (turnState) {
+        entry.turnState = turnState;
+        // Attribute the captured token to the turn currently on the wire so
+        // the per-turn drop guard (_withCodexWsClientMetadata) can retire it
+        // once turn_id advances; null falls back to first-use attribution. An
+        // empty turn_id (parity prewarm) is a valid owner — preserve '' rather
+        // than collapsing it to null, so a prewarm-captured token is retired on
+        // the next real turn instead of leaking onto it.
+        entry.turnStateTurnId = entry.currentTurnId != null ? entry.currentTurnId : null;
+    }
 }
 
 function _traceWsHeaderKeys(entry, event, midState, traceProvider, model) {

package/src/runtime/agent/orchestrator/providers/openai-ws.mjs

@@ -18,6 +18,7 @@ import { enrichModels } from './model-catalog.mjs';
 import { sanitizeModelList } from './model-list-sanitize.mjs';
 import { sendViaHttpSse, _envFlag } from './openai-oauth-http-sse.mjs';
 import { shouldFallbackTransport } from './retry-classifier.mjs';
+import { resolveOpenAiTransportPolicy } from './openai-transport-policy.mjs';
 import { loadConfig } from '../config.mjs';
 import {
     resolveProviderCacheKey,
@@ -146,19 +147,35 @@ export class OpenAIDirectProvider {
             auth: a,
             sendOpts: opts,
             displayModel: (id) => id,
+            // Public direct WS must not inherit the openai-oauth trace provider:
+            // that key drives the Codex WS client-metadata path
+            // (useCodexWsClientMetadata = traceProvider === 'openai-oauth') and
+            // the OAuth/Codex handshake headers. Direct API-key auth pins its own
+            // provider so it stays on the public (non-Codex) envelope.
+            traceProvider: 'openai-direct',
         });
         // WS→HTTP/SSE fallback mirrors the openai-oauth wrapper: the shared
         // HTTP transport now accepts auth.type==='openai-direct' (public
         // Responses endpoint + Bearer <apiKey>), so the api-key provider gets
         // the same envelope. Gate via shouldFallbackTransport (denies
         // 401/403/404/429 + liveTextEmitted/emittedToolCall/unsafeToRetry).
-        const httpFallbackEnabled = _envFlag('MIXDOG_OPENAI_HTTP_FALLBACK', true);
+        const transportPolicy = resolveOpenAiTransportPolicy();
+        const httpFallbackEnabled = transportPolicy.allowHttpFallback
+            && _envFlag('MIXDOG_OPENAI_HTTP_FALLBACK', true);
         const dispatchHttp = (a) => {
             if (!process.env.MIXDOG_QUIET_PROVIDER_LOG) {
                 process.stderr.write('[openai-ws] WebSocket unhealthy; falling back to HTTP/SSE\n');
             }
             return sendViaHttpSse({ ...common, auth: a, opts, fetchFn: opts._fetchFn });
         };
+        // Transport-policy switch (MIXDOG_OAI_TRANSPORT). 'http-sse' forces the
+        // HTTP/SSE transport directly — no WS attempt, so skip the fallback log
+        // that dispatchHttp emits (it is not a fallback here). All other modes
+        // ('auto'/'ws-full'/'ws-delta') keep the WS-first path below; ws-full vs
+        // ws-delta only affects the delta gate inside openai-ws-delta.mjs.
+        if (transportPolicy.transport === 'http') {
+            return await sendViaHttpSse({ ...common, auth, opts, fetchFn: opts._fetchFn });
+        }
         try {
             return await dispatchWs(auth);
         } catch (err) {