refactor(behaviors): reorganize workflow behavior modules

moazbuilds · moazbuilds · commit ba7b46aa3018 · 2025-12-21T13:03:08.000+02:00
- Create index files for each behavior type (error, trigger, checkpoint, loop)
- Extract common behavior file reading logic into shared reader module
- Move handler logic into respective behavior modules
- Update imports to use new module structure
diff --git a/src/workflows/behaviors/checkpoint/evaluator.ts b/src/workflows/behaviors/checkpoint/evaluator.ts
@@ -1,7 +1,5 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
 import type { ModuleBehavior } from '../../templates/index.js';
-import type { BehaviorAction } from '../types.js';
+import { readBehaviorFile } from '../reader.js';
 
 export interface CheckpointEvaluationOptions {
   behavior?: ModuleBehavior;
@@ -18,22 +16,8 @@ export async function evaluateCheckpointBehavior(options: CheckpointEvaluationOp
   const { cwd } = options;
 
   // Checkpoint is universal - any agent can write checkpoint to behavior.json
-  // No need to check if step has checkpoint behavior configured
-
-  // Check for behavior file
-  const behaviorFile = path.join(cwd, '.codemachine', 'memory', 'behavior.json');
-
-  // Read and parse behavior action
-  let behaviorAction: BehaviorAction;
-  try {
-    const content = await fs.promises.readFile(behaviorFile, 'utf8');
-    behaviorAction = JSON.parse(content);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      // No file = no special behavior, continue normally
-      return null;
-    }
-    console.error(`Failed to parse behavior file: ${error instanceof Error ? error.message : String(error)}`);
+  const behaviorAction = await readBehaviorFile(cwd);
+  if (!behaviorAction) {
     return null;
   }
 
diff --git a/src/workflows/behaviors/checkpoint/handler.ts b/src/workflows/behaviors/checkpoint/handler.ts
diff --git a/src/workflows/behaviors/checkpoint/index.ts b/src/workflows/behaviors/checkpoint/index.ts
@@ -0,0 +1,8 @@
+/**
+ * Checkpoint Behavior Module
+ *
+ * Handles workflow pause/checkpoint signals for user intervention.
+ */
+
+export * from './evaluator.js';
+export * from './handler.js';
diff --git a/src/workflows/behaviors/error/evaluator.ts b/src/workflows/behaviors/error/evaluator.ts
@@ -1,6 +1,4 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import type { BehaviorAction } from '../types.js';
+import { readBehaviorFile } from '../reader.js';
 
 export interface ErrorEvaluationOptions {
   output: string;
@@ -15,20 +13,8 @@ export interface ErrorEvaluationResult {
 export async function evaluateErrorBehavior(options: ErrorEvaluationOptions): Promise<ErrorEvaluationResult | null> {
   const { cwd } = options;
 
-  // Check for behavior file
-  const behaviorFile = path.join(cwd, '.codemachine', 'memory', 'behavior.json');
-
-  // Read and parse behavior action
-  let behaviorAction: BehaviorAction;
-  try {
-    const content = await fs.promises.readFile(behaviorFile, 'utf8');
-    behaviorAction = JSON.parse(content);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      // No file = no special behavior, continue normally
-      return null;
-    }
-    console.error(`Failed to parse behavior file: ${error instanceof Error ? error.message : String(error)}`);
+  const behaviorAction = await readBehaviorFile(cwd);
+  if (!behaviorAction) {
     return null;
   }
 
diff --git a/src/workflows/behaviors/error/handler.ts b/src/workflows/behaviors/error/handler.ts
diff --git a/src/workflows/behaviors/error/index.ts b/src/workflows/behaviors/error/index.ts
@@ -0,0 +1,8 @@
+/**
+ * Error Behavior Module
+ *
+ * Handles workflow termination on error signals.
+ */
+
+export * from './evaluator.js';
+export * from './handler.js';
diff --git a/src/workflows/behaviors/index.ts b/src/workflows/behaviors/index.ts
@@ -1,8 +1,13 @@
+/**
+ * Behaviors Module
+ *
+ * Centralized exports for all workflow behavior handlers.
+ */
+
 export * from './types.js';
+export * from './reader.js';
 export * from './skip.js';
-export * from './loop/controller.js';
-export * from './loop/evaluator.js';
-export * from './trigger/controller.js';
-export * from './trigger/evaluator.js';
-export * from './checkpoint/controller.js';
-export * from './checkpoint/evaluator.js';
+export * from './loop/index.js';
+export * from './trigger/index.js';
+export * from './checkpoint/index.js';
+export * from './error/index.js';
diff --git a/src/workflows/behaviors/loop/evaluator.ts b/src/workflows/behaviors/loop/evaluator.ts
@@ -1,7 +1,5 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
 import type { ModuleBehavior } from '../../templates/index.js';
-import type { BehaviorAction } from '../types.js';
+import { readBehaviorFile } from '../reader.js';
 
 export interface LoopEvaluationOptions {
   behavior?: ModuleBehavior;
@@ -23,20 +21,8 @@ export async function evaluateLoopBehavior(options: LoopEvaluationOptions): Prom
     return null;
   }
 
-  // Check for behavior file
-  const behaviorFile = path.join(cwd, '.codemachine', 'memory', 'behavior.json');
-
-  // Read and parse behavior action
-  let behaviorAction: BehaviorAction;
-  try {
-    const content = await fs.promises.readFile(behaviorFile, 'utf8');
-    behaviorAction = JSON.parse(content);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      // No file = no special behavior, continue normally
-      return null;
-    }
-    console.error(`Failed to parse behavior file: ${error instanceof Error ? error.message : String(error)}`);
+  const behaviorAction = await readBehaviorFile(cwd);
+  if (!behaviorAction) {
     return null;
   }
 
diff --git a/src/workflows/behaviors/loop/handler.ts b/src/workflows/behaviors/loop/handler.ts
@@ -2,16 +2,11 @@ import type { WorkflowStep } from '../../templates/index.js';
 import { isModuleStep } from '../../templates/types.js';
 import { evaluateLoopBehavior } from './evaluator.js';
 import { formatAgentLog } from '../../../shared/logging/index.js';
-import type { ActiveLoop } from '../skip.js';
 import type { WorkflowEventEmitter } from '../../events/emitter.js';
 import { debug } from '../../../shared/logging/logger.js';
+import type { ActiveLoop, LoopDecision } from './types.js';
 
-export interface LoopDecision {
-  shouldRepeat: boolean;
-  stepsBack: number;
-  skipList: string[];
-  reason?: string;
-}
+export type { LoopDecision };
 
 export async function handleLoopLogic(
   step: WorkflowStep,
diff --git a/src/workflows/behaviors/loop/index.ts b/src/workflows/behaviors/loop/index.ts
@@ -0,0 +1,9 @@
+/**
+ * Loop Behavior Module
+ *
+ * Handles step-back looping logic when agents request iteration.
+ */
+
+export * from './types.js';
+export * from './evaluator.js';
+export * from './handler.js';
diff --git a/src/workflows/behaviors/loop/types.ts b/src/workflows/behaviors/loop/types.ts
@@ -0,0 +1,18 @@
+/**
+ * Loop Behavior Types
+ *
+ * Type definitions for loop behavior handling.
+ */
+
+/** Tracks which steps to skip during an active loop iteration */
+export interface ActiveLoop {
+  skip: string[];
+}
+
+/** Result of loop decision evaluation */
+export interface LoopDecision {
+  shouldRepeat: boolean;
+  stepsBack: number;
+  skipList: string[];
+  reason?: string;
+}
diff --git a/src/workflows/behaviors/reader.ts b/src/workflows/behaviors/reader.ts
@@ -0,0 +1,39 @@
+/**
+ * Behavior File Reader
+ *
+ * Centralized logic for reading behavior.json signals from agents.
+ * All behavior evaluators use this to read agent-written behavior actions.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { BehaviorAction } from './types.js';
+
+/** Path to behavior.json relative to project root */
+const BEHAVIOR_FILE_PATH = '.codemachine/memory/behavior.json';
+
+/**
+ * Reads and parses the behavior.json file from the project directory.
+ *
+ * @param cwd - Project working directory
+ * @returns Parsed BehaviorAction or null if file doesn't exist/invalid
+ */
+export async function readBehaviorFile(cwd: string): Promise<BehaviorAction | null> {
+  const behaviorFile = path.join(cwd, BEHAVIOR_FILE_PATH);
+
+  try {
+    const content = await fs.promises.readFile(behaviorFile, 'utf8');
+    return JSON.parse(content) as BehaviorAction;
+  } catch (error) {
+    // No file = no behavior signal (normal case)
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+
+    // Log parse/read errors but don't crash
+    console.error(
+      `Failed to parse behavior file: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+}
diff --git a/src/workflows/behaviors/skip.ts b/src/workflows/behaviors/skip.ts
@@ -2,10 +2,10 @@ import type { WorkflowStep } from '../templates/index.js';
 import { isModuleStep } from '../templates/types.js';
 import type { WorkflowEventEmitter } from '../events/emitter.js';
 import { debug } from '../../shared/logging/logger.js';
+import type { ActiveLoop } from './loop/types.js';
 
-export interface ActiveLoop {
-  skip: string[];
-}
+// Re-export for backwards compatibility
+export type { ActiveLoop };
 
 export function shouldSkipStep(
   step: WorkflowStep,
diff --git a/src/workflows/behaviors/trigger/evaluator.ts b/src/workflows/behaviors/trigger/evaluator.ts
@@ -1,7 +1,5 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
 import type { ModuleBehavior } from '../../templates/index.js';
-import type { BehaviorAction } from '../types.js';
+import { readBehaviorFile } from '../reader.js';
 
 export interface TriggerEvaluationOptions {
   behavior?: ModuleBehavior;
@@ -22,20 +20,8 @@ export async function evaluateTriggerBehavior(options: TriggerEvaluationOptions)
     return null;
   }
 
-  // Check for behavior file
-  const behaviorFile = path.join(cwd, '.codemachine', 'memory', 'behavior.json');
-
-  // Read and parse behavior action
-  let behaviorAction: BehaviorAction;
-  try {
-    const content = await fs.promises.readFile(behaviorFile, 'utf8');
-    behaviorAction = JSON.parse(content);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      // No file = no special behavior, continue normally
-      return null;
-    }
-    console.error(`Failed to parse behavior file: ${error instanceof Error ? error.message : String(error)}`);
+  const behaviorAction = await readBehaviorFile(cwd);
+  if (!behaviorAction) {
     return null;
   }
 
diff --git a/src/workflows/behaviors/trigger/handler.ts b/src/workflows/behaviors/trigger/handler.ts
diff --git a/src/workflows/behaviors/trigger/index.ts b/src/workflows/behaviors/trigger/index.ts
@@ -0,0 +1,8 @@
+/**
+ * Trigger Behavior Module
+ *
+ * Handles dynamic agent triggering based on behavior signals.
+ */
+
+export * from './evaluator.js';
+export * from './handler.js';
diff --git a/src/workflows/execution/post.ts b/src/workflows/execution/post.ts
@@ -1,12 +1,11 @@
 import { markStepCompleted, removeFromNotCompleted } from '../../shared/workflows/index.js';
-import { handleLoopLogic, createActiveLoop } from '../behaviors/loop/controller.js';
-import { handleTriggerLogic } from '../behaviors/trigger/controller.js';
-import { handleCheckpointLogic } from '../behaviors/checkpoint/controller.js';
-import { handleErrorLogic } from '../behaviors/error/controller.js';
+import { handleLoopLogic, createActiveLoop, type ActiveLoop } from '../behaviors/loop/index.js';
+import { handleTriggerLogic } from '../behaviors/trigger/index.js';
+import { handleCheckpointLogic } from '../behaviors/checkpoint/index.js';
+import { handleErrorLogic } from '../behaviors/error/index.js';
 import type { WorkflowEventEmitter } from '../events/index.js';
 import { type ModuleStep, type WorkflowTemplate, isModuleStep } from '../templates/types.js';
 import { executeTriggerAgent } from './trigger.js';
-import type { ActiveLoop } from '../behaviors/skip.js';
 
 interface HandlePostExecOptions {
   step: ModuleStep;
