@wichayutdew/pi-workflows 0.3.0 → 1.0.1

package/src/harness/gate-submission-action.ts

@@ -0,0 +1,154 @@
+import type { LoadedWorkflow } from '../config/types.ts';
+import type { WorkflowRun } from '../engine/state.ts';
+import {
+  attachGateReviewId,
+  beginGate,
+  failGate,
+  failRun,
+  resolveGate,
+} from '../engine/transitions.ts';
+import { reviewedCommandShapeError } from '../policy/approved-commands.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'dependencies'
+  | 'isSessionActive'
+  | 'latestContext'
+  | 'launchPromptReview'
+  | 'persist'
+  | 'pi'
+  | 'restoreBaselineTools'
+  | 'run'
+  | 'sessionEpoch'
+  | 'settleAfterTransition'
+  | 'updateStatus'
+>;
+
+export type GateSubmissionAction = {
+  submitGate: (
+    this: HarnessActionContext,
+    workflow: LoadedWorkflow,
+    originalRun: WorkflowRun,
+    outcome: string,
+    artifact: string,
+  ) => Promise<void>;
+};
+
+function isCurrentGateRequest(
+  run: WorkflowRun | undefined,
+  originalRun: WorkflowRun,
+  requestId: string,
+): run is WorkflowRun {
+  return (
+    run !== undefined &&
+    run.runId === originalRun.runId &&
+    run.currentStepId === originalRun.currentStepId &&
+    run.pendingGate?.requestId === requestId &&
+    run.pendingGate.reviewId === undefined &&
+    (run.status === 'awaiting-gate' || run.status === 'paused')
+  );
+}
+
+async function submitGate(
+  this: HarnessActionContext,
+  workflow: LoadedWorkflow,
+  originalRun: WorkflowRun,
+  outcome: string,
+  artifact: string,
+): Promise<void> {
+  const requestSessionEpoch = this.sessionEpoch;
+  const requestId =
+    `${originalRun.runId}:${originalRun.currentStepId}:` +
+    this.dependencies.createRequestId();
+  const step = workflow.definition.steps[originalRun.currentStepId];
+  if (!step?.gate) throw new Error('Current step has no gate');
+
+  const commandShapeError = reviewedCommandShapeError(artifact);
+  if (commandShapeError) {
+    const awaitingReview = beginGate(
+      workflow,
+      originalRun,
+      outcome,
+      artifact,
+      requestId,
+      this.dependencies.now(),
+    );
+    this.run = resolveGate(
+      workflow,
+      awaitingReview,
+      {
+        approved: false,
+        feedback: commandShapeError,
+        resolvedAt: this.dependencies.now(),
+      },
+      this.dependencies.now(),
+    );
+    this.latestContext?.ui.notify(
+      `Plan contract needs repair before review: ${commandShapeError}`,
+      'warning',
+    );
+    this.settleAfterTransition(workflow);
+    return;
+  }
+
+  this.run = beginGate(
+    workflow,
+    originalRun,
+    outcome,
+    artifact,
+    requestId,
+    this.dependencies.now(),
+  );
+  this.persist();
+  this.restoreBaselineTools();
+  this.updateStatus();
+
+  if (step.gate.provider === 'prompt') {
+    this.launchPromptReview(workflow, this.run, this.latestContext);
+    return;
+  }
+
+  const response = await this.dependencies.requestPlannotatorReview(
+    this.pi.events,
+    requestId,
+    artifact,
+    `pi-workflows:${workflow.definition.id}:${originalRun.currentStepId}`,
+    step.gate.timeoutMs,
+  );
+  const currentRun = this.run;
+  if (
+    !this.isSessionActive ||
+    this.sessionEpoch !== requestSessionEpoch ||
+    !isCurrentGateRequest(currentRun, originalRun, requestId)
+  ) {
+    throw new Error('Gate request was superseded by a workflow state change');
+  }
+  if (response.status !== 'handled') {
+    const reason = response.error ?? 'Plannotator is unavailable';
+    const gateFailed = failGate(currentRun, reason, this.dependencies.now());
+    this.run = failRun(gateFailed, reason, this.dependencies.now());
+    this.persist();
+    this.restoreBaselineTools();
+    this.updateStatus();
+    throw new Error(reason);
+  }
+  this.run = attachGateReviewId(
+    currentRun,
+    response.result.reviewId,
+    this.dependencies.now(),
+  );
+  this.persist();
+  this.updateStatus();
+  this.latestContext?.ui.notify(
+    `Submitted "${originalRun.currentStepId}" for Plannotator review ${response.result.reviewId}`,
+    'info',
+  );
+}
+
+/**
+ * Returns the gate-submission action for harness composition.
+ */
+export function createGateSubmissionAction(): GateSubmissionAction {
+  return { submitGate };
+}

package/src/harness/lifecycle-actions.ts

@@ -0,0 +1,154 @@
+import { failRun } from '../engine/transitions.ts';
+import { buildMainWorkflowNotice } from '../prompt.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import { parseAvailableSkills } from './catalog.ts';
+import { waitForEventContextIdle } from './context-idle.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'cancelActiveDelegation'
+  | 'cancelPromptReview'
+  | 'captureSkills'
+  | 'catalog'
+  | 'dependencies'
+  | 'enqueueMutation'
+  | 'isSessionActive'
+  | 'latestContext'
+  | 'mainSteps'
+  | 'persist'
+  | 'pi'
+  | 'registeredWorkflowCommands'
+  | 'reloadCatalog'
+  | 'restoreBaselineTools'
+  | 'restoreFromSession'
+  | 'run'
+  | 'sessionEpoch'
+  | 'startNow'
+  | 'statusShortcutLabel'
+  | 'stopStatusRefresh'
+  | 'updateStatus'
+>;
+
+export type LifecycleActions = {
+  registerMultilineCommandInput: (this: HarnessActionContext) => void;
+  registerLifecycle: (this: HarnessActionContext) => void;
+  registerPolicy: (this: HarnessActionContext) => void;
+};
+
+function registerMultilineCommandInput(this: HarnessActionContext): void {
+  this.pi.on('input', async (event, context) => {
+    if (
+      event.source === 'extension' ||
+      event.images?.length ||
+      !event.text.startsWith('/')
+    ) {
+      return;
+    }
+    const newlineIndex = event.text.indexOf('\n');
+    if (newlineIndex === -1) return;
+    const command = event.text.slice(1, newlineIndex).replace(/\r$/, '');
+    if (!this.registeredWorkflowCommands.has(command)) return;
+    const workflow = [...this.catalog.workflows.values()].find(
+      (candidate) => candidate.definition.command === command,
+    );
+    if (!workflow) return;
+
+    const input = event.text.slice(newlineIndex + 1);
+    const skills = parseAvailableSkills(context.getSystemPrompt());
+    try {
+      await this.enqueueMutation(context, (sessionEpoch) =>
+        this.startNow(
+          workflow.definition.id,
+          input,
+          {
+            context,
+            skills: () => skills,
+            waitForIdle: () =>
+              waitForEventContextIdle(context, this.dependencies),
+          },
+          sessionEpoch,
+        ),
+      );
+    } catch (error) {
+      context.ui.notify(
+        `Cannot start workflow: ${error instanceof Error ? error.message : String(error)}`,
+        'error',
+      );
+    }
+    return { action: 'handled' as const };
+  });
+}
+
+function registerLifecycle(this: HarnessActionContext): void {
+  this.pi.on('session_start', async (_event, context) => {
+    this.sessionEpoch += 1;
+    this.isSessionActive = false;
+    this.cancelPromptReview();
+    this.mainSteps.deactivate();
+    await this.cancelActiveDelegation('Pi session changed');
+    if (this.run) this.restoreBaselineTools();
+    this.run = undefined;
+    this.latestContext = context;
+    if (!(await this.reloadCatalog(context, false))) return;
+    this.restoreFromSession(context);
+    this.isSessionActive = true;
+  });
+
+  this.pi.on('session_tree', async (_event, context) => {
+    this.sessionEpoch += 1;
+    this.isSessionActive = false;
+    this.cancelPromptReview();
+    this.mainSteps.deactivate();
+    await this.cancelActiveDelegation('Pi session tree changed');
+    this.latestContext = context;
+    if (!(await this.reloadCatalog(context, false))) return;
+    this.restoreFromSession(context);
+    this.isSessionActive = true;
+  });
+
+  this.pi.on('session_shutdown', async () => {
+    this.sessionEpoch += 1;
+    this.isSessionActive = false;
+    this.cancelPromptReview();
+    this.mainSteps.deactivate();
+    await this.cancelActiveDelegation('Pi session shut down');
+    if (this.run) this.restoreBaselineTools();
+    this.run = undefined;
+    this.latestContext = undefined;
+    this.stopStatusRefresh();
+  });
+}
+
+function registerPolicy(this: HarnessActionContext): void {
+  this.pi.on('before_agent_start', (event, context) => {
+    this.latestContext = context;
+    this.captureSkills(event.systemPromptOptions.skills);
+    if (!this.run || this.run.status !== 'running') return;
+    const workflow = this.catalog.workflows.get(this.run.workflowId);
+    if (!workflow) {
+      this.run = failRun(
+        this.run,
+        'Workflow configuration disappeared; reload or restore it',
+        this.dependencies.now(),
+      );
+      this.persist();
+      this.restoreBaselineTools();
+      this.updateStatus();
+      return;
+    }
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${buildMainWorkflowNotice(workflow, this.run, this.statusShortcutLabel)}`,
+    };
+  });
+}
+
+/**
+ * Returns Pi lifecycle and input registration actions for composition.
+ */
+export function createLifecycleActions(): LifecycleActions {
+  return {
+    registerMultilineCommandInput,
+    registerLifecycle,
+    registerPolicy,
+  };
+}

package/src/harness/pause-actions.ts

@@ -0,0 +1,120 @@
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { abortRun, pauseRun } from '../engine/transitions.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'cancelActiveDelegation'
+  | 'cancelPromptReview'
+  | 'dependencies'
+  | 'isolateMainSessionTools'
+  | 'mainSteps'
+  | 'persist'
+  | 'restoreBaselineTools'
+  | 'run'
+  | 'updateStatus'
+>;
+
+export type PauseActions = {
+  pauseNow: (
+    this: HarnessActionContext,
+    reason: string,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
+  abortNow: (
+    this: HarnessActionContext,
+    reason: string,
+    context: ExtensionCommandContext,
+  ) => Promise<void>;
+};
+
+async function pauseNow(
+  this: HarnessActionContext,
+  reason: string,
+  context: ExtensionCommandContext,
+): Promise<void> {
+  if (
+    !this.run ||
+    this.run.status === 'completed' ||
+    this.run.status === 'aborted'
+  ) {
+    context.ui.notify('No active workflow to pause', 'warning');
+    return;
+  }
+  if (this.run.status === 'paused') {
+    context.ui.notify(
+      `Workflow is already paused${this.run.pauseReason ? `: ${this.run.pauseReason}` : ''}`,
+      'info',
+    );
+    return;
+  }
+  this.cancelPromptReview();
+  const isMainStepSuspended = this.mainSteps.suspend();
+  const isCancellationConfirmed = await this.cancelActiveDelegation(
+    'Workflow paused by user',
+  );
+  if (!context.isIdle()) {
+    context.abort();
+    if (isMainStepSuspended) await context.waitForIdle();
+  }
+
+  this.run = pauseRun(this.run, reason, this.dependencies.now());
+  this.persist();
+  if (isCancellationConfirmed) {
+    this.restoreBaselineTools();
+  } else {
+    this.isolateMainSessionTools();
+  }
+  this.updateStatus();
+  context.ui.notify(
+    isCancellationConfirmed
+      ? `Paused "${this.run.workflowId}" at step "${this.run.currentStepId}". Fix the issue, then run /workflow-resume.`
+      : `Pause recorded at "${this.run.currentStepId}", but child cancellation is not confirmed. Main tools remain isolated until it exits.`,
+    isCancellationConfirmed ? 'info' : 'warning',
+  );
+}
+
+async function abortNow(
+  this: HarnessActionContext,
+  reason: string,
+  context: ExtensionCommandContext,
+): Promise<void> {
+  if (
+    !this.run ||
+    this.run.status === 'completed' ||
+    this.run.status === 'aborted'
+  ) {
+    context.ui.notify('No active workflow to abort', 'warning');
+    return;
+  }
+  this.cancelPromptReview();
+  const isMainStepSuspended = this.mainSteps.suspend();
+  const isCancellationConfirmed = await this.cancelActiveDelegation(
+    'Workflow aborted by user',
+  );
+  if (!context.isIdle()) {
+    context.abort();
+    if (isMainStepSuspended) await context.waitForIdle();
+  }
+  this.run = abortRun(this.run, reason, this.dependencies.now());
+  this.persist();
+  if (isCancellationConfirmed) {
+    this.restoreBaselineTools();
+  } else {
+    this.isolateMainSessionTools();
+  }
+  this.updateStatus();
+  context.ui.notify(
+    isCancellationConfirmed
+      ? `Aborted workflow "${this.run.workflowId}"`
+      : `Workflow "${this.run.workflowId}" is aborted, but its child has not confirmed cancellation; main tools remain isolated`,
+    isCancellationConfirmed ? 'info' : 'warning',
+  );
+}
+
+/**
+ * Returns pause and abort actions for harness composition.
+ */
+export function createPauseActions(): PauseActions {
+  return { pauseNow, abortNow };
+}

package/src/harness/plannotator-result-actions.ts

@@ -0,0 +1,123 @@
+import type { GateResolution } from '../engine/state.ts';
+import {
+  failRun,
+  resolveGate,
+  storeGateResolution,
+} from '../engine/transitions.ts';
+import {
+  parsePlannotatorResult,
+  PLANNOTATOR_RESULT_CHANNEL,
+} from '../integrations/plannotator.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'catalog'
+  | 'dependencies'
+  | 'handlePlannotatorResult'
+  | 'isSessionActive'
+  | 'latestContext'
+  | 'mutationQueue'
+  | 'persist'
+  | 'pi'
+  | 'restoreBaselineTools'
+  | 'run'
+  | 'settleAfterTransition'
+  | 'updateStatus'
+>;
+
+export type PlannotatorResultActions = {
+  registerPlannotatorResults: (this: HarnessActionContext) => void;
+  handlePlannotatorResult: (
+    this: HarnessActionContext,
+    data: unknown,
+  ) => Promise<void>;
+};
+
+function registerPlannotatorResults(this: HarnessActionContext): void {
+  this.pi.events.on(PLANNOTATOR_RESULT_CHANNEL, (data) => {
+    void this.mutationQueue
+      .run(() => this.handlePlannotatorResult(data))
+      .catch((error: unknown) => {
+        this.latestContext?.ui.notify(
+          `Cannot apply Plannotator result: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+          'error',
+        );
+      });
+  });
+}
+
+async function handlePlannotatorResult(
+  this: HarnessActionContext,
+  data: unknown,
+): Promise<void> {
+  if (
+    !this.isSessionActive ||
+    this.run?.pendingGate?.provider !== 'plannotator' ||
+    !this.run.pendingGate.reviewId
+  ) {
+    return;
+  }
+  const result = parsePlannotatorResult(data);
+  if (!result || result.reviewId !== this.run.pendingGate.reviewId) 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(
+      `Review ${result.reviewId} 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.run = failRun(
+      this.run,
+      'Gate result arrived, but workflow configuration is unavailable',
+      this.dependencies.now(),
+    );
+    this.persist();
+    this.restoreBaselineTools();
+    this.updateStatus();
+    return;
+  }
+  try {
+    this.run = resolveGate(
+      workflow,
+      this.run,
+      resolution,
+      this.dependencies.now(),
+    );
+    this.settleAfterTransition(workflow);
+  } catch (error) {
+    this.run = failRun(
+      this.run,
+      `Cannot apply gate result: ${error instanceof Error ? error.message : String(error)}`,
+      this.dependencies.now(),
+    );
+    this.persist();
+    this.restoreBaselineTools();
+    this.updateStatus();
+  }
+}
+
+/**
+ * Returns Plannotator result-channel actions for harness composition.
+ */
+export function createPlannotatorResultActions(): PlannotatorResultActions {
+  return { registerPlannotatorResults, handlePlannotatorResult };
+}