feat(workflow-executor): add guidance step type (PRD-272)

packages/workflow-executor/CLAUDE.md

@@ -67,7 +67,8 @@ src/
 │   ├── read-record-step-executor.ts  # AI-powered record field reading step
 │   ├── update-record-step-executor.ts # AI-powered record field update step (with confirmation flow)
 │   ├── trigger-record-action-step-executor.ts  # AI-powered action trigger step (with confirmation flow)
-│   └── load-related-record-step-executor.ts  # AI-powered relation loading step (with confirmation flow)
+│   ├── load-related-record-step-executor.ts  # AI-powered relation loading step (with confirmation flow)
+│   └── guidance-step-executor.ts  # Manual guidance step (saves user input, no AI)
 ├── http/                   # HTTP server (optional, for frontend data access)
 │   └── executor-http-server.ts  # Koa server: GET /runs/:runId, POST /runs/:runId/trigger
 └── index.ts                # Barrel exports

packages/workflow-executor/src/executors/base-step-executor.ts

@@ -17,6 +17,7 @@
   StepStateError,
   WorkflowExecutorError,
 } from '../errors';
+import patchBodySchemas from '../pending-data-validators';
 import SafeAgentPort from './safe-agent-port';
 import StepSummaryBuilder from './summary/step-summary-builder';
 
@@ -118,6 +119,43 @@
     );
   }
 
+  /**
+   * Finds an existing pending execution and, when pendingData is provided,
+   * validates it against the step-type schema and merges it into the execution.
+   * Returns the (possibly updated) execution, or undefined if none exists.
+   */
+  protected async patchAndReloadPendingData<TExec extends WithPendingData>(
+    pendingData?: unknown,
+  ): Promise<TExec | undefined> {
+    const { type } = this.context.stepDefinition;
+    const execution = await this.findPendingExecution<TExec>(type);
+
+    if (pendingData !== undefined && execution) {
+      const schema = patchBodySchemas[execution.type]!;
+      const parsed = schema.safeParse(pendingData);
+
+      if (!parsed.success) {
+        throw new StepStateError(
+          `Invalid pending data: ${parsed.error.issues.map(i => i.message).join(', ')}`,
+        );
+      }
+
+      const updated = {
+        ...execution,
+        pendingData: { ...(execution.pendingData as object), ...(parsed.data as object) },
+      } as TExec;
+
+      await this.context.runStore.saveStepExecution(
+        this.context.runId,
+        updated as StepExecutionData,
+      );
+
+      return updated;
+    }
+
+    return execution;
+  }
+
   /**
    * Shared confirmation flow for executors that require user approval before acting.
    * Receives a pre-loaded execution (from findPendingExecution) and checks pendingData.userConfirmed:

packages/workflow-executor/src/executors/guidance-step-executor.ts

@@ -0,0 +1,49 @@
+import type { StepExecutionResult } from '../types/execution';
+import type { GuidanceStepDefinition } from '../types/step-definition';
+import type { BaseStepStatus } from '../types/step-outcome';
+
+import { StepStateError } from '../errors';
+import patchBodySchemas from '../pending-data-validators';
+import BaseStepExecutor from './base-step-executor';
+
+export default class GuidanceStepExecutor extends BaseStepExecutor<GuidanceStepDefinition> {
+  protected async doExecute(): Promise<StepExecutionResult> {
+    const { incomingPendingData } = this.context;
+
+    if (!incomingPendingData) {
+      throw new StepStateError('Guidance step triggered without pending data');
+    }
+
+    const parsed = patchBodySchemas.guidance.safeParse(incomingPendingData);
+
+    if (!parsed.success) {
+      throw new StepStateError(
+        `Invalid guidance input: ${parsed.error.issues.map(i => i.message).join(', ')}`,
+      );
+    }
+
+    const { userInput } = parsed.data as { userInput: string };
+
+    await this.context.runStore.saveStepExecution(this.context.runId, {
+      type: 'guidance',
+      stepIndex: this.context.stepIndex,
+      executionResult: { userInput },
+    });
+
+    return this.buildOutcomeResult({ status: 'success' });
+  }
+
+  protected buildOutcomeResult(outcome: {
+    status: BaseStepStatus;
+    error?: string;
+  }): StepExecutionResult {
+    return {
+      stepOutcome: {
+        type: 'guidance',
+        stepId: this.context.stepId,
+        stepIndex: this.context.stepIndex,
+        ...outcome,
+      },
+    };
+  }
+}

packages/workflow-executor/src/executors/load-related-record-step-executor.ts

@@ -39,8 +39,8 @@ interface RelationTarget extends RelationRef {
 export default class LoadRelatedRecordStepExecutor extends RecordStepExecutor<LoadRelatedRecordStepDefinition> {
   protected async doExecute(): Promise<StepExecutionResult> {
     // Branch A -- Re-entry after pending execution found in RunStore
-    const pending = await this.findPendingExecution<LoadRelatedRecordStepExecutionData>(
-      'load-related-record',
+    const pending = await this.patchAndReloadPendingData<LoadRelatedRecordStepExecutionData>(
+      this.context.incomingPendingData,
     );
 
     if (pending) {

packages/workflow-executor/src/executors/mcp-step-executor.ts

@@ -46,7 +46,9 @@ export default class McpStepExecutor extends BaseStepExecutor<McpStepDefinition>
 
   protected async doExecute(): Promise<StepExecutionResult> {
     // Branch A -- Re-entry after pending execution found in RunStore
-    const pending = await this.findPendingExecution<McpStepExecutionData>('mcp');
+    const pending = await this.patchAndReloadPendingData<McpStepExecutionData>(
+      this.context.incomingPendingData,
+    );
 
     if (pending) {
       return this.handleConfirmationFlow<McpStepExecutionData>(pending, execution =>

packages/workflow-executor/src/executors/step-executor-factory.ts

@@ -12,6 +12,7 @@ import type {
 } from '../types/execution';
 import type {
   ConditionStepDefinition,
+  GuidanceStepDefinition,
   LoadRelatedRecordStepDefinition,
   McpStepDefinition,
   ReadRecordStepDefinition,
@@ -22,6 +23,7 @@ import type { RemoteTool } from '@forestadmin/ai-proxy';
 
 import { StepStateError, causeMessage } from '../errors';
 import ConditionStepExecutor from './condition-step-executor';
+import GuidanceStepExecutor from './guidance-step-executor';
 import LoadRelatedRecordStepExecutor from './load-related-record-step-executor';
 import McpStepExecutor from './mcp-step-executor';
 import ReadRecordStepExecutor from './read-record-step-executor';
@@ -44,9 +46,10 @@ export default class StepExecutorFactory {
     step: PendingStepExecution,
     contextConfig: StepContextConfig,
     loadTools: () => Promise<RemoteTool[]>,
+    incomingPendingData?: unknown,
   ): Promise<IStepExecutor> {
     try {
-      const context = StepExecutorFactory.buildContext(step, contextConfig);
+      const context = StepExecutorFactory.buildContext(step, contextConfig, incomingPendingData);
 
       switch (step.stepDefinition.type) {
         case StepType.Condition:
@@ -70,6 +73,8 @@ export default class StepExecutorFactory {
             context as ExecutionContext<McpStepDefinition>,
             await loadTools(),
           );
+        case StepType.Guidance:
+          return new GuidanceStepExecutor(context as ExecutionContext<GuidanceStepDefinition>);
         default:
           throw new StepStateError(
             `Unknown step type: ${(step.stepDefinition as { type: string }).type}`,
@@ -102,6 +107,7 @@ export default class StepExecutorFactory {
   private static buildContext(
     step: PendingStepExecution,
     cfg: StepContextConfig,
+    incomingPendingData?: unknown,
   ): ExecutionContext {
     return {
       ...step,
@@ -111,6 +117,7 @@ export default class StepExecutorFactory {
       runStore: cfg.runStore,
       schemaCache: cfg.schemaCache,
       logger: cfg.logger,
+      incomingPendingData,
     };
   }
 }

packages/workflow-executor/src/executors/summary/step-execution-formatters.ts

@@ -1,4 +1,5 @@
 import type {
+  GuidanceStepExecutionData,
   LoadRelatedRecordStepExecutionData,
   McpStepExecutionData,
   StepExecutionData,
@@ -23,6 +24,8 @@ export default class StepExecutionFormatters {
         return StepExecutionFormatters.formatLoadRelatedRecord(execution);
       case 'mcp':
         return StepExecutionFormatters.formatMcp(execution as McpStepExecutionData);
+      case 'guidance':
+        return StepExecutionFormatters.formatGuidance(execution as GuidanceStepExecutionData);
       default:
         return null;
     }
@@ -42,6 +45,12 @@ export default class StepExecutionFormatters {
     return `  Executed: ${toolName} (result not summarized)`;
   }
 
+  private static formatGuidance(execution: GuidanceStepExecutionData): string | null {
+    if (!execution.executionResult) return null;
+
+    return `  The user provided the following input: "${execution.executionResult.userInput}"`;
+  }
+
   private static formatLoadRelatedRecord(
     execution: LoadRelatedRecordStepExecutionData,
   ): string | null {

packages/workflow-executor/src/executors/summary/step-summary-builder.ts

@@ -23,7 +23,7 @@ export default class StepSummaryBuilder {
       if (customLine !== null) {
         lines.push(customLine);
       } else {
-        if (execution.executionParams !== undefined) {
+        if ('executionParams' in execution && execution.executionParams !== undefined) {
           lines.push(`  Input: ${JSON.stringify(execution.executionParams)}`);
         } else if ('pendingData' in execution && execution.pendingData !== undefined) {
           lines.push(`  Pending: ${JSON.stringify(execution.pendingData)}`);

packages/workflow-executor/src/executors/trigger-record-action-step-executor.ts

@@ -24,8 +24,8 @@ interface ActionTarget extends ActionRef {
 export default class TriggerRecordActionStepExecutor extends RecordStepExecutor<TriggerActionStepDefinition> {
   protected async doExecute(): Promise<StepExecutionResult> {
     // Branch A -- Re-entry after pending execution found in RunStore
-    const pending = await this.findPendingExecution<TriggerRecordActionStepExecutionData>(
-      'trigger-action',
+    const pending = await this.patchAndReloadPendingData<TriggerRecordActionStepExecutionData>(
+      this.context.incomingPendingData,
     );
 
     if (pending) {

packages/workflow-executor/src/executors/update-record-step-executor.ts

@@ -30,7 +30,9 @@ interface UpdateTarget extends FieldRef {
 export default class UpdateRecordStepExecutor extends RecordStepExecutor<UpdateRecordStepDefinition> {
   protected async doExecute(): Promise<StepExecutionResult> {
     // Branch A -- Re-entry after pending execution found in RunStore
-    const pending = await this.findPendingExecution<UpdateRecordStepExecutionData>('update-record');
+    const pending = await this.patchAndReloadPendingData<UpdateRecordStepExecutionData>(
+      this.context.incomingPendingData,
+    );
 
     if (pending) {
       return this.handleConfirmationFlow<UpdateRecordStepExecutionData>(pending, async exec => {

packages/workflow-executor/src/http/executor-http-server.ts

@@ -11,12 +11,7 @@ import Koa from 'koa';
 import koaJwt from 'koa-jwt';
 
 import ConsoleLogger from '../adapters/console-logger';
-import {
-  InvalidPendingDataError,
-  PendingDataNotFoundError,
-  RunNotFoundError,
-  UserMismatchError,
-} from '../errors';
+import { RunNotFoundError, UserMismatchError } from '../errors';
 
 export interface ExecutorHttpServerOptions {
   port: number;
@@ -198,20 +193,6 @@ export default class ExecutorHttpServer {
         return;
       }
 
-      if (err instanceof PendingDataNotFoundError) {
-        ctx.status = 404;
-        ctx.body = { error: 'Step execution not found or has no pending data' };
-
-        return;
-      }
-
-      if (err instanceof InvalidPendingDataError) {
-        ctx.status = 400;
-        ctx.body = { error: 'Invalid request body', details: err.issues };
-
-        return;
-      }
-
       throw err;
     }
 

packages/workflow-executor/src/index.ts

@@ -7,6 +7,7 @@ export type {
   LoadRelatedRecordStepDefinition,
   RecordStepDefinition,
   McpStepDefinition,
+  GuidanceStepDefinition,
   StepDefinition,
 } from './types/step-definition';
 
@@ -15,6 +16,7 @@ export type {
   ConditionStepOutcome,
   RecordStepOutcome,
   McpStepOutcome,
+  GuidanceStepOutcome,
   StepOutcome,
 } from './types/step-outcome';
 
@@ -35,6 +37,7 @@ export type {
   McpToolRef,
   McpToolCall,
   McpStepExecutionData,
+  GuidanceStepExecutionData,
   ExecutedStepExecutionData,
   StepExecutionData,
 } from './types/step-execution-data';
@@ -101,6 +104,7 @@ export { default as UpdateRecordStepExecutor } from './executors/update-record-s
 export { default as TriggerRecordActionStepExecutor } from './executors/trigger-record-action-step-executor';
 export { default as LoadRelatedRecordStepExecutor } from './executors/load-related-record-step-executor';
 export { default as McpStepExecutor } from './executors/mcp-step-executor';
+export { default as GuidanceStepExecutor } from './executors/guidance-step-executor';
 export { default as AgentClientAgentPort } from './adapters/agent-client-agent-port';
 export { default as ForestServerWorkflowPort } from './adapters/forest-server-workflow-port';
 export { default as ExecutorHttpServer } from './http/executor-http-server';

packages/workflow-executor/src/pending-data-validators.ts

@@ -32,6 +32,12 @@ const patchBodySchemas: Partial<Record<StepExecutionData['type'], z.ZodTypeAny>>
     })
     .strict(),
   // relatedCollectionName and suggestedFields are NOT accepted — internal executor data.
+
+  guidance: z
+    .object({
+      userInput: z.string().min(1),
+    })
+    .strict(),
 };
 
 export default patchBodySchemas;