pi-oracle 0.3.4 → 0.5.0

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

@@ -0,0 +1,84 @@
+export interface OracleDurableWorkerHandoffJobLike {
+  status?: string;
+  workerPid?: number;
+}
+
+export interface OracleAdmissionBlockingJobLike extends OracleDurableWorkerHandoffJobLike {
+  cleanupPending?: boolean;
+  workerStartedAt?: string;
+}
+
+export interface OracleRuntimeLeaseMetadataLike {
+  jobId: string;
+  runtimeId: string;
+  runtimeSessionName: string;
+  runtimeProfileDir: string;
+  projectId: string;
+  sessionId: string;
+  createdAt: string;
+}
+
+export interface OracleConversationLeaseMetadataLike {
+  jobId: string;
+  conversationId: string;
+  projectId: string;
+  sessionId: string;
+  createdAt: string;
+}
+
+export interface OracleQueuedPromotionFailureContext<TJob, TWorker> {
+  job: TJob;
+  latest?: TJob;
+  error: unknown;
+  at: string;
+  spawnedWorker?: TWorker;
+  runtimeLeaseAcquired: boolean;
+  conversationLeaseAcquired: boolean;
+}
+
+export type OracleQueuedPromotionFailureOutcome = void | "break";
+
+export interface OracleQueuedPromotionOptions<TJob extends { id: string; archivePath: string }, TWorker> {
+  listQueuedJobs: () => TJob[];
+  refreshJob: (jobId: string) => TJob | undefined;
+  readLatestJob: (jobId: string) => TJob | undefined;
+  isQueuedJob?: (job: TJob | undefined) => boolean;
+  acquireRuntimeLease: (job: TJob, at: string) => Promise<boolean>;
+  acquireConversationLease: (job: TJob, at: string) => Promise<boolean>;
+  releaseRuntimeLease: (job: TJob) => Promise<void>;
+  markSubmitted: (job: TJob, at: string) => Promise<void>;
+  spawnWorker: (job: TJob) => Promise<TWorker>;
+  persistWorker: (job: TJob, worker: TWorker) => Promise<void>;
+  hasDurableWorkerHandoff?: (job: TJob | undefined) => boolean;
+  isTerminalJob: (job: TJob) => boolean;
+  failQueuedPromotion: (job: TJob, message: string, at: string) => Promise<void>;
+  terminateSpawnedWorker: (worker: TWorker) => Promise<void>;
+  cleanupAfterFailure: (context: OracleQueuedPromotionFailureContext<TJob, TWorker>) => Promise<OracleQueuedPromotionFailureOutcome>;
+  onDurableHandoff?: (job: TJob, latest?: TJob) => Promise<void> | void;
+}
+
+export declare function isQueuedOracleJob(job: OracleDurableWorkerHandoffJobLike | undefined): boolean;
+export declare function compareQueuedOracleJobs(
+  left: { createdAt: string; queuedAt?: string; id: string },
+  right: { createdAt: string; queuedAt?: string; id: string },
+): number;
+export declare function hasDurableWorkerHandoff(job: OracleDurableWorkerHandoffJobLike | undefined): boolean;
+export declare function hasAdmissionBlockingWorker(
+  job: OracleAdmissionBlockingJobLike | undefined,
+  isTrackedProcessAliveFn?: (pid: number | undefined, startedAt?: string) => boolean,
+): boolean;
+export declare function jobBlocksAdmission(
+  job: OracleAdmissionBlockingJobLike | undefined,
+  isTrackedProcessAliveFn?: (pid: number | undefined, startedAt?: string) => boolean,
+): boolean;
+export declare function buildRuntimeLeaseMetadata(
+  job: { id: string; runtimeId: string; runtimeSessionName: string; runtimeProfileDir: string; projectId: string; sessionId: string },
+  createdAt: string,
+): OracleRuntimeLeaseMetadataLike;
+export declare function buildConversationLeaseMetadata(
+  job: { id: string; conversationId?: string; projectId: string; sessionId: string },
+  createdAt: string,
+): OracleConversationLeaseMetadataLike | undefined;
+export declare function runQueuedJobPromotionPass<TJob extends { id: string; archivePath: string }, TWorker>(
+  options: OracleQueuedPromotionOptions<TJob, TWorker>,
+): Promise<{ promotedJobIds: string[] }>;

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

@@ -0,0 +1,168 @@
+// Purpose: Provide shared oracle job coordination helpers for admission control, lease metadata, and queued promotion orchestration.
+// Responsibilities: Normalize queue ordering, derive lease metadata, detect durable handoff/admission blockers, and run a single queued-promotion pass.
+// Scope: Pure coordination/state-machine logic only; filesystem I/O and job persistence remain in injected callbacks.
+// Usage: Imported by lib/queue.ts, lib/runtime.ts, lib/jobs.ts, and worker/run-job.mjs to keep concurrency semantics aligned.
+// Invariants/Assumptions: Queued jobs have durable ids/archive paths, and callers provide side-effect callbacks that preserve atomic job updates.
+
+import { existsSync } from "node:fs";
+import { isTrackedProcessAlive } from "./process-helpers.mjs";
+
+/** @typedef {import("./job-coordination-helpers.d.mts").OracleAdmissionBlockingJobLike} OracleAdmissionBlockingJobLike */
+/** @typedef {import("./job-coordination-helpers.d.mts").OracleConversationLeaseMetadataLike} OracleConversationLeaseMetadataLike */
+/** @typedef {import("./job-coordination-helpers.d.mts").OracleDurableWorkerHandoffJobLike} OracleDurableWorkerHandoffJobLike */
+/** @typedef {import("./job-coordination-helpers.d.mts").OracleRuntimeLeaseMetadataLike} OracleRuntimeLeaseMetadataLike */
+
+/**
+ * @param {OracleDurableWorkerHandoffJobLike | undefined} job
+ * @returns {boolean}
+ */
+export function isQueuedOracleJob(job) {
+  return job?.status === "queued";
+}
+
+/**
+ * @param {{ createdAt: string; queuedAt?: string; id: string }} left
+ * @param {{ createdAt: string; queuedAt?: string; id: string }} right
+ * @returns {number}
+ */
+export function compareQueuedOracleJobs(left, right) {
+  const leftKey = left.queuedAt ?? left.createdAt;
+  const rightKey = right.queuedAt ?? right.createdAt;
+  return leftKey.localeCompare(rightKey) || left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id);
+}
+
+/**
+ * @param {OracleDurableWorkerHandoffJobLike | undefined} job
+ * @returns {boolean}
+ */
+export function hasDurableWorkerHandoff(job) {
+  if (!job || job.status === "queued") return false;
+  if (job.workerPid) return true;
+  return false;
+}
+
+/**
+ * @param {OracleAdmissionBlockingJobLike | undefined} job
+ * @param {(pid: number | undefined, startedAt?: string) => boolean} [isTrackedProcessAliveFn]
+ * @returns {boolean}
+ */
+export function hasAdmissionBlockingWorker(job, isTrackedProcessAliveFn = isTrackedProcessAlive) {
+  if (!job?.workerPid) return false;
+  return isTrackedProcessAliveFn(job.workerPid, job.workerStartedAt);
+}
+
+/**
+ * @param {OracleAdmissionBlockingJobLike | undefined} job
+ * @param {(pid: number | undefined, startedAt?: string) => boolean} [isTrackedProcessAliveFn]
+ * @returns {boolean}
+ */
+export function jobBlocksAdmission(job, isTrackedProcessAliveFn = isTrackedProcessAlive) {
+  return ["preparing", "submitted", "waiting"].includes(String(job?.status || "")) ||
+    job?.cleanupPending === true ||
+    hasAdmissionBlockingWorker(job, isTrackedProcessAliveFn);
+}
+
+/**
+ * @param {{ id: string; runtimeId: string; runtimeSessionName: string; runtimeProfileDir: string; projectId: string; sessionId: string }} job
+ * @param {string} createdAt
+ * @returns {OracleRuntimeLeaseMetadataLike}
+ */
+export function buildRuntimeLeaseMetadata(job, createdAt) {
+  return {
+    jobId: job.id,
+    runtimeId: job.runtimeId,
+    runtimeSessionName: job.runtimeSessionName,
+    runtimeProfileDir: job.runtimeProfileDir,
+    projectId: job.projectId,
+    sessionId: job.sessionId,
+    createdAt,
+  };
+}
+
+/**
+ * @param {{ id: string; conversationId?: string; projectId: string; sessionId: string }} job
+ * @param {string} createdAt
+ * @returns {OracleConversationLeaseMetadataLike | undefined}
+ */
+export function buildConversationLeaseMetadata(job, createdAt) {
+  if (!job.conversationId) return undefined;
+  return {
+    jobId: job.id,
+    conversationId: job.conversationId,
+    projectId: job.projectId,
+    sessionId: job.sessionId,
+    createdAt,
+  };
+}
+
+/**
+ * @template {{ id: string; archivePath: string }} TJob
+ * @template TWorker
+ * @param {import("./job-coordination-helpers.d.mts").OracleQueuedPromotionOptions<TJob, TWorker>} options
+ * @returns {Promise<{ promotedJobIds: string[] }>}
+ */
+export async function runQueuedJobPromotionPass(options) {
+  const promotedJobIds = [];
+  const isQueuedJob = options.isQueuedJob ?? isQueuedOracleJob;
+  const durableHandoff = options.hasDurableWorkerHandoff ?? hasDurableWorkerHandoff;
+
+  for (const queuedJob of options.listQueuedJobs()) {
+    const promotedAt = new Date().toISOString();
+    let runtimeLeaseAcquired = false;
+    let conversationLeaseAcquired = false;
+    /** @type {TWorker | undefined} */
+    let spawnedWorker;
+
+    try {
+      const current = options.refreshJob(queuedJob.id);
+      if (!isQueuedJob(current)) continue;
+      if (!existsSync(current.archivePath)) {
+        await options.failQueuedPromotion(current, `Queued oracle archive is missing: ${current.archivePath}`, promotedAt);
+        continue;
+      }
+
+      const runtimeAttempt = await options.acquireRuntimeLease(current, promotedAt);
+      if (!runtimeAttempt) break;
+      runtimeLeaseAcquired = true;
+
+      const conversationAttempt = await options.acquireConversationLease(current, promotedAt);
+      if (!conversationAttempt) {
+        await options.releaseRuntimeLease(current).catch(() => undefined);
+        runtimeLeaseAcquired = false;
+        continue;
+      }
+      conversationLeaseAcquired = true;
+
+      await options.markSubmitted(current, promotedAt);
+      spawnedWorker = await options.spawnWorker(current);
+      await options.persistWorker(current, spawnedWorker);
+      promotedJobIds.push(current.id);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const latest = options.readLatestJob(queuedJob.id);
+      if (spawnedWorker && durableHandoff(latest)) {
+        promotedJobIds.push(queuedJob.id);
+        await options.onDurableHandoff?.(queuedJob, latest);
+        continue;
+      }
+      if (spawnedWorker) {
+        await options.terminateSpawnedWorker(spawnedWorker).catch(() => undefined);
+      }
+      if (latest && !options.isTerminalJob(latest)) {
+        await options.failQueuedPromotion(latest, message, promotedAt);
+      }
+      const failureOutcome = await options.cleanupAfterFailure({
+        job: queuedJob,
+        latest,
+        error,
+        at: promotedAt,
+        spawnedWorker,
+        runtimeLeaseAcquired,
+        conversationLeaseAcquired,
+      });
+      if (failureOutcome === "break") break;
+    }
+  }
+
+  return { promotedJobIds };
+}

package/extensions/oracle/shared/job-lifecycle-helpers.d.mts

@@ -0,0 +1,131 @@
+export type OracleJobStatus = "queued" | "preparing" | "submitted" | "waiting" | "complete" | "failed" | "cancelled";
+
+export type OracleJobPhase =
+  | "queued"
+  | "submitted"
+  | "cloning_runtime"
+  | "launching_browser"
+  | "verifying_auth"
+  | "configuring_model"
+  | "uploading_archive"
+  | "awaiting_response"
+  | "extracting_response"
+  | "downloading_artifacts"
+  | "complete"
+  | "complete_with_artifact_errors"
+  | "failed"
+  | "cancelled";
+
+export interface OracleJobLifecycleEvent {
+  at: string;
+  source: string;
+  kind: "created" | "phase" | "cleanup" | "notification" | "wakeup";
+  status: OracleJobStatus;
+  phase: OracleJobPhase;
+  message: string;
+}
+
+export interface OracleLifecycleTrackedJobLike {
+  status: OracleJobStatus;
+  phase: OracleJobPhase;
+  phaseAt: string;
+  createdAt: string;
+  queuedAt?: string;
+  submittedAt?: string;
+  completedAt?: string;
+  heartbeatAt?: string;
+  lifecycleEvents?: OracleJobLifecycleEvent[];
+  cleanupPending?: boolean;
+  cleanupWarnings?: string[];
+  lastCleanupAt?: string;
+  notifyClaimedAt?: string;
+  notifyClaimedBy?: string;
+  notifiedAt?: string;
+  notificationEntryId?: string;
+  notificationSessionKey?: string;
+  notificationSessionFile?: string;
+  wakeupAttemptCount?: number;
+  wakeupLastRequestedAt?: string;
+  wakeupSettledAt?: string;
+  wakeupSettledSource?: string;
+  wakeupSettledSessionFile?: string;
+  wakeupSettledSessionKey?: string;
+  wakeupSettledBeforeFirstAttempt?: boolean;
+  wakeupObservedAt?: string;
+  wakeupObservedSource?: string;
+  wakeupObservedSessionFile?: string;
+  wakeupObservedSessionKey?: string;
+  error?: string;
+  artifactFailureCount?: number;
+  responsePath?: string;
+  responseFormat?: "text/plain";
+}
+
+export interface OraclePhaseTransitionOptions<TJob extends OracleLifecycleTrackedJobLike> {
+  at?: string;
+  source?: string;
+  message?: string;
+  patch?: Partial<TJob>;
+  clearNotificationClaim?: boolean;
+}
+
+export interface OracleWakeupSettlementOptions {
+  source: string;
+  at?: string;
+  sessionFile?: string;
+  sessionKey?: string;
+  allowBeforeFirstAttempt?: boolean;
+}
+
+export interface OracleNotificationTargetOptions {
+  at?: string;
+  source?: string;
+  notificationSessionKey: string;
+  notificationSessionFile?: string;
+}
+
+export interface OracleMarkNotifiedOptions {
+  at?: string;
+  source?: string;
+  notificationEntryId?: string;
+  notificationSessionKey?: string;
+  notificationSessionFile?: string;
+}
+
+export const ACTIVE_ORACLE_JOB_STATUSES: readonly OracleJobStatus[];
+export const OPEN_ORACLE_JOB_STATUSES: readonly OracleJobStatus[];
+export const TERMINAL_ORACLE_JOB_STATUSES: readonly OracleJobStatus[];
+export const MAX_ORACLE_JOB_LIFECYCLE_EVENTS: number;
+
+export declare function getOracleJobStatusForPhase(phase: OracleJobPhase): OracleJobStatus;
+export declare function assertValidOracleJobState<TJob extends OracleLifecycleTrackedJobLike>(job: TJob): TJob;
+export declare function appendOracleJobLifecycleEvent<TJob extends OracleLifecycleTrackedJobLike>(
+  job: TJob,
+  event: Omit<OracleJobLifecycleEvent, "status" | "phase"> & { status?: OracleJobStatus; phase?: OracleJobPhase },
+): TJob;
+export declare function getLatestOracleJobLifecycleEvent(job: Pick<OracleLifecycleTrackedJobLike, "lifecycleEvents">): OracleJobLifecycleEvent | undefined;
+export declare function getLatestOracleTerminalLifecycleEvent(job: Pick<OracleLifecycleTrackedJobLike, "lifecycleEvents">): OracleJobLifecycleEvent | undefined;
+export declare function markOracleJobCreated<TJob extends OracleLifecycleTrackedJobLike>(job: TJob, options?: { at?: string; source?: string; message?: string }): TJob;
+export declare function transitionOracleJobPhase<TJob extends OracleLifecycleTrackedJobLike>(
+  job: TJob,
+  phase: OracleJobPhase,
+  options?: OraclePhaseTransitionOptions<TJob>,
+): TJob;
+export declare function applyOracleJobCleanupWarnings<TJob extends OracleLifecycleTrackedJobLike>(
+  job: TJob,
+  warnings: string[],
+  options?: { at?: string; source?: string; message?: string },
+): TJob;
+export declare function clearOracleJobCleanupState<TJob extends OracleLifecycleTrackedJobLike>(
+  job: TJob,
+  options?: { at?: string; source?: string; message?: string },
+): TJob;
+export declare function claimOracleJobNotification<TJob extends OracleLifecycleTrackedJobLike>(job: TJob, claimedBy: string, at?: string): TJob;
+export declare function recordOracleJobNotificationTarget<TJob extends OracleLifecycleTrackedJobLike>(job: TJob, options: OracleNotificationTargetOptions): TJob;
+export declare function markOracleJobNotified<TJob extends OracleLifecycleTrackedJobLike>(job: TJob, options?: OracleMarkNotifiedOptions): TJob;
+export declare function releaseOracleJobNotificationClaim<TJob extends OracleLifecycleTrackedJobLike>(job: TJob): TJob;
+export declare function noteOracleJobWakeupRequested<TJob extends OracleLifecycleTrackedJobLike>(job: TJob, options?: { at?: string; source?: string }): TJob;
+export declare function markOracleJobWakeupSettled<TJob extends OracleLifecycleTrackedJobLike>(
+  job: TJob,
+  options: OracleWakeupSettlementOptions,
+): TJob;