@stabgan/openrouter-mcp-multimodal 4.6.0 → 4.6.2

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

@@ -3,7 +3,8 @@ import { extname } from 'node:path';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
-import { resolveSafeOutputPath, resolveSafeInputPath, UnsafeOutputPathError, } from './path-safety.js';
+import { resolveOptionalOutputPath, isToolErrorResult, UnsafeOutputPathError, } from './path-safety.js';
+import { resolveImageBase64 } from './image-source.js';
 import { readEnvInt } from './fetch-utils.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 const FALLBACK_MODEL = 'google/veo-3.1';
@@ -26,10 +27,7 @@ const SORA_ALTERNATIVES = [
     'bytedance/seedance-2.0-fast (fast turnaround)',
     'alibaba/wan-2.7 (good for artistic styles)',
 ];
-/**
- * Check if the model is a deprecated Sora model and return a warning string,
- * or null if no deprecation applies.
- */
+/** Return a deprecation warning for Sora models, or null. */
 function checkSoraDeprecation(model) {
     const normalized = model.toLowerCase().trim();
     if (!SORA_DEPRECATED_MODELS.has(normalized) && !normalized.startsWith('openai/sora')) {
@@ -49,57 +47,19 @@ 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) {
+async function imageFrameEntry(source, frameType) {
     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') };
-    }
-    // Local file: sandbox via path-safety's resolveSafeInputPath so
-    // generate_video's first_frame_image / last_frame_image /
-    // reference_images fields enforce the same OPENROUTER_INPUT_DIR
-    // / OPENROUTER_OUTPUT_DIR / cwd scope that generate_image's
-    // input_images already uses. Callers can still bypass with
-    // OPENROUTER_ALLOW_UNSAFE_PATHS=1 for legacy scripts.
-    const abs = await resolveSafeInputPath(source);
-    const buf = await fs.readFile(abs);
-    const ext = extname(abs).toLowerCase();
-    const mime = ext === '.png'
-        ? 'image/png'
-        : ext === '.webp'
-            ? 'image/webp'
-            : ext === '.gif'
-                ? 'image/gif'
-                : 'image/jpeg';
-    return { mime, data: buf.toString('base64') };
+    const img = await resolveImageBase64(source);
+    const entry = {
+        type: 'image_url',
+        image_url: { url: `data:${img.mime};base64,${img.data}` },
+    };
+    if (frameType)
+        entry.frame_type = frameType;
+    return { kind: 'frame', entry };
 }
 function buildRequestBody(args, model) {
     const body = { model, prompt: args.prompt };
@@ -118,28 +78,10 @@ function buildRequestBody(args, model) {
 async function attachFrameImages(args, body) {
     const frameTasks = [];
     if (args.first_frame_image) {
-        frameTasks.push(prepareImageInput(args.first_frame_image).then((img) => img
-            ? {
-                kind: 'frame',
-                entry: {
-                    type: 'image_url',
-                    image_url: { url: `data:${img.mime};base64,${img.data}` },
-                    frame_type: 'first_frame',
-                },
-            }
-            : null));
+        frameTasks.push(imageFrameEntry(args.first_frame_image, 'first_frame'));
     }
     if (args.last_frame_image) {
-        frameTasks.push(prepareImageInput(args.last_frame_image).then((img) => img
-            ? {
-                kind: 'frame',
-                entry: {
-                    type: 'image_url',
-                    image_url: { url: `data:${img.mime};base64,${img.data}` },
-                    frame_type: 'last_frame',
-                },
-            }
-            : null));
+        frameTasks.push(imageFrameEntry(args.last_frame_image, 'last_frame'));
     }
     const frameResults = await Promise.all(frameTasks);
     const frameImages = frameResults
@@ -148,10 +90,8 @@ async function attachFrameImages(args, body) {
     if (frameImages.length)
         body.frame_images = frameImages;
     if (args.reference_images?.length) {
-        const refResults = await Promise.all(args.reference_images.map((src) => prepareImageInput(src)));
-        const refs = refResults
-            .filter((img) => img !== null)
-            .map((img) => ({
+        const refResults = await Promise.all(args.reference_images.map((src) => resolveImageBase64(src)));
+        const refs = refResults.map((img) => ({
             type: 'image_url',
             image_url: { url: `data:${img.mime};base64,${img.data}` },
         }));
@@ -243,7 +183,6 @@ async function finalizeCompletedJob(apiClient, status, savePath) {
         }
         return { content, _meta: baseMeta };
     }
-    // No save_path — return inline if small enough, otherwise just the URL.
     if (buffer.length <= getMaxInlineBytes()) {
         return {
             content: [
@@ -274,12 +213,7 @@ export async function handleGenerateVideo(request, apiClient, progress) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
     const model = args.model || process.env.OPENROUTER_DEFAULT_VIDEO_GEN_MODEL || FALLBACK_MODEL;
-    // Sora deprecation warning — OpenAI is removing the Videos API and all
-    // Sora 2 model aliases on September 24, 2026. Warn and suggest alternatives.
     const deprecationWarning = checkSoraDeprecation(model);
-    // Audit entry — video is the most expensive tool we have. Always log
-    // model, resolution, duration, and a safe prompt preview so unintended
-    // spend can be traced.
     logger.audit('generate_video.start', {
         model,
         prompt_preview: args.prompt.slice(0, 80),
@@ -291,25 +225,15 @@ export async function handleGenerateVideo(request, apiClient, progress) {
         reference_images: args.reference_images?.length ?? 0,
         save_path: args.save_path ? 'provided' : 'none',
     });
-    // 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 savePathResult = await resolveOptionalOutputPath(args.save_path);
+    if (isToolErrorResult(savePathResult))
+        return savePathResult;
+    const safeSavePath = savePathResult.path;
     const body = buildRequestBody(args, model);
     try {
         await attachFrameImages(args, body);
     }
     catch (err) {
-        // Sandbox violation → UNSAFE_PATH; all other decode failures stay
-        // as UNSUPPORTED_FORMAT (couldn't read, invalid data URL, etc.).
         if (err instanceof UnsafeOutputPathError) {
             return toolErrorFrom(ErrorCode.UNSAFE_PATH, err, 'Reference/frame image');
         }
@@ -359,7 +283,6 @@ export async function handleGenerateVideo(request, apiClient, progress) {
     }
     try {
         const { content, _meta } = await finalizeCompletedJob(apiClient, outcome.status, safeSavePath);
-        // Prepend deprecation warning if applicable
         if (deprecationWarning) {
             content.unshift({ type: 'text', text: deprecationWarning });
             _meta.deprecated_model = true;
@@ -378,18 +301,10 @@ export async function handleGetVideoStatus(request, apiClient) {
     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);
-        }
-    }
+    const savePathResult = await resolveOptionalOutputPath(args.save_path);
+    if (isToolErrorResult(savePathResult))
+        return savePathResult;
+    const safeSavePath = savePathResult.path;
     let status;
     try {
         status = await apiClient.pollVideoJob(id);

package/dist/tool-handlers/health-check.d.ts

@@ -1,14 +1,6 @@
 import type { OpenRouterAPIClient } from '../openrouter-api.js';
 import { ModelCache } from '../model-cache.js';
-/**
- * Lightweight liveness probe. Runs the following checks:
- *  - Hit `/models` via the API client (indirectly validates API key +
- *    OpenRouter reachability)
- *  - Read cached model count
- *  - Report server + protocol versions
- *
- * Returns `{ ok, ... }` so ops can use it as a readiness signal.
- */
+/** Liveness probe — validates API key, reachability, and cached model count. */
 export declare function handleHealthCheck(_request: {
     params: {
         arguments: Record<string, unknown>;

package/dist/tool-handlers/health-check.js

@@ -1,14 +1,6 @@
 import { SERVER_VERSION, MCP_PROTOCOL_VERSION } from '../version.js';
 import { buildStructuredResult } from './structured-output.js';
-/**
- * Lightweight liveness probe. Runs the following checks:
- *  - Hit `/models` via the API client (indirectly validates API key +
- *    OpenRouter reachability)
- *  - Read cached model count
- *  - Report server + protocol versions
- *
- * Returns `{ ok, ... }` so ops can use it as a readiness signal.
- */
+/** Liveness probe — validates API key, reachability, and cached model count. */
 export async function handleHealthCheck(_request, apiClient, modelCache) {
     let apiKeyValid = false;
     let errorMessage;
@@ -20,9 +12,6 @@ export async function handleHealthCheck(_request, apiClient, modelCache) {
         errorMessage = err instanceof Error ? err.message : String(err);
     }
     const modelsCached = modelCache.isValid() ? modelCache.size() : 0;
-    // `ok` means the API was reachable and the key was accepted. An empty
-    // catalog counts as success (the API just returned no models) — callers
-    // branch on `models_cached` if they care about the count.
     const ok = apiKeyValid;
     return buildStructuredResult({
         ok,

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

@@ -0,0 +1,14 @@
+/** Resolve an image reference to a URL (data URL or http(s) passthrough). */
+export declare function resolveImageUrl(ref: string): Promise<string>;
+/** Resolve an image reference to base64 payload + mime (for video frame uploads). */
+export declare function resolveImageBase64(source: string): Promise<{
+    mime: string;
+    data: string;
+}>;
+/** OpenRouter dedicated-image API reference shape. */
+export declare function toOpenRouterImageReference(source: string): Promise<{
+    type: string;
+    image_url: {
+        url: string;
+    };
+}>;

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

@@ -0,0 +1,23 @@
+import { fetchImageWithMime } from './image-utils.js';
+/** Resolve an image reference to a URL (data URL or http(s) passthrough). */
+export async function resolveImageUrl(ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        throw new Error('empty image reference');
+    if (trimmed.startsWith('data:') || /^https?:\/\//i.test(trimmed))
+        return trimmed;
+    const { buffer, mime } = await fetchImageWithMime(trimmed);
+    return `data:${mime};base64,${buffer.toString('base64')}`;
+}
+/** Resolve an image reference to base64 payload + mime (for video frame uploads). */
+export async function resolveImageBase64(source) {
+    if (!source.trim())
+        throw new Error('empty image source');
+    const { buffer, mime } = await fetchImageWithMime(source);
+    return { mime, data: buffer.toString('base64') };
+}
+/** OpenRouter dedicated-image API reference shape. */
+export async function toOpenRouterImageReference(source) {
+    const url = await resolveImageUrl(source);
+    return { type: 'image_url', image_url: { url } };
+}

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

@@ -24,4 +24,9 @@ export declare function optimizeImage(buffer: Buffer): Promise<{
     base64: string;
     mime: string;
 }>;
+/** Load image bytes with a MIME type (respects OPENROUTER_IMAGE_* fetch limits). */
+export declare function fetchImageWithMime(source: string): Promise<{
+    buffer: Buffer;
+    mime: string;
+}>;
 export declare function prepareImageUrl(source: string): Promise<string>;

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

@@ -160,6 +160,29 @@ export async function optimizeImage(buffer) {
         };
     }
 }
+/** Load image bytes with a MIME type (respects OPENROUTER_IMAGE_* fetch limits). */
+export async function fetchImageWithMime(source) {
+    if (source.startsWith('data:')) {
+        const parsed = parseBase64DataUrl(source);
+        if (!parsed)
+            throw new Error('Invalid data URL');
+        return { buffer: Buffer.from(parsed.base64, 'base64'), mime: parsed.mediaType };
+    }
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        const { buffer, contentType } = await fetchHttpResource(source, {
+            timeoutMs: getFetchTimeoutMs(),
+            maxBytes: getMaxDownloadBytes(),
+            maxRedirects: getMaxRedirects(),
+        });
+        const mime = (contentType?.split(';')[0]?.trim() ||
+            sniffImageMime(buffer) ||
+            'image/jpeg').toLowerCase();
+        return { buffer, mime };
+    }
+    const safe = await resolveSafeInputPath(source);
+    const buffer = await fs.readFile(safe);
+    return { buffer, mime: getMimeType(safe) };
+}
 export async function prepareImageUrl(source) {
     if (source.startsWith('data:'))
         return source;

package/dist/tool-handlers/openai-withresponse.d.ts

@@ -1,13 +1,4 @@
-/**
- * Helper for calling `openai.chat.completions.create()` and getting back
- * BOTH the typed body and the raw fetch `Response` (so we can read the
- * X-OpenRouter-Cache-* headers).
- *
- * The real openai SDK returns an `APIPromise` that exposes `.withResponse()`.
- * Vitest tests typically stub `create()` to return a plain `ChatCompletion`
- * object. This helper handles both cases so tests don't need to mock the
- * chainable.
- */
+/** Call `openai.chat.completions.create()` and return body + raw Response headers. */
 import type { ChatCompletion } from 'openai/resources/chat/completions.js';
 export interface ChatCompletionWithHeaders {
     data: ChatCompletion;

package/dist/tool-handlers/openai-withresponse.js

@@ -1,16 +1,9 @@
 export async function awaitCompletionWithHeaders(call) {
-    // Prefer the APIPromise .withResponse() chainable, which returns
-    // `{ data, response }` — but only if the object looks like an
-    // APIPromise. Mocks that return plain objects get unwrapped via a
-    // direct await.
     const maybeChainable = call;
     if (typeof maybeChainable?.withResponse === 'function') {
         const { data, response } = await maybeChainable.withResponse();
         return { data, response };
     }
-    // Fallback: await the value directly. Covers both test mocks
-    // (which return a plain ChatCompletion via vi.fn().mockResolvedValue())
-    // and any exotic SDK shape we don't recognize.
     const data = (await call);
     return { data, response: undefined };
 }

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

@@ -1,22 +1,6 @@
 /**
- * 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.
+ * Map OpenRouter / OpenAI SDK errors to our closed `ErrorCode` enum.
  */
 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.
- *
- * When the error carries a `Retry-After` header (on 429 / 503) we populate
- * `_meta.retry_after_seconds` so agents can back off intelligently. We
- * also attach canonical `suggestions[]` for common cases.
- */
+/** Classify upstream errors into the closed `ErrorCode` set. */
 export declare function classifyUpstreamError(err: unknown, contextMessage?: string): ToolErrorResult;

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

@@ -1,8 +1,5 @@
 /**
- * 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.
+ * Map OpenRouter / OpenAI SDK errors to our closed `ErrorCode` enum.
  */
 import { ErrorCode, toolError } from '../errors.js';
 function extractRetryAfterSeconds(err) {
@@ -24,8 +21,6 @@ function extractRetryAfterSeconds(err) {
     const n = Number(raw);
     if (Number.isFinite(n) && n >= 0)
         return n;
-    // Retry-After can also be an HTTP-date; return undefined for those (caller
-    // can still retry on its own backoff schedule).
     return undefined;
 }
 function extractStatus(err) {
@@ -34,14 +29,11 @@ function extractStatus(err) {
     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)
@@ -63,30 +55,13 @@ function extractMessage(err) {
         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.
- *
- * When the error carries a `Retry-After` header (on 429 / 503) we populate
- * `_meta.retry_after_seconds` so agents can back off intelligently. We
- * also attach canonical `suggestions[]` for common cases.
- */
+/** Classify upstream errors into the closed `ErrorCode` set. */
 export function classifyUpstreamError(err, contextMessage) {
     const rawMsg = extractMessage(err);
     const status = extractStatus(err);
     const lower = rawMsg.toLowerCase();
-    // Prefix every user-visible message with the handler context when the
-    // caller supplied one (e.g. `rerank`, `generate_video.submit`). Makes
-    // server-side triage possible without digging through logs.
     const fullMsg = contextMessage ? `${contextMessage}: ${rawMsg}` : rawMsg;
     const retryAfterSeconds = extractRetryAfterSeconds(err);
-    // Explicit credit / balance signals.
     if (lower.includes('insufficient balance') ||
         lower.includes('insufficient credits') ||
         lower.includes('requires more credits') ||
@@ -99,7 +74,6 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    // Zero Data Retention.
     if (lower.includes('zdr') || lower.includes('zero data retention')) {
         return toolError(ErrorCode.ZDR_INCOMPATIBLE, fullMsg, { status }, {
             suggestions: [
@@ -108,7 +82,6 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    // Model lookup failures.
     if (lower.includes('model') &&
         (lower.includes('does not exist') ||
             lower.includes('not found') ||
@@ -120,7 +93,6 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    // Content policy / moderation — surface as UPSTREAM_REFUSED so callers can distinguish from 5xx.
     if (lower.includes('content policy') ||
         lower.includes('moderation') ||
         lower.includes('refused')) {
@@ -128,7 +100,6 @@ export function classifyUpstreamError(err, contextMessage) {
             suggestions: ['Rephrase the prompt', 'Try a different provider via provider.order'],
         });
     }
-    // Rate-limit specific.
     if (status === 429 || lower.includes('rate limit')) {
         return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' }, {
             suggestions: [
@@ -140,7 +111,6 @@ export function classifyUpstreamError(err, contextMessage) {
             retry_after_seconds: retryAfterSeconds,
         });
     }
-    // Timeouts (AbortError from `AbortSignal.timeout`).
     if (lower.includes('timed out') ||
         lower.includes('timeout') ||
         lower.includes('aborted') ||
@@ -149,11 +119,9 @@ export function classifyUpstreamError(err, contextMessage) {
             suggestions: ['Retry', 'Raise max_wait_ms or max_tokens'],
         });
     }
-    // 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 }, {
             suggestions: ['Retry after a brief delay', 'Check https://status.openrouter.ai'],

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

@@ -1,22 +1,17 @@
+import { type ToolErrorResult } from '../errors.js';
 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.
+ * Resolve and validate a caller-supplied output path.
+ * Throws `UnsafeOutputPathError` on traversal attempts.
  */
 export declare function resolveSafeOutputPath(savePath: string): Promise<string>;
-/**
- * Resolve and validate a caller-supplied INPUT path. Unlike
- * `resolveSafeOutputPath`, this never creates directories — it only
- * confirms the path lives inside the input sandbox and returns the
- * absolute path the caller can `fs.readFile` from.
- *
- * Accepts the same `OPENROUTER_ALLOW_UNSAFE_PATHS=1` legacy bypass.
- * Throws `UnsafeOutputPathError` on traversal attempts (re-used type so
- * handlers map errors uniformly to `ErrorCode.UNSAFE_PATH`).
- */
+/** Resolve and validate a caller-supplied input path (read-only, no mkdir). */
 export declare function resolveSafeInputPath(inputPath: string): Promise<string>;
+export type OptionalOutputPath = {
+    path: string | null;
+};
+export declare function isToolErrorResult(result: OptionalOutputPath | ToolErrorResult): result is ToolErrorResult;
+/** Resolve optional save_path; returns a tool error result on sandbox violation. */
+export declare function resolveOptionalOutputPath(savePath: string | undefined): Promise<OptionalOutputPath | ToolErrorResult>;