@wichayutdew/pi-workflows 1.0.0 → 2.0.0

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' &&
@@ -109,7 +338,9 @@ export const isWorkflowRun = (value: unknown): value is WorkflowRun => {
 
   const hasValidOptionalFields =
     isOptionalString(value.reviewedArtifact) &&
+    isOptionalString(value.reviewedFeedback) &&
     isOptionalString(value.stepHandoff) &&
+    isOptionalResumeInput(value.resumeInput) &&
     isOptionalString(value.pauseReason) &&
     isOptionalString(value.failedStepId) &&
     (value.pausedFrom === undefined ||
@@ -121,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);
+}

package/src/engine/state-types.ts

@@ -1,13 +1,105 @@
 export const RUN_STATE_VERSION = 1 as const;
+export const MAX_RESUME_INPUT_CHARS = 16_000;
+export const MAX_STEP_TRACE_TASK_CHARS = 64_000;
+export const MAX_STEP_TRACE_ATTEMPTS = 16;
+export const MAX_STEP_TRACE_SUMMARY_CHARS = 8_000;
+export const MAX_STEP_TRACE_ARTIFACT_CHARS = 16_000;
+export const MAX_STEP_TRACE_LOG_EVENTS = 400;
+export const MAX_STEP_TRACE_LOG_EVENT_CHARS = 2_000;
+export const MAX_STEP_TRACE_LOG_CHARS = 120_000;
+export const MAX_WORKFLOW_TRACE_CHARS = 2_000_000;
 
 export type WorkflowRunStatus =
   'running' | 'paused' | 'awaiting-gate' | 'completed' | 'aborted';
 
+export type GateApproval = {
+  /** Stable identity of the gate request that produced this approval. */
+  readonly requestId: string;
+  readonly artifact: string;
+  readonly feedback: string;
+  /** Prompt-excluded step structure approved by this gate request. */
+  readonly stepStructuralDigest: string;
+};
+
+export type StepAttemptResult = {
+  readonly outcome: string;
+  readonly summary: string;
+  readonly summaryTruncated?: true | undefined;
+  readonly artifact?: string | undefined;
+  readonly artifactTruncated?: true | undefined;
+  readonly workspaceCwd?: string | undefined;
+};
+
+export type StepGateDecision = {
+  readonly provider: 'prompt' | 'plannotator';
+  readonly requestId: string;
+  readonly approved: boolean;
+  readonly feedback: string;
+  readonly feedbackTruncated?: true | undefined;
+  readonly resolvedAt: number;
+  readonly reviewId?: string | undefined;
+};
+
+export type SubagentTranscriptReference = {
+  /** Trusted parent-derived directory containing this child run. */
+  readonly trustedRoot: string;
+  /** Exact child session returned by the delegation protocol. */
+  readonly sessionFile: string;
+  /** Pi-subagents run identity used to confine the session path. */
+  readonly runId: string;
+  readonly childIndex: number;
+};
+
+export type StepExecutionAttempt =
+  | {
+      readonly kind: 'main';
+      readonly requestId: string;
+      /** One-based attempt position within this step visit. */
+      readonly ordinal?: number | undefined;
+      /** Exact workflow task sent to the main agent. */
+      readonly task: string;
+      readonly taskTruncated?: true | undefined;
+      readonly omittedTaskChars?: number | undefined;
+      /** Redacted assistant/tool events retained from the start of this attempt. */
+      readonly log?: ReadonlyArray<string> | undefined;
+      /** Whether later events were omitted from the bounded prefix. */
+      readonly logTruncated?: true | undefined;
+      readonly omittedLogEvents?: number | undefined;
+      readonly startedAt: number;
+      readonly result?: StepAttemptResult | undefined;
+      readonly gateDecision?: StepGateDecision | undefined;
+    }
+  | {
+      readonly kind: 'subagent';
+      readonly requestId: string;
+      /** One-based attempt position within this step visit. */
+      readonly ordinal?: number | undefined;
+      readonly agent: string;
+      /** Exact task body sent after the private child-policy envelope. */
+      readonly task: string;
+      readonly taskTruncated?: true | undefined;
+      readonly omittedTaskChars?: number | undefined;
+      readonly startedAt: number;
+      readonly transcript?: SubagentTranscriptReference | undefined;
+      readonly result?: StepAttemptResult | undefined;
+      readonly gateDecision?: StepGateDecision | undefined;
+    };
+
 export type StepHistoryEntry = {
   readonly stepId: string;
   readonly stepDigest: string;
   readonly outcome: string;
   readonly summary: string;
+  /** Canonical execution directory selected by this completed step. */
+  readonly workspaceCwd?: string | undefined;
+  /** Artifact projection paired exactly with `approval` on approved gates. */
+  readonly artifact?: string | undefined;
+  /** Complete approval provenance for a newly completed gate step. */
+  readonly approval?: GateApproval | undefined;
+  /** Durable execution evidence for every attempt of this completed step. */
+  readonly attempts?: ReadonlyArray<StepExecutionAttempt> | undefined;
+  /** Older attempts compacted to keep the checkpoint bounded. */
+  readonly omittedAttempts?: number | undefined;
   readonly completedAt: number;
 };
 
@@ -22,8 +114,8 @@ export type PendingGate = {
   readonly requestId: string;
   readonly stepId: string;
   readonly artifact: string;
-  /** Legacy v1 field. New runs use the reviewed artifact as the handoff. */
-  summary?: string | undefined;
+  /** Compact step handoff kept separate from the opaque review artifact. */
+  readonly summary?: string | undefined;
   readonly submittedOutcome: string;
   readonly requestedAt: number;
   readonly reviewId?: string | undefined;
@@ -42,13 +134,24 @@ export type WorkflowRun = {
   readonly baselineTools: ReadonlyArray<string>;
   readonly visits: Readonly<Record<string, number>>;
   readonly history: ReadonlyArray<StepHistoryEntry>;
+  /** Attempts for the current, not-yet-completed step. */
+  readonly currentStepAttempts?:
+    ReadonlyArray<StepExecutionAttempt> | undefined;
+  /** Older current-step attempts compacted from the checkpoint. */
+  readonly currentStepOmittedAttempts?: number | undefined;
   readonly startedAt: number;
   readonly updatedAt: number;
   /**
-   * Most recent human-approved gate artifact. This is the only provenance
-   * source from which reviewed Bash capabilities may be derived.
+   * Most recent human-approved gate artifact. The workflow prompt decides how
+   * to interpret this opaque value.
    */
   readonly reviewedArtifact?: string | undefined;
+  /** Final feedback paired with the approved artifact. */
+  readonly reviewedFeedback?: string | undefined;
+  /** Immutable working directory captured when the workflow started. */
+  readonly startCwd?: string | undefined;
+  /** Current canonical execution directory for delegated workflow steps. */
+  readonly cwd?: string | undefined;
   /**
    * Input inherited from the previous completed step. Unlike `lastSummary`,
    * this survives a paused attempt of the current step.
@@ -56,6 +159,8 @@ export type WorkflowRun = {
   readonly stepHandoff?: string | undefined;
   readonly lastSummary: string;
   readonly gateFeedback: string;
+  /** User-authored guidance supplied for the current resume attempt. */
+  readonly resumeInput?: string | undefined;
   readonly pauseReason?: string | undefined;
   readonly pausedFrom?: 'running' | 'awaiting-gate' | undefined;
   /** Current step when execution failed and was paused for a resumable retry. */

package/src/engine/state.ts

@@ -1,10 +1,24 @@
 export { createRun } from './create-run.ts';
 export { isWorkflowRun } from './run-validation.ts';
-export { RUN_STATE_VERSION } from './state-types.ts';
+export {
+  MAX_RESUME_INPUT_CHARS,
+  MAX_STEP_TRACE_ATTEMPTS,
+  MAX_STEP_TRACE_LOG_CHARS,
+  MAX_STEP_TRACE_LOG_EVENT_CHARS,
+  MAX_STEP_TRACE_LOG_EVENTS,
+  MAX_STEP_TRACE_TASK_CHARS,
+  MAX_WORKFLOW_TRACE_CHARS,
+  RUN_STATE_VERSION,
+} from './state-types.ts';
 export type {
+  GateApproval,
   GateResolution,
   PendingGate,
+  StepAttemptResult,
+  StepExecutionAttempt,
+  StepGateDecision,
   StepHistoryEntry,
+  SubagentTranscriptReference,
   WorkflowRun,
   WorkflowRunStatus,
 } from './state-types.ts';