@steipete/oracle 0.4.0

package/dist/src/oracle/run.js

@@ -0,0 +1,492 @@
+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 { DEFAULT_SYSTEM_PROMPT, MODEL_CONFIGS, PRO_MODELS, TOKENIZER_OPTIONS } from './config.js';
+import { readFiles } from './files.js';
+import { buildPrompt, buildRequestBody } from './request.js';
+import { estimateRequestTokens } from './tokenEstimate.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 { formatBaseUrlForLog, maskApiKey } from './logging.js';
+import { startHeartbeat } from '../heartbeat.js';
+import { startOscProgress } from './oscProgress.js';
+import { createFsAdapter } from './fsAdapter.js';
+import { resolveGeminiModelId } from './gemini.js';
+import { resolveClaudeModelId } from './claude.js';
+import { renderMarkdownAnsi } from '../cli/markdownRenderer.js';
+import { executeBackgroundResponse } from './background.js';
+import { formatTokenEstimate, formatTokenValue, resolvePreviewMode } from './runUtils.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.
+const DEFAULT_TIMEOUT_NON_PRO_MS = 120_000;
+const DEFAULT_TIMEOUT_PRO_MS = 60 * 60 * 1000;
+const defaultWait = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+export async function runOracle(options, deps = {}) {
+    const { apiKey: optionsApiKey = options.apiKey, cwd = process.cwd(), fs: fsModule = createFsAdapter(fs), log = console.log, write: sinkWrite = (_text) => true, allowStdout = true, stdoutWrite: stdoutWriteDep, now = () => performance.now(), clientFactory = createDefaultClientFactory(), client, wait = defaultWait, } = deps;
+    const stdoutWrite = allowStdout
+        ? stdoutWriteDep ?? process.stdout.write.bind(process.stdout)
+        : () => true;
+    const isTty = allowStdout && isStdoutTty;
+    const baseUrl = options.baseUrl?.trim() || process.env.OPENAI_BASE_URL?.trim();
+    const logVerbose = (message) => {
+        if (options.verbose) {
+            log(dim(`[verbose] ${message}`));
+        }
+    };
+    const previewMode = resolvePreviewMode(options.previewMode ?? options.preview);
+    const isPreview = Boolean(previewMode);
+    const isAzureOpenAI = Boolean(options.azure?.endpoint);
+    const getApiKeyForModel = (model) => {
+        if (model.startsWith('gpt')) {
+            if (optionsApiKey)
+                return optionsApiKey;
+            if (isAzureOpenAI) {
+                return process.env.AZURE_OPENAI_API_KEY ?? process.env.OPENAI_API_KEY;
+            }
+            return process.env.OPENAI_API_KEY;
+        }
+        if (model.startsWith('gemini')) {
+            return optionsApiKey ?? process.env.GEMINI_API_KEY;
+        }
+        if (model.startsWith('claude')) {
+            return optionsApiKey ?? process.env.ANTHROPIC_API_KEY;
+        }
+        return undefined;
+    };
+    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'
+            : 'ANTHROPIC_API_KEY';
+    const apiKey = getApiKeyForModel(options.model);
+    if (!apiKey) {
+        throw new PromptValidationError(`Missing ${envVar}. Set it via the environment or a .env file.`, {
+            env: envVar,
+        });
+    }
+    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);
+    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 isLongRunningModel = isProTierModel;
+    const useBackground = options.background ?? isLongRunningModel;
+    const inputTokenBudget = options.maxInput ?? modelConfig.inputLimit;
+    const files = await readFiles(options.file ?? [], { cwd, fsModule });
+    const searchEnabled = options.search !== false;
+    logVerbose(`cwd: ${cwd}`);
+    let pendingNoFilesTip = null;
+    let pendingShortPromptTip = null;
+    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) {
+            pendingNoFilesTip =
+                'Tip: no files attached — Oracle works best with project context. Add files via --file path/to/code or docs.';
+        }
+    }
+    const shortPrompt = (options.prompt?.trim().length ?? 0) < 80;
+    if (!isPreview && shortPrompt) {
+        pendingShortPromptTip =
+            'Tip: brief prompts often yield generic answers — aim for 6–30 sentences and attach key files.';
+    }
+    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 fileCount = files.length;
+    const richTty = allowStdout && process.stdout.isTTY && chalk.level > 0;
+    const renderPlain = Boolean(options.renderPlain);
+    const timeoutSeconds = options.timeoutSeconds === undefined || options.timeoutSeconds === 'auto'
+        ? isLongRunningModel
+            ? DEFAULT_TIMEOUT_PRO_MS / 1000
+            : DEFAULT_TIMEOUT_NON_PRO_MS / 1000
+        : options.timeoutSeconds;
+    const timeoutMs = timeoutSeconds * 1000;
+    // Track the concrete model id we dispatch to (especially for Gemini preview aliases)
+    const effectiveModelId = options.effectiveModelId ??
+        (options.model.startsWith('gemini')
+            ? resolveGeminiModelId(options.model)
+            : modelConfig.apiModel ?? modelConfig.model);
+    const headerModelLabel = richTty ? chalk.cyan(modelConfig.model) : modelConfig.model;
+    const requestBody = buildRequestBody({
+        modelConfig,
+        systemPrompt,
+        userPrompt: promptWithFiles,
+        searchEnabled,
+        maxOutputTokens: options.maxOutput,
+        background: useBackground,
+        storeResponse: useBackground,
+    });
+    const estimatedInputTokens = estimateRequestTokens(requestBody, modelConfig);
+    const tokenLabel = formatTokenEstimate(estimatedInputTokens, (text) => (richTty ? chalk.green(text) : text));
+    const fileLabel = richTty ? chalk.magenta(fileCount.toString()) : fileCount.toString();
+    const filesPhrase = fileCount === 0 ? 'no files' : `${fileLabel} files`;
+    const headerLine = `Calling ${headerModelLabel} — ${tokenLabel} tokens, ${filesPhrase}.`;
+    const shouldReportFiles = (options.filesReport || fileTokenInfo.totalTokens > inputTokenBudget) && fileTokenInfo.stats.length > 0;
+    if (!isPreview) {
+        if (!options.suppressHeader) {
+            log(headerLine);
+        }
+        const maskedKey = maskApiKey(apiKey);
+        if (maskedKey && options.verbose) {
+            const resolvedSuffix = effectiveModelId !== modelConfig.model ? ` (resolved: ${effectiveModelId})` : '';
+            log(dim(`Using ${envVar}=${maskedKey} for model ${modelConfig.model}${resolvedSuffix}`));
+        }
+        if (baseUrl) {
+            log(dim(`Base URL: ${formatBaseUrlForLog(baseUrl)}`));
+        }
+        if (!options.suppressTips) {
+            if (pendingNoFilesTip) {
+                log(dim(pendingNoFilesTip));
+            }
+            if (pendingShortPromptTip) {
+                log(dim(pendingShortPromptTip));
+            }
+        }
+        if (isLongRunningModel) {
+            log(dim('This model can take up to 60 minutes (usually replies much faster).'));
+        }
+        if (options.verbose || isLongRunningModel) {
+            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 });
+    }
+    logVerbose(`Estimated tokens (request body): ${estimatedInputTokens.toLocaleString()}`);
+    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 apiEndpoint = modelConfig.model.startsWith('gemini')
+        ? undefined
+        : modelConfig.model.startsWith('claude')
+            ? process.env.ANTHROPIC_BASE_URL ?? baseUrl
+            : baseUrl;
+    const clientInstance = client ??
+        clientFactory(apiKey, {
+            baseUrl: apiEndpoint,
+            azure: options.azure,
+            model: options.model,
+            resolvedModelId: modelConfig.model.startsWith('claude')
+                ? resolveClaudeModelId(effectiveModelId)
+                : modelConfig.model.startsWith('gemini')
+                    ? resolveGeminiModelId(effectiveModelId)
+                    : effectiveModelId,
+        });
+    logVerbose('Dispatching request to API...');
+    if (options.verbose) {
+        log(''); // ensure verbose section is separated from Answer stream
+    }
+    const stopOscProgress = startOscProgress({
+        label: useBackground ? 'Waiting for API (background)' : 'Waiting for API',
+        targetMs: useBackground ? timeoutMs : Math.min(timeoutMs, 10 * 60_000),
+        indeterminate: true,
+        write: sinkWrite,
+    });
+    const runStart = now();
+    let response = null;
+    let elapsedMs = 0;
+    let sawTextDelta = false;
+    // Buffer streamed text so we can re-render markdown once the stream ends (TTY + non-plain mode).
+    const streamedChunks = [];
+    let answerHeaderPrinted = false;
+    const allowAnswerHeader = options.suppressAnswerHeader !== true;
+    const timeoutExceeded = () => now() - runStart >= timeoutMs;
+    const throwIfTimedOut = () => {
+        if (timeoutExceeded()) {
+            throw new OracleTransportError('client-timeout', `Timed out waiting for API response after ${formatElapsed(timeoutMs)}.`);
+        }
+    };
+    const ensureAnswerHeader = () => {
+        if (options.silent || answerHeaderPrinted)
+            return;
+        // Always add a separating newline for readability; optionally include the label depending on caller needs.
+        log('');
+        if (allowAnswerHeader) {
+            log(chalk.bold('Answer:'));
+        }
+        answerHeaderPrinted = true;
+    };
+    try {
+        if (useBackground) {
+            response = await executeBackgroundResponse({
+                client: clientInstance,
+                requestBody,
+                log,
+                wait,
+                heartbeatIntervalMs: options.heartbeatIntervalMs,
+                now,
+                maxWaitMs: timeoutMs,
+            });
+            elapsedMs = now() - runStart;
+        }
+        else {
+            const stream = await clientInstance.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);
+                        const remainingMs = Math.max(timeoutMs - elapsedMs, 0);
+                        const remainingLabel = remainingMs >= 60_000
+                            ? `${Math.ceil(remainingMs / 60_000)} min`
+                            : `${Math.max(1, Math.ceil(remainingMs / 1000))}s`;
+                        return `API connection active — ${elapsedText} elapsed. Timeout in ~${remainingLabel} if no response.`;
+                    },
+                });
+            }
+            try {
+                for await (const event of stream) {
+                    throwIfTimedOut();
+                    const isTextDelta = event.type === 'chunk' || event.type === 'response.output_text.delta';
+                    if (isTextDelta) {
+                        stopOscProgress();
+                        stopHeartbeatNow();
+                        sawTextDelta = true;
+                        ensureAnswerHeader();
+                        if (!options.silent && typeof event.delta === 'string') {
+                            // Always keep the log/bookkeeping sink up to date.
+                            sinkWrite(event.delta);
+                            if (renderPlain) {
+                                // Plain mode: stream directly to stdout regardless of write sink.
+                                stdoutWrite(event.delta);
+                            }
+                            else if (isTty) {
+                                // Buffer for end-of-stream markdown rendering on TTY.
+                                streamedChunks.push(event.delta);
+                            }
+                            else {
+                                // Non-TTY streams should still surface output; fall back to raw stdout.
+                                stdoutWrite(event.delta);
+                            }
+                        }
+                    }
+                }
+                throwIfTimedOut();
+            }
+            catch (streamError) {
+                // stream.abort() is not available on the interface
+                stopHeartbeatNow();
+                const transportError = toTransportError(streamError);
+                log(chalk.yellow(describeTransportError(transportError, timeoutMs)));
+                throw transportError;
+            }
+            response = await stream.finalResponse();
+            throwIfTimedOut();
+            stopHeartbeatNow();
+            elapsedMs = now() - runStart;
+        }
+    }
+    finally {
+        stopOscProgress();
+    }
+    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
+    if (sawTextDelta && !options.silent) {
+        const fullStreamedText = streamedChunks.join('');
+        const shouldRenderAfterStream = isTty && !renderPlain && fullStreamedText.length > 0;
+        if (shouldRenderAfterStream) {
+            const rendered = renderMarkdownAnsi(fullStreamedText);
+            stdoutWrite(rendered);
+            if (!rendered.endsWith('\n')) {
+                stdoutWrite('\n');
+            }
+            log('');
+        }
+        else if (renderPlain) {
+            // Plain streaming already wrote chunks; ensure clean separation.
+            stdoutWrite('\n');
+        }
+        else {
+            log('');
+        }
+    }
+    logVerbose(`Response status: ${response.status ?? 'completed'}`);
+    if (response.status && response.status !== 'completed') {
+        // API can reply `in_progress` even after the stream closes; give it a brief grace poll.
+        if (response.id && response.status === 'in_progress') {
+            const polishingStart = now();
+            const pollIntervalMs = 2_000;
+            const maxWaitMs = 60_000;
+            log(chalk.dim('Response still in_progress; polling until completion...'));
+            // Short polling loop — we don't want to hang forever, just catch late finalization.
+            while (now() - polishingStart < maxWaitMs) {
+                await wait(pollIntervalMs);
+                const refreshed = await clientInstance.responses.retrieve(response.id);
+                if (refreshed.status === 'completed') {
+                    response = refreshed;
+                    break;
+                }
+            }
+        }
+        if (response.status !== 'completed') {
+            const detail = response.error?.message || response.incomplete_details?.reason || response.status;
+            log(chalk.yellow(`API 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) {
+            // Already handled above (rendered or streamed); avoid double-printing.
+        }
+        else {
+            ensureAnswerHeader();
+            // Render markdown to ANSI in rich TTYs unless the caller opts out with --render-plain.
+            const printable = answerText
+                ? renderPlain || !richTty
+                    ? answerText
+                    : renderMarkdownAnsi(answerText)
+                : chalk.dim('(no text output)');
+            sinkWrite(printable);
+            if (!printable.endsWith('\n')) {
+                sinkWrite('\n');
+            }
+            stdoutWrite(printable);
+            if (!printable.endsWith('\n')) {
+                stdoutWrite('\n');
+            }
+            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 pricing = modelConfig.pricing ?? undefined;
+    const cost = pricing
+        ? inputTokens * pricing.inputPerToken + outputTokens * pricing.outputPerToken
+        : undefined;
+    const elapsedDisplay = formatElapsed(elapsedMs);
+    const statsParts = [];
+    const effortLabel = modelConfig.reasoning?.effort;
+    const modelLabel = effortLabel ? `${modelConfig.model}[${effortLabel}]` : modelConfig.model;
+    const sessionIdContainsModel = typeof options.sessionId === 'string' && options.sessionId.toLowerCase().includes(modelConfig.model.toLowerCase());
+    // Avoid duplicating the model name in the prefix (session id) and the stats bundle; keep a single source of truth.
+    if (!sessionIdContainsModel) {
+        statsParts.push(modelLabel);
+    }
+    if (cost != null) {
+        statsParts.push(formatUSD(cost));
+    }
+    else {
+        statsParts.push('cost=N/A');
+    }
+    const tokensDisplay = [inputTokens, outputTokens, reasoningTokens, totalTokens]
+        .map((value, index) => formatTokenValue(value, usage, index))
+        .join('/');
+    const tokensLabel = options.verbose ? 'tokens (input/output/reasoning/total)' : 'tok(i/o/r/t)';
+    statsParts.push(`${tokensLabel}=${tokensDisplay}`);
+    if (options.verbose) {
+        // Only surface request-vs-response deltas when verbose is explicitly requested to keep default stats compact.
+        const actualInput = usage.input_tokens;
+        if (actualInput !== undefined) {
+            const delta = actualInput - estimatedInputTokens;
+            const deltaText = delta === 0 ? '' : delta > 0 ? ` (+${delta.toLocaleString()})` : ` (${delta.toLocaleString()})`;
+            statsParts.push(`est→actual=${estimatedInputTokens.toLocaleString()}→${actualInput.toLocaleString()}${deltaText}`);
+        }
+    }
+    if (!searchEnabled) {
+        statsParts.push('search=off');
+    }
+    if (files.length > 0) {
+        statsParts.push(`files=${files.length}`);
+    }
+    const sessionPrefix = options.sessionId ? `${options.sessionId} ` : '';
+    log(chalk.blue(`Finished ${sessionPrefix}in ${elapsedDisplay} (${statsParts.join(' | ')})`));
+    return {
+        mode: 'live',
+        response,
+        usage: { inputTokens, outputTokens, reasoningTokens, totalTokens, ...(cost != null ? { cost } : {}) },
+        elapsedMs,
+    };
+}
+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 '';
+}

package/dist/src/oracle/runUtils.js

@@ -0,0 +1,27 @@
+export 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 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);
+    }
+    const text = value.toLocaleString();
+    return format(text);
+}
+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();
+    return estimatedFlag ? `${text}*` : text;
+}

package/dist/src/oracle/tokenEstimate.js

@@ -0,0 +1,37 @@
+import { TOKENIZER_OPTIONS } from './config.js';
+/**
+ * Estimate input tokens from the full request body instead of just system/user text.
+ * This is a conservative approximation: we tokenize the key textual fields and add a fixed buffer
+ * to cover structural JSON overhead and server-side wrappers (tools/reasoning/background/store).
+ */
+export function estimateRequestTokens(requestBody, modelConfig, bufferTokens = 200) {
+    const SEARCH_RESULT_BUFFER_TOKENS = 4000;
+    const parts = [];
+    if (requestBody.instructions) {
+        parts.push(requestBody.instructions);
+    }
+    for (const turn of requestBody.input ?? []) {
+        for (const content of turn.content ?? []) {
+            if (typeof content.text === 'string') {
+                parts.push(content.text);
+            }
+        }
+    }
+    if (requestBody.tools && requestBody.tools.length > 0) {
+        parts.push(JSON.stringify(requestBody.tools));
+    }
+    if (requestBody.reasoning) {
+        parts.push(JSON.stringify(requestBody.reasoning));
+    }
+    if (requestBody.background) {
+        parts.push('background:true');
+    }
+    if (requestBody.store) {
+        parts.push('store:true');
+    }
+    const concatenated = parts.join('\n');
+    const baseEstimate = modelConfig.tokenizer(concatenated, TOKENIZER_OPTIONS);
+    const hasWebSearch = requestBody.tools?.some((tool) => tool?.type === 'web_search_preview');
+    const searchBuffer = hasWebSearch ? SEARCH_RESULT_BUFFER_TOKENS : 0;
+    return baseEstimate + bufferTokens + searchBuffer;
+}

package/dist/src/oracle/tokenStats.js

@@ -0,0 +1,39 @@
+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/src/oracle/tokenStringifier.js

@@ -0,0 +1,24 @@
+// Minimal helper to stringify arbitrary input for tokenizer consumption.
+// Anthropic's tokenizer expects a string; we accept unknown and coerce safely.
+export function stringifyTokenizerInput(input) {
+    if (typeof input === 'string')
+        return input;
+    if (input === null || input === undefined)
+        return '';
+    if (typeof input === 'number' || typeof input === 'boolean' || typeof input === 'bigint') {
+        return String(input);
+    }
+    if (typeof input === 'object') {
+        try {
+            return JSON.stringify(input);
+        }
+        catch {
+            // fall through to generic stringification
+        }
+    }
+    if (typeof input === 'function') {
+        return input.toString();
+    }
+    return String(input);
+}
+export default stringifyTokenizerInput;

package/dist/src/oracle/types.js

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

package/dist/src/oracle.js

@@ -0,0 +1,12 @@
+export * from './oracle/types.js';
+export { MODEL_CONFIGS, DEFAULT_MODEL, PRO_MODELS, 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 { estimateRequestTokens } from './oracle/tokenEstimate.js';
+export { formatUSD, formatNumber, formatElapsed } from './oracle/format.js';
+export { formatFileSection } from './oracle/markdown.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';
+export { resolveGeminiModelId } from './oracle/gemini.js';