@stabgan/openrouter-mcp-multimodal 4.6.1 → 4.7.0

package/dist/tool-handlers/tool-result-payload.d.ts

@@ -0,0 +1,47 @@
+export type InlineMediaKind = 'image' | 'audio' | 'video';
+type TextContent = {
+    type: 'text';
+    text: string;
+};
+type ImageContent = {
+    type: 'image';
+    mimeType: string;
+    data: string;
+};
+type AudioContent = {
+    type: 'audio';
+    mimeType: string;
+    data: string;
+};
+type ResourceContent = {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+        blob: string;
+    };
+};
+export type BinaryToolContent = TextContent | ImageContent | AudioContent | ResourceContent;
+export interface BinaryArtifact {
+    kind: InlineMediaKind;
+    buffer: Buffer;
+    mimeType: string;
+}
+export interface BuildBinaryToolResultOptions {
+    savedPath?: string | null;
+    /** Overrides default saved/too-large message */
+    summaryText?: string;
+    /** Shown alongside inline media when not using inlineOnly */
+    prefixText?: string;
+    /** When inline fits and no save_path: return media block only (image UX) */
+    inlineOnly?: boolean;
+    remoteUrl?: string;
+    meta?: Record<string, unknown>;
+    maxInlineBytes?: number;
+}
+export declare function getMaxInlineBytes(kind: InlineMediaKind): number;
+export declare function buildBinaryToolResult(artifact: BinaryArtifact, opts?: BuildBinaryToolResultOptions): {
+    content: BinaryToolContent[];
+    _meta: Record<string, unknown>;
+};
+export {};

package/dist/tool-handlers/tool-result-payload.js

@@ -0,0 +1,96 @@
+/**
+ * Canonical MCP tool-result policy for binary artifacts:
+ * - saved to disk -> text pointer only (never duplicate inline media)
+ * - not saved -> inline only when under byte ceiling, else text + save_path hint
+ * - video uses MCP `resource` blocks (spec has no `video` content type)
+ */
+import { readEnvInt } from './fetch-utils.js';
+const DEFAULT_INLINE_MAX_BYTES = 1024 * 1024;
+const DEFAULT_VIDEO_INLINE_MAX_BYTES = 10 * 1024 * 1024;
+const INLINE_VIDEO_URI = 'inline://openrouter-mcp-multimodal/video';
+const KIND_ENV_KEYS = {
+    image: 'OPENROUTER_IMAGE_INLINE_MAX_BYTES',
+    audio: 'OPENROUTER_AUDIO_INLINE_MAX_BYTES',
+    video: 'OPENROUTER_VIDEO_INLINE_MAX_BYTES',
+};
+const KIND_DEFAULT_BYTES = {
+    image: DEFAULT_INLINE_MAX_BYTES,
+    audio: DEFAULT_INLINE_MAX_BYTES,
+    video: DEFAULT_VIDEO_INLINE_MAX_BYTES,
+};
+export function getMaxInlineBytes(kind) {
+    const globalFallback = readEnvInt('OPENROUTER_INLINE_MAX_BYTES', KIND_DEFAULT_BYTES[kind], 4096);
+    return readEnvInt(KIND_ENV_KEYS[kind], globalFallback, 4096);
+}
+function kindLabel(kind) {
+    switch (kind) {
+        case 'image':
+            return 'Image';
+        case 'audio':
+            return 'Audio';
+        case 'video':
+            return 'Video';
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+}
+function buildInlineBlock(kind, mimeType, data, remoteUrl) {
+    if (kind === 'video') {
+        return {
+            type: 'resource',
+            resource: {
+                uri: remoteUrl ?? INLINE_VIDEO_URI,
+                mimeType,
+                blob: data,
+            },
+        };
+    }
+    return { type: kind, mimeType, data };
+}
+export function buildBinaryToolResult(artifact, opts = {}) {
+    const { kind, buffer, mimeType } = artifact;
+    const maxInline = opts.maxInlineBytes ?? getMaxInlineBytes(kind);
+    const meta = {
+        ...opts.meta,
+        mime: mimeType,
+        size_bytes: buffer.length,
+    };
+    if (opts.savedPath) {
+        const text = opts.summaryText ??
+            `${kindLabel(kind)} saved to: ${opts.savedPath} (${buffer.length} bytes, ${mimeType})`;
+        return {
+            content: [{ type: 'text', text }],
+            _meta: { ...meta, save_path: opts.savedPath },
+        };
+    }
+    if (buffer.length <= maxInline) {
+        const data = buffer.toString('base64');
+        if (opts.inlineOnly) {
+            return {
+                content: [buildInlineBlock(kind, mimeType, data, opts.remoteUrl)],
+                _meta: meta,
+            };
+        }
+        const text = opts.prefixText ?? `${kindLabel(kind)} generated (${buffer.length} bytes, ${mimeType}).`;
+        return {
+            content: [textBlock(text), buildInlineBlock(kind, mimeType, data, opts.remoteUrl)],
+            _meta: meta,
+        };
+    }
+    const urlHint = opts.remoteUrl ? ` URL: ${opts.remoteUrl}` : '';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: opts.summaryText ??
+                    `${kindLabel(kind)} generated (${buffer.length} bytes, ${mimeType}). Too large to inline; pass save_path to persist.${urlHint}`,
+            },
+        ],
+        _meta: meta,
+    };
+}
+function textBlock(text) {
+    return { type: 'text', text };
+}

package/dist/tool-handlers/video-utils.d.ts

@@ -20,10 +20,5 @@ export interface VideoData {
     mediaType: string;
     sizeBytes: number;
 }
-/**
- * Prepare a video from any source (data URL / HTTP URL / local file) as
- * base64 + MIME. OpenRouter requires the client to send video as either a
- * URL or a data URL; we always base64 it so the tool works regardless of
- * provider quirks.
- */
+/** Prepare video from data URL, HTTP URL, or sandboxed local file. */
 export declare function prepareVideoData(source: string): Promise<VideoData>;

package/dist/tool-handlers/video-utils.js

@@ -1,11 +1,4 @@
-/**
- * Video format detection and fetch utilities. Mirrors the structure of
- * `audio-utils.ts`: all network/security logic comes from `fetch-utils.ts`,
- * this module owns format detection, base64 encoding, and MIME mapping.
- *
- * OpenRouter's video-understanding docs (accessed 2026-04-20) list four
- * supported container formats: mp4, mpeg, mov, webm.
- */
+/** Video format detection and fetch utilities. */
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { readEnvInt, fetchHttpResource, parseBase64DataUrl } from './fetch-utils.js';
@@ -107,14 +100,8 @@ export function detectVideoFormat(buffer) {
     }
     return undefined;
 }
-/**
- * Prepare a video from any source (data URL / HTTP URL / local file) as
- * base64 + MIME. OpenRouter requires the client to send video as either a
- * URL or a data URL; we always base64 it so the tool works regardless of
- * provider quirks.
- */
+/** Prepare video from data URL, HTTP URL, or sandboxed local file. */
 export async function prepareVideoData(source) {
-    // --- data URL ---
     if (source.startsWith('data:')) {
         const parsed = parseBase64DataUrl(source);
         if (!parsed)
@@ -136,7 +123,6 @@ export async function prepareVideoData(source) {
             sizeBytes: approxBytes,
         };
     }
-    // --- HTTP(S) URL ---
     if (source.startsWith('http://') || source.startsWith('https://')) {
         const { buffer, contentType } = await fetchHttpResource(source, {
             timeoutMs: getFetchTimeoutMs(),
@@ -155,7 +141,6 @@ export async function prepareVideoData(source) {
             sizeBytes: buffer.length,
         };
     }
-    // --- local file ---
     const safe = await resolveSafeInputPath(source);
     const buffer = await fs.readFile(safe);
     const format = detectVideoFormat(buffer) ?? getVideoFormat(safe);