@juspay/neurolink 10.10.2 → 10.10.4

package/dist/context/budgetChecker.d.ts

@@ -7,6 +7,22 @@
  * This runs BEFORE every LLM call to prevent context overflow.
  */
 import type { BudgetCheckResult, BudgetCheckParams } from "../types/index.js";
+/**
+ * Tokens the CONVERSATION HISTORY may occupy, i.e. the model's available input
+ * space minus everything that rides alongside it (system prompt, current
+ * prompt, tool definitions, file attachments).
+ *
+ * This is the number the compactor must target. Passing it the undeducted
+ * `availableInputTokens` made every stage gate compare history-only tokens
+ * against the WHOLE budget, so compaction only engaged once history alone
+ * exceeded the entire window — with a large MCP tool set a request could sit
+ * far over budget while the compactor reported "nothing to do" and fell through
+ * to emergency truncation.
+ *
+ * Returns 0 when the fixed overhead already exceeds the window; callers must
+ * treat that as unrecoverable rather than compacting to an empty history.
+ */
+export declare function resolveHistoryBudget(result: BudgetCheckResult): number;
 /**
  * Check whether a request fits within the model's context budget.
  *

package/dist/context/budgetChecker.js

@@ -12,8 +12,40 @@ import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../
 import { getActiveTraceContext } from "../telemetry/traceContext.js";
 /** Default compaction threshold (80% of available input) */
 const DEFAULT_COMPACTION_THRESHOLD = 0.8;
+/**
+ * Fraction of the derived history budget actually handed to the compactor.
+ * Estimation is char-based and approximate, so the compactor aims slightly
+ * under the true ceiling rather than exactly at it.
+ */
+const HISTORY_BUDGET_SAFETY_FACTOR = 0.95;
 /** Estimated tokens per tool definition */
 const TOKENS_PER_TOOL_DEFINITION = 200;
+/**
+ * Tokens the CONVERSATION HISTORY may occupy, i.e. the model's available input
+ * space minus everything that rides alongside it (system prompt, current
+ * prompt, tool definitions, file attachments).
+ *
+ * This is the number the compactor must target. Passing it the undeducted
+ * `availableInputTokens` made every stage gate compare history-only tokens
+ * against the WHOLE budget, so compaction only engaged once history alone
+ * exceeded the entire window — with a large MCP tool set a request could sit
+ * far over budget while the compactor reported "nothing to do" and fell through
+ * to emergency truncation.
+ *
+ * Returns 0 when the fixed overhead already exceeds the window; callers must
+ * treat that as unrecoverable rather than compacting to an empty history.
+ */
+export function resolveHistoryBudget(result) {
+    const { availableInputTokens, breakdown } = result;
+    if (!breakdown) {
+        return Math.max(0, Math.floor(availableInputTokens * HISTORY_BUDGET_SAFETY_FACTOR));
+    }
+    const overhead = breakdown.systemPrompt +
+        breakdown.currentPrompt +
+        breakdown.toolDefinitions +
+        breakdown.fileAttachments;
+    return Math.max(0, Math.floor((availableInputTokens - overhead) * HISTORY_BUDGET_SAFETY_FACTOR));
+}
 /**
  * Check whether a request fits within the model's context budget.
  *

package/dist/context/stepBudgetGuard.js

@@ -46,6 +46,22 @@ const TOKENS_PER_TOOL_DEFINITION = 200;
 const MAX_CALIBRATION_RATIO = 3;
 /** Messages at the end of the conversation the guard never modifies. */
 const PROTECTED_TAIL_MESSAGES = 4;
+/**
+ * Fraction of the context window the guard reclaims DOWN TO once it fires.
+ *
+ * The high-water mark (`thresholdRatio`) decides *when* to act; this low-water
+ * mark decides *how far*. Reclaiming only back to the threshold meant the very
+ * next step — which appends an assistant turn plus its tool results — crossed
+ * it again, so the guard mutated the message prefix on every single step of a
+ * long agentic run. Each of those mutations invalidates the Anthropic
+ * `cache_control` prefix from the edit point onward (see
+ * anthropicCacheBreakpoints), turning a ~0.1x cached read into full-price
+ * input every step.
+ *
+ * One deeper reclaim every N steps saves the same tokens and leaves the prefix
+ * stable in between, which is what makes the cache worth having.
+ */
+const CONTEXT_GUARD_LOW_WATER_RATIO = 0.6;
 /** Stage-1 preview budget for an old tool output (bytes). */
 const OLD_TOOL_OUTPUT_PREVIEW_BYTES = 2_048;
 /** Stage-1 preview budget for an old tool output (lines). */
@@ -295,14 +311,22 @@ export function createStepBudgetGuard(config) {
             lastRawEstimate = rawEstimate;
             return undefined;
         }
+        // Reclaim down to the LOW-WATER mark, not merely back under the threshold.
+        // See CONTEXT_GUARD_LOW_WATER_RATIO: stopping at the threshold guaranteed
+        // the next step crossed it again, mutating the cached prefix every step.
+        const lowWaterTokens = Math.floor((availableInput * CONTEXT_GUARD_LOW_WATER_RATIO) / calibration);
         // Stage 1: shrink old tool outputs to previews.
         const stage1 = truncateOldToolOutputs([...messages]);
         let compacted = stage1.messages;
         let newEstimate = overheadTokens + estimateStepMessagesTokens(compacted, provider);
-        // Stage 2: drop oldest complete tool exchanges if still over.
+        // Stage 2: drop oldest complete tool exchanges until under the low-water
+        // mark. Stage order is deliberately unchanged — truncating first preserves
+        // a preview of each output, and since BOTH stages edit the oldest messages
+        // the cache prefix is invalidated at roughly the same point either way.
+        // Frequency, not stage order, is what governs cache retention here.
         let droppedExchanges = 0;
-        if (newEstimate > effectiveThreshold) {
-            const stage2 = dropOldestToolExchanges(compacted, effectiveThreshold, overheadTokens, provider);
+        if (newEstimate > lowWaterTokens) {
+            const stage2 = dropOldestToolExchanges(compacted, lowWaterTokens, overheadTokens, provider);
             compacted = stage2.messages;
             droppedExchanges = stage2.droppedExchanges;
             newEstimate =
@@ -317,8 +341,13 @@ export function createStepBudgetGuard(config) {
             model,
             estimatedTokens: rawEstimate,
             thresholdTokens: effectiveThreshold,
+            lowWaterTokens,
             calibration,
             afterTokens: newEstimate,
+            // Headroom reclaimed below the firing threshold. Roughly how many further
+            // steps can run before the guard mutates the prefix again — a value near
+            // zero means the cache is being invalidated every step.
+            headroomTokens: effectiveThreshold - newEstimate,
             toolOutputsTruncated: stage1.truncated,
             exchangesDropped: droppedExchanges,
         });

package/dist/context/summarizationEngine.js

@@ -4,10 +4,10 @@
  * Extracted from ConversationMemoryManager and RedisConversationMemoryManager
  * to eliminate code duplication. Both managers delegate to this engine.
  */
-import { TokenUtils } from "../constants/tokens.js";
 import { buildContextFromPointer, generateSummary, } from "../utils/conversationMemory.js";
 import { RECENT_MESSAGES_RATIO } from "../config/conversationMemory.js";
 import { snapSplitToBatchBoundary } from "./toolPairRepair.js";
+import { estimateMessageTokens, estimateMessagesTokens, } from "../utils/tokenEstimation.js";
 import { withSpan } from "../telemetry/withSpan.js";
 import { tracers } from "../telemetry/tracers.js";
 import { logger } from "../utils/logger.js";
@@ -122,9 +122,11 @@ export class SummarizationEngine {
      * @returns Estimated token count
      */
     estimateTokens(messages) {
-        return messages.reduce((total, msg) => {
-            return total + TokenUtils.estimateTokenCount(msg.content);
-        }, 0);
+        // Delegates to the shared estimator so this threshold agrees with the
+        // budget checker and the compactor. The previous content-only sum scored
+        // tool calls (whose payload lives in `args`) at zero, so a Write/Edit-heavy
+        // session never reached the summarization threshold at all.
+        return estimateMessagesTokens(messages);
     }
     /**
      * Find split index to keep recent messages within target token count.
@@ -137,7 +139,7 @@ export class SummarizationEngine {
         let recentTokens = 0;
         let splitIndex = messages.length;
         for (let i = messages.length - 1; i >= 0; i--) {
-            const msgTokens = TokenUtils.estimateTokenCount(messages[i].content);
+            const msgTokens = estimateMessageTokens(messages[i]);
             if (recentTokens + msgTokens > targetRecentTokens) {
                 splitIndex = i + 1;
                 break;

package/dist/lib/context/budgetChecker.d.ts

@@ -7,6 +7,22 @@
  * This runs BEFORE every LLM call to prevent context overflow.
  */
 import type { BudgetCheckResult, BudgetCheckParams } from "../types/index.js";
+/**
+ * Tokens the CONVERSATION HISTORY may occupy, i.e. the model's available input
+ * space minus everything that rides alongside it (system prompt, current
+ * prompt, tool definitions, file attachments).
+ *
+ * This is the number the compactor must target. Passing it the undeducted
+ * `availableInputTokens` made every stage gate compare history-only tokens
+ * against the WHOLE budget, so compaction only engaged once history alone
+ * exceeded the entire window — with a large MCP tool set a request could sit
+ * far over budget while the compactor reported "nothing to do" and fell through
+ * to emergency truncation.
+ *
+ * Returns 0 when the fixed overhead already exceeds the window; callers must
+ * treat that as unrecoverable rather than compacting to an empty history.
+ */
+export declare function resolveHistoryBudget(result: BudgetCheckResult): number;
 /**
  * Check whether a request fits within the model's context budget.
  *

package/dist/lib/context/budgetChecker.js

@@ -12,8 +12,40 @@ import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../
 import { getActiveTraceContext } from "../telemetry/traceContext.js";
 /** Default compaction threshold (80% of available input) */
 const DEFAULT_COMPACTION_THRESHOLD = 0.8;
+/**
+ * Fraction of the derived history budget actually handed to the compactor.
+ * Estimation is char-based and approximate, so the compactor aims slightly
+ * under the true ceiling rather than exactly at it.
+ */
+const HISTORY_BUDGET_SAFETY_FACTOR = 0.95;
 /** Estimated tokens per tool definition */
 const TOKENS_PER_TOOL_DEFINITION = 200;
+/**
+ * Tokens the CONVERSATION HISTORY may occupy, i.e. the model's available input
+ * space minus everything that rides alongside it (system prompt, current
+ * prompt, tool definitions, file attachments).
+ *
+ * This is the number the compactor must target. Passing it the undeducted
+ * `availableInputTokens` made every stage gate compare history-only tokens
+ * against the WHOLE budget, so compaction only engaged once history alone
+ * exceeded the entire window — with a large MCP tool set a request could sit
+ * far over budget while the compactor reported "nothing to do" and fell through
+ * to emergency truncation.
+ *
+ * Returns 0 when the fixed overhead already exceeds the window; callers must
+ * treat that as unrecoverable rather than compacting to an empty history.
+ */
+export function resolveHistoryBudget(result) {
+    const { availableInputTokens, breakdown } = result;
+    if (!breakdown) {
+        return Math.max(0, Math.floor(availableInputTokens * HISTORY_BUDGET_SAFETY_FACTOR));
+    }
+    const overhead = breakdown.systemPrompt +
+        breakdown.currentPrompt +
+        breakdown.toolDefinitions +
+        breakdown.fileAttachments;
+    return Math.max(0, Math.floor((availableInputTokens - overhead) * HISTORY_BUDGET_SAFETY_FACTOR));
+}
 /**
  * Check whether a request fits within the model's context budget.
  *

package/dist/lib/context/stepBudgetGuard.js

@@ -46,6 +46,22 @@ const TOKENS_PER_TOOL_DEFINITION = 200;
 const MAX_CALIBRATION_RATIO = 3;
 /** Messages at the end of the conversation the guard never modifies. */
 const PROTECTED_TAIL_MESSAGES = 4;
+/**
+ * Fraction of the context window the guard reclaims DOWN TO once it fires.
+ *
+ * The high-water mark (`thresholdRatio`) decides *when* to act; this low-water
+ * mark decides *how far*. Reclaiming only back to the threshold meant the very
+ * next step — which appends an assistant turn plus its tool results — crossed
+ * it again, so the guard mutated the message prefix on every single step of a
+ * long agentic run. Each of those mutations invalidates the Anthropic
+ * `cache_control` prefix from the edit point onward (see
+ * anthropicCacheBreakpoints), turning a ~0.1x cached read into full-price
+ * input every step.
+ *
+ * One deeper reclaim every N steps saves the same tokens and leaves the prefix
+ * stable in between, which is what makes the cache worth having.
+ */
+const CONTEXT_GUARD_LOW_WATER_RATIO = 0.6;
 /** Stage-1 preview budget for an old tool output (bytes). */
 const OLD_TOOL_OUTPUT_PREVIEW_BYTES = 2_048;
 /** Stage-1 preview budget for an old tool output (lines). */
@@ -295,14 +311,22 @@ export function createStepBudgetGuard(config) {
             lastRawEstimate = rawEstimate;
             return undefined;
         }
+        // Reclaim down to the LOW-WATER mark, not merely back under the threshold.
+        // See CONTEXT_GUARD_LOW_WATER_RATIO: stopping at the threshold guaranteed
+        // the next step crossed it again, mutating the cached prefix every step.
+        const lowWaterTokens = Math.floor((availableInput * CONTEXT_GUARD_LOW_WATER_RATIO) / calibration);
         // Stage 1: shrink old tool outputs to previews.
         const stage1 = truncateOldToolOutputs([...messages]);
         let compacted = stage1.messages;
         let newEstimate = overheadTokens + estimateStepMessagesTokens(compacted, provider);
-        // Stage 2: drop oldest complete tool exchanges if still over.
+        // Stage 2: drop oldest complete tool exchanges until under the low-water
+        // mark. Stage order is deliberately unchanged — truncating first preserves
+        // a preview of each output, and since BOTH stages edit the oldest messages
+        // the cache prefix is invalidated at roughly the same point either way.
+        // Frequency, not stage order, is what governs cache retention here.
         let droppedExchanges = 0;
-        if (newEstimate > effectiveThreshold) {
-            const stage2 = dropOldestToolExchanges(compacted, effectiveThreshold, overheadTokens, provider);
+        if (newEstimate > lowWaterTokens) {
+            const stage2 = dropOldestToolExchanges(compacted, lowWaterTokens, overheadTokens, provider);
             compacted = stage2.messages;
             droppedExchanges = stage2.droppedExchanges;
             newEstimate =
@@ -317,8 +341,13 @@ export function createStepBudgetGuard(config) {
             model,
             estimatedTokens: rawEstimate,
             thresholdTokens: effectiveThreshold,
+            lowWaterTokens,
             calibration,
             afterTokens: newEstimate,
+            // Headroom reclaimed below the firing threshold. Roughly how many further
+            // steps can run before the guard mutates the prefix again — a value near
+            // zero means the cache is being invalidated every step.
+            headroomTokens: effectiveThreshold - newEstimate,
             toolOutputsTruncated: stage1.truncated,
             exchangesDropped: droppedExchanges,
         });

package/dist/lib/context/summarizationEngine.js

@@ -4,10 +4,10 @@
  * Extracted from ConversationMemoryManager and RedisConversationMemoryManager
  * to eliminate code duplication. Both managers delegate to this engine.
  */
-import { TokenUtils } from "../constants/tokens.js";
 import { buildContextFromPointer, generateSummary, } from "../utils/conversationMemory.js";
 import { RECENT_MESSAGES_RATIO } from "../config/conversationMemory.js";
 import { snapSplitToBatchBoundary } from "./toolPairRepair.js";
+import { estimateMessageTokens, estimateMessagesTokens, } from "../utils/tokenEstimation.js";
 import { withSpan } from "../telemetry/withSpan.js";
 import { tracers } from "../telemetry/tracers.js";
 import { logger } from "../utils/logger.js";
@@ -122,9 +122,11 @@ export class SummarizationEngine {
      * @returns Estimated token count
      */
     estimateTokens(messages) {
-        return messages.reduce((total, msg) => {
-            return total + TokenUtils.estimateTokenCount(msg.content);
-        }, 0);
+        // Delegates to the shared estimator so this threshold agrees with the
+        // budget checker and the compactor. The previous content-only sum scored
+        // tool calls (whose payload lives in `args`) at zero, so a Write/Edit-heavy
+        // session never reached the summarization threshold at all.
+        return estimateMessagesTokens(messages);
     }
     /**
      * Find split index to keep recent messages within target token count.
@@ -137,7 +139,7 @@ export class SummarizationEngine {
         let recentTokens = 0;
         let splitIndex = messages.length;
         for (let i = messages.length - 1; i >= 0; i--) {
-            const msgTokens = TokenUtils.estimateTokenCount(messages[i].content);
+            const msgTokens = estimateMessageTokens(messages[i]);
             if (recentTokens + msgTokens > targetRecentTokens) {
                 splitIndex = i + 1;
                 break;

package/dist/lib/neurolink.js

@@ -21,7 +21,7 @@ import { EventEmitter } from "events";
 import pLimit from "p-limit";
 import { ErrorCategory, ErrorSeverity } from "./constants/enums.js";
 import { CIRCUIT_BREAKER, CIRCUIT_BREAKER_RESET_MS, MEMORY_THRESHOLDS, NANOSECOND_TO_MS_DIVISOR, PERFORMANCE_THRESHOLDS, PROVIDER_TIMEOUTS, RETRY_ATTEMPTS, RETRY_DELAYS, TOOL_TIMEOUTS, } from "./constants/index.js";
-import { checkContextBudget } from "./context/budgetChecker.js";
+import { checkContextBudget, resolveHistoryBudget, } from "./context/budgetChecker.js";
 import { ContextCompactor } from "./context/contextCompactor.js";
 import { InvalidToolInputError, NoSuchToolError, } from "./utils/generationErrors.js";
 import { emergencyContentTruncation } from "./context/emergencyTruncation.js";
@@ -4896,7 +4896,14 @@ Current user's request: ${currentInput}`;
             });
             const actualTokens = actualOverflow?.actualTokens ?? recoveryBudget.estimatedInputTokens;
             const budgetTokens = actualOverflow?.budgetTokens ?? recoveryBudget.availableInputTokens;
-            const compactionTarget = Math.floor(budgetTokens * 0.7);
+            // Target the HISTORY's share, not the whole budget: the compactor's stage
+            // gates measure messages only, so handing them the full figure lets an
+            // over-budget request through untouched. The 0.7 factor stays on top as
+            // recovery headroom — this path runs only after the provider has already
+            // rejected the request once, so aiming well under is deliberate.
+            const recoveryOverhead = (recoveryBudget.breakdown?.systemPrompt ?? 0) +
+                (recoveryBudget.breakdown?.currentPrompt ?? 0);
+            const compactionTarget = Math.max(0, Math.floor((budgetTokens - recoveryOverhead) * 0.7));
             const requiredReduction = actualTokens > 0
                 ? (actualTokens - compactionTarget) / actualTokens
                 : 0.5;
@@ -5534,13 +5541,14 @@ Current user's request: ${currentInput}`;
             availableTools,
             conversationMessages,
             availableInputTokens: budgetResult.availableInputTokens,
+            historyBudget: resolveHistoryBudget(budgetResult),
             usageRatio: budgetResult.usageRatio,
             estimatedInputTokens: budgetResult.estimatedInputTokens,
             compactionSessionId,
         });
     }
     async compactMCPConversationForBudget(context) {
-        const { options, requestId, providerName, enhancedSystemPrompt, availableTools, conversationMessages, availableInputTokens, usageRatio, estimatedInputTokens, compactionSessionId, } = context;
+        const { options, requestId, providerName, enhancedSystemPrompt, availableTools, conversationMessages, availableInputTokens, historyBudget, usageRatio, estimatedInputTokens, compactionSessionId, } = context;
         logger.info("[NeuroLink] Context budget exceeded, triggering auto-compaction", {
             usageRatio,
             estimatedTokens: estimatedInputTokens,
@@ -5552,7 +5560,21 @@ Current user's request: ${currentInput}`;
                 ?.summarizationProvider,
             summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
         });
-        const compactionResult = await compactor.compact(conversationMessages, availableInputTokens, this.conversationMemoryConfig?.conversationMemory, requestId);
+        // Fixed overhead (system + prompt + tools + files) already exceeds the
+        // window — no amount of history compaction can fit this request, and
+        // compacting to an empty history would only hide the real cause.
+        if (historyBudget <= 0) {
+            throw new ContextBudgetExceededError(`Context exceeds model budget before any history is included. ` +
+                `System prompt, current prompt and tool definitions alone require ` +
+                `more than the ${availableInputTokens}-token input budget. ` +
+                `Reduce the tool set or the prompt size.`, {
+                estimatedTokens: estimatedInputTokens,
+                availableTokens: availableInputTokens,
+                stagesUsed: [],
+                breakdown: {},
+            });
+        }
+        const compactionResult = await compactor.compact(conversationMessages, historyBudget, this.conversationMemoryConfig?.conversationMemory, requestId);
         let compactedMessages = conversationMessages;
         if (compactionResult.compacted) {
             const repairedResult = repairToolPairs(compactionResult.messages);
@@ -5966,7 +5988,7 @@ Current user's request: ${currentInput}`;
                         summarizationModel: this.conversationMemoryConfig?.conversationMemory
                             ?.summarizationModel,
                     });
-                    const compactionResult = await compactor.compact(conversationMessages, budgetCheck.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
+                    const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(budgetCheck), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
                     if (compactionResult.compacted) {
                         const repairedResult = repairToolPairs(compactionResult.messages);
                         conversationMessages = repairedResult.messages;
@@ -8201,7 +8223,7 @@ Current user's request: ${currentInput}`;
                     ?.summarizationProvider,
                 summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
             });
-            const compactionResult = await compactor.compact(conversationMessages, streamBudget.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
+            const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(streamBudget), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
             if (compactionResult.compacted) {
                 const repairedResult = repairToolPairs(compactionResult.messages);
                 conversationMessages = repairedResult.messages;

package/dist/lib/utils/tokenEstimation.d.ts

@@ -50,6 +50,18 @@ export declare function estimateTokens(text: string, provider?: string, isCode?:
 /**
  * Estimate token count for a single ChatMessage.
  * Includes message framing overhead.
+ *
+ * Counts `content` AND `args`. A `tool_call` is persisted with an EMPTY
+ * `content` and its entire payload in `args` (see flushPendingToolData),
+ * so a content-only estimate scored a 39 KB Write call at ~28 tokens against a
+ * real cost near 9,750 — the budget checker, the compaction trigger and the
+ * summarization threshold were all blind to the single largest source of
+ * context growth in an agentic session.
+ *
+ * `result` is deliberately NOT counted: `result.result` is re-hydrated FROM
+ * `content` at read time (redisConversationMemoryManager), so counting both
+ * double-bills the same bytes. Only `result.error`, which has no counterpart in
+ * `content`, is included.
  */
 export declare function estimateMessageTokens(message: ChatMessage | {
     role: string;

package/dist/lib/utils/tokenEstimation.js

@@ -33,6 +33,12 @@ export const TOKENS_PER_MESSAGE = 4;
 export const TOKENS_PER_CONVERSATION = 24;
 /** Image token estimate (flat) */
 export const IMAGE_TOKEN_ESTIMATE = 1_024;
+/**
+ * Chars charged for a value that cannot be serialized for estimation (V8 max
+ * string length). Deliberately large: such a value is enormous by definition,
+ * and under-charging it would defeat the budget check it feeds.
+ */
+const OVERSIZED_VALUE_FALLBACK_CHARS = 200_000;
 /**
  * Per-provider token multipliers.
  * Applied on top of the base GPT-style character estimate.
@@ -80,9 +86,39 @@ export function estimateTokens(text, provider, isCode) {
     const safetyBuffer = baseTokens * TOKEN_SAFETY_MARGIN_ADDITIVE;
     return Math.ceil(providerAdjusted + safetyBuffer);
 }
+/**
+ * Serialize an arbitrary value for estimation. Never throws: `JSON.stringify`
+ * raises RangeError once a value exceeds V8's max string length, and a tool
+ * argument blob is exactly the shape that gets there. A payload that large is
+ * charged at the fallback size rather than aborting the estimate (and with it
+ * the whole turn).
+ */
+function serializeForEstimate(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        return "x".repeat(OVERSIZED_VALUE_FALLBACK_CHARS);
+    }
+}
 /**
  * Estimate token count for a single ChatMessage.
  * Includes message framing overhead.
+ *
+ * Counts `content` AND `args`. A `tool_call` is persisted with an EMPTY
+ * `content` and its entire payload in `args` (see flushPendingToolData),
+ * so a content-only estimate scored a 39 KB Write call at ~28 tokens against a
+ * real cost near 9,750 — the budget checker, the compaction trigger and the
+ * summarization threshold were all blind to the single largest source of
+ * context growth in an agentic session.
+ *
+ * `result` is deliberately NOT counted: `result.result` is re-hydrated FROM
+ * `content` at read time (redisConversationMemoryManager), so counting both
+ * double-bills the same bytes. Only `result.error`, which has no counterpart in
+ * `content`, is included.
  */
 export function estimateMessageTokens(message, provider) {
     let contentStr = "";
@@ -100,8 +136,16 @@ export function estimateMessageTokens(message, provider) {
             }
         }
     }
-    const contentTokens = estimateTokens(contentStr, provider);
-    return contentTokens + TOKENS_PER_MESSAGE;
+    let total = estimateTokens(contentStr, provider) + TOKENS_PER_MESSAGE;
+    const args = message.args;
+    if (args) {
+        total += estimateTokens(serializeForEstimate(args), provider);
+    }
+    const resultError = message.result?.error;
+    if (resultError) {
+        total += estimateTokens(serializeForEstimate(resultError), provider);
+    }
+    return total;
 }
 /**
  * Estimate total token count for an array of messages.

package/dist/neurolink.js

@@ -21,7 +21,7 @@ import { EventEmitter } from "events";
 import pLimit from "p-limit";
 import { ErrorCategory, ErrorSeverity } from "./constants/enums.js";
 import { CIRCUIT_BREAKER, CIRCUIT_BREAKER_RESET_MS, MEMORY_THRESHOLDS, NANOSECOND_TO_MS_DIVISOR, PERFORMANCE_THRESHOLDS, PROVIDER_TIMEOUTS, RETRY_ATTEMPTS, RETRY_DELAYS, TOOL_TIMEOUTS, } from "./constants/index.js";
-import { checkContextBudget } from "./context/budgetChecker.js";
+import { checkContextBudget, resolveHistoryBudget, } from "./context/budgetChecker.js";
 import { ContextCompactor } from "./context/contextCompactor.js";
 import { InvalidToolInputError, NoSuchToolError, } from "./utils/generationErrors.js";
 import { emergencyContentTruncation } from "./context/emergencyTruncation.js";
@@ -4896,7 +4896,14 @@ Current user's request: ${currentInput}`;
             });
             const actualTokens = actualOverflow?.actualTokens ?? recoveryBudget.estimatedInputTokens;
             const budgetTokens = actualOverflow?.budgetTokens ?? recoveryBudget.availableInputTokens;
-            const compactionTarget = Math.floor(budgetTokens * 0.7);
+            // Target the HISTORY's share, not the whole budget: the compactor's stage
+            // gates measure messages only, so handing them the full figure lets an
+            // over-budget request through untouched. The 0.7 factor stays on top as
+            // recovery headroom — this path runs only after the provider has already
+            // rejected the request once, so aiming well under is deliberate.
+            const recoveryOverhead = (recoveryBudget.breakdown?.systemPrompt ?? 0) +
+                (recoveryBudget.breakdown?.currentPrompt ?? 0);
+            const compactionTarget = Math.max(0, Math.floor((budgetTokens - recoveryOverhead) * 0.7));
             const requiredReduction = actualTokens > 0
                 ? (actualTokens - compactionTarget) / actualTokens
                 : 0.5;
@@ -5534,13 +5541,14 @@ Current user's request: ${currentInput}`;
             availableTools,
             conversationMessages,
             availableInputTokens: budgetResult.availableInputTokens,
+            historyBudget: resolveHistoryBudget(budgetResult),
             usageRatio: budgetResult.usageRatio,
             estimatedInputTokens: budgetResult.estimatedInputTokens,
             compactionSessionId,
         });
     }
     async compactMCPConversationForBudget(context) {
-        const { options, requestId, providerName, enhancedSystemPrompt, availableTools, conversationMessages, availableInputTokens, usageRatio, estimatedInputTokens, compactionSessionId, } = context;
+        const { options, requestId, providerName, enhancedSystemPrompt, availableTools, conversationMessages, availableInputTokens, historyBudget, usageRatio, estimatedInputTokens, compactionSessionId, } = context;
         logger.info("[NeuroLink] Context budget exceeded, triggering auto-compaction", {
             usageRatio,
             estimatedTokens: estimatedInputTokens,
@@ -5552,7 +5560,21 @@ Current user's request: ${currentInput}`;
                 ?.summarizationProvider,
             summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
         });
-        const compactionResult = await compactor.compact(conversationMessages, availableInputTokens, this.conversationMemoryConfig?.conversationMemory, requestId);
+        // Fixed overhead (system + prompt + tools + files) already exceeds the
+        // window — no amount of history compaction can fit this request, and
+        // compacting to an empty history would only hide the real cause.
+        if (historyBudget <= 0) {
+            throw new ContextBudgetExceededError(`Context exceeds model budget before any history is included. ` +
+                `System prompt, current prompt and tool definitions alone require ` +
+                `more than the ${availableInputTokens}-token input budget. ` +
+                `Reduce the tool set or the prompt size.`, {
+                estimatedTokens: estimatedInputTokens,
+                availableTokens: availableInputTokens,
+                stagesUsed: [],
+                breakdown: {},
+            });
+        }
+        const compactionResult = await compactor.compact(conversationMessages, historyBudget, this.conversationMemoryConfig?.conversationMemory, requestId);
         let compactedMessages = conversationMessages;
         if (compactionResult.compacted) {
             const repairedResult = repairToolPairs(compactionResult.messages);
@@ -5966,7 +5988,7 @@ Current user's request: ${currentInput}`;
                         summarizationModel: this.conversationMemoryConfig?.conversationMemory
                             ?.summarizationModel,
                     });
-                    const compactionResult = await compactor.compact(conversationMessages, budgetCheck.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
+                    const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(budgetCheck), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
                     if (compactionResult.compacted) {
                         const repairedResult = repairToolPairs(compactionResult.messages);
                         conversationMessages = repairedResult.messages;
@@ -8201,7 +8223,7 @@ Current user's request: ${currentInput}`;
                     ?.summarizationProvider,
                 summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
             });
-            const compactionResult = await compactor.compact(conversationMessages, streamBudget.availableInputTokens, this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
+            const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(streamBudget), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId);
             if (compactionResult.compacted) {
                 const repairedResult = repairToolPairs(compactionResult.messages);
                 conversationMessages = repairedResult.messages;

package/dist/utils/tokenEstimation.d.ts

@@ -50,6 +50,18 @@ export declare function estimateTokens(text: string, provider?: string, isCode?:
 /**
  * Estimate token count for a single ChatMessage.
  * Includes message framing overhead.
+ *
+ * Counts `content` AND `args`. A `tool_call` is persisted with an EMPTY
+ * `content` and its entire payload in `args` (see flushPendingToolData),
+ * so a content-only estimate scored a 39 KB Write call at ~28 tokens against a
+ * real cost near 9,750 — the budget checker, the compaction trigger and the
+ * summarization threshold were all blind to the single largest source of
+ * context growth in an agentic session.
+ *
+ * `result` is deliberately NOT counted: `result.result` is re-hydrated FROM
+ * `content` at read time (redisConversationMemoryManager), so counting both
+ * double-bills the same bytes. Only `result.error`, which has no counterpart in
+ * `content`, is included.
  */
 export declare function estimateMessageTokens(message: ChatMessage | {
     role: string;