mixdog 0.9.33 → 0.9.34

package/scripts/provider-toolcall-test.mjs

@@ -12,11 +12,15 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 
 import {
+    OpenAICompatProvider,
     _toResponsesToolsForTest,
     _toXaiResponsesInputForTest,
     parseToolCalls as compatParseToolCalls,
     parseResponsesToolCalls as compatParseResponsesToolCalls,
 } from '../src/runtime/agent/orchestrator/providers/openai-compat.mjs';
+import {
+    GrokOAuthProvider,
+} from '../src/runtime/agent/orchestrator/providers/grok-oauth.mjs';
 import {
     consumeCompatResponsesStream,
     isInvalidToolArgsMarker,
@@ -26,14 +30,26 @@ import {
 } from '../src/runtime/agent/orchestrator/providers/openai-compat-stream.mjs';
 import {
     _computeDelta,
+    _buildResponseCreateFrame,
+    _sansInput,
+    _stableStringify,
 } from '../src/runtime/agent/orchestrator/providers/openai-ws-delta.mjs';
 import {
     _cacheObservationForTest,
 } from '../src/runtime/agent/orchestrator/providers/openai-oauth-ws.mjs';
+import {
+    _withCodexWsClientMetadata,
+} from '../src/runtime/agent/orchestrator/providers/openai-oauth-ws.mjs';
+import {
+    _captureTurnStateFromEvent,
+} from '../src/runtime/agent/orchestrator/providers/openai-ws-stream.mjs';
 import {
     createGeminiTextLeakGuard,
     parseToolCalls as geminiParseToolCalls,
 } from '../src/runtime/agent/orchestrator/providers/gemini.mjs';
+import {
+    _resolveGeminiCacheUsage,
+} from '../src/runtime/agent/orchestrator/providers/gemini-cache.mjs';
 import { parseSSEStream as anthropicParseSSEStream } from '../src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs';
 import { _buildRequestBodyForCacheSmoke } from '../src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs';
 import {
@@ -294,6 +310,52 @@ test('gemini leak guard: unknown tool name → text flushed, no synthetic call',
     assert.ok(content.includes('nonexistent_tool'));
 });
 
+test('gemini cache usage: official cached token fields are subsets of prompt tokens', () => {
+    const direct = _resolveGeminiCacheUsage({
+        usageMetadata: { promptTokenCount: 1000, cachedContentTokenCount: 400 },
+    });
+    assert.deepEqual({
+        inputTokens: direct.inputTokens,
+        reportedCachedTokens: direct.reportedCachedTokens,
+        cachedTokens: direct.cachedTokens,
+        cacheTokenSource: direct.cacheTokenSource,
+    }, {
+        inputTokens: 1000,
+        reportedCachedTokens: 400,
+        cachedTokens: 400,
+        cacheTokenSource: 'usage_metadata',
+    });
+
+    const sdkAlias = _resolveGeminiCacheUsage({
+        usageMetadata: { prompt_token_count: 1200, total_cached_tokens: 500 },
+    });
+    assert.equal(sdkAlias.inputTokens, 1200);
+    assert.equal(sdkAlias.reportedCachedTokens, 500);
+    assert.equal(sdkAlias.cachedTokens, 500);
+});
+
+test('gemini cache usage: clamps over-reported cache and falls back only for attached cachedContent', () => {
+    const clamped = _resolveGeminiCacheUsage({
+        usageMetadata: { promptTokenCount: 100, cachedContentTokenCount: 150 },
+    });
+    assert.equal(clamped.cachedTokens, 100);
+
+    const fallback = _resolveGeminiCacheUsage({
+        usageMetadata: { promptTokenCount: 1000 },
+        cachedContent: 'cachedContents/abc',
+        providerState: { gemini: { cacheTokenSize: 250 } },
+    });
+    assert.equal(fallback.cachedTokens, 250);
+    assert.equal(fallback.cacheTokenSource, 'cache_create_fallback');
+
+    const noFallbackWithoutAttachment = _resolveGeminiCacheUsage({
+        usageMetadata: { promptTokenCount: 1000 },
+        providerState: { gemini: { cacheTokenSize: 250 } },
+    });
+    assert.equal(noFallbackWithoutAttachment.cachedTokens, 0);
+    assert.equal(noFallbackWithoutAttachment.cacheTokenSource, 'none');
+});
+
 // === 3. anthropic / anthropic-oauth ========================================
 // tool_use block parser lives in anthropic-oauth.mjs:936 parseSSEStream
 // (content_block_start/delta/stop → toolCalls.push). anthropic.mjs has NO
@@ -564,6 +626,19 @@ test('anthropic(-oauth) leak guard: benign prose <function> mention preserved, n
 
 import { customToolCallFromResponseItem } from '../src/runtime/agent/orchestrator/providers/custom-tool-wire.mjs';
 import { parseToolSearchArgs } from '../src/runtime/agent/orchestrator/providers/openai-oauth-ws.mjs';
+import { _warmupContinuityTraceForTest } from '../src/runtime/agent/orchestrator/providers/openai-oauth-ws.mjs';
+
+test('openai-oauth-ws (warmup continuity): warmup id anchors first real; first-3 misses counted', () => {
+    const t = _warmupContinuityTraceForTest({
+        warmupUsed: true, warmupResponseId: 'resp_w', priorEntryResponseId: 'resp_w',
+        sentPrevResponseId: null, earlyCacheMisses: [false, 'warm_session_zero_cached_tokens', false, true],
+    });
+    assert.equal(t.warmup_chain_continuous, true);
+    assert.equal(t.warmup_first_real_prev_id, 'resp_w');
+    assert.deepEqual(t.early_cache_misses, [false, 'warm_session_zero_cached_tokens', false]);
+    assert.equal(t.early_cache_miss_count, 1);
+    assert.equal(_warmupContinuityTraceForTest({ warmupUsed: true, warmupResponseId: 'a', priorEntryResponseId: 'b' }).warmup_chain_continuous, false);
+});
 
 test('openai-oauth (shared custom-tool-wire): custom_tool_call item → canonical call', () => {
     const item = { type: 'custom_tool_call', call_id: 'ctc_1', name: 'apply_patch', input: '*** patch ***' };
@@ -1061,32 +1136,26 @@ test('anthropic effort: explicit thinkingBudgetTokens wins over effort', () => {
 });
 // === 9. OpenAI OAuth WS cache tracing ======================================
 
-test('openai oauth ws delta: default full frame is an expected mode, not a cache break', () => {
-    const previous = process.env.MIXDOG_OAI_WS_DELTA;
-    try {
-        delete process.env.MIXDOG_OAI_WS_DELTA;
-        const body = { model: 'gpt-5.5', input: [{ type: 'message', role: 'user', content: 'hi' }] };
-        const delta = _computeDelta({
-            entry: {
-                lastRequestSansInput: '{}',
-                lastResponseId: 'resp_prev',
-                lastRequestInput: body.input,
-                lastResponseItems: [],
-            },
-            body,
-        });
-        assert.equal(delta.mode, 'full');
-        assert.equal(delta.reason, 'full_default');
-        assert.equal(delta.frame.previous_response_id, undefined);
-    } finally {
-        if (previous == null) delete process.env.MIXDOG_OAI_WS_DELTA;
-        else process.env.MIXDOG_OAI_WS_DELTA = previous;
-    }
+test('openai oauth ws delta: default delta safely falls back on request-property mismatch', () => {
+    const body = { model: 'gpt-5.5', input: [{ type: 'message', role: 'user', content: 'hi' }] };
+    const delta = _computeDelta({
+        entry: {
+            lastRequestSansInput: '{}',
+            lastResponseId: 'resp_prev',
+            lastRequestInput: body.input,
+            lastResponseItems: [],
+        },
+        body,
+    });
+    assert.equal(delta.mode, 'full');
+    assert.equal(delta.reason, 'request_properties_changed');
+    assert.equal(delta.frame.previous_response_id, undefined);
 });
 
-test('openai oauth ws delta: opt-in still falls back without turn-state unless forced', () => {
-    const previous = process.env.MIXDOG_OAI_WS_DELTA;
+test('openai oauth ws delta: ws-delta mode uses previous_response_id without turn-state, keeps safe fallback', () => {
+    const prevTransport = process.env.MIXDOG_OAI_TRANSPORT;
     try {
+        process.env.MIXDOG_OAI_TRANSPORT = 'ws-delta';
         const body = {
             model: 'gpt-5.5',
             input: [
@@ -1099,24 +1168,124 @@ test('openai oauth ws delta: opt-in still falls back without turn-state unless f
             lastResponseId: 'resp_prev',
             lastRequestInput: [body.input[0]],
             lastResponseItems: [],
+            // NOTE: no turnState — ws-delta (refs) mode must still emit a delta.
         };
 
-        process.env.MIXDOG_OAI_WS_DELTA = '1';
-        const safe = _computeDelta({ entry, body });
-        assert.equal(safe.mode, 'full');
-        assert.equal(safe.reason, 'delta_missing_turn_state');
-        assert.equal(safe.frame.previous_response_id, undefined);
-
-        process.env.MIXDOG_OAI_WS_DELTA = 'force';
-        const forced = _computeDelta({ entry, body });
-        assert.equal(forced.mode, 'delta');
-        assert.equal(forced.frame.previous_response_id, 'resp_prev');
-        assert.deepEqual(forced.frame.input, [body.input[1]]);
+        const refs = _computeDelta({ entry, body });
+        assert.equal(refs.mode, 'delta');
+        assert.equal(refs.frame.previous_response_id, 'resp_prev');
+        assert.deepEqual(refs.frame.input, [body.input[1]]);
+
+        // Safe fallback preserved: a changed request property breaks the prefix
+        // and retreats to a full frame even in ws-delta mode.
+        const changed = _computeDelta({ entry, body: { ...body, model: 'gpt-5.6' } });
+        assert.equal(changed.mode, 'full');
+        assert.equal(changed.reason, 'request_properties_changed');
+        assert.equal(changed.frame.previous_response_id, undefined);
+
+        const noAnchor = _computeDelta({ entry: { ...entry, lastResponseId: null }, body });
+        assert.equal(noAnchor.mode, 'full');
+        assert.equal(noAnchor.reason, 'no_anchor');
+        assert.equal(noAnchor.frame.previous_response_id, undefined);
+
+        const prefixMismatch = _computeDelta({
+            entry: { ...entry, lastRequestInput: [{ type: 'message', role: 'user', content: 'other' }] },
+            body,
+        });
+        assert.equal(prefixMismatch.mode, 'full');
+        assert.equal(prefixMismatch.reason, 'input_prefix_mismatch');
+        assert.equal(prefixMismatch.frame.previous_response_id, undefined);
+
+        const responseMismatch = _computeDelta({
+            entry: {
+                ...entry,
+                lastRequestInput: [body.input[0]],
+                lastResponseItems: [{ type: 'function_call', call_id: 'call_1', name: 'tool', arguments: '{}' }],
+            },
+            body: {
+                ...body,
+                input: [
+                    body.input[0],
+                    { type: 'function_call', call_id: 'call_other', name: 'tool', arguments: '{}' },
+                    body.input[1],
+                ],
+            },
+        });
+        assert.equal(responseMismatch.mode, 'full');
+        assert.equal(responseMismatch.reason, 'response_output_mismatch:function_call');
+        assert.equal(responseMismatch.frame.previous_response_id, undefined);
     } finally {
-        if (previous == null) delete process.env.MIXDOG_OAI_WS_DELTA;
-        else process.env.MIXDOG_OAI_WS_DELTA = previous;
+        if (prevTransport == null) delete process.env.MIXDOG_OAI_TRANSPORT;
+        else process.env.MIXDOG_OAI_TRANSPORT = prevTransport;
     }
 });
+
+test('openai oauth ws delta: warmup generate:false does not force request_properties_changed', () => {
+    const prevTransport = process.env.MIXDOG_OAI_TRANSPORT;
+    try {
+        process.env.MIXDOG_OAI_TRANSPORT = 'ws-delta';
+        const warmupBody = { model: 'gpt-5.5', generate: false, input: [{ type: 'message', role: 'user', content: 'prev' }] };
+        const body = { model: 'gpt-5.5', input: [warmupBody.input[0], { type: 'message', role: 'user', content: 'next' }] };
+        const entry = {
+            lastRequestSansInput: _stableStringify(_sansInput(warmupBody)),
+            lastResponseId: 'resp_warm',
+            lastRequestInput: [warmupBody.input[0]],
+            lastResponseItems: [],
+        };
+        assert.equal(_sansInput(warmupBody).generate, undefined);      // warmup marker normalized out
+        const delta = _computeDelta({ entry, body });
+        assert.equal(delta.mode, 'delta');
+        assert.deepEqual(delta.frame.input, [body.input[1]]);
+        // Non-warmup generate difference still breaks the delta.
+        const genEntry = { ...entry, lastRequestSansInput: _stableStringify(_sansInput({ ...warmupBody, generate: true })) };
+        const genChanged = _computeDelta({ entry: genEntry, body });
+        assert.equal(genChanged.mode, 'full');
+        assert.equal(genChanged.reason, 'request_properties_changed');
+    } finally {
+        if (prevTransport == null) delete process.env.MIXDOG_OAI_TRANSPORT;
+        else process.env.MIXDOG_OAI_TRANSPORT = prevTransport;
+    }
+});
+
+test('canonical frame: full-frame builder leads with type and preserves codex body key order', () => {
+    const body = {
+        model: 'gpt-5.5',
+        instructions: 'sys',
+        input: [{ type: 'message', role: 'user', content: 'hi' }],
+        tool_choice: 'auto',
+        parallel_tool_calls: true,
+        reasoning: { effort: 'medium' },
+        store: false,
+        stream: true,
+        include: ['reasoning.encrypted_content'],
+        prompt_cache_key: 'k',
+        text: { verbosity: 'low' },
+    };
+    const frame = _buildResponseCreateFrame(body);
+    assert.deepEqual(Object.keys(frame), ['type', ...Object.keys(body)]);
+    assert.equal(frame.type, 'response.create');
+    // A full-frame build is byte-identical to the legacy spread form.
+    assert.equal(JSON.stringify(frame), JSON.stringify({ type: 'response.create', ...body }));
+    assert.equal(frame.previous_response_id, undefined);
+});
+
+test('canonical frame: delta insert keeps key order, drops empty instructions, overrides input', () => {
+    const body = {
+        model: 'gpt-5.5',
+        instructions: 'sys',
+        input: [{ a: 1 }, { b: 2 }],
+        tool_choice: 'auto',
+        text: { verbosity: 'low' },
+    };
+    const delta = _buildResponseCreateFrame(body, { previousResponseId: 'resp_prev', inputOverride: [{ b: 2 }] });
+    assert.deepEqual(Object.keys(delta), ['type', 'model', 'instructions', 'previous_response_id', 'input', 'tool_choice', 'text']);
+    assert.equal(delta.previous_response_id, 'resp_prev');
+    assert.deepEqual(delta.input, [{ b: 2 }]);
+    // Empty instructions is dropped in delta mode (server resolves via prev id).
+    const noInstr = _buildResponseCreateFrame({ ...body, instructions: '' }, { previousResponseId: 'resp_prev', inputOverride: [] });
+    assert.deepEqual(Object.keys(noInstr), ['type', 'model', 'previous_response_id', 'input', 'tool_choice', 'text']);
+});
+
 test('openai oauth ws cache observation detects warm zero and partial retreats', () => {
     const zero = _cacheObservationForTest({
         entry: { promptCacheMaxCachedTokens: 47_616 },
@@ -1141,3 +1310,333 @@ test('openai oauth ws cache observation detects warm zero and partial retreats',
     assert.equal(healthy.actualMiss, false);
     assert.equal(healthy.missReason, null);
 });
+
+// === 10. OpenAI transport-policy switch (MIXDOG_OAI_TRANSPORT) ==============
+// One clean knob selects among ws-full | ws-delta | http-sse | auto. The
+// resolver is a pure function over an injected env, and the delta gate
+// (_computeDelta) + transport dispatch both read it, so these unit tests pin
+// the resolution and the delta branching without any network.
+import {
+    resolveOpenAiTransportPolicy,
+    _normalizeTransportMode,
+} from '../src/runtime/agent/orchestrator/providers/openai-transport-policy.mjs';
+import {
+    resolveResponsesTransportPolicy,
+    RESPONSES_TRANSPORT_CAPABILITIES,
+    _gateTransportMode,
+    FULL_RESPONSES_TRANSPORT_CAPS,
+} from '../src/runtime/agent/orchestrator/providers/openai-transport-policy.mjs';
+
+test('transport policy: default (no env) is ws-delta / refs continuation ON', () => {
+    const p = resolveOpenAiTransportPolicy({});
+    assert.equal(p.mode, 'ws-delta');
+    assert.equal(p.transport, 'ws');
+    assert.equal(p.allowHttpFallback, false);
+    assert.deepEqual(p.delta, { force: false, refs: true, optIn: true });
+});
+
+test('transport policy: default ignores the legacy MIXDOG_OAI_WS_DELTA env', () => {
+    // Legacy compatibility removed: delta is selected solely via ws-delta mode.
+    assert.deepEqual(resolveOpenAiTransportPolicy({ MIXDOG_OAI_WS_DELTA: '1' }).delta, { force: false, refs: true, optIn: true });
+    assert.deepEqual(resolveOpenAiTransportPolicy({ MIXDOG_OAI_WS_DELTA: 'force' }).delta, { force: false, refs: true, optIn: true });
+    assert.deepEqual(resolveOpenAiTransportPolicy({ MIXDOG_OAI_WS_DELTA: 'refs' }).delta, { force: false, refs: true, optIn: true });
+});
+
+test('transport policy: ws-full forces full frames', () => {
+    const p = resolveOpenAiTransportPolicy({ MIXDOG_OAI_TRANSPORT: 'ws-full' });
+    assert.equal(p.transport, 'ws');
+    assert.equal(p.allowHttpFallback, false);
+    assert.equal(p.delta.optIn, false);
+});
+
+test('transport policy: ws-delta selects refs-compatible delta (no turn-state demand)', () => {
+    const p = resolveOpenAiTransportPolicy({ MIXDOG_OAI_TRANSPORT: 'ws-delta' });
+    assert.equal(p.transport, 'ws');
+    assert.equal(p.allowHttpFallback, false);
+    assert.deepEqual(p.delta, { force: false, refs: true, optIn: true });
+});
+
+test('transport policy: http-sse forces the HTTP transport with delta OFF', () => {
+    const p = resolveOpenAiTransportPolicy({ MIXDOG_OAI_TRANSPORT: 'http-sse' });
+    assert.equal(p.transport, 'http');
+    assert.equal(p.allowHttpFallback, false);
+    assert.equal(p.delta.optIn, false);
+});
+
+test('transport policy: unknown MIXDOG_OAI_TRANSPORT falls back to default ws-delta', () => {
+    const p = resolveOpenAiTransportPolicy({ MIXDOG_OAI_TRANSPORT: 'quantum' });
+    assert.equal(p.mode, 'ws-delta');
+    assert.equal(p.transport, 'ws');
+});
+
+test('response frame builder can omit transport-only stream/background for codex warmup parity', () => {
+    const body = { model: 'gpt-5.5', input: [{ a: 1 }, { b: 2 }], stream: true, background: false, text: { verbosity: 'low' } };
+    const full = _buildResponseCreateFrame(body, { omitTransportFields: true });
+    assert.equal('stream' in full || 'background' in full, false);
+    const d = _buildResponseCreateFrame(body, { previousResponseId: 'resp_prev', inputOverride: [{ b: 2 }], omitTransportFields: true });
+    assert.deepEqual([d.previous_response_id, d.input, 'stream' in d], ['resp_prev', [{ b: 2 }], false]);
+});
+
+test('transport policy: mode token aliases normalize', () => {
+    assert.equal(_normalizeTransportMode('WS_FULL'), 'ws-full');
+    assert.equal(_normalizeTransportMode('  ws delta '), 'ws-delta');
+    assert.equal(_normalizeTransportMode('http/sse'), 'http-sse');
+    assert.equal(_normalizeTransportMode('sse'), 'http-sse');
+    assert.equal(_normalizeTransportMode('auto'), 'ws-delta');
+    assert.equal(_normalizeTransportMode('official'), null);
+    assert.equal(_normalizeTransportMode(''), null);
+    assert.equal(_normalizeTransportMode('bogus'), null);
+});
+
+test('transport policy: ws-delta drives _computeDelta to emit a delta frame', () => {
+    const prevTransport = process.env.MIXDOG_OAI_TRANSPORT;
+    try {
+        process.env.MIXDOG_OAI_TRANSPORT = 'ws-delta';
+        const body = {
+            model: 'gpt-5.5',
+            input: [
+                { type: 'message', role: 'user', content: 'prev' },
+                { type: 'message', role: 'user', content: 'next' },
+            ],
+        };
+        const entry = {
+            lastRequestSansInput: '{"model":"gpt-5.5"}',
+            lastResponseId: 'resp_prev',
+            lastRequestInput: [body.input[0]],
+            lastResponseItems: [],
+            // no turnState — refs mode must still delta
+        };
+        const delta = _computeDelta({ entry, body });
+        assert.equal(delta.mode, 'delta');
+        assert.equal(delta.frame.previous_response_id, 'resp_prev');
+        assert.deepEqual(delta.frame.input, [body.input[1]]);
+    } finally {
+        if (prevTransport == null) delete process.env.MIXDOG_OAI_TRANSPORT;
+        else process.env.MIXDOG_OAI_TRANSPORT = prevTransport;
+    }
+});
+
+test('transport policy: ws-full forces _computeDelta to full (delta OFF)', () => {
+    const prevTransport = process.env.MIXDOG_OAI_TRANSPORT;
+    try {
+        process.env.MIXDOG_OAI_TRANSPORT = 'ws-full';
+        const body = { model: 'gpt-5.5', input: [{ type: 'message', role: 'user', content: 'hi' }] };
+        const delta = _computeDelta({
+            entry: {
+                lastRequestSansInput: '{"model":"gpt-5.5"}',
+                lastResponseId: 'resp_prev',
+                lastRequestInput: body.input,
+                lastResponseItems: [],
+            },
+            body,
+        });
+        assert.equal(delta.mode, 'full');
+        assert.equal(delta.reason, 'full_default');
+        assert.equal(delta.frame.previous_response_id, undefined);
+    } finally {
+        if (prevTransport == null) delete process.env.MIXDOG_OAI_TRANSPORT;
+        else process.env.MIXDOG_OAI_TRANSPORT = prevTransport;
+    }
+});
+
+// === 10b. Shared Responses transport policy (capability gating) ============
+// resolveResponsesTransportPolicy generalizes the OpenAI switch across every
+// Responses backend. Full-capability providers (OpenAI OAuth/direct) resolve
+// byte-identically to resolveOpenAiTransportPolicy; xAI/Grok also carry WS
+// delta capability, so default/ws-delta drive the OFFICIAL xAI continuation
+// (previous_response_id + incremental input) rather than collapsing to
+// 'ws-full'.
+
+test('responses transport policy: full caps === legacy OpenAI resolver (byte-identical)', () => {
+    for (const env of [
+        {},
+        { MIXDOG_OAI_TRANSPORT: 'ws-delta' },
+        { MIXDOG_OAI_TRANSPORT: 'ws-full' },
+        { MIXDOG_OAI_TRANSPORT: 'http-sse' },
+        { MIXDOG_OAI_TRANSPORT: 'quantum' },
+    ]) {
+        const legacy = resolveOpenAiTransportPolicy(env);
+        const shared = resolveResponsesTransportPolicy(env, RESPONSES_TRANSPORT_CAPABILITIES['openai-oauth']);
+        assert.equal(shared.mode, legacy.mode);
+        assert.equal(shared.transport, legacy.transport);
+        assert.equal(shared.allowHttpFallback, legacy.allowHttpFallback);
+        assert.deepEqual(shared.delta, legacy.delta);
+    }
+});
+
+test('responses transport policy: openai direct caps match oauth (both full)', () => {
+    const env = { MIXDOG_OAI_TRANSPORT: 'ws-delta' };
+    const direct = resolveResponsesTransportPolicy(env, RESPONSES_TRANSPORT_CAPABILITIES.openai);
+    assert.equal(direct.transport, 'ws');
+    assert.deepEqual(direct.delta, { force: false, refs: true, optIn: true });
+});
+
+test('responses transport policy: xai auto defers (transport=auto, delta OFF, no http fallback)', () => {
+    const p = resolveResponsesTransportPolicy({}, RESPONSES_TRANSPORT_CAPABILITIES.xai);
+    assert.equal(p.mode, 'ws-delta');
+    assert.equal(p.transport, 'ws');
+    assert.equal(p.allowHttpFallback, false);
+    assert.deepEqual(p.delta, { force: false, refs: true, optIn: true });
+});
+
+test('responses transport policy: explicit auto is a ws-delta compatibility spelling', () => {
+    const p = resolveResponsesTransportPolicy({ MIXDOG_OAI_TRANSPORT: 'auto' }, RESPONSES_TRANSPORT_CAPABILITIES.xai);
+    assert.equal(p.transport, 'ws');
+    assert.deepEqual(p.delta, { force: false, refs: true, optIn: true });
+});
+
+test('responses transport policy: xai ws-delta drives official continuation (refs delta ON)', () => {
+    const p = resolveResponsesTransportPolicy({ MIXDOG_OAI_TRANSPORT: 'ws-delta' }, RESPONSES_TRANSPORT_CAPABILITIES.xai);
+    assert.equal(p.requestedMode, 'ws-delta');
+    assert.equal(p.mode, 'ws-delta');
+    assert.equal(p.transport, 'ws');
+    assert.equal(p.allowHttpFallback, false);
+    // Official xAI continuation: previous_response_id + incremental input, no
+    // Codex turn-state — refs delta ON.
+    assert.deepEqual(p.delta, { force: false, refs: true, optIn: true });
+});
+
+test('responses transport policy: xai ws-full → WS, http-sse → HTTP', () => {
+    const wsFull = resolveResponsesTransportPolicy({ MIXDOG_OAI_TRANSPORT: 'ws-full' }, RESPONSES_TRANSPORT_CAPABILITIES.xai);
+    assert.equal(wsFull.transport, 'ws');
+    assert.equal(wsFull.allowHttpFallback, false);
+    const http = resolveResponsesTransportPolicy({ MIXDOG_OAI_TRANSPORT: 'http-sse' }, RESPONSES_TRANSPORT_CAPABILITIES.xai);
+    assert.equal(http.transport, 'http');
+    assert.equal(http.allowHttpFallback, false);
+});
+
+test('openai-compat/xai: provider-local HTTP pin beats global OAI ws-delta', async () => {
+    const prevTransport = process.env.MIXDOG_OAI_TRANSPORT;
+    try {
+        process.env.MIXDOG_OAI_TRANSPORT = 'ws-delta';
+        const provider = new OpenAICompatProvider('xai', {
+            apiKey: 'xai-test',
+            responsesTransport: 'http',
+        });
+        let httpCalled = false;
+        provider._doSendXaiResponses = async () => {
+            httpCalled = true;
+            return { content: 'ok' };
+        };
+        provider._doSendXaiResponsesWebSocket = async () => {
+            throw new Error('explicit HTTP transport should not use WS');
+        };
+        const result = await provider._doSend([{ role: 'user', content: 'hi' }], 'grok-build', [], {});
+        assert.equal(result.content, 'ok');
+        assert.equal(httpCalled, true);
+    } finally {
+        if (prevTransport == null) delete process.env.MIXDOG_OAI_TRANSPORT;
+        else process.env.MIXDOG_OAI_TRANSPORT = prevTransport;
+    }
+});
+
+test('grok-oauth: all Grok models inherit global transport; explicit setting is the escape hatch', () => {
+    const prevOaiTransport = process.env.MIXDOG_OAI_TRANSPORT;
+    const prevResponsesTransport = process.env.MIXDOG_GROK_OAUTH_RESPONSES_TRANSPORT;
+    const prevGrokTransport = process.env.MIXDOG_GROK_OAUTH_TRANSPORT;
+    try {
+        process.env.MIXDOG_OAI_TRANSPORT = 'ws-delta';
+        delete process.env.MIXDOG_GROK_OAUTH_RESPONSES_TRANSPORT;
+        delete process.env.MIXDOG_GROK_OAUTH_TRANSPORT;
+        const provider = new GrokOAuthProvider({});
+
+        const apiInner = provider._ensureInner('tok', 'grok-build-0.1');
+        assert.equal(apiInner.config.responsesTransport, undefined);
+
+        // No Grok-specific override: proxy-only grok-build now inherits the
+        // shared switch too (WS→api.x.ai), no implicit HTTP pin.
+        const proxyInner = provider._ensureInner('tok', 'grok-build');
+        assert.equal(proxyInner.config.responsesTransport, undefined);
+
+        // Escape hatch: an explicit Grok-specific http setting pins proxy-only
+        // models back onto the Grok CLI proxy over HTTP.
+        process.env.MIXDOG_GROK_OAUTH_RESPONSES_TRANSPORT = 'http';
+        const pinnedProvider = new GrokOAuthProvider({});
+        const pinnedProxy = pinnedProvider._ensureInner('tok', 'grok-build');
+        assert.equal(pinnedProxy.config.responsesTransport, 'http');
+        const pinnedApi = pinnedProvider._ensureInner('tok2', 'grok-build-0.1');
+        assert.equal(pinnedApi.config.responsesTransport, 'http');
+    } finally {
+        if (prevOaiTransport == null) delete process.env.MIXDOG_OAI_TRANSPORT;
+        else process.env.MIXDOG_OAI_TRANSPORT = prevOaiTransport;
+        if (prevResponsesTransport == null) delete process.env.MIXDOG_GROK_OAUTH_RESPONSES_TRANSPORT;
+        else process.env.MIXDOG_GROK_OAUTH_RESPONSES_TRANSPORT = prevResponsesTransport;
+        if (prevGrokTransport == null) delete process.env.MIXDOG_GROK_OAUTH_TRANSPORT;
+        else process.env.MIXDOG_GROK_OAUTH_TRANSPORT = prevGrokTransport;
+    }
+});
+
+test('responses transport policy: _gateTransportMode down-shifts per capability', () => {
+    // delta unsupported → ws-delta collapses to ws-full; others pass through.
+    const noDelta = { ws: true, http: true, delta: false };
+    assert.equal(_gateTransportMode('ws-delta', noDelta), 'ws-full');
+    assert.equal(_gateTransportMode('ws-full', noDelta), 'ws-full');
+    assert.equal(_gateTransportMode('http-sse', noDelta), 'http-sse');
+    // WS unsupported → WS modes prefer HTTP.
+    const httpOnly = { ws: false, http: true, delta: false };
+    assert.equal(_gateTransportMode('ws-full', httpOnly), 'http-sse');
+    assert.equal(_gateTransportMode('ws-delta', httpOnly), 'http-sse');
+    // HTTP unsupported → http-sse prefers full-frame WS.
+    const wsOnly = { ws: true, http: false, delta: true };
+    assert.equal(_gateTransportMode('http-sse', wsOnly), 'ws-full');
+    // full caps pass everything through unchanged.
+    for (const m of ['auto', 'ws-full', 'ws-delta', 'http-sse']) {
+        assert.equal(_gateTransportMode(m, FULL_RESPONSES_TRANSPORT_CAPS), m);
+    }
+});
+
+// === 11. Codex x-codex-turn-state parity =================================
+// Server-issued sticky-routing token. codex-rs stores it in a per-turn
+// `OnceLock<String>` (client.rs:277-285): captured ONCE at turn start from the
+// `x-codex-turn-state` RESPONSE header, replayed unchanged on every request
+// within that turn, never fabricated, and dropped between turns (a fresh
+// ModelClientSession/OnceLock per turn). These tests pin that exact contract
+// against our pooled-socket emulation (capture + first-use/turn-id attribution
+// + per-turn drop guard).
+test('codex turn-state: captures server response header once, never synthesizes', () => {
+    const entry = {};
+    // No header on the event → nothing captured (never fabricated).
+    _captureTurnStateFromEvent(entry, { type: 'response.created', headers: {} });
+    assert.equal(entry.turnState, undefined);
+    // Server issues the token on a response header → captured.
+    _captureTurnStateFromEvent(entry, { type: 'response.created', headers: { 'x-codex-turn-state': 'tok-1' } });
+    assert.equal(entry.turnState, 'tok-1');
+    // OnceLock semantics: a later server token in the same turn does NOT overwrite.
+    _captureTurnStateFromEvent(entry, { headers: { 'x-codex-turn-state': 'tok-2' } });
+    assert.equal(entry.turnState, 'tok-1');
+});
+
+test('codex turn-state: captures from nested response/metadata header shapes', () => {
+    const fromResponse = {};
+    _captureTurnStateFromEvent(fromResponse, { response: { headers: { 'x-codex-turn-state': 'tok-r' } } });
+    assert.equal(fromResponse.turnState, 'tok-r');
+    const fromMeta = {};
+    _captureTurnStateFromEvent(fromMeta, { response: { metadata: { headers: { 'x-codex-turn-state': 'tok-m' } } } });
+    assert.equal(fromMeta.turnState, 'tok-m');
+});
+
+test('codex turn-state: echoed within a turn, dropped across turns, never fabricated', () => {
+    const ctxA = { sendOpts: { turnId: 'turn-A', codexSessionId: 'sess', threadId: 'thread' } };
+    // A server-captured token with unknown owner (handshake/prewarm capture).
+    const entry = { turnState: 'tok-A' };
+    const f1 = _withCodexWsClientMetadata({}, entry, true, ctxA);
+    assert.equal(f1.client_metadata['x-codex-turn-state'], 'tok-A');
+    // First use attributes the token to the turn now on the wire.
+    assert.equal(entry.turnStateTurnId, 'turn-A');
+    // Subsequent request in the SAME turn replays the same token.
+    const f2 = _withCodexWsClientMetadata({}, entry, true, ctxA);
+    assert.equal(f2.client_metadata['x-codex-turn-state'], 'tok-A');
+    // Next turn: the token must be dropped, never replayed or fabricated.
+    const ctxB = { sendOpts: { turnId: 'turn-B', codexSessionId: 'sess', threadId: 'thread' } };
+    const f3 = _withCodexWsClientMetadata({}, entry, true, ctxB);
+    assert.equal('x-codex-turn-state' in f3.client_metadata, false);
+    assert.equal(entry.turnState, null);
+});
+
+test('codex turn-state: parity disabled leaves the frame untouched (no metadata, no echo)', () => {
+    const entry = { turnState: 'tok-A' };
+    const frame = { input: [] };
+    const out = _withCodexWsClientMetadata(frame, entry, false, { sendOpts: { turnId: 'turn-A' } });
+    assert.equal(out, frame);
+    assert.equal(out.client_metadata, undefined);
+});

package/src/agents/heavy-worker/AGENT.md

@@ -8,10 +8,9 @@ Broad implementation agent.
 Bounded slices; smallest coherent change, not rewrite. Stop when scope is
 unclear or the blast radius grows.
 
-EDIT-FIRST DISCIPLINE. Survey the slice with one batched retrieval round,
-then patch the first bounded piece — edit incrementally, don't read
-exhaustively. Repeated read-only turns without an edit = stalling; on a
-runtime reminder, patch the piece you understand or report blocked.
+EDIT-FIRST DISCIPLINE. Patch the first bounded piece — edit incrementally,
+don't read exhaustively. Repeated read-only turns without an edit = stalling;
+on a runtime reminder, patch the piece you understand or report blocked.
 
 Self-verify edits with shell (targeted test/build).
 

package/src/agents/worker/AGENT.md

@@ -8,9 +8,8 @@ Scoped implementation agent.
 Smallest scoped change; no drive-by cleanup. Stop when done/blocked.
 
 EDIT-FIRST DISCIPLINE. Brief anchors (`file:line`) are pre-verified — trust
-and patch. No anchor: one locating batch, then `apply_patch`. Repeated
-read-only turns without an edit = stalling; on a runtime reminder, patch now
-or return blocked. Threshold is "plausible", not "proven".
+and patch. Repeated read-only turns without an edit = stalling; on a runtime
+reminder, patch now or return blocked. Threshold is "plausible", not "proven".
 
 Self-verify edits with shell (node --check/test).