@wichayutdew/pi-workflows 0.1.1

package/src/digest.ts

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonicalize(child)]),
+    );
+  }
+
+  return value;
+}
+
+export function digest(value: unknown): string {
+  return createHash('sha256')
+    .update(JSON.stringify(canonicalize(value)))
+    .digest('hex');
+}

package/src/engine/checkpoint.ts

@@ -0,0 +1,30 @@
+import { isWorkflowRun, type WorkflowRun } from './state.ts';
+
+export type CheckpointResult =
+  | { status: 'none' }
+  | { status: 'invalid' }
+  | { status: 'valid'; run: WorkflowRun };
+
+interface SessionEntryLike {
+  type?: unknown;
+  customType?: unknown;
+  data?: unknown;
+}
+
+/**
+ * Only the newest entry for this checkpoint type is authoritative. Falling
+ * back past corrupt or newer-version state could repeat already-finished work.
+ */
+export function readLatestCheckpoint(
+  entries: readonly SessionEntryLike[],
+  customType: string,
+): CheckpointResult {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (entry?.type !== 'custom' || entry.customType !== customType) continue;
+    return isWorkflowRun(entry.data)
+      ? { status: 'valid', run: structuredClone(entry.data) }
+      : { status: 'invalid' };
+  }
+  return { status: 'none' };
+}

package/src/engine/resume.ts

@@ -0,0 +1,44 @@
+import type { WorkflowRun } from './state.ts';
+
+export interface ResumeCheckpoint {
+  sessionEpoch: number;
+  runId: string;
+  workflowId: string;
+  currentStepId: string;
+  reviewId?: string;
+}
+
+export function captureResumeCheckpoint(
+  run: WorkflowRun,
+  sessionEpoch: number,
+): ResumeCheckpoint {
+  return {
+    sessionEpoch,
+    runId: run.runId,
+    workflowId: run.workflowId,
+    currentStepId: run.currentStepId,
+    ...(run.pendingGate?.reviewId
+      ? { reviewId: run.pendingGate.reviewId }
+      : {}),
+  };
+}
+
+/**
+ * Async resume work may overlap an abort, a session-tree switch, or a gate
+ * result. A gate result may update the same paused checkpoint and is safe to
+ * merge; a different session, run, step, review, or status is not.
+ */
+export function matchesResumeCheckpoint(
+  run: WorkflowRun | undefined,
+  sessionEpoch: number,
+  checkpoint: ResumeCheckpoint,
+): run is WorkflowRun {
+  return (
+    sessionEpoch === checkpoint.sessionEpoch &&
+    run?.status === 'paused' &&
+    run.runId === checkpoint.runId &&
+    run.workflowId === checkpoint.workflowId &&
+    run.currentStepId === checkpoint.currentStepId &&
+    run.pendingGate?.reviewId === checkpoint.reviewId
+  );
+}

package/src/engine/state.ts

@@ -0,0 +1,186 @@
+import type { LoadedWorkflow } from '../config/types.ts';
+
+export const RUN_STATE_VERSION = 1 as const;
+
+export type WorkflowRunStatus =
+  'running' | 'paused' | 'awaiting-gate' | 'completed' | 'aborted';
+
+export interface StepHistoryEntry {
+  stepId: string;
+  stepDigest: string;
+  outcome: string;
+  summary: string;
+  completedAt: number;
+}
+
+export interface GateResolution {
+  approved: boolean;
+  feedback: string;
+  resolvedAt: number;
+}
+
+export interface PendingGate {
+  provider: 'prompt' | 'plannotator';
+  requestId: string;
+  stepId: string;
+  artifact: string;
+  /** Legacy v1 field. New runs use the reviewed artifact as the handoff. */
+  summary?: string | undefined;
+  submittedOutcome: string;
+  requestedAt: number;
+  reviewId?: string | undefined;
+  resolution?: GateResolution | undefined;
+}
+
+export interface WorkflowRun {
+  stateVersion: typeof RUN_STATE_VERSION;
+  runId: string;
+  workflowId: string;
+  workflowDigest: string;
+  input: string;
+  status: WorkflowRunStatus;
+  currentStepId: string;
+  currentStepDigest: string;
+  baselineTools: string[];
+  visits: Record<string, number>;
+  history: StepHistoryEntry[];
+  startedAt: number;
+  updatedAt: number;
+  /**
+   * Most recent human-approved gate artifact. This is the only provenance
+   * source from which reviewed Bash capabilities may be derived.
+   */
+  reviewedArtifact?: string | undefined;
+  /**
+   * Input inherited from the previous completed step. Unlike `lastSummary`,
+   * this survives a paused attempt of the current step.
+   */
+  stepHandoff?: string | undefined;
+  lastSummary: string;
+  gateFeedback: string;
+  pauseReason?: string | undefined;
+  pausedFrom?: 'running' | 'awaiting-gate' | undefined;
+  pendingGate?: PendingGate | undefined;
+}
+
+export function createRun(
+  workflow: LoadedWorkflow,
+  input: string,
+  baselineTools: string[],
+  runId: string,
+  now: number,
+): WorkflowRun {
+  const start = workflow.definition.start;
+  return {
+    stateVersion: RUN_STATE_VERSION,
+    runId,
+    workflowId: workflow.definition.id,
+    workflowDigest: workflow.digest,
+    input,
+    status: 'running',
+    currentStepId: start,
+    currentStepDigest: workflow.stepDigests[start] ?? '',
+    baselineTools: [...new Set(baselineTools)],
+    visits: { [start]: 1 },
+    history: [],
+    startedAt: now,
+    updatedAt: now,
+    reviewedArtifact: '',
+    stepHandoff: '',
+    lastSummary: '',
+    gateFeedback: '',
+  };
+}
+
+export function isWorkflowRun(value: unknown): value is WorkflowRun {
+  if (value === null || typeof value !== 'object') return false;
+  const run = value as Partial<WorkflowRun>;
+  const historyIsValid =
+    Array.isArray(run.history) &&
+    run.history.every(
+      (entry) =>
+        entry !== null &&
+        typeof entry === 'object' &&
+        typeof entry.stepId === 'string' &&
+        typeof entry.stepDigest === 'string' &&
+        typeof entry.outcome === 'string' &&
+        typeof entry.summary === 'string' &&
+        typeof entry.completedAt === 'number',
+    );
+  const visitsAreValid =
+    run.visits !== null &&
+    typeof run.visits === 'object' &&
+    !Array.isArray(run.visits) &&
+    Object.values(run.visits).every(
+      (count) => Number.isInteger(count) && count >= 0,
+    );
+  const gateIsValid =
+    run.pendingGate === undefined ||
+    (run.pendingGate !== null &&
+      typeof run.pendingGate === 'object' &&
+      (run.pendingGate.provider === 'prompt' ||
+        run.pendingGate.provider === 'plannotator') &&
+      typeof run.pendingGate.requestId === 'string' &&
+      run.pendingGate.requestId.length > 0 &&
+      typeof run.pendingGate.stepId === 'string' &&
+      typeof run.pendingGate.artifact === 'string' &&
+      (run.pendingGate.summary === undefined ||
+        typeof run.pendingGate.summary === 'string') &&
+      typeof run.pendingGate.submittedOutcome === 'string' &&
+      typeof run.pendingGate.requestedAt === 'number' &&
+      (run.pendingGate.reviewId === undefined ||
+        typeof run.pendingGate.reviewId === 'string') &&
+      (run.pendingGate.resolution === undefined ||
+        (run.pendingGate.resolution !== null &&
+          typeof run.pendingGate.resolution === 'object' &&
+          typeof run.pendingGate.resolution.approved === 'boolean' &&
+          typeof run.pendingGate.resolution.feedback === 'string' &&
+          typeof run.pendingGate.resolution.resolvedAt === 'number')));
+  const optionalsAreValid =
+    (run.reviewedArtifact === undefined ||
+      typeof run.reviewedArtifact === 'string') &&
+    (run.stepHandoff === undefined || typeof run.stepHandoff === 'string') &&
+    (run.pauseReason === undefined || typeof run.pauseReason === 'string') &&
+    (run.pausedFrom === undefined ||
+      run.pausedFrom === 'running' ||
+      run.pausedFrom === 'awaiting-gate');
+  const statusIsValid =
+    run.status === 'running' ||
+    run.status === 'paused' ||
+    run.status === 'awaiting-gate' ||
+    run.status === 'completed' ||
+    run.status === 'aborted';
+  const pauseStateIsValid =
+    run.status === 'paused'
+      ? run.pausedFrom === 'running' || run.pausedFrom === 'awaiting-gate'
+      : run.pausedFrom === undefined;
+  const gateStateIsValid = !gateIsValid
+    ? false
+    : run.pendingGate === undefined
+      ? run.status !== 'awaiting-gate' && run.pausedFrom !== 'awaiting-gate'
+      : run.pendingGate.stepId === run.currentStepId &&
+        (run.status === 'awaiting-gate' ||
+          (run.status === 'paused' && run.pausedFrom === 'awaiting-gate'));
+  return (
+    run.stateVersion === RUN_STATE_VERSION &&
+    typeof run.runId === 'string' &&
+    typeof run.workflowId === 'string' &&
+    typeof run.workflowDigest === 'string' &&
+    typeof run.input === 'string' &&
+    typeof run.currentStepId === 'string' &&
+    typeof run.currentStepDigest === 'string' &&
+    Array.isArray(run.baselineTools) &&
+    run.baselineTools.every((tool) => typeof tool === 'string') &&
+    historyIsValid &&
+    visitsAreValid &&
+    gateIsValid &&
+    optionalsAreValid &&
+    statusIsValid &&
+    pauseStateIsValid &&
+    gateStateIsValid &&
+    typeof run.startedAt === 'number' &&
+    typeof run.updatedAt === 'number' &&
+    typeof run.lastSummary === 'string' &&
+    typeof run.gateFeedback === 'string'
+  );
+}

package/src/engine/transitions.ts

@@ -0,0 +1,426 @@
+import type { LoadedWorkflow } from '../config/types.ts';
+import type { GateResolution, StepHistoryEntry, WorkflowRun } from './state.ts';
+
+export interface ReconcileResult {
+  run?: WorkflowRun;
+  changed: boolean;
+  restartedStep?: string;
+  error?: string;
+}
+
+function currentStep(workflow: LoadedWorkflow, run: WorkflowRun) {
+  return workflow.definition.steps[run.currentStepId];
+}
+
+function withUpdate(
+  run: WorkflowRun,
+  changes: Partial<WorkflowRun>,
+  now: number,
+): WorkflowRun {
+  return { ...run, ...changes, updatedAt: now };
+}
+
+export function allowedOutcomes(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+): string[] {
+  const step = currentStep(workflow, run);
+  if (!step) return [];
+  const gateResolutionOutcomes = step.gate
+    ? new Set([step.gate.approvedOutcome, step.gate.rejectedOutcome])
+    : undefined;
+  return [
+    ...Object.keys(step.transitions).filter(
+      (outcome) => !gateResolutionOutcomes?.has(outcome),
+    ),
+    ...(step.gate ? [step.gate.submitOutcome] : []),
+  ];
+}
+
+export function pauseRun(
+  run: WorkflowRun,
+  reason: string,
+  now: number,
+): WorkflowRun {
+  if (run.status !== 'running' && run.status !== 'awaiting-gate') {
+    return withUpdate(run, { pauseReason: reason || run.pauseReason }, now);
+  }
+  return withUpdate(
+    run,
+    {
+      status: 'paused',
+      pausedFrom: run.status,
+      pauseReason: reason || `Paused during step "${run.currentStepId}"`,
+    },
+    now,
+  );
+}
+
+export function resumeRun(run: WorkflowRun, now: number): WorkflowRun {
+  if (run.status !== 'paused') return run;
+  return withUpdate(
+    run,
+    {
+      status: run.pausedFrom ?? (run.pendingGate ? 'awaiting-gate' : 'running'),
+      pauseReason: undefined,
+      pausedFrom: undefined,
+    },
+    now,
+  );
+}
+
+export function abortRun(
+  run: WorkflowRun,
+  reason: string,
+  now: number,
+): WorkflowRun {
+  return withUpdate(
+    run,
+    {
+      status: 'aborted',
+      pauseReason: reason || 'Aborted by user',
+      pausedFrom: undefined,
+      pendingGate: undefined,
+    },
+    now,
+  );
+}
+
+export function advanceRun(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  outcome: string,
+  summary: string,
+  now: number,
+): WorkflowRun {
+  if (run.status !== 'running') {
+    throw new Error(
+      `workflow is ${run.status}; only a running workflow can advance`,
+    );
+  }
+  const step = currentStep(workflow, run);
+  if (!step)
+    throw new Error(`current step "${run.currentStepId}" no longer exists`);
+  if (step.gate?.submitOutcome === outcome) {
+    throw new Error(
+      `outcome "${outcome}" must be submitted through the configured gate`,
+    );
+  }
+
+  const target = step.transitions[outcome];
+  if (!target) {
+    throw new Error(
+      `outcome "${outcome}" is not valid for step "${run.currentStepId}"`,
+    );
+  }
+  if (target === '$pause') {
+    return withUpdate(
+      run,
+      {
+        status: 'paused',
+        pausedFrom: 'running',
+        pauseReason: summary || `Step "${run.currentStepId}" requested a pause`,
+        lastSummary: summary,
+      },
+      now,
+    );
+  }
+
+  const completed: StepHistoryEntry = {
+    stepId: run.currentStepId,
+    stepDigest: run.currentStepDigest,
+    outcome,
+    summary,
+    completedAt: now,
+  };
+  if (target === '$done') {
+    return withUpdate(
+      run,
+      {
+        status: 'completed',
+        history: [...run.history, completed],
+        stepHandoff: summary,
+        lastSummary: summary,
+        gateFeedback: '',
+        pausedFrom: undefined,
+        pendingGate: undefined,
+      },
+      now,
+    );
+  }
+
+  const nextStep = workflow.definition.steps[target];
+  if (!nextStep)
+    throw new Error(`transition target "${target}" does not exist`);
+  const nextVisitCount = (run.visits[target] ?? 0) + 1;
+  const visits = { ...run.visits, [target]: nextVisitCount };
+  const overVisitLimit = nextVisitCount > workflow.definition.maxStepVisits;
+  return withUpdate(
+    run,
+    {
+      status: overVisitLimit ? 'paused' : 'running',
+      currentStepId: target,
+      currentStepDigest: workflow.stepDigests[target] ?? '',
+      visits,
+      history: [...run.history, completed],
+      stepHandoff: summary,
+      lastSummary: summary,
+      gateFeedback: '',
+      ...(overVisitLimit
+        ? {
+            pausedFrom: 'running' as const,
+            pauseReason: `Step "${target}" exceeded maxStepVisits (${workflow.definition.maxStepVisits})`,
+          }
+        : { pausedFrom: undefined, pauseReason: undefined }),
+    },
+    now,
+  );
+}
+
+export function beginGate(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  outcome: string,
+  artifact: string,
+  requestId: string,
+  now: number,
+): WorkflowRun {
+  if (run.status !== 'running') {
+    throw new Error(
+      `workflow is ${run.status}; gate submission requires a running workflow`,
+    );
+  }
+  const step = currentStep(workflow, run);
+  if (!step?.gate) throw new Error(`step "${run.currentStepId}" has no gate`);
+  if (outcome !== step.gate.submitOutcome) {
+    throw new Error(`gate expects outcome "${step.gate.submitOutcome}"`);
+  }
+  if (!artifact.trim())
+    throw new Error('gate submission requires a non-empty artifact');
+  if (!requestId) throw new Error('gate submission requires a request id');
+
+  return withUpdate(
+    run,
+    {
+      status: 'awaiting-gate',
+      pendingGate: {
+        provider: step.gate.provider,
+        requestId,
+        stepId: run.currentStepId,
+        artifact,
+        submittedOutcome: outcome,
+        requestedAt: now,
+      },
+    },
+    now,
+  );
+}
+
+export function attachGateReviewId(
+  run: WorkflowRun,
+  reviewId: string,
+  now: number,
+): WorkflowRun {
+  if (!run.pendingGate) throw new Error('workflow has no pending gate');
+  if (run.pendingGate.provider !== 'plannotator') {
+    throw new Error('only a Plannotator gate can have a review id');
+  }
+  return withUpdate(
+    run,
+    { pendingGate: { ...run.pendingGate, reviewId } },
+    now,
+  );
+}
+
+export function failGate(
+  run: WorkflowRun,
+  reason: string,
+  now: number,
+): WorkflowRun {
+  if (!run.pendingGate) return run;
+  return withUpdate(
+    run,
+    {
+      status: 'running',
+      pendingGate: undefined,
+      gateFeedback: reason,
+    },
+    now,
+  );
+}
+
+export function storeGateResolution(
+  run: WorkflowRun,
+  resolution: GateResolution,
+  now: number,
+): WorkflowRun {
+  if (!run.pendingGate) return run;
+  return withUpdate(
+    run,
+    { pendingGate: { ...run.pendingGate, resolution } },
+    now,
+  );
+}
+
+export function resolveGate(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  resolution: GateResolution,
+  now: number,
+): WorkflowRun {
+  const pending = run.pendingGate;
+  if (!pending) throw new Error('workflow has no pending gate');
+  const step = workflow.definition.steps[pending.stepId];
+  if (!step?.gate)
+    throw new Error(`gated step "${pending.stepId}" no longer exists`);
+  if (run.currentStepId !== pending.stepId) {
+    throw new Error('gate result does not match the current step');
+  }
+
+  const outcome = resolution.approved
+    ? step.gate.approvedOutcome
+    : step.gate.rejectedOutcome;
+  const summary = resolution.approved
+    ? pending.artifact
+    : resolution.feedback
+      ? `Gate ${resolution.approved ? 'approved' : 'rejected'}: ${resolution.feedback}`
+      : `Gate ${resolution.approved ? 'approved' : 'rejected'}`;
+  const runnable = withUpdate(
+    run,
+    {
+      status: 'running',
+      pendingGate: undefined,
+      ...(resolution.approved ? { reviewedArtifact: pending.artifact } : {}),
+      pausedFrom: undefined,
+      pauseReason: undefined,
+      gateFeedback: resolution.feedback,
+    },
+    now,
+  );
+  const advanced = advanceRun(workflow, runnable, outcome, summary, now);
+  return {
+    ...advanced,
+    gateFeedback: resolution.feedback,
+  };
+}
+
+function rebuildVisits(
+  history: readonly StepHistoryEntry[],
+  currentStepId: string,
+): Record<string, number> {
+  const visits: Record<string, number> = {};
+  for (const entry of history) {
+    visits[entry.stepId] = (visits[entry.stepId] ?? 0) + 1;
+  }
+  visits[currentStepId] = (visits[currentStepId] ?? 0) + 1;
+  return visits;
+}
+
+function retainedReviewedArtifact(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  history: readonly StepHistoryEntry[],
+): string {
+  const reviewedArtifact = run.reviewedArtifact ?? '';
+  if (!reviewedArtifact) return '';
+  const sourceRetained = history.some((entry) => {
+    const gate = workflow.definition.steps[entry.stepId]?.gate;
+    return (
+      gate !== undefined &&
+      entry.outcome === gate.approvedOutcome &&
+      entry.summary === reviewedArtifact
+    );
+  });
+  return sourceRetained ? reviewedArtifact : '';
+}
+
+export function reconcileRun(
+  run: WorkflowRun,
+  workflow: LoadedWorkflow,
+  now: number,
+): ReconcileResult {
+  if (run.workflowId !== workflow.definition.id) {
+    return {
+      changed: false,
+      error: `run belongs to "${run.workflowId}", not "${workflow.definition.id}"`,
+    };
+  }
+  if (run.workflowDigest === workflow.digest) {
+    return { run, changed: false };
+  }
+  if (!workflow.definition.steps[run.currentStepId]) {
+    return {
+      changed: true,
+      error: `current step "${run.currentStepId}" was removed; abort or restore the configuration`,
+    };
+  }
+
+  const changedHistoryIndex = run.history.findIndex(
+    (entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest,
+  );
+  if (changedHistoryIndex >= 0) {
+    const changedEntry = run.history[changedHistoryIndex];
+    if (!changedEntry || !workflow.definition.steps[changedEntry.stepId]) {
+      return {
+        changed: true,
+        error:
+          'a completed step was removed; abort or restore the configuration',
+      };
+    }
+    const retainedHistory = run.history.slice(0, changedHistoryIndex);
+    const restartedStep = changedEntry.stepId;
+    const stepHandoff = retainedHistory.at(-1)?.summary ?? '';
+    const reviewedArtifact = retainedReviewedArtifact(
+      workflow,
+      run,
+      retainedHistory,
+    );
+    return {
+      changed: true,
+      restartedStep,
+      run: withUpdate(
+        run,
+        {
+          workflowDigest: workflow.digest,
+          status: 'paused',
+          currentStepId: restartedStep,
+          currentStepDigest: workflow.stepDigests[restartedStep] ?? '',
+          history: retainedHistory,
+          visits: rebuildVisits(retainedHistory, restartedStep),
+          reviewedArtifact,
+          stepHandoff,
+          lastSummary: stepHandoff,
+          pendingGate: undefined,
+          pausedFrom: 'running',
+          pauseReason: `Configuration changed; restarted step "${restartedStep}"`,
+          gateFeedback: '',
+        },
+        now,
+      ),
+    };
+  }
+
+  const currentDigest = workflow.stepDigests[run.currentStepId] ?? '';
+  const currentChanged = currentDigest !== run.currentStepDigest;
+  return {
+    changed: true,
+    ...(currentChanged ? { restartedStep: run.currentStepId } : {}),
+    run: withUpdate(
+      run,
+      {
+        workflowDigest: workflow.digest,
+        currentStepDigest: currentDigest,
+        ...(currentChanged
+          ? {
+              status: 'paused' as const,
+              pendingGate: undefined,
+              pausedFrom: 'running' as const,
+              pauseReason: `Configuration changed; restarted step "${run.currentStepId}"`,
+              gateFeedback: '',
+            }
+          : {}),
+      },
+      now,
+    ),
+  };
+}