feat(workflows): implement pause directive handling and UI integration

moazbuilds · moazbuilds · commit d1fac7b99fd4 · 2025-12-30T20:19:37.000+02:00
add pause directive handler similar to checkpoint pattern
update workflow runner to handle pause in various scenarios
preload chained prompts for immediate UI display
remove fallback step info display in output window
diff --git a/prompts/templates/test-workflows/test-loop-chained/01-check-state.xml b/prompts/templates/test-workflows/test-loop-chained/01-check-state.xml
@@ -1,4 +1,12 @@
 <step n="1" goal="Check current state">
   <action>Read `.codemachine/memory/directive.json` to see current directive state</action>
   <action>Report what you found</action>
+  <action>Write to `.codemachine/memory/directive.json`:
+  ```json
+  {
+    "action": "pause",
+    "reason": "Testing pause directive"
+  }
+  ```
+  </action>
 </step>
diff --git a/src/cli/tui/routes/workflow/components/output/output-window.tsx b/src/cli/tui/routes/workflow/components/output/output-window.tsx
@@ -134,18 +134,6 @@ export function OutputWindow(props: OutputWindowProps) {
           },
         }
       }
-      // Fallback: use workflow step info from currentAgent
-      const agent = props.currentAgent
-      if (agent?.stepIndex !== undefined && agent?.totalSteps !== undefined && agent.totalSteps > 1) {
-        return {
-          mode: "passive",
-          chainedStep: {
-            name: agent.name,
-            index: agent.stepIndex + 1,
-            total: agent.totalSteps,
-          },
-        }
-      }
       return { mode: "passive" }
     }
 
diff --git a/src/workflows/directives/pause/handler.ts b/src/workflows/directives/pause/handler.ts
@@ -0,0 +1,46 @@
+/**
+ * Pause Directive Handler
+ *
+ * Handles agent-written { action: 'pause' } directive.
+ * Similar pattern to checkpoint/handler.ts.
+ */
+
+import type { WorkflowStep } from '../../templates/index.js';
+import { isModuleStep } from '../../templates/types.js';
+import { evaluatePauseDirective } from './evaluator.js';
+import type { WorkflowEventEmitter } from '../../events/emitter.js';
+
+export interface PauseHandlerDecision {
+  shouldPause: boolean;
+  reason?: string;
+}
+
+export async function handlePauseLogic(
+  step: WorkflowStep,
+  cwd: string,
+  emitter?: WorkflowEventEmitter,
+): Promise<PauseHandlerDecision | null> {
+  // Only module steps can have pause behavior
+  if (!isModuleStep(step)) {
+    return null;
+  }
+
+  const pauseDecision = await evaluatePauseDirective({
+    cwd,
+    pauseRequested: false, // Only check agent-written directive, not user keypress
+  });
+
+  if (pauseDecision?.shouldPause) {
+    const message = `${step.agentName} requested pause` +
+      `${pauseDecision.reason ? `: ${pauseDecision.reason}` : ''}`;
+
+    emitter?.logMessage(step.agentId, message);
+
+    return {
+      shouldPause: true,
+      reason: pauseDecision.reason,
+    };
+  }
+
+  return null;
+}
diff --git a/src/workflows/directives/pause/index.ts b/src/workflows/directives/pause/index.ts
@@ -7,3 +7,4 @@
 
 export * from './types.js';
 export * from './evaluator.js';
+export * from './handler.js';
diff --git a/src/workflows/runner/delegated.ts b/src/workflows/runner/delegated.ts
@@ -53,6 +53,19 @@ export async function handleDelegated(ctx: RunnerContext, callbacks: DelegatedCa
   // Update agent status to delegated
   ctx.emitter.updateAgentStatus(stepUniqueAgentId, 'delegated');
 
+  // Emit input state so UI shows chained prompts info in delegated mode
+  const queueStateForUI = session
+    ? session.getQueueState()
+    : { promptQueue: [...ctx.indexManager.promptQueue], promptQueueIndex: ctx.indexManager.promptQueueIndex };
+  if (queueStateForUI.promptQueue.length > 0) {
+    ctx.emitter.setInputState({
+      active: false, // Not active - controller is running
+      queuedPrompts: queueStateForUI.promptQueue.map(p => ({ name: p.name, label: p.label, content: p.content })),
+      currentIndex: queueStateForUI.promptQueueIndex,
+      monitoringId: machineCtx.currentMonitoringId,
+    });
+  }
+
   // Resolve interactive behavior using actual mode state
   const behavior = resolveInteractiveBehavior({
     step,
diff --git a/src/workflows/runner/wait.ts b/src/workflows/runner/wait.ts
@@ -72,15 +72,64 @@ export async function handleWaiting(ctx: RunnerContext, callbacks: WaitCallbacks
   // 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();
+    const action = await processPostStepDirectives({
+      ctx,
+      step,
+      stepOutput: { output: machineCtx.currentOutput?.output ?? '' },
+      stepIndex: machineCtx.currentStepIndex,
+      uniqueAgentId: stepUniqueAgentId,
+    });
+
+    debug('[Runner:scenario6] Post-step action: %s', action.type);
+
+    switch (action.type) {
+      case 'stop':
+        ctx.machine.send({ type: 'STOP' });
+        return;
+
+      case 'checkpoint':
+        return;
+
+      case 'pause': {
+        debug('[Runner:scenario6] Directive: pause');
+        ctx.emitter.logMessage(stepUniqueAgentId, `Paused${action.reason ? `: ${action.reason}` : ''}`);
+        ctx.mode.pause();
+        machineCtx.paused = true;
+        ctx.emitter.updateAgentStatus(stepUniqueAgentId, 'awaiting');
+        // Enable input box for user to resume
+        const pauseQueueState = session
+          ? session.getQueueState()
+          : { promptQueue: [...ctx.indexManager.promptQueue], promptQueueIndex: ctx.indexManager.promptQueueIndex };
+        ctx.emitter.setInputState({
+          active: true,
+          queuedPrompts: pauseQueueState.promptQueue.map(p => ({ name: p.name, label: p.label, content: p.content })),
+          currentIndex: pauseQueueState.promptQueueIndex,
+          monitoringId: machineCtx.currentMonitoringId,
+        });
+        return;
+      }
+
+      case 'loop':
+        debug('[Runner:scenario6] Loop to step %d', action.targetIndex);
+        ctx.emitter.updateAgentStatus(stepUniqueAgentId, 'completed');
+        await ctx.indexManager.stepCompleted(machineCtx.currentStepIndex);
+        ctx.indexManager.resetQueue();
+        machineCtx.currentStepIndex = action.targetIndex;
+        ctx.machine.send({ type: 'INPUT_RECEIVED', input: '' });
+        return;
+
+      case 'advance':
+      default:
+        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;
     }
-    ctx.emitter.updateAgentStatus(stepUniqueAgentId, 'completed');
-    ctx.indexManager.resetQueue();
-    await ctx.indexManager.stepCompleted(machineCtx.currentStepIndex);
-    ctx.machine.send({ type: 'INPUT_RECEIVED', input: '' });
-    return;
   }
 
   // Get provider from WorkflowMode (single source of truth)
@@ -242,6 +291,27 @@ async function runAutonomousPromptLoop(ctx: RunnerContext): Promise<void> {
   const uniqueAgentId = getUniqueAgentId(step, stepIndex);
   const session = ctx.getCurrentSession();
 
+  // Check for pause directive BEFORE sending next prompt (regardless of queue state)
+  const pauseResult = await evaluateOnAdvance(ctx.cwd);
+  if (pauseResult.type === 'pause') {
+    debug('[Runner:autonomous] Directive: pause (before next prompt)');
+    ctx.emitter.logMessage(uniqueAgentId, `Paused${pauseResult.reason ? `: ${pauseResult.reason}` : ''}`);
+    ctx.mode.pause();
+    machineCtx.paused = true;
+    ctx.emitter.updateAgentStatus(uniqueAgentId, 'awaiting');
+    // Enable input box for user to resume
+    const queueState = session
+      ? session.getQueueState()
+      : { promptQueue: [...ctx.indexManager.promptQueue], promptQueueIndex: ctx.indexManager.promptQueueIndex };
+    ctx.emitter.setInputState({
+      active: true,
+      queuedPrompts: queueState.promptQueue.map(p => ({ name: p.name, label: p.label, content: p.content })),
+      currentIndex: queueState.promptQueueIndex,
+      monitoringId: machineCtx.currentMonitoringId,
+    });
+    return;
+  }
+
   // Check if queue is exhausted
   const isExhausted = session
     ? session.isQueueExhausted
@@ -268,6 +338,25 @@ async function runAutonomousPromptLoop(ctx: RunnerContext): Promise<void> {
         // Checkpoint was handled by afterRun, just stay in current state
         return;
 
+      case 'pause': {
+        debug('[Runner:autonomous] Directive: pause');
+        ctx.emitter.logMessage(uniqueAgentId, `Paused${action.reason ? `: ${action.reason}` : ''}`);
+        ctx.mode.pause();
+        machineCtx.paused = true;
+        ctx.emitter.updateAgentStatus(uniqueAgentId, 'awaiting');
+        // Enable input box for user to resume
+        const pauseQueueState = session
+          ? session.getQueueState()
+          : { promptQueue: [...ctx.indexManager.promptQueue], promptQueueIndex: ctx.indexManager.promptQueueIndex };
+        ctx.emitter.setInputState({
+          active: true,
+          queuedPrompts: pauseQueueState.promptQueue.map(p => ({ name: p.name, label: p.label, content: p.content })),
+          currentIndex: pauseQueueState.promptQueueIndex,
+          monitoringId: machineCtx.currentMonitoringId,
+        });
+        return;
+      }
+
       case 'loop':
         // Loop directive processed - rewind to target step
         debug('[Runner:autonomous] Loop to step %d', action.targetIndex);
@@ -311,6 +400,25 @@ async function runAutonomousPromptLoop(ctx: RunnerContext): Promise<void> {
       case 'checkpoint':
         return;
 
+      case 'pause': {
+        debug('[Runner:autonomous] Directive: pause (no prompts)');
+        ctx.emitter.logMessage(uniqueAgentId, `Paused${action.reason ? `: ${action.reason}` : ''}`);
+        ctx.mode.pause();
+        machineCtx.paused = true;
+        ctx.emitter.updateAgentStatus(uniqueAgentId, 'awaiting');
+        // Enable input box for user to resume
+        const pauseQueueState = session
+          ? session.getQueueState()
+          : { promptQueue: [...ctx.indexManager.promptQueue], promptQueueIndex: ctx.indexManager.promptQueueIndex };
+        ctx.emitter.setInputState({
+          active: true,
+          queuedPrompts: pauseQueueState.promptQueue.map(p => ({ name: p.name, label: p.label, content: p.content })),
+          currentIndex: pauseQueueState.promptQueueIndex,
+          monitoringId: machineCtx.currentMonitoringId,
+        });
+        return;
+      }
+
       case 'loop':
         debug('[Runner:autonomous] Loop to step %d', action.targetIndex);
         ctx.emitter.updateAgentStatus(uniqueAgentId, 'completed');
diff --git a/src/workflows/step/hooks.ts b/src/workflows/step/hooks.ts
@@ -14,6 +14,7 @@ import type { StepIndexManager } from '../indexing/index.js';
 import { handleTriggerLogic } from '../directives/trigger/index.js';
 import { handleCheckpointLogic } from '../directives/checkpoint/index.js';
 import { handleErrorLogic } from '../directives/error/index.js';
+import { handlePauseLogic } from '../directives/pause/index.js';
 import type { WorkflowEventEmitter } from '../events/index.js';
 import { type ModuleStep, type WorkflowTemplate, isModuleStep } from '../templates/types.js';
 import { getUniqueAgentId } from '../context/index.js';
@@ -126,6 +127,8 @@ export interface AfterRunResult {
   stoppedByCheckpointQuit?: boolean;
   workflowShouldStop?: boolean;
   checkpointContinued?: boolean;
+  pauseRequested?: boolean;
+  pauseReason?: string;
 }
 
 /**
@@ -153,7 +156,8 @@ export type PostStepAction =
   | { type: 'advance' }
   | { type: 'loop'; targetIndex: number; newActiveLoop: ActiveLoop | null }
   | { type: 'stop' }
-  | { type: 'checkpoint' };
+  | { type: 'checkpoint' }
+  | { type: 'pause'; reason?: string };
 
 /**
  * Context for processPostStepDirectives
@@ -203,6 +207,10 @@ export async function processPostStepDirectives(context: ProcessPostStepContext)
     return { type: 'checkpoint' };
   }
 
+  if (postResult.pauseRequested) {
+    return { type: 'pause', reason: postResult.pauseReason };
+  }
+
   // Handle loop - newIndex is the raw index from loop logic
   if (postResult.newIndex !== undefined) {
     // Update active loop state
@@ -304,6 +312,12 @@ export async function afterRun(options: AfterRunOptions): Promise<AfterRunResult
     return { shouldBreak: false, checkpointContinued: true };
   }
 
+  // Check for pause directive
+  const pauseResult = await handlePauseLogic(step, cwd, emitter);
+  if (pauseResult?.shouldPause) {
+    return { shouldBreak: false, pauseRequested: true, pauseReason: pauseResult.reason };
+  }
+
   // Check for loop directive
   const loopResult = await handleLoopLogic(step, index, stepOutput.output, loopCounters, cwd, emitter);
 
diff --git a/src/workflows/step/run.ts b/src/workflows/step/run.ts
@@ -134,6 +134,33 @@ export async function runStepFresh(ctx: RunnerContext): Promise<RunStepResult |
     ctx.emitter.updateAgentModel(uniqueAgentId, resolvedModel);
   }
 
+  // Pre-load chained prompts from agent config so UI can show step info immediately
+  const agentConfig = await loadAgentConfig(step.agentId, ctx.cwd);
+  if (agentConfig?.chainedPromptsPath) {
+    const selectedConditions = await getSelectedConditions(ctx.cmRoot);
+    const preloadedPrompts = await loadChainedPrompts(
+      agentConfig.chainedPromptsPath,
+      ctx.cwd,
+      selectedConditions
+    );
+    if (preloadedPrompts.length > 0) {
+      debug('[step/run] Pre-loaded %d chained prompts for UI', preloadedPrompts.length);
+      const session = ctx.getCurrentSession();
+      if (session) {
+        session.loadChainedPrompts(preloadedPrompts);
+      } else {
+        ctx.indexManager.initQueue(preloadedPrompts, 0);
+      }
+      // Emit input state immediately so UI shows chained prompts info
+      ctx.emitter.setInputState({
+        active: false, // Not active yet - agent is running
+        queuedPrompts: preloadedPrompts.map(p => ({ name: p.name, label: p.label, content: p.content })),
+        currentIndex: 0,
+        monitoringId: undefined, // Not yet known
+      });
+    }
+  }
+
   try {
     // Execute the step
     const output = await executeStep(step, ctx.cwd, {
@@ -248,6 +275,18 @@ export async function runStepFresh(ctx: RunnerContext): Promise<RunStepResult |
       if (!machineCtx.autoMode) {
         ctx.emitter.updateAgentStatus(uniqueAgentId, 'awaiting');
       }
+
+      // Emit input state for fresh start so UI shows chained prompts info immediately
+      const queueState = session
+        ? session.getQueueState()
+        : { promptQueue: [...ctx.indexManager.promptQueue], promptQueueIndex: ctx.indexManager.promptQueueIndex };
+      ctx.emitter.setInputState({
+        active: !machineCtx.autoMode, // Only active input box in manual mode
+        queuedPrompts: queueState.promptQueue.map(p => ({ name: p.name, label: p.label, content: p.content })),
+        currentIndex: queueState.promptQueueIndex,
+        monitoringId: stepOutput.monitoringId,
+      });
+
       ctx.machine.send({ type: 'STEP_COMPLETE', output: stepOutput });
       return { output: stepOutput };
     } else {
diff --git a/templates/workflows/test2.workflow.js b/templates/workflows/test2.workflow.js
@@ -14,7 +14,7 @@ export default {
     // Test loop directive respect in Scenario 6
     // This module has chained prompts that set loop directive
     // After chained prompts complete, Scenario 6 should respect the loop directive
-    resolveModule('test-loop', { interactive: false, loopSteps: 1 }),
+    resolveModule('test-loop', { interactive: false, loopSteps: 3 }),
   ],
   subAgentIds: ['frontend-dev'],
 };

Original file line number	Diff line number	Diff line change
`@@ -134,18 +134,6 @@ export function OutputWindow(props: OutputWindowProps) {`
`134`	`134`	`},`
`135`	`135`	`}`
`136`	`136`	`}`
`137`		`- // Fallback: use workflow step info from currentAgent`
`138`		`- const agent = props.currentAgent`
`139`		`- if (agent?.stepIndex !== undefined && agent?.totalSteps !== undefined && agent.totalSteps > 1) {`
`140`		`- return {`
`141`		`- mode: "passive",`
`142`		`- chainedStep: {`
`143`		`- name: agent.name,`
`144`		`- index: agent.stepIndex + 1,`
`145`		`- total: agent.totalSteps,`
`146`		`- },`
`147`		`- }`
`148`		`- }`
`149`	`137`	`return { mode: "passive" }`
`150`	`138`	`}`
`151`	`139`
Original file line number	Diff line number	Diff line change
`@@ -7,3 +7,4 @@`
`7`	`7`
`8`	`8`	`export * from './types.js';`
`9`	`9`	`export * from './evaluator.js';`
	`10`	`+export * from './handler.js';`