hungry-ghost-hive 0.3.0

package/src/orchestrator/workflow.ts

@@ -0,0 +1,137 @@
+import type { Database } from 'sql.js';
+import type { StoryStatus } from '../db/queries/stories.js';
+import { queryAll, queryOne } from '../db/client.js';
+
+// Valid story status transitions
+const STORY_TRANSITIONS: Record<StoryStatus, StoryStatus[]> = {
+  draft: ['estimated'],
+  estimated: ['planned'],
+  planned: ['in_progress'],
+  in_progress: ['review', 'qa_failed'],
+  review: ['in_progress', 'qa'],
+  qa: ['qa_failed', 'pr_submitted'],
+  qa_failed: ['in_progress'],
+  pr_submitted: ['merged'],
+  merged: [],
+};
+
+export function canTransitionStory(from: StoryStatus, to: StoryStatus): boolean {
+  return STORY_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+export function getNextStatuses(status: StoryStatus): StoryStatus[] {
+  return STORY_TRANSITIONS[status] || [];
+}
+
+export type RequirementStatus = 'pending' | 'planning' | 'planned' | 'in_progress' | 'completed';
+
+const REQUIREMENT_TRANSITIONS: Record<RequirementStatus, RequirementStatus[]> = {
+  pending: ['planning'],
+  planning: ['planned'],
+  planned: ['in_progress'],
+  in_progress: ['completed'],
+  completed: [],
+};
+
+export function canTransitionRequirement(from: RequirementStatus, to: RequirementStatus): boolean {
+  return REQUIREMENT_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+// Workflow phase tracking
+export type WorkflowPhase =
+  | 'idle'
+  | 'requirement_intake'
+  | 'planning'
+  | 'estimation'
+  | 'development'
+  | 'review'
+  | 'qa'
+  | 'pr_submission'
+  | 'completed';
+
+export interface WorkflowState {
+  phase: WorkflowPhase;
+  requirementId?: string;
+  activeStories: number;
+  completedStories: number;
+  blockedStories: number;
+}
+
+export function getWorkflowState(db: Database, requirementId?: string): WorkflowState {
+  let whereClause = '';
+  const params: string[] = [];
+
+  if (requirementId) {
+    whereClause = 'WHERE requirement_id = ?';
+    params.push(requirementId);
+  }
+
+  const stories = queryAll<{ status: StoryStatus; count: number }>(db, `
+    SELECT status, COUNT(*) as count
+    FROM stories
+    ${whereClause}
+    GROUP BY status
+  `, params);
+
+  const counts: Record<string, number> = {};
+  for (const row of stories) {
+    counts[row.status] = row.count;
+  }
+
+  const activeStories =
+    (counts.in_progress || 0) +
+    (counts.review || 0) +
+    (counts.qa || 0);
+
+  const completedStories =
+    (counts.pr_submitted || 0) +
+    (counts.merged || 0);
+
+  const blockedStories = counts.qa_failed || 0;
+
+  // Determine current phase
+  let phase: WorkflowPhase = 'idle';
+
+  if (counts.merged && completedStories === Object.values(counts).reduce((a, b) => a + b, 0)) {
+    phase = 'completed';
+  } else if (counts.pr_submitted) {
+    phase = 'pr_submission';
+  } else if (counts.qa) {
+    phase = 'qa';
+  } else if (counts.review) {
+    phase = 'review';
+  } else if (counts.in_progress) {
+    phase = 'development';
+  } else if (counts.planned) {
+    phase = 'development'; // Ready to start development
+  } else if (counts.estimated) {
+    phase = 'estimation';
+  } else if (counts.draft) {
+    phase = 'planning';
+  } else if (requirementId) {
+    // Check requirement status
+    const req = queryOne<{ status: string }>(db, 'SELECT status FROM requirements WHERE id = ?', [requirementId]);
+    if (req) {
+      if (req.status === 'planning') phase = 'planning';
+      else if (req.status === 'pending') phase = 'requirement_intake';
+    }
+  }
+
+  return {
+    phase,
+    requirementId,
+    activeStories,
+    completedStories,
+    blockedStories,
+  };
+}
+
+export function isWorkflowBlocked(state: WorkflowState): boolean {
+  return state.blockedStories > 0;
+}
+
+export function getWorkflowProgress(state: WorkflowState): number {
+  const total = state.activeStories + state.completedStories + state.blockedStories;
+  if (total === 0) return 0;
+  return Math.round((state.completedStories / total) * 100);
+}

package/src/state-detectors/claude.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest';
+import { ClaudeStateDetector } from './claude.js';
+import { AgentState } from './types.js';
+
+describe('ClaudeStateDetector', () => {
+  const detector = new ClaudeStateDetector();
+
+  describe('detectState', () => {
+    it('should detect THINKING state', () => {
+      const result = detector.detectState('(thinking) about the problem');
+      expect(result.state).toBe(AgentState.THINKING);
+      expect(result.confidence).toBe(0.9);
+      expect(result.isWaiting).toBe(false);
+      expect(result.needsHuman).toBe(false);
+    });
+
+    it('should detect THINKING state with action words', () => {
+      const result = detector.detectState('Analyzing the code structure...');
+      expect(result.state).toBe(AgentState.THINKING);
+    });
+
+    it('should detect TOOL_RUNNING state', () => {
+      const result = detector.detectState('Running tests... (esc to interrupt)');
+      expect(result.state).toBe(AgentState.TOOL_RUNNING);
+      expect(result.isWaiting).toBe(false);
+      expect(result.needsHuman).toBe(false);
+    });
+
+    it('should detect TOOL_RUNNING with progress bar', () => {
+      const result = detector.detectState('[=====>    ] 50%');
+      expect(result.state).toBe(AgentState.TOOL_RUNNING);
+    });
+
+    it('should detect PROCESSING state', () => {
+      const result = detector.detectState('Processing your request...');
+      expect(result.state).toBe(AgentState.PROCESSING);
+      expect(result.isWaiting).toBe(false);
+    });
+
+    it('should detect AWAITING_SELECTION state', () => {
+      const result = detector.detectState('Enter to select ↑/↓ to navigate');
+      expect(result.state).toBe(AgentState.AWAITING_SELECTION);
+      expect(result.isWaiting).toBe(true);
+      expect(result.needsHuman).toBe(true);
+    });
+
+    it('should detect ASKING_QUESTION state', () => {
+      const result = detector.detectState('Would you like to continue?');
+      expect(result.state).toBe(AgentState.ASKING_QUESTION);
+      expect(result.needsHuman).toBe(true);
+    });
+
+    it('should detect ASKING_QUESTION with question mark', () => {
+      const result = detector.detectState('Should I proceed with this change?');
+      expect(result.state).toBe(AgentState.ASKING_QUESTION);
+    });
+
+    it('should detect PLAN_APPROVAL state', () => {
+      const result = detector.detectState('Please review the plan and approve');
+      expect(result.state).toBe(AgentState.PLAN_APPROVAL);
+      expect(result.needsHuman).toBe(true);
+    });
+
+    it('should detect PERMISSION_REQUIRED state', () => {
+      const result = detector.detectState('Permission required: Allow access [y/n]');
+      expect(result.state).toBe(AgentState.PERMISSION_REQUIRED);
+      expect(result.needsHuman).toBe(true);
+    });
+
+    it('should detect USER_DECLINED state', () => {
+      const result = detector.detectState('User declined the operation');
+      expect(result.state).toBe(AgentState.USER_DECLINED);
+      expect(result.needsHuman).toBe(true);
+    });
+
+    it('should detect WORK_COMPLETE state', () => {
+      const result = detector.detectState('Task completed successfully');
+      expect(result.state).toBe(AgentState.WORK_COMPLETE);
+      expect(result.isWaiting).toBe(true);
+      expect(result.needsHuman).toBe(false);
+    });
+
+    it('should detect IDLE_AT_PROMPT state', () => {
+      const result = detector.detectState('>\n');
+      expect(result.state).toBe(AgentState.IDLE_AT_PROMPT);
+      expect(result.isWaiting).toBe(true);
+      expect(result.needsHuman).toBe(false);
+    });
+
+    it('should return UNKNOWN for unclear output', () => {
+      const result = detector.detectState('Some random text');
+      expect(result.state).toBe(AgentState.UNKNOWN);
+      expect(result.confidence).toBe(0.3);
+    });
+
+    it('should prioritize higher priority patterns', () => {
+      // TOOL_RUNNING (priority 100) should win over PROCESSING (priority 90)
+      const result = detector.detectState('Executing and Processing');
+      expect(result.state).toBe(AgentState.TOOL_RUNNING);
+    });
+  });
+
+  describe('getStateDescription', () => {
+    it('should return description for THINKING', () => {
+      const desc = detector.getStateDescription(AgentState.THINKING);
+      expect(desc).toBe('Claude is thinking');
+    });
+
+    it('should return description for PERMISSION_REQUIRED', () => {
+      const desc = detector.getStateDescription(AgentState.PERMISSION_REQUIRED);
+      expect(desc).toBe('Permission required');
+    });
+
+    it('should return description for UNKNOWN', () => {
+      const desc = detector.getStateDescription(AgentState.UNKNOWN);
+      expect(desc).toBe('Unknown state');
+    });
+  });
+
+  describe('isActiveState', () => {
+    it('should return true for active states', () => {
+      expect(detector.isActiveState(AgentState.THINKING)).toBe(true);
+      expect(detector.isActiveState(AgentState.TOOL_RUNNING)).toBe(true);
+      expect(detector.isActiveState(AgentState.PROCESSING)).toBe(true);
+    });
+
+    it('should return false for non-active states', () => {
+      expect(detector.isActiveState(AgentState.IDLE_AT_PROMPT)).toBe(false);
+      expect(detector.isActiveState(AgentState.ASKING_QUESTION)).toBe(false);
+      expect(detector.isActiveState(AgentState.UNKNOWN)).toBe(false);
+    });
+  });
+
+  describe('isBlockedState', () => {
+    it('should return true for blocked states', () => {
+      expect(detector.isBlockedState(AgentState.ASKING_QUESTION)).toBe(true);
+      expect(detector.isBlockedState(AgentState.AWAITING_SELECTION)).toBe(true);
+      expect(detector.isBlockedState(AgentState.PLAN_APPROVAL)).toBe(true);
+      expect(detector.isBlockedState(AgentState.PERMISSION_REQUIRED)).toBe(true);
+      expect(detector.isBlockedState(AgentState.USER_DECLINED)).toBe(true);
+    });
+
+    it('should return false for non-blocked states', () => {
+      expect(detector.isBlockedState(AgentState.THINKING)).toBe(false);
+      expect(detector.isBlockedState(AgentState.IDLE_AT_PROMPT)).toBe(false);
+      expect(detector.isBlockedState(AgentState.WORK_COMPLETE)).toBe(false);
+    });
+  });
+});

package/src/state-detectors/claude.ts

@@ -0,0 +1,256 @@
+/**
+ * Claude Code State Detector
+ *
+ * Detects the UI state of Claude Code CLI based on output patterns
+ * Refactored from src/utils/claude-code-state.ts
+ */
+
+import { AgentState, StateDetectionResult, StateDetector } from './types.js';
+
+interface StateIndicator {
+  state: AgentState;
+  patterns: RegExp[];
+  priority: number;
+}
+
+/**
+ * Priority-based state indicators for Claude Code
+ * Higher priority patterns are checked first to handle overlapping indicators
+ */
+const CLAUDE_STATE_INDICATORS: StateIndicator[] = [
+  // High priority: Active work states
+  {
+    state: AgentState.THINKING,
+    patterns: [
+      /\(thinking\)/i,
+      /Concocting|Twisting|Considering|Analyzing/i,
+    ],
+    priority: 100,
+  },
+  {
+    state: AgentState.TOOL_RUNNING,
+    patterns: [
+      /esc to interrupt/i,
+      /Running|Executing/i,
+      /\[.*\]\s+\d+%/i, // Progress bars
+    ],
+    priority: 100,
+  },
+  {
+    state: AgentState.PROCESSING,
+    patterns: [
+      /Processing|Analyzing|Generating/i,
+      /Please wait/i,
+    ],
+    priority: 90,
+  },
+
+  // High priority: Blocked states requiring human intervention
+  {
+    state: AgentState.AWAITING_SELECTION,
+    patterns: [
+      /Enter to select.*↑\/↓/i,
+      /Use arrows to navigate/i,
+      /Select an option/i,
+    ],
+    priority: 90,
+  },
+  {
+    state: AgentState.ASKING_QUESTION,
+    patterns: [
+      /\?\s*$/m, // Line ending with question mark
+      /Please (choose|select|confirm)/i,
+      /Would you like to/i,
+      /Do you want to/i,
+    ],
+    priority: 85,
+  },
+  {
+    state: AgentState.PLAN_APPROVAL,
+    patterns: [
+      /approve.*plan/i,
+      /review.*plan/i,
+      /proceed.*plan/i,
+      /ExitPlanMode/i,
+    ],
+    priority: 90,
+  },
+  {
+    state: AgentState.PERMISSION_REQUIRED,
+    patterns: [
+      /permission.*required/i,
+      /authorize/i,
+      /Allow.*\[y\/n\]/i,
+      /Approve.*\[y\/n\]/i,
+    ],
+    priority: 90,
+  },
+  {
+    state: AgentState.USER_DECLINED,
+    patterns: [
+      /declined/i,
+      /permission denied/i,
+      /User chose not to/i,
+    ],
+    priority: 85,
+  },
+
+  // Lower priority: Ready/idle states
+  {
+    state: AgentState.WORK_COMPLETE,
+    patterns: [
+      /done|complete|finished/i,
+      /successfully/i,
+      /All.*tests passed/i,
+    ],
+    priority: 50,
+  },
+  {
+    state: AgentState.IDLE_AT_PROMPT,
+    patterns: [
+      /^>\s*$/m, // Prompt alone on line
+      /Ready for input/i,
+      /What would you like/i,
+    ],
+    priority: 40,
+  },
+];
+
+/**
+ * Claude Code State Detector Implementation
+ */
+export class ClaudeStateDetector implements StateDetector {
+  /**
+   * Detect the current Claude Code UI state from output text
+   */
+  detectState(output: string): StateDetectionResult {
+    // Sort indicators by priority (highest first)
+    const sortedIndicators = [...CLAUDE_STATE_INDICATORS].sort((a, b) => b.priority - a.priority);
+
+    // Check each indicator in priority order
+    for (const indicator of sortedIndicators) {
+      for (const pattern of indicator.patterns) {
+        if (pattern.test(output)) {
+          const result = this.mapStateToWaitingStatus(indicator.state);
+          return {
+            ...result,
+            confidence: 0.9,
+            reason: `Detected pattern for ${indicator.state}`,
+          };
+        }
+      }
+    }
+
+    // No clear state detected
+    return {
+      state: AgentState.UNKNOWN,
+      confidence: 0.3,
+      reason: 'No clear state indicators found',
+      isWaiting: false,
+      needsHuman: false,
+    };
+  }
+
+  /**
+   * Get a human-readable description of a state
+   */
+  getStateDescription(state: AgentState): string {
+    switch (state) {
+      case AgentState.THINKING:
+        return 'Claude is thinking';
+      case AgentState.TOOL_RUNNING:
+        return 'A tool is running';
+      case AgentState.PROCESSING:
+        return 'Processing request';
+      case AgentState.IDLE_AT_PROMPT:
+        return 'Idle at prompt';
+      case AgentState.WORK_COMPLETE:
+        return 'Work completed';
+      case AgentState.ASKING_QUESTION:
+        return 'Asking a question - needs response';
+      case AgentState.AWAITING_SELECTION:
+        return 'Awaiting user selection';
+      case AgentState.PLAN_APPROVAL:
+        return 'Waiting for plan approval';
+      case AgentState.PERMISSION_REQUIRED:
+        return 'Permission required';
+      case AgentState.USER_DECLINED:
+        return 'User declined - blocked';
+      case AgentState.UNKNOWN:
+        return 'Unknown state';
+      default:
+        return 'Unknown';
+    }
+  }
+
+  /**
+   * Check if a state represents active work (not waiting)
+   */
+  isActiveState(state: AgentState): boolean {
+    return [
+      AgentState.THINKING,
+      AgentState.TOOL_RUNNING,
+      AgentState.PROCESSING,
+    ].includes(state);
+  }
+
+  /**
+   * Check if a state requires human intervention
+   */
+  isBlockedState(state: AgentState): boolean {
+    return [
+      AgentState.ASKING_QUESTION,
+      AgentState.AWAITING_SELECTION,
+      AgentState.PLAN_APPROVAL,
+      AgentState.PERMISSION_REQUIRED,
+      AgentState.USER_DECLINED,
+    ].includes(state);
+  }
+
+  /**
+   * Map a state to waiting status flags
+   */
+  private mapStateToWaitingStatus(state: AgentState): Omit<StateDetectionResult, 'confidence' | 'reason'> {
+    switch (state) {
+      // Active states - not waiting
+      case AgentState.THINKING:
+      case AgentState.TOOL_RUNNING:
+      case AgentState.PROCESSING:
+        return {
+          state,
+          isWaiting: false,
+          needsHuman: false,
+        };
+
+      // Idle states - waiting but not blocked
+      case AgentState.IDLE_AT_PROMPT:
+      case AgentState.WORK_COMPLETE:
+        return {
+          state,
+          isWaiting: true,
+          needsHuman: false,
+        };
+
+      // Blocked states - waiting and needs human
+      case AgentState.ASKING_QUESTION:
+      case AgentState.AWAITING_SELECTION:
+      case AgentState.PLAN_APPROVAL:
+      case AgentState.PERMISSION_REQUIRED:
+      case AgentState.USER_DECLINED:
+        return {
+          state,
+          isWaiting: true,
+          needsHuman: true,
+        };
+
+      // Unknown state - assume not waiting
+      case AgentState.UNKNOWN:
+      default:
+        return {
+          state,
+          isWaiting: false,
+          needsHuman: false,
+        };
+    }
+  }
+}

package/src/state-detectors/codex.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { CodexStateDetector } from './codex.js';
+import { AgentState } from './types.js';
+
+describe('CodexStateDetector', () => {
+  const detector = new CodexStateDetector();
+
+  describe('detectState', () => {
+    it('should detect THINKING state', () => {
+      const result = detector.detectState('thinking...');
+      expect(result.state).toBe(AgentState.THINKING);
+      expect(result.confidence).toBe(0.85);
+    });
+
+    it('should detect TOOL_RUNNING state', () => {
+      const result = detector.detectState('Executing command...');
+      expect(result.state).toBe(AgentState.TOOL_RUNNING);
+      expect(result.isWaiting).toBe(false);
+    });
+
+    it('should detect TOOL_RUNNING with progress', () => {
+      const result = detector.detectState('50% complete');
+      expect(result.state).toBe(AgentState.TOOL_RUNNING);
+    });
+
+    it('should detect PROCESSING state', () => {
+      const result = detector.detectState('Processing your request...');
+      expect(result.state).toBe(AgentState.PROCESSING);
+    });
+
+    it('should detect AWAITING_SELECTION state', () => {
+      const result = detector.detectState('Select an option: [1] Option A [2] Option B');
+      expect(result.state).toBe(AgentState.AWAITING_SELECTION);
+      expect(result.needsHuman).toBe(true);
+    });
+
+    it('should detect ASKING_QUESTION state', () => {
+      const result = detector.detectState('Do you want to continue?');
+      expect(result.state).toBe(AgentState.ASKING_QUESTION);
+      expect(result.needsHuman).toBe(true);
+    });
+
+    it('should detect PERMISSION_REQUIRED state', () => {
+      const result = detector.detectState('Permission required [y/n]');
+      expect(result.state).toBe(AgentState.PERMISSION_REQUIRED);
+    });
+
+    it('should detect USER_DECLINED state', () => {
+      const result = detector.detectState('Operation cancelled by user');
+      expect(result.state).toBe(AgentState.USER_DECLINED);
+    });
+
+    it('should detect WORK_COMPLETE state', () => {
+      const result = detector.detectState('Successfully completed the task');
+      expect(result.state).toBe(AgentState.WORK_COMPLETE);
+      expect(result.isWaiting).toBe(true);
+      expect(result.needsHuman).toBe(false);
+    });
+
+    it('should detect IDLE_AT_PROMPT state', () => {
+      const result = detector.detectState('codex> ');
+      expect(result.state).toBe(AgentState.IDLE_AT_PROMPT);
+    });
+
+    it('should return UNKNOWN for unclear output', () => {
+      const result = detector.detectState('Random output text');
+      expect(result.state).toBe(AgentState.UNKNOWN);
+      expect(result.confidence).toBe(0.3);
+    });
+  });
+
+  describe('getStateDescription', () => {
+    it('should return Codex-specific description for THINKING', () => {
+      const desc = detector.getStateDescription(AgentState.THINKING);
+      expect(desc).toBe('Codex is thinking');
+    });
+
+    it('should return description for TOOL_RUNNING', () => {
+      const desc = detector.getStateDescription(AgentState.TOOL_RUNNING);
+      expect(desc).toBe('Running command');
+    });
+  });
+
+  describe('isActiveState', () => {
+    it('should identify active states correctly', () => {
+      expect(detector.isActiveState(AgentState.THINKING)).toBe(true);
+      expect(detector.isActiveState(AgentState.TOOL_RUNNING)).toBe(true);
+      expect(detector.isActiveState(AgentState.PROCESSING)).toBe(true);
+      expect(detector.isActiveState(AgentState.IDLE_AT_PROMPT)).toBe(false);
+    });
+  });
+
+  describe('isBlockedState', () => {
+    it('should identify blocked states correctly', () => {
+      expect(detector.isBlockedState(AgentState.ASKING_QUESTION)).toBe(true);
+      expect(detector.isBlockedState(AgentState.PERMISSION_REQUIRED)).toBe(true);
+      expect(detector.isBlockedState(AgentState.THINKING)).toBe(false);
+    });
+  });
+});