@indykish/oracle 0.9.0

package/dist/src/cli/browserConfig.js

@@ -0,0 +1,278 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { CHATGPT_URL, DEFAULT_MODEL_STRATEGY, DEFAULT_MODEL_TARGET, isTemporaryChatUrl, normalizeChatgptUrl, parseDuration } from '../browserMode.js';
+import { normalizeBrowserModelStrategy } from '../browser/modelStrategy.js';
+import { getOracleHomeDir } from '../oracleHome.js';
+const DEFAULT_BROWSER_TIMEOUT_MS = 1_200_000;
+const DEFAULT_BROWSER_INPUT_TIMEOUT_MS = 60_000;
+const DEFAULT_BROWSER_RECHECK_TIMEOUT_MS = 120_000;
+const DEFAULT_BROWSER_AUTO_REATTACH_TIMEOUT_MS = 120_000;
+const DEFAULT_CHROME_PROFILE = 'Default';
+// Ordered array: most specific models first to ensure correct selection.
+// The browser label is passed to the model picker which fuzzy-matches against ChatGPT's UI.
+const BROWSER_MODEL_LABELS = [
+    // Most specific first (e.g., "gpt-5.2-thinking" before "gpt-5.2")
+    ['gpt-5.2-thinking', 'GPT-5.2 Thinking'],
+    ['gpt-5.2-instant', 'GPT-5.2 Instant'],
+    ['gpt-5.2-pro', 'GPT-5.2 Pro'],
+    ['gpt-5.1-pro', 'GPT-5.2 Pro'],
+    ['gpt-5-pro', 'GPT-5.2 Pro'],
+    // Base models last (least specific)
+    ['gpt-5.2', 'GPT-5.2'], // Selects "Auto" in ChatGPT UI
+    ['gpt-5.1', 'GPT-5.2'], // Legacy alias → Auto
+    ['gemini-3-pro', 'Gemini 3 Pro'],
+];
+export function normalizeChatGptModelForBrowser(model) {
+    const normalized = model.toLowerCase();
+    if (!normalized.startsWith('gpt-') || normalized.includes('codex')) {
+        return model;
+    }
+    // Pro variants: always resolve to the latest Pro model in ChatGPT.
+    if (normalized === 'gpt-5-pro' || normalized === 'gpt-5.1-pro' || normalized.endsWith('-pro')) {
+        return 'gpt-5.2-pro';
+    }
+    // Explicit model variants: keep as-is (they have their own browser labels)
+    if (normalized === 'gpt-5.2-thinking' || normalized === 'gpt-5.2-instant') {
+        return normalized;
+    }
+    // Legacy aliases: map to base GPT-5.2 (Auto)
+    if (normalized === 'gpt-5.1') {
+        return 'gpt-5.2';
+    }
+    return model;
+}
+export async function buildBrowserConfig(options) {
+    const desiredModelOverride = options.browserModelLabel?.trim();
+    const normalizedOverride = desiredModelOverride?.toLowerCase() ?? '';
+    const baseModel = options.model.toLowerCase();
+    const isChatGptModel = baseModel.startsWith('gpt-') && !baseModel.includes('codex');
+    const shouldUseOverride = !isChatGptModel && normalizedOverride.length > 0 && normalizedOverride !== baseModel;
+    const modelStrategy = normalizeBrowserModelStrategy(options.browserModelStrategy) ?? DEFAULT_MODEL_STRATEGY;
+    const cookieNames = parseCookieNames(options.browserCookieNames ?? process.env.ORACLE_BROWSER_COOKIE_NAMES);
+    let inline = await resolveInlineCookies({
+        inlineArg: options.browserInlineCookies,
+        inlineFileArg: options.browserInlineCookiesFile,
+        envPayload: process.env.ORACLE_BROWSER_COOKIES_JSON,
+        envFile: process.env.ORACLE_BROWSER_COOKIES_FILE,
+        cwd: process.cwd(),
+    });
+    if (inline?.source?.startsWith('home:') && options.browserNoCookieSync !== true) {
+        inline = undefined;
+    }
+    let remoteChrome;
+    if (options.remoteChrome) {
+        remoteChrome = parseRemoteChromeTarget(options.remoteChrome);
+    }
+    const rawUrl = options.chatgptUrl ?? options.browserUrl;
+    const url = rawUrl ? normalizeChatgptUrl(rawUrl, CHATGPT_URL) : undefined;
+    const desiredModel = isChatGptModel
+        ? mapModelToBrowserLabel(options.model)
+        : shouldUseOverride
+            ? desiredModelOverride
+            : mapModelToBrowserLabel(options.model);
+    if (modelStrategy === 'select' && url && isTemporaryChatUrl(url) && /\bpro\b/i.test(desiredModel ?? '')) {
+        throw new Error('Temporary Chat mode does not expose Pro models in the ChatGPT model picker. ' +
+            'Remove "temporary-chat=true" from --chatgpt-url (or omit --chatgpt-url), or use a non-Pro model (e.g. --model gpt-5.2).');
+    }
+    return {
+        chromeProfile: options.browserChromeProfile ?? DEFAULT_CHROME_PROFILE,
+        chromePath: options.browserChromePath ?? null,
+        chromeCookiePath: options.browserCookiePath ?? null,
+        url,
+        debugPort: selectBrowserPort(options),
+        timeoutMs: options.browserTimeout ? parseDuration(options.browserTimeout, DEFAULT_BROWSER_TIMEOUT_MS) : undefined,
+        inputTimeoutMs: options.browserInputTimeout
+            ? parseDuration(options.browserInputTimeout, DEFAULT_BROWSER_INPUT_TIMEOUT_MS)
+            : undefined,
+        assistantRecheckDelayMs: options.browserRecheckDelay
+            ? parseDuration(options.browserRecheckDelay, 0)
+            : undefined,
+        assistantRecheckTimeoutMs: options.browserRecheckTimeout
+            ? parseDuration(options.browserRecheckTimeout, DEFAULT_BROWSER_RECHECK_TIMEOUT_MS)
+            : undefined,
+        reuseChromeWaitMs: options.browserReuseWait ? parseDuration(options.browserReuseWait, 0) : undefined,
+        profileLockTimeoutMs: options.browserProfileLockTimeout
+            ? parseDuration(options.browserProfileLockTimeout, 0)
+            : undefined,
+        autoReattachDelayMs: options.browserAutoReattachDelay
+            ? parseDuration(options.browserAutoReattachDelay, 0)
+            : undefined,
+        autoReattachIntervalMs: options.browserAutoReattachInterval
+            ? parseDuration(options.browserAutoReattachInterval, 0)
+            : undefined,
+        autoReattachTimeoutMs: options.browserAutoReattachTimeout
+            ? parseDuration(options.browserAutoReattachTimeout, DEFAULT_BROWSER_AUTO_REATTACH_TIMEOUT_MS)
+            : undefined,
+        cookieSyncWaitMs: options.browserCookieWait ? parseDuration(options.browserCookieWait, 0) : undefined,
+        cookieSync: options.browserNoCookieSync ? false : undefined,
+        cookieNames,
+        inlineCookies: inline?.cookies,
+        inlineCookiesSource: inline?.source ?? null,
+        headless: undefined, // disable headless; Cloudflare blocks it
+        keepBrowser: options.browserKeepBrowser ? true : undefined,
+        manualLogin: options.browserManualLogin === undefined ? undefined : options.browserManualLogin,
+        manualLoginProfileDir: options.browserManualLoginProfileDir ?? undefined,
+        hideWindow: options.browserHideWindow ? true : undefined,
+        desiredModel,
+        modelStrategy,
+        debug: options.verbose ? true : undefined,
+        // Allow cookie failures by default so runs can continue without Chrome/Keychain secrets.
+        allowCookieErrors: options.browserAllowCookieErrors ?? true,
+        remoteChrome,
+        thinkingTime: options.browserThinkingTime,
+    };
+}
+function selectBrowserPort(options) {
+    const candidate = options.browserPort ?? options.browserDebugPort;
+    if (candidate === undefined || candidate === null)
+        return null;
+    if (!Number.isFinite(candidate) || candidate <= 0 || candidate > 65_535) {
+        throw new Error(`Invalid browser port: ${candidate}. Expected a number between 1 and 65535.`);
+    }
+    return candidate;
+}
+export function mapModelToBrowserLabel(model) {
+    const normalized = normalizeChatGptModelForBrowser(model);
+    // Iterate ordered array to find first match (most specific first)
+    for (const [key, label] of BROWSER_MODEL_LABELS) {
+        if (key === normalized) {
+            return label;
+        }
+    }
+    return DEFAULT_MODEL_TARGET;
+}
+export function resolveBrowserModelLabel(input, model) {
+    const trimmed = input?.trim?.() ?? '';
+    if (!trimmed) {
+        return mapModelToBrowserLabel(model);
+    }
+    const normalizedInput = trimmed.toLowerCase();
+    if (normalizedInput === model.toLowerCase()) {
+        return mapModelToBrowserLabel(model);
+    }
+    return trimmed;
+}
+function parseRemoteChromeTarget(raw) {
+    const target = raw.trim();
+    if (!target) {
+        throw new Error('Invalid remote-chrome value: expected host:port but received an empty string.');
+    }
+    const ipv6Match = target.match(/^\[(.+)]:(\d+)$/);
+    let host;
+    let portSegment;
+    if (ipv6Match) {
+        host = ipv6Match[1]?.trim();
+        portSegment = ipv6Match[2]?.trim();
+    }
+    else {
+        const lastColon = target.lastIndexOf(':');
+        if (lastColon === -1) {
+            throw new Error(`Invalid remote-chrome format: ${target}. Expected host:port (IPv6 must use [host]:port notation).`);
+        }
+        host = target.slice(0, lastColon).trim();
+        portSegment = target.slice(lastColon + 1).trim();
+        if (host.includes(':')) {
+            throw new Error(`Invalid remote-chrome format: ${target}. Wrap IPv6 addresses in brackets, e.g. --remote-chrome "[2001:db8::1]:9222".`);
+        }
+    }
+    if (!host) {
+        throw new Error(`Invalid remote-chrome format: ${target}. Host portion is missing; expected host:port.`);
+    }
+    const port = Number.parseInt(portSegment ?? '', 10);
+    if (!Number.isFinite(port) || port <= 0 || port > 65_535) {
+        throw new Error(`Invalid remote-chrome port: "${portSegment ?? ''}". Expected a number between 1 and 65535.`);
+    }
+    return { host, port };
+}
+function parseCookieNames(raw) {
+    if (!raw)
+        return undefined;
+    const names = raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    return names.length ? names : undefined;
+}
+async function resolveInlineCookies({ inlineArg, inlineFileArg, envPayload, envFile, cwd, }) {
+    const tryLoad = async (source, allowPathResolution) => {
+        if (!source)
+            return undefined;
+        const trimmed = source.trim();
+        if (!trimmed)
+            return undefined;
+        if (allowPathResolution) {
+            const resolved = path.isAbsolute(trimmed) ? trimmed : path.join(cwd, trimmed);
+            try {
+                const stat = await fs.stat(resolved);
+                if (stat.isFile()) {
+                    const fileContent = await fs.readFile(resolved, 'utf8');
+                    const parsed = parseInlineCookiesPayload(fileContent);
+                    if (parsed)
+                        return parsed;
+                }
+            }
+            catch {
+                // not a file; treat as payload below
+            }
+        }
+        return parseInlineCookiesPayload(trimmed);
+    };
+    const sources = [
+        { value: inlineFileArg, allowPath: true, source: 'inline-file' },
+        { value: inlineArg, allowPath: true, source: 'inline-arg' },
+        { value: envFile, allowPath: true, source: 'env-file' },
+        { value: envPayload, allowPath: false, source: 'env-payload' },
+    ];
+    for (const { value, allowPath, source } of sources) {
+        const parsed = await tryLoad(value, allowPath);
+        if (parsed)
+            return { cookies: parsed, source };
+    }
+    // fallback: ~/.oracle/cookies.{json,base64}
+    const oracleHome = getOracleHomeDir();
+    const candidates = ['cookies.json', 'cookies.base64'];
+    for (const file of candidates) {
+        const fullPath = path.join(oracleHome, file);
+        try {
+            const stat = await fs.stat(fullPath);
+            if (!stat.isFile())
+                continue;
+            const content = await fs.readFile(fullPath, 'utf8');
+            const parsed = parseInlineCookiesPayload(content);
+            if (parsed)
+                return { cookies: parsed, source: `home:${file}` };
+        }
+        catch {
+            // ignore missing/invalid
+        }
+    }
+    return undefined;
+}
+function parseInlineCookiesPayload(raw) {
+    if (!raw)
+        return undefined;
+    const text = raw.trim();
+    if (!text)
+        return undefined;
+    let jsonPayload = text;
+    // Attempt base64 decode first; fall back to raw text on failure.
+    try {
+        const decoded = Buffer.from(text, 'base64').toString('utf8');
+        if (decoded.trim().startsWith('[')) {
+            jsonPayload = decoded;
+        }
+    }
+    catch {
+        // not base64; continue with raw text
+    }
+    try {
+        const parsed = JSON.parse(jsonPayload);
+        if (Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // invalid json; skip silently to keep this hidden flag non-fatal
+    }
+    return undefined;
+}

package/dist/src/cli/browserDefaults.js

@@ -0,0 +1,81 @@
+import { normalizeChatgptUrl, CHATGPT_URL } from '../browserMode.js';
+export function applyBrowserDefaultsFromConfig(options, config, getSource) {
+    const browser = config.browser;
+    if (!browser)
+        return;
+    const isUnset = (key) => {
+        const source = getSource(key);
+        return source === undefined || source === 'default';
+    };
+    const configuredChatgptUrl = browser.chatgptUrl ?? browser.url;
+    const cliChatgptSet = options.chatgptUrl !== undefined || options.browserUrl !== undefined;
+    if (isUnset('chatgptUrl') && !cliChatgptSet && configuredChatgptUrl !== undefined) {
+        options.chatgptUrl = normalizeChatgptUrl(configuredChatgptUrl ?? '', CHATGPT_URL);
+    }
+    if (isUnset('browserChromeProfile') && browser.chromeProfile !== undefined) {
+        options.browserChromeProfile = browser.chromeProfile ?? undefined;
+    }
+    if (isUnset('browserChromePath') && browser.chromePath !== undefined) {
+        options.browserChromePath = browser.chromePath ?? undefined;
+    }
+    if (isUnset('browserCookiePath') && browser.chromeCookiePath !== undefined) {
+        options.browserCookiePath = browser.chromeCookiePath ?? undefined;
+    }
+    if (isUnset('browserUrl') && options.browserUrl === undefined && browser.url !== undefined) {
+        options.browserUrl = browser.url;
+    }
+    if (isUnset('browserTimeout') && typeof browser.timeoutMs === 'number') {
+        options.browserTimeout = String(browser.timeoutMs);
+    }
+    if (isUnset('browserPort') && typeof browser.debugPort === 'number') {
+        options.browserPort = browser.debugPort;
+    }
+    if (isUnset('browserInputTimeout') && typeof browser.inputTimeoutMs === 'number') {
+        options.browserInputTimeout = String(browser.inputTimeoutMs);
+    }
+    if (isUnset('browserRecheckDelay') && typeof browser.assistantRecheckDelayMs === 'number') {
+        options.browserRecheckDelay = String(browser.assistantRecheckDelayMs);
+    }
+    if (isUnset('browserRecheckTimeout') && typeof browser.assistantRecheckTimeoutMs === 'number') {
+        options.browserRecheckTimeout = String(browser.assistantRecheckTimeoutMs);
+    }
+    if (isUnset('browserReuseWait') && typeof browser.reuseChromeWaitMs === 'number') {
+        options.browserReuseWait = String(browser.reuseChromeWaitMs);
+    }
+    if (isUnset('browserProfileLockTimeout') && typeof browser.profileLockTimeoutMs === 'number') {
+        options.browserProfileLockTimeout = String(browser.profileLockTimeoutMs);
+    }
+    if (isUnset('browserAutoReattachDelay') && typeof browser.autoReattachDelayMs === 'number') {
+        options.browserAutoReattachDelay = String(browser.autoReattachDelayMs);
+    }
+    if (isUnset('browserAutoReattachInterval') && typeof browser.autoReattachIntervalMs === 'number') {
+        options.browserAutoReattachInterval = String(browser.autoReattachIntervalMs);
+    }
+    if (isUnset('browserAutoReattachTimeout') && typeof browser.autoReattachTimeoutMs === 'number') {
+        options.browserAutoReattachTimeout = String(browser.autoReattachTimeoutMs);
+    }
+    if (isUnset('browserCookieWait') && typeof browser.cookieSyncWaitMs === 'number') {
+        options.browserCookieWait = String(browser.cookieSyncWaitMs);
+    }
+    if (isUnset('browserHeadless') && browser.headless !== undefined) {
+        options.browserHeadless = browser.headless;
+    }
+    if (isUnset('browserHideWindow') && browser.hideWindow !== undefined) {
+        options.browserHideWindow = browser.hideWindow;
+    }
+    if (isUnset('browserKeepBrowser') && browser.keepBrowser !== undefined) {
+        options.browserKeepBrowser = browser.keepBrowser;
+    }
+    if (isUnset('browserModelStrategy') && browser.modelStrategy !== undefined) {
+        options.browserModelStrategy = browser.modelStrategy;
+    }
+    if (isUnset('browserThinkingTime') && browser.thinkingTime !== undefined) {
+        options.browserThinkingTime = browser.thinkingTime;
+    }
+    if (isUnset('browserManualLogin') && browser.manualLogin !== undefined) {
+        options.browserManualLogin = browser.manualLogin;
+    }
+    if (isUnset('browserManualLoginProfileDir') && browser.manualLoginProfileDir !== undefined) {
+        options.browserManualLoginProfileDir = browser.manualLoginProfileDir;
+    }
+}

package/dist/src/cli/bundleWarnings.js

@@ -0,0 +1,9 @@
+import chalk from 'chalk';
+export function warnIfOversizeBundle(estimatedTokens, threshold = 196_000, log = console.log) {
+    if (Number.isNaN(estimatedTokens) || estimatedTokens <= threshold) {
+        return false;
+    }
+    const msg = `Warning: bundle is ~${estimatedTokens.toLocaleString()} tokens (>${threshold.toLocaleString()}); may exceed model limits.`;
+    log(chalk.red(msg));
+    return true;
+}

package/dist/src/cli/clipboard.js

@@ -0,0 +1,10 @@
+import clipboard from 'clipboardy';
+export async function copyToClipboard(text) {
+    try {
+        await clipboard.write(text);
+        return { success: true, command: 'clipboardy' };
+    }
+    catch (error) {
+        return { success: false, error };
+    }
+}

package/dist/src/cli/detach.js

@@ -0,0 +1,11 @@
+import { isProModel } from '../oracle/modelResolver.js';
+export function shouldDetachSession({ 
+// Params kept for future policy tweaks; currently only model/disableDetachEnv matter.
+engine, model, waitPreference: _waitPreference, disableDetachEnv, }) {
+    if (disableDetachEnv)
+        return false;
+    // Only Pro-tier API runs should start detached by default; browser runs stay inline so failures surface.
+    if (isProModel(model) && engine === 'api')
+        return true;
+    return false;
+}

package/dist/src/cli/dryRun.js

@@ -0,0 +1,105 @@
+import chalk from 'chalk';
+import { MODEL_CONFIGS, TOKENIZER_OPTIONS, DEFAULT_SYSTEM_PROMPT, buildPrompt, readFiles, getFileTokenStats, printFileTokenStats, } from '../oracle.js';
+import { isKnownModel } from '../oracle/modelResolver.js';
+import { assembleBrowserPrompt } from '../browser/prompt.js';
+import { buildTokenEstimateSuffix, formatAttachmentLabel } from '../browser/promptSummary.js';
+import { buildCookiePlan } from '../browser/policies.js';
+export async function runDryRunSummary({ engine, runOptions, cwd, version, log, browserConfig, }, deps = {}) {
+    if (engine === 'browser') {
+        await runBrowserDryRun({ runOptions, cwd, version, log, browserConfig }, deps);
+        return;
+    }
+    await runApiDryRun({ runOptions, cwd, version, log }, deps);
+}
+async function runApiDryRun({ runOptions, cwd, version, log, }, deps) {
+    const readFilesImpl = deps.readFilesImpl ?? readFiles;
+    const files = await readFilesImpl(runOptions.file ?? [], { cwd });
+    const systemPrompt = runOptions.system?.trim() || DEFAULT_SYSTEM_PROMPT;
+    const combinedPrompt = buildPrompt(runOptions.prompt ?? '', files, cwd);
+    const modelConfig = isKnownModel(runOptions.model) ? MODEL_CONFIGS[runOptions.model] : MODEL_CONFIGS['gpt-5.1'];
+    const tokenizer = modelConfig.tokenizer;
+    const estimatedInputTokens = tokenizer([
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: combinedPrompt },
+    ], TOKENIZER_OPTIONS);
+    const headerLine = `[dry-run] Oracle (${version}) would call ${runOptions.model} with ~${estimatedInputTokens.toLocaleString()} tokens and ${files.length} files.`;
+    log(chalk.cyan(headerLine));
+    if (files.length === 0) {
+        log(chalk.dim('[dry-run] No files matched the provided --file patterns.'));
+        return;
+    }
+    const inputBudget = runOptions.maxInput ?? modelConfig.inputLimit;
+    const stats = getFileTokenStats(files, {
+        cwd,
+        tokenizer,
+        tokenizerOptions: TOKENIZER_OPTIONS,
+        inputTokenBudget: inputBudget,
+    });
+    printFileTokenStats(stats, { inputTokenBudget: inputBudget, log });
+}
+async function runBrowserDryRun({ runOptions, cwd, version, log, browserConfig, }, deps) {
+    const assemblePromptImpl = deps.assembleBrowserPromptImpl ?? assembleBrowserPrompt;
+    const artifacts = await assemblePromptImpl(runOptions, { cwd });
+    const suffix = buildTokenEstimateSuffix(artifacts);
+    const headerLine = `[dry-run] Oracle (${version}) would launch browser mode (${runOptions.model}) with ~${artifacts.estimatedInputTokens.toLocaleString()} tokens${suffix}.`;
+    log(chalk.cyan(headerLine));
+    logBrowserCookieStrategy(browserConfig, log, 'dry-run');
+    logBrowserFileSummary(artifacts, log, 'dry-run');
+}
+function logBrowserCookieStrategy(browserConfig, log, label) {
+    if (!browserConfig)
+        return;
+    const plan = buildCookiePlan(browserConfig);
+    log(chalk.bold(`[${label}] ${plan.description}`));
+}
+function logBrowserFileSummary(artifacts, log, label) {
+    if (artifacts.attachments.length > 0) {
+        const prefix = artifacts.bundled ? `[${label}] Bundled upload:` : `[${label}] Attachments to upload:`;
+        log(chalk.bold(prefix));
+        artifacts.attachments.forEach((attachment) => {
+            log(`  • ${formatAttachmentLabel(attachment)}`);
+        });
+        if (artifacts.bundled) {
+            log(chalk.dim(`  (bundled ${artifacts.bundled.originalCount} files into ${artifacts.bundled.bundlePath})`));
+        }
+        return;
+    }
+    if (artifacts.inlineFileCount > 0) {
+        log(chalk.bold(`[${label}] Inline file content:`));
+        log(`  • ${artifacts.inlineFileCount} file${artifacts.inlineFileCount === 1 ? '' : 's'} pasted directly into the composer.`);
+        return;
+    }
+    log(chalk.dim(`[${label}] No files attached.`));
+}
+export async function runBrowserPreview({ runOptions, cwd, version, previewMode, log, }, deps = {}) {
+    const assemblePromptImpl = deps.assembleBrowserPromptImpl ?? assembleBrowserPrompt;
+    const artifacts = await assemblePromptImpl(runOptions, { cwd });
+    const suffix = buildTokenEstimateSuffix(artifacts);
+    const headerLine = `[preview] Oracle (${version}) browser mode (${runOptions.model}) with ~${artifacts.estimatedInputTokens.toLocaleString()} tokens${suffix}.`;
+    log(chalk.cyan(headerLine));
+    logBrowserFileSummary(artifacts, log, 'preview');
+    if (previewMode === 'json' || previewMode === 'full') {
+        const attachmentSummary = artifacts.attachments.map((attachment) => ({
+            path: attachment.path,
+            displayPath: attachment.displayPath,
+            sizeBytes: attachment.sizeBytes,
+        }));
+        const previewPayload = {
+            model: runOptions.model,
+            engine: 'browser',
+            composerText: artifacts.composerText,
+            attachments: attachmentSummary,
+            inlineFileCount: artifacts.inlineFileCount,
+            bundled: artifacts.bundled,
+            tokenEstimate: artifacts.estimatedInputTokens,
+        };
+        log('');
+        log(chalk.bold('Preview JSON'));
+        log(JSON.stringify(previewPayload, null, 2));
+    }
+    if (previewMode === 'full') {
+        log('');
+        log(chalk.bold('Composer Text'));
+        log(artifacts.composerText || chalk.dim('(empty prompt)'));
+    }
+}

package/dist/src/cli/duplicatePromptGuard.js

@@ -0,0 +1,14 @@
+import chalk from 'chalk';
+export async function shouldBlockDuplicatePrompt({ prompt, force, sessionStore, log = console.log, }) {
+    if (force)
+        return false;
+    const normalized = prompt?.trim();
+    if (!normalized)
+        return false;
+    const running = (await sessionStore.listSessions()).filter((entry) => entry.status === 'running');
+    const duplicate = running.find((entry) => (entry.options?.prompt?.trim?.() ?? '') === normalized);
+    if (!duplicate)
+        return false;
+    log(chalk.yellow(`A session with the same prompt is already running (${duplicate.id}). Reattach with "oracle session ${duplicate.id}" or rerun with --force to start another run.`));
+    return true;
+}

package/dist/src/cli/engine.js

@@ -0,0 +1,41 @@
+import { isProModel } from '../oracle/modelResolver.js';
+export function defaultWaitPreference(model, engine) {
+    // Pro-class API runs can take a long time; prefer non-blocking unless explicitly overridden.
+    if (engine === 'api' && isProModel(model)) {
+        return false;
+    }
+    return true; // browser or non-pro models are fast enough to block by default
+}
+/**
+ * Determine which engine to use based on CLI flags and the environment.
+ *
+ * Precedence:
+ * 1) Legacy --browser flag forces browser.
+ * 2) Explicit --engine value.
+ * 3) ORACLE_ENGINE environment override (api|browser).
+ * 4) OPENAI_API_KEY decides: api when set, otherwise browser.
+ */
+export function resolveEngine({ engine, browserFlag, env, }) {
+    if (browserFlag) {
+        return 'browser';
+    }
+    if (engine) {
+        return engine;
+    }
+    const envEngine = normalizeEngineMode(env.ORACLE_ENGINE);
+    if (envEngine) {
+        return envEngine;
+    }
+    return env.OPENAI_API_KEY ? 'api' : 'browser';
+}
+function normalizeEngineMode(raw) {
+    if (typeof raw !== 'string') {
+        return null;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === 'api')
+        return 'api';
+    if (normalized === 'browser')
+        return 'browser';
+    return null;
+}

package/dist/src/cli/errorUtils.js

@@ -0,0 +1,9 @@
+const LOGGED_SYMBOL = Symbol('oracle.alreadyLogged');
+export function markErrorLogged(error) {
+    if (error instanceof Error) {
+        error[LOGGED_SYMBOL] = true;
+    }
+}
+export function isErrorLogged(error) {
+    return Boolean(error instanceof Error && error[LOGGED_SYMBOL]);
+}

package/dist/src/cli/format.js

@@ -0,0 +1,13 @@
+export function formatCompactNumber(value) {
+    if (Number.isNaN(value) || !Number.isFinite(value))
+        return '0';
+    const abs = Math.abs(value);
+    const stripTrailingZero = (text) => text.replace(/\.0$/, '');
+    if (abs >= 1_000_000) {
+        return `${stripTrailingZero((value / 1_000_000).toFixed(1))}m`;
+    }
+    if (abs >= 1_000) {
+        return `${stripTrailingZero((value / 1_000).toFixed(1))}k`;
+    }
+    return value.toLocaleString();
+}

package/dist/src/cli/help.js

@@ -0,0 +1,77 @@
+import kleur from 'kleur';
+const createColorWrapper = (isTty) => (styler) => (text) => isTty ? styler(text) : text;
+export function applyHelpStyling(program, version, isTty) {
+    const wrap = createColorWrapper(isTty);
+    const colors = {
+        banner: wrap((text) => kleur.bold().blue(text)),
+        subtitle: wrap((text) => kleur.dim(text)),
+        section: wrap((text) => kleur.bold().white(text)),
+        bullet: wrap((text) => kleur.blue(text)),
+        command: wrap((text) => kleur.bold().blue(text)),
+        option: wrap((text) => kleur.cyan(text)),
+        argument: wrap((text) => kleur.magenta(text)),
+        description: wrap((text) => kleur.white(text)),
+        muted: wrap((text) => kleur.gray(text)),
+        accent: wrap((text) => kleur.cyan(text)),
+    };
+    program.configureHelp({
+        styleTitle(title) {
+            return colors.section(title);
+        },
+        styleDescriptionText(text) {
+            return colors.description(text);
+        },
+        styleCommandText(text) {
+            return colors.command(text);
+        },
+        styleSubcommandText(text) {
+            return colors.command(text);
+        },
+        styleOptionText(text) {
+            return colors.option(text);
+        },
+        styleArgumentText(text) {
+            return colors.argument(text);
+        },
+    });
+    program.addHelpText('beforeAll', () => renderHelpBanner(version, colors));
+    program.addHelpText('after', () => renderHelpFooter(program, colors));
+}
+function renderHelpBanner(version, colors) {
+    const subtitle = 'Prompt + files required — GPT-5.2 Pro/GPT-5.2 for tough questions with code/file context.';
+    return `${colors.banner(`Oracle CLI v${version}`)} ${colors.subtitle(`— ${subtitle}`)}\n`;
+}
+function renderHelpFooter(program, colors) {
+    const tips = [
+        `${colors.bullet('•')} Required: always pass a prompt AND ${colors.accent('--file …')} (directories/globs are fine); Oracle cannot see your project otherwise.`,
+        `${colors.bullet('•')} Attach lots of source (whole directories beat single files) and keep total input under ~196k tokens.`,
+        `${colors.bullet('•')} Oracle starts empty—open with a short project briefing (stack, services, build steps), spell out the question and prior attempts, and why it matters; the more explanation and context you provide, the better the response will be.`,
+        `${colors.bullet('•')} Spell out the project + platform + version requirements (repo name, target OS/toolchain versions, API dependencies) so Oracle doesn’t guess defaults.`,
+        `${colors.bullet('•')} When comparing multiple repos/files, spell out each repo + path + role (e.g., “Project A SettingsView → apps/project-a/Sources/SettingsView.swift; Project B SettingsView → ../project-b/mac/...”) so the model knows exactly which file is which.`,
+        `${colors.bullet('•')} Best results: 6–30 sentences plus key source files; very short prompts often yield generic answers.`,
+        `${colors.bullet('•')} Oracle is one-shot: it does not remember prior runs, so start fresh each time with full context.`,
+        `${colors.bullet('•')} Run ${colors.accent('--files-report')} to inspect token spend before hitting the API.`,
+        `${colors.bullet('•')} Non-preview runs spawn detached sessions (especially gpt-5.2-pro API). If the CLI times out, do not re-run — reattach with ${colors.accent('oracle session <slug>')} to resume/inspect the existing run.`,
+        `${colors.bullet('•')} Set a memorable 3–5 word slug via ${colors.accent('--slug "<words>"')} to keep session IDs tidy.`,
+        `${colors.bullet('•')} Finished sessions auto-hide preamble logs when reattached; raw timestamps remain in the saved log file.`,
+        `${colors.bullet('•')} Need hidden flags? Run ${colors.accent(`${program.name()} --help --verbose`)} to list search/token/browser overrides.`,
+        `${colors.bullet('•')} If any Oracle session is already running, do not start new API runs. Attach to the existing browser session instead; only trigger API calls when you explicitly mean to.`,
+        `${colors.bullet('•')} Duplicate prompt guard: if the same prompt is already running, new runs are blocked unless you pass ${colors.accent('--force')}—prefer reattaching instead of spawning duplicates.`,
+    ].join('\n');
+    const formatExample = (command, description) => `${colors.command(`  ${command}`)}\n${colors.muted(`    ${description}`)}`;
+    const examples = [
+        formatExample(`${program.name()} --render --copy --prompt "Review the TS data layer for schema drift" --file "src/**/*.ts,*/*.test.ts"`, 'Build the bundle, print it, and copy it for manual paste into ChatGPT.'),
+        formatExample(`${program.name()} --prompt "Cross-check the data layer assumptions" --models gpt-5.2-pro,gemini-3-pro --file "src/**/*.ts"`, 'Run multiple API models in one go and aggregate cost/usage.'),
+        formatExample(`${program.name()} status --hours 72 --limit 50`, 'Show sessions from the last 72h (capped at 50 entries).'),
+        formatExample(`${program.name()} session <sessionId>`, 'Attach to a running/completed session and stream the saved transcript.'),
+        formatExample(`${program.name()} --prompt "Ship review" --slug "release-readiness-audit"`, 'Encourage the model to hand you a 3–5 word slug and pass it along with --slug.'),
+        formatExample(`${program.name()} --prompt "Tabs frozen: compare Project A SettingsView (apps/project-a/Sources/SettingsView.swift) vs Project B SettingsView (../project-b/mac/App/Presentation/Views/SettingsView.swift)" --file apps/project-a/Sources/SettingsView.swift --file ../project-b/mac/App/Presentation/Views/SettingsView.swift`, 'Spell out what each attached file is (repo + path + role) before asking for comparisons so the model knows exactly what it is reading.'),
+    ].join('\n\n');
+    return `
+${colors.section('Tips')}
+${tips}
+
+${colors.section('Examples')}
+${examples}
+`;
+}