@juspay/neurolink 9.94.4 → 9.94.6

package/dist/core/modules/MessageBuilder.js

@@ -22,7 +22,18 @@ function computeTotalContentLength(messages) {
     return total;
 }
 /**
- * Check whether input contains multimodal content (images, files, PDFs, CSVs).
+ * Check whether input contains multimodal content (images, files, PDFs, CSVs,
+ * audio, video). #284: audioFiles/videoFiles were previously ignored here, so a
+ * request carrying only audio or video was misrouted to the text-only path.
+ *
+ * Intentional (round-2 review): routing audio/video through `isMultimodal`
+ * does NOT mean vision is required. `buildMultimodalMessagesArray` folds
+ * `audioFiles`/`videoFiles` into `inp.files` for auto-detection, and
+ * `appendDetectedFileResult` injects their content as plain text markers
+ * (`## Audio File:` / `## Video File:`), not image/vision blocks — see
+ * `test/continuous-test-suite-bugfixes.ts` ("MessageBuilder #284: ...").
+ * "Multimodal" here means "needs the multimodal builder so the payload isn't
+ * dropped", not "needs a vision model".
  */
 function detectMultimodal(opts) {
     const input = opts.input;
@@ -31,10 +42,18 @@ function detectMultimodal(opts) {
     const hasCSVFiles = !!input?.csvFiles?.length;
     const hasPdfFiles = !!input?.pdfFiles?.length;
     const hasFiles = !!input?.files?.length;
+    const hasAudioFiles = !!input?.audioFiles?.length;
+    const hasVideoFiles = !!input?.videoFiles?.length;
     return {
-        isMultimodal: hasImages || hasContent || hasCSVFiles || hasPdfFiles || hasFiles,
+        isMultimodal: hasImages ||
+            hasContent ||
+            hasCSVFiles ||
+            hasPdfFiles ||
+            hasFiles ||
+            hasAudioFiles ||
+            hasVideoFiles,
         hasImages,
-        hasFiles: hasCSVFiles || hasPdfFiles || hasFiles,
+        hasFiles: hasCSVFiles || hasPdfFiles || hasFiles || hasAudioFiles || hasVideoFiles,
     };
 }
 /**
@@ -75,6 +94,12 @@ export class MessageBuilder {
                         content: input?.content,
                         csvFiles: input?.csvFiles,
                         pdfFiles: input?.pdfFiles,
+                        // #284: audioFiles/videoFiles must be forwarded too, or the
+                        // multimodal builder receives an empty payload despite
+                        // detectMultimodal() correctly routing audio/video-only
+                        // requests here.
+                        audioFiles: input?.audioFiles,
+                        videoFiles: input?.videoFiles,
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
@@ -192,6 +217,10 @@ export class MessageBuilder {
                         content: input?.content,
                         csvFiles: input?.csvFiles,
                         pdfFiles: input?.pdfFiles,
+                        // #284: forward audioFiles/videoFiles here too — see the
+                        // matching comment in buildMessages() above.
+                        audioFiles: input?.audioFiles,
+                        videoFiles: input?.videoFiles,
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,

package/dist/lib/core/modules/MessageBuilder.js

@@ -22,7 +22,18 @@ function computeTotalContentLength(messages) {
     return total;
 }
 /**
- * Check whether input contains multimodal content (images, files, PDFs, CSVs).
+ * Check whether input contains multimodal content (images, files, PDFs, CSVs,
+ * audio, video). #284: audioFiles/videoFiles were previously ignored here, so a
+ * request carrying only audio or video was misrouted to the text-only path.
+ *
+ * Intentional (round-2 review): routing audio/video through `isMultimodal`
+ * does NOT mean vision is required. `buildMultimodalMessagesArray` folds
+ * `audioFiles`/`videoFiles` into `inp.files` for auto-detection, and
+ * `appendDetectedFileResult` injects their content as plain text markers
+ * (`## Audio File:` / `## Video File:`), not image/vision blocks — see
+ * `test/continuous-test-suite-bugfixes.ts` ("MessageBuilder #284: ...").
+ * "Multimodal" here means "needs the multimodal builder so the payload isn't
+ * dropped", not "needs a vision model".
  */
 function detectMultimodal(opts) {
     const input = opts.input;
@@ -31,10 +42,18 @@ function detectMultimodal(opts) {
     const hasCSVFiles = !!input?.csvFiles?.length;
     const hasPdfFiles = !!input?.pdfFiles?.length;
     const hasFiles = !!input?.files?.length;
+    const hasAudioFiles = !!input?.audioFiles?.length;
+    const hasVideoFiles = !!input?.videoFiles?.length;
     return {
-        isMultimodal: hasImages || hasContent || hasCSVFiles || hasPdfFiles || hasFiles,
+        isMultimodal: hasImages ||
+            hasContent ||
+            hasCSVFiles ||
+            hasPdfFiles ||
+            hasFiles ||
+            hasAudioFiles ||
+            hasVideoFiles,
         hasImages,
-        hasFiles: hasCSVFiles || hasPdfFiles || hasFiles,
+        hasFiles: hasCSVFiles || hasPdfFiles || hasFiles || hasAudioFiles || hasVideoFiles,
     };
 }
 /**
@@ -75,6 +94,12 @@ export class MessageBuilder {
                         content: input?.content,
                         csvFiles: input?.csvFiles,
                         pdfFiles: input?.pdfFiles,
+                        // #284: audioFiles/videoFiles must be forwarded too, or the
+                        // multimodal builder receives an empty payload despite
+                        // detectMultimodal() correctly routing audio/video-only
+                        // requests here.
+                        audioFiles: input?.audioFiles,
+                        videoFiles: input?.videoFiles,
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
@@ -192,6 +217,10 @@ export class MessageBuilder {
                         content: input?.content,
                         csvFiles: input?.csvFiles,
                         pdfFiles: input?.pdfFiles,
+                        // #284: forward audioFiles/videoFiles here too — see the
+                        // matching comment in buildMessages() above.
+                        audioFiles: input?.audioFiles,
+                        videoFiles: input?.videoFiles,
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,

package/dist/lib/types/generate.d.ts

@@ -53,6 +53,7 @@ export type GenerateOptions = {
         images?: Array<Buffer | string | ImageWithAltText>;
         csvFiles?: Array<Buffer | string>;
         pdfFiles?: Array<Buffer | string>;
+        audioFiles?: Array<Buffer | string>;
         videoFiles?: Array<Buffer | string>;
         files?: Array<Buffer | string | FileWithMetadata>;
         content?: Content[];

package/dist/lib/types/multimodal.d.ts

@@ -419,15 +419,46 @@ export type MultimodalInput = {
     segments?: DirectorSegment[];
 };
 /**
- * Content format for multimodal messages (used internally)
- * Compatible with Vercel AI SDK message format
+ * Content format for multimodal messages (used internally).
+ *
+ * #325: the loose `[key: string]: unknown` index signature has been replaced
+ * with the concrete fields the codebase actually reads/writes across the
+ * text / image / file / tool-call / tool-result shapes. This keeps the broad
+ * structural compatibility the internal pipeline relies on (a single object
+ * type, not a strict discriminated union that would force narrowing at every
+ * consumer) while removing the "any key is allowed" hole that let typos and
+ * unrelated keys through unchecked.
  */
 export type MessageContent = {
     type: string;
+    /** Text content (`type: "text"`). */
     text?: string;
+    /** Base64 / data-URI image (`type: "image"`). */
     image?: string;
+    /** MIME type for image/file parts. */
     mimeType?: string;
-    [key: string]: unknown;
+    /** Raw file bytes or base64 (`type: "file"`/document parts). */
+    data?: string | Buffer;
+    /** File name for document/file parts. */
+    name?: string;
+    /** File name (alias used by some file parts). */
+    filename?: string;
+    /** Tool-call identifier (`type: "tool-call"`/`"tool-result"`). */
+    toolCallId?: string;
+    /** Tool name (`type: "tool-call"`/`"tool-result"`). */
+    toolName?: string;
+    /** Tool-call arguments (`type: "tool-call"`). */
+    args?: Record<string, unknown>;
+    /** Tool-result payload (`type: "tool-result"`). */
+    result?: unknown;
+    /** Whether a tool-result represents an error (`type: "tool-result"`). */
+    isError?: boolean;
+    /**
+     * Provider-specific per-block options (e.g. Anthropic cache_control).
+     * Read as `item.providerOptions` when converting `MessageContent[]` to
+     * `ModelMessage[]` in `MessageBuilder.ts`.
+     */
+    providerOptions?: Record<string, unknown>;
 };
 /**
  * Extended chat message for multimodal support (internal use)

package/dist/lib/types/stream.d.ts

@@ -193,6 +193,7 @@ export type StreamOptions = {
         images?: Array<Buffer | string | ImageWithAltText>;
         csvFiles?: Array<Buffer | string>;
         pdfFiles?: Array<Buffer | string>;
+        audioFiles?: Array<Buffer | string>;
         videoFiles?: Array<Buffer | string>;
         files?: Array<Buffer | string | FileWithMetadata>;
         content?: Content[];

package/dist/lib/utils/errorHandling.d.ts

@@ -35,6 +35,9 @@ export declare const ERROR_CODES: {
     readonly IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL";
     readonly INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT";
     readonly INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE";
+    readonly IMAGE_BUFFER_INVALID: "IMAGE_BUFFER_INVALID";
+    readonly FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED";
+    readonly CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED";
     readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
     readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
     readonly RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT";
@@ -216,6 +219,13 @@ export declare class ErrorFactory {
      * Create an invalid image format error
      */
     static invalidImageFormat(): NeuroLinkError;
+    /**
+     * Create an image buffer validation error: empty, undersized, or a
+     * truncated buffer detected by `ImageProcessor.validateBufferNotEmpty()`.
+     * Takes the fully-formed message so call sites keep their specific
+     * byte-count detail instead of a fixed generic message.
+     */
+    static imageBufferInvalid(message: string): NeuroLinkError;
     /**
      * Create a rate limiter queue full error
      */
@@ -287,6 +297,18 @@ export declare class ErrorFactory {
      * generic `Error` instances.
      */
     static proxyWorkerLifecycle(message: string, context?: Record<string, unknown>): NeuroLinkError;
+    /**
+     * Create a generic file-processing-failed error (e.g. an unrecognized or
+     * corrupt file in `processUnifiedFilesArray`). Preserves the original error
+     * as `originalError` (stack + message copied onto the new error's context).
+     */
+    static fileProcessingFailed(filename: string, originalError: Error): NeuroLinkError;
+    /**
+     * Create a generic CSV-processing-failed error (explicit `csvFiles` path,
+     * distinct from `fileProcessingFailed` so callers can classify CSV-specific
+     * failures separately). Preserves the original error as `originalError`.
+     */
+    static csvProcessingFailed(filename: string, originalError: Error): NeuroLinkError;
 }
 /**
  * Timeout wrapper for async operations

package/dist/lib/utils/errorHandling.js

@@ -46,6 +46,10 @@ export const ERROR_CODES = {
     IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL",
     INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT",
     INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE",
+    IMAGE_BUFFER_INVALID: "IMAGE_BUFFER_INVALID",
+    // Generic file/CSV processing errors
+    FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED",
+    CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED",
     // PDF validation errors
     PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
     // Rate limiter errors
@@ -627,6 +631,22 @@ export class ErrorFactory {
             },
         });
     }
+    /**
+     * Create an image buffer validation error: empty, undersized, or a
+     * truncated buffer detected by `ImageProcessor.validateBufferNotEmpty()`.
+     * Takes the fully-formed message so call sites keep their specific
+     * byte-count detail instead of a fixed generic message.
+     */
+    static imageBufferInvalid(message) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.IMAGE_BUFFER_INVALID,
+            message,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { field: "input.images" },
+        });
+    }
     // ============================================================================
     // RATE LIMITER ERRORS
     // ============================================================================
@@ -924,6 +944,41 @@ export class ErrorFactory {
             context: context || {},
         });
     }
+    // ============================================================================
+    // GENERIC FILE / CSV PROCESSING ERRORS
+    // ============================================================================
+    /**
+     * Create a generic file-processing-failed error (e.g. an unrecognized or
+     * corrupt file in `processUnifiedFilesArray`). Preserves the original error
+     * as `originalError` (stack + message copied onto the new error's context).
+     */
+    static fileProcessingFailed(filename, originalError) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.FILE_PROCESSING_FAILED,
+            message: `Failed to process file "${filename}": ${originalError.message}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: { filename },
+            originalError,
+        });
+    }
+    /**
+     * Create a generic CSV-processing-failed error (explicit `csvFiles` path,
+     * distinct from `fileProcessingFailed` so callers can classify CSV-specific
+     * failures separately). Preserves the original error as `originalError`.
+     */
+    static csvProcessingFailed(filename, originalError) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.CSV_PROCESSING_FAILED,
+            message: `Failed to process CSV file "${filename}": ${originalError.message}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: { filename },
+            originalError,
+        });
+    }
 }
 /**
  * Timeout wrapper for async operations

package/dist/lib/utils/fileDetector.js

@@ -4,7 +4,7 @@
  * Uses multi-strategy approach for reliable type identification
  */
 import { open, readFile, realpath } from "fs/promises";
-import { isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep, } from "path";
+import { basename, isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep, } from "path";
 import { getGlobalDispatcher, interceptors, request } from "undici";
 // Lazy-loaded processor singletons — avoids loading heavy media deps
 // (mediabunny, fluent-ffmpeg, music-metadata, adm-zip) on every generate() call.
@@ -24,6 +24,8 @@ import { tracers, ATTR, withSpan } from "../telemetry/index.js";
 import { CSVProcessor } from "./csvProcessor.js";
 import { ImageProcessor } from "./imageProcessor.js";
 import { logger } from "./logger.js";
+import { withTimeout } from "./errorHandling.js";
+import { redactUrlForError, sanitizeErrorCause } from "./logSanitize.js";
 import { mimeHintToExtension, mimeHintToFileType, normalizeMimeHint, } from "./mimeTypeHints.js";
 import { PDFProcessor } from "./pdfProcessor.js";
 /**
@@ -31,6 +33,80 @@ import { PDFProcessor } from "./pdfProcessor.js";
  */
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_RETRY_DELAY = 1000; // milliseconds
+/**
+ * Short-TTL cache of URL → Content-Type (#323). A URL is commonly detected more
+ * than once (repeated multimodal prompts reuse the same asset URL); caching the
+ * HEAD's content-type avoids re-issuing the HEAD each time. `loadFromURL` also
+ * populates it from its GET response, so once a URL's body has been fetched a
+ * subsequent detection needs no network round-trip at all.
+ *
+ * Trade-off (round-2 review): this is a module-level cache shared by every
+ * request in the process, and correctness relies solely on the 60s TTL — a
+ * signed URL whose response changes at the same path within that window would
+ * read stale. That is an intentional, bounded trade-off (60s of possible
+ * staleness for far fewer HEAD round-trips), not a freshness guarantee.
+ * Expired entries are removed lazily on their next `get()` (see
+ * `getCachedUrlContentType`); `setCachedUrlContentType` additionally sweeps
+ * expired entries opportunistically once the cache hits its size cap, so a
+ * URL that is cached once and never looked up again doesn't linger until the
+ * FIFO eviction below forces it out.
+ */
+const URL_CONTENT_TYPE_TTL_MS = 60_000;
+const URL_CONTENT_TYPE_CACHE_MAX_SIZE = 512;
+const urlContentTypeCache = new Map();
+function getCachedUrlContentType(url, now) {
+    const hit = urlContentTypeCache.get(url);
+    if (hit && hit.expiresAt > now) {
+        // Bump recency: Map iteration order follows insertion order, and the
+        // eviction below deletes the *first* key, so a plain `get` on a hot
+        // entry would leave it first in line for eviction despite being the
+        // most recently used. Re-inserting turns the size-bounded FIFO below
+        // into an actual LRU.
+        urlContentTypeCache.delete(url);
+        urlContentTypeCache.set(url, hit);
+        return hit.contentType;
+    }
+    if (hit) {
+        // Entry exists but its TTL has passed — treat as a miss and evict it
+        // immediately rather than serving (or retaining) stale data.
+        urlContentTypeCache.delete(url);
+    }
+    return undefined;
+}
+/**
+ * Opportunistically remove already-expired entries. Only called once the
+ * cache is at its size cap (see `setCachedUrlContentType`) so it doesn't add
+ * an O(n) scan to the common-case hot path.
+ */
+function pruneExpiredUrlContentTypeEntries(now) {
+    for (const [key, entry] of urlContentTypeCache) {
+        if (entry.expiresAt <= now) {
+            urlContentTypeCache.delete(key);
+        }
+    }
+}
+function setCachedUrlContentType(url, contentType, now) {
+    if (!contentType) {
+        return;
+    }
+    urlContentTypeCache.set(url, {
+        contentType,
+        expiresAt: now + URL_CONTENT_TYPE_TTL_MS,
+    });
+    // Bound the cache so a long-lived process can't grow it unbounded. Prefer
+    // reclaiming already-expired entries first; only fall back to evicting the
+    // oldest still-live entry (FIFO/LRU-ish, see getCachedUrlContentType) if
+    // the cache is still over the cap after pruning.
+    if (urlContentTypeCache.size > URL_CONTENT_TYPE_CACHE_MAX_SIZE) {
+        pruneExpiredUrlContentTypeEntries(now);
+    }
+    if (urlContentTypeCache.size > URL_CONTENT_TYPE_CACHE_MAX_SIZE) {
+        const oldest = urlContentTypeCache.keys().next().value;
+        if (oldest !== undefined) {
+            urlContentTypeCache.delete(oldest);
+        }
+    }
+}
 /**
  * Retryable network error codes (Node.js/undici network errors)
  */
@@ -1338,25 +1414,58 @@ export class FileDetector {
         const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
         const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY;
         return withRetry(async () => {
-            const response = await request(url, {
-                dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
-                method: "GET",
-                headersTimeout: timeout,
-                bodyTimeout: timeout,
-            });
-            if (response.statusCode !== 200) {
-                throw new Error(`HTTP ${response.statusCode} fetching ${url}`);
-            }
-            const chunks = [];
-            let totalSize = 0;
-            for await (const chunk of response.body) {
-                totalSize += chunk.length;
-                if (totalSize > maxSize) {
-                    throw new Error(`File too large: ${formatFileSize(totalSize)} (max: ${formatFileSize(maxSize)})`);
+            try {
+                const response = await request(url, {
+                    dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
+                    method: "GET",
+                    headersTimeout: timeout,
+                    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)}`);
+                }
+                // #323: cache the Content-Type from this GET so a subsequent detection
+                // of the same URL needs no HEAD.
+                setCachedUrlContentType(url, response.headers["content-type"] || "", Date.now());
+                const chunks = [];
+                let totalSize = 0;
+                for await (const chunk of response.body) {
+                    totalSize += chunk.length;
+                    if (totalSize > maxSize) {
+                        throw new Error(`File too large: ${formatFileSize(totalSize)} (max: ${formatFileSize(maxSize)})`);
+                    }
+                    chunks.push(chunk);
+                }
+                return Buffer.concat(chunks);
+            }
+            catch (error) {
+                // Node/undici DNS, TLS, and connect-timeout errors embed the full
+                // request URL (including a presigned query token) in
+                // `error.message`. Redact into a NEW error instead of mutating the
+                // original in place, so anything that still holds a reference to
+                // the original — debug logs, telemetry spans, upstream callers —
+                // keeps seeing the real message. `.code` is copied onto the new
+                // error so `isRetryableNetworkError`'s retry check in the outer
+                // `withRetry` catch still classifies it correctly. The raw
+                // original error is NEVER attached as `cause` — that would leave
+                // the unredacted URL reachable via `error.cause.message` for
+                // anything that walks the cause chain (cause-aware logging,
+                // telemetry). `cause` instead gets its own sanitized copy.
+                // `sanitizeErrorCause` handles non-`Error` thrown values too (a raw
+                // string/object can just as easily carry the full URL), so there is
+                // no unconditional `throw error` fallback that would bypass
+                // redaction for that case.
+                const cause = sanitizeErrorCause(error);
+                const redacted = new Error(cause.message, { cause });
+                redacted.name = cause.name;
+                const code = cause.code;
+                if (code !== undefined) {
+                    redacted.code = code;
                 }
-                chunks.push(chunk);
+                throw redacted;
             }
-            return Buffer.concat(chunks);
         }, { maxRetries, retryDelay });
     }
     /**
@@ -1374,6 +1483,13 @@ export class FileDetector {
         // the base dir pointing outside cannot bypass containment. The
         // path.relative check (not a string prefix) correctly handles the root dir
         // ("/") and sibling-prefix ("/app" vs "/app-evil") edge cases.
+        //
+        // The actual open() below MUST target this validated `real` path, not the
+        // original `filePath` — otherwise a symlink swapped between the realpath()
+        // check and the open() call routes the read outside the sandbox even
+        // though validation passed (TOCTOU). With no sandbox configured there's no
+        // boundary to defend, so the original path is used as given.
+        let pathToOpen = filePath;
         if (options?.allowedBaseDir) {
             let base;
             let real;
@@ -1381,24 +1497,66 @@ export class FileDetector {
                 base = await realpath(resolvePath(options.allowedBaseDir));
                 real = await realpath(filePath);
             }
-            catch {
-                throw new Error(`Access denied: "${filePath}" could not be resolved within the allowed base directory`);
+            catch (error) {
+                // Full path stays in the debug log; the thrown (potentially
+                // client-facing) error only gets the basename to avoid leaking the
+                // host's directory layout to an untrusted caller. The cause is
+                // sanitized too — Node's realpath ENOENT/EACCES messages embed the
+                // full path verbatim, which would otherwise survive on the cause
+                // chain (cause-aware logging, telemetry) even though the outer
+                // message is already redacted.
+                logger.debug("loadFromPath: realpath resolution failed", {
+                    filePath,
+                    error,
+                });
+                // Assigned to a variable before the throw (rather than an inline
+                // `{ cause: sanitizeErrorCause(...) }`) so the sanitized, path-redacted
+                // copy is unambiguously the attached cause — the raw `error`, whose
+                // message still embeds the full path, is never reachable from the
+                // thrown result.
+                const cause = sanitizeErrorCause(error, { filePath });
+                const denied = new Error(`Access denied: "${basename(filePath)}" could not be resolved within the allowed base directory`, { cause });
+                throw denied;
             }
             const rel = relativePath(base, real);
             if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolutePath(rel)) {
-                throw new Error(`Access denied: "${filePath}" resolves outside the allowed base directory`);
+                logger.debug("loadFromPath: path resolves outside allowed base dir", {
+                    filePath,
+                    real,
+                });
+                throw new Error(`Access denied: "${basename(filePath)}" resolves outside the allowed base directory`);
             }
+            pathToOpen = real;
         }
         // Open a handle and stat/read through the SAME descriptor so a symlink
         // swap between the size check and the read cannot occur (TOCTOU).
-        const handle = await open(filePath, "r");
+        let handle;
+        try {
+            handle = await open(pathToOpen, "r");
+        }
+        catch (error) {
+            // A failed open (ENOENT/EACCES/…) embeds the opened path verbatim in
+            // its message. When a sandbox is configured `pathToOpen` is the
+            // realpath-resolved target (`real`), which differs from both `filePath`
+            // and its resolved form — so redact `pathToOpen` specifically, or the
+            // full host path would survive on both the thrown message and the cause
+            // chain despite this PR's path-redaction hardening.
+            const cause = sanitizeErrorCause(error, { filePath: pathToOpen });
+            const failed = new Error(cause.message, { cause });
+            failed.name = cause.name;
+            const code = cause.code;
+            if (code !== undefined) {
+                failed.code = code;
+            }
+            throw failed;
+        }
         try {
             const statInfo = await handle.stat();
             if (!statInfo.isFile()) {
-                throw new Error(`Not a file: ${filePath}`);
+                throw new Error(`Not a file: ${basename(filePath)}`);
             }
             if (statInfo.size > maxSize) {
-                throw new Error(`File too large: ${filePath} is ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
+                throw new Error(`File too large: ${basename(filePath)} is ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
             }
             return await handle.readFile();
         }
@@ -1450,6 +1608,15 @@ class MagicBytesStrategy {
             input[6] === 0x79 &&
             input[7] === 0x70) {
             const brand = input.length >= 12 ? input.toString("latin1", 8, 12) : "";
+            // AVIF images share the ISO-BMFF ftyp box with MP4/MOV; the major brand
+            // ('avif' still, 'avis' sequence, 'avio' intra-only AV1 image/sequence
+            // — spec-listed under compatible_brands but also emitted as
+            // major_brand by real encoders) distinguishes them. Detect before the
+            // audio/video branches so an AVIF buffer isn't misrouted to the video
+            // pipeline (#286).
+            if (/^(avif|avis|avio)/.test(brand)) {
+                return this.result("image", "image/avif", 95);
+            }
             if (/^(M4A|M4B|M4P|F4A|F4B)/.test(brand)) {
                 return this.result("audio", "audio/mp4", 95);
             }
@@ -1609,13 +1776,25 @@ class MimeTypeStrategy {
             return this.unknown();
         }
         try {
-            const response = await request(input, {
-                dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
-                method: "HEAD",
-                headersTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
-                bodyTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
-            });
-            const contentType = response.headers["content-type"] || "";
+            // #323: reuse a recently-seen Content-Type for this URL instead of
+            // re-issuing a HEAD (populated here and by loadFromURL's GET).
+            const now = Date.now();
+            let contentType = getCachedUrlContentType(input, now);
+            if (contentType === undefined) {
+                // Wrap the whole HEAD (request + body drain) in withTimeout so a stalled
+                // dump() can't hang detection, per the project's async-timeout guideline.
+                contentType = await withTimeout((async () => {
+                    const response = await request(input, {
+                        dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
+                        method: "HEAD",
+                        headersTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                        bodyTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                    });
+                    await response.body.dump();
+                    return response.headers["content-type"] || "";
+                })(), FileDetector.DEFAULT_HEAD_TIMEOUT);
+                setCachedUrlContentType(input, contentType, now);
+            }
             const type = this.mimeToFileType(contentType);
             return {
                 type,