@wichayutdew/pi-workflows 1.0.1 → 2.0.0

package/src/engine/run-reconciliation.ts

@@ -2,11 +2,13 @@ import type { LoadedWorkflow } from '../config/types.ts';
 import {
   rebuildVisits,
   refreshApprovedGateHistory,
-  retainedReviewedArtifact,
+  retainedReviewedApproval,
+  retainedWorkspaceCwd,
 } from './reconciliation-history.ts';
 import type { WorkflowRun } from './state-types.ts';
 import { withRunUpdate } from './transition-helpers.ts';
 import type { ReconcileResult } from './transition-types.ts';
+import { validateRunWorkflowSemantics } from './run-workflow-validation.ts';
 
 /**
  * Reconciles persisted run state with a reloaded workflow configuration.
@@ -30,33 +32,61 @@ export const reconcileRun = (
       error: `run belongs to "${run.workflowId}", not "${workflow.definition.id}"`,
     };
   }
-  if (run.workflowDigest === workflow.digest) {
-    return { run, changed: false };
+  const reconciledRun =
+    run.workflowDigest === workflow.digest
+      ? run
+      : refreshApprovedGateHistory(run, workflow);
+  const changedHistoryIndex =
+    run.workflowDigest === workflow.digest
+      ? -1
+      : reconciledRun.history.findIndex(
+          (entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest,
+        );
+  const changedHistoryEntry =
+    changedHistoryIndex >= 0
+      ? reconciledRun.history[changedHistoryIndex]
+      : undefined;
+  if (
+    changedHistoryEntry &&
+    !workflow.definition.steps[changedHistoryEntry.stepId]
+  ) {
+    return {
+      changed: true,
+      error: 'a completed step was removed; abort or restore the configuration',
+    };
   }
-  if (!workflow.definition.steps[run.currentStepId]) {
+  if (
+    changedHistoryIndex < 0 &&
+    !workflow.definition.steps[run.currentStepId]
+  ) {
     return {
       changed: true,
       error: `current step "${run.currentStepId}" was removed; abort or restore the configuration`,
     };
   }
-
-  const reconciledRun = refreshApprovedGateHistory(run, workflow);
-  const changedHistoryIndex = reconciledRun.history.findIndex(
-    (entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest,
-  );
+  const semanticError = validateRunWorkflowSemantics(reconciledRun, workflow);
+  if (semanticError) {
+    return {
+      changed: run.workflowDigest !== workflow.digest,
+      error: `workflow checkpoint is inconsistent: ${semanticError}`,
+    };
+  }
+  if (run.workflowDigest === workflow.digest) {
+    return { run, changed: false };
+  }
   if (changedHistoryIndex >= 0) {
-    const changedEntry = reconciledRun.history[changedHistoryIndex];
-    if (!changedEntry || !workflow.definition.steps[changedEntry.stepId]) {
-      return {
-        changed: true,
-        error:
-          'a completed step was removed; abort or restore the configuration',
-      };
+    const changedEntry = changedHistoryEntry;
+    if (!changedEntry) {
+      return { changed: true, error: 'changed history entry is unavailable' };
     }
 
     const retainedHistory = reconciledRun.history.slice(0, changedHistoryIndex);
     const restartedStep = changedEntry.stepId;
     const stepHandoff = retainedHistory.at(-1)?.summary ?? '';
+    const reviewedApproval = retainedReviewedApproval(
+      workflow,
+      retainedHistory,
+    );
     return {
       changed: true,
       restartedStep,
@@ -68,12 +98,12 @@ export const reconcileRun = (
           currentStepId: restartedStep,
           currentStepDigest: workflow.stepDigests[restartedStep] ?? '',
           history: retainedHistory,
+          currentStepAttempts: changedEntry.attempts,
+          currentStepOmittedAttempts: changedEntry.omittedAttempts,
           visits: rebuildVisits(retainedHistory, restartedStep),
-          reviewedArtifact: retainedReviewedArtifact(
-            workflow,
-            reconciledRun,
-            retainedHistory,
-          ),
+          cwd: retainedWorkspaceCwd(reconciledRun, retainedHistory),
+          reviewedArtifact: reviewedApproval?.artifact ?? '',
+          reviewedFeedback: reviewedApproval?.feedback ?? '',
           stepHandoff,
           lastSummary: stepHandoff,
           pendingGate: undefined,

package/src/engine/run-validation.ts

@@ -1,23 +1,220 @@
+import { isAbsolute, resolve } from 'node:path';
 import {
+  MAX_RESUME_INPUT_CHARS,
+  MAX_STEP_TRACE_ARTIFACT_CHARS,
+  MAX_STEP_TRACE_ATTEMPTS,
+  MAX_STEP_TRACE_LOG_CHARS,
+  MAX_STEP_TRACE_LOG_EVENT_CHARS,
+  MAX_STEP_TRACE_LOG_EVENTS,
+  MAX_STEP_TRACE_SUMMARY_CHARS,
+  MAX_STEP_TRACE_TASK_CHARS,
+  MAX_WORKFLOW_TRACE_CHARS,
   RUN_STATE_VERSION,
+  type GateApproval,
   type GateResolution,
   type PendingGate,
+  type StepAttemptResult,
+  type StepExecutionAttempt,
+  type StepGateDecision,
   type StepHistoryEntry,
   type WorkflowRun,
   type WorkflowRunStatus,
 } from './state-types.ts';
+import { workflowTraceChars } from './step-trace.ts';
 
 type UnknownRecord = Readonly<Record<string, unknown>>;
 
 const isRecord = (value: unknown): value is UnknownRecord =>
   value !== null && typeof value === 'object' && !Array.isArray(value);
 
+const isAbsoluteCwd = (value: unknown): value is string =>
+  typeof value === 'string' &&
+  value.length > 0 &&
+  isAbsolute(value) &&
+  !value.includes('\0');
+
+const isGateApproval = (value: unknown): value is GateApproval =>
+  isRecord(value) &&
+  typeof value.requestId === 'string' &&
+  value.requestId.length > 0 &&
+  typeof value.artifact === 'string' &&
+  value.artifact.trim().length > 0 &&
+  typeof value.feedback === 'string' &&
+  typeof value.stepStructuralDigest === 'string' &&
+  value.stepStructuralDigest.length > 0;
+
+const isStepAttemptResult = (value: unknown): value is StepAttemptResult =>
+  isRecord(value) &&
+  typeof value.outcome === 'string' &&
+  typeof value.summary === 'string' &&
+  value.summary.length <= MAX_STEP_TRACE_SUMMARY_CHARS &&
+  (value.summaryTruncated === undefined || value.summaryTruncated === true) &&
+  (value.artifact === undefined || typeof value.artifact === 'string') &&
+  (typeof value.artifact !== 'string' ||
+    value.artifact.length <= MAX_STEP_TRACE_ARTIFACT_CHARS) &&
+  (value.artifactTruncated === undefined || value.artifactTruncated === true) &&
+  !(value.artifactTruncated === true && value.artifact === undefined) &&
+  (value.workspaceCwd === undefined || isAbsoluteCwd(value.workspaceCwd));
+
+const isStepGateDecision = (value: unknown): value is StepGateDecision =>
+  isRecord(value) &&
+  (value.provider === 'prompt' || value.provider === 'plannotator') &&
+  typeof value.requestId === 'string' &&
+  value.requestId.length > 0 &&
+  typeof value.approved === 'boolean' &&
+  typeof value.feedback === 'string' &&
+  value.feedback.length <= MAX_STEP_TRACE_SUMMARY_CHARS &&
+  (value.feedbackTruncated === undefined || value.feedbackTruncated === true) &&
+  typeof value.resolvedAt === 'number' &&
+  (value.reviewId === undefined || typeof value.reviewId === 'string');
+
+const isSafeTraceIdentityField = (value: unknown): value is string =>
+  typeof value === 'string' &&
+  value.length > 0 &&
+  !value.includes('\0') &&
+  !value.includes('/') &&
+  !value.includes('\\') &&
+  value !== '.' &&
+  value !== '..';
+
+const hasValidMainStepLog = (value: UnknownRecord): boolean => {
+  const log = value.log;
+  if (
+    log !== undefined &&
+    (!Array.isArray(log) ||
+      log.length > MAX_STEP_TRACE_LOG_EVENTS ||
+      !log.every(
+        (line) =>
+          typeof line === 'string' &&
+          line.length > 0 &&
+          line.length <= MAX_STEP_TRACE_LOG_EVENT_CHARS,
+      ) ||
+      log.reduce<number>(
+        (total, line) => total + (typeof line === 'string' ? line.length : 0),
+        0,
+      ) > MAX_STEP_TRACE_LOG_CHARS)
+  ) {
+    return false;
+  }
+  if (value.logTruncated !== undefined && value.logTruncated !== true) {
+    return false;
+  }
+  if (
+    value.omittedLogEvents !== undefined &&
+    (!Number.isSafeInteger(value.omittedLogEvents) ||
+      (value.omittedLogEvents as number) <= 0)
+  ) {
+    return false;
+  }
+  return (
+    (value.logTruncated === true) ===
+      (typeof value.omittedLogEvents === 'number') &&
+    !(
+      log === undefined &&
+      (value.logTruncated !== undefined || value.omittedLogEvents !== undefined)
+    )
+  );
+};
+
+const isStepExecutionAttempt = (
+  value: unknown,
+): value is StepExecutionAttempt => {
+  if (
+    !isRecord(value) ||
+    (value.kind !== 'main' && value.kind !== 'subagent') ||
+    typeof value.requestId !== 'string' ||
+    value.requestId.length === 0 ||
+    value.requestId.includes('\0') ||
+    (value.ordinal !== undefined &&
+      (!Number.isSafeInteger(value.ordinal) ||
+        (value.ordinal as number) <= 0)) ||
+    typeof value.task !== 'string' ||
+    value.task.trim().length === 0 ||
+    value.task.length > MAX_STEP_TRACE_TASK_CHARS ||
+    (value.taskTruncated !== undefined && value.taskTruncated !== true) ||
+    (value.omittedTaskChars !== undefined &&
+      (!Number.isSafeInteger(value.omittedTaskChars) ||
+        (value.omittedTaskChars as number) <= 0)) ||
+    (value.taskTruncated === true) !==
+      (typeof value.omittedTaskChars === 'number') ||
+    typeof value.startedAt !== 'number' ||
+    (value.result !== undefined && !isStepAttemptResult(value.result)) ||
+    (value.gateDecision !== undefined &&
+      !isStepGateDecision(value.gateDecision))
+  ) {
+    return false;
+  }
+  if (value.kind === 'main') {
+    return (
+      value.agent === undefined &&
+      value.transcript === undefined &&
+      hasValidMainStepLog(value)
+    );
+  }
+  if (
+    value.log !== undefined ||
+    value.logTruncated !== undefined ||
+    value.omittedLogEvents !== undefined
+  ) {
+    return false;
+  }
+  if (typeof value.agent !== 'string' || value.agent.length === 0) {
+    return false;
+  }
+  if (value.transcript === undefined) return true;
+  if (!isRecord(value.transcript)) return false;
+  const transcript = value.transcript;
+  if (
+    !isAbsoluteCwd(transcript.trustedRoot) ||
+    !isAbsoluteCwd(transcript.sessionFile) ||
+    !isSafeTraceIdentityField(transcript.runId) ||
+    !Number.isSafeInteger(transcript.childIndex) ||
+    (transcript.childIndex as number) < 0
+  ) {
+    return false;
+  }
+  return (
+    resolve(
+      transcript.trustedRoot,
+      transcript.runId,
+      `run-${String(transcript.childIndex)}`,
+      'session.jsonl',
+    ) === resolve(transcript.sessionFile)
+  );
+};
+
+const isStepExecutionAttempts = (
+  value: unknown,
+): value is ReadonlyArray<StepExecutionAttempt> =>
+  Array.isArray(value) &&
+  value.length <= MAX_STEP_TRACE_ATTEMPTS &&
+  value.every(isStepExecutionAttempt) &&
+  new Set(value.map((attempt) => attempt.requestId)).size === value.length &&
+  value.every((attempt, index) => {
+    if (attempt.ordinal === undefined) return true;
+    const ordinal = attempt.ordinal;
+    return value
+      .slice(0, index)
+      .every(
+        (earlier) => earlier.ordinal === undefined || earlier.ordinal < ordinal,
+      );
+  });
+
 const isStepHistoryEntry = (value: unknown): value is StepHistoryEntry =>
   isRecord(value) &&
   typeof value.stepId === 'string' &&
   typeof value.stepDigest === 'string' &&
   typeof value.outcome === 'string' &&
   typeof value.summary === 'string' &&
+  (value.workspaceCwd === undefined || isAbsoluteCwd(value.workspaceCwd)) &&
+  (value.artifact === undefined || typeof value.artifact === 'string') &&
+  (value.approval === undefined ||
+    (isGateApproval(value.approval) &&
+      value.artifact === value.approval.artifact)) &&
+  (value.attempts === undefined || isStepExecutionAttempts(value.attempts)) &&
+  (value.omittedAttempts === undefined ||
+    (Number.isSafeInteger(value.omittedAttempts) &&
+      (value.omittedAttempts as number) > 0)) &&
   typeof value.completedAt === 'number';
 
 const isGateResolution = (value: unknown): value is GateResolution =>
@@ -49,6 +246,10 @@ const isVisitCounts = (value: unknown): value is Record<string, number> =>
 const isOptionalString = (value: unknown): value is string | undefined =>
   value === undefined || typeof value === 'string';
 
+const isOptionalResumeInput = (value: unknown): value is string | undefined =>
+  value === undefined ||
+  (typeof value === 'string' && value.length <= MAX_RESUME_INPUT_CHARS);
+
 const isWorkflowRunStatus = (value: unknown): value is WorkflowRunStatus =>
   value === 'running' ||
   value === 'paused' ||
@@ -75,6 +276,29 @@ const hasValidGateState = (
       (run.status === 'awaiting-gate' ||
         (run.status === 'paused' && run.pausedFrom === 'awaiting-gate'));
 
+const hasValidWorkspaceState = (
+  run: UnknownRecord,
+  history: ReadonlyArray<StepHistoryEntry>,
+): boolean => {
+  const startCwd = run.startCwd;
+  const cwd = run.cwd;
+  if (startCwd !== undefined && !isAbsoluteCwd(startCwd)) return false;
+  if (cwd !== undefined && !isAbsoluteCwd(cwd)) return false;
+
+  const bindings = history.flatMap((entry) =>
+    entry.workspaceCwd ? [entry.workspaceCwd] : [],
+  );
+  if (new Set(bindings).size > 1) return false;
+  const boundCwd = bindings.at(-1);
+  if (boundCwd !== undefined) {
+    return isAbsoluteCwd(startCwd) && isAbsoluteCwd(cwd) && cwd === boundCwd;
+  }
+
+  // Legacy checkpoints have only `cwd`; new checkpoints keep start/current
+  // equal until a structured workspace binding is accepted.
+  return startCwd === undefined || cwd === startCwd;
+};
+
 /**
  * Validates an unknown value as a persisted workflow run.
  *
@@ -100,6 +324,11 @@ export const isWorkflowRun = (value: unknown): value is WorkflowRun => {
     value.baselineTools.every((tool) => typeof tool === 'string') &&
     Array.isArray(value.history) &&
     value.history.every(isStepHistoryEntry) &&
+    (value.currentStepAttempts === undefined ||
+      isStepExecutionAttempts(value.currentStepAttempts)) &&
+    (value.currentStepOmittedAttempts === undefined ||
+      (Number.isSafeInteger(value.currentStepOmittedAttempts) &&
+        (value.currentStepOmittedAttempts as number) > 0)) &&
     isVisitCounts(value.visits) &&
     typeof value.startedAt === 'number' &&
     typeof value.updatedAt === 'number' &&
@@ -111,6 +340,7 @@ export const isWorkflowRun = (value: unknown): value is WorkflowRun => {
     isOptionalString(value.reviewedArtifact) &&
     isOptionalString(value.reviewedFeedback) &&
     isOptionalString(value.stepHandoff) &&
+    isOptionalResumeInput(value.resumeInput) &&
     isOptionalString(value.pauseReason) &&
     isOptionalString(value.failedStepId) &&
     (value.pausedFrom === undefined ||
@@ -122,6 +352,11 @@ export const isWorkflowRun = (value: unknown): value is WorkflowRun => {
   if (pendingGate !== undefined && !isPendingGate(pendingGate)) return false;
 
   return (
+    workflowTraceChars(value as WorkflowRun) <= MAX_WORKFLOW_TRACE_CHARS &&
+    hasValidWorkspaceState(
+      value,
+      value.history as ReadonlyArray<StepHistoryEntry>,
+    ) &&
     hasValidPauseState(value) &&
     hasValidFailureState(value) &&
     hasValidGateState(value, pendingGate)

package/src/engine/run-workflow-validation.ts

@@ -0,0 +1,191 @@
+import type { LoadedWorkflow, WorkflowStep } from '../config/types.ts';
+import type { StepHistoryEntry, WorkflowRun } from './state-types.ts';
+
+const sameVisitCounts = (
+  actual: Readonly<Record<string, number>>,
+  expected: Readonly<Record<string, number>>,
+): boolean => {
+  const actualEntries = Object.entries(actual).sort(([left], [right]) =>
+    left.localeCompare(right),
+  );
+  const expectedEntries = Object.entries(expected).sort(([left], [right]) =>
+    left.localeCompare(right),
+  );
+  return (
+    actualEntries.length === expectedEntries.length &&
+    actualEntries.every(
+      ([stepId, count], index) =>
+        expectedEntries[index]?.[0] === stepId &&
+        expectedEntries[index][1] === count,
+    )
+  );
+};
+
+const validateHistoryMetadata = (
+  workflow: LoadedWorkflow,
+  step: WorkflowStep,
+  entry: StepHistoryEntry,
+): string | undefined => {
+  const shouldBind = step.workspace?.bindOn.includes(entry.outcome) === true;
+  if (shouldBind !== (entry.workspaceCwd !== undefined)) {
+    return shouldBind
+      ? `history step "${entry.stepId}" is missing its workspace binding`
+      : `history step "${entry.stepId}" has an unauthorized workspace binding`;
+  }
+
+  const isApprovedGate =
+    step.gate !== undefined && entry.outcome === step.gate.approvedOutcome;
+  if (isApprovedGate && !entry.approval) {
+    return `history step "${entry.stepId}" is missing authoritative gate approval`;
+  }
+  if (isApprovedGate && entry.artifact !== entry.approval?.artifact) {
+    return `history step "${entry.stepId}" approval artifact is inconsistent`;
+  }
+  if (!isApprovedGate && (entry.approval || entry.artifact !== undefined)) {
+    return `history step "${entry.stepId}" has approval data for a non-approved outcome`;
+  }
+  if (
+    isApprovedGate &&
+    entry.approval?.stepStructuralDigest !==
+      workflow.stepStructuralDigests[entry.stepId]
+  ) {
+    return `history step "${entry.stepId}" approval does not match its configured structure`;
+  }
+  return undefined;
+};
+
+const validatePendingGate = (
+  run: WorkflowRun,
+  step: WorkflowStep,
+): string | undefined => {
+  const pending = run.pendingGate;
+  if (!pending) return undefined;
+  if (
+    !step.gate ||
+    pending.stepId !== run.currentStepId ||
+    pending.provider !== step.gate.provider ||
+    pending.submittedOutcome !== step.gate.submitOutcome
+  ) {
+    return 'pending gate does not match the current workflow step';
+  }
+  if (pending.provider === 'prompt' && pending.reviewId !== undefined) {
+    return 'built-in prompt gate cannot carry a Plannotator review id';
+  }
+  return undefined;
+};
+
+/**
+ * Validates persisted control-flow state against the loaded declarative graph.
+ *
+ * When configuration changed, the first digest-mismatched history entry is
+ * intentionally left to reconciliation, which restarts that exact reachable
+ * step and discards everything after it.
+ */
+export function validateRunWorkflowSemantics(
+  run: WorkflowRun,
+  workflow: LoadedWorkflow,
+): string | undefined {
+  const sameWorkflowDigest = run.workflowDigest === workflow.digest;
+  let expectedStepId = workflow.definition.start;
+  let reachedDone = false;
+  let boundWorkspaceCwd: string | undefined;
+  let latestApproval:
+    { readonly artifact: string; readonly feedback: string } | undefined;
+  const expectedVisits: Record<string, number> = { [expectedStepId]: 1 };
+
+  for (let index = 0; index < run.history.length; index += 1) {
+    const entry = run.history[index];
+    if (!entry) continue;
+    if (reachedDone) {
+      return 'workflow history continues after a $done transition';
+    }
+    if (entry.stepId !== expectedStepId) {
+      return `history step "${entry.stepId}" is not reachable after "${expectedStepId}"`;
+    }
+
+    const step = workflow.definition.steps[entry.stepId];
+    const configuredDigest = workflow.stepDigests[entry.stepId];
+    if (!step || entry.stepDigest !== configuredDigest) {
+      return sameWorkflowDigest
+        ? `history step "${entry.stepId}" does not match the active workflow digest`
+        : undefined;
+    }
+
+    const metadataError = validateHistoryMetadata(workflow, step, entry);
+    if (metadataError) return metadataError;
+    if (entry.workspaceCwd) {
+      if (
+        boundWorkspaceCwd !== undefined &&
+        boundWorkspaceCwd !== entry.workspaceCwd
+      ) {
+        return 'workflow history attempts to replace an existing workspace binding';
+      }
+      boundWorkspaceCwd = entry.workspaceCwd;
+    }
+    if (entry.approval) {
+      latestApproval = {
+        artifact: entry.approval.artifact,
+        feedback: entry.approval.feedback,
+      };
+    }
+
+    const target = step.transitions[entry.outcome];
+    if (!target) {
+      return `history outcome "${entry.outcome}" is not configured for step "${entry.stepId}"`;
+    }
+    if (target === '$pause') {
+      return `history step "${entry.stepId}" records a non-completing $pause transition`;
+    }
+    if (target === '$done') {
+      if (index !== run.history.length - 1) {
+        return 'workflow history continues after a $done transition';
+      }
+      reachedDone = true;
+      continue;
+    }
+
+    expectedStepId = target;
+    expectedVisits[target] = (expectedVisits[target] ?? 0) + 1;
+  }
+
+  if (run.currentStepId !== expectedStepId) {
+    return `current step "${run.currentStepId}" does not match reachable step "${expectedStepId}"`;
+  }
+  if (reachedDone !== (run.status === 'completed')) {
+    return reachedDone
+      ? 'a workflow that reached $done must be completed'
+      : 'a completed workflow has no $done transition in its history';
+  }
+  if (
+    run.status === 'completed' &&
+    run.currentStepDigest !== run.history.at(-1)?.stepDigest
+  ) {
+    return 'completed workflow current-step digest does not match its terminal history';
+  }
+  if (!sameVisitCounts(run.visits, expectedVisits)) {
+    return 'workflow visit counts do not match its execution history';
+  }
+  const reviewedArtifact = run.reviewedArtifact ?? '';
+  const reviewedFeedback = run.reviewedFeedback ?? '';
+  if (
+    reviewedArtifact !== (latestApproval?.artifact ?? '') ||
+    reviewedFeedback !== (latestApproval?.feedback ?? '')
+  ) {
+    return 'reviewed artifact and feedback do not match authoritative approval history';
+  }
+
+  const currentStep = workflow.definition.steps[run.currentStepId];
+  if (!currentStep) {
+    return `current step "${run.currentStepId}" is missing from the workflow`;
+  }
+  const currentStepChanged =
+    run.currentStepDigest !== workflow.stepDigests[run.currentStepId];
+  if (sameWorkflowDigest && currentStepChanged) {
+    return `current step "${run.currentStepId}" does not match the active workflow digest`;
+  }
+  if (boundWorkspaceCwd && !currentStep.subagent) {
+    return `bound workflow current step "${run.currentStepId}" must use a subagent`;
+  }
+  if (currentStepChanged) return undefined;
+  return validatePendingGate(run, currentStep);
+}