@juspay/neurolink 12.19.2 → 12.20.1

package/dist/proxy/updateCoordinator.js

@@ -1,3 +1,41 @@
+/**
+ * Parse serving identity conservatively from `/status`. A rolling status is
+ * trusted only when the worker-local fields agree with the supervisor snapshot.
+ */
+export function parseProxyServingWorkerIdentity(payload, rollingSupervisor) {
+    if (!payload || typeof payload !== "object") {
+        return null;
+    }
+    const value = payload;
+    if (typeof value.version !== "string" ||
+        !/^\d+\.\d+\.\d+$/.test(value.version) ||
+        !Number.isSafeInteger(value.pid) ||
+        Number(value.pid) <= 0) {
+        return null;
+    }
+    if (!rollingSupervisor) {
+        return { version: value.version, pid: Number(value.pid), generation: null };
+    }
+    const active = value.autoUpdate?.rolling?.active;
+    if (!active ||
+        active.version !== value.version ||
+        active.pid !== value.pid ||
+        !Number.isSafeInteger(active.generation) ||
+        Number(active.generation) <= 0) {
+        return null;
+    }
+    return {
+        version: value.version,
+        pid: Number(value.pid),
+        generation: Number(active.generation),
+    };
+}
+/** A long-running update may mutate live selection only for its original worker. */
+export function isSameProxyServingWorker(expected, current) {
+    return (current?.version === expected.version &&
+        current.pid === expected.pid &&
+        current.generation === expected.generation);
+}
 /**
  * A replacement updater starts from the newly installed package. The registry
  * then reports no newer version even when its launchd parent still runs the
@@ -72,6 +110,8 @@ function isQuiet(activity, quietThresholdMs, nowMs) {
 }
 /**
  * Prefer a naturally quiet window, then briefly drain new inference traffic.
+ * Automatic supervisor refresh uses allowBusyDrain=false: it fences admission
+ * only after a quiet observation and never waits for busy workers behind it.
  * Existing requests are never interrupted; a bounded drain failure is returned
  * to the caller so admission can be reopened and retried later.
  */
@@ -89,16 +129,43 @@ export async function waitForProxyUpdateWindow(options) {
         }
         const activity = await options.getActivity();
         if (activity && isQuiet(activity, options.quietThresholdMs, now())) {
-            return { ready: true, draining: false };
+            if (options.allowBusyDrain !== false) {
+                return { ready: true, draining: false };
+            }
+            break;
         }
         options.onPhase?.("waiting_for_quiet", activity);
         await wait(options.pollIntervalMs);
     }
+    if (options.allowBusyDrain === false) {
+        if (options.isStopping()) {
+            return { ready: false, draining: false, reason: "stopping" };
+        }
+        if (!options.isParentAlive()) {
+            return { ready: false, draining: false, reason: "parent_stopped" };
+        }
+        const activity = await options.getActivity();
+        if (!activity || !isQuiet(activity, options.quietThresholdMs, now())) {
+            options.onPhase?.("waiting_for_quiet", activity);
+            return { ready: false, draining: false, reason: "busy" };
+        }
+    }
     if (!(await options.setDraining(true))) {
         // The control response may have been lost after the parent applied it.
         // Treat state as unknown/draining so the caller always attempts resume.
         return { ready: false, draining: true, reason: "drain_failed" };
     }
+    if (options.allowBusyDrain === false) {
+        // The worker's idle fence closes the observation/admission race. Any new
+        // cross-generation activity means resume immediately, never hold a busy
+        // service behind maintenance responses for the normal drain timeout.
+        const activity = await options.getActivity();
+        if (activity && isProxyRuntimeSettled(activity)) {
+            return { ready: true, draining: true };
+        }
+        const resumed = await options.setDraining(false);
+        return { ready: false, draining: !resumed, reason: "busy" };
+    }
     const drainDeadline = now() + options.drainWaitMs;
     while (now() < drainDeadline) {
         if (options.isStopping()) {

package/dist/proxy/updateState.d.ts

@@ -67,3 +67,5 @@ export declare function reconcileRunningUpdate(runningVersion: string, stateFile
  * @param stateFilePath - Override path for testing
  */
 export declare function recordCheck(latestVersion: string, stateFilePath?: string): void;
+/** Preserve the last successful registry version when discovery fails. */
+export declare function recordCheckFailure(message: string, stateFilePath?: string): void;

package/dist/proxy/updateState.js

@@ -124,6 +124,12 @@ export function loadUpdateState(stateFilePath) {
         return {
             ...getDefaultUpdateState(),
             ...candidate,
+            lastCheckAttemptAt: typeof candidate.lastCheckAttemptAt === "string"
+                ? candidate.lastCheckAttemptAt
+                : undefined,
+            lastCheckError: typeof candidate.lastCheckError === "string"
+                ? candidate.lastCheckError.slice(0, 1_000)
+                : null,
             suppressedVersions: candidate.suppressedVersions ?? {},
             // Backfill order matters for state files written before `installedVersion`
             // existed. Back then `recordUpdateInstalled()` set ONLY
@@ -303,6 +309,15 @@ export function reconcileRunningUpdate(runningVersion, stateFilePath) {
 export function recordCheck(latestVersion, stateFilePath) {
     const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
     state.lastCheckAt = new Date().toISOString();
+    state.lastCheckAttemptAt = state.lastCheckAt;
+    state.lastCheckError = null;
     state.lastCheckVersion = latestVersion;
     saveUpdateState(state, stateFilePath);
 }
+/** Preserve the last successful registry version when discovery fails. */
+export function recordCheckFailure(message, stateFilePath) {
+    const state = loadUpdateState(stateFilePath) ?? getDefaultUpdateState();
+    state.lastCheckAttemptAt = new Date().toISOString();
+    state.lastCheckError = message.slice(0, 1_000);
+    saveUpdateState(state, stateFilePath);
+}

package/dist/rag/pipeline/RAGPipeline.js

@@ -26,6 +26,7 @@
  * ```
  */
 import { randomUUID } from "crypto";
+import { extname } from "path";
 import { MDocument } from "../document/MDocument.js";
 import { loadDocument } from "../document/loaders.js";
 import { InMemoryVectorStore } from "../retrieval/vectorQueryTool.js";
@@ -472,6 +473,19 @@ export class RAGPipeline {
         let chunksCreated = 0;
         for (const source of sources) {
             try {
+                if (typeof source === "string") {
+                    // IMAGE_EXTENSIONS includes .svg, but that constant's raster
+                    // guarantee is scoped to the processor path (SvgProcessor). Here
+                    // it would flow raw markup bytes into generateImageCaption (which
+                    // base64s them into a vision call) and into the multi-modal embed
+                    // call — both raster-only. Mirrors the identical skip in
+                    // ragIntegration.ts's ingestion-tool entry point so the two agree.
+                    const withoutQueryOrFragment = source.split(/[?#]/)[0];
+                    if (extname(withoutQueryOrFragment).toLowerCase() === ".svg") {
+                        logger.warn(`[RAGPipeline] SVG is not supported as a multi-modal image source, skipping: ${redactUrlForError(source)}`);
+                        continue;
+                    }
+                }
                 // Load the image
                 let imageDoc;
                 if (Buffer.isBuffer(source)) {
@@ -484,6 +498,21 @@ export class RAGPipeline {
                 else {
                     imageDoc = await this.imageLoader.load(source);
                 }
+                // The extension check above is necessary but not sufficient: it only
+                // sees the name. A source with no `.svg` suffix — an extension-less
+                // URL, or a local file named without one — reaches ImageLoader, which
+                // falls back to detecting the type from the bytes and returns
+                // `image/svg+xml` for markup starting `<svg`/`<?xm`. So re-check the
+                // resolved type AND the bytes: loadFromPath prefers a recognized
+                // extension over content detection, so SVG markup named `.png` keeps
+                // an image/png label. Skip rather than throw so SVG behaves the same
+                // whichever way it was identified. `supportedFormats` does not cover
+                // this: it is optional, and unset on the default config.
+                if (imageDoc.mimeType === "image/svg+xml" ||
+                    ImageProcessor.detectImageType(imageDoc.image) === "image/svg+xml") {
+                    logger.warn(`[RAGPipeline] SVG is not supported as a multi-modal image source, skipping: ${redactUrlForError(imageDoc.metadata.source)}`);
+                    continue;
+                }
                 const { supportedFormats } = this.multiModalConfig;
                 if (supportedFormats && !supportedFormats.includes(imageDoc.mimeType)) {
                     throw ErrorFactory.invalidParameters("ingestImages", new Error(`unsupported image MIME type: ${imageDoc.mimeType}`), { mimeType: imageDoc.mimeType, supportedFormats });

package/dist/rag/ragIntegration.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
 import { logger } from "../utils/logger.js";
 import { redactUrlForError } from "../utils/logSanitize.js";
+import { ImageProcessor } from "../utils/imageProcessor.js";
 import { createChunker } from "./ChunkerFactory.js";
 import { createVectorQueryTool, InMemoryVectorStore, } from "./retrieval/vectorQueryTool.js";
 import { ImageLoader } from "./document/imageLoader.js";
@@ -300,6 +301,25 @@ async function _prepareRAGToolInner(ragConfig, fallbackProvider) {
         for (const { path: imgPath } of imageFiles) {
             try {
                 const imageDoc = await imageLoader.load(imgPath);
+                // The two `ext === ".svg"` checks above are a cheap early-out, not the
+                // boundary: both match the NAME exactly, and the name is not what
+                // decides the type. ImageLoader resolves it two ways that disagree
+                // with a bare `.svg` comparison — `.svgz` maps to image/svg+xml
+                // through EXTENSION_MIME_MAP, and loadFromURL ignores the extension
+                // entirely and sniffs the bytes, so any image-extension URL actually
+                // serving SVG resolves to image/svg+xml here. A local raster suffix
+                // has the opposite problem: loadFromPath trusts the extension before
+                // the bytes, so inspect both. Otherwise `hasImage: true` below sends
+                // SVG markup to the raster embed call. Skip rather than throw,
+                // matching the early-outs and the identical guard
+                // in RAGPipeline.ingestImages — the two entry points are independent
+                // (prepareRAGTool builds its chunks here, not via ingestImages), so
+                // each needs its own.
+                if (imageDoc.mimeType === "image/svg+xml" ||
+                    ImageProcessor.detectImageType(imageDoc.image) === "image/svg+xml") {
+                    logger.warn(`[RAG] SVG is not supported as a RAG image source, skipping: ${redactUrlForError(imgPath)}`);
+                    continue;
+                }
                 // Use filename-based text representation for simple embedding
                 const imageText = imageDoc.text;
                 imageChunks.push({
@@ -476,7 +496,7 @@ async function _prepareRAGToolInner(ragConfig, fallbackProvider) {
         tool: aiTool,
         toolName,
         chunksIndexed: allChunks.length + imageChunks.length,
-        filesLoaded: fileContents.length + imageFiles.length,
+        filesLoaded: fileContents.length + imageChunks.length,
     };
 }
 /** @internal Exported for testing only */

package/dist/types/cli.d.ts

@@ -1044,6 +1044,24 @@ export type TelemetryStatsArgs = TelemetryCommandArgs & {
     byModel?: boolean;
     byProvider?: boolean;
 };
+/** Staging-only native collector migration; never activates a service. */
+export type TelemetryNativePrepareArgs = {
+    collectorConfig: string;
+    output: string;
+    queueDirectory: string;
+    compactionDirectory: string;
+    bodyPort: number;
+    bodyStream?: string;
+    metadataQueueMib: number;
+    bodyQueueMib: number;
+    diskQuotaMib: number;
+    metadataRetentionDays: number;
+    bodyRetentionDays: number;
+};
+export type TelemetryNativeValidateArgs = {
+    directory: string;
+    collectorBin: string;
+};
 /** Available exporter names */
 export type ExporterName = "langfuse" | "langsmith" | "otel" | "datadog" | "sentry" | "braintrust" | "arize" | "posthog" | "laminar";
 /** Observability command arguments */

package/dist/types/file.d.ts

@@ -9,6 +9,16 @@ export type FileType = "csv" | "image" | "pdf" | "audio" | "video" | "archive" |
  * Office document types
  */
 export type OfficeDocumentType = "docx" | "pptx" | "xlsx";
+/**
+ * Transcode target for a vision-incompatible image (`adapters/imageFormatSupport.ts`).
+ *
+ * Defaults to `"png"` everywhere a caller does not pick one: sources routed
+ * through that module are frequently lossless (TIFF, BMP, ICO) or already
+ * carry alpha, and a lossy re-encode of an image the model is about to read
+ * closely is the wrong default. `"jpeg"` is available for callers who know
+ * their source has no alpha and prefer the smaller payload.
+ */
+export type VisionImageOutputFormat = "png" | "jpeg";
 /**
  * Outcome of a vision-compatibility pass over one image.
  *

package/dist/types/generate.d.ts

@@ -17,7 +17,7 @@ import type { AvatarOptions, AvatarResult } from "./avatar.js";
 import type { MusicOptions, MusicResult } from "./music.js";
 import type { StandardRecord, ValidationSchema, ZodUnknownSchema } from "./aliases.js";
 import type { NeurolinkCredentials } from "./providers.js";
-import type { CSVProcessorOptions, FileWithMetadata, MultimodalAudioEntry } from "./file.js";
+import type { CSVProcessorOptions, FileWithMetadata, MultimodalAudioEntry, VisionImageOutputFormat } from "./file.js";
 import type { WorkflowConfig } from "./workflow.js";
 import type { Schema, Tool, ToolChoice } from "./tools.js";
 import type { StepResult, LanguageModel } from "./providers.js";
@@ -156,6 +156,18 @@ export type GenerateOptions = {
          */
         maxPages?: number;
     };
+    /**
+     * Options for images that need transcoding before a vision provider can
+     * read them (HEIC, TIFF, BMP, ICO, JPEG 2000, AVIF — see
+     * `adapters/imageFormatSupport.ts`).
+     */
+    imageOptions?: {
+        /**
+         * Transcode target for an incompatible image. Defaults to `"png"` — the
+         * module's own default, unchanged unless a caller opts in here.
+         */
+        outputFormat?: VisionImageOutputFormat;
+    };
     videoOptions?: {
         /** Frames to extract. Unset lets VideoProcessor pick from the clip's duration; clamped to 100. */
         frames?: number;
@@ -1394,6 +1406,20 @@ export type TextGenerationOptions = {
         /** Max pages converted by the image fallback (#297); defaults to PDF_LIMITS.DEFAULT_MAX_PAGES. */
         maxPages?: number;
     };
+    /**
+     * Options for images that need transcoding before a vision provider can
+     * read them (HEIC, TIFF, BMP, ICO, JPEG 2000, AVIF — see
+     * `adapters/imageFormatSupport.ts`). Mirrors `GenerateOptions.imageOptions`;
+     * this is the shape that actually reaches `MessageBuilder` for providers
+     * built on `BaseProvider`.
+     */
+    imageOptions?: {
+        /**
+         * Transcode target for an incompatible image. Defaults to `"png"` — the
+         * module's own default, unchanged unless a caller opts in here.
+         */
+        outputFormat?: VisionImageOutputFormat;
+    };
     enableSummarization?: boolean;
     /**
      * Skip injecting tool schemas into the system prompt.

package/dist/types/proxy.d.ts

@@ -16,6 +16,11 @@ import type { ProxyContextEvidence, ProxyPreparedContext } from "./proxyContext.
  * - src/lib/server/routes/claudeProxyRoutes.ts (runtime state, deps)
  */
 import type { Counter, Histogram, Span } from "@opentelemetry/api";
+import type { LogRecordExporter } from "@opentelemetry/sdk-logs";
+/** HTTP exporter with an explicit bounded-shutdown cancellation boundary. */
+export type ProxyOtlpLogTransport = LogRecordExporter & {
+    abortPending: () => void;
+};
 import type { Hono } from "hono";
 import type { Ora } from "ora";
 import type { MCPToolRegistry } from "../mcp/toolRegistry.js";
@@ -726,6 +731,49 @@ export type ProxyBodyDeliveryResult = {
     maxChunkExportMs?: number;
     reason?: string;
 };
+/** One-hop reference to identical redacted bytes from the same request. */
+export type ProxyBodyCaptureReference = {
+    captureId: string;
+    requestId: string;
+    bodySha256: string;
+    redactedBodyBytes: number;
+    /** Source export settlement time, used to bound backend reconstruction. */
+    exportedAt: string;
+};
+export type ProxyBodyCapturePublication = {
+    delivery?: ProxyBodyDeliveryResult | {
+        status: "reference";
+        reason: "identical_redacted_payload";
+    } | {
+        status: "policy_excluded";
+        reason: "body_byte_budget_exhausted" | "body_byte_budget_invalid";
+    };
+    reference?: ProxyBodyCaptureReference;
+};
+export type ProxyBodyCapturePolicyOptions = {
+    bytesPerMinute?: string;
+    deduplicate?: boolean;
+    now?: () => number;
+};
+export type ProxyBodyCapturePolicySnapshot = {
+    deduplicationEnabled: boolean;
+    maxReferences: number;
+    referenceTtlMs: number;
+    references: number;
+    byteBudgetPerMinute: number | null;
+    invalidByteBudget: boolean;
+    availableBytes: number | null;
+    submittedBytes: number;
+    deduplicatedCaptures: number;
+    deduplicatedBytes: number;
+    policyExcludedCaptures: number;
+    policyExcludedBytes: number;
+};
+export type ProxyBodyDeduplicationEntry = {
+    reference: ProxyBodyCaptureReference;
+    expiresAt: number;
+    acknowledged: Promise<boolean>;
+};
 /** One bounded body publication, tracked across exporter callbacks. */
 export type ProxyBodyPublicationProgress = {
     acknowledged: number;
@@ -828,6 +876,7 @@ export type ProxyRequestLoggerSnapshot = {
     diskEnabled?: boolean;
     otel?: ReturnType<typeof import("../proxy/otelLogSink.js").getProxyOtelLogSnapshot>;
     bodyCapture?: ProxyBodyCaptureWorkerSnapshot;
+    bodyCapturePolicy?: ProxyBodyCapturePolicySnapshot;
     enabled: boolean;
     requests: ProxyRequestLogSinkSnapshot;
     attempts: ProxyRequestLogSinkSnapshot;
@@ -2563,6 +2612,20 @@ export type UpdateCheckResult = {
     currentVersion: string;
     latestVersion: string;
     updateAvailable: boolean;
+} & ({
+    checkSucceeded: true;
+    checkError?: never;
+} | {
+    checkSucceeded: false;
+    checkError: string;
+    updateAvailable: false;
+});
+/** Immutable identity of the worker an update attempt is allowed to replace. */
+export type ProxyServingWorkerIdentity = {
+    version: string;
+    pid: number;
+    /** Rolling generation; null only for a legacy single-process service. */
+    generation: number | null;
 };
 /** Result of one local proxy health probe by the updater or fail-open guard. */
 export type ProxyHealthProbe = {
@@ -2587,6 +2650,9 @@ export type SuppressedVersion = {
 export type UpdateState = {
     lastCheckAt: string;
     lastCheckVersion: string;
+    /** Last attempt is distinct from the last successful registry observation. */
+    lastCheckAttemptAt?: string;
+    lastCheckError?: string | null;
     suppressedVersions: Record<string, SuppressedVersion>;
     /**
      * Last package version whose stable trampoline was successfully validated.
@@ -2621,7 +2687,7 @@ export type UpdateState = {
 export type ProxyUpdateWindowResult = {
     ready: boolean;
     draining: boolean;
-    reason?: "stopping" | "parent_stopped" | "drain_failed" | "drain_timeout";
+    reason?: "stopping" | "parent_stopped" | "drain_failed" | "drain_timeout" | "busy";
 };
 /** Dependencies and timing controls for the updater's safe-window coordinator. */
 export type ProxyUpdateWindowOptions = {
@@ -2629,6 +2695,8 @@ export type ProxyUpdateWindowOptions = {
     quietWaitMs: number;
     drainWaitMs: number;
     pollIntervalMs: number;
+    /** Automatic supervisor refresh must defer instead of draining busy traffic. */
+    allowBusyDrain?: boolean;
     getActivity: () => Promise<ProxyRuntimeActivity | null>;
     setDraining: (draining: boolean) => Promise<boolean>;
     isStopping: () => boolean;
@@ -2705,6 +2773,10 @@ export type ProxyWorkerControlMessage = {
 } | {
     type: "proxy-worker:shutdown";
     generation: number;
+} | {
+    type: "proxy-worker:socket-offer";
+    generation: number;
+    socketId: string;
 } | {
     type: "proxy-worker:socket-commit";
     generation: number;
@@ -2720,6 +2792,10 @@ export type ProxyWorkerStatusMessage = {
     pid: number;
     version: string;
     processInstanceId?: string;
+    /** New supervisors defer sending descriptors until commit. */
+    socketOfferProtocol?: "control-before-handle";
+    /** New workers confirm descriptor adoption before a generation drains. */
+    socketCommitProtocol?: "worker-ack";
 } | {
     type: "proxy-worker:drained";
     generation: number;
@@ -2738,6 +2814,11 @@ export type ProxyWorkerStatusMessage = {
     generation: number;
     pid: number;
     socketId: string;
+} | {
+    type: "proxy-worker:socket-committed";
+    generation: number;
+    pid: number;
+    socketId: string;
 } | {
     type: "proxy-worker:replacement-requested";
     generation: number;
@@ -2755,8 +2836,12 @@ export type TransferableProxySocket = Pick<import("node:net").Socket, "destroy"
 export type DetachableTransferableProxySocket = TransferableProxySocket & Pick<import("node:net").Socket, "off">;
 export type RollingWorkerHandle = {
     pid: number;
+    /** Combined offer and commit budget, before any retry. Defaults to 60s. */
+    socketTransferTimeoutMs?: number;
     sendControl: (message: ProxyWorkerControlMessage) => void;
-    sendSocket: (generation: number, socket: TransferableProxySocket, callback: (error?: Error | null) => void) => void;
+    sendSocket: (generation: number, socket: TransferableProxySocket, callback: (error?: Error | null) => void, 
+    /** Absolute admission deadline shared by queueing and any safe retry. */
+    deadlineAt?: number) => void;
     terminate: (signal?: NodeJS.Signals) => void;
     onMessage: (listener: (message: ProxyWorkerStatusMessage) => void) => () => void;
     onExit: (listener: (code: number | null, signal: string | null) => void) => () => void;
@@ -2853,6 +2938,9 @@ export type RollingProxyServerOptions = {
     shutdownTimeoutMs?: number;
     recoveryDelayMs?: number;
     maxRecoveryDelayMs?: number;
+    /** Backoff after failed pressure-induced replacement, while old worker serves. */
+    stallReplacementDelayMs?: number;
+    maxStallReplacementDelayMs?: number;
     onStateChange?: (snapshot: RollingWorkerSupervisorSnapshot) => void;
     onEvent?: (event: RollingWorkerSupervisorEvent) => void;
     log?: (message: string) => void;
@@ -2879,8 +2967,12 @@ export type RollingCandidateWorker = RollingManagedWorker & {
     activationRequested: boolean;
     settle: (error?: Error) => void;
 };
-export type RollingQueuedSocket = {
+export type RollingSocketAdmission = {
     socket: TransferableProxySocket;
+    deadlineAt: number;
+    retried: boolean;
+};
+export type RollingQueuedSocket = RollingSocketAdmission & {
     timeout: NodeJS.Timeout;
 };
 export type SocketWorkerRuntime = {
@@ -2896,6 +2988,8 @@ export type SocketWorkerRuntime = {
 };
 export type SocketWorkerRuntimeOptions = {
     onDrained?: () => void;
+    /** Bound for a committed socket's first HTTP request while draining. */
+    firstRequestGraceMs?: number;
 };
 /** Shape of the dynamically-imported js-yaml module. `dump` is optional —
  *  read-only consumers (proxy config loader) only need `load`; writers

package/dist/types/stream.d.ts

@@ -15,7 +15,7 @@ import type { AIModelProviderConfig, NeurolinkCredentials } from "./providers.js
 import type { TTSChunk, TTSOptions, TTSResult } from "./tts.js";
 import type { STTOptions, STTResult } from "./stt.js";
 import type { StandardRecord, ValidationSchema } from "./aliases.js";
-import type { CSVProcessorOptions, FileWithMetadata } from "./file.js";
+import type { CSVProcessorOptions, FileWithMetadata, VisionImageOutputFormat } from "./file.js";
 import type { WorkflowConfig } from "./workflow.js";
 import type { LanguageModel, StepResult } from "./providers.js";
 import type { Tool, ToolChoice } from "./tools.js";
@@ -373,6 +373,18 @@ export type StreamOptions = {
          */
         maxPages?: number;
     };
+    /**
+     * Options for images that need transcoding before a vision provider can
+     * read them (HEIC, TIFF, BMP, ICO, JPEG 2000, AVIF — see
+     * `adapters/imageFormatSupport.ts`). Mirrors `GenerateOptions.imageOptions`.
+     */
+    imageOptions?: {
+        /**
+         * Transcode target for an incompatible image. Defaults to `"png"` — the
+         * module's own default, unchanged unless a caller opts in here.
+         */
+        outputFormat?: VisionImageOutputFormat;
+    };
     videoOptions?: {
         /** Frames to extract. Unset lets VideoProcessor pick from the clip's duration; clamped to 100. */
         frames?: number;