@osolmaz/pi-workflows 0.15.2 → 0.16.0

package/src/client/view.ts

@@ -0,0 +1,138 @@
+import type { JsonValue } from "../state/json.js";
+
+export const RUN_VIEW_SCHEMA = "pi-workflows.run-view.v1" as const;
+export const SESSION_VIEW_SCHEMA = "pi-workflows.session-view.v1" as const;
+
+export type WorkflowDisplayStatus =
+  | "queued"
+  | "running"
+  | "waiting"
+  | "paused"
+  | "completed"
+  | "failed"
+  | "timed_out"
+  | "cancelled"
+  | "ambiguous";
+
+export type WorkflowDisplay = {
+  status: WorkflowDisplayStatus;
+  activity: "supervised_worker" | "origin_turn" | null;
+  controls: Array<"pause" | "resume" | "cancel" | "answer" | "review">;
+  reason: string | null;
+  reasonContent?: JsonValue;
+};
+
+export type WorkflowRunQueueView = {
+  runId: string;
+  workflowName: string;
+  workflowSourceRef: string;
+  initialized: boolean;
+  definitionDigest: string;
+  status: "queued" | "starting" | "running" | "parked" | "done" | "failed" | "cancelled";
+  originSessionId: string | null;
+  executionMode: "interactive" | "headless";
+  parentRunId: string | null;
+  errorCode: string | null;
+  createdAt: string;
+  updatedAt: string;
+  startedAt: string | null;
+  finishedAt: string | null;
+};
+
+export type WorkflowRunView = {
+  schema: typeof RUN_VIEW_SCHEMA;
+  runId: string;
+  revision: number;
+  display: WorkflowDisplay;
+  manifest: JsonValue;
+  state: JsonValue;
+  workflow: JsonValue;
+  queue: WorkflowRunQueueView;
+  updates: JsonValue[];
+  graphSteps: JsonValue[];
+  graphStepStart: number;
+  graphStepTotal: number;
+  takenTransitions: string[];
+  graphHistory: JsonValue;
+  takenTransitionStart: number;
+  takenTransitionTotal: number;
+  graphCursor: number;
+  stepStart: number;
+  stepTotal: number;
+  tracePage: JsonValue;
+  session: JsonValue;
+  settingsScopes: JsonValue[];
+  settingsStart: number;
+  settingsTotal: number;
+  followUpQueue: JsonValue;
+  followUpStart: number;
+  followUpTotal: number;
+  updateStart: number;
+  updateTotal: number;
+  live: boolean;
+  possiblyInterrupted: boolean;
+};
+
+export type WorkflowRunListPage = {
+  schema: "pi-workflows.run-list-page.v1";
+  revision: string;
+  start: number;
+  total: number;
+  items: WorkflowRunSummary[];
+};
+
+export type WorkflowRunSummary = {
+  runId: string;
+  workflowName: string;
+  originSessionId: string | null;
+  createdAt: string;
+  updatedAt: string;
+  display: WorkflowDisplay;
+  manifest: JsonValue;
+  live: boolean;
+  possiblyInterrupted: boolean;
+};
+
+export type ClientInteractiveRequest = {
+  requestId: string;
+  runId: string;
+  attemptId: string;
+  targetSessionId: string;
+  kind: "agent" | "assistant" | "decision";
+  contract: JsonValue;
+  revision: number;
+  status: "pending" | "presenting" | "settled" | "cancelled";
+  presenterId: string | null;
+  presentationClaimExpiresAt: string | null;
+  presentationSessionEntryId: string | null;
+  acceptedSubmissionId: string | null;
+  createdAt: string;
+  updatedAt: string;
+  settledAt: string | null;
+  consumedAt: string | null;
+};
+
+export type WorkflowDeliveryAvailability = {
+  notification: boolean;
+  turn: boolean;
+};
+
+export type WorkflowSessionView = {
+  schema: typeof SESSION_VIEW_SCHEMA;
+  sessionId: string;
+  run: WorkflowRunView | null;
+  pendingInteractions: JsonValue[];
+  pendingInteractionStart: number;
+  pendingInteractionTotal: number;
+  deliveries: WorkflowDeliveryAvailability;
+};
+
+export type OriginActivityReport = {
+  sessionId: string;
+  runId: string;
+  requestId: string;
+  deliveryId: string;
+  sessionEntryId: string;
+  sequence: number;
+  state: "started" | "refresh" | "settled";
+};

package/src/controllers/sqlite.ts

@@ -62,6 +62,27 @@ export type WorkflowRunClaimOptions = WorkflowRunReservationOptions & {
   leaseMs: number;
 };
 
+export type WorkflowRunQueueViewRecord = {
+  runId: string;
+  workflowName: string;
+  workflowSourceRef: string;
+  workflowSource: unknown;
+  initialized: boolean;
+  definitionDigest: string;
+  runStateStatus: string;
+  paused: boolean;
+  status: WorkflowRunLaunchStatus;
+  originSessionId: string | null;
+  executionMode: "interactive" | "headless";
+  parentRunId: string | null;
+  errorCode: string | null;
+  errorMessage: string | null;
+  createdAt: string;
+  updatedAt: string;
+  startedAt: string | null;
+  finishedAt: string | null;
+};
+
 export type WorkflowRunQueueRecord = {
   runId: string;
   workflowName: string;
@@ -191,6 +212,7 @@ type RunRow = {
   workflowName: string;
   workflowRef: string;
   runStatus: string;
+  paused: number;
   definitionDigest: Buffer;
   definitionHash: Buffer;
   inputHash: Buffer;
@@ -212,6 +234,34 @@ type RunRow = {
   ownerId: string | null;
   claimExpiresAt: number | null;
 };
+type WorkflowRunViewRow = {
+  runId: string;
+  workflowName: string;
+  workflowRef: string;
+  runStatus: string;
+  paused: number;
+  definitionDigest: Buffer;
+  status: WorkflowRunLaunchStatus;
+  originSessionId: string | null;
+  executionMode: "interactive" | "headless";
+  parentRunId: string | null;
+  errorCode: string | null;
+  errorMessage: string | null;
+  createdAt: number;
+  updatedAt: number;
+  startedAt: number | null;
+  finishedAt: number | null;
+  sourceType: "builtin" | "file";
+  sourceRef: string;
+  sourceRevision: string;
+};
+
+type RunListRevisionRow = {
+  count: number;
+  revisionSum: number;
+  updatedAt: number;
+};
+
 type RunSourceIdentityRow = {
   mountPath: string;
   sourceType: "builtin" | "file";
@@ -1238,6 +1288,40 @@ export class SqliteControllerStore implements ControllerStore {
     return row === undefined ? undefined : this.mapWorkflowRun(row);
   }
 
+  getWorkflowRunView(runId: string): WorkflowRunQueueViewRecord | undefined {
+    const row = this.workflowRunViewRows("WHERE r.run_id = ?", [runId])[0];
+    return row === undefined ? undefined : workflowRunViewRecord(row);
+  }
+
+  workflowRunListRevision(): { total: number; revision: string } {
+    const row = this.state.connection
+      .prepare(
+        `SELECT count(*) AS count, COALESCE(sum(res.revision), 0) AS revisionSum,
+                COALESCE(max(q.updated_at), 0) AS updatedAt
+         FROM runs r JOIN run_queue q ON q.run_id = r.run_id
+         JOIN resources res ON res.resource_id = r.resource_id`,
+      )
+      .get();
+    if (!isRunListRevisionRow(row)) throw new Error("Workflow run list revision is invalid");
+    return {
+      total: row.count,
+      revision: `${row.count}:${row.revisionSum}:${row.updatedAt}`,
+    };
+  }
+
+  listWorkflowRunViews(options: { offset: number; limit: number }): {
+    total: number;
+    revision: string;
+    runs: WorkflowRunQueueViewRecord[];
+  } {
+    const current = this.workflowRunListRevision();
+    const rows = this.workflowRunViewRows("ORDER BY q.created_at DESC LIMIT ? OFFSET ?", [
+      options.limit,
+      options.offset,
+    ]);
+    return { ...current, runs: rows.map(workflowRunViewRecord) };
+  }
+
   workflowRunProjectPath(runId: string): string | undefined {
     const row = this.state.connection
       .prepare(
@@ -1269,11 +1353,11 @@ export class SqliteControllerStore implements ControllerStore {
       clauses.push(`r.run_id NOT IN (${options.excludeRunIds.map(() => "?").join(", ")})`);
       params.push(...options.excludeRunIds);
     }
-    params.push(options.limit ?? 100);
+    if (options.limit !== undefined) params.push(options.limit);
     const rows = this.state.connection
       .prepare(
         workflowRunSelect(
-          `${clauses.length === 0 ? "" : `WHERE ${clauses.join(" AND ")}`} ORDER BY q.created_at DESC LIMIT ?`,
+          `${clauses.length === 0 ? "" : `WHERE ${clauses.join(" AND ")}`} ORDER BY q.created_at DESC${options.limit === undefined ? "" : " LIMIT ?"}`,
         ),
       )
       .all(...params);
@@ -1291,6 +1375,14 @@ export class SqliteControllerStore implements ControllerStore {
     return isRunRow(row) ? this.mapWorkflowRun(row) : undefined;
   }
 
+  findSessionReservationView(sessionId: string): WorkflowRunQueueViewRecord | undefined {
+    const row = this.workflowRunViewRows(
+      "WHERE b.origin_session_id = ? AND q.status NOT IN ('done', 'failed', 'cancelled') ORDER BY q.created_at DESC LIMIT 1",
+      [sessionId],
+    )[0];
+    return row === undefined ? undefined : workflowRunViewRecord(row);
+  }
+
   claimWorkflowRun(options: {
     runId: string;
     runnerId: string;
@@ -1561,6 +1653,104 @@ export class SqliteControllerStore implements ControllerStore {
     return this.releaseRunClaim(options.runId, options.claimToken, "parked", options.now);
   }
 
+  pauseParkedWorkflowRun(options: { runId: string; now?: string }): boolean {
+    const now = epoch(validTimestamp(options.now));
+    return this.state.transaction(() => {
+      const row = this.workflowRunRow(options.runId);
+      if (row === undefined || row.status !== "parked") return false;
+      const lease = this.requireLease(row.resourceId);
+      if (lease.ownerId !== null && lease.expiresAt !== null && lease.expiresAt > now) return false;
+      const pending = this.state.connection
+        .prepare(
+          `SELECT 1 FROM interactive_requests
+           WHERE run_id = ? AND status IN ('pending', 'presenting') LIMIT 1`,
+        )
+        .get(options.runId);
+      if (pending === undefined) return false;
+      if (row.paused === 1) return true;
+      if (!["running", "waiting"].includes(row.runStatus)) return false;
+      const changed = this.state.connection
+        .prepare(
+          `UPDATE runs SET paused = 1, status_detail = 'paused', updated_at = ?
+           WHERE run_id = ? AND paused = 0 AND status IN ('running', 'waiting')`,
+        )
+        .run(now, options.runId);
+      if (changed.changes !== 1) return false;
+      const revision = this.resourceRevision(row.resourceId);
+      this.bumpResource(row.resourceId, revision, now);
+      this.insertEvent(
+        row.resourceId,
+        revision + 1,
+        "run.paused",
+        "control",
+        null,
+        { status: "parked" },
+        now,
+      );
+      recordViewerDeltas(
+        this.state,
+        options.runId,
+        [{ targetType: "summary" }, { targetType: "replay" }],
+        now,
+      );
+      return true;
+    });
+  }
+
+  resumePausedInteraction(options: { runId: string; now?: string }): boolean {
+    const now = epoch(validTimestamp(options.now));
+    return this.state.transaction(() => {
+      const row = this.workflowRunRow(options.runId);
+      if (
+        row === undefined ||
+        row.status !== "parked" ||
+        row.runStatus !== "waiting" ||
+        row.paused !== 1
+      ) {
+        return false;
+      }
+      const lease = this.requireLease(row.resourceId);
+      if (lease.ownerId !== null && lease.expiresAt !== null && lease.expiresAt > now) return false;
+      const pending = this.state.connection
+        .prepare(
+          `SELECT 1 FROM interactive_requests
+           WHERE run_id = ? AND status IN ('pending', 'presenting') LIMIT 1`,
+        )
+        .get(options.runId);
+      if (pending === undefined) return false;
+      const changed = this.state.connection
+        .prepare(
+          `UPDATE runs
+           SET paused = 0, status_detail = 'waiting for origin-session input', updated_at = ?
+           WHERE run_id = ? AND status = 'waiting' AND paused = 1`,
+        )
+        .run(now, options.runId);
+      if (changed.changes !== 1) return false;
+      const revision = this.resourceRevision(row.resourceId);
+      this.bumpResource(row.resourceId, revision, now);
+      this.insertEvent(
+        row.resourceId,
+        revision + 1,
+        "run.resumed",
+        "control",
+        null,
+        { status: "waiting" },
+        now,
+      );
+      recordViewerDeltas(
+        this.state,
+        options.runId,
+        [{ targetType: "summary" }, { targetType: "replay" }],
+        now,
+      );
+      return true;
+    });
+  }
+
+  isWorkflowRunPaused(runId: string): boolean {
+    return this.workflowRunRow(runId)?.paused === 1;
+  }
+
   parkWorkflowRunForSourceChange(options: {
     runId: string;
     claimToken: string;
@@ -2038,6 +2228,21 @@ export class SqliteControllerStore implements ControllerStore {
     return isTurnIntentRow(row) ? this.mapTurnIntent(row) : undefined;
   }
 
+  isWorkflowTurnIntentClaimLive(options: {
+    intentId: string;
+    targetSessionId: string;
+    claimToken: string;
+    now?: string;
+  }): boolean {
+    const row = this.turnIntentRow(options.intentId);
+    return (
+      row !== undefined &&
+      row.targetSessionId === options.targetSessionId &&
+      row.resolvedAt === null &&
+      this.verifyEffectToken(row.effectId, options.claimToken, options.now)
+    );
+  }
+
   claimWorkflowTurnIntent(options: {
     intentId: string;
     targetSessionId: string;
@@ -2084,6 +2289,24 @@ export class SqliteControllerStore implements ControllerStore {
     return claimed;
   }
 
+  hasClaimableWorkflowTurnIntent(options: { targetSessionId: string; now?: string }): boolean {
+    const now = epoch(validTimestamp(options.now));
+    const row = this.state.connection
+      .prepare(
+        `SELECT 1 AS present
+         FROM turn_intents t
+         JOIN effects e ON e.effect_id = t.effect_id
+         JOIN leases l ON l.resource_id = e.resource_id
+         WHERE t.target_session_id = ? AND t.resolved_at IS NULL
+           AND t.eligible_at IS NOT NULL AND t.eligible_at <= ?
+           AND e.status = 'pending'
+           AND (l.owner_id IS NULL OR l.expires_at IS NULL OR l.expires_at <= ?)
+         LIMIT 1`,
+      )
+      .get(options.targetSessionId, now, now);
+    return row !== undefined;
+  }
+
   makeWorkflowTurnIntentEligible(options: {
     intentId: string;
     fallbackFacts: WorkflowTurnIntentFacts;
@@ -2240,6 +2463,22 @@ export class SqliteControllerStore implements ControllerStore {
     return this.requireNotification(options.runId, options.attemptId, options.notificationIndex);
   }
 
+  hasClaimableWorkflowNotification(options: { targetSessionId: string; now?: string }): boolean {
+    const now = epoch(validTimestamp(options.now));
+    const row = this.state.connection
+      .prepare(
+        `SELECT 1 AS present
+         FROM notifications n
+         JOIN effects e ON e.effect_id = n.effect_id
+         JOIN leases l ON l.resource_id = e.resource_id
+         WHERE n.target_session_id = ? AND e.status = 'pending'
+           AND (l.owner_id IS NULL OR l.expires_at IS NULL OR l.expires_at <= ?)
+         LIMIT 1`,
+      )
+      .get(options.targetSessionId, now);
+    return row !== undefined;
+  }
+
   listPendingWorkflowNotifications(options: {
     targetSessionId: string;
     limit?: number;
@@ -2279,6 +2518,20 @@ export class SqliteControllerStore implements ControllerStore {
     return result;
   }
 
+  isWorkflowNotificationClaimLive(options: {
+    notificationId: string;
+    targetSessionId: string;
+    claimToken: string;
+    now?: string;
+  }): boolean {
+    const row = this.notificationRowById(options.notificationId);
+    return (
+      row !== undefined &&
+      row.targetSessionId === options.targetSessionId &&
+      this.verifyEffectToken(row.effectId, options.claimToken, options.now)
+    );
+  }
+
   markWorkflowNotificationDelivered(options: {
     notificationId: string;
     targetSessionId: string;
@@ -2771,6 +3024,13 @@ export class SqliteControllerStore implements ControllerStore {
     }
   }
 
+  private workflowRunViewRows(clause: string, params: unknown[]): WorkflowRunViewRow[] {
+    return this.state.connection
+      .prepare(workflowRunViewSelect(clause))
+      .all(...params)
+      .filter(isWorkflowRunViewRow);
+  }
+
   /* istanbul ignore next -- pure projection covered by integration tests */
   private mapWorkflowRun(row: RunRow): WorkflowRunQueueRecord {
     return {
@@ -3452,7 +3712,7 @@ function workflowSelect(clause: string): string {
 function workflowRunSelect(clause: string): string {
   return `SELECT r.run_id AS runId, r.resource_id AS resourceId,
     d.workflow_name AS workflowName, r.workflow_ref AS workflowRef, r.status AS runStatus,
-    r.definition_digest AS definitionDigest, d.definition_hash AS definitionHash,
+    r.paused, r.definition_digest AS definitionDigest, d.definition_hash AS definitionHash,
     r.input_hash AS inputHash,
     r.launch_options_hash AS launchOptionsHash,
     q.status, q.available_at AS availableAt, q.affinity_runner_id AS affinityRunnerId,
@@ -3468,6 +3728,24 @@ function workflowRunSelect(clause: string): string {
     JOIN leases l ON l.resource_id = r.resource_id ${clause}`;
 }
 
+function workflowRunViewSelect(clause: string): string {
+  return `SELECT r.run_id AS runId, d.workflow_name AS workflowName,
+    r.workflow_ref AS workflowRef, r.status AS runStatus, r.paused,
+    r.definition_digest AS definitionDigest, q.status,
+    b.origin_session_id AS originSessionId, b.execution_mode AS executionMode,
+    r.parent_run_id AS parentRunId, q.error_code AS errorCode,
+    CAST(error.content AS TEXT) AS errorMessage,
+    q.created_at AS createdAt, q.updated_at AS updatedAt,
+    q.started_at AS startedAt, q.finished_at AS finishedAt,
+    source.source_type AS sourceType, source.source_ref AS sourceRef,
+    source.source_revision AS sourceRevision
+    FROM runs r JOIN workflow_definitions d ON d.definition_digest = r.definition_digest
+    JOIN run_queue q ON q.run_id = r.run_id
+    LEFT JOIN run_bindings b ON b.run_id = r.run_id
+    LEFT JOIN run_sources source ON source.run_id = r.run_id AND source.mount_path = ''
+    LEFT JOIN blobs error ON error.blob_hash = q.error_hash ${clause}`;
+}
+
 function turnIntentSelect(clause: string): string {
   return `SELECT t.turn_intent_id AS intentId, t.source_event_id AS sourceEventId,
     t.run_id AS runId, t.workflow_ref AS workflowRef,
@@ -3559,6 +3837,67 @@ function isControllerRow(value: unknown): value is ControllerRow {
 function isLeaseRow(value: unknown): value is LeaseRow {
   return isRecord(value);
 }
+function workflowRunViewRecord(row: WorkflowRunViewRow): WorkflowRunQueueViewRecord {
+  const root =
+    row.sourceType === "builtin"
+      ? { kind: "builtin", id: row.sourceRef, revision: row.sourceRevision }
+      : { kind: "file", path: row.sourceRef, hash: row.sourceRevision };
+  return {
+    runId: row.runId,
+    workflowName: row.workflowName,
+    workflowSourceRef: row.workflowRef,
+    workflowSource: { root, mounted: [] },
+    initialized: row.runStatus !== "queued",
+    definitionDigest: `sha256:${row.definitionDigest.toString("hex")}`,
+    runStateStatus: row.runStatus,
+    paused: row.paused === 1,
+    status: row.status,
+    originSessionId: row.executionMode === "headless" ? null : row.originSessionId,
+    executionMode: row.executionMode,
+    parentRunId: row.parentRunId,
+    errorCode: row.errorCode,
+    errorMessage: row.errorMessage,
+    createdAt: new Date(row.createdAt).toISOString(),
+    updatedAt: new Date(row.updatedAt).toISOString(),
+    startedAt: row.startedAt === null ? null : new Date(row.startedAt).toISOString(),
+    finishedAt: row.finishedAt === null ? null : new Date(row.finishedAt).toISOString(),
+  };
+}
+
+function isWorkflowRunViewRow(value: unknown): value is WorkflowRunViewRow {
+  return (
+    isRecord(value) &&
+    typeof value.runId === "string" &&
+    typeof value.workflowName === "string" &&
+    typeof value.workflowRef === "string" &&
+    typeof value.runStatus === "string" &&
+    typeof value.paused === "number" &&
+    Buffer.isBuffer(value.definitionDigest) &&
+    typeof value.status === "string" &&
+    (value.originSessionId === null || typeof value.originSessionId === "string") &&
+    (value.executionMode === "interactive" || value.executionMode === "headless") &&
+    (value.parentRunId === null || typeof value.parentRunId === "string") &&
+    (value.errorCode === null || typeof value.errorCode === "string") &&
+    (value.errorMessage === null || typeof value.errorMessage === "string") &&
+    typeof value.createdAt === "number" &&
+    typeof value.updatedAt === "number" &&
+    (value.startedAt === null || typeof value.startedAt === "number") &&
+    (value.finishedAt === null || typeof value.finishedAt === "number") &&
+    (value.sourceType === "builtin" || value.sourceType === "file") &&
+    typeof value.sourceRef === "string" &&
+    typeof value.sourceRevision === "string"
+  );
+}
+
+function isRunListRevisionRow(value: unknown): value is RunListRevisionRow {
+  return (
+    isRecord(value) &&
+    typeof value.count === "number" &&
+    typeof value.revisionSum === "number" &&
+    typeof value.updatedAt === "number"
+  );
+}
+
 function isRunRow(value: unknown): value is RunRow {
   return isRecord(value);
 }