@juspay/neurolink 11.8.1 → 11.10.0

package/dist/core/geminiLoopAdapter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared Gemini adapter onto the agentic loop engine.
+ *
+ * Lives in `core/` rather than inside either provider's folder because two
+ * providers use it: Google AI Studio (Task 9) and Vertex Gemini (Task 10).
+ * Both issue the same wire call — `models.generateContentStream` — and consume
+ * the same response shape, so one `executeStep` serves four hand-rolled loops
+ * (each provider has a streaming one and a near-duplicate inside `generate()`).
+ *
+ * Function-name sanitization stays entirely on this side of the engine
+ * boundary, which is the design decision Task 7 recorded rather than a
+ * shortcut. Google requires function names to match a restricted pattern, so
+ * declarations are built with sanitized names and the model calls back with
+ * those same sanitized names. The engine only ever sees plain string names, so
+ * this adapter translates sanitized -> original before returning `toolCalls`,
+ * and original -> sanitized when writing `functionResponse` parts. Neither the
+ * engine nor any other adapter needs to know sanitization happened.
+ */
+import type { AgenticLoopAdapter, GeminiLoopAdapterConfig, GeminiStepRaw, GeminiTurnContent } from "../types/index.js";
+export declare function createGeminiLoopAdapter(config: GeminiLoopAdapterConfig): AgenticLoopAdapter<GeminiTurnContent[], GeminiStepRaw>;

package/dist/core/geminiLoopAdapter.js

@@ -0,0 +1,170 @@
+/**
+ * Shared Gemini adapter onto the agentic loop engine.
+ *
+ * Lives in `core/` rather than inside either provider's folder because two
+ * providers use it: Google AI Studio (Task 9) and Vertex Gemini (Task 10).
+ * Both issue the same wire call — `models.generateContentStream` — and consume
+ * the same response shape, so one `executeStep` serves four hand-rolled loops
+ * (each provider has a streaming one and a near-duplicate inside `generate()`).
+ *
+ * Function-name sanitization stays entirely on this side of the engine
+ * boundary, which is the design decision Task 7 recorded rather than a
+ * shortcut. Google requires function names to match a restricted pattern, so
+ * declarations are built with sanitized names and the model calls back with
+ * those same sanitized names. The engine only ever sees plain string names, so
+ * this adapter translates sanitized -> original before returning `toolCalls`,
+ * and original -> sanitized when writing `functionResponse` parts. Neither the
+ * engine nor any other adapter needs to know sanitization happened.
+ */
+import { collectStreamChunksIncremental, extractTextFromParts, mapGeminiFinishReason, pushModelResponseToHistory, refreshNativeToolDeclarations, } from "../providers/googleNativeGemini3/utils.js";
+export function createGeminiLoopAdapter(config) {
+    /**
+     * Sanitized wire name -> the name the caller registered. Rebuilt per step
+     * because mid-turn discovery can add entries between steps.
+     */
+    const originalNameFor = (sanitized) => config.declarations?.originalNameMap?.get(sanitized) ?? sanitized;
+    const sanitizedNameFor = (original) => {
+        const map = config.declarations?.originalNameMap;
+        if (!map) {
+            return original;
+        }
+        for (const [sanitized, name] of map) {
+            if (name === original) {
+                return sanitized;
+            }
+        }
+        return original;
+    };
+    return {
+        providerLabel: config.providerLabel,
+        maxSteps: config.maxSteps,
+        ...(config.toolFailureBreaker
+            ? { toolFailureBreaker: config.toolFailureBreaker }
+            : {}),
+        /**
+         * Mid-turn discovery: `search_tools` hydrates new tools into the live
+         * record between steps, and Gemini only calls what the request declared,
+         * so the declarations are refreshed before each step is built. This is
+         * why `resolveToolOnMiss` exists as well — a tool discovered during a
+         * step is callable in the same step, before the next refresh.
+         */
+        buildStepRequest(conversation, step) {
+            if (config.declarations) {
+                refreshNativeToolDeclarations(config.liveTools, config.declarations);
+            }
+            return { raw: config.buildRequest(conversation, step) };
+        },
+        /**
+         * The engine decides WHEN to reclaim; the provider decides HOW. Wiring
+         * this is not optional dressing: both loops append a model turn and a
+         * tool turn every step, so without it a long agentic run overflows the
+         * context window mid-turn and loses the work already done.
+         */
+        ...(config.planReclaim
+            ? {
+                planReclaim: (conversation, step) => {
+                    const reclaimed = config.planReclaim?.(conversation, step);
+                    return reclaimed ? { conversation: reclaimed } : undefined;
+                },
+            }
+            : {}),
+        /**
+         * A step that produced no text, no function calls, and a
+         * MALFORMED_FUNCTION_CALL finish reason is a transient formatting
+         * failure, not a finished turn. Vertex retries it once with a corrective
+         * note rather than hard-ending on empty content — automated RCA turns
+         * were dying at step 2-4 on this and being mislabelled as step-cap exits.
+         *
+         * Opt-in: AI Studio has no such retry today and gaining one silently
+         * would be a behaviour change, not a migration.
+         */
+        ...(config.enableMalformedRetry && config.buildMalformedRetryNote
+            ? {
+                isMalformedStep: (stepResult) => stepResult.toolCalls.length === 0 &&
+                    !stepResult.text &&
+                    stepResult.rawStopReason === "MALFORMED_FUNCTION_CALL",
+                buildMalformedRetryNote: config.buildMalformedRetryNote,
+            }
+            : {}),
+        resolveToolOnMiss: (name) => {
+            const tool = config.liveTools?.[name];
+            const execute = tool?.execute;
+            if (!execute) {
+                return undefined;
+            }
+            // Wrapped because the 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.
+            return {
+                execute: async (args, opts) => execute(args, opts),
+            };
+        },
+        async executeStep(request, channel, signal) {
+            const rawStream = await config.sendStep(request.raw, signal);
+            // `collectStreamChunksIncremental` wants a StreamChannel but only ever
+            // calls `.push`, so the engine's push-only channel satisfies it. The
+            // helper is reused rather than reimplemented precisely because it also
+            // owns usage extraction and thought-signature preservation.
+            const collected = await collectStreamChunksIncremental(rawStream, {
+                push: (chunk) => channel.push(chunk),
+            });
+            // The provider's context guard calibrates from real per-step counts;
+            // `inputTokens` is this step's full prompt size, which is what it
+            // projects the next request from.
+            config.noteUsage?.(collected.inputTokens, collected.outputTokens);
+            const text = extractTextFromParts(collected.rawResponseParts);
+            // Names cross the engine boundary in their ORIGINAL form.
+            const toolCalls = collected.stepFunctionCalls.map((call, index) => ({
+                id: `${config.providerLabel}_${index}_${call.name}`,
+                name: originalNameFor(call.name),
+                args: call.args,
+            }));
+            return {
+                text,
+                toolCalls,
+                usage: {
+                    inputTokens: collected.inputTokens,
+                    outputTokens: collected.outputTokens,
+                    ...(collected.cacheReadTokens
+                        ? { cacheReadTokens: collected.cacheReadTokens }
+                        : {}),
+                    ...(collected.reasoningTokens
+                        ? { reasoningTokens: collected.reasoningTokens }
+                        : {}),
+                },
+                rawStopReason: collected.finishReason,
+                raw: {
+                    rawResponseParts: collected.rawResponseParts,
+                    stepFunctionCalls: collected.stepFunctionCalls,
+                },
+            };
+        },
+        buildToolResultMessages(conversation, stepResult, toolResults) {
+            // Copied before `pushModelResponseToHistory` mutates it: the engine
+            // treats the conversation as a value it hands in and gets back, so
+            // mutating the caller's array in place would make a retried or
+            // reclaimed step see history it should not.
+            const next = [...conversation];
+            pushModelResponseToHistory(next, stepResult.raw.rawResponseParts, stepResult.raw.stepFunctionCalls);
+            next.push({
+                role: "user",
+                parts: toolResults.map((result) => ({
+                    functionResponse: {
+                        // Back to the sanitized wire name the model actually called.
+                        name: sanitizedNameFor(result.name),
+                        response: result.error
+                            ? { error: result.error }
+                            : { result: result.output },
+                    },
+                })),
+            });
+            return next;
+        },
+        mapFinishReason(rawStopReason, hadToolCallsAtCap) {
+            const mapped = mapGeminiFinishReason(rawStopReason);
+            // A turn cut off at the step cap ended because of the cap, not because
+            // the last response said "STOP".
+            return hadToolCallsAtCap && mapped === "stop" ? "tool-calls" : mapped;
+        },
+    };
+}

package/dist/lib/core/geminiLoopAdapter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared Gemini adapter onto the agentic loop engine.
+ *
+ * Lives in `core/` rather than inside either provider's folder because two
+ * providers use it: Google AI Studio (Task 9) and Vertex Gemini (Task 10).
+ * Both issue the same wire call — `models.generateContentStream` — and consume
+ * the same response shape, so one `executeStep` serves four hand-rolled loops
+ * (each provider has a streaming one and a near-duplicate inside `generate()`).
+ *
+ * Function-name sanitization stays entirely on this side of the engine
+ * boundary, which is the design decision Task 7 recorded rather than a
+ * shortcut. Google requires function names to match a restricted pattern, so
+ * declarations are built with sanitized names and the model calls back with
+ * those same sanitized names. The engine only ever sees plain string names, so
+ * this adapter translates sanitized -> original before returning `toolCalls`,
+ * and original -> sanitized when writing `functionResponse` parts. Neither the
+ * engine nor any other adapter needs to know sanitization happened.
+ */
+import type { AgenticLoopAdapter, GeminiLoopAdapterConfig, GeminiStepRaw, GeminiTurnContent } from "../types/index.js";
+export declare function createGeminiLoopAdapter(config: GeminiLoopAdapterConfig): AgenticLoopAdapter<GeminiTurnContent[], GeminiStepRaw>;

package/dist/lib/core/geminiLoopAdapter.js

@@ -0,0 +1,171 @@
+/**
+ * Shared Gemini adapter onto the agentic loop engine.
+ *
+ * Lives in `core/` rather than inside either provider's folder because two
+ * providers use it: Google AI Studio (Task 9) and Vertex Gemini (Task 10).
+ * Both issue the same wire call — `models.generateContentStream` — and consume
+ * the same response shape, so one `executeStep` serves four hand-rolled loops
+ * (each provider has a streaming one and a near-duplicate inside `generate()`).
+ *
+ * Function-name sanitization stays entirely on this side of the engine
+ * boundary, which is the design decision Task 7 recorded rather than a
+ * shortcut. Google requires function names to match a restricted pattern, so
+ * declarations are built with sanitized names and the model calls back with
+ * those same sanitized names. The engine only ever sees plain string names, so
+ * this adapter translates sanitized -> original before returning `toolCalls`,
+ * and original -> sanitized when writing `functionResponse` parts. Neither the
+ * engine nor any other adapter needs to know sanitization happened.
+ */
+import { collectStreamChunksIncremental, extractTextFromParts, mapGeminiFinishReason, pushModelResponseToHistory, refreshNativeToolDeclarations, } from "../providers/googleNativeGemini3/utils.js";
+export function createGeminiLoopAdapter(config) {
+    /**
+     * Sanitized wire name -> the name the caller registered. Rebuilt per step
+     * because mid-turn discovery can add entries between steps.
+     */
+    const originalNameFor = (sanitized) => config.declarations?.originalNameMap?.get(sanitized) ?? sanitized;
+    const sanitizedNameFor = (original) => {
+        const map = config.declarations?.originalNameMap;
+        if (!map) {
+            return original;
+        }
+        for (const [sanitized, name] of map) {
+            if (name === original) {
+                return sanitized;
+            }
+        }
+        return original;
+    };
+    return {
+        providerLabel: config.providerLabel,
+        maxSteps: config.maxSteps,
+        ...(config.toolFailureBreaker
+            ? { toolFailureBreaker: config.toolFailureBreaker }
+            : {}),
+        /**
+         * Mid-turn discovery: `search_tools` hydrates new tools into the live
+         * record between steps, and Gemini only calls what the request declared,
+         * so the declarations are refreshed before each step is built. This is
+         * why `resolveToolOnMiss` exists as well — a tool discovered during a
+         * step is callable in the same step, before the next refresh.
+         */
+        buildStepRequest(conversation, step) {
+            if (config.declarations) {
+                refreshNativeToolDeclarations(config.liveTools, config.declarations);
+            }
+            return { raw: config.buildRequest(conversation, step) };
+        },
+        /**
+         * The engine decides WHEN to reclaim; the provider decides HOW. Wiring
+         * this is not optional dressing: both loops append a model turn and a
+         * tool turn every step, so without it a long agentic run overflows the
+         * context window mid-turn and loses the work already done.
+         */
+        ...(config.planReclaim
+            ? {
+                planReclaim: (conversation, step) => {
+                    const reclaimed = config.planReclaim?.(conversation, step);
+                    return reclaimed ? { conversation: reclaimed } : undefined;
+                },
+            }
+            : {}),
+        /**
+         * A step that produced no text, no function calls, and a
+         * MALFORMED_FUNCTION_CALL finish reason is a transient formatting
+         * failure, not a finished turn. Vertex retries it once with a corrective
+         * note rather than hard-ending on empty content — automated RCA turns
+         * were dying at step 2-4 on this and being mislabelled as step-cap exits.
+         *
+         * Opt-in: AI Studio has no such retry today and gaining one silently
+         * would be a behaviour change, not a migration.
+         */
+        ...(config.enableMalformedRetry && config.buildMalformedRetryNote
+            ? {
+                isMalformedStep: (stepResult) => stepResult.toolCalls.length === 0 &&
+                    !stepResult.text &&
+                    stepResult.rawStopReason === "MALFORMED_FUNCTION_CALL",
+                buildMalformedRetryNote: config.buildMalformedRetryNote,
+            }
+            : {}),
+        resolveToolOnMiss: (name) => {
+            const tool = config.liveTools?.[name];
+            const execute = tool?.execute;
+            if (!execute) {
+                return undefined;
+            }
+            // Wrapped because the 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.
+            return {
+                execute: async (args, opts) => execute(args, opts),
+            };
+        },
+        async executeStep(request, channel, signal) {
+            const rawStream = await config.sendStep(request.raw, signal);
+            // `collectStreamChunksIncremental` wants a StreamChannel but only ever
+            // calls `.push`, so the engine's push-only channel satisfies it. The
+            // helper is reused rather than reimplemented precisely because it also
+            // owns usage extraction and thought-signature preservation.
+            const collected = await collectStreamChunksIncremental(rawStream, {
+                push: (chunk) => channel.push(chunk),
+            });
+            // The provider's context guard calibrates from real per-step counts;
+            // `inputTokens` is this step's full prompt size, which is what it
+            // projects the next request from.
+            config.noteUsage?.(collected.inputTokens, collected.outputTokens);
+            const text = extractTextFromParts(collected.rawResponseParts);
+            // Names cross the engine boundary in their ORIGINAL form.
+            const toolCalls = collected.stepFunctionCalls.map((call, index) => ({
+                id: `${config.providerLabel}_${index}_${call.name}`,
+                name: originalNameFor(call.name),
+                args: call.args,
+            }));
+            return {
+                text,
+                toolCalls,
+                usage: {
+                    inputTokens: collected.inputTokens,
+                    outputTokens: collected.outputTokens,
+                    ...(collected.cacheReadTokens
+                        ? { cacheReadTokens: collected.cacheReadTokens }
+                        : {}),
+                    ...(collected.reasoningTokens
+                        ? { reasoningTokens: collected.reasoningTokens }
+                        : {}),
+                },
+                rawStopReason: collected.finishReason,
+                raw: {
+                    rawResponseParts: collected.rawResponseParts,
+                    stepFunctionCalls: collected.stepFunctionCalls,
+                },
+            };
+        },
+        buildToolResultMessages(conversation, stepResult, toolResults) {
+            // Copied before `pushModelResponseToHistory` mutates it: the engine
+            // treats the conversation as a value it hands in and gets back, so
+            // mutating the caller's array in place would make a retried or
+            // reclaimed step see history it should not.
+            const next = [...conversation];
+            pushModelResponseToHistory(next, stepResult.raw.rawResponseParts, stepResult.raw.stepFunctionCalls);
+            next.push({
+                role: "user",
+                parts: toolResults.map((result) => ({
+                    functionResponse: {
+                        // Back to the sanitized wire name the model actually called.
+                        name: sanitizedNameFor(result.name),
+                        response: result.error
+                            ? { error: result.error }
+                            : { result: result.output },
+                    },
+                })),
+            });
+            return next;
+        },
+        mapFinishReason(rawStopReason, hadToolCallsAtCap) {
+            const mapped = mapGeminiFinishReason(rawStopReason);
+            // A turn cut off at the step cap ended because of the cap, not because
+            // the last response said "STOP".
+            return hadToolCallsAtCap && mapped === "stop" ? "tool-calls" : mapped;
+        },
+    };
+}
+//# sourceMappingURL=geminiLoopAdapter.js.map

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

@@ -22,6 +22,7 @@ import { redactUrlCredentials } from "../../utils/logSanitize.js";
 import { ANTHROPIC_MAX_CACHE_BREAKPOINTS, applyAnthropicHistoryCacheBreakpoints, countAnthropicCacheMarkers, } from "../../utils/anthropicCacheBreakpoints.js";
 import { calculateCost } from "../../utils/pricing.js";
 import { resolveDeferredTool } from "../../tools/toolDiscovery.js";
+import { stringifyAnthropicToolOutput } from "./toolOutput.js";
 import { createAnthropicConfig, getProviderModel, validateApiKey, } from "../../utils/providerConfig.js";
 import { composeAbortSignals, createTimeoutController, mergeAbortSignals, } from "../../utils/timeout.js";
 import { resolveToolChoice } from "../../utils/toolChoice.js";
@@ -183,33 +184,6 @@ const detectAuthMethod = (oauthToken) => {
 // ───────────────────────────────────────────────────────────────────────────
 // Native Messages-API conversion helpers (NeuroLink/V3 shapes → Anthropic)
 // ───────────────────────────────────────────────────────────────────────────
-/** Serialize a tool-result `output` into text for a tool_result block. */
-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 {
-            return JSON.stringify(o.value);
-        }
-        catch {
-            return String(o.value);
-        }
-    }
-    try {
-        return JSON.stringify(output);
-    }
-    catch {
-        return String(output);
-    }
-};
 /**
  * Convert NeuroLink/V3-shaped messages (the shape produced by
  * buildMessagesForStream and by the AI-SDK prompt on the V3 doGenerate path)

package/dist/lib/providers/anthropic/loopAdapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type Anthropic from "@anthropic-ai/sdk";
+import type { AgenticLoopAdapter, AnthropicLoopAdapterConfig } from "../../types/index.js";
+export declare function createAnthropicLoopAdapter(config: AnthropicLoopAdapterConfig): AgenticLoopAdapter<Anthropic.Messages.MessageParam[], Anthropic.Messages.ContentBlockParam[]>;