@juspay/neurolink 9.55.9 → 9.55.11

package/dist/lib/services/server/ai/observability/instrumentation.js

@@ -18,6 +18,7 @@ import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
 import { AsyncLocalStorage } from "async_hooks";
+import { extractMcpErrorText } from "../../../../utils/mcpErrorText.js";
 import { logger } from "../../../../utils/logger.js";
 const LOG_PREFIX = "[OpenTelemetry]";
 function createOtelResource(config, serviceName) {
@@ -131,6 +132,64 @@ function _hasExternalTracerProvider() {
         return false;
     }
 }
+/**
+ * Parse `ai.toolCall.result` on a Vercel AI SDK tool span and surface any
+ * embedded MCP `{ isError: true }` as a Langfuse ERROR + status message.
+ */
+function applyToolCallIsErrorStatus(attrs) {
+    const resultAttr = attrs["ai.toolCall.result"];
+    if (typeof resultAttr !== "string" || resultAttr.length === 0) {
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(resultAttr);
+    }
+    catch {
+        return;
+    }
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        parsed.isError !== true) {
+        return;
+    }
+    attrs["langfuse.level"] = "ERROR";
+    // Always set a status_message, even when the MCP payload has non-text or
+    // empty content. Without a fallback the Curator P0-1 gap reappears for
+    // those failures (level=ERROR but statusMessage=null).
+    const errorText = extractMcpErrorText(parsed);
+    const toolName = typeof attrs["ai.toolCall.name"] === "string"
+        ? attrs["ai.toolCall.name"]
+        : "tool";
+    attrs["langfuse.status_message"] =
+        errorText || `MCP ${toolName} returned isError=true`;
+}
+/**
+ * Map non-ERROR span conditions (content-filter, length, client abort, SDK
+ * timeout, empty output) onto Langfuse WARNING/ERROR levels. Mutates `attrs`.
+ */
+function applyNonErrorLangfuseLevel(attrs) {
+    const finishReason = attrs["ai.finishReason"] ?? attrs["gen_ai.response.finish_reasons"];
+    const reasonStr = Array.isArray(finishReason)
+        ? finishReason.join(",")
+        : String(finishReason ?? "");
+    if (reasonStr.includes("content-filter") || reasonStr === "length") {
+        attrs["langfuse.level"] = "WARNING";
+        attrs["langfuse.status_message"] =
+            `Generation stopped: finishReason=${reasonStr}`;
+        return;
+    }
+    if (attrs["neurolink.no_output"] === true) {
+        attrs["langfuse.level"] = "WARNING";
+        attrs["langfuse.status_message"] =
+            "Stream produced no output (NoOutputGeneratedError)";
+        return;
+    }
+    if (reasonStr === "aborted") {
+        attrs["langfuse.level"] = "WARNING";
+        attrs["langfuse.status_message"] = "Generation aborted by client";
+    }
+}
 /**
  * Span processor that enriches spans with user and session context from AsyncLocalStorage
  * Also extracts GenAI semantic convention attributes for Langfuse integration
@@ -459,26 +518,23 @@ class ContextEnricher {
             const readableStatus = span.status;
             try {
                 const mutableAttrs = span.attributes;
+                // Curator P0-1/P0-2: detect MCP isError pattern on AI SDK tool call spans.
+                // The AI SDK's `ai.toolCall` span stays status=UNSET when the tool
+                // *returns* { isError:true } (no exception thrown), so Langfuse sees
+                // level=DEFAULT and no status message. Parse the stringified result
+                // and surface the embedded error text.
+                if (readableSpan.name === "ai.toolCall" &&
+                    readableStatus?.code !== SpanStatusCode.ERROR) {
+                    applyToolCallIsErrorStatus(mutableAttrs);
+                }
                 if (readableStatus?.code === SpanStatusCode.ERROR) {
                     mutableAttrs["langfuse.level"] = "ERROR";
                     if (readableStatus.message) {
                         mutableAttrs["langfuse.status_message"] = readableStatus.message;
                     }
                 }
-                else {
-                    // P8 extended: Detect WARNING-level conditions on non-ERROR spans.
-                    // The AI SDK sets ai.finishReason on its spans; content-filter and
-                    // length finish reasons indicate partial failures that deserve WARNING.
-                    const finishReason = mutableAttrs["ai.finishReason"] ??
-                        mutableAttrs["gen_ai.response.finish_reasons"];
-                    const reasonStr = Array.isArray(finishReason)
-                        ? finishReason.join(",")
-                        : String(finishReason ?? "");
-                    if (reasonStr.includes("content-filter") || reasonStr === "length") {
-                        mutableAttrs["langfuse.level"] = "WARNING";
-                        mutableAttrs["langfuse.status_message"] =
-                            `Generation stopped: finishReason=${reasonStr}`;
-                    }
+                else if (mutableAttrs["langfuse.level"] === undefined) {
+                    applyNonErrorLangfuseLevel(mutableAttrs);
                 }
             }
             catch {
@@ -520,9 +576,36 @@ async function createLangfuseProcessor(config) {
         baseUrl: config.baseUrl || "https://cloud.langfuse.com",
         environment: config.environment || "dev",
         release: config.release || "v1.0.0",
-        shouldExportSpan: () => true,
+        // Curator P1-3: skip internal wrapper spans that duplicate ai.toolCall /
+        // ai.generateText observations in Langfuse. Wrappers still emit OTel spans
+        // for internal metrics; they just aren't forwarded to Langfuse.
+        shouldExportSpan: langfuseShouldExportSpan,
     });
 }
+/**
+ * True when a span is an internal NeuroLink wrapper that should NOT be sent to
+ * Langfuse. Internal wrappers carry the `langfuse.internal: true` attribute.
+ *
+ * Exposed so host apps that bring their own `LangfuseSpanProcessor` (e.g.
+ * `skipLangfuseSpanProcessor: true`, or manual registration on an existing
+ * TracerProvider) can apply the same filter and avoid duplicate observations.
+ */
+export function isLangfuseInternalSpan(span) {
+    return span.attributes?.["langfuse.internal"] === true;
+}
+/**
+ * Drop-in `shouldExportSpan` predicate for a `LangfuseSpanProcessor` that
+ * filters out NeuroLink internal wrapper spans.
+ *
+ * Usage in host apps:
+ * ```ts
+ * import { langfuseShouldExportSpan } from "@juspay/neurolink";
+ * new LangfuseSpanProcessor({ ..., shouldExportSpan: langfuseShouldExportSpan });
+ * ```
+ */
+export function langfuseShouldExportSpan({ otelSpan, }) {
+    return !isLangfuseInternalSpan(otelSpan);
+}
 async function initializeExternalOpenTelemetryMode(config, resource, otlpEndpoint, serviceName, langfuseRequested, hasLangfuseCreds) {
     if (langfuseRequested && !hasLangfuseCreds) {
         if (!otlpEndpoint) {

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

@@ -543,6 +543,33 @@ export type ProcessedYaml = ProcessedFileBase & {
     /** YAML content converted to JSON string for AI consumption */
     asJson: string | null;
 };
+/**
+ * Structural types for fluent-ffmpeg probe data.
+ * Defined here so the optional fluent-ffmpeg package is not required at typecheck time.
+ */
+export type FfprobeStream = {
+    codec_type?: string;
+    codec_name?: string;
+    width?: number;
+    height?: number;
+    r_frame_rate?: string;
+    avg_frame_rate?: string;
+    bit_rate?: number | string;
+    channels?: number;
+    sample_rate?: number | string;
+    tags?: Record<string, string | number>;
+    [key: string]: unknown;
+};
+export type FfprobeData = {
+    streams: FfprobeStream[];
+    format: {
+        duration?: number;
+        size?: number | string;
+        bit_rate?: number | string;
+        tags?: Record<string, string | number>;
+        [key: string]: unknown;
+    };
+};
 /**
  * Structural types for exceljs objects.
  * Defined here so the optional exceljs package is not required at typecheck time.

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

@@ -0,0 +1,10 @@
+/**
+ * Extract a human-readable error string from an MCP isError result object.
+ *
+ * Shared utility — no side effects, no dependencies on other SDK modules —
+ * so it can be imported from the neurolink.ts event loop, the telemetry
+ * instrumentation (which loads earlier), and the MCP discovery layer without
+ * creating circular imports. Any change to truncation or content-type parsing
+ * must happen here and propagate to all three surfaces.
+ */
+export declare function extractMcpErrorText(raw: unknown): string;

package/dist/lib/utils/mcpErrorText.js

@@ -0,0 +1,36 @@
+/**
+ * Extract a human-readable error string from an MCP isError result object.
+ *
+ * Shared utility — no side effects, no dependencies on other SDK modules —
+ * so it can be imported from the neurolink.ts event loop, the telemetry
+ * instrumentation (which loads earlier), and the MCP discovery layer without
+ * creating circular imports. Any change to truncation or content-type parsing
+ * must happen here and propagate to all three surfaces.
+ */
+export function extractMcpErrorText(raw) {
+    let resultObj;
+    try {
+        resultObj = typeof raw === "string" ? JSON.parse(raw) : raw;
+    }
+    catch {
+        return "";
+    }
+    if (!resultObj || typeof resultObj !== "object") {
+        return "";
+    }
+    const content = resultObj.content;
+    if (!Array.isArray(content)) {
+        return "";
+    }
+    // Fail closed on malformed entries (e.g. `content: [null]`) rather than
+    // throwing — the caller expects an empty string for unparseable input.
+    const texts = content
+        .filter((c) => c !== null &&
+        typeof c === "object" &&
+        c.type === "text" &&
+        typeof c.text === "string" &&
+        c.text.length > 0)
+        .map((c) => c.text);
+    return texts.join(" ").substring(0, 500);
+}
+//# sourceMappingURL=mcpErrorText.js.map

package/dist/lib/utils/timeout.js

@@ -313,6 +313,12 @@ export function createTimeoutController(timeout, provider, operation) {
     }
     const controller = new AbortController();
     const timer = setTimeout(() => {
+        // NOTE: we cannot stamp the AI SDK's ai.streamText/ai.generateText span
+        // from here — the setTimeout callback runs in the async context captured
+        // at schedule time, which is BEFORE the AI SDK span exists. Instead we
+        // rely on the AI SDK propagating the TimeoutError through its recordSpan
+        // wrapper, which sets span.status = ERROR + message. ContextEnricher's
+        // SpanStatusCode.ERROR branch then surfaces level=ERROR + status_message.
         controller.abort(new TimeoutError(`${provider} ${operation} operation timed out after ${timeout}`, timeoutMs, provider, operation));
     }, timeoutMs);
     const cleanup = () => {

package/dist/mcp/toolDiscoveryService.js

@@ -9,10 +9,72 @@ import { globalCircuitBreakerManager, CircuitBreakerOpenError, } from "./mcpCirc
 import { isObject, isNullish } from "../utils/typeUtils.js";
 import { validateToolName, validateToolDescription, } from "../utils/parameterValidation.js";
 import { withTimeout } from "../utils/errorHandling.js";
+import { extractMcpErrorText } from "../utils/mcpErrorText.js";
 import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
 import { tracers } from "../telemetry/tracers.js";
 import { withSpan } from "../telemetry/withSpan.js";
 const mcpTracer = tracers.mcp;
+/**
+ * JSON-stringify a value for a Langfuse input/output preview attribute,
+ * truncated to a hard cap to stay under span attribute size limits. The
+ * returned string is guaranteed to be ≤ maxLen characters; when truncated,
+ * the last character is replaced with an ellipsis.
+ */
+function safeJsonStringify(value, maxLen) {
+    if (maxLen <= 0) {
+        return "";
+    }
+    try {
+        const str = JSON.stringify(value);
+        if (typeof str !== "string") {
+            return "";
+        }
+        if (str.length <= maxLen) {
+            return str;
+        }
+        return str.slice(0, Math.max(0, maxLen - 1)) + "…";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Match property names that commonly hold secrets. Values under these keys
+ * are replaced with `[REDACTED]` before serialization. Case-insensitive.
+ * Conservative list — anything matching *here* is masked; the rest of the
+ * structure is preserved so Langfuse still gets a meaningful preview.
+ */
+const SENSITIVE_KEY_PATTERN = /^(password|passwd|secret|token|api[_-]?key|apikey|access[_-]?key|authorization|auth|bearer|credential|cookie|session[_-]?id|private[_-]?key|client[_-]?secret|refresh[_-]?token|x-api-key)$/i;
+/**
+ * Walk a value, producing a structurally-equivalent copy with sensitive-key
+ * values masked. Unlike `transformParamsForLogging` (which collapses objects
+ * to a "N params" string), this preserves non-sensitive content so Langfuse
+ * input/output previews stay useful. Bounded depth guards against cycles.
+ */
+function redactForPreview(value, depth = 0) {
+    if (depth > 10) {
+        return "[...]";
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => redactForPreview(v, depth + 1));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (SENSITIVE_KEY_PATTERN.test(k)) {
+            out[k] = "[REDACTED]";
+        }
+        else {
+            out[k] = redactForPreview(v, depth + 1);
+        }
+    }
+    return out;
+}
 /**
  * Default timeout for MCP tool execution operations in milliseconds.
  * Configurable via MCP_TOOL_TIMEOUT env var.
@@ -376,6 +438,18 @@ export class ToolDiscoveryService extends EventEmitter {
                         "mcp.server_id": serverId,
                         "mcp.tool_name": toolName,
                         "mcp.timeout_ms": effectiveTimeout,
+                        // Curator P1-4: Langfuse observations rely on ai.*/gen_ai.*
+                        // attributes for tool name and I/O previews. Provide them so
+                        // the SPAN observation in Langfuse is legible without
+                        // timestamp-joining against the parent ai.toolCall. Redact
+                        // parameters via the existing secret-stripping helper so
+                        // tokens/credentials/paths don't leave the process.
+                        "ai.tool.name": toolName,
+                        "gen_ai.tool.name": toolName,
+                        "gen_ai.request": safeJsonStringify({
+                            name: toolName,
+                            arguments: redactForPreview(parameters),
+                        }, 2048),
                     },
                 }, async (callSpan) => {
                     try {
@@ -384,11 +458,26 @@ export class ToolDiscoveryService extends EventEmitter {
                             name: toolName,
                             arguments: parameters,
                         }), timeout, new Error(`Tool execution timeout: ${toolName}`));
-                        callSpan.setStatus({ code: SpanStatusCode.OK });
+                        // Curator P0-1/P0-2: the MCP client does NOT throw on protocol
+                        // errors — it returns { isError: true, content: [...] }. Detect
+                        // that pattern so the span status reflects reality.
+                        const resultObj = callResult;
+                        if (resultObj && resultObj.isError === true) {
+                            const errorText = extractMcpErrorText(resultObj);
+                            callSpan.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: errorText || `Tool ${toolName} returned isError`,
+                            });
+                        }
+                        else {
+                            callSpan.setStatus({ code: SpanStatusCode.OK });
+                        }
                         // ── MCP output normalization ──────────────────────────────────
                         // Intercept here — after receive, before cache, before memory,
                         // before LLM context injection. Returns a compact surrogate when
                         // the payload exceeds mcp.outputLimits.maxBytes.
+                        let resultForPreview = callResult;
+                        let resultForReturn = callResult;
                         if (this.outputNormalizer) {
                             try {
                                 const normalized = await this.outputNormalizer.normalize(callResult, { toolName, serverId });
@@ -396,7 +485,8 @@ export class ToolDiscoveryService extends EventEmitter {
                                 if (normalized.isExternalized) {
                                     callSpan.setAttribute("mcp.output.original_bytes", normalized.originalBytes);
                                 }
-                                return normalized.result;
+                                resultForPreview = normalized.result;
+                                resultForReturn = normalized.result;
                             }
                             catch (normErr) {
                                 mcpLogger.warn(`[ToolDiscoveryService] McpOutputNormalizer failed for ` +
@@ -405,7 +495,13 @@ export class ToolDiscoveryService extends EventEmitter {
                             }
                         }
                         // ── end normalization ─────────────────────────────────────────
-                        return callResult;
+                        // Curator P1-4: build gen_ai.response AFTER normalization so
+                        // large payloads use the compact surrogate instead of the raw
+                        // result (avoids redundant stringify + memory hit on payloads
+                        // that were specifically externalized to Redis). Redact via the
+                        // same secret-stripping path used for request parameters.
+                        callSpan.setAttribute("gen_ai.response", safeJsonStringify(redactForPreview(resultForPreview), 2048));
+                        return resultForReturn;
                     }
                     catch (err) {
                         callSpan.setStatus({

package/dist/mcp/toolRegistry.js

@@ -257,6 +257,9 @@ export class MCPToolRegistry extends MCPRegistry {
             attributes: {
                 [ATTR.GEN_AI_TOOL_NAME]: toolName,
                 [ATTR.MCP_SERVER_ID]: preResolvedServerId || "builtin",
+                // Curator P1-3: registry-level wrapper — duplicates ai.toolCall in
+                // Langfuse. Retained for OTel/metrics; skipped for Langfuse export.
+                "langfuse.internal": true,
             },
         }, async (span) => {
             try {

package/dist/neurolink.js

@@ -64,6 +64,7 @@ import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableErr
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
+import { extractMcpErrorText } from "./utils/mcpErrorText.js";
 import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults.js";
 import { resolveModel } from "./utils/modelAliasResolver.js";
 // Import orchestration components
@@ -133,29 +134,6 @@ function mcpCategoryToErrorCategory(mcpCategory) {
             return ErrorCategory.EXECUTION;
     }
 }
-/**
- * Extract a human-readable error string from an MCP isError result object.
- * Returns an empty string if nothing useful can be extracted.
- */
-function extractMcpErrorText(raw) {
-    try {
-        const resultObj = typeof raw === "string" ? JSON.parse(raw) : raw;
-        if (!resultObj || typeof resultObj !== "object") {
-            return "";
-        }
-        const content = resultObj.content;
-        if (!Array.isArray(content)) {
-            return "";
-        }
-        const texts = content
-            .filter((c) => c.type === "text" && c.text)
-            .map((c) => c.text);
-        return texts.join(" ").substring(0, 500);
-    }
-    catch {
-        return "";
-    }
-}
 /**
  * Check if an error is a non-retryable provider error that should immediately
  * stop the retry/fallback chain. These errors represent permanent failures
@@ -6267,6 +6245,13 @@ Current user's request: ${currentInput}`;
                 "tool.type": executionContext.toolType,
                 "tool.input_size": executionContext.inputSize,
                 "tool.input_preview": executionContext.truncatedInput,
+                // NOT marked langfuse.internal: this is the public entrypoint for
+                // `NeuroLink.executeTool()`. Direct API callers (not going through
+                // the AI SDK) would otherwise produce zero Langfuse observations —
+                // the lower-level registry/discovery spans are internal wrappers.
+                // AI-SDK-initiated custom tools will produce both ai.toolCall and
+                // this span, which is the accepted tradeoff for keeping direct
+                // invocations observable.
             },
         }, (toolSpan) => this.executeToolWithSpan(toolName, params, options, executionContext, toolSpan));
     }

package/dist/processors/media/AudioProcessor.js

@@ -36,10 +36,27 @@
  * }
  * ```
  */
-import { parseBuffer, selectCover } from "music-metadata";
 import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
 import { SIZE_LIMITS_MB } from "../config/index.js";
 import { FileErrorCode } from "../errors/index.js";
+let _musicMetadata = null;
+async function loadMusicMetadata() {
+    if (_musicMetadata) {
+        return _musicMetadata;
+    }
+    try {
+        _musicMetadata = await import(/* @vite-ignore */ "music-metadata");
+        return _musicMetadata;
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : null;
+        if (e?.code === "ERR_MODULE_NOT_FOUND" &&
+            e.message.includes("music-metadata")) {
+            throw new Error('Audio processing requires the "music-metadata" package. Install it with:\n  pnpm add music-metadata', { cause: err });
+        }
+        throw err;
+    }
+}
 // =============================================================================
 // TYPES
 // =============================================================================
@@ -239,7 +256,7 @@ export class AudioProcessor extends BaseFileProcessor {
             // Step 5: Extract tags from common metadata
             const tags = this.extractTags(audioMetadata);
             // Step 6: Extract embedded cover art if present
-            const coverArt = this.extractCoverArt(audioMetadata);
+            const coverArt = await this.extractCoverArt(audioMetadata);
             // Step 7: Attempt transcription if API key is available
             const filename = this.getFilename(fileInfo);
             const transcriptionResult = await this.attemptTranscription(buffer, filename, fileInfo.mimetype);
@@ -404,6 +421,7 @@ export class AudioProcessor extends BaseFileProcessor {
         // parseBuffer accepts (Uint8Array, fileInfo?: IFileInfo | string, options?)
         // where string is interpreted as MIME type.
         const mimeType = fileInfo.mimetype || undefined;
+        const { parseBuffer } = await loadMusicMetadata();
         return parseBuffer(buffer, mimeType);
     }
     /**
@@ -467,11 +485,12 @@ export class AudioProcessor extends BaseFileProcessor {
      * @param audioMetadata - Parsed audio metadata from music-metadata
      * @returns Cover art as Buffer, or null if no cover art is embedded
      */
-    extractCoverArt(audioMetadata) {
+    async extractCoverArt(audioMetadata) {
         const pictures = audioMetadata.common.picture;
         if (!pictures || pictures.length === 0) {
             return null;
         }
+        const { selectCover } = await loadMusicMetadata();
         const cover = selectCover(pictures);
         if (!cover) {
             return null;

package/dist/processors/media/VideoProcessor.js

@@ -44,9 +44,7 @@
  * ```
  */
 import { randomUUID } from "crypto";
-import ffmpegCommand from "fluent-ffmpeg";
 import { createWriteStream, existsSync, promises as fs } from "fs";
-import { Input, FilePathSource, ALL_FORMATS } from "mediabunny";
 import { tmpdir } from "os";
 import { join } from "path";
 import { Readable } from "stream";
@@ -56,6 +54,40 @@ import { SIZE_LIMITS_MB } from "../config/index.js";
 import { FileErrorCode } from "../errors/index.js";
 import { tracers, ATTR, withSpan } from "../../telemetry/index.js";
 import { logger } from "../../utils/logger.js";
+// fluent-ffmpeg's default export is callable + has static methods — avoid caching
+// the module type (it confuses TS); Node's module cache handles dedup.
+async function loadFluentFfmpeg() {
+    try {
+        const mod = await import(/* @vite-ignore */ "fluent-ffmpeg");
+        return mod.default;
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : null;
+        if (e?.code === "ERR_MODULE_NOT_FOUND" &&
+            e.message.includes("fluent-ffmpeg")) {
+            throw new Error('Video processing requires the "fluent-ffmpeg" package. Install it with:\n  pnpm add fluent-ffmpeg', { cause: err });
+        }
+        throw err;
+    }
+}
+let _mediabunny = null;
+async function loadMediaBunny() {
+    if (_mediabunny) {
+        return _mediabunny;
+    }
+    try {
+        _mediabunny = await import(/* @vite-ignore */ "mediabunny");
+        return _mediabunny;
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : null;
+        if (e?.code === "ERR_MODULE_NOT_FOUND" &&
+            e.message.includes("mediabunny")) {
+            throw new Error('Video processing requires the "mediabunny" package. Install it with:\n  pnpm add mediabunny', { cause: err });
+        }
+        throw err;
+    }
+}
 // =============================================================================
 // FFMPEG PATH INITIALIZATION
 // =============================================================================
@@ -90,7 +122,8 @@ async function initFfmpegPaths() {
         const ffmpegStatic = await import("ffmpeg-static");
         const ffmpegPath = ffmpegStatic.default;
         if (typeof ffmpegPath === "string" && existsSync(ffmpegPath)) {
-            ffmpegCommand.setFfmpegPath(ffmpegPath);
+            const ff = await loadFluentFfmpeg();
+            ff.setFfmpegPath(ffmpegPath);
         }
     }
     catch {
@@ -469,7 +502,8 @@ export class VideoProcessor extends BaseFileProcessor {
      * @param filePath - Path to the video file
      * @returns Success result with probe data or error message
      */
-    probeVideo(filePath) {
+    async probeVideo(filePath) {
+        const ffmpeg = await loadFluentFfmpeg();
         return new Promise((resolve) => {
             const timeoutId = setTimeout(() => {
                 resolve({
@@ -477,7 +511,7 @@ export class VideoProcessor extends BaseFileProcessor {
                     error: `ffprobe timed out after ${VIDEO_CONFIG.FFPROBE_TIMEOUT_MS}ms`,
                 });
             }, VIDEO_CONFIG.FFPROBE_TIMEOUT_MS);
-            ffmpegCommand.ffprobe(filePath, (err, data) => {
+            ffmpeg.ffprobe(filePath, (err, data) => {
                 clearTimeout(timeoutId);
                 if (err) {
                     resolve({
@@ -496,11 +530,12 @@ export class VideoProcessor extends BaseFileProcessor {
      * Falls back to ffprobe if mediabunny fails or doesn't support the format.
      */
     async probeVideoWithMediabunny(filePath) {
+        const mb = await loadMediaBunny();
         let input;
         try {
-            input = new Input({
-                source: new FilePathSource(filePath),
-                formats: [...ALL_FORMATS],
+            input = new mb.Input({
+                source: new mb.FilePathSource(filePath),
+                formats: [...mb.ALL_FORMATS],
             });
             const duration = await input.computeDuration();
             const videoTrack = await input.getPrimaryVideoTrack();
@@ -671,7 +706,8 @@ export class VideoProcessor extends BaseFileProcessor {
      * @param outputDir - Directory to write frame files
      * @param timestamps - Array of timestamps in seconds
      */
-    runFfmpegFrameExtraction(videoPath, outputDir, timestamps, intervalSec) {
+    async runFfmpegFrameExtraction(videoPath, outputDir, timestamps, intervalSec) {
+        const ff = await loadFluentFfmpeg();
         return new Promise((resolve, reject) => {
             // Improved select expression to pick exactly one frame per interval
             // instead of multiple frames within a 0.5s window.
@@ -679,7 +715,7 @@ export class VideoProcessor extends BaseFileProcessor {
             const timeoutId = setTimeout(() => {
                 reject(new Error(`ffmpeg frame extraction timed out after ${VIDEO_CONFIG.FFMPEG_TIMEOUT_MS}ms`));
             }, VIDEO_CONFIG.FFMPEG_TIMEOUT_MS);
-            ffmpegCommand(videoPath)
+            ff(videoPath)
                 .outputOptions([
                 "-vf",
                 `select='${selectExpr}',scale='min(${VIDEO_CONFIG.FRAME_MAX_DIMENSION}\\,iw):-2'`,
@@ -740,11 +776,12 @@ export class VideoProcessor extends BaseFileProcessor {
      */
     async extractSubtitles(videoPath, tempDir) {
         const subtitlePath = join(tempDir, "subtitles.srt");
+        const ffSub = await loadFluentFfmpeg();
         await new Promise((resolve, reject) => {
             const timeoutId = setTimeout(() => {
                 reject(new Error(`ffmpeg subtitle extraction timed out after ${VIDEO_CONFIG.FFMPEG_TIMEOUT_MS}ms`));
             }, VIDEO_CONFIG.FFMPEG_TIMEOUT_MS);
-            ffmpegCommand(videoPath)
+            ffSub(videoPath)
                 .outputOptions(["-map", "0:s:0", "-c:s", "srt"])
                 .output(subtitlePath)
                 .on("end", () => {