mixdog 0.9.6 → 0.9.8

package/README.md

@@ -32,14 +32,14 @@ repo-focused tools for reading, editing, testing, and reviewing code.
 ## Install
 
 ```bash
-npm install
+npm install -g mixdog
+mixdog --help
 ```
 
-To install the `mixdog` command globally from this checkout:
+For local development from this checkout:
 
 ```bash
-npm install -g .
-mixdog --help
+npm install
 ```
 
 ## Run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/scripts/provider-toolcall-test.mjs

@@ -24,6 +24,12 @@ import {
 import {
     consumeCompatChatCompletionStream,
 } from '../src/runtime/agent/orchestrator/providers/openai-compat-stream.mjs';
+import {
+    _computeDelta,
+} from '../src/runtime/agent/orchestrator/providers/openai-ws-delta.mjs';
+import {
+    _cacheObservationForTest,
+} from '../src/runtime/agent/orchestrator/providers/openai-oauth-ws.mjs';
 import {
     createGeminiTextLeakGuard,
     parseToolCalls as geminiParseToolCalls,
@@ -976,3 +982,85 @@ test('anthropic effort: explicit thinkingBudgetTokens wins over effort', () => {
     assert.equal(body.output_config, undefined);
     assert.equal(shouldIncludeEffortBeta(model, { effort: 'low', thinkingBudgetTokens: 2048 }), false);
 });
+// === 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: opt-in still falls back without turn-state unless forced', () => {
+    const previous = process.env.MIXDOG_OAI_WS_DELTA;
+    try {
+        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: [],
+        };
+
+        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]]);
+    } finally {
+        if (previous == null) delete process.env.MIXDOG_OAI_WS_DELTA;
+        else process.env.MIXDOG_OAI_WS_DELTA = previous;
+    }
+});
+test('openai oauth ws cache observation detects warm zero and partial retreats', () => {
+    const zero = _cacheObservationForTest({
+        entry: { promptCacheMaxCachedTokens: 47_616 },
+        result: { usage: { inputTokens: 59_000, promptTokens: 59_000, cachedTokens: 0 } },
+    });
+    assert.equal(zero.actualMiss, true);
+    assert.equal(zero.missReason, 'warm_session_zero_cached_tokens');
+    assert.equal(zero.uncachedTokens, 59_000);
+
+    const partial = _cacheObservationForTest({
+        entry: { promptCacheMaxCachedTokens: 101_888 },
+        result: { usage: { inputTokens: 102_456, promptTokens: 102_456, cachedTokens: 60_928 } },
+    });
+    assert.equal(partial.actualMiss, true);
+    assert.equal(partial.missReason, 'warm_session_cached_tokens_dropped');
+    assert.equal(partial.cachedTokens % 512, 0);
+
+    const healthy = _cacheObservationForTest({
+        entry: { promptCacheMaxCachedTokens: 101_888 },
+        result: { usage: { inputTokens: 106_468, promptTokens: 106_468, cachedTokens: 103_424 } },
+    });
+    assert.equal(healthy.actualMiss, false);
+    assert.equal(healthy.missReason, null);
+});

package/src/rules/agent/30-explorer.md

@@ -6,23 +6,29 @@ kind: retrieval
 
 # Role: explorer
 
-You are a one-shot locator, not a researcher.
+You are a one-shot locator, not a researcher. You find WHERE, never WHY or
+HOW: no reading code to understand it, no explaining behaviour, no tracing
+logic across files. Coordinates are the entire deliverable.
 
-Find code anchors fast. Batch independent lookups in turn 1: one `grep`
-with all literal strings/errors/identifier guesses, plus `code_graph`/`find`
-or `glob` when useful.
+Default shape: ONE tool turn, then the answer. Turn 1 is ONE maximal batch:
+a single `grep` carrying ALL literal strings/errors/identifier guesses
+(content mode, small `-C`), plus `code_graph`/`find`/`glob` in the same
+turn. Fire everything at once; never probe one tool at a time. Any second
+turn means turn 1 under-batched.
 
-Prefer user-visible strings and identifiers. `dist`/generated hits are leads,
-not answers: trace them back to source. On miss, derive new tokens from
-returned paths/names or widen scope; do not repeat synonyms. NEVER issue
-serial single-tool turns: every turn after the first must batch ALL remaining
-candidate lookups in one shot.
+Answer straight from search output: grep/code_graph hits already carry
+`path:line` — NEVER spend a turn on `read` just to confirm or polish an
+anchor you already have. Prefer user-visible strings and identifiers.
+`dist`/generated hits are leads, not answers: trace them back to source.
 
-Budget: 4 tool turns. The FIRST credible `path:line` ends the search — answer
-with what you have; more anchors are not more value. Spend remaining turns
-only while you have zero anchors, and buy coverage with wider batches, never
-with extra serial turns. On ANY iteration warning, answer immediately with
-best anchors or `EXPLORATION_FAILED`.
+Budget: 5 tool turns; coordinates only, zero analysis. The FIRST
+credible `path:line` ends the search — answer in that same turn; do not
+verify, refine, or collect extras. A plausible anchor now beats a perfect
+anchor later: mark weak ones `?` instead of checking them. Turns 2-5 exist
+ONLY for a zero-anchor turn 1: derive new tokens from returned paths/names
+or widen scope (no repeated synonyms), batching ALL remaining candidates in
+one shot. Past turn 5 you are wasting the caller's time: answer with
+best-so-far anchors or `EXPLORATION_FAILED`.
 
 Answer format, nothing else:
 - up to 5 lines: `path:line — symbol/name — short reason` (append `?` if weak)

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

@@ -72,6 +72,7 @@ export {
     _logicalResponseItemMatch,
     parseToolSearchArgs,
     _streamResponse,
+    _cacheObservation as _cacheObservationForTest,
 };
 
 globalThis.__mixdogOpenaiWsRuntimeLoaded = true;
@@ -293,6 +294,34 @@ function _codexWsCompatibilityHeaders(context = {}) {
     // body client_metadata; the server may gate x-codex-turn-state issuance
     // on handshake-level client identity, so mirror codex here.
     if (metadata['x-codex-installation-id']) headers['x-codex-installation-id'] = metadata['x-codex-installation-id'];
+    // Turn-metadata handshake header. codex's compatibility_headers()
+    // (responses_metadata.rs:227-252) attaches x-codex-turn-metadata /
+    // x-codex-parent-thread-id / x-codex-window-id on the request. A/B
+    // (2026-07-04, tm0b vs tm1b, 10 parallel-5 sessions each, gpt-5.5):
+    // WITH the turn-metadata blob it2 cache misses dropped 4/10 -> 0/10 and
+    // full-prefix hits rose 2/10 -> 7/10; x-codex-turn-state was never issued
+    // in either arm, so the win comes from better cache routing on the
+    // handshake fingerprint, not sticky turn-state. Default ON.
+    // MIXDOG_OAI_TURN_METADATA overrides:
+    //   unset / 1 / turn-metadata : window-id + turn-metadata + installation-id
+    //   parent                    : + x-codex-parent-thread-id (= thread_id)
+    //   window                    : window-id only (drop turn-metadata blob)
+    //   0 / off / false / no      : strip the blob (pre-2026-07-04 baseline)
+    const probe = String(process.env.MIXDOG_OAI_TURN_METADATA || '').trim().toLowerCase();
+    if (probe === '0' || probe === 'off' || probe === 'false' || probe === 'no') {
+        // Not opted in: keep window-id + installation-id but drop the full
+        // turn-metadata blob so we match the historical (turn-state-never-issued)
+        // baseline exactly.
+        delete headers['x-codex-turn-metadata'];
+    } else if (probe === 'parent') {
+        const parentThreadId = _cleanMetaString(context?.sendOpts?.parentThreadId
+            || context?.sendOpts?.codexParentThreadId
+            || metadata.thread_id);
+        if (parentThreadId) headers['x-codex-parent-thread-id'] = parentThreadId;
+    } else if (probe === 'window') {
+        delete headers['x-codex-turn-metadata'];
+    }
+    // probe === '1' | 'true' | 'yes' | 'on' | 'turn-metadata' => full set as built above.
     return headers;
 }
 
@@ -1060,7 +1089,7 @@ export async function sendViaWebSocket({
             });
             const chainFallback = mode !== 'delta'
                 && deltaReason
-                && !['no_anchor', 'full_forced'].includes(deltaReason);
+                && !['no_anchor', 'full_forced', 'full_default', 'delta_missing_turn_state'].includes(deltaReason);
             if (chainFallback || (mode === 'delta' && deltaReason)) {
                 appendAgentTrace({
                     sessionId: poolKey,

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

@@ -179,13 +179,18 @@ export function _computeDelta({ entry, body }) {
     // token, previous_response_id requests hop cache nodes and only the first
     // prefix blocks hit. Re-enable delta explicitly via MIXDOG_OAI_WS_DELTA=1
     // for future probes if the backend starts issuing turn-state.
-    const deltaOptIn = ['1', 'true', 'yes', 'on'].includes(String(process.env.MIXDOG_OAI_WS_DELTA || '').trim().toLowerCase());
+    const deltaMode = String(process.env.MIXDOG_OAI_WS_DELTA || '').trim().toLowerCase();
+    const deltaForce = ['force', 'unsafe', 'always'].includes(deltaMode);
+    const deltaOptIn = deltaForce || ['1', 'true', 'yes', 'on'].includes(deltaMode);
     if (!deltaOptIn) {
         return { mode: 'full', reason: 'full_default', frame: { type: 'response.create', ...body } };
     }
     if (!entry || !entry.lastRequestSansInput || !entry.lastResponseId) {
         return { mode: 'full', reason: 'no_anchor', frame: { type: 'response.create', ...body } };
     }
+    if (!deltaForce && !entry.turnState) {
+        return { mode: 'full', reason: 'delta_missing_turn_state', frame: { type: 'response.create', ...body } };
+    }
     if (!Array.isArray(entry.lastRequestInput)) {
         return { mode: 'full', reason: 'no_input_snapshot', frame: { type: 'response.create', ...body } };
     }

package/src/standalone/explore-tool.mjs

@@ -70,7 +70,7 @@ function escapeXml(str) {
 // reminder. The full no-verdict contract lives at system level
 // (rules/agent/30-explorer.md).
 export function buildExplorerPrompt(query) {
-  return `<query>${escapeXml(query)}</query>\nReminder: budget 4 tool turns — batch every candidate lookup per turn, never one tool at a time. The moment you have credible anchors, STOP and answer; spend remaining turns only while you have zero anchors. Output only anchor lines formatted as path:line — symbol/name — short reason, or EXPLORATION_FAILED. No preamble, bullets, numbering, headings, summary, code quotes, analysis, verdicts, ratings, or recommendations.`;
+  return `<query>${escapeXml(query)}</query>\nReminder: coordinates only — WHERE, never WHY. Finish within 5 tool turns, ideally 1. Turn 1 MUST be one maximal batch: fire EVERY candidate lookup at once (grep with all token variants + code_graph + find/glob in the same turn); never one tool at a time. Answer straight from search output — grep/code_graph hits already carry path:line; never spend a turn reading to confirm, polish, or understand. The FIRST credible anchor ends the search: STOP and answer in that same turn, marking weak anchors with ?. By turn 5 answer with best-so-far or EXPLORATION_FAILED. Output only anchor lines formatted as path:line — symbol/name — short reason, or EXPLORATION_FAILED. No preamble, bullets, numbering, headings, summary, code quotes, analysis, verdicts, ratings, or recommendations.`;
 }
 
 export function normalizeExploreQueries(rawQuery) {
@@ -355,16 +355,15 @@ async function runExploreSync(args = {}, ctx = {}) {
   const presetName = (route && typeof route === 'object')
     ? `${clean(route.provider)}/${clean(route.model)}`
     : (route || '');
-  // Explorer self-manages its turn budget: the 4-turn budget lives ONLY in
+  // Explorer self-manages its turn budget: the 5-turn budget lives ONLY in
   // explorer-scoped surfaces (rules/agent/30-explorer.md + per-query prompt),
-  // never in shared loop policy. The cap here is a runaway guard, unchanged
-  // from the original value; B-round live tests showed hard targets
-  // legitimately need ~10.
+  // never as a loop hard cap — no maxLoopIterations here by design. The
+  // wall-clock hard timeout (EXPLORE_COMPUTE_HARD_TIMEOUT_MS) remains the
+  // only runaway guard.
   const llm = makeAgentDispatch({
     agent: 'explorer',
     cwd: resolvedCwd,
     brief: true,
-    maxLoopIterations: 12,
     parentSessionId: ctx.callerSessionId || null,
     clientHostPid: ctx.clientHostPid || null,
     config,