pi-harness-runtime 0.10.13 → 0.10.14

package/harness/context-compact-orchestrator.js

@@ -0,0 +1,365 @@
+/**
+ * Context Compact Orchestrator — Integration Layer
+ *
+ * Connects token estimation + microcompact + full compact into the harness loop.
+ * Enhanced with proper proactive/reactive compact and circuit breaker.
+ *
+ * Architecture:
+ *   LoopRuntime.executeTask()
+ *     +-> CompactOrchestrator.invokeWithCompact()
+ *           +-> beforeInvoke():
+ *           |     1. Estimate token count with buffer awareness
+ *           |     2. Check circuit breaker status
+ *           |     3. Microcompact: prune old tool results if time-based
+ *           |     4. If over autoCompactThreshold → Full compact via forked summarization
+ *           +-> afterInvoke():
+ *                 1. Update token stats
+ *                 2. Handle reactive 413 (context too long)
+ *                 3. Generate continue prompt
+ */
+import { roughTokenCount, roughMessagesTokens, } from "../packages/token-estimation/src/index.js";
+import { ContextWindowManager, microcompactToolResults, MAX_CONSECUTIVE_COMPACT_FAILURES, } from "./context-window-manager.js";
+import { continuePromptGenerator } from "./continue-prompt.js";
+// --- Orchestrator -------------------------------------------------------------
+/**
+ * Compact Orchestrator
+ *
+ * Wraps LLM invocations with compact checks.
+ * Call invokeWithCompact() instead of calling the LLM directly.
+ *
+ * Usage:
+ *   const orchestrator = new CompactOrchestrator({ jobId: "job-1" });
+ *   const result = await orchestrator.invokeWithCompact(
+ *     { messages, model, maxOutputTokens, tools },
+ *     { onCheckpoint, onQuotaEvent, summarizeViaForkedAgent }
+ *   );
+ */
+export class CompactOrchestrator {
+    provider;
+    model;
+    autoCompactThreshold;
+    blockingThreshold;
+    maxCompactAttempts;
+    microcompactTimeGapMs;
+    microcompactKeepRecent;
+    contextWindow;
+    compactAttempts = 0;
+    lastAssistantTimestamp = 0;
+    // Tool result tracking for microcompact
+    toolResultsById = new Map();
+    constructor(config) {
+        this.provider = config.provider ?? "openai";
+        this.model = config.model ?? "gpt-4";
+        this.autoCompactThreshold = config.autoCompactThreshold ?? 0.85;
+        this.blockingThreshold = config.blockingThreshold ?? 0.97;
+        this.maxCompactAttempts =
+            config.maxCompactAttempts ?? MAX_CONSECUTIVE_COMPACT_FAILURES;
+        this.microcompactTimeGapMs = config.microcompactTimeGapMs ?? 30 * 60 * 1000;
+        this.microcompactKeepRecent = config.microcompactKeepRecent ?? 2;
+        this.contextWindow = new ContextWindowManager();
+        // Set context window size if provided
+        if (config.contextWindowSize) {
+            this.contextWindow.setContextWindow(this.provider, this.model, config.contextWindowSize);
+        }
+    }
+    /**
+     * Main entry point: invoke LLM with compact checks.
+     *
+     * @param opts - InvokeWithCompactOptions (messages array is modified in-place on compact)
+     * @param callbacks - CompactOrchestratorCallbacks (for side-effects)
+     */
+    async invokeWithCompact(opts, callbacks) {
+        const { messages, model, maxOutputTokens } = opts;
+        this.compactAttempts++;
+        // -- Estimate tokens with buffer awareness -----------------------------
+        const estimate = this.contextWindow.estimateTokensWithBuffer({
+            messages,
+            tools: opts.tools,
+            systemPrompt: opts.systemPrompt,
+            provider: this.provider,
+            model: model ?? this.model,
+        });
+        // -- Circuit breaker check ---------------------------------------------
+        if (this.contextWindow.shouldCircuitBreak()) {
+            return {
+                success: false,
+                error: `Compact circuit breaker engaged after ${this.contextWindow.getConsecutiveFailures()} consecutive failures.`,
+            };
+        }
+        // -- Blocking: must compact before API call ---------------------------
+        if (this.contextWindow.shouldBlockApiCall(estimate)) {
+            callbacks.onPreCompact?.("token_threshold");
+            const compact = await this.runFullCompact(messages, model ?? this.model, maxOutputTokens, "token_threshold", callbacks);
+            if (!compact.success) {
+                return {
+                    success: false,
+                    error: `Context too large and compact failed: ${compact.error}`,
+                };
+            }
+            if (compact.result) {
+                callbacks.onPostCompact?.(compact.result);
+                callbacks.onCheckpoint?.(compact.result);
+            }
+            this.contextWindow.recordCompactSuccess();
+        }
+        // -- Time-based microcompact -----------------------------------------
+        this.tryMicrocompact(messages);
+        // -- Proactive auto-compact at 85% ----------------------------------
+        if (this.contextWindow.shouldProactiveCompact(estimate)) {
+            callbacks.onPreCompact?.("token_threshold");
+            const compact = await this.runFullCompact(messages, model ?? this.model, maxOutputTokens, "token_threshold", callbacks);
+            if (compact.success) {
+                this.contextWindow.recordCompactSuccess();
+                if (compact.result) {
+                    callbacks.onPostCompact?.(compact.result);
+                    callbacks.onCheckpoint?.(compact.result);
+                }
+            }
+        }
+        // -- Make the LLM call -----------------------------------------------
+        const invoke = opts.invokeAgent ?? callbacks.invokeAgent;
+        if (!invoke) {
+            return {
+                success: false,
+                error: "No invokeAgent provided — must pass invokeAgent in opts or callbacks",
+            };
+        }
+        const result = await invoke(opts);
+        // Track tool results
+        this.trackToolResults(messages);
+        // -- Update stats -----------------------------------------------------
+        if (result.usage) {
+            this.contextWindow.updateStats({
+                provider: this.provider,
+                model: model ?? this.model,
+                maxTokens: estimate.total + (result.usage.outputTokens ?? 0),
+                usedTokens: result.usage.inputTokens ?? estimate.total,
+            });
+        }
+        // -- Reactive compact on context-too-long error ---------------------
+        const isContextError = this.isContextTooLongError(result.error);
+        if (isContextError) {
+            const failures = this.contextWindow.recordCompactFailure();
+            if (this.contextWindow.shouldCircuitBreak()) {
+                return {
+                    success: false,
+                    error: `Context too long, compact circuit breaker engaged after ${failures} failures.`,
+                };
+            }
+            callbacks.onPreCompact?.("output_limit");
+            const compact = await this.runFullCompact(messages, model ?? this.model, maxOutputTokens, "output_limit", callbacks);
+            if (compact.success) {
+                this.contextWindow.recordCompactSuccess();
+                if (compact.result) {
+                    callbacks.onPostCompact?.(compact.result);
+                    callbacks.onCheckpoint?.(compact.result);
+                }
+                // Retry once after compact
+                const retryResult = await invoke(opts);
+                if (retryResult.success) {
+                    this.lastAssistantTimestamp = Date.now();
+                    return retryResult;
+                }
+            }
+        }
+        if (result.success) {
+            this.lastAssistantTimestamp = Date.now();
+        }
+        return result;
+    }
+    /**
+     * Run full compact: summarize old messages.
+     */
+    async runFullCompact(messages, model, maxOutputTokens, reason, callbacks) {
+        const beforeTokens = this.estimateTokens({
+            messages,
+            model,
+            maxOutputTokens,
+        });
+        // Keep last 5-10 messages; compact everything before that
+        const keepRecent = Math.min(10, Math.floor(messages.length * 0.2));
+        const recentMessages = messages.slice(-keepRecent);
+        const oldMessages = messages.slice(0, -keepRecent);
+        if (oldMessages.length === 0) {
+            return { success: false, error: "Nothing to compact" };
+        }
+        // -- Generate summary ------------------------------------------------
+        let summary = "";
+        let droppedCount = oldMessages.length;
+        if (callbacks.summarizeViaForkedAgent) {
+            try {
+                const result = await callbacks.summarizeViaForkedAgent(oldMessages, reason);
+                summary = result.summary;
+                droppedCount = result.droppedCount;
+            }
+            catch {
+                summary = this.heuristicSummary(oldMessages, reason);
+            }
+        }
+        else {
+            summary = this.heuristicSummary(oldMessages, reason);
+        }
+        // -- Build compact boundary message -----------------------------------
+        const boundaryMsg = {
+            role: "system",
+            content: continuePromptGenerator.generateBoundary({
+                summary,
+                reason,
+                messagesCompacted: droppedCount,
+            }),
+            timestamp: Date.now(),
+            metadata: {
+                compactBoundary: true,
+                reason,
+                compactedMessages: droppedCount,
+            },
+        };
+        // -- Preserve tool results from recent messages -----------------------
+        const preservedRecent = recentMessages.map((msg) => {
+            if (msg.role !== "assistant" || !msg.toolResults)
+                return msg;
+            return {
+                ...msg,
+                toolResults: this.preserveRecentToolResults(msg, this.microcompactKeepRecent),
+            };
+        });
+        // -- Rebuild message array -------------------------------------------
+        messages.length = 0;
+        messages.push(boundaryMsg, ...preservedRecent);
+        const afterTokens = this.estimateTokens({
+            messages,
+            model,
+            maxOutputTokens,
+        });
+        const result = {
+            trigger: reason,
+            beforeTokens,
+            afterTokens,
+            messagesCompacted: droppedCount,
+            summary,
+        };
+        const continueMessage = continuePromptGenerator.generateMinimal({
+            summary,
+            recentMessages: preservedRecent,
+        });
+        return { success: true, result, continueMessage };
+    }
+    /**
+     * Preserve only recent N tool results per message
+     */
+    preserveRecentToolResults(msg, keepCount) {
+        if (!msg.toolResults)
+            return undefined;
+        const sorted = [...msg.toolResults]
+            .sort((a, b) => b.timestamp - a.timestamp)
+            .slice(0, keepCount);
+        return sorted.map((tr) => ({
+            ...tr,
+            content: tr.content.substring(0, 1000),
+        }));
+    }
+    /**
+     * Heuristic summary when LLM summarization unavailable
+     */
+    heuristicSummary(messages, reason) {
+        const summaries = [];
+        // Extract key information from last 20 messages
+        for (const msg of messages.slice(-20)) {
+            if (msg.role === "user" && msg.content.length > 50) {
+                summaries.push(`- User: ${msg.content.substring(0, 200)}`);
+            }
+            if (msg.metadata?.action) {
+                summaries.push(`- Action: ${msg.metadata.action}`);
+            }
+        }
+        return [
+            `[Context compacted due to: ${reason}]`,
+            "",
+            "The conversation history was too long to fit in the context window.",
+            "Key context from earlier conversation:",
+            "",
+            summaries.join("\n") || "- Conversation was in progress",
+            "",
+            "Please continue from the recent messages provided.",
+        ].join("\n");
+    }
+    /**
+     * Microcompact: prune old tool results based on time gap.
+     * Uses the microcompactToolResults helper from context-window-manager.
+     */
+    tryMicrocompact(messages) {
+        if (Date.now() - this.lastAssistantTimestamp < this.microcompactTimeGapMs) {
+            return;
+        }
+        const freed = microcompactToolResults(messages, {
+            maxAgeMs: this.microcompactTimeGapMs,
+            keepRecent: this.microcompactKeepRecent,
+        });
+        if (freed > 0) {
+            this.lastAssistantTimestamp = Date.now();
+        }
+    }
+    /**
+     * Check if error is a context-too-long error
+     */
+    isContextTooLongError(error) {
+        if (!error)
+            return false;
+        return (/context.*(length|window).*exceed/i.test(error) ||
+            /too many (tokens|input tokens)/i.test(error) ||
+            /413/i.test(error) ||
+            /prompt is too long/i.test(error));
+    }
+    /**
+     * Estimate token count for an invoke call.
+     */
+    estimateTokens(opts) {
+        const messageTokens = roughMessagesTokens(opts.messages.map((m) => ({ role: m.role, content: m.content })));
+        const toolTokens = (opts.tools ?? []).reduce((sum, tool) => sum +
+            roughTokenCount(tool.name) +
+            roughTokenCount(tool.description ?? "") +
+            roughTokenCount(JSON.stringify(tool.input_schema ?? {})), 0);
+        return messageTokens + toolTokens;
+    }
+    /**
+     * Track tool results for microcompact decisions.
+     */
+    trackToolResults(messages) {
+        for (const msg of messages) {
+            if (msg.role !== "assistant" || !msg.toolResults)
+                continue;
+            for (const tr of msg.toolResults) {
+                this.toolResultsById.set(tr.id, {
+                    timestamp: tr.timestamp,
+                    tokens: tr.tokens,
+                });
+            }
+        }
+    }
+    /** Get current compact attempt count */
+    getCompactAttempts() {
+        return this.compactAttempts;
+    }
+    /** Get consecutive failure count */
+    getConsecutiveFailures() {
+        return this.contextWindow.getConsecutiveFailures();
+    }
+    /** Check if circuit breaker is engaged */
+    isCircuitBroken() {
+        return this.contextWindow.shouldCircuitBreak();
+    }
+    /** Reset compact state for a new task */
+    reset() {
+        this.compactAttempts = 0;
+        this.toolResultsById.clear();
+        this.contextWindow.resetCircuitBreaker();
+    }
+    /** Get utilization status for a model */
+    getUtilizationStatus(provider, model) {
+        return this.contextWindow.getUtilizationStatus(provider, model);
+    }
+    /** Generate utilization report */
+    generateUtilizationReport() {
+        return this.contextWindow.generateReport();
+    }
+}

package/harness/context-window-manager.js

@@ -0,0 +1,330 @@
+/**
+ * Context Window Manager — RFC-0010
+ *
+ * Manages context window usage across providers.
+ * Tracks utilization and suggests strategies when approaching limits.
+ *
+ * Enhanced with:
+ * - Compact thresholds (proactive at 85%, blocking at 97%)
+ * - Circuit breaker for consecutive compact failures
+ * - Buffer-aware token estimation
+ */
+import { roughTokenCount, roughMessagesTokens, } from "../packages/token-estimation/src/index.ts";
+// --- Constants ----------------------------------------------------------------
+/** Proactive compact triggers at this many tokens before limit */
+export const AUTOCOMPACT_BUFFER_TOKENS = 13_000;
+/** Warning threshold buffer */
+export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000;
+/** Blocking threshold buffer */
+export const BLOCKING_THRESHOLD_BUFFER_TOKENS = 20_000;
+/** Maximum consecutive compact failures before circuit breaker */
+export const MAX_CONSECUTIVE_COMPACT_FAILURES = 3;
+// --- Context Window Manager -------------------------------------------------
+export class ContextWindowManager {
+    stats = new Map();
+    configs = new Map();
+    consecutiveFailures = 0;
+    lastCompactTimestamp = 0;
+    modelContextWindows = new Map();
+    constructor(defaultConfigs) {
+        // Initialize with defaults
+        const defaults = {
+            minimax: {
+                warningThreshold: 0.8,
+                criticalThreshold: 0.95,
+                strategy: "truncate",
+            },
+            anthropic: {
+                warningThreshold: 0.85,
+                criticalThreshold: 0.97,
+                strategy: "truncate",
+            },
+            openai: {
+                warningThreshold: 0.8,
+                criticalThreshold: 0.95,
+                strategy: "truncate",
+            },
+            ...defaultConfigs,
+        };
+        for (const [provider, config] of Object.entries(defaults)) {
+            this.configs.set(provider, config);
+        }
+    }
+    // --- Public API -----------------------------------------------------------
+    /**
+     * Update context window stats after a request
+     */
+    updateStats(update) {
+        const { provider, model, maxTokens, usedTokens } = update;
+        const stats = {
+            provider,
+            model,
+            maxTokens,
+            usedTokens,
+            availableTokens: maxTokens - usedTokens,
+            utilizationPct: usedTokens / maxTokens,
+        };
+        this.stats.set(`${provider}:${model}`, stats);
+        return stats;
+    }
+    /**
+     * Get stats for a provider/model
+     */
+    getStats(provider, model) {
+        return this.stats.get(`${provider}:${model}`) ?? null;
+    }
+    /**
+     * Get all stats
+     */
+    getAllStats() {
+        return Array.from(this.stats.values());
+    }
+    /**
+     * Check utilization status
+     */
+    getUtilizationStatus(provider, model) {
+        const stats = this.getStats(provider, model);
+        if (!stats)
+            return "unknown";
+        const config = this.configs.get(provider);
+        if (!config)
+            return "ok";
+        const pct = stats.utilizationPct;
+        if (pct >= config.criticalThreshold)
+            return "critical";
+        if (pct >= config.warningThreshold)
+            return "warning";
+        return "ok";
+    }
+    /**
+     * Get compact thresholds for a provider
+     */
+    getCompactThresholds(provider) {
+        const config = this.configs.get(provider);
+        return {
+            autoCompactAt: 0.85,
+            warningAt: config?.warningThreshold ?? 0.8,
+            blockingAt: config?.criticalThreshold ?? 0.97,
+            maxRetries: MAX_CONSECUTIVE_COMPACT_FAILURES,
+            reservedOutputTokens: 20_000,
+        };
+    }
+    /**
+     * Get effective context window size (minus reserved output tokens)
+     */
+    getEffectiveContextWindow(provider, model) {
+        const key = `${provider}:${model}`;
+        const base = this.modelContextWindows.get(key) ?? 200_000;
+        const thresholds = this.getCompactThresholds(provider);
+        return base - thresholds.reservedOutputTokens;
+    }
+    /**
+     * Set the context window size for a model
+     */
+    setContextWindow(provider, model, maxTokens) {
+        this.modelContextWindows.set(`${provider}:${model}`, maxTokens);
+    }
+    /**
+     * Estimate remaining capacity
+     */
+    estimateRemainingRequests(provider, model, avgTokensPerRequest) {
+        const stats = this.getStats(provider, model);
+        if (!stats)
+            return null;
+        return Math.floor(stats.availableTokens / avgTokensPerRequest);
+    }
+    /**
+     * Estimate tokens with buffer awareness for compact decisions
+     */
+    estimateTokensWithBuffer(opts) {
+        const { messages, tools, systemPrompt, provider, model } = opts;
+        // Calculate message tokens
+        const messageTokens = roughMessagesTokens(messages.map((m) => ({
+            role: m.role,
+            content: m.content,
+        })));
+        // Calculate tool tokens
+        const toolTokens = (tools ?? []).reduce((sum, tool) => sum +
+            roughTokenCount(tool.name) +
+            roughTokenCount(tool.description ?? "") +
+            roughTokenCount(JSON.stringify(tool.input_schema ?? {})), 0);
+        // Calculate system prompt tokens
+        const systemTokens = systemPrompt ? roughTokenCount(systemPrompt) : 0;
+        const total = messageTokens + toolTokens + systemTokens;
+        const effectiveWindow = this.getEffectiveContextWindow(provider, model);
+        const bufferRemaining = effectiveWindow - total;
+        // Determine if we should compact or block
+        const autoCompactTokens = effectiveWindow - AUTOCOMPACT_BUFFER_TOKENS;
+        const blockingTokens = effectiveWindow - BLOCKING_THRESHOLD_BUFFER_TOKENS;
+        const shouldCompact = total >= autoCompactTokens;
+        const shouldBlock = total >= blockingTokens;
+        return {
+            total,
+            bufferRemaining,
+            utilizationPct: total / effectiveWindow,
+            atRisk: bufferRemaining < AUTOCOMPACT_BUFFER_TOKENS,
+            shouldCompact,
+            shouldBlock,
+        };
+    }
+    /**
+     * Check if we should trigger proactive compact
+     */
+    shouldProactiveCompact(estimate) {
+        return estimate.shouldCompact && !this.shouldCircuitBreak();
+    }
+    /**
+     * Check if we should block (must compact before API call)
+     */
+    shouldBlockApiCall(estimate) {
+        return estimate.shouldBlock;
+    }
+    /**
+     * Record a compact failure (for circuit breaker)
+     */
+    recordCompactFailure() {
+        this.consecutiveFailures++;
+        return this.consecutiveFailures;
+    }
+    /**
+     * Record a compact success (reset circuit breaker)
+     */
+    recordCompactSuccess() {
+        this.consecutiveFailures = 0;
+        this.lastCompactTimestamp = Date.now();
+    }
+    /**
+     * Check if circuit breaker should activate
+     */
+    shouldCircuitBreak() {
+        return this.consecutiveFailures >= MAX_CONSECUTIVE_COMPACT_FAILURES;
+    }
+    /**
+     * Get consecutive failure count
+     */
+    getConsecutiveFailures() {
+        return this.consecutiveFailures;
+    }
+    /**
+     * Reset circuit breaker
+     */
+    resetCircuitBreaker() {
+        this.consecutiveFailures = 0;
+    }
+    /**
+     * Get time since last compact (ms)
+     */
+    getTimeSinceLastCompact() {
+        return Date.now() - this.lastCompactTimestamp;
+    }
+    /**
+     * Prepare messages for a request (truncation/summarization strategy)
+     */
+    prepareMessages(messages, maxTokens, strategy = "truncate") {
+        const estimateTokens = (text) => Math.ceil(text.length / 4);
+        let totalTokens = messages.reduce((sum, m) => sum + estimateTokens(m.content), 0);
+        if (totalTokens <= maxTokens) {
+            return messages;
+        }
+        if (strategy === "truncate") {
+            // Remove oldest messages first
+            const truncated = [...messages];
+            while (totalTokens > maxTokens && truncated.length > 1) {
+                const removed = truncated.shift();
+                if (removed) {
+                    totalTokens -= estimateTokens(removed.content);
+                }
+            }
+            return truncated;
+        }
+        // summarize and split both fall back to truncate for now
+        // In a real implementation, split would return multiple message batches
+        return this.prepareMessages(messages, maxTokens, "truncate");
+    }
+    /**
+     * Set config for a provider
+     */
+    setConfig(provider, config) {
+        this.configs.set(provider, config);
+    }
+    /**
+     * Get config for a provider
+     */
+    getConfig(provider) {
+        return this.configs.get(provider);
+    }
+    /**
+     * Generate utilization report
+     */
+    generateReport() {
+        const lines = ["Context Window Utilization Report", "=".repeat(40), ""];
+        for (const [, stats] of this.stats.entries()) {
+            const config = this.configs.get(stats.provider);
+            const bar = this.renderBar(stats.utilizationPct);
+            const status = this.getUtilizationStatus(stats.provider, stats.model);
+            lines.push(`${stats.provider}/${stats.model}`);
+            lines.push(`  ${bar} ${(stats.utilizationPct * 100).toFixed(1)}%`);
+            lines.push(`  Used: ${stats.usedTokens.toLocaleString()} / ${stats.maxTokens.toLocaleString()} tokens`);
+            lines.push(`  Available: ${stats.availableTokens.toLocaleString()} tokens`);
+            lines.push(`  Status: ${status.toUpperCase()}`);
+            if (config) {
+                lines.push(`  Thresholds: warning=${(config.warningThreshold * 100).toFixed(0)}%, critical=${(config.criticalThreshold * 100).toFixed(0)}%`);
+            }
+            lines.push("");
+        }
+        // Add circuit breaker status
+        lines.push("Circuit Breaker Status", "-".repeat(20));
+        lines.push(`Consecutive failures: ${this.consecutiveFailures}`);
+        lines.push(`Circuit broken: ${this.shouldCircuitBreak() ? "YES ⚠️" : "No"}`);
+        return lines.join("\n");
+    }
+    renderBar(pct, width = 20) {
+        const filled = Math.round(pct * width);
+        const empty = width - filled;
+        return "[" + "█".repeat(filled) + "░".repeat(empty) + "]";
+    }
+}
+// --- Microcompact Helpers ---------------------------------------------------
+/**
+ * Microcompact: prune old tool results based on time gap.
+ * Returns the number of tokens freed.
+ */
+export function microcompactToolResults(messages, options = {}) {
+    const maxAgeMs = options.maxAgeMs ?? 30 * 60 * 1000; // 30 minutes
+    const keepRecent = options.keepRecent ?? 2;
+    const now = Date.now();
+    let freedTokens = 0;
+    for (const msg of messages) {
+        if (msg.role !== "assistant" || !msg.toolResults)
+            continue;
+        // Sort by timestamp, newest first
+        const sorted = [...msg.toolResults].sort((a, b) => b.timestamp - a.timestamp);
+        // Keep IDs of recent tool results
+        const keepIds = new Set(sorted.slice(0, keepRecent).map((r) => r.id));
+        // Prune old ones
+        for (const tr of msg.toolResults) {
+            if (!keepIds.has(tr.id) && now - tr.timestamp > maxAgeMs) {
+                freedTokens += tr.tokens;
+                // Truncate content but keep marker
+                tr.content = "[Old tool result cleared]";
+                tr.tokens = 0;
+            }
+        }
+    }
+    return freedTokens;
+}
+/**
+ * Parse token gap from a prompt-too-long error message.
+ * Returns the gap (excess tokens) or undefined if unparseable.
+ */
+export function parseTokenGapFromError(errorMessage) {
+    // Match patterns like: "137500 tokens > 135000 maximum"
+    const match = errorMessage.match(/prompt is too long[^0-9]*(\d+)\s*tokens?\s*>\s*(\d+)/i);
+    if (match) {
+        const actual = parseInt(match[1], 10);
+        const limit = parseInt(match[2], 10);
+        const gap = actual - limit;
+        return gap > 0 ? gap : undefined;
+    }
+    return undefined;
+}