@juspay/neurolink 10.10.0 → 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/modules/GenerationHandler.js

@@ -26,6 +26,7 @@ import { DEFAULT_MAX_STEPS, DEFAULT_WRAPUP_TIME_LEAD_MS, } from "../constants.js
 import { createStepBudgetGuard, estimateFixedOverheadTokens, } from "../../context/stepBudgetGuard.js";
 import { isTemperatureDeprecatedError, isSchemaComplexityError, isToolsSchemaConflictError, isToolsSchemaExclusionInForce, } from "./structuredOutputPolicy.js";
 import { coerceJsonToSchema } from "../../utils/json/coerce.js";
+import { convertZodToJsonSchema } from "../../utils/schemaConversion.js";
 import { NoObjectGeneratedError } from "../../utils/generationErrors.js";
 import { Output, stepCountIs } from "../../utils/tool.js";
 import { generateText } from "../../utils/generation.js";
@@ -105,11 +106,14 @@ export function resolveTurnBudget(options, turnStartMs) {
  * `providerOptions:` spreads in the args literal would silently clobber each
  * other (object spread does not deep-merge).
  */
-function buildProviderOptions(options, isGoogleProvider, callerTimeoutMs) {
+function buildProviderOptions(options, isGoogleProvider, callerTimeoutMs, finalResultSchema) {
     const providerOptions = {};
     if (callerTimeoutMs !== undefined) {
         providerOptions.neurolink = { timeoutMs: callerTimeoutMs };
     }
+    if (finalResultSchema) {
+        providerOptions.anthropic = { finalResultSchema };
+    }
     if (options.thinkingConfig?.enabled && isGoogleProvider) {
         // Gemini 3 uses thinkingLevel; Gemini 2.5 uses thinkingBudget.
         providerOptions.google = {
@@ -236,7 +240,22 @@ export class GenerationHandler {
         const prepareStep = options.prepareStep;
         const { callerTimeoutMs, turnBudgetMs, wrapupLeadMs, turnDeadline } = resolveTurnBudget(options, turnStartMs);
         let wrapupForced = false;
-        const providerOptions = buildProviderOptions(options, isGoogleProvider, callerTimeoutMs);
+        // The native Anthropic Messages surface cannot combine AI-SDK structured
+        // output with tools (see structuredOutputPolicy — experimental_output
+        // replaces the tools array), so `useStructuredOutput` is false above and
+        // the schema would simply be dropped for every agent/MCP turn. Hand the
+        // JSON Schema to the provider instead: it appends an additive
+        // `final_result` tool and returns the answer as that tool's arguments,
+        // keeping the real tools callable. Bedrock is deliberately excluded — it
+        // runs on the third-party @ai-sdk/amazon-bedrock model, which has no such
+        // handling.
+        const finalResultSchema = this.providerName === "anthropic" &&
+            !!options.schema &&
+            shouldUseTools &&
+            Object.keys(tools).length > 0
+            ? convertZodToJsonSchema(options.schema)
+            : undefined;
+        const providerOptions = buildProviderOptions(options, isGoogleProvider, callerTimeoutMs, finalResultSchema);
         // Hoist system-role messages into generateText's top-level `system` option
         // rather than passing them inside `messages` (deprecated by the AI SDK,
         // rejected in v7). See extractSystemMessages for the rationale. (#1024)

package/dist/lib/core/modules/structuredOutputPolicy.d.ts

@@ -23,6 +23,14 @@ export declare function isGeminiProvider(providerName: string, modelName: string
  * experimental_output + tools silently drops tool_use blocks on this surface, so
  * structured output must be disabled when tools are active. Vertex+Claude is NOT
  * matched here (different transport, no conflict).
+ *
+ * Being excluded here no longer means the schema is LOST for provider
+ * "anthropic": GenerationHandler forwards the JSON Schema to the provider via
+ * `providerOptions.anthropic.finalResultSchema`, and the provider appends an
+ * additive `final_result` tool (see providers/anthropic/structuredOutput.ts) —
+ * schema enforcement without giving up tool calling. "bedrock" has no such
+ * handling (it runs on the third-party @ai-sdk/amazon-bedrock model) and still
+ * falls back to text-mode coercion.
  */
 export declare function isNativeAnthropicProvider(providerName: string): boolean;
 /**

package/dist/lib/core/modules/structuredOutputPolicy.js

@@ -33,6 +33,14 @@ export function isGeminiProvider(providerName, modelName) {
  * experimental_output + tools silently drops tool_use blocks on this surface, so
  * structured output must be disabled when tools are active. Vertex+Claude is NOT
  * matched here (different transport, no conflict).
+ *
+ * Being excluded here no longer means the schema is LOST for provider
+ * "anthropic": GenerationHandler forwards the JSON Schema to the provider via
+ * `providerOptions.anthropic.finalResultSchema`, and the provider appends an
+ * additive `final_result` tool (see providers/anthropic/structuredOutput.ts) —
+ * schema enforcement without giving up tool calling. "bedrock" has no such
+ * handling (it runs on the third-party @ai-sdk/amazon-bedrock model) and still
+ * falls back to text-mode coercion.
  */
 export function isNativeAnthropicProvider(providerName) {
     return providerName === "anthropic" || providerName === "bedrock";

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/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/lib/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;