pi-oracle 0.3.4 → 0.5.0

package/extensions/oracle/worker/state-locks.mjs

@@ -1,237 +1,52 @@
-import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { basename, join } from "node:path";
-
-const DEFAULT_WAIT_MS = 30_000;
-const POLL_MS = 200;
-export const ORACLE_METADATA_WRITE_GRACE_MS = 1_000;
-export const ORACLE_TMP_STATE_DIR_GRACE_MS = 60_000;
-
-async function sleep(ms) {
-  await new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-async function ensurePrivateDir(path) {
-  await mkdir(path, { recursive: true, mode: 0o700 });
-  await chmod(path, 0o700).catch(() => undefined);
-}
-
-function leaseKey(kind, key) {
-  return `${kind}-${createHash("sha256").update(key).digest("hex").slice(0, 24)}`;
-}
-
-function getLocksDir(stateDir) {
-  return join(stateDir, "locks");
-}
-
-function getLeasesDir(stateDir) {
-  return join(stateDir, "leases");
-}
-
-function lockPath(stateDir, kind, key) {
-  return join(getLocksDir(stateDir), leaseKey(kind, key));
-}
-
-function leasePath(stateDir, kind, key) {
-  return join(getLeasesDir(stateDir), leaseKey(kind, key));
-}
-
-function getMetadataPath(path) {
-  return join(path, "metadata.json");
-}
-
-async function writeMetadata(path, metadata) {
-  const targetPath = getMetadataPath(path);
-  const tempPath = join(path, `metadata.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
-  await writeFile(tempPath, `${JSON.stringify(metadata, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-  await chmod(tempPath, 0o600).catch(() => undefined);
-  await rename(tempPath, targetPath);
-  await chmod(targetPath, 0o600).catch(() => undefined);
-}
-
-async function createStateDirAtomically(parentDir, finalPath, metadata) {
-  const tempPath = join(parentDir, `.tmp-${basename(finalPath)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`);
-  await mkdir(tempPath, { recursive: false, mode: 0o700 });
-  try {
-    await writeMetadata(tempPath, metadata);
-    await rename(tempPath, finalPath);
-  } catch (error) {
-    await rm(tempPath, { recursive: true, force: true }).catch(() => undefined);
-    throw error;
-  }
-}
-
-function getMetadataState(path) {
-  const metadataPath = getMetadataPath(path);
-  if (!existsSync(metadataPath)) return "missing";
-  try {
-    JSON.parse(readFileSync(metadataPath, "utf8"));
-    return "present";
-  } catch {
-    return "invalid";
-  }
-}
-
-function isIncompleteStateDirStale(path, now = Date.now()) {
-  try {
-    const stats = statSync(path);
-    const baselineMs = Math.max(stats.mtimeMs, stats.ctimeMs);
-    const graceMs = basename(path).startsWith(".tmp-") ? ORACLE_TMP_STATE_DIR_GRACE_MS : ORACLE_METADATA_WRITE_GRACE_MS;
-    return now - baselineMs >= graceMs;
-  } catch {
-    return false;
-  }
-}
-
-function isProcessAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return false;
-    return true;
-  }
-}
-
-function isStateDirExistsError(error) {
-  return Boolean(error && typeof error === "object" && "code" in error && (error.code === "EEXIST" || error.code === "ENOTEMPTY"));
-}
-
-async function readLockProcessPid(path) {
-  const metadataPath = getMetadataPath(path);
-  if (!existsSync(metadataPath)) return undefined;
-  try {
-    const metadata = JSON.parse(await readFile(metadataPath, "utf8"));
-    return typeof metadata?.processPid === "number" && Number.isInteger(metadata.processPid) && metadata.processPid > 0
-      ? metadata.processPid
-      : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-async function maybeReclaimIncompleteStateDir(path, now = Date.now()) {
-  if (getMetadataState(path) === "present") return false;
-  if (!isIncompleteStateDirStale(path, now)) return false;
-  await rm(path, { recursive: true, force: true }).catch(() => undefined);
-  return true;
-}
-
-async function maybeReclaimStaleLock(path, now = Date.now()) {
-  if (await maybeReclaimIncompleteStateDir(path, now)) return true;
-  const processPid = await readLockProcessPid(path);
-  if (!processPid || isProcessAlive(processPid)) return false;
-  await rm(path, { recursive: true, force: true }).catch(() => undefined);
-  return true;
-}
-
-export async function acquireLock(stateDir, kind, key, metadata, timeoutMs = DEFAULT_WAIT_MS) {
-  const parentDir = getLocksDir(stateDir);
-  const path = join(parentDir, leaseKey(kind, key));
-  const deadline = Date.now() + timeoutMs;
-  await ensurePrivateDir(stateDir);
-  await ensurePrivateDir(parentDir);
-
-  while (Date.now() < deadline) {
-    try {
-      await createStateDirAtomically(parentDir, path, metadata);
-      return path;
-    } catch (error) {
-      if (!isStateDirExistsError(error)) throw error;
-      if (await maybeReclaimStaleLock(path)) continue;
-    }
-    await sleep(POLL_MS);
-  }
-
-  throw new Error(`Timed out waiting for oracle ${kind} lock: ${key}`);
+// Purpose: Provide worker-facing wrappers around the shared oracle state lock/lease coordination helpers.
+// Responsibilities: Bind shared state helpers to the worker call signatures and re-export crash-recovery constants.
+// Scope: Worker wrapper only; atomic lock/lease behavior lives in shared/state-coordination-helpers.mjs.
+// Usage: Imported by worker entrypoints that need per-state-dir locks or lease metadata persistence.
+// Invariants/Assumptions: Callers pass the oracle state directory explicitly so worker tests can isolate state safely.
+
+import {
+  acquireStateLock,
+  createStateLease,
+  listStateLeaseMetadata,
+  ORACLE_METADATA_WRITE_GRACE_MS,
+  ORACLE_TMP_STATE_DIR_GRACE_MS,
+  readStateLeaseMetadata,
+  releaseStateLease,
+  releaseStatePath,
+  withStateLock,
+  writeStateLeaseMetadata,
+} from "../shared/state-coordination-helpers.mjs";
+
+export { ORACLE_METADATA_WRITE_GRACE_MS, ORACLE_TMP_STATE_DIR_GRACE_MS };
+
+export async function acquireLock(stateDir, kind, key, metadata, timeoutMs) {
+  return acquireStateLock(stateDir, kind, key, metadata, timeoutMs);
 }
 
 export async function releaseLock(path) {
-  if (!path) return;
-  await rm(path, { recursive: true, force: true }).catch(() => undefined);
+  await releaseStatePath(path);
 }
 
 export async function withLock(stateDir, kind, key, metadata, fn, timeoutMs) {
-  const handle = await acquireLock(stateDir, kind, key, metadata, timeoutMs);
-  try {
-    return await fn();
-  } finally {
-    await releaseLock(handle);
-  }
+  return withStateLock(stateDir, kind, key, metadata, fn, timeoutMs);
 }
 
-export async function createLease(stateDir, kind, key, metadata, timeoutMs = DEFAULT_WAIT_MS) {
-  const parentDir = getLeasesDir(stateDir);
-  const path = join(parentDir, leaseKey(kind, key));
-  const deadline = Date.now() + timeoutMs;
-  await ensurePrivateDir(stateDir);
-  await ensurePrivateDir(parentDir);
-
-  while (Date.now() < deadline) {
-    try {
-      await createStateDirAtomically(parentDir, path, metadata);
-      return path;
-    } catch (error) {
-      if (!isStateDirExistsError(error)) throw error;
-      if (await maybeReclaimIncompleteStateDir(path)) continue;
-      if (getMetadataState(path) === "present") throw error;
-    }
-    await sleep(POLL_MS);
-  }
-
-  throw new Error(`Timed out waiting for oracle ${kind} lease: ${key}`);
+export async function createLease(stateDir, kind, key, metadata, timeoutMs) {
+  return createStateLease(stateDir, kind, key, metadata, timeoutMs);
 }
 
 export async function writeLeaseMetadata(stateDir, kind, key, metadata) {
-  const parentDir = getLeasesDir(stateDir);
-  const path = join(parentDir, leaseKey(kind, key));
-  await ensurePrivateDir(stateDir);
-  await ensurePrivateDir(parentDir);
-  if (existsSync(path)) {
-    await chmod(path, 0o700).catch(() => undefined);
-    await writeMetadata(path, metadata);
-    return path;
-  }
-  try {
-    await createStateDirAtomically(parentDir, path, metadata);
-  } catch (error) {
-    if (!isStateDirExistsError(error)) throw error;
-    if (await maybeReclaimIncompleteStateDir(path)) {
-      await createStateDirAtomically(parentDir, path, metadata);
-    } else {
-      await writeMetadata(path, metadata);
-    }
-  }
-  return path;
+  return writeStateLeaseMetadata(stateDir, kind, key, metadata);
 }
 
 export async function readLeaseMetadata(stateDir, kind, key) {
-  const path = getMetadataPath(leasePath(stateDir, kind, key));
-  if (!existsSync(path)) return undefined;
-  try {
-    return JSON.parse(await readFile(path, "utf8"));
-  } catch {
-    return undefined;
-  }
+  return readStateLeaseMetadata(stateDir, kind, key);
 }
 
 export function listLeaseMetadata(stateDir, kind) {
-  const dir = getLeasesDir(stateDir);
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir)
-    .filter((name) => name.startsWith(`${kind}-`))
-    .map((name) => join(dir, name, "metadata.json"))
-    .filter((path) => existsSync(path))
-    .flatMap((path) => {
-      try {
-        return [JSON.parse(readFileSync(path, "utf8"))];
-      } catch {
-        return [];
-      }
-    });
+  return listStateLeaseMetadata(stateDir, kind);
 }
 
 export async function releaseLease(stateDir, kind, key) {
-  await rm(leasePath(stateDir, kind, key), { recursive: true, force: true }).catch(() => undefined);
+  await releaseStateLease(stateDir, kind, key);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-oracle",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "description": "ChatGPT web-oracle extension for pi with isolated browser auth, async jobs, and project-context archives.",
   "private": false,
   "license": "MIT",
@@ -42,11 +42,12 @@
     ]
   },
   "scripts": {
-    "check:oracle-extension": "node --check extensions/oracle/worker/run-job.mjs && node --check extensions/oracle/worker/state-locks.mjs && node --check extensions/oracle/worker/artifact-heuristics.mjs && node --check extensions/oracle/worker/chatgpt-ui-helpers.mjs && node --check extensions/oracle/worker/auth-cookie-policy.mjs && node --check extensions/oracle/worker/auth-bootstrap.mjs && esbuild extensions/oracle/index.ts --bundle --platform=node --format=esm --external:@mariozechner/pi-coding-agent --external:@mariozechner/pi-ai --external:@sinclair/typebox --outfile=/tmp/pi-oracle-extension-check.js",
+    "check:oracle-extension": "node --check extensions/oracle/shared/process-helpers.mjs && node --check extensions/oracle/shared/state-coordination-helpers.mjs && node --check extensions/oracle/shared/job-coordination-helpers.mjs && node --check extensions/oracle/shared/job-lifecycle-helpers.mjs && node --check extensions/oracle/shared/job-observability-helpers.mjs && node --check extensions/oracle/worker/run-job.mjs && node --check extensions/oracle/worker/state-locks.mjs && node --check extensions/oracle/worker/artifact-heuristics.mjs && node --check extensions/oracle/worker/chatgpt-ui-helpers.mjs && node --check extensions/oracle/worker/chatgpt-flow-helpers.mjs && node --check extensions/oracle/worker/auth-flow-helpers.mjs && node --check extensions/oracle/worker/auth-cookie-policy.mjs && node --check extensions/oracle/worker/auth-bootstrap.mjs && esbuild extensions/oracle/index.ts --bundle --platform=node --format=esm --external:@mariozechner/pi-coding-agent --external:@mariozechner/pi-ai --external:@sinclair/typebox --outfile=/tmp/pi-oracle-extension-check.js",
     "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck:worker-helpers": "tsc --noEmit -p tsconfig.worker-helpers.json",
     "sanity:oracle": "node scripts/oracle-sanity-runner.mjs",
     "pack:check": "npm pack --dry-run",
-    "verify:oracle": "npm run check:oracle-extension && npm run typecheck && npm run sanity:oracle && npm run pack:check",
+    "verify:oracle": "npm run check:oracle-extension && npm run typecheck && npm run typecheck:worker-helpers && npm run sanity:oracle && npm run pack:check",
     "test": "npm run verify:oracle",
     "prepublishOnly": "npm run verify:oracle"
   },

package/prompts/oracle.md

@@ -6,29 +6,35 @@ You are preparing an /oracle job.
 Do not answer the user's request directly yet.
 
 Required workflow:
-1. Understand the request.
-2. Gather repo context first by reading files and searching the codebase.
-3. Choose archive inputs for the oracle job.
-4. Craft a concise but complete oracle prompt for ChatGPT web.
-5. Call oracle_submit with the prompt and exact archive inputs.
-6. Stop immediately after dispatching the oracle job.
+1. Call `oracle_preflight` immediately.
+2. If `oracle_preflight` reports `ready: false`, stop immediately and report the blocking issue plus the suggested next step. Do not read files, search the codebase, or prepare archive inputs first.
+3. Understand the request and decide whether it is explicitly narrow or genuinely broad.
+4. Gather only the smallest repo context needed to choose archive inputs and write a strong oracle prompt.
+5. If the user scope is explicit and narrow, prefer a minimal targeted read/search set and dispatch as soon as you have enough context. Do not broaden into repo-wide exploration unless the narrow pass proves insufficient.
+6. If the request is broad, architectural, release-oriented, or otherwise repo-wide, gather broader context and usually archive `.`.
+7. Choose archive inputs for the oracle job.
+8. Craft a concise but complete oracle prompt for ChatGPT web.
+9. Call `oracle_submit` with the prompt and exact archive inputs.
+10. Stop immediately after dispatching the oracle job.
 
 Oracle model (`oracle_submit`):
 - To choose a specific ChatGPT model, pass **`preset`** with one of the allowed ids from the canonical preset registry.
 - Matching human-readable preset labels and common hyphen/space variants are also accepted and normalized automatically, but prefer canonical ids when readily available.
 - **Or** omit **`preset`** entirely to use the configured default model (from oracle config).
 - **`preset`** is the only model-selection parameter on `oracle_submit`. Do not pass `modelFamily`, `effort`, or `autoSwitchToThinking`.
-- If unsure which preset fits the task, ask the user.
+- If unsure, omit **`preset`** and use the configured default. Ask the user about model choice only when they explicitly want model control or the choice would materially change the result.
 
 Rules:
+- Use `oracle_preflight` before any expensive `/oracle` preparation so missing persisted-session or local auth/config blockers fail fast.
 - Always include an archive. Do not submit without context files.
-- By default, include the whole repository by passing `.`. Default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like `.env` files, key material, credential dotfiles, local database files, and nested `secrets/` directories anywhere in the repo.
+- By default, include the whole repository by passing `.` when the request is genuinely broad, repo-wide, or unclear after a quick narrow pass. Default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like `.env` files, key material, credential dotfiles, local database files, and nested `secrets/` directories anywhere in the repo.
 - Only limit file selection if the user explicitly requests it, if the task is clearly scoped to a smaller area, or if privacy/sensitivity requires it.
-- For very targeted asks like reviewing one function or explaining one stack trace, a smaller archive is preferable.
+- For very targeted asks like reviewing one function, one file, one stack trace, or one narrowly scoped question, start with the smallest obviously sufficient archive and expand only if that first pass proves insufficient.
+- Do not keep exploring once you already have enough context to submit well.
 - If the request depends on git state or pending changes (for example code review, ship readiness, or release approval), create a tracked diff bundle file inside the repo (for example under `.pi/`) containing `git status` plus `git diff` output, include that file in the archive, and tell the oracle to use it because the `.git` directory is not included in oracle exports.
 - When `files=["."]` and the post-exclusion archive is still too large, submit automatically prunes the largest nested directories matching generic generated-output names like `build/`, `dist/`, `out/`, `coverage/`, and `tmp/` outside obvious source roots like `src/` and `lib/` until the archive fits or no candidate remains. Successful submissions report what was pruned.
 - If a submitted oracle job later fails because upload is rejected, retry with a smaller archive in this order: (1) remove the largest obviously irrelevant/generated content, (2) if still too large, include modified files plus adjacent files plus directly relevant subtrees, (3) if still too large, explain the cut or ask the user.
-- Prefer the configured default (omit **`preset`**) unless the task clearly needs a different model; then choose a canonical **`preset`** id.
+- Prefer the configured default (omit **`preset`**) unless the task clearly needs a different model or the user explicitly asked for one; then choose a canonical **`preset`** id.
 - If `oracle_submit` itself fails because the local archive still exceeds the upload limit after default exclusions and automatic generic generated-output-dir pruning, or for any other submit-time error, stop and report the error. Do not retry automatically.
 - If `oracle_submit` returns a queued job instead of an immediately dispatched one, treat that as success and end your turn exactly the same way.
 - After oracle_submit returns, end your turn. Do not keep working while the oracle runs.