pi-oracle 0.6.16 → 0.7.0

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"),

package/extensions/oracle/lib/jobs.ts

@@ -943,7 +943,7 @@ export async function createJob(
     requestSource: input.requestSource,
     selection: input.selection,
     followUpToJobId: input.followUpToJobId,
-    chatUrl: input.followUpToJobId ? input.chatUrl : undefined,
+    chatUrl: input.chatUrl,
     conversationId,
     responseFormat: "text/plain",
     artifactPaths: [],

package/extensions/oracle/lib/runtime.ts

@@ -429,6 +429,15 @@ async function spawnCp(args: string[], options?: { timeoutMs?: number }): Promis
   });
 }
 
+async function removeChromiumProcessSingletonArtifacts(profileDir: string): Promise<void> {
+  await Promise.all([
+    rm(join(profileDir, "SingletonLock"), { force: true }),
+    rm(join(profileDir, "SingletonSocket"), { force: true }),
+    rm(join(profileDir, "SingletonCookie"), { force: true }),
+    rm(join(profileDir, "DevToolsActivePort"), { force: true }),
+  ]);
+}
+
 export async function cloneSeedProfileToRuntime(
   config: OracleConfig,
   runtimeProfileDir: string,
@@ -441,6 +450,7 @@ export async function cloneSeedProfileToRuntime(
     await rm(runtimeProfileDir, { recursive: true, force: true }).catch(() => undefined);
     await mkdir(dirname(runtimeProfileDir), { recursive: true, mode: 0o700 }).catch(() => undefined);
     await spawnCp(profileCloneArgs(config, seedDir, runtimeProfileDir), { timeoutMs: options?.cpTimeoutMs ?? PROFILE_CLONE_TIMEOUT_MS });
+    await removeChromiumProcessSingletonArtifacts(runtimeProfileDir);
   });
 
   return getSeedGeneration(config);