@steipete/oracle 0.11.1 → 0.12.1

package/dist/src/browser/sessionRunner.js

@@ -5,6 +5,61 @@ import { runBrowserMode } from "../browserMode.js";
 import { assembleBrowserPrompt } from "./prompt.js";
 import { BrowserAutomationError } from "../oracle/errors.js";
 import { appendArtifacts, saveBrowserTranscriptArtifact, saveDeepResearchReportArtifact, } from "./artifacts.js";
+const LARGE_PRO_FAST_INPUT_TOKEN_THRESHOLD = 25_000;
+const LARGE_PRO_FAST_ELAPSED_MS_THRESHOLD = 120_000;
+function buildUnavailableModelSelectionEvidence(browserConfig) {
+    if (!browserConfig.desiredModel) {
+        return undefined;
+    }
+    return {
+        requestedModel: browserConfig.desiredModel,
+        resolvedLabel: null,
+        strategy: browserConfig.modelStrategy,
+        status: "unavailable",
+        verified: false,
+        source: "config",
+        capturedAt: new Date().toISOString(),
+    };
+}
+function formatModelSelectionEvidence(evidence) {
+    const requested = evidence.requestedModel ?? "(none)";
+    const resolved = evidence.resolvedLabel ?? "(unavailable)";
+    const strategy = evidence.strategy ?? "(default)";
+    const verified = evidence.verified ? "yes" : "no";
+    return `[browser] Model selection evidence: requested=${requested}; resolved=${resolved}; status=${evidence.status}; strategy=${strategy}; verified=${verified}.`;
+}
+function isRequestedProBrowserRun(runOptions, browserConfig, evidence) {
+    const candidates = [
+        runOptions.model,
+        browserConfig.desiredModel,
+        evidence?.requestedModel,
+        evidence?.resolvedLabel,
+    ];
+    return candidates.some((value) => typeof value === "string" && /\bpro\b/i.test(value));
+}
+export function buildBrowserRunWarningsForTest(args) {
+    return buildBrowserRunWarnings(args);
+}
+function buildBrowserRunWarnings(args) {
+    if (!isRequestedProBrowserRun(args.runOptions, args.browserConfig, args.modelSelection) ||
+        args.inputTokens < LARGE_PRO_FAST_INPUT_TOKEN_THRESHOLD ||
+        args.elapsedMs >= LARGE_PRO_FAST_ELAPSED_MS_THRESHOLD) {
+        return [];
+    }
+    return [
+        {
+            code: "browser-pro-fast-large-run",
+            severity: "warning",
+            message: `Large browser Pro run completed quickly (${(args.elapsedMs / 1000).toFixed(0)}s for ~${args.inputTokens.toLocaleString()} input tokens); verify the stored model selection evidence before claiming Pro Extended output.`,
+            details: {
+                inputTokens: args.inputTokens,
+                elapsedMs: args.elapsedMs,
+                requestedModel: args.modelSelection?.requestedModel ?? args.browserConfig.desiredModel,
+                resolvedLabel: args.modelSelection?.resolvedLabel ?? null,
+            },
+        },
+    ];
+}
 export async function runBrowserSessionExecution({ runOptions, browserConfig, cwd, log }, deps = {}) {
     const assemblePrompt = deps.assemblePrompt ?? assembleBrowserPrompt;
     const executeBrowser = deps.executeBrowser ?? runBrowserMode;
@@ -37,7 +92,7 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
         if (typeof message !== "string")
             return;
         const shouldAlwaysPrint = message.startsWith("[browser] ") &&
-            /archive|fallback|follow-up|retry|thinking|waiting for chatgpt|browser slot|browser control|browser guidance/i.test(message);
+            /archive|fallback|follow-up|retry|thinking|waiting for chatgpt|browser slot|browser control|browser guidance|model selection|model picker/i.test(message);
         if (!runOptions.verbose && !shouldAlwaysPrint)
             return;
         log(message);
@@ -84,6 +139,20 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
         const message = error instanceof Error ? error.message : "Browser automation failed.";
         throw new BrowserAutomationError(message, { stage: "execute-browser" }, error);
     }
+    const modelSelection = browserResult.modelSelection ?? buildUnavailableModelSelectionEvidence(browserConfig);
+    if (modelSelection) {
+        log(formatModelSelectionEvidence(modelSelection));
+    }
+    const warnings = buildBrowserRunWarnings({
+        runOptions,
+        browserConfig,
+        inputTokens: promptArtifacts.estimatedInputTokens,
+        elapsedMs: browserResult.tookMs,
+        modelSelection,
+    });
+    for (const warning of warnings) {
+        log(chalk.yellow(`[browser] ${warning.message}`));
+    }
     if (!runOptions.silent) {
         log(chalk.bold("Answer:"));
         log(browserResult.answerMarkdown || browserResult.answerText || chalk.dim("(no text output)"));
@@ -145,9 +214,12 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
             chromeTargetId: browserResult.chromeTargetId,
             tabUrl: browserResult.tabUrl,
             conversationId: browserResult.conversationId,
+            promptSubmitted: browserResult.promptSubmitted,
             controllerPid: browserResult.controllerPid ?? process.pid,
         },
         archive: browserResult.archive,
+        modelSelection,
+        warnings,
         answerText,
         artifacts: savedArtifacts,
     };

package/dist/src/browser/utils.js

@@ -1,50 +1,4 @@
-export function parseDuration(input, fallback) {
-    if (!input) {
-        return fallback;
-    }
-    const trimmed = input.trim();
-    if (!trimmed) {
-        return fallback;
-    }
-    const lowercase = trimmed.toLowerCase();
-    if (/^[0-9]+$/.test(lowercase)) {
-        return Number(lowercase);
-    }
-    const normalized = lowercase.replace(/\s+/g, "");
-    const singleMatch = /^([0-9]+)(ms|s|m|h)$/i.exec(normalized);
-    if (singleMatch && singleMatch[0].length === normalized.length) {
-        const value = Number(singleMatch[1]);
-        return convertUnit(value, singleMatch[2]);
-    }
-    const multiDuration = /([0-9]+)(ms|h|m|s)/g;
-    let total = 0;
-    let lastIndex = 0;
-    let match = multiDuration.exec(normalized);
-    while (match !== null) {
-        total += convertUnit(Number(match[1]), match[2]);
-        lastIndex = multiDuration.lastIndex;
-        match = multiDuration.exec(normalized);
-    }
-    if (total > 0 && lastIndex === normalized.length) {
-        return total;
-    }
-    return fallback;
-}
-function convertUnit(value, unitRaw) {
-    const unit = unitRaw?.toLowerCase();
-    switch (unit) {
-        case "ms":
-            return value;
-        case "s":
-            return value * 1000;
-        case "m":
-            return value * 60_000;
-        case "h":
-            return value * 3_600_000;
-        default:
-            return value;
-    }
-}
+export { parseDuration } from "../duration.js";
 export function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/src/browser/zipBundle.js

@@ -0,0 +1,152 @@
+const ZIP_UTF8_FLAG = 0x0800;
+const ZIP_STORE_METHOD = 0;
+const ZIP_VERSION_NEEDED = 20;
+const ZIP_DOS_TIME = 0x0000;
+const ZIP_DOS_DATE = 0x0021;
+const CRC32_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < table.length; i += 1) {
+        let value = i;
+        for (let bit = 0; bit < 8; bit += 1) {
+            value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+        }
+        table[i] = value >>> 0;
+    }
+    return table;
+})();
+function crc32(buffer) {
+    let crc = 0xffffffff;
+    for (const byte of buffer) {
+        crc = CRC32_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function normalizeZipPath(inputPath, fallback) {
+    const normalized = inputPath
+        .replace(/\\/g, "/")
+        .replace(/^[a-zA-Z]:\//, "")
+        .replace(/^\/+/, "")
+        .split("/")
+        .filter((segment) => segment && segment !== "." && segment !== "..")
+        .join("/");
+    return normalized || fallback;
+}
+function uniqueZipPath(inputPath, index, seen) {
+    const normalized = normalizeZipPath(inputPath, `file-${index + 1}.txt`);
+    const extIndex = normalized.lastIndexOf(".");
+    const base = extIndex > 0 ? normalized.slice(0, extIndex) : normalized;
+    const ext = extIndex > 0 ? normalized.slice(extIndex) : "";
+    let candidate = normalized;
+    let suffix = 2;
+    while (seen.has(candidate)) {
+        candidate = `${base}-${suffix}${ext}`;
+        suffix += 1;
+    }
+    seen.add(candidate);
+    return candidate;
+}
+function assertZip32(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 0xffffffff) {
+        throw new Error(`${label} exceeds ZIP32 limits.`);
+    }
+}
+function assertZip16(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 0xffff) {
+        throw new Error(`${label} exceeds ZIP16 limits.`);
+    }
+}
+function localFileHeader(entry) {
+    const header = Buffer.alloc(30);
+    header.writeUInt32LE(0x04034b50, 0);
+    header.writeUInt16LE(ZIP_VERSION_NEEDED, 4);
+    header.writeUInt16LE(ZIP_UTF8_FLAG, 6);
+    header.writeUInt16LE(ZIP_STORE_METHOD, 8);
+    header.writeUInt16LE(ZIP_DOS_TIME, 10);
+    header.writeUInt16LE(ZIP_DOS_DATE, 12);
+    header.writeUInt32LE(entry.crc32, 14);
+    header.writeUInt32LE(entry.content.length, 18);
+    header.writeUInt32LE(entry.content.length, 22);
+    header.writeUInt16LE(entry.name.length, 26);
+    header.writeUInt16LE(0, 28);
+    return header;
+}
+function centralDirectoryHeader(entry) {
+    const header = Buffer.alloc(46);
+    header.writeUInt32LE(0x02014b50, 0);
+    header.writeUInt16LE(ZIP_VERSION_NEEDED, 4);
+    header.writeUInt16LE(ZIP_VERSION_NEEDED, 6);
+    header.writeUInt16LE(ZIP_UTF8_FLAG, 8);
+    header.writeUInt16LE(ZIP_STORE_METHOD, 10);
+    header.writeUInt16LE(ZIP_DOS_TIME, 12);
+    header.writeUInt16LE(ZIP_DOS_DATE, 14);
+    header.writeUInt32LE(entry.crc32, 16);
+    header.writeUInt32LE(entry.content.length, 20);
+    header.writeUInt32LE(entry.content.length, 24);
+    header.writeUInt16LE(entry.name.length, 28);
+    header.writeUInt16LE(0, 30);
+    header.writeUInt16LE(0, 32);
+    header.writeUInt16LE(0, 34);
+    header.writeUInt16LE(0, 36);
+    header.writeUInt32LE(0, 38);
+    header.writeUInt32LE(entry.localHeaderOffset, 42);
+    return header;
+}
+function endOfCentralDirectory(entryCount, centralSize, centralOffset) {
+    const footer = Buffer.alloc(22);
+    footer.writeUInt32LE(0x06054b50, 0);
+    footer.writeUInt16LE(0, 4);
+    footer.writeUInt16LE(0, 6);
+    footer.writeUInt16LE(entryCount, 8);
+    footer.writeUInt16LE(entryCount, 10);
+    footer.writeUInt32LE(centralSize, 12);
+    footer.writeUInt32LE(centralOffset, 16);
+    footer.writeUInt16LE(0, 20);
+    return footer;
+}
+export function createStoredZip(entries) {
+    if (entries.length > 0xffff) {
+        throw new Error("Too many files for a ZIP32 browser bundle.");
+    }
+    assertZip16(entries.length, "ZIP entry count");
+    const seen = new Set();
+    const prepared = [];
+    const localParts = [];
+    let offset = 0;
+    entries.forEach((entry, index) => {
+        const name = Buffer.from(uniqueZipPath(entry.path, index, seen), "utf8");
+        const content = Buffer.isBuffer(entry.content)
+            ? entry.content
+            : Buffer.from(entry.content, "utf8");
+        assertZip16(name.length, "ZIP file name");
+        assertZip32(content.length, "ZIP entry size");
+        assertZip32(offset, "ZIP local header offset");
+        const preparedEntry = {
+            name,
+            content,
+            crc32: crc32(content),
+            localHeaderOffset: offset,
+        };
+        prepared.push(preparedEntry);
+        const header = localFileHeader(preparedEntry);
+        localParts.push(header, name, content);
+        offset += header.length + name.length + content.length;
+        assertZip32(offset, "ZIP local data size");
+    });
+    const centralOffset = offset;
+    const centralParts = [];
+    for (const entry of prepared) {
+        const header = centralDirectoryHeader(entry);
+        centralParts.push(header, entry.name);
+        offset += header.length + entry.name.length;
+        assertZip32(offset, "ZIP central directory size");
+    }
+    const centralSize = offset - centralOffset;
+    assertZip32(centralOffset, "ZIP central directory offset");
+    assertZip32(centralSize, "ZIP central directory size");
+    const footer = endOfCentralDirectory(prepared.length, centralSize, centralOffset);
+    return Buffer.concat([...localParts, ...centralParts, footer]);
+}
+export const __test__ = {
+    crc32,
+    normalizeZipPath,
+};

package/dist/src/cli/browserConfig.js

@@ -1,6 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { CHATGPT_URL, DEFAULT_MODEL_STRATEGY, DEFAULT_MODEL_TARGET, normalizeChatgptUrl, parseDuration, } from "../browserMode.js";
+import { CHATGPT_URL, DEFAULT_MODEL_STRATEGY, DEFAULT_MODEL_TARGET } from "../browser/constants.js";
+import { normalizeChatgptUrl } from "../browser/utils.js";
+import { parseDuration } from "../duration.js";
 import { normalizeBrowserModelStrategy } from "../browser/modelStrategy.js";
 import { getOracleHomeDir } from "../oracleHome.js";
 const DEFAULT_BROWSER_TIMEOUT_MS = 1_200_000;
@@ -12,14 +14,14 @@ const DEFAULT_CHROME_PROFILE = "Default";
 // 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.5-pro", "GPT-5.5 Pro"],
+    ["gpt-5.5-pro", "Pro"],
     ["gpt-5.5", "Thinking 5.5"],
-    ["gpt-5.4-pro", "GPT-5.4 Pro"],
+    ["gpt-5.4-pro", "Pro"],
     ["gpt-5.2-thinking", "GPT-5.2 Thinking"],
     ["gpt-5.2-instant", "GPT-5.2 Instant"],
-    ["gpt-5.2-pro", "GPT-5.5 Pro"],
-    ["gpt-5.1-pro", "GPT-5.5 Pro"],
-    ["gpt-5-pro", "GPT-5.5 Pro"],
+    ["gpt-5.2-pro", "Pro"],
+    ["gpt-5.1-pro", "Pro"],
+    ["gpt-5-pro", "Pro"],
     // Base models last (least specific)
     ["gpt-5.4", "Thinking 5.4"],
     ["gpt-5.2", "GPT-5.2"], // Selects "Auto" in ChatGPT UI
@@ -32,14 +34,14 @@ export function normalizeChatGptModelForBrowser(model) {
     if (!normalized.startsWith("gpt-") || normalized.includes("codex")) {
         return model;
     }
-    if (normalized === "gpt-5.5-pro" ||
-        normalized === "gpt-5.5" ||
-        normalized === "gpt-5.4-pro" ||
-        normalized === "gpt-5.4") {
+    if (normalized === "gpt-5.5-pro" || normalized === "gpt-5.5" || normalized === "gpt-5.4") {
         return normalized;
     }
     // Pro variants: resolve to the latest Pro model in ChatGPT.
-    if (normalized === "gpt-5-pro" || normalized === "gpt-5.1-pro" || normalized === "gpt-5.2-pro") {
+    if (normalized === "gpt-5-pro" ||
+        normalized === "gpt-5.1-pro" ||
+        normalized === "gpt-5.2-pro" ||
+        normalized === "gpt-5.4-pro") {
         return "gpt-5.5-pro";
     }
     // Explicit model variants: keep as-is (they have their own browser labels)

package/dist/src/cli/browserDefaults.js

@@ -1,4 +1,5 @@
-import { normalizeChatgptUrl, CHATGPT_URL } from "../browserMode.js";
+import { CHATGPT_URL } from "../browser/constants.js";
+import { normalizeChatgptUrl } from "../browser/utils.js";
 export function applyBrowserDefaultsFromConfig(options, config, getSource) {
     const browser = config.browser;
     if (!browser)

package/dist/src/cli/docsCheck.js

@@ -0,0 +1,186 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_DOC_PATHS = [
+    "README.md",
+    "docs/index.md",
+    "docs/agents.md",
+    "docs/sessions.md",
+    "docs/spec.md",
+    "docs/cli-reference.md",
+];
+const FLAG_RE = /(^|[\s`([{|,])(--[a-z][a-z0-9-]*)(?=$|[\s`)[\].,;:|=<>}])/g;
+const SLASH_FLAG_RE = /--[a-z][a-z0-9-]*(?:\/(?:--[a-z][a-z0-9-]*|-[a-z][a-z0-9-]*))+/g;
+const ROOT_ONLY_SECTIONS = new Set(["Core consult flags"]);
+export async function checkDocsFlags({ command, cwd = process.cwd(), paths, }) {
+    const availableFlags = collectCommanderFlags(command);
+    const rootFlags = collectCommanderFlags(command, { recursive: false });
+    const commandFlags = collectCommandFlags(command);
+    const docPaths = await resolveDocPaths(cwd, paths);
+    const issues = [];
+    const checkedFlags = new Set();
+    for (const docPath of docPaths) {
+        const body = await fs.readFile(path.resolve(cwd, docPath), "utf8");
+        for (const reference of extractMarkdownFlagReferences(body)) {
+            const { command: commandPath, flag, section } = reference;
+            checkedFlags.add(flag);
+            const scopedFlags = commandPath
+                ? (commandFlags.get(commandPath) ?? availableFlags)
+                : section && ROOT_ONLY_SECTIONS.has(section)
+                    ? rootFlags
+                    : availableFlags;
+            if (!scopedFlags.has(flag)) {
+                issues.push({ file: docPath, flag, section, command: commandPath });
+            }
+        }
+    }
+    return {
+        checkedFiles: docPaths,
+        checkedFlags: [...checkedFlags].sort(),
+        issues: issues.sort((a, b) => a.file.localeCompare(b.file) || a.flag.localeCompare(b.flag)),
+    };
+}
+export function printDocsCheckResult(result, log = console.log) {
+    if (result.issues.length === 0) {
+        log(`Docs/help check: ok (${result.checkedFlags.length} flags, ${result.checkedFiles.length} files)`);
+        return;
+    }
+    log("Docs/help drift:");
+    for (const issue of result.issues) {
+        const scopes = [issue.section, issue.command].filter(Boolean);
+        const scope = scopes.length > 0 ? ` (${scopes.join(", ")})` : "";
+        log(`- ${issue.file}${scope} mentions ${issue.flag}, but CLI help does not expose ${issue.flag}`);
+    }
+}
+export function collectCommanderFlags(command, options) {
+    const flags = new Set(["--help", "--version"]);
+    for (const option of command.options) {
+        for (const flag of extractOptionFlags(option.flags)) {
+            flags.add(flag);
+        }
+    }
+    if (options?.recursive === false) {
+        return flags;
+    }
+    for (const subcommand of command.commands) {
+        for (const flag of collectCommanderFlags(subcommand)) {
+            flags.add(flag);
+        }
+    }
+    return flags;
+}
+function collectCommandFlags(command, pathParts = ["oracle"]) {
+    const flags = new Map();
+    flags.set(pathParts.join(" "), collectCommanderFlags(command, { recursive: false }));
+    for (const subcommand of command.commands) {
+        for (const [path, subcommandFlags] of collectCommandFlags(subcommand, [
+            ...pathParts,
+            subcommand.name(),
+        ])) {
+            flags.set(path, subcommandFlags);
+        }
+    }
+    return flags;
+}
+export function extractMarkdownFlags(markdown) {
+    return [
+        ...new Set(extractMarkdownFlagReferences(markdown).map((reference) => reference.flag)),
+    ].sort();
+}
+function extractMarkdownFlagReferences(markdown) {
+    const references = [];
+    let section;
+    for (const line of markdown.split(/\r?\n/)) {
+        const heading = line.match(/^##+\s+(.+?)\s*$/);
+        if (heading) {
+            section = heading[1];
+        }
+        const commandPath = extractOracleCommandPath(line);
+        const lineFlags = new Set();
+        for (const match of line.matchAll(FLAG_RE)) {
+            const flag = match[2];
+            if (!flag || flag.endsWith("-")) {
+                continue;
+            }
+            lineFlags.add(flag);
+        }
+        for (const flag of expandSlashFlagReferences(line)) {
+            lineFlags.add(flag);
+        }
+        for (const flag of lineFlags) {
+            references.push({ flag, section, command: commandPath });
+        }
+    }
+    return references.sort((a, b) => a.flag.localeCompare(b.flag) || (a.section ?? "").localeCompare(b.section ?? ""));
+}
+function extractOracleCommandPath(line) {
+    const trimmed = line.trim().replace(/^[$>]\s+/, "");
+    if (!trimmed.startsWith("oracle ") && !trimmed.startsWith("npx ")) {
+        return undefined;
+    }
+    const tokens = trimmed.split(/\s+/);
+    let oracleIndex = tokens[0] === "oracle" ? 0 : -1;
+    if (oracleIndex === -1) {
+        oracleIndex = tokens.findIndex((token) => token === "@steipete/oracle");
+    }
+    if (oracleIndex === -1) {
+        return undefined;
+    }
+    const pathParts = ["oracle"];
+    for (const token of tokens.slice(oracleIndex + 1)) {
+        if (token.startsWith("-") || !/^[a-z][a-z0-9-]*$/.test(token)) {
+            break;
+        }
+        pathParts.push(token);
+    }
+    return pathParts.join(" ");
+}
+function extractOptionFlags(flagsText) {
+    const flags = new Set();
+    for (const match of flagsText.matchAll(/--\[no-\]([a-z][a-z0-9-]*)/g)) {
+        flags.add(`--${match[1]}`);
+        flags.add(`--no-${match[1]}`);
+    }
+    for (const match of flagsText.matchAll(/--[a-z][a-z0-9-]*/g)) {
+        flags.add(match[0]);
+    }
+    return [...flags];
+}
+function expandSlashFlagReferences(line) {
+    const flags = [];
+    for (const match of line.matchAll(SLASH_FLAG_RE)) {
+        const parts = match[0].split("/");
+        const base = parts[0];
+        const basePrefix = base.slice(0, base.lastIndexOf("-") + 1);
+        flags.push(base);
+        for (const part of parts.slice(1)) {
+            if (part.startsWith("--")) {
+                flags.push(part);
+            }
+            else if (part.startsWith("-") && basePrefix) {
+                flags.push(`${basePrefix}${part.slice(1)}`);
+            }
+        }
+    }
+    return flags;
+}
+async function resolveDocPaths(cwd, paths) {
+    const candidates = paths && paths.length > 0 ? paths : DEFAULT_DOC_PATHS;
+    const existing = [];
+    for (const candidate of candidates) {
+        try {
+            const stat = await fs.stat(path.resolve(cwd, candidate));
+            if (stat.isFile()) {
+                existing.push(candidate);
+            }
+        }
+        catch {
+            if (paths && paths.length > 0) {
+                throw new Error(`Docs check path not found: ${candidate}`);
+            }
+        }
+    }
+    if (existing.length === 0) {
+        throw new Error("No docs found to check. Run from the repo root or pass --docs-path <file>.");
+    }
+    return existing;
+}

package/dist/src/cli/engine.js

@@ -12,21 +12,28 @@ export function defaultWaitPreference(model, engine) {
  * 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.
+ * 3) Explicit API provider routing flags force API.
+ * 4) ORACLE_ENGINE environment override (api|browser).
+ * 5) API environment decides: api when set, otherwise browser.
  */
-export function resolveEngine({ engine, browserFlag, env, }) {
+export function resolveEngine({ engine, browserFlag, apiProviderRequested, env, }) {
     if (browserFlag) {
         return "browser";
     }
     if (engine) {
         return engine;
     }
+    if (apiProviderRequested) {
+        return "api";
+    }
     const envEngine = normalizeEngineMode(env.ORACLE_ENGINE);
     if (envEngine) {
         return envEngine;
     }
-    return env.OPENAI_API_KEY ? "api" : "browser";
+    return hasApiEnvironment(env) ? "api" : "browser";
+}
+function hasApiEnvironment(env) {
+    return Boolean(env.OPENAI_API_KEY || env.OPENROUTER_API_KEY);
 }
 function normalizeEngineMode(raw) {
     if (typeof raw !== "string") {

package/dist/src/cli/options.js

@@ -1,8 +1,8 @@
 import { InvalidArgumentError } from "commander";
-import { parseDuration } from "../browserMode.js";
+import { parseDuration } from "../duration.js";
 import path from "node:path";
 import fg from "fast-glob";
-import { DEFAULT_MODEL, MODEL_CONFIGS } from "../oracle.js";
+import { DEFAULT_MODEL, MODEL_CONFIGS } from "../oracle/config.js";
 export function collectPaths(value, previous = []) {
     if (!value) {
         return previous;
@@ -140,11 +140,17 @@ export function parseTimeoutOption(value) {
     const normalized = value.trim().toLowerCase();
     if (normalized === "auto")
         return "auto";
-    const parsed = Number.parseFloat(normalized);
-    if (Number.isNaN(parsed) || parsed <= 0) {
-        throw new InvalidArgumentError('Timeout must be a positive number of seconds or "auto".');
+    if (/^[0-9]+(?:\.[0-9]+)?$/.test(normalized)) {
+        const parsed = Number.parseFloat(normalized);
+        if (parsed > 0) {
+            return parsed;
+        }
     }
-    return parsed;
+    const parsedMs = parseDuration(normalized, Number.NaN);
+    if (!Number.isFinite(parsedMs) || parsedMs <= 0) {
+        throw new InvalidArgumentError('Timeout must be a positive number of seconds, a duration like "10m", or "auto".');
+    }
+    return parsedMs / 1000;
 }
 export function parseDurationOption(value, label) {
     if (value == null)