pi-oracle 0.3.4 → 0.4.0

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

@@ -0,0 +1,130 @@
+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 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;

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

@@ -0,0 +1,377 @@
+// Purpose: Centralize oracle job lifecycle state transitions, invariants, and durable transition breadcrumbs.
+// Responsibilities: Define valid phase/status relationships, apply lifecycle mutations, append bounded lifecycle events, and normalize cleanup/notification/wake-up state changes.
+// Scope: Pure job-state reducers only; persistence, locking, browser work, and UI delivery stay in higher-level modules.
+// Usage: Imported by extension lib code and worker code so all lifecycle transitions share the same invariants and event semantics.
+// Invariants/Assumptions: Phase/status pairs must stay aligned, terminal jobs own completedAt, and cleanupPending is only legal for terminal states.
+
+/** @typedef {import("./job-lifecycle-helpers.d.mts").OracleJobLifecycleEvent} OracleJobLifecycleEvent */
+/** @typedef {import("./job-lifecycle-helpers.d.mts").OracleJobPhase} OracleJobPhase */
+/** @typedef {import("./job-lifecycle-helpers.d.mts").OracleJobStatus} OracleJobStatus */
+/** @typedef {import("./job-lifecycle-helpers.d.mts").OracleLifecycleTrackedJobLike} OracleLifecycleTrackedJobLike */
+
+export const ACTIVE_ORACLE_JOB_STATUSES = Object.freeze(["preparing", "submitted", "waiting"]);
+export const OPEN_ORACLE_JOB_STATUSES = Object.freeze(["queued", ...ACTIVE_ORACLE_JOB_STATUSES]);
+export const TERMINAL_ORACLE_JOB_STATUSES = Object.freeze(["complete", "failed", "cancelled"]);
+export const MAX_ORACLE_JOB_LIFECYCLE_EVENTS = 64;
+
+/** @type {Record<OracleJobPhase, OracleJobStatus>} */
+const PHASE_STATUS = Object.freeze({
+  queued: "queued",
+  submitted: "submitted",
+  cloning_runtime: "waiting",
+  launching_browser: "waiting",
+  verifying_auth: "waiting",
+  configuring_model: "waiting",
+  uploading_archive: "waiting",
+  awaiting_response: "waiting",
+  extracting_response: "waiting",
+  downloading_artifacts: "waiting",
+  complete: "complete",
+  complete_with_artifact_errors: "complete",
+  failed: "failed",
+  cancelled: "cancelled",
+});
+
+/**
+ * @param {OracleJobPhase} phase
+ * @returns {OracleJobStatus}
+ */
+export function getOracleJobStatusForPhase(phase) {
+  return PHASE_STATUS[phase];
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @returns {TJob}
+ */
+export function assertValidOracleJobState(job) {
+  const expectedStatus = PHASE_STATUS[job.phase];
+  if (!expectedStatus) {
+    throw new Error(`Invalid oracle job state: unknown phase ${String(job.phase)}`);
+  }
+  if (job.status !== expectedStatus) {
+    throw new Error(`Invalid oracle job state: phase ${job.phase} requires status ${expectedStatus}, got ${job.status}`);
+  }
+  if (job.status === "queued" && !job.queuedAt) {
+    throw new Error("Invalid oracle job state: queued jobs must record queuedAt");
+  }
+  if (["submitted", "waiting"].includes(job.status) && !job.submittedAt) {
+    throw new Error(`Invalid oracle job state: ${job.status} jobs must record submittedAt`);
+  }
+  if (TERMINAL_ORACLE_JOB_STATUSES.includes(job.status) && !job.completedAt) {
+    throw new Error(`Invalid oracle job state: terminal job ${job.status} must record completedAt`);
+  }
+  if (job.completedAt && !TERMINAL_ORACLE_JOB_STATUSES.includes(job.status)) {
+    throw new Error(`Invalid oracle job state: non-terminal job ${job.status} cannot record completedAt`);
+  }
+  if (job.cleanupPending && !TERMINAL_ORACLE_JOB_STATUSES.includes(job.status)) {
+    throw new Error(`Invalid oracle job state: non-terminal job ${job.status} cannot be cleanupPending`);
+  }
+  return job;
+}
+
+/**
+ * @param {Pick<OracleLifecycleTrackedJobLike, "phase" | "status" | "lifecycleEvents">} job
+ * @param {Omit<OracleJobLifecycleEvent, "status" | "phase"> & { status?: OracleJobStatus; phase?: OracleJobPhase }} event
+ * @returns {OracleJobLifecycleEvent[]}
+ */
+function nextLifecycleEvents(job, event) {
+  const entry = {
+    at: event.at,
+    source: event.source,
+    kind: event.kind,
+    message: event.message,
+    status: event.status ?? job.status,
+    phase: event.phase ?? job.phase,
+  };
+  const events = [...(job.lifecycleEvents || []), entry];
+  return events.slice(-MAX_ORACLE_JOB_LIFECYCLE_EVENTS);
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {Omit<OracleJobLifecycleEvent, "status" | "phase"> & { status?: OracleJobStatus; phase?: OracleJobPhase }} event
+ * @returns {TJob}
+ */
+export function appendOracleJobLifecycleEvent(job, event) {
+  return assertValidOracleJobState({
+    ...job,
+    lifecycleEvents: nextLifecycleEvents(job, event),
+  });
+}
+
+/**
+ * @param {Pick<OracleLifecycleTrackedJobLike, "lifecycleEvents">} job
+ * @returns {OracleJobLifecycleEvent | undefined}
+ */
+export function getLatestOracleJobLifecycleEvent(job) {
+  const events = job.lifecycleEvents || [];
+  return events.length > 0 ? events[events.length - 1] : undefined;
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {{ at?: string; source?: string; message?: string }} [options]
+ * @returns {TJob}
+ */
+export function markOracleJobCreated(job, options = {}) {
+  const at = options.at ?? job.createdAt;
+  return appendOracleJobLifecycleEvent(assertValidOracleJobState(job), {
+    at,
+    source: options.source ?? "oracle:create",
+    kind: "created",
+    message: options.message ?? `Job created in ${job.status} state.`,
+  });
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {OracleJobPhase} phase
+ * @param {{ at?: string; source?: string; message?: string; patch?: Partial<TJob>; clearNotificationClaim?: boolean }} [options]
+ * @returns {TJob}
+ */
+export function transitionOracleJobPhase(job, phase, options = {}) {
+  const at = options.at ?? new Date().toISOString();
+  const patch = options.patch || {};
+  const status = patch.status ?? getOracleJobStatusForPhase(phase);
+  if (status !== getOracleJobStatusForPhase(phase)) {
+    throw new Error(`Invalid oracle job transition: phase ${phase} requires status ${getOracleJobStatusForPhase(phase)}, got ${String(status)}`);
+  }
+
+  /** @type {TJob} */
+  const next = {
+    ...job,
+    ...patch,
+    status,
+    phase,
+    phaseAt: at,
+    ...(phase === "queued" ? { queuedAt: patch.queuedAt ?? job.queuedAt ?? at } : {}),
+    ...(["submitted", "waiting"].includes(status) || patch.submittedAt !== undefined || job.submittedAt !== undefined
+      ? { submittedAt: patch.submittedAt ?? job.submittedAt ?? at }
+      : {}),
+    ...(TERMINAL_ORACLE_JOB_STATUSES.includes(status)
+      ? { completedAt: patch.completedAt ?? job.completedAt ?? at }
+      : { completedAt: patch.completedAt ?? job.completedAt }),
+    ...(options.clearNotificationClaim
+      ? { notifyClaimedAt: undefined, notifyClaimedBy: undefined }
+      : {}),
+  };
+
+  const validated = assertValidOracleJobState(next);
+  const changed = job.phase !== validated.phase || job.status !== validated.status || Boolean(options.message);
+  if (!changed) return validated;
+
+  return appendOracleJobLifecycleEvent(validated, {
+    at,
+    source: options.source ?? "oracle:lifecycle",
+    kind: "phase",
+    message: options.message ?? `Transitioned to ${validated.phase} (${validated.status}).`,
+  });
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {string[]} warnings
+ * @param {{ at?: string; source?: string; message?: string }} [options]
+ * @returns {TJob}
+ */
+export function applyOracleJobCleanupWarnings(job, warnings, options = {}) {
+  if (warnings.length === 0) return assertValidOracleJobState(job);
+  const at = options.at ?? new Date().toISOString();
+  const next = assertValidOracleJobState({
+    ...job,
+    cleanupPending: false,
+    cleanupWarnings: Array.from(new Set([...(job.cleanupWarnings || []), ...warnings])),
+    lastCleanupAt: at,
+    error: [job.error, ...warnings].filter(Boolean).join("\n"),
+  });
+  return appendOracleJobLifecycleEvent(next, {
+    at,
+    source: options.source ?? "oracle:cleanup",
+    kind: "cleanup",
+    message: options.message ?? `Cleanup completed with ${warnings.length} warning(s).`,
+  });
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {{ at?: string; source?: string; message?: string }} [options]
+ * @returns {TJob}
+ */
+export function clearOracleJobCleanupState(job, options = {}) {
+  const at = options.at ?? new Date().toISOString();
+  const next = assertValidOracleJobState({
+    ...job,
+    cleanupPending: false,
+    cleanupWarnings: undefined,
+    lastCleanupAt: at,
+  });
+  return appendOracleJobLifecycleEvent(next, {
+    at,
+    source: options.source ?? "oracle:cleanup",
+    kind: "cleanup",
+    message: options.message ?? "Cleanup finished without warnings.",
+  });
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {string} claimedBy
+ * @param {string} [at]
+ * @returns {TJob}
+ */
+export function claimOracleJobNotification(job, claimedBy, at = new Date().toISOString()) {
+  return assertValidOracleJobState({
+    ...job,
+    notifyClaimedBy: claimedBy,
+    notifyClaimedAt: at,
+  });
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {{ at?: string; source?: string; notificationSessionKey: string; notificationSessionFile?: string }} options
+ * @returns {TJob}
+ */
+export function recordOracleJobNotificationTarget(job, options) {
+  const at = options.at ?? new Date().toISOString();
+  const next = assertValidOracleJobState({
+    ...job,
+    notificationSessionKey: options.notificationSessionKey,
+    notificationSessionFile: options.notificationSessionFile,
+  });
+  return appendOracleJobLifecycleEvent(next, {
+    at,
+    source: options.source ?? "oracle:poller",
+    kind: "notification",
+    message: `Notification target recorded for ${options.notificationSessionKey}.`,
+  });
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {{ at?: string; source?: string; notificationEntryId?: string; notificationSessionKey?: string; notificationSessionFile?: string }} [options]
+ * @returns {TJob}
+ */
+export function markOracleJobNotified(job, options = {}) {
+  const at = options.at ?? new Date().toISOString();
+  const next = assertValidOracleJobState({
+    ...job,
+    notifiedAt: at,
+    notificationEntryId: options.notificationEntryId ?? job.notificationEntryId,
+    notificationSessionKey: options.notificationSessionKey ?? job.notificationSessionKey,
+    notificationSessionFile: options.notificationSessionFile ?? job.notificationSessionFile,
+    wakeupAttemptCount: 0,
+    wakeupLastRequestedAt: undefined,
+    wakeupSettledAt: undefined,
+    notifyClaimedAt: undefined,
+    notifyClaimedBy: undefined,
+  });
+  return appendOracleJobLifecycleEvent(next, {
+    at,
+    source: options.source ?? "oracle:poller",
+    kind: "notification",
+    message: "Notification delivery recorded.",
+  });
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @returns {TJob}
+ */
+export function releaseOracleJobNotificationClaim(job) {
+  return assertValidOracleJobState({
+    ...job,
+    notifyClaimedAt: undefined,
+    notifyClaimedBy: undefined,
+  });
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {{ at?: string; source?: string }} [options]
+ * @returns {TJob}
+ */
+export function noteOracleJobWakeupRequested(job, options = {}) {
+  const at = options.at ?? new Date().toISOString();
+  const next = assertValidOracleJobState({
+    ...job,
+    wakeupAttemptCount: (job.wakeupAttemptCount ?? 0) + 1,
+    wakeupLastRequestedAt: at,
+  });
+  return appendOracleJobLifecycleEvent(next, {
+    at,
+    source: options.source ?? "oracle:poller",
+    kind: "wakeup",
+    message: `Wake-up reminder requested (attempt ${next.wakeupAttemptCount}).`,
+  });
+}
+
+/**
+ * @template {OracleLifecycleTrackedJobLike} TJob
+ * @param {TJob} job
+ * @param {{ source: string; at?: string; sessionFile?: string; sessionKey?: string; allowBeforeFirstAttempt?: boolean }} options
+ * @returns {TJob}
+ */
+export function markOracleJobWakeupSettled(job, options) {
+  const at = options.at ?? new Date().toISOString();
+  const beforeFirstAttempt = !job.wakeupLastRequestedAt && (job.wakeupAttemptCount ?? 0) === 0;
+
+  if (job.wakeupSettledAt) {
+    const next = assertValidOracleJobState({
+      ...job,
+      wakeupSettledSource: job.wakeupSettledSource ?? options.source,
+      wakeupSettledSessionFile: job.wakeupSettledSessionFile ?? options.sessionFile,
+      wakeupSettledSessionKey: job.wakeupSettledSessionKey ?? options.sessionKey,
+      wakeupSettledBeforeFirstAttempt: job.wakeupSettledBeforeFirstAttempt ?? beforeFirstAttempt,
+    });
+    return appendOracleJobLifecycleEvent(next, {
+      at,
+      source: options.source,
+      kind: "wakeup",
+      message: `Wake-up already settled via ${next.wakeupSettledSource ?? options.source}.`,
+    });
+  }
+
+  if (beforeFirstAttempt && !options.allowBeforeFirstAttempt) {
+    const observed = assertValidOracleJobState({
+      ...job,
+      wakeupObservedAt: job.wakeupObservedAt ?? at,
+      wakeupObservedSource: job.wakeupObservedSource ?? options.source,
+      wakeupObservedSessionFile: job.wakeupObservedSessionFile ?? options.sessionFile,
+      wakeupObservedSessionKey: job.wakeupObservedSessionKey ?? options.sessionKey,
+    });
+    return appendOracleJobLifecycleEvent(observed, {
+      at,
+      source: options.source,
+      kind: "wakeup",
+      message: `Wake-up observed before the first reminder attempt via ${options.source}.`,
+    });
+  }
+
+  const settled = assertValidOracleJobState({
+    ...job,
+    wakeupSettledAt: at,
+    wakeupSettledSource: options.source,
+    wakeupSettledSessionFile: options.sessionFile,
+    wakeupSettledSessionKey: options.sessionKey,
+    wakeupSettledBeforeFirstAttempt: beforeFirstAttempt,
+  });
+  return appendOracleJobLifecycleEvent(settled, {
+    at,
+    source: options.source,
+    kind: "wakeup",
+    message: `Wake-up settled via ${options.source}.`,
+  });
+}

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

@@ -0,0 +1,59 @@
+import type { OracleJobLifecycleEvent } from "./job-lifecycle-helpers.d.mts";
+
+export interface OracleJobSummaryLike {
+  id: string;
+  status: string;
+  phase: string;
+  createdAt: string;
+  queuedAt?: string;
+  submittedAt?: string;
+  completedAt?: string;
+  projectId: string;
+  sessionId: string;
+  followUpToJobId?: string;
+  chatUrl?: string;
+  conversationId?: string;
+  responsePath?: string;
+  responseFormat?: string;
+  artifactFailureCount?: number;
+  lastCleanupAt?: string;
+  cleanupWarnings?: string[];
+  error?: string;
+  workerLogPath?: string;
+  lifecycleEvents?: OracleJobLifecycleEvent[];
+}
+
+export interface OracleQueuePositionLike {
+  position: number;
+  depth: number;
+}
+
+export interface OracleJobSummaryOptions {
+  queuePosition?: OracleQueuePositionLike;
+  artifactsPath?: string;
+  responsePreview?: string;
+  includeLatestEvent?: boolean;
+  includeWorkerLogPath?: boolean;
+}
+
+export interface OracleSubmitResponseOptions {
+  autoPrunedPrefixes: Array<{ relativePath: string; bytes: number }>;
+  queued: boolean;
+  queuePosition?: number;
+  queueDepth?: number;
+}
+
+export interface OracleStatusCounts {
+  active: number;
+  queued: number;
+}
+
+export declare function formatBytes(bytes: number): string;
+export declare function formatOracleLifecycleEvent(event: OracleJobLifecycleEvent | undefined): string | undefined;
+export declare function formatOracleJobSummary(job: OracleJobSummaryLike, options?: OracleJobSummaryOptions): string;
+export declare function buildOracleWakeupNotificationContent(
+  job: OracleJobSummaryLike,
+  options?: { responsePath?: string; artifactsPath?: string },
+): string;
+export declare function formatOracleSubmitResponse(job: OracleJobSummaryLike & { promptPath: string; archivePath: string }, options: OracleSubmitResponseOptions): string;
+export declare function buildOracleStatusText(counts: OracleStatusCounts): string;