pi-oracle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitch Fultz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# pi-oracle
+
+`pi-oracle` is a `pi` extension that lets the agent use ChatGPT.com as a long-running web oracle instead of using the API.
+
+It exists for the hard cases where you want:
+- the user’s real ChatGPT account
+- web-model behavior instead of API usage
+- large project-context uploads
+- async background execution that wakes the originating `pi` session when done
+
+Normal oracle jobs run in an isolated browser profile, not in the user’s active Chrome window.
+
+Status: experimental public beta, validated primarily on macOS.
+
+## What it does
+
+The extension adds:
+- `/oracle <request>`
+- `/oracle-auth`
+- `/oracle-status [job-id]`
+- `/oracle-cancel [job-id]`
+- `/oracle-clean <job-id|all>`
+- `oracle_submit`
+- `oracle_read`
+- `oracle_cancel`
+
+An oracle job:
+1. gathers a project archive
+2. opens ChatGPT in an isolated runtime profile
+3. uploads the archive and sends the prompt
+4. waits in the background
+5. persists the response and any artifacts under `/tmp/oracle-<job-id>/`
+6. wakes the originating `pi` session on completion
+
+## Why this exists
+
+The goal is to get strong ChatGPT web-model answers without:
+- paying API costs for every long review
+- blocking the agent for 10–90 minutes
+- stealing focus from the user’s active browser session
+
+## Current scope
+
+Currently validated for:
+- macOS
+- local Google Chrome
+- local ChatGPT web login in Chrome
+- isolated auth seed profile + per-job runtime profile clones
+- concurrent jobs across different projects/sessions
+- same-conversation exclusion for follow-ups
+- plain-text responses
+- artifact capture, including multi-artifact runs
+
+Not promised yet:
+- cross-platform support
+- immunity to future ChatGPT UI changes
+- fully polished partial-artifact terminal semantics
+
+## Requirements
+
+- macOS
+- Google Chrome installed
+- ChatGPT already signed into a local Chrome profile
+- `pi` installed
+- `agent-browser` available on the machine
+- `tar` and `zstd` available
+
+## Install
+
+Planned npm install path once published:
+
+```bash
+pi install npm:pi-oracle
+```
+
+Current GitHub install path:
+
+```bash
+pi install https://github.com/fitchmultz/pi-oracle
+```
+
+## First-time setup
+
+1. Make sure ChatGPT already works in your local Chrome profile.
+2. Configure the oracle if needed via `~/.pi/agent/extensions/oracle.json`.
+3. Run `/oracle-auth`.
+4. Run a tiny `/oracle` smoke test.
+
+## Configuration
+
+Config files:
+- global: `~/.pi/agent/extensions/oracle.json`
+- project: `.pi/extensions/oracle.json`
+
+Common settings:
+- `browser.args`
+- `browser.executablePath`
+- `browser.authSeedProfileDir`
+- `browser.runtimeProfilesDir`
+- `auth.chromeProfile`
+- `auth.chromeCookiePath`
+
+Project config should only override safe, non-privileged settings.
+
+Detailed design and maintainer docs:
+- `docs/ORACLE_DESIGN.md`
+- `docs/ORACLE_RECOVERY_DRILL.md`
+
+## Privacy / local data
+
+This extension is local-first, but it does read and persist local data:
+- `/oracle-auth` reads ChatGPT cookies from a local Chrome profile
+- job archives are uploaded to ChatGPT.com
+- responses and artifacts are written under `/tmp/oracle-<job-id>/`
+
+Review the code and design docs before using it with sensitive material.
+
+## Validation helpers
+
+```bash
+npm run check:oracle-extension
+npm run sanity:oracle
+npm run pack:check
+```
+
+## Beta caveats
+
+The highest-risk areas to monitor are:
+- ChatGPT UI drift
+- auth/bootstrap drift
+- artifact download behavior
+- local environment assumptions
+
+## License
+
+MIT. See `LICENSE`.

package/extensions/oracle/index.ts

@@ -0,0 +1,46 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { loadOracleConfig } from "./lib/config.js";
+import { registerOracleCommands } from "./lib/commands.js";
+import { refreshOracleStatus, startPoller, stopPoller, stopPollerForSession } from "./lib/poller.js";
+import { registerOracleTools } from "./lib/tools.js";
+
+export default function oracleExtension(pi: ExtensionAPI) {
+  const extensionDir = dirname(fileURLToPath(import.meta.url));
+  const workerPath = join(extensionDir, "worker", "run-job.mjs");
+  const authWorkerPath = join(extensionDir, "worker", "auth-bootstrap.mjs");
+
+  registerOracleCommands(pi, authWorkerPath);
+  registerOracleTools(pi, workerPath);
+
+  function startPollerForContext(previousSessionFile: string | undefined, ctx: ExtensionContext) {
+    stopPollerForSession(previousSessionFile, ctx.cwd);
+    try {
+      const config = loadOracleConfig(ctx.cwd);
+      startPoller(pi, ctx, config.poller.intervalMs);
+      refreshOracleStatus(ctx);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      stopPoller(ctx);
+      ctx.ui.setStatus("oracle", ctx.ui.theme.fg("danger", "oracle: config error"));
+      ctx.ui.notify(message, "warning");
+    }
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    startPollerForContext(undefined, ctx);
+  });
+
+  pi.on("session_switch", async (event, ctx) => {
+    startPollerForContext(event.previousSessionFile, ctx);
+  });
+
+  pi.on("session_fork", async (event, ctx) => {
+    startPollerForContext(event.previousSessionFile, ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    stopPoller(ctx);
+  });
+}

package/extensions/oracle/lib/commands.ts

@@ -0,0 +1,184 @@
+import { spawn } from "node:child_process";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { loadOracleConfig } from "./config.js";
+import { buildOracleDispatchPrompt } from "./instructions.js";
+import { cancelOracleJob, isActiveOracleJob, listJobsForCwd, readJob, reconcileStaleOracleJobs } from "./jobs.js";
+import { refreshOracleStatus } from "./poller.js";
+import { withGlobalReconcileLock } from "./locks.js";
+import { getProjectId } from "./runtime.js";
+
+function summarizeJob(jobId: string): string {
+  const job = readJob(jobId);
+  if (!job) return `Oracle job ${jobId} not found.`;
+
+  return [
+    `job: ${job.id}`,
+    `status: ${job.status}`,
+    `phase: ${job.phase}`,
+    `created: ${job.createdAt}`,
+    `project: ${job.projectId}`,
+    `session: ${job.sessionId}`,
+    job.completedAt ? `completed: ${job.completedAt}` : undefined,
+    job.followUpToJobId ? `follow-up-to: ${job.followUpToJobId}` : undefined,
+    job.chatUrl ? `chat: ${job.chatUrl}` : undefined,
+    job.conversationId ? `conversation: ${job.conversationId}` : undefined,
+    job.responsePath ? `response: ${job.responsePath}` : undefined,
+    job.responseFormat ? `response-format: ${job.responseFormat}` : undefined,
+    typeof job.artifactFailureCount === "number" ? `artifact-failures: ${job.artifactFailureCount}` : undefined,
+    job.error ? `error: ${job.error}` : undefined,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function getLatestJobId(cwd: string): string | undefined {
+  return listJobsForCwd(cwd)[0]?.id;
+}
+
+function readScopedJob(jobId: string, cwd: string) {
+  const job = readJob(jobId);
+  if (!job || job.projectId !== getProjectId(cwd)) return undefined;
+  return job;
+}
+
+async function runAuthBootstrap(authWorkerPath: string, cwd: string): Promise<string> {
+  const config = loadOracleConfig(cwd);
+  await withGlobalReconcileLock({ processPid: process.pid, source: "oracle_auth", cwd }, async () => {
+    await reconcileStaleOracleJobs();
+  });
+
+  return await new Promise<string>((resolve, reject) => {
+    const child = spawn(process.execPath, [authWorkerPath, JSON.stringify(config)], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (data) => {
+      stdout += String(data);
+    });
+    child.stderr.on("data", (data) => {
+      stderr += String(data);
+    });
+    child.on("error", (error) => reject(error));
+    child.on("close", (code) => {
+      const message = stdout.trim() || stderr.trim() || "Oracle auth bootstrap finished with no output.";
+      if (code === 0) resolve(message);
+      else reject(new Error(message));
+    });
+  });
+}
+
+export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string): void {
+  pi.registerCommand("oracle", {
+    description: "Ask the agent to prepare and dispatch a ChatGPT web oracle job",
+    handler: async (args, ctx) => {
+      const request = args.trim();
+      if (!request) {
+        ctx.ui.notify("Usage: /oracle <request>", "warning");
+        return;
+      }
+
+      const message = buildOracleDispatchPrompt(request);
+      if (ctx.isIdle()) {
+        pi.sendUserMessage(message);
+      } else {
+        pi.sendUserMessage(message, { deliverAs: "followUp" });
+        ctx.ui.notify("Queued oracle preparation as a follow-up", "info");
+      }
+    },
+  });
+
+  pi.registerCommand("oracle-auth", {
+    description: "Sync ChatGPT cookies from real Chrome into the oracle auth seed profile",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify("Syncing ChatGPT cookies from real Chrome into the oracle auth seed profile…", "info");
+      try {
+        const result = await runAuthBootstrap(authWorkerPath, ctx.cwd);
+        ctx.ui.notify(result, "info");
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+      }
+    },
+  });
+
+  pi.registerCommand("oracle-status", {
+    description: "Show oracle job status",
+    handler: async (args, ctx) => {
+      const explicitJobId = args.trim();
+      const jobId = explicitJobId || getLatestJobId(ctx.cwd);
+      if (!jobId) {
+        ctx.ui.notify("No oracle jobs found for this project", "info");
+        return;
+      }
+      if (explicitJobId && !readScopedJob(jobId, ctx.cwd)) {
+        ctx.ui.notify(`Oracle job ${jobId} was not found in this project`, "warning");
+        return;
+      }
+      ctx.ui.notify(summarizeJob(jobId), "info");
+    },
+  });
+
+  pi.registerCommand("oracle-cancel", {
+    description: "Cancel an active oracle job",
+    handler: async (args, ctx) => {
+      const explicitJobId = args.trim();
+      const jobId = explicitJobId || getLatestJobId(ctx.cwd);
+      if (!jobId) {
+        ctx.ui.notify("No oracle jobs found for this project", "info");
+        return;
+      }
+
+      const job = explicitJobId ? readScopedJob(jobId, ctx.cwd) : readJob(jobId);
+      if (!job) {
+        ctx.ui.notify(`Oracle job ${jobId} not found in this project`, "warning");
+        return;
+      }
+      if (!isActiveOracleJob(job)) {
+        ctx.ui.notify(`Oracle job ${jobId} is not active (${job.status})`, "info");
+        return;
+      }
+
+      const cancelled = await cancelOracleJob(jobId);
+      refreshOracleStatus(ctx);
+      ctx.ui.notify(`Cancelled oracle job ${cancelled.id}`, "info");
+    },
+  });
+
+  pi.registerCommand("oracle-clean", {
+    description: "Remove oracle temp files for a job or all project jobs",
+    handler: async (args, ctx: ExtensionCommandContext) => {
+      const target = args.trim();
+      if (!target) {
+        ctx.ui.notify("Usage: /oracle-clean <job-id|all>", "warning");
+        return;
+      }
+
+      const jobs = target === "all" ? listJobsForCwd(ctx.cwd) : [readScopedJob(target, ctx.cwd)].filter(Boolean);
+      if (jobs.length === 0) {
+        ctx.ui.notify("No matching oracle jobs found", "warning");
+        return;
+      }
+
+      const activeJobs = jobs.filter((job): job is NonNullable<typeof job> => Boolean(job && isActiveOracleJob(job)));
+      if (activeJobs.length > 0) {
+        ctx.ui.notify(
+          `Refusing to remove active oracle job${activeJobs.length === 1 ? "" : "s"}: ${activeJobs.map((job) => job.id).join(", ")}`,
+          "warning",
+        );
+        return;
+      }
+
+      for (const job of jobs) {
+        if (!job) continue;
+        await rm(join("/tmp", `oracle-${job.id}`), { recursive: true, force: true });
+      }
+
+      refreshOracleStatus(ctx);
+      ctx.ui.notify(`Removed ${jobs.length} oracle job director${jobs.length === 1 ? "y" : "ies"}`, "info");
+    },
+  });
+}