mixdog 0.9.2 → 0.9.4

package/src/runtime/agent/orchestrator/session/loop/recall-fasttrack.mjs

@@ -0,0 +1,182 @@
+// Recall-fasttrack compaction pipeline, extracted from loop.mjs.
+// Hydrates the session transcript into the memory pipeline (ingest_session),
+// dumps chunked/raw roots, drains cycle1 until no raw rows remain, and folds
+// the combined recall text back into a compacted message array capped at
+// CONTEXT_SHARE_RATIO of the model context window. No behavior change: this is
+// the same body that lived inline in loop.mjs, re-exported via the facade so
+// existing importers keep working.
+import { createHash } from 'crypto';
+import { executeInternalTool } from '../../internal-tools.mjs';
+import { loadConfig as loadOrchestratorConfig } from '../../config.mjs';
+import {
+    recallFastTrackCompactMessages,
+    CONTEXT_SHARE_RATIO,
+    RECALL_TOKEN_CAP_FLOOR_TOKENS,
+    drainSessionCycle1,
+    countRawPendingRows,
+} from '../compact.mjs';
+import {
+    compactDiagnosticError,
+    compactByteLength,
+    compactDebugLog,
+} from './compact-debug.mjs';
+import { positiveTokenInt } from './env.mjs';
+
+export async function runRecallFastTrackCompact({ sessionRef, messages, compactBudgetTokens, compactPolicy, sessionId, signal }) {
+    if (!sessionId) throw new Error('recall-fasttrack requires a session id');
+    const startedAt = Date.now();
+    const diagnostics = {
+        hydrateLimit: null,
+        ingestMs: null,
+        ingestSkipped: false,
+        ingestError: null,
+        initialDumpMs: null,
+        initialDumpBytes: null,
+        initialDumpChars: null,
+        initialRawPending: null,
+        cycle1Ms: null,
+        cycle1Skipped: false,
+        cycle1SkipReason: null,
+        cycle1Passes: null,
+        cycle1RawRemaining: null,
+        cycle1TextBytes: null,
+        cycle1Error: null,
+        finalRecallBytes: null,
+        finalRecallChars: null,
+        totalMs: null,
+    };
+    const query = `session:${sessionId}:all-chunks`;
+    const querySha = createHash('sha256').update(query).digest('hex').slice(0, 16);
+    const callerCtx = {
+        callerSessionId: sessionId || null,
+        callerCwd: sessionRef?.cwd || undefined,
+        routingSessionId: sessionId || null,
+        clientHostPid: sessionRef?.clientHostPid,
+        signal: signal || null,
+    };
+    const hydrateLimit = positiveTokenInt(sessionRef?.compaction?.recallIngestLimit)
+        || Math.max(500, Math.min(5000, messages.length || 0));
+    diagnostics.hydrateLimit = hydrateLimit;
+    let t0 = Date.now();
+    try {
+        await executeInternalTool('memory', {
+            action: 'ingest_session',
+            sessionId,
+            messages,
+            cwd: sessionRef?.cwd,
+            limit: hydrateLimit,
+        }, callerCtx);
+    } catch (err) {
+        diagnostics.ingestSkipped = true;
+        diagnostics.ingestError = compactDiagnosticError(err);
+        try { process.stderr.write(`[loop] recall-fasttrack ingest skipped (sess=${sessionId || 'unknown'}): ${err?.message || err}\n`); } catch {}
+    } finally {
+        diagnostics.ingestMs = Date.now() - t0;
+    }
+    const dumpArgs = {
+        action: 'dump_session_roots',
+        sessionId,
+        includeRaw: true,
+        limit: positiveTokenInt(sessionRef?.compaction?.recallChunkLimit ?? sessionRef?.compaction?.recallLimit) || hydrateLimit,
+    };
+    const runTool = (name, args) => executeInternalTool(name, args, callerCtx);
+    t0 = Date.now();
+    let recallText = await executeInternalTool('memory', dumpArgs, callerCtx);
+    diagnostics.initialDumpMs = Date.now() - t0;
+    diagnostics.initialDumpChars = String(recallText || '').length;
+    diagnostics.initialDumpBytes = compactByteLength(recallText);
+    diagnostics.initialRawPending = countRawPendingRows(recallText);
+    let cycle1Text = '';
+    const hasRawRows = /(?:^|\n)# raw_pending\s+\d+\s+id=/i.test(String(recallText || ''));
+    // Recap off = NO memory-pipeline LLM calls: skip the cycle1 drain entirely
+    // and let the dump's raw transcript lines (includeRaw:true above) ride into
+    // the injected summary as-is. Poll-on-use: re-read the flag per compact so
+    // a runtime toggle applies without restart. Default on if config read fails.
+    let recapOn = true;
+    try { recapOn = loadOrchestratorConfig({ secrets: false })?.recap?.enabled !== false; } catch { /* default on */ }
+    if (hasRawRows && !recapOn) {
+        diagnostics.cycle1Skipped = true;
+        diagnostics.cycle1SkipReason = 'recap disabled';
+        diagnostics.cycle1Passes = 0;
+        diagnostics.cycle1RawRemaining = countRawPendingRows(recallText);
+        cycle1Text = 'cycle1: skipped (recap disabled — raw transcript lines kept as-is)';
+    } else if (hasRawRows) {
+        t0 = Date.now();
+        try {
+            // Drain this session's cycle1 in window×concurrency units until no
+            // raw rows remain, so the injected root is fully chunked rather than
+            // carrying the unprocessed transcript tail (single-pass left raw in).
+            const drained = await drainSessionCycle1(runTool, {
+                sessionId,
+                dumpArgs,
+                deadlineMs: positiveTokenInt(sessionRef?.compaction?.recallCycle1DeadlineMs) || 120_000,
+                maxPasses: positiveTokenInt(sessionRef?.compaction?.recallCycle1MaxPasses) || 0,
+                cycleArgs: {
+                    min_batch: 1,
+                    session_cap: 1,
+                    batch_size: positiveTokenInt(sessionRef?.compaction?.recallCycle1BatchSize) || 100,
+                    rows_per_session: positiveTokenInt(sessionRef?.compaction?.recallRowsPerSession) || 100,
+                    window_size: positiveTokenInt(sessionRef?.compaction?.recallWindowSize) || 20,
+                    concurrency: positiveTokenInt(sessionRef?.compaction?.recallConcurrency) || 5,
+                },
+            });
+            recallText = drained.recallText;
+            cycle1Text = drained.cycle1Text;
+            diagnostics.cycle1Passes = drained.passes;
+            diagnostics.cycle1RawRemaining = drained.rawRemaining;
+            diagnostics.cycle1TextBytes = compactByteLength(cycle1Text);
+            if (drained.error) {
+                diagnostics.cycle1Error = drained.error;
+                try { process.stderr.write(`[loop] recall-fasttrack cycle1 error (sess=${sessionId || 'unknown'}): ${drained.error}\n`); } catch {}
+            }
+            if (drained.rawRemaining > 0) {
+                try { process.stderr.write(`[loop] recall-fasttrack drained passes=${drained.passes} rawRemaining=${drained.rawRemaining} (sess=${sessionId || 'unknown'})\n`); } catch {}
+            }
+        } catch (err) {
+            diagnostics.cycle1Error = compactDiagnosticError(err);
+            try { process.stderr.write(`[loop] recall-fasttrack cycle1 skipped (sess=${sessionId || 'unknown'}): ${err?.message || err}\n`); } catch {}
+        } finally {
+            diagnostics.cycle1Ms = Date.now() - t0;
+        }
+    } else {
+        diagnostics.cycle1Skipped = true;
+        diagnostics.cycle1SkipReason = 'session chunks already hydrated';
+        diagnostics.cycle1Passes = 0;
+        diagnostics.cycle1RawRemaining = 0;
+        cycle1Text = 'cycle1: skipped (session chunks already hydrated)';
+    }
+    const combinedRecallText = [`session_id=${sessionId}`, cycle1Text, recallText].map(v => String(v || '').trim()).filter(Boolean).join('\n\n');
+    diagnostics.finalRecallChars = combinedRecallText.length;
+    diagnostics.finalRecallBytes = compactByteLength(combinedRecallText);
+    // Recall injection (chunked-summary + raw-fallback text, combined above)
+    // never exceeds CONTEXT_SHARE_RATIO (5%) of the model context window
+    // (floor RECALL_TOKEN_CAP_FLOOR_TOKENS); the rest of the budget belongs to
+    // live conversation. Same unified 5% as the compact target ratio
+    // (compact-policy.mjs COMPACT_TARGET_RATIO). Omitted when contextWindow is
+    // unknown/0 so current no-cap behavior is preserved.
+    const _recallCapWindow = Number(compactPolicy.contextWindow) || 0;
+    const recallTokenCap = _recallCapWindow > 0
+        ? Math.max(RECALL_TOKEN_CAP_FLOOR_TOKENS, Math.floor(_recallCapWindow * CONTEXT_SHARE_RATIO))
+        : undefined;
+    const result = recallFastTrackCompactMessages(messages, compactBudgetTokens, {
+        reserveTokens: compactPolicy.reserveTokens,
+        force: true,
+        recallText: combinedRecallText,
+        query,
+        querySha,
+        allowEmptyRecall: true,
+        tailTurns: compactPolicy.tailTurns,
+        keepTokens: compactPolicy.keepTokens,
+        preserveRecentTokens: compactPolicy.preserveRecentTokens,
+        recallTokenCap,
+    });
+    diagnostics.totalMs = Date.now() - startedAt;
+    if (result && typeof result === 'object') {
+        result.diagnostics = {
+            ...(result.diagnostics || {}),
+            pipeline: diagnostics,
+        };
+    }
+    compactDebugLog('recall-fasttrack pipeline', diagnostics);
+    return result;
+}

package/src/runtime/agent/orchestrator/session/loop/steering-ladder.mjs

@@ -0,0 +1,173 @@
+// Completion-first steering ladder (worker runaway prevention), extracted from
+// loop.mjs. Owns the mutable ladder counters and the post-batch steering-hint
+// emitters. State is threaded live via a context object of getters/setters so
+// no snapshot goes stale — the loop mutates `messages`/`iterations` in place and
+// this module reads them through the accessors on each call. No behavior change:
+// the counters, thresholds, and emitted messages are verbatim from agentLoop.
+import { appendAgentTrace } from '../../agent-trace.mjs';
+import { level2SteerMessage } from './completion-guards.mjs';
+import { isEagerDispatchable } from './tool-helpers.mjs';
+
+// Consecutive ignored level-2 steers (zero edits) that force the wrap-up early.
+export const EARLY_SOFT_CAP_LEVEL2_FIRES = 3;
+
+// Build the completion-first steering-ladder controller. `ctx` supplies live
+// accessors so every read reflects the loop's current mutable state:
+//   - messages, sessionId, sessionAgent, tools           (stable refs/values)
+//   - getIterations()                                    (current iteration)
+//   - softCapEnabled                                     (constant per loop)
+//   - getEditCount()                                     (mutated by the loop)
+//   - pushSystemReminder(text)  → push a meta:'hook' user message
+//   - pushUserMessage(msg)      → push a raw user message (level-2 latch text)
+export function createSteeringLadder(ctx) {
+    const {
+        sessionId,
+        sessionAgent,
+        tools,
+        getIterations,
+        softCapEnabled,
+        getEditCount,
+    } = ctx;
+    const pushSystemReminder = ctx.pushSystemReminder;
+    const pushUserMessage = ctx.pushUserMessage;
+    // Permission-based role detection (agent names are user-definable):
+    // read-permission sessions legitimately never edit, so they get the
+    // report-oriented level-2 text and never arm the early soft-cap.
+    const readOnlyRole = ctx.readOnlyRole === true;
+
+    // Step 1: escalation ladder. _level1FireCount is CUMULATIVE (never reset)
+    // so repeated batching reminders accumulate across the whole session.
+    // _level2LatchAtIteration latches level-2 steering to at most once / 5 turns.
+    let _level1FireCount = 0;
+    let _level2LatchAtIteration = -Infinity;
+    // Independent ladder counter: consecutive turns where EVERY call is
+    // read-only (any count) with zero edits. Catches multi-call read-only
+    // turns that the single-call level-1 streak misses. Reset on any edit.
+    let _allReadOnlyStreak = 0;
+    // Tracks consecutive assistant turns that ran exactly one read-only tool
+    // call (missed parallelism). Not reset per-iteration — only by the
+    // steering-hint fire below or by a turn that batches/edits.
+    let _serialReadOnlyStreak = 0;
+    // Tracks consecutive grep calls scoped to the SAME path (any patterns) —
+    // the "serial rewording" spiral: re-grepping one file with reworded
+    // patterns instead of reading it. Only counts turns whose every call is a
+    // grep on that path; any other tool/path resets it.
+    let _sameFileGrepStreak = 0;
+    let _sameFileGrepPath = null;
+    // Early soft-cap: N ignored level-2 steers with zero edits forces the
+    // wrap-up early; any edit disarms it (level-2 requires editCount === 0).
+    let _level2FireCount = 0;
+
+    // Level-2 steering emitter shared by both ladder paths (single-call
+    // level-1 streak and the independent all-read-only streak). Sets the latch
+    // so it fires at most once per 5 turns regardless of which path triggered.
+    const _emitLevel2Steer = () => {
+        const iterations = getIterations();
+        _level2LatchAtIteration = iterations;
+        _level2FireCount += 1;
+        // When this fire arms the early soft-cap, the wrap-up injected at the
+        // next loop head supersedes the level-2 text — skip the redundant hint.
+        const _armsEarlyCap = !readOnlyRole && softCapEnabled && _level2FireCount >= EARLY_SOFT_CAP_LEVEL2_FIRES && getEditCount() === 0;
+        if (!_armsEarlyCap) pushUserMessage({ role: 'user', content: level2SteerMessage(_level1FireCount, readOnlyRole), meta: 'hook' });
+        try {
+            appendAgentTrace({
+                sessionId,
+                iteration: iterations,
+                kind: 'steer',
+                payload: { tag: 'level2_steer', level1_fires: _level1FireCount, level2_fires: _level2FireCount, edit_count: getEditCount(), all_read_only_streak: _allReadOnlyStreak },
+                agent: sessionAgent || null,
+            });
+        } catch { /* best-effort */ }
+    };
+
+    return {
+        // Loop head reads: is the early soft-cap armed?
+        get level2FireCount() { return _level2FireCount; },
+        earlySoftCapArmed() {
+            return !readOnlyRole && _level2FireCount >= EARLY_SOFT_CAP_LEVEL2_FIRES && getEditCount() === 0;
+        },
+        // Post-batch steering hint gate. `hintAlreadyFired` seeds the once-per-
+        // turn latch (soft-cap active suppresses all hints). Returns nothing;
+        // pushes at most one steering message via the ctx push callbacks.
+        emitPostBatchSteering(calls, hintAlreadyFired) {
+            const iterations = getIterations();
+            const editCount = getEditCount();
+            // Steering hint gate: at most ONE hint per turn (priority: soft-cap >
+            // level-2 > same-file grep > level-1), and none once the soft-cap
+            // wrap-up is active — its "text only" directive must not share a send
+            // with a "keep exploring" hint.
+            let _hintFiredThisTurn = hintAlreadyFired;
+            // Missed-parallelism steering: 3+ consecutive turns of a single
+            // read-only tool call suggest the model isn't batching independent
+            // lookups. Nudge once, then reset (fires again after 3 more).
+            if (calls.length === 1 && isEagerDispatchable(calls[0].name, tools)) {
+                _serialReadOnlyStreak += 1;
+                if (_serialReadOnlyStreak >= 3 && !_hintFiredThisTurn) {
+                    _serialReadOnlyStreak = 0;
+                    // Escalation ladder (Step 1). Cumulative level-1 fires are
+                    // tracked and NEVER reset. Once level-1 has fired >=3 times with
+                    // ZERO edits, escalate to level-2 steering (blocked-report is a
+                    // valid completion) instead of the batching nudge — latched to at
+                    // most once per 5 turns.
+                    _level1FireCount += 1;
+                    if (_level1FireCount >= 3 && editCount === 0 && (iterations - _level2LatchAtIteration) >= 5) {
+                        _emitLevel2Steer();
+                    } else {
+                        pushSystemReminder('Last 3 turns each ran a single read-only tool. Batch independent lookups (read/grep/glob/code_graph) into ONE turn, or start editing if you have enough context.');
+                    }
+                    _hintFiredThisTurn = true;
+                }
+            } else {
+                _serialReadOnlyStreak = 0;
+            }
+            // Independent all-read-only escalation (audit finding): the level-1
+            // streak above only counts single-call turns, so a worker that runs
+            // 2+ read-only calls per turn escapes the ladder entirely. Track a
+            // cumulative count of consecutive turns where EVERY call is read-only
+            // (any count) and no edit has been made; at 12 such turns fire level-2
+            // directly (same once-per-5-turn latch), reset on any edit.
+            {
+                const _allReadOnly = calls.length > 0 && calls.every((c) => isEagerDispatchable(c.name, tools));
+                if (_allReadOnly && editCount === 0) {
+                    _allReadOnlyStreak += 1;
+                    if (_allReadOnlyStreak >= 12 && (iterations - _level2LatchAtIteration) >= 5 && !_hintFiredThisTurn) {
+                        _emitLevel2Steer();
+                        _hintFiredThisTurn = true;
+                    }
+                } else {
+                    _allReadOnlyStreak = 0;
+                }
+            }
+            // Serial-rewording steering: 4+ consecutive turns grepping the SAME
+            // path with reworded patterns = a search spiral that single-call
+            // batching cannot catch. Crisis-only: fires once per spiral, then
+            // resets. Read-the-file is almost always the answer at that point.
+            {
+                const _grepPathOf = (c) => {
+                    if (c?.name !== 'grep') return null;
+                    const p = c?.arguments?.path;
+                    return typeof p === 'string' && p ? p : null;
+                };
+                const _turnPaths = calls.map(_grepPathOf);
+                const _uniq = [...new Set(_turnPaths)];
+                if (_uniq.length === 1 && _uniq[0] !== null) {
+                    if (_uniq[0] === _sameFileGrepPath) _sameFileGrepStreak += 1;
+                    else { _sameFileGrepPath = _uniq[0]; _sameFileGrepStreak = 1; }
+                    if (_sameFileGrepStreak >= 4 && !_hintFiredThisTurn) {
+                        pushSystemReminder(`4+ consecutive grep turns on the same path (${_sameFileGrepPath}). Rewording patterns is not converging — read the relevant span directly (read with offset/limit) or act on what you have.`);
+                        _sameFileGrepStreak = 0;
+                        _sameFileGrepPath = null;
+                        _hintFiredThisTurn = true;
+                    }
+                } else {
+                    _sameFileGrepStreak = 0;
+                    _sameFileGrepPath = null;
+                }
+            }
+        },
+        // Reviewer fix: a zero-tool turn must not bridge the all-read-only
+        // streak across non-tool turns — that would fire level-2 early on a
+        // worker that paused to synthesize text mid-run.
+        resetAllReadOnlyStreak() { _allReadOnlyStreak = 0; },
+    };
+}

package/src/runtime/agent/orchestrator/session/loop/steering.mjs

@@ -0,0 +1,63 @@
+// Steering-message normalization/merge helpers extracted from loop.mjs.
+// Merges queued steering entries into a single content payload + display text.
+
+export function steeringContentText(content) {
+    if (typeof content === 'string') return content;
+    if (Array.isArray(content)) {
+        return content.map((part) => {
+            if (typeof part === 'string') return part;
+            if (part?.type === 'text') return part.text || '';
+            if (part?.type === 'image') return '[Image]';
+            return part?.text || '';
+        }).filter(Boolean).join('\n');
+    }
+    return String(content ?? '');
+}
+
+export function normalizeSteeringEntry(entry) {
+    if (typeof entry === 'string') {
+        const text = entry.trim();
+        return text ? { content: text, text } : null;
+    }
+    if (!entry || typeof entry !== 'object') return null;
+    const content = Object.prototype.hasOwnProperty.call(entry, 'content') ? entry.content : entry;
+    const text = typeof entry.text === 'string' ? entry.text.trim() : steeringContentText(content).trim();
+    if (Array.isArray(content)) return content.length > 0 ? { content, text } : null;
+    if (typeof content === 'string') {
+        const value = content.trim();
+        return value ? { content: value, text: text || value } : null;
+    }
+    const fallback = steeringContentText(content).trim();
+    return fallback ? { content: fallback, text: text || fallback } : null;
+}
+
+export function mergeSteeringEntries(entries) {
+    const normalized = (Array.isArray(entries) ? entries : [])
+        .map(normalizeSteeringEntry)
+        .filter(Boolean);
+    if (normalized.length === 0) return null;
+    const displayText = normalized.map((entry) => entry.text || steeringContentText(entry.content))
+        .filter((text) => String(text || '').trim())
+        .join('\n');
+    if (normalized.every((entry) => typeof entry.content === 'string')) {
+        return {
+            content: normalized.map((entry) => entry.content).filter(Boolean).join('\n'),
+            text: displayText,
+            count: normalized.length,
+        };
+    }
+    const parts = [];
+    for (const entry of normalized) {
+        if (typeof entry.content === 'string') {
+            if (entry.content.trim()) parts.push({ type: 'text', text: entry.content });
+        } else if (Array.isArray(entry.content)) {
+            parts.push(...entry.content);
+        } else {
+            const text = steeringContentText(entry.content);
+            if (text.trim()) parts.push({ type: 'text', text });
+        }
+        parts.push({ type: 'text', text: '\n' });
+    }
+    while (parts.length && parts[parts.length - 1]?.type === 'text' && parts[parts.length - 1]?.text === '\n') parts.pop();
+    return { content: parts, text: displayText || steeringContentText(parts), count: normalized.length };
+}

package/src/runtime/agent/orchestrator/session/loop/stored-tool-args.mjs

@@ -0,0 +1,100 @@
+// Stored tool-call argument compaction/restoration, extracted from loop.mjs.
+// Long body/command args are truncated with a sha256-tagged head/tail preview
+// when persisted into assistant history; the FULL body of a single call can be
+// restored on retry (e.g. a failed edit) so the model sees the original patch.
+import { createHash } from 'crypto';
+
+const STORED_TOOL_ARG_BODY_KEY_RE = /^(?:content|old_string|new_string|patch|rewrite)$/i;
+const STORED_TOOL_ARG_LONG_KEY_RE = /^(?:command|script)$/i;
+const STORED_TOOL_ARG_BODY_LIMIT = 2_000;
+const STORED_TOOL_ARG_LONG_LIMIT = 8_000;
+const STORED_TOOL_ARG_PREVIEW_HEAD = 360;
+const STORED_TOOL_ARG_PREVIEW_TAIL = 160;
+
+function compactStoredToolArgString(value, key = '') {
+    if (typeof value !== 'string') return value;
+    const isBody = STORED_TOOL_ARG_BODY_KEY_RE.test(key);
+    const isLong = isBody || STORED_TOOL_ARG_LONG_KEY_RE.test(key);
+    const limit = isBody ? STORED_TOOL_ARG_BODY_LIMIT : (isLong ? STORED_TOOL_ARG_LONG_LIMIT : Infinity);
+    if (value.length <= limit) return value;
+    const hash = createHash('sha256').update(value).digest('hex').slice(0, 16);
+    const head = value.slice(0, STORED_TOOL_ARG_PREVIEW_HEAD).replace(/\r\n/g, '\n');
+    const tail = value.slice(-STORED_TOOL_ARG_PREVIEW_TAIL).replace(/\r\n/g, '\n');
+    return `[mixdog compacted ${key || 'string'}: ${value.length} chars, sha256:${hash}]\n${head}\n... [middle omitted from stored tool-call args] ...\n${tail}`;
+}
+
+function compactStoredToolArgValue(value, key = '', depth = 0) {
+    if (value === null || value === undefined) return value;
+    if (typeof value === 'string') return compactStoredToolArgString(value, key);
+    if (typeof value !== 'object') return value;
+    if (depth >= 6) return Array.isArray(value) ? `[${value.length} items]` : '{...}';
+    if (Array.isArray(value)) {
+        return value.map((item) => compactStoredToolArgValue(item, key, depth + 1));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = compactStoredToolArgValue(v, k, depth + 1);
+    }
+    return out;
+}
+
+export function compactToolCallsForHistory(calls) {
+    if (!Array.isArray(calls)) return calls;
+    return calls.map((call) => {
+        if (!call || typeof call !== 'object') return call;
+        return {
+            ...call,
+            arguments: compactStoredToolArgValue(call.arguments),
+        };
+    });
+}
+
+// Restore the FULL body of ONE tool call inside a history assistant message
+// whose toolCalls were compacted at push time. Used for a failed edit call so
+// the model sees the original patch/old_string on retry instead of a
+// `[mixdog compacted …]` placeholder it cannot act on. Must run BEFORE the
+// message is first transmitted so it never mutates an already-cached prefix
+// (the prompt cache is content-prefix matched).
+//
+// Only the compactable body/long keys (patch, old_string, new_string, content,
+// rewrite, command, script) are restored, and at ANY depth — compaction is
+// recursive (compactStoredToolArgValue), so batch shapes like edits[].old_string
+// or writes[].content carry nested compacted bodies too. Every other field
+// (e.g. `path`, which a tool may mutate in place during execution) is taken from
+// the compacted snapshot captured at push time, before any mutation. The
+// compacted args tree is built fresh by compactToolCallsForHistory and is not
+// shared with originalCalls, so rebuilding it here is safe.
+export function restoreToolCallBodyForId(assistantMsg, originalCalls, callId) {
+    if (!assistantMsg || !Array.isArray(assistantMsg.toolCalls) || !callId) return;
+    if (!Array.isArray(originalCalls)) return;
+    const tc = assistantMsg.toolCalls.find((t) => t && t.id === callId);
+    const orig = originalCalls.find((c) => c && c.id === callId);
+    if (!tc || !orig) return;
+    if (!tc.arguments || typeof tc.arguments !== 'object'
+        || !orig.arguments || typeof orig.arguments !== 'object') return;
+    tc.arguments = _restoreCompactedBodies(tc.arguments, orig.arguments, '');
+}
+
+// Recursively rebuild a compacted args tree: replace ONLY compactable body/long
+// string fields (matched by key at any depth) with their full originals, and
+// keep every other field from the compacted snapshot. tcVal and origVal share
+// the same structure (compaction only shortens body strings), so the walk
+// descends them in parallel; a missing or non-object origVal falls back to the
+// compacted value rather than throwing.
+function _restoreCompactedBodies(tcVal, origVal, key) {
+    if ((STORED_TOOL_ARG_BODY_KEY_RE.test(key) || STORED_TOOL_ARG_LONG_KEY_RE.test(key))
+        && typeof origVal === 'string') {
+        return origVal;
+    }
+    if (Array.isArray(tcVal) && Array.isArray(origVal)) {
+        return tcVal.map((item, i) => _restoreCompactedBodies(item, origVal[i], key));
+    }
+    if (tcVal && typeof tcVal === 'object' && origVal && typeof origVal === 'object') {
+        const out = {};
+        for (const k of Object.keys(tcVal)) {
+            out[k] = (k in origVal) ? _restoreCompactedBodies(tcVal[k], origVal[k], k) : tcVal[k];
+        }
+        return out;
+    }
+    return tcVal;
+}

package/src/runtime/agent/orchestrator/session/loop/termination.mjs

@@ -0,0 +1,58 @@
+// Loop termination-reason classification, extracted from loop.mjs.
+// Pure function over the final response + loop-end flags. No behavior change:
+// the classification ladder is verbatim from the tail of agentLoop.
+import { HIDDEN_AGENT_NAMES } from './hidden-agents.mjs';
+
+// Stop reasons that signal the turn was cut short mid-synthesis (token cap,
+// provider pause). Empty content + one of these reasons means the worker
+// was not done. Covers Anthropic (pause_turn, max_tokens), OpenAI (length),
+// Gemini (MAX_TOKENS, OTHER), and case variants.
+export const INCOMPLETE_STOP_REASONS = new Set([
+    'pause_turn', 'max_tokens', 'length', 'MAX_TOKENS', 'OTHER',
+]);
+
+// Classify WHY the loop ended so agent-tool can promote an empty/abnormal
+// finish to an explicit Lead-facing error instead of a silent empty
+// "completed". Determine "has content" exactly the way the no-tool-call
+// branch in agentLoop does (trimmed string content, or any reasoning content).
+export function classifyTerminationReason(response, {
+    terminatedByCap,
+    terminatedBySoftCap,
+    softCapActive,
+    sessionAgent,
+} = {}) {
+    const _finalHasContent = (typeof response?.content === 'string' && response.content.trim().length > 0)
+        || (typeof response?.reasoningContent === 'string' && response.reasoningContent.trim().length > 0);
+    const _finalStopReason = response?.stopReason ?? response?.stop_reason ?? null;
+    const _finalIncompleteStop = _finalStopReason && INCOMPLETE_STOP_REASONS.has(_finalStopReason);
+    const _finalIsHidden = HIDDEN_AGENT_NAMES.has(sessionAgent);
+    if (terminatedByCap) {
+        // Real problem regardless of hidden/public: the loop never terminated
+        // on its own contract.
+        return 'iteration_cap';
+    }
+    if (terminatedBySoftCap || softCapActive) {
+        // Worker soft-cap wrap-up path: non-lead session hit the exploration
+        // budget and was steered to a text-only finish. Distinct from the hard
+        // cap (iteration_cap) — this is an expected, budget-driven termination,
+        // not a runaway. Covers BOTH the grace-exhausted path
+        // (terminatedBySoftCap) AND the compliant path where the model emitted
+        // the final text with no more tool calls while the soft cap was active
+        // (loop ends via the no-tool-call break, so terminatedBySoftCap stays
+        // false but softCapActive is still true).
+        return 'soft_cap_wrapup';
+    }
+    if (!_finalHasContent && _finalIncompleteStop) {
+        // Cut short mid-synthesis (token cap / provider pause). Real problem
+        // for hidden agents too.
+        return 'truncated';
+    }
+    if (!_finalHasContent && !_finalIsHidden) {
+        // Empty terminal turn. Only public agents violate their contract by
+        // finishing empty — hidden agents (explorer/cycle/…) legitimately emit
+        // text-only/empty terminal turns per their own role contract, so leave
+        // terminationReason undefined for them.
+        return 'empty';
+    }
+    return undefined;
+}

package/src/runtime/agent/orchestrator/session/loop/tool-classify.mjs

@@ -0,0 +1,52 @@
+// Tool-name classification + intra-turn signature helpers, extracted from
+// loop.mjs. These drive cross-turn read dedup, scoped caching, shell routing,
+// and duplicate-call detection. Strips the MCP prefix so direct calls and
+// MCP-wrapped calls share the same cache.
+import { createHash } from 'crypto';
+
+export const MCP_TOOL_PREFIX = 'mcp__plugin_mixdog_mixdog__';
+
+export function _stripMcpPrefix(name) {
+    return typeof name === 'string' && name.startsWith(MCP_TOOL_PREFIX)
+        ? name.slice(MCP_TOOL_PREFIX.length) : name;
+}
+export function _isReadTool(name) {
+    return _stripMcpPrefix(name) === 'read';
+}
+export function _isMutationTool(name) {
+    const n = _stripMcpPrefix(name);
+    return n === 'apply_patch';
+}
+export const SCOPED_CACHEABLE_TOOLS = new Set([
+    'code_graph',
+    'grep',
+    'list',
+    'glob',
+]);
+export function _isScopedCacheableTool(name) {
+    const n = _stripMcpPrefix(name);
+    return SCOPED_CACHEABLE_TOOLS.has(n);
+}
+export function _isShellTool(name) {
+    const n = _stripMcpPrefix(name);
+    return n === 'shell' || n === 'bash_session';
+}
+
+// Canonical signature for intra-turn duplicate detection. Sorting keys
+// produces a stable hash regardless of arg-object key order. Anything
+// non-serializable falls back to String(args) — still deterministic for
+// the model's typical structured-arg shape.
+export function _canonicalArgs(args) {
+    if (args == null || typeof args !== 'object') {
+        try { return JSON.stringify(args); } catch { return String(args); }
+    }
+    try {
+        const keys = Object.keys(args).sort();
+        const sorted = {};
+        for (const k of keys) sorted[k] = args[k];
+        return JSON.stringify(sorted);
+    } catch { return String(args); }
+}
+export function _intraTurnSig(name, args) {
+    return createHash('sha256').update(`${name}:${_canonicalArgs(args)}`).digest('hex').slice(0, 16);
+}