Classes

ApprovalHandler

Approval Handler Determines whether to auto-approve or require manual review

Constructor

constructor(config: AgentConfig)

Parameters:

Methods

shouldAutoApprove

Check if a phase should be auto-approved

shouldAutoApprove(phase: ApprovalPhase): boolean

Parameters:

Returns:

boolean -

requiresManualApproval

Check if a phase requires manual approval

requiresManualApproval(phase: ApprovalPhase): boolean

Parameters:

Returns:

boolean -

makeDecision

Make approval decision for a phase

makeDecision(phase: ApprovalPhase, _documentContent: string): Promise<ApprovalDecision>

Parameters:

Returns:

Promise<ApprovalDecision> -

waitForApproval

Wait for manual approval Returns a promise that resolves when approval is received

waitForApproval(_approvalId: string, pollIntervalMs?: number): Promise<boolean>

Parameters:

Returns:

Promise<boolean> -

logDecision

Log approval decision

logDecision(decision: ApprovalDecision): void

Parameters:

AutonomousAgent

Autonomous Agent Orchestrates complete spec workflow execution without human intervention

Constructor

constructor(config: AgentConfig)

Parameters:

Methods

initialize

Initialize the agent

initialize(): Promise<void>

Returns:

Promise<void> -

executeSpec

Start autonomous execution of a spec workflow

executeSpec(specName: string, description: string): Promise<void>

Parameters:

Returns:

Promise<void> -

getContext

Get current execution context

getContext(): AgentExecutionContext | undefined

Returns:

AgentExecutionContext \| undefined -

pause

Pause agent execution

pause(): Promise<void>

Returns:

Promise<void> -

resume

Resume agent execution

resume(): Promise<void>

Returns:

Promise<void> -

stop

Stop agent and cleanup

stop(): Promise<void>

Returns:

Promise<void> -

getStatus

Get agent status

getStatus(): { agentId: string; agentName: string; connected: boolean; context?: AgentExecutionContext; }

Returns:

{ agentId: string; agentName: string; connected: boolean; context?: AgentExecutionContext; } -

ClaudeAgentSDK

Claude Agent SDK Wrapper

Provides a simplified interface to execute tasks using Claude Agent SDK with full autonomy and Epic Flow context.

Constructor

constructor(config: ClaudeAgentConfig)

Parameters:

Methods

executeTask

Execute a task using Claude Agent SDK

Runs the task with full autonomy (bypassPermissions mode) and streams the results. The agent has complete access to the file system and can execute any commands needed.

executeTask(codebase: CodebaseModel | undefined, task: TaskModel): Promise<AgentExecutionResult>

Parameters:

Returns:

Promise<AgentExecutionResult> - Execution result with success status and details

Examples:

const sdk = new ClaudeAgentSDK({ apiKey: process.env.ANTHROPIC_API_KEY });
const result = await sdk.executeTask(codebase, task);
if (result.success) {
  console.log('Task completed:', result.message);
} else {
  console.error('Task failed:', result.error);
}

getConfig

Get current configuration

getConfig(): Readonly<Required<ClaudeAgentConfig>>

Returns:

Readonly<Required<ClaudeAgentConfig>> -

ConversationCompressor

Service for compressing conversation turns using summarization

Current implementation uses rule-based summarization for speed and cost efficiency. Future enhancement: Can be upgraded to use Claude Haiku for smarter summarization.

Methods

compressTurns

Compress turns into a summary

Current implementation: Rule-based summarization that extracts:

• User requests and requirements
• Assistant actions and outcomes
• Tools used and files modified
• Key decisions and findings

Future: Can call Claude Haiku API for smarter summarization

compressTurns(turns: ConversationTurn[]): Promise<string>

Parameters:

Returns:

Promise<string> - Summary text

ConversationManager

Manages conversation history using Discussion documents

Strategy:

• Stores each turn as a separate Discussion document
• Links turns to tasks via entityType='task' and entityId=taskId
• Keeps last N turns verbatim (high fidelity for recent context)
• Compresses older turns into summary Discussion documents
• Supports conversation resumption across worker instances
• Enables agent hand-offs with portable context

Constructor

constructor(discussionManager: DiscussionManager, taskId: string, config?: Partial<ConversationConfig> | undefined)

Parameters:

Methods

addTurn

Add a new turn to the conversation

Creates a Discussion document for the turn.

addTurn(role: "user" | "assistant" | "system", content: string, metadata?: TurnMetadata | undefined): Promise<DiscussionModel>

Parameters:

Returns:

Promise<DiscussionModel> - The created Discussion document

getConversation

Get all conversation turns for the task

getConversation(): Promise<DiscussionModel[]>

Returns:

Promise<DiscussionModel[]> - Array of Discussion documents representing the conversation

shouldCompress

Check if compression should be triggered

Compression is triggered when:

• Compression is enabled in config
• Total verbatim turns exceed compression threshold
• We have more verbatim turns than we should keep

shouldCompress(): Promise<boolean>

Returns:

Promise<boolean> - True if compression should be performed

compressConversation

Compress older conversation turns

Strategy:

• Keep last N turns verbatim
• Compress everything before that into a summary Discussion document
• Soft delete the compressed turns (keep for audit trail)

compressConversation(compressor: (turns: DiscussionModel[]) => Promise<string>): Promise<void>

Parameters:

Returns:

Promise<void> -

buildContextPrompt

Build context prompt for Claude from Discussion documents

Constructs a formatted prompt that includes:

• Compressed history summaries (if present)
• Recent turns verbatim
• Metadata annotations for tool use and file modifications

buildContextPrompt(): Promise<string>

Returns:

Promise<string> - Formatted context prompt for Claude

getStats

Get conversation statistics

getStats(): Promise<{ totalTurns: number; verbatimTurns: number; compressedTurns: number; hasCompression: boolean; totalTokens: number; totalCost: number; }>

Returns:

Promise<{ totalTurns: number; verbatimTurns: number; compressedTurns: number; hasCompression: boolean; totalTokens: number; totalCost: number; }> - Statistics object

FileSystemLogger

FileSystem Logger

Provides structured logging to filesystem for task execution audit trail.

Constructor

constructor(config: FileSystemLoggerConfig)

Parameters:

Methods

initialize

Initialize directory structure for task logging

Creates the following directories:

• logs/ - Execution logs
• conversation/ - Conversation history
• files/ - File changes
• revisions/ - Task revision history

initialize(task?: TaskModel | undefined): void

Parameters:

writeTaskMetadata

Write task metadata to task.json

writeTaskMetadata(task: TaskModel): void

Parameters:

logTaskRevision

Log task revision

Saves a snapshot of the task document to track changes over time. Creates a timestamped file in revisions/ directory.

logTaskRevision(task: TaskModel, changeDescription: string): void

Parameters:

log

Write a log entry

log(level: LogLevel, message: string, context?: Record<string, any> | undefined, error?: Error | undefined): void

Parameters:

debug

Log debug message

debug(message: string, context?: Record<string, any> | undefined): void

Parameters:

info

Log info message

info(message: string, context?: Record<string, any> | undefined): void

Parameters:

warn

Log warning message

warn(message: string, context?: Record<string, any> | undefined): void

Parameters:

error

Log error message

error(message: string, context?: Record<string, any> | undefined, error?: Error | undefined): void

Parameters:

logConversation

Write a conversation turn

logConversation(role: "user" | "assistant", content: string, metadata?: Record<string, any> | undefined): void

Parameters:

logFileChange

Log file change

logFileChange(filePath: string, changeType: "created" | "modified" | "deleted", content?: string | undefined, metadata?: Record<string, any> | undefined): void

Parameters:

writeExecutionSummary

Write execution summary

Creates a markdown summary of the task execution.

writeExecutionSummary(summary: { success: boolean; duration: number; message: string; filesModified?: string[]; commandsExecuted?: string[]; conversationTurns?: number; tokenUsage?: { input: number; output: number; total: number; }; cost?: number; }): void

Parameters:

getPaths

Get log directory paths

getPaths(): { taskLogDir: string; logsDir: string; conversationDir: string; filesDir: string; revisionsDir: string; }

Returns:

{ taskLogDir: string; logsDir: string; conversationDir: string; filesDir: string; revisionsDir: string; } -

GitWorktreeManager

Git Worktree Manager

Manages git worktrees for efficient parallel task execution.

Constructor

constructor(config?: WorktreeConfig)

Parameters:

Methods

initialize

Initialize the worktree manager

Creates the base directory structure for repositories and worktrees.

initialize(): Promise<void>

Returns:

Promise<void> -

getWorktree

Get or create a worktree for a task

This method will:

1. Ensure the bare repository exists (clone if needed)
2. Create a worktree with the appropriate branch name
3. Checkout the default branch and create the feature branch
4. Return the worktree path

getWorktree(codebase: CodebaseModel, task: TaskModel): Promise<WorktreeInfo>

Parameters:

Returns:

Promise<WorktreeInfo> - Worktree information with path

releaseWorktree

Release a worktree

Removes the worktree and cleans up associated resources.

releaseWorktree(worktreeId: string): Promise<void>

Parameters:

Returns:

Promise<void> -

cleanupStaleWorktrees

Cleanup stale worktrees

Removes worktrees that are older than the specified age or have been inactive for a long time.

cleanupStaleWorktrees(maxAgeMs?: number): Promise<void>

Parameters:

Returns:

Promise<void> -

getActiveWorktrees

Get all active worktrees

getActiveWorktrees(): WorktreeInfo[]

Returns:

WorktreeInfo[] -

getStats

Get worktree statistics

getStats(): { active: number; maxWorktrees: number; available: number; }

Returns:

{ active: number; maxWorktrees: number; available: number; } -

AgentOrchestrator

Agent Orchestrator

Coordinates autonomous agent execution by polling for work and spawning workers.

Constructor

constructor(config: OrchestratorConfig)

Parameters:

Methods

start

Start the orchestrator

Connects to RxDB, starts task queue, and begins polling.

start(): Promise<void>

Returns:

Promise<void> -

stop

Stop the orchestrator

Stops polling, cleans up workers, and disconnects from RxDB.

stop(): Promise<void>

Returns:

Promise<void> -

isRunning

Check if orchestrator is running

isRunning(): boolean

Returns:

boolean -

getStats

Get orchestrator statistics

getStats(): OrchestratorStats

Returns:

OrchestratorStats -

TaskQueue

Task Priority Queue

Manages task execution priority and scheduling for the agent orchestrator.

Constructor

constructor(client: IRxDBClient, config: TaskQueueConfig)

Parameters:

Methods

start

Start the task queue

Begins heartbeat updates and initial task loading.

start(): Promise<void>

Returns:

Promise<void> -

stop

Stop the task queue

Stops heartbeat updates and clears the queue.

stop(): Promise<void>

Returns:

Promise<void> -

refreshQueue

Refresh the queue with latest tasks from database

Uses REST client to query tasks directly from server (no replication delay). Updates the queue with proper priority ordering.

refreshQueue(): Promise<void>

Returns:

Promise<void> -

getNextTask

Get next task to execute

Returns the highest priority task that hasn't exceeded max retries.

getNextTask(): Promise<TaskModel | null>

Returns:

Promise<TaskModel \| null> - Next task to execute, or null if queue is empty

markComplete

Mark task as complete

Removes the task from the queue.

markComplete(taskId: string): void

Parameters:

markFailed

Mark task as failed

Updates the task entry with failure information. If max retries exceeded, removes from queue.

markFailed(taskId: string, error: string): void

Parameters:

getStats

Get queue statistics

getStats(): { total: number; byPriority: Record<TaskPriority, number>; averageAttempts: number; }

Returns:

{ total: number; byPriority: Record<TaskPriority, number>; averageAttempts: number; } -

WorkerAgent

Worker Agent

Executes assigned tasks with full autonomy using Claude Agent SDK.

Constructor

constructor(config: WorkerAgentConfig)

Parameters:

Methods

start

Start the worker agent

Connects to RxDB and initializes Git Worktree Manager.

start(): Promise<void>

Returns:

Promise<void> -

getTask

Get assigned task

Retrieves the task assigned to this worker agent. Uses REST client to fetch fresh data directly from server (no replication delay).

getTask(): Promise<TaskModel>

Returns:

Promise<TaskModel> - Task model

getCodebase

Get codebase configuration

Retrieves the codebase configuration for the task.

getCodebase(codebaseId: string): Promise<CodebaseModel>

Parameters:

Returns:

Promise<CodebaseModel> - Codebase model

executeTask

Execute assigned task

Main execution workflow:

1. Retrieve task and codebase
2. Update task status to In Progress
3. Get git worktree
4. Execute with Claude Agent SDK
5. Handle result (success, error, or needs human input)
6. Update task status
7. Release worktree

executeTask(): Promise<TaskExecutionResult>

Returns:

Promise<TaskExecutionResult> - Task execution result

cleanup

Cleanup worker agent

Releases resources and disconnects from RxDB.

cleanup(): Promise<void>

Returns:

Promise<void> -

WorkerSpawner

Worker Spawner

Manages Docker container lifecycle for worker agents.

Constructor

constructor(config: OrchestratorConfig)

Parameters:

Methods

hasWorkerForTask

Check if a worker already exists for a task

hasWorkerForTask(taskId: string): boolean

Parameters:

Returns:

boolean - True if worker exists (running or starting), false otherwise

spawnWorker

Spawn a worker container for a task

Creates a Docker container with the task context and starts it.

spawnWorker(task: TaskModel): Promise<WorkerInfo>

Parameters:

Returns:

Promise<WorkerInfo> - Worker information

getActiveWorkers

Get all active workers

getActiveWorkers(): WorkerInfo[]

Returns:

WorkerInfo[] - Array of active worker information

getWorker

Get worker information by ID

getWorker(workerId: string): WorkerInfo | undefined

Parameters:

Returns:

WorkerInfo \| undefined - Worker information or undefined

cleanupWorker

Cleanup a worker container

Stops and removes the container, then removes from tracking.

cleanupWorker(workerId: string): Promise<void>

Parameters:

Returns:

Promise<void> -

monitorWorker

Monitor worker status

Updates worker status based on container state.

monitorWorker(workerId: string): Promise<void>

Parameters:

Returns:

Promise<void> -

cleanupAll

Cleanup all workers

Stops and removes all tracked workers.

cleanupAll(): Promise<void>

Returns:

Promise<void> -

getStats

Get worker statistics

getStats(): { total: number; running: number; completed: number; failed: number; }

Returns:

{ total: number; running: number; completed: number; failed: number; } -

WorkflowExecutor

Workflow Executor Orchestrates the complete spec workflow using MCP tools

Constructor

constructor(config: AgentConfig, client: IRxDBClient, specTools: SpecManagementTools, approvalHandler: ApprovalHandler, _logger: LoggingService)

Parameters:

Methods

executeWorkflow

Execute complete workflow for a spec

executeWorkflow(specName: string, description: string): Promise<void>

Parameters:

Returns:

Promise<void> -

FileSystemLogger

Mock for FileSystemLogger

Jest automatically uses this mock when jest.mock('./filesystem-logger') is called from files in the same directory or when the module is mocked from tests.

Constructor

constructor(_config: any)

Parameters:

Methods

initialize

initialize(): void

info

info(_message: string, _context?: Record<string, any> | undefined): void

Parameters:

warn

warn(_message: string, _context?: Record<string, any> | undefined): void

Parameters:

error

error(_message: string, _context?: Record<string, any> | undefined, _error?: Error | undefined): void

Parameters:

debug

debug(_message: string, _context?: Record<string, any> | undefined): void

Parameters:

logConversationTurn

logConversationTurn(_role: string, _content: string, _metadata?: any): void

Parameters:

logFileChange

logFileChange(_filePath: string, _changeType: string, _content?: string | undefined): void

Parameters:

logTaskRevision

logTaskRevision(_task: any): void

Parameters:

saveTaskMetadata

saveTaskMetadata(_task: any): void

Parameters:

getLogDirectory

getLogDirectory(): string

Returns:

string -

CircuitBreaker

Constructor

constructor(config?: CircuitBreakerConfig)

Parameters:

Methods

isOpen

Check if circuit is open for provider

isOpen(provider: string): boolean

Parameters:

Returns:

boolean -

recordSuccess

Record successful execution

recordSuccess(provider: string): void

Parameters:

recordFailure

Record failed execution

recordFailure(provider: string): void

Parameters:

getFailureCount

Get current failure count for provider

getFailureCount(provider: string): number

Parameters:

Returns:

number -

reset

Manually reset circuit for provider

reset(provider: string): void

Parameters:

LLMExecutorFactory

Constructor

constructor(config: LLMExecutorConfig)

Parameters:

Methods

getExecutor

Get executor for a task

Selection priority:

1. Task metadata override (task.metadata.llmProvider)
2. Task complexity routing (if hybrid mode enabled)
3. Default provider from config

getExecutor(task: TaskModel, providerOverride?: string | undefined): Promise<LLMExecutor>

Parameters:

Returns:

Promise<LLMExecutor> -

executeWithFallback

Execute with automatic fallback on failure

executeWithFallback(task: TaskModel, params: ExecutionParams): Promise<ExecutionResult>

Parameters:

Returns:

Promise<ExecutionResult> -

ClaudeExecutor

ClaudeExecutor

Implements LLMExecutor interface by wrapping the existing ClaudeHeadlessExecutor. This is a thin adapter that delegates to the existing proven Claude CLI implementation.

Key responsibilities:

• Map ExecutionParams to the format expected by executeTaskHeadless
• Map AgentExecutionResult back to ExecutionResult
• Extract token usage and costs from execution metadata
• Classify errors as retryable or non-retryable
• Verify Claude CLI availability via health checks

Constructor

constructor(config: ClaudeConfig)

Parameters:

Methods

execute

Execute a coding task using Claude CLI via the existing headless executor

This method:

1. Calls the internal executor (ClaudeHeadlessExecutor wrapper)
2. Extracts token usage and costs from execution metadata
3. Maps the result to our ExecutionResult interface
4. Classifies errors as retryable or non-retryable

Note: This is a thin wrapper that allows for dependency injection and testing. The actual ClaudeHeadlessExecutor requires complex setup (RxDB, codebase model, etc.) which is handled by the WorkerAgent in production. This wrapper provides a simplified interface for the factory pattern.

execute(params: ExecutionParams): Promise<ExecutionResult>

Parameters:

Returns:

Promise<ExecutionResult> - Promise resolving to execution result with conversation history and token usage

executeInternal

Internal execution method that wraps ClaudeHeadlessExecutor

This method is separated to allow for easy mocking in tests while maintaining the same interface. In production, this would call executeTaskHeadless with proper configuration.

executeInternal(_params: ExecutionParams): Promise<any>

Parameters:

Returns:

Promise<any> - Promise resolving to agent execution result

healthCheck

Check if Claude CLI is available and healthy

Verifies that the Claude CLI binary is installed and executable. Does not verify API key validity (that happens on first execution).

healthCheck(): Promise<HealthStatus>

Returns:

Promise<HealthStatus> - Promise resolving to health status

getProviderInfo

Get provider information

getProviderInfo(): ProviderInfo

Returns:

ProviderInfo - Provider metadata including name, model, and capabilities

Examples:

const executor = new ClaudeExecutor({
  model: 'claude-sonnet-4-5',
  cliPath: '/usr/local/bin/claude-code'
});

const result = await executor.execute({
  taskId: 'task-123',
  taskPrompt: 'Write a hello world function',
  systemPrompt: 'You are a coding assistant',
  workingDirectory: '/workspace'
});

OllamaExecutor

OllamaExecutor

Implements LLMExecutor interface for Ollama inference server. Ollama is a self-hosted LLM server ideal for POC, testing, and development.

Features:

• HTTP-based API using custom HttpClient
• Support for DeepSeek Coder and other Ollama models
• Zero per-token cost (self-hosted)
• Health checks via /api/tags endpoint

Constructor

constructor(config: OllamaConfig)

Parameters:

Methods

execute

Execute a coding task using Ollama

execute(params: ExecutionParams): Promise<ExecutionResult>

Parameters:

Returns:

Promise<ExecutionResult> - Promise resolving to execution result with conversation history and token usage

healthCheck

Check if Ollama server is healthy and model is loaded

healthCheck(): Promise<HealthStatus>

Returns:

Promise<HealthStatus> - Promise resolving to health status

getProviderInfo

Get provider information

getProviderInfo(): ProviderInfo

Returns:

ProviderInfo - Provider metadata including name, model, and capabilities

Examples:

const executor = new OllamaExecutor({
  endpoint: 'http://localhost:11434',
  model: 'deepseek-coder:33b'
});

const result = await executor.execute({
  taskId: 'task-123',
  taskPrompt: 'Write a hello world function',
  systemPrompt: 'You are a coding assistant',
  workingDirectory: '/workspace'
});

VLLMExecutor

VLLMExecutor

Implements LLMExecutor interface for vLLM inference server. vLLM is a high-performance inference server designed for production deployments on GPU infrastructure, providing OpenAI-compatible API endpoints.

Features:

• OpenAI-compatible API using HttpClient
• Support for DeepSeek Coder and other vLLM-supported models
• Fixed GPU cost (no per-token pricing)
• Health checks via /health endpoint
• Optimized for H100 GPU deployment

Constructor

constructor(config: VLLMConfig)

Parameters:

Methods

execute

Execute a coding task using vLLM

Sends request to vLLM's OpenAI-compatible /v1/chat/completions endpoint. Parses response and maps to our ExecutionResult format.

execute(params: ExecutionParams): Promise<ExecutionResult>

Parameters:

Returns:

Promise<ExecutionResult> - Promise resolving to execution result with conversation history and token usage

healthCheck

Check if vLLM server is healthy

Calls vLLM's /health endpoint to verify server availability.

healthCheck(): Promise<HealthStatus>

Returns:

Promise<HealthStatus> - Promise resolving to health status

getProviderInfo

Get provider information

getProviderInfo(): ProviderInfo

Returns:

ProviderInfo - Provider metadata including name, model, and capabilities

Examples:

const executor = new VLLMExecutor({
  endpoint: 'https://gpu.epic-flow.com/v1',
  model: 'deepseek-ai/deepseek-coder-33b-instruct',
  apiKey: 'optional-api-key'
});

const result = await executor.execute({
  taskId: 'task-123',
  taskPrompt: 'Write a hello world function',
  systemPrompt: 'You are a coding assistant',
  workingDirectory: '/workspace'
});

HttpClient

Constructor

constructor(config?: HttpClientConfig)

Parameters:

Methods

get

get(url: string, options?: RequestInit): Promise<HttpResponse<T>>

Parameters:

Returns:

Promise<HttpResponse<T>> -

post

post(url: string, body?: any, options?: RequestInit): Promise<HttpResponse<T>>

Parameters:

Returns:

Promise<HttpResponse<T>> -