@juspay/neurolink 11.9.0 → 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/googleNativeGemini3/utils.js

@@ -657,10 +657,18 @@ export async function collectStreamChunksIncremental(stream, channel) {
     let outputTokens = 0;
     let cacheReadTokens = 0;
     let reasoningTokens = 0;
+    // Surfaced so a caller can map SAFETY / MALFORMED_FUNCTION_CALL rather
+    // than inferring the turn ended normally. Additive: existing callers that
+    // ignore it are unaffected.
+    let finishReason;
     for await (const chunk of stream) {
         const chunkRecord = chunk;
         const candidates = chunkRecord.candidates;
         const firstCandidate = candidates?.[0];
+        const candidateFinish = firstCandidate?.finishReason;
+        if (typeof candidateFinish === "string") {
+            finishReason = candidateFinish;
+        }
         const chunkContent = firstCandidate?.content;
         if (chunkContent && Array.isArray(chunkContent.parts)) {
             for (const part of chunkContent.parts) {
@@ -689,6 +697,7 @@ export async function collectStreamChunksIncremental(stream, channel) {
     return {
         rawResponseParts,
         stepFunctionCalls,
+        finishReason,
         inputTokens,
         outputTokens,
         cacheReadTokens,

package/dist/lib/types/loopEngine.d.ts

@@ -1,5 +1,6 @@
 import type Anthropic from "@anthropic-ai/sdk";
 import type { Tool } from "./tools.js";
+import type { NativeFunctionCall, NativeToolDeclarationsResult } from "./providers.js";
 /**
  * One chunk on the engine's stream.
  *
@@ -173,6 +174,94 @@ export type AnthropicLoopAdapterConfig = {
     noteObservedPromptTokens?: (promptTokens: number) => void;
     abortSignal?: AbortSignal;
 };
+/** What one Gemini step produced, carried to `buildToolResultMessages`. */
+export type GeminiStepRaw = {
+    rawResponseParts: unknown[];
+    stepFunctionCalls: NativeFunctionCall[];
+};
+/** One turn entry in a Gemini conversation: a role plus its content parts. */
+export type GeminiTurnContent = {
+    role: string;
+    parts: unknown[];
+};
+/**
+ * Construction input for `createGeminiLoopAdapter`, shared by Google AI Studio
+ * and Vertex Gemini. Both issue `models.generateContentStream` and consume the
+ * same response shape, so one adapter serves four hand-rolled loops.
+ */
+export type GeminiLoopAdapterCoreConfig = {
+    /** Used in log lines and generated tool-call ids. */
+    providerLabel: string;
+    maxSteps: number;
+    /** Build one step's request object (model, contents, config). */
+    buildRequest: (conversation: GeminiTurnContent[], step: number) => unknown;
+    /** Issue the request. Kept injectable so each provider keeps its own client. */
+    sendStep: (request: unknown, signal: AbortSignal) => Promise<AsyncIterable<{
+        functionCalls?: NativeFunctionCall[];
+        [key: string]: unknown;
+    }>>;
+    /**
+     * The turn's live tool record. Mid-turn `search_tools` discovery hydrates
+     * into this, which is what both the declaration refresh and
+     * `resolveToolOnMiss` read.
+     */
+    liveTools: Record<string, Tool>;
+    /**
+     * Declarations built for this turn. Carries `originalNameMap`, which keeps
+     * Google's function-name sanitization on the adapter side of the engine
+     * boundary.
+     */
+    declarations?: NativeToolDeclarationsResult;
+    toolFailureBreaker?: AgenticLoopToolFailureBreaker;
+    /**
+     * In-turn context reclaim, run once per step before the request is built.
+     * Returns the rebuilt conversation when it reclaimed, undefined when the
+     * request still fits.
+     *
+     * Provider-supplied rather than engine-owned because the two Gemini
+     * providers reclaim differently (reclaimAiStudioContext vs
+     * reclaimVertexLoopContext) while the engine only decides WHEN to ask. The
+     * loops append a model turn plus a tool turn every step with nothing else
+     * bounding growth, so a migration that drops this overflows the context
+     * window mid-turn and loses every completed step.
+     */
+    planReclaim?: (conversation: GeminiTurnContent[], step: number) => GeminiTurnContent[] | undefined;
+    /**
+     * Usage feedback for the provider's own context guard, called after each
+     * step with that step's real token counts.
+     */
+    noteUsage?: (inputTokens: number, outputTokens: number) => void;
+};
+/**
+ * Opt in to the single MALFORMED_FUNCTION_CALL retry.
+ *
+ * Vertex Gemini only. AI Studio has no such retry today (confirmed: zero
+ * MALFORMED_FUNCTION_CALL handling in its client), and turning it on there
+ * would be a behaviour change disguised as a shared refactor. The engine owns
+ * the one-retry budget; this only says whether to ask.
+ *
+ * A union rather than two independent optional fields because the retry is
+ * only worth spending a step on if the re-issued request differs from the one
+ * that just failed. `runAgenticLoop` falls back to the unchanged conversation
+ * when no note builder is supplied (`buildMalformedRetryNote?.(…) ??
+ * conversation`), so enabling the retry without one re-sends a byte-identical
+ * request and most often reproduces the same malformed call — a step burned
+ * for nothing. Requiring the builder here makes that combination unsayable
+ * instead of merely discouraged.
+ */
+export type GeminiMalformedRetryConfig = {
+    enableMalformedRetry: true;
+    /**
+     * Append the corrective turn that the retry re-issues with.
+     * Provider-supplied because the note is written in the provider's own
+     * content shape.
+     */
+    buildMalformedRetryNote: (conversation: GeminiTurnContent[]) => GeminiTurnContent[];
+} | {
+    enableMalformedRetry?: false;
+    buildMalformedRetryNote?: never;
+};
+export type GeminiLoopAdapterConfig = GeminiLoopAdapterCoreConfig & GeminiMalformedRetryConfig;
 export type AgenticLoopOptions = {
     tools?: Record<string, {
         execute?: (args: Record<string, unknown>, opts: unknown) => Promise<unknown>;

package/dist/lib/types/providers.d.ts

@@ -1738,6 +1738,8 @@ export type NativeFunctionResponse = {
 export type CollectedChunkResult = {
     rawResponseParts: unknown[];
     stepFunctionCalls: NativeFunctionCall[];
+    /** Raw `Candidate.finishReason` from the last chunk that carried one. */
+    finishReason?: string;
     inputTokens: number;
     outputTokens: number;
     /**

package/dist/providers/googleNativeGemini3/utils.js

@@ -657,10 +657,18 @@ export async function collectStreamChunksIncremental(stream, channel) {
     let outputTokens = 0;
     let cacheReadTokens = 0;
     let reasoningTokens = 0;
+    // Surfaced so a caller can map SAFETY / MALFORMED_FUNCTION_CALL rather
+    // than inferring the turn ended normally. Additive: existing callers that
+    // ignore it are unaffected.
+    let finishReason;
     for await (const chunk of stream) {
         const chunkRecord = chunk;
         const candidates = chunkRecord.candidates;
         const firstCandidate = candidates?.[0];
+        const candidateFinish = firstCandidate?.finishReason;
+        if (typeof candidateFinish === "string") {
+            finishReason = candidateFinish;
+        }
         const chunkContent = firstCandidate?.content;
         if (chunkContent && Array.isArray(chunkContent.parts)) {
             for (const part of chunkContent.parts) {
@@ -689,6 +697,7 @@ export async function collectStreamChunksIncremental(stream, channel) {
     return {
         rawResponseParts,
         stepFunctionCalls,
+        finishReason,
         inputTokens,
         outputTokens,
         cacheReadTokens,

package/dist/types/loopEngine.d.ts

@@ -1,5 +1,6 @@
 import type Anthropic from "@anthropic-ai/sdk";
 import type { Tool } from "./tools.js";
+import type { NativeFunctionCall, NativeToolDeclarationsResult } from "./providers.js";
 /**
  * One chunk on the engine's stream.
  *
@@ -173,6 +174,94 @@ export type AnthropicLoopAdapterConfig = {
     noteObservedPromptTokens?: (promptTokens: number) => void;
     abortSignal?: AbortSignal;
 };
+/** What one Gemini step produced, carried to `buildToolResultMessages`. */
+export type GeminiStepRaw = {
+    rawResponseParts: unknown[];
+    stepFunctionCalls: NativeFunctionCall[];
+};
+/** One turn entry in a Gemini conversation: a role plus its content parts. */
+export type GeminiTurnContent = {
+    role: string;
+    parts: unknown[];
+};
+/**
+ * Construction input for `createGeminiLoopAdapter`, shared by Google AI Studio
+ * and Vertex Gemini. Both issue `models.generateContentStream` and consume the
+ * same response shape, so one adapter serves four hand-rolled loops.
+ */
+export type GeminiLoopAdapterCoreConfig = {
+    /** Used in log lines and generated tool-call ids. */
+    providerLabel: string;
+    maxSteps: number;
+    /** Build one step's request object (model, contents, config). */
+    buildRequest: (conversation: GeminiTurnContent[], step: number) => unknown;
+    /** Issue the request. Kept injectable so each provider keeps its own client. */
+    sendStep: (request: unknown, signal: AbortSignal) => Promise<AsyncIterable<{
+        functionCalls?: NativeFunctionCall[];
+        [key: string]: unknown;
+    }>>;
+    /**
+     * The turn's live tool record. Mid-turn `search_tools` discovery hydrates
+     * into this, which is what both the declaration refresh and
+     * `resolveToolOnMiss` read.
+     */
+    liveTools: Record<string, Tool>;
+    /**
+     * Declarations built for this turn. Carries `originalNameMap`, which keeps
+     * Google's function-name sanitization on the adapter side of the engine
+     * boundary.
+     */
+    declarations?: NativeToolDeclarationsResult;
+    toolFailureBreaker?: AgenticLoopToolFailureBreaker;
+    /**
+     * In-turn context reclaim, run once per step before the request is built.
+     * Returns the rebuilt conversation when it reclaimed, undefined when the
+     * request still fits.
+     *
+     * Provider-supplied rather than engine-owned because the two Gemini
+     * providers reclaim differently (reclaimAiStudioContext vs
+     * reclaimVertexLoopContext) while the engine only decides WHEN to ask. The
+     * loops append a model turn plus a tool turn every step with nothing else
+     * bounding growth, so a migration that drops this overflows the context
+     * window mid-turn and loses every completed step.
+     */
+    planReclaim?: (conversation: GeminiTurnContent[], step: number) => GeminiTurnContent[] | undefined;
+    /**
+     * Usage feedback for the provider's own context guard, called after each
+     * step with that step's real token counts.
+     */
+    noteUsage?: (inputTokens: number, outputTokens: number) => void;
+};
+/**
+ * Opt in to the single MALFORMED_FUNCTION_CALL retry.
+ *
+ * Vertex Gemini only. AI Studio has no such retry today (confirmed: zero
+ * MALFORMED_FUNCTION_CALL handling in its client), and turning it on there
+ * would be a behaviour change disguised as a shared refactor. The engine owns
+ * the one-retry budget; this only says whether to ask.
+ *
+ * A union rather than two independent optional fields because the retry is
+ * only worth spending a step on if the re-issued request differs from the one
+ * that just failed. `runAgenticLoop` falls back to the unchanged conversation
+ * when no note builder is supplied (`buildMalformedRetryNote?.(…) ??
+ * conversation`), so enabling the retry without one re-sends a byte-identical
+ * request and most often reproduces the same malformed call — a step burned
+ * for nothing. Requiring the builder here makes that combination unsayable
+ * instead of merely discouraged.
+ */
+export type GeminiMalformedRetryConfig = {
+    enableMalformedRetry: true;
+    /**
+     * Append the corrective turn that the retry re-issues with.
+     * Provider-supplied because the note is written in the provider's own
+     * content shape.
+     */
+    buildMalformedRetryNote: (conversation: GeminiTurnContent[]) => GeminiTurnContent[];
+} | {
+    enableMalformedRetry?: false;
+    buildMalformedRetryNote?: never;
+};
+export type GeminiLoopAdapterConfig = GeminiLoopAdapterCoreConfig & GeminiMalformedRetryConfig;
 export type AgenticLoopOptions = {
     tools?: Record<string, {
         execute?: (args: Record<string, unknown>, opts: unknown) => Promise<unknown>;

package/dist/types/providers.d.ts

@@ -1738,6 +1738,8 @@ export type NativeFunctionResponse = {
 export type CollectedChunkResult = {
     rawResponseParts: unknown[];
     stepFunctionCalls: NativeFunctionCall[];
+    /** Raw `Candidate.finishReason` from the last chunk that carried one. */
+    finishReason?: string;
     inputTokens: number;
     outputTokens: number;
     /**

package/package.json

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