@juspay/neurolink 12.29.1 → 12.30.0

package/dist/providers/openaiChatCompletionsBase.js

@@ -262,6 +262,16 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
     useStreamingWireForGenerate() {
         return false;
     }
+    /**
+     * When true, an assistant turn's reasoning goes back to the vendor as
+     * `reasoning_content` on every later request of the conversation. DeepSeek
+     * documents this as required once tools are in play and answers 400
+     * without it. Default false: strict OpenAI-compatible backends reject a
+     * field they don't know. Read per request, never during construction.
+     */
+    replayReasoningContent() {
+        return false;
+    }
     /**
      * Hook to adjust the fully-built wire request body before it is sent, on
      * both the streaming and non-streaming paths. Default identity. Override for
@@ -542,6 +552,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         const resolveWireMaxTokens = this.resolveWireMaxTokens.bind(this);
         const suppressResponseFormatWithTools = this.suppressResponseFormatWithTools.bind(this);
         const useStreamingWireForGenerate = this.useStreamingWireForGenerate.bind(this);
+        const replayReasoningContent = this.replayReasoningContent.bind(this);
         const getTimeoutForOptions = (opts) => this.getTimeout((opts ?? {}));
         return {
             specificationVersion: "v3",
@@ -555,7 +566,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                 const wireNameMaps = buildWireToolNameMaps((options.tools ?? [])
                     .filter((t) => t.type === "function")
                     .map((t) => t.name));
-                const baseMessages = messageBuilderToOpenAI(options.prompt, wireNameMaps?.toWire);
+                const baseMessages = messageBuilderToOpenAI(options.prompt, wireNameMaps?.toWire, replayReasoningContent());
                 const hasTools = Array.isArray(options.tools) && options.tools.length > 0;
                 const responseFormat = options.responseFormat &&
                     !(hasTools && suppressResponseFormatWithTools())
@@ -1657,7 +1668,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                 const transformedPrompt = Array.isArray(params?.prompt)
                     ? params.prompt
                     : promptMessages;
-                const conversation = messageBuilderToOpenAI(transformedPrompt, wireNameMaps?.toWire);
+                const conversation = messageBuilderToOpenAI(transformedPrompt, wireNameMaps?.toWire, this.replayReasoningContent());
                 loopConversation = conversation;
                 const sampled = {
                     ...options,
@@ -2171,6 +2182,9 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             role: "assistant",
             content: stepResult.text.length > 0 ? stepResult.text : null,
             tool_calls: toolCallsForMessage,
+            ...(this.replayReasoningContent() && stepResult.reasoning
+                ? { reasoning_content: stepResult.reasoning }
+                : {}),
         });
         for (const [, t] of stepResult.toolCalls) {
             const startedAt = new Date();

package/dist/providers/openaiChatCompletionsClient.d.ts

@@ -48,7 +48,7 @@ export declare const stringifyToolInput: (input: unknown) => string;
 export declare const stringifyToolOutput: (output: unknown) => string;
 export declare const imageDataToURL: (data: unknown, mediaType?: string) => string | undefined;
 export declare const convertContentForOpenAI: (content: unknown) => string | OpenAICompatMessageContent[];
-export declare const messageBuilderToOpenAI: (messages: ReadonlyArray<OpenAICompatMessage>, toolNameToWire?: Map<string, string>) => OpenAICompatChatMessage[];
+export declare const messageBuilderToOpenAI: (messages: ReadonlyArray<OpenAICompatMessage>, toolNameToWire?: Map<string, string>, replayReasoning?: boolean) => OpenAICompatChatMessage[];
 export declare const buildToolsForOpenAI: (tools: Record<string, Tool>, toolNameToWire?: Map<string, string>) => OpenAICompatChatTool[] | undefined;
 export declare const v3ToolsToOpenAI: (tools: OpenAICompatV3CallTools | undefined, toolNameToWire?: Map<string, string>) => OpenAICompatChatTool[] | undefined;
 export declare const v3ToolChoiceToOpenAI: (choice: OpenAICompatV3CallToolChoice, toolNameToWire?: Map<string, string>) => OpenAICompatToolChoiceWire | undefined;

package/dist/providers/openaiChatCompletionsClient.js

@@ -96,6 +96,11 @@ export const estimateWireTokens = (messages, tools, provider) => {
         if (toolCalls) {
             total += estimateTokens(safeStringify(toolCalls), provider);
         }
+        const reasoning = message
+            .reasoning_content;
+        if (reasoning) {
+            total += estimateTokens(reasoning, provider);
+        }
     }
     if (tools && tools.length > 0) {
         total += estimateTokens(safeStringify(tools), provider);
@@ -242,7 +247,7 @@ export const convertContentForOpenAI = (content) => {
     }
     return out;
 };
-export const messageBuilderToOpenAI = (messages, toolNameToWire) => {
+export const messageBuilderToOpenAI = (messages, toolNameToWire, replayReasoning = false) => {
     const out = [];
     for (const msg of messages) {
         switch (msg.role) {
@@ -264,10 +269,14 @@ export const messageBuilderToOpenAI = (messages, toolNameToWire) => {
                 const parts = Array.isArray(msg.content) ? msg.content : [msg.content];
                 const text = [];
                 const toolCalls = [];
+                const reasoning = [];
                 for (const part of parts) {
                     if (part && typeof part === "object") {
                         const p = part;
-                        if (p.type === "text") {
+                        if (p.type === "reasoning") {
+                            reasoning.push(part.text ?? "");
+                        }
+                        else if (p.type === "text") {
                             text.push({
                                 type: "text",
                                 text: part.text ?? "",
@@ -297,10 +306,12 @@ export const messageBuilderToOpenAI = (messages, toolNameToWire) => {
                     : text.length === 1 && text[0].type === "text"
                         ? text[0].text
                         : text;
+                const reasoningContent = replayReasoning ? reasoning.join("") : "";
                 out.push({
                     role: "assistant",
                     content: flat,
                     ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+                    ...(reasoningContent ? { reasoning_content: reasoningContent } : {}),
                 });
                 break;
             }

package/dist/types/file.d.ts

@@ -1,6 +1,7 @@
 /**
  * File detection and processing types for unified file handling
  */
+import type { ImageWithAltText } from "./multimodal.js";
 /**
  * Supported file types for multimodal input
  */
@@ -276,8 +277,15 @@ export type FileProcessingResult = {
     type: FileType;
     content: string | Buffer;
     mimeType: string;
-    /** Additional images extracted from the file (e.g., video keyframes, audio cover art) */
-    images?: Array<Buffer | string>;
+    /**
+     * Additional images extracted from the file (e.g., video keyframes, audio
+     * cover art).
+     *
+     * An entry may carry alt text, which is how a video keyframe states the
+     * timestamp it was sampled at. Bare bytes still work — the field was
+     * widened, not changed.
+     */
+    images?: Array<Buffer | string | ImageWithAltText>;
     metadata: {
         confidence: number;
         size?: number;
@@ -549,6 +557,16 @@ export type VideoProcessorOptions = {
     quality?: number;
     /** Frame encoding. Defaults to jpeg. */
     format?: "jpeg" | "png";
+    /**
+     * Transcribe the clip's spoken audio (#433). Off by default: it costs an
+     * ffmpeg pass plus a Whisper call, and most attached video is silent
+     * screen capture.
+     *
+     * Best-effort — a clip with no audio track, no `OPENAI_API_KEY`, or a
+     * failed call still processes, and the reason lands in
+     * `ProcessedVideo.transcriptionSkippedReason`.
+     */
+    transcribeAudio?: boolean;
 };
 /**
  * Office processor options for Word, PowerPoint, and Excel documents

package/dist/types/generate.d.ts

@@ -18,7 +18,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, MultimodalVideoEntry, VisionImageOutputFormat } from "./file.js";
+import type { CSVProcessorOptions, VideoProcessorOptions, FileWithMetadata, MultimodalAudioEntry, MultimodalVideoEntry, 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";
@@ -180,16 +180,15 @@ export type GenerateOptions = {
          */
         outputFormat?: VisionImageOutputFormat;
     };
-    videoOptions?: {
-        /** Frames to extract. Unset lets VideoProcessor pick from the clip's duration; clamped to 100. */
-        frames?: number;
-        /** Frame encoder quality, clamped to 1-100. Default 80. */
-        quality?: number;
-        /** Frame encoding. Default jpeg. */
-        format?: "jpeg" | "png";
-        /** Not implemented yet (#433) — warns rather than silently doing nothing. */
-        transcribeAudio?: boolean;
-    };
+    /**
+     * Video processing options — keyframe budget, encoder settings, and
+     * whether to transcribe the clip's spoken audio.
+     *
+     * The canonical shape, rather than a third structurally-identical copy of
+     * it: `StreamOptions` and `TextGenerationOptions` declare the same field,
+     * and the inline copies had already drifted apart in what they documented.
+     */
+    videoOptions?: VideoProcessorOptions;
     /**
      * Text-to-Speech (TTS) configuration
      *
@@ -1428,6 +1427,16 @@ export type TextGenerationOptions = {
     expectedOutcome?: string;
     evaluationCriteria?: string[];
     csvOptions?: CSVProcessorOptions;
+    /**
+     * Video processing options (#478, #433).
+     *
+     * Reconstructed option objects have to carry this the same way they carry
+     * `csvOptions` and `pdfOptions`: the message builder hands it to the
+     * detector, which hands it to `VideoProcessor`, and anything that rebuilds
+     * the options along the way and omits it restores the defaults without
+     * saying so.
+     */
+    videoOptions?: VideoProcessorOptions;
     /** PDF processing options (#258). */
     pdfOptions?: {
         /** Password for an encrypted PDF (image-conversion fallback path). */
@@ -1453,21 +1462,6 @@ export type TextGenerationOptions = {
          */
         outputFormat?: VisionImageOutputFormat;
     };
-    /**
-     * Video processing options (mirrors `GenerateOptions.videoOptions`). Never
-     * declared here before, so `buildGenerateTextOptions` had nowhere to
-     * forward the caller's setting even once the allowlist itself named it.
-     */
-    videoOptions?: {
-        /** Frames to extract. Unset lets VideoProcessor pick from the clip's duration; clamped to 100. */
-        frames?: number;
-        /** Frame encoder quality, clamped to 1-100. Default 80. */
-        quality?: number;
-        /** Frame encoding. Default jpeg. */
-        format?: "jpeg" | "png";
-        /** Not implemented yet (#433) — warns rather than silently doing nothing. */
-        transcribeAudio?: boolean;
-    };
     enableSummarization?: boolean;
     /**
      * Skip injecting tool schemas into the system prompt.

package/dist/types/openaiCompatible.d.ts

@@ -34,6 +34,9 @@ export type OpenAICompatChatMessage = {
     role: "assistant";
     content?: string | OpenAICompatMessageContent[] | null;
     tool_calls?: OpenAICompatToolCallWire[];
+    /** The turn's reasoning, sent back only where the catalog opts in
+     *  (DeepSeek's replayReasoningContent quirk). */
+    reasoning_content?: string;
 } | {
     role: "tool";
     content: string;

package/dist/types/processor.d.ts

@@ -711,6 +711,20 @@ export type ProcessedAudio = ProcessedFileBase & {
     transcriptionSkippedReason?: string;
     coverArt?: Buffer;
 };
+/**
+ * One extracted keyframe and the moment it came from.
+ *
+ * Internal to extraction: `ProcessedVideo` splits this back into the parallel
+ * `keyframes` / `keyframeTimestampsSec` arrays its existing consumers expect.
+ * Keeping the pair together while frames are being read and encoded is what
+ * makes a dropped frame impossible to mislabel — the alternative is
+ * reconstructing timestamps from an interval after the fact, which is wrong
+ * for every frame following a failed encode.
+ */
+export type VideoKeyframe = {
+    readonly buffer: Buffer;
+    readonly timestampSec: number;
+};
 /**
  * Processed video result.
  * Extends ProcessedFileBase with video-specific fields including metadata,
@@ -720,6 +734,19 @@ export type ProcessedAudio = ProcessedFileBase & {
 export type ProcessedVideo = ProcessedFileBase & {
     textContent: string;
     keyframes: Buffer[];
+    /**
+     * When each entry of `keyframes` was sampled, in seconds from the start of
+     * the clip. Same length, same order, ascending.
+     *
+     * A parallel array rather than a richer `keyframes` element type: that
+     * field is read by `fileReferenceRegistry` and by the detector as a plain
+     * `Buffer[]`, and reshaping it would break them for a value they do not
+     * need. Extraction can also drop an individual frame when its encode
+     * fails, so the timestamps are recorded as frames are kept — never
+     * reconstructed from an interval, which would silently mislabel every
+     * frame after a dropped one.
+     */
+    keyframeTimestampsSec: number[];
     metadata: {
         duration: number;
         durationFormatted: string;
@@ -735,6 +762,22 @@ export type ProcessedVideo = ProcessedFileBase & {
         fileSize: number;
     };
     subtitleText?: string;
+    /**
+     * Speech transcribed from the clip's audio track, when
+     * `VideoProcessorOptions.transcribeAudio` asked for it and it worked.
+     *
+     * Distinct from `subtitleText`, which is an embedded subtitle stream the
+     * file already carried. A recording can have one, both or neither.
+     */
+    transcript?: string;
+    hasTranscript: boolean;
+    /**
+     * Why no transcript was produced. Follows `ProcessedAudio`'s precedent:
+     * "nobody asked", "there is no audio track", "no API key", "the call
+     * failed" and "nobody was speaking" are five different situations that
+     * otherwise all present as an absent transcript.
+     */
+    transcriptionSkippedReason?: string;
     hasKeyframes: boolean;
     frameCount: number;
 };

package/dist/types/providerCatalog.d.ts

@@ -73,6 +73,11 @@ export type CatalogQuirks = {
      *  ConfiguredOpenAICompatProvider so `generate({ schema })` keeps working
      *  (mirrors the pre-catalog `supportsStructuredOutputs: false` behavior). */
     responseFormatDowngrade?: "json-schema-to-json-object";
+    /** Vendor wants each assistant turn's `reasoning_content` sent back on
+     *  every later request of the conversation (DeepSeek documents a 400
+     *  without it once tools are in play). ConfiguredOpenAICompatProvider
+     *  turns on the replay; every other provider leaves the field off. */
+    replayReasoningContent?: boolean;
 };
 export type CatalogBillingPolicy = "free-tier" | "free-with-card" | "no-free-tier";
 export type CatalogSetup = {

package/dist/types/providers.d.ts

@@ -798,6 +798,9 @@ export type OpenAICompatCatalogEntry = {
      *  `response_format: { type: "json_schema" }` but accepts
      *  `{ type: "json_object" }`. */
     responseFormatDowngrade?: "json-schema-to-json-object";
+    /** See CatalogQuirks.replayReasoningContent — a vendor that wants each
+     *  assistant turn's `reasoning_content` sent back on later requests. */
+    replayReasoningContent?: boolean;
 };
 /** The subset of OpenAICompatCatalogEntry that resolveOpenAICompatConfig()
  *  needs — lets call sites pass a minimal object without the full catalog

package/dist/types/stream.d.ts

@@ -16,7 +16,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, VisionImageOutputFormat } from "./file.js";
+import type { CSVProcessorOptions, FileWithMetadata, VideoProcessorOptions, VisionImageOutputFormat } from "./file.js";
 import type { WorkflowConfig } from "./workflow.js";
 import type { LanguageModel, StepResult } from "./providers.js";
 import type { Tool, ToolChoice } from "./tools.js";
@@ -356,6 +356,16 @@ export type StreamOptions = {
         };
     };
     csvOptions?: CSVProcessorOptions;
+    /**
+     * Video processing options (#478, #433).
+     *
+     * Reconstructed option objects have to carry this the same way they carry
+     * `csvOptions` and `pdfOptions`: the message builder hands it to the
+     * detector, which hands it to `VideoProcessor`, and anything that rebuilds
+     * the options along the way and omits it restores the defaults without
+     * saying so.
+     */
+    videoOptions?: VideoProcessorOptions;
     /** PDF processing options (#258). */
     pdfOptions?: {
         /** Password for an encrypted PDF (image-conversion fallback path). */
@@ -386,16 +396,6 @@ export type StreamOptions = {
          */
         outputFormat?: VisionImageOutputFormat;
     };
-    videoOptions?: {
-        /** Frames to extract. Unset lets VideoProcessor pick from the clip's duration; clamped to 100. */
-        frames?: number;
-        /** Frame encoder quality, clamped to 1-100. Default 80. */
-        quality?: number;
-        /** Frame encoding. Default jpeg. */
-        format?: "jpeg" | "png";
-        /** Not implemented yet (#433) — warns rather than silently doing nothing. */
-        transcribeAudio?: boolean;
-    };
     /**
      * Text-to-Speech (TTS) configuration for streaming
      *

package/dist/utils/fileDetector.d.ts

@@ -114,6 +114,21 @@ export declare class FileDetector {
     /**
      * SDK-8: Format an informative placeholder when a file processor fails.
      * Instead of bare "[Video file: name]" strings, include size, format, and
+     * Describe one keyframe well enough for a model to place it in time.
+     *
+     * The clip's total length rides along because the eighth frame of a
+     * recording means nothing without knowing how long the recording is.
+     *
+     * Explicit units rather than a clock — see `formatKeyframeTimestamp`. An
+     * earlier draft used "0:03" here and the model reported the frame as
+     * appearing at "3:00".
+     *
+     * A timestamp can be missing if extraction and its schedule ever disagree
+     * in length. That should not happen, but an unlabelled frame is better
+     * than one labelled "NaN".
+     */
+    private static describeKeyframe;
+    /**
      * the reason for failure so the LLM can acknowledge the attachment.
      */
     private static formatInformativePlaceholder;

package/dist/utils/fileDetector.js

@@ -37,6 +37,7 @@ import { withTimeout } from "./errorHandling.js";
 import { normalizeUrlForCache, redactUrlForError, sanitizeErrorCause, } from "./logSanitize.js";
 import { mimeHintToExtension, mimeHintToFileType, normalizeMimeHint, } from "./mimeTypeHints.js";
 import { PDFProcessor } from "./pdfProcessor.js";
+import { formatKeyframeTimestamp } from "./mediaDuration.js";
 /**
  * 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
@@ -797,6 +798,26 @@ export class FileDetector {
     /**
      * SDK-8: Format an informative placeholder when a file processor fails.
      * Instead of bare "[Video file: name]" strings, include size, format, and
+     * Describe one keyframe well enough for a model to place it in time.
+     *
+     * The clip's total length rides along because the eighth frame of a
+     * recording means nothing without knowing how long the recording is.
+     *
+     * Explicit units rather than a clock — see `formatKeyframeTimestamp`. An
+     * earlier draft used "0:03" here and the model reported the frame as
+     * appearing at "3:00".
+     *
+     * A timestamp can be missing if extraction and its schedule ever disagree
+     * in length. That should not happen, but an unlabelled frame is better
+     * than one labelled "NaN".
+     */
+    static describeKeyframe(timestampSec, durationFormatted) {
+        if (typeof timestampSec !== "number" || !Number.isFinite(timestampSec)) {
+            return undefined;
+        }
+        return `Video keyframe at ${formatKeyframeTimestamp(timestampSec)} into a ${durationFormatted} video`;
+    }
+    /**
      * the reason for failure so the LLM can acknowledge the attachment.
      */
     static formatInformativePlaceholder(typeName, filename, content, detection, error) {
@@ -1120,25 +1141,37 @@ export class FileDetector {
             // the processor; previously these stopped at the CLI layer.
             videoOptions);
             if (videoResult.success && videoResult.data) {
+                // Bound to a local because the keyframe map below is a closure, and
+                // TypeScript drops the `videoResult.data` narrowing across one.
+                const video = videoResult.data;
                 return {
                     type: "video",
-                    content: videoResult.data.textContent ||
+                    content: video.textContent ||
                         FileDetector.formatInformativePlaceholder("Video", videoFilename, content, detection),
                     mimeType: detection.mimeType,
-                    images: videoResult.data.keyframes && videoResult.data.keyframes.length > 0
-                        ? videoResult.data.keyframes
+                    // Each keyframe carries the moment it was sampled at. Alt text is
+                    // the only per-image channel that survives to the model — the
+                    // message builder folds it into the prompt as
+                    // "[Image N: <alt>]" — so without it the frames arrive as an
+                    // unlabelled pile and "what happens at 0:30?" has no answer even
+                    // though the frame at 0:30 is right there.
+                    images: video.keyframes && video.keyframes.length > 0
+                        ? video.keyframes.map((frame, index) => ({
+                            data: frame,
+                            altText: FileDetector.describeKeyframe(video.keyframeTimestampsSec[index], video.metadata.durationFormatted),
+                        }))
                         : undefined,
                     metadata: {
                         ...detection.metadata,
-                        frameCount: videoResult.data.frameCount,
-                        hasKeyframes: videoResult.data.hasKeyframes,
+                        frameCount: video.frameCount,
+                        hasKeyframes: video.hasKeyframes,
                         // Carried so native delivery can apply its duration ceiling
                         // without opening the container a second time. The processor
                         // reports 0 when nothing could probe it; that is "unknown", not a
                         // zero-length clip, so it is left off rather than passed through
                         // as a number a ceiling check would happily accept.
-                        ...(videoResult.data.metadata.duration > 0
-                            ? { durationSec: videoResult.data.metadata.duration }
+                        ...(video.metadata.duration > 0
+                            ? { durationSec: video.metadata.duration }
                             : {}),
                     },
                 };

package/dist/utils/mediaDuration.d.ts

@@ -21,3 +21,22 @@
  * fabricated number would be worse than an obvious zero.
  */
 export declare function formatMediaDuration(seconds: number): string;
+/**
+ * Format the moment a video keyframe was sampled at — "3.00s",
+ * "1234.00s (20m 34s)".
+ *
+ * Deliberately not the clock form, for the reason in this module's header:
+ * the string is read by a language model, and "0:03" is ambiguous. That is
+ * not theoretical here — an early draft labelled frames "0:03" and the model
+ * reported the green frame as appearing at "3:00".
+ *
+ * Deliberately not `formatMediaDuration` alone either. That rounds to whole
+ * seconds, and an explicit `videoOptions.frames` spreads frames evenly rather
+ * than on the duration tier: sixteen frames across a 3.6s clip are 0.225s
+ * apart, and every one of them would render as "0s". The precise value is
+ * therefore always present, with the readable form added only past a minute,
+ * where "1234.00s" stops meaning anything to a reader.
+ *
+ * Non-finite and negative inputs clamp to zero rather than emitting "NaNs".
+ */
+export declare function formatKeyframeTimestamp(seconds: number): string;

package/dist/utils/mediaDuration.js

@@ -42,3 +42,26 @@ export function formatMediaDuration(seconds) {
     }
     return parts.join(" ");
 }
+/**
+ * Format the moment a video keyframe was sampled at — "3.00s",
+ * "1234.00s (20m 34s)".
+ *
+ * Deliberately not the clock form, for the reason in this module's header:
+ * the string is read by a language model, and "0:03" is ambiguous. That is
+ * not theoretical here — an early draft labelled frames "0:03" and the model
+ * reported the green frame as appearing at "3:00".
+ *
+ * Deliberately not `formatMediaDuration` alone either. That rounds to whole
+ * seconds, and an explicit `videoOptions.frames` spreads frames evenly rather
+ * than on the duration tier: sixteen frames across a 3.6s clip are 0.225s
+ * apart, and every one of them would render as "0s". The precise value is
+ * therefore always present, with the readable form added only past a minute,
+ * where "1234.00s" stops meaning anything to a reader.
+ *
+ * Non-finite and negative inputs clamp to zero rather than emitting "NaNs".
+ */
+export function formatKeyframeTimestamp(seconds) {
+    const safe = Number.isFinite(seconds) && seconds > 0 ? seconds : 0;
+    const precise = `${safe.toFixed(2)}s`;
+    return safe >= 60 ? `${precise} (${formatMediaDuration(safe)})` : precise;
+}

package/dist/utils/messageBuilder.js

@@ -832,20 +832,6 @@ export function mergeMediaFileAliases(input) {
     input.audioFiles = undefined;
     input.videoFiles = undefined;
 }
-/**
- * #478: `transcribeAudio` (CLI `--transcribe-audio`) is accepted by the options
- * surface but no video-audio transcription exists yet — VideoProcessor extracts
- * keyframes and embedded subtitle tracks only, and the transcription step is
- * still open as #433. Say so once per request rather than letting the caller
- * believe a transcript was produced and silently omitted.
- */
-function warnIfVideoTranscriptionRequested(videoOptions) {
-    if (videoOptions?.transcribeAudio) {
-        logger.warn("[NEUROLINK] Video audio transcription was requested but is not implemented yet " +
-            "(tracked as #433). Keyframes and any embedded subtitle tracks are still extracted; " +
-            "spoken audio will not be transcribed.");
-    }
-}
 /**
  * Process the unified files array with auto-detection.
  * Handles lazy file registration, full processing, and preview injection.
@@ -916,6 +902,10 @@ async function detectFileForUnifiedArray(file, options, provider, genericFileMax
                 frames: options.videoOptions.frames,
                 quality: options.videoOptions.quality,
                 format: options.videoOptions.format,
+                // #433: `--transcribe-audio` stopped here until now — the flag was
+                // accepted, warned about, and never handed to the processor that
+                // would have to act on it.
+                transcribeAudio: options.videoOptions.transcribeAudio,
             }
             : undefined,
         provider: provider,
@@ -952,7 +942,6 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
     }
     const totalFiles = pending.length;
     const files = pending;
-    warnIfVideoTranscriptionRequested(options.videoOptions);
     return withSpan({
         name: "neurolink.file.process_all",
         tracer: tracers.file,

package/dist/utils/multimodalOptionsBuilder.d.ts

@@ -15,6 +15,7 @@ import type { StreamOptions } from "../types/index.js";
  *   - input.audioFiles: Audio files (Buffer | string paths)
  *   - input.videoFiles: Video files (Buffer | string paths)
  *   - csvOptions: CSV parsing options
+ *   - videoOptions: Video frame/quality/format/transcription options
  *   - systemPrompt: System-level instructions
  *   - conversationMessages: Chat history
  *   - temperature: Model temperature (0-1)
@@ -64,6 +65,7 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
     imageOptions: {
         outputFormat?: import("../index.js").VisionImageOutputFormat;
     } | undefined;
+    videoOptions: import("../index.js").VideoProcessorOptions | undefined;
     systemPrompt: string | undefined;
     conversationHistory: import("../index.js").ChatMessage[] | undefined;
     provider: string;

package/dist/utils/multimodalOptionsBuilder.js

@@ -14,6 +14,7 @@
  *   - input.audioFiles: Audio files (Buffer | string paths)
  *   - input.videoFiles: Video files (Buffer | string paths)
  *   - csvOptions: CSV parsing options
+ *   - videoOptions: Video frame/quality/format/transcription options
  *   - systemPrompt: System-level instructions
  *   - conversationMessages: Chat history
  *   - temperature: Model temperature (0-1)
@@ -60,6 +61,12 @@ export function buildMultimodalOptions(options, providerName, modelName) {
         csvOptions: options.csvOptions,
         pdfOptions: options.pdfOptions,
         imageOptions: options.imageOptions,
+        // Same whitelist hazard as above, one level up: `videoFiles` reaching
+        // the processor is not enough on its own — without `videoOptions` too,
+        // the frame/quality/format/transcribeAudio knobs a caller set on
+        // `StreamOptions` never reach VideoProcessor on the Bedrock branch, and
+        // it silently falls back to the duration-tier default.
+        videoOptions: options.videoOptions,
         systemPrompt: options.systemPrompt,
         conversationHistory: options.conversationMessages,
         provider: providerName,