@juspay/neurolink 12.17.2 → 12.17.3

package/dist/neurolink.js

@@ -5899,7 +5899,10 @@ Current user's request: ${currentInput}`;
             toolsUsed: result.toolsUsed || [],
             toolCalls: result.toolCalls ?? [],
             toolExecutions: transformedToolExecutions,
-            enhancedWithTools: Boolean(hasToolExecutions),
+            // A tool RAN (toolsUsed), not merely dispatched (toolExecutions can
+            // include failed/never-found calls) — see hasToolExecutions above,
+            // which still gates the null-result check and must not change.
+            enhancedWithTools: !!(result.toolsUsed && result.toolsUsed.length > 0),
             availableTools: transformToolsForMCP(transformToolsToExpectedFormat(availableTools)),
             audio: result.audio,
             ttsMetadata: result.ttsMetadata,
@@ -6060,7 +6063,8 @@ Current user's request: ${currentInput}`;
                             executionTime: te.durationMs,
                             success: !te.isError,
                         })),
-                        enhancedWithTools: !!poolResult.toolExecutions?.length,
+                        // A tool RAN (toolsUsed), not merely dispatched.
+                        enhancedWithTools: !!poolResult.toolsUsed?.length,
                         analytics: poolResult.analytics,
                         evaluation: poolResult.evaluation,
                         audio: poolResult.audio,
@@ -6432,7 +6436,8 @@ Current user's request: ${currentInput}`;
                         executionTime: te.durationMs,
                         success: !te.isError,
                     })),
-                    enhancedWithTools: !!result.toolExecutions?.length,
+                    // A tool RAN (toolsUsed), not merely dispatched.
+                    enhancedWithTools: !!result.toolsUsed?.length,
                     analytics: result.analytics,
                     evaluation: result.evaluation,
                     audio: result.audio,

package/dist/providers/openaiChatCompletionsBase.js

@@ -899,57 +899,66 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         // Omit the tools for a pass that only has to reformat an answer the
         // model has already given. Dropping them is what makes `response_format`
         // legal again on a vendor that refuses the two together.
-        withTools = true) => runNativeGenerateLoop({
-            doGenerate,
-            ...createNativeGenerateGuard({
-                provider: this.providerName,
-                availableInputTokens: getAvailableInputTokens(this.providerName, modelId, options.maxTokens ?? undefined),
-                // Runs on every step of the generate loop, so a cyclic or
-                // oversized tool schema must not throw the turn away. Shares the
-                // estimator's own serializer: its fallback over-reports, which
-                // makes the guard fire rather than silently size the overhead at
-                // nothing.
-                getFixedOverheadTokens: () => estimateTokens(serializeForEstimate({
-                    tools: v3Tools,
-                    responseFormat: format,
-                }), this.providerName),
-            }),
-            conversation: conv,
-            ...(withTools && v3Tools ? { tools: v3Tools } : {}),
-            toolsRecord,
-            ...(withTools && hasTools && options.toolChoice
-                ? { toolChoice: resolveToolChoice(options, toolsRecord, true) }
-                : {}),
-            // The per-call `timeout` keeps its per-MODEL-CALL meaning once
-            // `turnTimeoutMs` owns the whole-turn deadline, and it reaches the
-            // model layer only through this channel. Without it each step fell
-            // back to the provider default, so a caller asking for a short
-            // per-call timeout got the default on every request.
-            ...(typeof options.timeout === "number"
-                ? {
-                    providerOptions: {
-                        neurolink: { timeoutMs: options.timeout },
-                    },
-                }
-                : {}),
-            ...(format ? { responseFormat: format } : {}),
-            maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
-            ...(options.maxTokens ? { maxOutputTokens: options.maxTokens } : {}),
-            ...(options.temperature !== undefined
-                ? { temperature: options.temperature }
-                : {}),
-            ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
-            ...(options.toolTimeoutMs !== undefined
-                ? { toolTimeoutMs: options.toolTimeoutMs }
-                : {}),
-            // withProviderRetry + handleProviderError are what the ai loop
-            // supplied around each call: without them a 429 surfaces as a raw
-            // upstream string instead of a RateLimitError, and a throttle is
-            // never retried.
-            runStep: (call) => withProviderRetry(call, trace.getActiveSpan() ?? undefined, `${this.providerName} generate`).catch((err) => {
-                throw this.handleProviderError(err);
-            }),
-        }, toolExecutionSummaries);
+        withTools = true) => {
+            return runNativeGenerateLoop({
+                doGenerate,
+                ...createNativeGenerateGuard({
+                    provider: this.providerName,
+                    availableInputTokens: getAvailableInputTokens(this.providerName, modelId, options.maxTokens ?? undefined),
+                    // Runs on every step of the generate loop, so a cyclic or
+                    // oversized tool schema must not throw the turn away. Shares the
+                    // estimator's own serializer: its fallback over-reports, which
+                    // makes the guard fire rather than silently size the overhead at
+                    // nothing.
+                    // Charge the guard only for what this pass actually sends. A
+                    // reformat pass runs with `withTools === false` and omits `tools`
+                    // from the request (see the spread below), so counting them here
+                    // over-reports the fixed overhead. That inflation is not cosmetic:
+                    // it feeds `planLoopGuardReclaim`, so a large tool schema can push
+                    // the estimate past the reclaim threshold and drop older tool
+                    // exchanges out of a reformat request that would have fit.
+                    getFixedOverheadTokens: () => estimateTokens(serializeForEstimate({
+                        ...(withTools && v3Tools ? { tools: v3Tools } : {}),
+                        responseFormat: format,
+                    }), this.providerName),
+                }),
+                conversation: conv,
+                ...(withTools && v3Tools ? { tools: v3Tools } : {}),
+                toolsRecord,
+                ...(withTools && hasTools && options.toolChoice
+                    ? { toolChoice: resolveToolChoice(options, toolsRecord, true) }
+                    : {}),
+                // The per-call `timeout` keeps its per-MODEL-CALL meaning once
+                // `turnTimeoutMs` owns the whole-turn deadline, and it reaches the
+                // model layer only through this channel. Without it each step fell
+                // back to the provider default, so a caller asking for a short
+                // per-call timeout got the default on every request.
+                ...(typeof options.timeout === "number"
+                    ? {
+                        providerOptions: {
+                            neurolink: { timeoutMs: options.timeout },
+                        },
+                    }
+                    : {}),
+                ...(format ? { responseFormat: format } : {}),
+                maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
+                ...(options.maxTokens ? { maxOutputTokens: options.maxTokens } : {}),
+                ...(options.temperature !== undefined
+                    ? { temperature: options.temperature }
+                    : {}),
+                ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+                ...(options.toolTimeoutMs !== undefined
+                    ? { toolTimeoutMs: options.toolTimeoutMs }
+                    : {}),
+                // withProviderRetry + handleProviderError are what the ai loop
+                // supplied around each call: without them a 429 surfaces as a raw
+                // upstream string instead of a RateLimitError, and a throttle is
+                // never retried.
+                runStep: (call) => withProviderRetry(call, trace.getActiveSpan() ?? undefined, `${this.providerName} generate`).catch((err) => {
+                    throw this.handleProviderError(err);
+                }),
+            }, toolExecutionSummaries);
+        };
         // Structured output rides `response_format` first. When a vendor rejects
         // that outright — a tools/JSON-mode conflict, or a schema its constrained
         // decoder will not accept — the recovery is to ask for the same object in

package/dist/utils/fileDetector.js

@@ -4,6 +4,7 @@
  * Uses multi-strategy approach for reliable type identification
  */
 import { open, readFile, realpath } from "fs/promises";
+import { STATUS_CODES } from "node:http";
 import { basename, isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep, } from "path";
 import { request } from "undici";
 import { redirectFollowingDispatcher } from "./redirectDispatcher.js";
@@ -675,21 +676,35 @@ export class FileDetector {
             new ContentHeuristicStrategy(),
         ];
         let best = null;
+        // #397: track which strategy produced `best` so the eventual log line
+        // can name it — the strategy instances themselves are gone by the time
+        // logging happens below, only their results survive.
+        let bestStrategyName = "none";
         for (const strategy of strategies) {
+            const strategyName = strategy.constructor.name;
             const result = await strategy.detect(strategy instanceof ExtensionStrategy && extensionInput
                 ? extensionInput
                 : input);
             if (!best || result.metadata.confidence > best.metadata.confidence) {
                 best = result;
+                bestStrategyName = strategyName;
             }
             if (result.metadata.confidence >= confidenceThreshold) {
-                logger.info(`[FileDetector] Type: ${result.type} (${result.metadata.confidence}%)`);
+                logger.info(`[FileDetector] Type: ${result.type} (${result.metadata.confidence}%, strategy: ${strategyName})`);
                 return FileDetector.withResolvedExtension(result, input, options);
             }
         }
-        // Below-threshold detection is the common case for any file under the
-        // ContentHeuristic ceiling — a debug detail, not a warning-worthy anomaly.
-        logger.debug(`[FileDetector] Best-effort type below threshold: ${best?.type ?? "unknown"} (${best?.metadata.confidence ?? 0}%, threshold ${confidenceThreshold}%)`);
+        // A genuinely unidentifiable input — every strategy failed to produce
+        // even a type — is a real failure, not a best-effort guess, so it is
+        // surfaced at error level instead of being buried in debug output.
+        if (!best || best.type === "unknown") {
+            logger.error(`[FileDetector] Detection failed: no strategy identified a type (best: ${bestStrategyName}, ${best?.metadata.confidence ?? 0}%, threshold ${confidenceThreshold}%)`);
+        }
+        else {
+            // Below-threshold detection is the common case for any file under the
+            // ContentHeuristic ceiling — a debug detail, not a warning-worthy anomaly.
+            logger.debug(`[FileDetector] Best-effort type below threshold: ${best.type} (${best.metadata.confidence}%, threshold ${confidenceThreshold}%, strategy: ${bestStrategyName})`);
+        }
         return FileDetector.withResolvedExtension(best, input, options);
     }
     /**
@@ -1543,9 +1558,15 @@ export class FileDetector {
                     bodyTimeout: timeout,
                 });
                 if (response.statusCode !== 200) {
-                    // Query string / fragment stripped — a presigned URL's token must
-                    // not be echoed into a thrown error.
-                    throw new Error(`HTTP ${response.statusCode} fetching ${redactUrlForError(url)}`);
+                    // #360: pair the code with its standard reason phrase (e.g. 404 →
+                    // "Not Found") so the message is readable rather than a bare
+                    // number. Sourced from Node's own `http.STATUS_CODES` table
+                    // rather than a hand-written map that could drift from it, and
+                    // falls back gracefully for a non-standard code that table
+                    // doesn't recognize. Query string / fragment stays stripped — a
+                    // presigned URL's token must not be echoed into a thrown error.
+                    const statusText = STATUS_CODES[response.statusCode];
+                    throw new Error(`HTTP ${response.statusCode}${statusText ? ` ${statusText}` : ""} fetching ${redactUrlForError(url)}`);
                 }
                 const contentType = response.headers["content-type"] || "";
                 const declaredLength = Number(response.headers["content-length"]);

package/dist/utils/messageBuilder.js

@@ -1877,10 +1877,14 @@ async function processImageToBase64(image, index) {
             const match = image.match(/^data:([^;]+);base64,(.+)$/);
             if (match) {
                 const declaredMime = match[1];
-                // #348: only accept image/* data URIs; reject a non-image MIME before
-                // it reaches a provider API rather than passing it through unchecked.
-                if (!declaredMime.startsWith("image/")) {
-                    throw new Error(`Unsupported data URI MIME type for image input at index ${index}: "${declaredMime}" (expected image/*)`);
+                // #348: validate against the actual supported-image allowlist, not
+                // just the "image/*" prefix — "image/invalid-format" started with
+                // "image/" and passed here, only to fail later at the provider.
+                // Reuses ImageProcessor's allowlist (itself sourced from
+                // imageFormatSupport's SUPPORTED_INPUT_IMAGE_MIME_TYPES) so intake
+                // validation can never drift from the set NeuroLink actually accepts.
+                if (!ImageProcessor.validateImageFormat(declaredMime)) {
+                    throw new Error(`Unsupported data URI MIME type for image input at index ${index}: "${declaredMime}" (not a supported image format)`);
                 }
                 mimeType = declaredMime;
                 imageData = match[2]; // Raw base64 only — NOT the full data: URI
@@ -2323,7 +2327,16 @@ pdfFiles, provider, model, audioFiles = []) {
             for (const pdf of pdfFiles) {
                 try {
                     const effectiveMaxPages = pdf.maxPages ?? PDF_LIMITS.DEFAULT_MAX_PAGES;
-                    const conversionResult = await PDFImageConverter.convertToImages(pdf.buffer, {
+                    // #302: stream pages one at a time instead of materialising every
+                    // rendered page before any of them reaches `content` — this is the
+                    // path generate()/stream() callers actually exercise, so it must
+                    // carry the memory characteristic convertToImagesStream was built
+                    // for. Per-page ordering, error isolation (#294) and the resulting
+                    // message content are kept identical to the batch path below;
+                    // only how the pages are produced changes.
+                    const pageErrors = [];
+                    let convertedCount = 0;
+                    for await (const page of PDFImageConverter.convertToImagesStream(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
@@ -2337,7 +2350,34 @@ pdfFiles, provider, model, audioFiles = []) {
                         ...(pdf.maxCanvasPixels
                             ? { maxCanvasPixels: pdf.maxCanvasPixels }
                             : {}), // #260
-                    });
+                    })) {
+                        if (page.error) {
+                            // #294: per-page isolation — a failed page is recorded and
+                            // skipped, not thrown, so the rest of the document still
+                            // reaches the model.
+                            pageErrors.push({ page: page.pageIndex, error: page.error });
+                            continue;
+                        }
+                        convertedCount++;
+                        // Add each page as an ImagePart (raw base64, not data: URI — see SSRF note above)
+                        content.push({
+                            type: "image",
+                            image: page.image,
+                            mimeType: "image/png",
+                        });
+                        logger.debug(`[PDF→Image] Added page ${page.pageIndex} of ${pdf.filename}`);
+                    }
+                    // Batch's convertToImages throws when nothing converted (either a
+                    // zero-page PDF or every page failed) instead of returning an empty
+                    // result; convertToImagesStream has no such guard (it simply yields
+                    // nothing / all-error pages), so replicate that contract explicitly
+                    // to keep the two paths' failure behavior identical.
+                    if (convertedCount === 0) {
+                        if (pageErrors.length > 0) {
+                            throw new Error(`All ${pageErrors.length} page(s) failed to render. First error: ${pageErrors[0].error}`);
+                        }
+                        throw new Error("PDF has 0 pages. Cannot convert empty PDF to images.");
+                    }
                     // 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.
@@ -2348,31 +2388,16 @@ pdfFiles, provider, model, audioFiles = []) {
                     // 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) {
+                    if (convertedCount >= 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}`);
-                        });
+                    if (pageErrors.length > 0) {
+                        logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)}: ${pageErrors.length} page(s) ` +
+                            `failed to render and were omitted (page ${pageErrors.map((e) => e.page).join(", ")}).`);
                     }
+                    logger.info(`[PDF→Image] ✅ Converted ${pdf.filename}: ${convertedCount} page(s) → images`);
                 }
                 catch (error) {
                     const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/utils/pdfProcessor.js

@@ -589,10 +589,32 @@ export class PDFProcessor {
         if (largestPixels > maxCanvasPixels) {
             effectiveScale = scale * Math.sqrt(maxCanvasPixels / largestPixels);
         }
-        const document = await pdf(pdfBuffer, {
-            scale: effectiveScale,
-            ...(password ? { password } : {}),
-        });
+        // #258: map pdfjs's PasswordException to the same actionable typed error
+        // convertToImages raises — kept in sync per the class docstring above.
+        // Unlike the per-page loop below, a failure here happens before any page
+        // can be isolated, so it must reject the generator outright rather than
+        // being yielded as a page error.
+        let document;
+        try {
+            document = await pdf(pdfBuffer, {
+                scale: effectiveScale,
+                ...(password ? { password } : {}),
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const pdfErr = error;
+            if (pdfErr?.name === "PasswordException" ||
+                /password/i.test(errorMessage)) {
+                const incorrect = pdfErr.code === 2 || /incorrect|invalid/i.test(errorMessage);
+                throw incorrect
+                    ? ErrorFactory.pdfIncorrectPassword()
+                    : ErrorFactory.pdfPasswordRequired();
+            }
+            throw new Error(`PDF to image conversion failed: ${errorMessage}`, {
+                cause: error,
+            });
+        }
         const totalPages = document.length;
         let converted = 0;
         for (let pageNum = 1; pageNum <= totalPages; pageNum++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.17.2",
+  "version": "12.17.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": {
@@ -80,6 +80,7 @@
     "test:context": "pnpm exec tsx test/continuous-test-suite-context.ts",
     "test:evaluation": "pnpm exec tsx test/continuous-test-suite-evaluation.ts",
     "test:handler-registry": "pnpm exec tsx test/continuous-test-suite-handler-registry.ts",
+    "test:harness-offline-timeout": "pnpm exec tsx test/continuous-test-suite-harness-offline-timeout.ts",
     "test:resolve-request-kind": "pnpm exec tsx test/continuous-test-suite-resolve-request-kind.ts",
     "test:mcp": "pnpm exec tsx test/continuous-test-suite-mcp-infra.ts",
     "test:tool-resolution": "pnpm exec tsx test/continuous-test-suite-tool-resolution.ts",
@@ -132,6 +133,7 @@
     "test:provider-fallback": "pnpm exec tsx test/continuous-test-suite-provider-fallback.ts",
     "test:provider-fallback-latency": "pnpm exec tsx test/continuous-test-suite-provider-fallback-latency.ts",
     "test:provider-wiring": "pnpm exec tsx test/continuous-test-suite-provider-wiring.ts",
+    "test:pdf-image-streaming": "pnpm exec tsx test/continuous-test-suite-pdf-image-streaming.ts",
     "test:rag": "pnpm exec tsx test/continuous-test-suite-rag.ts",
     "test:skills": "pnpm exec tsx test/continuous-test-suite-skills.ts",
     "test:servers": "pnpm exec tsx test/continuous-test-suite-servers.ts",
@@ -251,7 +253,8 @@
     "test:anthropic-execution-control": "tsx test/continuous-test-suite-anthropic-execution-control.ts",
     "test:aistudio-loop-characterization": "tsx test/continuous-test-suite-aistudio-loop-characterization.ts",
     "test:docs-mcp": "pnpm exec tsx test/continuous-test-suite-docs-mcp.ts",
-    "test:vertex-claude-characterization": "tsx test/continuous-test-suite-vertex-claude-characterization.ts"
+    "test:vertex-claude-characterization": "tsx test/continuous-test-suite-vertex-claude-characterization.ts",
+    "test:toolfree-guard-overhead": "pnpm exec tsx test/continuous-test-suite-toolfree-guard-overhead.ts"
   },
   "files": [
     "dist",