@wichayutdew/pi-workflows 0.2.3 → 1.0.0

package/src/harness/status-actions.ts

@@ -0,0 +1,191 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+import type { KeyId } from '@earendil-works/pi-tui';
+import type { WorkflowCatalog } from '../config/types.ts';
+import type { WorkflowRun } from '../engine/state.ts';
+import type { MainStepRuntimeController } from '../runtime/main-step-runtime.ts';
+import {
+  workflowStatusIcon,
+  type WorkflowStatusExecution,
+  type WorkflowStatusSnapshot,
+} from '../workflow-status.ts';
+import type { WorkflowHarnessDependencies } from './dependencies.ts';
+import type { ActiveDelegation } from './types.ts';
+
+const STATUS_KEY = 'pi-workflows';
+const LEGACY_PROGRESS_WIDGET_KEY = 'pi-workflows-progress';
+const STATUS_REFRESH_INTERVAL_MS = 250;
+
+type StatusContext = {
+  pi: ExtensionAPI;
+  dependencies: WorkflowHarnessDependencies;
+  catalog: WorkflowCatalog;
+  run: WorkflowRun | undefined;
+  latestContext: ExtensionContext | undefined;
+  activeDelegation: ActiveDelegation | undefined;
+  mainSteps: MainStepRuntimeController;
+  statusShortcut: KeyId;
+  statusShortcutLabel: string;
+  statusRefreshTimer: ReturnType<typeof setInterval> | undefined;
+  isStatusOverlayOpen: boolean;
+  legacyProgressWidgetContext: ExtensionContext | undefined;
+  workflowStatusSnapshot: () => WorkflowStatusSnapshot | undefined;
+  updateStatus: () => void;
+  stopStatusRefresh: () => void;
+  showWorkflowStatus: (context: ExtensionContext) => Promise<void>;
+};
+
+export type StatusActions = {
+  workflowStatusSnapshot: (
+    this: StatusContext,
+  ) => WorkflowStatusSnapshot | undefined;
+  updateStatus: (this: StatusContext) => void;
+  refreshStatusWhileRunning: (this: StatusContext) => void;
+  stopStatusRefresh: (this: StatusContext) => void;
+  registerWorkflowStatusShortcut: (this: StatusContext) => void;
+  openWorkflowStatus: (this: StatusContext, context: ExtensionContext) => void;
+  showWorkflowStatus: (
+    this: StatusContext,
+    context: ExtensionContext,
+  ) => Promise<void>;
+};
+
+function workflowStatusSnapshot(
+  this: StatusContext,
+): WorkflowStatusSnapshot | undefined {
+  if (!this.run) return undefined;
+  const workflow = this.catalog.workflows.get(this.run.workflowId);
+  let execution: WorkflowStatusExecution | undefined;
+  if (this.activeDelegation) {
+    execution = {
+      kind: 'subagent',
+      agent: this.activeDelegation.agent,
+      requestId: this.activeDelegation.requestId,
+      progress: this.activeDelegation.progress ?? 'starting',
+    };
+  } else if (this.mainSteps.activeStepId) {
+    execution = { kind: 'main' };
+  }
+  return {
+    run: this.run,
+    now: this.dependencies.now(),
+    ...(workflow ? { workflow } : {}),
+    ...(execution ? { execution } : {}),
+  };
+}
+
+function updateStatus(this: StatusContext): void {
+  refreshStatusWhileRunning.call(this);
+  if (!this.latestContext) return;
+  if (this.legacyProgressWidgetContext !== this.latestContext) {
+    this.latestContext.ui.setWidget(LEGACY_PROGRESS_WIDGET_KEY, undefined);
+    this.legacyProgressWidgetContext = this.latestContext;
+  }
+  if (!this.run) {
+    this.latestContext.ui.setStatus(STATUS_KEY, undefined);
+    return;
+  }
+  const snapshot = this.workflowStatusSnapshot();
+  if (this.run.status !== 'running') {
+    this.latestContext.ui.setStatus(STATUS_KEY, undefined);
+    return;
+  }
+  this.latestContext.ui.setStatus(
+    STATUS_KEY,
+    `${workflowStatusIcon(this.run, snapshot?.now)} ${this.run.workflowId}: working · ${this.statusShortcutLabel}`,
+  );
+}
+
+function refreshStatusWhileRunning(this: StatusContext): void {
+  if (this.run?.status === 'running' && this.latestContext) {
+    if (this.statusRefreshTimer) return;
+    this.statusRefreshTimer = this.dependencies.scheduleInterval(() => {
+      this.updateStatus();
+    }, STATUS_REFRESH_INTERVAL_MS);
+    this.statusRefreshTimer.unref();
+    return;
+  }
+  this.stopStatusRefresh();
+}
+
+function stopStatusRefresh(this: StatusContext): void {
+  if (this.statusRefreshTimer) {
+    this.dependencies.cancelInterval(this.statusRefreshTimer);
+  }
+  this.statusRefreshTimer = undefined;
+}
+
+function registerWorkflowStatusShortcut(this: StatusContext): void {
+  this.pi.registerShortcut(this.statusShortcut, {
+    description: 'Toggle workflow status',
+    handler: async (extensionContext) => {
+      this.latestContext = extensionContext;
+      if (this.isStatusOverlayOpen) return;
+      if (!this.run) {
+        extensionContext.ui.notify(
+          'No workflow checkpoint in this session',
+          'info',
+        );
+        return;
+      }
+      await this.showWorkflowStatus(extensionContext);
+    },
+  });
+}
+
+function openWorkflowStatus(
+  this: StatusContext,
+  context: ExtensionContext,
+): void {
+  void this.showWorkflowStatus(context).catch((error: unknown) => {
+    context.ui.notify(
+      `Cannot open workflow status: ${error instanceof Error ? error.message : String(error)}`,
+      'error',
+    );
+  });
+}
+
+async function showWorkflowStatus(
+  this: StatusContext,
+  context: ExtensionContext,
+): Promise<void> {
+  if (
+    this.isStatusOverlayOpen ||
+    !this.run ||
+    !context.hasUI ||
+    context.mode !== 'tui'
+  ) {
+    return;
+  }
+  this.isStatusOverlayOpen = true;
+  try {
+    await this.dependencies.showWorkflowStatus(
+      context,
+      () => this.workflowStatusSnapshot(),
+      this.statusShortcut,
+      {
+        scheduleRefresh: this.dependencies.scheduleInterval,
+        cancelRefresh: this.dependencies.cancelInterval,
+      },
+    );
+  } finally {
+    this.isStatusOverlayOpen = false;
+  }
+}
+
+/**
+ * Returns the status-related workflow actions for composition by the harness.
+ */
+export function createStatusActions(): StatusActions {
+  return {
+    workflowStatusSnapshot,
+    updateStatus,
+    refreshStatusWhileRunning,
+    stopStatusRefresh,
+    registerWorkflowStatusShortcut,
+    openWorkflowStatus,
+    showWorkflowStatus,
+  };
+}

package/src/harness/step-execution-actions.ts

@@ -0,0 +1,283 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { LoadedWorkflow, WorkflowStep } from '../config/types.ts';
+import type { WorkflowRun } from '../engine/state.ts';
+import { advanceRun, allowedOutcomes } from '../engine/transitions.ts';
+import { digest } from '../digest.ts';
+import type { SubagentDelegationResponse } from '../integrations/subagents/protocol.ts';
+import { buildMainStepTask } from '../prompt.ts';
+import { narrowApprovedBashCommands } from '../policy/approved-commands.ts';
+import type { MainStepExecution } from '../runtime/main-step-runtime.ts';
+import type { WorkflowStepResult } from '../runtime/step-result.ts';
+import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
+import { createDelegationPlan } from './delegation-plan.ts';
+import type { DelegationRecovery, MainStepIdentity } from './types.ts';
+
+type HarnessActionContext = Pick<
+  FullHarnessActionContext,
+  | 'activeDelegation'
+  | 'catalog'
+  | 'dependencies'
+  | 'finishMainStep'
+  | 'handleDelegationUpdate'
+  | 'isSessionActive'
+  | 'latestContext'
+  | 'launchMainStep'
+  | 'mainSteps'
+  | 'mutationQueue'
+  | 'pauseForExecutionFailure'
+  | 'pi'
+  | 'queueDelegationFailure'
+  | 'queueDelegationResponse'
+  | 'queueMainStepResult'
+  | 'run'
+  | 'sessionEpoch'
+  | 'settleAfterTransition'
+  | 'subagents'
+  | 'submitGate'
+  | 'updateStatus'
+>;
+
+export type StepExecutionActions = {
+  launchCurrentStep: (
+    this: HarnessActionContext,
+    workflow: LoadedWorkflow,
+    recovery?: DelegationRecovery,
+  ) => void;
+  launchMainStep: (
+    this: HarnessActionContext,
+    workflow: LoadedWorkflow,
+    run: WorkflowRun,
+    step: WorkflowStep,
+  ) => void;
+  queueMainStepResult: (
+    this: HarnessActionContext,
+    identity: MainStepIdentity,
+    result: WorkflowStepResult | undefined,
+    context: ExtensionContext,
+  ) => Promise<void>;
+  finishMainStep: (
+    this: HarnessActionContext,
+    identity: MainStepIdentity,
+    result: WorkflowStepResult | undefined,
+    context: ExtensionContext,
+  ) => Promise<void>;
+};
+
+function launchCurrentStep(
+  this: HarnessActionContext,
+  workflow: LoadedWorkflow,
+  recovery?: DelegationRecovery,
+): void {
+  const run = this.run;
+  if (
+    !run ||
+    run.status !== 'running' ||
+    this.activeDelegation ||
+    this.mainSteps.activeStepId
+  ) {
+    return;
+  }
+  const step = workflow.definition.steps[run.currentStepId];
+  if (!step) {
+    this.pauseForExecutionFailure(
+      'Workflow',
+      `Step "${run.currentStepId}" is missing from the workflow`,
+    );
+    return;
+  }
+  if (!step.subagent) {
+    this.launchMainStep(workflow, run, step);
+    return;
+  }
+
+  const plan = createDelegationPlan(
+    {
+      workflow,
+      run,
+      step,
+      sessionEpoch: this.sessionEpoch,
+      latestContext: this.latestContext,
+      recovery,
+    },
+    this.dependencies,
+  );
+  if (plan.kind === 'invalid') {
+    this.pauseForExecutionFailure('Subagent step', plan.reason);
+    return;
+  }
+  const { active, request } = plan;
+
+  this.activeDelegation = active;
+  this.updateStatus();
+  this.latestContext?.ui.notify(
+    `Delegated "${run.currentStepId}" to subagent "${active.agent}"`,
+    'info',
+  );
+  let delegation: Promise<SubagentDelegationResponse>;
+  try {
+    delegation = this.subagents.delegate(request, {
+      onUpdate: (update) => {
+        this.handleDelegationUpdate(active, update);
+      },
+      onLateTerminal: (response) => {
+        this.queueDelegationResponse(active, response);
+      },
+    });
+  } catch (error) {
+    this.queueDelegationFailure(
+      active,
+      error instanceof Error ? error.message : String(error),
+    );
+    return;
+  }
+  void delegation.then(
+    (response) => {
+      this.queueDelegationResponse(active, response);
+    },
+    (error: unknown) => {
+      this.queueDelegationFailure(
+        active,
+        error instanceof Error ? error.message : String(error),
+      );
+    },
+  );
+}
+
+function launchMainStep(
+  this: HarnessActionContext,
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  step: WorkflowStep,
+): void {
+  const approvedBashCommands = narrowApprovedBashCommands(
+    run.reviewedArtifact ?? '',
+    run.stepHandoff ?? '',
+    step.permissions.bash.approvedSources ?? [],
+  );
+  const identity: MainStepIdentity = {
+    runId: run.runId,
+    stepId: run.currentStepId,
+    stepDigest: run.currentStepDigest,
+    sessionEpoch: this.sessionEpoch,
+  };
+  const policyDigest = digest({
+    version: 1,
+    execution: 'main',
+    workflowId: workflow.definition.id,
+    runId: run.runId,
+    stepId: run.currentStepId,
+    stepDigest: run.currentStepDigest,
+    permissions: step.permissions,
+    approvedBashCommands,
+    nonce: this.dependencies.createRequestId(),
+  });
+  const execution: MainStepExecution = {
+    workflowId: workflow.definition.id,
+    runId: run.runId,
+    stepId: run.currentStepId,
+    stepDigest: run.currentStepDigest,
+    policyDigest,
+    step: structuredClone(step),
+    approvedBashCommands,
+    outcomes: allowedOutcomes(workflow, run),
+    summaryMaxChars: workflow.definition.summaryMaxChars,
+    ...(step.gate ? { gateSubmitOutcome: step.gate.submitOutcome } : {}),
+    onSettled: (result, context) =>
+      this.queueMainStepResult(identity, result, context),
+  };
+
+  try {
+    this.mainSteps.activate(execution);
+    this.updateStatus();
+    this.latestContext?.ui.notify(
+      `Started "${run.currentStepId}" in the main agent`,
+      'info',
+    );
+    this.pi.sendUserMessage(buildMainStepTask(workflow, run), {
+      deliverAs: 'followUp',
+    });
+  } catch (error) {
+    this.mainSteps.deactivate();
+    this.pauseForExecutionFailure(
+      'Main-agent step',
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
+
+function queueMainStepResult(
+  this: HarnessActionContext,
+  identity: MainStepIdentity,
+  result: WorkflowStepResult | undefined,
+  context: ExtensionContext,
+): Promise<void> {
+  return this.mutationQueue
+    .run(() => this.finishMainStep(identity, result, context))
+    .catch((error: unknown) => {
+      this.pauseForExecutionFailure(
+        'Main-agent step',
+        error instanceof Error ? error.message : String(error),
+      );
+    });
+}
+
+async function finishMainStep(
+  this: HarnessActionContext,
+  identity: MainStepIdentity,
+  result: WorkflowStepResult | undefined,
+  context: ExtensionContext,
+): Promise<void> {
+  this.latestContext = context;
+  if (
+    !this.isSessionActive ||
+    this.sessionEpoch !== identity.sessionEpoch ||
+    !this.run ||
+    this.run.status !== 'running' ||
+    this.run.runId !== identity.runId ||
+    this.run.currentStepId !== identity.stepId ||
+    this.run.currentStepDigest !== identity.stepDigest
+  ) {
+    return;
+  }
+  if (!result) {
+    throw new Error(
+      'agent settled without calling workflow_complete_step exactly once',
+    );
+  }
+
+  const workflow = this.catalog.workflows.get(this.run.workflowId);
+  const step = workflow?.definition.steps[this.run.currentStepId];
+  if (!workflow || !step) {
+    throw new Error('Active workflow configuration is unavailable');
+  }
+  if (step.gate?.submitOutcome === result.outcome) {
+    await this.submitGate(
+      workflow,
+      this.run,
+      result.outcome,
+      result.artifact ?? '',
+    );
+    return;
+  }
+
+  this.run = advanceRun(
+    workflow,
+    this.run,
+    result.outcome,
+    result.summary,
+    this.dependencies.now(),
+  );
+  this.settleAfterTransition(workflow);
+}
+
+/**
+ * Returns main and delegated step-launch actions for harness composition.
+ */
+export function createStepExecutionActions(): StepExecutionActions {
+  return {
+    launchCurrentStep,
+    launchMainStep,
+    queueMainStepResult,
+    finishMainStep,
+  };
+}

package/src/harness/types.ts

@@ -0,0 +1,76 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { DelegationReplayAudit } from '../integrations/subagents/diagnostics.ts';
+import type {
+  ChildStepPolicy,
+  SubagentDelegationStatus,
+} from '../integrations/subagents/protocol.ts';
+import type { WorkflowHarnessDependencies } from './dependencies.ts';
+
+export type ActiveDelegation = {
+  requestId: string;
+  runId: string;
+  stepId: string;
+  stepDigest: string;
+  sessionEpoch: number;
+  resultDirectory: string;
+  policy: ChildStepPolicy;
+  transcriptTask: string;
+  agent: string;
+  trustedSessionRoot?: string;
+  broadRecoveryAuthorized: boolean;
+  recoveryAttemptCount: number;
+  recoveryFailures: ReadonlyArray<DelegationRecoveryFailure>;
+  progress?: string;
+  cancelling?: boolean;
+};
+
+export type DelegationRecoveryBlocker =
+  | 'cancelled'
+  | 'detached'
+  | 'inconsistent-timeout'
+  | 'interrupted'
+  | 'reported-mutation'
+  | 'stopped';
+
+export type DelegationFailureDetails = {
+  reason: string;
+  status: SubagentDelegationStatus;
+  error?: string;
+  exitCode?: number;
+  recoveryBlocker?: DelegationRecoveryBlocker;
+  diagnostic?: Awaited<
+    ReturnType<WorkflowHarnessDependencies['readToolFailureDiagnostic']>
+  >;
+  replayAudit?: DelegationReplayAudit;
+};
+
+export type MainStepIdentity = {
+  runId: string;
+  stepId: string;
+  stepDigest: string;
+  sessionEpoch: number;
+};
+
+export type ActivePromptReview = {
+  requestId: string;
+  runId: string;
+  stepId: string;
+  sessionEpoch: number;
+  abortController: AbortController;
+};
+
+export type WorkflowStartContext = {
+  context: ExtensionContext;
+  skills: () => ReadonlyArray<{ name: string }> | undefined;
+  waitForIdle: () => Promise<void>;
+};
+
+export type DelegationRecoveryFailure = {
+  readonly fingerprint: string;
+  readonly reason: string;
+};
+
+export type DelegationRecovery = {
+  readonly attempt: number;
+  readonly failures: ReadonlyArray<DelegationRecoveryFailure>;
+};