@steipete/oracle 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +56 -11
  2. package/dist/bin/oracle-cli.js +440 -98
  3. package/dist/src/browser/actions/archiveConversation.js +12 -0
  4. package/dist/src/browser/actions/modelSelection.js +61 -18
  5. package/dist/src/browser/actions/navigation.js +5 -3
  6. package/dist/src/browser/actions/promptComposer.js +75 -18
  7. package/dist/src/browser/actions/thinkingTime.js +23 -8
  8. package/dist/src/browser/config.js +1 -7
  9. package/dist/src/browser/constants.js +1 -1
  10. package/dist/src/browser/index.js +65 -48
  11. package/dist/src/browser/manualLoginProfile.js +54 -0
  12. package/dist/src/browser/projectSourcesRunner.js +16 -5
  13. package/dist/src/browser/prompt.js +56 -37
  14. package/dist/src/browser/sessionRunner.js +72 -1
  15. package/dist/src/browser/utils.js +1 -47
  16. package/dist/src/browser/zipBundle.js +152 -0
  17. package/dist/src/cli/browserConfig.js +13 -18
  18. package/dist/src/cli/browserDefaults.js +2 -1
  19. package/dist/src/cli/docsCheck.js +186 -0
  20. package/dist/src/cli/engine.js +11 -4
  21. package/dist/src/cli/options.js +12 -6
  22. package/dist/src/cli/perfTrace.js +242 -0
  23. package/dist/src/cli/promptRequirement.js +2 -0
  24. package/dist/src/cli/providerDoctor.js +85 -0
  25. package/dist/src/cli/runOptions.js +46 -16
  26. package/dist/src/cli/sessionDisplay.js +39 -4
  27. package/dist/src/cli/sessionLifecycle.js +38 -0
  28. package/dist/src/cli/sessionRunner.js +228 -3
  29. package/dist/src/cli/sessionTable.js +2 -1
  30. package/dist/src/duration.js +47 -0
  31. package/dist/src/mcp/tools/consult.js +19 -3
  32. package/dist/src/mcp/types.js +5 -2
  33. package/dist/src/mcp/utils.js +4 -1
  34. package/dist/src/oracle/baseUrl.js +17 -0
  35. package/dist/src/oracle/client.js +1 -22
  36. package/dist/src/oracle/config.js +17 -4
  37. package/dist/src/oracle/gemini.js +2 -22
  38. package/dist/src/oracle/geminiModels.js +21 -0
  39. package/dist/src/oracle/modelResolver.js +7 -1
  40. package/dist/src/oracle/multiModelRunner.js +20 -2
  41. package/dist/src/oracle/providerFailures.js +204 -0
  42. package/dist/src/oracle/providerRoutePlan.js +281 -0
  43. package/dist/src/oracle/providerRouting.js +92 -0
  44. package/dist/src/oracle/run.js +157 -54
  45. package/dist/src/oracle.js +1 -0
  46. package/dist/src/remote/client.js +8 -0
  47. package/dist/src/remote/server.js +26 -0
  48. package/dist/src/sessionManager.js +5 -1
  49. package/package.json +8 -6
package/README.md CHANGED
@@ -19,7 +19,7 @@ Browser mode lets you use GPT-5.5 Pro without any API keys — it automates your
19
19
 
20
20
  ### First-time login
21
21
 
22
- Run this once to create an automation profile and log into ChatGPT. The browser will stay open so you can complete the login:
22
+ Run this once to create Oracle's private automation profile and log into ChatGPT. This profile is separate from your normal Chrome profile. The browser will stay open so you can complete the login:
23
23
 
24
24
  ```bash
25
25
  oracle --engine browser --browser-manual-login \
@@ -72,6 +72,18 @@ npx -y @steipete/oracle --engine api --model gpt-5.2-pro --followup resp_abc1234
72
72
  # Preview without spending tokens
73
73
  npx -y @steipete/oracle --dry-run summary -p "Check release notes" --file docs/release-notes.md
74
74
 
75
+ # Check provider routing/readiness before an API panel
76
+ npx -y @steipete/oracle doctor --providers --models gpt-5.5-pro,gemini-3-pro,claude-4.6-sonnet
77
+
78
+ # Multi-model advisory panel with recoverable partial success
79
+ npx -y @steipete/oracle --models gpt-5.5-pro,gemini-3-pro,claude-4.6-sonnet \
80
+ --allow-partial --write-output /tmp/panel.md \
81
+ -p "Review the naming options" --file docs/naming.md
82
+
83
+ # Trace startup and time-to-first-output
84
+ npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json \
85
+ --dry-run summary -p "Quick smoke"
86
+
75
87
  # Browser run (no API key, will open ChatGPT)
76
88
  npx -y @steipete/oracle --engine browser -p "Walk through the UI smoke test" --file "src/**/*.ts"
77
89
 
@@ -116,6 +128,8 @@ Engine auto-picks API when `OPENAI_API_KEY` is set, otherwise browser; browser i
116
128
  - 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.
117
129
  - 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.
118
130
  - 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.
131
+ - Fast failure: root runs without a prompt exit nonzero after printing help; `--dry-run` conflicts with `--render` / `--render-markdown`; foreground API runs exit 130 on Ctrl-C while browser cleanup and session recovery still run.
132
+ - Performance traces: `--perf-trace` / `ORACLE_PERF_TRACE=1` writes JSON timing marks for startup, root command, first output, and exit. `--perf-trace-path` or `--perf-trace=/tmp/oracle.json` selects the path; detached API children write a session-suffixed sidecar trace.
119
133
  - AGENTS.md/CLAUDE.md:
120
134
  ```
121
135
  - Oracle bundles a prompt plus the right files so another AI (GPT 5 Pro + more) can answer. Use when stuck/bugs/reviewing.
@@ -166,11 +180,36 @@ npx -y @steipete/oracle oracle-mcp
166
180
  - Render/copy bundles for manual paste into ChatGPT when automation is blocked.
167
181
  - GPT‑5 Pro API runs detach by default; reattach via `oracle session <id>` / `oracle status` or block with `--wait`.
168
182
  - OpenAI/Azure follow-up API runs can continue from `--followup <sessionId|responseId>`; for multi-model parents, add `--followup-model <model>`.
169
- - Azure endpoints supported via `--azure-endpoint/--azure-deployment/--azure-api-version` or `AZURE_OPENAI_*` envs.
183
+ - 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.
184
+ - Redacted provider checks via `oracle doctor --providers`, `--route`, and `--preflight` before spending API time.
170
185
  - File safety: globs/excludes, size guards, `--files-report`.
171
186
  - Sessions you can replay (`oracle status`, `oracle session <id> --render`).
172
187
  - Session logs and bundles live in `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`).
173
188
 
189
+ ## API provider checks
190
+
191
+ Use these before expensive API or multi-model runs:
192
+
193
+ ```bash
194
+ oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro
195
+ oracle --preflight --models gpt-5.4,gemini-3-pro
196
+ oracle --provider openai --route --model gpt-5.4
197
+ ```
198
+
199
+ `doctor` and `--preflight` print redacted readiness only: provider route, base host, key source, Azure state, and local configuration errors. `--route` shows the selected route and exits before creating a session. If Azure env/config is present but you want first-party OpenAI, add `--provider openai` or `--no-azure`.
200
+
201
+ For advisory panels where one good answer is useful, combine partial success with explicit output files:
202
+
203
+ ```bash
204
+ oracle \
205
+ --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro \
206
+ --allow-partial \
207
+ --write-output /tmp/oracle-panel.md \
208
+ -p "Compare these naming options"
209
+ ```
210
+
211
+ Successful models write per-model files such as `/tmp/oracle-panel.gpt-5.4.md`; Oracle also writes `/tmp/oracle-panel.oracle.json` with successes, failures, output paths, and provider failure categories.
212
+
174
213
  ## Follow-up and lineage
175
214
 
176
215
  Use `--followup` to continue an existing OpenAI/Azure Responses API run with additional context/files:
@@ -243,7 +282,7 @@ Browser automation can open or control Chrome, so dry-runs and live runs print a
243
282
  | `--followup <sessionId\|responseId>` | Continue an OpenAI/Azure Responses API run from a stored oracle session or `resp_...` response id. |
244
283
  | `--followup-model <model>` | For multi-model OpenAI/Azure parent sessions, choose which model response to continue from. |
245
284
  | `--base-url <url>` | Point API runs at LiteLLM/Azure/OpenRouter/etc. |
246
- | `--chatgpt-url <url>` | Target a ChatGPT workspace/folder (browser). |
285
+ | `--chatgpt-url <url>` | Target a ChatGPT workspace/folder or Temporary Chat URL (browser). |
247
286
  | `--browser-model-strategy <select\|current\|ignore>` | Control ChatGPT model selection in browser mode (current keeps the active model; ignore skips the picker). |
248
287
  | `--browser-manual-login` | Skip cookie copy; reuse a persistent automation profile and wait for manual ChatGPT login. |
249
288
  | `--browser-attach-running` | Reuse your current local browser session through local `DevToolsActivePort` discovery; Oracle opens a dedicated tab instead of launching Chrome (defaults to `127.0.0.1:9222`, or combine with `--remote-chrome <host:port>` to hint a different local endpoint). |
@@ -252,6 +291,8 @@ Browser automation can open or control Chrome, so dry-runs and live runs print a
252
291
  | `--browser-research deep` | Activate ChatGPT Deep Research for broad web research and cited reports (browser only). |
253
292
  | `--browser-follow-up <prompt>` | Browser-only multi-turn consult: submit an additional prompt in the same ChatGPT conversation after the initial answer. Repeat for challenge/revision/final-decision passes. Not supported with Deep Research mode. |
254
293
  | `--browser-archive <auto\|always\|never>` | Archive completed ChatGPT browser conversations after local artifacts are saved. `auto` archives successful one-shot chats only, and skips project, Deep Research, multi-turn, failed, and incomplete sessions. |
294
+ | `--browser-attachments <auto\|never\|always>` | Control browser file delivery: `auto` pastes small text files inline and uploads larger bundles, `never` always pastes inline, and `always` uploads files as ChatGPT attachments. |
295
+ | `--browser-bundle-files`, `--browser-bundle-format <text\|zip>` | Bundle browser uploads into one attachment. `text` keeps the existing single Markdown-style text bundle; `zip` preserves individual file names inside one ZIP upload. |
255
296
  | `--browser-port <port>` | Pin the Chrome DevTools port (WSL/Windows firewall helper). |
256
297
  | `--browser-inline-cookies[(-file)] <payload \| path>` | Supply cookies without Chrome/Keychain (browser). |
257
298
  | `--browser-timeout`, `--browser-input-timeout` | Control overall/browser input timeouts (supports h/m/s/ms). |
@@ -262,12 +303,15 @@ Browser automation can open or control Chrome, so dry-runs and live runs print a
262
303
  | `--browser-max-concurrent-tabs` | Soft limit for simultaneous ChatGPT tabs sharing one manual-login profile (default 3). |
263
304
  | `--render`, `--copy` | Print and/or copy the assembled markdown bundle. |
264
305
  | `--wait` | Block for background API runs (e.g., GPT‑5.1 Pro) instead of detaching. |
265
- | `--timeout <seconds\|auto>` | Overall API deadline (auto = 60m for pro, 120s otherwise). |
306
+ | `--timeout <seconds\|duration\|auto>` | Overall API deadline (auto = 60m for pro, 120s otherwise; durations like `10m` derive HTTP/stale-session timeouts unless overridden). |
266
307
  | `--background`, `--no-background` | Force Responses API background mode (create + retrieve) for API runs. |
267
- | `--http-timeout <ms\|s\|m\|h>` | HTTP client timeout (default 20m). |
308
+ | `--http-timeout <ms\|s\|m\|h>` | Override the HTTP client timeout; if omitted, explicit `--timeout` values are reused for transport. |
268
309
  | `--zombie-timeout <ms\|s\|m\|h>` | Override stale-session cutoff used by `oracle status`. |
269
310
  | `--zombie-last-activity` | Use last log activity to detect stale sessions. |
270
- | `--write-output <path>` | Save only the final answer (multi-model adds `.<model>`). Browser sessions also save transcripts and generated artifacts under `~/.oracle/sessions/<id>/artifacts/`. |
311
+ | `--write-output <path>` | Save only the final answer (multi-model adds `.<model>` and writes `<stem>.oracle.json`). Browser sessions also save transcripts and generated artifacts under `~/.oracle/sessions/<id>/artifacts/`. |
312
+ | `--allow-partial`, `--partial <fail\|ok>` | Multi-model failure policy. Default `fail` exits 1 after printing a structured partial summary; `ok` exits 0 when at least one model succeeds. |
313
+ | `--preflight` | Check redacted provider readiness for requested API model(s), then exit without creating a session. |
314
+ | `--perf-trace`, `--perf-trace-path <path>` | Write startup/first-output timing trace JSON; also accepts `--perf-trace=/tmp/oracle.json`, `ORACLE_PERF_TRACE=1`, or `ORACLE_PERF_TRACE=/tmp/oracle.json`. |
271
315
  | `--files-report` | Print per-file token usage. |
272
316
  | `--dry-run [summary\|json\|full]` | Preview without sending. |
273
317
  | `--remote-host`, `--remote-token` | Use a remote `oracle serve` host (browser). |
@@ -275,6 +319,7 @@ Browser automation can open or control Chrome, so dry-runs and live runs print a
275
319
  | `--youtube <url>` | YouTube video URL to analyze (Gemini browser mode). |
276
320
  | `--generate-image <file>` | Generate image and save to file (Gemini browser mode; ChatGPT browser mode saves downloadable image artifacts when present). Extra ChatGPT images save as numbered siblings. |
277
321
  | `--edit-image <file>` | Edit existing image with `--output` (Gemini browser mode). For ChatGPT browser mode, attach source images with `--file` and use `--generate-image` for the output path. |
322
+ | `--provider openai\|azure\|auto`, `--no-azure`, `--route` | Choose or inspect API provider routing; `openai` / `--no-azure` ignores Azure env/config for the run. |
278
323
  | `--azure-endpoint`, `--azure-deployment`, `--azure-api-version` | Target Azure OpenAI endpoints (picks Azure client automatically). |
279
324
 
280
325
  ## Configuration
@@ -300,11 +345,11 @@ When several agents share one manual-login ChatGPT profile, Oracle coordinates b
300
345
 
301
346
  Advanced flags
302
347
 
303
- | Area | Flags |
304
- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
305
- | Browser | `--browser-manual-login`, `--browser-attach-running`, `--browser-thinking-time`, `--browser-research`, `--browser-follow-up`, `--browser-archive`, `--browser-timeout`, `--browser-input-timeout`, `--browser-recheck-delay`, `--browser-recheck-timeout`, `--browser-reuse-wait`, `--browser-profile-lock-timeout`, `--browser-max-concurrent-tabs`, `--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` |
306
- | Run control | `--background`, `--no-background`, `--http-timeout`, `--zombie-timeout`, `--zombie-last-activity` |
307
- | Azure/OpenAI | `--azure-endpoint`, `--azure-deployment`, `--azure-api-version`, `--base-url` |
348
+ | Area | Flags |
349
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
350
+ | Browser | `--browser-manual-login`, `--browser-attach-running`, `--browser-thinking-time`, `--browser-research`, `--browser-follow-up`, `--browser-archive`, `--browser-timeout`, `--browser-input-timeout`, `--browser-recheck-delay`, `--browser-recheck-timeout`, `--browser-reuse-wait`, `--browser-profile-lock-timeout`, `--browser-max-concurrent-tabs`, `--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-bundle-format`, `--browser-keep-browser`, `--browser-headless`, `--browser-hide-window`, `--browser-no-cookie-sync`, `--browser-allow-cookie-errors`, `--browser-chrome-path`, `--browser-cookie-path`, `--chatgpt-url` |
351
+ | Run control | `--background`, `--no-background`, `--http-timeout`, `--zombie-timeout`, `--zombie-last-activity` |
352
+ | Azure/OpenAI | `--azure-endpoint`, `--azure-deployment`, `--azure-api-version`, `--base-url` |
308
353
 
309
354
  Remote browser example
310
355