feat(workflows): add controller conversation state handling

Add controllerConversationActive flag to prevent runner from overwriting input state during return-to-controller
Expose controller info for deferred emission to enable return-to-controller during step execution

Author: moazbuilds

src/workflows/controller/view.ts

@@ -27,13 +27,22 @@ export interface ControllerViewOptions {
   eventBus: WorkflowEventBus;
 }
 
+export interface ControllerInfo {
+  id: string;
+  name: string;
+  engine: string;
+  model?: string;
+}
+
 export interface ControllerViewResult {
   /** Whether controller view ran (false if skipped) */
   ran: boolean;
   /** Controller agent ID if ran */
   agentId?: string;
   /** Monitoring ID for log viewing */
   monitoringId?: number;
+  /** Controller info for deferred emission (after workflow:started) */
+  controllerInfo?: ControllerInfo;
 }
 
 /**
@@ -65,20 +74,32 @@ export async function runControllerView(
   const definition = template.controller;
   debug('[ControllerView] Controller definition found: %s', definition.agentId);
 
+  // Find the controller agent from available agents (needed for both paths)
+  const allAgents = await collectAgentDefinitions(cwd);
+  const controller = allAgents.find(a => a.id === definition.agentId);
+
   // Check if controller session already exists
   const existingConfig = await loadControllerConfig(cmRoot);
   if (existingConfig?.controllerConfig?.sessionId) {
     debug('[ControllerView] Controller session already exists, skipping init');
+
+    // Return controller info for deferred emission (after workflow:started)
+    // This enables the 'c' key to return to controller even while step agent executes
+    const controllerInfo = controller ? {
+      id: definition.agentId,
+      name: (controller.name as string | undefined) ?? controller.id,
+      engine: existingConfig.controllerConfig.engine || 'unknown',
+      model: existingConfig.controllerConfig.model,
+    } : undefined;
+
     // Transition to executing view with autonomous mode
     await setAutonomousMode(cmRoot, 'true');
     await setControllerView(cmRoot, false);
     emitter.setWorkflowView('executing');
-    return { ran: false };
+    return { ran: false, controllerInfo };
   }
 
-  // Find the controller agent from available agents
-  const allAgents = await collectAgentDefinitions(cwd);
-  const controller = allAgents.find(a => a.id === definition.agentId);
+  // Validate controller agent exists (for init path)
   if (!controller) {
     debug('[ControllerView] Controller agent not found: %s', definition.agentId);
     throw new Error(`Controller agent not found: ${definition.agentId}`);

src/workflows/mode/mode.ts

@@ -13,6 +13,7 @@ import type { ModeProviders, ModeEvent, ModeEventListener } from './types.js';
 export class WorkflowMode {
   private _autoMode: boolean = false;
   private _paused: boolean = false;
+  private _controllerConversationActive: boolean = false;
   private readonly providers: ModeProviders;
   private readonly listeners: Set<ModeEventListener> = new Set();
 
@@ -34,6 +35,22 @@ export class WorkflowMode {
     return this._paused;
   }
 
+  /**
+   * Whether controller conversation is active (return-to-controller)
+   * When true, runner should skip processing to avoid overwriting controller input state
+   */
+  get controllerConversationActive(): boolean {
+    return this._controllerConversationActive;
+  }
+
+  /**
+   * Set controller conversation active state
+   */
+  setControllerConversationActive(active: boolean): void {
+    debug('[WorkflowMode] Controller conversation active: %s', active);
+    this._controllerConversationActive = active;
+  }
+
   /**
    * Whether user input should be used (derived from autoMode and paused)
    */

src/workflows/mode/types.ts

@@ -16,6 +16,9 @@ export interface WorkflowModeState {
 
   /** Whether workflow is paused */
   paused: boolean;
+
+  /** Whether controller conversation is active (return-to-controller) */
+  controllerConversationActive: boolean;
 }
 
 /**

src/workflows/runner/core.ts

@@ -155,6 +155,13 @@ export async function handleState(
   callbacks: ModeHandlerCallbacks,
   fsmState: 'awaiting' | 'delegated'
 ): Promise<void> {
+  // Skip processing if controller conversation is active (return-to-controller)
+  // This prevents overwriting controller's input state with step agent's state
+  if (ctx.mode.controllerConversationActive) {
+    debug('[Runner:core] Skipping handleState - controller conversation active');
+    return;
+  }
+
   const machineCtx = ctx.machine.context;
   const stepIndex = machineCtx.currentStepIndex;
   const step = ctx.moduleSteps[stepIndex];

src/workflows/signals/handlers/return.ts

@@ -76,10 +76,14 @@ export async function handleReturnToControllerSignal(ctx: SignalContext): Promis
   const divider = formatUserInput('━━━ RETURNING TO CONTROLLER ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
   AgentLoggerService.getInstance().write(config.monitoringId, `\n${divider}\n`)
 
+  // Mark controller conversation as active to prevent runner from overwriting input state
+  ctx.mode.setControllerConversationActive(true)
+
   debug('[ReturnToControllerSignal] Entering conversation loop')
 
-  // Inlined conversation loop (replaces runControllerConversation)
-  await new Promise<void>((resolve, reject) => {
+  try {
+    // Inlined conversation loop (replaces runControllerConversation)
+    await new Promise<void>((resolve, reject) => {
     const cleanup = () => {
       ;(process as NodeJS.EventEmitter).off('workflow:input', onInput)
       ;(process as NodeJS.EventEmitter).off('workflow:controller-continue', onContinue)
@@ -147,6 +151,10 @@ export async function handleReturnToControllerSignal(ctx: SignalContext): Promis
     ;(process as NodeJS.EventEmitter).on('workflow:input', onInput)
     ;(process as NodeJS.EventEmitter).on('workflow:controller-continue', onContinue)
   })
+  } finally {
+    // Clear controller conversation flag to allow runner to process again
+    ctx.mode.setControllerConversationActive(false)
+  }
 
   debug('[ReturnToControllerSignal] Conversation ended, resuming workflow')