@librechat/agents 3.1.57 → 3.1.61

package/dist/esm/messages/prune.mjs

@@ -1,6 +1,329 @@
-import { AIMessage } from '@langchain/core/messages';
-import { Providers, ContentTypes } from '../common/enum.mjs';
+import { AIMessage, ToolMessage } from '@langchain/core/messages';
+import { truncateToolResultContent, truncateToolInput, calculateMaxToolResultChars } from '../utils/truncation.mjs';
+import { resolveContextPruningSettings } from './contextPruningSettings.mjs';
+import { Providers, ContentTypes, Constants } from '../common/enum.mjs';
+import { applyContextPruning } from './contextPruning.mjs';
 
+function sumTokenCounts(tokenMap, count) {
+    let total = 0;
+    for (let i = 0; i < count; i++) {
+        total += tokenMap[i] ?? 0;
+    }
+    return total;
+}
+/** Default fraction of the token budget reserved as headroom (5 %). */
+const DEFAULT_RESERVE_RATIO = 0.05;
+/** Context pressure at which observation masking and context fading activate. */
+const PRESSURE_THRESHOLD_MASKING = 0.8;
+/** Pressure band thresholds paired with budget factors for progressive context fading. */
+const PRESSURE_BANDS = [
+    [0.99, 0.05],
+    [0.9, 0.2],
+    [0.85, 0.5],
+    [0.8, 1.0],
+];
+/** Maximum character length for masked (consumed) tool results. */
+const MASKED_RESULT_MAX_CHARS = 300;
+/** Hard cap for the originalToolContent store (~2 MB estimated from char length). */
+const ORIGINAL_CONTENT_MAX_CHARS = 2_000_000;
+/** Minimum cumulative calibration ratio — provider can't count fewer tokens
+ *  than our raw estimate (within reason). Prevents divide-by-zero edge cases. */
+const CALIBRATION_RATIO_MIN = 0.5;
+/** Maximum cumulative calibration ratio — sanity cap for the running ratio. */
+const CALIBRATION_RATIO_MAX = 5;
+function getToolCallIds(message) {
+    if (message.getType() !== 'ai') {
+        return new Set();
+    }
+    const ids = new Set();
+    const aiMessage = message;
+    for (const toolCall of aiMessage.tool_calls ?? []) {
+        if (typeof toolCall.id === 'string' && toolCall.id.length > 0) {
+            ids.add(toolCall.id);
+        }
+    }
+    if (Array.isArray(aiMessage.content)) {
+        for (const part of aiMessage.content) {
+            if (typeof part !== 'object') {
+                continue;
+            }
+            const record = part;
+            if ((record.type === 'tool_use' || record.type === 'tool_call') &&
+                typeof record.id === 'string' &&
+                record.id.length > 0) {
+                ids.add(record.id);
+            }
+        }
+    }
+    return ids;
+}
+function getToolResultId(message) {
+    if (message.getType() !== 'tool') {
+        return null;
+    }
+    const toolMessage = message;
+    if (typeof toolMessage.tool_call_id === 'string' &&
+        toolMessage.tool_call_id.length > 0) {
+        return toolMessage.tool_call_id;
+    }
+    if (typeof toolMessage.toolCallId === 'string' &&
+        toolMessage.toolCallId.length > 0) {
+        return toolMessage.toolCallId;
+    }
+    return null;
+}
+function resolveTokenCountForMessage({ message, messageIndexMap, tokenCounter, indexTokenCountMap, }) {
+    const originalIndex = messageIndexMap.get(message) ?? -1;
+    if (originalIndex > -1 && indexTokenCountMap[originalIndex] != null) {
+        return indexTokenCountMap[originalIndex];
+    }
+    return tokenCounter(message);
+}
+function repairOrphanedToolMessages({ context, allMessages, tokenCounter, indexTokenCountMap, }) {
+    const messageIndexMap = new Map();
+    for (let i = 0; i < allMessages.length; i++) {
+        messageIndexMap.set(allMessages[i], i);
+    }
+    const validToolCallIds = new Set();
+    const presentToolResultIds = new Set();
+    for (const message of context) {
+        for (const id of getToolCallIds(message)) {
+            validToolCallIds.add(id);
+        }
+        const resultId = getToolResultId(message);
+        if (resultId != null) {
+            presentToolResultIds.add(resultId);
+        }
+    }
+    let reclaimedTokens = 0;
+    let droppedOrphanCount = 0;
+    const repairedContext = [];
+    const droppedMessages = [];
+    for (const message of context) {
+        if (message.getType() === 'tool') {
+            const toolResultId = getToolResultId(message);
+            if (toolResultId == null || !validToolCallIds.has(toolResultId)) {
+                droppedOrphanCount += 1;
+                reclaimedTokens += resolveTokenCountForMessage({
+                    message,
+                    tokenCounter,
+                    messageIndexMap,
+                    indexTokenCountMap,
+                });
+                droppedMessages.push(message);
+                continue;
+            }
+            repairedContext.push(message);
+            continue;
+        }
+        if (message.getType() === 'ai' && message instanceof AIMessage) {
+            const toolCallIds = getToolCallIds(message);
+            if (toolCallIds.size > 0) {
+                let hasOrphanToolCalls = false;
+                for (const id of toolCallIds) {
+                    if (!presentToolResultIds.has(id)) {
+                        hasOrphanToolCalls = true;
+                        break;
+                    }
+                }
+                if (hasOrphanToolCalls) {
+                    const originalTokens = resolveTokenCountForMessage({
+                        message,
+                        messageIndexMap,
+                        tokenCounter,
+                        indexTokenCountMap,
+                    });
+                    const stripped = stripOrphanToolUseBlocks(message, presentToolResultIds);
+                    if (stripped != null) {
+                        const strippedTokens = tokenCounter(stripped);
+                        reclaimedTokens += originalTokens - strippedTokens;
+                        repairedContext.push(stripped);
+                    }
+                    else {
+                        droppedOrphanCount += 1;
+                        reclaimedTokens += originalTokens;
+                        droppedMessages.push(message);
+                    }
+                    continue;
+                }
+            }
+        }
+        repairedContext.push(message);
+    }
+    return {
+        context: repairedContext,
+        reclaimedTokens,
+        droppedOrphanCount,
+        droppedMessages,
+    };
+}
+/**
+ * Strips tool_use content blocks and tool_calls entries from an AI message
+ * when their corresponding ToolMessages are not in the context.
+ * Returns null if the message has no content left after stripping.
+ */
+function stripOrphanToolUseBlocks(message, presentToolResultIds) {
+    const keptToolCalls = (message.tool_calls ?? []).filter((tc) => typeof tc.id === 'string' && presentToolResultIds.has(tc.id));
+    let keptContent;
+    if (Array.isArray(message.content)) {
+        const filtered = message.content.filter((block) => {
+            if (typeof block !== 'object') {
+                return true;
+            }
+            const record = block;
+            if ((record.type === 'tool_use' || record.type === 'tool_call') &&
+                typeof record.id === 'string') {
+                return presentToolResultIds.has(record.id);
+            }
+            return true;
+        });
+        if (filtered.length === 0) {
+            return null;
+        }
+        keptContent = filtered;
+    }
+    else {
+        keptContent = message.content;
+    }
+    return new AIMessage({
+        ...message,
+        content: keptContent,
+        tool_calls: keptToolCalls.length > 0 ? keptToolCalls : undefined,
+    });
+}
+/**
+ * Lightweight structural cleanup: strips orphan tool_use blocks from AI messages
+ * and drops orphan ToolMessages whose AI counterpart is missing.
+ *
+ * Unlike `repairOrphanedToolMessages`, this does NOT track tokens — it is
+ * intended as a final safety net in Graph.ts right before model invocation
+ * to prevent Anthropic/Bedrock structural validation errors.
+ *
+ * Uses duck-typing instead of `getType()` because messages at this stage
+ * may be plain objects (from LangGraph state serialization) rather than
+ * proper BaseMessage class instances.
+ *
+ * Includes a fast-path: if every tool_call has a matching tool_result and
+ * vice-versa, the original array is returned immediately with zero allocation.
+ */
+function sanitizeOrphanToolBlocks(messages) {
+    const allToolCallIds = new Set();
+    const allToolResultIds = new Set();
+    for (const msg of messages) {
+        const msgAny = msg;
+        const toolCalls = msgAny.tool_calls;
+        if (Array.isArray(toolCalls)) {
+            for (const tc of toolCalls) {
+                if (typeof tc.id === 'string' &&
+                    tc.id.length > 0 &&
+                    !tc.id.startsWith(Constants.ANTHROPIC_SERVER_TOOL_PREFIX)) {
+                    allToolCallIds.add(tc.id);
+                }
+            }
+        }
+        if (Array.isArray(msgAny.content)) {
+            for (const block of msgAny.content) {
+                if (typeof block === 'object' &&
+                    (block.type === 'tool_use' || block.type === 'tool_call') &&
+                    typeof block.id === 'string' &&
+                    !block.id.startsWith(Constants.ANTHROPIC_SERVER_TOOL_PREFIX)) {
+                    allToolCallIds.add(block.id);
+                }
+            }
+        }
+        const toolCallId = msgAny.tool_call_id;
+        if (typeof toolCallId === 'string' && toolCallId.length > 0) {
+            allToolResultIds.add(toolCallId);
+        }
+    }
+    let hasOrphans = false;
+    for (const id of allToolCallIds) {
+        if (!allToolResultIds.has(id)) {
+            hasOrphans = true;
+            break;
+        }
+    }
+    if (!hasOrphans) {
+        for (const id of allToolResultIds) {
+            if (!allToolCallIds.has(id)) {
+                hasOrphans = true;
+                break;
+            }
+        }
+    }
+    if (!hasOrphans) {
+        return messages;
+    }
+    const result = [];
+    const strippedAiIndices = new Set();
+    for (const msg of messages) {
+        const msgAny = msg;
+        const msgType = typeof msg.getType === 'function'
+            ? msg.getType()
+            : (msgAny.role ??
+                msgAny._type);
+        const toolCallId = msgAny.tool_call_id;
+        if ((msgType === 'tool' || msg instanceof ToolMessage) &&
+            typeof toolCallId === 'string' &&
+            !allToolCallIds.has(toolCallId)) {
+            continue;
+        }
+        const toolCalls = msgAny.tool_calls;
+        if ((msgType === 'ai' ||
+            msgType === 'assistant' ||
+            msg instanceof AIMessage) &&
+            Array.isArray(toolCalls) &&
+            toolCalls.length > 0) {
+            const hasOrphanCalls = toolCalls.some((tc) => typeof tc.id === 'string' && !allToolResultIds.has(tc.id));
+            if (hasOrphanCalls) {
+                if (msg instanceof AIMessage) {
+                    const stripped = stripOrphanToolUseBlocks(msg, allToolResultIds);
+                    if (stripped != null) {
+                        strippedAiIndices.add(result.length);
+                        result.push(stripped);
+                    }
+                    continue;
+                }
+                const keptToolCalls = toolCalls.filter((tc) => typeof tc.id === 'string' && allToolResultIds.has(tc.id));
+                const keptContent = Array.isArray(msgAny.content)
+                    ? msgAny.content.filter((block) => {
+                        if (typeof block !== 'object')
+                            return true;
+                        if ((block.type === 'tool_use' || block.type === 'tool_call') &&
+                            typeof block.id === 'string') {
+                            return allToolResultIds.has(block.id);
+                        }
+                        return true;
+                    })
+                    : msgAny.content;
+                if (keptToolCalls.length === 0 &&
+                    Array.isArray(keptContent) &&
+                    keptContent.length === 0) {
+                    continue;
+                }
+                strippedAiIndices.add(result.length);
+                const patched = Object.create(Object.getPrototypeOf(msg), Object.getOwnPropertyDescriptors(msg));
+                patched.tool_calls = keptToolCalls.length > 0 ? keptToolCalls : [];
+                patched.content = keptContent;
+                result.push(patched);
+                continue;
+            }
+        }
+        result.push(msg);
+    }
+    // Bedrock/Anthropic require the conversation to end with a user message;
+    // a stripped AI message (tool_use removed) represents a dead-end exchange.
+    while (result.length > 0 && strippedAiIndices.has(result.length - 1)) {
+        result.pop();
+    }
+    return result;
+}
+/**
+ * Truncates an oversized tool_use `input` field using head+tail, preserving
+ * it as a valid JSON object. Head gets ~70%, tail gets ~30% so the model
+ * sees both the beginning (what was called) and end (closing structure/values).
+ * Falls back to head-only when the budget is too small for a meaningful tail.
+ */
 function isIndexInContext(arrayA, arrayB, targetIndex) {
     const startingIndexInA = arrayA.length - arrayB.length;
     return targetIndex >= startingIndexInA;
@@ -34,8 +357,14 @@ function calculateTotalTokens(usage) {
     const baseInputTokens = Number(usage.input_tokens) || 0;
     const cacheCreation = Number(usage.input_token_details?.cache_creation) || 0;
     const cacheRead = Number(usage.input_token_details?.cache_read) || 0;
-    const totalInputTokens = baseInputTokens + cacheCreation + cacheRead;
     const totalOutputTokens = Number(usage.output_tokens) || 0;
+    const cacheSum = cacheCreation + cacheRead;
+    // Anthropic: input_tokens excludes cache, cache_read can be much larger than input_tokens.
+    // OpenAI: input_tokens includes cache, cache_read is always <= input_tokens.
+    const cacheIsAdditive = cacheSum > 0 && cacheSum > baseInputTokens;
+    const totalInputTokens = cacheIsAdditive
+        ? baseInputTokens + cacheSum
+        : baseInputTokens;
     return {
         input_tokens: totalInputTokens,
         output_tokens: totalOutputTokens,
@@ -49,12 +378,12 @@ function calculateTotalTokens(usage) {
  * @param options Configuration options for processing messages
  * @returns Object containing the message context, remaining tokens, messages not included, and summary index
  */
-function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, indexTokenCountMap, startType: _startType, thinkingEnabled, tokenCounter, thinkingStartIndex: _thinkingStartIndex = -1, reasoningType = ContentTypes.THINKING, }) {
+function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, indexTokenCountMap, startType: _startType, thinkingEnabled, tokenCounter, thinkingStartIndex: _thinkingStartIndex = -1, reasoningType = ContentTypes.THINKING, instructionTokens: _instructionTokens = 0, }) {
     // Every reply is primed with <|start|>assistant<|message|>, so we
     // start with 3 tokens for the label after all messages have been counted.
     let currentTokenCount = 3;
     const instructions = _messages[0]?.getType() === 'system' ? _messages[0] : undefined;
-    const instructionsTokenCount = instructions != null ? (indexTokenCountMap[0] ?? 0) : 0;
+    const instructionsTokenCount = instructions != null ? (indexTokenCountMap[0] ?? 0) : _instructionTokens;
     const initialContextTokens = maxContextTokens - instructionsTokenCount;
     let remainingContextTokens = initialContextTokens;
     let startType = _startType;
@@ -152,6 +481,16 @@ function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, in
         context.push(_messages[0]);
         messages.shift();
     }
+    // The backward iteration pushed messages in reverse chronological order
+    // (newest first).  Restore correct chronological order before prepending
+    // the remaining (older) messages so that messagesToRefine is always
+    // ordered oldest → newest.  Without this, callers that rely on
+    // messagesToRefine order (e.g. the summarization node extracting the
+    // latest turn) would see tool_use/tool_result pairs in the wrong order.
+    prunedMemory.reverse();
+    if (messages.length > 0) {
+        prunedMemory.unshift(...messages);
+    }
     remainingContextTokens -= currentTokenCount;
     const result = {
         remainingContextTokens,
@@ -165,7 +504,6 @@ function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, in
         thinkingEndIndex < 0 ||
         (thinkingStartIndex > -1 &&
             isIndexInContext(_messages, context, thinkingStartIndex))) {
-        // we reverse at this step to ensure the context is in the correct order for the model, and we need to work backwards
         result.context = context.reverse();
         return result;
     }
@@ -175,9 +513,6 @@ function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, in
     if (!thinkingBlock) {
         throw new Error('The payload is malformed. There is a thinking sequence but no thinking block found.');
     }
-    // Since we have a thinking sequence, we need to find the last assistant message
-    // in the latest AI/tool sequence to add the thinking block that falls outside of the current context
-    // Latest messages are ordered first.
     let assistantIndex = -1;
     for (let i = 0; i < context.length; i++) {
         const currentMessage = context[i];
@@ -190,7 +525,10 @@ function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, in
         }
     }
     if (assistantIndex === -1) {
-        throw new Error('Context window exceeded: aggressive pruning removed all AI messages (likely due to an oversized tool response). Increase max context tokens or reduce tool output size.');
+        // No AI messages survived pruning — skip thinking block reattachment.
+        // The caller handles empty/insufficient context via overflow recovery.
+        result.context = context.reverse();
+        return result;
     }
     thinkingStartIndex = originalLength - 1 - assistantIndex;
     const thinkingTokenCount = tokenCounter(new AIMessage({ content: [thinkingBlock] }));
@@ -202,7 +540,6 @@ function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, in
         return result;
     }
     const thinkingMessage = context[assistantIndex];
-    // now we need to an additional round of pruning but making the thinking block fit
     const newThinkingMessageTokenCount = (indexTokenCountMap[thinkingStartIndex] ?? 0) + thinkingTokenCount;
     remainingContextTokens = initialContextTokens - newThinkingMessageTokenCount;
     currentTokenCount = 3;
@@ -267,13 +604,271 @@ function getMessagesWithinTokenLimit({ messages: _messages, maxContextTokens, in
 function checkValidNumber(value) {
     return typeof value === 'number' && !isNaN(value) && value > 0;
 }
+/**
+ * Observation masking: replaces consumed ToolMessage content with tight
+ * head+tail truncations that serve as informative placeholders.
+ *
+ * A ToolMessage is "consumed" when a subsequent AI message exists that is NOT
+ * purely tool calls — meaning the model has already read and acted on the
+ * result. Unconsumed results (the latest tool outputs the model hasn't
+ * responded to yet) are left intact so the model can still use them.
+ *
+ * AI messages are never masked — they contain the model's own reasoning and
+ * conclusions, which is what prevents the model from repeating work after
+ * its tool results are masked.
+ *
+ * @returns The number of tool messages that were masked.
+ */
+function maskConsumedToolResults(params) {
+    const { messages, indexTokenCountMap, tokenCounter } = params;
+    let maskedCount = 0;
+    // Pass 1 (backward): identify consumed tool message indices.
+    // A ToolMessage is "consumed" once we've seen a subsequent AI message with
+    // substantive text content (not just tool calls).
+    // Collected in forward order (oldest first) for recency weighting.
+    let seenNonToolCallAI = false;
+    const consumedIndices = [];
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        const type = msg.getType();
+        if (type === 'ai') {
+            const hasText = typeof msg.content === 'string'
+                ? msg.content.trim().length > 0
+                : Array.isArray(msg.content) &&
+                    msg.content.some((b) => typeof b === 'object' &&
+                        b.type === 'text' &&
+                        typeof b.text === 'string' &&
+                        b.text.trim().length >
+                            0);
+            if (hasText) {
+                seenNonToolCallAI = true;
+            }
+        }
+        else if (type === 'tool' && seenNonToolCallAI) {
+            consumedIndices.push(i);
+        }
+    }
+    if (consumedIndices.length === 0) {
+        return 0;
+    }
+    consumedIndices.reverse();
+    const totalBudgetChars = params.availableRawBudget != null && params.availableRawBudget > 0
+        ? params.availableRawBudget * 4
+        : 0;
+    const count = consumedIndices.length;
+    for (let c = 0; c < count; c++) {
+        const i = consumedIndices[c];
+        const message = messages[i];
+        const content = message.content;
+        if (typeof content !== 'string') {
+            continue;
+        }
+        let maxChars;
+        if (totalBudgetChars > 0) {
+            const position = count > 1 ? c / (count - 1) : 1;
+            const weight = 0.2 + 0.8 * position;
+            const totalWeight = count > 1 ? 0.6 * count : 1;
+            const share = (weight / totalWeight) * totalBudgetChars;
+            maxChars = Math.max(MASKED_RESULT_MAX_CHARS, Math.floor(share));
+        }
+        else {
+            maxChars = MASKED_RESULT_MAX_CHARS;
+        }
+        if (content.length <= maxChars) {
+            continue;
+        }
+        if (params.originalContentStore && !params.originalContentStore.has(i)) {
+            params.originalContentStore.set(i, content);
+            if (params.onContentStored) {
+                params.onContentStored(content.length);
+            }
+        }
+        const cloned = new ToolMessage({
+            content: truncateToolResultContent(content, maxChars),
+            tool_call_id: message.tool_call_id,
+            name: message.name,
+            id: message.id,
+            additional_kwargs: message.additional_kwargs,
+            response_metadata: message.response_metadata,
+        });
+        messages[i] = cloned;
+        indexTokenCountMap[i] = tokenCounter(cloned);
+        maskedCount++;
+    }
+    return maskedCount;
+}
+/**
+ * Pre-flight truncation: truncates oversized ToolMessage content before the
+ * main backward-iteration pruning runs. Unlike the ingestion guard (which caps
+ * at tool-execution time), pre-flight truncation applies per-turn based on the
+ * current context window budget (which may have shrunk due to growing conversation).
+ *
+ * After truncation, recounts tokens via tokenCounter and updates indexTokenCountMap
+ * so subsequent pruning works with accurate counts.
+ *
+ * @returns The number of tool messages that were truncated.
+ */
+function preFlightTruncateToolResults(params) {
+    const { messages, maxContextTokens, indexTokenCountMap, tokenCounter } = params;
+    const baseMaxChars = calculateMaxToolResultChars(maxContextTokens);
+    let truncatedCount = 0;
+    const toolIndices = [];
+    for (let i = 0; i < messages.length; i++) {
+        if (messages[i].getType() === 'tool') {
+            toolIndices.push(i);
+        }
+    }
+    for (let t = 0; t < toolIndices.length; t++) {
+        const i = toolIndices[t];
+        const message = messages[i];
+        const content = message.content;
+        if (typeof content !== 'string') {
+            continue;
+        }
+        const position = toolIndices.length > 1 ? t / (toolIndices.length - 1) : 1;
+        const recencyFactor = 0.2 + 0.8 * position;
+        const maxChars = Math.max(200, Math.floor(baseMaxChars * recencyFactor));
+        if (content.length <= maxChars) {
+            continue;
+        }
+        const truncated = truncateToolResultContent(content, maxChars);
+        const cloned = new ToolMessage({
+            content: truncated,
+            tool_call_id: message.tool_call_id,
+            name: message.name,
+            id: message.id,
+            additional_kwargs: message.additional_kwargs,
+            response_metadata: message.response_metadata,
+        });
+        messages[i] = cloned;
+        indexTokenCountMap[i] = tokenCounter(cloned);
+        truncatedCount++;
+    }
+    return truncatedCount;
+}
+/**
+ * Pre-flight truncation: truncates oversized `tool_use` input fields in AI messages.
+ *
+ * Tool call inputs (arguments) can be very large — e.g., code evaluation payloads from
+ * MCP tools like chrome-devtools. Since these tool calls have already been executed,
+ * the model only needs a summary of what was called, not the full arguments. Truncating
+ * them before pruning can prevent entire messages from being dropped.
+ *
+ * Uses 15% of the context window (in estimated characters, ~4 chars/token) as the
+ * per-input cap, capped at 200K chars.
+ *
+ * @returns The number of AI messages that had tool_use inputs truncated.
+ */
+function preFlightTruncateToolCallInputs(params) {
+    const { messages, maxContextTokens, indexTokenCountMap, tokenCounter } = params;
+    const maxInputChars = Math.min(Math.floor(maxContextTokens * 0.15) * 4, 200_000);
+    let truncatedCount = 0;
+    for (let i = 0; i < messages.length; i++) {
+        const message = messages[i];
+        if (message.getType() !== 'ai') {
+            continue;
+        }
+        if (!Array.isArray(message.content)) {
+            continue;
+        }
+        const originalContent = message.content;
+        const state = { changed: false };
+        const newContent = originalContent.map((block) => {
+            if (typeof block !== 'object') {
+                return block;
+            }
+            const record = block;
+            if (record.type !== 'tool_use' && record.type !== 'tool_call') {
+                return block;
+            }
+            const input = record.input;
+            if (input == null) {
+                return block;
+            }
+            const serialized = typeof input === 'string' ? input : JSON.stringify(input);
+            if (serialized.length <= maxInputChars) {
+                return block;
+            }
+            state.changed = true;
+            // Replaces original input with { _truncated, _originalChars } —
+            // safe because the tool call already executed in a prior turn.
+            return {
+                ...record,
+                input: truncateToolInput(serialized, maxInputChars),
+            };
+        });
+        if (!state.changed) {
+            continue;
+        }
+        const aiMsg = message;
+        const newToolCalls = (aiMsg.tool_calls ?? []).map((tc) => {
+            const serializedArgs = JSON.stringify(tc.args);
+            if (serializedArgs.length <= maxInputChars) {
+                return tc;
+            }
+            // Replaces original args with { _truncated, _originalChars } —
+            // safe because the tool call already executed in a prior turn.
+            return {
+                ...tc,
+                args: truncateToolInput(serializedArgs, maxInputChars),
+            };
+        });
+        messages[i] = new AIMessage({
+            ...aiMsg,
+            content: newContent,
+            tool_calls: newToolCalls.length > 0 ? newToolCalls : undefined,
+        });
+        indexTokenCountMap[i] = tokenCounter(messages[i]);
+        truncatedCount++;
+    }
+    return truncatedCount;
+}
 function createPruneMessages(factoryParams) {
     const indexTokenCountMap = { ...factoryParams.indexTokenCountMap };
     let lastTurnStartIndex = factoryParams.startIndex;
     let lastCutOffIndex = 0;
-    let totalTokens = Object.values(indexTokenCountMap).reduce((a = 0, b = 0) => a + b, 0);
+    let totalTokens = 0;
+    for (const key in indexTokenCountMap) {
+        totalTokens += indexTokenCountMap[key] ?? 0;
+    }
     let runThinkingStartIndex = -1;
+    /** Cumulative raw tiktoken tokens we've sent to the provider (messages only,
+     *  excludes instruction overhead and new outputs not yet seen by provider). */
+    let cumulativeRawSent = 0;
+    /** Cumulative provider-reported message tokens (providerInput - instructionOverhead). */
+    let cumulativeProviderReported = 0;
+    /** Stable calibration ratio = cumulativeProviderReported / cumulativeRawSent.
+     *  Converges monotonically as data accumulates. Falls back to seeded value. */
+    let calibrationRatio = factoryParams.calibrationRatio != null && factoryParams.calibrationRatio > 0
+        ? factoryParams.calibrationRatio
+        : 1;
+    /** Best observed instruction overhead from a near-zero variance turn.
+     *  Self-seeds from provider observations within the run. */
+    let bestInstructionOverhead;
+    let bestVarianceAbs = Infinity;
+    /** Local estimate at the time bestInstructionOverhead was observed.
+     *  Used to invalidate the cached overhead when instructions change
+     *  mid-run (e.g. tool discovery adds tools to the bound set). */
+    let bestInstructionEstimate;
+    /** Original (pre-masking) tool result content keyed by message index.
+     *  Allows the summarizer to see full tool outputs even after masking
+     *  has truncated them in the live message array. Cleared when the
+     *  pruner is recreated after summarization. */
+    const originalToolContent = new Map();
+    let originalToolContentSize = 0;
+    const contextPruningSettings = resolveContextPruningSettings(factoryParams.contextPruningConfig);
     return function pruneMessages(params) {
+        if (params.messages.length === 0) {
+            return {
+                context: [],
+                indexTokenCountMap,
+                messagesToRefine: [],
+                prePruneContextTokens: 0,
+                remainingContextTokens: factoryParams.maxTokens,
+                calibrationRatio,
+                resolvedInstructionOverhead: bestInstructionOverhead,
+            };
+        }
         if (factoryParams.provider === Providers.OPENAI &&
             factoryParams.thinkingEnabled === true) {
             for (let i = lastTurnStartIndex; i < params.messages.length; i++) {
@@ -310,70 +905,309 @@ function createPruneMessages(factoryParams) {
                         checkValidNumber(params.usageMetadata.input_token_details.cache_read)))) &&
             checkValidNumber(params.usageMetadata.output_tokens)) {
             currentUsage = calculateTotalTokens(params.usageMetadata);
-            totalTokens = currentUsage.total_tokens;
         }
         const newOutputs = new Set();
+        let outputTokensAssigned = false;
         for (let i = lastTurnStartIndex; i < params.messages.length; i++) {
             const message = params.messages[i];
-            if (i === lastTurnStartIndex &&
-                indexTokenCountMap[i] === undefined &&
-                currentUsage) {
+            if (indexTokenCountMap[i] !== undefined) {
+                continue;
+            }
+            // Assign output_tokens to the first uncounted AI message — this is the
+            // model's response.  Previous code blindly targeted lastTurnStartIndex
+            // which could hit a pre-counted HumanMessage or miss the AI entirely.
+            if (!outputTokensAssigned && currentUsage && message.getType() === 'ai') {
                 indexTokenCountMap[i] = currentUsage.output_tokens;
+                newOutputs.add(i);
+                outputTokensAssigned = true;
             }
-            else if (indexTokenCountMap[i] === undefined) {
+            else {
+                // Always store raw tiktoken count — the map stays in raw space.
+                // Budget decisions multiply by calibrationRatio on the fly.
                 indexTokenCountMap[i] = factoryParams.tokenCounter(message);
                 if (currentUsage) {
                     newOutputs.add(i);
                 }
-                totalTokens += indexTokenCountMap[i] ?? 0;
             }
+            totalTokens += indexTokenCountMap[i] ?? 0;
         }
-        // If `currentUsage` is defined, we need to distribute the current total tokens to our `indexTokenCountMap`,
-        // We must distribute it in a weighted manner, so that the total token count is equal to `currentUsage.total_tokens`,
-        // relative the manually counted tokens in `indexTokenCountMap`.
-        // EDGE CASE: when the resulting context gets pruned, we should not distribute the usage for messages that are not in the context.
-        if (currentUsage) {
-            let totalIndexTokens = 0;
-            if (params.messages[0].getType() === 'system') {
-                totalIndexTokens += indexTokenCountMap[0] ?? 0;
+        // Cumulative calibration: accumulate raw tiktoken tokens and provider-
+        // reported tokens across turns.  The ratio of the two running totals
+        // converges monotonically to the true provider multiplier — no EMA,
+        // no per-turn oscillation, no map mutation.
+        if (currentUsage && params.totalTokensFresh !== false) {
+            const instructionOverhead = factoryParams.getInstructionTokens?.() ?? 0;
+            const providerInputTokens = params.lastCallUsage?.inputTokens ?? currentUsage.input_tokens;
+            // Sum raw tiktoken counts for messages the provider saw (excludes
+            // new outputs from this turn — the provider hasn't seen them yet).
+            let rawSentThisTurn = 0;
+            const firstIsSystem = params.messages.length > 0 && params.messages[0].getType() === 'system';
+            if (firstIsSystem) {
+                rawSentThisTurn += indexTokenCountMap[0] ?? 0;
             }
             for (let i = lastCutOffIndex; i < params.messages.length; i++) {
-                if (i === 0 && params.messages[0].getType() === 'system') {
+                if ((i === 0 && firstIsSystem) || newOutputs.has(i)) {
                     continue;
                 }
-                if (newOutputs.has(i)) {
-                    continue;
-                }
-                totalIndexTokens += indexTokenCountMap[i] ?? 0;
-            }
-            // Calculate ratio based only on messages that remain in the context
-            const ratio = currentUsage.total_tokens / totalIndexTokens;
-            const isRatioSafe = ratio >= 1 / 3 && ratio <= 2.5;
-            // Apply the ratio adjustment only to messages at or after lastCutOffIndex, and only if the ratio is safe
-            if (isRatioSafe) {
-                if (params.messages[0].getType() === 'system' &&
-                    lastCutOffIndex !== 0) {
-                    indexTokenCountMap[0] = Math.round((indexTokenCountMap[0] ?? 0) * ratio);
-                }
-                for (let i = lastCutOffIndex; i < params.messages.length; i++) {
-                    if (newOutputs.has(i)) {
-                        continue;
+                rawSentThisTurn += indexTokenCountMap[i] ?? 0;
+            }
+            const providerMessageTokens = Math.max(0, providerInputTokens - instructionOverhead);
+            if (rawSentThisTurn > 0 && providerMessageTokens > 0) {
+                cumulativeRawSent += rawSentThisTurn;
+                cumulativeProviderReported += providerMessageTokens;
+                const newRatio = cumulativeProviderReported / cumulativeRawSent;
+                calibrationRatio = Math.max(CALIBRATION_RATIO_MIN, Math.min(CALIBRATION_RATIO_MAX, newRatio));
+            }
+            const calibratedOurTotal = instructionOverhead + rawSentThisTurn * calibrationRatio;
+            const overallRatio = calibratedOurTotal > 0 ? providerInputTokens / calibratedOurTotal : 0;
+            const variancePct = Math.round((overallRatio - 1) * 100);
+            const absVariance = Math.abs(overallRatio - 1);
+            if (absVariance < bestVarianceAbs && rawSentThisTurn > 0) {
+                bestVarianceAbs = absVariance;
+                bestInstructionOverhead = Math.max(0, Math.round(providerInputTokens - rawSentThisTurn * calibrationRatio));
+                bestInstructionEstimate = factoryParams.getInstructionTokens?.() ?? 0;
+            }
+            factoryParams.log?.('debug', 'Calibration observed', {
+                providerInputTokens,
+                calibratedEstimate: Math.round(calibratedOurTotal),
+                variance: `${variancePct > 0 ? '+' : ''}${variancePct}%`,
+                calibrationRatio: Math.round(calibrationRatio * 100) / 100,
+                instructionOverhead,
+                cumulativeRawSent,
+                cumulativeProviderReported,
+            });
+        }
+        // Computed BEFORE pre-flight truncation so the effective budget can drive
+        // truncation thresholds — without this, thresholds based on maxTokens are
+        // too generous and leave individual messages larger than the actual budget.
+        const estimatedInstructionTokens = factoryParams.getInstructionTokens?.() ?? 0;
+        const estimateStable = bestInstructionEstimate != null &&
+            bestInstructionEstimate > 0 &&
+            Math.abs(estimatedInstructionTokens - bestInstructionEstimate) /
+                bestInstructionEstimate <
+                0.1;
+        const currentInstructionTokens = bestInstructionOverhead != null &&
+            bestInstructionOverhead <= estimatedInstructionTokens &&
+            estimateStable
+            ? bestInstructionOverhead
+            : estimatedInstructionTokens;
+        const reserveRatio = factoryParams.reserveRatio ?? DEFAULT_RESERVE_RATIO;
+        const reserveTokens = reserveRatio > 0 && reserveRatio < 1
+            ? Math.round(factoryParams.maxTokens * reserveRatio)
+            : 0;
+        const pruningBudget = factoryParams.maxTokens - reserveTokens;
+        const effectiveMaxTokens = Math.max(0, pruningBudget - currentInstructionTokens);
+        let calibratedTotalTokens = Math.round(totalTokens * calibrationRatio);
+        factoryParams.log?.('debug', 'Budget', {
+            maxTokens: factoryParams.maxTokens,
+            pruningBudget,
+            effectiveMax: effectiveMaxTokens,
+            instructionTokens: currentInstructionTokens,
+            messageCount: params.messages.length,
+            calibratedTotalTokens,
+            calibrationRatio: Math.round(calibrationRatio * 100) / 100,
+        });
+        // When instructions alone consume the entire budget, no message can
+        // fit regardless of truncation.  Short-circuit: yield all messages for
+        // summarization and return an empty context so the Graph can route to
+        // the summarize node immediately instead of falling through to the
+        // emergency path that would reach the same outcome more expensively.
+        if (effectiveMaxTokens === 0 &&
+            factoryParams.summarizationEnabled === true &&
+            params.messages.length > 0) {
+            factoryParams.log?.('warn', 'Instructions consume entire budget — yielding all messages for summarization', {
+                instructionTokens: currentInstructionTokens,
+                pruningBudget,
+                messageCount: params.messages.length,
+            });
+            lastTurnStartIndex = params.messages.length;
+            return {
+                context: [],
+                indexTokenCountMap,
+                messagesToRefine: [...params.messages],
+                prePruneContextTokens: calibratedTotalTokens,
+                remainingContextTokens: 0,
+                contextPressure: pruningBudget > 0 ? calibratedTotalTokens / pruningBudget : 0,
+                calibrationRatio,
+                resolvedInstructionOverhead: bestInstructionOverhead,
+            };
+        }
+        // ---------------------------------------------------------------------------
+        // Progressive context fading — inspired by Claude Code's staged compaction.
+        // Below 80%: no modifications, tool results retain full size.
+        // Above 80%: graduated truncation with increasing aggression per pressure band.
+        // Recency weighting ensures older results fade first, newer results last.
+        //
+        // At the gentlest level, truncation preserves most content (head+tail).
+        // At the most aggressive level, the result is effectively a one-line placeholder.
+        //
+        //   80%: gentle — budget factor 1.0, oldest get light truncation
+        //   85%: moderate — budget factor 0.50, older results shrink significantly
+        //   90%: aggressive — budget factor 0.20, most results heavily truncated
+        //   99%: emergency — budget factor 0.05, effectively placeholders for old results
+        // ---------------------------------------------------------------------------
+        totalTokens = sumTokenCounts(indexTokenCountMap, params.messages.length);
+        calibratedTotalTokens = Math.round(totalTokens * calibrationRatio);
+        const contextPressure = pruningBudget > 0 ? calibratedTotalTokens / pruningBudget : 0;
+        let preFlightResultCount = 0;
+        let preFlightInputCount = 0;
+        // -----------------------------------------------------------------------
+        // Observation masking (80%+ pressure, both paths):
+        // Replace consumed ToolMessage content with tight head+tail placeholders.
+        // AI messages stay intact so the model can read its own prior reasoning
+        // and won't repeat work.  Unconsumed results (latest tool outputs the
+        // model hasn't acted on yet) stay full.
+        //
+        // When summarization is enabled, snapshot messages first so the
+        // summarizer can see the full originals when compaction fires.
+        // -----------------------------------------------------------------------
+        let observationsMasked = 0;
+        if (contextPressure >= PRESSURE_THRESHOLD_MASKING) {
+            const rawMessageBudget = calibrationRatio > 0
+                ? Math.floor(effectiveMaxTokens / calibrationRatio)
+                : effectiveMaxTokens;
+            // When summarization is enabled, use half the reserve ratio as extra
+            // masking headroom — the LLM keeps more context while the summarizer
+            // gets full content from originalToolContent regardless. The remaining
+            // half of the reserve covers estimation errors.
+            const reserveHeadroom = factoryParams.summarizationEnabled === true
+                ? Math.floor(rawMessageBudget *
+                    (factoryParams.reserveRatio ?? DEFAULT_RESERVE_RATIO) *
+                    0.5)
+                : 0;
+            observationsMasked = maskConsumedToolResults({
+                messages: params.messages,
+                indexTokenCountMap,
+                tokenCounter: factoryParams.tokenCounter,
+                availableRawBudget: rawMessageBudget + reserveHeadroom,
+                originalContentStore: factoryParams.summarizationEnabled === true
+                    ? originalToolContent
+                    : undefined,
+                onContentStored: factoryParams.summarizationEnabled === true
+                    ? (charLen) => {
+                        originalToolContentSize += charLen;
+                        while (originalToolContentSize > ORIGINAL_CONTENT_MAX_CHARS &&
+                            originalToolContent.size > 0) {
+                            const oldest = originalToolContent.keys().next();
+                            if (oldest.done === true) {
+                                break;
+                            }
+                            const removed = originalToolContent.get(oldest.value);
+                            if (removed != null) {
+                                originalToolContentSize -= removed.length;
+                            }
+                            originalToolContent.delete(oldest.value);
+                        }
                     }
-                    indexTokenCountMap[i] = Math.round((indexTokenCountMap[i] ?? 0) * ratio);
-                }
+                    : undefined,
+            });
+            if (observationsMasked > 0) {
+                cumulativeRawSent = 0;
+                cumulativeProviderReported = 0;
             }
         }
+        if (contextPressure >= PRESSURE_THRESHOLD_MASKING &&
+            factoryParams.summarizationEnabled !== true) {
+            const budgetFactor = PRESSURE_BANDS.find(([threshold]) => contextPressure >= threshold)?.[1] ?? 1.0;
+            const baseBudget = Math.max(1024, Math.floor(effectiveMaxTokens * budgetFactor));
+            preFlightResultCount = preFlightTruncateToolResults({
+                messages: params.messages,
+                maxContextTokens: baseBudget,
+                indexTokenCountMap,
+                tokenCounter: factoryParams.tokenCounter,
+            });
+            preFlightInputCount = preFlightTruncateToolCallInputs({
+                messages: params.messages,
+                maxContextTokens: baseBudget,
+                indexTokenCountMap,
+                tokenCounter: factoryParams.tokenCounter,
+            });
+        }
+        if (factoryParams.contextPruningConfig?.enabled === true &&
+            factoryParams.summarizationEnabled !== true) {
+            applyContextPruning({
+                messages: params.messages,
+                indexTokenCountMap,
+                tokenCounter: factoryParams.tokenCounter,
+                resolvedSettings: contextPruningSettings,
+            });
+        }
+        // Fit-to-budget: when summarization is enabled and individual messages
+        // exceed the effective budget, truncate them so every message can fit in
+        // a single context slot.  Without this, oversized tool results (e.g.
+        // take_snapshot at 9K chars) cause empty context → emergency truncation
+        // → immediate re-summarization after just one tool call.
+        //
+        // This is NOT the lossy position-based fading above — it only targets
+        // messages that individually exceed the budget, using the full effective
+        // budget as the cap (not a pressure-scaled fraction).
+        // Fit-to-budget caps are in raw space (divide by ratio) so that after
+        // calibration the truncated results actually fit within the budget.
+        const rawSpaceEffectiveMax = calibrationRatio > 0
+            ? Math.round(effectiveMaxTokens / calibrationRatio)
+            : effectiveMaxTokens;
+        if (factoryParams.summarizationEnabled === true &&
+            rawSpaceEffectiveMax > 0) {
+            preFlightResultCount = preFlightTruncateToolResults({
+                messages: params.messages,
+                maxContextTokens: rawSpaceEffectiveMax,
+                indexTokenCountMap,
+                tokenCounter: factoryParams.tokenCounter,
+            });
+            preFlightInputCount = preFlightTruncateToolCallInputs({
+                messages: params.messages,
+                maxContextTokens: rawSpaceEffectiveMax,
+                indexTokenCountMap,
+                tokenCounter: factoryParams.tokenCounter,
+            });
+        }
+        const preTruncationTotalTokens = totalTokens;
+        totalTokens = sumTokenCounts(indexTokenCountMap, params.messages.length);
+        calibratedTotalTokens = Math.round(totalTokens * calibrationRatio);
+        const anyAdjustment = observationsMasked > 0 ||
+            preFlightResultCount > 0 ||
+            preFlightInputCount > 0 ||
+            totalTokens !== preTruncationTotalTokens;
+        if (anyAdjustment) {
+            factoryParams.log?.('debug', 'Context adjusted', {
+                contextPressure: Math.round(contextPressure * 100),
+                observationsMasked,
+                toolOutputsTruncated: preFlightResultCount,
+                toolInputsTruncated: preFlightInputCount,
+                tokensBefore: preTruncationTotalTokens,
+                tokensAfter: totalTokens,
+                tokensSaved: preTruncationTotalTokens - totalTokens,
+            });
+        }
         lastTurnStartIndex = params.messages.length;
-        if (lastCutOffIndex === 0 && totalTokens <= factoryParams.maxTokens) {
-            return { context: params.messages, indexTokenCountMap };
+        if (lastCutOffIndex === 0 &&
+            calibratedTotalTokens + currentInstructionTokens <= pruningBudget) {
+            return {
+                context: params.messages,
+                indexTokenCountMap,
+                messagesToRefine: [],
+                prePruneContextTokens: calibratedTotalTokens,
+                remainingContextTokens: pruningBudget - calibratedTotalTokens - currentInstructionTokens,
+                contextPressure,
+                originalToolContent: originalToolContent.size > 0 ? originalToolContent : undefined,
+                calibrationRatio,
+                resolvedInstructionOverhead: bestInstructionOverhead,
+            };
         }
-        const { context, thinkingStartIndex } = getMessagesWithinTokenLimit({
-            maxContextTokens: factoryParams.maxTokens,
+        const rawSpaceBudget = calibrationRatio > 0
+            ? Math.round(pruningBudget / calibrationRatio)
+            : pruningBudget;
+        const rawSpaceInstructionTokens = calibrationRatio > 0
+            ? Math.round(currentInstructionTokens / calibrationRatio)
+            : currentInstructionTokens;
+        const { context: initialContext, thinkingStartIndex, messagesToRefine, remainingContextTokens: initialRemainingContextTokens, } = getMessagesWithinTokenLimit({
+            maxContextTokens: rawSpaceBudget,
             messages: params.messages,
             indexTokenCountMap,
             startType: params.startType,
             thinkingEnabled: factoryParams.thinkingEnabled,
             tokenCounter: factoryParams.tokenCounter,
+            instructionTokens: rawSpaceInstructionTokens,
             reasoningType: factoryParams.provider === Providers.BEDROCK
                 ? ContentTypes.REASONING_CONTENT
                 : ContentTypes.THINKING,
@@ -381,13 +1215,285 @@ function createPruneMessages(factoryParams) {
                 ? runThinkingStartIndex
                 : undefined,
         });
+        const { context: repairedContext, reclaimedTokens: initialReclaimedTokens, droppedMessages, } = repairOrphanedToolMessages({
+            context: initialContext,
+            allMessages: params.messages,
+            tokenCounter: factoryParams.tokenCounter,
+            indexTokenCountMap,
+        });
+        const contextBreakdown = repairedContext.map((msg) => {
+            const type = msg.getType();
+            const name = type === 'tool' ? (msg.name ?? 'unknown') : '';
+            return name !== '' ? `${type}(${name})` : type;
+        });
+        factoryParams.log?.('debug', 'Pruning complete', {
+            contextLength: repairedContext.length,
+            contextTypes: contextBreakdown.join(', '),
+            messagesToRefineCount: messagesToRefine.length,
+            droppedOrphans: droppedMessages.length,
+            remainingTokens: initialRemainingContextTokens,
+        });
+        let context = repairedContext;
+        let reclaimedTokens = initialReclaimedTokens;
+        // Orphan repair may drop ToolMessages whose parent AI was pruned.
+        // Append them to messagesToRefine so summarization can still see the
+        // tool results (otherwise the summary says "in progress" for a tool
+        // call that already completed, causing the model to repeat it).
+        if (droppedMessages.length > 0) {
+            messagesToRefine.push(...droppedMessages);
+        }
+        // ---------------------------------------------------------------
+        // Fallback fading: when summarization skipped fading earlier and
+        // pruning still produced an empty context, apply lossy pressure-band
+        // fading and retry.  This is a last resort before emergency truncation
+        // — the summarizer already saw the full messages, so fading the
+        // surviving context for the LLM is acceptable.
+        // ---------------------------------------------------------------
+        if (context.length === 0 &&
+            params.messages.length > 0 &&
+            effectiveMaxTokens > 0 &&
+            factoryParams.summarizationEnabled === true) {
+            const fadingBudget = Math.max(1024, effectiveMaxTokens);
+            factoryParams.log?.('debug', 'Fallback fading — empty context with summarization', {
+                messageCount: params.messages.length,
+                effectiveMaxTokens,
+                fadingBudget,
+            });
+            const fadedMessages = [...params.messages];
+            const preFadingTokenCounts = {};
+            for (let i = 0; i < params.messages.length; i++) {
+                preFadingTokenCounts[i] = indexTokenCountMap[i];
+            }
+            preFlightTruncateToolResults({
+                messages: fadedMessages,
+                maxContextTokens: fadingBudget,
+                indexTokenCountMap,
+                tokenCounter: factoryParams.tokenCounter,
+            });
+            preFlightTruncateToolCallInputs({
+                messages: fadedMessages,
+                maxContextTokens: fadingBudget,
+                indexTokenCountMap,
+                tokenCounter: factoryParams.tokenCounter,
+            });
+            const fadingRetry = getMessagesWithinTokenLimit({
+                maxContextTokens: pruningBudget,
+                messages: fadedMessages,
+                indexTokenCountMap,
+                startType: params.startType,
+                thinkingEnabled: factoryParams.thinkingEnabled,
+                tokenCounter: factoryParams.tokenCounter,
+                instructionTokens: currentInstructionTokens,
+                reasoningType: factoryParams.provider === Providers.BEDROCK
+                    ? ContentTypes.REASONING_CONTENT
+                    : ContentTypes.THINKING,
+                thinkingStartIndex: factoryParams.thinkingEnabled === true
+                    ? runThinkingStartIndex
+                    : undefined,
+            });
+            const fadingRepaired = repairOrphanedToolMessages({
+                context: fadingRetry.context,
+                allMessages: fadedMessages,
+                tokenCounter: factoryParams.tokenCounter,
+                indexTokenCountMap,
+            });
+            if (fadingRepaired.context.length > 0) {
+                context = fadingRepaired.context;
+                reclaimedTokens = fadingRepaired.reclaimedTokens;
+                messagesToRefine.push(...fadingRetry.messagesToRefine);
+                if (fadingRepaired.droppedMessages.length > 0) {
+                    messagesToRefine.push(...fadingRepaired.droppedMessages);
+                }
+                factoryParams.log?.('debug', 'Fallback fading recovered context', {
+                    contextLength: context.length,
+                    messagesToRefineCount: messagesToRefine.length,
+                    remainingTokens: fadingRetry.remainingContextTokens,
+                });
+                for (const [key, value] of Object.entries(preFadingTokenCounts)) {
+                    indexTokenCountMap[key] = value;
+                }
+            }
+            else {
+                for (const [key, value] of Object.entries(preFadingTokenCounts)) {
+                    indexTokenCountMap[key] = value;
+                }
+            }
+        }
+        // ---------------------------------------------------------------
+        // Emergency truncation: if pruning produced an empty context but
+        // messages exist, aggressively truncate all tool_call inputs and
+        // tool results, then retry.  Budget is proportional to the
+        // effective token limit (~4 chars/token, spread across messages)
+        // with a floor of 200 chars so content is never completely blank.
+        // Uses head+tail so the model sees both what was called and the
+        // final outcome (e.g., return value at the end of a script eval).
+        // ---------------------------------------------------------------
+        if (context.length === 0 &&
+            params.messages.length > 0 &&
+            effectiveMaxTokens > 0) {
+            const perMessageTokenBudget = Math.floor(effectiveMaxTokens / Math.max(1, params.messages.length));
+            const emergencyMaxChars = Math.max(200, perMessageTokenBudget * 4);
+            factoryParams.log?.('warn', 'Empty context, entering emergency truncation', {
+                messageCount: params.messages.length,
+                effectiveMax: effectiveMaxTokens,
+                emergencyMaxChars,
+            });
+            // Clone the messages array so emergency truncation doesn't permanently
+            // mutate graph state.  The originals remain intact for future turns
+            // where more budget may be available.  Also snapshot indexTokenCountMap
+            // entries so the closure doesn't retain stale (too-small) counts for
+            // the original un-truncated messages on the next turn.
+            const emergencyMessages = [...params.messages];
+            const preEmergencyTokenCounts = {};
+            for (let i = 0; i < params.messages.length; i++) {
+                preEmergencyTokenCounts[i] = indexTokenCountMap[i];
+            }
+            try {
+                let emergencyTruncatedCount = 0;
+                for (let i = 0; i < emergencyMessages.length; i++) {
+                    const message = emergencyMessages[i];
+                    if (message.getType() === 'tool') {
+                        const content = message.content;
+                        if (typeof content === 'string' &&
+                            content.length > emergencyMaxChars) {
+                            const cloned = new ToolMessage({
+                                content: truncateToolResultContent(content, emergencyMaxChars),
+                                tool_call_id: message.tool_call_id,
+                                name: message.name,
+                                id: message.id,
+                                additional_kwargs: message.additional_kwargs,
+                                response_metadata: message.response_metadata,
+                            });
+                            emergencyMessages[i] = cloned;
+                            indexTokenCountMap[i] = factoryParams.tokenCounter(cloned);
+                            emergencyTruncatedCount++;
+                        }
+                    }
+                    if (message.getType() === 'ai' && Array.isArray(message.content)) {
+                        const aiMsg = message;
+                        const contentBlocks = aiMsg.content;
+                        const needsTruncation = contentBlocks.some((block) => {
+                            if (typeof block !== 'object')
+                                return false;
+                            const record = block;
+                            if ((record.type === 'tool_use' || record.type === 'tool_call') &&
+                                record.input != null) {
+                                const serialized = typeof record.input === 'string'
+                                    ? record.input
+                                    : JSON.stringify(record.input);
+                                return serialized.length > emergencyMaxChars;
+                            }
+                            return false;
+                        });
+                        if (needsTruncation) {
+                            const newContent = contentBlocks.map((block) => {
+                                if (typeof block !== 'object')
+                                    return block;
+                                const record = block;
+                                if ((record.type === 'tool_use' || record.type === 'tool_call') &&
+                                    record.input != null) {
+                                    const serialized = typeof record.input === 'string'
+                                        ? record.input
+                                        : JSON.stringify(record.input);
+                                    if (serialized.length > emergencyMaxChars) {
+                                        // Replaces original input with { _truncated, _originalChars } —
+                                        // safe because the tool call already executed in a prior turn.
+                                        return {
+                                            ...record,
+                                            input: truncateToolInput(serialized, emergencyMaxChars),
+                                        };
+                                    }
+                                }
+                                return block;
+                            });
+                            const newToolCalls = (aiMsg.tool_calls ?? []).map((tc) => {
+                                const serializedArgs = JSON.stringify(tc.args);
+                                if (serializedArgs.length > emergencyMaxChars) {
+                                    // Replaces original args with { _truncated, _originalChars } —
+                                    // safe because the tool call already executed in a prior turn.
+                                    return {
+                                        ...tc,
+                                        args: truncateToolInput(serializedArgs, emergencyMaxChars),
+                                    };
+                                }
+                                return tc;
+                            });
+                            emergencyMessages[i] = new AIMessage({
+                                ...aiMsg,
+                                content: newContent,
+                                tool_calls: newToolCalls.length > 0 ? newToolCalls : undefined,
+                            });
+                            indexTokenCountMap[i] = factoryParams.tokenCounter(emergencyMessages[i]);
+                            emergencyTruncatedCount++;
+                        }
+                    }
+                }
+                factoryParams.log?.('info', 'Emergency truncation complete');
+                factoryParams.log?.('debug', 'Emergency truncation details', {
+                    truncatedCount: emergencyTruncatedCount,
+                    emergencyMaxChars,
+                });
+                const retryResult = getMessagesWithinTokenLimit({
+                    maxContextTokens: pruningBudget,
+                    messages: emergencyMessages,
+                    indexTokenCountMap,
+                    startType: params.startType,
+                    thinkingEnabled: factoryParams.thinkingEnabled,
+                    tokenCounter: factoryParams.tokenCounter,
+                    instructionTokens: currentInstructionTokens,
+                    reasoningType: factoryParams.provider === Providers.BEDROCK
+                        ? ContentTypes.REASONING_CONTENT
+                        : ContentTypes.THINKING,
+                    thinkingStartIndex: factoryParams.thinkingEnabled === true
+                        ? runThinkingStartIndex
+                        : undefined,
+                });
+                const repaired = repairOrphanedToolMessages({
+                    context: retryResult.context,
+                    allMessages: emergencyMessages,
+                    tokenCounter: factoryParams.tokenCounter,
+                    indexTokenCountMap,
+                });
+                context = repaired.context;
+                reclaimedTokens = repaired.reclaimedTokens;
+                messagesToRefine.push(...retryResult.messagesToRefine);
+                if (repaired.droppedMessages.length > 0) {
+                    messagesToRefine.push(...repaired.droppedMessages);
+                }
+                factoryParams.log?.('debug', 'Emergency truncation retry result', {
+                    contextLength: context.length,
+                    messagesToRefineCount: messagesToRefine.length,
+                    remainingTokens: retryResult.remainingContextTokens,
+                });
+            }
+            finally {
+                // Restore the closure's indexTokenCountMap to pre-emergency values so the
+                // next turn counts old messages at their original (un-truncated) size.
+                // The emergency-truncated counts were only needed for this turn's
+                // getMessagesWithinTokenLimit retry.
+                for (const [key, value] of Object.entries(preEmergencyTokenCounts)) {
+                    indexTokenCountMap[key] = value;
+                }
+            }
+        }
+        const remainingContextTokens = Math.max(0, Math.min(pruningBudget, initialRemainingContextTokens + reclaimedTokens));
         runThinkingStartIndex = thinkingStartIndex ?? -1;
         /** The index is the first value of `context`, index relative to `params.messages` */
         lastCutOffIndex = Math.max(params.messages.length -
             (context.length - (context[0]?.getType() === 'system' ? 1 : 0)), 0);
-        return { context, indexTokenCountMap };
+        return {
+            context,
+            indexTokenCountMap,
+            messagesToRefine,
+            prePruneContextTokens: calibratedTotalTokens,
+            remainingContextTokens,
+            contextPressure,
+            originalToolContent: originalToolContent.size > 0 ? originalToolContent : undefined,
+            calibrationRatio,
+            resolvedInstructionOverhead: bestInstructionOverhead,
+        };
     };
 }
 
-export { calculateTotalTokens, checkValidNumber, createPruneMessages, getMessagesWithinTokenLimit };
+export { DEFAULT_RESERVE_RATIO, calculateTotalTokens, checkValidNumber, createPruneMessages, getMessagesWithinTokenLimit, maskConsumedToolResults, preFlightTruncateToolCallInputs, preFlightTruncateToolResults, repairOrphanedToolMessages, sanitizeOrphanToolBlocks };
 //# sourceMappingURL=prune.mjs.map