pi-oracle 0.3.4 → 0.4.0

package/extensions/oracle/shared/job-observability-helpers.mjs

@@ -0,0 +1,143 @@
+// Purpose: Provide shared oracle job observability formatting for UI messages, tool responses, and wake-up notifications.
+// Responsibilities: Format job summaries, lifecycle breadcrumbs, submit responses, wake-up notification content, and session status text consistently across channels.
+// Scope: Presentation helpers only; lifecycle mutation, persistence, and browser execution remain in lifecycle/job modules.
+// Usage: Imported by commands, tools, poller, and extension startup/status code to keep detached-oracle messaging consistent.
+// Invariants/Assumptions: Job summaries read from durable job state, and lifecycle event trails are bounded and already normalized by shared lifecycle helpers.
+
+import { getLatestOracleJobLifecycleEvent } from "./job-lifecycle-helpers.mjs";
+
+/** @typedef {import("./job-observability-helpers.d.mts").OracleJobSummaryLike} OracleJobSummaryLike */
+/** @typedef {import("./job-observability-helpers.d.mts").OracleJobSummaryOptions} OracleJobSummaryOptions */
+/** @typedef {import("./job-observability-helpers.d.mts").OracleStatusCounts} OracleStatusCounts */
+/** @typedef {import("./job-observability-helpers.d.mts").OracleSubmitResponseOptions} OracleSubmitResponseOptions */
+/** @typedef {import("./job-lifecycle-helpers.d.mts").OracleJobLifecycleEvent} OracleJobLifecycleEvent */
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
+  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let value = bytes;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+  return `${value >= 10 || unitIndex === 0 ? value.toFixed(0) : value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+/**
+ * @param {OracleJobLifecycleEvent | undefined} event
+ * @returns {string | undefined}
+ */
+export function formatOracleLifecycleEvent(event) {
+  if (!event) return undefined;
+  return `${event.at} [${event.source}] ${event.message}`;
+}
+
+/**
+ * @param {Array<{ relativePath: string; bytes: number }>} autoPrunedPrefixes
+ * @returns {string | undefined}
+ */
+function formatAutoPrunedArchiveMessage(autoPrunedPrefixes) {
+  if (autoPrunedPrefixes.length === 0) return undefined;
+  return `Archive auto-pruned generic generated-output-name dirs to fit size limit: ${autoPrunedPrefixes.map((entry) => `${entry.relativePath}/ (${formatBytes(entry.bytes)})`).join(", ")}`;
+}
+
+/**
+ * @param {OracleJobSummaryLike} job
+ * @param {OracleJobSummaryOptions} [options]
+ * @returns {string}
+ */
+export function formatOracleJobSummary(job, options = {}) {
+  const latestEvent = options.includeLatestEvent === false ? undefined : formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job));
+  return [
+    `job: ${job.id}`,
+    `status: ${job.status}`,
+    `phase: ${job.phase}`,
+    `created: ${job.createdAt}`,
+    job.queuedAt ? `queued: ${job.queuedAt}` : undefined,
+    job.submittedAt ? `submitted: ${job.submittedAt}` : undefined,
+    options.queuePosition ? `queue-position: ${options.queuePosition.position} of ${options.queuePosition.depth} global` : undefined,
+    `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,
+    options.artifactsPath ? `artifacts: ${options.artifactsPath}` : undefined,
+    typeof job.artifactFailureCount === "number" ? `artifact-failures: ${job.artifactFailureCount}` : undefined,
+    options.includeWorkerLogPath === false ? undefined : job.workerLogPath ? `worker-log: ${job.workerLogPath}` : undefined,
+    job.lastCleanupAt ? `last-cleanup: ${job.lastCleanupAt}` : undefined,
+    job.cleanupWarnings?.length ? `cleanup-warnings: ${job.cleanupWarnings.join(" | ")}` : undefined,
+    latestEvent ? `last-event: ${latestEvent}` : undefined,
+    job.error ? `error: ${job.error}` : undefined,
+    options.responsePreview ? "" : undefined,
+    options.responsePreview,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/**
+ * @param {OracleJobSummaryLike} job
+ * @param {{ responsePath?: string; artifactsPath?: string }} [options]
+ * @returns {string}
+ */
+export function buildOracleWakeupNotificationContent(job, options = {}) {
+  const responsePath = options.responsePath ?? job.responsePath ?? `response unavailable for ${job.id}`;
+  const artifactsPath = options.artifactsPath ?? `artifacts unavailable for ${job.id}`;
+  return [
+    `Oracle job ${job.id} is ${job.status}.`,
+    `Use oracle_read with jobId ${job.id} to open the response and settle wake-up retries.`,
+    `Response file: ${responsePath}`,
+    `Artifacts: ${artifactsPath}`,
+    formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job)) ? `Last event: ${formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job))}` : undefined,
+    job.error ? `Error: ${job.error}` : "After oracle_read, continue from the oracle output.",
+  ].filter(Boolean).join("\n");
+}
+
+/**
+ * @param {OracleJobSummaryLike & { promptPath: string; archivePath: string }} job
+ * @param {OracleSubmitResponseOptions} options
+ * @returns {string}
+ */
+export function formatOracleSubmitResponse(job, options) {
+  return [
+    `${options.queued ? "Oracle job queued" : "Oracle job dispatched"}: ${job.id}`,
+    options.queued && options.queuePosition && options.queueDepth ? `Queue position: ${options.queuePosition} of ${options.queueDepth}` : undefined,
+    job.followUpToJobId ? `Follow-up to: ${job.followUpToJobId}` : undefined,
+    `Prompt: ${job.promptPath}`,
+    `Archive: ${job.archivePath}`,
+    formatAutoPrunedArchiveMessage(options.autoPrunedPrefixes),
+    `Response will be written to: ${job.responsePath}`,
+    formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job)) ? `Last event: ${formatOracleLifecycleEvent(getLatestOracleJobLifecycleEvent(job))}` : undefined,
+    options.queued ? "The job will start automatically when capacity is available." : undefined,
+    "Stop now and wait for the oracle completion wake-up.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/**
+ * @param {OracleStatusCounts} counts
+ * @returns {string}
+ */
+export function buildOracleStatusText(counts) {
+  if (counts.active > 0 && counts.queued > 0) {
+    return `oracle: running (${counts.active}), queued (${counts.queued})`;
+  }
+  if (counts.active > 0) {
+    const suffix = counts.active > 1 ? ` (${counts.active})` : "";
+    return `oracle: running${suffix}`;
+  }
+  if (counts.queued > 0) {
+    const suffix = counts.queued > 1 ? ` (${counts.queued})` : "";
+    return `oracle: queued${suffix}`;
+  }
+  return "oracle: ready";
+}

package/extensions/oracle/shared/process-helpers.d.mts

@@ -0,0 +1,20 @@
+export interface OracleTrackedProcessOptions {
+  termGraceMs?: number;
+  killGraceMs?: number;
+}
+
+export interface OracleDetachedProcessHandle {
+  pid: number | undefined;
+  startedAt?: string;
+}
+
+export declare function readProcessStartedAt(pid: number | undefined): string | undefined;
+export declare function isProcessAlive(pid: number | undefined): boolean;
+export declare function isTrackedProcessAlive(pid: number | undefined, startedAt?: string): boolean;
+export declare function waitForProcessStartedAt(pid: number | undefined, timeoutMs?: number): Promise<string | undefined>;
+export declare function terminateTrackedProcess(
+  pid: number | undefined,
+  startedAt?: string,
+  options?: OracleTrackedProcessOptions,
+): Promise<boolean>;
+export declare function spawnDetachedNodeProcess(scriptPath: string, args?: string[]): Promise<OracleDetachedProcessHandle>;

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>;