feat(workflows): add interactive step control for workflow execution

Implement interactive behavior resolution for workflow steps with 8 defined scenarios. Adds new `interactive` flag to step configuration to control waiting behavior (true=wait for input, false=auto-advance). Includes autonomous prompt loop handling for non-interactive steps in auto mode.

The changes allow:
- Controller-driven execution in auto mode
- User-driven execution in manual mode
- Fully autonomous execution for non-interactive steps
- Proper handling of invalid configurations

Author: moazbuilds

prompts/templates/test-workflows/test-agent-1.md

@@ -1,14 +1 @@
-You are Test Agent 1.
-
-Your task is to write a checkpoint directive to pause the workflow for human review.
-
-Write the following JSON to the file `.codemachine/memory/directive.json`:
-
-```json
-{
-  "action": "checkpoint",
-  "reason": "Test checkpoint from Agent 1 - pausing for human review"
-}
-```
-
-After writing the file, say "Checkpoint directive written. Workflow should pause for review."
+Calculate 2+2= ? then say your name.

prompts/templates/test-workflows/test-agent-2.md

@@ -1,10 +1 @@
-You are Test Agent 2. You will test parallel orchestration by running:
-
-bun run dev run "frontend-dev 'say your name' & frontend-dev 'say your name' & frontend-dev 'say your name'"
-2- MUST modify .codemachine/memory/directive.json to make it exactly:
-{
-  "action": "checkpoint",
-  "reason": "Your plan needs modifications please check file .codemachine/memory/directive.json"
-}
-no more no less
-This tests the orchestrator with parallel execution (all agents run simultaneously). 
+Calculate 4+4= ? then say your name.

src/workflows/runner/wait.ts

@@ -10,6 +10,7 @@ import { AgentLoggerService } from '../../agents/monitoring/index.js';
 import type { InputContext } from '../input/index.js';
 import { getUniqueAgentId } from '../context/index.js';
 import { runStepResume } from '../step/run.js';
+import { resolveInteractiveBehavior } from '../step/interactive.js';
 import type { RunnerContext } from './types.js';
 
 export interface WaitCallbacks {
@@ -18,48 +19,76 @@ export interface WaitCallbacks {
 
 /**
  * Handle waiting state - get input from provider
+ *
+ * Uses resolveInteractiveBehavior() for all 8 scenarios:
+ * - Scenarios 1-4: Wait for controller/user input (shouldWait=true)
+ * - Scenario 5: Run autonomous prompt loop (runAutonomousLoop=true)
+ * - Scenario 6: Auto-advance to next step (queue exhausted after autonomous loop)
+ * - Scenarios 7-8: Invalid cases forced to interactive:true (shouldWait=true)
  */
 export async function handleWaiting(ctx: RunnerContext, callbacks: WaitCallbacks): Promise<void> {
   const machineCtx = ctx.machine.context;
 
   debug('[Runner] Handling waiting state, autoMode=%s, paused=%s, promptQueue=%d items, queueIndex=%d',
     ctx.mode.autoMode, ctx.mode.paused, ctx.indexManager.promptQueue.length, ctx.indexManager.promptQueueIndex);
 
-  // Get provider from WorkflowMode (single source of truth)
-  // WorkflowMode.getActiveProvider() automatically handles paused and autoMode state
-  const provider = ctx.mode.getActiveProvider();
-  if (ctx.mode.paused) {
-    debug('[Runner] Workflow is paused, using user input provider');
-  } else if (!ctx.mode.autoMode) {
-    debug('[Runner] Manual mode, using user input provider');
-  }
-
   // Get queue state from session (uses indexManager as single source of truth)
   const session = ctx.getCurrentSession();
   const hasChainedPrompts = session
     ? !session.isQueueExhausted
     : !ctx.indexManager.isQueueExhausted();
 
-  if (!ctx.mode.paused && !hasChainedPrompts && ctx.mode.autoMode) {
-    // Check if we're resuming a step (sessionId exists but no completedAt)
-    const stepData = await ctx.indexManager.getStepData(machineCtx.currentStepIndex);
-    const isResumingStep = stepData?.sessionId && !stepData.completedAt;
+  // Get current step and resolve interactive behavior
+  const step = ctx.moduleSteps[machineCtx.currentStepIndex];
+  const stepUniqueAgentId = getUniqueAgentId(step, machineCtx.currentStepIndex);
 
-    if (isResumingStep) {
-      // Resuming incomplete step - let controller decide
-      debug('[Runner] Resuming step in auto mode, letting controller handle it');
-    } else {
-      // No chained prompts, not paused, and in auto mode - auto-advance to next step
-      debug('[Runner] No chained prompts (auto mode), auto-advancing to next step');
-      await ctx.indexManager.stepCompleted(machineCtx.currentStepIndex);
-      ctx.machine.send({ type: 'INPUT_RECEIVED', input: '' });
-      return;
+  // Resolve interactive behavior using single source of truth
+  const behavior = resolveInteractiveBehavior({
+    step,
+    autoMode: ctx.mode.autoMode,
+    hasChainedPrompts,
+    stepIndex: machineCtx.currentStepIndex,
+  });
+
+  debug('[Runner] Scenario=%d, shouldWait=%s, runAutonomousLoop=%s, wasForced=%s',
+    behavior.scenario, behavior.shouldWait, behavior.runAutonomousLoop, behavior.wasForced);
+
+  // Handle Scenarios 7-8: interactive:false in manual mode
+  // Behave like normal manual mode: ensure agent is awaiting and show prompt box
+  if (behavior.wasForced) {
+    ctx.emitter.logMessage(stepUniqueAgentId, 'Manual mode active. Waiting for your input to continue. Use auto mode for fully autonomous execution.');
+    ctx.emitter.updateAgentStatus(stepUniqueAgentId, 'awaiting');
+  }
+
+  // Handle Scenario 5: Fully autonomous prompt loop (interactive:false + autoMode + chainedPrompts)
+  if (!ctx.mode.paused && behavior.runAutonomousLoop) {
+    debug('[Runner] Running autonomous prompt loop (Scenario 5)');
+    await runAutonomousPromptLoop(ctx);
+    return;
+  }
+
+  // Handle Scenario 6: Auto-advance (interactive:false + autoMode + no chainedPrompts)
+  // This can happen when queue is exhausted after autonomous loop
+  if (!ctx.mode.paused && !behavior.shouldWait && !behavior.runAutonomousLoop) {
+    debug('[Runner] Auto-advancing to next step (Scenario 6)');
+    if (session) {
+      await session.complete();
     }
+    ctx.emitter.updateAgentStatus(stepUniqueAgentId, 'completed');
+    ctx.indexManager.resetQueue();
+    await ctx.indexManager.stepCompleted(machineCtx.currentStepIndex);
+    ctx.machine.send({ type: 'INPUT_RECEIVED', input: '' });
+    return;
   }
 
-  // Build input context
-  const step = ctx.moduleSteps[machineCtx.currentStepIndex];
-  const stepUniqueAgentId = getUniqueAgentId(step, machineCtx.currentStepIndex);
+  // Get provider from WorkflowMode (single source of truth)
+  // WorkflowMode.getActiveProvider() automatically handles paused and autoMode state
+  const provider = ctx.mode.getActiveProvider();
+  if (ctx.mode.paused) {
+    debug('[Runner] Workflow is paused, using user input provider');
+  } else if (!ctx.mode.autoMode) {
+    debug('[Runner] Manual mode, using user input provider');
+  }
 
   // Get queue state from session if available, otherwise from indexManager
   const queueState = session
@@ -131,6 +160,76 @@ export async function handleWaiting(ctx: RunnerContext, callbacks: WaitCallbacks
   }
 }
 
+/**
+ * Run autonomous prompt loop (Scenario 5)
+ *
+ * Automatically sends the next chained prompt without controller/user involvement.
+ * Each prompt runs through the state machine naturally - when it completes,
+ * handleWaiting is called again and this function sends the next prompt.
+ *
+ * Used when interactive:false + autoMode + hasChainedPrompts.
+ */
+async function runAutonomousPromptLoop(ctx: RunnerContext): Promise<void> {
+  const machineCtx = ctx.machine.context;
+  const stepIndex = machineCtx.currentStepIndex;
+  const step = ctx.moduleSteps[stepIndex];
+  const uniqueAgentId = getUniqueAgentId(step, stepIndex);
+  const session = ctx.getCurrentSession();
+
+  // Check if queue is exhausted
+  const isExhausted = session
+    ? session.isQueueExhausted
+    : ctx.indexManager.isQueueExhausted();
+
+  if (isExhausted) {
+    // All prompts sent - complete step and advance to next
+    debug('[Runner:autonomous] Queue exhausted, completing step %d', stepIndex);
+    ctx.emitter.updateAgentStatus(uniqueAgentId, 'completed');
+    ctx.indexManager.resetQueue();
+    await ctx.indexManager.stepCompleted(stepIndex);
+    ctx.machine.send({ type: 'INPUT_RECEIVED', input: '' });
+    return;
+  }
+
+  // Get next prompt
+  const nextPrompt = ctx.indexManager.getCurrentQueuedPrompt();
+  if (!nextPrompt) {
+    // No more prompts - complete step and advance
+    debug('[Runner:autonomous] No more prompts, completing step %d', stepIndex);
+    ctx.emitter.updateAgentStatus(uniqueAgentId, 'completed');
+    ctx.indexManager.resetQueue();
+    await ctx.indexManager.stepCompleted(stepIndex);
+    ctx.machine.send({ type: 'INPUT_RECEIVED', input: '' });
+    return;
+  }
+
+  // Send the next prompt
+  const chainIndex = ctx.indexManager.promptQueueIndex;
+  debug('[Runner:autonomous] Sending prompt %d: %s...', chainIndex, nextPrompt.content.slice(0, 50));
+
+  // Advance queue
+  if (session) {
+    session.advanceQueue();
+  } else {
+    ctx.indexManager.advanceQueue();
+  }
+
+  // Track chain completion
+  await ctx.indexManager.chainCompleted(stepIndex, chainIndex);
+
+  // Resume step with the prompt - when it completes, state machine will
+  // transition back to awaiting and handleWaiting will be called again
+  ctx.machine.send({ type: 'RESUME' });
+  await runStepResume(ctx, {
+    resumePrompt: nextPrompt.content,
+    resumeMonitoringId: machineCtx.currentMonitoringId,
+    source: 'controller',
+  });
+  // After runStepResume completes, machine goes back to awaiting state
+  // and handleWaiting will be called again - it will detect Scenario 5
+  // and call this function again to send the next prompt
+}
+
 /**
  * Handle resume with input - delegates to step/run.ts
  */

src/workflows/step/index.ts

@@ -12,3 +12,9 @@ export { selectEngine, EngineAuthCache, authCache } from './engine.js';
 export { beforeRun, afterRun, cleanupRun, type BeforeRunOptions, type AfterRunResult } from './hooks.js';
 export { runStepFresh, runStepResume, type RunStepOptions, type RunStepResult } from './run.js';
 export { shouldSkipStep, logSkipDebug, type ActiveLoop, type SkipCheckOptions } from './skip.js';
+export {
+  resolveInteractiveBehavior,
+  type InteractiveBehavior,
+  type InteractiveScenario,
+  type ResolveInteractiveOptions,
+} from './interactive.js';

src/workflows/step/interactive.ts

@@ -0,0 +1,130 @@
+/**
+ * Interactive Behavior Resolution
+ *
+ * Single source of truth for determining step interactive behavior.
+ * Handles all 8 scenarios defined in the interactive flag specification.
+ *
+ * VALID SCENARIOS:
+ * | # | interactive | autoMode | chainedPrompts | Behavior                                    |
+ * |---|-------------|----------|----------------|---------------------------------------------|
+ * | 1 | true        | true     | yes            | Controller drives with prompts              |
+ * | 2 | true        | true     | no             | Controller drives single step               |
+ * | 3 | true        | false    | yes            | User drives with prompts                    |
+ * | 4 | true        | false    | no             | User drives each step                       |
+ * | 5 | false       | true     | yes            | FULLY AUTONOMOUS - auto-send ALL prompts    |
+ * | 6 | false       | true     | no             | Auto-advance to next step                   |
+ *
+ * INVALID SCENARIOS (force interactive:true + log warning):
+ * | # | interactive | autoMode | chainedPrompts | Handling                                    |
+ * |---|-------------|----------|----------------|---------------------------------------------|
+ * | 7 | false       | false    | yes            | Force interactive:true, warn, -> case 3    |
+ * | 8 | false       | false    | no             | Force interactive:true, warn, -> case 4    |
+ */
+
+import { debug } from '../../shared/logging/logger.js';
+import type { ModuleStep } from '../templates/types.js';
+
+export type InteractiveScenario = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+
+export interface InteractiveBehavior {
+  /** The resolved scenario number (1-8) */
+  scenario: InteractiveScenario;
+  /** Whether to wait for input (user or controller) */
+  shouldWait: boolean;
+  /** Whether to run autonomous prompt loop (Scenario 5) */
+  runAutonomousLoop: boolean;
+  /** Whether interactive was forced due to invalid config */
+  wasForced: boolean;
+}
+
+export interface ResolveInteractiveOptions {
+  step: ModuleStep;
+  autoMode: boolean;
+  hasChainedPrompts: boolean;
+  stepIndex: number;
+}
+
+/**
+ * Resolve interactive behavior for a workflow step
+ *
+ * Determines the correct behavior based on:
+ * - step.interactive value (true, false, or undefined)
+ * - autoMode state (controller available or manual mode)
+ * - hasChainedPrompts (whether step has prompts to process)
+ *
+ * For invalid cases (interactive:false + manual mode), forces interactive:true
+ * and logs a warning since manual mode requires user interaction.
+ */
+export function resolveInteractiveBehavior(
+  options: ResolveInteractiveOptions
+): InteractiveBehavior {
+  const { step, autoMode, hasChainedPrompts, stepIndex } = options;
+  const interactive = step.interactive;
+
+  // Handle undefined interactive (default behavior based on chainedPrompts)
+  if (interactive === undefined) {
+    const effectiveInteractive = hasChainedPrompts;
+    return resolveInteractiveBehavior({
+      step: { ...step, interactive: effectiveInteractive },
+      autoMode,
+      hasChainedPrompts,
+      stepIndex,
+    });
+  }
+
+  // interactive === true
+  if (interactive === true) {
+    if (autoMode) {
+      // Scenarios 1-2: Controller drives
+      return {
+        scenario: hasChainedPrompts ? 1 : 2,
+        shouldWait: true,
+        runAutonomousLoop: false,
+        wasForced: false,
+      };
+    } else {
+      // Scenarios 3-4: User drives
+      return {
+        scenario: hasChainedPrompts ? 3 : 4,
+        shouldWait: true,
+        runAutonomousLoop: false,
+        wasForced: false,
+      };
+    }
+  }
+
+  // interactive === false
+  if (autoMode) {
+    // Valid: Scenarios 5-6
+    if (hasChainedPrompts) {
+      // Scenario 5: Fully autonomous - auto-send ALL prompts
+      return {
+        scenario: 5,
+        shouldWait: false,
+        runAutonomousLoop: true,
+        wasForced: false,
+      };
+    } else {
+      // Scenario 6: Auto-advance to next step
+      return {
+        scenario: 6,
+        shouldWait: false,
+        runAutonomousLoop: false,
+        wasForced: false,
+      };
+    }
+  } else {
+    // Invalid: Scenarios 7-8 - force interactive:true
+    debug(
+      '[interactive] Step %d has interactive:false in manual mode. ' +
+        'Forcing interactive:true. Use auto mode for non-interactive steps.',
+      stepIndex
+    );
+    return {
+      scenario: hasChainedPrompts ? 7 : 8,
+      shouldWait: true,
+      runAutonomousLoop: false,
+      wasForced: true,
+    };
+  }
+}