pi-oracle 0.6.17 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.7.1 - 2026-05-18
+
+### Changed
+- updated the local pi development baseline to `@earendil-works/pi-coding-agent` `0.75.3` and refreshed the npm lockfile
+- raised the local Node.js tooling floor and sanity checks to `>=22.19.0`
+- refreshed the `protobufjs` override to `7.5.6` for the current patched dependency graph
+- removed tracked CueLoop runtime state from the repository and ignored local `.cueloop/` artifacts
+
+### Compatibility
+- reviewed current pi `0.75.3` package and extension guidance and confirmed the oracle extension remains compatible with current extension lifecycle and package install/update guidance
+
+
+## 0.7.0 - 2026-05-17
+
+### Added
+- added Grok Heavy as a second oracle provider, with `provider: "grok"`, Grok-only `mode: "heavy"`, `/oracle-auth grok`, separate Grok auth seed profiles, and provider defaults in oracle config
+- added provider-aware `oracle_preflight` support, including explicit Grok checks and follow-up readiness checks that use the prior job's provider
+- added Grok web worker support for auth readiness, Heavy selection, archive upload, prompt submission, response extraction, and same-thread follow-ups
+
+### Changed
+- documented provider selection, Grok's 200 MiB upload ceiling, ChatGPT's 250 MiB ceiling, and same-provider-only follow-up behavior in README, design docs, and prompt templates
+- updated oracle job summaries to report Grok provider/mode selections, not only ChatGPT presets
+
+### Fixed
+- preserved Cloudflare continuity cookies for current ChatGPT verification flows and removed Chromium singleton artifacts when cloning runtime profiles
+- tightened Grok/X cookie import to an explicit auth-cookie allowlist and made Grok jobs fail clearly if a completed response never produces a stable conversation URL
+- improved ChatGPT response extraction fallback behavior when the UI no longer exposes the old `ChatGPT said:` heading structure
+
+### Validation
+- verified Grok Heavy live submission and same-thread Grok follow-up using isolated local-extension `pi` sessions
+- verified a final ChatGPT `instant` live smoke using an isolated local-extension `pi` session before release
+
 ## 0.6.17 - 2026-05-10
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # pi-oracle
 
-`pi-oracle` lets a `pi` agent send hard, long-running work to ChatGPT.com through the web app, with repo archives, background execution, saved results, and a best-effort wake-up back into `pi` when the answer is ready.
+`pi-oracle` lets a `pi` agent send hard, long-running work to ChatGPT.com or Grok through the web app, with repo archives, background execution, saved results, and a best-effort wake-up back into `pi` when the answer is ready.
 
 > Status: experimental public beta. Validated primarily on macOS with Google Chrome/Chromium and `pi` 0.65.0+. Normal oracle jobs run in an isolated browser profile, not your active browser window.
 
@@ -12,47 +12,47 @@ You: /oracle Review the pending changes. Include the whole repo unless a narrowe
 pi-oracle:
   1. preflights local session/auth readiness
   2. builds a context-rich `.tar.zst` repo archive
-  3. starts an isolated ChatGPT web runtime in the background
-  4. uploads the archive and prompt to ChatGPT.com
+  3. starts an isolated provider web runtime in the background
+  4. uploads the archive and prompt to the selected provider
   5. saves the response/artifacts under /tmp/oracle-<job-id>/
   6. sends a best-effort wake-up back to the matching pi session
 
 Later: /oracle-read <job-id>
 ```
 
-What you are seeing: the local `pi` agent keeps control of context selection and safety checks, while ChatGPT web handles the expensive second-opinion work asynchronously. If the wake-up is missed, the result still lives on disk and can be read by job id.
+What you are seeing: the local `pi` agent keeps control of context selection and safety checks, while the selected web provider handles the expensive second-opinion work asynchronously. If the wake-up is missed, the result still lives on disk and can be read by job id.
 
 ## Who this is for
 
-Use `pi-oracle` if you use `pi` and want a larger asynchronous reviewer, planner, or analyst that can use your real ChatGPT web account instead of an API model.
+Use `pi-oracle` if you use `pi` and want a larger asynchronous reviewer, planner, or analyst that can use your real ChatGPT or Grok web account instead of an API model.
 
 It is most useful for:
 
 - maintainers reviewing broad repo changes before shipping
 - agents that need a slower second opinion without blocking the main `pi` turn
 - migration, architecture, or failure-mode analysis that benefits from a large archive
-- follow-up questions that should continue the same ChatGPT thread later
+- follow-up questions that should continue the same provider thread later
 
 Do not use it for:
 
 - short local coding tasks that `pi` can handle directly
-- projects that must never be uploaded to ChatGPT.com
+- projects that must never be uploaded to ChatGPT.com, Grok, or another configured web provider
 - non-macOS environments or machines without the required local browser/tooling
 
 ## Problem it solves
 
-A normal coding-agent turn is the wrong shape for some work: the task may need a large repo snapshot, a slower web model, a real ChatGPT subscription, artifact downloads, or a durable result that arrives after the active turn ends.
+A normal coding-agent turn is the wrong shape for some work: the task may need a large repo snapshot, a slower web model, a real ChatGPT/Grok subscription, artifact downloads, or a durable result that arrives after the active turn ends.
 
-`pi-oracle` makes that workflow explicit and recoverable instead of asking the main agent to manually drive ChatGPT in your real browser window.
+`pi-oracle` makes that workflow explicit and recoverable instead of asking the main agent to manually drive provider chat UIs in your real browser window.
 
 ## What it does
 
 | Problem | Capability | Proof in this repo |
 | --- | --- | --- |
-| Hard tasks need more context than a quick turn should gather. | `/oracle` prompts the agent to preflight, choose a context-rich archive, and submit it to ChatGPT web. | [`prompts/oracle.md`](prompts/oracle.md), `oracle_submit`, archive tests in `scripts/oracle-sanity-*` |
+| Hard tasks need more context than a quick turn should gather. | `/oracle` prompts the agent to preflight, choose a context-rich archive, and submit it to the selected provider web app. | [`prompts/oracle.md`](prompts/oracle.md), `oracle_submit`, archive tests in `scripts/oracle-sanity-*` |
 | Browser automation should not steal focus or mutate your active profile. | Jobs clone an authenticated seed profile into per-job isolated runtime profiles. | [`docs/ORACLE_DESIGN.md`](docs/ORACLE_DESIGN.md), [`extensions/oracle/lib/runtime.ts`](extensions/oracle/lib/runtime.ts) |
 | Long jobs need durability. | Job state, responses, logs, and artifacts persist under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/`. | [`extensions/oracle/lib/jobs.ts`](extensions/oracle/lib/jobs.ts), `/oracle-read`, `/oracle-status` |
-| ChatGPT auth can expire or drift. | `/oracle-auth` refreshes the isolated auth seed from a configured local Chromium profile, with recovery guidance. | [`extensions/oracle/lib/auth.ts`](extensions/oracle/lib/auth.ts), [`docs/ORACLE_RECOVERY_DRILL.md`](docs/ORACLE_RECOVERY_DRILL.md) |
+| Provider auth can expire or drift. | `/oracle-auth [chatgpt|grok]` refreshes the isolated auth seed from a configured local Chromium profile, with recovery guidance. | [`extensions/oracle/lib/auth.ts`](extensions/oracle/lib/auth.ts), [`docs/ORACLE_RECOVERY_DRILL.md`](docs/ORACLE_RECOVERY_DRILL.md) |
 | Agents need a simple API, not UI-driving instructions. | The package exposes agent-facing tools: `oracle_preflight`, `oracle_submit`, `oracle_read`, `oracle_auth`, and `oracle_cancel`. | [`extensions/oracle/lib/tools.ts`](extensions/oracle/lib/tools.ts) |
 
 ## Fastest way to see it work
@@ -79,17 +79,17 @@ You need:
 - Node.js 22 or newer
 - `pi` 0.65.0 or newer
 - Google Chrome or another Chromium-family browser
-- ChatGPT already signed in to the configured local browser profile
+- ChatGPT or Grok already signed in to the configured local browser profile for the provider you plan to use
 - `agent-browser`, `tar`, and `zstd` available on the machine
 - a normal persisted `pi` session, not `pi --no-session`
 
-### 3. Sync ChatGPT auth once
+### 3. Sync provider auth once
 
 ```text
 /oracle-auth
 ```
 
-This reads ChatGPT cookies from your configured local browser profile and writes an isolated oracle seed profile. It should not automate your active browser window for normal jobs.
+This reads cookies for the configured default provider from your local browser profile and writes an isolated oracle seed profile. Use `/oracle-auth grok` to force-refresh the Grok seed when your default provider is still ChatGPT. It should not automate your active browser window for normal jobs.
 
 ### 4. Submit a tiny job
 
@@ -100,10 +100,10 @@ This reads ChatGPT cookies from your configured local browser profile and writes
 Expected result:
 
 - The `/oracle` prompt now runs an early oracle preflight before expensive repo reading or archive creation.
-- The agent chooses a context-rich relevant archive up to the 250 MB ceiling, not the smallest possible one-file slice when nearby context helps.
+- The agent chooses a context-rich relevant archive up to the selected provider's upload ceiling, not the smallest possible one-file slice when nearby context helps.
 - `oracle_submit` creates or queues a job.
 - If local packing is too large, the prompt treats that as a retryable archive-selection failure and narrows automatically before surfacing the problem.
-- The job uploads a repo archive to ChatGPT.com, capped at 250 MiB after default exclusions/pruning.
+- The job uploads a repo archive to the selected provider, capped at 250 MiB for ChatGPT or 200 MiB for Grok after default exclusions/pruning.
 - The response is saved under `/tmp/oracle-<job-id>/response.md` by default.
 - The matching `pi` session gets one best-effort wake-up when the job finishes.
 
@@ -140,7 +140,7 @@ flowchart LR
     B --> C["Agent chooses context-rich archive inputs"]
     C --> D["oracle_submit builds .tar.zst archive"]
     D --> E["Detached worker clones isolated auth seed profile"]
-    E --> F["ChatGPT web receives archive + prompt"]
+    E --> F["Selected provider receives archive + prompt"]
     F --> G["Response/artifacts saved under oracle job dir"]
     G --> H["Best-effort wake-up to matching pi session"]
 ```
@@ -150,16 +150,16 @@ Key design choices:
 - **Prompt templates own context gathering.** `/oracle` and `/oracle-followup` tell the agent how to preflight, gather context, choose archive inputs, and then stop after dispatch.
 - **Tools own execution.** `oracle_submit` builds the archive, admits or queues the job, starts the worker, and returns immediately.
 - **Auth uses a seed profile.** `/oracle-auth` imports cookies into an isolated seed profile; each job clones that seed into its own temporary runtime profile.
-- **Follow-ups preserve ChatGPT thread state.** `/oracle-followup <job-id> ...` resolves the prior job's saved ChatGPT URL and submits the next prompt with `followUpJobId`.
+- **Follow-ups preserve provider thread state.** `/oracle-followup <job-id> ...` resolves the prior job's saved provider URL and submits the next prompt with `followUpJobId`.
 - **Wake-up is best effort, storage is durable.** A missed wake-up does not lose the result.
 
 ## Commands and tools
 
 User-facing commands:
 
-- `/oracle <request>` — prepare context and dispatch a ChatGPT web oracle job
-- `/oracle-followup <job-id> <request>` — continue an earlier oracle job in the same ChatGPT thread
-- `/oracle-auth` — sync ChatGPT cookies into the isolated oracle auth seed profile
+- `/oracle <request>` — prepare context and dispatch a ChatGPT or Grok web oracle job
+- `/oracle-followup <job-id> <request>` — continue an earlier oracle job in the same provider thread
+- `/oracle-auth [chatgpt|grok]` — sync provider cookies into the isolated oracle auth seed profile
 - `/oracle-read [job-id]` — inspect job status and saved response preview
 - `/oracle-status [job-id]` — inspect a job or list recent job ids when no explicit id is given
 - `/oracle-cancel <job-id>` — cancel a queued or active job
@@ -175,14 +175,16 @@ Agent-facing tools:
 
 ## Configuration
 
-Most users can start with defaults. Set an agent-level config only when you need a non-default preset or browser profile.
+Most users can start with defaults. Set an agent-level config only when you need a non-default provider, mode, preset, or browser profile.
 
 `~/.pi/agent/extensions/oracle.json`
 
 ```json
 {
   "defaults": {
-    "preset": "<preset id from ORACLE_SUBMIT_PRESETS>"
+    "provider": "chatgpt",
+    "preset": "<preset id from ORACLE_SUBMIT_PRESETS>",
+    "grokMode": "heavy"
   },
   "auth": {
     "chromeProfile": "Default"
@@ -192,10 +194,12 @@ Most users can start with defaults. Set an agent-level config only when you need
 
 Notes:
 
+- `defaults.provider` is the default web provider: `chatgpt` or `grok`.
 - `defaults.preset` is the default ChatGPT model preset for oracle jobs.
-- The canonical preset ids live in [`extensions/oracle/lib/config.ts`](extensions/oracle/lib/config.ts).
-- If the packaged default is fine, omit `defaults.preset`.
-- When an agent is unsure which oracle preset fits, it should omit `preset` and use the configured default model instead of asking by default.
+- `defaults.grokMode` is the default Grok mode. Only `heavy` is supported today.
+- The canonical preset ids and provider modes live in [`extensions/oracle/lib/config.ts`](extensions/oracle/lib/config.ts).
+- If the packaged default is fine, omit `defaults`.
+- When an agent is unsure which oracle preset fits, it should omit `preset` and use the configured default model instead of asking by default. If the prompt says to use Grok, it should pass `provider: "grok"` to `oracle_submit`.
 - You usually do not need browser paths unless auto-detection fails.
 
 ### Custom Chromium cookie sources
@@ -204,7 +208,7 @@ Use this only for a Chromium-family browser that the default cookie importer can
 
 Before running `/oracle-auth` with this path:
 
-1. Log into ChatGPT in the target browser profile.
+1. Log into ChatGPT or Grok in the target browser profile, depending on `defaults.provider`.
 2. Fully quit the browser so its `Cookies` database is stable.
 3. Find the profile `Cookies` SQLite DB path.
 4. Find the browser's macOS Keychain safe-storage item account and service name.
@@ -231,7 +235,16 @@ Example Helium config:
 
 `auth.chromeCookiePath` must be paired with `auth.chromiumKeychain`; partial config is rejected so oracle does not silently fall back to another browser source.
 
-## Available presets
+## Available providers and presets
+
+| Provider | Mode / preset | Upload ceiling |
+| --- | --- | --- |
+| ChatGPT | Presets below | 250 MiB |
+| Grok | `heavy` only | 200 MiB |
+
+Grok accepts the same `.tar.zst` archives that pi-oracle builds. Manual testing against `https://grok.com` found a 200 MiB file is accepted and a 200 MiB + 1 byte file is rejected, so pi-oracle caps Grok archives at 200 MiB.
+
+## Available ChatGPT presets
 
 | Preset id | Description |
 | --- | --- |
@@ -244,7 +257,7 @@ Example Helium config:
 | `instant` | Instant |
 | `instant_auto_switch` | Instant - Auto-switch to Thinking Enabled |
 
-`oracle_submit` accepts canonical preset ids or a matching human-readable preset label. Keep config values on canonical ids.
+For ChatGPT, `oracle_submit` accepts canonical preset ids or a matching human-readable preset label. Keep config values on canonical ids. For Grok, use `provider: "grok"`; only Heavy is supported today.
 
 ## Outputs and cleanup
 
@@ -258,8 +271,8 @@ Example Helium config:
 
 This extension is local-first, but it handles sensitive local and project data:
 
-- `/oracle-auth` reads ChatGPT cookies from the configured local browser profile.
-- `oracle_submit` uploads selected project archives to ChatGPT.com.
+- `/oracle-auth` reads provider cookies from the configured local browser profile. Use `/oracle-auth grok` for Grok when ChatGPT remains the default provider.
+- `oracle_submit` uploads selected project archives to the selected provider web app.
 - Responses, logs, and artifacts are written to the configured oracle jobs directory.
 
 Review the code and design docs before using it with private or regulated material.
@@ -267,9 +280,9 @@ Review the code and design docs before using it with private or regulated materi
 ## Current limits
 
 - Experimental public beta, validated primarily on macOS.
-- ChatGPT UI, auth, model controls, and artifact download behavior can drift.
-- Archive uploads are capped at 250 MiB after default exclusions and automatic whole-repo pruning.
-- A real ChatGPT web session is required.
+- Provider UI, auth, model controls, and artifact download behavior can drift.
+- Archive uploads are capped at 250 MiB for ChatGPT and 200 MiB for Grok after default exclusions and automatic whole-repo pruning.
+- A real ChatGPT or Grok web session is required for the provider you use.
 - The README currently uses command-level proof and design docs; no public screenshot or demo GIF is checked into the repo.
 - Production hardening should keep focusing on UI drift detection, auth recovery, artifact capture, and environment diagnostics.
 
@@ -277,18 +290,18 @@ Review the code and design docs before using it with private or regulated materi
 
 ### `/oracle-auth` fails or says login is required
 
-- Make sure ChatGPT works in the same local browser profile you configured.
+- Make sure the selected provider works in the same local browser profile you configured.
 - For custom Chromium cookie sources, confirm `auth.chromeCookiePath` points at that profile's `Cookies` DB and `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service.
 - Re-run `/oracle-auth`.
 - Agent callers can use `oracle_auth({})` once before retrying a stale-auth oracle submission.
-- If ChatGPT is half-logged-in or challenge flow state looks weird, finish the login/challenge in the headed auth browser and retry.
+- If the provider is half-logged-in or challenge flow state looks weird, finish the login/challenge in the headed auth browser and retry.
 
 ### Custom Chromium auth says cookies synced but the session is rejected
 
-This usually means the cookie import worked but the source cookies are not the active ChatGPT session you expected.
+This usually means the cookie import worked but the source cookies are not the active provider session you expected.
 
 1. Open the configured browser profile.
-2. Confirm ChatGPT works there without logging in again.
+2. Confirm the selected provider works there without logging in again.
 3. Quit the browser fully so its `Cookies` DB is stable.
 4. Confirm `auth.chromeCookiePath` points at that exact profile's `Cookies` DB.
 5. Confirm `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service for that DB.
@@ -355,7 +368,7 @@ For end-to-end local-extension smoke testing, use [`docs/ORACLE_ISOLATED_PI_VALI
 | --- | --- |
 | [`extensions/oracle/index.ts`](extensions/oracle/index.ts) | Extension entrypoint |
 | `extensions/oracle/lib/` | Commands, tools, config, jobs, queueing, runtime, poller |
-| `extensions/oracle/worker/` | Detached ChatGPT web worker and UI/auth helpers |
+| `extensions/oracle/worker/` | Detached provider web worker and UI/auth helpers |
 | `extensions/oracle/shared/` | Shared process, state, job, and observability helpers |
 | [`prompts/oracle.md`](prompts/oracle.md) | `/oracle` prompt-template workflow |
 | [`prompts/oracle-followup.md`](prompts/oracle-followup.md) | `/oracle-followup` prompt-template workflow |

package/docs/ORACLE_DESIGN.md

@@ -12,7 +12,7 @@ Compatibility target:
 
 ## Goal
 
-Create a `pi` extension that lets the user or agent consult ChatGPT.com through the web product instead of the API, with:
+Create a `pi` extension that lets the user or agent consult ChatGPT.com or Grok through the web product instead of the API, with:
 
 - manual invocation via `/oracle ...`
 - automatic invocation by the agent in rare high-difficulty cases
@@ -34,7 +34,7 @@ The production architecture is now:
 - clone that seed into a **per-job runtime profile** for each oracle run
 - launch each job in its own **runtime browser session**
 - persist same-thread continuity by saved `chatUrl`, not by keeping tabs or browsers alive
-- allow parallel jobs only when they do not target the same ChatGPT conversation
+- allow parallel jobs only when they do not target the same provider conversation
 
 ## Rejected production path
 
@@ -67,13 +67,13 @@ The extension now follows the current `pi` session lifecycle model:
   - intentionally uses native pi prompt/template queueing so submissions survive streaming and compaction
 - `/oracle-followup <job-id> <request>`
   - implemented as a prompt template, not an extension command
-  - asks the agent to continue an earlier oracle job in the same ChatGPT thread via `followUpJobId`
+  - asks the agent to continue an earlier oracle job in the same provider thread via `followUpJobId`
   - keeps same-thread continuation available to normal users without requiring raw tool-call syntax
 
 ### Commands
 
-- `/oracle-auth`
-  - syncs ChatGPT cookies from the configured local browser profile into the isolated oracle profile and verifies them there
+- `/oracle-auth [chatgpt|grok]`
+  - syncs ChatGPT or Grok cookies from the configured local browser profile into the isolated oracle profile and verifies them there, based on the configured default provider or explicit command argument
 - `/oracle-read [job-id]`
   - shows job status plus the saved response preview
 - `/oracle-status [job-id]`
@@ -87,13 +87,14 @@ The extension now follows the current `pi` session lifecycle model:
 
 - `oracle_preflight`
   - lightweight agent-facing readiness check for persisted-session and local oracle prerequisites
+  - accepts optional `provider` and `followUpJobId` so readiness checks use the same auth seed/provider that submission will use
   - intended to run before expensive `/oracle` context gathering
 - `oracle_auth`
   - agent-facing auth refresh tool that mirrors `/oracle-auth` for stale-auth recovery before a retry
 - `oracle_submit`
   - low-level agent-facing dispatch tool
   - creates archive and launches a detached worker
-  - supports optional `followUpJobId` to continue the same ChatGPT thread by persisted URL
+  - supports optional `followUpJobId` to continue the same provider thread by persisted URL
 - `oracle_read`
   - reads job status and outputs
 - `oracle_cancel`
@@ -103,16 +104,16 @@ The extension now follows the current `pi` session lifecycle model:
 
 ### `/oracle ...`
 
-`/oracle <request>` should not directly drive ChatGPT.
+`/oracle <request>` should not directly drive ChatGPT or Grok.
 It expands through the prompt-template path so pi can apply its native queueing semantics before the agent starts work.
 
 Instead it instructs the agent to:
 
-1. call `oracle_preflight` immediately
+1. call `oracle_preflight` immediately, passing `provider: "grok"` when the user explicitly asks for Grok
 2. stop right away if preflight reports the session or local oracle setup is not ready
 3. understand whether the request is explicitly narrow or genuinely broad
-4. if the immediately preceding oracle run failed because ChatGPT login is required or the worker explicitly said to rerun `/oracle-auth`, call `oracle_auth` once before retrying
-5. gather enough repo context to submit well and bias toward context-rich archives when they fit within the 250 MB ceiling
+4. if the immediately preceding oracle run failed because ChatGPT or Grok login is required or the worker explicitly said to rerun `/oracle-auth`, call `oracle_auth` once before retrying
+5. gather enough repo context to submit well and bias toward context-rich archives when they fit within the provider ceiling: 250 MB for ChatGPT and 200 MiB for Grok
 6. if the request is narrow, start from the directly relevant area but still include nearby tests, docs, config, and adjacent modules when they may improve answer quality
 7. if the request is broad/repo-wide, gather broader context and usually archive `.`
 8. if `oracle_submit` fails before dispatch with an `archive_too_large` / upload-limit error, treat that as retryable: use the reported size summary plus any auto-pruned paths to cut scope and retry automatically with a smaller archive
@@ -127,7 +128,7 @@ Auth bootstrap flow:
 
 1. load oracle config
 2. acquire the global auth-maintenance lock
-3. read ChatGPT cookies directly from the configured local browser cookie store in read-only mode
+3. read ChatGPT or Grok cookies directly from the configured local browser cookie store in read-only mode, depending on `defaults.provider`
    - configurable source profile / cookie DB path
    - optional configured Chromium Keychain source for browsers outside the default importer
    - no launch or mutation of the real browser profile
@@ -137,23 +138,23 @@ Auth bootstrap flow:
    - dedicated auth `--session`
    - dedicated staged seed `--profile`
    - configured executable path / user agent / launch args if set
-7. clear isolated browser cookies and seed the staged profile with imported ChatGPT cookies
-8. open ChatGPT in the isolated browser
-9. verify auth with `/backend-api/me` plus ChatGPT UI readiness checks
+7. clear isolated browser cookies and seed the staged profile with imported provider cookies
+8. open the configured provider in the isolated browser
+9. verify auth with provider-specific readiness checks
 10. on success, close the isolated browser so Chrome flushes profile state cleanly
 11. atomically swap the staged profile into `browser.authSeedProfileDir`, keeping `*.prev` as rollback
 12. write a seed-generation marker used by future runtime clones
-13. if ChatGPT presents a challenge page, leave the staged auth browser/profile open for the user to solve and reuse
+13. if the provider presents a challenge page, leave the staged auth browser/profile open for the user to solve and reuse
 
-This keeps production oracle jobs off the user’s real Chrome while using the user’s existing authenticated ChatGPT cookies as the bootstrap source.
+This keeps production oracle jobs off the user’s real Chrome while using the user’s existing authenticated provider cookies as the bootstrap source.
 
 The authenticated seed profile remains the source of truth for future oracle runtimes.
 
 ### `oracle_submit`
 
-Agent-facing submissions use **`preset`**; the canonical registry is `ORACLE_SUBMIT_PRESETS` in `extensions/oracle/lib/config.ts`. **`preset` is the only model-selection parameter** on `oracle_submit`. There are no `modelFamily`, `effort`, or `autoSwitchToThinking` fields. Submit-time inputs accept canonical preset ids plus matching human-readable labels/common hyphen-space variants, and the tool normalizes them back to the canonical id before persisting job state. Prompt-template guidance biases toward omitting `preset` and using the configured default unless the task clearly needs a different model or the user explicitly asked for one. It also biases toward context-rich archives up to the 250 MB ceiling, narrowing only when the user explicitly asks for a tight archive, privacy/sensitivity requires it, or size pressure forces it. When local archive creation still exceeds that ceiling after default exclusions and whole-repo auto-pruning, prompt guidance now treats the failure as a retryable archive-selection miss rather than a terminal dead end: agents should cut scope automatically, retry once or twice, and only surface the cut decisions if the archive still cannot fit.
+Agent-facing submissions resolve a provider first. ChatGPT submissions use **`preset`**; the canonical registry is `ORACLE_SUBMIT_PRESETS` in `extensions/oracle/lib/config.ts`. Grok submissions use **`mode: "heavy"`** today and reject ChatGPT-only presets. For ChatGPT, **`preset` is the only model-selection parameter** on `oracle_submit`; there are no `modelFamily`, `effort`, or `autoSwitchToThinking` fields. Submit-time inputs accept canonical preset ids plus matching human-readable labels/common hyphen-space variants, and the tool normalizes them back to the canonical id before persisting job state. Prompt-template guidance biases toward omitting provider/model fields and using configured defaults unless the task or user explicitly asks for one. It also biases toward context-rich archives up to the provider ceiling, narrowing only when the user explicitly asks for a tight archive, privacy/sensitivity requires it, or size pressure forces it. When local archive creation still exceeds that ceiling after default exclusions and whole-repo auto-pruning, prompt guidance now treats the failure as a retryable archive-selection miss rather than a terminal dead end: agents should cut scope automatically, retry once or twice, and only surface the cut decisions if the archive still cannot fit.
 
-1. resolve the preset (submit-time or config default) into an execution snapshot
+1. resolve the provider and preset/mode (submit-time or config default) into an execution snapshot
 2. resolve optional `followUpJobId` into a prior `chatUrl` and `conversationId`
 3. build the archive first into a temporary path
 4. allocate a unique runtime:
@@ -182,13 +183,13 @@ Per job:
    - headless by default
 3. open either:
    - the saved `chatUrl` for follow-up jobs, or
-   - the configured default ChatGPT URL
+   - the configured provider URL
 4. classify page state before touching the UI
 5. fail fast on:
    - login required
    - challenge/verification page
    - transient outage after one retry
-6. configure model family / effort
+6. configure ChatGPT model family/effort or Grok Heavy
 7. upload archive
 8. wait for upload confirmation scoped to the active composer
 9. fill prompt
@@ -205,7 +206,7 @@ Per job:
 
 Default and recommended:
 
-- auth seed via `--profile <authSeedProfileDir>` for durable ChatGPT authentication state
+- auth seed via `--profile <authSeedProfileDir>` for durable provider authentication state
 - per-job runtime via unique `--session <runtimeSessionName>` + unique `--profile <runtimeProfileDir>`
 
 Not the default:
@@ -236,7 +237,9 @@ Browser/auth settings are global-only because they control local privileged brow
 ```json
 {
   "defaults": {
-    "preset": "<preset id from ORACLE_SUBMIT_PRESETS>"
+    "provider": "chatgpt",
+    "preset": "<preset id from ORACLE_SUBMIT_PRESETS>",
+    "grokMode": "heavy"
   },
   "browser": {
     "sessionPrefix": "oracle",
@@ -287,11 +290,11 @@ When both `auth.chromeCookiePath` and `auth.chromiumKeychain` are present, auth
 2. snapshots the Chromium `Cookies` DB plus `Cookies-wal` / `Cookies-shm` sidecars, tolerating sidecars that disappear while the browser is closing
 3. decrypts Chromium AES-CBC cookie values, including Chromium v24+ host-hash-prefixed values
 4. dedupes duplicate cookie rows by keeping the first row after newest-expiry ordering
-5. filters importable ChatGPT auth cookies and seeds the isolated oracle auth profile
+5. filters importable provider auth cookies and seeds the isolated oracle auth profile
 
 Operational requirements for this path:
 
-- ChatGPT must already be logged in in the configured browser profile.
+- ChatGPT or Grok must already be logged in in the configured browser profile, depending on the provider being synced.
 - The target browser should be fully quit before `/oracle-auth` so the cookie DB snapshot is stable.
 - The configured Keychain item must be accessible to the current macOS user; allow Keychain access if prompted.
 - `browser.executablePath` should point at the same Chromium-family browser so the headed auth/bootstrap browser uses the intended app.
@@ -357,7 +360,7 @@ Important fields include:
 - `sessionId`
 - `originSessionFile`
 - `requestSource`
-- `selection`: resolved execution snapshot with `{ preset, modelFamily, effort?, autoSwitchToThinking }`
+- `selection`: resolved execution snapshot with `{ provider, preset?, mode?, modelFamily, effort?, autoSwitchToThinking }`
 - `followUpToJobId`
 - `chatUrl`
 - `conversationId`
@@ -488,7 +491,7 @@ Same-thread continuity is persisted as data, not runtime browser state.
 
 Approach:
 
-- expose `/oracle-followup <job-id> <request>` as the user-facing way to continue the same ChatGPT thread later
+- expose `/oracle-followup <job-id> <request>` as the user-facing way to continue the same provider thread later
 - store `chatUrl` only after the conversation URL stabilizes
 - derive and persist `conversationId` from that URL when possible
 - for a follow-up job, resolve `followUpJobId` to the prior `chatUrl`

package/extensions/oracle/lib/auth.ts

@@ -4,12 +4,13 @@
 // Usage: Imported by oracle commands and tools whenever the shared oracle auth seed profile must be refreshed.
 // Invariants/Assumptions: Auth bootstrap runs under the global reconcile lock when available, uses the effective oracle config for the current workspace root, and returns the worker's stdout/stderr message verbatim on success or failure.
 import { spawn } from "node:child_process";
-import { formatOracleAuthConfigRemediation, formatOracleAuthConfigSummary, getOracleConfigLoadDetails, loadOracleConfig } from "./config.js";
+import { formatOracleAuthConfigRemediation, formatOracleAuthConfigSummary, getOracleConfigLoadDetails, loadOracleConfig, resolveOracleConfigForProvider, type OracleProvider } from "./config.js";
 import { pruneTerminalOracleJobs, reconcileStaleOracleJobs } from "./jobs.js";
 import { isLockTimeoutError, withGlobalReconcileLock } from "./locks.js";
 
-export async function runOracleAuthBootstrap(authWorkerPath: string, cwd: string): Promise<string> {
-  const config = loadOracleConfig(cwd);
+export async function runOracleAuthBootstrap(authWorkerPath: string, cwd: string, provider?: OracleProvider): Promise<string> {
+  const baseConfig = loadOracleConfig(cwd);
+  const config = resolveOracleConfigForProvider(baseConfig, provider ?? baseConfig.defaults.provider);
   const configLoad = getOracleConfigLoadDetails(cwd);
   const authConfigGuidance = {
     ...configLoad,

package/extensions/oracle/lib/commands.ts

@@ -8,6 +8,7 @@ import { readFile } from "node:fs/promises";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { formatOracleCancelOutcome, formatOracleJobSummary } from "../shared/job-observability-helpers.mjs";
 import { runOracleAuthBootstrap } from "./auth.js";
+import type { OracleProvider } from "./config.js";
 import {
   cancelOracleJob,
   getJobDir,
@@ -65,13 +66,23 @@ function readScopedJob(jobId: string, cwd: string) {
   return job;
 }
 
+function parseOracleAuthProvider(args: string): OracleProvider | undefined {
+  const value = args.trim().toLowerCase();
+  if (!value) return undefined;
+  if (value === "chatgpt" || value === "chat-gpt" || value === "openai") return "chatgpt";
+  if (value === "grok" || value === "xai" || value === "x.ai") return "grok";
+  throw new Error("Usage: /oracle-auth [chatgpt|grok]");
+}
+
 export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string, workerPath: string): void {
   pi.registerCommand("oracle-auth", {
-    description: "Sync ChatGPT cookies from the configured local browser profile into the oracle auth seed profile",
-    handler: async (_args, ctx) => {
-      ctx.ui.notify("Syncing ChatGPT cookies from the configured local browser profile into the oracle auth seed profile…", "info");
+    description: "Sync ChatGPT or Grok cookies from the configured local browser profile into the provider auth seed profile",
+    handler: async (args, ctx) => {
       try {
-        const result = await runOracleAuthBootstrap(authWorkerPath, ctx.cwd);
+        const provider = parseOracleAuthProvider(args);
+        const providerLabel = provider === "grok" ? "Grok" : provider === "chatgpt" ? "ChatGPT" : "configured provider";
+        ctx.ui.notify(`Syncing ${providerLabel} cookies from the configured local browser profile into the oracle auth seed profile…`, "info");
+        const result = await runOracleAuthBootstrap(authWorkerPath, ctx.cwd, provider);
         ctx.ui.notify(result, "info");
       } catch (error) {
         ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");

package/extensions/oracle/lib/config.ts

@@ -10,12 +10,18 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { isAbsolute, join, normalize } from "node:path";
 import { getProjectId } from "./runtime.js";
 
-export const MODEL_FAMILIES = ["instant", "thinking", "pro"] as const;
+export const ORACLE_PROVIDERS = ["chatgpt", "grok"] as const;
+export type OracleProvider = (typeof ORACLE_PROVIDERS)[number];
+
+export const MODEL_FAMILIES = ["instant", "thinking", "pro", "grok"] as const;
 export type OracleModelFamily = (typeof MODEL_FAMILIES)[number];
 
 export const EFFORTS = ["light", "standard", "extended", "heavy"] as const;
 export type OracleEffort = (typeof EFFORTS)[number];
 
+export const GROK_MODES = ["heavy"] as const;
+export type OracleGrokMode = (typeof GROK_MODES)[number];
+
 /**
  * Canonical preset registry for `oracle_submit` preset selection.
  * This is the single authored source of truth — all derived lists come from `Object.keys(...)`.
@@ -156,7 +162,9 @@ export function getOracleSubmitPresetById(id: OracleSubmitPresetId): OracleSubmi
 
 /** Resolved execution snapshot generated from a preset at submit time. */
 export type OracleResolvedSelection = {
-  preset: OracleSubmitPresetId;
+  provider: OracleProvider;
+  preset?: OracleSubmitPresetId;
+  mode?: OracleGrokMode;
   modelFamily: OracleModelFamily;
   effort?: OracleEffort;
   autoSwitchToThinking: boolean;
@@ -169,6 +177,7 @@ export type OracleResolvedSelection = {
 export function resolveOracleSubmitPreset(presetId: OracleSubmitPresetId): OracleResolvedSelection {
   const def = getOracleSubmitPresetById(presetId);
   return {
+    provider: "chatgpt",
     preset: presetId,
     modelFamily: def.modelFamily,
     effort: def.modelFamily === "instant" ? undefined : def.effort,
@@ -176,6 +185,37 @@ export function resolveOracleSubmitPreset(presetId: OracleSubmitPresetId): Oracl
   };
 }
 
+export function resolveOracleGrokMode(mode: OracleGrokMode): OracleResolvedSelection {
+  return {
+    provider: "grok",
+    mode,
+    modelFamily: "grok",
+    effort: "heavy",
+    autoSwitchToThinking: false,
+  };
+}
+
+export function getProviderAuthSeedProfileDir(config: OracleConfig, provider: OracleProvider): string {
+  return provider === "grok" ? `${config.browser.authSeedProfileDir}-grok` : config.browser.authSeedProfileDir;
+}
+
+export function resolveOracleConfigForProvider(config: OracleConfig, provider: OracleProvider): OracleConfig {
+  if (provider === "chatgpt") return config;
+  return {
+    ...config,
+    defaults: {
+      ...config.defaults,
+      provider,
+    },
+    browser: {
+      ...config.browser,
+      authSeedProfileDir: getProviderAuthSeedProfileDir(config, provider),
+      chatUrl: "https://grok.com/",
+      authUrl: "https://grok.com/",
+    },
+  };
+}
+
 export const BROWSER_RUN_MODES = ["headless", "headed"] as const;
 export type OracleBrowserRunMode = (typeof BROWSER_RUN_MODES)[number];
 
@@ -189,7 +229,9 @@ const DEFAULT_MAC_CHROME_USER_DATA_DIR = join(homedir(), "Library", "Application
 
 export interface OracleConfig {
   defaults: {
+    provider: OracleProvider;
     preset: OracleSubmitPresetId;
+    grokMode: OracleGrokMode;
   };
   browser: {
     sessionPrefix: string;
@@ -316,7 +358,9 @@ export function formatOracleAuthConfigSummary(details: OracleConfigLoadDetails):
 
 export const DEFAULT_CONFIG: OracleConfig = {
   defaults: {
+    provider: "chatgpt",
     preset: "pro_extended",
+    grokMode: "heavy",
   },
   browser: {
     sessionPrefix: "oracle",
@@ -529,7 +573,9 @@ function validateOracleConfig(value: unknown): OracleConfig {
   const root = normalizeLegacyBrowserConfig(expectObject(value, "root"));
 
   const defaults = expectObject(root.defaults, "defaults");
+  const provider = expectEnum(defaults.provider, "defaults.provider", ORACLE_PROVIDERS);
   const preset = expectEnum(defaults.preset, "defaults.preset", PRESET_IDS);
+  const grokMode = expectEnum(defaults.grokMode, "defaults.grokMode", GROK_MODES);
 
   const browser = expectObject(root.browser, "browser");
   const auth = expectObject(root.auth, "auth");
@@ -552,7 +598,9 @@ function validateOracleConfig(value: unknown): OracleConfig {
 
   return {
     defaults: {
+      provider,
       preset,
+      grokMode,
     },
     browser: {
       sessionPrefix: expectString(browser.sessionPrefix, "browser.sessionPrefix"),