@stabgan/openrouter-mcp-multimodal 4.6.2 → 4.8.0

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

@@ -1,4 +1,3 @@
-import { promises as fs } from 'node:fs';
 import { extname } from 'node:path';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
@@ -7,11 +6,12 @@ import { resolveOptionalOutputPath, isToolErrorResult, UnsafeOutputPathError, }
 import { resolveImageBase64 } from './image-source.js';
 import { readEnvInt } from './fetch-utils.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildBinaryToolResult } from './tool-result-payload.js';
+import { replaceExtension, writeOutputFile } from './path-utils.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;
 /** Models deprecated by OpenAI — removal date: 2026-09-24. */
 const SORA_DEPRECATED_MODELS = new Set([
     'openai/sora-2',
@@ -37,8 +37,22 @@ function checkSoraDeprecation(model) {
         `Your request will still be attempted, but may fail. Recommended alternatives:\n` +
         SORA_ALTERNATIVES.map((a) => `  • ${a}`).join('\n'));
 }
-function getMaxInlineBytes() {
-    return readEnvInt('OPENROUTER_VIDEO_INLINE_MAX_BYTES', INLINE_RETURN_CEILING_BYTES, 4096);
+function isTerminalFailureStatus(status) {
+    const normalized = status.toLowerCase();
+    return normalized === 'failed' || normalized === 'cancelled' || normalized === 'canceled';
+}
+async function invokeProgressHook(hook, update) {
+    if (!hook)
+        return;
+    try {
+        await hook(update);
+    }
+    catch (err) {
+        logger.warn('generate_video.progress_hook_error', {
+            video_id: update.video_id,
+            err: err instanceof Error ? err.message : String(err),
+        });
+    }
 }
 function getDefaultPollInterval() {
     return readEnvInt('OPENROUTER_VIDEO_POLL_INTERVAL_MS', DEFAULT_POLL_INTERVAL_MS, MIN_POLL_INTERVAL_MS);
@@ -103,7 +117,11 @@ 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 });
+    await invokeProgressHook(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())));
@@ -115,9 +133,9 @@ async function pollUntilTerminal(apiClient, envelope, opts) {
                 id: envelope.id,
                 err: err instanceof Error ? err.message : String(err),
             });
-            continue; // transient; try again until deadline
+            continue;
         }
-        await opts.onProgress?.({
+        await invokeProgressHook(opts.onProgress, {
             status: last.status,
             progress: typeof last.progress === 'number' ? last.progress : undefined,
             attempt,
@@ -125,7 +143,7 @@ async function pollUntilTerminal(apiClient, envelope, opts) {
         });
         if (last.status === 'completed')
             return { kind: 'completed', status: last };
-        if (last.status === 'failed')
+        if (isTerminalFailureStatus(last.status))
             return { kind: 'failed', status: last };
     }
     return { kind: 'timeout', last };
@@ -148,14 +166,17 @@ async function finalizeCompletedJob(apiClient, status, savePath) {
         throw new Error('Completed job returned no content URLs.');
     }
     const { buffer, contentType } = await apiClient.downloadVideoContent(status.id, 0, getMaxDownloadBytes());
+    if (buffer.length === 0) {
+        throw new Error('Completed job returned empty video content.');
+    }
     const mime = (contentType?.split(';')[0]?.trim() || 'video/mp4').toLowerCase();
     const ext = mime.includes('webm')
-        ? '.webm'
+        ? 'webm'
         : mime.includes('mov')
-            ? '.mov'
+            ? 'mov'
             : mime.includes('mpeg')
-                ? '.mpeg'
-                : '.mp4';
+                ? 'mpeg'
+                : 'mp4';
     const baseMeta = {
         server_version: SERVER_VERSION,
         video_id: status.id,
@@ -167,45 +188,20 @@ async function finalizeCompletedJob(apiClient, status, savePath) {
     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);
+        const finalPath = extname(savePath) === `.${ext}` ? savePath : replaceExtension(savePath, ext);
+        await writeOutputFile(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 };
-    }
-    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 buildBinaryToolResult({ kind: 'video', buffer, mimeType: mime }, {
+            savedPath: finalPath,
+            summaryText: `Video saved to: ${finalPath}${summaryNote}`,
+            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;
+    return buildBinaryToolResult({ kind: 'video', buffer, mimeType: mime }, {
+        remoteUrl: url,
+        meta: baseMeta,
+    });
 }
 export async function handleGenerateVideo(request, apiClient, progress) {
     const args = request.params.arguments ?? {};
@@ -312,7 +308,7 @@ export async function handleGetVideoStatus(request, apiClient) {
     catch (err) {
         return classifyUpstreamError(err, 'get_video_status.poll');
     }
-    if (status.status === 'failed') {
+    if (status.status === 'failed' || isTerminalFailureStatus(status.status)) {
         return toolError(ErrorCode.JOB_FAILED, extractJobError(status), { video_id: id });
     }
     if (status.status === 'completed') {
@@ -368,4 +364,9 @@ export async function handleGenerateVideoFromImage(request, apiClient, progress)
         },
     }, apiClient, progress);
 }
-export const _internals = { buildRequestBody, stripAndReplaceExt, extractJobError };
+export const _internals = {
+    buildRequestBody,
+    extractJobError,
+    isTerminalFailureStatus,
+    invokeProgressHook,
+};

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

@@ -17,7 +17,7 @@ export async function handleGetModelInfo(request, modelCache, apiClient) {
     if (!modelCache.isValid()) {
         return toolError(ErrorCode.INTERNAL, 'No model data available.');
     }
-    const info = modelCache.get(model);
+    const info = modelCache.lookup(model);
     if (!info) {
         return toolError(ErrorCode.MODEL_NOT_FOUND, `Model '${model}' not found.`);
     }

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

@@ -1,24 +1,48 @@
 import { SERVER_VERSION, MCP_PROTOCOL_VERSION } from '../version.js';
 import { buildStructuredResult } from './structured-output.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
 /** Liveness probe — validates API key, reachability, and cached model count. */
 export async function handleHealthCheck(_request, apiClient, modelCache) {
-    let apiKeyValid = false;
-    let errorMessage;
     try {
-        await modelCache.ensureFresh(() => apiClient.getModels());
-        apiKeyValid = true;
+        let apiKeyValid = false;
+        let errorMessage;
+        let errorMeta = {};
+        try {
+            await modelCache.ensureFresh(() => apiClient.getModels());
+            apiKeyValid = true;
+        }
+        catch (err) {
+            const classified = classifyUpstreamError(err, 'health_check');
+            errorMessage = classified.content[0]?.text;
+            errorMeta = {
+                code: classified._meta.code,
+                ...(classified._meta.suggestions ? { suggestions: classified._meta.suggestions } : {}),
+                ...(classified._meta.details ? { details: classified._meta.details } : {}),
+            };
+        }
+        const modelsCached = modelCache.isValid() ? modelCache.size() : 0;
+        const ok = apiKeyValid;
+        return buildStructuredResult({
+            ok,
+            server_version: SERVER_VERSION,
+            protocol_version: MCP_PROTOCOL_VERSION,
+            api_key_valid: apiKeyValid,
+            models_cached: modelsCached,
+            ...(errorMessage ? { error: errorMessage } : {}),
+        }, errorMeta);
     }
     catch (err) {
-        errorMessage = err instanceof Error ? err.message : String(err);
+        const classified = classifyUpstreamError(err, 'health_check');
+        return buildStructuredResult({
+            ok: false,
+            server_version: SERVER_VERSION,
+            protocol_version: MCP_PROTOCOL_VERSION,
+            api_key_valid: false,
+            models_cached: 0,
+            error: classified.content[0]?.text,
+        }, {
+            code: classified._meta.code,
+            ...(classified._meta.suggestions ? { suggestions: classified._meta.suggestions } : {}),
+        });
     }
-    const modelsCached = modelCache.isValid() ? modelCache.size() : 0;
-    const ok = apiKeyValid;
-    return buildStructuredResult({
-        ok,
-        server_version: SERVER_VERSION,
-        protocol_version: MCP_PROTOCOL_VERSION,
-        api_key_valid: apiKeyValid,
-        models_cached: modelsCached,
-        ...(errorMessage ? { error: errorMessage } : {}),
-    });
 }

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

@@ -1,5 +1,5 @@
-import path from 'path';
-import { promises as fs } from 'fs';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
 import { readEnvInt, isBlockedIPv4 as _isBlockedIPv4, assertUrlSafeForFetch as _assertUrlSafeForFetch, fetchHttpResource, parseBase64DataUrl, } from './fetch-utils.js';
 import { resolveSafeInputPath } from './path-safety.js';
 // Re-export for backward compatibility (tests import from image-utils)

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

@@ -2,5 +2,7 @@
  * Map OpenRouter / OpenAI SDK errors to our closed `ErrorCode` enum.
  */
 import { type ToolErrorResult } from '../errors.js';
+/** Strip bearer tokens and OpenRouter key material from user-visible messages. */
+export declare function sanitizeErrorMessage(msg: string): string;
 /** Classify upstream errors into the closed `ErrorCode` set. */
 export declare function classifyUpstreamError(err: unknown, contextMessage?: string): ToolErrorResult;

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

@@ -2,6 +2,17 @@
  * Map OpenRouter / OpenAI SDK errors to our closed `ErrorCode` enum.
  */
 import { ErrorCode, toolError } from '../errors.js';
+const AUTH_SUGGESTIONS = [
+    'Verify OPENROUTER_API_KEY is set and matches https://openrouter.ai/keys',
+    'Ensure the key has not been revoked or expired',
+];
+/** Strip bearer tokens and OpenRouter key material from user-visible messages. */
+export function sanitizeErrorMessage(msg) {
+    return msg
+        .replace(/Bearer\s+\S+/gi, 'Bearer [REDACTED]')
+        .replace(/sk-or-v\d+-[\w-]+/gi, '[REDACTED]')
+        .replace(/Authorization:\s*\S+/gi, 'Authorization: [REDACTED]');
+}
 function extractRetryAfterSeconds(err) {
     if (typeof err !== 'object' || err === null)
         return undefined;
@@ -18,22 +29,29 @@ function extractRetryAfterSeconds(err) {
     const raw = getHeader(e.headers) ?? getHeader(e.response?.headers);
     if (!raw)
         return undefined;
-    const n = Number(raw);
-    if (Number.isFinite(n) && n >= 0)
-        return n;
+    const asInt = parseInt(raw, 10);
+    if (Number.isFinite(asInt) && asInt >= 0)
+        return asInt;
+    const asDate = Date.parse(raw);
+    if (Number.isFinite(asDate)) {
+        const deltaSec = Math.ceil((asDate - Date.now()) / 1000);
+        return deltaSec > 0 ? deltaSec : 0;
+    }
     return undefined;
 }
 function extractStatus(err) {
     if (typeof err !== 'object' || err === null)
         return undefined;
-    const s = err.status;
-    if (typeof s === 'number')
-        return s;
-    const c = err.code;
-    if (typeof c === 'number')
-        return c;
-    if (typeof c === 'string' && /^\d{3}$/.test(c))
-        return parseInt(c, 10);
+    const e = err;
+    if (typeof e.status === 'number')
+        return e.status;
+    if (typeof e.code === 'number')
+        return e.code;
+    if (typeof e.code === 'string' && /^\d{3}$/.test(e.code))
+        return parseInt(e.code, 10);
+    const nested = e.error;
+    if (nested && typeof nested === 'object' && typeof nested.code === 'number')
+        return nested.code;
     if (err instanceof Error) {
         const m = err.message.match(/\bHTTP (\d{3})\b/);
         if (m)
@@ -41,27 +59,116 @@ function extractStatus(err) {
     }
     return undefined;
 }
+function extractNestedError(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const nested = err.error;
+    if (!nested)
+        return undefined;
+    return nested;
+}
 function extractMessage(err) {
+    let msg;
     if (err instanceof Error) {
-        const nested = err.error;
+        const nested = extractNestedError(err);
         if (nested && typeof nested === 'object' && typeof nested.message === 'string') {
-            return `${err.message} — ${nested.message}`;
+            msg = `${err.message} — ${nested.message}`;
+        }
+        else if (typeof nested === 'string') {
+            msg = `${err.message} — ${nested}`;
         }
-        if (typeof nested === 'string')
-            return `${err.message} — ${nested}`;
-        return err.message;
+        else {
+            msg = err.message;
+        }
+    }
+    else if (typeof err === 'string') {
+        msg = err;
     }
-    if (typeof err === 'string')
-        return err;
-    return 'unknown error';
+    else if (typeof err === 'object' && err !== null) {
+        const e = err;
+        if (typeof e.message === 'string') {
+            msg = e.message;
+        }
+        else {
+            const nested = extractNestedError(err);
+            if (nested && typeof nested === 'object' && typeof nested.message === 'string') {
+                msg = nested.message;
+            }
+            else if (typeof nested === 'string') {
+                msg = nested;
+            }
+            else {
+                msg = 'unknown error';
+            }
+        }
+    }
+    else {
+        msg = 'unknown error';
+    }
+    return sanitizeErrorMessage(msg);
+}
+function extractErrorType(err) {
+    const nested = extractNestedError(err);
+    if (nested && typeof nested === 'object') {
+        if (typeof nested.error_type === 'string')
+            return nested.error_type;
+        if (typeof nested.type === 'string')
+            return nested.type;
+    }
+    return undefined;
+}
+function isAuthFailure(status, lower, errorType) {
+    if (status === 401)
+        return true;
+    if (errorType === 'authentication' || errorType === 'authentication_error')
+        return true;
+    return (lower.includes('invalid api key') ||
+        lower.includes('invalid credentials') ||
+        lower.includes('invalid authentication') ||
+        lower.includes('no auth credentials') ||
+        lower.includes('missing api key') ||
+        lower.includes('unauthorized') ||
+        lower.includes('authentication failed') ||
+        lower.includes('user not found') ||
+        (status === 403 &&
+            (lower.includes('invalid api key') ||
+                lower.includes('invalid credentials') ||
+                lower.includes('authentication'))));
+}
+function isModelNotFound(status, lower) {
+    if (status === 404)
+        return true;
+    return (lower.includes('model') &&
+        (lower.includes('does not exist') ||
+            lower.includes('not found') ||
+            lower.includes('invalid model')));
+}
+function isGuardrailOrPolicy(lower) {
+    return (lower.includes('content policy') ||
+        lower.includes('moderation') ||
+        lower.includes('refused') ||
+        lower.includes('prompt injection') ||
+        lower.includes('guardrail') ||
+        lower.includes('request blocked') ||
+        lower.includes('blocked:'));
+}
+function looksLikeHtml(msg) {
+    const t = msg.trimStart().toLowerCase();
+    return t.startsWith('<!doctype') || t.startsWith('<html');
 }
 /** Classify upstream errors into the closed `ErrorCode` set. */
 export function classifyUpstreamError(err, contextMessage) {
     const rawMsg = extractMessage(err);
     const status = extractStatus(err);
+    const errorType = extractErrorType(err);
     const lower = rawMsg.toLowerCase();
     const fullMsg = contextMessage ? `${contextMessage}: ${rawMsg}` : rawMsg;
     const retryAfterSeconds = extractRetryAfterSeconds(err);
+    if (looksLikeHtml(rawMsg)) {
+        return toolError(ErrorCode.UPSTREAM_HTTP, contextMessage
+            ? `${contextMessage}: upstream returned an HTML error page`
+            : 'upstream returned an HTML error page', { status }, { suggestions: ['Retry after a brief delay', 'Check https://status.openrouter.ai'] });
+    }
     if (lower.includes('insufficient balance') ||
         lower.includes('insufficient credits') ||
         lower.includes('requires more credits') ||
@@ -82,10 +189,7 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    if (lower.includes('model') &&
-        (lower.includes('does not exist') ||
-            lower.includes('not found') ||
-            lower.includes('invalid model'))) {
+    if (isModelNotFound(status, lower)) {
         return toolError(ErrorCode.MODEL_NOT_FOUND, fullMsg, { status }, {
             suggestions: [
                 'Use search_models to discover valid model ids',
@@ -93,13 +197,6 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    if (lower.includes('content policy') ||
-        lower.includes('moderation') ||
-        lower.includes('refused')) {
-        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' }, {
-            suggestions: ['Rephrase the prompt', 'Try a different provider via provider.order'],
-        });
-    }
     if (status === 429 || lower.includes('rate limit')) {
         return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' }, {
             suggestions: [
@@ -119,8 +216,18 @@ export function classifyUpstreamError(err, contextMessage) {
             suggestions: ['Retry', 'Raise max_wait_ms or max_tokens'],
         });
     }
+    if (isAuthFailure(status, lower, errorType)) {
+        return toolError(ErrorCode.INVALID_CREDENTIALS, fullMsg, { status, reason: 'auth' }, { suggestions: [...AUTH_SUGGESTIONS] });
+    }
+    if (isGuardrailOrPolicy(lower) || status === 403) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' }, {
+            suggestions: ['Rephrase the prompt', 'Try a different provider via provider.order'],
+        });
+    }
     if (typeof status === 'number' && status >= 400 && status < 500) {
-        return toolError(ErrorCode.INVALID_INPUT, fullMsg, { status });
+        return toolError(ErrorCode.INVALID_INPUT, fullMsg, { status }, {
+            suggestions: ['Verify request parameters against OpenRouter docs'],
+        });
     }
     if (typeof status === 'number' && status >= 500) {
         return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg, { status }, {

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

@@ -15,3 +15,9 @@ export type OptionalOutputPath = {
 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>;
+export declare function isValidJobId(jobId: string): boolean;
+/**
+ * Resolve async-chat job status.json under OPENROUTER_OUTPUT_DIR/openrouter-jobs/.
+ * Uses realpath when the job directory exists to block symlink escapes.
+ */
+export declare function resolveSafeJobStatusPath(jobsDir: string, jobId: string): Promise<string | null>;

package/dist/tool-handlers/path-safety.js

@@ -33,6 +33,22 @@ function isUnsafeMode() {
     const v = process.env.OPENROUTER_ALLOW_UNSAFE_PATHS;
     return v === '1' || v?.toLowerCase() === 'true';
 }
+function pathHasNullByte(p) {
+    return p.includes('\0');
+}
+function withRootSep(rootReal) {
+    return rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
+}
+/** Prefix check; case-insensitive on Windows (drive letter / path casing). */
+function isInsideRoot(resolved, rootReal) {
+    const withSep = withRootSep(rootReal);
+    if (process.platform === 'win32') {
+        const lower = resolved.toLowerCase();
+        const rootLower = rootReal.toLowerCase();
+        return lower === rootLower || lower.startsWith(withRootSep(rootLower));
+    }
+    return resolved === rootReal || resolved.startsWith(withSep);
+}
 export class UnsafeOutputPathError extends Error {
     constructor(message) {
         super(message);
@@ -49,23 +65,26 @@ export async function resolveSafeOutputPath(savePath) {
         await fs.mkdir(path.dirname(abs), { recursive: true });
         return abs;
     }
+    if (pathHasNullByte(savePath)) {
+        throw new UnsafeOutputPathError('save_path contains a null byte');
+    }
     const root = getOutputRoot();
     const rootReal = await fs.realpath(root).catch(() => path.resolve(root));
     const candidate = path.isAbsolute(savePath)
         ? path.resolve(savePath)
         : path.resolve(rootReal, savePath);
-    const withSep = rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
     const candidateDir = path.dirname(candidate);
     const existingAncestor = await findExistingAncestor(candidateDir);
     const ancestorReal = await fs.realpath(existingAncestor);
-    if (!(ancestorReal === rootReal || ancestorReal.startsWith(withSep))) {
-        throw new UnsafeOutputPathError(`save_path resolves outside OPENROUTER_OUTPUT_DIR (${rootReal}). ` +
+    if (!isInsideRoot(ancestorReal, rootReal)) {
+        throw new UnsafeOutputPathError(`save_path resolves outside OPENROUTER_OUTPUT_DIR. ` +
             `Set OPENROUTER_OUTPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.`);
     }
     await fs.mkdir(candidateDir, { recursive: true });
     const parentReal = await fs.realpath(candidateDir);
-    if (!(parentReal === rootReal || parentReal.startsWith(withSep))) {
-        throw new UnsafeOutputPathError(`save_path escapes OPENROUTER_OUTPUT_DIR via symlink (${rootReal}).`);
+    if (!isInsideRoot(parentReal, rootReal)) {
+        throw new UnsafeOutputPathError('save_path escapes OPENROUTER_OUTPUT_DIR via symlink. ' +
+            'Set OPENROUTER_OUTPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.');
     }
     return path.join(parentReal, path.basename(candidate));
 }
@@ -108,23 +127,37 @@ export async function resolveSafeInputPath(inputPath) {
     if (isUnsafeMode()) {
         return path.resolve(inputPath);
     }
+    if (pathHasNullByte(inputPath)) {
+        throw new UnsafeOutputPathError('input path contains a null byte');
+    }
     const root = getInputRoot();
     const rootReal = await fs.realpath(root).catch(() => path.resolve(root));
-    const withSep = rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
     const abs = path.isAbsolute(inputPath)
         ? path.resolve(inputPath)
         : path.resolve(rootReal, inputPath);
-    let canonical;
-    try {
-        canonical = await fs.realpath(abs);
+    const existingAncestor = await findExistingAncestor(abs);
+    const ancestorReal = await fs.realpath(existingAncestor);
+    if (!isInsideRoot(ancestorReal, rootReal)) {
+        throw new UnsafeOutputPathError(`input path resolves outside OPENROUTER_INPUT_DIR: ${inputPath}. ` +
+            'Set OPENROUTER_INPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.');
     }
-    catch {
-        canonical = abs;
+    try {
+        const canonical = await fs.realpath(abs);
+        if (!isInsideRoot(canonical, rootReal)) {
+            throw new UnsafeOutputPathError(`input path resolves outside OPENROUTER_INPUT_DIR: ${inputPath}. ` +
+                'Set OPENROUTER_INPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.');
+        }
+        return canonical;
     }
-    if (!(canonical === rootReal || canonical.startsWith(withSep))) {
-        throw new UnsafeOutputPathError(`input path resolves outside OPENROUTER_INPUT_DIR (${rootReal}): ${inputPath}`);
+    catch (err) {
+        if (err instanceof UnsafeOutputPathError)
+            throw err;
+        if (!isInsideRoot(abs, rootReal)) {
+            throw new UnsafeOutputPathError(`input path resolves outside OPENROUTER_INPUT_DIR: ${inputPath}. ` +
+                'Set OPENROUTER_INPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.');
+        }
+        return abs;
     }
-    return abs;
 }
 export function isToolErrorResult(result) {
     return 'isError' in result;
@@ -142,3 +175,33 @@ export async function resolveOptionalOutputPath(savePath) {
         return toolErrorFrom(ErrorCode.INTERNAL, err);
     }
 }
+const JOB_ID_PATTERN = /^chat_[a-zA-Z0-9_-]{1,128}$/;
+export function isValidJobId(jobId) {
+    if (!JOB_ID_PATTERN.test(jobId))
+        return false;
+    if (jobId.includes('..') || jobId.includes('/') || jobId.includes('\\'))
+        return false;
+    return true;
+}
+/**
+ * Resolve async-chat job status.json under OPENROUTER_OUTPUT_DIR/openrouter-jobs/.
+ * Uses realpath when the job directory exists to block symlink escapes.
+ */
+export async function resolveSafeJobStatusPath(jobsDir, jobId) {
+    if (!isValidJobId(jobId))
+        return null;
+    const rootReal = await fs.realpath(jobsDir).catch(() => path.resolve(jobsDir));
+    const jobDirCandidate = path.resolve(jobsDir, jobId);
+    let jobDirReal;
+    try {
+        jobDirReal = await fs.realpath(jobDirCandidate);
+    }
+    catch {
+        if (!isInsideRoot(jobDirCandidate, rootReal))
+            return null;
+        return path.join(jobDirCandidate, 'status.json');
+    }
+    if (!isInsideRoot(jobDirReal, rootReal))
+        return null;
+    return path.join(jobDirReal, 'status.json');
+}

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

@@ -0,0 +1,4 @@
+/** Strip existing extension (if any) and append a new one. */
+export declare function replaceExtension(filePath: string, newExt: string): string;
+/** Write bytes atomically via a same-directory temp file and rename. */
+export declare function writeOutputFile(target: string, data: Buffer): Promise<void>;

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

@@ -0,0 +1,20 @@
+import { extname } from 'node:path';
+import { promises as fs } from 'node:fs';
+/** Strip existing extension (if any) and append a new one. */
+export function replaceExtension(filePath, newExt) {
+    const current = extname(filePath);
+    const base = current ? filePath.slice(0, -current.length) : filePath;
+    return `${base}.${newExt}`;
+}
+/** Write bytes atomically via a same-directory temp file and rename. */
+export async function writeOutputFile(target, data) {
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await fs.writeFile(tmp, data);
+        await fs.rename(tmp, target);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+        throw err;
+    }
+}