pi-oracle 0.3.4 → 0.5.0

package/extensions/oracle/lib/runtime.ts

@@ -1,8 +1,15 @@
-import { randomUUID, createHash } from "node:crypto";
+// Purpose: Manage oracle browser runtime allocation, lease admission, seed/runtime profile handling, and runtime cleanup for the extension side.
+// Responsibilities: Allocate runtimes, enforce persisted-session requirements, acquire/release runtime and conversation leases, and clean up runtime artifacts safely.
+// Scope: Extension-side runtime coordination only; shared concurrency/process primitives live in extensions/oracle/shared.
+// Usage: Imported by jobs, tools, and queue logic to provision or tear down isolated oracle browser runtimes.
+// Invariants/Assumptions: Lease metadata is the admission source of truth, tracked worker identity checks defend against PID reuse, and runtime cleanup always attempts lease release.
+import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
-import { existsSync, realpathSync, readFileSync } from "node:fs";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { constants as fsConstants, existsSync, realpathSync, readFileSync } from "node:fs";
+import { access, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { jobBlocksAdmission } from "../shared/job-coordination-helpers.mjs";
+import { isTrackedProcessAlive } from "../shared/process-helpers.mjs";
 import type { OracleConfig } from "./config.js";
 import { createLease, listLeaseMetadata, readLeaseMetadata, releaseLease, withAuthLock } from "./locks.js";
 
@@ -12,6 +19,8 @@ const ORACLE_JOBS_DIR = process.env.PI_ORACLE_JOBS_DIR?.trim() || DEFAULT_ORACLE
 const AGENT_BROWSER_BIN = [process.env.AGENT_BROWSER_PATH, "/opt/homebrew/bin/agent-browser", "/usr/local/bin/agent-browser"].find(
   (candidate) => typeof candidate === "string" && candidate && existsSync(candidate),
 ) || "agent-browser";
+const PROFILE_CLONE_TIMEOUT_MS = 120_000;
+const ORACLE_SUBPROCESS_KILL_GRACE_MS = 2_000;
 
 export interface OracleRuntimeLeaseMetadata {
   jobId: string;
@@ -89,6 +98,45 @@ export function authSessionName(config: OracleConfig): string {
   return `${config.browser.sessionPrefix}-auth`;
 }
 
+function missingAuthSeedProfileMessage(seedDir: string): string {
+  return `Oracle auth seed profile not found: ${seedDir}. Run /oracle-auth first.`;
+}
+
+function invalidAuthSeedProfileTypeMessage(seedDir: string): string {
+  return `Oracle auth seed profile is not a directory: ${seedDir}. Remove the invalid path or rerun /oracle-auth.`;
+}
+
+function unreadableAuthSeedProfileMessage(seedDir: string): string {
+  return `Oracle auth seed profile is not readable: ${seedDir}. Fix its permissions or rerun /oracle-auth.`;
+}
+
+export async function assertOracleAuthSeedProfileReady(config: OracleConfig): Promise<void> {
+  const seedDir = config.browser.authSeedProfileDir;
+  let seedStats;
+  try {
+    seedStats = await stat(seedDir);
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    if (code === "ENOENT") throw new Error(missingAuthSeedProfileMessage(seedDir));
+    if (code === "EACCES" || code === "EPERM") throw new Error(unreadableAuthSeedProfileMessage(seedDir));
+    throw new Error(`Failed to inspect oracle auth seed profile ${seedDir}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  if (!seedStats.isDirectory()) {
+    throw new Error(invalidAuthSeedProfileTypeMessage(seedDir));
+  }
+
+  try {
+    await access(seedDir, fsConstants.R_OK | fsConstants.X_OK);
+  } catch {
+    throw new Error(unreadableAuthSeedProfileMessage(seedDir));
+  }
+}
+
+export async function assertOracleSubmitPrerequisites(config: OracleConfig): Promise<void> {
+  await assertOracleAuthSeedProfileReady(config);
+}
+
 export function getSeedGeneration(config: OracleConfig): string | undefined {
   const path = join(config.browser.authSeedProfileDir, SEED_GENERATION_FILE);
   if (!existsSync(path)) return undefined;
@@ -110,8 +158,18 @@ function activeJobExists(jobId: string): boolean {
   const path = join(ORACLE_JOBS_DIR, `oracle-${jobId}`, "job.json");
   if (!existsSync(path)) return false;
   try {
-    const job = JSON.parse(readFileSync(path, "utf8")) as { status?: string; cleanupWarnings?: unknown; cleanupPending?: unknown };
-    return ["preparing", "submitted", "waiting"].includes(job.status || "") || job.cleanupPending === true || (Array.isArray(job.cleanupWarnings) && job.cleanupWarnings.length > 0);
+    const job = JSON.parse(readFileSync(path, "utf8")) as {
+      status?: string;
+      cleanupPending?: unknown;
+      workerPid?: unknown;
+      workerStartedAt?: unknown;
+    };
+    return jobBlocksAdmission({
+      status: typeof job.status === "string" ? job.status : undefined,
+      cleanupPending: job.cleanupPending === true,
+      workerPid: typeof job.workerPid === "number" ? job.workerPid : undefined,
+      workerStartedAt: typeof job.workerStartedAt === "string" ? job.workerStartedAt : undefined,
+    }, isTrackedProcessAlive);
   } catch {
     return false;
   }
@@ -198,31 +256,62 @@ function profileCloneArgs(config: OracleConfig, sourceDir: string, destinationDi
   return ["-R", sourceDir, destinationDir];
 }
 
-async function spawnCp(args: string[]): Promise<void> {
+async function spawnCp(args: string[], options?: { timeoutMs?: number }): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     const child = spawn("cp", args, { stdio: ["ignore", "pipe", "pipe"] });
     let stderr = "";
+    let timedOut = false;
+    let killTimer: NodeJS.Timeout | undefined;
+    let killGraceTimer: NodeJS.Timeout | undefined;
+
+    const clearTimers = () => {
+      if (killTimer) clearTimeout(killTimer);
+      if (killGraceTimer) clearTimeout(killGraceTimer);
+    };
+
+    if ((options?.timeoutMs ?? 0) > 0) {
+      killTimer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        killGraceTimer = setTimeout(() => {
+          child.kill("SIGKILL");
+        }, ORACLE_SUBPROCESS_KILL_GRACE_MS);
+        killGraceTimer.unref?.();
+      }, options?.timeoutMs);
+      killTimer.unref?.();
+    }
+
     child.stderr.on("data", (data) => {
       stderr += String(data);
     });
-    child.on("error", reject);
+    child.on("error", (error) => {
+      clearTimers();
+      reject(error);
+    });
     child.on("close", (code) => {
+      clearTimers();
+      if (timedOut) {
+        reject(new Error(stderr || `cp timed out after ${options?.timeoutMs}ms`));
+        return;
+      }
       if (code === 0) resolve();
       else reject(new Error(stderr || `cp exited with code ${code}`));
     });
   });
 }
 
-export async function cloneSeedProfileToRuntime(config: OracleConfig, runtimeProfileDir: string): Promise<string | undefined> {
+export async function cloneSeedProfileToRuntime(
+  config: OracleConfig,
+  runtimeProfileDir: string,
+  options?: { cpTimeoutMs?: number },
+): Promise<string | undefined> {
   const seedDir = config.browser.authSeedProfileDir;
-  if (!existsSync(seedDir)) {
-    throw new Error(`Oracle auth seed profile not found: ${seedDir}. Run /oracle-auth first.`);
-  }
+  await assertOracleAuthSeedProfileReady(config);
 
   await withAuthLock({ runtimeProfileDir, seedDir }, async () => {
     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));
+    await spawnCp(profileCloneArgs(config, seedDir, runtimeProfileDir), { timeoutMs: options?.cpTimeoutMs ?? PROFILE_CLONE_TIMEOUT_MS });
   });
 
   return getSeedGeneration(config);
@@ -286,9 +375,6 @@ export async function cleanupRuntimeArtifacts(runtime: {
       report.warnings.push(`Failed to remove runtime profile ${runtime.runtimeProfileDir}: ${error.message}`);
     });
   }
-  if (report.warnings.length > 0) {
-    return report;
-  }
   if (runtime.conversationId) {
     report.attempted.push("conversationLease");
   }
@@ -305,6 +391,3 @@ export async function cleanupRuntimeArtifacts(runtime: {
   return report;
 }
 
-export function stableProjectLabel(projectId: string): string {
-  return basename(projectId) || createHash("sha256").update(projectId).digest("hex").slice(0, 8);
-}