@steipete/oracle 0.4.4 → 0.5.0

package/dist/src/oracle/errors.js

@@ -74,7 +74,7 @@ export function extractResponseMetadata(response) {
     }
     return metadata;
 }
-export function toTransportError(error) {
+export function toTransportError(error, model) {
     if (error instanceof OracleTransportError) {
         return error;
     }
@@ -87,10 +87,26 @@ export function toTransportError(error) {
     if (error instanceof APIConnectionError) {
         return new OracleTransportError('connection-lost', 'Connection to OpenAI dropped before the response completed.', error);
     }
-    if (error instanceof APIError) {
-        if (error.status === 404 || error.status === 405) {
-            return new OracleTransportError('unsupported-endpoint', 'HTTP 404/405 from the Responses API; this base URL or gateway likely does not expose /v1/responses. Set OPENAI_BASE_URL to api.openai.com/v1, update your Azure API version/deployment, or use the browser engine.', error);
+    const isApiError = error instanceof APIError || error?.name === 'APIError';
+    if (isApiError) {
+        const apiError = error;
+        const code = apiError.code ?? apiError.error?.code;
+        const messageText = apiError.message?.toLowerCase?.() ?? '';
+        const apiMessage = apiError.error?.message ||
+            apiError.message ||
+            (apiError.status ? `${apiError.status} OpenAI API error` : 'OpenAI API error');
+        // TODO: Remove once gpt-5.1-pro is available via the Responses API.
+        if (model === 'gpt-5.1-pro' &&
+            (code === 'model_not_found' ||
+                messageText.includes('does not exist') ||
+                messageText.includes('unknown model') ||
+                messageText.includes('model_not_found'))) {
+            return new OracleTransportError('model-unavailable', 'gpt-5.1-pro is not yet available on this API base. Use gpt-5-pro for now until OpenAI enables it. // TODO: Remove once gpt-5.1-pro is available', apiError);
         }
+        if (apiError.status === 404 || apiError.status === 405) {
+            return new OracleTransportError('unsupported-endpoint', 'HTTP 404/405 from the Responses API; this base URL or gateway likely does not expose /v1/responses. Set OPENAI_BASE_URL to api.openai.com/v1, update your Azure API version/deployment, or use the browser engine.', apiError);
+        }
+        return new OracleTransportError('api-error', apiMessage, apiError);
     }
     return new OracleTransportError('unknown', error instanceof Error ? error.message : 'Unknown transport failure.', error);
 }
@@ -104,6 +120,10 @@ export function describeTransportError(error, deadlineMs) {
             return 'Connection to OpenAI ended unexpectedly before the response completed.';
         case 'client-abort':
             return 'Request was aborted before OpenAI completed the response.';
+        case 'api-error':
+            return error.message;
+        case 'model-unavailable':
+            return error.message;
         case 'unsupported-endpoint':
             return 'The Responses API returned 404/405 — your base URL/gateway probably lacks /v1/responses (check OPENAI_BASE_URL or switch to api.openai.com / browser engine).';
         default:

package/dist/src/oracle/modelResolver.js

@@ -0,0 +1,144 @@
+import { MODEL_CONFIGS, PRO_MODELS } from './config.js';
+import { countTokens as countTokensGpt5Pro } from 'gpt-tokenizer/model/gpt-5-pro';
+const OPENROUTER_DEFAULT_BASE = 'https://openrouter.ai/api/v1';
+const OPENROUTER_MODELS_ENDPOINT = 'https://openrouter.ai/api/v1/models';
+export function isKnownModel(model) {
+    return Object.hasOwn(MODEL_CONFIGS, model);
+}
+export function isOpenRouterBaseUrl(baseUrl) {
+    if (!baseUrl)
+        return false;
+    try {
+        const url = new URL(baseUrl);
+        return url.hostname.includes('openrouter.ai');
+    }
+    catch {
+        return false;
+    }
+}
+export function defaultOpenRouterBaseUrl() {
+    return OPENROUTER_DEFAULT_BASE;
+}
+export function normalizeOpenRouterBaseUrl(baseUrl) {
+    try {
+        const url = new URL(baseUrl);
+        // If user passed the responses endpoint, trim it so the client does not double-append.
+        if (url.pathname.endsWith('/responses')) {
+            url.pathname = url.pathname.replace(/\/responses\/?$/, '');
+        }
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        return baseUrl;
+    }
+}
+export function safeModelSlug(model) {
+    return model.replace(/[/\\]/g, '__').replace(/[:*?"<>|]/g, '_');
+}
+const catalogCache = new Map();
+const CACHE_TTL_MS = 5 * 60 * 1000;
+async function fetchOpenRouterCatalog(apiKey, fetcher) {
+    const cached = catalogCache.get(apiKey);
+    const now = Date.now();
+    if (cached && now - cached.fetchedAt < CACHE_TTL_MS) {
+        return cached.models;
+    }
+    const response = await fetcher(OPENROUTER_MODELS_ENDPOINT, {
+        headers: {
+            authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to load OpenRouter models (${response.status})`);
+    }
+    const json = (await response.json());
+    const models = json?.data ?? [];
+    catalogCache.set(apiKey, { fetchedAt: now, models });
+    return models;
+}
+function mapToOpenRouterId(candidate, catalog, providerHint) {
+    if (candidate.includes('/'))
+        return candidate;
+    const byExact = catalog.find((entry) => entry.id === candidate);
+    if (byExact)
+        return byExact.id;
+    const bySuffix = catalog.find((entry) => entry.id.endsWith(`/${candidate}`));
+    if (bySuffix)
+        return bySuffix.id;
+    if (providerHint) {
+        return `${providerHint}/${candidate}`;
+    }
+    return candidate;
+}
+export async function resolveModelConfig(model, options = {}) {
+    const known = isKnownModel(model) ? MODEL_CONFIGS[model] : null;
+    const fetcher = options.fetcher ?? globalThis.fetch.bind(globalThis);
+    const openRouterActive = isOpenRouterBaseUrl(options.baseUrl) || Boolean(options.openRouterApiKey);
+    if (known && !openRouterActive) {
+        return known;
+    }
+    // Try to enrich from OpenRouter catalog when available.
+    if (openRouterActive && options.openRouterApiKey) {
+        try {
+            const catalog = await fetchOpenRouterCatalog(options.openRouterApiKey, fetcher);
+            const targetId = mapToOpenRouterId(typeof model === 'string' ? model : String(model), catalog, known?.provider);
+            const info = catalog.find((entry) => entry.id === targetId) ?? null;
+            if (info) {
+                return {
+                    ...(known ?? {
+                        model,
+                        tokenizer: countTokensGpt5Pro,
+                        inputLimit: info.context_length ?? 200_000,
+                        reasoning: null,
+                    }),
+                    apiModel: targetId,
+                    openRouterId: targetId,
+                    provider: known?.provider ?? 'other',
+                    inputLimit: info.context_length ?? known?.inputLimit ?? 200_000,
+                    pricing: info.pricing && info.pricing.prompt != null && info.pricing.completion != null
+                        ? {
+                            inputPerToken: info.pricing.prompt / 1_000_000,
+                            outputPerToken: info.pricing.completion / 1_000_000,
+                        }
+                        : known?.pricing ?? null,
+                    supportsBackground: known?.supportsBackground ?? true,
+                    supportsSearch: known?.supportsSearch ?? true,
+                };
+            }
+            // No metadata hit; fall through to synthesized config.
+            return {
+                ...(known ?? {
+                    model,
+                    tokenizer: countTokensGpt5Pro,
+                    inputLimit: 200_000,
+                    reasoning: null,
+                }),
+                apiModel: targetId,
+                openRouterId: targetId,
+                provider: known?.provider ?? 'other',
+                supportsBackground: known?.supportsBackground ?? true,
+                supportsSearch: known?.supportsSearch ?? true,
+                pricing: known?.pricing ?? null,
+            };
+        }
+        catch {
+            // If catalog fetch fails, fall back to a synthesized config.
+        }
+    }
+    // Synthesized generic config for custom endpoints or failed catalog fetch.
+    return {
+        ...(known ?? {
+            model,
+            tokenizer: countTokensGpt5Pro,
+            inputLimit: 200_000,
+            reasoning: null,
+        }),
+        provider: known?.provider ?? 'other',
+        supportsBackground: known?.supportsBackground ?? true,
+        supportsSearch: known?.supportsSearch ?? true,
+        pricing: known?.pricing ?? null,
+    };
+}
+export function isProModel(model) {
+    return isKnownModel(model) && PRO_MODELS.has(model);
+}

package/dist/src/oracle/oscProgress.js

@@ -55,7 +55,7 @@ export function startOscProgress(options = {}) {
     timer.unref?.();
     let stopped = false;
     return () => {
-        // biome-ignore lint/nursery/noUnnecessaryConditions: multiple callers may try to stop
+        // multiple callers may try to stop
         if (stopped) {
             return;
         }

package/dist/src/oracle/run.js

@@ -4,7 +4,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
 import { performance } from 'node:perf_hooks';
-import { DEFAULT_SYSTEM_PROMPT, MODEL_CONFIGS, PRO_MODELS, TOKENIZER_OPTIONS } from './config.js';
+import { DEFAULT_SYSTEM_PROMPT, MODEL_CONFIGS, TOKENIZER_OPTIONS } from './config.js';
 import { readFiles } from './files.js';
 import { buildPrompt, buildRequestBody } from './request.js';
 import { estimateRequestTokens } from './tokenEstimate.js';
@@ -21,6 +21,7 @@ import { resolveClaudeModelId } from './claude.js';
 import { renderMarkdownAnsi } from '../cli/markdownRenderer.js';
 import { executeBackgroundResponse } from './background.js';
 import { formatTokenEstimate, formatTokenValue, resolvePreviewMode } from './runUtils.js';
+import { defaultOpenRouterBaseUrl, isKnownModel, isOpenRouterBaseUrl, isProModel, resolveModelConfig, normalizeOpenRouterBaseUrl, } from './modelResolver.js';
 const isStdoutTty = process.stdout.isTTY && chalk.level > 0;
 const dim = (text) => (isStdoutTty ? kleur.dim(text) : text);
 // Default timeout for non-pro API runs (fast models) — give them up to 120s.
@@ -36,15 +37,42 @@ export async function runOracle(options, deps = {}) {
         : () => true;
     const isTty = allowStdout && isStdoutTty;
     const resolvedXaiBaseUrl = process.env.XAI_BASE_URL?.trim() || 'https://api.x.ai/v1';
+    const openRouterApiKey = process.env.OPENROUTER_API_KEY?.trim();
+    const defaultOpenRouterBase = defaultOpenRouterBaseUrl();
+    const knownModelConfig = isKnownModel(options.model) ? MODEL_CONFIGS[options.model] : undefined;
+    const provider = knownModelConfig?.provider ?? 'other';
+    const hasOpenAIKey = Boolean(optionsApiKey) ||
+        Boolean(process.env.OPENAI_API_KEY) ||
+        Boolean(process.env.AZURE_OPENAI_API_KEY && options.azure?.endpoint);
+    const hasAnthropicKey = Boolean(optionsApiKey) || Boolean(process.env.ANTHROPIC_API_KEY);
+    const hasGeminiKey = Boolean(optionsApiKey) || Boolean(process.env.GEMINI_API_KEY);
+    const hasXaiKey = Boolean(optionsApiKey) || Boolean(process.env.XAI_API_KEY);
     let baseUrl = options.baseUrl?.trim();
     if (!baseUrl) {
         if (options.model.startsWith('grok')) {
             baseUrl = resolvedXaiBaseUrl;
         }
+        else if (provider === 'anthropic') {
+            baseUrl = process.env.ANTHROPIC_BASE_URL?.trim();
+        }
         else {
             baseUrl = process.env.OPENAI_BASE_URL?.trim();
         }
     }
+    const providerKeyMissing = (provider === 'openai' && !hasOpenAIKey) ||
+        (provider === 'anthropic' && !hasAnthropicKey) ||
+        (provider === 'google' && !hasGeminiKey) ||
+        (provider === 'xai' && !hasXaiKey) ||
+        provider === 'other';
+    const openRouterFallback = providerKeyMissing && Boolean(openRouterApiKey);
+    if (!baseUrl || openRouterFallback) {
+        if (openRouterFallback) {
+            baseUrl = defaultOpenRouterBase;
+        }
+    }
+    if (baseUrl && isOpenRouterBaseUrl(baseUrl)) {
+        baseUrl = normalizeOpenRouterBaseUrl(baseUrl);
+    }
     const logVerbose = (message) => {
         if (options.verbose) {
             log(dim(`[verbose] ${message}`));
@@ -54,51 +82,61 @@ export async function runOracle(options, deps = {}) {
     const isPreview = Boolean(previewMode);
     const isAzureOpenAI = Boolean(options.azure?.endpoint);
     const getApiKeyForModel = (model) => {
-        if (model.startsWith('gpt')) {
+        if (isOpenRouterBaseUrl(baseUrl) || openRouterFallback) {
+            return { key: optionsApiKey ?? openRouterApiKey, source: 'OPENROUTER_API_KEY' };
+        }
+        if (typeof model === 'string' && model.startsWith('gpt')) {
             if (optionsApiKey)
-                return optionsApiKey;
+                return { key: optionsApiKey, source: 'apiKey option' };
             if (isAzureOpenAI) {
-                return process.env.AZURE_OPENAI_API_KEY ?? process.env.OPENAI_API_KEY;
+                const key = process.env.AZURE_OPENAI_API_KEY ?? process.env.OPENAI_API_KEY;
+                return { key, source: 'AZURE_OPENAI_API_KEY|OPENAI_API_KEY' };
             }
-            return process.env.OPENAI_API_KEY;
+            return { key: process.env.OPENAI_API_KEY, source: 'OPENAI_API_KEY' };
         }
-        if (model.startsWith('gemini')) {
-            return optionsApiKey ?? process.env.GEMINI_API_KEY;
+        if (typeof model === 'string' && model.startsWith('gemini')) {
+            return { key: optionsApiKey ?? process.env.GEMINI_API_KEY, source: 'GEMINI_API_KEY' };
         }
-        if (model.startsWith('claude')) {
-            return optionsApiKey ?? process.env.ANTHROPIC_API_KEY;
+        if (typeof model === 'string' && model.startsWith('claude')) {
+            return { key: optionsApiKey ?? process.env.ANTHROPIC_API_KEY, source: 'ANTHROPIC_API_KEY' };
         }
-        if (model.startsWith('grok')) {
-            return optionsApiKey ?? process.env.XAI_API_KEY;
+        if (typeof model === 'string' && model.startsWith('grok')) {
+            return { key: optionsApiKey ?? process.env.XAI_API_KEY, source: 'XAI_API_KEY' };
         }
-        return undefined;
+        return { key: optionsApiKey ?? openRouterApiKey, source: optionsApiKey ? 'apiKey option' : 'OPENROUTER_API_KEY' };
     };
-    const envVar = options.model.startsWith('gpt')
-        ? isAzureOpenAI
-            ? 'AZURE_OPENAI_API_KEY (or OPENAI_API_KEY)'
-            : 'OPENAI_API_KEY'
-        : options.model.startsWith('gemini')
-            ? 'GEMINI_API_KEY'
-            : options.model.startsWith('claude')
-                ? 'ANTHROPIC_API_KEY'
-                : 'XAI_API_KEY';
-    const apiKey = getApiKeyForModel(options.model);
+    const apiKeyResult = getApiKeyForModel(options.model);
+    const apiKey = apiKeyResult.key;
     if (!apiKey) {
+        const envVar = isOpenRouterBaseUrl(baseUrl) || openRouterFallback
+            ? 'OPENROUTER_API_KEY'
+            : options.model.startsWith('gpt')
+                ? isAzureOpenAI
+                    ? 'AZURE_OPENAI_API_KEY (or OPENAI_API_KEY)'
+                    : 'OPENAI_API_KEY'
+                : options.model.startsWith('gemini')
+                    ? 'GEMINI_API_KEY'
+                    : options.model.startsWith('claude')
+                        ? 'ANTHROPIC_API_KEY'
+                        : options.model.startsWith('grok')
+                            ? 'XAI_API_KEY'
+                            : 'OPENROUTER_API_KEY';
         throw new PromptValidationError(`Missing ${envVar}. Set it via the environment or a .env file.`, {
             env: envVar,
         });
     }
+    const envVar = apiKeyResult.source;
     const minPromptLength = Number.parseInt(process.env.ORACLE_MIN_PROMPT_CHARS ?? '10', 10);
     const promptLength = options.prompt?.trim().length ?? 0;
     // Enforce the short-prompt guardrail on pro-tier models because they're costly; cheaper models can run short prompts without blocking.
-    const isProTierModel = PRO_MODELS.has(options.model);
+    const isProTierModel = isProModel(options.model);
     if (isProTierModel && !Number.isNaN(minPromptLength) && promptLength < minPromptLength) {
         throw new PromptValidationError(`Prompt is too short (<${minPromptLength} chars). This was likely accidental; please provide more detail.`, { minPromptLength, promptLength });
     }
-    const modelConfig = MODEL_CONFIGS[options.model];
-    if (!modelConfig) {
-        throw new PromptValidationError(`Unsupported model "${options.model}". Choose one of: ${Object.keys(MODEL_CONFIGS).join(', ')}`, { model: options.model });
-    }
+    const modelConfig = await resolveModelConfig(options.model, {
+        baseUrl,
+        openRouterApiKey: openRouterApiKey ?? (isOpenRouterBaseUrl(baseUrl) ? apiKey : undefined),
+    });
     const isLongRunningModel = isProTierModel;
     const supportsBackground = modelConfig.supportsBackground !== false;
     const useBackground = supportsBackground ? options.background ?? isLongRunningModel : false;
@@ -227,9 +265,11 @@ export async function runOracle(options, deps = {}) {
     }
     const apiEndpoint = modelConfig.model.startsWith('gemini')
         ? undefined
-        : modelConfig.model.startsWith('claude')
-            ? process.env.ANTHROPIC_BASE_URL ?? baseUrl
-            : baseUrl;
+        : isOpenRouterBaseUrl(baseUrl)
+            ? baseUrl
+            : modelConfig.model.startsWith('claude')
+                ? process.env.ANTHROPIC_BASE_URL ?? baseUrl
+                : baseUrl;
     const clientInstance = client ??
         clientFactory(apiKey, {
             baseUrl: apiEndpoint,
@@ -289,7 +329,15 @@ export async function runOracle(options, deps = {}) {
             elapsedMs = now() - runStart;
         }
         else {
-            const stream = await clientInstance.responses.stream(requestBody);
+            let stream;
+            try {
+                stream = await clientInstance.responses.stream(requestBody);
+            }
+            catch (streamInitError) {
+                const transportError = toTransportError(streamInitError, requestBody.model);
+                log(chalk.yellow(describeTransportError(transportError, timeoutMs)));
+                throw transportError;
+            }
             let heartbeatActive = false;
             let stopHeartbeat = null;
             const stopHeartbeatNow = () => {
@@ -348,7 +396,7 @@ export async function runOracle(options, deps = {}) {
             catch (streamError) {
                 // stream.abort() is not available on the interface
                 stopHeartbeatNow();
-                const transportError = toTransportError(streamError);
+                const transportError = toTransportError(streamError, requestBody.model);
                 log(chalk.yellow(describeTransportError(transportError, timeoutMs)));
                 throw transportError;
             }
@@ -364,7 +412,7 @@ export async function runOracle(options, deps = {}) {
     if (!response) {
         throw new Error('API did not return a response.');
     }
-    // biome-ignore lint/nursery/noUnnecessaryConditions: we only add spacing when any streamed text was printed
+    // We only add spacing when streamed text was printed.
     if (sawTextDelta && !options.silent) {
         const fullStreamedText = streamedChunks.join('');
         const shouldRenderAfterStream = isTty && !renderPlain && fullStreamedText.length > 0;
@@ -410,7 +458,7 @@ export async function runOracle(options, deps = {}) {
     }
     const answerText = extractTextOutput(response);
     if (!options.silent) {
-        // biome-ignore lint/nursery/noUnnecessaryConditions: flips true when streaming events arrive
+        // Flag flips to true when streaming events arrive.
         if (sawTextDelta) {
             // Already handled above (rendered or streamed); avoid double-printing.
         }

package/dist/src/oracle/runUtils.js

@@ -8,20 +8,24 @@ export function resolvePreviewMode(value) {
     }
     return undefined;
 }
-export function formatTokenEstimate(value, format = (text) => text) {
-    if (value >= 1000) {
-        const abbreviated = Math.floor(value / 100) / 10; // 4,252 -> 4.2
-        const text = `${abbreviated.toFixed(1).replace(/\.0$/, '')}k`;
-        return format(text);
+/**
+ * Format a token count, abbreviating thousands as e.g. 11.38k and trimming trailing zeros.
+ */
+export function formatTokenCount(value) {
+    if (Math.abs(value) >= 1000) {
+        const abbreviated = (value / 1000).toFixed(2).replace(/\.0+$/, '').replace(/\.([1-9]*)0$/, '.$1');
+        return `${abbreviated}k`;
     }
-    const text = value.toLocaleString();
-    return format(text);
+    return value.toLocaleString();
+}
+export function formatTokenEstimate(value, format = (text) => text) {
+    return format(formatTokenCount(value));
 }
 export function formatTokenValue(value, usage, index) {
     const estimatedFlag = (index === 0 && usage?.input_tokens == null) ||
         (index === 1 && usage?.output_tokens == null) ||
         (index === 2 && usage?.reasoning_tokens == null) ||
         (index === 3 && usage?.total_tokens == null);
-    const text = value.toLocaleString();
+    const text = formatTokenCount(value);
     return estimatedFlag ? `${text}*` : text;
 }