Auto-Flow Intelligence System

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service Files: backend/src/services/autoFlow.service.ts, backend/src/services/autoFlowTriggers.service.ts, backend/src/services/autoExecutionConfig.service.ts, backend/src/services/flowMonitor.service.ts, backend/src/services/flowContext.service.ts, backend/src/services/flowSummarization.service.ts

---

Overview

The Auto-Flow Intelligence System provides proactive workflow monitoring, automatic suggestion generation, and safe auto-execution of actions. It reduces manual intervention by intelligently detecting when users need to run orchestrators, approve transitions, or view artifacts, and can automatically execute safe actions based on configurable policies.

---

Architecture

Auto-Flow System Flow

---

Core Components

1. Auto-Flow Service

File: backend/src/services/autoFlow.service.ts

Class: AutoFlowService

Key Functions:

monitorAndAutoExecute(instanceId, config)

• Monitors workflow state
• Checks for auto-executable actions
• Executes safe actions automatically
• Prevents execution loops
• Returns execution results

generateNextSuggestions(instanceId)

• Analyzes workflow context
• Generates context-aware suggestions
• Prioritizes suggestions
• Returns actionable suggestions

executeAction(action, context, config)

• Executes action automatically
• Uses client-agnostic action executor
• Generates follow-up suggestions
• Logs execution for audit trail

getFlowContext(instanceId, contextId)

• Retrieves workflow context
• Includes task status, artifacts, transitions
• Client-agnostic (uses contextId)
• Cached for performance

2. Auto-Flow Triggers

File: backend/src/services/autoFlowTriggers.service.ts

Class: AutoFlowTriggers

Event Handlers:

onTaskCompleted(taskId)

• Triggered when task completes
• Checks if orchestrator should auto-run
• Generates next suggestions
• Stores suggestions for user

onArtifactCreated(artifactId)

• Triggered when artifact created
• Suggests viewing artifacts
• Suggests state transition if ready

onGuardSatisfied(instanceId, guard)

• Triggered when guard satisfied
• Auto-transitions if configured
• Generates next suggestions

onStateTransitioned(instanceId, from, to)

• Triggered on state transition
• Clears old suggestions
• Generates new suggestions for new state

3. Flow Monitor Service

File: backend/src/services/flowMonitor.service.ts

Class: FlowMonitorService

Key Functions:

startMonitoring(config)

• Starts periodic monitoring
• Checks all active instances
• Detects stuck workflows
• Suggests recovery actions

monitorInstance(instanceId, config)

• Monitors single instance
• Checks if stuck
• Checks unreviewed artifacts
• Generates smart suggestions

checkIfStuck(instance, context, config)

• Detects stuck workflows
• Checks task status
• Checks transition availability
• Returns stuck status and reason

4. Flow Context Service

File: backend/src/services/flowContext.service.ts

Class: FlowContextService

Key Functions:

getFlowContext(instanceId)

• Retrieves workflow context
• Caches for performance (30s TTL)
• Client-agnostic (uses contextId)
• Returns FlowContext object

invalidateCache(instanceId)

• Invalidates cached context
• Called after state changes
• Ensures fresh context

5. Flow Summarization Service

File: backend/src/services/flowSummarization.service.ts

Key Functions:

getFlowSummary(contextId)

• Retrieves flow summary
• Tracks phases, errors, navigation
• Returns FlowSummaryData

updateFlowSummary(contextId)

• Updates summary with current state
• Tracks phase entries/exits
• Records navigation

recordFlowError(contextId, error, phase)

• Records errors in summary
• Stores return points
• Enables error recovery

6. Auto-Execution Config Service

File: backend/src/services/autoExecutionConfig.service.ts

Key Functions:

getAutoExecutionConfig(contextId)

• Retrieves auto-execution config
• Returns default if not set
• Client-agnostic

setAutoExecutionConfig(contextId, config, userId)

• Sets auto-execution config
• Stores in context config metadata
• Supports per-context configuration

---

Auto-Execution Configuration

Configuration Options

Type: AutoExecutionConfig

Fields:

• autoRunOrchestrator - Auto-run orchestrator when tasks pending
• autoTransitionOnGuard - Auto-transition when guards satisfied
• autoSuggestNextStep - Generate next step suggestions
• autoExecuteSafeActions - Execute safe actions automatically
• maxAutoExecutionsPerHour - Rate limiting

Default Configuration

{
  autoRunOrchestrator: false,
  autoTransitionOnGuard: false,
  autoSuggestNextStep: true,
  autoExecuteSafeActions: true,
  maxAutoExecutionsPerHour: 10
}

Safety Policies

Function: canAutoExecute(action, config)

Checks:

• Action type (VIEW actions always safe)
• Configuration settings
• Action metadata (requiresConfirmation, autoExecutable)
• Rate limiting

---

Flow Context

FlowContext Interface

interface FlowContext {
  instanceId: string;
  contextId?: string;        // Client-agnostic context ID
  channelId?: string;        // Backward compatibility
  userId?: number;
  currentState: string;
  protocolId?: string;
  machineId?: string;
  hasPendingTasks: boolean;
  hasCompletedTasks: boolean;
  hasArtifacts: boolean;
  availableTransitions: Array<{ target: string; guard?: string }>;
}

---

Suggestion Generation

Context-Aware Suggestions

The system generates suggestions based on:

1. Current State:

   • Intake state → Suggest breaking down tasks
   • Execution state → Suggest running orchestrator
   • Integration state → Suggest viewing artifacts

2. Task Status:

   • Pending tasks → Suggest orchestrator
   • Completed tasks → Suggest transition

3. Artifact Status:

   • Unreviewed artifacts → Suggest review
   • All reviewed → Suggest transition

4. Transition Availability:

   • Guards satisfied → Suggest transition
   • Guards not satisfied → Suggest satisfying guards

---

Data Flow

---

Integration Points

State Machine Integration

• Monitors state machine instances
• Triggers on state transitions
• Suggests transitions when guards satisfied
• Auto-executes safe transitions

Coder Orchestrator Integration

• Suggests running orchestrator
• Auto-runs orchestrator if configured
• Monitors task completion
• Suggests artifact review

Suggestion System Integration

• Uses suggestion storage (client-agnostic)
• Generates ActionSuggestion objects
• Stores suggestions for user
• Prioritizes suggestions

---

API Endpoints

Auto-Flow Management

• POST /api/auto-flow/monitor/:instanceId - Trigger monitoring
• GET /api/auto-flow/config/:contextId - Get auto-execution config
• POST /api/auto-flow/config/:contextId - Set auto-execution config
• GET /api/auto-flow/context/:instanceId - Get flow context

Flow Summary

• GET /api/flow-summary/:contextId - Get flow summary
• POST /api/flow-summary/:contextId/error - Record error
• POST /api/flow-summary/:contextId/checkpoint - Create checkpoint

---

Source Files

Primary Sources:

• backend/src/services/autoFlow.service.ts - Main auto-flow service
• backend/src/services/autoFlowTriggers.service.ts - Event triggers
• backend/src/services/autoExecutionConfig.service.ts - Configuration
• backend/src/services/flowMonitor.service.ts - Workflow monitoring
• backend/src/services/flowContext.service.ts - Context management
• backend/src/services/flowSummarization.service.ts - Flow summarization

Related Files:

• backend/src/services/suggestionCore.service.ts - Suggestion core
• backend/src/services/actionExecutor.service.ts - Action execution
• backend/src/services/stateMachineInstance.service.ts - State machine

---

Related Documentation

• State Machine System - Workflow management
• Suggestion System - Proactive suggestions
• Coder Orchestrator System - Task execution
• Context Services - Client-agnostic context
• 00-OVERVIEW.md - Complete system overview