@juspay/neurolink 10.10.1 → 10.10.3

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/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/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/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/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/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "10.10.1",
+  "version": "10.10.3",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -82,6 +82,8 @@
     "test:media": "npx tsx test/continuous-test-suite-media-gen.ts",
     "test:litellm-parity": "npx tsx test/continuous-test-suite-litellm-parity.ts",
     "test:memory": "npx tsx test/continuous-test-suite-memory.ts",
+    "test:tool-pairing": "npx tsx test/continuous-test-suite-tool-pairing.ts",
+    "test:token-accounting": "npx tsx test/continuous-test-suite-token-accounting.ts",
     "test:middleware": "npx tsx test/continuous-test-suite-middleware.ts",
     "test:observability": "npx tsx test/continuous-test-suite-observability.ts",
     "test:ppt": "npx tsx test/continuous-test-suite-ppt.ts",