mixdog 0.9.63 → 0.9.64

package/src/runtime/agent/orchestrator/providers/openai-responses-payload.mjs

@@ -0,0 +1,357 @@
+// ChatGPT-backend Responses payload builders, extracted from openai-oauth.mjs.
+/**
+ * OpenAI ChatGPT OAuth subscription provider.
+ *
+ * Dispatches over the WebSocket upgrade of chatgpt.com/backend-api/codex/
+ * responses (responses_websockets=2026-02-06 beta). Authenticates via PKCE
+ * OAuth using Mixdog-owned token storage. Streaming/framing lives in
+ * openai-oauth-ws.mjs; this file owns auth, model catalog, request-body
+ * shape, and HTTP/SSE fallback when WebSocket transport is unhealthy.
+ */
+import { createHash } from 'crypto';
+import { readFileSync, existsSync, mkdirSync, statSync, unlinkSync } from 'fs';
+import { join, resolve } from 'path';
+import { getPluginData } from '../config.mjs';
+import { enrichModels } from './model-catalog.mjs';
+import { sanitizeModelList } from './model-list-sanitize.mjs';
+import { writeJsonAtomicSync, withFileLock } from '../../../shared/atomic-file.mjs';
+import { boundProviderAuthPath } from '../../../shared/provider-auth-binding.mjs';
+import { makeModelCache } from './model-cache.mjs';
+
+import { sendViaWebSocket } from './openai-oauth-ws.mjs';
+import { _combineUsageWithWarmup } from './openai-ws-events.mjs';
+import { resolveOpenAiTransportPolicy } from './openai-transport-policy.mjs';
+import {
+    buildStableProviderPromptCacheKey,
+    resolveProviderPromptCacheLane,
+    resolveProviderCacheKey,
+} from '../agent-runtime/cache-strategy.mjs';
+import {
+    appendAgentTrace,
+    traceAgentFetch,
+    traceAgentSse,
+    traceAgentUsage,
+} from '../agent-trace.mjs';
+import {
+    PROVIDER_HTTP_RESPONSE_TIMEOUT_MS,
+    PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS,
+    PROVIDER_SSE_IDLE_WATCHDOG_ENABLED,
+    streamStalledError,
+    createTimeoutSignal,
+    createPassthroughSignal,
+} from '../stall-policy.mjs';
+import { populateHttpStatusFromMessage, shouldFallbackTransport } from './retry-classifier.mjs';
+import { getLlmDispatcher, preconnect } from '../../../shared/llm/http-agent.mjs';
+import { makeInvalidToolArgsMarker } from './openai-compat-stream.mjs';
+import { createLeakGuard, createToolCallDedupe, dedupeToolCallList } from './anthropic-leaked-toolcall.mjs';
+import {
+    normalizeContentForOpenAIResponses,
+    splitToolContentForOpenAIResponses,
+} from './media-normalization.mjs';
+import {
+    customToolCallFromResponseItem,
+    customToolInputFromArguments,
+    isCustomToolCallRecord,
+    isResponsesFreeformTool,
+    nativeToolSearchCallInput,
+    nativeToolSearchOutputInput,
+    toResponsesCustomTool,
+} from './custom-tool-wire.mjs';
+import {
+    sendViaHttpSse,
+    _envFlag,
+    _shouldUseOpenAIHttpFallback,
+} from './openai-oauth-http-sse.mjs';
+import { createOpenAIOAuthLogin } from './openai-oauth-login.mjs';
+import { warmCodexClientVersion } from './codex-client-meta.mjs';
+import {
+    _displayCodexModel,
+    _codexFamily,
+    _normalizeCodexModel,
+    _compareVersion,
+    _isMainCodexFamily,
+    _markLatestCodex,
+} from './openai-codex-model.mjs';
+
+// Public test/integration entry retained alongside the transport module export.
+// --- Constants ---
+
+import { _findCachedCodexModel, codexModelSupportsServiceTier } from './openai-oauth.mjs';
+
+function _contentTextParts(content, type = 'input_text') {
+    if (typeof content === 'string') return content ? [{ type, text: content }] : [];
+    if (!Array.isArray(content)) {
+        const text = content == null ? '' : JSON.stringify(content);
+        return text ? [{ type, text }] : [];
+    }
+    const out = [];
+    for (const item of content) {
+        if (!item || typeof item !== 'object') continue;
+        if (typeof item.text === 'string') {
+            out.push({ type: item.type === 'output_text' ? 'output_text' : type, text: item.text });
+        } else if (typeof item.content === 'string') {
+            out.push({ type, text: item.content });
+        }
+    }
+    return out;
+}
+
+/**
+ * Convert a message slice to Responses API input items.
+ */
+export function convertMessagesToResponsesInput(messages, opts = {}) {
+    const out = [];
+    const pendingToolMedia = [];
+    const customToolCallNameById = new Map();
+    const wireParity = process.env.MIXDOG_OAI_CODEX_WIRE_PARITY === '1';
+    const wireMessage = (role, content) => (wireParity
+        ? { type: 'message', role, content, internal_chat_message_metadata_passthrough: {} }
+        : { role, content });
+    const flushToolMedia = () => {
+        if (!pendingToolMedia.length) return;
+        out.push(wireMessage('user', pendingToolMedia.splice(0)));
+    };
+    for (const m of messages) {
+        if (!m || m.role === 'system') continue;
+        if (m.role === 'tool') {
+            const { output, mediaContent } = splitToolContentForOpenAIResponses(m.content);
+            if (customToolCallNameById.has(m.toolCallId || '')) {
+                out.push({
+                    type: 'custom_tool_call_output',
+                    call_id: m.toolCallId || '',
+                    name: customToolCallNameById.get(m.toolCallId || '') || undefined,
+                    output,
+                });
+                if (mediaContent) pendingToolMedia.push(...mediaContent);
+                continue;
+            }
+            const nativeSearchOutput = nativeToolSearchOutputInput(
+                m,
+                opts.nativeToolSearchProvider || 'openai-oauth',
+            );
+            if (nativeSearchOutput) {
+                out.push(nativeSearchOutput);
+                if (mediaContent) pendingToolMedia.push(...mediaContent);
+                continue;
+            }
+            out.push({
+                type: 'function_call_output',
+                call_id: m.toolCallId || '',
+                output,
+            });
+            if (mediaContent) pendingToolMedia.push(...mediaContent);
+            continue;
+        }
+        flushToolMedia();
+        if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length) {
+            // Reasoning replay deliberately omitted: openai-oauth rejects an
+            // `rs_*` reasoning item with the same id across the same
+            // handshake session_id (in-memory conversation state lives
+            // for the WS_IDLE_MS window even after a socket close).
+            // Server-side state already preserves the prefix; sending
+            // reasoning in `input` triggers "Duplicate item".
+            if (m.content) out.push(wireMessage('assistant', normalizeContentForOpenAIResponses(m.content, { role: 'assistant' })));
+            for (const tc of m.toolCalls) {
+                const nativeSearchCall = nativeToolSearchCallInput(tc);
+                if (nativeSearchCall) {
+                    out.push(nativeSearchCall);
+                } else if (isCustomToolCallRecord(tc)) {
+                    if (tc.id) customToolCallNameById.set(tc.id, tc.name || '');
+                    out.push({
+                        type: 'custom_tool_call',
+                        call_id: tc.id,
+                        name: tc.name,
+                        input: customToolInputFromArguments(tc.name, tc.arguments),
+                    });
+                } else {
+                    out.push({
+                        type: 'function_call',
+                        call_id: tc.id,
+                        name: tc.name === 'tool_search' ? 'load_tool' : tc.name,
+                        arguments: JSON.stringify(tc.arguments),
+                    });
+                }
+            }
+            continue;
+        }
+        out.push(wireMessage(
+            m.role === 'assistant' ? 'assistant' : 'user',
+            normalizeContentForOpenAIResponses(m.content, { role: m.role }),
+        ));
+    }
+    flushToolMedia();
+    return out;
+}
+
+export function toOpenAIResponsesTool(t) {
+    if (t?.name === 'load_tool' || t?.name === 'tool_search') {
+        return {
+            type: 'tool_search',
+            execution: 'client',
+            description: t.description,
+            parameters: t.inputSchema,
+        };
+    }
+    if (isResponsesFreeformTool(t)) return toResponsesCustomTool(t);
+    return {
+        type: 'function',
+        name: t.name,
+        description: t.description,
+        parameters: t.inputSchema,
+    };
+}
+
+export const _convertMessagesToResponsesInputForTest = convertMessagesToResponsesInput;
+
+// codex build_reasoning() (core/src/client.rs:785-805) only attaches the
+// reasoning object when model_info.supports_reasoning_summaries; models
+// without summary support get NO reasoning field at all. Mirror that via the
+// cached codex catalog; unknown models default to true (gpt-5 family all
+// support summaries) so a cold catalog cannot strip reasoning from the wire.
+function _codexModelSupportsReasoningSummaries(id) {
+    const info = _findCachedCodexModel(id);
+    if (!info) return true;
+    const flags = [info.supportsReasoningSummaries, info.supports_reasoning_summaries, info.supportsReasoning, info.supports_reasoning];
+    for (const flag of flags) {
+        if (typeof flag === 'boolean') return flag;
+    }
+    return true;
+}
+
+// codex reasoning_effort_for_request (core/src/client.rs): `ultra` collapses to
+// `max` on the wire — the openai-oauth backend does not accept `ultra`. Every
+// other effort passes through unchanged; empty/unknown falls back to medium.
+export function _normalizeReasoningEffort(effort) {
+    const e = String(effort || '').trim().toLowerCase();
+    if (!e) return 'medium';
+    if (e === 'ultra') return 'max';
+    return e;
+}
+
+export function buildRequestBody(messages, model, tools, sendOpts) {
+    // codex reasoning_effort_for_request: `ultra` collapses to `max` on the
+    // wire (the only remap; every other effort passes through). Default medium.
+    // Kept inline (not a module const) so buildRequestBody stays self-contained.
+    // Extract system/instructions
+    const systemMsgs = messages.filter(m => m.role === 'system');
+    const instructions = systemMsgs.map(m => m.content).join('\n\n') || 'You are a helpful assistant.';
+    const opts = sendOpts || {};
+    const input = convertMessagesToResponsesInput(messages, {
+        providerState: opts.providerState,
+        model,
+        nativeToolSearchProvider: opts.promptCacheProvider || 'openai-oauth',
+    });
+    // Match the request body shape the OAuth backend expects so the
+    // server-side auto-cache routes correctly. text.verbosity / include /
+    // tool_choice / parallel_tool_calls are all inert without side effects
+    // for most callers but their presence affects how the OAuth backend classifies the
+    // request (and therefore whether the prompt cache is consulted).
+    const include = ['reasoning.encrypted_content'];
+    for (const item of Array.isArray(opts.nativeInclude) ? opts.nativeInclude : []) {
+        const value = String(item || '').trim();
+        if (value && !include.includes(value)) include.push(value);
+    }
+    // Field order MIRRORS codex-rs ResponsesApiRequest (common.rs struct order):
+    // model, instructions, input, tools, tool_choice, parallel_tool_calls,
+    // reasoning, store, stream, include, service_tier, prompt_cache_key, text.
+    // JSON serialization order is load-bearing for the server prompt cache
+    // (exact-prefix match): matching codex's byte layout keeps our requests on
+    // the same cache-routing shape codex warms. tools/service_tier/
+    // prompt_cache_key are appended below in the same relative order.
+    const body = {
+        model,
+        instructions,
+        input,
+        tool_choice: opts.toolChoice || 'auto',
+        parallel_tool_calls: true,
+        // codex build_reasoning() sends { effort, summary } — summary defaults to
+        // ReasoningSummary::Auto (protocol config_types.rs), serialized lowercase
+        // as "auto". Matching this keeps our reasoning object byte-identical to
+        // codex so the server prompt-cache prefix hash lines up. codex also
+        // normalizes `ultra` -> `max` on the wire (reasoning_effort_for_request
+        // in core/src/client.rs); the openai-oauth backend does not accept
+        // `ultra` as a wire value, so mirror that mapping here.
+        // WIRE-VERIFIED (codex desktop logs_2.sqlite, 40 response.create
+        // captures, 2026-07-03): codex sends reasoning as {"effort":"..."}
+        // with NO summary field on gpt-5.5, regardless of what the repo's
+        // build_reasoning() suggests. Match the observed bytes.
+        reasoning: { effort: _normalizeReasoningEffort(opts.effort) },
+        store: process.env.MIXDOG_OAI_STORE === 'true' ? true : false,
+        stream: true,
+        include,
+    };
+    const maxOutputTokens = Number(opts.maxOutputTokens ?? opts.outputTokens ?? opts.max_output_tokens);
+    if (_envFlag('MIXDOG_OPENAI_OAUTH_SEND_MAX_OUTPUT_TOKENS', false)
+        && Number.isFinite(maxOutputTokens)
+        && maxOutputTokens > 0) {
+        body.max_output_tokens = Math.floor(maxOutputTokens);
+    }
+    if (opts.fast === true) {
+        // 'priority' is the only fast-class value the OpenAI OAuth backend
+        // accepts on the wire: 'fast' is hard-rejected ("Unsupported
+        // service_tier: fast", probed 2026-06-11). Only send the request value
+        // when the model catalog advertises it.
+        if (codexModelSupportsServiceTier(model, 'priority')) {
+            body.service_tier = 'priority';
+        }
+    }
+    // Add tools. `nativeTools` are server-hosted Responses tools (for
+    // example web_search) and must be passed through without wrapping them as
+    // function tools. codex places `tools` right after `input` (before
+    // tool_choice); we insert it there via a rebuilt object so serialization
+    // order matches, rather than appending it last.
+    const functionTools = tools?.length ? tools.map(toOpenAIResponsesTool) : [];
+    const nativeTools = Array.isArray(opts.nativeTools)
+        ? opts.nativeTools.filter(t => t && typeof t === 'object')
+        : [];
+    const toolsList = (functionTools.length || nativeTools.length)
+        ? [...nativeTools, ...functionTools]
+        : null;
+    const promptCacheProvider = opts.promptCacheProvider || 'openai-oauth';
+    const promptCacheLane = opts.promptCacheLane || resolveProviderPromptCacheLane(promptCacheProvider, opts);
+    const promptCacheKey = buildStableProviderPromptCacheKey(promptCacheProvider, opts, {
+        model,
+        instructions,
+        tools: toolsList || [],
+        effort: body.reasoning?.effort,
+        fast: opts.fast === true,
+        serviceTier: body.service_tier || '',
+        toolChoice: body.tool_choice,
+        parallelToolCalls: body.parallel_tool_calls,
+        cacheLaneSlot: promptCacheLane.slot,
+        cacheLaneShards: promptCacheLane.shards,
+    });
+    // WIRE-VERIFIED (codex desktop logs, 2026-07-03): every live gpt-5.5
+    // response.create carries text:{"verbosity":"low"} (or a schema variant);
+    // none omit the field. Default to codex's observed "low", allow override.
+    const verbosity = (typeof opts.verbosity === 'string' && opts.verbosity.trim()
+        ? opts.verbosity.trim().toLowerCase()
+        : null) || 'low';
+    // Rebuild the body in codex struct order so JSON serialization is
+    // byte-compatible with codex: ... input, tools, tool_choice,
+    // parallel_tool_calls, reasoning, store, stream, include, service_tier,
+    // prompt_cache_key, text. service_tier is only present when fast set it.
+    const ordered = {
+        model: body.model,
+        instructions: body.instructions,
+        input: body.input,
+        ...(toolsList ? { tools: toolsList } : {}),
+        tool_choice: body.tool_choice,
+        parallel_tool_calls: body.parallel_tool_calls,
+        reasoning: body.reasoning,
+        store: body.store,
+        stream: body.stream,
+        include: body.include,
+        ...(body.service_tier ? { service_tier: body.service_tier } : {}),
+        prompt_cache_key: promptCacheKey,
+        text: { verbosity },
+        ...(body.max_output_tokens ? { max_output_tokens: body.max_output_tokens } : {}),
+    };
+    // NOTE: prompt_cache_retention is a public OpenAI Responses API parameter,
+    // but the openai-oauth endpoint still rejects it ("Unsupported parameter:
+    // prompt_cache_retention", re-probed 2026-06-22). Leave retention on the
+    // openai-oauth server default; public OpenAI direct injects 24h separately.
+    return ordered;
+}
+
+// --- Provider ---

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

@@ -0,0 +1,216 @@
+// Codex WS handshake helpers: CF cookie jar, id parity, debug dump redaction. Extracted from openai-ws-pool.mjs.
+/**
+ * openai-ws-pool.mjs — WebSocket connection pool for the OpenAI OAuth provider.
+ *
+ * Extracted from openai-oauth-ws.mjs. Owns the socket pool singleton
+ * (_wsPool), handshake/open/acquire/release lifecycle, idle-close timers and
+ * the process-exit drain fence. openai-oauth-ws.mjs imports acquire/release/
+ * _sendFrame and re-exports the drain hooks for legacy import paths.
+ */
+import WebSocket from 'ws';
+import { errText } from '../../../shared/err-text.mjs';
+import { createHash, randomBytes } from 'crypto';
+import { performance } from 'node:perf_hooks';
+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,
+    PROVIDER_WS_PING_ENABLED,
+    PROVIDER_WS_PING_INTERVAL_MS,
+    PROVIDER_WS_PONG_TIMEOUT_MS,
+    PROVIDER_WS_LIVENESS_STALE_MS,
+    resolveTimeoutMs,
+} from '../stall-policy.mjs';
+
+// Human-readable transport label for handshake/acquire error messages. Shared
+// with openai-oauth-ws.mjs (stream-side errors use the same labels).
+import { _wsPool, _sendFrame } from './openai-ws-pool.mjs';
+
+const _cfCookieJar = new Map(); // accountKey -> { name -> value }
+const _CF_COOKIE_ALLOWLIST = new Set(['__cf_bm', '_cfuvid']);
+
+export function _envOn(name) {
+    const v = String(process.env[name] || '').trim().toLowerCase();
+    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.
+export 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);
+}
+
+export 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.
+export 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.
+export 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.
+export 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 || '');
+    }
+}
+
+export 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 {}
+}
+
+export 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');
+}
+
+export function _cfCookieHeader(auth) {
+    if (!_envOn('MIXDOG_OAI_CF_COOKIES')) return null;
+    const jar = _cfCookieJar.get(_cfCookieAccountKey(auth));
+    if (!jar || !jar.size) return null;
+    return [...jar.entries()].map(([k, v]) => `${k}=${v}`).join('; ');
+}
+
+export function _cfCookieCapture(auth, setCookieHeaders) {
+    if (!_envOn('MIXDOG_OAI_CF_COOKIES')) return;
+    const list = Array.isArray(setCookieHeaders) ? setCookieHeaders : (setCookieHeaders ? [setCookieHeaders] : []);
+    if (!list.length) return;
+    const key = _cfCookieAccountKey(auth);
+    let jar = _cfCookieJar.get(key);
+    if (!jar) { jar = new Map(); _cfCookieJar.set(key, jar); }
+    for (const raw of list) {
+        const pair = String(raw || '').split(';', 1)[0];
+        const eq = pair.indexOf('=');
+        if (eq <= 0) continue;
+        const name = pair.slice(0, eq).trim();
+        if (_CF_COOKIE_ALLOWLIST.has(name)) jar.set(name, pair.slice(eq + 1).trim());
+    }
+}