@juspay/neurolink 12.0.1 → 12.0.3

package/dist/cli/commands/models.js

@@ -320,6 +320,48 @@ export class ModelsCommandFactory {
             if (!argv.deprecated) {
                 models = models.filter((model) => !model.deprecated);
             }
+            // Live-discovery fallback: providers that resolve their catalog at
+            // runtime (litellm, ollama, openai-compatible gateways) have no static
+            // registry rows, so a scoped `models list --provider litellm` printed
+            // "Found 0 models" while generate/stream against those models worked.
+            // When the static registry is empty for a single requested provider,
+            // ask the provider itself.
+            if (models.length === 0 &&
+                argv.provider &&
+                (Array.isArray(argv.provider) ? argv.provider : [argv.provider])
+                    .length === 1) {
+                const providerName = String(Array.isArray(argv.provider) ? argv.provider[0] : argv.provider);
+                try {
+                    const { AIProviderFactory } = await import("../../core/factory.js");
+                    const provider = (await AIProviderFactory.createProvider(providerName));
+                    const liveIds = typeof provider.getAvailableModels === "function"
+                        ? await provider.getAvailableModels()
+                        : [];
+                    if (liveIds.length > 0) {
+                        if (spinner) {
+                            spinner.succeed(`Found ${liveIds.length} models (live from ${providerName})`);
+                        }
+                        if (argv.format === "json") {
+                            logger.always(JSON.stringify(liveIds.map((id) => ({
+                                id,
+                                provider: providerName,
+                                source: "live",
+                            })), null, 2));
+                        }
+                        else {
+                            logger.always(chalk.bold(`\n📋 Models exposed by ${providerName} (live discovery):\n`));
+                            for (const id of liveIds) {
+                                logger.always(`  ${id}`);
+                            }
+                        }
+                        return;
+                    }
+                }
+                catch {
+                    // Live discovery is best-effort — fall through to the static
+                    // (empty) listing rather than turning a listing into an error.
+                }
+            }
             if (spinner) {
                 spinner.succeed(`Found ${models.length} models`);
             }

package/dist/core/baseProvider.js

@@ -1,6 +1,7 @@
 import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import { directAgentTools } from "../agent/directTools.js";
 import { defaultProviderFor } from "../factories/mediaHandlerCatalog.js";
+import { PROVIDER_DESCRIPTORS_BY_NAME } from "../factories/providerDescriptors.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
 import { resolveRequestKind } from "./resolveRequestKind.js";
@@ -1243,14 +1244,23 @@ export class BaseProvider {
         }, options, startTime);
     }
     async executeStandardGenerateFlow(options, startTime, model, messages, tools) {
-        // Apply a defensive default timeout (3 min) when the caller didn't pass
-        // one. Without this guard, AI SDK's generateText() will wait forever on
+        // Apply a defensive default timeout when the caller didn't pass one.
+        // Without this guard, AI SDK's generateText() will wait forever on
         // an upstream that accepts the connection but never produces a response
         // (observed against the litellm gateway when a request triggers the
         // team-access denial path — connection stays open, no response is sent,
         // and the matrix test hangs the entire suite). Callers can still pass
         // a larger value (e.g. video generation passes 10 min).
-        const effectiveTimeout = options.timeout ?? 180_000;
+        //
+        // A provider descriptor may declare a LARGER generate budget than the
+        // 3-min floor (litellm: 300s — slow proxied models routinely need more
+        // than 180s end-to-end even while streaming). The declared value only
+        // ever raises the default, never lowers it: several descriptors carry
+        // aspirational sub-180s numbers (openai 30s, bedrock 45s) that were
+        // never enforced on this path, and enforcing them now would break
+        // long-running generations that have always been allowed.
+        const descriptorGenerateMs = PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName)?.timeouts?.generateMs;
+        const effectiveTimeout = options.timeout ?? Math.max(descriptorGenerateMs ?? 0, 180_000);
         const timeoutController = createTimeoutController(effectiveTimeout, this.providerName, "generate");
         const composedSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
         const composedOptions = composedSignal

package/dist/core/modules/GenerationHandler.js

@@ -731,7 +731,11 @@ export class GenerationHandler {
                             toolName;
                         toolsUsed.push(toolName);
                         let callArgs = {};
-                        if (tcRecord.args) {
+                        if (tcRecord.input) {
+                            // AI SDK v6 carries tool-call arguments as `input`.
+                            callArgs = tcRecord.input;
+                        }
+                        else if (tcRecord.args) {
                             callArgs = tcRecord.args;
                         }
                         else if (tcRecord.arguments) {

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

@@ -102,7 +102,7 @@ import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 import { runWorkflow } from "./workflow/core/workflowRunner.js";
 import { ModelPool, classifyProviderError } from "./routing/index.js";
 import { ClassifierRouter } from "./routing/classifierRouter.js";
-import { looksLikeModelAccessDenied as sharedLooksLikeModelAccessDenied, isNonRetryableProviderError as sharedIsNonRetryableProviderError, isNonRetryableForPool as sharedIsNonRetryableForPool, } from "./utils/providerErrorClassification.js";
+import { looksLikeModelAccessDenied as sharedLooksLikeModelAccessDenied, looksLikeModelNotFound as sharedLooksLikeModelNotFound, isNonRetryableProviderError as sharedIsNonRetryableProviderError, isNonRetryableForPool as sharedIsNonRetryableForPool, } from "./utils/providerErrorClassification.js";
 import { getErrorStatusCode } from "./utils/providerRetry.js";
 import { detectAndRedactPII } from "./utils/piiDetector.js";
 import { validateResponse } from "./utils/responseValidator.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();
@@ -3211,6 +3228,16 @@ Current user's request: ${currentInput}`;
         // String prompts are immutable, so they pass through.
         if (typeof optionsOrPrompt !== "string") {
             optionsOrPrompt = cloneOptionsForCallIsolation(optionsOrPrompt);
+            // The deprecated `conversationHistory` field is not wired into message
+            // building — messages passed there never reach the model, which reads
+            // as "the SDK forgot my context" rather than a caller bug. Warn loudly
+            // instead of failing silently; `conversationMessages` is the wired path.
+            const legacyOpts = optionsOrPrompt;
+            if (Array.isArray(legacyOpts.conversationHistory) &&
+                legacyOpts.conversationHistory.length > 0 &&
+                !legacyOpts.conversationMessages) {
+                logger.warn("[NeuroLink.generate] `conversationHistory` is deprecated and NOT passed to the model — use `conversationMessages` (ChatMessage[]) instead.");
+            }
         }
         // Retrieve once at the public call boundary so fallback attempts reuse the
         // same grounding block and internal preparation cannot inject it twice.
@@ -3347,9 +3374,14 @@ Current user's request: ${currentInput}`;
         // mid-fallback; cloneOptionsForCallIsolation keeps abortSignal
         // by-reference, so the retried options observe the same signal.
         const callerAborted = () => callOpts.abortSignal?.aborted === true;
+        // modelChain-only orchestration advances on two error shapes the next
+        // member can actually fix: access-denied (the original gate) and
+        // model-not-found ("Invalid model name" from a gateway that doesn't
+        // serve that member — a chain written for one LiteLLM deployment must
+        // not hard-fail on another just because a member is absent there).
         const shouldOrchestrateFallback = (err) => effectiveCallback
             ? !(isAbortError(err) && callerAborted())
-            : looksLikeModelAccessDenied(err);
+            : looksLikeModelAccessDenied(err) || sharedLooksLikeModelNotFound(err);
         if (!shouldOrchestrateFallback(lastError)) {
             throw lastError;
         }
@@ -3494,6 +3526,8 @@ Current user's request: ${currentInput}`;
         }
         finally {
             this._disableToolCacheForCurrentRequest = false;
+            this._toolCacheKeysServedThisRequest = new Set();
+            this._generationTurnActive = false;
             generateSpan.end();
         }
     }
@@ -3512,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"
@@ -6657,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();
@@ -7289,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();
             }
@@ -7588,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);
@@ -10032,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 ===
@@ -10049,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) {
@@ -11500,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/providers/litellm/client.js

@@ -367,8 +367,11 @@ export class LiteLLMProvider extends OpenAIChatCompletionsProvider {
             {
                 match: (ctx) => /ECONNREFUSED|Failed to fetch/.test(ctx.message),
                 errorClass: NetworkError,
+                // Name the base URL this instance actually dialed — per-request
+                // credentials can override LITELLM_BASE_URL, and an error pointing
+                // at the env value sends the caller debugging the wrong host.
                 message: () => "LiteLLM proxy server not available. Please start the LiteLLM proxy server at " +
-                    `${process.env.LITELLM_BASE_URL || "http://localhost:4000"}`,
+                    redactUrlCredentials(this.config.baseURL),
             },
             {
                 match: (ctx) => /API_KEY_INVALID|Invalid API key/.test(ctx.message),
@@ -420,7 +423,12 @@ export class LiteLLMProvider extends OpenAIChatCompletionsProvider {
         return this.getFallbackModels();
     }
     async fetchModelsFromAPI() {
-        const modelsUrl = `${stripTrailingSlash(this.config.baseURL)}/v1/models`;
+        // Tolerate a `/v1`-suffixed base URL. Chat appends /chat/completions, so
+        // deployments are commonly configured with base = https://host/v1 — but
+        // appending /v1/models to that yields /v1/v1/models, which LiteLLM 404s,
+        // and discovery silently degrades to the hardcoded fallback list.
+        const root = stripTrailingSlash(this.config.baseURL).replace(/\/v1$/, "");
+        const modelsUrl = `${root}/v1/models`;
         const proxyFetch = createProxyFetch();
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), 5000);

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/providerErrorClassification.js

@@ -67,7 +67,11 @@ export function looksLikeModelNotFound(error) {
         lower.includes("not_found_error") ||
         msg.includes("NOT_FOUND") ||
         lower.includes("does not exist") ||
-        lower.includes("unknown model")) &&
+        lower.includes("unknown model") ||
+        // LiteLLM's phrasing for a model id its router doesn't serve — a 400,
+        // not a 404: "Invalid model name passed in model=... Call `/v1/models`
+        // to view available models for your key."
+        lower.includes("invalid model name")) &&
         namesAModel);
 }
 /**

package/dist/utils/providerHealth.js

@@ -808,13 +808,37 @@ export class ProviderHealthChecker {
             healthStatus.recommendations.push("Set LITELLM_BASE_URL to a valid URL (e.g., http://localhost:4000)");
             return;
         }
-        const availability = await this.checkLiteLLMAvailability({
-            model: this.getConfiguredLiteLLMModel(),
-            timeout,
-        });
-        if (!availability.available) {
+        // Only pin the availability check to a specific model when the user
+        // explicitly configured one. The fallback default ("openai/gpt-4o-mini")
+        // is a guess, not configuration — proxies that serve a different model
+        // set (every self-hosted gateway) were reported "Not configured" here
+        // while generate/stream against them worked fine with explicit models.
+        const configuredModel = process.env.LITELLM_MODEL;
+        let failureReason;
+        if (configuredModel) {
+            const availability = await this.checkLiteLLMAvailability({
+                model: configuredModel,
+                timeout,
+            });
+            if (!availability.available) {
+                failureReason = availability.reason ?? "unknown error";
+            }
+        }
+        else {
+            // No configured model: a reachable proxy with any models counts.
+            try {
+                const models = await this.getLiteLLMAvailableModels(timeout);
+                if (models.length === 0) {
+                    failureReason = "LiteLLM returned an empty model list";
+                }
+            }
+            catch (error) {
+                failureReason = error instanceof Error ? error.message : String(error);
+            }
+        }
+        if (failureReason !== undefined) {
             healthStatus.isConfigured = false;
-            healthStatus.configurationIssues.push(`LiteLLM runtime check failed: ${availability.reason ?? "unknown error"}`);
+            healthStatus.configurationIssues.push(`LiteLLM runtime check failed: ${failureReason}`);
             healthStatus.recommendations.push("Start the LiteLLM proxy and ensure the configured model is available from /v1/models");
             return;
         }

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