@juspay/neurolink 11.2.4 → 11.3.0

package/dist/core/loopEngine.d.ts

@@ -0,0 +1,23 @@
+import type { AgenticLoopAdapter, AgenticLoopOptions, AgenticLoopResult } from "../types/index.js";
+/**
+ * Run one adapter-parameterized agentic tool-calling turn. Owns the
+ * maxSteps-bounded loop, generic tool dispatch (with an opt-in
+ * TOOL_NOT_FOUND/failure-strike breaker — see AgenticLoopAdapter.toolFailureBreaker),
+ * per-step usage accumulation, a single optional malformed-call retry,
+ * chunk emission through streamChannel, and a pre-first-chunk 429/5xx
+ * retry (via withProviderRetry) around every adapter.executeStep() call.
+ * The retry wrap is unconditional and adapter-agnostic — every migrated
+ * provider gets it for free, not just the ones that had a hand-rolled
+ * version before migration (see Verified Fact 4-adjacent note in Task 4
+ * Step 1 and the Risks & Rollback "Deliberate behavior changes" list for
+ * which families are gaining this for the first time). Everything
+ * wire-format-specific (building the request, parsing the SDK response,
+ * serializing tool results back into the conversation, mapping the raw
+ * stop reason) is delegated to `adapter`.
+ */
+export declare function runAgenticLoop<TConversation>(adapter: AgenticLoopAdapter<TConversation>, initialConversation: TConversation, options: AgenticLoopOptions): {
+    stream: AsyncIterable<{
+        content: string;
+    }>;
+    resultPromise: Promise<AgenticLoopResult<TConversation>>;
+};

package/dist/core/loopEngine.js

@@ -0,0 +1,245 @@
+import { createStreamChannel } from "./streamChannel.js";
+import { logger } from "../utils/logger.js";
+import { withProviderRetry } from "../utils/providerRetry.js";
+/**
+ * Marks a step error that occurred AFTER at least one chunk had already
+ * been streamed to the consumer for this step. Retrying at that point
+ * would duplicate or interleave already-emitted output, so this wrapper
+ * deliberately carries none of the original error's status/retry
+ * metadata (`.statusCode`/`.status`, no APICallError/NeuroLinkError
+ * branding) — that makes `withProviderRetry`'s internal
+ * `isRetryableProviderError()` check return false via its duck-typed
+ * fallback, which ends the retry loop on the very next classification
+ * instead of sleeping and re-invoking `adapter.executeStep`. The engine
+ * unwraps back to the original `cause` before it ever reaches the
+ * caller — see the try/catch around the `withProviderRetry` call below.
+ */
+class PostEmissionStepError extends Error {
+    cause;
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.cause = cause;
+    }
+}
+function sumUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        cacheReadTokens: (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0) || undefined,
+        cacheWriteTokens: (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0) || undefined,
+        reasoningTokens: (a.reasoningTokens ?? 0) + (b.reasoningTokens ?? 0) || undefined,
+    };
+}
+/**
+ * Run one adapter-parameterized agentic tool-calling turn. Owns the
+ * maxSteps-bounded loop, generic tool dispatch (with an opt-in
+ * TOOL_NOT_FOUND/failure-strike breaker — see AgenticLoopAdapter.toolFailureBreaker),
+ * per-step usage accumulation, a single optional malformed-call retry,
+ * chunk emission through streamChannel, and a pre-first-chunk 429/5xx
+ * retry (via withProviderRetry) around every adapter.executeStep() call.
+ * The retry wrap is unconditional and adapter-agnostic — every migrated
+ * provider gets it for free, not just the ones that had a hand-rolled
+ * version before migration (see Verified Fact 4-adjacent note in Task 4
+ * Step 1 and the Risks & Rollback "Deliberate behavior changes" list for
+ * which families are gaining this for the first time). Everything
+ * wire-format-specific (building the request, parsing the SDK response,
+ * serializing tool results back into the conversation, mapping the raw
+ * stop reason) is delegated to `adapter`.
+ */
+export function runAgenticLoop(adapter, initialConversation, options) {
+    const channel = createStreamChannel();
+    const internalAbort = new AbortController();
+    const onCallerAbort = () => internalAbort.abort();
+    options.abortSignal?.addEventListener("abort", onCallerAbort);
+    if (options.abortSignal?.aborted) {
+        internalAbort.abort();
+    }
+    const failedTools = new Map();
+    let malformedRetryUsed = false;
+    const resultPromise = (async () => {
+        let conversation = initialConversation;
+        let usage = { inputTokens: 0, outputTokens: 0 };
+        let finalText = "";
+        let rawStopReason;
+        const allToolCalls = [];
+        const allToolExecutions = [];
+        let hadToolCallsAtCap = false;
+        try {
+            for (let step = 0; step < adapter.maxSteps; step++) {
+                if (internalAbort.signal.aborted) {
+                    break;
+                }
+                if (adapter.planReclaim) {
+                    const reclaimed = adapter.planReclaim(conversation, step);
+                    if (reclaimed) {
+                        conversation = reclaimed.conversation;
+                    }
+                }
+                const request = adapter.buildStepRequest(conversation, step);
+                // Pre-first-chunk 429/5xx retry: watch whether THIS attempt of
+                // THIS step pushes anything to the shared channel before it
+                // throws. `hasEmitted` resets at the top of every attempt
+                // withProviderRetry makes; the instant an attempt emits and then
+                // throws, the thrown error is rewrapped as a PostEmissionStepError
+                // (no status/branding info survives the rewrap), which
+                // isRetryableProviderError() duck-types as non-retryable — so
+                // withProviderRetry gives up immediately instead of sleeping and
+                // re-invoking executeStep, which would duplicate/interleave
+                // output already sent to the consumer. The original error (not
+                // the wrapper) is what the caller of runAgenticLoop ultimately
+                // sees, via the unwrap in the catch below.
+                let hasEmitted = false;
+                const watchedChannel = {
+                    push: (chunk) => {
+                        hasEmitted = true;
+                        channel.push(chunk);
+                    },
+                };
+                let stepResult;
+                try {
+                    stepResult = await withProviderRetry(async () => {
+                        hasEmitted = false;
+                        try {
+                            return await adapter.executeStep(request, watchedChannel, internalAbort.signal);
+                        }
+                        catch (err) {
+                            throw hasEmitted ? new PostEmissionStepError(err) : err;
+                        }
+                    }, undefined, // no OTel span threaded through the engine today; adapters instrument their own steps if they need span-level detail
+                    `${adapter.providerLabel}.step`);
+                }
+                catch (err) {
+                    throw err instanceof PostEmissionStepError ? err.cause : err;
+                }
+                usage = sumUsage(usage, stepResult.usage);
+                rawStopReason = stepResult.rawStopReason;
+                if (adapter.isMalformedStep?.(stepResult) &&
+                    !malformedRetryUsed &&
+                    !internalAbort.signal.aborted) {
+                    malformedRetryUsed = true;
+                    logger.warn(`[${adapter.providerLabel}] Malformed function call at step ${step + 1}/${adapter.maxSteps}; retrying once.`);
+                    conversation =
+                        adapter.buildMalformedRetryNote?.(conversation) ?? conversation;
+                    continue;
+                }
+                if (stepResult.toolCalls.length === 0) {
+                    finalText = stepResult.text || finalText;
+                    break;
+                }
+                if (step === adapter.maxSteps - 1) {
+                    hadToolCallsAtCap = true;
+                }
+                const toolResults = [];
+                for (const call of stepResult.toolCalls) {
+                    allToolCalls.push(call);
+                    const breaker = adapter.toolFailureBreaker;
+                    const failInfo = breaker ? failedTools.get(call.name) : undefined;
+                    if (breaker && failInfo && failInfo.count >= breaker.maxRetries) {
+                        const output = {
+                            error: `TOOL_PERMANENTLY_FAILED: "${call.name}" has failed ${failInfo.count} times. Last error: ${failInfo.lastError}.`,
+                            status: "permanently_failed",
+                            do_not_retry: true,
+                        };
+                        toolResults.push({
+                            ...call,
+                            output,
+                            error: output.error,
+                            permanentlyFailed: true,
+                        });
+                        allToolExecutions.push({
+                            name: call.name,
+                            input: call.args,
+                            output,
+                        });
+                        continue;
+                    }
+                    const tool = options.tools?.[call.name];
+                    if (!tool?.execute) {
+                        const output = breaker
+                            ? {
+                                error: `TOOL_NOT_FOUND: "${call.name}" does not exist.`,
+                                status: "permanently_failed",
+                                do_not_retry: true,
+                            }
+                            : { error: `Tool not found: ${call.name}` };
+                        toolResults.push({
+                            ...call,
+                            output,
+                            error: output.error,
+                            permanentlyFailed: !!breaker,
+                        });
+                        allToolExecutions.push({
+                            name: call.name,
+                            input: call.args,
+                            output,
+                        });
+                        continue;
+                    }
+                    try {
+                        const output = await tool.execute(call.args, {
+                            toolCallId: call.id,
+                            abortSignal: internalAbort.signal,
+                        });
+                        toolResults.push({ ...call, output });
+                        allToolExecutions.push({
+                            name: call.name,
+                            input: call.args,
+                            output,
+                        });
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        if (breaker) {
+                            const current = failedTools.get(call.name) ?? {
+                                count: 0,
+                                lastError: "",
+                            };
+                            current.count++;
+                            current.lastError = message;
+                            failedTools.set(call.name, current);
+                        }
+                        const output = { error: message, status: "failed" };
+                        toolResults.push({ ...call, output, error: message });
+                        allToolExecutions.push({
+                            name: call.name,
+                            input: call.args,
+                            output,
+                        });
+                    }
+                }
+                conversation = adapter.buildToolResultMessages(conversation, stepResult, toolResults);
+            }
+            const finishReason = adapter.mapFinishReason(rawStopReason, hadToolCallsAtCap);
+            return {
+                text: finalText,
+                toolCalls: allToolCalls,
+                toolExecutions: allToolExecutions,
+                usage,
+                finishReason,
+                rawStopReason,
+                conversation,
+            };
+        }
+        catch (err) {
+            // Must run before the finally block's channel.close(): a consumer
+            // parked in the channel's iterable is woken by whichever of
+            // error()/close() runs first, and close() alone would let a
+            // stream-only consumer observe a clean end of stream for a turn that
+            // actually failed. Calling error() here — synchronously, inside this
+            // catch — guarantees it lands before close(), with no dependence on
+            // microtask scheduling (unlike an outer promise-chained catch handler
+            // on this IIFE, which would run in a later microtask after `finally`
+            // already closed the channel).
+            channel.error(err);
+            throw err;
+        }
+        finally {
+            // close() after error() is harmless: it only flips `done`, and
+            // streamChannel.error() keeps its error state intact regardless of a
+            // later close() call.
+            channel.close();
+            options.abortSignal?.removeEventListener("abort", onCallerAbort);
+        }
+    })();
+    return { stream: channel.iterable, resultPromise };
+}

package/dist/core/nativeToolFormat.d.ts

@@ -0,0 +1,33 @@
+import type { NativeAnthropicToolDeclaration, NativeToolDeclarationsResult, Tool } from "../types/index.js";
+/**
+ * Convert a NeuroLink tool record into the wire-format a native
+ * (non-AI-SDK) provider SDK expects. Absorbs the direct-Anthropic
+ * provider's `toolsToAnthropic` — previously duplicated between the
+ * streaming loop's pre-loop snapshot and its mid-turn discovery-hydration
+ * call site (both in anthropic/client.ts). Gemini's `functionDeclarations`
+ * shape was already centralized in `buildNativeToolDeclarations`; this
+ * function is a thin facade over it so every native provider calls one
+ * entry point.
+ *
+ * Scope note: Vertex's Claude-on-Vertex `input_schema` builder
+ * (`buildAnthropicToolDeclaration` in googleVertex/client.ts) is
+ * deliberately NOT routed through this function. Despite the superficial
+ * similarity, it is not a byte-for-byte duplicate of `toolsToAnthropic`: it
+ * strips the converted schema down to `{type, properties, required}` only
+ * (dropping any other JSON-Schema keywords `convertZodToJsonSchema` may
+ * produce), it always runs `inlineJsonSchema` (Anthropic-direct never has),
+ * it prefers `parameters` over `inputSchema` (the opposite fallback order
+ * from Anthropic-direct), and it has no `cache_control` support of its own
+ * because Vertex applies cache breakpoints later via the separate
+ * `applyVertexAnthropicCacheBreakpoints` pass. Collapsing these into one
+ * shared implementation would risk a live tool-calling regression on one
+ * provider or the other; see the Task 2 report for the full comparison.
+ *
+ * These are genuine TS overload declarations, not redeclarations: the base
+ * `no-redeclare` ESLint rule doesn't understand the overload-signatures +
+ * implementation pattern (the TS-aware `@typescript-eslint/no-redeclare`
+ * variant would, but isn't enabled project-wide), so each signature below
+ * is individually exempted.
+ */
+export declare function toNativeToolDeclarations(tools: Record<string, Tool>, format: "input_schema"): NativeAnthropicToolDeclaration[] | undefined;
+export declare function toNativeToolDeclarations(tools: Record<string, Tool>, format: "functionDeclarations"): NativeToolDeclarationsResult;

package/dist/core/nativeToolFormat.js

@@ -0,0 +1,30 @@
+import { buildNativeToolDeclarations } from "../providers/googleNativeGemini3/utils.js";
+import { cacheControlOf } from "../providers/anthropic/cacheControl.js";
+import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
+// eslint-disable-next-line no-redeclare -- TS overload implementation signature, not a redeclaration
+export function toNativeToolDeclarations(tools, format) {
+    if (format === "functionDeclarations") {
+        return buildNativeToolDeclarations(tools);
+    }
+    const entries = Object.entries(tools ?? {});
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return entries.map(([name, tool]) => {
+        const t = tool;
+        const rawSchema = t.inputSchema ?? t.parameters;
+        const input_schema = (rawSchema
+            ? convertZodToJsonSchema(rawSchema)
+            : { type: "object", properties: {} });
+        // GenerationHandler marks the last tool definition with a cache
+        // breakpoint when prompt caching is active — keep honoring it.
+        const cc = cacheControlOf(tool);
+        const declaration = {
+            name,
+            ...(t.description ? { description: t.description } : {}),
+            input_schema,
+            ...(cc ? { cache_control: cc } : {}),
+        };
+        return declaration;
+    });
+}

package/dist/core/streamChannel.d.ts

@@ -0,0 +1,10 @@
+import type { StreamChannel } from "../types/index.js";
+/**
+ * Create a push-based channel bridging a background producer (an agentic
+ * tool-calling loop) with an async-iterable consumer, enabling truly
+ * incremental streaming: values are yielded to the caller as they arrive
+ * rather than being buffered until the producer finishes.
+ */
+export declare function createStreamChannel<T = {
+    content: string;
+}>(): StreamChannel<T>;

package/dist/core/streamChannel.js

@@ -0,0 +1,76 @@
+/**
+ * Create a push-based channel bridging a background producer (an agentic
+ * tool-calling loop) with an async-iterable consumer, enabling truly
+ * incremental streaming: values are yielded to the caller as they arrive
+ * rather than being buffered until the producer finishes.
+ */
+export function createStreamChannel() {
+    const queue = [];
+    let done = false;
+    let fatalError = undefined;
+    // Tracked separately from `fatalError`: a producer can legitimately
+    // reject with `undefined` (e.g. `throw undefined`), and `fatalError !==
+    // undefined` would then be indistinguishable from "no error occurred",
+    // closing the stream cleanly instead of surfacing the failure.
+    let hasError = false;
+    let notify = null;
+    function wake() {
+        if (notify) {
+            const fn = notify;
+            notify = null;
+            fn();
+        }
+    }
+    function push(value) {
+        if (done) {
+            return;
+        }
+        queue.push(value);
+        wake();
+    }
+    function close() {
+        done = true;
+        wake();
+    }
+    function error(err) {
+        done = true;
+        fatalError = err;
+        hasError = true;
+        wake();
+    }
+    let readIndex = 0;
+    async function* iterable() {
+        try {
+            while (true) {
+                if (readIndex < queue.length) {
+                    yield queue[readIndex++];
+                    // Periodically compact consumed entries to avoid unbounded retention.
+                    if (readIndex > 1024 && readIndex * 2 >= queue.length) {
+                        queue.splice(0, readIndex);
+                        readIndex = 0;
+                    }
+                }
+                else if (done) {
+                    if (hasError) {
+                        throw fatalError instanceof Error
+                            ? fatalError
+                            : new Error(String(fatalError));
+                    }
+                    return;
+                }
+                else {
+                    await new Promise((resolve) => {
+                        notify = resolve;
+                    });
+                }
+            }
+        }
+        finally {
+            // Consumer stopped reading (disconnect/cancel): stop buffering.
+            done = true;
+            queue.length = 0;
+            notify?.();
+        }
+    }
+    return { push, close, error, iterable: iterable() };
+}

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

@@ -0,0 +1,23 @@
+import type { AgenticLoopAdapter, AgenticLoopOptions, AgenticLoopResult } from "../types/index.js";
+/**
+ * Run one adapter-parameterized agentic tool-calling turn. Owns the
+ * maxSteps-bounded loop, generic tool dispatch (with an opt-in
+ * TOOL_NOT_FOUND/failure-strike breaker — see AgenticLoopAdapter.toolFailureBreaker),
+ * per-step usage accumulation, a single optional malformed-call retry,
+ * chunk emission through streamChannel, and a pre-first-chunk 429/5xx
+ * retry (via withProviderRetry) around every adapter.executeStep() call.
+ * The retry wrap is unconditional and adapter-agnostic — every migrated
+ * provider gets it for free, not just the ones that had a hand-rolled
+ * version before migration (see Verified Fact 4-adjacent note in Task 4
+ * Step 1 and the Risks & Rollback "Deliberate behavior changes" list for
+ * which families are gaining this for the first time). Everything
+ * wire-format-specific (building the request, parsing the SDK response,
+ * serializing tool results back into the conversation, mapping the raw
+ * stop reason) is delegated to `adapter`.
+ */
+export declare function runAgenticLoop<TConversation>(adapter: AgenticLoopAdapter<TConversation>, initialConversation: TConversation, options: AgenticLoopOptions): {
+    stream: AsyncIterable<{
+        content: string;
+    }>;
+    resultPromise: Promise<AgenticLoopResult<TConversation>>;
+};