feat(behaviors): implement pause behavior with centralized manager

Add pause behavior module with evaluator, listener and handler components
Introduce behavior manager to coordinate all workflow behaviors
Update runner to use behavior manager for pause functionality

Author: moazbuilds

src/workflows/behaviors/index.ts

@@ -11,3 +11,5 @@ export * from './loop/index.js';
 export * from './trigger/index.js';
 export * from './checkpoint/index.js';
 export * from './error/index.js';
+export * from './manager/index.js';
+export * from './pause/index.js';

src/workflows/behaviors/manager/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Behavior Manager Module
+ *
+ * Central coordinator between runner and individual behaviors.
+ */
+
+export * from './types.js';
+export * from './manager.js';

src/workflows/behaviors/manager/manager.ts

@@ -0,0 +1,164 @@
+/**
+ * Behavior Manager
+ *
+ * Central coordinator for all workflow behaviors.
+ * Runner only knows about the manager, not individual behaviors.
+ */
+
+import { debug } from '../../../shared/logging/logger.js';
+import type { WorkflowEventEmitter } from '../../events/emitter.js';
+import type { StateMachine } from '../../state/index.js';
+import type {
+  Behavior,
+  BehaviorType,
+  BehaviorContext,
+  BehaviorResult,
+  BehaviorManagerOptions,
+  BehaviorInitContext,
+  StepContext,
+} from './types.js';
+import { PauseBehavior } from '../pause/handler.js';
+
+/**
+ * BehaviorManager - orchestrates all workflow behaviors
+ */
+export class BehaviorManager {
+  private behaviors: Map<BehaviorType, Behavior> = new Map();
+  private emitter: WorkflowEventEmitter;
+  private machine: StateMachine;
+  private cwd: string;
+  private cmRoot: string;
+  private abortController: AbortController | null = null;
+  private stepContext: StepContext | null = null;
+
+  constructor(options: BehaviorManagerOptions) {
+    this.emitter = options.emitter;
+    this.machine = options.machine;
+    this.cwd = options.cwd;
+    this.cmRoot = options.cmRoot;
+
+    // Register built-in behaviors
+    this.registerBuiltInBehaviors();
+
+    // Initialize all behaviors
+    this.initAll();
+  }
+
+  /**
+   * Register built-in behaviors
+   */
+  private registerBuiltInBehaviors(): void {
+    this.register(new PauseBehavior());
+    // Future: this.register(new SkipBehavior());
+    // Future: this.register(new StopBehavior());
+  }
+
+  /**
+   * Initialize all behaviors
+   */
+  private initAll(): void {
+    const initContext: BehaviorInitContext = {
+      getAbortController: () => this.abortController,
+      getStepContext: () => this.stepContext,
+      emitter: this.emitter,
+      machine: this.machine,
+      cwd: this.cwd,
+      cmRoot: this.cmRoot,
+    };
+
+    for (const behavior of this.behaviors.values()) {
+      behavior.init?.(initContext);
+    }
+  }
+
+  /**
+   * Register a behavior
+   */
+  register(behavior: Behavior): void {
+    debug('[BehaviorManager] Registering behavior: %s', behavior.name);
+    this.behaviors.set(behavior.name, behavior);
+  }
+
+  /**
+   * Get a registered behavior by type
+   */
+  get<T extends Behavior>(type: BehaviorType): T | undefined {
+    return this.behaviors.get(type) as T | undefined;
+  }
+
+  /**
+   * Set the current abort controller (called by runner)
+   */
+  setAbortController(controller: AbortController | null): void {
+    this.abortController = controller;
+  }
+
+  /**
+   * Get the current abort controller
+   */
+  getAbortController(): AbortController | null {
+    return this.abortController;
+  }
+
+  /**
+   * Set current step context (called by runner before each step)
+   */
+  setStepContext(context: StepContext | null): void {
+    this.stepContext = context;
+  }
+
+  /**
+   * Get current step context
+   */
+  getStepContext(): StepContext | null {
+    return this.stepContext;
+  }
+
+  /**
+   * Handle a behavior event
+   */
+  async handle(
+    type: BehaviorType,
+    partialContext: Partial<BehaviorContext> & { stepIndex: number; agentId: string; agentName: string }
+  ): Promise<BehaviorResult> {
+    const behavior = this.behaviors.get(type);
+
+    if (!behavior) {
+      debug('[BehaviorManager] No behavior registered for: %s', type);
+      return { handled: false };
+    }
+
+    const context: BehaviorContext = {
+      cwd: this.cwd,
+      cmRoot: this.cmRoot,
+      emitter: this.emitter,
+      machine: this.machine,
+      abortController: this.abortController,
+      ...partialContext,
+    };
+
+    debug('[BehaviorManager] Handling behavior: %s', type);
+    return behavior.handle(context);
+  }
+
+  /**
+   * Reset all behaviors (called at step start)
+   */
+  resetAll(): void {
+    debug('[BehaviorManager] Resetting all behaviors');
+    for (const behavior of this.behaviors.values()) {
+      behavior.reset?.();
+    }
+  }
+
+  /**
+   * Cleanup all behaviors (called on workflow end)
+   */
+  cleanup(): void {
+    debug('[BehaviorManager] Cleaning up all behaviors');
+    for (const behavior of this.behaviors.values()) {
+      behavior.cleanup?.();
+    }
+    this.behaviors.clear();
+  }
+}

src/workflows/behaviors/manager/types.ts

@@ -0,0 +1,93 @@
+/**
+ * Behavior Manager Types
+ *
+ * Core interfaces for the behavior system.
+ */
+
+import type { WorkflowEventEmitter } from '../../events/emitter.js';
+import type { StateMachine } from '../../state/index.js';
+
+/**
+ * Supported behavior types
+ */
+export type BehaviorType = 'pause' | 'skip' | 'stop' | 'mode-change';
+
+/**
+ * Current step context - set by runner before each step
+ */
+export interface StepContext {
+  stepIndex: number;
+  agentId: string;
+  agentName: string;
+}
+
+/**
+ * Context passed to behaviors during initialization
+ */
+export interface BehaviorInitContext {
+  getAbortController: () => AbortController | null;
+  getStepContext: () => StepContext | null;
+  emitter: WorkflowEventEmitter;
+  machine: StateMachine;
+  cwd: string;
+  cmRoot: string;
+}
+
+/**
+ * Context passed to behaviors when handling events
+ */
+export interface BehaviorContext {
+  cwd: string;
+  cmRoot: string;
+  stepIndex: number;
+  agentId: string;
+  agentName: string;
+  abortController: AbortController | null;
+  emitter: WorkflowEventEmitter;
+  machine: StateMachine;
+}
+
+/**
+ * Result returned from behavior handlers
+ */
+export interface BehaviorResult {
+  handled: boolean;
+  action?: 'pause' | 'skip' | 'stop' | 'continue';
+  reason?: string;
+}
+
+/**
+ * Behavior interface - all behaviors must implement this
+ */
+export interface Behavior {
+  /** Unique name for this behavior */
+  readonly name: BehaviorType;
+
+  /** Initialize behavior (setup listeners, etc.) */
+  init?(context: BehaviorInitContext): void;
+
+  /** Check if behavior is active/triggered */
+  isActive?(): boolean;
+
+  /** Trigger/request the behavior */
+  trigger?(): void;
+
+  /** Handle the behavior event */
+  handle(context: BehaviorContext): Promise<BehaviorResult>;
+
+  /** Reset behavior state (called at step start) */
+  reset?(): void;
+
+  /** Cleanup resources (called on workflow end) */
+  cleanup?(): void;
+}
+
+/**
+ * Options for creating a BehaviorManager
+ */
+export interface BehaviorManagerOptions {
+  emitter: WorkflowEventEmitter;
+  machine: StateMachine;
+  cwd: string;
+  cmRoot: string;
+}

src/workflows/behaviors/pause/evaluator.ts

@@ -0,0 +1,36 @@
+/**
+ * Pause Behavior Evaluator
+ *
+ * Evaluates whether a pause should occur based on:
+ * - User keypress (pauseRequested flag)
+ * - Agent writing { action: 'pause' } to behavior.json
+ */
+
+import { readBehaviorFile } from '../reader.js';
+import type { PauseDecision, PauseEvaluationOptions } from './types.js';
+
+/**
+ * Evaluate if pause behavior should trigger
+ */
+export async function evaluatePauseBehavior(
+  options: PauseEvaluationOptions
+): Promise<PauseDecision | null> {
+  const { cwd, pauseRequested } = options;
+
+  // Check user keypress first (higher priority)
+  if (pauseRequested) {
+    return { shouldPause: true, source: 'user' };
+  }
+
+  // Check agent-written behavior.json
+  const behaviorAction = await readBehaviorFile(cwd);
+  if (behaviorAction?.action === 'pause') {
+    return {
+      shouldPause: true,
+      reason: behaviorAction.reason,
+      source: 'agent',
+    };
+  }
+
+  return null;
+}

src/workflows/behaviors/pause/handler.ts

@@ -0,0 +1,85 @@
+/**
+ * Pause Behavior Handler
+ *
+ * Implements the Behavior interface for pause functionality.
+ * The listener handles everything - log, state machine, abort.
+ */
+
+import { debug } from '../../../shared/logging/logger.js';
+import type {
+  Behavior,
+  BehaviorContext,
+  BehaviorResult,
+  BehaviorInitContext,
+} from '../manager/types.js';
+import { createPauseListener } from './listener.js';
+
+/**
+ * PauseBehavior - handles workflow pause events
+ *
+ * When user presses 'p', the listener handles everything:
+ * - Logs message to emitter
+ * - Sends PAUSE to state machine
+ * - Aborts current execution
+ *
+ * Runner just catches AbortError and returns.
+ */
+export class PauseBehavior implements Behavior {
+  readonly name = 'pause' as const;
+  private cleanupFn: (() => void) | null = null;
+
+  /**
+   * Initialize behavior - setup event listener that handles everything
+   */
+  init(context: BehaviorInitContext): void {
+    debug('[PauseBehavior] Initializing');
+
+    this.cleanupFn = createPauseListener({
+      getAbortController: context.getAbortController,
+      getStepContext: context.getStepContext,
+      emitter: context.emitter,
+      machine: context.machine,
+    });
+  }
+
+  /**
+   * Check if behavior is active (not used in new architecture)
+   */
+  isActive(): boolean {
+    return false; // Listener handles everything, no need to check
+  }
+
+  /**
+   * Trigger pause (for programmatic pause via runner.pause())
+   */
+  trigger(): void {
+    // Emit the event, listener will handle it
+    process.emit('workflow:pause' as any);
+  }
+
+  /**
+   * Reset behavior state (called at step start)
+   */
+  reset(): void {
+    // Nothing to reset - listener handles everything immediately
+  }
+
+  /**
+   * Cleanup resources
+   */
+  cleanup(): void {
+    debug('[PauseBehavior] Cleaning up');
+    this.cleanupFn?.();
+    this.cleanupFn = null;
+  }
+
+  /**
+   * Handle pause behavior (legacy - not called in new architecture)
+   * Kept for interface compliance
+   */
+  async handle(_context: BehaviorContext): Promise<BehaviorResult> {
+    // In new architecture, listener handles everything
+    // This is only here for interface compliance
+    return { handled: true, action: 'pause' };
+  }
+}