@steipete/oracle 0.18.0 → 0.19.0

package/dist/oracle/src/oracle/run.js

@@ -1,444 +0,0 @@
-import chalk from 'chalk';
-import kleur from 'kleur';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import process from 'node:process';
-import { performance } from 'node:perf_hooks';
-import { APIConnectionError, APIConnectionTimeoutError } from 'openai';
-import { DEFAULT_SYSTEM_PROMPT, MODEL_CONFIGS, TOKENIZER_OPTIONS } from './config.js';
-import { readFiles } from './files.js';
-import { buildPrompt, buildRequestBody } from './request.js';
-import { formatElapsed, formatUSD } from './format.js';
-import { getFileTokenStats, printFileTokenStats } from './tokenStats.js';
-import { OracleResponseError, OracleTransportError, PromptValidationError, describeTransportError, toTransportError, } from './errors.js';
-import { createDefaultClientFactory } from './client.js';
-import { startHeartbeat } from '../heartbeat.js';
-import { startOscProgress } from './oscProgress.js';
-import { getCliVersion } from '../version.js';
-import { createFsAdapter } from './fsAdapter.js';
-const isTty = process.stdout.isTTY;
-const dim = (text) => (isTty ? kleur.dim(text) : text);
-const BACKGROUND_MAX_WAIT_MS = 30 * 60 * 1000;
-const BACKGROUND_POLL_INTERVAL_MS = 5000;
-const BACKGROUND_RETRY_BASE_MS = 3000;
-const BACKGROUND_RETRY_MAX_MS = 15000;
-const defaultWait = (ms) => new Promise((resolve) => {
-    setTimeout(resolve, ms);
-});
-export async function runOracle(options, deps = {}) {
-    const { apiKey = options.apiKey ?? process.env.OPENAI_API_KEY, cwd = process.cwd(), fs: fsModule = createFsAdapter(fs), log = console.log, write = (text) => process.stdout.write(text), now = () => performance.now(), clientFactory = createDefaultClientFactory(), client, wait = defaultWait, } = deps;
-    const maskApiKey = (key) => {
-        if (!key)
-            return null;
-        if (key.length <= 8)
-            return `${key[0] ?? ''}***${key[key.length - 1] ?? ''}`;
-        const prefix = key.slice(0, 4);
-        const suffix = key.slice(-4);
-        return `${prefix}****${suffix}`;
-    };
-    const logVerbose = (message) => {
-        if (options.verbose) {
-            log(dim(`[verbose] ${message}`));
-        }
-    };
-    const previewMode = resolvePreviewMode(options.previewMode ?? options.preview);
-    const isPreview = Boolean(previewMode);
-    if (!apiKey) {
-        throw new PromptValidationError('Missing OPENAI_API_KEY. Set it via the environment or a .env file.', {
-            env: 'OPENAI_API_KEY',
-        });
-    }
-    const maskedKey = maskApiKey(apiKey);
-    if (maskedKey) {
-        log(dim(`Using OPENAI_API_KEY=${maskedKey}`));
-    }
-    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 useBackground = options.background ?? (options.model === 'gpt-5-pro');
-    const inputTokenBudget = options.maxInput ?? modelConfig.inputLimit;
-    const files = await readFiles(options.file ?? [], { cwd, fsModule });
-    const searchEnabled = options.search !== false;
-    logVerbose(`cwd: ${cwd}`);
-    if (files.length > 0) {
-        const displayPaths = files
-            .map((file) => path.relative(cwd, file.path) || file.path)
-            .slice(0, 10)
-            .join(', ');
-        const extra = files.length > 10 ? ` (+${files.length - 10} more)` : '';
-        logVerbose(`Attached files (${files.length}): ${displayPaths}${extra}`);
-    }
-    else {
-        logVerbose('No files attached.');
-        if (!isPreview) {
-            log(dim('Tip: no files attached — Oracle works best with project context. Add files via --file path/to/code or docs.'));
-        }
-    }
-    const fileTokenInfo = getFileTokenStats(files, {
-        cwd,
-        tokenizer: modelConfig.tokenizer,
-        tokenizerOptions: TOKENIZER_OPTIONS,
-        inputTokenBudget,
-    });
-    const totalFileTokens = fileTokenInfo.totalTokens;
-    logVerbose(`Attached files use ${totalFileTokens.toLocaleString()} tokens`);
-    const systemPrompt = options.system?.trim() || DEFAULT_SYSTEM_PROMPT;
-    const promptWithFiles = buildPrompt(options.prompt, files, cwd);
-    const tokenizerInput = [
-        { role: 'system', content: systemPrompt },
-        { role: 'user', content: promptWithFiles },
-    ];
-    const estimatedInputTokens = modelConfig.tokenizer(tokenizerInput, TOKENIZER_OPTIONS);
-    logVerbose(`Estimated tokens (prompt + files): ${estimatedInputTokens.toLocaleString()}`);
-    const fileCount = files.length;
-    const cliVersion = getCliVersion();
-    const richTty = process.stdout.isTTY && chalk.level > 0;
-    const headerModelLabel = richTty ? chalk.cyan(modelConfig.model) : modelConfig.model;
-    const tokenLabel = richTty ? chalk.green(estimatedInputTokens.toLocaleString()) : estimatedInputTokens.toLocaleString();
-    const fileLabel = richTty ? chalk.magenta(fileCount.toString()) : fileCount.toString();
-    const headerLine = `Oracle (${cliVersion}) consulting ${headerModelLabel}'s crystal ball with ${tokenLabel} tokens and ${fileLabel} files...`;
-    const shouldReportFiles = (options.filesReport || fileTokenInfo.totalTokens > inputTokenBudget) && fileTokenInfo.stats.length > 0;
-    if (!isPreview) {
-        log(headerLine);
-        if (options.model === 'gpt-5-pro') {
-            log(dim('Pro is thinking, this can take up to 30 minutes...'));
-        }
-        log(dim('Press Ctrl+C to cancel.'));
-    }
-    if (shouldReportFiles) {
-        printFileTokenStats(fileTokenInfo, { inputTokenBudget, log });
-    }
-    if (estimatedInputTokens > inputTokenBudget) {
-        throw new PromptValidationError(`Input too large (${estimatedInputTokens.toLocaleString()} tokens). Limit is ${inputTokenBudget.toLocaleString()} tokens.`, { estimatedInputTokens, inputTokenBudget });
-    }
-    const requestBody = buildRequestBody({
-        modelConfig,
-        systemPrompt,
-        userPrompt: promptWithFiles,
-        searchEnabled,
-        maxOutputTokens: options.maxOutput,
-        background: useBackground,
-        storeResponse: useBackground,
-    });
-    if (isPreview && previewMode) {
-        if (previewMode === 'json' || previewMode === 'full') {
-            log('Request JSON');
-            log(JSON.stringify(requestBody, null, 2));
-            log('');
-        }
-        if (previewMode === 'full') {
-            log('Assembled Prompt');
-            log(promptWithFiles);
-            log('');
-        }
-        log(`Estimated input tokens: ${estimatedInputTokens.toLocaleString()} / ${inputTokenBudget.toLocaleString()} (model: ${modelConfig.model})`);
-        return {
-            mode: 'preview',
-            previewMode,
-            requestBody,
-            estimatedInputTokens,
-            inputTokenBudget,
-        };
-    }
-    const openAiClient = client ?? clientFactory(apiKey);
-    logVerbose('Dispatching request to OpenAI Responses API...');
-    const stopOscProgress = startOscProgress({
-        label: useBackground ? 'Waiting for OpenAI (background)' : 'Waiting for OpenAI',
-        targetMs: useBackground ? BACKGROUND_MAX_WAIT_MS : 10 * 60_000,
-        write,
-    });
-    const runStart = now();
-    let response = null;
-    let elapsedMs = 0;
-    let sawTextDelta = false;
-    let answerHeaderPrinted = false;
-    const ensureAnswerHeader = () => {
-        if (!options.silent && !answerHeaderPrinted) {
-            log('');
-            log(chalk.bold('Answer:'));
-            answerHeaderPrinted = true;
-        }
-    };
-    try {
-        if (useBackground) {
-            response = await executeBackgroundResponse({
-                client: openAiClient,
-                requestBody,
-                log,
-                wait,
-                heartbeatIntervalMs: options.heartbeatIntervalMs,
-                now,
-            });
-            elapsedMs = now() - runStart;
-        }
-        else {
-            const stream = await openAiClient.responses.stream(requestBody);
-            let heartbeatActive = false;
-            let stopHeartbeat = null;
-            const stopHeartbeatNow = () => {
-                if (!heartbeatActive) {
-                    return;
-                }
-                heartbeatActive = false;
-                stopHeartbeat?.();
-                stopHeartbeat = null;
-            };
-            if (options.heartbeatIntervalMs && options.heartbeatIntervalMs > 0) {
-                heartbeatActive = true;
-                stopHeartbeat = startHeartbeat({
-                    intervalMs: options.heartbeatIntervalMs,
-                    log: (message) => log(message),
-                    isActive: () => heartbeatActive,
-                    makeMessage: (elapsedMs) => {
-                        const elapsedText = formatElapsed(elapsedMs);
-                        return `API connection active — ${elapsedText} elapsed. Expect up to ~10 min before GPT-5 responds.`;
-                    },
-                });
-            }
-            try {
-                for await (const event of stream) {
-                    if (event.type === 'response.output_text.delta') {
-                        stopOscProgress();
-                        stopHeartbeatNow();
-                        sawTextDelta = true;
-                        ensureAnswerHeader();
-                        if (!options.silent && typeof event.delta === 'string') {
-                            write(event.delta);
-                        }
-                    }
-                }
-            }
-            catch (streamError) {
-                if (typeof stream.abort === 'function') {
-                    stream.abort();
-                }
-                stopHeartbeatNow();
-                const transportError = toTransportError(streamError);
-                log(chalk.yellow(describeTransportError(transportError)));
-                throw transportError;
-            }
-            response = await stream.finalResponse();
-            stopHeartbeatNow();
-            elapsedMs = now() - runStart;
-        }
-    }
-    finally {
-        stopOscProgress();
-    }
-    if (!response) {
-        throw new Error('OpenAI did not return a response.');
-    }
-    logVerbose(`Response status: ${response.status ?? 'completed'}`);
-    if (response.status && response.status !== 'completed') {
-        const detail = response.error?.message || response.incomplete_details?.reason || response.status;
-        log(chalk.yellow(`OpenAI ended the run early (status=${response.status}${response.incomplete_details?.reason ? `, reason=${response.incomplete_details.reason}` : ''}).`));
-        throw new OracleResponseError(`Response did not complete: ${detail}`, response);
-    }
-    const answerText = extractTextOutput(response);
-    if (!options.silent) {
-        // biome-ignore lint/nursery/noUnnecessaryConditions: flips true when streaming events arrive
-        if (sawTextDelta) {
-            write('\n\n');
-        }
-        else {
-            ensureAnswerHeader();
-            log(answerText || chalk.dim('(no text output)'));
-            log('');
-        }
-    }
-    const usage = response.usage ?? {};
-    const inputTokens = usage.input_tokens ?? estimatedInputTokens;
-    const outputTokens = usage.output_tokens ?? 0;
-    const reasoningTokens = usage.reasoning_tokens ?? 0;
-    const totalTokens = usage.total_tokens ?? inputTokens + outputTokens + reasoningTokens;
-    const cost = inputTokens * modelConfig.pricing.inputPerToken + outputTokens * modelConfig.pricing.outputPerToken;
-    const elapsedDisplay = formatElapsed(elapsedMs);
-    const statsParts = [];
-    const modelLabel = modelConfig.model + (modelConfig.reasoning ? '[high]' : '');
-    statsParts.push(modelLabel);
-    statsParts.push(formatUSD(cost));
-    const tokensDisplay = [inputTokens, outputTokens, reasoningTokens, totalTokens]
-        .map((value, index) => formatTokenValue(value, usage, index))
-        .join('/');
-    statsParts.push(`tok(i/o/r/t)=${tokensDisplay}`);
-    if (!searchEnabled) {
-        statsParts.push('search=off');
-    }
-    if (files.length > 0) {
-        statsParts.push(`files=${files.length}`);
-    }
-    log(chalk.blue(`Finished in ${elapsedDisplay} (${statsParts.join(' | ')})`));
-    return {
-        mode: 'live',
-        response,
-        usage: { inputTokens, outputTokens, reasoningTokens, totalTokens },
-        elapsedMs,
-    };
-}
-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();
-    return estimatedFlag ? `${text}*` : text;
-}
-function resolvePreviewMode(value) {
-    const allowed = new Set(['summary', 'json', 'full']);
-    if (typeof value === 'string' && value.length > 0) {
-        return allowed.has(value) ? value : 'summary';
-    }
-    if (value) {
-        return 'summary';
-    }
-    return undefined;
-}
-export function extractTextOutput(response) {
-    if (Array.isArray(response.output_text) && response.output_text.length > 0) {
-        return response.output_text.join('\n');
-    }
-    if (Array.isArray(response.output)) {
-        const segments = [];
-        for (const item of response.output) {
-            if (Array.isArray(item.content)) {
-                for (const chunk of item.content) {
-                    if (chunk && (chunk.type === 'output_text' || chunk.type === 'text') && chunk.text) {
-                        segments.push(chunk.text);
-                    }
-                }
-            }
-            else if (typeof item.text === 'string') {
-                segments.push(item.text);
-            }
-        }
-        return segments.join('\n');
-    }
-    return '';
-}
-async function executeBackgroundResponse(params) {
-    const { client, requestBody, log, wait, heartbeatIntervalMs, now } = params;
-    const initialResponse = await client.responses.create(requestBody);
-    if (!initialResponse || !initialResponse.id) {
-        throw new OracleResponseError('OpenAI did not return a response ID for the background run.', initialResponse);
-    }
-    const responseId = initialResponse.id;
-    log(dim(`OpenAI scheduled background response ${responseId} (status=${initialResponse.status ?? 'unknown'}). Monitoring up to ${Math.round(BACKGROUND_MAX_WAIT_MS / 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 `OpenAI background run still in progress — ${elapsedText} elapsed.`;
-            },
-        });
-    }
-    try {
-        return await pollBackgroundResponse({
-            client,
-            responseId,
-            initialResponse,
-            log,
-            wait,
-            now,
-            maxWaitMs: BACKGROUND_MAX_WAIT_MS,
-        });
-    }
-    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';
-        // biome-ignore lint/nursery/noUnnecessaryConditions: guard only for first iteration
-        if (firstCycle) {
-            firstCycle = false;
-            log(dim(`OpenAI background response status=${status}. We'll keep retrying automatically.`));
-        }
-        else if (status !== lastStatus && status !== 'completed') {
-            log(dim(`OpenAI 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 OpenAI background response to finish.');
-        }
-        await wait(BACKGROUND_POLL_INTERVAL_MS);
-        if (now() - startMark >= maxWaitMs) {
-            throw new OracleTransportError('client-timeout', 'Timed out waiting for OpenAI 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(dim(`Reconnected to OpenAI background response (status=${nextStatus}). OpenAI 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)} Retrying in ${formatElapsed(delay)}...`));
-            await wait(delay);
-            if (now() - startMark >= maxWaitMs) {
-                throw new OracleTransportError('client-timeout', 'Timed out waiting for OpenAI 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/oracle/src/oracle/tokenStats.js

@@ -1,39 +0,0 @@
-import chalk from 'chalk';
-import { createFileSections } from './files.js';
-export function getFileTokenStats(files, { cwd = process.cwd(), tokenizer, tokenizerOptions, inputTokenBudget, }) {
-    if (!files.length) {
-        return { stats: [], totalTokens: 0 };
-    }
-    const sections = createFileSections(files, cwd);
-    const stats = sections
-        .map((section) => {
-        const tokens = tokenizer(section.sectionText, tokenizerOptions);
-        const percent = inputTokenBudget ? (tokens / inputTokenBudget) * 100 : undefined;
-        return {
-            path: section.absolutePath,
-            displayPath: section.displayPath,
-            tokens,
-            percent,
-        };
-    })
-        .sort((a, b) => b.tokens - a.tokens);
-    const totalTokens = stats.reduce((sum, entry) => sum + entry.tokens, 0);
-    return { stats, totalTokens };
-}
-export function printFileTokenStats({ stats, totalTokens }, { inputTokenBudget, log = console.log }) {
-    if (!stats.length) {
-        return;
-    }
-    log(chalk.bold('File Token Usage'));
-    for (const entry of stats) {
-        const percentLabel = inputTokenBudget && entry.percent != null ? `${entry.percent.toFixed(2)}%` : 'n/a';
-        log(`${entry.tokens.toLocaleString().padStart(10)}  ${percentLabel.padStart(8)}  ${entry.displayPath}`);
-    }
-    if (inputTokenBudget) {
-        const totalPercent = (totalTokens / inputTokenBudget) * 100;
-        log(`Total: ${totalTokens.toLocaleString()} tokens (${totalPercent.toFixed(2)}% of ${inputTokenBudget.toLocaleString()})`);
-    }
-    else {
-        log(`Total: ${totalTokens.toLocaleString()} tokens`);
-    }
-}

package/dist/oracle/src/oracle/types.js

@@ -1 +0,0 @@
-export {};

package/dist/oracle/src/oracle.js

@@ -1,9 +0,0 @@
-export * from './oracle/types.js';
-export { MODEL_CONFIGS, DEFAULT_SYSTEM_PROMPT, TOKENIZER_OPTIONS, } from './oracle/config.js';
-export { readFiles, createFileSections } from './oracle/files.js';
-export { buildPrompt, buildRequestBody, renderPromptMarkdown } from './oracle/request.js';
-export { formatUSD, formatNumber, formatElapsed } from './oracle/format.js';
-export { getFileTokenStats, printFileTokenStats } from './oracle/tokenStats.js';
-export { OracleResponseError, OracleTransportError, OracleUserError, FileValidationError, BrowserAutomationError, PromptValidationError, describeTransportError, extractResponseMetadata, asOracleUserError, toTransportError, } from './oracle/errors.js';
-export { createDefaultClientFactory } from './oracle/client.js';
-export { runOracle, extractTextOutput } from './oracle/run.js';