@wichayutdew/pi-workflows 0.3.0 → 1.0.0

package/src/harness/prompt-gate-actions.ts

@@ -0,0 +1,270 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { LoadedWorkflow } from '../config/types.ts';
+import type { GateResolution, WorkflowRun } from '../engine/state.ts';
+import {
+  failRun,
+  pauseRun,
+  resolveGate,
+  storeGateResolution,
+} from '../engine/transitions.ts';
+import type { PromptGateReviewResult } from '../integrations/prompt-gate.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import type { ActivePromptReview } from './types.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'activePromptReview'
+  | 'cancelPromptReview'
+  | 'catalog'
+  | 'dependencies'
+  | 'finishPromptReview'
+  | 'isSessionActive'
+  | 'latestContext'
+  | 'mutationQueue'
+  | 'pausePromptGate'
+  | 'persist'
+  | 'queuePromptReviewFailure'
+  | 'queuePromptReviewResult'
+  | 'restoreBaselineTools'
+  | 'run'
+  | 'sessionEpoch'
+  | 'settleAfterTransition'
+  | 'updateStatus'
+>;
+
+export type PromptGateActions = {
+  launchPromptReview: (
+    this: HarnessActionContext,
+    workflow: LoadedWorkflow,
+    run: WorkflowRun,
+    context: ExtensionContext | undefined,
+  ) => void;
+  queuePromptReviewResult: (
+    this: HarnessActionContext,
+    active: ActivePromptReview,
+    result: PromptGateReviewResult,
+  ) => void;
+  queuePromptReviewFailure: (
+    this: HarnessActionContext,
+    active: ActivePromptReview,
+    reason: string,
+  ) => void;
+  finishPromptReview: (
+    this: HarnessActionContext,
+    active: ActivePromptReview,
+    result: PromptGateReviewResult,
+  ) => Promise<void>;
+  pausePromptGate: (
+    this: HarnessActionContext,
+    requestId: string,
+    reason: string,
+    isFailed: boolean,
+  ) => void;
+  cancelPromptReview: (this: HarnessActionContext) => void;
+};
+
+function launchPromptReview(
+  this: HarnessActionContext,
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  context: ExtensionContext | undefined,
+): void {
+  const pendingGate = run.pendingGate;
+  if (!pendingGate || pendingGate.provider !== 'prompt') return;
+  if (!context?.hasUI) {
+    this.pausePromptGate(
+      pendingGate.requestId,
+      'Built-in review requires Pi TUI or RPC mode; resume there to continue',
+      false,
+    );
+    return;
+  }
+  if (this.activePromptReview?.requestId === pendingGate.requestId) return;
+  this.cancelPromptReview();
+
+  const active: ActivePromptReview = {
+    requestId: pendingGate.requestId,
+    runId: run.runId,
+    stepId: pendingGate.stepId,
+    sessionEpoch: this.sessionEpoch,
+    abortController: this.dependencies.createAbortController(),
+  };
+  this.activePromptReview = active;
+  void this.dependencies
+    .requestPromptGateReview(
+      context.ui,
+      `Review ${workflow.definition.id}:${pendingGate.stepId}`,
+      pendingGate.artifact,
+      active.abortController.signal,
+    )
+    .then(
+      (result) => {
+        this.queuePromptReviewResult(active, result);
+      },
+      (error: unknown) => {
+        this.queuePromptReviewFailure(
+          active,
+          error instanceof Error ? error.message : String(error),
+        );
+      },
+    );
+}
+
+function queuePromptReviewResult(
+  this: HarnessActionContext,
+  active: ActivePromptReview,
+  result: PromptGateReviewResult,
+): void {
+  void this.mutationQueue
+    .run(() => this.finishPromptReview(active, result))
+    .catch((error: unknown) => {
+      this.latestContext?.ui.notify(
+        `Cannot apply built-in review: ${error instanceof Error ? error.message : String(error)}`,
+        'error',
+      );
+    });
+}
+
+function queuePromptReviewFailure(
+  this: HarnessActionContext,
+  active: ActivePromptReview,
+  reason: string,
+): void {
+  void this.mutationQueue
+    .run(async () => {
+      if (this.activePromptReview !== active) return;
+      this.activePromptReview = undefined;
+      this.pausePromptGate(
+        active.requestId,
+        `Built-in review failed: ${reason}`,
+        true,
+      );
+    })
+    .catch((error: unknown) => {
+      this.latestContext?.ui.notify(
+        `Cannot pause failed built-in review: ${error instanceof Error ? error.message : String(error)}`,
+        'error',
+      );
+    });
+}
+
+async function finishPromptReview(
+  this: HarnessActionContext,
+  active: ActivePromptReview,
+  result: PromptGateReviewResult,
+): Promise<void> {
+  if (this.activePromptReview !== active) return;
+  this.activePromptReview = undefined;
+  if (
+    !this.isSessionActive ||
+    this.sessionEpoch !== active.sessionEpoch ||
+    !this.run ||
+    this.run.runId !== active.runId ||
+    this.run.currentStepId !== active.stepId ||
+    this.run.pendingGate?.provider !== 'prompt' ||
+    this.run.pendingGate.requestId !== active.requestId
+  ) {
+    return;
+  }
+  if (result.status === 'dismissed') {
+    this.pausePromptGate(
+      active.requestId,
+      'Built-in review was dismissed; resume to reopen it',
+      false,
+    );
+    return;
+  }
+
+  const resolution: GateResolution = {
+    approved: result.approved,
+    feedback: result.feedback,
+    resolvedAt: this.dependencies.now(),
+  };
+  if (this.run.status === 'paused') {
+    this.run = storeGateResolution(
+      this.run,
+      resolution,
+      this.dependencies.now(),
+    );
+    this.persist();
+    this.latestContext?.ui.notify(
+      'Built-in review finished while paused. Run /workflow-resume to apply it.',
+      'info',
+    );
+    return;
+  }
+  if (this.run.status !== 'awaiting-gate') return;
+
+  const workflow = this.catalog.workflows.get(this.run.workflowId);
+  if (!workflow) {
+    this.pausePromptGate(
+      active.requestId,
+      'Built-in review finished, but workflow configuration is unavailable',
+      true,
+    );
+    return;
+  }
+  try {
+    this.run = resolveGate(
+      workflow,
+      this.run,
+      resolution,
+      this.dependencies.now(),
+    );
+    this.settleAfterTransition(workflow);
+  } catch (error) {
+    this.pausePromptGate(
+      active.requestId,
+      `Cannot apply built-in review: ${error instanceof Error ? error.message : String(error)}`,
+      true,
+    );
+  }
+}
+
+function pausePromptGate(
+  this: HarnessActionContext,
+  requestId: string,
+  reason: string,
+  isFailed: boolean,
+): void {
+  if (
+    !this.run ||
+    this.run.pendingGate?.provider !== 'prompt' ||
+    this.run.pendingGate.requestId !== requestId
+  ) {
+    return;
+  }
+  if (this.run.status === 'awaiting-gate') {
+    this.run = isFailed
+      ? failRun(this.run, reason, this.dependencies.now())
+      : pauseRun(this.run, reason, this.dependencies.now());
+  }
+  this.persist();
+  this.restoreBaselineTools();
+  this.updateStatus();
+  this.latestContext?.ui.notify(
+    `Workflow paused at "${this.run.currentStepId}": ${reason}`,
+    'warning',
+  );
+}
+
+function cancelPromptReview(this: HarnessActionContext): void {
+  const active = this.activePromptReview;
+  if (!active) return;
+  this.activePromptReview = undefined;
+  active.abortController.abort();
+}
+
+/**
+ * Returns built-in prompt-gate actions for harness composition.
+ */
+export function createPromptGateActions(): PromptGateActions {
+  return {
+    launchPromptReview,
+    queuePromptReviewResult,
+    queuePromptReviewFailure,
+    finishPromptReview,
+    pausePromptGate,
+    cancelPromptReview,
+  };
+}

package/src/harness/resume-action.ts

@@ -0,0 +1,261 @@
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import {
+  failGate,
+  failRun,
+  reconcileRun,
+  resolveGate,
+  resumeRun,
+  storeGateResolution,
+} from '../engine/transitions.ts';
+import {
+  captureResumeCheckpoint,
+  matchesResumeCheckpoint,
+} from '../engine/resume.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'activeDelegation'
+  | 'captureSkills'
+  | 'catalog'
+  | 'dependencies'
+  | 'isolateMainSessionTools'
+  | 'launchCurrentStep'
+  | 'launchPromptReview'
+  | 'persist'
+  | 'pi'
+  | 'preflight'
+  | 'reloadCatalog'
+  | 'restoreBaselineTools'
+  | 'run'
+  | 'sessionEpoch'
+  | 'updateStatus'
+>;
+
+export type ResumeAction = {
+  resumeNow: (
+    this: HarnessActionContext,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
+};
+
+async function resumeNow(
+  this: HarnessActionContext,
+  context: ExtensionCommandContext,
+): Promise<void> {
+  if (!this.run || this.run.status !== 'paused') {
+    context.ui.notify('No paused workflow to resume', 'warning');
+    return;
+  }
+  if (this.activeDelegation) {
+    context.ui.notify(
+      `Cannot resume while subagent "${this.activeDelegation.agent}" is still cancelling`,
+      'warning',
+    );
+    return;
+  }
+  const checkpoint = captureResumeCheckpoint(this.run, this.sessionEpoch);
+  if (!context.isIdle()) {
+    context.abort();
+    await context.waitForIdle();
+  }
+  if (!matchesResumeCheckpoint(this.run, this.sessionEpoch, checkpoint)) {
+    context.ui.notify(
+      'Resume was superseded by another workflow or session change',
+      'warning',
+    );
+    return;
+  }
+  this.captureSkills(context.getSystemPromptOptions().skills);
+  await this.reloadCatalog(context, false);
+  if (!matchesResumeCheckpoint(this.run, this.sessionEpoch, checkpoint)) {
+    context.ui.notify(
+      'Resume was superseded by another workflow or session change',
+      'warning',
+    );
+    return;
+  }
+
+  let workflow = this.catalog.workflows.get(this.run.workflowId);
+  if (!workflow) {
+    context.ui.notify(
+      `Workflow "${this.run.workflowId}" is no longer loaded; restore it or abort`,
+      'error',
+    );
+    return;
+  }
+  const reconciled = reconcileRun(this.run, workflow, this.dependencies.now());
+  if (!reconciled.run) {
+    context.ui.notify(
+      reconciled.error ?? 'Cannot reconcile workflow configuration',
+      'error',
+    );
+    return;
+  }
+
+  let resumed = reconciled.run;
+  if (
+    resumed.pendingGate?.provider === 'plannotator' &&
+    !resumed.pendingGate.reviewId
+  ) {
+    resumed = failGate(
+      resumed,
+      'Gate submission was interrupted before a review id was recorded; submit it again',
+      this.dependencies.now(),
+    );
+  }
+  if (
+    resumed.pendingGate?.provider === 'plannotator' &&
+    resumed.pendingGate.reviewId &&
+    !resumed.pendingGate.resolution
+  ) {
+    const requestedReviewId = resumed.pendingGate.reviewId;
+    const gateStep = workflow.definition.steps[resumed.pendingGate.stepId];
+    const statusResponse =
+      await this.dependencies.requestPlannotatorReviewStatus(
+        this.pi.events,
+        `${resumed.runId}:review-status:${this.dependencies.createRequestId()}`,
+        requestedReviewId,
+        gateStep?.gate?.provider === 'plannotator'
+          ? gateStep.gate.timeoutMs
+          : 5_000,
+      );
+    if (!matchesResumeCheckpoint(this.run, this.sessionEpoch, checkpoint)) {
+      context.ui.notify(
+        'Resume was superseded by another workflow or session change',
+        'warning',
+      );
+      return;
+    }
+
+    workflow = this.catalog.workflows.get(this.run.workflowId);
+    if (!workflow) {
+      context.ui.notify(
+        `Workflow "${this.run.workflowId}" is no longer loaded; restore it or abort`,
+        'error',
+      );
+      return;
+    }
+    const latest = reconcileRun(this.run, workflow, this.dependencies.now());
+    if (!latest.run) {
+      context.ui.notify(
+        latest.error ?? 'Cannot reconcile workflow configuration',
+        'error',
+      );
+      return;
+    }
+    resumed = latest.run;
+
+    if (
+      !resumed.pendingGate?.resolution &&
+      resumed.pendingGate?.reviewId === requestedReviewId &&
+      statusResponse.status !== 'handled'
+    ) {
+      context.ui.notify(
+        statusResponse.error ?? 'Cannot query the pending Plannotator review',
+        'error',
+      );
+      return;
+    }
+    if (
+      !resumed.pendingGate?.resolution &&
+      resumed.pendingGate?.reviewId === requestedReviewId &&
+      statusResponse.status === 'handled' &&
+      statusResponse.result.status === 'completed'
+    ) {
+      resumed = storeGateResolution(
+        resumed,
+        {
+          approved: statusResponse.result.approved,
+          feedback: statusResponse.result.feedback,
+          resolvedAt: this.dependencies.now(),
+        },
+        this.dependencies.now(),
+      );
+    } else if (
+      !resumed.pendingGate?.resolution &&
+      resumed.pendingGate?.reviewId === requestedReviewId &&
+      statusResponse.status === 'handled' &&
+      statusResponse.result.status === 'missing'
+    ) {
+      resumed = failGate(
+        resumed,
+        'Plannotator no longer has the pending review; submit it again',
+        this.dependencies.now(),
+      );
+    }
+  }
+
+  const storedResolution = resumed.pendingGate?.resolution;
+  if (storedResolution) {
+    try {
+      resumed = resolveGate(
+        workflow,
+        resumed,
+        storedResolution,
+        this.dependencies.now(),
+      );
+    } catch (error) {
+      context.ui.notify(
+        `Cannot apply stored gate result: ${error instanceof Error ? error.message : String(error)}`,
+        'error',
+      );
+      return;
+    }
+  } else {
+    resumed = resumeRun(resumed, this.dependencies.now());
+  }
+  this.run = resumed;
+
+  if (this.run.status === 'awaiting-gate') {
+    this.persist();
+    this.restoreBaselineTools();
+    this.updateStatus();
+    if (this.run.pendingGate?.provider === 'prompt') {
+      this.launchPromptReview(workflow, this.run, context);
+      context.ui.notify('Workflow resumed with built-in review open', 'info');
+      return;
+    }
+    context.ui.notify(
+      `Workflow resumed and is waiting for review ${this.run.pendingGate?.reviewId ?? ''}`.trim(),
+      'info',
+    );
+    return;
+  }
+  if (this.run.status !== 'running') {
+    this.persist();
+    this.restoreBaselineTools();
+    this.updateStatus();
+    context.ui.notify(`Workflow is now ${this.run.status}`, 'info');
+    return;
+  }
+
+  const preflightErrors = this.preflight(workflow, this.run.currentStepId);
+  if (preflightErrors.length > 0) {
+    this.run = failRun(
+      this.run,
+      `Step preflight failed: ${preflightErrors.join('; ')}`,
+      this.dependencies.now(),
+    );
+    this.persist();
+    this.restoreBaselineTools();
+    this.updateStatus();
+    context.ui.notify(
+      `Cannot resume workflow:\n${preflightErrors.join('\n')}`,
+      'error',
+    );
+    return;
+  }
+
+  this.persist();
+  this.isolateMainSessionTools();
+  this.updateStatus();
+  this.launchCurrentStep(workflow);
+}
+
+/**
+ * Returns the resume action for harness composition.
+ */
+export function createResumeAction(): ResumeAction {
+  return { resumeNow };
+}

package/src/harness/start-actions.ts

@@ -0,0 +1,183 @@
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { createRun } from '../engine/state.ts';
+import { formatWorkflowList } from '../workflow-list.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import type { WorkflowStartContext } from './types.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'activeDelegation'
+  | 'captureSkills'
+  | 'catalog'
+  | 'dependencies'
+  | 'isSessionActive'
+  | 'isolateMainSessionTools'
+  | 'launchCurrentStep'
+  | 'openWorkflowStatus'
+  | 'persist'
+  | 'pi'
+  | 'preflight'
+  | 'reloadCatalog'
+  | 'run'
+  | 'sessionEpoch'
+  | 'updateStatus'
+>;
+
+type SessionIdentity = Pick<
+  FullHarnessActionContext,
+  'isSessionActive' | 'sessionEpoch'
+>;
+
+function isCurrentSession(
+  session: SessionIdentity,
+  sessionEpoch: number,
+): boolean {
+  return session.isSessionActive && session.sessionEpoch === sessionEpoch;
+}
+
+export type StartActions = {
+  listWorkflows: (
+    this: HarnessActionContext,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
+  startNow: (
+    this: HarnessActionContext,
+    workflowId: string,
+    input: string,
+    startContext: WorkflowStartContext,
+    sessionEpoch: number,
+  ) => Promise<void>;
+  reloadNow: (
+    this: HarnessActionContext,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
+};
+
+async function listWorkflows(
+  this: HarnessActionContext,
+  context: ExtensionCommandContext,
+): Promise<void> {
+  const workflows = [...this.catalog.workflows.values()].sort((left, right) =>
+    left.definition.id.localeCompare(right.definition.id),
+  );
+  if (workflows.length === 0) {
+    context.ui.notify(
+      `No workflows loaded from ${this.catalog.userDirectory}`,
+      this.catalog.diagnostics.length > 0 ? 'warning' : 'info',
+    );
+    return;
+  }
+  this.pi.sendMessage({
+    customType: 'workflow-list',
+    content: formatWorkflowList(
+      workflows.map((workflow) => workflow.definition),
+    ),
+    display: true,
+  });
+}
+
+async function startNow(
+  this: HarnessActionContext,
+  workflowId: string,
+  input: string,
+  startContext: WorkflowStartContext,
+  sessionEpoch: number,
+): Promise<void> {
+  const { context } = startContext;
+  if (this.activeDelegation) {
+    context.ui.notify(
+      `Cannot start a workflow while subagent "${this.activeDelegation.agent}" is still cancelling`,
+      'warning',
+    );
+    return;
+  }
+  if (
+    this.run &&
+    this.run.status !== 'completed' &&
+    this.run.status !== 'aborted'
+  ) {
+    context.ui.notify(
+      `Workflow "${this.run.workflowId}" is ${this.run.status}; resume or abort it first`,
+      'warning',
+    );
+    return;
+  }
+  if (!context.isIdle()) {
+    context.abort();
+    await startContext.waitForIdle();
+  }
+  if (!isCurrentSession(this, sessionEpoch)) {
+    context.ui.notify(
+      'Workflow start was superseded by a session change',
+      'warning',
+    );
+    return;
+  }
+
+  this.captureSkills(startContext.skills());
+  if (!(await this.reloadCatalog(context, false))) {
+    context.ui.notify(
+      'Workflow start was superseded by a newer configuration load',
+      'warning',
+    );
+    return;
+  }
+  if (!isCurrentSession(this, sessionEpoch)) {
+    context.ui.notify(
+      'Workflow start was superseded by a session change',
+      'warning',
+    );
+    return;
+  }
+  const workflow = this.catalog.workflows.get(workflowId);
+  if (!workflow) {
+    context.ui.notify(`Workflow "${workflowId}" is not loaded`, 'error');
+    return;
+  }
+  const preflightErrors = this.preflight(workflow, workflow.definition.start);
+  if (preflightErrors.length > 0) {
+    context.ui.notify(
+      `Cannot start workflow:\n${preflightErrors.join('\n')}`,
+      'error',
+    );
+    return;
+  }
+
+  this.run = createRun(
+    workflow,
+    input.trim(),
+    this.pi.getActiveTools(),
+    this.dependencies.createRequestId(),
+    this.dependencies.now(),
+  );
+  this.persist();
+  this.isolateMainSessionTools();
+  this.updateStatus();
+  this.openWorkflowStatus(context);
+  this.launchCurrentStep(workflow);
+}
+
+async function reloadNow(
+  this: HarnessActionContext,
+  context: ExtensionCommandContext,
+): Promise<void> {
+  if (
+    this.run &&
+    (this.run.status === 'running' || this.run.status === 'awaiting-gate')
+  ) {
+    context.ui.notify(
+      'Pause the workflow before reloading its configuration',
+      'warning',
+    );
+    return;
+  }
+  this.captureSkills(context.getSystemPromptOptions().skills);
+  await this.reloadCatalog(context, true);
+}
+
+/**
+ * Returns workflow listing, start, and reload actions for harness composition.
+ */
+export function createStartActions(): StartActions {
+  return { listWorkflows, startNow, reloadNow };
+}