@steipete/oracle 0.8.5 → 0.9.0

package/README.md

@@ -11,7 +11,39 @@
   <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.1 Pro (default alias to GPT-5.2 Pro on the API), GPT-5.1 Codex (API-only), GPT-5.1, GPT-5.2, Gemini 3 Pro, Claude Sonnet 4.5, 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.4 Pro (default), 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.5, 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)
+
+Browser mode lets you use GPT-5.2 Pro without any API keys — it automates your Chrome browser directly.
+
+### First-time login
+
+Run this once to create an automation profile and log into ChatGPT. The browser will stay open so you can complete the login:
+
+```bash
+oracle --engine browser --browser-manual-login \
+  --browser-keep-browser --browser-input-timeout 120000 \
+  -p "HI"
+```
+
+### Subsequent runs
+
+Once logged in, the automation profile is saved. Use this for all future runs:
+
+```bash
+oracle --engine browser --browser-manual-login \
+  --browser-auto-reattach-delay 5s \
+  --browser-auto-reattach-interval 3s \
+  --browser-auto-reattach-timeout 60s \
+  -p "your prompt"
+```
+
+> **Why these flags?**
+> - `--browser-manual-login` — Skips macOS Keychain cookie access (avoids repeated permission popups)
+> - `--browser-auto-reattach-*` — Reconnects when ChatGPT redirects mid-page-load (fixes "Inspected target navigated or closed" error)
+> - `--browser-keep-browser` — Keeps browser open for first-time login (not needed after)
+> - `--browser-input-timeout 120000` — Gives you 2 minutes to log in on first run
 
 ## Quick start
 
@@ -30,6 +62,12 @@ npx -y @steipete/oracle -p "Write a concise architecture note for the storage ad
 # Multi-model API run
 npx -y @steipete/oracle -p "Cross-check the data layer assumptions" --models gpt-5.1-pro,gemini-3-pro --file "src/**/*.ts"
 
+# Follow up from an existing OpenAI/Azure session id
+npx -y @steipete/oracle --engine api --model gpt-5.2-pro --followup release-readiness-audit --followup-model gpt-5.2-pro -p "Re-evaluate with this new context" --file "src/**/*.ts"
+
+# Follow up directly from an OpenAI Responses API id
+npx -y @steipete/oracle --engine api --model gpt-5.2-pro --followup resp_abc1234567890 -p "Continue from this response" --file docs/notes.md
+
 # Preview without spending tokens
 npx -y @steipete/oracle --dry-run summary -p "Check release notes" --file docs/release-notes.md
 
@@ -42,6 +80,7 @@ npx -y @steipete/oracle --engine browser --model gemini-3-pro --prompt "a cute r
 # Sessions (list and replay)
 npx -y @steipete/oracle status --hours 72
 npx -y @steipete/oracle session <id> --render
+npx -y @steipete/oracle restart <id>
 
 # TUI (interactive, only for humans)
 npx -y @steipete/oracle tui
@@ -52,7 +91,7 @@ Engine auto-picks API when `OPENAI_API_KEY` is set, otherwise browser; browser i
 ## Integration
 
 **CLI**
-- API mode expects API keys in your environment: `OPENAI_API_KEY` (GPT-5.x), `GEMINI_API_KEY` (Gemini 3 Pro), `ANTHROPIC_API_KEY` (Claude Sonnet 4.5 / Opus 4.1).
+- 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.5 / 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).
 - Prefer API mode or `--copy` + manual paste; browser automation is experimental.
@@ -95,11 +134,61 @@ npx -y @steipete/oracle oracle-mcp
 - Multi-model API runs with aggregated cost/usage, including OpenRouter IDs alongside first-party models.
 - 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>`.
 - Azure endpoints supported via `--azure-endpoint/--azure-deployment/--azure-api-version` or `AZURE_OPENAI_*` envs.
 - File safety: globs/excludes, size guards, `--files-report`.
 - Sessions you can replay (`oracle status`, `oracle session <id> --render`).
 - Session logs and bundles live in `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`).
 
+## Follow-up and lineage
+
+Use `--followup` to continue an existing OpenAI/Azure Responses API run with additional context/files:
+
+```bash
+oracle \
+  --engine api \
+  --model gpt-5.2-pro \
+  --followup <existing-session-id-or-resp_id> \
+  --followup-model gpt-5.2-pro \
+  --slug "my-followup-run" \
+  --wait \
+  -p "Follow-up: re-evaluate the previous recommendation with the attached files." \
+  --file "server/src/strategy/plan.ts" \
+  --file "server/src/strategy/executor.ts"
+```
+
+When the parent session used `--models`, `--followup-model` picks which model's response id to chain from.
+Custom `--base-url` providers plus Gemini/Claude API runs are excluded here because they do not preserve `previous_response_id` in Oracle.
+
+`oracle status` shows parent/child lineage in tree form:
+
+```text
+Recent Sessions
+Status    Model         Mode    Timestamp           Chars    Cost  Slug
+completed gpt-5.2-pro   api     03/01/2026 09:00 AM  1800  $2.110  architecture-review-parent
+completed gpt-5.2-pro   api     03/01/2026 09:14 AM  2200  $2.980  ├─ architecture-review-followup
+running   gpt-5.2-pro   api     03/01/2026 09:22 AM  1400       -  │  └─ architecture-review-implementation-pass
+pending   gpt-5.2-pro   api     03/01/2026 09:25 AM   900       -  └─ architecture-review-risk-check
+```
+
+## Browser auto-reattach (long Pro runs)
+
+When browser runs time out (common with long GPT‑5.x Pro responses), Oracle can keep polling the existing ChatGPT tab and capture the final answer without manual `oracle session <id>` commands.
+
+Enable auto-reattach by setting a non-zero interval:
+- `--browser-auto-reattach-delay` — wait before the first retry (e.g. `30s`)
+- `--browser-auto-reattach-interval` — how often to retry (e.g. `2m`)
+- `--browser-auto-reattach-timeout` — per-attempt budget (default `2m`)
+
+```bash
+oracle --engine browser \
+  --browser-timeout 6m \
+  --browser-auto-reattach-delay 30s \
+  --browser-auto-reattach-interval 2m \
+  --browser-auto-reattach-timeout 2m \
+  -p "Run the long UI audit" --file "src/**/*.ts"
+```
+
 ## Flags you’ll actually use
 
 | Flag | Purpose |
@@ -107,8 +196,10 @@ npx -y @steipete/oracle oracle-mcp
 | `-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.1-pro` default, `gpt-5-pro`, `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.2`, `gpt-5.2-instant`, `gpt-5.2-pro`, `gemini-3-pro`, `claude-4.5-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.4-pro` default, `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.5-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-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 (browser). |
 | `--browser-model-strategy <select\|current\|ignore>` | Control ChatGPT model selection in browser mode (current keeps the active model; ignore skips the picker). |
@@ -117,6 +208,9 @@ npx -y @steipete/oracle oracle-mcp
 | `--browser-port <port>` | Pin the Chrome DevTools port (WSL/Windows firewall helper). |
 | `--browser-inline-cookies[(-file)] <payload|path>` | Supply cookies without Chrome/Keychain (browser). |
 | `--browser-timeout`, `--browser-input-timeout` | Control overall/browser input timeouts (supports h/m/s/ms). |
+| `--browser-recheck-delay`, `--browser-recheck-timeout` | Delayed recheck for long Pro runs: wait then retry capture after timeout (supports h/m/s/ms). |
+| `--browser-reuse-wait` | Wait for a shared Chrome profile before launching (parallel browser runs). |
+| `--browser-profile-lock-timeout` | Wait for the shared manual-login profile lock before sending (serializes parallel runs). |
 | `--render`, `--copy` | Print and/or copy the assembled markdown bundle. |
 | `--wait` | Block for background API runs (e.g., GPT‑5.1 Pro) instead of detaching. |
 | `--timeout <seconds\|auto>` | Overall API deadline (auto = 60m for pro, 120s otherwise). |
@@ -139,7 +233,7 @@ npx -y @steipete/oracle oracle-mcp
 Put defaults in `~/.oracle/config.json` (JSON5). Example:
 ```json5
 {
-  model: "gpt-5.1-pro",
+  model: "gpt-5.4-pro",
   engine: "api",
   filesReport: true,
   browser: {
@@ -154,7 +248,7 @@ Advanced flags
 
 | Area | Flags |
 | --- | --- |
-| Browser | `--browser-manual-login`, `--browser-thinking-time`, `--browser-timeout`, `--browser-input-timeout`, `--browser-cookie-wait`, `--browser-inline-cookies[(-file)]`, `--browser-attachments`, `--browser-inline-files`, `--browser-bundle-files`, `--browser-keep-browser`, `--browser-headless`, `--browser-hide-window`, `--browser-no-cookie-sync`, `--browser-allow-cookie-errors`, `--browser-chrome-path`, `--browser-cookie-path`, `--chatgpt-url` |
+| Browser | `--browser-manual-login`, `--browser-thinking-time`, `--browser-timeout`, `--browser-input-timeout`, `--browser-recheck-delay`, `--browser-recheck-timeout`, `--browser-reuse-wait`, `--browser-profile-lock-timeout`, `--browser-auto-reattach-delay`, `--browser-auto-reattach-interval`, `--browser-auto-reattach-timeout`, `--browser-cookie-wait`, `--browser-inline-cookies[(-file)]`, `--browser-attachments`, `--browser-inline-files`, `--browser-bundle-files`, `--browser-keep-browser`, `--browser-headless`, `--browser-hide-window`, `--browser-no-cookie-sync`, `--browser-allow-cookie-errors`, `--browser-chrome-path`, `--browser-cookie-path`, `--chatgpt-url` |
 | Run control | `--background`, `--no-background`, `--http-timeout`, `--zombie-timeout`, `--zombie-last-activity` |
 | Azure/OpenAI | `--azure-endpoint`, `--azure-deployment`, `--azure-api-version`, `--base-url` |