@wichayutdew/pi-workflows 1.0.1 → 2.0.1

package/src/config/validation/step.ts

@@ -1,10 +1,19 @@
-import type { PromptSpec, WorkflowGate, WorkflowStep } from '../types.ts';
+import { isAbsolute, win32 } from 'node:path';
+import {
+  MAX_WORKSPACE_ALLOWED_ROOTS,
+  MAX_WORKSPACE_PATH_CHARS,
+  type PromptSpec,
+  type StepWorkspaceBinding,
+  type WorkflowGate,
+  type WorkflowStep,
+} from '../types.ts';
 import { parsePermissions, parseRequirements } from './permissions.ts';
 import {
   isJsonObject,
   OUTCOME_PATTERN,
   readInteger,
   readString,
+  readStringList,
   rejectUnknownKeys,
   type ValidationErrors,
 } from './shared.ts';
@@ -135,7 +144,7 @@ function parseGate(
         rejectedOutcome,
         timeoutMs: readInteger(
           value.timeoutMs,
-          5_000,
+          30_000,
           `${path}.timeoutMs`,
           errors,
           { min: 1_000, max: 30_000 },
@@ -143,6 +152,85 @@ function parseGate(
       };
 }
 
+function parseWorkspaceRoots(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): Array<string> {
+  if (value === undefined) return ['.'];
+  if (!Array.isArray(value)) {
+    errors.push(`${path}: expected an array of relative paths`);
+    return [];
+  }
+  if (value.length > MAX_WORKSPACE_ALLOWED_ROOTS) {
+    errors.push(
+      `${path}: at most ${MAX_WORKSPACE_ALLOWED_ROOTS} relative paths are allowed`,
+    );
+  }
+
+  const roots = value
+    .slice(0, MAX_WORKSPACE_ALLOWED_ROOTS)
+    .reduce<Array<string>>((result, item, index) => {
+      const itemPath = `${path}[${index}]`;
+      if (typeof item !== 'string' || !item || item.trim() !== item) {
+        errors.push(`${itemPath}: expected a non-empty relative path`);
+        return result;
+      }
+      const root = item;
+      if (root.length > MAX_WORKSPACE_PATH_CHARS) {
+        errors.push(
+          `${itemPath}: path exceeds ${MAX_WORKSPACE_PATH_CHARS} characters`,
+        );
+        return result;
+      }
+      if (
+        root.includes('\0') ||
+        isAbsolute(root) ||
+        win32.parse(root).root !== ''
+      ) {
+        errors.push(`${itemPath}: expected a relative path`);
+        return result;
+      }
+      if (result.includes(root)) {
+        errors.push(`${itemPath}: duplicate value "${root}"`);
+        return result;
+      }
+      return [...result, root];
+    }, []);
+  if (roots.length === 0) {
+    errors.push(`${path}: at least one relative path is required`);
+  }
+  return roots;
+}
+
+function parseWorkspace(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): StepWorkspaceBinding | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(value, ['bindOn', 'allowedRoots'], path, errors);
+  const bindOn = readStringList(
+    value.bindOn,
+    `${path}.bindOn`,
+    errors,
+    OUTCOME_PATTERN,
+  );
+  if (bindOn.length === 0) {
+    errors.push(`${path}.bindOn: at least one outcome is required`);
+  }
+  const allowedRoots = parseWorkspaceRoots(
+    value.allowedRoots,
+    `${path}.allowedRoots`,
+    errors,
+  );
+  return { bindOn, allowedRoots };
+}
+
 /** Parse one workflow step and validate relationships within that step. */
 export function parseWorkflowStep(
   value: unknown,
@@ -164,6 +252,7 @@ export function parseWorkflowStep(
       'requires',
       'transitions',
       'gate',
+      'workspace',
     ],
     path,
     errors,
@@ -196,6 +285,11 @@ export function parseWorkflowStep(
     errors,
   );
   const gate = parseGate(value.gate, `${path}.gate`, errors);
+  const workspace = parseWorkspace(
+    value.workspace,
+    `${path}.workspace`,
+    errors,
+  );
 
   if (gate) {
     if (!Object.hasOwn(transitions, gate.approvedOutcome)) {
@@ -214,6 +308,15 @@ export function parseWorkflowStep(
       );
     }
   }
+  if (workspace) {
+    workspace.bindOn.forEach((outcome) => {
+      if (!Object.hasOwn(transitions, outcome)) {
+        errors.push(
+          `${path}.workspace.bindOn: unknown transition outcome "${outcome}"`,
+        );
+      }
+    });
+  }
 
   if (!title || !prompt) return undefined;
   return {
@@ -224,5 +327,6 @@ export function parseWorkflowStep(
     requires,
     transitions,
     ...(gate ? { gate } : {}),
+    ...(workspace ? { workspace } : {}),
   };
 }

package/src/config/validation/workflow.ts

@@ -67,6 +67,82 @@ function validateGraph(
       }
     });
   });
+  validateWorkspaceGraph(steps, errors);
+}
+
+function validateWorkspaceGraph(
+  steps: Readonly<Record<string, WorkflowStep>>,
+  errors: ValidationErrors,
+): void {
+  const binders = Object.entries(steps).filter(
+    (
+      entry,
+    ): entry is [
+      string,
+      WorkflowStep & { workspace: NonNullable<WorkflowStep['workspace']> },
+    ] => entry[1].workspace !== undefined,
+  );
+  const firstBinderId = binders[0]?.[0];
+
+  binders.forEach(([stepId, step], index) => {
+    const workspacePath = `workflow.steps.${stepId}.workspace`;
+    if (index > 0) {
+      errors.push(
+        `${workspacePath}: only one workspace-binding step is allowed; "${firstBinderId}" also configures workspace binding`,
+      );
+    }
+    if (!step.subagent) {
+      errors.push(`${workspacePath}: workspace binding requires a subagent`);
+    }
+    if (step.gate) {
+      errors.push(
+        `${workspacePath}: workspace binding is not allowed on a gated step`,
+      );
+    }
+
+    const downstream = step.workspace.bindOn.flatMap((outcome) => {
+      const target = step.transitions[outcome];
+      if (target === '$done' || target === '$pause') {
+        errors.push(
+          `workflow.steps.${stepId}.transitions.${outcome}: workspace-binding outcome must target an ordinary step`,
+        );
+        return [];
+      }
+      return target && Object.hasOwn(steps, target) ? [target] : [];
+    });
+    validateWorkspaceDescendants(steps, downstream, errors);
+  });
+}
+
+function validateWorkspaceDescendants(
+  steps: Readonly<Record<string, WorkflowStep>>,
+  initialStepIds: ReadonlyArray<string>,
+  errors: ValidationErrors,
+): void {
+  const pending = [...initialStepIds];
+  const visited = new Set<string>();
+  while (pending.length > 0) {
+    const stepId = pending.pop();
+    if (!stepId || visited.has(stepId)) continue;
+    visited.add(stepId);
+    const step = steps[stepId];
+    if (!step) continue;
+    if (!step.subagent) {
+      errors.push(
+        `workflow.steps.${stepId}.subagent: every nonterminal step reachable after workspace binding must use a subagent`,
+      );
+    }
+    Object.values(step.transitions).forEach((target) => {
+      if (
+        target !== '$done' &&
+        target !== '$pause' &&
+        Object.hasOwn(steps, target) &&
+        !visited.has(target)
+      ) {
+        pending.push(target);
+      }
+    });
+  }
 }
 
 /** Validate and normalize an untrusted workflow definition. */

package/src/engine/create-run.ts

@@ -10,6 +10,7 @@ import type { WorkflowRun } from './state-types.ts';
  * @param baselineTools - Tool names available before workflow restrictions.
  * @param runId - Stable run identifier.
  * @param now - Creation timestamp.
+ * @param cwd - Canonical working directory captured at workflow start.
  * @returns A new running workflow state.
  */
 export const createRun = (
@@ -18,6 +19,7 @@ export const createRun = (
   baselineTools: ReadonlyArray<string>,
   runId: string,
   now: number,
+  cwd?: string,
 ): WorkflowRun => {
   const startStepId = workflow.definition.start;
   return {
@@ -36,6 +38,7 @@ export const createRun = (
     updatedAt: now,
     reviewedArtifact: '',
     reviewedFeedback: '',
+    ...(cwd ? { startCwd: cwd, cwd } : {}),
     stepHandoff: '',
     lastSummary: '',
     gateFeedback: '',

package/src/engine/gate-transitions.ts

@@ -1,5 +1,6 @@
 import type { LoadedWorkflow } from '../config/types.ts';
 import { advanceRun } from './run-advance.ts';
+import { recordCurrentGateDecision } from './step-trace.ts';
 import type { GateResolution, WorkflowRun } from './state-types.ts';
 import { currentStep, withRunUpdate } from './transition-helpers.ts';
 
@@ -12,6 +13,7 @@ import { currentStep, withRunUpdate } from './transition-helpers.ts';
  * @param artifact - Artifact to display for review.
  * @param requestId - Stable gate request identifier.
  * @param now - Update timestamp.
+ * @param summary - Compact step handoff, separate from the review artifact.
  * @returns A new awaiting-gate workflow state.
  * @throws When the run or gate submission is invalid.
  */
@@ -22,6 +24,7 @@ export const beginGate = (
   artifact: string,
   requestId: string,
   now: number,
+  summary: string,
 ): WorkflowRun => {
   if (run.status !== 'running') {
     throw new Error(
@@ -38,6 +41,9 @@ export const beginGate = (
   if (!artifact.trim()) {
     throw new Error('gate submission requires a non-empty artifact');
   }
+  if (!summary.trim()) {
+    throw new Error('gate submission requires a non-empty summary');
+  }
   if (!requestId) throw new Error('gate submission requires a request id');
 
   return withRunUpdate(
@@ -49,6 +55,7 @@ export const beginGate = (
         requestId,
         stepId: run.currentStepId,
         artifact,
+        summary,
         submittedOutcome: outcome,
         requestedAt: now,
       },
@@ -102,6 +109,9 @@ export const failGate = (
           status: 'running',
           pendingGate: undefined,
           gateFeedback: reason,
+          pausedFrom: undefined,
+          pauseReason: undefined,
+          failedStepId: undefined,
         },
         now,
       )
@@ -158,30 +168,69 @@ export const resolveGate = (
   const outcome = resolution.approved
     ? step.gate.approvedOutcome
     : step.gate.rejectedOutcome;
+  const stepStructuralDigest =
+    workflow.stepStructuralDigests[pendingGate.stepId] ?? '';
+  if (resolution.approved && !stepStructuralDigest) {
+    throw new Error(
+      `gated step "${pendingGate.stepId}" has no structural digest`,
+    );
+  }
   const summary = resolution.approved
-    ? pendingGate.artifact
+    ? (pendingGate.summary ?? '')
     : resolution.feedback
       ? `Gate rejected: ${resolution.feedback}`
       : 'Gate rejected';
-  const runnableRun = withRunUpdate(
+  const decidedRun = recordCurrentGateDecision(
     run,
+    {
+      provider: pendingGate.provider,
+      requestId: pendingGate.requestId,
+      approved: resolution.approved,
+      feedback: resolution.feedback,
+      resolvedAt: resolution.resolvedAt,
+      ...(pendingGate.reviewId ? { reviewId: pendingGate.reviewId } : {}),
+    },
+    now,
+  );
+  const runnableRun = withRunUpdate(
+    decidedRun,
     {
       status: 'running',
       pendingGate: undefined,
-      ...(resolution.approved
-        ? {
-            reviewedArtifact: pendingGate.artifact,
-            reviewedFeedback: resolution.feedback,
-          }
-        : {}),
       pausedFrom: undefined,
       pauseReason: undefined,
       gateFeedback: resolution.feedback,
     },
     now,
   );
+  const advanced = advanceRun(workflow, runnableRun, outcome, summary, now);
+  const completedApprovedGate =
+    resolution.approved && advanced.history.length > runnableRun.history.length;
+  const history = completedApprovedGate
+    ? advanced.history.map((entry, index) =>
+        index === advanced.history.length - 1
+          ? {
+              ...entry,
+              artifact: pendingGate.artifact,
+              approval: {
+                requestId: pendingGate.requestId,
+                artifact: pendingGate.artifact,
+                feedback: resolution.feedback,
+                stepStructuralDigest,
+              },
+            }
+          : entry,
+      )
+    : advanced.history;
   return {
-    ...advanceRun(workflow, runnableRun, outcome, summary, now),
+    ...advanced,
+    history,
+    ...(completedApprovedGate
+      ? {
+          reviewedArtifact: pendingGate.artifact,
+          reviewedFeedback: resolution.feedback,
+        }
+      : {}),
     gateFeedback: resolution.feedback,
   };
 };

package/src/engine/reconciliation-history.ts

@@ -1,6 +1,30 @@
 import type { LoadedWorkflow } from '../config/types.ts';
 import type { StepHistoryEntry, WorkflowRun } from './state-types.ts';
 
+type ReviewedApproval = {
+  readonly artifact: string;
+  readonly feedback: string;
+};
+
+const isApprovedGateEntry = (
+  workflow: LoadedWorkflow,
+  entry: StepHistoryEntry,
+): boolean => {
+  const gate = workflow.definition.steps[entry.stepId]?.gate;
+  return gate !== undefined && entry.outcome === gate.approvedOutcome;
+};
+
+const latestApprovedGateEntry = (
+  workflow: LoadedWorkflow,
+  history: ReadonlyArray<StepHistoryEntry>,
+): { readonly entry: StepHistoryEntry; readonly index: number } | undefined => {
+  for (let index = history.length - 1; index >= 0; index -= 1) {
+    const entry = history[index];
+    if (entry && isApprovedGateEntry(workflow, entry)) return { entry, index };
+  }
+  return undefined;
+};
+
 /**
  * Rebuilds step visit counts from retained history and the current step.
  *
@@ -26,37 +50,49 @@ export const rebuildVisits = (
 };
 
 /**
- * Retains reviewed authority only when its approving history remains.
+ * Restores the execution directory represented by retained history.
  *
- * @param workflow - Updated workflow.
- * @param run - Existing workflow state.
+ * @param run - Existing workflow state with immutable start directory.
  * @param history - History retained after reconciliation.
- * @returns The retained artifact, or an empty string when provenance was lost.
+ * @returns The latest retained binding, or the workflow start directory.
  */
-export const retainedReviewedArtifact = (
-  workflow: LoadedWorkflow,
+export const retainedWorkspaceCwd = (
   run: WorkflowRun,
   history: ReadonlyArray<StepHistoryEntry>,
-): string => {
-  const reviewedArtifact = run.reviewedArtifact ?? '';
-  if (!reviewedArtifact) return '';
+): string | undefined => {
+  for (let index = history.length - 1; index >= 0; index -= 1) {
+    const cwd = history[index]?.workspaceCwd;
+    if (cwd) return cwd;
+  }
+  return run.startCwd ?? run.cwd;
+};
 
-  const isApprovalRetained = history.some((entry) => {
-    const gate = workflow.definition.steps[entry.stepId]?.gate;
-    return (
-      gate !== undefined &&
-      entry.outcome === gate.approvedOutcome &&
-      entry.summary === reviewedArtifact
-    );
-  });
-  return isApprovalRetained ? reviewedArtifact : '';
+/**
+ * Restores one reviewed approval from the latest retained approving history.
+ *
+ * Approved history records carry their own artifact, feedback, gate request
+ * identity, and prompt-excluded structural digest.
+ *
+ * @param workflow - Updated workflow.
+ * @param history - History retained after reconciliation.
+ * @returns The retained pair, or `undefined` when provenance was lost.
+ */
+export const retainedReviewedApproval = (
+  workflow: LoadedWorkflow,
+  history: ReadonlyArray<StepHistoryEntry>,
+): ReviewedApproval | undefined => {
+  const retainedApproval = latestApprovedGateEntry(workflow, history);
+  const approval = retainedApproval?.entry.approval;
+  return approval
+    ? { artifact: approval.artifact, feedback: approval.feedback }
+    : undefined;
 };
 
 /**
  * Refreshes the digest of retained approved-gate history.
  *
- * The reviewed artifact itself proves the gate output is unchanged, allowing a
- * prompt-only configuration refresh without discarding approved authority.
+ * The approved history's prompt-excluded structural digest must still match,
+ * allowing only a prompt-only refresh without discarding the reviewed value.
  *
  * @param run - Existing workflow state.
  * @param workflow - Updated workflow.
@@ -66,18 +102,19 @@ export const refreshApprovedGateHistory = (
   run: WorkflowRun,
   workflow: LoadedWorkflow,
 ): WorkflowRun => {
-  const reviewedArtifact = run.reviewedArtifact ?? '';
-  if (!reviewedArtifact) return run;
-
   const history = run.history.map((entry) => {
     const gate = workflow.definition.steps[entry.stepId]?.gate;
     const currentDigest = workflow.stepDigests[entry.stepId];
+    const currentStructuralDigest =
+      workflow.stepStructuralDigests[entry.stepId];
     const shouldRefresh =
       gate !== undefined &&
       typeof currentDigest === 'string' &&
       currentDigest.length > 0 &&
+      typeof currentStructuralDigest === 'string' &&
+      currentStructuralDigest.length > 0 &&
       entry.outcome === gate.approvedOutcome &&
-      entry.summary === reviewedArtifact &&
+      entry.approval?.stepStructuralDigest === currentStructuralDigest &&
       entry.stepDigest !== currentDigest;
     return shouldRefresh ? { ...entry, stepDigest: currentDigest } : entry;
   });

package/src/engine/run-advance.ts

@@ -2,16 +2,29 @@ import type { LoadedWorkflow } from '../config/types.ts';
 import type { StepHistoryEntry, WorkflowRun } from './state-types.ts';
 import { currentStep, withRunUpdate } from './transition-helpers.ts';
 
+export type RunStepEffects = {
+  /** Canonical directory selected through the step's YAML-authorized result. */
+  readonly workspaceCwd?: string | undefined;
+};
+
 const completedStep = (
   run: WorkflowRun,
   outcome: string,
   summary: string,
   now: number,
+  effects: RunStepEffects,
 ): StepHistoryEntry => ({
   stepId: run.currentStepId,
   stepDigest: run.currentStepDigest,
   outcome,
   summary,
+  ...(effects.workspaceCwd ? { workspaceCwd: effects.workspaceCwd } : {}),
+  ...(run.currentStepAttempts?.length
+    ? { attempts: run.currentStepAttempts }
+    : {}),
+  ...(run.currentStepOmittedAttempts
+    ? { omittedAttempts: run.currentStepOmittedAttempts }
+    : {}),
   completedAt: now,
 });
 
@@ -23,6 +36,7 @@ const completedStep = (
  * @param outcome - Submitted step outcome.
  * @param summary - Step handoff summary.
  * @param now - Update timestamp.
+ * @param effects - Validated declarative effects accepted with this result.
  * @returns A new paused, running, or completed workflow state.
  * @throws When the run, outcome, current step, or transition target is invalid.
  */
@@ -32,6 +46,7 @@ export const advanceRun = (
   outcome: string,
   summary: string,
   now: number,
+  effects: RunStepEffects = {},
 ): WorkflowRun => {
   if (run.status !== 'running') {
     throw new Error(
@@ -55,6 +70,14 @@ export const advanceRun = (
       `outcome "${outcome}" is not valid for step "${run.currentStepId}"`,
     );
   }
+  const shouldBindWorkspace = step.workspace?.bindOn.includes(outcome) ?? false;
+  if (shouldBindWorkspace !== Boolean(effects.workspaceCwd)) {
+    throw new Error(
+      shouldBindWorkspace
+        ? `outcome "${outcome}" requires a validated workspace binding`
+        : `outcome "${outcome}" cannot bind a workspace`,
+    );
+  }
   if (target === '$pause') {
     return withRunUpdate(
       run,
@@ -63,30 +86,35 @@ export const advanceRun = (
         pausedFrom: 'running',
         pauseReason: summary || `Step "${run.currentStepId}" requested a pause`,
         lastSummary: summary,
+        resumeInput: undefined,
       },
       now,
     );
   }
 
-  const completed = completedStep(run, outcome, summary, now);
+  const completed = completedStep(run, outcome, summary, now, effects);
+  const cwd = effects.workspaceCwd ?? run.cwd;
   if (target === '$done') {
     return withRunUpdate(
       run,
       {
         status: 'completed',
         history: [...run.history, completed],
+        currentStepAttempts: undefined,
+        currentStepOmittedAttempts: undefined,
+        ...(cwd ? { cwd } : {}),
         stepHandoff: summary,
         lastSummary: summary,
         gateFeedback: '',
         pausedFrom: undefined,
         pendingGate: undefined,
+        resumeInput: undefined,
       },
       now,
     );
   }
 
-  const nextStep = workflow.definition.steps[target];
-  if (!nextStep) {
+  if (!workflow.definition.steps[target]) {
     throw new Error(`transition target "${target}" does not exist`);
   }
 
@@ -97,11 +125,13 @@ export const advanceRun = (
         status: 'paused',
         pausedFrom: 'running',
         pauseReason: `Step "${target}" exceeded maxStepVisits (${workflow.definition.maxStepVisits})`,
+        failedStepId: target,
       }
     : {
         status: 'running',
         pausedFrom: undefined,
         pauseReason: undefined,
+        failedStepId: undefined,
       };
 
   return withRunUpdate(
@@ -112,10 +142,13 @@ export const advanceRun = (
       currentStepDigest: workflow.stepDigests[target] ?? '',
       visits: { ...run.visits, [target]: nextVisitCount },
       history: [...run.history, completed],
+      currentStepAttempts: undefined,
+      currentStepOmittedAttempts: undefined,
+      ...(cwd ? { cwd } : {}),
       stepHandoff: summary,
       lastSummary: summary,
       gateFeedback: '',
-      ...(nextStep.gate ? { reviewedArtifact: '', reviewedFeedback: '' } : {}),
+      resumeInput: undefined,
     },
     now,
   );

package/src/engine/run-lifecycle.ts

@@ -98,6 +98,16 @@ export const resumeRun = (run: WorkflowRun, now: number): WorkflowRun => {
   );
 };
 
+/**
+ * Replaces the user-authored guidance for one explicit resume attempt.
+ */
+export const setResumeInput = (
+  run: WorkflowRun,
+  input: string,
+  now: number,
+): WorkflowRun =>
+  withRunUpdate(run, { resumeInput: input.trim() || undefined }, now);
+
 /**
  * Aborts a run and clears resumable gate state.
  *
@@ -119,6 +129,7 @@ export const abortRun = (
       pausedFrom: undefined,
       failedStepId: undefined,
       pendingGate: undefined,
+      resumeInput: undefined,
     },
     now,
   );