@steipete/oracle 0.13.0 → 0.14.0

package/README.md

@@ -11,7 +11,7 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"></a>
 </p>
 
-Oracle bundles your prompt and files so another AI can answer with real context. It speaks GPT-5.5 Pro (default), GPT-5.5, GPT-5.4 Pro, GPT-5.4, GPT-5.1 Pro, GPT-5.1 Codex (API-only), GPT-5.1, GPT-5.2, Gemini 3.1 Pro (API-only), Gemini 3 Pro, Claude Sonnet 4.6, Claude Opus 4.1, and more—and it can ask one or multiple models in a single run. Browser automation is available; use `--browser-model-strategy current` to keep the active ChatGPT model (or `ignore` to skip the picker). API remains the most reliable path, and `--copy` is an easy manual fallback.
+Oracle bundles your prompt and files so another AI can answer with real context. It speaks GPT-5.5 Pro (default), GPT-5.5, GPT-5.4 Pro, GPT-5.4, GPT-5.1 Pro, GPT-5.1 Codex (API-only), GPT-5.1, GPT-5.2, Gemini 3.1 Pro, Gemini 3.5 Flash, Gemini 3.1 Flash-Lite, Claude Sonnet 4.6, Claude Opus 4.1, and more—and it can ask one or multiple models in a single run. Browser automation is available; use `--browser-model-strategy current` to keep the active ChatGPT model (or `ignore` to skip the picker). API remains the most reliable path, and `--copy` is an easy manual fallback.
 
 ## Setting up (macOS Browser Mode)
 
@@ -101,7 +101,7 @@ npx -y @steipete/oracle --engine browser --model gpt-5.5-pro \
   --browser-follow-up "Give the final decision"
 
 # Gemini browser mode (no API key; uses Chrome cookies from gemini.google.com)
-npx -y @steipete/oracle --engine browser --model gemini-3-pro --prompt "a cute robot holding a banana" --generate-image out.jpg --aspect 1:1
+npx -y @steipete/oracle --engine browser --model gemini-3.1-pro --prompt "a cute robot holding a banana" --generate-image out.jpg --aspect 1:1
 
 # Sessions (list and replay)
 npx -y @steipete/oracle status --hours 72
@@ -118,13 +118,14 @@ Engine auto-picks API when `OPENAI_API_KEY` is set, otherwise browser; browser i
 
 **CLI**
 
-- API mode expects API keys in your environment: `OPENAI_API_KEY` (GPT-5.x), `GEMINI_API_KEY` (Gemini 3.1 Pro / Gemini 3 Pro), `ANTHROPIC_API_KEY` (Claude Sonnet 4.6 / Opus 4.1).
+- API mode expects API keys in your environment: `OPENAI_API_KEY` (GPT-5.x), `GEMINI_API_KEY` (Gemini 3.1 Pro / 3.5 Flash / 3.1 Flash-Lite), `ANTHROPIC_API_KEY` (Claude Sonnet 4.6 / Opus 4.1).
 - Gemini browser mode uses Chrome cookies instead of an API key—just be logged into `gemini.google.com` in Chrome (no Python/venv required).
-- If your Gemini account can’t access “Pro”, Oracle auto-falls back to a supported model for web runs (and logs the fallback in verbose mode).
+- Gemini browser mode accepts explicit `gemini-3.1-flash-lite`, `gemini-3.5-flash`, and `gemini-3.1-pro` IDs. Legacy `gemini-3-pro` browser runs target current Gemini 3.1 Pro. If your account can’t access the requested model, Oracle falls back to 3.1 Flash-Lite and logs the fallback in verbose mode.
 - Prefer API mode or `--copy` + manual paste; browser automation is experimental.
 - Browser support: stable on macOS; works on Linux (add `--browser-chrome-path/--browser-cookie-path` when needed) and Windows (manual-login or inline cookies recommended when app-bound cookies block decryption).
 - Remote browser service: `oracle serve` on a signed-in host; clients use `--remote-host/--remote-token`.
-- Browser artifacts: browser sessions save `transcript.md` and generated artifacts under `~/.oracle/sessions/<id>/artifacts/`. Deep Research saves `deep-research-report.md` when the report surface is captured; ChatGPT-generated images are downloaded with the active browser cookies when image URLs are present.
+- Browser artifacts: browser sessions save `transcript.md` and generated artifacts under `~/.oracle/sessions/<id>/artifacts/`. Deep Research saves `deep-research-report.md` when the report surface is captured; ChatGPT-generated images and downloadable files are saved with the active browser session when supported file URLs are present.
+- MCP image agents: use the `chatgpt_image` tool for the easiest path, or pass `generateImage` to `consult` with `engine: "browser"`; saved paths come back in `structuredContent.images`.
 - Browser archiving: by default, successful non-project, non-Deep-Research, non-multi-turn ChatGPT one-shots are archived after local artifacts are saved. Use `--browser-archive never` to disable or `--browser-archive always` to force archiving after a successful browser run. Archived chats remain manageable in ChatGPT.
 - Conversation mode guidance: use one-shot browser runs for narrow bug reports or quick file-set reviews; use explicit browser follow-ups for ambiguous architecture/product tradeoffs where a challenge pass and final decision are valuable; use Deep Research for broad public-web questions that need citations. Oracle never invents follow-ups automatically.
 - Project Sources: `oracle project-sources list|add --chatgpt-url <project-url>` manages the Project Sources tab in ChatGPT browser mode. v1 is append-only (`list`, `add`, `--dry-run`) so agents can share explicit project context without deleting or replacing user sources.
@@ -179,7 +180,7 @@ npx -y @steipete/oracle oracle-mcp
 - Claude Code / MCP browser consults can use the `chatgpt-pro-heavy` preset for a compact ChatGPT Pro second-opinion workflow.
 - Render/copy bundles for manual paste into ChatGPT when automation is blocked.
 - GPT‑5 Pro API runs detach by default; reattach via `oracle session <id>` / `oracle status` or block with `--wait`.
-- OpenAI/Azure follow-up API runs can continue from `--followup <sessionId|responseId>`; for multi-model parents, add `--followup-model <model>`.
+- Saved ChatGPT browser conversations and OpenAI/Azure API runs can continue from `--followup <sessionId|responseId>`; for multi-model API parents, add `--followup-model <model>`.
 - Azure endpoints supported via `--azure-endpoint/--azure-deployment/--azure-api-version` or `AZURE_OPENAI_*` envs; use `--provider openai` / `--no-azure` to force first-party OpenAI when Azure env vars are present.
 - Redacted provider checks via `oracle doctor --providers`, `--route`, and `--preflight` before spending API time.
 - File safety: globs/excludes, size guards, `--files-report`.
@@ -212,7 +213,17 @@ Successful models write per-model files such as `/tmp/oracle-panel.gpt-5.4.md`;
 
 ## Follow-up and lineage
 
-Use `--followup` to continue an existing OpenAI/Azure Responses API run with additional context/files:
+Use `--followup` to continue a saved ChatGPT browser conversation or an existing OpenAI/Azure Responses API run with additional context/files:
+
+```bash
+oracle \
+  --followup <browser-session-id-or-slug> \
+  --slug "my-browser-followup" \
+  -p "Follow-up: review this additional file in the same conversation." \
+  --file "server/src/strategy/plan.ts"
+```
+
+Browser followup reopens the exact saved conversation and inherits its browser profile, configuration, and model. Resume fails closed before submission if Oracle cannot verify the saved thread and prior turns.
 
 ```bash
 oracle \
@@ -277,9 +288,9 @@ Browser automation can open or control Chrome, so dry-runs and live runs print a
 | `-p, --prompt <text>`                                                          | Required prompt.                                                                                                                                                                                                                                                                                                                          |
 | `-f, --file <paths...>`                                                        | Attach files/dirs (globs + `!` excludes).                                                                                                                                                                                                                                                                                                 |
 | `-e, --engine <api\|browser>`                                                  | Choose API or browser (browser is experimental).                                                                                                                                                                                                                                                                                          |
-| `-m, --model <name>`                                                           | Built-ins (`gpt-5.5-pro` default, `gpt-5.5`, `gpt-5.4-pro`, `gpt-5.4`, `gpt-5.1-pro`, `gpt-5-pro`, `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.2`, `gpt-5.2-instant`, `gpt-5.2-pro`, `gemini-3.1-pro` API-only, `gemini-3-pro`, `claude-4.6-sonnet`, `claude-4.1-opus`) plus any OpenRouter id (e.g., `minimax/minimax-m2`, `openai/gpt-4o-mini`). |
+| `-m, --model <name>`                                                           | Built-ins (`gpt-5.5-pro` default, `gpt-5.5`, `gpt-5.4-pro`, `gpt-5.4`, `gpt-5.1-pro`, `gpt-5-pro`, `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.2`, `gpt-5.2-instant`, `gpt-5.2-pro`, `gemini-3.1-pro` API + UI, `gemini-3-pro`, `claude-4.6-sonnet`, `claude-4.1-opus`) plus any OpenRouter id (e.g., `minimax/minimax-m2`, `openai/gpt-4o-mini`). |
 | `--models <list>`                                                              | Comma-separated API models (mix built-ins and OpenRouter ids) for multi-model runs.                                                                                                                                                                                                                                                       |
-| `--followup <sessionId\|responseId>`                                           | Continue an OpenAI/Azure Responses API run from a stored oracle session or `resp_...` response id.                                                                                                                                                                                                                                        |
+| `--followup <sessionId\|responseId>`                                           | Continue a saved ChatGPT browser conversation or an OpenAI/Azure Responses API run from a stored Oracle session or `resp_...` response id.                                                                                                                                                                                                |
 | `--followup-model <model>`                                                     | For multi-model OpenAI/Azure parent sessions, choose which model response to continue from.                                                                                                                                                                                                                                               |
 | `--base-url <url>`                                                             | Point API runs at LiteLLM/Azure/OpenRouter/etc.                                                                                                                                                                                                                                                                                           |
 | `--chatgpt-url <url>`                                                          | Target a ChatGPT workspace/folder or Temporary Chat URL (browser).                                                                                                                                                                                                                                                                        |

package/dist/bin/oracle-cli.js

@@ -41,6 +41,7 @@ import { resolveConfiguredMaxFileSizeBytes } from "../src/cli/fileSize.js";
 import { isAzureOpenAICandidateModel, validateProviderRouting, } from "../src/oracle/providerRouting.js";
 import { buildSessionLifecycle, formatSessionLifecycleBlock } from "../src/cli/sessionLifecycle.js";
 import { buildDetachedPerfTraceEnv, createPerfTrace, isTraceValueFlag, } from "../src/cli/perfTrace.js";
+import { resolveBrowserFollowupReference } from "../src/cli/followup.js";
 const VERSION = getCliVersion();
 const CLI_ENTRYPOINT = fileURLToPath(import.meta.url);
 const LEGACY_FLAG_ALIASES = new Map([
@@ -203,8 +204,8 @@ program
     .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("--followup <sessionId|responseId>", "Continue an OpenAI/Azure Responses API run from a stored response id (resp_...) or from a stored oracle session id.")
-    .option("--followup-model <model>", "When following up a multi-model session, choose which model response to continue from.")
+    .option("--followup <sessionId|responseId>", "Continue a stored ChatGPT browser conversation or an OpenAI/Azure Responses API run.")
+    .option("--followup-model <model>", "For multi-model API sessions, choose which model response to continue from.")
     .option("-f, --file <paths...>", "Files/directories or glob patterns to attach (prefix with !pattern to exclude). Oversized files are rejected automatically (default cap: 1 MB; configurable via ORACLE_MAX_FILE_SIZE_BYTES or config.maxFileSizeBytes).", collectPaths, [])
     .option("--max-file-size-bytes <bytes>", "Reject files larger than this many bytes.", parseIntOption)
     .addOption(new Option("--include <paths...>", "Alias for --file.")
@@ -226,7 +227,7 @@ program
     .addOption(new Option("--copy-markdown", "Copy the assembled markdown bundle to the clipboard; pair with --render to print it too.").default(false))
     .addOption(new Option("--copy").hideHelp().default(false))
     .option("-s, --slug <words>", "Custom session slug (3-5 words).")
-    .option("-m, --model <model>", 'Model to target (gpt-5.5-pro default). Also gpt-5.5, gpt-5.4-pro, gpt-5.4, gpt-5.1-pro, gpt-5-pro, gpt-5.1, gpt-5.1-codex API-only, gpt-5.2, gpt-5.2-instant, gpt-5.2-pro, gemini-3.1-pro API-only, gemini-3-pro, claude-4.6-sonnet, claude-4.1-opus, or ChatGPT labels like "5.5 Pro" / "5.2 Thinking" for browser runs).', normalizeModelOption)
+    .option("-m, --model <model>", 'Model to target (gpt-5.5-pro default). Also gpt-5.5, gpt-5.4-pro, gpt-5.4, gpt-5.1-pro, gpt-5-pro, gpt-5.1, gpt-5.1-codex API-only, gpt-5.2, gpt-5.2-instant, gpt-5.2-pro, gemini-3.1-flash-lite, gemini-3.5-flash, gemini-3.1-pro, legacy gemini-3-pro, claude-4.6-sonnet, claude-4.1-opus, or ChatGPT labels like "5.5 Pro" / "5.2 Thinking" for browser runs).', normalizeModelOption)
     .addOption(new Option("--models <models>", 'Comma-separated API model list to query in parallel (e.g., "gpt-5.5-pro,gemini-3-pro").')
     .argParser(collectModelList)
     .default([]))
@@ -553,6 +554,7 @@ program
     .option("--live", "Tail the live browser tab for this session until it completes, stalls, or detaches.", false)
     .option("--write-output <path>", "Write harvested browser output to this file (requires --harvest or --live).")
     .option("--browser-tab <ref>", "Override the browser tab ref used for harvesting/live tail (current, target id, URL, or title substring).")
+    .option("--no-recover", "Do not relaunch Chrome to reopen the saved conversation URL when --harvest/--live finds no live tab.")
     .addOption(new Option("--clean", "Deprecated alias for --clear.").default(false).hideHelp())
     .action(async (sessionId, _options, cmd) => {
     const { handleSessionCommand } = await import("../src/cli/sessionCommand.js");
@@ -657,6 +659,7 @@ function buildRunOptions(options, overrides = {}) {
         model: options.model,
         models: overrides.models ?? options.models,
         previousResponseId: overrides.previousResponseId ?? options.previousResponseId,
+        browserResumeConversationUrl: overrides.browserResumeConversationUrl ?? options.browserResumeConversationUrl,
         effectiveModelId: overrides.effectiveModelId ?? options.effectiveModelId ?? options.model,
         file: overrides.file ?? options.file ?? [],
         maxFileSizeBytes: overrides.maxFileSizeBytes ?? options.maxFileSizeBytes,
@@ -894,6 +897,7 @@ function buildRunOptionsFromMetadata(metadata) {
         model: stored.model ?? DEFAULT_MODEL,
         models: stored.models,
         previousResponseId: stored.previousResponseId,
+        browserResumeConversationUrl: stored.browserResumeConversationUrl,
         effectiveModelId: stored.effectiveModelId ?? stored.model,
         file: stored.file ?? [],
         maxFileSizeBytes: stored.maxFileSizeBytes,
@@ -1167,18 +1171,6 @@ async function runRootCommand(options) {
         throw new Error("--remote-host does not support --models yet. Use API engine locally instead.");
     }
     const resolvedModel = normalizedMultiModels[0] ?? (isGemini ? resolveApiModel(cliModelArg) : resolvedModelCandidate);
-    const includesGeminiApiOnly = (normalizedMultiModels.length > 0 ? normalizedMultiModels : [resolvedModel]).some((model) => model === "gemini-3.1-pro");
-    if (browserExplicitlyRequested && includesGeminiApiOnly) {
-        throw new Error("gemini-3.1-pro is API-only today. Use --engine api or switch to gemini-3-pro for Gemini web.");
-    }
-    if (engine === "browser" && includesGeminiApiOnly) {
-        console.log(chalk.dim("gemini-3.1-pro is API-only today; switching to API."));
-        engine = "api";
-    }
-    const browserFollowUpCount = options.browserFollowUp?.filter((entry) => entry.trim().length > 0).length ?? 0;
-    if (engine !== "browser" && browserFollowUpCount > 0) {
-        throw new Error("--browser-follow-up requires --engine browser.");
-    }
     const effectiveModelId = resolvedModel.startsWith("gemini")
         ? resolveGeminiModelId(resolvedModel)
         : isKnownModel(resolvedModel)
@@ -1196,18 +1188,6 @@ async function runRootCommand(options) {
     resolvedOptions.effectiveModelId = effectiveModelId;
     resolvedOptions.provider = providerMode;
     resolvedOptions.writeOutputPath = resolveOutputPath(options.writeOutput, process.cwd());
-    // 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 pro API runs
-    let waitPreference = resolveWaitFlag({
-        waitFlag: options.wait,
-        model: resolvedModel,
-        engine,
-    });
-    if (remoteHost && waitPreference === false) {
-        console.log(chalk.dim("Remote browser runs require --wait; ignoring --no-wait."));
-        waitPreference = true;
-    }
     if (options.status) {
         const { attachSession, showStatus } = await import("../src/cli/sessionDisplay.js");
         if (options.session) {
@@ -1280,16 +1260,53 @@ async function runRootCommand(options) {
             getSource("browserAttachmentTimeout") === "default")) {
         options.browserAttachmentTimeout = attachmentTimeoutEnv;
     }
+    let browserFollowup = null;
+    if (options.followup) {
+        if (normalizedMultiModels.length > 0) {
+            throw new Error("--followup cannot be combined with --models.");
+        }
+        browserFollowup = await resolveBrowserFollowupReference(options.followup, sessionStore);
+        if (browserFollowup) {
+            engine = "browser";
+            resolvedOptions.model = browserFollowup.model;
+            resolvedOptions.effectiveModelId = browserFollowup.model;
+            resolvedOptions.followupSessionId = browserFollowup.sessionId;
+            resolvedOptions.browserResumeConversationUrl = browserFollowup.resumeConversationUrl;
+        }
+        else {
+            assertFollowupSupported({
+                engine,
+                model: resolvedModel,
+                baseUrl: resolvedBaseUrl,
+                azureEndpoint: resolvedOptions.azure?.endpoint,
+            });
+            const followup = await resolveFollowupReference(options.followup, options.followupModel);
+            resolvedOptions.previousResponseId = followup.responseId;
+            resolvedOptions.followupSessionId = followup.sessionId;
+            resolvedOptions.followupModel = options.followupModel;
+        }
+    }
+    const activeModel = resolvedOptions.model;
+    const browserFollowUpCount = options.browserFollowUp?.filter((entry) => entry.trim().length > 0).length ?? 0;
+    if (engine !== "browser" && browserFollowUpCount > 0) {
+        throw new Error("--browser-follow-up requires --engine browser.");
+    }
     const sessionMode = engine === "browser" ? "browser" : "api";
     const browserConfig = await (async () => {
         if (sessionMode !== "browser")
             return undefined;
+        if (browserFollowup) {
+            return browserFollowup.browserConfig;
+        }
         const { buildBrowserConfig, resolveBrowserModelLabel } = await import("../src/cli/browserConfig.js");
-        return buildBrowserConfig({
+        const config = await buildBrowserConfig({
             ...options,
-            model: resolvedModel,
-            browserModelLabel: resolveBrowserModelLabel(cliModelArg, resolvedModel),
+            model: activeModel,
+            browserModelLabel: resolveBrowserModelLabel(cliModelArg, activeModel),
         });
+        return resolvedOptions.browserResumeConversationUrl
+            ? { ...config, resumeConversationUrl: resolvedOptions.browserResumeConversationUrl }
+            : config;
     })();
     if (previewMode) {
         if (!options.prompt) {
@@ -1299,21 +1316,6 @@ async function runRootCommand(options) {
             options.prompt = `${options.prompt.trim()}\n${userConfig.promptSuffix}`;
         }
         resolvedOptions.prompt = options.prompt;
-        if (options.followup) {
-            assertFollowupSupported({
-                engine,
-                model: resolvedModel,
-                baseUrl: resolvedBaseUrl,
-                azureEndpoint: resolvedOptions.azure?.endpoint,
-            });
-            if (normalizedMultiModels.length > 0) {
-                throw new Error("--followup cannot be combined with --models.");
-            }
-            const followup = await resolveFollowupReference(options.followup, options.followupModel);
-            resolvedOptions.previousResponseId = followup.responseId;
-            resolvedOptions.followupSessionId = followup.sessionId;
-            resolvedOptions.followupModel = options.followupModel;
-        }
         const runOptions = buildRunOptions(resolvedOptions, {
             preview: true,
             previewMode,
@@ -1360,21 +1362,6 @@ async function runRootCommand(options) {
         options.prompt = `${options.prompt.trim()}\n${userConfig.promptSuffix}`;
     }
     resolvedOptions.prompt = options.prompt;
-    if (options.followup) {
-        assertFollowupSupported({
-            engine,
-            model: resolvedModel,
-            baseUrl: resolvedBaseUrl,
-            azureEndpoint: resolvedOptions.azure?.endpoint,
-        });
-        if (normalizedMultiModels.length > 0) {
-            throw new Error("--followup cannot be combined with --models.");
-        }
-        const followup = await resolveFollowupReference(options.followup, options.followupModel);
-        resolvedOptions.previousResponseId = followup.responseId;
-        resolvedOptions.followupSessionId = followup.sessionId;
-        resolvedOptions.followupModel = options.followupModel;
-    }
     const duplicateBlocked = await shouldBlockDuplicatePrompt({
         prompt: resolvedOptions.prompt,
         browserFollowUps: resolvedOptions.browserFollowUp,
@@ -1413,7 +1400,7 @@ async function runRootCommand(options) {
         };
         console.log(chalk.dim(`Routing browser automation to remote host ${remoteHost}`));
     }
-    else if (browserConfig && resolvedModel.startsWith("gemini")) {
+    else if (browserConfig && activeModel.startsWith("gemini")) {
         const { createGeminiWebExecutor } = await import("../src/gemini-web/index.js");
         browserDeps = {
             executeBrowser: createGeminiWebExecutor({
@@ -1448,6 +1435,18 @@ async function runRootCommand(options) {
         }, {});
         return;
     }
+    // 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 pro API runs
+    let waitPreference = resolveWaitFlag({
+        waitFlag: options.wait,
+        model: activeModel,
+        engine,
+    });
+    if (remoteHost && waitPreference === false) {
+        console.log(chalk.dim("Remote browser runs require --wait; ignoring --no-wait."));
+        waitPreference = true;
+    }
     await sessionStore.ensureStorage();
     const baseRunOptions = buildRunOptions(resolvedOptions, {
         preview: false,
@@ -1469,6 +1468,7 @@ async function runRootCommand(options) {
         browserConfig,
         followupSessionId: resolvedOptions.followupSessionId,
         followupModel: resolvedOptions.followupModel,
+        browserResumeConversationUrl: resolvedOptions.browserResumeConversationUrl,
         waitPreference,
         youtube: options.youtube,
         generateImage: options.generateImage,
@@ -1480,14 +1480,14 @@ async function runRootCommand(options) {
     const liveRunOptions = {
         ...baseRunOptions,
         sessionId: sessionMeta.id,
-        effectiveModelId,
+        effectiveModelId: resolvedOptions.effectiveModelId ?? effectiveModelId,
     };
     const disableDetachEnv = process.env.ORACLE_NO_DETACH === "1";
     const detachAllowed = remoteExecutionActive
         ? false
         : shouldDetachSession({
             engine,
-            model: resolvedModel,
+            model: activeModel,
             waitPreference,
             disableDetachEnv,
         });

package/dist/docs-site/CNAME

@@ -0,0 +1 @@
+askoracle.sh