@wichayutdew/pi-workflows 0.2.3 → 1.0.0

package/src/engine/transitions.ts

@@ -1,471 +1,17 @@
-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}"`,
-      failedStepId: undefined,
-    },
-    now,
-  );
-}
-
-export function failRun(
-  run: WorkflowRun,
-  reason: string,
-  now: number,
-): WorkflowRun {
-  const paused = pauseRun(run, reason, now);
-  if (paused.status !== 'paused') return paused;
-  return {
-    ...paused,
-    failedStepId: paused.currentStepId,
-  };
-}
-
-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,
-      failedStepId: undefined,
-    },
-    now,
-  );
-}
-
-export function abortRun(
-  run: WorkflowRun,
-  reason: string,
-  now: number,
-): WorkflowRun {
-  return withUpdate(
-    run,
-    {
-      status: 'aborted',
-      pauseReason: reason || 'Aborted by user',
-      pausedFrom: undefined,
-      failedStepId: 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: '',
-      ...(nextStep.gate ? { reviewedArtifact: '' } : {}),
-      ...(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 : '';
-}
-
-function refreshApprovedGateHistory(
-  run: WorkflowRun,
-  workflow: LoadedWorkflow,
-): WorkflowRun {
-  const reviewedArtifact = run.reviewedArtifact ?? '';
-  if (!reviewedArtifact) return run;
-  let changed = false;
-  const history = run.history.map((entry) => {
-    const gate = workflow.definition.steps[entry.stepId]?.gate;
-    const currentDigest = workflow.stepDigests[entry.stepId];
-    if (
-      gate &&
-      currentDigest &&
-      entry.outcome === gate.approvedOutcome &&
-      entry.summary === reviewedArtifact &&
-      entry.stepDigest !== currentDigest
-    ) {
-      changed = true;
-      return { ...entry, stepDigest: currentDigest };
-    }
-    return entry;
-  });
-  return changed ? { ...run, history } : run;
-}
-
-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 reconciledRun = refreshApprovedGateHistory(run, workflow);
-
-  const changedHistoryIndex = reconciledRun.history.findIndex(
-    (entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest,
-  );
-  if (changedHistoryIndex >= 0) {
-    const changedEntry = reconciledRun.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 = reconciledRun.history.slice(0, changedHistoryIndex);
-    const restartedStep = changedEntry.stepId;
-    const stepHandoff = retainedHistory.at(-1)?.summary ?? '';
-    const reviewedArtifact = retainedReviewedArtifact(
-      workflow,
-      reconciledRun,
-      retainedHistory,
-    );
-    return {
-      changed: true,
-      restartedStep,
-      run: withUpdate(
-        reconciledRun,
-        {
-          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',
-          failedStepId: undefined,
-          pauseReason: `Configuration changed; restarted step "${restartedStep}"`,
-          gateFeedback: '',
-        },
-        now,
-      ),
-    };
-  }
-
-  const currentDigest = workflow.stepDigests[run.currentStepId] ?? '';
-  const currentChanged = currentDigest !== reconciledRun.currentStepDigest;
-  return {
-    changed: true,
-    ...(currentChanged ? { restartedStep: run.currentStepId } : {}),
-    run: withUpdate(
-      reconciledRun,
-      {
-        workflowDigest: workflow.digest,
-        currentStepDigest: currentDigest,
-        ...(currentChanged
-          ? {
-              status: 'paused' as const,
-              pendingGate: undefined,
-              pausedFrom: 'running' as const,
-              failedStepId: undefined,
-              pauseReason: `Configuration changed; restarted step "${run.currentStepId}"`,
-              gateFeedback: '',
-            }
-          : {}),
-      },
-      now,
-    ),
-  };
-}
+export {
+  attachGateReviewId,
+  beginGate,
+  failGate,
+  resolveGate,
+  storeGateResolution,
+} from './gate-transitions.ts';
+export { advanceRun } from './run-advance.ts';
+export {
+  abortRun,
+  allowedOutcomes,
+  failRun,
+  pauseRun,
+  resumeRun,
+} from './run-lifecycle.ts';
+export { reconcileRun } from './run-reconciliation.ts';
+export type { ReconcileResult } from './transition-types.ts';

package/src/harness/action-context.ts

@@ -0,0 +1,181 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+import type { KeyId } from '@earendil-works/pi-tui';
+import type {
+  LoadedWorkflow,
+  WorkflowCatalog,
+  WorkflowStep,
+} from '../config/types.ts';
+import type { WorkflowRun } from '../engine/state.ts';
+import type { PromptGateReviewResult } from '../integrations/prompt-gate.ts';
+import type { SubagentDelegationClientController } from '../integrations/subagents/client.ts';
+import type {
+  SubagentDelegationResponse,
+  SubagentDelegationUpdate,
+} from '../integrations/subagents/protocol.ts';
+import type { MainStepRuntimeController } from '../runtime/main-step-runtime.ts';
+import type { SerialTaskQueueController } from '../runtime/serial-task-queue.ts';
+import type { WorkflowStepResult } from '../runtime/step-result.ts';
+import type { WorkflowStatusSnapshot } from '../workflow-status.ts';
+import type { DelegationFailureActions } from './delegation-failure.ts';
+import type { WorkflowHarnessDependencies } from './dependencies.ts';
+import type {
+  ActiveDelegation,
+  ActivePromptReview,
+  DelegationRecovery,
+  DelegationFailureDetails,
+  MainStepIdentity,
+  WorkflowStartContext,
+} from './types.ts';
+
+/**
+ * Internal composition surface shared by the harness action modules.
+ *
+ * The class facade owns this state. Action modules receive it as their dynamic
+ * `this` value so their dependencies stay explicit and independently testable.
+ */
+export type HarnessActionContext = {
+  pi: ExtensionAPI;
+  dependencies: WorkflowHarnessDependencies;
+  delegationFailures: DelegationFailureActions;
+  subagents: SubagentDelegationClientController;
+  mainSteps: MainStepRuntimeController;
+  catalog: WorkflowCatalog;
+  run: WorkflowRun | undefined;
+  latestContext: ExtensionContext | undefined;
+  availableSkills: Set<string>;
+  isSessionActive: boolean;
+  sessionEpoch: number;
+  activeDelegation: ActiveDelegation | undefined;
+  activePromptReview: ActivePromptReview | undefined;
+  registeredWorkflowCommands: Set<string>;
+  catalogLoadSequence: number;
+  mutationQueue: SerialTaskQueueController;
+  statusShortcut: KeyId;
+  statusShortcutLabel: string;
+  statusRefreshTimer: ReturnType<typeof setInterval> | undefined;
+  isStatusOverlayOpen: boolean;
+  legacyProgressWidgetContext: ExtensionContext | undefined;
+  workflowIds: () => Array<string>;
+  list: (context: ExtensionCommandContext) => Promise<void>;
+  start: (
+    workflowId: string,
+    input: string,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
+  startNow: (
+    workflowId: string,
+    input: string,
+    startContext: WorkflowStartContext,
+    sessionEpoch: number,
+  ) => Promise<void>;
+  pause: (reason: string, context: ExtensionCommandContext) => Promise<void>;
+  pauseNow: (reason: string, context: ExtensionCommandContext) => Promise<void>;
+  resume: (context: ExtensionCommandContext) => Promise<void>;
+  resumeNow: (context: ExtensionCommandContext) => Promise<void>;
+  abort: (reason: string, context: ExtensionCommandContext) => Promise<void>;
+  abortNow: (reason: string, context: ExtensionCommandContext) => Promise<void>;
+  reload: (context: ExtensionCommandContext) => Promise<void>;
+  reloadNow: (context: ExtensionCommandContext) => Promise<void>;
+  workflowStatusSnapshot: () => WorkflowStatusSnapshot | undefined;
+  registerLifecycle: () => void;
+  registerPolicy: () => void;
+  registerMultilineCommandInput: () => void;
+  launchCurrentStep: (
+    workflow: LoadedWorkflow,
+    recovery?: DelegationRecovery,
+  ) => void;
+  launchMainStep: (
+    workflow: LoadedWorkflow,
+    run: WorkflowRun,
+    step: WorkflowStep,
+  ) => void;
+  queueMainStepResult: (
+    identity: MainStepIdentity,
+    result: WorkflowStepResult | undefined,
+    context: ExtensionContext,
+  ) => Promise<void>;
+  finishMainStep: (
+    identity: MainStepIdentity,
+    result: WorkflowStepResult | undefined,
+    context: ExtensionContext,
+  ) => Promise<void>;
+  handleDelegationUpdate: (
+    active: ActiveDelegation,
+    update: SubagentDelegationUpdate,
+  ) => void;
+  queueDelegationResponse: (
+    active: ActiveDelegation,
+    response: SubagentDelegationResponse,
+  ) => void;
+  queueDelegationFailure: (active: ActiveDelegation, reason: string) => void;
+  finishDelegation: (
+    active: ActiveDelegation,
+    response: SubagentDelegationResponse,
+  ) => Promise<void>;
+  cancelActiveDelegation: (reason: string) => Promise<boolean>;
+  cleanupDelegation: (active: ActiveDelegation) => Promise<void>;
+  retryDelegationAfterFailure: (
+    active: ActiveDelegation,
+    failure: DelegationFailureDetails | undefined,
+    reason: string,
+  ) => boolean;
+  pauseForDelegationFailure: (reason: string) => void;
+  pauseForExecutionFailure: (label: string, reason: string) => void;
+  retainUnconfirmedDelegation: (
+    active: ActiveDelegation,
+    reason: string,
+  ) => void;
+  releaseMainAfterCancellation: (active: ActiveDelegation) => void;
+  submitGate: (
+    workflow: LoadedWorkflow,
+    originalRun: WorkflowRun,
+    outcome: string,
+    artifact: string,
+  ) => Promise<void>;
+  launchPromptReview: (
+    workflow: LoadedWorkflow,
+    run: WorkflowRun,
+    context: ExtensionContext | undefined,
+  ) => void;
+  queuePromptReviewResult: (
+    active: ActivePromptReview,
+    result: PromptGateReviewResult,
+  ) => void;
+  queuePromptReviewFailure: (
+    active: ActivePromptReview,
+    reason: string,
+  ) => void;
+  finishPromptReview: (
+    active: ActivePromptReview,
+    result: PromptGateReviewResult,
+  ) => Promise<void>;
+  pausePromptGate: (requestId: string, reason: string, failed: boolean) => void;
+  cancelPromptReview: () => void;
+  registerPlannotatorResults: () => void;
+  handlePlannotatorResult: (data: unknown) => Promise<void>;
+  settleAfterTransition: (workflow: LoadedWorkflow) => void;
+  preflight: (workflow: LoadedWorkflow, stepId: string) => Array<string>;
+  isolateMainSessionTools: () => void;
+  restoreBaselineTools: () => void;
+  captureSkills: (skills: ReadonlyArray<{ name: string }> | undefined) => void;
+  enqueueMutation: (
+    context: ExtensionContext,
+    operation: (sessionEpoch: number) => Promise<void>,
+  ) => Promise<void>;
+  persist: () => void;
+  restoreFromSession: (context: ExtensionContext) => void;
+  reloadCatalog: (
+    context: ExtensionContext,
+    announce: boolean,
+  ) => Promise<boolean>;
+  updateStatus: () => void;
+  refreshStatusWhileRunning: () => void;
+  stopStatusRefresh: () => void;
+  registerWorkflowStatusShortcut: () => void;
+  openWorkflowStatus: (context: ExtensionContext) => void;
+  showWorkflowStatus: (context: ExtensionContext) => Promise<void>;
+};

package/src/harness/catalog.ts

@@ -0,0 +1,45 @@
+import { DEFAULT_SETTINGS, type WorkflowCatalog } from '../config/types.ts';
+
+/**
+ * Creates the initial empty catalog value used before configuration is loaded.
+ */
+export function createEmptyCatalog(): WorkflowCatalog {
+  return {
+    workflows: new Map(),
+    settings: DEFAULT_SETTINGS,
+    diagnostics: [],
+    userDirectory: '',
+  };
+}
+
+/**
+ * Formats a bounded diagnostic summary suitable for a Pi notification.
+ */
+export function formatCatalogDiagnostics(catalog: WorkflowCatalog): string {
+  const shownDiagnostics = catalog.diagnostics
+    .slice(0, 3)
+    .map((diagnostic) => `${diagnostic.path}: ${diagnostic.message}`);
+  const remainingCount = catalog.diagnostics.length - shownDiagnostics.length;
+  return [
+    ...shownDiagnostics,
+    ...(remainingCount > 0 ? [`${remainingCount} more diagnostic(s)`] : []),
+  ].join('\n');
+}
+
+/**
+ * Extracts the latest advertised skill names from a Pi system prompt.
+ */
+export function parseAvailableSkills(
+  systemPrompt: string,
+): Array<{ name: string }> {
+  const sections = [
+    ...systemPrompt.matchAll(
+      /<available_skills>([\s\S]*?)<\/available_skills>/g,
+    ),
+  ];
+  const section = sections.at(-1)?.[1] ?? '';
+  return [...section.matchAll(/<name>([^<]+)<\/name>/g)].flatMap((match) => {
+    const name = match[1]?.trim();
+    return name ? [{ name }] : [];
+  });
+}