mixdog 0.9.2 → 0.9.3

package/src/runtime/agent/orchestrator/session/loop/compact-policy.mjs

@@ -0,0 +1,262 @@
+// Compaction policy resolution, pressure/target budgeting, telemetry
+// persistence, and event emission — extracted from loop.mjs.
+// runRecallFastTrackCompact stays in the loop (it drives the recall pipeline
+// against live session state).
+import {
+    estimateRequestReserveTokens,
+    resolveCompactBufferRatio,
+    resolveCompactBufferTokens,
+} from '../context-utils.mjs';
+import {
+    compactTypeIsRecallFastTrack,
+    compactTypeIsSemantic,
+    normalizeCompactType,
+    DEFAULT_COMPACT_TYPE,
+    DEFAULT_COMPACTION_KEEP_TOKENS,
+} from '../compact.mjs';
+import { positiveTokenInt, envFlag, envTokenInt } from './env.mjs';
+
+const COMPACT_SAFETY_PERCENT = 1.00;
+const COMPACT_TARGET_RATIO = 0.02;
+const COMPACT_TARGET_MIN_TOKENS = 4_000;
+const COMPACT_TARGET_MAX_TOKENS = 16_000;
+
+function resolveSemanticCompactSetting(sessionRef, cfg = {}) {
+    if (process.env.MIXDOG_AGENT_COMPACT_SEMANTIC !== undefined) return envFlag('MIXDOG_AGENT_COMPACT_SEMANTIC', true);
+    if (cfg.semantic === false || cfg.semantic === 'false' || cfg.semantic === 'off') return false;
+    if (cfg.semantic === true || cfg.semantic === 'true' || cfg.semantic === 'on') return true;
+    // The compact type is already explicit (`semantic` by default). Honor it
+    // directly instead of substituting another compaction path.
+    return true;
+}
+
+function resolveCompactTypeSetting(_sessionRef, cfg = {}) {
+    const configured = process.env.MIXDOG_AGENT_COMPACT_TYPE
+        ?? process.env.MIXDOG_COMPACT_TYPE
+        ?? cfg.type
+        ?? cfg.compactType
+        ?? cfg.compact_type;
+    return normalizeCompactType(configured, DEFAULT_COMPACT_TYPE);
+}
+
+function resolveCompactTargetRatio(cfg = {}) {
+    const raw = cfg.targetPercent
+        ?? cfg.targetPct
+        ?? cfg.targetRatio
+        ?? cfg.targetFraction
+        ?? process.env.MIXDOG_AGENT_COMPACT_TARGET_PERCENT
+        ?? process.env.MIXDOG_COMPACT_TARGET_PERCENT
+        ?? COMPACT_TARGET_RATIO;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) return COMPACT_TARGET_RATIO;
+    return n > 1 ? n / 100 : n;
+}
+function resolveCompactTargetTokens(boundaryTokens, cfg = {}) {
+    const boundary = positiveTokenInt(boundaryTokens);
+    if (!boundary) return null;
+    const explicit = positiveTokenInt(cfg.targetTokens ?? cfg.target)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_TOKENS')
+        || envTokenInt('MIXDOG_COMPACT_TARGET_TOKENS');
+    if (explicit) return Math.max(1, Math.min(boundary, explicit));
+    const minTarget = Math.min(boundary, positiveTokenInt(cfg.targetMinTokens ?? cfg.minTargetTokens)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_MIN_TOKENS')
+        || envTokenInt('MIXDOG_COMPACT_TARGET_MIN_TOKENS')
+        || COMPACT_TARGET_MIN_TOKENS);
+    const maxTarget = Math.min(boundary, positiveTokenInt(cfg.targetMaxTokens ?? cfg.maxTargetTokens)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_MAX_TOKENS')
+        || envTokenInt('MIXDOG_COMPACT_TARGET_MAX_TOKENS')
+        || COMPACT_TARGET_MAX_TOKENS);
+    const byRatio = Math.max(1, Math.floor(boundary * resolveCompactTargetRatio(cfg)));
+    return Math.max(1, Math.min(boundary, maxTarget, Math.max(minTarget, byRatio)));
+}
+function resolveCompactKeepTokens(cfg = {}) {
+    return positiveTokenInt(cfg.keepTokens ?? cfg.keep?.tokens ?? cfg.preserveRecentTokens)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_KEEP_TOKENS')
+        || DEFAULT_COMPACTION_KEEP_TOKENS;
+}
+export function resolveWorkerCompactPolicy(sessionRef, tools) {
+    if (!sessionRef) return null;
+    const cfg = sessionRef.compaction || {};
+    const auto = cfg.auto !== false && envFlag('MIXDOG_AGENT_COMPACT_AUTO', true);
+    if (!auto) return { auto: false };
+    const contextWindow = positiveTokenInt(sessionRef.contextWindow ?? cfg.contextWindow);
+    const explicitBoundary = positiveTokenInt(sessionRef.compactBoundaryTokens ?? cfg.boundaryTokens);
+    const autoLimit = positiveTokenInt(sessionRef.autoCompactTokenLimit ?? cfg.autoCompactTokenLimit);
+    const boundaryTokens = explicitBoundary && contextWindow
+        ? Math.min(explicitBoundary, contextWindow)
+        : (explicitBoundary || contextWindow || autoLimit);
+    if (!boundaryTokens) return null;
+    const compactBoundaryTokens = Math.max(1, Math.floor(boundaryTokens * COMPACT_SAFETY_PERCENT));
+    // Only an explicit auto-compact limit STRICTLY BELOW the boundary acts as
+    // the trigger. A persisted value == boundary (legacy derived full-window
+    // autoCompactTokenLimit) would set autoTriggerTokens == boundary and
+    // collapse/override the default trigger, so it is ignored in favor of the
+    // default boundary trigger.
+    const autoTriggerTokens = autoLimit && autoLimit < compactBoundaryTokens ? Math.max(1, autoLimit) : null;
+    // Sanitized explicit limit: only a sub-boundary value is a real auto-compact
+    // limit. Anything >= boundary is a legacy derived full-window artifact and
+    // is reported as null so rememberCompactTelemetry does not re-persist it
+    // back onto the session and re-collapse the buffer on the next turn.
+    const explicitAutoCompactTokenLimit = autoTriggerTokens;
+    const bufferTokens = autoTriggerTokens
+        ? Math.max(0, compactBoundaryTokens - autoTriggerTokens)
+        : resolveCompactBufferTokens(compactBoundaryTokens, cfg);
+    const bufferRatio = compactBoundaryTokens ? (bufferTokens / compactBoundaryTokens) : resolveCompactBufferRatio(cfg);
+    const triggerTokens = autoTriggerTokens || Math.max(1, compactBoundaryTokens - bufferTokens);
+    const configuredReserve = positiveTokenInt(cfg.reservedTokens)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_RESERVED_TOKENS')
+        || 0;
+    const requestReserve = estimateRequestReserveTokens(tools);
+    const keepTokens = resolveCompactKeepTokens(cfg);
+    const compactType = resolveCompactTypeSetting(sessionRef, cfg);
+    return {
+        auto: true,
+        type: compactType,
+        compactType,
+        prune: cfg.prune === true || envFlag('MIXDOG_AGENT_COMPACT_PRUNE', false),
+        boundaryTokens: compactBoundaryTokens,
+        triggerTokens,
+        bufferTokens,
+        bufferRatio,
+        contextWindow,
+        rawContextWindow: positiveTokenInt(sessionRef.rawContextWindow ?? cfg.rawContextWindow) || contextWindow,
+        effectiveContextWindowPercent: Number.isFinite(Number(sessionRef.effectiveContextWindowPercent ?? cfg.effectiveContextWindowPercent))
+            ? Number(sessionRef.effectiveContextWindowPercent ?? cfg.effectiveContextWindowPercent)
+            : null,
+        autoCompactTokenLimit: explicitAutoCompactTokenLimit,
+        semantic: compactTypeIsSemantic(compactType) && resolveSemanticCompactSetting(sessionRef, cfg),
+        recallFastTrack: compactTypeIsRecallFastTrack(compactType),
+        semanticTimeoutMs: positiveTokenInt(cfg.timeoutMs) || envTokenInt('MIXDOG_AGENT_COMPACT_TIMEOUT_MS') || 30_000,
+        tailTurns: positiveTokenInt(cfg.tailTurns) || envTokenInt('MIXDOG_AGENT_COMPACT_TAIL_TURNS') || 2,
+        keepTokens,
+        preserveRecentTokens: positiveTokenInt(cfg.preserveRecentTokens) || envTokenInt('MIXDOG_AGENT_COMPACT_PRESERVE_RECENT_TOKENS') || keepTokens,
+        reserveTokens: requestReserve + configuredReserve,
+        requestReserveTokens: requestReserve,
+        configuredReserveTokens: configuredReserve,
+    };
+}
+/** Transcript + request reserve only (never provider lastContextTokens). */
+function compactPressureTokens(messageTokensEst, policy) {
+    if (messageTokensEst === null) return 0;
+    return Math.max(0, messageTokensEst + (policy?.reserveTokens || 0));
+}
+
+/** Telemetry pressure when a reactive overflow retry forces the next compact. */
+export function compactionTelemetryPressureTokens(messageTokensEst, policy, { reactivePending = false } = {}) {
+    const base = compactPressureTokens(messageTokensEst, policy);
+    if (!reactivePending) return base;
+    const floor = positiveTokenInt(policy?.triggerTokens) || positiveTokenInt(policy?.boundaryTokens) || 0;
+    return floor ? Math.max(base, floor) : base;
+}
+export function compactTargetBudget(policy) {
+    const boundary = positiveTokenInt(policy?.boundaryTokens);
+    if (!boundary) return null;
+    const reserve = Math.max(0, Number(policy?.reserveTokens) || 0);
+    const targetEffective = resolveCompactTargetTokens(boundary, policy) || boundary;
+    return Math.max(1, Math.min(boundary, targetEffective + reserve));
+}
+export function shouldCompactForSession(messageTokensEst, policy, { forceReactive = false } = {}) {
+    if (!policy?.auto || !policy.boundaryTokens) return false;
+    if (forceReactive) return true;
+    if (messageTokensEst === null) return true;
+    return compactPressureTokens(messageTokensEst, policy) >= (policy.triggerTokens || policy.boundaryTokens);
+}
+export function countPrunedToolOutputs(before, after) {
+    if (!Array.isArray(before) || !Array.isArray(after)) return 0;
+    let count = 0;
+    const n = Math.min(before.length, after.length);
+    for (let i = 0; i < n; i += 1) {
+        if (before[i]?.role !== 'tool' || after[i]?.role !== 'tool') continue;
+        if (before[i]?.content !== after[i]?.content && after[i]?.compactedKind === 'tool_output_prune') count += 1;
+    }
+    return count;
+}
+export function rememberCompactTelemetry(sessionRef, policy, meta = {}) {
+    if (!sessionRef || !policy) return;
+    const prev = sessionRef.compaction && typeof sessionRef.compaction === 'object'
+        ? sessionRef.compaction
+        : {};
+    const changed = meta.compactChanged === true || meta.pruneCount > 0;
+    sessionRef.compaction = {
+        ...prev,
+        auto: policy.auto !== false,
+        prune: policy.prune === true,
+        reservedTokens: policy.configuredReserveTokens || prev.reservedTokens || null,
+        requestReserveTokens: policy.requestReserveTokens || 0,
+        reserveTokens: policy.reserveTokens || 0,
+        boundaryTokens: policy.boundaryTokens || null,
+        triggerTokens: policy.triggerTokens || null,
+        bufferTokens: policy.bufferTokens || 0,
+        bufferRatio: policy.bufferRatio ?? prev.bufferRatio ?? null,
+        contextWindow: policy.contextWindow || null,
+        rawContextWindow: policy.rawContextWindow || null,
+        effectiveContextWindowPercent: policy.effectiveContextWindowPercent ?? null,
+        autoCompactTokenLimit: policy.autoCompactTokenLimit || null,
+        type: policy.compactType || policy.type || DEFAULT_COMPACT_TYPE,
+        compactType: policy.compactType || policy.type || DEFAULT_COMPACT_TYPE,
+        semantic: policy.semantic === true ? 'auto' : false,
+        recallFastTrack: policy.recallFastTrack === true,
+        semanticModel: policy.semanticModel || null,
+        semanticTimeoutMs: policy.semanticTimeoutMs || null,
+        tailTurns: policy.tailTurns || null,
+        keepTokens: policy.keepTokens || null,
+        preserveRecentTokens: policy.preserveRecentTokens || null,
+        lastCheckedAt: Date.now(),
+        lastBeforeTokens: meta.beforeTokens ?? null,
+        lastAfterTokens: meta.afterTokens ?? null,
+        lastPressureTokens: meta.pressureTokens ?? null,
+        currentEstimatedTokens: meta.pressureTokens ?? prev.currentEstimatedTokens ?? null,
+        lastApiRequestTokens: positiveTokenInt(sessionRef?.lastContextTokens) || prev.lastApiRequestTokens || null,
+        lastStage: meta.stage || prev.lastStage || null,
+        lastChanged: changed,
+        lastTrigger: meta.trigger || prev.lastTrigger || null,
+        lastSemantic: meta.semanticCompact === true,
+        lastSemanticError: Object.hasOwn(meta, 'semanticError')
+            ? (meta.semanticError ?? null)
+            : (prev.lastSemanticError ?? null),
+        lastRecallFastTrack: meta.recallFastTrack === true,
+        lastRecallFastTrackError: Object.hasOwn(meta, 'recallFastTrackError')
+            ? (meta.recallFastTrackError ?? null)
+            : (prev.lastRecallFastTrackError ?? null),
+        lastError: Object.hasOwn(meta, 'compactError') || Object.hasOwn(meta, 'lastError')
+            ? (meta.compactError ?? meta.lastError ?? null)
+            : (prev.lastError ?? null),
+        lastPruneCount: meta.pruneCount || 0,
+        lastDurationMs: meta.durationMs != null && Number.isFinite(Number(meta.durationMs))
+            ? Math.max(0, Math.round(Number(meta.durationMs)))
+            : null,
+        compactCount: (prev.compactCount || 0) + (changed ? 1 : 0),
+    };
+    if (changed) {
+        const changedAt = Date.now();
+        sessionRef.compaction.lastChangedAt = changedAt;
+        sessionRef.compaction.lastCompactAt = changedAt;
+        sessionRef.lastContextTokensStaleAfterCompact = true;
+    }
+    sessionRef.contextWindow = policy.contextWindow || sessionRef.contextWindow;
+    sessionRef.rawContextWindow = policy.rawContextWindow || sessionRef.rawContextWindow;
+    sessionRef.compactBoundaryTokens = policy.boundaryTokens || sessionRef.compactBoundaryTokens || null;
+    // Persist only the sanitized (sub-boundary) explicit limit. policy.autoCompactTokenLimit
+    // is already null for legacy derived full-window values, so a stale
+    // boundary-sized autoCompactTokenLimit on the session is cleared here rather
+    // than carried forward to re-collapse the buffer next turn.
+    {
+        const _boundary = positiveTokenInt(sessionRef.compactBoundaryTokens);
+        const _prevLimit = positiveTokenInt(sessionRef.autoCompactTokenLimit);
+        const _keepPrev = _prevLimit && (!_boundary || _prevLimit < _boundary) ? _prevLimit : null;
+        sessionRef.autoCompactTokenLimit = policy.autoCompactTokenLimit || _keepPrev || null;
+    }
+    if (policy.effectiveContextWindowPercent !== null) {
+        sessionRef.effectiveContextWindowPercent = policy.effectiveContextWindowPercent;
+    }
+}
+
+export function emitCompactEvent(opts, event = {}) {
+    if (!opts || typeof opts.onCompactEvent !== 'function') return;
+    try { opts.onCompactEvent({ ts: Date.now(), ...event }); }
+    catch { /* best-effort UI/log hook */ }
+}
+
+export function compactEventType(policy, fallback = DEFAULT_COMPACT_TYPE) {
+    return policy?.compactType || policy?.type || fallback;
+}

package/src/runtime/agent/orchestrator/session/loop/context-overflow.mjs

@@ -0,0 +1,38 @@
+// Agent context-overflow error, extracted from loop.mjs. Raised when the latest
+// turn cannot fit the target context budget even after compaction.
+
+export class AgentContextOverflowError extends Error {
+    constructor({ stage, sessionId, provider, model, contextWindow, budgetTokens, reserveTokens, messageTokensEst }, cause) {
+        const target = [provider, model].filter(Boolean).join('/') || 'target model';
+        const causeMsg = cause && cause.message ? `: ${cause.message}` : '';
+        super(
+            `agent context overflow (${target}, stage=${stage || 'compact'}): ` +
+            `latest turn cannot fit target context budget=${budgetTokens ?? 'unknown'} ` +
+            `reserve=${reserveTokens ?? 'unknown'} contextWindow=${contextWindow ?? 'unknown'} ` +
+            `messageTokensEst=${messageTokensEst ?? 'unknown'}${causeMsg}`,
+        );
+        this.name = 'AgentContextOverflowError';
+        this.code = 'AGENT_CONTEXT_OVERFLOW';
+        this.sessionId = sessionId || null;
+        this.provider = provider || null;
+        this.model = model || null;
+        this.contextWindow = contextWindow ?? null;
+        this.budgetTokens = budgetTokens ?? null;
+        this.reserveTokens = reserveTokens ?? null;
+        this.messageTokensEst = messageTokensEst ?? null;
+        if (cause) this.cause = cause;
+    }
+}
+
+export function agentContextOverflowError({ stage, sessionId, sessionRef, model, budgetTokens, reserveTokens, messageTokensEst }, cause) {
+    return new AgentContextOverflowError({
+        stage,
+        sessionId,
+        provider: sessionRef?.provider || null,
+        model: sessionRef?.model || model || null,
+        contextWindow: sessionRef?.contextWindow ?? null,
+        budgetTokens,
+        reserveTokens,
+        messageTokensEst,
+    }, cause);
+}

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

@@ -0,0 +1,14 @@
+// Env-var / token parsing helpers extracted from loop.mjs.
+
+export function positiveTokenInt(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+export function envFlag(name, fallback = false) {
+    const v = process.env[name];
+    if (v === undefined) return fallback;
+    return !['0', 'false', 'off', 'no'].includes(String(v).trim().toLowerCase());
+}
+export function envTokenInt(name) {
+    return positiveTokenInt(process.env[name]);
+}

package/src/runtime/agent/orchestrator/session/loop/hidden-agents.mjs

@@ -0,0 +1,21 @@
+// Hidden (sub-agent) role registry, extracted from loop.mjs.
+// Source of truth: defaults/agents.json — read once and cached. HIDDEN_AGENT_NAMES
+// is built eagerly so it stays in sync with the declarative registry (no
+// hardcoded duplicate).
+import { readFileSync as _readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve as resolvePath } from 'path';
+
+const _AGENTS_JSON = resolvePath(dirname(fileURLToPath(import.meta.url)), '../../../../../defaults/agents.json');
+let _hiddenAgentsCache = null;
+function _getHiddenAgents() {
+    if (_hiddenAgentsCache) return _hiddenAgentsCache;
+    try {
+        _hiddenAgentsCache = JSON.parse(_readFileSync(_AGENTS_JSON, 'utf8'));
+    } catch { _hiddenAgentsCache = { agents: [] }; }
+    return _hiddenAgentsCache;
+}
+
+export const HIDDEN_AGENT_NAMES = new Set(
+    (_getHiddenAgents().agents || []).map((r) => r && r.agent).filter((n) => typeof n === 'string' && n.length > 0)
+);

package/src/runtime/agent/orchestrator/session/loop/pre-dispatch-deny.mjs

@@ -0,0 +1,49 @@
+// Shared pre-dispatch deny — single source of truth for the remaining
+// control-plane / role scoping rejects. Called by BOTH the eager dispatch
+// path (startEagerTool) and the serial dispatch path (executeTool body).
+// Returns null when the call is allowed to proceed; otherwise returns the
+// Error string the serial path would emit. The eager caller ignores the
+// message body and just treats non-null as "do not start eager".
+//
+// This is NOT a permission gate — runtime permission enforcement was removed
+// (every tool call is trusted). What remains is architectural scoping:
+// agent workers are sandboxed to code/research tools. They must never reach
+// owner/host control surfaces: session management, the ENTIRE channels module
+// (Discord messaging, schedules, webhook/config, channel-bridge toggle,
+// command injection), or host input injection. Explicit name list (no imports)
+// keeps this hot-path gate dependency-free; add new owner/channel tools here.
+import { isAgentOwner } from '../../agent-owner.mjs';
+
+const WORKER_DENIED_TOOLS = new Set([
+    // session control-plane — unified into the single `agent` tool
+    // (type=spawn|send|close|list). Denying the one name blocks all worker
+    // session control.
+    'agent',
+    // channels module (owner/Discord-facing)
+    'reply', 'react', 'edit_message', 'download_attachment', 'fetch',
+    'schedule_status', 'trigger_schedule', 'schedule_control',
+    'activate_channel_bridge', 'reload_config', 'inject_command',
+    // host input injection
+    'inject_input',
+]);
+
+function _preDispatchDeny(call, toolKind, sessionRef) {
+    const name = call?.name;
+    if (typeof name !== 'string' || !name) return null;
+    const _agentOwned = sessionRef?.scope?.startsWith?.('agent:')
+        || isAgentOwner(sessionRef);
+    const _controlPlaneTool = WORKER_DENIED_TOOLS.has(name);
+    if (_agentOwned && _controlPlaneTool) {
+        return `Error: control-plane tool "${name}" is Lead-only and not available to agent workers.`;
+    }
+    const noToolAgent = sessionRef?.agent === 'cycle1-agent' || sessionRef?.agent === 'cycle2-agent';
+    if (noToolAgent) {
+        return `Error: tool "${name}" is not available in agent "${sessionRef.agent}". Re-emit the answer as pipe-separated text per the agent's output format (first character a digit, NO tool_use blocks, NO JSON, NO prose, NO apology).`;
+    }
+    return null;
+}
+
+/** Exported for smoke tests — same runtime deny as the agent loop. */
+export function preDispatchDenyForSession(sessionRef, call, toolKind = 'builtin') {
+    return _preDispatchDeny(call, toolKind, sessionRef);
+}

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/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);
+}