@juspay/neurolink 12.21.1 → 12.22.0

package/dist/providers/googleNativeGemini3/utils.d.ts

@@ -250,6 +250,28 @@ export declare function buildTurnStalledMessage(stallTimeoutMs: number, toolCall
  * short-circuit — stopReason "aborted").
  */
 export declare function buildAbortedTurnMessage(toolCallCount: number): string;
+/**
+ * Pick the honest terminal message for a native-loop exit by its ACTUAL
+ * cause. The step-cap text is the fallback for genuine budget exhaustion
+ * only — time/stall/abort exits must never claim a step limit was reached
+ * (the 2026-07-03 "reached the 200-step limit" incident was a wall-clock
+ * abort wearing the cap message).
+ *
+ * Takes plain booleans rather than a turn clock so a loop whose wall-clock
+ * deadline is owned by something other than `createTurnClock` — AI Studio's
+ * pre-existing per-request timeout controller — can report through the same
+ * builders instead of growing a second set.
+ */
+export declare function buildLoopExitMessage(params: {
+    timedOut: boolean;
+    stalled: boolean;
+    /** Turn duration so far, for the time-limit message. */
+    elapsedMs: number;
+    wasAborted: boolean;
+    stallTimeoutMs?: number;
+    maxSteps: number;
+    toolCallCount: number;
+}): string;
 /**
  * Wrap-up nudge injected when the remaining turn time drops inside the
  * `wrapupTimeLeadMs` window — the time-budget twin of the soft step-budget

package/dist/providers/googleNativeGemini3/utils.js

@@ -922,6 +922,30 @@ export function buildAbortedTurnMessage(toolCallCount) {
         : "";
     return `This turn was stopped before I could finish.${calls}`;
 }
+/**
+ * Pick the honest terminal message for a native-loop exit by its ACTUAL
+ * cause. The step-cap text is the fallback for genuine budget exhaustion
+ * only — time/stall/abort exits must never claim a step limit was reached
+ * (the 2026-07-03 "reached the 200-step limit" incident was a wall-clock
+ * abort wearing the cap message).
+ *
+ * Takes plain booleans rather than a turn clock so a loop whose wall-clock
+ * deadline is owned by something other than `createTurnClock` — AI Studio's
+ * pre-existing per-request timeout controller — can report through the same
+ * builders instead of growing a second set.
+ */
+export function buildLoopExitMessage(params) {
+    if (params.timedOut) {
+        return buildTurnTimeoutMessage(params.elapsedMs, params.toolCallCount);
+    }
+    if (params.stalled) {
+        return buildTurnStalledMessage(params.stallTimeoutMs ?? 0, params.toolCallCount);
+    }
+    if (params.wasAborted) {
+        return buildAbortedTurnMessage(params.toolCallCount);
+    }
+    return buildToolLoopCapMessage(params.maxSteps, params.toolCallCount);
+}
 /**
  * Wrap-up nudge injected when the remaining turn time drops inside the
  * `wrapupTimeLeadMs` window — the time-budget twin of the soft step-budget

package/dist/providers/googleVertex/client.d.ts

@@ -300,18 +300,9 @@ export declare class GoogleVertexProvider extends BaseProvider {
      */
     private emitGenerationEnd;
     /**
-     * Emit a `turn:lifecycle` event on the SDK emitter (alongside
-     * tool:start/tool:end) so loop conditions that previously only reached
-     * process logs — step-cap, time-limit, stall, abort, tool timeouts,
-     * malformed-call retries — are observable by consumers' own pipelines.
-     */
-    private emitTurnEvent;
-    /**
-     * Pick the honest terminal message for a native-loop exit by its ACTUAL
-     * cause. The step-cap text is the fallback for genuine budget exhaustion
-     * only — time/stall/abort exits must never claim a step limit was reached
-     * (the 2026-07-03 "reached the 200-step limit" incident was a wall-clock
-     * abort wearing the cap message).
+     * Turn-clock-shaped adapter over the shared {@link buildLoopExitMessage}.
+     * Every call site in this file holds a clock, so the mapping lives here
+     * rather than at ten call sites; the decision itself is the shared one.
      */
     private buildLoopExitMessage;
     protected formatProviderError(error: unknown): Error;

package/dist/providers/googleVertex/client.js

@@ -32,7 +32,7 @@ import { convertZodToJsonSchema, inlineJsonSchema, ensureNestedSchemaTypes, } fr
 import { createNativeThinkingConfig } from "../../utils/thinkingConfig.js";
 import { TimeoutError, withTimeout } from "../../utils/async/index.js";
 import { parseTimeout } from "../../utils/timeout.js";
-import { appendStepText, buildAbortedTurnMessage, buildContextCapMessage, buildDedupedEngineTools, buildToolLoopCapMessage, buildTurnStalledMessage, buildTurnTimeoutMessage, buildWrapupNudgeText, createContextGuard, createTurnClock, extractThoughtSignature, isAbortError, mapGeminiFinishReason, prependConversationMessages, resolveTurnStopReason, DedupExecuteMap, } from "../googleNativeGemini3/index.js";
+import { appendStepText, buildContextCapMessage, buildDedupedEngineTools, buildLoopExitMessage, buildToolLoopCapMessage, buildWrapupNudgeText, createContextGuard, createTurnClock, extractThoughtSignature, isAbortError, mapGeminiFinishReason, prependConversationMessages, resolveTurnStopReason, DedupExecuteMap, } from "../googleNativeGemini3/index.js";
 import { createGeminiLoopAdapter } from "../../core/geminiLoopAdapter.js";
 import { runAgenticLoop } from "../../core/loopEngine.js";
 import { createAnthropicLoopAdapter } from "../anthropic/loopAdapter.js";
@@ -5697,41 +5697,22 @@ export class GoogleVertexProvider extends BaseProvider {
         }
     }
     /**
-     * Emit a `turn:lifecycle` event on the SDK emitter (alongside
-     * tool:start/tool:end) so loop conditions that previously only reached
-     * process logs — step-cap, time-limit, stall, abort, tool timeouts,
-     * malformed-call retries — are observable by consumers' own pipelines.
-     */
-    emitTurnEvent(payload) {
-        try {
-            this.neurolink?.getEventEmitter()?.emit("turn:lifecycle", {
-                provider: this.providerName,
-                timestamp: Date.now(),
-                ...payload,
-            });
-        }
-        catch {
-            /* listener errors are non-fatal */
-        }
-    }
-    /**
-     * Pick the honest terminal message for a native-loop exit by its ACTUAL
-     * cause. The step-cap text is the fallback for genuine budget exhaustion
-     * only — time/stall/abort exits must never claim a step limit was reached
-     * (the 2026-07-03 "reached the 200-step limit" incident was a wall-clock
-     * abort wearing the cap message).
+     * Turn-clock-shaped adapter over the shared {@link buildLoopExitMessage}.
+     * Every call site in this file holds a clock, so the mapping lives here
+     * rather than at ten call sites; the decision itself is the shared one.
      */
     buildLoopExitMessage(params) {
-        if (params.turnClock.timedOut) {
-            return buildTurnTimeoutMessage(params.turnClock.elapsedMs(), params.toolCallCount);
-        }
-        if (params.turnClock.stalled) {
-            return buildTurnStalledMessage(params.stallTimeoutMs ?? 0, params.toolCallCount);
-        }
-        if (params.wasAborted) {
-            return buildAbortedTurnMessage(params.toolCallCount);
-        }
-        return buildToolLoopCapMessage(params.maxSteps, params.toolCallCount);
+        return buildLoopExitMessage({
+            timedOut: params.turnClock.timedOut,
+            stalled: params.turnClock.stalled,
+            elapsedMs: params.turnClock.elapsedMs(),
+            wasAborted: params.wasAborted,
+            ...(params.stallTimeoutMs !== undefined
+                ? { stallTimeoutMs: params.stallTimeoutMs }
+                : {}),
+            maxSteps: params.maxSteps,
+            toolCallCount: params.toolCallCount,
+        });
     }
     formatProviderError(error) {
         const errorRecord = error;

package/dist/providers/openaiChatCompletionsClient.js

@@ -193,7 +193,14 @@ export const convertContentForOpenAI = (content) => {
             const data = part.image ??
                 part.data ??
                 part.url;
-            const url = imageDataToURL(data);
+            // ImagePart carries the resolved format as `mediaType` (MessageBuilder
+            // canonicalizes to it); `mimeType` is accepted for parts that bypass
+            // that normalization. Without this, a raw base64 payload (as opposed to
+            // an already-labelled data: URI) always fell back to imageDataToURL's
+            // hardcoded "image/png" default, mislabeling real JPEG/WebP/etc bytes.
+            const mediaType = part.mediaType ??
+                part.mimeType;
+            const url = imageDataToURL(data, mediaType);
             if (url) {
                 out.push({ type: "image_url", image_url: { url } });
             }

package/dist/utils/stringDistance.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared string-distance helpers for "did you mean?" suggestions.
+ *
+ * Extracted from toolCallRepair.ts, which had the only implementation, so
+ * provider-name validation can reuse it rather than carry a second copy.
+ */
+/**
+ * Longest string the distance primitive will compare.
+ *
+ * Exported so every call site can apply the same limit *before* calling
+ * `levenshtein` — skipping an over-limit operand entirely, rather than
+ * comparing a truncated prefix of it. Truncating silently merged any two
+ * strings that happened to share their first `MAX_COMPARABLE_LENGTH`
+ * characters into distance 0, which let a direct MCP tool-name lookup
+ * (`resolveToolName`) resolve to the wrong tool for a long, colliding name.
+ */
+export declare const MAX_COMPARABLE_LENGTH = 128;
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * Uses the iterative matrix approach — O(m*n) time, O(min(m,n)) space.
+ *
+ * Throws rather than truncating when either input exceeds
+ * `MAX_COMPARABLE_LENGTH`: silently comparing truncated prefixes produces a
+ * *wrong* distance (two distinct strings sharing a long prefix collapse to
+ * distance 0) instead of no distance, which is worse than refusing outright.
+ * Callers that want fuzzy matching over long input must apply the length
+ * check themselves and skip the comparison — see `suggestClosest` below and
+ * `resolveToolName`/`rankToolNameCandidates` in toolCallRepair.ts.
+ */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Candidates within `maxDistance` edits of `input`, closest first.
+ *
+ * Ties break on the candidate's own order in `candidates`, so a caller that
+ * passes canonical names before aliases gets the canonical one suggested.
+ * Comparison is case-insensitive; the returned strings keep their original
+ * casing so they can be pasted back verbatim.
+ *
+ * `input` longer than `MAX_COMPARABLE_LENGTH` is rejected outright (no
+ * suggestions), and any individual candidate over the same limit is skipped
+ * rather than compared — never truncated. Truncating either side risks
+ * exactly the false distance-0 match `levenshtein`'s guard rejects: two
+ * distinct strings sharing a long-enough prefix would otherwise look
+ * identical and "suggest" the wrong one.
+ *
+ * @param input - The string the user actually typed
+ * @param candidates - Valid values, most-preferred first
+ * @param options.maxDistance - Edit budget (default 3)
+ * @param options.limit - Most suggestions to return (default 3)
+ */
+export declare function suggestClosest(input: string, candidates: readonly string[], options?: {
+    maxDistance?: number;
+    limit?: number;
+}): string[];

package/dist/utils/stringDistance.js

@@ -0,0 +1,133 @@
+/**
+ * Shared string-distance helpers for "did you mean?" suggestions.
+ *
+ * Extracted from toolCallRepair.ts, which had the only implementation, so
+ * provider-name validation can reuse it rather than carry a second copy.
+ */
+/**
+ * Longest string the distance primitive will compare.
+ *
+ * Exported so every call site can apply the same limit *before* calling
+ * `levenshtein` — skipping an over-limit operand entirely, rather than
+ * comparing a truncated prefix of it. Truncating silently merged any two
+ * strings that happened to share their first `MAX_COMPARABLE_LENGTH`
+ * characters into distance 0, which let a direct MCP tool-name lookup
+ * (`resolveToolName`) resolve to the wrong tool for a long, colliding name.
+ */
+export const MAX_COMPARABLE_LENGTH = 128;
+const OVER_LIMIT_MESSAGE = `levenshtein: input exceeds MAX_COMPARABLE_LENGTH (${MAX_COMPARABLE_LENGTH}); callers must skip over-limit operands rather than truncate them`;
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * Uses the iterative matrix approach — O(m*n) time, O(min(m,n)) space.
+ *
+ * Throws rather than truncating when either input exceeds
+ * `MAX_COMPARABLE_LENGTH`: silently comparing truncated prefixes produces a
+ * *wrong* distance (two distinct strings sharing a long prefix collapse to
+ * distance 0) instead of no distance, which is worse than refusing outright.
+ * Callers that want fuzzy matching over long input must apply the length
+ * check themselves and skip the comparison — see `suggestClosest` below and
+ * `resolveToolName`/`rankToolNameCandidates` in toolCallRepair.ts.
+ */
+export function levenshtein(a, b) {
+    // Names reach this from request bodies and model output, where the static
+    // type is no runtime guarantee: a parsed-JSON object with a forged `length`
+    // must never size the matrix below. This `typeof` test is what CodeQL's
+    // js/loop-bound-injection recognises as ruling such an object out; a length
+    // comparison alone is not.
+    if (typeof a !== "string") {
+        throw new TypeError("levenshtein: operands must be strings");
+    }
+    if (typeof b !== "string") {
+        throw new TypeError("levenshtein: operands must be strings");
+    }
+    // Ahead of every return, so the limit holds for all inputs, including equal
+    // strings and an empty operand.
+    if (a.length > MAX_COMPARABLE_LENGTH) {
+        throw new RangeError(OVER_LIMIT_MESSAGE);
+    }
+    if (b.length > MAX_COMPARABLE_LENGTH) {
+        throw new RangeError(OVER_LIMIT_MESSAGE);
+    }
+    if (a === b) {
+        return 0;
+    }
+    if (a.length === 0) {
+        return b.length;
+    }
+    if (b.length === 0) {
+        return a.length;
+    }
+    // Use shorter string as column to minimize space
+    if (a.length > b.length) {
+        [a, b] = [b, a];
+    }
+    const aLen = a.length;
+    const bLen = b.length;
+    let prev = new Array(aLen + 1);
+    let curr = new Array(aLen + 1);
+    for (let i = 0; i <= aLen; i++) {
+        prev[i] = i;
+    }
+    for (let j = 1; j <= bLen; j++) {
+        curr[0] = j;
+        for (let i = 1; i <= aLen; i++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[i] = Math.min(prev[i] + 1, // deletion
+            curr[i - 1] + 1, // insertion
+            prev[i - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[aLen];
+}
+/**
+ * Candidates within `maxDistance` edits of `input`, closest first.
+ *
+ * Ties break on the candidate's own order in `candidates`, so a caller that
+ * passes canonical names before aliases gets the canonical one suggested.
+ * Comparison is case-insensitive; the returned strings keep their original
+ * casing so they can be pasted back verbatim.
+ *
+ * `input` longer than `MAX_COMPARABLE_LENGTH` is rejected outright (no
+ * suggestions), and any individual candidate over the same limit is skipped
+ * rather than compared — never truncated. Truncating either side risks
+ * exactly the false distance-0 match `levenshtein`'s guard rejects: two
+ * distinct strings sharing a long-enough prefix would otherwise look
+ * identical and "suggest" the wrong one.
+ *
+ * @param input - The string the user actually typed
+ * @param candidates - Valid values, most-preferred first
+ * @param options.maxDistance - Edit budget (default 3)
+ * @param options.limit - Most suggestions to return (default 3)
+ */
+export function suggestClosest(input, candidates, options) {
+    const maxDistance = options?.maxDistance ?? 3;
+    const limit = options?.limit ?? 3;
+    // Limits apply to the lowercased strings, since those are what get compared
+    // and lowercasing can lengthen a string ("İ" becomes two code units).
+    const needle = input.toLowerCase();
+    if (needle.length > MAX_COMPARABLE_LENGTH) {
+        return [];
+    }
+    const scored = [];
+    candidates.forEach((candidate, order) => {
+        const lowered = candidate.toLowerCase();
+        // Two strings whose lengths differ by more than the edit budget cannot be
+        // within it, so this rules most candidates out without building a matrix
+        // for them.
+        if (Math.abs(lowered.length - needle.length) > maxDistance) {
+            return;
+        }
+        if (lowered.length > MAX_COMPARABLE_LENGTH) {
+            return;
+        }
+        const distance = levenshtein(needle, lowered);
+        if (distance <= maxDistance) {
+            scored.push({ candidate, order, distance });
+        }
+    });
+    return scored
+        .sort((a, b) => a.distance - b.distance || a.order - b.order)
+        .slice(0, limit)
+        .map((entry) => entry.candidate);
+}

package/dist/utils/toolCallRepair.js

@@ -1,4 +1,5 @@
 import { logger } from "./logger.js";
+import { levenshtein, MAX_COMPARABLE_LENGTH } from "./stringDistance.js";
 /**
  * Create an `experimental_repairToolCall` handler for streamText/generateText.
  * Fully dynamic — reads the tool schema at repair time, no configuration needed.
@@ -58,15 +59,27 @@ export function resolveToolName(calledName, availableTools) {
     }
     // 3. Levenshtein distance — accept if normalized distance < 0.3
     // Compare by normalized score (not raw edits) so length differences don't skew selection.
+    // `levenshtein` throws rather than truncates past MAX_COMPARABLE_LENGTH (see
+    // stringDistance.ts), so an over-limit name is skipped here instead of
+    // compared on a truncated prefix — a called name and a tool name that
+    // merely share a long-enough prefix must never tie at distance 0 and
+    // resolve to the wrong tool. The guard checks the lowercased operands, since
+    // those are what get compared and lowercasing can lengthen a string ("İ").
     let bestMatch = null;
     let bestNormalized = Infinity;
-    for (const t of availableTools) {
-        const dist = levenshtein(calledLower, t.toLowerCase());
-        const maxLen = Math.max(calledName.length, t.length);
-        const normalized = maxLen === 0 ? 0 : dist / maxLen;
-        if (normalized < 0.3 && normalized < bestNormalized) {
-            bestNormalized = normalized;
-            bestMatch = t;
+    if (calledLower.length <= MAX_COMPARABLE_LENGTH) {
+        for (const t of availableTools) {
+            const tLower = t.toLowerCase();
+            if (tLower.length > MAX_COMPARABLE_LENGTH) {
+                continue;
+            }
+            const dist = levenshtein(calledLower, tLower);
+            const maxLen = Math.max(calledName.length, t.length);
+            const normalized = maxLen === 0 ? 0 : dist / maxLen;
+            if (normalized < 0.3 && normalized < bestNormalized) {
+                bestNormalized = normalized;
+                bestMatch = t;
+            }
         }
     }
     if (bestMatch) {
@@ -85,10 +98,27 @@ export function resolveToolName(calledName, availableTools) {
  */
 export function rankToolNameCandidates(calledName, availableTools, limit = 5) {
     const calledLower = calledName.toLowerCase();
-    return [...availableTools]
-        .sort((a, b) => levenshtein(calledLower, a.toLowerCase()) -
-        levenshtein(calledLower, b.toLowerCase()))
-        .slice(0, limit);
+    const calledWithinLimit = calledLower.length <= MAX_COMPARABLE_LENGTH;
+    // `levenshtein` throws past MAX_COMPARABLE_LENGTH instead of truncating, so
+    // an over-limit operand is scored as "furthest away" rather than compared
+    // on a truncated (and potentially falsely-tied) prefix. This still only
+    // orders the list — no candidate is dropped — matching this function's
+    // "no accept/reject judgment" contract.
+    const distanceTo = (name) => {
+        const nameLower = name.toLowerCase();
+        if (!calledWithinLimit || nameLower.length > MAX_COMPARABLE_LENGTH) {
+            return Number.POSITIVE_INFINITY;
+        }
+        return levenshtein(calledLower, nameLower);
+    };
+    // Precompute once per tool (not per comparison), and compare with an
+    // explicit equality check — two Infinity distances (both over-limit) would
+    // otherwise subtract to NaN, an invalid sort-comparator result.
+    return availableTools
+        .map((name) => ({ name, distance: distanceTo(name) }))
+        .sort((a, b) => (a.distance === b.distance ? 0 : a.distance - b.distance))
+        .slice(0, limit)
+        .map((entry) => entry.name);
 }
 /**
  * Thrown at a direct MCP execution boundary (`NeuroLink.executeExternalMCPTool`)
@@ -220,14 +250,21 @@ function findMatchingKey(inputKey, schemaKeys) {
     if (ciMatch) {
         return ciMatch;
     }
-    // Levenshtein — threshold ≤2 edits
+    // Levenshtein — threshold ≤2 edits. Same over-limit guard as
+    // resolveToolName above: skip rather than let levenshtein() truncate.
     let best = null;
     let bestDist = Infinity;
-    for (const k of schemaKeys) {
-        const dist = levenshtein(inputLower, k.toLowerCase());
-        if (dist <= 2 && dist < bestDist) {
-            bestDist = dist;
-            best = k;
+    if (inputLower.length <= MAX_COMPARABLE_LENGTH) {
+        for (const k of schemaKeys) {
+            const kLower = k.toLowerCase();
+            if (kLower.length > MAX_COMPARABLE_LENGTH) {
+                continue;
+            }
+            const dist = levenshtein(inputLower, kLower);
+            if (dist <= 2 && dist < bestDist) {
+                bestDist = dist;
+                best = k;
+            }
         }
     }
     return best;
@@ -308,41 +345,3 @@ export function coerceType(value, propSchema) {
     }
     return value;
 }
-// ─── Levenshtein Distance ──────────────────────────────────────────
-/**
- * Compute Levenshtein edit distance between two strings.
- * Uses the iterative matrix approach — O(m*n) time, O(min(m,n)) space.
- */
-function levenshtein(a, b) {
-    if (a === b) {
-        return 0;
-    }
-    if (a.length === 0) {
-        return b.length;
-    }
-    if (b.length === 0) {
-        return a.length;
-    }
-    // Use shorter string as column to minimize space
-    if (a.length > b.length) {
-        [a, b] = [b, a];
-    }
-    const aLen = a.length;
-    const bLen = b.length;
-    let prev = new Array(aLen + 1);
-    let curr = new Array(aLen + 1);
-    for (let i = 0; i <= aLen; i++) {
-        prev[i] = i;
-    }
-    for (let j = 1; j <= bLen; j++) {
-        curr[0] = j;
-        for (let i = 1; i <= aLen; i++) {
-            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-            curr[i] = Math.min(prev[i] + 1, // deletion
-            curr[i - 1] + 1, // insertion
-            prev[i - 1] + cost);
-        }
-        [prev, curr] = [curr, prev];
-    }
-    return prev[aLen];
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.21.1",
+  "version": "12.22.0",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {