@juspay/neurolink 10.10.1 → 10.10.2

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

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "10.10.1",
+  "version": "10.10.2",
   "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,7 @@
     "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: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",