@steipete/oracle 1.1.0 → 1.2.0

package/README.md

@@ -20,6 +20,9 @@ Oracle gives your agents a simple, reliable way to **bundle a prompt plus the ri
 
 If you omit `--engine`, Oracle prefers the API engine when `OPENAI_API_KEY` is present; otherwise it falls back to browser mode. Switch explicitly with `-e, --engine {api|browser}` when you want to override the auto choice. Everything else (prompt assembly, file handling, session logging) stays the same.
 
+Note: Browser engine is considered experimental, requires an OpenAI Pro account and only works on macOS with Chrome.
+Your system password is needed to copy cookies. API engine is stable and should be preferred.
+
 ## Quick start
 
 ```bash
@@ -43,8 +46,23 @@ oracle session <id>                 # replay a run locally
 
 ## How do I integrate this?
 
-- **One-liner in CI** — `OPENAI_API_KEY=sk-... npx -y @steipete/oracle --prompt "Smoke-check latest PR" --file src/ docs/ --preview summary` (add to your pipeline as a non-blocking report step).
-- **Package script** — In `package.json`: `"oracle": "oracle --prompt \"Review the diff\" --file ."` then run `OPENAI_API_KEY=... pnpm oracle`.
+**CLI** (direct calls; great for CI or scripted tasks)
+- One-liner in CI: `OPENAI_API_KEY=sk-... npx -y @steipete/oracle --prompt "Smoke-check latest PR" --file src/ docs/ --preview summary`.
+- Package script: add `"oracle": "oracle --prompt \"Review the diff\" --file ."` to `package.json`, then run `OPENAI_API_KEY=... pnpm oracle`.
+- Don’t want to export the key? Inline works: `OPENAI_API_KEY=sk-... oracle -p "Quick check" --file src/`.
+
+**MCP** (tools + resources; mix-and-match with the CLI sessions)
+- Run the bundled stdio server: `pnpm mcp` (or `oracle-mcp`) after `pnpm build`. Tools: `consult`, `sessions`; resources: `oracle-session://{id}/{metadata|log|request}`. Details in [docs/mcp.md](docs/mcp.md).
+- mcporter config (stdio):
+  ```json
+  {
+    "name": "oracle",
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@steipete/oracle", "oracle-mcp"]
+  }
+  ```
+- You can call the MCP tools against sessions created by the CLI (shared `~/.oracle/sessions`), and vice versa.
 
 ## Highlights
 
@@ -56,17 +74,22 @@ oracle session <id>                 # replay a run locally
 - **File safety** — Per-file token accounting and size guards; `--files-report` shows exactly what you’re sending.
 - **Readable previews** — `--preview` / `--render-markdown` let you inspect the bundle before spending.
 
+## Configuration
+
+Put per-user defaults in `~/.oracle/config.json` (parsed as JSON5, so comments/trailing commas are fine). Example settings cover default engine/model, notifications, browser defaults, and prompt suffixes. See `docs/configuration.md` for a complete example and precedence.
+
 ## Flags you’ll actually use
 
 | Flag | Purpose |
 | --- | --- |
 | `-p, --prompt <text>` | Required prompt. |
 | `-f, --file <paths...>` | Attach files/dirs (supports globs and `!` excludes). |
-| `-e, --engine <api|browser>` | Choose API or browser automation. Omitted: API when `OPENAI_API_KEY` is set, otherwise browser. |
+| `-e, --engine <api\|browser>` | Choose API or browser automation. Omitted: API when `OPENAI_API_KEY` is set, otherwise browser. |
 | `-m, --model <name>` | `gpt-5-pro` (default) or `gpt-5.1`. |
 | `--files-report` | Print per-file token usage. |
-| `--preview [summary|json|full]` | Inspect the request without sending. |
+| `--preview [summary\|json\|full]` | Inspect the request without sending. |
 | `--render-markdown` | Print the assembled `[SYSTEM]/[USER]/[FILE]` bundle. |
+| `--wait` / `--no-wait` | Block until completion. Default: `wait` for gpt-5.1/browser; `no-wait` for gpt-5-pro API (reattach later). |
 | `-v, --verbose` | Extra logging (also surfaces advanced flags with `--help`). |
 
 More knobs (`--max-input`, cookie sync controls for browser mode, etc.) live behind `oracle --help --verbose`.
@@ -78,6 +101,8 @@ Add `--render` (alias `--render-markdown`) when attaching to pretty-print the st
 
 **Recommendation:** Prefer the API engine when you have an API key (`--engine api` or just set `OPENAI_API_KEY`). The API delivers more reliable results and supports longer, uninterrupted runs than the browser engine in most cases.
 
+**Wait vs no-wait:** gpt-5-pro API runs default to detaching (shows a reattach hint); add `--wait` to stay attached. gpt-5.1 and browser runs block by default. You can reattach anytime via `oracle session <id>`.
+
 ## Testing
 
 ```bash

package/dist/bin/oracle-cli.js

@@ -3,7 +3,7 @@ import 'dotenv/config';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { Command, Option } from 'commander';
-import { resolveEngine } from '../src/cli/engine.js';
+import { resolveEngine, defaultWaitPreference } from '../src/cli/engine.js';
 import { shouldRequirePrompt } from '../src/cli/promptRequirement.js';
 import chalk from 'chalk';
 import { ensureSessionStorage, initializeSession, readSessionMetadata, createSessionLogWriter, deleteSessionsOlderThan, } from '../src/sessionManager.js';
@@ -11,34 +11,45 @@ import { runOracle, renderPromptMarkdown, readFiles } from '../src/oracle.js';
 import { CHATGPT_URL } from '../src/browserMode.js';
 import { applyHelpStyling } from '../src/cli/help.js';
 import { collectPaths, parseFloatOption, parseIntOption, parseSearchOption, usesDefaultStatusFilters, resolvePreviewMode, normalizeModelOption, resolveApiModel, inferModelFromLabel, parseHeartbeatOption, } from '../src/cli/options.js';
+import { applyHiddenAliases } from '../src/cli/hiddenAliases.js';
 import { buildBrowserConfig, resolveBrowserModelLabel } from '../src/cli/browserConfig.js';
 import { performSessionRun } from '../src/cli/sessionRunner.js';
-import { attachSession, showStatus } from '../src/cli/sessionDisplay.js';
+import { attachSession, showStatus, formatCompletionSummary } from '../src/cli/sessionDisplay.js';
 import { handleSessionCommand, formatSessionCleanupMessage } from '../src/cli/sessionCommand.js';
 import { isErrorLogged } from '../src/cli/errorUtils.js';
 import { handleSessionAlias, handleStatusFlag } from '../src/cli/rootAlias.js';
 import { getCliVersion } from '../src/version.js';
-import { runDryRunSummary } from '../src/cli/dryRun.js';
+import { runDryRunSummary, runBrowserPreview } from '../src/cli/dryRun.js';
+import { launchTui } from '../src/cli/tui/index.js';
+import { resolveNotificationSettings, deriveNotificationSettingsFromMetadata, } from '../src/cli/notifier.js';
+import { loadUserConfig } from '../src/config.js';
 const VERSION = getCliVersion();
 const CLI_ENTRYPOINT = fileURLToPath(import.meta.url);
 const rawCliArgs = process.argv.slice(2);
+const userCliArgs = rawCliArgs[0] === CLI_ENTRYPOINT ? rawCliArgs.slice(1) : rawCliArgs;
 const isTty = process.stdout.isTTY;
+const tuiEnabled = () => isTty && process.env.ORACLE_NO_TUI !== '1';
 const program = new Command();
 applyHelpStyling(program, VERSION, isTty);
 program.hook('preAction', (thisCommand) => {
     if (thisCommand !== program) {
         return;
     }
-    if (rawCliArgs.some((arg) => arg === '--help' || arg === '-h')) {
+    if (userCliArgs.some((arg) => arg === '--help' || arg === '-h')) {
+        return;
+    }
+    if (userCliArgs.length === 0 && tuiEnabled()) {
+        // Skip prompt enforcement; runRootCommand will launch the TUI.
         return;
     }
     const opts = thisCommand.optsWithGlobals();
+    applyHiddenAliases(opts, (key, value) => thisCommand.setOptionValue(key, value));
     const positional = thisCommand.args?.[0];
     if (!opts.prompt && positional) {
         opts.prompt = positional;
         thisCommand.setOptionValue('prompt', positional);
     }
-    if (shouldRequirePrompt(rawCliArgs, opts)) {
+    if (shouldRequirePrompt(userCliArgs, opts)) {
         console.log(chalk.yellow('Prompt is required. Provide it via --prompt "<text>" or positional [prompt].'));
         thisCommand.help({ error: false });
         process.exitCode = 1;
@@ -51,12 +62,20 @@ program
     .version(VERSION)
     .argument('[prompt]', 'Prompt text (shorthand for --prompt).')
     .option('-p, --prompt <text>', 'User prompt to send to the model.')
+    .addOption(new Option('--message <text>', 'Alias for --prompt.').hideHelp())
     .option('-f, --file <paths...>', 'Files/directories or glob patterns to attach (prefix with !pattern to exclude). Files larger than 1 MB are rejected automatically.', collectPaths, [])
+    .addOption(new Option('--include <paths...>', 'Alias for --file.')
+    .argParser(collectPaths)
+    .default([])
+    .hideHelp())
     .option('-s, --slug <words>', 'Custom session slug (3-5 words).')
     .option('-m, --model <model>', 'Model to target (gpt-5-pro | gpt-5.1, or ChatGPT labels like "5.1 Instant" for browser runs).', normalizeModelOption, 'gpt-5-pro')
-    .addOption(new Option('-e, --engine <mode>', 'Execution engine (api | browser). If omitted, Oracle picks api when OPENAI_API_KEY is set, otherwise browser.').choices(['api', 'browser']))
+    .addOption(new Option('-e, --engine <mode>', 'Execution engine (api | browser). If omitted, oracle picks api when OPENAI_API_KEY is set, otherwise browser.').choices(['api', 'browser']))
     .option('--files-report', 'Show token usage per attached file (also prints automatically when files exceed the token budget).', false)
     .option('-v, --verbose', 'Enable verbose logging for all operations.', false)
+    .addOption(new Option('--[no-]notify', 'Desktop notification when a session finishes (default on unless CI/SSH).')
+    .default(undefined))
+    .addOption(new Option('--[no-]notify-sound', 'Play a notification sound on completion (default off).').default(undefined))
     .option('--dry-run', 'Validate inputs and show token estimates without calling the model.', false)
     .addOption(new Option('--preview [mode]', 'Preview the request without calling the API (summary | json | full).')
     .choices(['summary', 'json', 'full'])
@@ -87,8 +106,11 @@ program
     .addOption(new Option('--browser-keep-browser', 'Keep Chrome running after completion.').hideHelp())
     .addOption(new Option('--browser-allow-cookie-errors', 'Continue even if Chrome cookies cannot be copied.').hideHelp())
     .addOption(new Option('--browser-inline-files', 'Paste files directly into the ChatGPT composer instead of uploading attachments.').default(false))
+    .addOption(new Option('--browser-bundle-files', 'Bundle all attachments into a single archive before uploading.').default(false))
     .option('--debug-help', 'Show the advanced/debug option set and exit.', false)
     .option('--heartbeat <seconds>', 'Emit periodic in-progress updates (0 to disable).', parseHeartbeatOption, 30)
+    .addOption(new Option('--wait').default(undefined))
+    .addOption(new Option('--no-wait').default(undefined).hideHelp())
     .showHelpAfterError('(use --help for usage)');
 program.addHelpText('after', `
 Examples:
@@ -106,6 +128,7 @@ const sessionCommand = program
     .option('--limit <count>', 'Maximum sessions to show when listing (max 1000).', parseIntOption, 100)
     .option('--all', 'Include all stored sessions regardless of age.', false)
     .option('--clear', 'Delete stored sessions older than the provided window (24h default).', false)
+    .option('--hide-prompt', 'Hide stored prompt when displaying a session.', false)
     .option('--render', 'Render completed session output as markdown (rich TTY only).', false)
     .option('--render-markdown', 'Alias for --render.', false)
     .option('--path', 'Print the stored session paths instead of attaching.', false)
@@ -122,6 +145,7 @@ const statusCommand = program
     .option('--clear', 'Delete stored sessions older than the provided window (24h default).', false)
     .option('--render', 'Render completed session output as markdown (rich TTY only).', false)
     .option('--render-markdown', 'Alias for --render.', false)
+    .option('--hide-prompt', 'Hide stored prompt when displaying a session.', false)
     .addOption(new Option('--clean', 'Deprecated alias for --clear.').default(false).hideHelp())
     .action(async (sessionId, _options, command) => {
     const statusOptions = command.opts();
@@ -145,7 +169,11 @@ const statusCommand = program
         return;
     }
     if (sessionId) {
-        await attachSession(sessionId);
+        const autoRender = !command.getOptionValueSource?.('render') && !command.getOptionValueSource?.('renderMarkdown')
+            ? process.stdout.isTTY
+            : false;
+        const renderMarkdown = Boolean(statusOptions.render || statusOptions.renderMarkdown || autoRender);
+        await attachSession(sessionId, { renderMarkdown, renderPrompt: !statusOptions.hidePrompt });
         return;
     }
     const showExamples = usesDefaultStatusFilters(command);
@@ -178,9 +206,16 @@ function buildRunOptions(options, overrides = {}) {
         verbose: overrides.verbose ?? options.verbose,
         heartbeatIntervalMs: overrides.heartbeatIntervalMs ?? resolveHeartbeatIntervalMs(options.heartbeat),
         browserInlineFiles: overrides.browserInlineFiles ?? options.browserInlineFiles ?? false,
+        browserBundleFiles: overrides.browserBundleFiles ?? options.browserBundleFiles ?? false,
         background: overrides.background ?? undefined,
     };
 }
+export function enforceBrowserSearchFlag(runOptions, sessionMode, logFn = console.log) {
+    if (sessionMode === 'browser' && runOptions.search === false) {
+        logFn(chalk.dim('Note: search is not available in browser engine; ignoring search=false.'));
+        runOptions.search = undefined;
+    }
+}
 function resolveHeartbeatIntervalMs(seconds) {
     if (typeof seconds !== 'number' || seconds <= 0) {
         return undefined;
@@ -199,7 +234,7 @@ function buildRunOptionsFromMetadata(metadata) {
         maxOutput: stored.maxOutput,
         system: stored.system,
         silent: stored.silent,
-        search: undefined,
+        search: stored.search,
         preview: false,
         previewMode: undefined,
         apiKey: undefined,
@@ -207,6 +242,7 @@ function buildRunOptionsFromMetadata(metadata) {
         verbose: stored.verbose,
         heartbeatIntervalMs: stored.heartbeatIntervalMs,
         browserInlineFiles: stored.browserInlineFiles,
+        browserBundleFiles: stored.browserBundleFiles,
         background: stored.background,
     };
 }
@@ -217,6 +253,7 @@ function getBrowserConfigFromMetadata(metadata) {
     return metadata.options?.browserConfig ?? metadata.browser?.config;
 }
 async function runRootCommand(options) {
+    const userConfig = (await loadUserConfig()).config;
     const helpRequested = rawCliArgs.some((arg) => arg === '--help' || arg === '-h');
     if (helpRequested) {
         if (options.verbose) {
@@ -228,7 +265,11 @@ async function runRootCommand(options) {
         return;
     }
     const previewMode = resolvePreviewMode(options.preview);
-    if (rawCliArgs.length === 0) {
+    if (userCliArgs.length === 0) {
+        if (tuiEnabled()) {
+            await launchTui({ version: VERSION });
+            return;
+        }
         console.log(chalk.yellow('No prompt or subcommand supplied. See `oracle --help` for usage.'));
         program.help({ error: false });
         return;
@@ -243,13 +284,35 @@ async function runRootCommand(options) {
     if (options.dryRun && options.renderMarkdown) {
         throw new Error('--dry-run cannot be combined with --render-markdown.');
     }
-    const engine = resolveEngine({ engine: options.engine, browserFlag: options.browser, env: process.env });
+    const preferredEngine = options.engine ?? userConfig.engine;
+    const engine = resolveEngine({ engine: preferredEngine, browserFlag: options.browser, env: process.env });
     if (options.browser) {
         console.log(chalk.yellow('`--browser` is deprecated; use `--engine browser` instead.'));
     }
+    if (program.getOptionValueSource?.('model') === 'default' && userConfig.model) {
+        options.model = userConfig.model;
+    }
+    if (program.getOptionValueSource?.('search') === 'default' && userConfig.search) {
+        options.search = userConfig.search === 'on';
+    }
+    if (program.getOptionValueSource?.('filesReport') === 'default' && userConfig.filesReport != null) {
+        options.filesReport = Boolean(userConfig.filesReport);
+    }
+    if (program.getOptionValueSource?.('heartbeat') === 'default' && typeof userConfig.heartbeatSeconds === 'number') {
+        options.heartbeat = userConfig.heartbeatSeconds;
+    }
     const cliModelArg = normalizeModelOption(options.model) || 'gpt-5-pro';
     const resolvedModel = engine === 'browser' ? inferModelFromLabel(cliModelArg) : resolveApiModel(cliModelArg);
     const resolvedOptions = { ...options, model: resolvedModel };
+    // Decide whether to block until completion:
+    // - explicit --wait / --no-wait wins
+    // - otherwise block for fast models (gpt-5.1, browser) and detach by default for gpt-5-pro API
+    const waitPreference = resolveWaitFlag({
+        waitFlag: options.wait,
+        noWaitFlag: options.noWait,
+        model: resolvedModel,
+        engine,
+    });
     if (await handleStatusFlag(options, { attachSession, showStatus })) {
         return;
     }
@@ -269,19 +332,34 @@ async function runRootCommand(options) {
         return;
     }
     if (previewMode) {
-        if (engine === 'browser') {
-            throw new Error('--engine browser cannot be combined with --preview.');
-        }
         if (!options.prompt) {
             throw new Error('Prompt is required when using --preview.');
         }
+        if (userConfig.promptSuffix) {
+            options.prompt = `${options.prompt.trim()}\n${userConfig.promptSuffix}`;
+        }
+        resolvedOptions.prompt = options.prompt;
         const runOptions = buildRunOptions(resolvedOptions, { preview: true, previewMode });
+        if (engine === 'browser') {
+            await runBrowserPreview({
+                runOptions,
+                cwd: process.cwd(),
+                version: VERSION,
+                previewMode,
+                log: console.log,
+            }, {});
+            return;
+        }
         await runOracle(runOptions, { log: console.log, write: (chunk) => process.stdout.write(chunk) });
         return;
     }
     if (!options.prompt) {
         throw new Error('Prompt is required when starting a new session.');
     }
+    if (userConfig.promptSuffix) {
+        options.prompt = `${options.prompt.trim()}\n${userConfig.promptSuffix}`;
+    }
+    resolvedOptions.prompt = options.prompt;
     if (options.dryRun) {
         const baseRunOptions = buildRunOptions(resolvedOptions, { preview: false, previewMode: undefined });
         await runDryRunSummary({
@@ -296,6 +374,13 @@ async function runRootCommand(options) {
     if (options.file && options.file.length > 0) {
         await readFiles(options.file, { cwd: process.cwd() });
     }
+    applyBrowserDefaultsFromConfig(options, userConfig);
+    const notifications = resolveNotificationSettings({
+        cliNotify: options.notify,
+        cliNotifySound: options.notifySound,
+        env: process.env,
+        config: userConfig.notify,
+    });
     const sessionMode = engine === 'browser' ? 'browser' : 'api';
     const browserModelLabelOverride = sessionMode === 'browser' ? resolveBrowserModelLabel(cliModelArg, resolvedModel) : undefined;
     const browserConfig = sessionMode === 'browser'
@@ -306,12 +391,21 @@ async function runRootCommand(options) {
         })
         : undefined;
     await ensureSessionStorage();
-    const baseRunOptions = buildRunOptions(resolvedOptions, { preview: false, previewMode: undefined });
+    const baseRunOptions = buildRunOptions(resolvedOptions, {
+        preview: false,
+        previewMode: undefined,
+        background: userConfig.background ?? resolvedOptions.background,
+    });
+    enforceBrowserSearchFlag(baseRunOptions, sessionMode, console.log);
+    if (sessionMode === 'browser' && baseRunOptions.search === false) {
+        console.log(chalk.dim('Note: search is not available in browser engine; ignoring search=false.'));
+        baseRunOptions.search = undefined;
+    }
     const sessionMeta = await initializeSession({
         ...baseRunOptions,
         mode: sessionMode,
         browserConfig,
-    }, process.cwd());
+    }, process.cwd(), notifications);
     const reattachCommand = `pnpm oracle session ${sessionMeta.id}`;
     console.log(chalk.bold(`Reattach later with: ${chalk.cyan(reattachCommand)}`));
     console.log('');
@@ -324,8 +418,18 @@ async function runRootCommand(options) {
             console.log(chalk.yellow(`Unable to detach session runner (${message}). Running inline...`));
             return false;
         });
+    if (!waitPreference) {
+        if (!detached) {
+            console.log(chalk.red('Unable to start in background; use --wait to run inline.'));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(chalk.blue(`Session running in background. Reattach via: oracle session ${sessionMeta.id}`));
+        console.log(chalk.dim('Pro runs can take up to 10 minutes. Add --wait to stay attached.'));
+        return;
+    }
     if (detached === false) {
-        await runInteractiveSession(sessionMeta, liveRunOptions, sessionMode, browserConfig, true);
+        await runInteractiveSession(sessionMeta, liveRunOptions, sessionMode, browserConfig, true, notifications, userConfig);
         console.log(chalk.bold(`Session ${sessionMeta.id} completed`));
         return;
     }
@@ -335,11 +439,11 @@ async function runRootCommand(options) {
         console.log(chalk.bold(`Session ${sessionMeta.id} completed`));
     }
 }
-async function runInteractiveSession(sessionMeta, runOptions, mode, browserConfig, showReattachHint = true) {
+async function runInteractiveSession(sessionMeta, runOptions, mode, browserConfig, showReattachHint = true, notifications, userConfig) {
     const { logLine, writeChunk, stream } = createSessionLogWriter(sessionMeta.id);
     let headerAugmented = false;
     const combinedLog = (message = '') => {
-        if (!headerAugmented && message.startsWith('Oracle (')) {
+        if (!headerAugmented && message.startsWith('oracle (')) {
             headerAugmented = true;
             if (showReattachHint) {
                 console.log(`${message}\n${chalk.blue(`Reattach via: oracle session ${sessionMeta.id}`)}`);
@@ -367,7 +471,14 @@ async function runInteractiveSession(sessionMeta, runOptions, mode, browserConfi
             log: combinedLog,
             write: combinedWrite,
             version: VERSION,
+            notifications: notifications ?? deriveNotificationSettingsFromMetadata(sessionMeta, process.env, userConfig?.notify),
         });
+        const latest = await readSessionMetadata(sessionMeta.id);
+        const summary = latest ? formatCompletionSummary(latest, { includeSlug: true }) : null;
+        if (summary) {
+            console.log('\n' + chalk.green.bold(summary));
+            logLine(summary); // plain text in log, colored on stdout
+        }
     }
     catch (error) {
         throw error;
@@ -407,6 +518,8 @@ async function executeSession(sessionId) {
     const sessionMode = getSessionMode(metadata);
     const browserConfig = getBrowserConfigFromMetadata(metadata);
     const { logLine, writeChunk, stream } = createSessionLogWriter(sessionId);
+    const userConfig = (await loadUserConfig()).config;
+    const notifications = deriveNotificationSettingsFromMetadata(metadata, process.env, userConfig.notify);
     try {
         await performSessionRun({
             sessionMeta: metadata,
@@ -417,6 +530,7 @@ async function executeSession(sessionId) {
             log: logLine,
             write: writeChunk,
             version: VERSION,
+            notifications,
         });
     }
     catch {
@@ -456,6 +570,43 @@ function printDebugOptionGroup(entries) {
         console.log(`  ${label}${description}`);
     });
 }
+function resolveWaitFlag({ waitFlag, noWaitFlag, model, engine, }) {
+    if (waitFlag === true)
+        return true;
+    if (noWaitFlag === true)
+        return false;
+    return defaultWaitPreference(model, engine);
+}
+function applyBrowserDefaultsFromConfig(options, config) {
+    const browser = config.browser;
+    if (!browser)
+        return;
+    const source = (key) => program.getOptionValueSource?.(key);
+    if (source('browserChromeProfile') === 'default' && browser.chromeProfile !== undefined) {
+        options.browserChromeProfile = browser.chromeProfile ?? undefined;
+    }
+    if (source('browserChromePath') === 'default' && browser.chromePath !== undefined) {
+        options.browserChromePath = browser.chromePath ?? undefined;
+    }
+    if (source('browserUrl') === 'default' && browser.url !== undefined) {
+        options.browserUrl = browser.url;
+    }
+    if (source('browserTimeout') === 'default' && typeof browser.timeoutMs === 'number') {
+        options.browserTimeout = String(browser.timeoutMs);
+    }
+    if (source('browserInputTimeout') === 'default' && typeof browser.inputTimeoutMs === 'number') {
+        options.browserInputTimeout = String(browser.inputTimeoutMs);
+    }
+    if (source('browserHeadless') === 'default' && browser.headless !== undefined) {
+        options.browserHeadless = browser.headless;
+    }
+    if (source('browserHideWindow') === 'default' && browser.hideWindow !== undefined) {
+        options.browserHideWindow = browser.hideWindow;
+    }
+    if (source('browserKeepBrowser') === 'default' && browser.keepBrowser !== undefined) {
+        options.browserKeepBrowser = browser.keepBrowser;
+    }
+}
 program.action(async function () {
     const options = this.optsWithGlobals();
     await runRootCommand(options);

package/dist/bin/oracle-mcp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { startMcpServer } from '../src/mcp/server.js';
+startMcpServer().catch((error) => {
+    console.error('oracle-mcp exited with an error:', error);
+    process.exitCode = 1;
+});