@steipete/oracle 1.0.8 → 1.1.0

package/dist/oracle/src/cli/sessionDisplay.js

@@ -0,0 +1,270 @@
+import chalk from 'chalk';
+import kleur from 'kleur';
+import { filterSessionsByRange, listSessionsMetadata, readSessionLog, readSessionMetadata, SESSIONS_DIR, wait, } from '../sessionManager.js';
+import { renderMarkdownAnsi } from './markdownRenderer.js';
+const isTty = () => Boolean(process.stdout.isTTY);
+const dim = (text) => (isTty() ? kleur.dim(text) : text);
+const MAX_RENDER_BYTES = 200_000;
+const CLEANUP_TIP = 'Tip: Run "oracle session --clear --hours 24" to prune cached runs (add --all to wipe everything).';
+export async function showStatus({ hours, includeAll, limit, showExamples = false }) {
+    const metas = await listSessionsMetadata();
+    const { entries, truncated, total } = filterSessionsByRange(metas, { hours, includeAll, limit });
+    const richTty = process.stdout.isTTY && chalk.level > 0;
+    if (!entries.length) {
+        console.log(CLEANUP_TIP);
+        if (showExamples) {
+            printStatusExamples();
+        }
+        return;
+    }
+    console.log(chalk.bold('Recent Sessions'));
+    for (const entry of entries) {
+        const statusRaw = (entry.status || 'unknown').padEnd(9);
+        const status = richTty ? colorStatus(entry.status ?? 'unknown', statusRaw) : statusRaw;
+        const model = (entry.model || 'n/a').padEnd(9);
+        const created = entry.createdAt.replace('T', ' ').replace('Z', '');
+        console.log(`${created} | ${status} | ${model} | ${entry.id}`);
+    }
+    if (truncated) {
+        console.log(chalk.yellow(`Showing ${entries.length} of ${total} sessions from the requested range. Run "oracle session --clear" or delete entries in ${SESSIONS_DIR} to free space, or rerun with --status-limit/--status-all.`));
+    }
+    if (showExamples) {
+        printStatusExamples();
+    }
+}
+function colorStatus(status, padded) {
+    switch (status) {
+        case 'completed':
+            return chalk.green(padded);
+        case 'error':
+            return chalk.red(padded);
+        case 'running':
+            return chalk.yellow(padded);
+        default:
+            return padded;
+    }
+}
+export async function attachSession(sessionId, options) {
+    const metadata = await readSessionMetadata(sessionId);
+    if (!metadata) {
+        console.error(chalk.red(`No session found with ID ${sessionId}`));
+        process.exitCode = 1;
+        return;
+    }
+    const initialStatus = metadata.status;
+    const wantsRender = Boolean(options?.renderMarkdown);
+    const isVerbose = Boolean(process.env.ORACLE_VERBOSE_RENDER);
+    if (!options?.suppressMetadata) {
+        const reattachLine = buildReattachLine(metadata);
+        if (reattachLine) {
+            console.log(chalk.blue(reattachLine));
+        }
+        console.log(`Created: ${metadata.createdAt}`);
+        console.log(`Status: ${metadata.status}`);
+        console.log(`Model: ${metadata.model}`);
+        const responseSummary = formatResponseMetadata(metadata.response);
+        if (responseSummary) {
+            console.log(dim(`Response: ${responseSummary}`));
+        }
+        const transportSummary = formatTransportMetadata(metadata.transport);
+        if (transportSummary) {
+            console.log(dim(`Transport: ${transportSummary}`));
+        }
+        const userErrorSummary = formatUserErrorMetadata(metadata.error);
+        if (userErrorSummary) {
+            console.log(dim(`User error: ${userErrorSummary}`));
+        }
+    }
+    const shouldTrimIntro = initialStatus === 'completed' || initialStatus === 'error';
+    if (shouldTrimIntro) {
+        const fullLog = await readSessionLog(sessionId);
+        const trimmed = trimBeforeFirstAnswer(fullLog);
+        const size = Buffer.byteLength(trimmed, 'utf8');
+        const canRender = wantsRender && isTty() && size <= MAX_RENDER_BYTES;
+        if (wantsRender && size > MAX_RENDER_BYTES) {
+            const msg = `Render skipped (log too large: ${size} bytes > ${MAX_RENDER_BYTES}). Showing raw text.`;
+            console.log(dim(msg));
+            if (isVerbose) {
+                console.log(dim(`Verbose: renderMarkdown=true tty=${isTty()} size=${size}`));
+            }
+        }
+        else if (wantsRender && !isTty()) {
+            const msg = 'Render requested but stdout is not a TTY; showing raw text.';
+            console.log(dim(msg));
+            if (isVerbose) {
+                console.log(dim(`Verbose: renderMarkdown=true tty=${isTty()} size=${size}`));
+            }
+        }
+        if (canRender) {
+            if (isVerbose) {
+                console.log(dim(`Verbose: rendering markdown (size=${size}, tty=${isTty()})`));
+            }
+            process.stdout.write(renderMarkdownAnsi(trimmed));
+        }
+        else {
+            process.stdout.write(trimmed);
+        }
+        return;
+    }
+    if (wantsRender) {
+        console.log(dim('Render will apply after completion; streaming raw text meanwhile...'));
+        if (isVerbose) {
+            console.log(dim(`Verbose: streaming phase renderMarkdown=true tty=${isTty()}`));
+        }
+    }
+    let lastLength = 0;
+    const printNew = async () => {
+        const text = await readSessionLog(sessionId);
+        const nextChunk = text.slice(lastLength);
+        if (nextChunk.length > 0) {
+            process.stdout.write(nextChunk);
+            lastLength = text.length;
+        }
+    };
+    await printNew();
+    // biome-ignore lint/nursery/noUnnecessaryConditions: deliberate infinite poll
+    while (true) {
+        const latest = await readSessionMetadata(sessionId);
+        if (!latest) {
+            break;
+        }
+        if (latest.status === 'completed' || latest.status === 'error') {
+            await printNew();
+            if (!options?.suppressMetadata) {
+                if (latest.status === 'error' && latest.errorMessage) {
+                    console.log('\nResult:');
+                    console.log(`Session failed: ${latest.errorMessage}`);
+                }
+                if (latest.usage && initialStatus === 'running') {
+                    const usage = latest.usage;
+                    console.log(`\nFinished (tok i/o/r/t: ${usage.inputTokens}/${usage.outputTokens}/${usage.reasoningTokens}/${usage.totalTokens})`);
+                }
+            }
+            break;
+        }
+        await wait(1000);
+        await printNew();
+    }
+}
+export function formatResponseMetadata(metadata) {
+    if (!metadata) {
+        return null;
+    }
+    const parts = [];
+    if (metadata.responseId) {
+        parts.push(`response=${metadata.responseId}`);
+    }
+    if (metadata.requestId) {
+        parts.push(`request=${metadata.requestId}`);
+    }
+    if (metadata.status) {
+        parts.push(`status=${metadata.status}`);
+    }
+    if (metadata.incompleteReason) {
+        parts.push(`incomplete=${metadata.incompleteReason}`);
+    }
+    return parts.length > 0 ? parts.join(' | ') : null;
+}
+export function formatTransportMetadata(metadata) {
+    if (!metadata?.reason) {
+        return null;
+    }
+    const reasonLabels = {
+        'client-timeout': 'client timeout (20m deadline hit)',
+        'connection-lost': 'connection lost before completion',
+        'client-abort': 'request aborted locally',
+        unknown: 'unknown transport failure',
+    };
+    const label = reasonLabels[metadata.reason] ?? 'transport error';
+    return `${metadata.reason} — ${label}`;
+}
+export function formatUserErrorMetadata(metadata) {
+    if (!metadata) {
+        return null;
+    }
+    const parts = [];
+    if (metadata.category) {
+        parts.push(metadata.category);
+    }
+    if (metadata.message) {
+        parts.push(`message=${metadata.message}`);
+    }
+    if (metadata.details && Object.keys(metadata.details).length > 0) {
+        parts.push(`details=${JSON.stringify(metadata.details)}`);
+    }
+    return parts.length > 0 ? parts.join(' | ') : null;
+}
+export function buildReattachLine(metadata) {
+    if (!metadata.id) {
+        return null;
+    }
+    const referenceTime = metadata.startedAt ?? metadata.createdAt;
+    if (!referenceTime) {
+        return null;
+    }
+    const elapsedLabel = formatRelativeDuration(referenceTime);
+    if (!elapsedLabel) {
+        return null;
+    }
+    if (metadata.status === 'running') {
+        return `Session ${metadata.id} reattached, request started ${elapsedLabel} ago.`;
+    }
+    return null;
+}
+export function trimBeforeFirstAnswer(logText) {
+    const marker = 'Answer:';
+    const index = logText.indexOf(marker);
+    if (index === -1) {
+        return logText;
+    }
+    return logText.slice(index);
+}
+function formatRelativeDuration(referenceIso) {
+    const timestamp = Date.parse(referenceIso);
+    if (Number.isNaN(timestamp)) {
+        return null;
+    }
+    const diffMs = Date.now() - timestamp;
+    if (diffMs < 0) {
+        return null;
+    }
+    const seconds = Math.max(1, Math.round(diffMs / 1000));
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    if (minutes < 60) {
+        return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+    }
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    if (hours < 24) {
+        const parts = [`${hours}h`];
+        if (remainingMinutes > 0) {
+            parts.push(`${remainingMinutes}m`);
+        }
+        return parts.join(' ');
+    }
+    const days = Math.floor(hours / 24);
+    const remainingHours = hours % 24;
+    const parts = [`${days}d`];
+    if (remainingHours > 0) {
+        parts.push(`${remainingHours}h`);
+    }
+    if (remainingMinutes > 0 && days === 0) {
+        parts.push(`${remainingMinutes}m`);
+    }
+    return parts.join(' ');
+}
+function printStatusExamples() {
+    console.log('');
+    console.log(chalk.bold('Usage Examples'));
+    console.log(`${chalk.bold('  oracle status --hours 72 --limit 50')}`);
+    console.log(dim('    Show 72h of history capped at 50 entries.'));
+    console.log(`${chalk.bold('  oracle status --clear --hours 168')}`);
+    console.log(dim('    Delete sessions older than 7 days (use --all to wipe everything).'));
+    console.log(`${chalk.bold('  oracle session <session-id>')}`);
+    console.log(dim('    Attach to a specific running/completed session to stream its output.'));
+    console.log(dim(CLEANUP_TIP));
+}

package/dist/oracle/src/cli/sessionRunner.js

@@ -0,0 +1,94 @@
+import kleur from 'kleur';
+import { updateSessionMetadata } from '../sessionManager.js';
+import { runOracle, OracleResponseError, OracleTransportError, extractResponseMetadata, asOracleUserError, } from '../oracle.js';
+import { runBrowserSessionExecution } from '../browser/sessionRunner.js';
+import { formatResponseMetadata, formatTransportMetadata } from './sessionDisplay.js';
+import { markErrorLogged } from './errorUtils.js';
+const isTty = process.stdout.isTTY;
+const dim = (text) => (isTty ? kleur.dim(text) : text);
+export async function performSessionRun({ sessionMeta, runOptions, mode, browserConfig, cwd, log, write, version, }) {
+    await updateSessionMetadata(sessionMeta.id, {
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        mode,
+        ...(browserConfig ? { browser: { config: browserConfig } } : {}),
+    });
+    try {
+        if (mode === 'browser') {
+            if (!browserConfig) {
+                throw new Error('Missing browser configuration for session.');
+            }
+            const result = await runBrowserSessionExecution({ runOptions, browserConfig, cwd, log, cliVersion: version }, {});
+            await updateSessionMetadata(sessionMeta.id, {
+                status: 'completed',
+                completedAt: new Date().toISOString(),
+                usage: result.usage,
+                elapsedMs: result.elapsedMs,
+                browser: {
+                    config: browserConfig,
+                    runtime: result.runtime,
+                },
+                response: undefined,
+                transport: undefined,
+                error: undefined,
+            });
+            return;
+        }
+        const result = await runOracle(runOptions, {
+            cwd,
+            log,
+            write,
+        });
+        if (result.mode !== 'live') {
+            throw new Error('Unexpected preview result while running a session.');
+        }
+        await updateSessionMetadata(sessionMeta.id, {
+            status: 'completed',
+            completedAt: new Date().toISOString(),
+            usage: result.usage,
+            elapsedMs: result.elapsedMs,
+            response: extractResponseMetadata(result.response),
+            transport: undefined,
+            error: undefined,
+        });
+    }
+    catch (error) {
+        const message = formatError(error);
+        log(`ERROR: ${message}`);
+        markErrorLogged(error);
+        const userError = asOracleUserError(error);
+        if (userError) {
+            log(dim(`User error (${userError.category}): ${userError.message}`));
+        }
+        const responseMetadata = error instanceof OracleResponseError ? error.metadata : undefined;
+        const metadataLine = formatResponseMetadata(responseMetadata);
+        if (metadataLine) {
+            log(dim(`Response metadata: ${metadataLine}`));
+        }
+        const transportMetadata = error instanceof OracleTransportError ? { reason: error.reason } : undefined;
+        const transportLine = formatTransportMetadata(transportMetadata);
+        if (transportLine) {
+            log(dim(`Transport: ${transportLine}`));
+        }
+        await updateSessionMetadata(sessionMeta.id, {
+            status: 'error',
+            completedAt: new Date().toISOString(),
+            errorMessage: message,
+            mode,
+            browser: browserConfig ? { config: browserConfig } : undefined,
+            response: responseMetadata,
+            transport: transportMetadata,
+            error: userError
+                ? {
+                    category: userError.category,
+                    message: userError.message,
+                    details: userError.details,
+                }
+                : undefined,
+        });
+        throw error;
+    }
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/oracle/src/heartbeat.js

@@ -0,0 +1,43 @@
+export function startHeartbeat(config) {
+    const { intervalMs, log, isActive, makeMessage } = config;
+    if (!intervalMs || intervalMs <= 0) {
+        return () => { };
+    }
+    let stopped = false;
+    let pending = false;
+    const start = Date.now();
+    const timer = setInterval(async () => {
+        // biome-ignore lint/nursery/noUnnecessaryConditions: stop flag flips asynchronously
+        if (stopped || pending) {
+            return;
+        }
+        if (!isActive()) {
+            stop();
+            return;
+        }
+        pending = true;
+        try {
+            const elapsed = Date.now() - start;
+            const message = await makeMessage(elapsed);
+            if (message && !stopped) {
+                log(message);
+            }
+        }
+        catch {
+            // ignore heartbeat errors
+        }
+        finally {
+            pending = false;
+        }
+    }, intervalMs);
+    timer.unref?.();
+    const stop = () => {
+        // biome-ignore lint/nursery/noUnnecessaryConditions: multiple callers may race to stop
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        clearInterval(timer);
+    };
+    return stop;
+}

package/dist/oracle/src/oracle/client.js

@@ -0,0 +1,48 @@
+import OpenAI from 'openai';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+const CUSTOM_CLIENT_FACTORY = loadCustomClientFactory();
+export function createDefaultClientFactory() {
+    if (CUSTOM_CLIENT_FACTORY) {
+        return CUSTOM_CLIENT_FACTORY;
+    }
+    return (key) => {
+        const instance = new OpenAI({
+            apiKey: key,
+            timeout: 20 * 60 * 1000,
+        });
+        return {
+            responses: {
+                stream: (body) => instance.responses.stream(body),
+                create: (body) => instance.responses.create(body),
+                retrieve: (id) => instance.responses.retrieve(id),
+            },
+        };
+    };
+}
+function loadCustomClientFactory() {
+    const override = process.env.ORACLE_CLIENT_FACTORY;
+    if (!override) {
+        return null;
+    }
+    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;
+}

package/dist/oracle/src/oracle/config.js

@@ -0,0 +1,29 @@
+import { countTokens as countTokensGpt5 } from 'gpt-tokenizer/model/gpt-5';
+import { countTokens as countTokensGpt5Pro } from 'gpt-tokenizer/model/gpt-5-pro';
+export const MODEL_CONFIGS = {
+    'gpt-5-pro': {
+        model: 'gpt-5-pro',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 15 / 1_000_000,
+            outputPerToken: 120 / 1_000_000,
+        },
+        reasoning: null,
+    },
+    'gpt-5.1': {
+        model: 'gpt-5.1',
+        tokenizer: countTokensGpt5,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 1.25 / 1_000_000,
+            outputPerToken: 10 / 1_000_000,
+        },
+        reasoning: { effort: 'high' },
+    },
+};
+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.',
+].join(' ');
+export const TOKENIZER_OPTIONS = { allowedSpecial: 'all' };

package/dist/oracle/src/oracle/errors.js

@@ -0,0 +1,101 @@
+import { APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, } from 'openai';
+export class OracleUserError extends Error {
+    category;
+    details;
+    constructor(category, message, details, cause) {
+        super(message);
+        this.name = 'OracleUserError';
+        this.category = category;
+        this.details = details;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+export class FileValidationError extends OracleUserError {
+    constructor(message, details, cause) {
+        super('file-validation', message, details, cause);
+        this.name = 'FileValidationError';
+    }
+}
+export class BrowserAutomationError extends OracleUserError {
+    constructor(message, details, cause) {
+        super('browser-automation', message, details, cause);
+        this.name = 'BrowserAutomationError';
+    }
+}
+export class PromptValidationError extends OracleUserError {
+    constructor(message, details, cause) {
+        super('prompt-validation', message, details, cause);
+        this.name = 'PromptValidationError';
+    }
+}
+export function asOracleUserError(error) {
+    if (error instanceof OracleUserError) {
+        return error;
+    }
+    return null;
+}
+export class OracleTransportError extends Error {
+    reason;
+    constructor(reason, message, cause) {
+        super(message);
+        this.name = 'OracleTransportError';
+        this.reason = reason;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+export class OracleResponseError extends Error {
+    metadata;
+    response;
+    constructor(message, response) {
+        super(message);
+        this.name = 'OracleResponseError';
+        this.response = response;
+        this.metadata = extractResponseMetadata(response);
+    }
+}
+export function extractResponseMetadata(response) {
+    if (!response) {
+        return {};
+    }
+    const metadata = {
+        responseId: response.id,
+        status: response.status,
+        incompleteReason: response.incomplete_details?.reason ?? undefined,
+    };
+    const requestId = response._request_id;
+    if (requestId !== undefined) {
+        metadata.requestId = requestId;
+    }
+    return metadata;
+}
+export function toTransportError(error) {
+    if (error instanceof OracleTransportError) {
+        return error;
+    }
+    if (error instanceof APIConnectionTimeoutError) {
+        return new OracleTransportError('client-timeout', 'OpenAI request timed out before completion.', error);
+    }
+    if (error instanceof APIUserAbortError) {
+        return new OracleTransportError('client-abort', 'The request was aborted before OpenAI finished responding.', error);
+    }
+    if (error instanceof APIConnectionError) {
+        return new OracleTransportError('connection-lost', 'Connection to OpenAI dropped before the response completed.', error);
+    }
+    return new OracleTransportError('unknown', error instanceof Error ? error.message : 'Unknown transport failure.', error);
+}
+export function describeTransportError(error) {
+    switch (error.reason) {
+        case 'client-timeout':
+            return 'Client-side timeout: OpenAI streaming call exceeded the 20m deadline.';
+        case 'connection-lost':
+            return 'Connection to OpenAI ended unexpectedly before the response completed.';
+        case 'client-abort':
+            return 'Request was aborted before OpenAI completed the response.';
+        default:
+            return 'OpenAI streaming call ended with an unknown transport error.';
+    }
+}