@steipete/oracle 0.4.5 → 0.5.1

package/dist/src/oracle/client.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import { createGeminiClient } from './gemini.js';
 import { createClaudeClient } from './claude.js';
+import { isOpenRouterBaseUrl } from './modelResolver.js';
 export function createDefaultClientFactory() {
     const customFactory = loadCustomClientFactory();
     if (customFactory)
@@ -16,6 +17,8 @@ export function createDefaultClientFactory() {
             return createClaudeClient(key, options.model, options.resolvedModelId, options.baseUrl);
         }
         let instance;
+        const openRouter = isOpenRouterBaseUrl(options?.baseUrl);
+        const defaultHeaders = openRouter ? buildOpenRouterHeaders() : undefined;
         if (options?.azure?.endpoint) {
             instance = new AzureOpenAI({
                 apiKey: key,
@@ -30,8 +33,12 @@ export function createDefaultClientFactory() {
                 apiKey: key,
                 timeout: 20 * 60 * 1000,
                 baseURL: options?.baseUrl,
+                defaultHeaders,
             });
         }
+        if (openRouter) {
+            return buildOpenRouterCompletionClient(instance);
+        }
         return {
             responses: {
                 stream: (body) => instance.responses.stream(body),
@@ -41,6 +48,18 @@ export function createDefaultClientFactory() {
         };
     };
 }
+function buildOpenRouterHeaders() {
+    const headers = {};
+    const referer = process.env.OPENROUTER_REFERER ?? process.env.OPENROUTER_HTTP_REFERER ?? 'https://github.com/steipete/oracle';
+    const title = process.env.OPENROUTER_TITLE ?? 'Oracle CLI';
+    if (referer) {
+        headers['HTTP-Referer'] = referer;
+    }
+    if (title) {
+        headers['X-Title'] = title;
+    }
+    return headers;
+}
 function loadCustomClientFactory() {
     const override = process.env.ORACLE_CLIENT_FACTORY;
     if (!override) {
@@ -85,3 +104,91 @@ function loadCustomClientFactory() {
 }
 // Exposed for tests
 export { loadCustomClientFactory as __loadCustomClientFactory };
+function buildOpenRouterCompletionClient(instance) {
+    const adaptRequest = (body) => {
+        const messages = [];
+        if (body.instructions) {
+            messages.push({ role: 'system', content: body.instructions });
+        }
+        for (const entry of body.input) {
+            const textParts = entry.content
+                .map((c) => (c.type === 'input_text' ? c.text : ''))
+                .filter((t) => t)
+                .join('\n\n');
+            messages.push({ role: entry.role ?? 'user', content: textParts });
+        }
+        const base = {
+            model: body.model,
+            messages,
+            max_tokens: body.max_output_tokens,
+        };
+        const streaming = { ...base, stream: true };
+        const nonStreaming = { ...base, stream: false };
+        return { streaming, nonStreaming };
+    };
+    const adaptResponse = (response) => {
+        const text = response.choices?.[0]?.message?.content ?? '';
+        const usage = {
+            input_tokens: response.usage?.prompt_tokens ?? 0,
+            output_tokens: response.usage?.completion_tokens ?? 0,
+            total_tokens: response.usage?.total_tokens ?? 0,
+        };
+        return {
+            id: response.id ?? `openrouter-${Date.now()}`,
+            status: 'completed',
+            output_text: [text],
+            output: [{ type: 'text', text }],
+            usage,
+        };
+    };
+    const stream = async (body) => {
+        const { streaming } = adaptRequest(body);
+        let finalUsage;
+        let finalId;
+        let aggregated = '';
+        async function* iterator() {
+            const completion = await instance.chat.completions.create(streaming);
+            for await (const chunk of completion) {
+                finalId = chunk.id ?? finalId;
+                const delta = chunk.choices?.[0]?.delta?.content ?? '';
+                if (delta) {
+                    aggregated += delta;
+                    yield { type: 'chunk', delta };
+                }
+                if (chunk.usage) {
+                    finalUsage = chunk.usage;
+                }
+            }
+        }
+        const gen = iterator();
+        return {
+            [Symbol.asyncIterator]() {
+                return gen;
+            },
+            async finalResponse() {
+                return adaptResponse({
+                    id: finalId ?? `openrouter-${Date.now()}`,
+                    choices: [{ message: { role: 'assistant', content: aggregated } }],
+                    usage: finalUsage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+                    created: Math.floor(Date.now() / 1000),
+                    model: '',
+                    object: 'chat.completion',
+                });
+            },
+        };
+    };
+    const create = async (body) => {
+        const { nonStreaming } = adaptRequest(body);
+        const response = (await instance.chat.completions.create(nonStreaming));
+        return adaptResponse(response);
+    };
+    return {
+        responses: {
+            stream,
+            create,
+            retrieve: async () => {
+                throw new Error('retrieve is not supported for OpenRouter chat/completions fallback.');
+            },
+        },
+    };
+}

package/dist/src/oracle/config.js

@@ -3,11 +3,12 @@ import { countTokens as countTokensGpt5Pro } from 'gpt-tokenizer/model/gpt-5-pro
 import { countTokens as countTokensAnthropicRaw } from '@anthropic-ai/tokenizer';
 import { stringifyTokenizerInput } from './tokenStringifier.js';
 export const DEFAULT_MODEL = 'gpt-5.1-pro';
-export const PRO_MODELS = new Set(['gpt-5.1-pro', 'gpt-5-pro', 'claude-4.1-opus']);
+export const PRO_MODELS = new Set(['gpt-5.1-pro', 'gpt-5-pro', 'claude-4.5-sonnet', 'claude-4.1-opus']);
 const countTokensAnthropic = (input) => countTokensAnthropicRaw(stringifyTokenizerInput(input));
 export const MODEL_CONFIGS = {
     'gpt-5.1-pro': {
         model: 'gpt-5.1-pro',
+        provider: 'openai',
         tokenizer: countTokensGpt5Pro,
         inputLimit: 196000,
         pricing: {
@@ -18,6 +19,7 @@ export const MODEL_CONFIGS = {
     },
     'gpt-5-pro': {
         model: 'gpt-5-pro',
+        provider: 'openai',
         tokenizer: countTokensGpt5Pro,
         inputLimit: 196000,
         pricing: {
@@ -28,6 +30,7 @@ export const MODEL_CONFIGS = {
     },
     'gpt-5.1': {
         model: 'gpt-5.1',
+        provider: 'openai',
         tokenizer: countTokensGpt5,
         inputLimit: 196000,
         pricing: {
@@ -38,6 +41,7 @@ export const MODEL_CONFIGS = {
     },
     'gpt-5.1-codex': {
         model: 'gpt-5.1-codex',
+        provider: 'openai',
         tokenizer: countTokensGpt5,
         inputLimit: 196000,
         pricing: {
@@ -48,6 +52,7 @@ export const MODEL_CONFIGS = {
     },
     'gemini-3-pro': {
         model: 'gemini-3-pro',
+        provider: 'google',
         tokenizer: countTokensGpt5Pro,
         inputLimit: 200000,
         pricing: {
@@ -61,6 +66,7 @@ export const MODEL_CONFIGS = {
     'claude-4.5-sonnet': {
         model: 'claude-4.5-sonnet',
         apiModel: 'claude-sonnet-4-5',
+        provider: 'anthropic',
         tokenizer: countTokensAnthropic,
         inputLimit: 200000,
         pricing: {
@@ -74,6 +80,7 @@ export const MODEL_CONFIGS = {
     'claude-4.1-opus': {
         model: 'claude-4.1-opus',
         apiModel: 'claude-opus-4-1',
+        provider: 'anthropic',
         tokenizer: countTokensAnthropic,
         inputLimit: 200000,
         pricing: {
@@ -87,6 +94,7 @@ export const MODEL_CONFIGS = {
     'grok-4.1': {
         model: 'grok-4.1',
         apiModel: 'grok-4-1-fast-reasoning',
+        provider: 'xai',
         tokenizer: countTokensGpt5Pro,
         inputLimit: 2_000_000,
         pricing: {
@@ -101,6 +109,6 @@ export const MODEL_CONFIGS = {
 };
 export const DEFAULT_SYSTEM_PROMPT = [
     'You are Oracle, a focused one-shot problem solver.',
-    'Emphasize direct answers, cite any files referenced, and clearly note when the search tool was used.',
+    'Emphasize direct answers and cite any files referenced.',
 ].join(' ');
 export const TOKENIZER_OPTIONS = { allowedSpecial: 'all' };

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,62 @@ 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 resolverOpenRouterApiKey = openRouterFallback || isOpenRouterBaseUrl(baseUrl) ? openRouterApiKey ?? apiKey : undefined;
+    const modelConfig = await resolveModelConfig(options.model, {
+        baseUrl,
+        openRouterApiKey: resolverOpenRouterApiKey,
+    });
     const isLongRunningModel = isProTierModel;
     const supportsBackground = modelConfig.supportsBackground !== false;
     const useBackground = supportsBackground ? options.background ?? isLongRunningModel : false;
@@ -227,9 +266,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 +330,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 +397,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 +413,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 +459,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;
 }