pi-oracle 0.3.4 → 0.5.0

package/extensions/oracle/shared/process-helpers.mjs

@@ -0,0 +1,128 @@
+// Purpose: Provide shared process-identity and termination helpers for oracle runtime, worker, and queue coordination.
+// Responsibilities: Read stable process start identities, detect liveness, wait for freshly spawned processes, and terminate tracked processes safely.
+// Scope: Local process coordination only; job-state mutation and queue semantics stay in higher-level helpers.
+// Usage: Imported by lib/jobs.ts, lib/runtime.ts, worker/run-job.mjs, and shared state helpers.
+// Invariants/Assumptions: Process identity is validated with `ps -o lstart=` to defend against PID reuse on macOS.
+
+import { spawn, execFileSync } from "node:child_process";
+
+/** @typedef {import("./process-helpers.d.mts").OracleTrackedProcessOptions} OracleTrackedProcessOptions */
+/** @typedef {import("./process-helpers.d.mts").OracleDetachedProcessHandle} OracleDetachedProcessHandle */
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {number | undefined} pid
+ * @returns {string | undefined}
+ */
+export function readProcessStartedAt(pid) {
+  if (!pid || pid <= 0) return undefined;
+  try {
+    const startedAt = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" }).trim();
+    return startedAt || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {number | undefined} pid
+ * @returns {boolean}
+ */
+export function isProcessAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return false;
+    return true;
+  }
+}
+
+/**
+ * @param {number | undefined} pid
+ * @param {string | undefined} startedAt
+ * @returns {boolean}
+ */
+export function isTrackedProcessAlive(pid, startedAt) {
+  const currentStartedAt = readProcessStartedAt(pid);
+  if (!currentStartedAt) return false;
+  return startedAt ? currentStartedAt === startedAt : true;
+}
+
+/**
+ * @param {number | undefined} pid
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string | undefined>}
+ */
+export async function waitForProcessStartedAt(pid, timeoutMs = 2_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const startedAt = readProcessStartedAt(pid);
+    if (startedAt) return startedAt;
+    await sleep(100);
+  }
+  return readProcessStartedAt(pid);
+}
+
+/**
+ * @param {number | undefined} pid
+ * @param {string | undefined} startedAt
+ * @param {OracleTrackedProcessOptions} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function terminateTrackedProcess(pid, startedAt, options = {}) {
+  if (!pid || pid <= 0) return true;
+  const currentStartedAt = readProcessStartedAt(pid);
+  if (!currentStartedAt) return true;
+  if (startedAt && currentStartedAt !== startedAt) return false;
+
+  const termGraceMs = options.termGraceMs ?? 5_000;
+  const killGraceMs = options.killGraceMs ?? 2_000;
+
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    return !isTrackedProcessAlive(pid, startedAt);
+  }
+
+  const termDeadline = Date.now() + termGraceMs;
+  while (Date.now() < termDeadline) {
+    if (!isTrackedProcessAlive(pid, startedAt)) return true;
+    await sleep(250);
+  }
+
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+    return !isTrackedProcessAlive(pid, startedAt);
+  }
+
+  const killDeadline = Date.now() + killGraceMs;
+  while (Date.now() < killDeadline) {
+    if (!isTrackedProcessAlive(pid, startedAt)) return true;
+    await sleep(250);
+  }
+
+  return !isTrackedProcessAlive(pid, startedAt);
+}
+
+/**
+ * @param {string} scriptPath
+ * @param {string[]} args
+ * @returns {Promise<OracleDetachedProcessHandle>}
+ */
+export async function spawnDetachedNodeProcess(scriptPath, args = []) {
+  const child = spawn(process.execPath, [scriptPath, ...args], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  return {
+    pid: child.pid,
+    startedAt: await waitForProcessStartedAt(child.pid),
+  };
+}

package/extensions/oracle/shared/state-coordination-helpers.d.mts

@@ -0,0 +1,43 @@
+export const ORACLE_METADATA_WRITE_GRACE_MS: number;
+export const ORACLE_TMP_STATE_DIR_GRACE_MS: number;
+
+export declare function hashOracleStateKey(kind: string, key: string): string;
+export declare function getStateLocksDir(stateDir: string): string;
+export declare function getStateLeasesDir(stateDir: string): string;
+export declare function sweepStaleStateLocks(stateDir: string, now?: number): Promise<string[]>;
+export declare function acquireStateLock(
+  stateDir: string,
+  kind: string,
+  key: string,
+  metadata: unknown,
+  timeoutMs?: number,
+): Promise<string>;
+export declare function releaseStatePath(path: string | undefined): Promise<void>;
+export declare function withStateLock<T>(
+  stateDir: string,
+  kind: string,
+  key: string,
+  metadata: unknown,
+  fn: () => Promise<T>,
+  timeoutMs?: number,
+): Promise<T>;
+export declare function createStateLease(
+  stateDir: string,
+  kind: string,
+  key: string,
+  metadata: unknown,
+  timeoutMs?: number,
+): Promise<string>;
+export declare function writeStateLeaseMetadata(
+  stateDir: string,
+  kind: string,
+  key: string,
+  metadata: unknown,
+): Promise<string>;
+export declare function readStateLeaseMetadata<T = unknown>(
+  stateDir: string,
+  kind: string,
+  key: string,
+): Promise<T | undefined>;
+export declare function listStateLeaseMetadata<T = unknown>(stateDir: string, kind: string): T[];
+export declare function releaseStateLease(stateDir: string, kind: string, key: string | undefined): Promise<void>;

package/extensions/oracle/shared/state-coordination-helpers.mjs

@@ -0,0 +1,381 @@
+// Purpose: Provide shared atomic lock/lease state helpers for oracle coordination across extension and worker processes.
+// Responsibilities: Create lock/lease directories atomically, publish metadata safely, reclaim stale incomplete state, and enumerate lease metadata.
+// Scope: Filesystem-backed concurrency primitives only; higher-level admission and queue behavior stays in wrapper modules.
+// Usage: Imported by lib/locks.ts and worker/state-locks.mjs so both layers share identical crash-recovery semantics.
+// Invariants/Assumptions: State lives under a private per-machine directory, and final published state dirs must never appear without complete metadata.
+
+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";
+import { isProcessAlive } from "./process-helpers.mjs";
+
+const DEFAULT_WAIT_MS = 30_000;
+const POLL_MS = 200;
+export const ORACLE_METADATA_WRITE_GRACE_MS = 1_000;
+/** Incomplete `.tmp-*` dirs are in-flight atomic creates; a 1s grace is too short under multi-process sweep + slow FS. */
+export const ORACLE_TMP_STATE_DIR_GRACE_MS = 60_000;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {string} path
+ * @returns {Promise<void>}
+ */
+async function ensurePrivateDir(path) {
+  await mkdir(path, { recursive: true, mode: 0o700 });
+  await chmod(path, 0o700).catch(() => undefined);
+}
+
+/**
+ * @param {string} kind
+ * @param {string} key
+ * @returns {string}
+ */
+export function hashOracleStateKey(kind, key) {
+  return `${kind}-${createHash("sha256").update(key).digest("hex").slice(0, 24)}`;
+}
+
+/**
+ * @param {string} stateDir
+ * @returns {string}
+ */
+export function getStateLocksDir(stateDir) {
+  return join(stateDir, "locks");
+}
+
+/**
+ * @param {string} stateDir
+ * @returns {string}
+ */
+export function getStateLeasesDir(stateDir) {
+  return join(stateDir, "leases");
+}
+
+/**
+ * @param {string} stateDir
+ * @param {string} kind
+ * @param {string} key
+ * @returns {string}
+ */
+function lockPath(stateDir, kind, key) {
+  return join(getStateLocksDir(stateDir), hashOracleStateKey(kind, key));
+}
+
+/**
+ * @param {string} stateDir
+ * @param {string} kind
+ * @param {string} key
+ * @returns {string}
+ */
+function leasePath(stateDir, kind, key) {
+  return join(getStateLeasesDir(stateDir), hashOracleStateKey(kind, key));
+}
+
+/**
+ * @param {string} path
+ * @returns {string}
+ */
+function getMetadataPath(path) {
+  return join(path, "metadata.json");
+}
+
+/**
+ * @param {string} path
+ * @param {unknown} metadata
+ * @returns {Promise<void>}
+ */
+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);
+}
+
+/**
+ * @param {string} parentDir
+ * @param {string} finalPath
+ * @param {unknown} metadata
+ * @returns {Promise<void>}
+ */
+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;
+  }
+}
+
+/**
+ * @param {string} path
+ * @returns {"present" | "missing" | "invalid"}
+ */
+function getMetadataState(path) {
+  const metadataPath = getMetadataPath(path);
+  if (!existsSync(metadataPath)) return "missing";
+  try {
+    JSON.parse(readFileSync(metadataPath, "utf8"));
+    return "present";
+  } catch {
+    return "invalid";
+  }
+}
+
+/**
+ * @param {string} path
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+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;
+  }
+}
+
+/**
+ * @param {string} path
+ * @returns {number | undefined}
+ */
+function readLockProcessPid(path) {
+  const metadataPath = getMetadataPath(path);
+  if (!existsSync(metadataPath)) return undefined;
+  try {
+    const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+    return typeof metadata?.processPid === "number" && Number.isInteger(metadata.processPid) && metadata.processPid > 0
+      ? metadata.processPid
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isStateDirExistsError(error) {
+  return Boolean(error && typeof error === "object" && "code" in error && (error.code === "EEXIST" || error.code === "ENOTEMPTY"));
+}
+
+/**
+ * @param {string} path
+ * @param {number} [now]
+ * @returns {Promise<boolean>}
+ */
+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;
+}
+
+/**
+ * @param {string} path
+ * @param {number} [now]
+ * @returns {Promise<boolean>}
+ */
+async function maybeReclaimStaleLock(path, now = Date.now()) {
+  if (await maybeReclaimIncompleteStateDir(path, now)) return true;
+  const processPid = readLockProcessPid(path);
+  if (!processPid || isProcessAlive(processPid)) return false;
+  await rm(path, { recursive: true, force: true }).catch(() => undefined);
+  return true;
+}
+
+/**
+ * @param {string} stateDir
+ * @param {number} [now]
+ * @returns {Promise<string[]>}
+ */
+export async function sweepStaleStateLocks(stateDir, now = Date.now()) {
+  const dir = getStateLocksDir(stateDir);
+  if (!existsSync(dir)) return [];
+  const removed = [];
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (await maybeReclaimStaleLock(path, now)) {
+      removed.push(path);
+    }
+  }
+  return removed;
+}
+
+/**
+ * @param {string} stateDir
+ * @param {string} kind
+ * @param {string} key
+ * @param {unknown} metadata
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string>}
+ */
+export async function acquireStateLock(stateDir, kind, key, metadata, timeoutMs = DEFAULT_WAIT_MS) {
+  const parentDir = getStateLocksDir(stateDir);
+  const path = join(parentDir, hashOracleStateKey(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}`);
+}
+
+/**
+ * @param {string | undefined} path
+ * @returns {Promise<void>}
+ */
+export async function releaseStatePath(path) {
+  if (!path) return;
+  await rm(path, { recursive: true, force: true }).catch(() => undefined);
+}
+
+/**
+ * @template T
+ * @param {string} stateDir
+ * @param {string} kind
+ * @param {string} key
+ * @param {unknown} metadata
+ * @param {() => Promise<T>} fn
+ * @param {number} [timeoutMs]
+ * @returns {Promise<T>}
+ */
+export async function withStateLock(stateDir, kind, key, metadata, fn, timeoutMs = DEFAULT_WAIT_MS) {
+  const handle = await acquireStateLock(stateDir, kind, key, metadata, timeoutMs);
+  try {
+    return await fn();
+  } finally {
+    await releaseStatePath(handle);
+  }
+}
+
+/**
+ * @param {string} stateDir
+ * @param {string} kind
+ * @param {string} key
+ * @param {unknown} metadata
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string>}
+ */
+export async function createStateLease(stateDir, kind, key, metadata, timeoutMs = DEFAULT_WAIT_MS) {
+  const parentDir = getStateLeasesDir(stateDir);
+  const path = join(parentDir, hashOracleStateKey(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}`);
+}
+
+/**
+ * @param {string} stateDir
+ * @param {string} kind
+ * @param {string} key
+ * @param {unknown} metadata
+ * @returns {Promise<string>}
+ */
+export async function writeStateLeaseMetadata(stateDir, kind, key, metadata) {
+  const parentDir = getStateLeasesDir(stateDir);
+  const path = join(parentDir, hashOracleStateKey(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;
+}
+
+/**
+ * @template T
+ * @param {string} stateDir
+ * @param {string} kind
+ * @param {string} key
+ * @returns {Promise<T | undefined>}
+ */
+export async function readStateLeaseMetadata(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;
+  }
+}
+
+/**
+ * @template T
+ * @param {string} stateDir
+ * @param {string} kind
+ * @returns {T[]}
+ */
+export function listStateLeaseMetadata(stateDir, kind) {
+  const dir = getStateLeasesDir(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 [];
+      }
+    });
+}
+
+/**
+ * @param {string} stateDir
+ * @param {string} kind
+ * @param {string | undefined} key
+ * @returns {Promise<void>}
+ */
+export async function releaseStateLease(stateDir, kind, key) {
+  if (!key) return;
+  await rm(leasePath(stateDir, kind, key), { recursive: true, force: true }).catch(() => undefined);
+}

package/extensions/oracle/worker/artifact-heuristics.mjs

@@ -1,3 +1,8 @@
+// Purpose: Parse agent-browser snapshots and infer likely downloadable artifact labels from response UI structure.
+// Responsibilities: Extract snapshot entries, detect candidate filenames, and partition strong versus suspicious artifact signals.
+// Scope: Pure heuristic parsing only; browser interaction and artifact download orchestration stay in the worker.
+// Usage: Imported by worker runtime code, UI helper modules, and sanity tests to keep artifact detection behavior deterministic.
+// Invariants/Assumptions: Snapshot text comes from agent-browser `snapshot -i`, and heuristics should prefer false negatives over noisy false positives.
 export const FILE_LABEL_PATTERN_SOURCE = String.raw`(?:^|[^A-Za-z0-9._~/-])((?:(?:[A-Za-z]:)?[\\/]|[.~][\\/])?(?:[^\\/\s"'<>|]+[\\/])*[^\\/\s"'<>|]+\.[A-Za-z0-9]{1,12})(?=$|[^A-Za-z0-9._~/-])`;
 const FILE_LABEL_PATTERN = new RegExp(FILE_LABEL_PATTERN_SOURCE, "g");
 export const GENERIC_ARTIFACT_LABELS = ["ATTACHED", "DONE"];