@juspay/neurolink 12.0.2 → 12.0.3

package/dist/neurolink.d.ts

@@ -85,6 +85,23 @@ export declare class NeuroLink {
     /** Artifact store for externalized MCP tool outputs (set when strategy=externalize). */
     private mcpArtifactStore?;
     private _disableToolCacheForCurrentRequest;
+    /**
+     * (toolName + args) keys already served during the CURRENT request.
+     * A repeat occurrence within one request bypasses the tool-result cache:
+     * when the model deliberately re-calls a tool with identical args in the
+     * same turn (a counter, a poll, "check status again"), it wants fresh
+     * state — serving the memoized first result silently freezes stateful
+     * tools (observed live: a 5-round counter loop executed once). Cross-
+     * request dedup — BZ-664's actual goal — is untouched: the first
+     * occurrence in a request may still be served from cache. Request-scoped
+     * like _disableToolCacheForCurrentRequest above (assigned a fresh Set at
+     * request start so the router's save/restore-by-reference pattern works).
+     */
+    private _toolCacheKeysServedThisRequest;
+    /** True only while a generate()/stream() turn is executing — the
+     *  repeat-call cache bypass applies inside a turn; direct executeTool
+     *  calls keep full BZ-664 cache semantics. */
+    private _generationTurnActive;
     private mcpEnhancementsConfig?;
     private toolCircuitBreakers;
     private toolExecutionMetrics;
@@ -1524,6 +1541,7 @@ export declare class NeuroLink {
      * - Annotations: skip cache for destructive tools, retry safe tools on failure
      * - Middleware: apply global middleware chain before execution
      */
+    private toolCacheRepeatKey;
     private executeToolInternal;
     /**
      * Get tool annotations for execution decisions (cache, retry).

package/dist/neurolink.js

@@ -377,6 +377,23 @@ export class NeuroLink {
     /** Artifact store for externalized MCP tool outputs (set when strategy=externalize). */
     mcpArtifactStore;
     _disableToolCacheForCurrentRequest = false;
+    /**
+     * (toolName + args) keys already served during the CURRENT request.
+     * A repeat occurrence within one request bypasses the tool-result cache:
+     * when the model deliberately re-calls a tool with identical args in the
+     * same turn (a counter, a poll, "check status again"), it wants fresh
+     * state — serving the memoized first result silently freezes stateful
+     * tools (observed live: a 5-round counter loop executed once). Cross-
+     * request dedup — BZ-664's actual goal — is untouched: the first
+     * occurrence in a request may still be served from cache. Request-scoped
+     * like _disableToolCacheForCurrentRequest above (assigned a fresh Set at
+     * request start so the router's save/restore-by-reference pattern works).
+     */
+    _toolCacheKeysServedThisRequest = new Set();
+    /** True only while a generate()/stream() turn is executing — the
+     *  repeat-call cache bypass applies inside a turn; direct executeTool
+     *  calls keep full BZ-664 cache semantics. */
+    _generationTurnActive = false;
     mcpEnhancementsConfig;
     // Enhanced error handling support
     toolCircuitBreakers = new Map();
@@ -3509,6 +3526,8 @@ Current user's request: ${currentInput}`;
         }
         finally {
             this._disableToolCacheForCurrentRequest = false;
+            this._toolCacheKeysServedThisRequest = new Set();
+            this._generationTurnActive = false;
             generateSpan.end();
         }
     }
@@ -3527,6 +3546,8 @@ Current user's request: ${currentInput}`;
         await this.resolveDynamicOptions(options);
         options.model = resolveModel(options.model, this.modelAliasConfig);
         this._disableToolCacheForCurrentRequest = !!options.disableToolCache;
+        this._toolCacheKeysServedThisRequest = new Set();
+        this._generationTurnActive = true;
         generateSpan.setAttribute("neurolink.provider", options.provider || "default");
         generateSpan.setAttribute("neurolink.model", options.model || "default");
         generateSpan.setAttribute("neurolink.input_length", typeof optionsOrPrompt === "string"
@@ -6672,6 +6693,8 @@ Current user's request: ${currentInput}`;
         const streamIsRoot = !trace.getSpan(context.active());
         const spanStartTime = Date.now();
         this._disableToolCacheForCurrentRequest = !!options.disableToolCache;
+        this._toolCacheKeysServedThisRequest = new Set();
+        this._generationTurnActive = true;
         try {
             options.model = resolveModel(options.model, this.modelAliasConfig);
             const startTime = Date.now();
@@ -7304,6 +7327,8 @@ Current user's request: ${currentInput}`;
             }
             finally {
                 self._disableToolCacheForCurrentRequest = false;
+                self._toolCacheKeysServedThisRequest = new Set();
+                self._generationTurnActive = false;
                 params.streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - params.spanStartTime);
                 params.streamSpan.end();
             }
@@ -7603,6 +7628,8 @@ Current user's request: ${currentInput}`;
                         }
                     }
                     self._disableToolCacheForCurrentRequest = false;
+                    self._toolCacheKeysServedThisRequest = new Set();
+                    self._generationTurnActive = false;
                     cleanupListeners();
                     streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - spanStartTime);
                     streamSpan.setAttribute(ATTR.NL_OUTPUT_LENGTH, accumulatedContent.length);
@@ -10047,6 +10074,16 @@ Current user's request: ${currentInput}`;
      * - Annotations: skip cache for destructive tools, retry safe tools on failure
      * - Middleware: apply global middleware chain before execution
      */
+    toolCacheRepeatKey(toolName, params) {
+        try {
+            return `${toolName}:${JSON.stringify(params) ?? ""}`;
+        }
+        catch {
+            // Unserializable args (circular refs) — no repeat tracking; the
+            // ToolResultCache's own keying handles (or rejects) them as before.
+            return undefined;
+        }
+    }
     async executeToolInternal(toolName, params, options, HITLState) {
         const functionTag = "NeuroLink.executeToolInternal";
         // === MCP ENHANCEMENT: Infer annotations for cache/retry decisions ===
@@ -10064,13 +10101,24 @@ Current user's request: ${currentInput}`;
                 __ctx: options.authContext ?? this.toolExecutionContext,
             }
             : params;
-        if (isCacheEnabled && toolResultCache) {
+        const repeatKey = this._generationTurnActive
+            ? this.toolCacheRepeatKey(toolName, cacheParams)
+            : undefined;
+        const isRepeatCallThisRequest = repeatKey !== undefined &&
+            this._toolCacheKeysServedThisRequest.has(repeatKey);
+        if (repeatKey !== undefined) {
+            this._toolCacheKeysServedThisRequest.add(repeatKey);
+        }
+        if (isCacheEnabled && toolResultCache && !isRepeatCallThisRequest) {
             const cached = toolResultCache.getCachedResult(toolName, cacheParams);
             if (cached !== undefined) {
                 logger.debug(`[${functionTag}] Cache HIT for tool: ${toolName}`);
                 return cached;
             }
         }
+        else if (isRepeatCallThisRequest) {
+            logger.debug(`[${functionTag}] Repeat call within this request — bypassing tool cache for: ${toolName}`);
+        }
         // === MCP ENHANCEMENT: Middleware chain wrapper ===
         const executeWithMiddleware = async (executeFn) => {
             if (this.mcpToolMiddlewares.length === 0) {
@@ -11515,7 +11563,19 @@ Current user's request: ${currentInput}`;
                     ? { __ctx: this.toolExecutionContext }
                     : {}),
             };
-            if (cacheEnabled && this.mcpToolResultCache) {
+            // Same repeat-within-request bypass as executeToolInternal: a model
+            // re-calling the identical tool+args in one turn wants fresh state.
+            const externalRepeatKey = this._generationTurnActive
+                ? this.toolCacheRepeatKey(toolName, cacheKeyArgs)
+                : undefined;
+            const isExternalRepeatThisRequest = externalRepeatKey !== undefined &&
+                this._toolCacheKeysServedThisRequest.has(externalRepeatKey);
+            if (externalRepeatKey !== undefined) {
+                this._toolCacheKeysServedThisRequest.add(externalRepeatKey);
+            }
+            if (cacheEnabled &&
+                this.mcpToolResultCache &&
+                !isExternalRepeatThisRequest) {
                 const cached = this.mcpToolResultCache.getCachedResult(toolName, cacheKeyArgs);
                 if (cached !== undefined) {
                     mcpLogger.debug(`[NeuroLink] Tool result cache HIT: ${toolName} on ${serverId}`);

package/dist/utils/messageBuilder.js

@@ -2184,76 +2184,146 @@ pdfFiles, provider, model, audioFiles = []) {
         }));
     }
     else {
-        // Provider doesn't support native PDF - convert PDF pages to images
-        // This enables PDF processing for providers like Mistral, Ollama that support images but not PDFs
-        logger.info(`[PDF→Image] Provider ${provider} doesn't support native PDF. Converting ${pdfFiles.length} PDF(s) to images...`);
+        // No native PDF support: inline the PDF's text layer, clearly labeled per
+        // file. Image-only conversion sent content a text-only backend can never
+        // read — observed live as the model flatly claiming no file was attached
+        // — and for proxy providers (litellm/openrouter) supportsVision() is a
+        // pass-through, so vision cannot be trusted to carry the content either.
+        // Text is therefore always included (primary for text-only backends,
+        // extra grounding otherwise); page images are appended below only when
+        // the provider may actually see them. A PDF with no text layer (pure
+        // scan) gets an explicit note rather than silence, so the model
+        // acknowledges an unreadable attachment instead of denying it exists.
+        const providerCanSeeImages = ProviderImageAdapter.supportsVision(provider, model);
         for (const pdf of pdfFiles) {
+            const name = safeBasename(pdf.filename);
             try {
-                const effectiveMaxPages = pdf.maxPages ?? PDF_LIMITS.DEFAULT_MAX_PAGES;
-                const conversionResult = await PDFImageConverter.convertToImages(pdf.buffer, {
-                    // #297: this is the only PDF→image call the product actually makes,
-                    // and it used to hardcode scale 2.0 — silently overriding the
-                    // lowered PDF_LIMITS.DEFAULT_SCALE and keeping the memory cost the
-                    // issue reports (a 100-page render at 2.0 is ~776MB; 1.5 is ~44%
-                    // fewer pixels per page). Callers can raise it back per request.
-                    scale: pdf.scale ?? PDF_LIMITS.DEFAULT_SCALE,
-                    // Page ceiling guards token overflow; also now caller-adjustable
-                    // rather than a constant nothing could reach.
-                    maxPages: effectiveMaxPages,
+                const { PDFParse } = await import("pdf-parse");
+                const parser = new PDFParse({
+                    data: new Uint8Array(pdf.buffer),
                     ...(pdf.password ? { password: pdf.password } : {}), // #258
-                    ...(pdf.maxCanvasPixels
-                        ? { maxCanvasPixels: pdf.maxCanvasPixels }
-                        : {}), // #260
                 });
-                // The renderer stops at maxPages, so a longer document is silently
-                // truncated — say so rather than letting the model answer from a
-                // partial document as though it had the whole thing.
-                //
-                // Keyed on the cap being reached, not on pdf.pageCount: that field is
-                // null whenever `input.content` omits `metadata.pages`, which is the
-                // common case, so a page-count comparison would simply never fire
-                // there. Reaching the cap is also unambiguous — a short count caused by
-                // per-page render failures (#294 isolates those into `errors`) would
-                // otherwise be misreported as a maxPages truncation.
-                if (conversionResult.pageCount >= effectiveMaxPages) {
-                    logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)} hit the ${effectiveMaxPages}-page ` +
-                        `conversion limit. Any pages beyond that were not sent — the model may be ` +
-                        `answering from a partial document. Raise pdfOptions.maxPages or split the file.`);
-                }
-                if (conversionResult.errors && conversionResult.errors.length > 0) {
-                    logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)}: ${conversionResult.errors.length} page(s) ` +
-                        `failed to render and were omitted (page ${conversionResult.errors.map((e) => e.page).join(", ")}).`);
+                try {
+                    const extracted = await parser.getText();
+                    const pdfText = (extracted?.text ?? "").trim();
+                    if (pdfText.length > 0) {
+                        content.push({
+                            type: "text",
+                            text: `\n[Attached PDF: ${name}]\n${pdfText}\n[End of PDF: ${name}]`,
+                        });
+                        logger.info(`[PDF→Text] ✅ Extracted text for non-vision provider ${provider}: ${name} (${pdfText.length} chars)`);
+                    }
+                    else {
+                        content.push({
+                            type: "text",
+                            text: `\n[Attached PDF: ${name} — no extractable text layer (likely a scanned document); its contents are unavailable to this text-only model.]`,
+                        });
+                        logger.warn(`[PDF→Text] ${name} has no text layer; provider ${provider} cannot see images — content unavailable`);
+                    }
                 }
-                logger.info(`[PDF→Image] ✅ Converted ${pdf.filename}: ${conversionResult.pageCount} page(s) → images`);
-                // Add each page as an ImagePart (raw base64, not data: URI — see SSRF note above)
-                conversionResult.images.forEach((base64Image, pageIndex) => {
-                    content.push({
-                        type: "image",
-                        image: base64Image,
-                        mimeType: "image/png",
-                    });
-                    logger.debug(`[PDF→Image] Added page ${pageIndex + 1}/${conversionResult.pageCount} of ${pdf.filename}`);
-                });
-                // Log any warnings from conversion
-                if (conversionResult.warnings) {
-                    conversionResult.warnings.forEach((warning) => {
-                        logger.warn(`[PDF→Image] ${warning}`);
-                    });
+                finally {
+                    await parser.destroy?.();
                 }
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                logger.error(`[PDF→Image] ❌ Failed to convert ${pdf.filename}: ${errorMessage}`);
-                // #258: password errors are already actionable typed errors — re-throw
-                // them unwrapped so the "supply a password" guidance isn't buried.
-                const code = error?.code;
-                if (code === "PDF_PASSWORD_REQUIRED" ||
-                    code === "PDF_INCORRECT_PASSWORD") {
-                    throw error;
+                logger.error(`[PDF→Text] ❌ Failed to parse ${name}: ${errorMessage}`);
+                // #258: password errors are actionable and must surface. pdf-parse
+                // raises pdf.js's PasswordException (not our typed PDF_PASSWORD_*
+                // codes), so detect by name/message shape. When the provider can see
+                // images, defer the throw to the image-conversion path below — it
+                // raises the canonical typed error with the "supply the password"
+                // guidance callers and tests rely on.
+                const isPasswordError = error?.name === "PasswordException" ||
+                    /password/i.test(errorMessage);
+                if (isPasswordError) {
+                    if (!providerCanSeeImages) {
+                        throw error;
+                    }
+                    // Image branch will produce the canonical typed password error.
+                    continue;
+                }
+                content.push({
+                    type: "text",
+                    text: `\n[Attached PDF: ${name} — could not be parsed (${errorMessage}); its contents are unavailable.]`,
+                });
+            }
+        }
+        // Page images in addition to the text, for providers that may actually
+        // see them (vision models, and proxies whose upstream might).
+        if (providerCanSeeImages) {
+            logger.info(`[PDF→Image] Provider ${provider} doesn't support native PDF. Converting ${pdfFiles.length} PDF(s) to images...`);
+            for (const pdf of pdfFiles) {
+                try {
+                    const effectiveMaxPages = pdf.maxPages ?? PDF_LIMITS.DEFAULT_MAX_PAGES;
+                    const conversionResult = await PDFImageConverter.convertToImages(pdf.buffer, {
+                        // #297: this is the only PDF→image call the product actually makes,
+                        // and it used to hardcode scale 2.0 — silently overriding the
+                        // lowered PDF_LIMITS.DEFAULT_SCALE and keeping the memory cost the
+                        // issue reports (a 100-page render at 2.0 is ~776MB; 1.5 is ~44%
+                        // fewer pixels per page). Callers can raise it back per request.
+                        scale: pdf.scale ?? PDF_LIMITS.DEFAULT_SCALE,
+                        // Page ceiling guards token overflow; also now caller-adjustable
+                        // rather than a constant nothing could reach.
+                        maxPages: effectiveMaxPages,
+                        ...(pdf.password ? { password: pdf.password } : {}), // #258
+                        ...(pdf.maxCanvasPixels
+                            ? { maxCanvasPixels: pdf.maxCanvasPixels }
+                            : {}), // #260
+                    });
+                    // The renderer stops at maxPages, so a longer document is silently
+                    // truncated — say so rather than letting the model answer from a
+                    // partial document as though it had the whole thing.
+                    //
+                    // Keyed on the cap being reached, not on pdf.pageCount: that field is
+                    // null whenever `input.content` omits `metadata.pages`, which is the
+                    // common case, so a page-count comparison would simply never fire
+                    // there. Reaching the cap is also unambiguous — a short count caused by
+                    // per-page render failures (#294 isolates those into `errors`) would
+                    // otherwise be misreported as a maxPages truncation.
+                    if (conversionResult.pageCount >= effectiveMaxPages) {
+                        logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)} hit the ${effectiveMaxPages}-page ` +
+                            `conversion limit. Any pages beyond that were not sent — the model may be ` +
+                            `answering from a partial document. Raise pdfOptions.maxPages or split the file.`);
+                    }
+                    if (conversionResult.errors && conversionResult.errors.length > 0) {
+                        logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)}: ${conversionResult.errors.length} page(s) ` +
+                            `failed to render and were omitted (page ${conversionResult.errors.map((e) => e.page).join(", ")}).`);
+                    }
+                    logger.info(`[PDF→Image] ✅ Converted ${pdf.filename}: ${conversionResult.pageCount} page(s) → images`);
+                    // Add each page as an ImagePart (raw base64, not data: URI — see SSRF note above)
+                    conversionResult.images.forEach((base64Image, pageIndex) => {
+                        content.push({
+                            type: "image",
+                            image: base64Image,
+                            mimeType: "image/png",
+                        });
+                        logger.debug(`[PDF→Image] Added page ${pageIndex + 1}/${conversionResult.pageCount} of ${pdf.filename}`);
+                    });
+                    // Log any warnings from conversion
+                    if (conversionResult.warnings) {
+                        conversionResult.warnings.forEach((warning) => {
+                            logger.warn(`[PDF→Image] ${warning}`);
+                        });
+                    }
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.error(`[PDF→Image] ❌ Failed to convert ${pdf.filename}: ${errorMessage}`);
+                    // #258: password errors are already actionable typed errors — re-throw
+                    // them unwrapped so the "supply a password" guidance isn't buried.
+                    const code = error?.code;
+                    if (code === "PDF_PASSWORD_REQUIRED" ||
+                        code === "PDF_INCORRECT_PASSWORD") {
+                        throw error;
+                    }
+                    // Re-throw so the user knows PDF processing failed. The inlined
+                    // text layer above does NOT soften this: conversion failures
+                    // include caller mistakes (e.g. an invalid maxCanvasPixels, #260)
+                    // that must surface rather than be silently downgraded.
+                    throw new Error(`PDF to image conversion failed for ${pdf.filename}: ${errorMessage}. ` +
+                        `Provider ${provider} doesn't support native PDFs and image conversion failed.`, { cause: error });
                 }
-                // Re-throw so the user knows PDF processing failed
-                throw new Error(`PDF to image conversion failed for ${pdf.filename}: ${errorMessage}. ` +
-                    `Provider ${provider} doesn't support native PDFs and image conversion failed.`, { cause: error });
             }
         }
     }

package/dist/utils/transformationUtils.d.ts

@@ -33,6 +33,11 @@ export declare function transformToolExecutionsForMCP(toolExecutions?: unknown[]
     executionTime: number;
     success: boolean;
     serverId?: string;
+    params?: unknown;
+    output?: unknown;
+    startedAt?: number;
+    isError?: boolean;
+    error?: string;
 }>;
 /**
  * Convert ToolExecutionRecord entries (or legacy-shaped entries) to the

package/dist/utils/transformationUtils.js

@@ -234,11 +234,36 @@ export function transformToolExecutionsForMCP(toolExecutions) {
                     toolCall.server ||
                     undefined;
         }
+        // Pass the execution payload through instead of discarding it. This
+        // transform used to keep only {toolName, executionTime, success,
+        // serverId}; toToolExecutionRecords() downstream then found no
+        // input/output on the entries and emitted params:{} with
+        // resultText:"undefined" for every tool execution on the MCP path —
+        // even when the source entry was a full record with real args and a
+        // real result. Field names chosen to match what
+        // toToolExecutionRecords() reads (input/params, output/result/
+        // resultText, startedAt, isError).
+        const params = teRecord.params ?? teRecord.input ?? teRecord.args ?? undefined;
+        const output = teRecord.output ??
+            teRecord.result ??
+            teRecord.response ??
+            (typeof teRecord.resultText === "string"
+                ? teRecord.resultText
+                : undefined);
         return {
             toolName: toolName,
             executionTime: executionTime,
             success: success,
             serverId: serverId,
+            ...(params !== undefined ? { params } : {}),
+            ...(output !== undefined ? { output } : {}),
+            ...(typeof teRecord.startedAt === "number"
+                ? { startedAt: teRecord.startedAt }
+                : {}),
+            ...(teRecord.isError !== undefined
+                ? { isError: teRecord.isError === true }
+                : { isError: !success }),
+            ...(typeof teRecord.error === "string" ? { error: teRecord.error } : {}),
         };
     });
 }

package/package.json

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