mixdog 0.9.94 → 0.9.95

package/src/runtime/agent/orchestrator/providers/anthropic-effort.mjs

@@ -17,6 +17,67 @@ function _sortEffortLevels(levels) {
     return [...levels].sort((a, b) => rank(a) - rank(b));
 }
 
+// Control flags that ride the capabilities.effort map alongside real levels
+// (`{supported:true, low:true, …}`). They are NOT selectable effort levels;
+// letting them through minted a bogus "supported" level that got persisted
+// into the on-disk catalog and offered in the UI.
+const CONTROL_EFFORT_KEYS = new Set(['supported', 'enabled', 'default']);
+
+// ── Catalog-first capability index ───────────────────────────────────────
+// The provider catalog already carries what each model advertises
+// (capabilities.effort → reasoningOptions:[{type:'effort',values:[…]}]), so it
+// — not a hardcoded regex ladder — is the source of truth for what we put on
+// the wire. anthropic-model-resolve feeds this whenever the in-memory catalog
+// moves. The regex ladder below stays as the fallback for ids the catalog does
+// not know (offline start, api-key provider, first run before /v1/models).
+const _catalogEffortLevels = new Map();
+
+function _catalogKeys(model) {
+    const id = normalizeModelId(model);
+    if (!id) return [];
+    // A dated id and its bare version alias describe the SAME model — index
+    // both so `claude-opus-5` and `claude-opus-5-20260101` resolve alike.
+    const undated = id.replace(/-\d{8}$/, '');
+    return undated !== id ? [id, undated] : [id];
+}
+
+/**
+ * Replace the catalog-derived capability index. Records without a
+ * `reasoningOptions` array are treated as UNKNOWN (skipped, so the regex
+ * fallback still applies) rather than as "no effort" — offline/static fallback
+ * lists carry no capability data and must not disable effort.
+ */
+export function setModelEffortCapabilities(models) {
+    _catalogEffortLevels.clear();
+    if (!Array.isArray(models)) return;
+    for (const model of models) {
+        if (!model?.id || !Array.isArray(model.reasoningOptions)) continue;
+        const option = model.reasoningOptions.find(
+            (entry) => String(entry?.type || '').trim().toLowerCase() === 'effort',
+        );
+        const levels = new Set(
+            (Array.isArray(option?.values) ? option.values : [])
+                .map((value) => String(value || '').trim().toLowerCase())
+                .filter((value) => value && !CONTROL_EFFORT_KEYS.has(value)),
+        );
+        for (const key of _catalogKeys(model.id)) {
+            const existing = _catalogEffortLevels.get(key);
+            // A bare alias shared by several records keeps the richer entry.
+            if (existing?.size && levels.size === 0) continue;
+            _catalogEffortLevels.set(key, levels);
+        }
+    }
+}
+
+/** Advertised levels for `model`, or null when the catalog has no record. */
+function _catalogLevels(model) {
+    for (const key of _catalogKeys(model)) {
+        const levels = _catalogEffortLevels.get(key);
+        if (levels) return levels;
+    }
+    return null;
+}
+
 export const EFFORT_BETA_HEADER = 'effort-2025-11-24';
 
 export const LEGACY_EFFORT_BUDGET = Object.freeze({
@@ -40,7 +101,10 @@ function parseClaudeVersion(model) {
     if (triple) {
         return { family: triple[1], major: Number(triple[2]), minor: Number(triple[3]) };
     }
-    const pair = m.match(/^claude-(sonnet|fable)-(\d+)(?:$|[-@])/);
+    // Bare version ids carry family + major only (claude-opus-5). opus/haiku
+    // were missing here, so `claude-opus-5` parsed to null and fell through
+    // every capability check as an unknown shape.
+    const pair = m.match(/^claude-(sonnet|fable|opus|haiku)-(\d+)(?:$|[-@])/);
     if (pair) {
         return { family: pair[1], major: Number(pair[2]), minor: null };
     }
@@ -64,6 +128,9 @@ function isLegacyAnthropicReasoningModel(model) {
     if (parsed.family === 'sonnet' || parsed.family === 'opus') {
         if (parsed.major < 4) return true;
         if (parsed.major === 4 && parsed.minor !== null && parsed.minor < 6) return true;
+        // Bare major, no minor (claude-opus-4 / claude-sonnet-4): adaptive
+        // effort only ships from 5 up, so 4.x aliases stay manual-thinking.
+        if (parsed.minor === null && parsed.major < 5) return true;
         return false;
     }
     return false;
@@ -72,13 +139,22 @@ function isLegacyAnthropicReasoningModel(model) {
 // @[MODEL LAUNCH]: extend allowlist when new Claude models ship with effort support.
 export function modelSupportsEffort(model) {
     if (isEnvTruthy(process.env.MIXDOG_ANTHROPIC_ALWAYS_ENABLE_EFFORT)) return true;
+    const advertised = _catalogLevels(model);
+    if (advertised) return advertised.size > 0;
+    return _regexSupportsEffort(model);
+}
+
+// Fallback ladder for ids the catalog does not carry. Also used by
+// effortValuesForModel, which BUILDS the catalog records and therefore must
+// never consult the index it feeds.
+function _regexSupportsEffort(model) {
     const m = normalizeModelId(model);
     if (!m.includes('claude')) return false;
     if (isLegacyAnthropicReasoningModel(model)) return false;
     if (m.includes('opus-4-6') || m.includes('sonnet-4-6')) return true;
     if (m.includes('sonnet-5') || m.includes('fable-5')) return true;
     if (/^claude-opus-4-(6|7|8)(?:$|[-@])/.test(m)) return true;
-    if (/^claude-opus-5-/.test(m)) return true;
+    if (/^claude-opus-5(?:$|[-@])/.test(m)) return true;
     // Fallthrough for not-yet-enumerated modern models: only grant effort when
     // parseClaudeVersion resolves a family with major>=4 (and not a manual-
     // thinking legacy already excluded above). A bare `startsWith('claude-')`
@@ -98,6 +174,12 @@ export function modelSupportsEffort(model) {
 // supported by: Fable 5, Mythos 5, Opus 4.8, Opus 4.7, Sonnet 5.
 // NOT Opus 4.6 / Sonnet 4.6 (those support max but not xhigh).
 export function modelSupportsXhighEffort(model) {
+    const advertised = _catalogLevels(model);
+    if (advertised) return advertised.has('xhigh');
+    return _regexSupportsXhighEffort(model);
+}
+
+function _regexSupportsXhighEffort(model) {
     const m = normalizeModelId(model);
     if (/^claude-opus-4-(7|8)(?:$|[-@])/.test(m)) return true;
     if (/^claude-opus-5(?:$|[-@])/.test(m)) return true;
@@ -111,7 +193,14 @@ export function modelSupportsXhighEffort(model) {
 // @[MODEL LAUNCH]: extend when new Opus models support max effort.
 // Max list = xhigh list PLUS Opus 4.6, Sonnet 4.6, Opus 4.5.
 export function modelSupportsMaxEffort(model) {
-    if (modelSupportsXhighEffort(model)) return true;
+    const advertised = _catalogLevels(model);
+    // xhigh support implies max support (kept from the ladder below).
+    if (advertised) return advertised.has('max') || advertised.has('xhigh');
+    return _regexSupportsMaxEffort(model);
+}
+
+function _regexSupportsMaxEffort(model) {
+    if (_regexSupportsXhighEffort(model)) return true;
     const m = normalizeModelId(model);
     if (/^claude-opus-4-(5|6)(?:$|[-@])/.test(m)) return true;
     if (/^claude-sonnet-4-6(?:$|[-@])/.test(m)) return true;
@@ -209,7 +298,7 @@ export function applyAnthropicEffortToBody(
         // Set unconditionally (independent of `normalized`) so effort-capable
         // turns always carry adaptive thinking + round-trip signatures.
         // MIXDOG_ANTHROPIC_THINKING_DISPLAY=omitted (operator/bench knob):
-        // CC-parity mode — no thinking blocks come back, so nothing is
+        // thinking blocks are omitted entirely, so nothing is
         // replayed into later requests (saves the 1h cache-write + re-read on
         // accumulated thinking) at the cost of losing visible reasoning and
         // cross-iteration thinking continuity. Default stays summarized.
@@ -254,7 +343,8 @@ export function effortValuesForModel(capabilities, modelId) {
     // advertises (xhigh, max, or anything future), no hardcoded allowlist.
     if (effort !== true && typeof effort === 'object') {
         const advertised = Object.keys(effort).filter(
-            (level) => effort[level] === true || effort[level]?.supported === true,
+            (level) => !CONTROL_EFFORT_KEYS.has(String(level).trim().toLowerCase())
+                && (effort[level] === true || effort[level]?.supported === true),
         );
         if (advertised.length) return _sortEffortLevels(advertised);
         // Object with no per-level flags: fall through to the boolean/supported
@@ -265,10 +355,10 @@ export function effortValuesForModel(capabilities, modelId) {
     // the model supports effort but doesn't enumerate levels, so derive the
     // set from the known level ladder, gated by the top-tier model check.
     let levels = [...EFFORT_LEVELS];
-    if (!modelSupportsMaxEffort(modelId)) {
+    if (!_regexSupportsMaxEffort(modelId)) {
         levels = levels.filter((level) => level !== 'max');
     }
-    if (!modelSupportsXhighEffort(modelId)) {
+    if (!_regexSupportsXhighEffort(modelId)) {
         levels = levels.filter((level) => level !== 'xhigh');
     }
     return levels;

package/src/runtime/agent/orchestrator/providers/anthropic-model-resolve.mjs

@@ -8,20 +8,22 @@
 import { enrichModels } from './model-catalog.mjs';
 import { sanitizeModelList } from './model-list-sanitize.mjs';
 import { makeModelCache } from './model-cache.mjs';
-import { effortValuesForModel } from './anthropic-effort.mjs';
+import { effortValuesForModel, setModelEffortCapabilities } from './anthropic-effort.mjs';
 
 // Disk-backed cache so repeated process starts (cron, tool calls) don't
 // hammer /v1/models. 24h TTL matches the upstream client cadence.
 const MODEL_CACHE_TTL_MS = 24 * 60 * 60_000;
 // Bump when the on-disk cache shape changes so stale-shape entries are
 // discarded instead of misread.
-const ANTHROPIC_MODEL_CACHE_SCHEMA_VERSION = 1;
+// v2: effort level lists no longer carry the `supported` control flag as a
+// selectable level, so v1 caches are discarded rather than replayed.
+const ANTHROPIC_MODEL_CACHE_SCHEMA_VERSION = 2;
 
 const _modelCache = makeModelCache({
     fileName: 'anthropic-oauth-models.json',
     ttlMs: MODEL_CACHE_TTL_MS,
     version: ANTHROPIC_MODEL_CACHE_SCHEMA_VERSION,
-    onSave: (m) => { _inMemoryCatalog = Array.isArray(m) ? m.slice() : null; },
+    onSave: (m) => { _setInMemoryCatalog(m); },
 });
 
 // Async wrappers so callers can keep awaiting; the shared cache CRUD is sync.
@@ -42,6 +44,9 @@ let _inMemoryCatalog = null;
 // listModels() warm path, so expose a setter instead of the raw binding.
 export function _setInMemoryCatalog(models) {
     _inMemoryCatalog = Array.isArray(models) ? models.slice() : null;
+    // The request builder resolves effort capability from the catalog, so the
+    // capability index moves with the mirror — one write, one source of truth.
+    setModelEffortCapabilities(_inMemoryCatalog || []);
 }
 
 export function _catalogHas(id) {
@@ -185,7 +190,9 @@ export function _catalogOutputTokens(model) {
     try {
         if (!Array.isArray(_inMemoryCatalog)) {
             const cached = _modelCache.loadSync();
-            if (Array.isArray(cached)) _inMemoryCatalog = cached.slice();
+            // Route the lazy warm through the setter: a direct assignment left
+            // the effort-capability index empty even though the mirror was warm.
+            if (Array.isArray(cached)) _setInMemoryCatalog(cached);
         }
         if (!Array.isArray(_inMemoryCatalog)) return null;
         const entry = _inMemoryCatalog.find(m => m?.id === model);

package/src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs

@@ -1094,7 +1094,7 @@ export class AnthropicOAuthProvider {
                     continue;
                 }
                 const classifier = _classifyMidstreamError(err, midState);
-                // CC-parity stall recovery (2026-08-03 v3 postmortem): a
+                // Stall recovery (2026-08-03 v3 postmortem): a
                 // stalled stream that exposed NOTHING (no text/thinking
                 // relayed, no tool emitted) is re-issued NON-STREAMING instead
                 // of retrying the same streaming shape. Effort-mode models can
@@ -1103,8 +1103,7 @@ export class AnthropicOAuthProvider {
                 // generation into the same timer (observed live: deterministic
                 // 4×~138s beheading, ~552s per turn), while the non-streaming
                 // transport simply waits for the full body (bounded by
-                // PROVIDER_NONSTREAM_TOTAL_TIMEOUT_MS). Claude Code does
-                // exactly this on its watchdog aborts. Replay is trivially
+                // PROVIDER_NONSTREAM_TOTAL_TIMEOUT_MS). Replay is trivially
                 // safe here — nothing was relayed or dispatched.
                 if (classifier === 'stream_stalled'
                     && _outcome?.replayUnsafe !== true

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -604,7 +604,7 @@ export class AnthropicProvider {
                         continue;
                     }
                     const classifier = _classifyMidstreamError(err, midState);
-                    // CC-parity stall recovery (ported from anthropic-oauth,
+                    // Stall recovery (shared with anthropic-oauth,
                     // 2026-08-03): a stalled stream that exposed NOTHING is
                     // re-issued non-streaming instead of retrying the same
                     // streaming shape into the same idle window. Replay is

package/src/runtime/agent/orchestrator/providers/codex-client-meta.mjs

@@ -2,13 +2,11 @@
  * codex-client-meta.mjs — codex client identity headers for the OpenAI OAuth
  * transports.
  *
- * codex-rs sends two client-identity headers on EVERY request including the
- * WS handshake:
+ * The reference client sends two client-identity headers on EVERY request,
+ * including the WS handshake:
  *  - `User-Agent: codex_cli_rs/<version> (<os> <ver>; <arch>) <terminal>`
- *    (login/src/auth/default_client.rs get_codex_user_agent + default_headers)
  *  - `version: <CARGO_PKG_VERSION>` via the built-in provider http_headers
- *    (model-provider-info/src/lib.rs:339-343), merged into the WS handshake by
- *    merge_request_headers (codex-api/src/endpoint/responses_websocket.rs).
+ *    merged into the WS handshake.
  * The backend uses these for client gating (model catalog visibility measured
  * 2026-07-03) and plausibly for x-codex-turn-state issuance / sticky
  * cache-node routing, so mixdog mirrors both.
@@ -17,7 +15,7 @@ import os from 'node:os';
 
 // Offline fallback only; live value refreshes from npm (24h TTL, in-process).
 // The backend gates model exposure AND per-request model access on the client
-// version (gpt-5.6-* require >= 0.144.0 per codex models-manager/models.json,
+// version (gpt-5.6-* require >= 0.144.0 per the published model catalog,
 // verified 2026-07-09), so keep this at the current release when bumping.
 const CODEX_CLIENT_VERSION_FLOOR = '0.144.1';
 const VERSION_TTL_MS = 24 * 60 * 60_000;

package/src/runtime/agent/orchestrator/providers/lib/stream-outcome.mjs

@@ -50,7 +50,7 @@
  *                        || toolCallsComplete > 0 || toolCallsDispatched > 0
  *   sideEffectDispatched = toolCallsDispatched > 0
  *   replayUnsafe       = the ONE architecture-specific deny MixDog adds on top
- *                        of the Codex retry rules, because it streams UI text
+ *                        of the standard retry rules, because it streams UI text
  *                        and dispatches tools eagerly:
  *                        visibleOutput || sideEffectDispatched
  *                        || dispatchAmbiguous || unsafe marker

package/src/runtime/agent/orchestrator/providers/openai-codex-metadata.mjs

@@ -35,8 +35,8 @@ function _codexInstallationId(sendOpts) {
         || `mixdog-${_hashText(`${process.env.USERPROFILE || process.env.HOME || ''}:${process.cwd()}`, 32)}`;
 }
 
-// The identity block codex rebuilds per request (responses_metadata.rs
-// client_metadata()): never cached on the pooled socket, or a later turn would
+// The identity block is rebuilt per request: never cached on the pooled
+// socket, or a later turn would
 // replay the first turn's identity.
 function _codexMetadataBase(entry, { poolKey, cacheKey, sendOpts, handshake = false } = {}) {
     const sessionId = _cleanMetaString(sendOpts?.codexSessionId || sendOpts?.session?.codexSessionId || poolKey || cacheKey)
@@ -49,8 +49,8 @@ function _codexMetadataBase(entry, { poolKey, cacheKey, sendOpts, handshake = fa
         : _sessionStartedAtUnixMs(sessionId);
     const requestKind = _codexRequestKind(sendOpts, sessionId);
     const wireParity = process.env.MIXDOG_OAI_CODEX_WIRE_PARITY === '1';
-    // codex opens the WS with a prewarm (empty turn_id) BEFORE the real turn
-    // (client.rs). Under wire parity the handshake IS that prewarm, so its
+    // The reference client opens the WS with a prewarm (empty turn_id) BEFORE
+    // the real turn. Under wire parity the handshake IS that prewarm, so its
     // turn_id empties and its request_kind becomes 'prewarm' instead of
     // presenting the handshake as a live turn. Parity off is unchanged.
     const isPrewarm = requestKind === 'prewarm' || handshake === true;
@@ -66,7 +66,7 @@ function _codexMetadataBase(entry, { poolKey, cacheKey, sendOpts, handshake = fa
         turn_id: turnId,
         window_id: windowId,
         request_kind: effectiveRequestKind,
-        // Richer codex turn-metadata (responses_metadata.rs:264-280). A/B
+        // Richer turn-metadata. A/B
         // 2026-07-04 showed no effect, so it stays behind a knob for future
         // probes; wire parity implies it.
         ...((process.env.MIXDOG_OAI_TURN_METADATA_RICH === '1' || wireParity) ? {
@@ -98,8 +98,8 @@ export function _metadataTrace(metadata) {
     };
 }
 
-// Handshake projection of the same identity. codex attaches these on every
-// request (client.rs:582-584, responses_metadata.rs:227-252); A/B 2026-07-04
+// Handshake projection of the same identity. These ride on every
+// request; A/B 2026-07-04
 // showed the turn-metadata blob alone lifts prefix-cache hits, so it is ON by
 // default. MIXDOG_OAI_TURN_METADATA overrides:
 //   unset|1|turn-metadata : window-id + turn-metadata + installation-id
@@ -141,7 +141,7 @@ export function _withCodexWsClientMetadata(frame, entry, enabled, context = {})
         'x-codex-ws-stream-request-start-ms': String(Date.now()),
     };
     if (entry && typeof entry === 'object') {
-        // codex scopes x-codex-turn-state to ONE turn (client.rs:263-279) while
+        // x-codex-turn-state is scoped to ONE turn while
         // pooled sockets span turns: attribute a captured token to the FIRST
         // turn that observes it, then drop it once turn_id moves on. An empty
         // turn_id (parity prewarm) is a valid owner, so the check is against

package/src/runtime/agent/orchestrator/providers/openai-oauth-http-sse.mjs

@@ -126,8 +126,8 @@ function _isMaxOutputIncompleteReason(reason) {
     return /^(?:max_output_tokens|max_tokens|length|output_token_limit)$/i.test(String(reason || '').trim());
 }
 
-// Wire-level `end_turn` on a terminal Responses frame (codex-rs
-// codex-api/src/sse/responses.rs ResponseCompleted.end_turn: Option<bool>).
+// Wire-level `end_turn` on a terminal Responses frame: an optional boolean on
+// the completed response.
 // Optional by contract: only a real boolean normalizes; a missing/non-boolean
 // field stays undefined so absence is never collapsed into false.
 export function _endTurnFromEvent(event) {
@@ -178,9 +178,9 @@ function _buildOpenAIHttpFallbackHeaders({ auth, cacheKey }) {
     };
     if (cacheKey) {
         const sid = String(cacheKey);
-        // Codex-native anchors (see openai-ws-pool _buildHandshakeHeaders):
-        // `session-id`/`thread-id` (hyphen) match codex-rs headers.rs; legacy
-        // underscore `session_id` kept for backward compat.
+        // Backend-native anchors (see openai-ws-pool _buildHandshakeHeaders):
+        // the hyphenated `session-id`/`thread-id` pair; legacy underscore
+        // `session_id` kept for backward compat.
         headers.session_id = sid;
         headers['session-id'] = sid;
         headers['thread-id'] = sid;
@@ -244,9 +244,8 @@ export async function sendViaHttpSse({
     const responsesUrl = auth?.type === 'openai-direct'
         ? OPENAI_DIRECT_RESPONSES_URL
         : CODEX_RESPONSES_URL;
-    // Request-body zstd (codex parity: core client.rs
-    // responses_request_compression enables zstd for the codex backend on the
-    // OpenAI provider — the server decompresses Content-Encoding: zstd).
+    // Request-body zstd: compression is enabled for the codex backend on the
+    // OpenAI provider — the server decompresses Content-Encoding: zstd.
     // openai-direct is excluded: only the codex backend is verified. Env
     // kill-switch plus a process-wide latch flipped on the first 400 seen on
     // a compressed request, which then replays that attempt uncompressed.

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

@@ -88,7 +88,7 @@ globalThis.__mixdogOpenaiWsRuntimeLoaded = true;
 // by connect/handshake and pre-output stream failures.
 const MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT = MIDSTREAM_RETRY_POLICY.ws.transientCloseRetries;
 const MIDSTREAM_DEFAULT_RETRY_LIMIT = MIDSTREAM_RETRY_POLICY.ws.defaultRetries;
-// Codex core/src/util.rs uses a 200ms base, factor 2, and symmetric ±10%
+// The reference client uses a 200ms base, factor 2, and symmetric ±10%
 // jitter for each of its five stream retries.
 const MIDSTREAM_BACKOFF_MS = Object.freeze([200, 400, 800, 1600, 3200]);
 const CODEX_RETRY_JITTER_RATIO = 0.1;
@@ -773,7 +773,7 @@ export async function sendViaWebSocket({
         let result;
         const streamTimeouts = null;
         try {
-            // codex prewarm gate (client.rs:1686-1688): only when the session
+            // Prewarm gate: only when the session
             // has no prior request state. A reused pooled socket with a live
             // chain must go straight to the real request.
             if (warmupBody && typeof warmupBody === 'object' && !completedWarmup

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

@@ -203,7 +203,7 @@ export function toOpenAIResponsesTool(t) {
 
 export const _convertMessagesToResponsesInputForTest = convertMessagesToResponsesInput;
 
-// codex build_reasoning() (core/src/client.rs:785-805) only attaches the
+// The reference client 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
@@ -218,7 +218,7 @@ function _codexModelSupportsReasoningSummaries(id) {
     return true;
 }
 
-// codex reasoning_effort_for_request (core/src/client.rs): `ultra` collapses to
+// Effort normalization: `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) {
@@ -251,12 +251,12 @@ export function buildRequestBody(messages, model, tools, sendOpts) {
         const value = String(item || '').trim();
         if (value && !include.includes(value)) include.push(value);
     }
-    // Field order MIRRORS codex-rs ResponsesApiRequest (common.rs struct order):
+    // Field order MIRRORS the reference request struct:
     // 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/
+    // (exact-prefix match): matching that byte layout keeps our requests on
+    // the same cache-routing shape the backend warms. tools/service_tier/
     // prompt_cache_key are appended below in the same relative order.
     const body = {
         model,
@@ -264,17 +264,15 @@ export function buildRequestBody(messages, model, tools, sendOpts) {
         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.
+        // The reference client sends { effort, summary } — summary defaults
+        // to "auto" (lowercase on the wire). Matching this keeps our
+        // reasoning object byte-identical so the server prompt-cache prefix
+        // hash lines up. `ultra` is normalized to `max` on the wire too; the
+        // openai-oauth backend does not accept `ultra` as a wire value, so
+        // mirror that mapping here.
+        // WIRE-VERIFIED (40 response.create captures, 2026-07-03): the wire
+        // carries reasoning as {"effort":"..."} with NO summary field on
+        // gpt-5.5. Match the observed bytes.
         reasoning: { effort: _normalizeReasoningEffort(opts.effort) },
         store: process.env.MIXDOG_OAI_STORE === 'true' ? true : false,
         stream: true,

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

@@ -41,8 +41,8 @@ export function _envOn(name) {
 // (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
+// The reference client sends dashed RFC-4122 UUIDs as session-id/thread-id;
+// 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
@@ -108,11 +108,12 @@ export function _codexBetaFeatures() {
     return out.join(',');
 }
 
-// --- Opt-in raw WS capture for byte-diff against codex-rs -------------------
+// --- Opt-in raw WS capture for wire byte-diff -------------------------------
 // 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
+// the reference client. 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;

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

@@ -110,16 +110,16 @@ function _selectIdleEntry(entries, compatibility) {
 }
 
 // --- Cache-route probe state (2026-07-04 hunt) -----------------------------
-// CF cookie stickiness (codex chatgpt_cloudflare_cookies.rs:22-55 persists
+// CF cookie stickiness (the reference client persists
 // __cf_bm/_cfuvid across HTTP clients; our WS handshakes never echo them, so
 // Cloudflare may re-shard every fresh socket). Jar is per-process, keyed by
 // auth account. Env knobs (A/B):
 //   MIXDOG_OAI_CF_COOKIES=1        capture Set-Cookie from the 101 upgrade and
 //                                  send Cookie on subsequent handshakes
 //   MIXDOG_OAI_SESSION_AFFINITY=1  send x-session-affinity: <cacheKey>
-//                                  (opencode request.ts:187, ws-pool.ts:66)
-//   MIXDOG_OAI_WS_URL_SESSION=0    drop the ?session_id= URL query (codex/pi/
-//                                  opencode all use the bare WS URL)
+//                                  (a known cache-affinity hint)
+//   MIXDOG_OAI_WS_URL_SESSION=0    drop the ?session_id= URL query (reference
+//                                  clients all use the bare WS URL)
 function _getPoolArr(poolKey) {
     if (!poolKey) return null;
     let arr = _wsPool.get(poolKey);
@@ -340,15 +340,15 @@ function _buildHandshakeHeaders({ auth, sessionToken, turnState, cacheKey: _cach
             '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
-    // (client.rs:1033-1057), but OUR backend measurements disagree with pure
-    // codex parity here: 2026-04-19 probes showed the OAuth backend dedupes
+    // The reference client sends only the dashed session-id/thread-id pair,
+    // but OUR backend measurements disagree with pure
+    // wire parity here: 2026-04-19 probes showed the OAuth backend dedupes
     // 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.
     // 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
+    // probes; R15 regressed to 13% miss when it was dropped). Strict wire
+    // parity 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
@@ -432,7 +432,7 @@ function _openSocket({ auth, sessionToken, turnState, externalSignal, cacheKey,
     if (process.env.MIXDOG_DEBUG_AGENT) {
         process.stderr.write(`[agent-trace] ws-open-start url=${baseUrl} tokenHash=${createHash('sha256').update(String(sessionToken)).digest('hex').slice(0, 8)} ts=${_wsOpenStart}\n`);
     }
-    // Bare WS URL by default (codex/pi/opencode parity). Interleaved A/B
+    // Bare WS URL by default (reference-client parity). Interleaved A/B
     // (2026-07-04, ivA/ivB, 24 sessions each, alternating rounds to cancel
     // server-time noise): dropping the ?session_id= query improved it1
     // warmup-prefix hits 15/24 -> 22/24 and it2 full hits 11 -> 15 (miss

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

@@ -126,9 +126,8 @@ function _writeWsLifecycleTrace(lifecycle) {
     process.stderr.write(`[ws-trace] t=${new Date().toISOString()} lifecycle=${lifecycle}\n`);
 }
 
-// Wire-level `end_turn` on a terminal Responses frame (codex-rs
-// codex-api/src/sse/responses.rs ResponseCompleted.end_turn: Option<bool>,
-// consumed in core/src/session/turn.rs:2299 as "false ⇒ needs follow-up").
+// Wire-level `end_turn` on a terminal Responses frame: an optional boolean on
+// the completed response, where "false ⇒ needs follow-up".
 // The field is optional: only a real boolean is normalized; anything else —
 // including a missing field — stays undefined so absence is preserved and no
 // caller can mistake "server said nothing" for "server said true/false".