mixdog 0.9.1 → 0.9.3

package/src/runtime/agent/orchestrator/session/context-utils.mjs

@@ -66,7 +66,7 @@ function codePointTokenWeight(cp) {
 // surrogate-pair emoji are scored once, at the high emoji weight), takes the
 // max of the weighted sum and the chars/4 ASCII floor, then applies the safety
 // multiplier. Always overcounts relative to chars/4 for non-ASCII text.
-function estimateTokens(text) {
+export function estimateTokens(text) {
     const s = String(text ?? '');
     if (s.length === 0) return 0;
     let weighted = 0;
@@ -74,7 +74,7 @@ function estimateTokens(text) {
     const asciiFloor = s.length / 4; // never below the legacy chars/4 lower bound
     return Math.ceil(Math.max(weighted, asciiFloor) * TOKEN_ESTIMATE_SAFETY_MULTIPLIER);
 }
-function messageEstimateText(m) {
+export function messageEstimateText(m) {
     if (!m || typeof m !== 'object') return '';
     let text = typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? '');
     if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length) {
@@ -84,13 +84,260 @@ function messageEstimateText(m) {
     if (m.role === 'tool' && m.toolCallId) text += `\n${m.toolCallId}`;
     return text;
 }
-function estimateMessageTokens(m) {
+export function estimateMessageTokens(m) {
     return estimateTokens(messageEstimateText(m)) + 4;
 }
 export function estimateMessagesTokens(messages) {
     return messages.reduce((sum, m) => sum + estimateMessageTokens(m), 0);
 }
 
+export const DEFAULT_COMPACTION_BUFFER_TOKENS = 0;
+export const DEFAULT_COMPACTION_BUFFER_RATIO = 0.1;
+export const MAX_COMPACTION_BUFFER_RATIO = 0.25;
+export const DEFAULT_COMPACTION_KEEP_TOKENS = 8_000;
+const LEGACY_DEFAULT_COMPACTION_BUFFER_RATIO = 0.1;
+
+export function positiveTokenInt(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+function envTokenInt(name) {
+    return positiveTokenInt(process.env[name]);
+}
+
+export function normalizeCompactionBufferRatio(value, fallback = DEFAULT_COMPACTION_BUFFER_RATIO) {
+    const n = Number(value);
+    if (Number.isFinite(n) && n > 0) return n > 1 ? n / 100 : n;
+    return fallback;
+}
+
+// Percent-named inputs (bufferPercent / bufferPct / *_BUFFER_PERCENT) carry a
+// PERCENT: 1 means 1% (0.01). Ratio-named inputs (bufferRatio / bufferFraction)
+// carry a fraction: 0.01 means 1%, and a legacy value > 1 is read as a percent.
+export function resolveBufferRatioCandidate(percentInputs = [], ratioInputs = []) {
+    for (const raw of percentInputs) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0) return Math.min(1, n / 100);
+    }
+    for (const raw of ratioInputs) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0) return n > 1 ? n / 100 : n;
+    }
+    return null;
+}
+
+export function resolveCompactBufferRatio(cfg = {}) {
+    const resolved = resolveBufferRatioCandidate(
+        [cfg.bufferPercent, cfg.bufferPct, process.env.MIXDOG_AGENT_COMPACT_BUFFER_PERCENT],
+        [cfg.bufferRatio, cfg.bufferFraction, process.env.MIXDOG_AGENT_COMPACT_BUFFER_RATIO],
+    );
+    return normalizeCompactionBufferRatio(resolved, DEFAULT_COMPACTION_BUFFER_RATIO);
+}
+
+export function compactionBufferTokensForBoundary(boundaryTokens, opts = {}) {
+    const boundary = Math.max(0, Math.floor(Number(boundaryTokens) || 0));
+    const explicit = Math.max(0, Math.floor(Number(opts.explicitTokens) || 0));
+    if (!boundary) return explicit;
+    const maxRatio = normalizeCompactionBufferRatio(opts.maxRatio, MAX_COMPACTION_BUFFER_RATIO);
+    const cap = Math.max(0, Math.floor(boundary * maxRatio));
+    if (explicit > 0) return Math.max(0, Math.min(explicit, cap));
+    const ratio = normalizeCompactionBufferRatio(opts.ratio, DEFAULT_COMPACTION_BUFFER_RATIO);
+    return Math.max(0, Math.min(Math.floor(boundary * ratio), cap));
+}
+
+export function isPersistedZeroBufferTelemetry(cfg = {}, boundaryTokens = 0) {
+    const boundary = positiveTokenInt(boundaryTokens);
+    if (!boundary) return false;
+    if (envTokenInt('MIXDOG_AGENT_COMPACT_BUFFER_TOKENS')) return false;
+    for (const envName of ['MIXDOG_AGENT_COMPACT_BUFFER_PERCENT', 'MIXDOG_AGENT_COMPACT_BUFFER_RATIO']) {
+        const n = Number(process.env[envName]);
+        if (Number.isFinite(n) && n > 0) return false;
+    }
+    for (const key of ['bufferPercent', 'bufferPct', 'bufferFraction']) {
+        const n = Number(cfg?.[key]);
+        if (Number.isFinite(n) && n > 0) return false;
+    }
+    const ratio = Number(cfg?.bufferRatio);
+    if (Number.isFinite(ratio) && ratio > 0) return false;
+    const explicitTokens = Number(cfg?.bufferTokens ?? cfg?.buffer);
+    if (!Number.isFinite(explicitTokens) || explicitTokens !== 0) return false;
+    return true;
+}
+
+export function isLegacyDefaultBufferTelemetry(cfg = {}, boundaryTokens = 0) {
+    const boundary = positiveTokenInt(boundaryTokens);
+    if (!boundary) return false;
+    if (envTokenInt('MIXDOG_AGENT_COMPACT_BUFFER_TOKENS')) return false;
+    for (const envName of ['MIXDOG_AGENT_COMPACT_BUFFER_PERCENT', 'MIXDOG_AGENT_COMPACT_BUFFER_RATIO']) {
+        const n = Number(process.env[envName]);
+        if (Number.isFinite(n) && n > 0) return false;
+    }
+    // Percent/fraction-named fields are operator config. Legacy/default
+    // telemetry persisted bufferTokens + bufferRatio after a check/compact pass.
+    for (const key of ['bufferPercent', 'bufferPct', 'bufferFraction']) {
+        const n = Number(cfg?.[key]);
+        if (Number.isFinite(n) && n > 0) return false;
+    }
+    const explicitTokens = positiveTokenInt(cfg?.bufferTokens ?? cfg?.buffer);
+    const ratio = Number(cfg?.bufferRatio);
+    if (!explicitTokens || !Number.isFinite(ratio) || Math.abs(ratio - LEGACY_DEFAULT_COMPACTION_BUFFER_RATIO) > 1e-9) return false;
+    const expectedTokens = Math.floor(boundary * LEGACY_DEFAULT_COMPACTION_BUFFER_RATIO);
+    const cfgBoundary = positiveTokenInt(cfg?.boundaryTokens);
+    const cfgTrigger = positiveTokenInt(cfg?.triggerTokens);
+    return explicitTokens === expectedTokens
+        || (cfgBoundary === boundary && cfgTrigger > 0 && explicitTokens === Math.max(0, boundary - cfgTrigger));
+}
+
+export function compactBufferConfigForBoundary(cfg = {}, boundaryTokens = 0) {
+    const base = cfg || {};
+    if (!isLegacyDefaultBufferTelemetry(base, boundaryTokens)
+        && !isPersistedZeroBufferTelemetry(base, boundaryTokens)) {
+        return base;
+    }
+    return {
+        ...base,
+        bufferTokens: null,
+        buffer: null,
+        bufferRatio: null,
+    };
+}
+
+export function resolveCompactBufferTokens(boundaryTokens, cfg = {}, opts = {}) {
+    const boundary = positiveTokenInt(boundaryTokens);
+    const effectiveCfg = compactBufferConfigForBoundary(cfg, boundary);
+    const configured = positiveTokenInt(effectiveCfg.bufferTokens ?? effectiveCfg.buffer)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_BUFFER_TOKENS')
+        || 0;
+    if (!boundary) return configured || positiveTokenInt(opts.defaultTokens) || DEFAULT_COMPACTION_BUFFER_TOKENS;
+    return compactionBufferTokensForBoundary(boundary, {
+        explicitTokens: configured,
+        ratio: resolveCompactBufferRatio(effectiveCfg),
+        maxRatio: opts.maxRatio ?? MAX_COMPACTION_BUFFER_RATIO,
+    });
+}
+
+export function resolveCompactTriggerTokens(sessionOrConfig = {}, boundaryTokens = 0) {
+    const boundary = positiveTokenInt(boundaryTokens);
+    if (!boundary) return null;
+    const cfg = sessionOrConfig?.compaction || sessionOrConfig || {};
+    const autoLimit = positiveTokenInt(sessionOrConfig?.autoCompactTokenLimit ?? cfg?.autoCompactTokenLimit);
+    if (autoLimit && autoLimit < boundary) return Math.max(1, autoLimit);
+    const buffer = resolveCompactBufferTokens(boundary, cfg);
+    return Math.max(1, boundary - buffer);
+}
+
+function stripSystemReminder(text) {
+    return String(text || '')
+        .replace(/^\s*<system-reminder>\s*/i, '')
+        .replace(/\s*<\/system-reminder>\s*$/i, '')
+        .trim();
+}
+
+function splitMarkdownSections(text) {
+    const sections = [];
+    let current = [];
+    for (const line of String(text || '').split(/\r?\n/)) {
+        if (/^#\s+/.test(line) && current.length) {
+            const body = current.join('\n').trim();
+            if (body) sections.push(body);
+            current = [line];
+        } else {
+            current.push(line);
+        }
+    }
+    const tail = current.join('\n').trim();
+    if (tail) sections.push(tail);
+    return sections;
+}
+
+function reminderSectionBucket(section) {
+    const heading = String(section.match(/^#\s+([^\n]+)/)?.[1] || '').trim().toLowerCase();
+    if (heading.includes('core memory')) return 'memory';
+    if (heading.includes('active workflow') || heading.includes('available agents') || heading.includes('workflow')) return 'workflow';
+    if (heading.includes('workspace')) return 'workspace';
+    if (heading.includes('environment')) return 'environment';
+    return 'other';
+}
+
+export function summarizeContextMessages(messages) {
+    const rows = {
+        system: { count: 0, tokens: 0 },
+        user: { count: 0, tokens: 0 },
+        assistant: { count: 0, tokens: 0 },
+        tool: { count: 0, tokens: 0 },
+        other: { count: 0, tokens: 0 },
+    };
+    const semantic = {
+        system: { count: 0, tokens: 0 },
+        chat: { count: 0, tokens: 0 },
+        assistant: { count: 0, tokens: 0 },
+        toolResults: { count: 0, tokens: 0 },
+        reminders: { count: 0, tokens: 0, otherTokens: 0 },
+        workflow: { tokens: 0 },
+        memory: { tokens: 0 },
+        workspace: { tokens: 0 },
+        environment: { tokens: 0 },
+        other: { tokens: 0 },
+    };
+    let toolCallCount = 0;
+    let toolCallTokens = 0;
+    let toolResultCount = 0;
+    let toolResultTokens = 0;
+    for (const message of messages || []) {
+        const role = rows[message?.role] ? message.role : 'other';
+        const text = messageEstimateText(message);
+        const tokens = estimateMessageTokens(message);
+        rows[role].count += 1;
+        rows[role].tokens += tokens;
+        if (role === 'system') {
+            semantic.system.count += 1;
+            semantic.system.tokens += tokens;
+        } else if (role === 'user') {
+            if (String(text || '').trim().startsWith('<system-reminder>')) {
+                semantic.reminders.count += 1;
+                semantic.reminders.tokens += tokens;
+                let sectionTokens = 0;
+                for (const section of splitMarkdownSections(stripSystemReminder(text))) {
+                    const bucket = reminderSectionBucket(section);
+                    const sectionTokenCount = estimateTokens(section);
+                    semantic[bucket].tokens += sectionTokenCount;
+                    sectionTokens += sectionTokenCount;
+                }
+                semantic.reminders.otherTokens += Math.max(0, tokens - sectionTokens);
+            } else {
+                semantic.chat.count += 1;
+                semantic.chat.tokens += tokens;
+            }
+        } else if (role === 'assistant') {
+            semantic.assistant.count += 1;
+            semantic.assistant.tokens += tokens;
+        } else if (role === 'tool') {
+            semantic.toolResults.count += 1;
+            semantic.toolResults.tokens += tokens;
+        }
+        if (message?.role === 'assistant' && Array.isArray(message.toolCalls) && message.toolCalls.length) {
+            toolCallCount += message.toolCalls.length;
+            try { toolCallTokens += estimateTokens(JSON.stringify(message.toolCalls)); }
+            catch { toolCallTokens += estimateTokens(`[${message.toolCalls.length} tool calls]`); }
+        }
+        if (message?.role === 'tool') {
+            toolResultCount += 1;
+            toolResultTokens += tokens;
+        }
+    }
+    return {
+        count: Array.isArray(messages) ? messages.length : 0,
+        estimatedTokens: Array.isArray(messages) ? estimateMessagesTokens(messages) : 0,
+        roles: rows,
+        semantic,
+        toolCallCount,
+        toolCallTokens,
+        toolResultCount,
+        toolResultTokens,
+    };
+}
+
 // Per-request overhead the provider injects that never appears in the
 // `messages` array: function-calling preamble + system-prompt framing the
 // provider wraps around the request. The chars/4 message estimate misses all

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

@@ -0,0 +1,28 @@
+// Compaction debug/diagnostic helpers extracted from loop.mjs.
+import { estimateMessagesTokens } from '../context-utils.mjs';
+
+export function estimateMessagesTokensSafe(messages) {
+    try { return estimateMessagesTokens(messages); }
+    catch { return null; }
+}
+
+export function compactDebugEnabled() {
+    return String(process.env.MIXDOG_COMPACT_DEBUG || '').trim() === '1';
+}
+
+export function compactDiagnosticError(err) {
+    if (!err) return null;
+    const text = String(err?.message || err);
+    return text.length > 500 ? `${text.slice(0, 499)}…` : text;
+}
+
+export function compactByteLength(text) {
+    try { return Buffer.byteLength(String(text || ''), 'utf8'); }
+    catch { return String(text || '').length; }
+}
+
+export function compactDebugLog(scope, details = {}) {
+    if (!compactDebugEnabled()) return;
+    try { process.stderr.write(`[compact] ${scope} ${JSON.stringify(details)}\n`); }
+    catch { /* best-effort diagnostics only */ }
+}

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