@indykish/oracle 0.9.0

package/dist/src/oracle/background.js

@@ -0,0 +1,141 @@
+import { APIConnectionError, APIConnectionTimeoutError } from 'openai';
+import chalk from 'chalk';
+import { formatElapsed } from './format.js';
+import { startHeartbeat } from '../heartbeat.js';
+import { OracleResponseError, OracleTransportError, describeTransportError, toTransportError, } from './errors.js';
+const BACKGROUND_POLL_INTERVAL_MS = 5000;
+const BACKGROUND_RETRY_BASE_MS = 3000;
+const BACKGROUND_RETRY_MAX_MS = 15000;
+export async function executeBackgroundResponse(params) {
+    const { client, requestBody, log, wait, heartbeatIntervalMs, now, maxWaitMs } = params;
+    let initialResponse;
+    try {
+        initialResponse = await client.responses.create(requestBody);
+    }
+    catch (error) {
+        const transportError = toTransportError(error, requestBody.model);
+        log(chalk.yellow(describeTransportError(transportError, maxWaitMs)));
+        throw transportError;
+    }
+    if (!initialResponse || !initialResponse.id) {
+        throw new OracleResponseError('API did not return a response ID for the background run.', initialResponse);
+    }
+    const responseId = initialResponse.id;
+    log(chalk.dim(`API scheduled background response ${responseId} (status=${initialResponse.status ?? 'unknown'}). Monitoring up to ${Math.round(maxWaitMs / 60000)} minutes for completion...`));
+    let heartbeatActive = false;
+    let stopHeartbeat = null;
+    const stopHeartbeatNow = () => {
+        if (!heartbeatActive)
+            return;
+        heartbeatActive = false;
+        stopHeartbeat?.();
+        stopHeartbeat = null;
+    };
+    if (heartbeatIntervalMs && heartbeatIntervalMs > 0) {
+        heartbeatActive = true;
+        stopHeartbeat = startHeartbeat({
+            intervalMs: heartbeatIntervalMs,
+            log: (message) => log(message),
+            isActive: () => heartbeatActive,
+            makeMessage: (elapsedMs) => {
+                const elapsedText = formatElapsed(elapsedMs);
+                return `API background run still in progress — ${elapsedText} elapsed.`;
+            },
+        });
+    }
+    try {
+        return await pollBackgroundResponse({
+            client,
+            responseId,
+            initialResponse,
+            log,
+            wait,
+            now,
+            maxWaitMs,
+        });
+    }
+    finally {
+        stopHeartbeatNow();
+    }
+}
+async function pollBackgroundResponse(params) {
+    const { client, responseId, initialResponse, log, wait, now, maxWaitMs } = params;
+    const startMark = now();
+    let response = initialResponse;
+    let firstCycle = true;
+    let lastStatus = response.status;
+    // biome-ignore lint/nursery/noUnnecessaryConditions: intentional polling loop.
+    while (true) {
+        const status = response.status ?? 'completed';
+        // firstCycle toggles immediately; keep for clarity in logs.
+        if (firstCycle) {
+            firstCycle = false;
+            log(chalk.dim(`API background response status=${status}. We'll keep retrying automatically.`));
+        }
+        else if (status !== lastStatus && status !== 'completed') {
+            log(chalk.dim(`API background response status=${status}.`));
+        }
+        lastStatus = status;
+        if (status === 'completed') {
+            return response;
+        }
+        if (status !== 'in_progress' && status !== 'queued') {
+            const detail = response.error?.message || response.incomplete_details?.reason || status;
+            throw new OracleResponseError(`Response did not complete: ${detail}`, response);
+        }
+        if (now() - startMark >= maxWaitMs) {
+            throw new OracleTransportError('client-timeout', 'Timed out waiting for API background response to finish.');
+        }
+        await wait(BACKGROUND_POLL_INTERVAL_MS);
+        if (now() - startMark >= maxWaitMs) {
+            throw new OracleTransportError('client-timeout', 'Timed out waiting for API background response to finish.');
+        }
+        const { response: nextResponse, reconnected } = await retrieveBackgroundResponseWithRetry({
+            client,
+            responseId,
+            wait,
+            now,
+            maxWaitMs,
+            startMark,
+            log,
+        });
+        if (reconnected) {
+            const nextStatus = nextResponse.status ?? 'in_progress';
+            log(chalk.dim(`Reconnected to API background response (status=${nextStatus}). API is still working...`));
+        }
+        response = nextResponse;
+    }
+}
+async function retrieveBackgroundResponseWithRetry(params) {
+    const { client, responseId, wait, now, maxWaitMs, startMark, log } = params;
+    let retries = 0;
+    // biome-ignore lint/nursery/noUnnecessaryConditions: intentional retry loop
+    while (true) {
+        try {
+            const next = await client.responses.retrieve(responseId);
+            return { response: next, reconnected: retries > 0 };
+        }
+        catch (error) {
+            const transportError = asRetryableTransportError(error);
+            if (!transportError) {
+                throw error;
+            }
+            retries += 1;
+            const delay = Math.min(BACKGROUND_RETRY_BASE_MS * 2 ** (retries - 1), BACKGROUND_RETRY_MAX_MS);
+            log(chalk.yellow(`${describeTransportError(transportError, maxWaitMs)} Retrying in ${formatElapsed(delay)}...`));
+            await wait(delay);
+            if (now() - startMark >= maxWaitMs) {
+                throw new OracleTransportError('client-timeout', 'Timed out waiting for API background response to finish.');
+            }
+        }
+    }
+}
+function asRetryableTransportError(error) {
+    if (error instanceof OracleTransportError) {
+        return error;
+    }
+    if (error instanceof APIConnectionError || error instanceof APIConnectionTimeoutError) {
+        return toTransportError(error);
+    }
+    return null;
+}

package/dist/src/oracle/claude.js

@@ -0,0 +1,101 @@
+const DEFAULT_CLAUDE_ENDPOINT = 'https://api.anthropic.com/v1/messages';
+const ANTHROPIC_VERSION = '2023-06-01';
+function extractPrompt(body) {
+    const first = body.input?.[0]?.content?.[0];
+    if (first && first.type === 'input_text') {
+        return first.text ?? '';
+    }
+    return '';
+}
+async function callClaude({ apiKey, model, prompt, endpoint, stream = false, }) {
+    const url = endpoint?.trim() || DEFAULT_CLAUDE_ENDPOINT;
+    const payload = {
+        model,
+        max_tokens: 2048,
+        messages: [
+            {
+                role: 'user',
+                content: prompt,
+            },
+        ],
+        stream,
+    };
+    return fetch(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': ANTHROPIC_VERSION,
+        },
+        body: JSON.stringify(payload),
+    });
+}
+async function parseClaudeResponse(raw) {
+    const json = (await raw.json());
+    if (json.error) {
+        throw new Error(json.error.message || 'Claude request failed');
+    }
+    const textParts = json.content?.map((part) => part.text ?? '').filter(Boolean) ?? [];
+    const outputText = textParts.join('');
+    return {
+        id: json.id ?? `claude-${Date.now()}`,
+        status: 'completed',
+        output_text: [outputText],
+        output: [{ type: 'text', text: outputText }],
+        usage: {
+            input_tokens: json.usage?.input_tokens ?? 0,
+            output_tokens: json.usage?.output_tokens ?? 0,
+            total_tokens: (json.usage?.input_tokens ?? 0) + (json.usage?.output_tokens ?? 0),
+        },
+    };
+}
+export function createClaudeClient(apiKey, modelName, resolvedModelId, baseUrl) {
+    const modelId = resolveClaudeModelId(resolvedModelId ?? modelName);
+    const stream = async (body) => {
+        const prompt = extractPrompt(body);
+        const resp = await callClaude({ apiKey, model: modelId, prompt, stream: false, endpoint: baseUrl });
+        const parsed = await parseClaudeResponse(resp);
+        const iterator = async function* () {
+            if (parsed.output_text?.[0]) {
+                yield { type: 'response.output_text.delta', delta: parsed.output_text[0] };
+            }
+            return;
+        };
+        return {
+            [Symbol.asyncIterator]: () => iterator(),
+            finalResponse: async () => parsed,
+        };
+    };
+    const create = async (body) => {
+        const prompt = extractPrompt(body);
+        const resp = await callClaude({ apiKey, model: modelId, prompt, stream: false, endpoint: baseUrl });
+        return parseClaudeResponse(resp);
+    };
+    const retrieve = async (id) => ({
+        id,
+        status: 'error',
+        error: { message: 'Retrieve by ID not supported for Claude API yet.' },
+    });
+    return {
+        responses: {
+            stream,
+            create,
+            retrieve,
+        },
+    };
+}
+export function resolveClaudeModelId(modelName) {
+    if (modelName === 'claude-4.6-sonnet') {
+        return 'claude-sonnet-4-6';
+    }
+    if (modelName === 'claude-4.6-opus') {
+        return 'claude-opus-4-6';
+    }
+    if (modelName === 'claude-4.5-sonnet' || modelName === 'claude-sonnet-4-5-20241022') {
+        return 'claude-sonnet-4-5';
+    }
+    if (modelName === 'claude-4.1-opus' || modelName === 'claude-opus-4-1-20240808') {
+        return 'claude-opus-4-1';
+    }
+    return modelName;
+}

package/dist/src/oracle/client.js

@@ -0,0 +1,197 @@
+import OpenAI, { AzureOpenAI } from 'openai';
+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)
+        return customFactory;
+    return (key, options) => {
+        if (options?.model?.startsWith('gemini')) {
+            // Gemini client uses its own SDK; allow passing the already-resolved id for transparency/logging.
+            return createGeminiClient(key, options.model, options.resolvedModelId);
+        }
+        if (options?.model?.startsWith('claude')) {
+            return createClaudeClient(key, options.model, options.resolvedModelId, options.baseUrl);
+        }
+        let instance;
+        const openRouter = isOpenRouterBaseUrl(options?.baseUrl);
+        const defaultHeaders = openRouter ? buildOpenRouterHeaders() : undefined;
+        const httpTimeoutMs = typeof options?.httpTimeoutMs === 'number' && Number.isFinite(options.httpTimeoutMs) && options.httpTimeoutMs > 0
+            ? options.httpTimeoutMs
+            : 20 * 60 * 1000;
+        if (options?.azure?.endpoint) {
+            instance = new AzureOpenAI({
+                apiKey: key,
+                endpoint: options.azure.endpoint,
+                apiVersion: options.azure.apiVersion,
+                deployment: options.azure.deployment,
+                timeout: httpTimeoutMs,
+            });
+        }
+        else {
+            instance = new OpenAI({
+                apiKey: key,
+                timeout: httpTimeoutMs,
+                baseURL: options?.baseUrl,
+                defaultHeaders,
+            });
+        }
+        if (openRouter) {
+            return buildOpenRouterCompletionClient(instance);
+        }
+        return {
+            responses: {
+                stream: (body) => instance.responses.stream(body),
+                create: (body) => instance.responses.create(body),
+                retrieve: (id) => instance.responses.retrieve(id),
+            },
+        };
+    };
+}
+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) {
+        return null;
+    }
+    if (override === 'INLINE_TEST_FACTORY') {
+        return () => ({
+            responses: {
+                create: async () => ({ id: 'inline-test', status: 'completed' }),
+                stream: async () => ({
+                    [Symbol.asyncIterator]: () => ({
+                        async next() {
+                            return { done: true, value: undefined };
+                        },
+                    }),
+                    finalResponse: async () => ({ id: 'inline-test', status: 'completed' }),
+                }),
+                retrieve: async (id) => ({ id, status: 'completed' }),
+            },
+        });
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const resolved = path.isAbsolute(override) ? override : path.resolve(process.cwd(), override);
+        const moduleExports = require(resolved);
+        const factory = typeof moduleExports === 'function'
+            ? moduleExports
+            : typeof moduleExports?.default === 'function'
+                ? moduleExports.default
+                : typeof moduleExports?.createClientFactory === 'function'
+                    ? moduleExports.createClientFactory
+                    : null;
+        if (typeof factory === 'function') {
+            return factory;
+        }
+        console.warn(`Custom client factory at ${resolved} did not export a function.`);
+    }
+    catch (error) {
+        console.warn(`Failed to load ORACLE_CLIENT_FACTORY module "${override}":`, error);
+    }
+    return null;
+}
+// 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

@@ -0,0 +1,227 @@
+import { countTokens as countTokensGpt5 } from 'gpt-tokenizer/model/gpt-5';
+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.2-pro';
+export const PRO_MODELS = new Set(['gpt-5.1-pro', 'gpt-5-pro', 'gpt-5.2-pro', 'gpt-5.3-pro', 'claude-4.5-sonnet', 'claude-4.6-sonnet', 'claude-4.1-opus', 'claude-4.6-opus']);
+const countTokensAnthropic = (input) => countTokensAnthropicRaw(stringifyTokenizerInput(input));
+export const MODEL_CONFIGS = {
+    'gpt-5.1-pro': {
+        model: 'gpt-5.1-pro',
+        apiModel: 'gpt-5.2-pro',
+        provider: 'openai',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 21 / 1_000_000,
+            outputPerToken: 168 / 1_000_000,
+        },
+        reasoning: null,
+    },
+    'gpt-5-pro': {
+        model: 'gpt-5-pro',
+        provider: 'openai',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 15 / 1_000_000,
+            outputPerToken: 120 / 1_000_000,
+        },
+        reasoning: null,
+    },
+    'gpt-5.1': {
+        model: 'gpt-5.1',
+        provider: 'openai',
+        tokenizer: countTokensGpt5,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 1.25 / 1_000_000,
+            outputPerToken: 10 / 1_000_000,
+        },
+        reasoning: { effort: 'high' },
+    },
+    'gpt-5.1-codex': {
+        model: 'gpt-5.1-codex',
+        provider: 'openai',
+        tokenizer: countTokensGpt5,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 1.25 / 1_000_000,
+            outputPerToken: 10 / 1_000_000,
+        },
+        reasoning: { effort: 'high' },
+    },
+    'gpt-5.2': {
+        model: 'gpt-5.2',
+        provider: 'openai',
+        tokenizer: countTokensGpt5,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 1.75 / 1_000_000,
+            outputPerToken: 14 / 1_000_000,
+        },
+        reasoning: { effort: 'xhigh' },
+    },
+    'gpt-5.2-instant': {
+        model: 'gpt-5.2-instant',
+        apiModel: 'gpt-5.2-chat-latest',
+        provider: 'openai',
+        tokenizer: countTokensGpt5,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 1.75 / 1_000_000,
+            outputPerToken: 14 / 1_000_000,
+        },
+        reasoning: null,
+    },
+    'gpt-5.2-pro': {
+        model: 'gpt-5.2-pro',
+        provider: 'openai',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 21 / 1_000_000,
+            outputPerToken: 168 / 1_000_000,
+        },
+        reasoning: { effort: 'xhigh' },
+    },
+    'gpt-5.3': {
+        model: 'gpt-5.3',
+        provider: 'openai',
+        tokenizer: countTokensGpt5,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 2 / 1_000_000,
+            outputPerToken: 16 / 1_000_000,
+        },
+        reasoning: { effort: 'xhigh' },
+    },
+    'gpt-5.3-pro': {
+        model: 'gpt-5.3-pro',
+        provider: 'openai',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 25 / 1_000_000,
+            outputPerToken: 200 / 1_000_000,
+        },
+        reasoning: { effort: 'xhigh' },
+    },
+    'gemini-3-pro': {
+        model: 'gemini-3-pro',
+        provider: 'google',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 200000,
+        pricing: {
+            inputPerToken: 2 / 1_000_000,
+            outputPerToken: 12 / 1_000_000,
+        },
+        reasoning: null,
+        supportsBackground: false,
+        supportsSearch: true,
+    },
+    'gemini-3.5-pro': {
+        model: 'gemini-3.5-pro',
+        provider: 'google',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 200000,
+        pricing: {
+            inputPerToken: 3 / 1_000_000,
+            outputPerToken: 18 / 1_000_000,
+        },
+        reasoning: null,
+        supportsBackground: false,
+        supportsSearch: true,
+    },
+    'claude-4.5-sonnet': {
+        model: 'claude-4.5-sonnet',
+        apiModel: 'claude-sonnet-4-5',
+        provider: 'anthropic',
+        tokenizer: countTokensAnthropic,
+        inputLimit: 200000,
+        pricing: {
+            inputPerToken: 3 / 1_000_000,
+            outputPerToken: 15 / 1_000_000,
+        },
+        reasoning: null,
+        supportsBackground: false,
+        supportsSearch: false,
+    },
+    'claude-4.1-opus': {
+        model: 'claude-4.1-opus',
+        apiModel: 'claude-opus-4-1',
+        provider: 'anthropic',
+        tokenizer: countTokensAnthropic,
+        inputLimit: 200000,
+        pricing: {
+            inputPerToken: 15 / 1_000_000,
+            outputPerToken: 75 / 1_000_000,
+        },
+        reasoning: { effort: 'high' },
+        supportsBackground: false,
+        supportsSearch: false,
+    },
+    'claude-4.6-sonnet': {
+        model: 'claude-4.6-sonnet',
+        apiModel: 'claude-sonnet-4-6',
+        provider: 'anthropic',
+        tokenizer: countTokensAnthropic,
+        inputLimit: 200000,
+        pricing: {
+            inputPerToken: 3 / 1_000_000,
+            outputPerToken: 15 / 1_000_000,
+        },
+        reasoning: null,
+        supportsBackground: false,
+        supportsSearch: false,
+    },
+    'claude-4.6-opus': {
+        model: 'claude-4.6-opus',
+        apiModel: 'claude-opus-4-6',
+        provider: 'anthropic',
+        tokenizer: countTokensAnthropic,
+        inputLimit: 200000,
+        pricing: {
+            inputPerToken: 15 / 1_000_000,
+            outputPerToken: 75 / 1_000_000,
+        },
+        reasoning: { effort: 'high' },
+        supportsBackground: false,
+        supportsSearch: false,
+    },
+    'grok-4.1': {
+        model: 'grok-4.1',
+        apiModel: 'grok-4-1-fast-reasoning',
+        provider: 'xai',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 2_000_000,
+        pricing: {
+            inputPerToken: 0.2 / 1_000_000,
+            outputPerToken: 0.5 / 1_000_000,
+        },
+        reasoning: null,
+        supportsBackground: false,
+        supportsSearch: true,
+        searchToolType: 'web_search',
+    },
+    'grok-4.2': {
+        model: 'grok-4.2',
+        apiModel: 'grok-4-2',
+        provider: 'xai',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 2_000_000,
+        pricing: {
+            inputPerToken: 0.3 / 1_000_000,
+            outputPerToken: 1.0 / 1_000_000,
+        },
+        reasoning: null,
+        supportsBackground: false,
+        supportsSearch: true,
+        searchToolType: 'web_search',
+    },
+};
+export const DEFAULT_SYSTEM_PROMPT = [
+    'You are Oracle, a focused one-shot problem solver.',
+    'Emphasize direct answers and cite any files referenced.',
+].join(' ');
+export const TOKENIZER_OPTIONS = { allowedSpecial: 'all' };