@wichayutdew/pi-workflows 1.0.1 → 2.0.0

package/src/harness/status-actions.ts

@@ -7,7 +7,7 @@ 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,
+  formatWorkflowProgressStatus,
   type WorkflowStatusExecution,
   type WorkflowStatusSnapshot,
 } from '../workflow-status.ts';
@@ -45,7 +45,6 @@ export type StatusActions = {
   refreshStatusWhileRunning: (this: StatusContext) => void;
   stopStatusRefresh: (this: StatusContext) => void;
   registerWorkflowStatusShortcut: (this: StatusContext) => void;
-  openWorkflowStatus: (this: StatusContext, context: ExtensionContext) => void;
   showWorkflowStatus: (
     this: StatusContext,
     context: ExtensionContext,
@@ -88,13 +87,17 @@ function updateStatus(this: StatusContext): void {
     return;
   }
   const snapshot = this.workflowStatusSnapshot();
-  if (this.run.status !== 'running') {
+  if (this.run.status !== 'running' && this.run.status !== 'awaiting-gate') {
+    this.latestContext.ui.setStatus(STATUS_KEY, undefined);
+    return;
+  }
+  if (!snapshot) {
     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}`,
+    formatWorkflowProgressStatus(snapshot, this.statusShortcutLabel),
   );
 }
 
@@ -135,18 +138,6 @@ function registerWorkflowStatusShortcut(this: StatusContext): void {
   });
 }
 
-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,
@@ -185,7 +176,6 @@ export function createStatusActions(): StatusActions {
     refreshStatusWhileRunning,
     stopStatusRefresh,
     registerWorkflowStatusShortcut,
-    openWorkflowStatus,
     showWorkflowStatus,
   };
 }

package/src/harness/step-effects.ts

@@ -0,0 +1,61 @@
+import type { WorkflowStep } from '../config/types.ts';
+import type { WorkflowRun } from '../engine/state.ts';
+import type { RunStepEffects } from '../engine/run-advance.ts';
+import type { WorkflowStepResult } from '../runtime/step-result.ts';
+import type { WorkflowHarnessDependencies } from './dependencies.ts';
+
+type StepEffectDependencies = Pick<
+  WorkflowHarnessDependencies,
+  'resolveWorkspaceDirectory'
+>;
+
+const boundWorkspaceCwd = (run: WorkflowRun): string | undefined => {
+  for (let index = run.history.length - 1; index >= 0; index -= 1) {
+    const cwd = run.history[index]?.workspaceCwd;
+    if (cwd) return cwd;
+  }
+  return undefined;
+};
+
+/**
+ * Validates declarative effects carried by a structured step result.
+ *
+ * No prompt text, summary, artifact, command, or repository convention is
+ * interpreted here.
+ */
+export function resolveStepEffects(
+  run: WorkflowRun,
+  step: WorkflowStep,
+  result: WorkflowStepResult,
+  dependencies: StepEffectDependencies,
+): RunStepEffects {
+  const shouldBind = step.workspace?.bindOn.includes(result.outcome) ?? false;
+  if (shouldBind && !result.workspace) {
+    throw new Error(
+      `step outcome "${result.outcome}" requires a workspace result`,
+    );
+  }
+  if (!shouldBind && result.workspace) {
+    throw new Error(
+      `step outcome "${result.outcome}" is not allowed to bind a workspace`,
+    );
+  }
+  if (!result.workspace || !step.workspace) return {};
+  const startCwd = run.startCwd ?? run.cwd;
+  if (!startCwd) {
+    throw new Error(
+      'workflow run has no starting directory for workspace validation',
+    );
+  }
+
+  const workspaceCwd = dependencies.resolveWorkspaceDirectory({
+    candidateCwd: result.workspace.cwd,
+    startCwd,
+    allowedRoots: step.workspace.allowedRoots,
+  });
+  const existingCwd = boundWorkspaceCwd(run);
+  if (existingCwd && existingCwd !== workspaceCwd) {
+    throw new Error(`workflow workspace is already bound to "${existingCwd}"`);
+  }
+  return { workspaceCwd };
+}

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

@@ -1,16 +1,22 @@
 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 {
+  appendMainStepLog,
+  beginMainStepAttempt,
+  beginSubagentStepAttempt,
+  recordCurrentStepResult,
+} from '../engine/step-trace.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';
+import { resolveStepEffects } from './step-effects.ts';
 
 type HarnessActionContext = Pick<
   FullHarnessActionContext,
@@ -25,10 +31,13 @@ type HarnessActionContext = Pick<
   | 'mainSteps'
   | 'mutationQueue'
   | 'pauseForExecutionFailure'
+  | 'persist'
   | 'pi'
   | 'queueDelegationFailure'
   | 'queueDelegationResponse'
+  | 'queueMainStepLog'
   | 'queueMainStepResult'
+  | 'recordMainStepLog'
   | 'run'
   | 'sessionEpoch'
   | 'settleAfterTransition'
@@ -49,6 +58,18 @@ export type StepExecutionActions = {
     run: WorkflowRun,
     step: WorkflowStep,
   ) => void;
+  queueMainStepLog: (
+    this: HarnessActionContext,
+    identity: MainStepIdentity,
+    lines: ReadonlyArray<string>,
+    context: ExtensionContext,
+  ) => Promise<void>;
+  recordMainStepLog: (
+    this: HarnessActionContext,
+    identity: MainStepIdentity,
+    lines: ReadonlyArray<string>,
+    context: ExtensionContext,
+  ) => Promise<void>;
   queueMainStepResult: (
     this: HarnessActionContext,
     identity: MainStepIdentity,
@@ -107,6 +128,18 @@ function launchCurrentStep(
   }
   const { active, request } = plan;
 
+  try {
+    this.run = beginSubagentStepAttempt(
+      run,
+      active.requestId,
+      active.agent,
+      active.transcriptTask,
+      this.dependencies.now(),
+    );
+    this.persist();
+  } catch {
+    // Status evidence is best-effort and must never block step execution.
+  }
   this.activeDelegation = active;
   this.updateStatus();
   this.latestContext?.ui.notify(
@@ -149,17 +182,38 @@ function launchMainStep(
   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 actualCwd = this.latestContext?.cwd;
+  if (!run.cwd || !actualCwd) {
+    this.pauseForExecutionFailure(
+      'Main-agent step',
+      'Workflow working directory is unavailable; abort it and start a new run',
+    );
+    return;
+  }
+  try {
+    const expectedCanonicalCwd = this.dependencies.resolveWorkspaceDirectory({
+      candidateCwd: run.cwd,
+      startCwd: run.cwd,
+      allowedRoots: ['.'],
+    });
+    const actualCanonicalCwd = this.dependencies.resolveWorkspaceDirectory({
+      candidateCwd: actualCwd,
+      startCwd: actualCwd,
+      allowedRoots: ['.'],
+    });
+    if (actualCanonicalCwd !== expectedCanonicalCwd) {
+      throw new Error(
+        `current session cwd "${actualCwd}" does not match captured workflow cwd "${run.cwd}"`,
+      );
+    }
+  } catch (error) {
+    this.pauseForExecutionFailure(
+      'Main-agent step',
+      error instanceof Error ? error.message : String(error),
+    );
+    return;
+  }
+
   const policyDigest = digest({
     version: 1,
     execution: 'main',
@@ -168,32 +222,52 @@ function launchMainStep(
     stepId: run.currentStepId,
     stepDigest: run.currentStepDigest,
     permissions: step.permissions,
-    approvedBashCommands,
     nonce: this.dependencies.createRequestId(),
   });
+  const task = buildMainStepTask(workflow, run);
+  const identity: MainStepIdentity = {
+    requestId: policyDigest,
+    runId: run.runId,
+    stepId: run.currentStepId,
+    stepDigest: run.currentStepDigest,
+    sessionEpoch: this.sessionEpoch,
+  };
   const execution: MainStepExecution = {
     workflowId: workflow.definition.id,
     runId: run.runId,
     stepId: run.currentStepId,
     stepDigest: run.currentStepDigest,
     policyDigest,
+    task,
     step: structuredClone(step),
-    approvedBashCommands,
     outcomes: allowedOutcomes(workflow, run),
     summaryMaxChars: workflow.definition.summaryMaxChars,
     ...(step.gate ? { gateSubmitOutcome: step.gate.submitOutcome } : {}),
+    onTrace: (lines, context) =>
+      this.queueMainStepLog(identity, lines, context),
     onSettled: (result, context) =>
       this.queueMainStepResult(identity, result, context),
   };
 
   try {
+    try {
+      this.run = beginMainStepAttempt(
+        run,
+        policyDigest,
+        task,
+        this.dependencies.now(),
+      );
+      this.persist();
+    } catch {
+      // Status evidence is best-effort and must never block step execution.
+    }
     this.mainSteps.activate(execution);
     this.updateStatus();
     this.latestContext?.ui.notify(
       `Started "${run.currentStepId}" in the main agent`,
       'info',
     );
-    this.pi.sendUserMessage(buildMainStepTask(workflow, run), {
+    this.pi.sendUserMessage(task, {
       deliverAs: 'followUp',
     });
   } catch (error) {
@@ -205,6 +279,73 @@ function launchMainStep(
   }
 }
 
+function hasCurrentMainStepIdentity(
+  context: HarnessActionContext,
+  identity: MainStepIdentity,
+): context is HarnessActionContext & { run: WorkflowRun } {
+  return (
+    context.isSessionActive &&
+    context.sessionEpoch === identity.sessionEpoch &&
+    context.run?.status === 'running' &&
+    context.run.runId === identity.runId &&
+    context.run.currentStepId === identity.stepId &&
+    context.run.currentStepDigest === identity.stepDigest
+  );
+}
+
+function matchesLatestMainStepAttempt(
+  run: WorkflowRun,
+  identity: MainStepIdentity,
+): boolean {
+  const attempt = run.currentStepAttempts?.at(-1);
+  return (
+    attempt === undefined ||
+    (attempt.kind === 'main' && attempt.requestId === identity.requestId)
+  );
+}
+
+function queueMainStepLog(
+  this: HarnessActionContext,
+  identity: MainStepIdentity,
+  lines: ReadonlyArray<string>,
+  context: ExtensionContext,
+): Promise<void> {
+  return this.mutationQueue
+    .run(() => this.recordMainStepLog(identity, lines, context))
+    .catch(() => {
+      // Status evidence is best-effort and must never pause step execution.
+    });
+}
+
+async function recordMainStepLog(
+  this: HarnessActionContext,
+  identity: MainStepIdentity,
+  lines: ReadonlyArray<string>,
+  context: ExtensionContext,
+): Promise<void> {
+  if (
+    !hasCurrentMainStepIdentity(this, identity) ||
+    !matchesLatestMainStepAttempt(this.run, identity)
+  ) {
+    return;
+  }
+  const attempt = this.run.currentStepAttempts?.at(-1);
+  if (attempt?.kind !== 'main' || attempt.requestId !== identity.requestId) {
+    return;
+  }
+  this.latestContext = context;
+  const traced = appendMainStepLog(
+    this.run,
+    identity.requestId,
+    lines,
+    this.dependencies.now(),
+  );
+  if (traced === this.run) return;
+  this.run = traced;
+  this.persist();
+  this.updateStatus();
+}
+
 function queueMainStepResult(
   this: HarnessActionContext,
   identity: MainStepIdentity,
@@ -227,18 +368,13 @@ async function finishMainStep(
   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
+    !hasCurrentMainStepIdentity(this, identity) ||
+    !matchesLatestMainStepAttempt(this.run, identity)
   ) {
     return;
   }
+  this.latestContext = context;
   if (!result) {
     throw new Error(
       'agent settled without calling workflow_complete_step exactly once',
@@ -251,23 +387,41 @@ async function finishMainStep(
     throw new Error('Active workflow configuration is unavailable');
   }
   if (step.gate?.submitOutcome === result.outcome) {
+    this.run = recordCurrentStepResult(
+      this.run,
+      result,
+      this.dependencies.now(),
+    );
     await this.submitGate(
       workflow,
       this.run,
       result.outcome,
+      result.summary,
       result.artifact ?? '',
     );
     return;
   }
 
+  const effects = resolveStepEffects(this.run, step, result, this.dependencies);
+  const tracedRun = recordCurrentStepResult(
+    this.run,
+    result,
+    this.dependencies.now(),
+    effects.workspaceCwd,
+  );
   this.run = advanceRun(
     workflow,
-    this.run,
+    tracedRun,
     result.outcome,
     result.summary,
     this.dependencies.now(),
+    effects,
   );
-  this.settleAfterTransition(workflow);
+  this.settleAfterTransition(workflow, {
+    stepId: identity.stepId,
+    outcome: result.outcome,
+    summary: result.summary,
+  });
 }
 
 /**
@@ -277,6 +431,8 @@ export function createStepExecutionActions(): StepExecutionActions {
   return {
     launchCurrentStep,
     launchMainStep,
+    queueMainStepLog,
+    recordMainStepLog,
     queueMainStepResult,
     finishMainStep,
   };

package/src/harness/step-reporting.ts

@@ -0,0 +1,168 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { LoadedWorkflow } from '../config/types.ts';
+import type { WorkflowRun } from '../engine/state.ts';
+import { redactStepDetailText } from '../step-log.ts';
+
+export const WORKFLOW_STEP_SUMMARY_MESSAGE_TYPE = 'workflow-step-summary';
+export const MAX_POSTED_STEP_SUMMARY_CHARS = 4_000;
+export const MAX_POSTED_STEP_FAILURE_CHARS = 1_000;
+
+export type SettledStepReport = {
+  readonly stepId: string;
+  readonly outcome: string;
+  readonly summary: string;
+};
+
+type StepSummaryDetails = {
+  readonly workflowId: string;
+  readonly runId: string;
+  readonly stepId: string;
+  readonly stepTitle: string;
+  readonly status: 'completed' | 'paused' | 'failed';
+  readonly outcome?: string;
+  readonly workflowCompleted: boolean;
+};
+
+function boundedPostedText(value: string, maxChars: number): string {
+  const normalized = redactStepDetailText(value).trim();
+  if (normalized.length <= maxChars) return normalized;
+  return `${normalized.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+
+/** Produces the only failure text suitable for compact chat/toast surfaces. */
+export function conciseStepFailureSummary(reason: string): string {
+  return (
+    boundedPostedText(reason, MAX_POSTED_STEP_FAILURE_CHARS) ||
+    'The step failed without a diagnostic summary.'
+  );
+}
+
+/** Produces a compact pause reason while full state remains in the checkpoint. */
+export function conciseStepPauseSummary(reason: string): string {
+  return (
+    boundedPostedText(reason, MAX_POSTED_STEP_FAILURE_CHARS) ||
+    'Manual action is required before this step can continue.'
+  );
+}
+
+function stepTitle(
+  workflow: LoadedWorkflow | undefined,
+  stepId: string,
+): string {
+  const title = workflow?.definition.steps[stepId]?.title ?? stepId;
+  return boundedPostedText(title, 200) || stepId;
+}
+
+function postStepMessage(
+  pi: ExtensionAPI,
+  content: string,
+  details: StepSummaryDetails,
+): void {
+  try {
+    pi.sendMessage(
+      {
+        customType: WORKFLOW_STEP_SUMMARY_MESSAGE_TYPE,
+        content,
+        display: true,
+        details,
+      },
+      { triggerTurn: false },
+    );
+  } catch {
+    // Reporting is best-effort and must never block a durable transition.
+  }
+}
+
+/**
+ * Posts only the structured handoff supplied by a successfully settled step.
+ *
+ * Execution transcripts and artifacts are deliberately unavailable to this
+ * function, so they cannot leak into the concise chat summary.
+ */
+export function reportSettledStep(
+  pi: ExtensionAPI,
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  report: SettledStepReport,
+): void {
+  const workflowCompleted = run.status === 'completed';
+  const paused =
+    run.status === 'paused' &&
+    run.failedStepId === undefined &&
+    run.currentStepId === report.stepId;
+  const status = paused ? 'paused' : 'completed';
+  const title = stepTitle(workflow, report.stepId);
+  const summary =
+    boundedPostedText(report.summary, MAX_POSTED_STEP_SUMMARY_CHARS) ||
+    'No summary was provided.';
+  const completion = workflowCompleted
+    ? `\n\nWorkflow \`${run.workflowId}\` completed.`
+    : '';
+  postStepMessage(
+    pi,
+    `### Step ${status}: ${title} (\`${report.stepId}\`)\n\n` +
+      `Outcome: \`${report.outcome}\`\n\n${summary}${completion}`,
+    {
+      workflowId: run.workflowId,
+      runId: run.runId,
+      stepId: report.stepId,
+      stepTitle: title,
+      status,
+      outcome: report.outcome,
+      workflowCompleted,
+    },
+  );
+}
+
+/**
+ * Posts a concise failure reason for the current step.
+ *
+ * The full diagnostic remains in the workflow checkpoint/status explorer.
+ * Only a redacted prefix is displayed in chat.
+ */
+export function reportFailedStep(
+  pi: ExtensionAPI,
+  workflow: LoadedWorkflow | undefined,
+  run: WorkflowRun,
+  reason: string,
+): void {
+  const title = stepTitle(workflow, run.currentStepId);
+  const summary = conciseStepFailureSummary(reason);
+  postStepMessage(
+    pi,
+    `### Step failed: ${title} (\`${run.currentStepId}\`)\n\n${summary}\n\n` +
+      `Workflow \`${run.workflowId}\` is paused.`,
+    {
+      workflowId: run.workflowId,
+      runId: run.runId,
+      stepId: run.currentStepId,
+      stepTitle: title,
+      status: 'failed',
+      workflowCompleted: false,
+    },
+  );
+}
+
+/** Posts the concise reason for a non-failure workflow pause. */
+export function reportPausedStep(
+  pi: ExtensionAPI,
+  workflow: LoadedWorkflow | undefined,
+  run: WorkflowRun,
+  reason: string,
+): void {
+  const title = stepTitle(workflow, run.currentStepId);
+  const summary = conciseStepPauseSummary(reason);
+  postStepMessage(
+    pi,
+    `### Step paused: ${title} (\`${run.currentStepId}\`)\n\n${summary}\n\n` +
+      `Workflow \`${run.workflowId}\` is paused.`,
+    {
+      workflowId: run.workflowId,
+      runId: run.runId,
+      stepId: run.currentStepId,
+      stepTitle: title,
+      status: 'paused',
+      workflowCompleted: false,
+    },
+  );
+}

package/src/harness/types.ts

@@ -45,6 +45,7 @@ export type DelegationFailureDetails = {
 };
 
 export type MainStepIdentity = {
+  requestId: string;
   runId: string;
   stepId: string;
   stepDigest: string;

package/src/harness/workspace-directory.ts

@@ -0,0 +1,67 @@
+import { realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep, win32 } from 'node:path';
+
+export type ResolveWorkspaceDirectoryOptions = {
+  readonly candidateCwd: string;
+  readonly startCwd: string;
+  readonly allowedRoots: ReadonlyArray<string>;
+};
+
+const isWithin = (root: string, candidate: string): boolean => {
+  const pathFromRoot = relative(root, candidate);
+  return (
+    pathFromRoot === '' ||
+    (pathFromRoot !== '..' &&
+      !pathFromRoot.startsWith(`..${sep}`) &&
+      !isAbsolute(pathFromRoot))
+  );
+};
+
+/**
+ * Canonicalizes and validates one YAML-authorized execution directory.
+ *
+ * This boundary intentionally knows only filesystem paths. The workflow prompt
+ * owns how the directory was selected or created.
+ */
+export function resolveWorkspaceDirectory({
+  candidateCwd,
+  startCwd,
+  allowedRoots,
+}: ResolveWorkspaceDirectoryOptions): string {
+  if (
+    !candidateCwd ||
+    !isAbsolute(candidateCwd) ||
+    candidateCwd.includes('\0')
+  ) {
+    throw new Error('workspace cwd must be a non-empty absolute path');
+  }
+  if (!startCwd || !isAbsolute(startCwd) || startCwd.includes('\0')) {
+    throw new Error('workflow start cwd must be a non-empty absolute path');
+  }
+  if (allowedRoots.length === 0) {
+    throw new Error('workspace binding must declare an allowed root');
+  }
+
+  const canonicalStart = realpathSync(startCwd);
+  const canonicalRoots = allowedRoots.map((allowedRoot) => {
+    if (
+      !allowedRoot ||
+      isAbsolute(allowedRoot) ||
+      win32.parse(allowedRoot).root !== '' ||
+      allowedRoot.includes('\0')
+    ) {
+      throw new Error(
+        'workspace allowed roots must be non-empty relative paths',
+      );
+    }
+    return realpathSync(resolve(canonicalStart, allowedRoot));
+  });
+  const canonicalCwd = realpathSync(candidateCwd);
+  if (!statSync(canonicalCwd).isDirectory()) {
+    throw new Error('workspace cwd must resolve to a directory');
+  }
+  if (!canonicalRoots.some((root) => isWithin(root, canonicalCwd))) {
+    throw new Error('workspace cwd is outside the YAML-authorized roots');
+  }
+  return canonicalCwd;
+}