@juspay/neurolink 10.10.1 → 10.10.3

package/dist/lib/context/summarizationEngine.js

@@ -4,9 +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";
@@ -121,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.
@@ -136,15 +139,24 @@ 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;
             }
             recentTokens += msgTokens;
         }
-        // Ensure at least one message is summarized
-        return Math.max(1, splitIndex);
+        // Ensure at least one message is summarized, then snap off any tool batch
+        // the boundary would otherwise cut in half (which would leave the recent
+        // window opening on an orphaned tool_result).
+        const snapped = snapSplitToBatchBoundary(messages, Math.max(1, splitIndex));
+        // A forward snap can consume the ENTIRE array when the batch starts at
+        // index 0. Summarizing everything would leave no recent window at all and
+        // move the pointer to the last message, so the next read returns a summary
+        // and nothing else. Decline instead — `summarizeSession` skips a round on
+        // an empty slice. `structuredSummarizer` already guards this case; this is
+        // the same guard for the pointer-based path.
+        return snapped >= messages.length ? 0 : snapped;
     }
 }
 //# sourceMappingURL=summarizationEngine.js.map

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

@@ -1,14 +1,43 @@
 /**
  * Tool Use/Result Pair Repair
  *
- * After compaction, validates that every tool_use (tool_call) has a
- * corresponding tool_result and vice versa. Inserts synthetic
- * placeholders for orphaned entries.
+ * After compaction (or a pointer-based history slice) the message array can
+ * contain a `tool_call` whose `tool_result` was dropped, or a `tool_result`
+ * whose `tool_call` was dropped. Providers reject both, so orphans are filled
+ * with synthetic placeholders.
+ *
+ * Pairing is BATCH- and ID-aware, not adjacency-based. A single agent step
+ * with parallel tool calls is persisted as every `tool_call` followed by every
+ * `tool_result` (see flushPendingToolData), so `tool_call` is routinely
+ * followed by another `tool_call` in perfectly healthy history. Matching on
+ * adjacency treats that as an orphan and injects a bogus "result unavailable"
+ * over a result that is present a few entries later.
+ *
+ * Two modes, chosen per batch:
+ *   - ID mode      — `toolCallId` present: pair by id, order-independent.
+ *   - legacy mode  — sessions written before `toolCallId` existed: pair
+ *                    positionally WITHIN the batch (call[i] ↔ result[i]).
  */
 import type { ChatMessage, RepairResult } from "../types/index.js";
 /**
- * Repair orphaned tool_use/tool_result pairs in a message array.
+ * Move a summarize/keep split so it never falls INSIDE a tool batch.
+ *
+ * `splitIndex` means "messages[0..splitIndex) get summarized" — so the summary
+ * pointer lands on messages[splitIndex - 1]. Landing mid-batch leaves the
+ * recent window starting on an orphaned `tool_result`, which providers reject.
+ *
+ * Preferred direction is BACKWARD (summarize less, keep the whole batch in the
+ * recent window) since that never loses detail. When the batch starts at index
+ * 0 there is nothing left to summarize, so the split moves forward past the
+ * batch instead — the caller's "at least one message summarized" invariant
+ * wins over keeping the batch recent.
+ */
+export declare function snapSplitToBatchBoundary(messages: ChatMessage[], splitIndex: number): number;
+/**
+ * Repair orphaned tool_call/tool_result pairs in a message array.
  *
- * Ensures every tool_call has a following tool_result and vice versa.
+ * Guarantees on return: every `tool_call` is followed (within its batch) by
+ * exactly one `tool_result`, and no `tool_result` precedes its `tool_call`.
+ * A healthy batch — including a parallel one — is returned untouched.
  */
 export declare function repairToolPairs(messages: ChatMessage[]): RepairResult;

package/dist/lib/context/toolPairRepair.js

@@ -1,62 +1,237 @@
 /**
  * Tool Use/Result Pair Repair
  *
- * After compaction, validates that every tool_use (tool_call) has a
- * corresponding tool_result and vice versa. Inserts synthetic
- * placeholders for orphaned entries.
+ * After compaction (or a pointer-based history slice) the message array can
+ * contain a `tool_call` whose `tool_result` was dropped, or a `tool_result`
+ * whose `tool_call` was dropped. Providers reject both, so orphans are filled
+ * with synthetic placeholders.
+ *
+ * Pairing is BATCH- and ID-aware, not adjacency-based. A single agent step
+ * with parallel tool calls is persisted as every `tool_call` followed by every
+ * `tool_result` (see flushPendingToolData), so `tool_call` is routinely
+ * followed by another `tool_call` in perfectly healthy history. Matching on
+ * adjacency treats that as an orphan and injects a bogus "result unavailable"
+ * over a result that is present a few entries later.
+ *
+ * Two modes, chosen per batch:
+ *   - ID mode      — `toolCallId` present: pair by id, order-independent.
+ *   - legacy mode  — sessions written before `toolCallId` existed: pair
+ *                    positionally WITHIN the batch (call[i] ↔ result[i]).
  */
 import { randomUUID } from "crypto";
+const MISSING_RESULT_CONTENT = "[Tool result unavailable - conversation was compacted]";
 /**
- * Repair orphaned tool_use/tool_result pairs in a message array.
- *
- * Ensures every tool_call has a following tool_result and vice versa.
+ * Collect the tool batch starting at `start` (which must index a tool-role
+ * message). Consumes the maximal run of calls followed by the maximal run of
+ * results. A leading run of results with no calls (head-cut orphan) yields a
+ * batch with an empty `calls` array.
  */
-export function repairToolPairs(messages) {
-    const result = [];
+function collectBatch(messages, start) {
+    let i = start;
+    const calls = [];
+    const results = [];
+    while (i < messages.length && messages[i].role === "tool_call") {
+        calls.push(messages[i]);
+        i++;
+    }
+    while (i < messages.length && messages[i].role === "tool_result") {
+        results.push(messages[i]);
+        i++;
+    }
+    return { calls, results, endIndex: i };
+}
+/** Synthetic `tool_result` standing in for a call whose result was dropped. */
+function syntheticResult(call) {
+    return {
+        id: `repair-result-${randomUUID()}`,
+        role: "tool_result",
+        content: MISSING_RESULT_CONTENT,
+        tool: call.tool,
+        ...(call.toolCallId ? { toolCallId: call.toolCallId } : {}),
+        timestamp: call.timestamp,
+        metadata: { truncated: true },
+    };
+}
+/** Synthetic `tool_call` standing in for a result whose call was dropped. */
+function syntheticCall(result) {
+    return {
+        id: `repair-call-${randomUUID()}`,
+        role: "tool_call",
+        content: `[Tool call for ${result.tool || "unknown"} - conversation was compacted]`,
+        tool: result.tool,
+        ...(result.toolCallId ? { toolCallId: result.toolCallId } : {}),
+        timestamp: result.timestamp,
+        metadata: { truncated: true },
+    };
+}
+/**
+ * Repair one batch, emitting calls then results with every call matched to
+ * exactly one result. Returns the rebuilt run plus how many placeholders of
+ * each kind were needed.
+ */
+function repairBatch(batch) {
+    const { calls, results } = batch;
+    // ID mode requires ids on BOTH sides; a partially-migrated batch (some
+    // entries written before toolCallId existed) falls back to legacy pairing
+    // rather than treating the id-less half as universally orphaned.
+    const useIds = calls.length > 0 &&
+        results.length > 0 &&
+        calls.every((m) => !!m.toolCallId) &&
+        results.every((m) => !!m.toolCallId);
+    const outCalls = [...calls];
+    const outResults = [];
     let orphanedCallsFixed = 0;
     let orphanedResultsFixed = 0;
-    for (let i = 0; i < messages.length; i++) {
-        const msg = messages[i];
-        const nextMsg = i + 1 < messages.length ? messages[i + 1] : undefined;
-        if (msg.role === "tool_call") {
-            result.push(msg);
-            // Check if next message is the corresponding tool_result
-            if (!nextMsg || nextMsg.role !== "tool_result") {
-                // Insert synthetic tool_result
-                result.push({
-                    id: `repair-result-${randomUUID()}`,
-                    role: "tool_result",
-                    content: "[Tool result unavailable - conversation was compacted]",
-                    tool: msg.tool,
-                    timestamp: msg.timestamp,
-                    metadata: { truncated: true },
-                });
-                orphanedCallsFixed++;
+    let changed = false;
+    if (useIds) {
+        // Duplicate ids (a retry that re-emitted a result) keep the FIRST result;
+        // later duplicates are dropped so a call never gains a second result.
+        const resultById = new Map();
+        for (const result of results) {
+            const key = result.toolCallId;
+            if (!resultById.has(key)) {
+                resultById.set(key, result);
+            }
+            else {
+                changed = true;
             }
         }
-        else if (msg.role === "tool_result") {
-            // Check if previous message was the corresponding tool_call
-            const prevMsg = result.length > 0 ? result[result.length - 1] : undefined;
-            if (!prevMsg ||
-                (prevMsg.role !== "tool_call" && prevMsg.role !== "tool_result")) {
-                // Insert synthetic tool_call before this result
-                result.push({
-                    id: `repair-call-${randomUUID()}`,
-                    role: "tool_call",
-                    content: `[Tool call for ${msg.tool || "unknown"} - conversation was compacted]`,
-                    tool: msg.tool,
-                    timestamp: msg.timestamp,
-                    metadata: { truncated: true },
-                });
-                orphanedResultsFixed++;
+        for (const call of calls) {
+            const key = call.toolCallId;
+            const match = resultById.get(key);
+            if (match) {
+                outResults.push(match);
+                resultById.delete(key);
+            }
+            else {
+                outResults.push(syntheticResult(call));
+                orphanedCallsFixed++;
             }
-            result.push(msg);
         }
-        else {
+        // Results with no surviving call — the compactor cut the head of the batch.
+        for (const leftover of resultById.values()) {
+            outCalls.push(syntheticCall(leftover));
+            outResults.push(leftover);
+            orphanedResultsFixed++;
+        }
+    }
+    else {
+        // Legacy positional pairing, scoped to the batch.
+        const paired = Math.min(calls.length, results.length);
+        for (let i = 0; i < paired; i++) {
+            outResults.push(results[i]);
+        }
+        for (let i = paired; i < calls.length; i++) {
+            outResults.push(syntheticResult(calls[i]));
+            orphanedCallsFixed++;
+        }
+        for (let i = paired; i < results.length; i++) {
+            outCalls.push(syntheticCall(results[i]));
+            outResults.push(results[i]);
+            orphanedResultsFixed++;
+        }
+    }
+    return {
+        messages: [...outCalls, ...outResults],
+        orphanedCallsFixed,
+        orphanedResultsFixed,
+        changed,
+    };
+}
+/** True for the two roles that make up a tool batch. */
+function isToolRole(msg) {
+    return msg?.role === "tool_call" || msg?.role === "tool_result";
+}
+/**
+ * True when a split at `index` would cut a single batch in half.
+ *
+ * A batch is calls-then-results, so a `tool_result` FOLLOWED BY a `tool_call`
+ * is the boundary BETWEEN two batches — a legal place to split. Treating every
+ * adjacent pair of tool messages as "inside a batch" would fuse a whole
+ * `call,result,call,result,…` history into one indivisible run, and the walks
+ * below would then skip past all of it.
+ */
+function cutsBatch(messages, index) {
+    const before = messages[index - 1];
+    const after = messages[index];
+    if (!isToolRole(before) || !isToolRole(after)) {
+        return false;
+    }
+    return !(before?.role === "tool_result" && after?.role === "tool_call");
+}
+/**
+ * Move a summarize/keep split so it never falls INSIDE a tool batch.
+ *
+ * `splitIndex` means "messages[0..splitIndex) get summarized" — so the summary
+ * pointer lands on messages[splitIndex - 1]. Landing mid-batch leaves the
+ * recent window starting on an orphaned `tool_result`, which providers reject.
+ *
+ * Preferred direction is BACKWARD (summarize less, keep the whole batch in the
+ * recent window) since that never loses detail. When the batch starts at index
+ * 0 there is nothing left to summarize, so the split moves forward past the
+ * batch instead — the caller's "at least one message summarized" invariant
+ * wins over keeping the batch recent.
+ */
+export function snapSplitToBatchBoundary(messages, splitIndex) {
+    if (splitIndex <= 0 || splitIndex >= messages.length) {
+        return splitIndex;
+    }
+    if (!cutsBatch(messages, splitIndex)) {
+        return splitIndex;
+    }
+    let start = splitIndex;
+    while (start > 0 && cutsBatch(messages, start)) {
+        start--;
+    }
+    if (start > 0) {
+        return start;
+    }
+    let end = splitIndex;
+    while (end < messages.length && cutsBatch(messages, end)) {
+        end++;
+    }
+    return end;
+}
+/**
+ * Repair orphaned tool_call/tool_result pairs in a message array.
+ *
+ * Guarantees on return: every `tool_call` is followed (within its batch) by
+ * exactly one `tool_result`, and no `tool_result` precedes its `tool_call`.
+ * A healthy batch — including a parallel one — is returned untouched.
+ */
+export function repairToolPairs(messages) {
+    // Fast path: nothing tool-shaped to repair. Keeps the read-path cost at one
+    // linear scan for the overwhelmingly common text-only conversation.
+    const hasToolMessage = messages.some((msg) => msg.role === "tool_call" || msg.role === "tool_result");
+    if (!hasToolMessage) {
+        return {
+            repaired: false,
+            messages,
+            orphanedCallsFixed: 0,
+            orphanedResultsFixed: 0,
+        };
+    }
+    const result = [];
+    let orphanedCallsFixed = 0;
+    let orphanedResultsFixed = 0;
+    let changed = false;
+    let i = 0;
+    while (i < messages.length) {
+        const msg = messages[i];
+        if (msg.role !== "tool_call" && msg.role !== "tool_result") {
             result.push(msg);
+            i++;
+            continue;
         }
+        const batch = collectBatch(messages, i);
+        const repaired = repairBatch(batch);
+        result.push(...repaired.messages);
+        orphanedCallsFixed += repaired.orphanedCallsFixed;
+        orphanedResultsFixed += repaired.orphanedResultsFixed;
+        changed = changed || repaired.changed;
+        i = batch.endIndex;
     }
-    const repaired = orphanedCallsFixed > 0 || orphanedResultsFixed > 0;
+    const repaired = orphanedCallsFixed > 0 || orphanedResultsFixed > 0 || changed;
     return {
         repaired,
         messages: repaired ? result : messages,

package/dist/lib/core/redisConversationMemoryManager.js

@@ -1406,6 +1406,10 @@ User message: "${userMessage}"`;
                     role: "tool_call",
                     content: "", // Can be empty for tool calls
                     tool: toolName,
+                    // Persisted so repairToolPairs can pair by ID rather than adjacency —
+                    // a parallel batch writes all calls before any result, so position
+                    // carries no pairing information.
+                    ...(toolCallId ? { toolCallId } : {}),
                     args: (toolCall.args ||
                         toolCall.arguments ||
                         toolCall.parameters ||
@@ -1493,6 +1497,10 @@ User message: "${userMessage}"`;
                     role: "tool_result",
                     content: serializedResult, // Full output (was "")
                     tool: toolName,
+                    // Only a REAL id is persisted: the "unknown" sentinel above would
+                    // otherwise collide across every unidentifiable result and pair them
+                    // to each other. Absent id falls back to legacy positional pairing.
+                    ...(toolCallId && toolCallId !== "unknown" ? { toolCallId } : {}),
                     result,
                     metadata,
                 };

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/types/context.d.ts

@@ -412,6 +412,18 @@ export type RepairResult = {
     orphanedCallsFixed: number;
     orphanedResultsFixed: number;
 };
+/**
+ * One contiguous tool batch: the run of `tool_call` messages emitted by a
+ * single agent step, plus the run of `tool_result` messages that follows it.
+ * A step with parallel tool calls writes every call before any result, so the
+ * batch — not adjacency — is the unit that pairing and truncation operate on.
+ * `endIndex` is exclusive.
+ */
+export type RepairToolBatch = {
+    calls: ChatMessage[];
+    results: ChatMessage[];
+    endIndex: number;
+};
 /** Options for summarization prompt building. */
 export type SummarizationPromptOptions = {
     /**

package/dist/lib/types/conversation.d.ts

@@ -284,6 +284,17 @@ export type ChatMessage = {
     timestamp?: string;
     /** Tool name (optional) - for tool_call/tool_result messages */
     tool?: string;
+    /**
+     * Provider tool-call correlation ID, carried on BOTH the `tool_call` and its
+     * matching `tool_result`. This is the only reliable way to pair the two:
+     * a step with parallel tool calls is persisted as every `tool_call` followed
+     * by every `tool_result` (see flushPendingToolData), so adjacency does
+     * NOT imply pairing and position-based matching corrupts the batch.
+     *
+     * Optional for backward compatibility — sessions written before this field
+     * existed pair positionally within a batch (see repairToolPairs legacy mode).
+     */
+    toolCallId?: string;
     /** Tool arguments (optional) - for tool_call messages */
     args?: Record<string, unknown>;
     /** Tool result metadata (optional) - for tool_result messages */

package/dist/lib/utils/conversationMemory.js

@@ -9,6 +9,7 @@ import { safeDebugSerialize, sanitizeRecord } from "./logSanitize.js";
 import { DEFAULT_FALLBACK_THRESHOLD, getConversationMemoryDefaults, MEMORY_THRESHOLD_PERCENTAGE, } from "../config/conversationMemory.js";
 import { getAvailableInputTokens } from "../constants/contextWindows.js";
 import { buildSummarizationPrompt } from "../context/prompts/summarizationPrompt.js";
+import { repairToolPairs } from "../context/toolPairRepair.js";
 import { logger } from "./logger.js";
 const memoryTracer = tracers.memory;
 /**
@@ -164,8 +165,23 @@ export async function getConversationMessages(conversationMemory, options) {
             // against any future "fabricate-on-error" regression. Telemetry
             // attributes record how many turns were dropped so polluted sessions
             // are visible in Langfuse traces.
-            const messages = rawMessages.filter((msg) => !isPollutedAssistantTurn(msg));
-            const droppedCount = rawMessages.length - messages.length;
+            const filtered = rawMessages.filter((msg) => !isPollutedAssistantTurn(msg));
+            // Pair repair on READ, not just after compaction. buildContextFromPointer
+            // slices the history at the summary pointer, and a session interrupted
+            // mid-tool-batch is stored with calls whose results never arrived —
+            // either way the provider receives an orphan and hard-rejects the turn.
+            // No-ops (single linear scan) when the slice holds no tool messages.
+            const repair = repairToolPairs(filtered);
+            const messages = repair.messages;
+            if (repair.repaired) {
+                span.setAttribute("neurolink.memory.tool_pairs_repaired", repair.orphanedCallsFixed + repair.orphanedResultsFixed);
+                logger.debug("[conversationMemoryUtils] Repaired orphaned tool pairs on read", {
+                    sessionId,
+                    orphanedCallsFixed: repair.orphanedCallsFixed,
+                    orphanedResultsFixed: repair.orphanedResultsFixed,
+                });
+            }
+            const droppedCount = rawMessages.length - filtered.length;
             if (droppedCount > 0) {
                 // Span attribute is always set so polluted sessions stay visible in
                 // Langfuse traces on every read — that's the persistent debugging

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 flushPendingToolExecutions),
+ * 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 flushPendingToolExecutions),
+ * 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.