@stabgan/openrouter-mcp-multimodal 2.0.0 → 3.0.0

package/dist/openrouter-api.js

@@ -1,25 +1,55 @@
 const BASE_URL = 'https://openrouter.ai/api/v1';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const VIDEO_TIMEOUT_MS = 60_000;
+const MAX_BACKOFF_MS = 10_000;
 async function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
-async function fetchWithRetry(url, init, retries = 2) {
+function parseRetryAfter(headerValue) {
+    if (!headerValue)
+        return null;
+    const asInt = parseInt(headerValue, 10);
+    if (Number.isFinite(asInt) && asInt >= 0)
+        return asInt * 1000;
+    const asDate = Date.parse(headerValue);
+    if (Number.isFinite(asDate)) {
+        const delta = asDate - Date.now();
+        return delta > 0 ? delta : 0;
+    }
+    return null;
+}
+function backoffWithJitter(attempt, retryAfterMs) {
+    const base = 400 * (attempt + 1);
+    const target = Math.min(Math.max(base, retryAfterMs ?? 0), MAX_BACKOFF_MS);
+    const jitter = 0.5 + Math.random(); // 0.5x .. 1.5x
+    return Math.round(target * jitter);
+}
+/**
+ * fetch() wrapper with retries on 429 / 5xx / network error.
+ *
+ * A fresh `AbortSignal.timeout(timeoutMs)` is created per attempt so retries
+ * each get a full timeout budget. Backoff honors `Retry-After` (seconds or
+ * HTTP-date) and applies jitter to avoid thundering-herd synchronization.
+ */
+async function fetchWithRetry(url, init, { retries = 2, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
     let lastErr;
     for (let attempt = 0; attempt <= retries; attempt++) {
         try {
-            const res = await fetch(url, init);
+            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
             if (res.status === 429 || res.status >= 500) {
-                if (attempt < retries)
-                    await sleep(400 * (attempt + 1));
-                else
-                    return res;
-                continue;
+                if (attempt < retries) {
+                    const retryAfter = parseRetryAfter(res.headers.get('retry-after'));
+                    await sleep(backoffWithJitter(attempt, retryAfter));
+                    continue;
+                }
+                return res;
             }
             return res;
         }
         catch (e) {
             lastErr = e;
             if (attempt < retries)
-                await sleep(400 * (attempt + 1));
+                await sleep(backoffWithJitter(attempt, null));
         }
     }
     throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
@@ -29,14 +59,100 @@ export class OpenRouterAPIClient {
     constructor(apiKey) {
         this.apiKey = apiKey;
     }
+    authHeaders(extra) {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            'HTTP-Referer': 'https://github.com/stabgan/openrouter-mcp-multimodal',
+            'X-Title': 'openrouter-mcp-multimodal',
+            ...extra,
+        };
+    }
     async getModels() {
-        const res = await fetchWithRetry(`${BASE_URL}/models`, {
-            headers: { Authorization: `Bearer ${this.apiKey}` },
-            signal: AbortSignal.timeout(30000),
-        }, 2);
+        const res = await fetchWithRetry(`${BASE_URL}/models`, { headers: this.authHeaders() }, { retries: 2, timeoutMs: DEFAULT_TIMEOUT_MS });
         if (!res.ok)
             throw new Error(`Failed to fetch models: HTTP ${res.status}`);
         const data = (await res.json());
         return data.data ?? [];
     }
+    /** Submit a video-generation job. Returns the `{ id, polling_url, status }` envelope. */
+    async submitVideoJob(body) {
+        const res = await fetchWithRetry(`${BASE_URL}/videos`, {
+            method: 'POST',
+            headers: this.authHeaders({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(body),
+        }, { retries: 2, timeoutMs: VIDEO_TIMEOUT_MS });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`POST /videos failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        return (await res.json());
+    }
+    /** Poll a submitted video-generation job by id. */
+    async pollVideoJob(id) {
+        const res = await fetchWithRetry(`${BASE_URL}/videos/${encodeURIComponent(id)}`, { headers: this.authHeaders() }, { retries: 2, timeoutMs: DEFAULT_TIMEOUT_MS });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`GET /videos/${id} failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * Download the generated video binary. Returns `{ buffer, contentType }`.
+     * This intentionally does NOT go through our SSRF-guarded `fetchHttpResource`
+     * because the URL is always OpenRouter itself (trusted origin) — and it can
+     * return arbitrarily large bodies that the caller bounds via
+     * `OPENROUTER_VIDEO_MAX_DOWNLOAD_BYTES`.
+     */
+    async downloadVideoContent(id, index = 0, maxBytes = 256 * 1024 * 1024) {
+        const url = `${BASE_URL}/videos/${encodeURIComponent(id)}/content?index=${index}`;
+        const res = await fetchWithRetry(url, { headers: this.authHeaders() }, { retries: 1, timeoutMs: VIDEO_TIMEOUT_MS * 2 });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`GET /videos/${id}/content failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        const declared = res.headers.get('content-length');
+        if (declared) {
+            const n = parseInt(declared, 10);
+            if (Number.isFinite(n) && n > maxBytes) {
+                throw new Error(`Generated video too large: ${n} bytes > ${maxBytes}`);
+            }
+        }
+        const reader = res.body?.getReader();
+        if (!reader) {
+            const buf = Buffer.from(await res.arrayBuffer());
+            if (buf.length > maxBytes)
+                throw new Error('Generated video too large');
+            return { buffer: buf, contentType: res.headers.get('content-type') };
+        }
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    /* ignore */
+                }
+                throw new Error('Generated video too large');
+            }
+            chunks.push(Buffer.from(value));
+        }
+        return { buffer: Buffer.concat(chunks), contentType: res.headers.get('content-type') };
+    }
+}
+async function safeReadText(res) {
+    try {
+        const t = await res.text();
+        return t.length > 500 ? t.slice(0, 500) + '…' : t;
+    }
+    catch {
+        return '';
+    }
 }
+// Exported for tests.
+export const _internals = { parseRetryAfter, backoffWithJitter, fetchWithRetry };

package/dist/tool-handlers/analyze-audio.d.ts

@@ -8,16 +8,12 @@ export declare function handleAnalyzeAudio(request: {
     params: {
         arguments: AnalyzeAudioToolRequest;
     };
-}, openai: OpenAI, defaultModel?: string): Promise<{
+}, openai: OpenAI, defaultModel?: string): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: string;
+        type: "text";
         text: string;
     }[];
-    isError: boolean;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
+    _meta: {
+        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
+    };
 }>;

package/dist/tool-handlers/analyze-audio.js

@@ -1,13 +1,32 @@
 import { prepareAudioData } from './audio-utils.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash';
 export async function handleAnalyzeAudio(request, openai, defaultModel) {
-    const { audio_path, question, model } = request.params.arguments;
+    const { audio_path, question, model } = request.params.arguments ?? { audio_path: '' };
     if (!audio_path) {
-        return { content: [{ type: 'text', text: 'audio_path is required.' }], isError: true };
+        return toolError(ErrorCode.INVALID_INPUT, 'audio_path is required.');
     }
+    let audioData;
     try {
-        const audioData = await prepareAudioData(audio_path);
-        const completion = await openai.chat.completions.create({
+        audioData = await prepareAudioData(audio_path);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Blocked host'))
+            return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+        if (msg.toLowerCase().includes('too large')) {
+            return toolErrorFrom(ErrorCode.RESOURCE_TOO_LARGE, err);
+        }
+        if (msg.toLowerCase().includes('unsupported')) {
+            return toolErrorFrom(ErrorCode.UNSUPPORTED_FORMAT, err);
+        }
+        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+    }
+    let completion;
+    try {
+        completion = await openai.chat.completions.create({
             model: model || defaultModel || DEFAULT_MODEL,
             messages: [
                 {
@@ -25,10 +44,24 @@ export async function handleAnalyzeAudio(request, openai, defaultModel) {
                 },
             ],
         });
-        return { content: [{ type: 'text', text: completion.choices[0].message.content || '' }] };
     }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    catch (err) {
+        return classifyUpstreamError(err);
+    }
+    const extracted = extractCompletionText(completion);
+    const cutoff = detectReasoningCutoff(extracted);
+    if (cutoff)
+        return cutoff;
+    if (!extracted.text) {
+        return toolError(ErrorCode.INTERNAL, 'Audio model returned no textual content.', {
+            finish_reason: extracted.finishReason,
+        });
     }
+    return {
+        content: [{ type: 'text', text: extracted.text }],
+        _meta: {
+            finish_reason: extracted.finishReason,
+            ...(toUsageMeta(extracted.usage) ?? {}),
+        },
+    };
 }

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

@@ -8,16 +8,12 @@ export declare function handleAnalyzeImage(request: {
     params: {
         arguments: AnalyzeImageToolRequest;
     };
-}, openai: OpenAI, defaultModel?: string): Promise<{
+}, openai: OpenAI, defaultModel?: string): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: string;
+        type: "text";
         text: string;
     }[];
-    isError: boolean;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
+    _meta: {
+        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
+    };
 }>;

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

@@ -1,13 +1,29 @@
 import { prepareImageUrl } from './image-utils.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
 const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
 export async function handleAnalyzeImage(request, openai, defaultModel) {
-    const { image_path, question, model } = request.params.arguments;
+    const { image_path, question, model } = request.params.arguments ?? { image_path: '' };
     if (!image_path) {
-        return { content: [{ type: 'text', text: 'image_path is required.' }], isError: true };
+        return toolError(ErrorCode.INVALID_INPUT, 'image_path is required.');
     }
+    let imageUrl;
     try {
-        const imageUrl = await prepareImageUrl(image_path);
-        const completion = await openai.chat.completions.create({
+        imageUrl = await prepareImageUrl(image_path);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Blocked host'))
+            return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+        if (msg.toLowerCase().includes('too large')) {
+            return toolErrorFrom(ErrorCode.RESOURCE_TOO_LARGE, err);
+        }
+        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+    }
+    let completion;
+    try {
+        completion = await openai.chat.completions.create({
             model: model || defaultModel || DEFAULT_MODEL,
             messages: [
                 {
@@ -19,10 +35,24 @@ export async function handleAnalyzeImage(request, openai, defaultModel) {
                 },
             ],
         });
-        return { content: [{ type: 'text', text: completion.choices[0].message.content || '' }] };
     }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    catch (err) {
+        return classifyUpstreamError(err);
+    }
+    const extracted = extractCompletionText(completion);
+    const cutoff = detectReasoningCutoff(extracted);
+    if (cutoff)
+        return cutoff;
+    if (!extracted.text) {
+        return toolError(ErrorCode.INTERNAL, 'Vision model returned no textual content.', {
+            finish_reason: extracted.finishReason,
+        });
     }
+    return {
+        content: [{ type: 'text', text: extracted.text }],
+        _meta: {
+            finish_reason: extracted.finishReason,
+            ...(toUsageMeta(extracted.usage) ?? {}),
+        },
+    };
 }

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

@@ -0,0 +1,19 @@
+import OpenAI from 'openai';
+export interface AnalyzeVideoToolRequest {
+    video_path: string;
+    question?: string;
+    model?: string;
+}
+export declare function handleAnalyzeVideo(request: {
+    params: {
+        arguments: AnalyzeVideoToolRequest;
+    };
+}, openai: OpenAI, defaultModel?: string): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    _meta: {
+        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
+    };
+}>;

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

@@ -0,0 +1,93 @@
+import { prepareVideoData } from './video-utils.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { logger } from '../logger.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
+/**
+ * Default model — `google/gemini-2.5-flash` has the widest video-input
+ * support on OpenRouter at time of writing. Override via env
+ * `OPENROUTER_DEFAULT_VIDEO_MODEL` or per-call `model`.
+ */
+const FALLBACK_DEFAULT_MODEL = 'google/gemini-2.5-flash';
+export async function handleAnalyzeVideo(request, openai, defaultModel) {
+    const { video_path, question, model } = request.params.arguments ?? {
+        video_path: '',
+    };
+    if (!video_path) {
+        return toolError(ErrorCode.INVALID_INPUT, 'video_path is required.');
+    }
+    const pickedModel = model ||
+        process.env.OPENROUTER_DEFAULT_VIDEO_MODEL ||
+        defaultModel ||
+        FALLBACK_DEFAULT_MODEL;
+    let videoData;
+    try {
+        videoData = await prepareVideoData(video_path);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Blocked host')) {
+            return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+        }
+        if (msg.includes('too large')) {
+            return toolErrorFrom(ErrorCode.RESOURCE_TOO_LARGE, err);
+        }
+        if (msg.includes('Unsupported') || msg.includes('not a video')) {
+            return toolErrorFrom(ErrorCode.UNSUPPORTED_FORMAT, err);
+        }
+        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+    }
+    let completion;
+    try {
+        logger.debug('analyze_video.submit', {
+            model: pickedModel,
+            format: videoData.format,
+            size_bytes: videoData.sizeBytes,
+        });
+        completion = await openai.chat.completions.create({
+            model: pickedModel,
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'text',
+                            text: question || 'Describe what happens in this video, step by step.',
+                        },
+                        {
+                            // The `video_url` content type is an OpenRouter extension; the
+                            // OpenAI SDK's typings don't know about it yet. See:
+                            // https://openrouter.ai/docs/guides/overview/multimodal/videos
+                            type: 'video_url',
+                            video_url: {
+                                url: `data:${videoData.mediaType};base64,${videoData.data}`,
+                            },
+                        },
+                    ],
+                },
+            ],
+        });
+    }
+    catch (err) {
+        logger.warn('analyze_video.error', {
+            err: err instanceof Error ? err.message : String(err),
+        });
+        return classifyUpstreamError(err);
+    }
+    const extracted = extractCompletionText(completion);
+    const cutoff = detectReasoningCutoff(extracted);
+    if (cutoff)
+        return cutoff;
+    if (!extracted.text) {
+        return toolError(ErrorCode.INTERNAL, 'Video model returned no textual content.', {
+            finish_reason: extracted.finishReason,
+        });
+    }
+    return {
+        content: [{ type: 'text', text: extracted.text }],
+        _meta: {
+            finish_reason: extracted.finishReason,
+            ...(toUsageMeta(extracted.usage) ?? {}),
+        },
+    };
+}

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

@@ -4,7 +4,7 @@
  */
 import path from 'path';
 import { promises as fs } from 'fs';
-import { readEnvInt, fetchHttpResource } from './fetch-utils.js';
+import { readEnvInt, fetchHttpResource, parseBase64DataUrl } from './fetch-utils.js';
 // Re-export for tests
 export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
 const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
@@ -89,19 +89,17 @@ function formatFromContentType(ct) {
 export async function prepareAudioData(source) {
     // --- data URL ---
     if (source.startsWith('data:')) {
-        const match = source.match(/^data:([^;]+);base64,(.+)$/);
-        if (!match)
+        const parsed = parseBase64DataUrl(source);
+        if (!parsed)
             throw new Error('Invalid data URL format');
-        const mime = match[1];
-        const b64 = match[2];
-        const format = mimeSubtypeToFormat(mime.split('/')[1] ?? '');
+        const format = mimeSubtypeToFormat(parsed.mediaType.split('/')[1] ?? '');
         if (!format) {
-            throw new Error(`Unsupported audio format from MIME: ${mime}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
+            throw new Error(`Unsupported audio format from MIME: ${parsed.mediaType}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
         }
-        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 { data: b64, format };
+        return { data: parsed.base64, format };
     }
     // --- HTTP(S) URL ---
     if (source.startsWith('http://') || source.startsWith('https://')) {

package/dist/tool-handlers/chat-completion.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 export interface ChatCompletionToolRequest {
     model?: string;
     messages: ChatCompletionMessageParam[];
@@ -10,16 +10,12 @@ export declare function handleChatCompletion(request: {
     params: {
         arguments: ChatCompletionToolRequest;
     };
-}, openai: OpenAI, defaultModel?: string): Promise<{
+}, openai: OpenAI, defaultModel?: string): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: string;
+        type: "text";
         text: string;
     }[];
-    isError: boolean;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
+    _meta: {
+        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
+    };
 }>;

package/dist/tool-handlers/chat-completion.js

@@ -1,19 +1,39 @@
+import { ErrorCode, toolError } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
 export async function handleChatCompletion(request, openai, defaultModel) {
-    const { messages, model, temperature, max_tokens } = request.params.arguments;
+    const { messages, model, temperature, max_tokens } = request.params.arguments ?? {
+        messages: [],
+    };
     if (!messages?.length) {
-        return { content: [{ type: 'text', text: 'Messages array cannot be empty.' }], isError: true };
+        return toolError(ErrorCode.INVALID_INPUT, 'Messages array cannot be empty.');
     }
+    let completion;
     try {
-        const completion = await openai.chat.completions.create({
+        completion = await openai.chat.completions.create({
             model: model || defaultModel || 'nvidia/nemotron-nano-12b-v2-vl:free',
             messages,
             temperature: temperature ?? 1,
             ...(max_tokens && { max_tokens }),
         });
-        return { content: [{ type: 'text', text: completion.choices[0].message.content || '' }] };
     }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return { content: [{ type: 'text', text: `API error: ${msg}` }], isError: true };
+    catch (err) {
+        return classifyUpstreamError(err);
     }
+    const extracted = extractCompletionText(completion);
+    const cutoff = detectReasoningCutoff(extracted);
+    if (cutoff)
+        return cutoff;
+    if (!extracted.text) {
+        return toolError(ErrorCode.INTERNAL, 'Model returned no textual content.', {
+            finish_reason: extracted.finishReason,
+        });
+    }
+    return {
+        content: [{ type: 'text', text: extracted.text }],
+        _meta: {
+            finish_reason: extracted.finishReason,
+            ...(toUsageMeta(extracted.usage) ?? {}),
+        },
+    };
 }

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

@@ -0,0 +1,27 @@
+/**
+ * Shared helpers for tools that call `openai.chat.completions.create` and
+ * return the assistant's message as text. Handles:
+ *   - plain string content (the common case)
+ *   - multimodal array content (concatenate text parts)
+ *   - reasoning-only responses (`content: null` + `reasoning`/`reasoning_details`)
+ *   - `finish_reason === 'length'` — warn the caller so they know to raise
+ *     `max_tokens` instead of silently getting nothing back.
+ */
+import type { ChatCompletion } from 'openai/resources/chat/completions.js';
+import { type ToolErrorResult } from '../errors.js';
+export interface ExtractedText {
+    text: string;
+    /** True when `text` came from the reasoning trace (not a final answer). */
+    reasonedOnly: boolean;
+    finishReason: ChatCompletion.Choice['finish_reason'] | undefined;
+    usage?: ChatCompletion['usage'];
+}
+export declare function extractCompletionText(completion: ChatCompletion): ExtractedText;
+/**
+ * If the extracted response is reasoning-only and was cut off by
+ * `max_tokens`, return a structured INVALID_INPUT suggesting the caller
+ * raise the budget. Otherwise return `null` (let the caller format the
+ * success response).
+ */
+export declare function detectReasoningCutoff(extracted: ExtractedText): ToolErrorResult | null;
+export declare function toUsageMeta(usage: ChatCompletion['usage'] | undefined): Record<string, unknown> | undefined;

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

@@ -0,0 +1,69 @@
+import { ErrorCode, toolError } from '../errors.js';
+export function extractCompletionText(completion) {
+    const choice = completion.choices?.[0];
+    const msg = choice?.message;
+    const finishReason = choice?.finish_reason;
+    const usage = completion.usage ?? undefined;
+    if (!msg)
+        return { text: '', reasonedOnly: false, finishReason, usage };
+    const { content, reasoning, reasoning_details } = msg;
+    if (typeof content === 'string' && content.length > 0) {
+        return { text: content, reasonedOnly: false, finishReason, usage };
+    }
+    if (Array.isArray(content)) {
+        const parts = content
+            .filter((p) => p.type === 'text' && typeof p.text === 'string')
+            .map((p) => p.text ?? '');
+        const joined = parts.join('');
+        if (joined.length > 0) {
+            return { text: joined, reasonedOnly: false, finishReason, usage };
+        }
+    }
+    if (typeof reasoning === 'string' && reasoning.length > 0) {
+        return { text: reasoning, reasonedOnly: true, finishReason, usage };
+    }
+    if (Array.isArray(reasoning_details) && reasoning_details.length > 0) {
+        const joined = reasoning_details
+            .filter((d) => typeof d.text === 'string')
+            .map((d) => d.text)
+            .join('\n');
+        if (joined.length > 0) {
+            return { text: joined, reasonedOnly: true, finishReason, usage };
+        }
+    }
+    return { text: '', reasonedOnly: false, finishReason, usage };
+}
+/**
+ * If the extracted response is reasoning-only and was cut off by
+ * `max_tokens`, return a structured INVALID_INPUT suggesting the caller
+ * raise the budget. Otherwise return `null` (let the caller format the
+ * success response).
+ */
+export function detectReasoningCutoff(extracted) {
+    if (extracted.reasonedOnly && extracted.finishReason === 'length') {
+        return toolError(ErrorCode.INVALID_INPUT, 'Model exhausted max_tokens during internal reasoning without emitting a final answer. ' +
+            'Raise max_tokens or choose a non-reasoning model.', {
+            finish_reason: extracted.finishReason,
+            reasoning_preview: extracted.text.slice(0, 200),
+            usage: extracted.usage
+                ? {
+                    prompt_tokens: extracted.usage.prompt_tokens,
+                    completion_tokens: extracted.usage.completion_tokens,
+                    total_tokens: extracted.usage.total_tokens,
+                }
+                : undefined,
+        });
+    }
+    return null;
+}
+export function toUsageMeta(usage) {
+    if (!usage)
+        return undefined;
+    return {
+        usage: {
+            prompt_tokens: usage.prompt_tokens,
+            completion_tokens: usage.completion_tokens,
+            total_tokens: usage.total_tokens,
+        },
+    };
+}