@stabgan/openrouter-mcp-multimodal 2.0.0 → 3.1.0

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

@@ -0,0 +1,353 @@
+import { promises as fs } from 'node:fs';
+import { extname } from 'node:path';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { logger } from '../logger.js';
+import { resolveSafeOutputPath, UnsafeOutputPathError, } from './path-safety.js';
+import { readEnvInt } from './fetch-utils.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+const FALLBACK_MODEL = 'google/veo-3.1';
+const DEFAULT_POLL_INTERVAL_MS = 15_000;
+const DEFAULT_MAX_WAIT_MS = 10 * 60_000;
+const MIN_POLL_INTERVAL_MS = 50; // just to avoid a 0ms busy-loop if a caller omits
+const INLINE_RETURN_CEILING_BYTES = 10 * 1024 * 1024;
+function getMaxInlineBytes() {
+    return readEnvInt('OPENROUTER_VIDEO_INLINE_MAX_BYTES', INLINE_RETURN_CEILING_BYTES, 4096);
+}
+function getDefaultPollInterval() {
+    return readEnvInt('OPENROUTER_VIDEO_POLL_INTERVAL_MS', DEFAULT_POLL_INTERVAL_MS, MIN_POLL_INTERVAL_MS);
+}
+function getDefaultMaxWait() {
+    return readEnvInt('OPENROUTER_VIDEO_MAX_WAIT_MS', DEFAULT_MAX_WAIT_MS, 10_000);
+}
+function getMaxDownloadBytes() {
+    // Generation output can be bigger than the input cap since it's our own
+    // content. Default 256 MB, override via env.
+    return readEnvInt('OPENROUTER_VIDEO_GEN_MAX_BYTES', 256 * 1024 * 1024, 1024 * 1024);
+}
+/**
+ * Fold a caller-supplied image source (local path, http URL, or data URL)
+ * into the `{ url: "data:video|image/...base64,..." }` shape OpenRouter
+ * expects inside `frame_images[].image` / `input_references[]`.
+ *
+ * We reuse `prepareVideoData` for videos but images live in `image-utils`.
+ * Since generate_video's references are images, not videos, we do a small
+ * image-specific fetch here (data URL pass-through, HTTP via fetch-utils,
+ * local via fs). We deliberately do NOT run them through sharp — the model
+ * wants the pristine frame.
+ */
+async function prepareImageInput(source) {
+    if (!source)
+        return null;
+    if (source.startsWith('data:')) {
+        const match = source.match(/^data:([^;,]+)(?:;[^,]*)*;base64,(.+)$/);
+        if (!match)
+            throw new Error(`Invalid image data URL: ${source.slice(0, 40)}…`);
+        return { mime: match[1], data: match[2] };
+    }
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        const { fetchHttpResource } = await import('./fetch-utils.js');
+        const { buffer, contentType } = await fetchHttpResource(source, {
+            timeoutMs: 30_000,
+            maxBytes: 25 * 1024 * 1024,
+            maxRedirects: 8,
+        });
+        const mime = (contentType?.split(';')[0]?.trim() || 'image/jpeg').toLowerCase();
+        return { mime, data: buffer.toString('base64') };
+    }
+    const buf = await fs.readFile(source);
+    const ext = extname(source).toLowerCase();
+    const mime = ext === '.png'
+        ? 'image/png'
+        : ext === '.webp'
+            ? 'image/webp'
+            : ext === '.gif'
+                ? 'image/gif'
+                : 'image/jpeg';
+    return { mime, data: buf.toString('base64') };
+}
+function buildRequestBody(args, model) {
+    const body = { model, prompt: args.prompt };
+    if (args.resolution)
+        body.resolution = args.resolution;
+    if (args.aspect_ratio)
+        body.aspect_ratio = args.aspect_ratio;
+    if (typeof args.duration === 'number')
+        body.duration = args.duration;
+    if (typeof args.seed === 'number')
+        body.seed = args.seed;
+    if (args.provider && typeof args.provider === 'object')
+        body.provider = args.provider;
+    return body;
+}
+async function attachFrameImages(args, body) {
+    const frameImages = [];
+    if (args.first_frame_image) {
+        const img = await prepareImageInput(args.first_frame_image);
+        if (img) {
+            frameImages.push({
+                frame_type: 'first_frame',
+                image: { url: `data:${img.mime};base64,${img.data}` },
+            });
+        }
+    }
+    if (args.last_frame_image) {
+        const img = await prepareImageInput(args.last_frame_image);
+        if (img) {
+            frameImages.push({
+                frame_type: 'last_frame',
+                image: { url: `data:${img.mime};base64,${img.data}` },
+            });
+        }
+    }
+    if (frameImages.length)
+        body.frame_images = frameImages;
+    if (args.reference_images?.length) {
+        const refs = [];
+        for (const src of args.reference_images) {
+            const img = await prepareImageInput(src);
+            if (img)
+                refs.push({ image: { url: `data:${img.mime};base64,${img.data}` } });
+        }
+        if (refs.length)
+            body.input_references = refs;
+    }
+}
+async function pollUntilTerminal(apiClient, envelope, opts) {
+    let attempt = 0;
+    let last = null;
+    const initialStatus = (envelope.status ?? 'pending');
+    await opts.onProgress?.({ status: initialStatus, attempt: 0, video_id: envelope.id });
+    while (Date.now() < opts.deadlineAt) {
+        attempt += 1;
+        await sleep(Math.min(opts.pollIntervalMs, Math.max(0, opts.deadlineAt - Date.now())));
+        try {
+            last = await apiClient.pollVideoJob(envelope.id);
+        }
+        catch (err) {
+            logger.warn('generate_video.poll_error', {
+                id: envelope.id,
+                err: err instanceof Error ? err.message : String(err),
+            });
+            continue; // transient; try again until deadline
+        }
+        await opts.onProgress?.({
+            status: last.status,
+            progress: typeof last.progress === 'number' ? last.progress : undefined,
+            attempt,
+            video_id: envelope.id,
+        });
+        if (last.status === 'completed')
+            return { kind: 'completed', status: last };
+        if (last.status === 'failed')
+            return { kind: 'failed', status: last };
+    }
+    return { kind: 'timeout', last };
+}
+function sleep(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((r) => setTimeout(r, ms));
+}
+function extractJobError(status) {
+    if (!status.error)
+        return 'Upstream marked the job failed.';
+    if (typeof status.error === 'string')
+        return status.error;
+    return status.error.message ?? 'Upstream marked the job failed.';
+}
+async function finalizeCompletedJob(apiClient, status, savePath) {
+    const url = status.unsigned_urls?.[0];
+    if (!url) {
+        throw new Error('Completed job returned no content URLs.');
+    }
+    const { buffer, contentType } = await apiClient.downloadVideoContent(status.id, 0, getMaxDownloadBytes());
+    const mime = (contentType?.split(';')[0]?.trim() || 'video/mp4').toLowerCase();
+    const ext = mime.includes('webm')
+        ? '.webm'
+        : mime.includes('mov')
+            ? '.mov'
+            : mime.includes('mpeg')
+                ? '.mpeg'
+                : '.mp4';
+    const baseMeta = {
+        video_id: status.id,
+        mime,
+        size_bytes: buffer.length,
+    };
+    if (status.usage)
+        baseMeta.usage = status.usage;
+    if (status.unsigned_urls)
+        baseMeta.unsigned_urls = status.unsigned_urls;
+    if (savePath) {
+        const finalPath = extname(savePath) === ext ? savePath : stripAndReplaceExt(savePath, ext);
+        await fs.writeFile(finalPath, buffer);
+        baseMeta.save_path = finalPath;
+        const summaryNote = finalPath !== savePath ? ` (detected ${mime}, saved as ${finalPath})` : '';
+        const content = [
+            { type: 'text', text: `Video saved to: ${finalPath}${summaryNote}` },
+        ];
+        if (buffer.length <= getMaxInlineBytes()) {
+            content.push({
+                type: 'video',
+                mimeType: mime,
+                data: buffer.toString('base64'),
+            });
+        }
+        return { content, _meta: baseMeta };
+    }
+    // No save_path — return inline if small enough, otherwise just the URL.
+    if (buffer.length <= getMaxInlineBytes()) {
+        return {
+            content: [
+                { type: 'text', text: `Video generated (${buffer.length} bytes, ${mime}).` },
+                { type: 'video', mimeType: mime, data: buffer.toString('base64') },
+            ],
+            _meta: baseMeta,
+        };
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Video generated (${buffer.length} bytes, ${mime}). Too large to inline; pass save_path to persist. URL: ${url}`,
+            },
+        ],
+        _meta: baseMeta,
+    };
+}
+function stripAndReplaceExt(p, newExt) {
+    const cur = extname(p);
+    const base = cur ? p.slice(0, -cur.length) : p;
+    return base + newExt;
+}
+export async function handleGenerateVideo(request, apiClient, progress) {
+    const args = request.params.arguments ?? {};
+    if (!args.prompt || !args.prompt.trim()) {
+        return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
+    }
+    // Fail-fast on unsafe save_path BEFORE spending credits on the job.
+    let safeSavePath = null;
+    if (args.save_path) {
+        try {
+            safeSavePath = await resolveSafeOutputPath(args.save_path);
+        }
+        catch (err) {
+            if (err instanceof UnsafeOutputPathError)
+                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+            return toolErrorFrom(ErrorCode.INTERNAL, err);
+        }
+    }
+    const model = args.model ||
+        process.env.OPENROUTER_DEFAULT_VIDEO_GEN_MODEL ||
+        FALLBACK_MODEL;
+    const body = buildRequestBody(args, model);
+    try {
+        await attachFrameImages(args, body);
+    }
+    catch (err) {
+        return toolErrorFrom(ErrorCode.UNSUPPORTED_FORMAT, err, 'Reference/frame image');
+    }
+    let envelope;
+    try {
+        logger.info('generate_video.submit', { model, keys: Object.keys(body) });
+        envelope = await apiClient.submitVideoJob(body);
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'generate_video.submit');
+    }
+    const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, args.poll_interval_ms ?? getDefaultPollInterval());
+    const maxWaitMs = Math.max(100, args.max_wait_ms ?? getDefaultMaxWait());
+    const deadlineAt = Date.now() + maxWaitMs;
+    const outcome = await pollUntilTerminal(apiClient, envelope, {
+        pollIntervalMs,
+        deadlineAt,
+        onProgress: progress,
+    });
+    if (outcome.kind === 'failed') {
+        return toolError(ErrorCode.JOB_FAILED, extractJobError(outcome.status), {
+            video_id: outcome.status.id,
+        });
+    }
+    if (outcome.kind === 'timeout') {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Video still generating after ${maxWaitMs}ms. Use get_video_status with video_id=${envelope.id} to resume.`,
+                },
+            ],
+            isError: false,
+            _meta: {
+                code: ErrorCode.JOB_STILL_RUNNING,
+                video_id: envelope.id,
+                polling_url: envelope.polling_url ?? `https://openrouter.ai/api/v1/videos/${envelope.id}`,
+                last_status: outcome.last?.status,
+            },
+        };
+    }
+    try {
+        const { content, _meta } = await finalizeCompletedJob(apiClient, outcome.status, safeSavePath);
+        return { content, _meta };
+    }
+    catch (err) {
+        if (err instanceof UnsafeOutputPathError) {
+            return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+        }
+        return toolErrorFrom(ErrorCode.UPSTREAM_HTTP, err, 'Download');
+    }
+}
+export async function handleGetVideoStatus(request, apiClient) {
+    const args = request.params.arguments ?? {};
+    const id = args.video_id?.trim();
+    if (!id)
+        return toolError(ErrorCode.INVALID_INPUT, 'video_id is required.');
+    // Pre-resolve save_path so the poll surfaces a fast error before hitting OpenRouter.
+    let safeSavePath = null;
+    if (args.save_path) {
+        try {
+            safeSavePath = await resolveSafeOutputPath(args.save_path);
+        }
+        catch (err) {
+            if (err instanceof UnsafeOutputPathError)
+                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+            return toolErrorFrom(ErrorCode.INTERNAL, err);
+        }
+    }
+    let status;
+    try {
+        status = await apiClient.pollVideoJob(id);
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'get_video_status.poll');
+    }
+    if (status.status === 'failed') {
+        return toolError(ErrorCode.JOB_FAILED, extractJobError(status), { video_id: id });
+    }
+    if (status.status === 'completed') {
+        try {
+            const { content, _meta } = await finalizeCompletedJob(apiClient, status, safeSavePath);
+            return { content, _meta };
+        }
+        catch (err) {
+            if (err instanceof UnsafeOutputPathError)
+                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+            return toolErrorFrom(ErrorCode.UPSTREAM_HTTP, err, 'Download');
+        }
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Video ${id} status: ${status.status}${typeof status.progress === 'number' ? ` (progress=${status.progress})` : ''}`,
+            },
+        ],
+        isError: false,
+        _meta: {
+            code: ErrorCode.JOB_STILL_RUNNING,
+            video_id: id,
+            last_status: status.status,
+            progress: status.progress,
+        },
+    };
+}
+export const _internals = { buildRequestBody, stripAndReplaceExt, extractJobError };

package/dist/tool-handlers/get-model-info.d.ts

@@ -6,16 +6,9 @@ export declare function handleGetModelInfo(request: {
             model: string;
         };
     };
-}, modelCache: ModelCache, apiClient?: OpenRouterAPIClient): Promise<{
+}, modelCache: ModelCache, apiClient?: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: string;
+        type: "text";
         text: string;
     }[];
-    isError: boolean;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
 }>;

package/dist/tool-handlers/get-model-info.js

@@ -1,14 +1,24 @@
+import { ErrorCode, toolError } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
 export async function handleGetModelInfo(request, modelCache, apiClient) {
-    const { model } = request.params.arguments;
-    if (!modelCache.isValid() && apiClient) {
-        modelCache.setModels(await apiClient.getModels());
+    const { model } = request.params.arguments ?? { model: '' };
+    if (!model || typeof model !== 'string') {
+        return toolError(ErrorCode.INVALID_INPUT, 'model is required.');
+    }
+    if (apiClient) {
+        try {
+            await modelCache.ensureFresh(() => apiClient.getModels());
+        }
+        catch (error) {
+            return classifyUpstreamError(error, 'get_model_info');
+        }
     }
     if (!modelCache.isValid()) {
-        return { content: [{ type: 'text', text: 'No model data available.' }], isError: true };
+        return toolError(ErrorCode.INTERNAL, 'No model data available.');
     }
     const info = modelCache.get(model);
     if (!info) {
-        return { content: [{ type: 'text', text: `Model '${model}' not found.` }], isError: true };
+        return toolError(ErrorCode.MODEL_NOT_FOUND, `Model '${model}' not found.`);
     }
     return { content: [{ type: 'text', text: JSON.stringify(info, null, 2) }] };
 }

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

@@ -6,5 +6,21 @@ export declare function getImageJpegQuality(): number;
 export declare function getMimeType(filePath: string): string;
 export declare function fetchHttpImage(urlString: string): Promise<Buffer>;
 export declare function fetchImage(source: string): Promise<Buffer>;
-export declare function optimizeImage(buffer: Buffer): Promise<string>;
+/**
+ * Sniff image MIME type from magic bytes. Used to label the output of a
+ * failed `sharp` optimization (where we return original bytes but don't
+ * know the source MIME yet) and HTTP image responses whose Content-Type
+ * header is missing or wrong.
+ */
+export declare function sniffImageMime(buffer: Buffer): string | null;
+/**
+ * Optimize an image buffer and return both the base64 payload AND the MIME
+ * type that matches that payload. Callers should NOT assume JPEG — the
+ * pipeline falls back to the original bytes (with its detected MIME) when
+ * sharp is unavailable or fails. This closes BUG-012.
+ */
+export declare function optimizeImage(buffer: Buffer): Promise<{
+    base64: string;
+    mime: string;
+}>;
 export declare function prepareImageUrl(source: string): Promise<string>;

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

@@ -1,6 +1,6 @@
 import path from 'path';
 import { promises as fs } from 'fs';
-import { readEnvInt, isBlockedIPv4 as _isBlockedIPv4, assertUrlSafeForFetch as _assertUrlSafeForFetch, fetchHttpResource, } from './fetch-utils.js';
+import { readEnvInt, isBlockedIPv4 as _isBlockedIPv4, assertUrlSafeForFetch as _assertUrlSafeForFetch, fetchHttpResource, parseBase64DataUrl, } from './fetch-utils.js';
 // Re-export for backward compatibility (tests import from image-utils)
 export const isBlockedIPv4 = _isBlockedIPv4;
 export const assertUrlSafeForFetch = _assertUrlSafeForFetch;
@@ -66,24 +66,71 @@ export async function fetchHttpImage(urlString) {
 }
 export async function fetchImage(source) {
     if (source.startsWith('data:')) {
-        const match = source.match(/^data:[^;]+;base64,(.+)$/);
-        if (!match)
+        const parsed = parseBase64DataUrl(source);
+        if (!parsed)
             throw new Error('Invalid data URL');
-        const b64 = match[1];
-        const approxBytes = Math.ceil((b64.length * 3) / 4);
+        const approxBytes = Math.ceil((parsed.base64.length * 3) / 4);
         if (approxBytes > getMaxDataUrlBytes())
             throw new Error('Data URL too large');
-        return Buffer.from(b64, 'base64');
+        return Buffer.from(parsed.base64, 'base64');
     }
     if (source.startsWith('http://') || source.startsWith('https://')) {
         return fetchHttpImage(source);
     }
     return fs.readFile(source);
 }
+/**
+ * Sniff image MIME type from magic bytes. Used to label the output of a
+ * failed `sharp` optimization (where we return original bytes but don't
+ * know the source MIME yet) and HTTP image responses whose Content-Type
+ * header is missing or wrong.
+ */
+export function sniffImageMime(buffer) {
+    if (buffer.length < 4)
+        return null;
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+        return 'image/png';
+    }
+    // JPEG: FF D8 FF
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    // GIF: 47 49 46 38
+    if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38) {
+        return 'image/gif';
+    }
+    // WebP: RIFF....WEBP
+    if (buffer.length >= 12 &&
+        buffer[0] === 0x52 &&
+        buffer[1] === 0x49 &&
+        buffer[2] === 0x46 &&
+        buffer[3] === 0x46 &&
+        buffer[8] === 0x57 &&
+        buffer[9] === 0x45 &&
+        buffer[10] === 0x42 &&
+        buffer[11] === 0x50) {
+        return 'image/webp';
+    }
+    // BMP
+    if (buffer[0] === 0x42 && buffer[1] === 0x4d)
+        return 'image/bmp';
+    return null;
+}
+/**
+ * Optimize an image buffer and return both the base64 payload AND the MIME
+ * type that matches that payload. Callers should NOT assume JPEG — the
+ * pipeline falls back to the original bytes (with its detected MIME) when
+ * sharp is unavailable or fails. This closes BUG-012.
+ */
 export async function optimizeImage(buffer) {
     const sharp = await loadSharp();
-    if (!sharp)
-        return buffer.toString('base64');
+    if (!sharp) {
+        return {
+            base64: buffer.toString('base64'),
+            mime: sniffImageMime(buffer) ?? 'application/octet-stream',
+        };
+    }
     const maxDim = getMaxImageDimension();
     const quality = getImageJpegQuality();
     try {
@@ -94,17 +141,23 @@ export async function optimizeImage(buffer) {
             pipeline = pipeline.resize(opts);
         }
         const out = await pipeline.jpeg({ quality }).toBuffer();
-        return out.toString('base64');
+        return { base64: out.toString('base64'), mime: 'image/jpeg' };
     }
     catch {
-        return buffer.toString('base64');
+        return {
+            base64: buffer.toString('base64'),
+            mime: sniffImageMime(buffer) ?? 'application/octet-stream',
+        };
     }
 }
 export async function prepareImageUrl(source) {
     if (source.startsWith('data:'))
         return source;
     const buffer = await fetchImage(source);
-    const base64 = await optimizeImage(buffer);
-    const mime = source.startsWith('http') ? 'image/jpeg' : getMimeType(source);
-    return `data:${mime};base64,${base64}`;
+    const { base64, mime } = await optimizeImage(buffer);
+    // When optimization succeeded, mime is 'image/jpeg'. When it failed, we
+    // use the sniffed mime. For local files we prefer the extension-derived
+    // mime (more specific) when optimization fell back.
+    const finalMime = mime === 'image/jpeg' || source.startsWith('http') ? mime : getMimeType(source);
+    return `data:${finalMime};base64,${base64}`;
 }

package/dist/tool-handlers/openrouter-errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared mapping from OpenRouter / OpenAI SDK error shapes to our closed
+ * `ErrorCode` enum. Every tool handler that calls the OpenAI client routes
+ * its `catch` block through `classifyUpstreamError` so error taxonomies
+ * don't drift.
+ */
+import { type ToolErrorResult } from '../errors.js';
+/**
+ * Classify a caught error from `openai.*` or a raw `fetch` to the
+ * OpenRouter REST API into the closed `ErrorCode` set.
+ *
+ * Matching strategy:
+ *   1. HTTP status first (when available).
+ *   2. Message heuristics for common OpenRouter strings (credits, ZDR,
+ *      "model does not exist", content policy, etc.).
+ *   3. Default to INTERNAL to avoid leaking raw shapes.
+ */
+export declare function classifyUpstreamError(err: unknown, _contextMessage?: string): ToolErrorResult;

package/dist/tool-handlers/openrouter-errors.js

@@ -0,0 +1,99 @@
+/**
+ * Shared mapping from OpenRouter / OpenAI SDK error shapes to our closed
+ * `ErrorCode` enum. Every tool handler that calls the OpenAI client routes
+ * its `catch` block through `classifyUpstreamError` so error taxonomies
+ * don't drift.
+ */
+import { ErrorCode, toolError } from '../errors.js';
+function extractStatus(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const s = err.status;
+    if (typeof s === 'number')
+        return s;
+    // openai-node sometimes puts the status in `code` for `APIError`.
+    const c = err.code;
+    if (typeof c === 'number')
+        return c;
+    if (typeof c === 'string' && /^\d{3}$/.test(c))
+        return parseInt(c, 10);
+    // Fall back: parse the message for `HTTP NNN` — our internal client wraps
+    // fetch failures as `POST /videos failed: HTTP 400 — <detail>`.
+    if (err instanceof Error) {
+        const m = err.message.match(/\bHTTP (\d{3})\b/);
+        if (m)
+            return parseInt(m[1], 10);
+    }
+    return undefined;
+}
+function extractMessage(err) {
+    if (err instanceof Error) {
+        const nested = err.error;
+        if (nested && typeof nested === 'object' && typeof nested.message === 'string') {
+            return `${err.message} — ${nested.message}`;
+        }
+        if (typeof nested === 'string')
+            return `${err.message} — ${nested}`;
+        return err.message;
+    }
+    if (typeof err === 'string')
+        return err;
+    return 'unknown error';
+}
+/**
+ * Classify a caught error from `openai.*` or a raw `fetch` to the
+ * OpenRouter REST API into the closed `ErrorCode` set.
+ *
+ * Matching strategy:
+ *   1. HTTP status first (when available).
+ *   2. Message heuristics for common OpenRouter strings (credits, ZDR,
+ *      "model does not exist", content policy, etc.).
+ *   3. Default to INTERNAL to avoid leaking raw shapes.
+ */
+export function classifyUpstreamError(err, _contextMessage) {
+    const msg = extractMessage(err);
+    const status = extractStatus(err);
+    const lower = msg.toLowerCase();
+    const fullMsg = msg;
+    // Explicit credit / balance signals.
+    if (lower.includes('insufficient balance') ||
+        lower.includes('insufficient credits') ||
+        lower.includes('requires more credits') ||
+        lower.includes('requires at least') ||
+        status === 402) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'credits' });
+    }
+    // Zero Data Retention.
+    if (lower.includes('zdr') || lower.includes('zero data retention')) {
+        return toolError(ErrorCode.ZDR_INCOMPATIBLE, fullMsg, { status });
+    }
+    // Model lookup failures.
+    if (lower.includes('model') &&
+        (lower.includes('does not exist') || lower.includes('not found') || lower.includes('invalid model'))) {
+        return toolError(ErrorCode.MODEL_NOT_FOUND, fullMsg, { status });
+    }
+    // Content policy / moderation — surface as UPSTREAM_REFUSED so callers can distinguish from 5xx.
+    if (lower.includes('content policy') || lower.includes('moderation') || lower.includes('refused')) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' });
+    }
+    // Rate-limit specific.
+    if (status === 429 || lower.includes('rate limit')) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' });
+    }
+    // Timeouts (AbortError from `AbortSignal.timeout`).
+    if (lower.includes('timed out') ||
+        lower.includes('timeout') ||
+        lower.includes('aborted') ||
+        (err instanceof Error && err.name === 'AbortError')) {
+        return toolError(ErrorCode.UPSTREAM_TIMEOUT, fullMsg, { status });
+    }
+    // Anything in the 4xx band that isn't covered above — user supplied a bad request.
+    if (typeof status === 'number' && status >= 400 && status < 500) {
+        return toolError(ErrorCode.INVALID_INPUT, fullMsg, { status });
+    }
+    // 5xx / network errors.
+    if (typeof status === 'number' && status >= 500) {
+        return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg, { status });
+    }
+    return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg);
+}

package/dist/tool-handlers/path-safety.d.ts

@@ -0,0 +1,11 @@
+export declare class UnsafeOutputPathError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve and validate a caller-supplied output path. Creates the parent
+ * directory if needed. Returns the absolute path that is safe to write.
+ *
+ * Throws `UnsafeOutputPathError` when the resolved path escapes the root
+ * (traversal attempt) and the sandbox is enabled.
+ */
+export declare function resolveSafeOutputPath(savePath: string): Promise<string>;