@wichayutdew/pi-workflows 0.3.0 → 1.0.0

package/src/harness/context-idle.ts

@@ -0,0 +1,21 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { WorkflowHarnessDependencies } from './dependencies.ts';
+
+const CONTEXT_IDLE_TIMEOUT_MS = 30_000;
+const CONTEXT_IDLE_POLL_INTERVAL_MS = 10;
+
+/**
+ * Waits for an interrupted Pi event context to settle before workflow start.
+ */
+export async function waitForEventContextIdle(
+  context: ExtensionContext,
+  dependencies: Pick<WorkflowHarnessDependencies, 'now' | 'waitForDelay'>,
+): Promise<void> {
+  const deadline = dependencies.now() + CONTEXT_IDLE_TIMEOUT_MS;
+  while (!context.isIdle()) {
+    if (dependencies.now() >= deadline) {
+      throw new Error('Timed out waiting for the interrupted Pi turn to stop');
+    }
+    await dependencies.waitForDelay(CONTEXT_IDLE_POLL_INTERVAL_MS);
+  }
+}

package/src/harness/core-actions.ts

@@ -0,0 +1,299 @@
+import { join } from 'node:path';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { LoadedWorkflow } from '../config/types.ts';
+import { hasRuntimeCommandConflict } from '../config/command-conflicts.ts';
+import { readLatestCheckpoint } from '../engine/checkpoint.ts';
+import { failRun, pauseRun } from '../engine/transitions.ts';
+import { preflightStep } from '../preflight.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import { formatCatalogDiagnostics } from './catalog.ts';
+
+const STATE_ENTRY_TYPE = 'pi-workflows-state-v1';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'activeDelegation'
+  | 'availableSkills'
+  | 'catalog'
+  | 'catalogLoadSequence'
+  | 'dependencies'
+  | 'isSessionActive'
+  | 'isolateMainSessionTools'
+  | 'latestContext'
+  | 'launchCurrentStep'
+  | 'mainSteps'
+  | 'mutationQueue'
+  | 'persist'
+  | 'pi'
+  | 'preflight'
+  | 'registeredWorkflowCommands'
+  | 'restoreBaselineTools'
+  | 'run'
+  | 'sessionEpoch'
+  | 'start'
+  | 'statusShortcut'
+  | 'updateStatus'
+>;
+
+export type CoreActions = {
+  settleAfterTransition: (
+    this: HarnessActionContext,
+    workflow: LoadedWorkflow,
+  ) => void;
+  preflight: (
+    this: HarnessActionContext,
+    workflow: LoadedWorkflow,
+    stepId: string,
+  ) => Array<string>;
+  isolateMainSessionTools: (this: HarnessActionContext) => void;
+  restoreBaselineTools: (this: HarnessActionContext) => void;
+  captureSkills: (
+    this: HarnessActionContext,
+    skills: ReadonlyArray<{ name: string }> | undefined,
+  ) => void;
+  enqueueMutation: (
+    this: HarnessActionContext,
+    context: ExtensionContext,
+    operation: (sessionEpoch: number) => Promise<void>,
+  ) => Promise<void>;
+  persist: (this: HarnessActionContext) => void;
+  restoreFromSession: (
+    this: HarnessActionContext,
+    context: ExtensionContext,
+  ) => void;
+  reloadCatalog: (
+    this: HarnessActionContext,
+    context: ExtensionContext,
+    shouldAnnounce: boolean,
+  ) => Promise<boolean>;
+};
+
+function settleAfterTransition(
+  this: HarnessActionContext,
+  workflow: LoadedWorkflow,
+): void {
+  if (!this.run) return;
+  if (this.run.status === 'running') {
+    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();
+  if (this.run.status !== 'running') {
+    this.restoreBaselineTools();
+    this.updateStatus();
+    if (this.run.status === 'completed') {
+      this.latestContext?.ui.notify(
+        `Workflow "${this.run.workflowId}" completed`,
+        'info',
+      );
+    } else if (this.run.status === 'paused') {
+      this.latestContext?.ui.notify(
+        `Workflow paused: ${this.run.pauseReason ?? 'manual action required'}`,
+        'warning',
+      );
+    }
+    return;
+  }
+
+  this.isolateMainSessionTools();
+  this.updateStatus();
+  this.launchCurrentStep(workflow);
+}
+
+function preflight(
+  this: HarnessActionContext,
+  workflow: LoadedWorkflow,
+  stepId: string,
+): Array<string> {
+  const step = workflow.definition.steps[stepId];
+  if (!step) return [`step "${stepId}" does not exist`];
+  return preflightStep(step, {
+    tools: this.pi.getAllTools(),
+    commands: this.pi.getCommands(),
+    skills: this.availableSkills,
+  });
+}
+
+function isolateMainSessionTools(this: HarnessActionContext): void {
+  this.pi.setActiveTools([]);
+}
+
+function restoreBaselineTools(this: HarnessActionContext): void {
+  this.mainSteps.release();
+  if (this.run) {
+    this.pi.setActiveTools([...this.run.baselineTools]);
+    return;
+  }
+  this.pi.setActiveTools(this.pi.getActiveTools());
+}
+
+function captureSkills(
+  this: HarnessActionContext,
+  skills: ReadonlyArray<{ name: string }> | undefined,
+): void {
+  if (!skills) return;
+  this.availableSkills = new Set(skills.map((skill) => skill.name));
+}
+
+function enqueueMutation(
+  this: HarnessActionContext,
+  context: ExtensionContext,
+  operation: (sessionEpoch: number) => Promise<void>,
+): Promise<void> {
+  if (!this.isSessionActive) {
+    context.ui.notify('The Pi session is still initializing', 'warning');
+    return Promise.resolve();
+  }
+  const sessionEpoch = this.sessionEpoch;
+  return this.mutationQueue.run(async () => {
+    if (!this.isSessionActive || this.sessionEpoch !== sessionEpoch) {
+      context.ui.notify(
+        'Workflow command was superseded by a session change',
+        'warning',
+      );
+      return;
+    }
+    await operation(sessionEpoch);
+  });
+}
+
+function persist(this: HarnessActionContext): void {
+  if (this.run) {
+    this.pi.appendEntry(STATE_ENTRY_TYPE, structuredClone(this.run));
+  }
+}
+
+function restoreFromSession(
+  this: HarnessActionContext,
+  context: ExtensionContext,
+): void {
+  this.latestContext = context;
+  const previousBaseline = this.run?.baselineTools;
+  const entries = context.sessionManager.getBranch();
+  const checkpoint = readLatestCheckpoint(entries, STATE_ENTRY_TYPE);
+  this.run = checkpoint.status === 'valid' ? checkpoint.run : undefined;
+  if (checkpoint.status === 'invalid') {
+    context.ui.notify(
+      'The newest workflow checkpoint is invalid or from an unsupported version; recovery stopped',
+      'error',
+    );
+  }
+  if (
+    this.run &&
+    (this.run.status === 'running' || this.run.status === 'awaiting-gate')
+  ) {
+    this.run = pauseRun(
+      this.run,
+      'Session was restored; inspect the checkpoint before resuming',
+      this.dependencies.now(),
+    );
+    this.persist();
+  }
+  if (!this.run && previousBaseline) {
+    this.pi.setActiveTools([...previousBaseline]);
+  } else {
+    this.restoreBaselineTools();
+  }
+  if (this.activeDelegation) this.isolateMainSessionTools();
+  this.updateStatus();
+}
+
+async function reloadCatalog(
+  this: HarnessActionContext,
+  context: ExtensionContext,
+  shouldAnnounce: boolean,
+): Promise<boolean> {
+  const loadSequence = ++this.catalogLoadSequence;
+  const sessionEpoch = this.sessionEpoch;
+  const catalog = await this.dependencies.loadCatalog({
+    cwd: context.cwd,
+    projectTrusted: context.isProjectTrusted(),
+  });
+  if (
+    loadSequence !== this.catalogLoadSequence ||
+    sessionEpoch !== this.sessionEpoch
+  ) {
+    return false;
+  }
+  this.latestContext = context;
+  const workflows = new Map(catalog.workflows);
+  const diagnostics = [...catalog.diagnostics];
+  if (catalog.settings.statusShortcut !== this.statusShortcut) {
+    diagnostics.push({
+      level: 'warning',
+      path: join(catalog.userDirectory, 'settings.yaml'),
+      message:
+        `settings.statusShortcut is "${catalog.settings.statusShortcut}", ` +
+        `but the active shortcut is "${this.statusShortcut}"; run Pi /reload to apply shortcut changes`,
+    });
+  }
+  const availableCommands = this.pi.getCommands();
+  for (const [workflowId, workflow] of catalog.workflows) {
+    const command = workflow.definition.command;
+    if (
+      hasRuntimeCommandConflict(
+        command,
+        availableCommands,
+        this.registeredWorkflowCommands,
+      )
+    ) {
+      workflows.delete(workflowId);
+      diagnostics.push({
+        level: 'error',
+        path: workflow.sourcePath,
+        message: `command "/${command}" conflicts with another loaded Pi resource`,
+      });
+    }
+  }
+  this.catalog = { ...catalog, workflows, diagnostics };
+  for (const workflow of workflows.values()) {
+    this.pi.registerCommand(workflow.definition.command, {
+      description: workflow.definition.description,
+      handler: async (args, commandContext) =>
+        this.start(workflow.definition.id, args, commandContext),
+    });
+    this.registeredWorkflowCommands.add(workflow.definition.command);
+  }
+
+  const diagnosticText = formatCatalogDiagnostics(this.catalog);
+  if (shouldAnnounce) {
+    context.ui.notify(
+      diagnosticText
+        ? `Loaded ${this.catalog.workflows.size} workflow(s)\n${diagnosticText}`
+        : `Loaded ${this.catalog.workflows.size} workflow(s)`,
+      diagnosticText ? 'warning' : 'info',
+    );
+  } else if (
+    this.catalog.diagnostics.some((diagnostic) => diagnostic.level === 'error')
+  ) {
+    context.ui.notify(
+      `Workflow configuration errors:\n${diagnosticText}`,
+      'warning',
+    );
+  }
+  return true;
+}
+
+/**
+ * Returns shared transition, persistence, preflight, and catalog actions.
+ */
+export function createCoreActions(): CoreActions {
+  return {
+    settleAfterTransition,
+    preflight,
+    isolateMainSessionTools,
+    restoreBaselineTools,
+    captureSkills,
+    enqueueMutation,
+    persist,
+    restoreFromSession,
+    reloadCatalog,
+  };
+}

package/src/harness/delegation-control-actions.ts

@@ -0,0 +1,250 @@
+import { failRun } from '../engine/transitions.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import {
+  boundedFailureField,
+  MAX_DELEGATION_RECOVERY_ATTEMPTS,
+} from './delegation-retry-policy.ts';
+import type { ActiveDelegation, DelegationFailureDetails } from './types.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'activeDelegation'
+  | 'catalog'
+  | 'cleanupDelegation'
+  | 'delegationFailures'
+  | 'dependencies'
+  | 'isSessionActive'
+  | 'isolateMainSessionTools'
+  | 'latestContext'
+  | 'launchCurrentStep'
+  | 'mainSteps'
+  | 'pauseForExecutionFailure'
+  | 'persist'
+  | 'restoreBaselineTools'
+  | 'run'
+  | 'sessionEpoch'
+  | 'subagents'
+  | 'updateStatus'
+>;
+
+export type DelegationControlActions = {
+  cancelActiveDelegation: (
+    this: HarnessActionContext,
+    reason: string,
+  ) => Promise<boolean>;
+  cleanupDelegation: (
+    this: HarnessActionContext,
+    active: ActiveDelegation,
+  ) => Promise<void>;
+  retryDelegationAfterFailure: (
+    this: HarnessActionContext,
+    active: ActiveDelegation,
+    failure: DelegationFailureDetails | undefined,
+    reason: string,
+  ) => boolean;
+  pauseForDelegationFailure: (
+    this: HarnessActionContext,
+    reason: string,
+  ) => void;
+  pauseForExecutionFailure: (
+    this: HarnessActionContext,
+    label: string,
+    reason: string,
+  ) => void;
+  retainUnconfirmedDelegation: (
+    this: HarnessActionContext,
+    active: ActiveDelegation,
+    reason: string,
+  ) => void;
+  releaseMainAfterCancellation: (
+    this: HarnessActionContext,
+    active: ActiveDelegation,
+  ) => void;
+};
+
+async function cancelActiveDelegation(
+  this: HarnessActionContext,
+  reason: string,
+): Promise<boolean> {
+  const active = this.activeDelegation;
+  if (!active) return true;
+  active.cancelling = true;
+  active.progress = 'cancelling';
+  this.updateStatus();
+  if (this.subagents.activeRequestId !== active.requestId) {
+    active.progress = 'cancellation unconfirmed';
+    this.updateStatus();
+    this.latestContext?.ui.notify(
+      `${reason}; the delegation channel already closed without a terminal response`,
+      'warning',
+    );
+    return false;
+  }
+  const isConfirmed = await this.subagents.cancelActiveAndWait();
+  if (isConfirmed && this.activeDelegation === active) {
+    this.activeDelegation = undefined;
+    await this.cleanupDelegation(active);
+  } else if (!isConfirmed) {
+    this.latestContext?.ui.notify(
+      `${reason}; waiting for subagent "${active.agent}" to confirm termination`,
+      'warning',
+    );
+  }
+  return isConfirmed;
+}
+
+async function cleanupDelegation(
+  this: HarnessActionContext,
+  active: ActiveDelegation,
+): Promise<void> {
+  try {
+    await this.dependencies.removeDelegationWorkspace(active.resultDirectory);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    try {
+      this.latestContext?.ui.notify(
+        `Could not remove temporary delegation workspace "${active.resultDirectory}": ${boundedFailureField(detail)}`,
+        'warning',
+      );
+    } catch {
+      // Cleanup and its warning are housekeeping; neither may pause the run.
+    }
+  }
+}
+
+function retryDelegationAfterFailure(
+  this: HarnessActionContext,
+  active: ActiveDelegation,
+  failure: DelegationFailureDetails | undefined,
+  reason: string,
+): boolean {
+  if (!failure) return false;
+  const fingerprint =
+    this.delegationFailures.delegationFailureFingerprint(failure);
+  const isRepeatedFailure = active.recoveryFailures.some(
+    (previousFailure) => previousFailure.fingerprint === fingerprint,
+  );
+  if (
+    active.recoveryAttemptCount >= MAX_DELEGATION_RECOVERY_ATTEMPTS ||
+    isRepeatedFailure ||
+    !this.delegationFailures.isRetryableTerminalFailure(failure) ||
+    !this.delegationFailures.isSafeToRetryDelegation(
+      active.policy,
+      active.broadRecoveryAuthorized,
+      failure.replayAudit,
+    ) ||
+    !this.isSessionActive ||
+    this.sessionEpoch !== active.sessionEpoch ||
+    !this.run ||
+    this.run.status !== 'running' ||
+    this.run.runId !== active.runId ||
+    this.run.currentStepId !== active.stepId ||
+    this.run.currentStepDigest !== active.stepDigest ||
+    this.activeDelegation
+  ) {
+    return false;
+  }
+  const workflow = this.catalog.workflows.get(this.run.workflowId);
+  if (!workflow) return false;
+
+  const attempt = active.recoveryAttemptCount + 1;
+  this.latestContext?.ui.notify(
+    `Automatic recovery for "${active.stepId}" after a subagent failure (${attempt}/${MAX_DELEGATION_RECOVERY_ATTEMPTS})`,
+    'warning',
+  );
+  this.launchCurrentStep(workflow, {
+    attempt,
+    failures: [...active.recoveryFailures, { fingerprint, reason }],
+  });
+  return true;
+}
+
+function pauseForDelegationFailure(
+  this: HarnessActionContext,
+  reason: string,
+): void {
+  this.pauseForExecutionFailure('Subagent step', reason);
+}
+
+function pauseForExecutionFailure(
+  this: HarnessActionContext,
+  label: string,
+  reason: string,
+): void {
+  if (!this.run || this.run.status !== 'running') return;
+  this.mainSteps.deactivate();
+  this.run = failRun(
+    this.run,
+    `${label} failed: ${reason}`,
+    this.dependencies.now(),
+  );
+  this.persist();
+  if (this.activeDelegation) {
+    this.isolateMainSessionTools();
+  } else {
+    this.restoreBaselineTools();
+  }
+  this.updateStatus();
+  this.latestContext?.ui.notify(
+    `Workflow paused at "${this.run.currentStepId}": ${reason}`,
+    'error',
+  );
+}
+
+function retainUnconfirmedDelegation(
+  this: HarnessActionContext,
+  active: ActiveDelegation,
+  reason: string,
+): void {
+  active.cancelling = true;
+  active.progress = 'cancellation unconfirmed';
+  if (this.run?.status === 'running') {
+    this.run = failRun(
+      this.run,
+      `Subagent step failed: ${reason}`,
+      this.dependencies.now(),
+    );
+    this.persist();
+  }
+  this.isolateMainSessionTools();
+  this.updateStatus();
+  this.latestContext?.ui.notify(
+    `Workflow paused, but subagent "${active.agent}" has not confirmed termination. Main tools and resume remain blocked; restart Pi if no terminal response arrives.`,
+    'error',
+  );
+}
+
+function releaseMainAfterCancellation(
+  this: HarnessActionContext,
+  active: ActiveDelegation,
+): void {
+  if (this.activeDelegation === active) this.activeDelegation = undefined;
+  if (
+    !this.activeDelegation &&
+    this.run &&
+    this.run.status !== 'running' &&
+    this.run.status !== 'awaiting-gate'
+  ) {
+    this.restoreBaselineTools();
+    this.updateStatus();
+    this.latestContext?.ui.notify(
+      `Subagent "${active.agent}" has terminated; main tools are restored`,
+      'info',
+    );
+  }
+}
+
+/**
+ * Returns delegation cancellation and recovery actions for composition.
+ */
+export function createDelegationControlActions(): DelegationControlActions {
+  return {
+    cancelActiveDelegation,
+    cleanupDelegation,
+    retryDelegationAfterFailure,
+    pauseForDelegationFailure,
+    pauseForExecutionFailure,
+    retainUnconfirmedDelegation,
+    releaseMainAfterCancellation,
+  };
+}