@juspay/neurolink 11.8.0 → 11.9.0

package/dist/providers/anthropic/loopAdapter.js

@@ -0,0 +1,312 @@
+/**
+ * Direct Anthropic's adapter onto the shared agentic loop engine.
+ *
+ * Everything here is the wire-format half of the turn: building one Messages
+ * request, folding an SSE event sequence into content blocks, serializing tool
+ * results back into the conversation, and mapping the stop reason. The turn
+ * loop, the step cap, tool dispatch, retry and usage accumulation belong to
+ * `runAgenticLoop`.
+ *
+ * Two behaviours here are easy to lose in a migration and are called out
+ * because losing either is silent:
+ *
+ *  - Thinking deltas ride the channel as `{ content: "", reasoning }`. The
+ *    engine's chunk type carries `reasoning` for exactly this reason; a
+ *    channel that only understood `content` would drop every thinking delta
+ *    while the text path kept working.
+ *  - `resolveToolOnMiss` is wired to real deferred-catalog hydration, not as
+ *    interface decoration. The pre-migration loop resolves every tool call as
+ *    `toolsRecord[name] ?? resolveDeferredTool(toolsRecord, name)`, which is
+ *    how a cataloged tool the model calls without having loaded it via
+ *    `search_tools` gets found. Dropping it would break those tools with a
+ *    "Tool not found" that looks like a hallucination.
+ */
+import { resolveDeferredTool } from "../../tools/toolDiscovery.js";
+import { stringifyAnthropicToolOutput } from "./toolOutput.js";
+/** Map Anthropic's stop_reason onto the unified finish reason. */
+function mapAnthropicFinishReason(rawStopReason, hadToolCallsAtCap) {
+    switch (rawStopReason) {
+        case "max_tokens":
+            return "length";
+        case "tool_use":
+            return "tool-calls";
+        case "refusal":
+            return "content-filter";
+        default:
+            return hadToolCallsAtCap ? "tool-calls" : "stop";
+    }
+}
+export function createAnthropicLoopAdapter(config) {
+    return {
+        providerLabel: "anthropic",
+        maxSteps: config.maxSteps,
+        ...(config.toolFailureBreaker
+            ? { toolFailureBreaker: config.toolFailureBreaker }
+            : {}),
+        /**
+         * The engine decides WHEN to reclaim; the provider decides HOW, in its own
+         * concrete message types. Not optional dressing: this loop appends an
+         * assistant tool_use message and a user tool_result message every step,
+         * and nothing else bounds that growth.
+         */
+        ...(config.planReclaim
+            ? {
+                planReclaim: (conversation, step) => {
+                    const reclaimed = config.planReclaim?.(conversation, step);
+                    return reclaimed ? { conversation: reclaimed } : undefined;
+                },
+            }
+            : {}),
+        resolveToolOnMiss: (name) => {
+            const hydrated = resolveDeferredTool(config.toolsRecord, name);
+            const execute = hydrated?.execute;
+            if (!execute) {
+                return undefined;
+            }
+            // Wrapped rather than handed over directly: the engine's hook types
+            // `opts` as `unknown`, and a function declaring a narrower options type
+            // is not assignable to one accepting `unknown`. One assertion at the
+            // boundary, never a double assertion through `unknown`.
+            return {
+                execute: async (args, opts) => execute(args, opts),
+            };
+        },
+        buildStepRequest(conversation, step) {
+            return { raw: config.buildParams(conversation, step) };
+        },
+        async executeStep(request, channel, signal) {
+            const params = request.raw;
+            // Single assertion, not a double: `messages.create` returns a union of
+            // Message and Stream, and Stream<RawMessageStreamEvent> already IS an
+            // AsyncIterable of that event, so the two types overlap and the
+            // compiler still checks the narrowing.
+            const events = (await config.client.messages.create({ ...params, stream: true }, 
+            // The engine's signal, not config's: runAgenticLoop already derives
+            // it from the caller's abortSignal, so preferring config's would
+            // ignore engine-initiated cancellation entirely.
+            { signal }));
+            const textByIndex = new Map();
+            const toolByIndex = new Map();
+            const thinkingByIndex = new Map();
+            const redactedByIndex = new Map();
+            let text = "";
+            let reasoning = "";
+            let rawStopReason;
+            let inputTokens = 0;
+            let outputTokens = 0;
+            let cacheReadTokens = 0;
+            let cacheWriteTokens = 0;
+            let stepOutputTokens = 0;
+            for await (const rawEvent of events) {
+                if (signal.aborted) {
+                    break;
+                }
+                // Narrowed through the SDK's own discriminated union rather than
+                // re-declared: `RawMessageStreamEvent` already describes every event
+                // shape, so `event.type` checks below are compiler-checked instead of
+                // asserted.
+                const event = rawEvent;
+                if (event.type === "message_start") {
+                    const usage = event.message?.usage;
+                    inputTokens += usage?.input_tokens ?? 0;
+                    const startOutput = usage?.output_tokens ?? 0;
+                    outputTokens += startOutput - stepOutputTokens;
+                    stepOutputTokens = startOutput;
+                    // Anthropic reports cache reads/writes separately from input_tokens
+                    // on this same event; without these the stream drops all cache
+                    // accounting.
+                    cacheReadTokens += usage?.cache_read_input_tokens ?? 0;
+                    cacheWriteTokens += usage?.cache_creation_input_tokens ?? 0;
+                    // The guard calibrates from the FULL prompt size, not input_tokens
+                    // alone: on a cache hit the uncached remainder is tiny and using it
+                    // would let the guard drift far under the real cost.
+                    config.noteObservedPromptTokens?.((usage?.input_tokens ?? 0) +
+                        (usage?.cache_read_input_tokens ?? 0) +
+                        (usage?.cache_creation_input_tokens ?? 0));
+                    continue;
+                }
+                if (event.type === "content_block_start") {
+                    const index = event.index ?? 0;
+                    // A redacted_thinking block carries its whole payload here and
+                    // produces no deltas, so if it is not captured on this event it is
+                    // never seen again. Anthropic validates the thinking chain when
+                    // extended thinking continues across a tool-use turn, so a missing
+                    // one fails the NEXT request — and only for accounts where safety
+                    // redaction actually triggers, which is why it survives testing.
+                    if (event.content_block?.type === "redacted_thinking") {
+                        const data = event.content_block.data;
+                        if (typeof data === "string") {
+                            redactedByIndex.set(index, data);
+                        }
+                    }
+                    if (event.content_block?.type === "tool_use") {
+                        toolByIndex.set(index, {
+                            id: event.content_block.id ?? "",
+                            name: event.content_block.name ?? "",
+                            inputJson: "",
+                        });
+                    }
+                    continue;
+                }
+                if (event.type === "content_block_delta") {
+                    const index = event.index ?? 0;
+                    const delta = event.delta;
+                    if (delta?.type === "text_delta" && delta.text) {
+                        text += delta.text;
+                        textByIndex.set(index, (textByIndex.get(index) ?? "") + delta.text);
+                        channel.push({ content: delta.text });
+                    }
+                    else if (delta?.type === "thinking_delta" && delta.thinking) {
+                        const acc = thinkingByIndex.get(index) ?? {
+                            text: "",
+                            signature: "",
+                        };
+                        acc.text += delta.thinking;
+                        thinkingByIndex.set(index, acc);
+                        reasoning += delta.thinking;
+                        // Reasoning rides its own field; `content` stays a present string
+                        // so plain-text consumers are unaffected.
+                        channel.push({ content: "", reasoning: delta.thinking });
+                    }
+                    else if (delta?.type === "signature_delta" && delta.signature) {
+                        const acc = thinkingByIndex.get(index) ?? {
+                            text: "",
+                            signature: "",
+                        };
+                        acc.signature += delta.signature;
+                        thinkingByIndex.set(index, acc);
+                    }
+                    else if (delta?.type === "input_json_delta" && delta.partial_json) {
+                        const pending = toolByIndex.get(index);
+                        if (pending) {
+                            pending.inputJson += delta.partial_json;
+                        }
+                    }
+                    continue;
+                }
+                if (event.type === "message_delta") {
+                    rawStopReason = event.delta?.stop_reason ?? rawStopReason;
+                    const cumulative = event.usage?.output_tokens ?? stepOutputTokens;
+                    outputTokens += cumulative - stepOutputTokens;
+                    stepOutputTokens = cumulative;
+                }
+            }
+            // JSON.parse happily yields null, an array or a primitive, and an
+            // assertion converts none of them. Both `tool_use.input` and
+            // AgenticLoopToolCall.args require an object, so anything else becomes
+            // {} rather than being passed through as invalid wire content.
+            const parseArgs = (json) => {
+                if (!json) {
+                    return {};
+                }
+                try {
+                    const parsed = JSON.parse(json);
+                    return typeof parsed === "object" &&
+                        parsed !== null &&
+                        !Array.isArray(parsed)
+                        ? parsed
+                        : {};
+                }
+                catch {
+                    return {};
+                }
+            };
+            // Rebuild the assistant turn in wire order so it can be replayed as the
+            // assistant message on the next step. Text that arrived before a tool
+            // call has to survive here, or the model stops seeing its own reasoning
+            // mid-turn.
+            const blocks = [];
+            const indices = new Set([
+                ...textByIndex.keys(),
+                ...toolByIndex.keys(),
+                ...thinkingByIndex.keys(),
+                ...redactedByIndex.keys(),
+            ]);
+            for (const index of [...indices].sort((a, b) => a - b)) {
+                // Thinking blocks are replayed with their signature. Anthropic
+                // validates that signature when extended thinking continues across
+                // turns, so dropping the block — or keeping the text without the
+                // signature — breaks the next step of a thinking turn.
+                const redacted = redactedByIndex.get(index);
+                if (redacted) {
+                    blocks.push({ type: "redacted_thinking", data: redacted });
+                }
+                const thinking = thinkingByIndex.get(index);
+                // Both halves required: Anthropic's thinking block carries a
+                // mandatory signature, and replaying one with an empty string is
+                // rejected outright. A thinking block that never received a
+                // signature_delta is dropped rather than sent unsigned.
+                if (thinking?.text && thinking.signature) {
+                    blocks.push({
+                        type: "thinking",
+                        thinking: thinking.text,
+                        signature: thinking.signature,
+                    });
+                }
+                const blockText = textByIndex.get(index);
+                if (blockText) {
+                    blocks.push({
+                        type: "text",
+                        text: blockText,
+                    });
+                }
+                const pending = toolByIndex.get(index);
+                if (pending) {
+                    blocks.push({
+                        type: "tool_use",
+                        id: pending.id,
+                        name: pending.name,
+                        input: parseArgs(pending.inputJson),
+                    });
+                }
+            }
+            const allCalls = [...toolByIndex.values()].map((pending) => ({
+                id: pending.id,
+                name: pending.name,
+                args: parseArgs(pending.inputJson),
+            }));
+            // A terminal structured-output call ends the turn: its arguments are the
+            // answer. Reporting it as text and leaving it out of `toolCalls` is what
+            // routes it through the engine's ordinary zero-tool-calls exit, so it is
+            // never dispatched, never counted against the breaker, and never shows
+            // up as a tool execution.
+            const terminal = config.finalResultToolName
+                ? allCalls.find((call) => call.name === config.finalResultToolName)
+                : undefined;
+            const toolCalls = terminal ? [] : allCalls;
+            const finalText = terminal ? JSON.stringify(terminal.args) : text;
+            return {
+                text: finalText,
+                ...(reasoning ? { reasoning } : {}),
+                toolCalls,
+                usage: {
+                    inputTokens,
+                    outputTokens,
+                    cacheReadTokens,
+                    cacheWriteTokens,
+                },
+                rawStopReason,
+                raw: blocks,
+            };
+        },
+        buildToolResultMessages(conversation, stepResult, toolResults) {
+            const assistantMessage = {
+                role: "assistant",
+                content: stepResult.raw,
+            };
+            const resultMessage = {
+                role: "user",
+                content: toolResults.map((result) => ({
+                    type: "tool_result",
+                    tool_use_id: result.id,
+                    content: result.error
+                        ? `Error executing tool ${result.name}: ${result.error}`
+                        : stringifyAnthropicToolOutput(result.output),
+                    ...(result.error ? { is_error: true } : {}),
+                })),
+            };
+            return [...conversation, assistantMessage, resultMessage];
+        },
+        mapFinishReason: mapAnthropicFinishReason,
+    };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Tool-result serialization shared by Anthropic's client and its loop adapter.
+ *
+ * Extracted rather than exported from `client.ts` because the adapter is
+ * imported BY the client: importing back the other way would close a cycle.
+ * The behaviour is unchanged from the module-private version it replaces.
+ */
+/** Serialize a tool-result `output` into text for a tool_result block. */
+export declare const stringifyAnthropicToolOutput: (output: unknown) => string;

package/dist/providers/anthropic/toolOutput.js

@@ -0,0 +1,38 @@
+/**
+ * Tool-result serialization shared by Anthropic's client and its loop adapter.
+ *
+ * Extracted rather than exported from `client.ts` because the adapter is
+ * imported BY the client: importing back the other way would close a cycle.
+ * The behaviour is unchanged from the module-private version it replaces.
+ */
+/** Serialize a tool-result `output` into text for a tool_result block. */
+export const stringifyAnthropicToolOutput = (output) => {
+    if (output === null || output === undefined) {
+        return "";
+    }
+    if (typeof output === "string") {
+        return output;
+    }
+    const o = output;
+    if (o.type === "text" && typeof o.value === "string") {
+        return o.value;
+    }
+    if (o.type === "json" || o.type === "error-json") {
+        try {
+            // `?? String(...)`: JSON.stringify returns undefined for an undefined
+            // value, which would break this function's string contract and emit an
+            // invalid tool_result.content.
+            return JSON.stringify(o.value) ?? String(o.value);
+        }
+        catch {
+            return String(o.value);
+        }
+    }
+    try {
+        // Same guard: a function or symbol stringifies to undefined.
+        return JSON.stringify(output) ?? String(output);
+    }
+    catch {
+        return String(output);
+    }
+};

package/dist/types/loopEngine.d.ts

@@ -1,3 +1,19 @@
+import type Anthropic from "@anthropic-ai/sdk";
+import type { Tool } from "./tools.js";
+/**
+ * One chunk on the engine's stream.
+ *
+ * `reasoning` is carried alongside `content` rather than instead of it: the
+ * providers that emit extended thinking (direct Anthropic, Google AI Studio,
+ * Vertex) push a chunk with empty `content` and the thinking delta in
+ * `reasoning`, so a channel typed `{ content: string }` alone would drop
+ * every thinking delta the moment those providers move onto the engine —
+ * silently, since the text path would keep working.
+ */
+export type AgenticLoopChunk = {
+    content: string;
+    reasoning?: string;
+};
 export type AgenticLoopToolCall = {
     id: string;
     name: string;
@@ -97,9 +113,7 @@ export type AgenticLoopAdapter<TConversation = unknown, TRaw = unknown> = {
     } | undefined;
     buildStepRequest(conversation: TConversation, step: number): AgenticLoopStepRequest;
     executeStep(request: AgenticLoopStepRequest, channel: {
-        push(chunk: {
-            content: string;
-        }): void;
+        push(chunk: AgenticLoopChunk): void;
     }, signal: AbortSignal): Promise<AgenticLoopStepResult<TRaw>>;
     buildToolResultMessages(conversation: TConversation, stepResult: AgenticLoopStepResult<TRaw>, toolResults: AgenticLoopToolCallResult[]): TConversation;
     mapFinishReason(rawStopReason: string | undefined, hadToolCalls: boolean): string;
@@ -109,6 +123,56 @@ export type AgenticLoopAdapter<TConversation = unknown, TRaw = unknown> = {
     isMalformedStep?(stepResult: AgenticLoopStepResult<TRaw>): boolean;
     buildMalformedRetryNote?(conversation: TConversation): TConversation;
 };
+/**
+ * Construction input for `createAnthropicLoopAdapter`, shared by direct
+ * Anthropic and Vertex+Claude.
+ *
+ * `toolFailureBreaker` is the one field the two call sites must differ on:
+ * Vertex+Claude ports the Gemini loops' failure-strike breaker, native
+ * Anthropic has never had one, and setting it for both would change native
+ * Anthropic's behaviour under the guise of a shared refactor.
+ */
+export type AnthropicLoopAdapterConfig = {
+    client: Pick<Anthropic, "messages">;
+    maxSteps: number;
+    /**
+     * Build one step's request. A closure so the per-turn work the caller
+     * already does — system prompt, tool declarations, sampling, thinking
+     * config, cache breakpoints — stays where it is rather than moving here.
+     */
+    buildParams: (conversation: Anthropic.Messages.MessageParam[], step: number) => Anthropic.Messages.MessageCreateParams;
+    /** The turn's live tool record, used for deferred-catalog resolution. */
+    toolsRecord: Record<string, Tool>;
+    /**
+     * Name of the terminal structured-output tool when one is in play. A call
+     * to it ends the turn: its arguments ARE the answer, so it is reported as
+     * text and omitted from `toolCalls`, which routes it through the engine's
+     * ordinary zero-tool-calls exit.
+     */
+    finalResultToolName?: string;
+    toolFailureBreaker?: AgenticLoopToolFailureBreaker;
+    /**
+     * In-turn context reclaim, run once per step before the request is built.
+     * Returns the rebuilt conversation when it reclaimed, undefined while the
+     * request still fits — leaving history byte-identical in the common case so
+     * the rolling prompt-cache prefix stays valid.
+     *
+     * Provider-supplied because the guard decides and the caller mutates in its
+     * own concrete types: dropping an assistant tool_use message together with
+     * its paired user tool_result is what keeps blocks paired. The loop appends
+     * both every step with nothing else bounding growth, so a migration that
+     * drops this overflows the window mid-turn.
+     */
+    planReclaim?: (conversation: Anthropic.Messages.MessageParam[], step: number) => Anthropic.Messages.MessageParam[] | undefined;
+    /**
+     * Calibration feedback for the provider's reclaim guard: the FULL prompt
+     * size for the step just made — uncached input plus both cache tiers.
+     * Passing input_tokens alone reads a cache-hit step as tiny and lets the
+     * guard drift far under the real cost.
+     */
+    noteObservedPromptTokens?: (promptTokens: number) => void;
+    abortSignal?: AbortSignal;
+};
 export type AgenticLoopOptions = {
     tools?: Record<string, {
         execute?: (args: Record<string, unknown>, opts: unknown) => Promise<unknown>;

package/dist/types/providers.d.ts

@@ -842,6 +842,12 @@ export type BedrockContentBlock = {
 export type BedrockPendingContentBlock = BedrockContentBlock & {
     _inputBuffer?: string;
 };
+/** A tool_use block being assembled across Anthropic `input_json_delta` events. */
+export type AnthropicPendingToolUse = {
+    id: string;
+    name: string;
+    inputJson: string;
+};
 /**
  * Bedrock message structure
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "11.8.0",
+  "version": "11.9.0",
   "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": {
@@ -213,7 +213,9 @@
     "test:vector-pgvector": "npx tsx test/continuous-test-suite-vector-pgvector.ts",
     "test:vector-pinecone": "npx tsx test/continuous-test-suite-vector-pinecone.ts",
     "test:bedrock-loop-characterization": "tsx test/continuous-test-suite-bedrock-loop-characterization.ts",
-    "test:sagemaker-streaming": "tsx test/continuous-test-suite-sagemaker-streaming.ts"
+    "test:sagemaker-streaming": "tsx test/continuous-test-suite-sagemaker-streaming.ts",
+    "test:anthropic-loop-characterization": "tsx test/continuous-test-suite-anthropic-loop-characterization.ts",
+    "test:aistudio-loop-characterization": "tsx test/continuous-test-suite-aistudio-loop-characterization.ts"
   },
   "files": [
     "dist",