mixdog 0.9.52 → 0.9.53

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

@@ -14,14 +14,27 @@ function _usageNum(value) {
     return Number.isFinite(n) ? n : 0;
 }
 
-export function _combineUsageWithWarmup(actual, warmup) {
+export function _combineUsageWithWarmup(actual, warmup, { separateMainContext = false } = {}) {
     if (!warmup) return actual;
-    if (!actual) return warmup;
+    if (!actual) {
+        // A warmup-only settle is billable, but has no corresponding main
+        // request whose context footprint can be measured.
+        const combined = {
+            ...warmup,
+            warmupInputTokens: _usageNum(warmup.inputTokens),
+            warmupCachedTokens: _usageNum(warmup.cachedTokens),
+            warmupOutputTokens: _usageNum(warmup.outputTokens),
+            warmupPromptTokens: _usageNum(warmup.promptTokens),
+            warmupCacheWriteTokens: _usageNum(warmup.cacheWriteTokens),
+        };
+        if (separateMainContext) combined.mainUsageAvailable = false;
+        return combined;
+    }
     const actualRaw = actual.raw || {};
     const warmupRaw = warmup.raw || {};
     const actualTicks = _usageNum(actualRaw.cost_in_usd_ticks);
     const warmupTicks = _usageNum(warmupRaw.cost_in_usd_ticks);
-    return {
+    const combined = {
         ...actual,
         inputTokens: _usageNum(actual.inputTokens) + _usageNum(warmup.inputTokens),
         outputTokens: _usageNum(actual.outputTokens) + _usageNum(warmup.outputTokens),
@@ -30,12 +43,26 @@ export function _combineUsageWithWarmup(actual, warmup) {
         warmupInputTokens: _usageNum(warmup.inputTokens),
         warmupCachedTokens: _usageNum(warmup.cachedTokens),
         warmupOutputTokens: _usageNum(warmup.outputTokens),
+        warmupPromptTokens: _usageNum(warmup.promptTokens),
+        warmupCacheWriteTokens: _usageNum(warmup.cacheWriteTokens),
         raw: {
             ...actualRaw,
             warmup_usage: warmupRaw,
             ...(actualTicks || warmupTicks ? { cost_in_usd_ticks: actualTicks + warmupTicks } : {}),
         },
     };
+    if (separateMainContext) {
+        // OAuth startup prewarm is billable but is not part of the main
+        // request's context footprint. Keep these fields opt-in so shared xAI
+        // usage objects retain their prior shape and accounting behavior.
+        combined.mainInputTokens = _usageNum(actual.inputTokens);
+        combined.mainOutputTokens = _usageNum(actual.outputTokens);
+        combined.mainCachedTokens = _usageNum(actual.cachedTokens);
+        combined.mainPromptTokens = _usageNum(actual.promptTokens);
+        combined.mainCacheWriteTokens = _usageNum(actual.cacheWriteTokens);
+        combined.mainUsageAvailable = true;
+    }
+    return combined;
 }
 
 export function _parseEvent(raw) {

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

@@ -98,9 +98,29 @@ export const WS_PRE_RESPONSE_CREATED_MS = (() => {
 // Single inter-chunk idle timer. Resets on EVERY received frame — any frame,
 // including metadata/keepalive, proves the socket is live.
 export const WS_INTER_CHUNK_MS = PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS;
+// Bound the second allocation performed when ws RawData is decoded to UTF-8.
+// The ws library has already assembled the Buffer by this point, so this check
+// must stay before data.toString() below. xAI shares this stream implementation
+// but retains its existing unbounded behavior.
+export const OPENAI_WS_MAX_INCOMING_FRAME_BYTES = 16 * 1024 * 1024;
 const X_CODEX_TURN_STATE_HEADER = 'x-codex-turn-state';
 const WS_TRACE_ENABLED = process.env.MIXDOG_WS_TRACE === '1';
 
+function _incomingFrameByteLength(data) {
+    if (typeof data === 'string') return Buffer.byteLength(data);
+    if (Array.isArray(data)) {
+        let total = 0;
+        for (const chunk of data) {
+            const size = Number(chunk?.byteLength ?? chunk?.length);
+            if (!Number.isFinite(size) || size < 0) return null;
+            total += size;
+        }
+        return total;
+    }
+    const size = Number(data?.byteLength ?? data?.length);
+    return Number.isFinite(size) && size >= 0 ? size : null;
+}
+
 function _writeWsLifecycleTrace(lifecycle) {
     process.stderr.write(`[ws-trace] t=${new Date().toISOString()} lifecycle=${lifecycle}\n`);
 }
@@ -207,13 +227,6 @@ function _traceWsHeaderKeys(entry, event, midState, traceProvider, model) {
         else entry.wsHeaderKeysEmptyTraced = true;
     } catch {}
 }
-// _wsErrLabel moved to openai-ws-pool.mjs (imported above).
-// Delta/matching helpers (_sansInput, _stableStringify, _cloneJson,
-// _logicalResponseItemMatch, _stripResponseItemsFromHead, _computeDelta,
-// _estimateFrameTokens) → openai-ws-delta.mjs. Usage/event helpers
-// (_combineUsageWithWarmup, _parseEvent, _incompleteReasonFromEvent,
-// _isMaxOutputIncompleteReason, _httpStatusFromWsClose) → openai-ws-events.mjs.
-// All imported + re-exported at the top of this file.
 // tool_search_call.arguments parse. Module-scope (exported) for direct test
 // coverage. Same policy as the function_call_arguments.done path and
 // openai-oauth _parseJsonObject —
@@ -260,6 +273,9 @@ export async function _streamResponse({
     }
     const preResponseCreatedMs = _positiveInt(_timeouts?.preResponseCreatedMs, WS_PRE_RESPONSE_CREATED_MS);
     const interChunkMs = _positiveInt(_timeouts?.interChunkMs, WS_INTER_CHUNK_MS);
+    const maxIncomingFrameBytes = traceProvider === 'xai'
+        ? 0
+        : _positiveInt(_timeouts?.maxIncomingFrameBytes, OPENAI_WS_MAX_INCOMING_FRAME_BYTES);
     // First-MEANINGFUL-frame deadline. Distinct from preResponseCreatedMs (a
     // short pre-created byte-silence window that resetIdle clears on the FIRST
     // frame of any kind): this timer is cleared only by a meaningful response
@@ -777,6 +793,20 @@ export async function _streamResponse({
         };
 
         messageHandler = (data) => {
+            const frameBytes = _incomingFrameByteLength(data);
+            if (maxIncomingFrameBytes > 0 && frameBytes != null && frameBytes > maxIncomingFrameBytes) {
+                const err = new Error(
+                    `OpenAI WebSocket response frame is too large (${frameBytes} bytes; limit ${maxIncomingFrameBytes} bytes); request is retryable`,
+                );
+                err.code = 'EOPENAIWSFRAMETOOLARGE';
+                err.wsFrameTooLarge = true;
+                err.retryable = true;
+                terminalError = err;
+                midState.wsFrameTooLarge = true;
+                try { socket.close(1009, 'frame_too_large'); } catch {}
+                finish();
+                return;
+            }
             if (midState.sendSpan && midState.sendStartedAt != null
                 && midState.sendSpanAttemptFirstEvent !== true) {
                 midState.sendSpanAttemptFirstEvent = true;
@@ -1383,24 +1413,3 @@ export async function _streamResponse({
     });
 }
 
-/**
- * Classify a handshake error for retry eligibility.
- *
- * Default-deny: anything we don't recognize as transient returns null (treat
- * as permanent). Permanent buckets (401/403/404/429) also return null — the
- * server has made a deterministic decision that a retry can't change.
- *
- * Returns one of:
- *   'timeout' — `ws` handshakeTimeout fired
- *   'reset'   — ECONNRESET / socket hang up
- *   'dns'     — EAI_AGAIN / ENOTFOUND / EAI_NODATA
- *   'refused' — ECONNREFUSED
- *   'network' — ENETUNREACH / EHOSTUNREACH / EPIPE
- *   'acquire_timeout' — hard client-side open/acquire deadline fired
- *   'http_5xx' (with specific status e.g. 'http_503') — server overload
- *   null      — not retryable
- */
-// Thin re-export wrapper: handshake classification now lives in the shared
-// retry-classifier (classifyHandshakeError). Kept here as a named export so
-// internal call sites (_acquireWithRetry) and any external importer keep
-// resolving the same symbol.

package/src/runtime/agent/orchestrator/providers/retry-classifier.mjs

@@ -363,10 +363,7 @@ export function classifyMidstreamError(err, signals, policy = {}) {
   return _classifyMidstreamWs(err, signals, attemptIndex, policy)
 }
 
-// Verbatim relocation of openai-oauth-ws's _classifyMidstreamError. `signals`
-// carries sawResponseCreated / sawCompleted / emittedText / emittedToolCall /
-// wsCloseCode / firstByteTimeout / wsSendFailed /
-// userAbort / watchdogAbort / responseFailedPayload exactly as before.
+// WebSocket classification consumes the provider's stream-state signals.
 function _classifyMidstreamWs(err, state, attemptIndex, policy) {
   if (state.sawCompleted) return null
   // Once a tool call has been dispatched, no transport outcome is replay-safe.
@@ -374,6 +371,9 @@ function _classifyMidstreamWs(err, state, attemptIndex, policy) {
   // already be executing, so retry/fallback could duplicate its side effect.
   if (state.emittedToolCall) return null
   if (state.emittedText || err?.liveTextEmitted) return null
+  if (err?.wsFrameTooLarge || state.wsFrameTooLarge) {
+    return _allowMidstream('ws_frame_too_large', attemptIndex, policy)
+  }
   if (state.firstByteTimeout || err?.firstByteTimeout) {
     return _allowMidstream('first_byte_timeout', attemptIndex, policy)
   }
@@ -450,9 +450,7 @@ function _classifyMidstreamWs(err, state, attemptIndex, policy) {
   return null
 }
 
-// Verbatim relocation of anthropic-oauth's _classifyMidstreamError. `signals`
-// carries sawMessageStart / sawCompleted / emittedToolCall / userAbort /
-// watchdogAbort exactly as before.
+// SSE classification consumes the provider's stream-state signals.
 function _classifyMidstreamSse(err, state, attemptIndex, policy) {
   if (attemptIndex >= policy.defaultRetries) return null
   if (state.sawCompleted) return null

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

@@ -641,6 +641,14 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     // additive — callers that ignore these fields keep working.
                     deltaCachedRead: response.usage.cachedTokens || 0,
                     deltaCacheWrite: response.usage.cacheWriteTokens || 0,
+                    // Billing deltas include OAuth WS warmup. Context
+                    // snapshots/baselines must describe only the main send.
+                    contextInputTokens: response.usage.mainInputTokens ?? response.usage.inputTokens ?? 0,
+                    contextOutputTokens: response.usage.mainOutputTokens ?? response.usage.outputTokens ?? 0,
+                    contextPromptTokens: response.usage.mainPromptTokens ?? response.usage.promptTokens ?? 0,
+                    contextCachedReadTokens: response.usage.mainCachedTokens ?? response.usage.cachedTokens ?? 0,
+                    contextCacheWriteTokens: response.usage.mainCacheWriteTokens ?? response.usage.cacheWriteTokens ?? 0,
+                    contextUsageAvailable: response.usage.mainUsageAvailable !== false,
                     sendTools,
                     ts: Date.now(),
                 }));

package/src/runtime/agent/orchestrator/session/context-compaction-policy.mjs

@@ -0,0 +1,170 @@
+import { isAgentOwner } from '../agent-owner.mjs';
+
+export const DEFAULT_COMPACTION_BUFFER_TOKENS = 0;
+export const DEFAULT_COMPACTION_BUFFER_RATIO = 0.1;
+export const DEFAULT_MAIN_COMPACTION_BUFFER_RATIO = 0.05;
+export const MAX_COMPACTION_BUFFER_RATIO = 0.25;
+const MAX_BUFFER_INPUT_RATIO = 0.999_999;
+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;
+}
+export function resolveBufferRatioCandidate(percentInputs = [], ratioInputs = []) {
+    for (const raw of percentInputs) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0) return Math.min(MAX_BUFFER_INPUT_RATIO, n / 100);
+    }
+    for (const raw of ratioInputs) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0) return Math.min(MAX_BUFFER_INPUT_RATIO, 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);
+}
+function positiveTokenCandidate(values = []) {
+    for (const value of values) {
+        const tokens = positiveTokenInt(value);
+        if (tokens) return tokens;
+    }
+    return null;
+}
+function resolveMainBufferSetting(cfg = {}) {
+    const configTokens = positiveTokenCandidate([cfg.mainBufferTokens, cfg.mainBuffer]);
+    if (configTokens) return { tokens: configTokens };
+    const configRatio = resolveBufferRatioCandidate(
+        [cfg.mainBufferPercent, cfg.mainBufferPct],
+        [cfg.mainBufferRatio, cfg.mainBufferFraction],
+    );
+    if (configRatio !== null) return { ratio: configRatio };
+    const envTokens = positiveTokenCandidate([process.env.MIXDOG_MAIN_COMPACT_BUFFER_TOKENS]);
+    if (envTokens) return { tokens: envTokens };
+    const envRatio = resolveBufferRatioCandidate(
+        [process.env.MIXDOG_MAIN_COMPACT_BUFFER_PERCENT],
+        [process.env.MIXDOG_MAIN_COMPACT_BUFFER_RATIO],
+    );
+    return envRatio === null ? null : { ratio: envRatio };
+}
+export function resolveMainCompactBufferRatio(cfg = {}) {
+    const setting = resolveMainBufferSetting(cfg);
+    return setting?.ratio ?? DEFAULT_MAIN_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);
+    return Number.isFinite(explicitTokens) && explicitTokens === 0;
+}
+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;
+    }
+    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 resolveMainCompactBufferTokens(boundaryTokens, cfg = {}, opts = {}) {
+    const boundary = positiveTokenInt(boundaryTokens);
+    const setting = resolveMainBufferSetting(cfg);
+    const configured = setting?.tokens || 0;
+    if (!boundary) return configured || positiveTokenInt(opts.defaultTokens) || DEFAULT_COMPACTION_BUFFER_TOKENS;
+    return compactionBufferTokensForBoundary(boundary, {
+        explicitTokens: configured,
+        ratio: setting?.ratio ?? DEFAULT_MAIN_COMPACTION_BUFFER_RATIO,
+        maxRatio: opts.maxRatio ?? MAX_COMPACTION_BUFFER_RATIO,
+    });
+}
+export function resolveCompactTriggerTokens(sessionOrConfig = {}, boundaryTokens = 0) {
+    return resolveSessionCompactPolicy(sessionOrConfig, boundaryTokens).triggerTokens;
+}
+export function resolveSessionCompactPolicy(sessionOrConfig = {}, boundaryTokens = 0) {
+    const cfg = sessionOrConfig?.compaction || sessionOrConfig || {};
+    const boundary = positiveTokenInt(boundaryTokens);
+    if (!boundary) {
+        return {
+            autoCompactTokenLimit: null,
+            triggerTokens: null,
+            bufferTokens: 0,
+            bufferRatio: isAgentOwner(sessionOrConfig)
+                ? resolveCompactBufferRatio(cfg)
+                : resolveMainCompactBufferRatio(cfg),
+        };
+    }
+    const rawLimit = positiveTokenInt(sessionOrConfig?.autoCompactTokenLimit ?? cfg?.autoCompactTokenLimit);
+    const explicitLimit = rawLimit && rawLimit < boundary ? rawLimit : null;
+    let triggerTokens;
+    if (explicitLimit) triggerTokens = explicitLimit;
+    else if (isAgentOwner(sessionOrConfig)) triggerTokens = Math.max(1, boundary - resolveCompactBufferTokens(boundary, cfg));
+    else triggerTokens = Math.max(1, boundary - resolveMainCompactBufferTokens(boundary, cfg));
+    const bufferTokens = Math.max(0, boundary - triggerTokens);
+    const bufferRatio = bufferTokens / boundary;
+    return { autoCompactTokenLimit: explicitLimit, triggerTokens, bufferTokens, bufferRatio };
+}

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

@@ -1,8 +1,27 @@
 import { isOffloadedToolResultText } from './tool-result-offload.mjs';
 import { createHash } from 'node:crypto';
 import { providerNativeToolPrefixCount } from '../../../../session-runtime/provider-request-tools.mjs';
-import { isAgentOwner } from '../agent-owner.mjs';
 import { contentImageDescriptors, contentToText } from '../providers/media-normalization.mjs';
+export {
+    DEFAULT_COMPACTION_BUFFER_TOKENS,
+    DEFAULT_COMPACTION_BUFFER_RATIO,
+    DEFAULT_MAIN_COMPACTION_BUFFER_RATIO,
+    MAX_COMPACTION_BUFFER_RATIO,
+    DEFAULT_COMPACTION_KEEP_TOKENS,
+    positiveTokenInt,
+    normalizeCompactionBufferRatio,
+    resolveBufferRatioCandidate,
+    resolveCompactBufferRatio,
+    resolveMainCompactBufferRatio,
+    compactionBufferTokensForBoundary,
+    isPersistedZeroBufferTelemetry,
+    isLegacyDefaultBufferTelemetry,
+    compactBufferConfigForBoundary,
+    resolveCompactBufferTokens,
+    resolveMainCompactBufferTokens,
+    resolveCompactTriggerTokens,
+    resolveSessionCompactPolicy,
+} from './context-compaction-policy.mjs';
 
 // ---------------------------------------------------------------------------
 // Conservative, Unicode-aware token estimator.
@@ -377,228 +396,6 @@ function contextSummaryResult(state, count) {
     };
 }
 
-export const DEFAULT_COMPACTION_BUFFER_TOKENS = 0;
-export const DEFAULT_COMPACTION_BUFFER_RATIO = 0.1;
-// Main/user recall-fasttrack compacts at 95% by default. Lower triggers remain
-// opt-in through the mainBuffer* configuration and MIXDOG_MAIN_COMPACT_BUFFER_*.
-export const DEFAULT_MAIN_COMPACTION_BUFFER_RATIO = 0.05;
-export const MAX_COMPACTION_BUFFER_RATIO = 0.25;
-const MAX_BUFFER_INPUT_RATIO = 0.999_999;
-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(MAX_BUFFER_INPUT_RATIO, n / 100);
-    }
-    for (const raw of ratioInputs) {
-        const n = Number(raw);
-        if (Number.isFinite(n) && n > 0) return Math.min(MAX_BUFFER_INPUT_RATIO, 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);
-}
-
-// Main/user settings are deliberately separate from the semantic-agent buffer:
-// `buffer*` and MIXDOG_AGENT_COMPACT_BUFFER_* remain agent-only controls.
-// Source precedence is config before environment; within each source the fixed
-// unit precedence is tokens, percent, then ratio. Invalid/zero values are
-// ignored, and percent/ratio inputs are capped below 100%/1.0.
-function positiveTokenCandidate(values = []) {
-    for (const value of values) {
-        const tokens = positiveTokenInt(value);
-        if (tokens) return tokens;
-    }
-    return null;
-}
-
-function resolveMainBufferSetting(cfg = {}) {
-    const configTokens = positiveTokenCandidate([cfg.mainBufferTokens, cfg.mainBuffer]);
-    if (configTokens) return { tokens: configTokens };
-    const configRatio = resolveBufferRatioCandidate(
-        [cfg.mainBufferPercent, cfg.mainBufferPct],
-        [cfg.mainBufferRatio, cfg.mainBufferFraction],
-    );
-    if (configRatio !== null) return { ratio: configRatio };
-
-    const envTokens = positiveTokenCandidate([process.env.MIXDOG_MAIN_COMPACT_BUFFER_TOKENS]);
-    if (envTokens) return { tokens: envTokens };
-    const envRatio = resolveBufferRatioCandidate(
-        [process.env.MIXDOG_MAIN_COMPACT_BUFFER_PERCENT],
-        [process.env.MIXDOG_MAIN_COMPACT_BUFFER_RATIO],
-    );
-    return envRatio === null ? null : { ratio: envRatio };
-}
-
-export function resolveMainCompactBufferRatio(cfg = {}) {
-    const setting = resolveMainBufferSetting(cfg);
-    return setting?.ratio ?? DEFAULT_MAIN_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 resolveMainCompactBufferTokens(boundaryTokens, cfg = {}, opts = {}) {
-    const boundary = positiveTokenInt(boundaryTokens);
-    const setting = resolveMainBufferSetting(cfg);
-    const configured = setting?.tokens || 0;
-    if (!boundary) return configured || positiveTokenInt(opts.defaultTokens) || DEFAULT_COMPACTION_BUFFER_TOKENS;
-    return compactionBufferTokensForBoundary(boundary, {
-        explicitTokens: configured,
-        ratio: setting?.ratio ?? DEFAULT_MAIN_COMPACTION_BUFFER_RATIO,
-        maxRatio: opts.maxRatio ?? MAX_COMPACTION_BUFFER_RATIO,
-    });
-}
-
-export function resolveCompactTriggerTokens(sessionOrConfig = {}, boundaryTokens = 0) {
-    return resolveSessionCompactPolicy(sessionOrConfig, boundaryTokens).triggerTokens;
-}
-
-// Single source of truth for per-session compaction policy math. Manager
-// (compactTriggerForSession), the turn loop (resolveWorkerCompactPolicy), and
-// the /context gauge all derive their trigger/buffer from here so the numbers
-// never diverge. Rules:
-//   - a truly-explicit sub-boundary auto-compact limit always wins
-//     (trigger = limit) for every session type;
-//   - agent-owned semantic sessions otherwise keep the default early-trigger
-//     buffer (config-driven, default 10% -> compact at 90% of the boundary);
-//   - main/user recall-fasttrack sessions use their independently configurable
-//     buffer (default 25% -> compact at 75% of the effective boundary).
-// Returns the sanitized explicit limit (null when absent/legacy full-window)
-// plus triggerTokens / bufferTokens / bufferRatio for the given boundary.
-export function resolveSessionCompactPolicy(sessionOrConfig = {}, boundaryTokens = 0) {
-    const cfg = sessionOrConfig?.compaction || sessionOrConfig || {};
-    const boundary = positiveTokenInt(boundaryTokens);
-    if (!boundary) {
-        return {
-            autoCompactTokenLimit: null,
-            triggerTokens: null,
-            bufferTokens: 0,
-            bufferRatio: isAgentOwner(sessionOrConfig)
-                ? resolveCompactBufferRatio(cfg)
-                : resolveMainCompactBufferRatio(cfg),
-        };
-    }
-    const rawLimit = positiveTokenInt(sessionOrConfig?.autoCompactTokenLimit ?? cfg?.autoCompactTokenLimit);
-    const explicitLimit = rawLimit && rawLimit < boundary ? rawLimit : null;
-    let triggerTokens;
-    if (explicitLimit) {
-        triggerTokens = explicitLimit;
-    } else if (isAgentOwner(sessionOrConfig)) {
-        triggerTokens = Math.max(1, boundary - resolveCompactBufferTokens(boundary, cfg));
-    } else {
-        triggerTokens = Math.max(1, boundary - resolveMainCompactBufferTokens(boundary, cfg));
-    }
-    const bufferTokens = Math.max(0, boundary - triggerTokens);
-    const bufferRatio = bufferTokens / boundary;
-    return { autoCompactTokenLimit: explicitLimit, triggerTokens, bufferTokens, bufferRatio };
-}
-
 function stripSystemReminder(text) {
     return String(text || '')
         .replace(/^\s*<system-reminder>\s*/i, '')