@juspay/neurolink 10.10.0 → 10.10.2

package/dist/lib/providers/anthropic/structuredOutput.js

@@ -0,0 +1,98 @@
+import { logger } from "../../utils/logger.js";
+import { inlineJsonSchema } from "../../utils/schemaConversion.js";
+/**
+ * Additive structured output for the native Anthropic Messages API.
+ *
+ * Anthropic has no `response_format`, so a schema has to be expressed as a
+ * tool. The provider's pre-existing `responseFormat` path does that by
+ * REPLACING the tools array with a single json tool and pinning `tool_choice`
+ * to it — correct for a schema-only call, but mutually exclusive with real
+ * tools, so agent/MCP turns that pass both silently lost the schema.
+ *
+ * The additive pattern here APPENDS a `final_result` tool to the caller's
+ * tools and leaves `tool_choice` on auto: the model keeps calling real tools
+ * for as long as it needs, then emits its answer as `final_result` arguments
+ * that already conform to the schema. This mirrors the native
+ * Claude-on-Vertex loop in `googleVertex/client.ts`, which has used the same
+ * tool name, description, and instruction wording since it shipped.
+ */
+/** Internal tool name — filtered out of every returned tool call / execution. */
+export const FINAL_RESULT_TOOL_NAME = "final_result";
+const FINAL_RESULT_TOOL_DESCRIPTION = "Return the final structured result. You MUST call this tool when you have gathered all information and are ready to provide the final answer. The arguments should contain the structured data matching the expected schema.";
+/** Appended to the system prompt whenever the final_result tool is in play. */
+export const FINAL_RESULT_INSTRUCTION = "\n\nIMPORTANT: You MUST call the 'final_result' tool to return your response in the required structured format. Do not respond with plain text - always use the final_result tool.";
+/**
+ * Build the `final_result` tool definition from a JSON Schema.
+ *
+ * `$ref`s are inlined and `$schema` dropped — Anthropic's `input_schema` must
+ * be a self-contained object schema. Schemas that are not object-rooted (a
+ * bare array/string schema) are wrapped so `input_schema.type` is always
+ * "object", which the Messages API requires.
+ */
+export function buildFinalResultTool(jsonSchema) {
+    const inlined = inlineJsonSchema({ ...jsonSchema });
+    delete inlined.$schema;
+    const properties = inlined.properties;
+    const input_schema = {
+        type: "object",
+        properties: properties ?? inlined,
+        required: Array.isArray(inlined.required) ? inlined.required : [],
+    };
+    return {
+        name: FINAL_RESULT_TOOL_NAME,
+        description: FINAL_RESULT_TOOL_DESCRIPTION,
+        input_schema,
+    };
+}
+/**
+ * Append `final_result` to an Anthropic tool list.
+ *
+ * Returns a NEW array so the caller's tool list is never mutated, and reports
+ * `applied: false` (with the list unchanged) when the pattern must not run:
+ * there are no real tools to preserve, or the caller already exposes a tool of
+ * that name — shadowing a caller's tool would break their turn.
+ */
+export function appendFinalResultTool(tools, jsonSchema) {
+    if (!tools || tools.length === 0) {
+        return { tools, applied: false };
+    }
+    if (tools.some((tool) => tool.name === FINAL_RESULT_TOOL_NAME)) {
+        logger.warn("[Anthropic] A caller tool is already named 'final_result'; skipping the additive structured-output tool");
+        return { tools, applied: false };
+    }
+    // Appended LAST so any cache_control breakpoint an upstream layer placed on
+    // the previously-last tool keeps marking the same prefix boundary.
+    return { tools: [...tools, buildFinalResultTool(jsonSchema)], applied: true };
+}
+/**
+ * Append the final_result instruction to an Anthropic `system` value.
+ *
+ * The block-array form gets a NEW trailing block rather than an edit to the
+ * existing one: rewriting a block that carries a `cache_control` marker would
+ * change the cached prefix and invalidate the prompt cache on every turn.
+ */
+export function appendFinalResultInstruction(system) {
+    if (system === undefined) {
+        return FINAL_RESULT_INSTRUCTION.trim();
+    }
+    if (typeof system === "string") {
+        return system + FINAL_RESULT_INSTRUCTION;
+    }
+    return [...system, { type: "text", text: FINAL_RESULT_INSTRUCTION.trim() }];
+}
+/**
+ * Canonical JSON text for a `final_result` payload.
+ *
+ * Accepts the raw accumulated `input_json` from a stream so a payload
+ * truncated by the token cap is still returned verbatim — the caller's
+ * coercion layer can repair it, whereas dropping it loses the whole answer.
+ */
+export function stringifyFinalResultInput(inputJson) {
+    try {
+        return JSON.stringify(JSON.parse(inputJson || "{}"));
+    }
+    catch {
+        return inputJson;
+    }
+}
+//# sourceMappingURL=structuredOutput.js.map

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

@@ -269,6 +269,11 @@ export type GenerateOptions = {
      * (see `coerceJsonToSchema`), and `disableTools: true` remains available as
      * an explicit override.
      *
+     * On the native Anthropic Messages surface (provider "anthropic", including
+     * via a proxy) tools + schema are honored through an internal `final_result`
+     * tool the model calls with the structured answer — invisible to callers: it
+     * never appears in `toolCalls` / `toolExecutions`.
+     *
      * @example
      * ```typescript
      * // ✅ Vertex + Claude: tools AND schema together are fully supported
@@ -278,6 +283,12 @@ export type GenerateOptions = {
      *   model: "claude-sonnet-4-6",
      * });
      *
+     * // ✅ Direct Anthropic + tools: schema honored via the final_result tool
+     * const result = await neurolink.generate({
+     *   schema: MySchema,
+     *   provider: "anthropic",
+     * });
+     *
      * // ✅ Gemini + tools: SDK auto-falls back to coerced text-mode JSON
      * const result = await neurolink.generate({
      *   schema: MySchema,

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/providers/anthropic/client.js

@@ -30,6 +30,7 @@ import { toAnthropicImageBlock, fileToAnthropicBlock, } from "../anthropicImageB
 import { resolveSamplingParams } from "../../models/modelRegistry.js";
 import { createChunkQueue, createDeferredAnalytics, stringifyToolInput, } from "../openaiChatCompletionsClient.js";
 import { ANTHROPIC_BETA_HEADERS } from "./constants.js";
+import { appendFinalResultInstruction, appendFinalResultTool, FINAL_RESULT_TOOL_NAME, stringifyFinalResultInput, } from "./structuredOutput.js";
 // AnthropicProviderConfig is imported from types/providers.ts
 // Re-export for backward compatibility
 // Configuration helpers - now using consolidated utility
@@ -1063,7 +1064,11 @@ export class AnthropicProvider extends BaseProvider {
             supportedUrls: {},
             doGenerate: async (options) => {
                 await refreshAuth();
-                const { system, messages } = messagesToAnthropic(options.prompt);
+                const built = messagesToAnthropic(options.prompt);
+                const messages = built.messages;
+                // `let`: the additive structured-output path below appends the
+                // final_result instruction to the system prompt.
+                let system = built.system;
                 let tools = (options.tools ?? [])
                     .filter((t) => t.type === "function")
                     .map((t) => {
@@ -1107,6 +1112,24 @@ export class AnthropicProvider extends BaseProvider {
                     ];
                     toolChoice = { type: "tool", name: jsonTool };
                 }
+                // Additive structured output: when the caller wants a schema AND real
+                // tools, the forced-json path above cannot be used (it replaces the
+                // tools array), and the AI-SDK experimental_output path is excluded
+                // for this surface by structuredOutputPolicy. GenerationHandler hands
+                // the JSON Schema down here instead, and we APPEND a `final_result`
+                // tool — tool_choice stays auto, so every real tool keeps working and
+                // the model self-selects final_result when it is ready to answer.
+                const finalResultSchema = options.providerOptions?.anthropic
+                    ?.finalResultSchema;
+                let finalResultActive = false;
+                if (!jsonTool && finalResultSchema) {
+                    const appended = appendFinalResultTool(tools, finalResultSchema);
+                    tools = appended.tools;
+                    finalResultActive = appended.applied;
+                    if (appended.applied) {
+                        system = appendFinalResultInstruction(system);
+                    }
+                }
                 // Extended thinking passthrough (providerOptions.anthropic.thinking).
                 const thinking = options.providerOptions?.anthropic?.thinking;
                 // Prompt-cache parity with the native Vertex+Claude path: upstream
@@ -1179,6 +1202,7 @@ export class AnthropicProvider extends BaseProvider {
                     timeoutController?.cleanup();
                 }
                 const content = [];
+                let finalResultText;
                 for (const block of response.content) {
                     if (block.type === "thinking") {
                         content.push({ type: "reasoning", text: block.thinking });
@@ -1198,6 +1222,12 @@ export class AnthropicProvider extends BaseProvider {
                                 text: stringifyToolInput(block.input),
                             });
                         }
+                        else if (finalResultActive &&
+                            block.name === FINAL_RESULT_TOOL_NAME) {
+                            // Internal pattern: never surfaced as a tool call. Its arguments
+                            // ARE the structured answer.
+                            finalResultText = stringifyToolInput(block.input);
+                        }
                         else {
                             content.push({
                                 type: "tool-call",
@@ -1208,12 +1238,29 @@ export class AnthropicProvider extends BaseProvider {
                         }
                     }
                 }
+                // final_result is terminal — parity with the native Claude-on-Vertex
+                // and Gemini loops, which break out of the tool loop the moment it
+                // arrives. Reasoning blocks are kept; any prose preamble and any tool
+                // calls issued alongside it are dropped so `text` is exactly the
+                // structured payload and the AI-SDK loop stops here.
+                if (finalResultText !== undefined) {
+                    const reasoning = content.filter((part) => part.type === "reasoning");
+                    content.length = 0;
+                    content.push(...reasoning, { type: "text", text: finalResultText });
+                    logger.debug("[Anthropic] Extracted structured output from final_result tool (generate)", { chars: finalResultText.length });
+                }
                 const cacheRead = response.usage.cache_read_input_tokens ?? 0;
                 const cacheWrite = response.usage.cache_creation_input_tokens ?? 0;
                 return {
                     content,
                     finishReason: {
-                        unified: mapAnthropicStopReason(response.stop_reason),
+                        // A final_result call ends the turn: the provider reports
+                        // stop_reason "tool_use", but no tool call is surfaced, so
+                        // reporting "tool-calls" would misread as a step-capped turn.
+                        // `raw` still carries the provider's verbatim stop_reason.
+                        unified: finalResultText !== undefined
+                            ? "stop"
+                            : mapAnthropicStopReason(response.stop_reason),
                         raw: response.stop_reason ?? "stop",
                     },
                     usage: {
@@ -1341,6 +1388,9 @@ export class AnthropicProvider extends BaseProvider {
         let anthropicTools;
         let payload;
         let shouldUseTools;
+        // True once the additive `final_result` tool is in the request — the
+        // streaming twin of the doGenerate path above.
+        let finalResultActive = false;
         try {
             // options.tools is pre-merged by BaseProvider.stream() with base tools
             // (MCP/built-in) + user-provided tools (RAG, etc.)
@@ -1355,6 +1405,18 @@ export class AnthropicProvider extends BaseProvider {
             // convert to the Anthropic Messages payload (system + content blocks).
             const built = await this.buildMessagesForStream(options);
             payload = messagesToAnthropic(built);
+            // Schema + tools: append final_result rather than pinning tool_choice to
+            // a json tool, so the real tools stay callable for the whole turn.
+            // Unlike generate, no plumbing is needed — this is a native loop, so the
+            // caller's Zod/JSON schema is right here on the options.
+            if (options.schema && anthropicTools && anthropicTools.length > 0) {
+                const appended = appendFinalResultTool(anthropicTools, convertZodToJsonSchema(options.schema));
+                anthropicTools = appended.tools;
+                finalResultActive = appended.applied;
+                if (appended.applied) {
+                    payload.system = appendFinalResultInstruction(payload.system);
+                }
+            }
         }
         catch (setupErr) {
             timeoutController?.cleanup();
@@ -1439,6 +1501,14 @@ export class AnthropicProvider extends BaseProvider {
             ...(totalCacheRead > 0 ? { cacheReadTokens: totalCacheRead } : {}),
             ...(totalCacheWrite > 0 ? { cacheCreationTokens: totalCacheWrite } : {}),
         });
+        // Structured-output turns are delivered as ONE chunk, not incrementally:
+        // a caller that passed a schema needs parseable JSON, and text deltas
+        // emitted before the model calls final_result would prefix the payload
+        // with prose and break every JSON.parse on the consumer side. Same
+        // contract as the native Vertex loops. Non-schema streams are untouched
+        // and stay fully incremental.
+        let bufferedText = "";
+        let finalResultText;
         const runLoop = async () => {
             const conversation = payload.messages.slice();
             for (let step = 0; step < maxSteps; step++) {
@@ -1532,7 +1602,12 @@ export class AnthropicProvider extends BaseProvider {
                         const delta = event.delta;
                         if (delta.type === "text_delta") {
                             textAcc.set(event.index, (textAcc.get(event.index) ?? "") + delta.text);
-                            pushChunk({ content: delta.text });
+                            if (finalResultActive) {
+                                bufferedText += delta.text;
+                            }
+                            else {
+                                pushChunk({ content: delta.text });
+                            }
                         }
                         else if (delta.type === "thinking_delta") {
                             const acc = thinkingAcc.get(event.index) ?? {
@@ -1568,6 +1643,20 @@ export class AnthropicProvider extends BaseProvider {
                     }
                 }
                 lastStop = stopReason;
+                // final_result is terminal: its arguments ARE the answer, so the turn
+                // ends here and any tool calls issued alongside it are not executed
+                // (parity with the native Vertex loops). It is never executed as a
+                // tool, never recorded in toolsUsed, and never stored as a tool
+                // execution — the pattern stays invisible to callers.
+                if (finalResultActive) {
+                    const finalCall = [...toolAcc.values()].find((acc) => acc.name === FINAL_RESULT_TOOL_NAME);
+                    if (finalCall) {
+                        finalResultText = stringifyFinalResultInput(finalCall.inputJson);
+                        lastStop = "end_turn";
+                        logger.debug("[Anthropic] Extracted structured output from final_result tool (stream)", { chars: finalResultText.length });
+                        break;
+                    }
+                }
                 if (stopReason !== "tool_use" || toolAcc.size === 0) {
                     break;
                 }
@@ -1710,6 +1799,19 @@ export class AnthropicProvider extends BaseProvider {
             throw this.formatProviderError(error);
         })
             .finally(() => {
+            // Deliver the buffered structured-output turn: `finalResultText` when
+            // the model called final_result, otherwise the prose it produced
+            // instead — never nothing, so a model that ignores the instruction
+            // degrades to today's plain-text behaviour rather than an empty
+            // stream. In `finally` so a turn that dies mid-loop still surfaces
+            // the text it had already buffered, exactly as the unbuffered path
+            // surfaces its partial deltas.
+            if (finalResultActive) {
+                const output = finalResultText ?? bufferedText;
+                if (output.length > 0) {
+                    pushChunk({ content: output });
+                }
+            }
             timeoutController?.cleanup();
             pushChunk({ done: true });
         });

package/dist/providers/anthropic/structuredOutput.d.ts

@@ -0,0 +1,58 @@
+import type Anthropic from "@anthropic-ai/sdk";
+/**
+ * Additive structured output for the native Anthropic Messages API.
+ *
+ * Anthropic has no `response_format`, so a schema has to be expressed as a
+ * tool. The provider's pre-existing `responseFormat` path does that by
+ * REPLACING the tools array with a single json tool and pinning `tool_choice`
+ * to it — correct for a schema-only call, but mutually exclusive with real
+ * tools, so agent/MCP turns that pass both silently lost the schema.
+ *
+ * The additive pattern here APPENDS a `final_result` tool to the caller's
+ * tools and leaves `tool_choice` on auto: the model keeps calling real tools
+ * for as long as it needs, then emits its answer as `final_result` arguments
+ * that already conform to the schema. This mirrors the native
+ * Claude-on-Vertex loop in `googleVertex/client.ts`, which has used the same
+ * tool name, description, and instruction wording since it shipped.
+ */
+/** Internal tool name — filtered out of every returned tool call / execution. */
+export declare const FINAL_RESULT_TOOL_NAME = "final_result";
+/** Appended to the system prompt whenever the final_result tool is in play. */
+export declare const FINAL_RESULT_INSTRUCTION = "\n\nIMPORTANT: You MUST call the 'final_result' tool to return your response in the required structured format. Do not respond with plain text - always use the final_result tool.";
+/**
+ * Build the `final_result` tool definition from a JSON Schema.
+ *
+ * `$ref`s are inlined and `$schema` dropped — Anthropic's `input_schema` must
+ * be a self-contained object schema. Schemas that are not object-rooted (a
+ * bare array/string schema) are wrapped so `input_schema.type` is always
+ * "object", which the Messages API requires.
+ */
+export declare function buildFinalResultTool(jsonSchema: Record<string, unknown>): Anthropic.Messages.Tool;
+/**
+ * Append `final_result` to an Anthropic tool list.
+ *
+ * Returns a NEW array so the caller's tool list is never mutated, and reports
+ * `applied: false` (with the list unchanged) when the pattern must not run:
+ * there are no real tools to preserve, or the caller already exposes a tool of
+ * that name — shadowing a caller's tool would break their turn.
+ */
+export declare function appendFinalResultTool(tools: Anthropic.Messages.Tool[] | undefined, jsonSchema: Record<string, unknown>): {
+    tools: Anthropic.Messages.Tool[] | undefined;
+    applied: boolean;
+};
+/**
+ * Append the final_result instruction to an Anthropic `system` value.
+ *
+ * The block-array form gets a NEW trailing block rather than an edit to the
+ * existing one: rewriting a block that carries a `cache_control` marker would
+ * change the cached prefix and invalidate the prompt cache on every turn.
+ */
+export declare function appendFinalResultInstruction(system: string | Anthropic.Messages.TextBlockParam[] | undefined): string | Anthropic.Messages.TextBlockParam[];
+/**
+ * Canonical JSON text for a `final_result` payload.
+ *
+ * Accepts the raw accumulated `input_json` from a stream so a payload
+ * truncated by the token cap is still returned verbatim — the caller's
+ * coercion layer can repair it, whereas dropping it loses the whole answer.
+ */
+export declare function stringifyFinalResultInput(inputJson: string): string;

package/dist/providers/anthropic/structuredOutput.js

@@ -0,0 +1,97 @@
+import { logger } from "../../utils/logger.js";
+import { inlineJsonSchema } from "../../utils/schemaConversion.js";
+/**
+ * Additive structured output for the native Anthropic Messages API.
+ *
+ * Anthropic has no `response_format`, so a schema has to be expressed as a
+ * tool. The provider's pre-existing `responseFormat` path does that by
+ * REPLACING the tools array with a single json tool and pinning `tool_choice`
+ * to it — correct for a schema-only call, but mutually exclusive with real
+ * tools, so agent/MCP turns that pass both silently lost the schema.
+ *
+ * The additive pattern here APPENDS a `final_result` tool to the caller's
+ * tools and leaves `tool_choice` on auto: the model keeps calling real tools
+ * for as long as it needs, then emits its answer as `final_result` arguments
+ * that already conform to the schema. This mirrors the native
+ * Claude-on-Vertex loop in `googleVertex/client.ts`, which has used the same
+ * tool name, description, and instruction wording since it shipped.
+ */
+/** Internal tool name — filtered out of every returned tool call / execution. */
+export const FINAL_RESULT_TOOL_NAME = "final_result";
+const FINAL_RESULT_TOOL_DESCRIPTION = "Return the final structured result. You MUST call this tool when you have gathered all information and are ready to provide the final answer. The arguments should contain the structured data matching the expected schema.";
+/** Appended to the system prompt whenever the final_result tool is in play. */
+export const FINAL_RESULT_INSTRUCTION = "\n\nIMPORTANT: You MUST call the 'final_result' tool to return your response in the required structured format. Do not respond with plain text - always use the final_result tool.";
+/**
+ * Build the `final_result` tool definition from a JSON Schema.
+ *
+ * `$ref`s are inlined and `$schema` dropped — Anthropic's `input_schema` must
+ * be a self-contained object schema. Schemas that are not object-rooted (a
+ * bare array/string schema) are wrapped so `input_schema.type` is always
+ * "object", which the Messages API requires.
+ */
+export function buildFinalResultTool(jsonSchema) {
+    const inlined = inlineJsonSchema({ ...jsonSchema });
+    delete inlined.$schema;
+    const properties = inlined.properties;
+    const input_schema = {
+        type: "object",
+        properties: properties ?? inlined,
+        required: Array.isArray(inlined.required) ? inlined.required : [],
+    };
+    return {
+        name: FINAL_RESULT_TOOL_NAME,
+        description: FINAL_RESULT_TOOL_DESCRIPTION,
+        input_schema,
+    };
+}
+/**
+ * Append `final_result` to an Anthropic tool list.
+ *
+ * Returns a NEW array so the caller's tool list is never mutated, and reports
+ * `applied: false` (with the list unchanged) when the pattern must not run:
+ * there are no real tools to preserve, or the caller already exposes a tool of
+ * that name — shadowing a caller's tool would break their turn.
+ */
+export function appendFinalResultTool(tools, jsonSchema) {
+    if (!tools || tools.length === 0) {
+        return { tools, applied: false };
+    }
+    if (tools.some((tool) => tool.name === FINAL_RESULT_TOOL_NAME)) {
+        logger.warn("[Anthropic] A caller tool is already named 'final_result'; skipping the additive structured-output tool");
+        return { tools, applied: false };
+    }
+    // Appended LAST so any cache_control breakpoint an upstream layer placed on
+    // the previously-last tool keeps marking the same prefix boundary.
+    return { tools: [...tools, buildFinalResultTool(jsonSchema)], applied: true };
+}
+/**
+ * Append the final_result instruction to an Anthropic `system` value.
+ *
+ * The block-array form gets a NEW trailing block rather than an edit to the
+ * existing one: rewriting a block that carries a `cache_control` marker would
+ * change the cached prefix and invalidate the prompt cache on every turn.
+ */
+export function appendFinalResultInstruction(system) {
+    if (system === undefined) {
+        return FINAL_RESULT_INSTRUCTION.trim();
+    }
+    if (typeof system === "string") {
+        return system + FINAL_RESULT_INSTRUCTION;
+    }
+    return [...system, { type: "text", text: FINAL_RESULT_INSTRUCTION.trim() }];
+}
+/**
+ * Canonical JSON text for a `final_result` payload.
+ *
+ * Accepts the raw accumulated `input_json` from a stream so a payload
+ * truncated by the token cap is still returned verbatim — the caller's
+ * coercion layer can repair it, whereas dropping it loses the whole answer.
+ */
+export function stringifyFinalResultInput(inputJson) {
+    try {
+        return JSON.stringify(JSON.parse(inputJson || "{}"));
+    }
+    catch {
+        return inputJson;
+    }
+}

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

@@ -269,6 +269,11 @@ export type GenerateOptions = {
      * (see `coerceJsonToSchema`), and `disableTools: true` remains available as
      * an explicit override.
      *
+     * On the native Anthropic Messages surface (provider "anthropic", including
+     * via a proxy) tools + schema are honored through an internal `final_result`
+     * tool the model calls with the structured answer — invisible to callers: it
+     * never appears in `toolCalls` / `toolExecutions`.
+     *
      * @example
      * ```typescript
      * // ✅ Vertex + Claude: tools AND schema together are fully supported
@@ -278,6 +283,12 @@ export type GenerateOptions = {
      *   model: "claude-sonnet-4-6",
      * });
      *
+     * // ✅ Direct Anthropic + tools: schema honored via the final_result tool
+     * const result = await neurolink.generate({
+     *   schema: MySchema,
+     *   provider: "anthropic",
+     * });
+     *
      * // ✅ Gemini + tools: SDK auto-falls back to coerced text-mode JSON
      * const result = await neurolink.generate({
      *   schema: MySchema,

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