@steipete/oracle 0.8.3 → 0.8.5

package/dist/src/cli/bridge/host.js

@@ -0,0 +1,259 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import chalk from 'chalk';
+import { getOracleHomeDir } from '../../oracleHome.js';
+import { parseHostPort, normalizeHostPort, formatBridgeConnectionString } from '../../bridge/connection.js';
+import { serveRemote } from '../../remote/server.js';
+export async function runBridgeHost(options) {
+    const bindRaw = options.bind?.trim() || '127.0.0.1:9473';
+    const { hostname: bindHost, port: bindPort } = parseHostPort(bindRaw);
+    const tokenRaw = options.token?.trim() || 'auto';
+    const token = tokenRaw === 'auto' ? randomBytes(16).toString('hex') : tokenRaw;
+    if (!token.trim()) {
+        throw new Error('Token is required (use --token auto to generate one).');
+    }
+    const writeConnectionPath = options.writeConnection?.trim() || path.join(getOracleHomeDir(), 'bridge-connection.json');
+    const sshTarget = options.ssh?.trim();
+    const sshRemotePort = typeof options.sshRemotePort === 'number' ? options.sshRemotePort : bindPort;
+    if (sshRemotePort <= 0 || sshRemotePort > 65_535) {
+        throw new Error(`Invalid --ssh-remote-port: ${sshRemotePort}. Expected 1-65535.`);
+    }
+    const connectionHostForClient = sshTarget ? normalizeHostPort('127.0.0.1', sshRemotePort) : normalizeHostPort(bindHost === '0.0.0.0' || bindHost === '::' ? '127.0.0.1' : bindHost, bindPort);
+    const artifact = await upsertConnectionArtifact(writeConnectionPath, {
+        remoteHost: connectionHostForClient,
+        remoteToken: token,
+        tunnel: sshTarget
+            ? {
+                ssh: sshTarget,
+                remotePort: sshRemotePort,
+                localPort: bindPort,
+                identity: options.sshIdentity?.trim() || undefined,
+                extraArgs: options.sshExtraArgs?.trim() || undefined,
+            }
+            : undefined,
+    });
+    if (options.printToken) {
+        console.log(token);
+    }
+    if (options.print) {
+        console.log(formatBridgeConnectionString({ remoteHost: artifact.remoteHost, remoteToken: token }, { includeToken: true }));
+    }
+    if (options.background) {
+        await spawnBridgeHostInBackground({
+            bind: bindRaw,
+            token,
+            writeConnectionPath,
+            sshTarget,
+            sshRemotePort,
+            sshIdentity: options.sshIdentity?.trim(),
+            sshExtraArgs: options.sshExtraArgs?.trim(),
+        });
+        return;
+    }
+    console.log(chalk.cyanBright('Bridge host starting...'));
+    console.log(chalk.dim(`- Local bind: ${normalizeHostPort(bindHost, bindPort)}`));
+    console.log(chalk.dim(`- Connection artifact: ${writeConnectionPath}`));
+    console.log(chalk.dim(`- Client remoteHost: ${artifact.remoteHost}`));
+    console.log(chalk.dim('Token stored in connection artifact (not printed). Use --print or --print-token if needed.'));
+    let tunnel = null;
+    if (sshTarget) {
+        tunnel = startReverseTunnel({
+            sshTarget,
+            remotePort: sshRemotePort,
+            localPort: bindPort,
+            identity: options.sshIdentity?.trim() || undefined,
+            extraArgs: options.sshExtraArgs?.trim() || undefined,
+            log: (msg) => console.log(chalk.dim(msg)),
+        });
+        console.log(chalk.dim(`Reverse SSH tunnel active (remote 127.0.0.1:${sshRemotePort} -> local 127.0.0.1:${bindPort})`));
+    }
+    const filteredServeLogger = (message) => {
+        if (message.includes('Access token:')) {
+            return;
+        }
+        console.log(message);
+    };
+    try {
+        await serveRemote({
+            host: bindHost,
+            port: bindPort,
+            token,
+            logger: filteredServeLogger,
+        });
+    }
+    finally {
+        tunnel?.stop();
+    }
+}
+async function upsertConnectionArtifact(filePath, input) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    const now = new Date().toISOString();
+    const existing = await fs.readFile(filePath, 'utf8').catch(() => null);
+    let createdAt = now;
+    if (existing) {
+        try {
+            const parsed = JSON.parse(existing);
+            if (typeof parsed.createdAt === 'string' && parsed.createdAt.trim().length > 0) {
+                createdAt = parsed.createdAt;
+            }
+        }
+        catch {
+            // ignore invalid previous content
+        }
+    }
+    const artifact = {
+        remoteHost: input.remoteHost,
+        remoteToken: input.remoteToken,
+        createdAt,
+        updatedAt: now,
+        tunnel: input.tunnel,
+    };
+    const contents = `${JSON.stringify(artifact, null, 2)}\n`;
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    await fs.writeFile(tempPath, contents, { encoding: 'utf8', mode: 0o600 });
+    await fs.rename(tempPath, filePath);
+    if (process.platform !== 'win32') {
+        await fs.chmod(filePath, 0o600).catch(() => undefined);
+    }
+    return artifact;
+}
+function startReverseTunnel({ sshTarget, remotePort, localPort, identity, extraArgs, log, }) {
+    let stopped = false;
+    let child = null;
+    let attempt = 0;
+    let timer = null;
+    const spawnOnce = () => {
+        if (stopped)
+            return;
+        const args = [
+            '-N',
+            '-R',
+            `${remotePort}:127.0.0.1:${localPort}`,
+            '-o',
+            'ExitOnForwardFailure=yes',
+            '-o',
+            'ServerAliveInterval=30',
+            '-o',
+            'ServerAliveCountMax=3',
+        ];
+        if (identity) {
+            args.push('-i', identity);
+        }
+        if (extraArgs) {
+            args.push(...splitArgs(extraArgs));
+        }
+        args.push(sshTarget);
+        child = spawn('ssh', args, { stdio: 'ignore' });
+        const pid = child.pid;
+        log(`[bridge host] ssh tunnel started${pid ? ` (pid ${pid})` : ''}: ${sshTarget}`);
+        child.once('exit', (code, signal) => {
+            child = null;
+            if (stopped)
+                return;
+            const label = signal ? `signal ${signal}` : `code ${code ?? 0}`;
+            const delayMs = Math.min(30_000, 1_000 * 2 ** attempt);
+            attempt += 1;
+            log(`[bridge host] ssh tunnel exited (${label}); restarting in ${delayMs}ms`);
+            timer = setTimeout(spawnOnce, delayMs);
+            timer.unref?.();
+        });
+    };
+    spawnOnce();
+    return {
+        stop: () => {
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            if (child) {
+                child.removeAllListeners();
+                child.kill();
+                child = null;
+            }
+        },
+    };
+}
+function splitArgs(input) {
+    const args = [];
+    let current = '';
+    let quote = null;
+    const push = () => {
+        const trimmed = current.trim();
+        if (trimmed.length)
+            args.push(trimmed);
+        current = '';
+    };
+    for (let i = 0; i < input.length; i += 1) {
+        const ch = input[i] ?? '';
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            push();
+            continue;
+        }
+        current += ch;
+    }
+    push();
+    return args;
+}
+async function spawnBridgeHostInBackground({ bind, token, writeConnectionPath, sshTarget, sshRemotePort, sshIdentity, sshExtraArgs, }) {
+    const oracleHome = getOracleHomeDir();
+    await fs.mkdir(oracleHome, { recursive: true, mode: 0o700 });
+    const logPath = path.join(oracleHome, 'bridge-host.log');
+    const pidPath = path.join(oracleHome, 'bridge-host.pid');
+    const logHandle = await fs.open(logPath, 'a');
+    const stdio = ['ignore', logHandle.fd, logHandle.fd];
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        throw new Error('Unable to determine CLI entrypoint for background mode.');
+    }
+    const args = [
+        scriptPath,
+        'bridge',
+        'host',
+        '--foreground',
+        '--bind',
+        bind,
+        '--token',
+        token,
+        '--write-connection',
+        writeConnectionPath,
+    ];
+    if (sshTarget) {
+        args.push('--ssh', sshTarget);
+    }
+    if (typeof sshRemotePort === 'number') {
+        args.push('--ssh-remote-port', String(sshRemotePort));
+    }
+    if (sshIdentity) {
+        args.push('--ssh-identity', sshIdentity);
+    }
+    if (sshExtraArgs) {
+        args.push('--ssh-extra-args', sshExtraArgs);
+    }
+    const child = spawn(process.execPath, args, { detached: true, stdio });
+    child.unref();
+    await fs.writeFile(pidPath, `${child.pid ?? ''}\n`, { encoding: 'utf8', mode: 0o600 });
+    if (process.platform !== 'win32') {
+        await fs.chmod(pidPath, 0o600).catch(() => undefined);
+    }
+    await logHandle.close();
+    console.log(chalk.green(`Bridge host running in background (pid ${child.pid ?? '?'})`));
+    console.log(chalk.dim(`- Log: ${logPath}`));
+    console.log(chalk.dim(`- PID: ${pidPath}`));
+}

package/dist/src/cli/engine.js

@@ -12,7 +12,8 @@ export function defaultWaitPreference(model, engine) {
  * Precedence:
  * 1) Legacy --browser flag forces browser.
  * 2) Explicit --engine value.
- * 3) OPENAI_API_KEY decides: api when set, otherwise browser.
+ * 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) {
@@ -21,5 +22,20 @@ export function resolveEngine({ engine, browserFlag, env, }) {
     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/options.js

@@ -1,4 +1,5 @@
 import { InvalidArgumentError } from 'commander';
+import { parseDuration } from '../browserMode.js';
 import path from 'node:path';
 import fg from 'fast-glob';
 import { DEFAULT_MODEL, MODEL_CONFIGS } from '../oracle.js';
@@ -138,6 +139,19 @@ export function parseTimeoutOption(value) {
     }
     return parsed;
 }
+export function parseDurationOption(value, label) {
+    if (value == null)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new InvalidArgumentError(`${label} must be a duration like 30m, 10s, 500ms, or 2h.`);
+    }
+    const parsed = parseDuration(trimmed, Number.NaN);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new InvalidArgumentError(`${label} must be a positive duration like 30m, 10s, 500ms, or 2h.`);
+    }
+    return parsed;
+}
 export function resolveApiModel(modelValue) {
     const normalized = normalizeModelOption(modelValue).toLowerCase();
     if (normalized in MODEL_CONFIGS) {

package/dist/src/cli/runOptions.js

@@ -61,6 +61,10 @@ export function resolveRunOptionsFromConfig({ prompt, files = [], model, models,
 function resolveEngineWithConfig({ engine, configEngine, env, }) {
     if (engine)
         return engine;
+    const envOverride = (env.ORACLE_ENGINE ?? '').trim().toLowerCase();
+    if (envOverride === 'api' || envOverride === 'browser') {
+        return envOverride;
+    }
     if (configEngine)
         return configEngine;
     return resolveEngine({ engine: undefined, env });

package/dist/src/mcp/tools/consult.js

@@ -3,6 +3,8 @@ import { getCliVersion } from '../../version.js';
 import { LoggingMessageNotificationParamsSchema } from '@modelcontextprotocol/sdk/types.js';
 import { ensureBrowserAvailable, mapConsultToRunOptions } from '../utils.js';
 import { sessionStore } from '../../sessionStore.js';
+import { resolveRemoteServiceConfig } from '../../remote/remoteServiceConfig.js';
+import { createRemoteBrowserExecutor } from '../../remote/client.js';
 async function readSessionLogTail(sessionId, maxBytes) {
     try {
         const log = await sessionStore.readLog(sessionId);
@@ -23,14 +25,54 @@ import { resolveNotificationSettings } from '../../cli/notifier.js';
 import { mapModelToBrowserLabel, resolveBrowserModelLabel } from '../../cli/browserConfig.js';
 // Use raw shapes so the MCP SDK (with its bundled Zod) wraps them and emits valid JSON Schema.
 const consultInputShape = {
-    prompt: z.string().min(1, 'Prompt is required.'),
-    files: z.array(z.string()).default([]),
-    model: z.string().optional(),
-    models: z.array(z.string()).optional(),
-    engine: z.enum(['api', 'browser']).optional(),
-    browserModelLabel: z.string().optional(),
-    search: z.boolean().optional(),
-    slug: z.string().optional(),
+    prompt: z
+        .string()
+        .min(1, 'Prompt is required.')
+        .describe('User prompt to run.'),
+    files: z
+        .array(z.string())
+        .default([])
+        .describe('Optional file paths or glob patterns (like the CLI `--file`). Resolved relative to the MCP server working directory.'),
+    model: z
+        .string()
+        .optional()
+        .describe('Single model name/label. Prefer setting `engine` explicitly to avoid default surprises.'),
+    models: z
+        .array(z.string())
+        .optional()
+        .describe('Multi-model fan-out (API engine only). Cannot be combined with browser automation.'),
+    engine: z
+        .enum(['api', 'browser'])
+        .optional()
+        .describe('Execution engine. `api` uses OpenAI/other providers. `browser` automates the ChatGPT web UI (supports attachments and ChatGPT-only model labels).'),
+    browserModelLabel: z
+        .string()
+        .optional()
+        .describe('Browser-only: explicit ChatGPT UI label to select (overrides model mapping). Example: "GPT-5.2 Thinking".'),
+    browserAttachments: z
+        .enum(['auto', 'never', 'always'])
+        .optional()
+        .describe('Browser-only: how to deliver `files`. Use "always" for real ChatGPT file uploads (including images/PDFs). Use "never" to paste file contents inline. "auto" chooses based on prompt size.'),
+    browserBundleFiles: z
+        .boolean()
+        .optional()
+        .describe('Browser-only: bundle many files into a single upload (helps with upload limits).'),
+    browserThinkingTime: z
+        .enum(['light', 'standard', 'extended', 'heavy'])
+        .optional()
+        .describe('Browser-only: set ChatGPT thinking time when supported by the chosen model.'),
+    browserKeepBrowser: z
+        .boolean()
+        .optional()
+        .describe('Browser-only: keep Chrome running after completion (useful for debugging).'),
+    search: z
+        .boolean()
+        .optional()
+        .describe('API-only: enable/disable the provider search tool (browser engine ignores this).'),
+    slug: z
+        .string()
+        .optional()
+        .describe('Optional human-friendly session id (used for later `oracle sessions` lookups).'),
 };
 const consultModelSummaryShape = z.object({
     model: z.string(),
@@ -100,13 +142,13 @@ export function summarizeModelRunsForConsult(runs) {
 export function registerConsultTool(server) {
     server.registerTool('consult', {
         title: 'Run an oracle session',
-        description: 'Run a one-shot Oracle session (API or browser). Attach files/dirs for context, optional model/engine overrides, and an optional slug. Background handling follows the CLI defaults; browser runs only start when Chrome is available.',
+        description: 'Run a one-shot Oracle session (API or ChatGPT browser automation). Use `files` to attach project context. For browser-based image/file uploads, set `browserAttachments:"always"`. Sessions are stored under `ORACLE_HOME_DIR` (shared with the CLI).',
         // Cast to any to satisfy SDK typings across differing Zod versions.
         inputSchema: consultInputShape,
         outputSchema: consultOutputShape,
     }, async (input) => {
         const textContent = (text) => [{ type: 'text', text }];
-        const { prompt, files, model, models, engine, search, browserModelLabel, slug } = consultInputSchema.parse(input);
+        const { prompt, files, model, models, engine, search, browserModelLabel, browserAttachments, browserBundleFiles, browserThinkingTime, browserKeepBrowser, slug, } = consultInputSchema.parse(input);
         const { config: userConfig } = await loadUserConfig();
         const { runOptions, resolvedEngine } = mapConsultToRunOptions({
             prompt,
@@ -115,31 +157,53 @@ export function registerConsultTool(server) {
             models,
             engine,
             search,
+            browserAttachments,
+            browserBundleFiles,
             userConfig,
             env: process.env,
         });
         const cwd = process.cwd();
-        const browserGuard = ensureBrowserAvailable(resolvedEngine);
+        const resolvedRemote = resolveRemoteServiceConfig({ userConfig, env: process.env });
+        const browserGuard = ensureBrowserAvailable(resolvedEngine, { remoteHost: resolvedRemote.host });
         if (resolvedEngine === 'browser' && browserGuard) {
             return {
                 isError: true,
                 content: textContent(browserGuard),
             };
         }
+        let browserDeps;
+        if (resolvedEngine === 'browser' && resolvedRemote.host) {
+            if (!resolvedRemote.token) {
+                return {
+                    isError: true,
+                    content: textContent(`Remote host configured (${resolvedRemote.host}) but remote token is missing. Run \`oracle bridge client --connect <...>\` or set ORACLE_REMOTE_TOKEN.`),
+                };
+            }
+            browserDeps = {
+                executeBrowser: createRemoteBrowserExecutor({ host: resolvedRemote.host, token: resolvedRemote.token }),
+            };
+        }
         let browserConfig;
         if (resolvedEngine === 'browser') {
+            const envProfileDir = (process.env.ORACLE_BROWSER_PROFILE_DIR ?? '').trim();
+            const hasProfileDir = envProfileDir.length > 0;
             const preferredLabel = (browserModelLabel ?? model)?.trim();
             const isChatGptModel = runOptions.model.startsWith('gpt-') && !runOptions.model.includes('codex');
             const desiredModelLabel = isChatGptModel
                 ? mapModelToBrowserLabel(runOptions.model)
                 : resolveBrowserModelLabel(preferredLabel, runOptions.model);
-            // Keep the browser path minimal; only forward a desired model label for the ChatGPT picker.
+            const configuredUrl = userConfig.browser?.chatgptUrl ?? userConfig.browser?.url ?? undefined;
+            // Default to manual-login when a persistent profile dir is provided (common for Codex/Claude).
+            const manualLogin = hasProfileDir;
             browserConfig = {
-                url: CHATGPT_URL,
-                cookieSync: true,
+                url: configuredUrl ?? CHATGPT_URL,
+                cookieSync: !manualLogin,
                 headless: false,
                 hideWindow: false,
-                keepBrowser: false,
+                keepBrowser: browserKeepBrowser ?? false,
+                manualLogin,
+                manualLoginProfileDir: manualLogin ? envProfileDir : null,
+                thinkingTime: browserThinkingTime,
                 desiredModel: desiredModelLabel || mapModelToBrowserLabel(runOptions.model),
             };
         }
@@ -187,6 +251,7 @@ export function registerConsultTool(server) {
                 version: getCliVersion(),
                 notifications,
                 muteStdout: true,
+                browserDeps,
             });
         }
         catch (error) {

package/dist/src/mcp/tools/sessions.js

@@ -2,11 +2,20 @@ import { z } from 'zod';
 import { sessionStore } from '../../sessionStore.js';
 import { sessionsInputSchema } from '../types.js';
 const sessionsInputShape = {
-    id: z.string().optional(),
-    hours: z.number().optional(),
-    limit: z.number().optional(),
-    includeAll: z.boolean().optional(),
-    detail: z.boolean().optional(),
+    id: z
+        .string()
+        .optional()
+        .describe('Session id or slug. If set, returns a single session (use detail:true to include metadata/request).'),
+    hours: z.number().optional().describe('Look back this many hours when listing sessions (default: 24).'),
+    limit: z.number().optional().describe('Maximum sessions to return when listing (default: 100).'),
+    includeAll: z
+        .boolean()
+        .optional()
+        .describe('Include sessions outside the time window when listing (mirrors `oracle status --all`).'),
+    detail: z
+        .boolean()
+        .optional()
+        .describe('When id is set, include session metadata + stored request + full log text.'),
 };
 const sessionsOutputShape = {
     entries: z
@@ -31,7 +40,7 @@ const sessionsOutputShape = {
 export function registerSessionsTool(server) {
     server.registerTool('sessions', {
         title: 'List or fetch oracle sessions',
-        description: 'List stored sessions (same defaults as `oracle status`) or, with id/slug, return a summary row. Pass detail:true to include metadata, log, and stored request for that session.',
+        description: 'Inspect Oracle session history stored under `ORACLE_HOME_DIR` (shared with the CLI). List recent sessions or fetch one by id/slug (optionally including metadata + request + log).',
         inputSchema: sessionsInputShape,
         outputSchema: sessionsOutputShape,
     }, async (input) => {

package/dist/src/mcp/types.js

@@ -6,6 +6,10 @@ export const consultInputSchema = z.object({
     models: z.array(z.string()).optional(),
     engine: z.enum(['api', 'browser']).optional(),
     browserModelLabel: z.string().optional(),
+    browserAttachments: z.enum(['auto', 'never', 'always']).optional(),
+    browserBundleFiles: z.boolean().optional(),
+    browserThinkingTime: z.enum(['light', 'standard', 'extended', 'heavy']).optional(),
+    browserKeepBrowser: z.boolean().optional(),
     search: z.boolean().optional(),
     slug: z.string().optional(),
 });

package/dist/src/mcp/utils.js

@@ -1,6 +1,6 @@
 import { resolveRunOptionsFromConfig } from '../cli/runOptions.js';
 import { Launcher } from 'chrome-launcher';
-export function mapConsultToRunOptions({ prompt, files, model, models, engine, search, userConfig, env = process.env, }) {
+export function mapConsultToRunOptions({ prompt, files, model, models, engine, search, browserAttachments, browserBundleFiles, userConfig, env = process.env, }) {
     // Normalize CLI-style inputs through the shared resolver so config/env defaults apply,
     // then overlay MCP-only overrides such as explicit search toggles.
     const mergedModels = Array.isArray(models) && models.length > 0
@@ -10,12 +10,22 @@ export function mapConsultToRunOptions({ prompt, files, model, models, engine, s
     if (typeof search === 'boolean') {
         result.runOptions.search = search;
     }
+    if (browserAttachments) {
+        result.runOptions.browserAttachments = browserAttachments;
+    }
+    if (typeof browserBundleFiles === 'boolean') {
+        result.runOptions.browserBundleFiles = browserBundleFiles;
+    }
     return result;
 }
-export function ensureBrowserAvailable(engine) {
+export function ensureBrowserAvailable(engine, options) {
     if (engine !== 'browser') {
         return null;
     }
+    const remoteHost = options?.remoteHost?.trim() || process.env.ORACLE_REMOTE_HOST?.trim();
+    if (remoteHost) {
+        return null;
+    }
     if (process.env.CHROME_PATH) {
         return null;
     }

package/dist/src/oracle/background.js

@@ -3,7 +3,6 @@ import chalk from 'chalk';
 import { formatElapsed } from './format.js';
 import { startHeartbeat } from '../heartbeat.js';
 import { OracleResponseError, OracleTransportError, describeTransportError, toTransportError, } from './errors.js';
-const BACKGROUND_MAX_WAIT_MS = 30 * 60 * 1000;
 const BACKGROUND_POLL_INTERVAL_MS = 5000;
 const BACKGROUND_RETRY_BASE_MS = 3000;
 const BACKGROUND_RETRY_MAX_MS = 15000;
@@ -22,7 +21,7 @@ export async function executeBackgroundResponse(params) {
         throw new OracleResponseError('API did not return a response ID for the background run.', initialResponse);
     }
     const responseId = initialResponse.id;
-    log(chalk.dim(`API scheduled background response ${responseId} (status=${initialResponse.status ?? 'unknown'}). Monitoring up to ${Math.round(BACKGROUND_MAX_WAIT_MS / 60000)} minutes for completion...`));
+    log(chalk.dim(`API scheduled background response ${responseId} (status=${initialResponse.status ?? 'unknown'}). Monitoring up to ${Math.round(maxWaitMs / 60000)} minutes for completion...`));
     let heartbeatActive = false;
     let stopHeartbeat = null;
     const stopHeartbeatNow = () => {

package/dist/src/oracle/client.js

@@ -19,19 +19,22 @@ export function createDefaultClientFactory() {
         let instance;
         const openRouter = isOpenRouterBaseUrl(options?.baseUrl);
         const defaultHeaders = openRouter ? buildOpenRouterHeaders() : undefined;
+        const httpTimeoutMs = typeof options?.httpTimeoutMs === 'number' && Number.isFinite(options.httpTimeoutMs) && options.httpTimeoutMs > 0
+            ? options.httpTimeoutMs
+            : 20 * 60 * 1000;
         if (options?.azure?.endpoint) {
             instance = new AzureOpenAI({
                 apiKey: key,
                 endpoint: options.azure.endpoint,
                 apiVersion: options.azure.apiVersion,
                 deployment: options.azure.deployment,
-                timeout: 20 * 60 * 1000,
+                timeout: httpTimeoutMs,
             });
         }
         else {
             instance = new OpenAI({
                 apiKey: key,
-                timeout: 20 * 60 * 1000,
+                timeout: httpTimeoutMs,
                 baseURL: options?.baseUrl,
                 defaultHeaders,
             });

package/dist/src/oracle/files.js

@@ -5,7 +5,7 @@ import { FileValidationError } from './errors.js';
 const MAX_FILE_SIZE_BYTES = 1 * 1024 * 1024; // 1 MB
 const DEFAULT_FS = fs;
 const DEFAULT_IGNORED_DIRS = ['node_modules', 'dist', 'coverage', '.git', '.turbo', '.next', 'build', 'tmp'];
-export async function readFiles(filePaths, { cwd = process.cwd(), fsModule = DEFAULT_FS, maxFileSizeBytes = MAX_FILE_SIZE_BYTES } = {}) {
+export async function readFiles(filePaths, { cwd = process.cwd(), fsModule = DEFAULT_FS, maxFileSizeBytes = MAX_FILE_SIZE_BYTES, readContents = true, } = {}) {
     if (!filePaths || filePaths.length === 0) {
         return [];
     }
@@ -83,7 +83,7 @@ export async function readFiles(filePaths, { cwd = process.cwd(), fsModule = DEF
     }
     const files = [];
     for (const filePath of accepted) {
-        const content = await fsModule.readFile(filePath, 'utf8');
+        const content = readContents ? await fsModule.readFile(filePath, 'utf8') : '';
         files.push({ path: filePath, content });
     }
     return files;

package/dist/src/oracle/run.js

@@ -297,6 +297,7 @@ export async function runOracle(options, deps = {}) {
                 : modelConfig.model.startsWith('gemini')
                     ? resolveGeminiModelId(effectiveModelId)
                     : effectiveModelId,
+            httpTimeoutMs: options.httpTimeoutMs,
         });
     logVerbose('Dispatching request to API...');
     if (options.verbose) {

package/dist/src/remote/client.js

@@ -1,6 +1,7 @@
 import http from 'node:http';
 import path from 'node:path';
 import { readFile } from 'node:fs/promises';
+import { parseHostPort } from '../bridge/connection.js';
 export function createRemoteBrowserExecutor({ host, token }) {
     // Return a drop-in replacement for runBrowserMode so the browser session runner can stay unchanged.
     return async function remoteBrowserExecutor(options) {
@@ -79,12 +80,12 @@ async function serializeAttachments(attachments) {
     return serialized;
 }
 function parseHost(input) {
-    const [hostname, portStr] = input.split(':');
-    const port = Number.parseInt(portStr ?? '', 10);
-    if (!hostname || Number.isNaN(port)) {
-        throw new Error(`Invalid remote host: ${input}`);
+    try {
+        return parseHostPort(input);
+    }
+    catch (error) {
+        throw new Error(`Invalid remote host: ${input} (${error instanceof Error ? error.message : String(error)})`);
     }
-    return { hostname, port };
 }
 function handleEvent(line, options, onResult, onError) {
     let event;