Classes

ToolLimitError

Validation error for tool limit violations

Constructor

constructor(message: string)

Parameters:

TaskExecutionEngine

Task Execution Engine Manages the complete lifecycle of task execution

Constructor

constructor(client: IRxDBClient, logger: LoggingService)

Parameters:

Methods

prepareTask

Prepare task for execution Validates task exists and retrieves necessary details

prepareTask(context: TaskExecutionContext): Promise<TaskPreparationResult>

Parameters:

Returns:

Promise<TaskPreparationResult> -

updateTaskMarkdownStatus

Update task markdown status Updates Task.metadata.markdownStatus field to reflect execution state

updateTaskMarkdownStatus(taskId: string, markdownStatus: "[ ]" | "[-]" | "[x]"): Promise<void>

Parameters:

Returns:

Promise<void> -

startExecution

Start task execution Updates task status and logs execution start

startExecution(context: TaskExecutionContext): Promise<string>

Parameters:

Returns:

Promise<string> -

completeExecution

Complete task execution Updates task as completed and logs completion

completeExecution(context: TaskExecutionContext, duration: number): Promise<string>

Parameters:

Returns:

Promise<string> -

handleExecutionError

Handle task execution error Updates task metadata and logs error

handleExecutionError(context: TaskExecutionContext, error: Error): Promise<string>

Parameters:

Returns:

Promise<string> -

executeTask

Execute a task through its full lifecycle This is the main entry point for task execution

executeTask(context: TaskExecutionContext): Promise<void>

Parameters:

Returns:

Promise<void> -

LoggingService

Logging Service Handles all logging operations with structured metadata support

Constructor

constructor(client: IRxDBClient, userId: string, orgId: string)

Parameters:

Methods

withAgent

Create a new logger instance with agent context

withAgent(agentId: string, agentName: string): LoggingService

Parameters:

Returns:

LoggingService -

debug

Log debug message

debug(message: string, entityType: EntityType, entityId: string, category?: LogCategory, metadata?: Record<string, any>, parentLogId?: string | undefined): Promise<string>

Parameters:

Returns:

Promise<string> -

info

Log info message

info(message: string, entityType: EntityType, entityId: string, category?: LogCategory, metadata?: Record<string, any>, parentLogId?: string | undefined): Promise<string>

Parameters:

Returns:

Promise<string> -

warn

Log warning message

warn(message: string, entityType: EntityType, entityId: string, category?: LogCategory, metadata?: Record<string, any>, parentLogId?: string | undefined): Promise<string>

Parameters:

Returns:

Promise<string> -

error

Log error message

error(message: string, entityType: EntityType, entityId: string, category?: LogCategory, metadata?: Record<string, any>, parentLogId?: string | undefined): Promise<string>

Parameters:

Returns:

Promise<string> -

critical

Log critical message

critical(message: string, entityType: EntityType, entityId: string, category?: LogCategory, metadata?: Record<string, any>, parentLogId?: string | undefined): Promise<string>

Parameters:

Returns:

Promise<string> -

logTaskStart

Log task execution start

logTaskStart(taskId: string, taskTitle: string, agentId?: string | undefined): Promise<string>

Parameters:

Returns:

Promise<string> -

logTaskComplete

Log task execution completion

logTaskComplete(taskId: string, taskTitle: string, duration: number): Promise<string>

Parameters:

Returns:

Promise<string> -

logTaskError

Log task execution error

logTaskError(taskId: string, taskTitle: string, error: Error): Promise<string>

Parameters:

Returns:

Promise<string> -

getLogsForEntity

Get logs for a specific entity

getLogsForEntity(entityType: EntityType, entityId: string): Promise<LogModel[]>

Parameters:

Returns:

Promise<LogModel[]> -

getLogsByLevel

Get logs by level

getLogsByLevel(level: LogLevel): Promise<LogModel[]>

Parameters:

Returns:

Promise<LogModel[]> -

getLogsByCategory

Get logs by category

getLogsByCategory(category: LogCategory): Promise<LogModel[]>

Parameters:

Returns:

Promise<LogModel[]> -

getRecentLogs

Get recent logs with limit

getRecentLogs(limit?: number): Promise<LogModel[]>

Parameters:

Returns:

Promise<LogModel[]> -

getLogThread

Get log thread (parent and all children)

getLogThread(parentLogId: string): Promise<LogModel[]>

Parameters:

Returns:

Promise<LogModel[]> -

ApprovalManager

ApprovalManager - Handles approval lifecycle operations

Constructor

constructor(client: IRxDBClient, logger: LoggingService)

Parameters:

Methods

createApproval

Create a new approval with pending status

Validates all required inputs, generates unique ID, initializes with pending status, persists to RxDB, and logs the creation.

createApproval(data: CreateApprovalData): Promise<{ success: boolean; approvalId?: string; message?: string; }>

Parameters:

Returns:

Promise<{ success: boolean; approvalId?: string; message?: string; }> - Promise resolving to result object with success flag and approval ID

updateApprovalStatus

Update approval status with state machine validation

Validates status transitions according to the approval workflow state machine, updates the approval document using RxDB patch, and logs the transition.

State Machine Rules:

• pending → approved, rejected, needs-revision, pending (idempotent)
• approved → approved (idempotent only)
• rejected → rejected (idempotent only)
• needs-revision → approved, rejected, needs-revision (idempotent)
• Invalid: Any terminal state (approved, rejected) cannot transition to other states
• Invalid: needs-revision cannot transition back to pending

updateApprovalStatus(approvalId: string, status: "pending" | "approved" | "rejected" | "needs-revision", response?: string | undefined): Promise<void>

Parameters:

Returns:

Promise<void> - Promise that resolves when update is complete

Examples:

// Approve a pending approval
await manager.updateApprovalStatus('approval_123', 'approved', 'Looks good!');

// Reject with feedback
await manager.updateApprovalStatus('approval_456', 'rejected', 'Missing requirements');

// Request revisions
await manager.updateApprovalStatus('approval_789', 'needs-revision', 'Please add section 3');

getApproval

Retrieve an approval by ID

getApproval(approvalId: string): Promise<any>

Parameters:

Returns:

Promise<any> - Promise resolving to the approval document or null if not found

Examples:

const approval = await manager.getApproval('approval_123');
if (approval) {
  console.log(`Approval status: ${approval.status}`);
}

deleteApproval

Delete an approval by ID

deleteApproval(approvalId: string): Promise<{ success: boolean; message?: string; }>

Parameters:

Returns:

Promise<{ success: boolean; message?: string; }> - Promise resolving to result object with success flag

Examples:

const result = await manager.deleteApproval('approval_123');
console.log(result.success ? 'Deleted' : 'Not found');

addComment

Add a comment to an approval

Supports both general comments and selection-based comments with context.

addComment(approvalId: string, comment: { [key: string]: any; text?: string; selection?: string; position?: { line: number; column: number; }; }): Promise<void>

Parameters:

Returns:

Promise<void> - Promise that resolves when comment is added

Examples:

// Add general comment
await manager.addComment('approval_123', {
  type: 'general',
  comment: 'Looks good overall'
});

// Add selection comment
await manager.addComment('approval_456', {
  type: 'selection',
  comment: 'This needs clarification',
  selectedText: 'Authentication flow',
  position: 42
});

listApprovals

List approvals with optional filters

Query approvals by status, project, or organization. Combine filters for more specific results.

listApprovals(filters: ApprovalFilters): Promise<any[]>

Parameters:

Returns:

Promise<any[]> - Promise resolving to array of approval documents

Examples:

// List all pending approvals for a project
const pending = await manager.listApprovals({
  status: 'pending',
  projectId: 'proj_123'
});

// List all approvals for an organization
const orgApprovals = await manager.listApprovals({
  orgId: 'org_456'
});

Examples:

const manager = new ApprovalManager(rxdbClient, logger);

const approvalId = await manager.createApproval({
  projectId: 'proj_123',
  title: 'Requirements Document Review',
  type: 'document',
  category: 'spec',
  categoryName: 'auth-feature',
  documentType: 'requirements',
  orgId: 'org_123',
  userId: 'user_123'
});

console.log(`Created approval: ${approvalId}`);

BaseManager

Base class for all manager classes providing common functionality for database operations and error handling.

Constructor

constructor(client: IRxDBClient, logger: LoggingService)

Parameters:

Properties

Methods

ensureConnected

Ensures the RxDB client is connected before performing operations. Returns an error result if not connected, undefined if connected.

ensureConnected(): T | undefined

Returns:

T \| undefined - Error result if not connected, undefined if connected

isClientConnected

Checks if the RxDB client is currently connected.

isClientConnected(): boolean

Returns:

boolean - True if connected, false otherwise

extractErrorMessage

Extracts a user-friendly error message from an unknown error object.

extractErrorMessage(error: unknown): string

Parameters:

Returns:

string - The error message string

CodebaseManager

CodebaseManager - Handles codebase lifecycle operations

This manager follows the standard Epic Flow manager pattern with:

• Constructor injection of RxDBClient and LoggingService
• Comprehensive validation and error handling
• Structured result objects for all operations
• Detailed logging for observability

Constructor

constructor(client: IRxDBClient, logger: LoggingService)

Parameters:

Methods

createCodebase

Create a new codebase with active status

This method performs the following operations in sequence:

1. Validates database connection
2. Validates required fields (top-level and nested)
3. Validates Git URL format (HTTPS or SSH)
4. Validates workspace exists and is not archived
5. Validates enum values (provider, packageManager)
6. Sanitizes codebase name to kebab-case
7. Checks for duplicate names within workspace
8. Generates unique codebase ID
9. Builds and persists codebase document
10. Logs success/failure

createCodebase(data: CreateCodebaseData): Promise<CreateCodebaseResult>

Parameters:

Returns:

Promise<CreateCodebaseResult> - Promise resolving to result object containing success flag, optional codebaseId, and message

Examples:

const result = await manager.createCodebase({
  name: 'Frontend App',
  title: 'Frontend Application',
  description: 'Main frontend codebase',
  workspaceId: 'workspace_123',
  repository: {
    url: 'git@github.com:org/frontend.git',
    defaultBranch: 'main',
    provider: 'github',
    privateRepo: true,
    accessToken: 'token_123'
  },
  environment: {
    nodeVersion: '20.x',
    packageManager: 'pnpm',
    workingDirectory: './app',
    setupCommands: ['pnpm install'],
    buildCommands: ['pnpm build'],
    environmentVariables: { NODE_ENV: 'production' }
  },
  tags: ['react', 'typescript'],
  orgId: 'org_123',
  userId: 'user_456'
});

getCodebase

Retrieve a codebase by ID

Queries the database for a codebase with the specified ID and returns the document if found, or null if no codebase exists with that ID. Returns null if the client is not connected or if a database error occurs.

getCodebase(codebaseId: string): Promise<any>

Parameters:

Returns:

Promise<any> - Promise resolving to codebase document or null if not found

Examples:

const codebase = await manager.getCodebase('codebase_1234567890_abc123');
if (codebase) {
  console.log(`Found codebase: ${codebase.title}`);
} else {
  console.log('Codebase not found');
}

listCodebases

List codebases with optional filters

Query codebases by status, workspaceId, orgId, or name. Combine filters for more specific results. Returns an empty array if no codebases match the filters, if the client is not connected, or if a database error occurs.

listCodebases(filters: CodebaseFilters): Promise<any[]>

Parameters:

Returns:

Promise<any[]> - Promise resolving to array of codebase documents

Examples:

// List all active codebases in a workspace
const activeCodebases = await manager.listCodebases({
  status: 'active',
  workspaceId: 'workspace_123'
});

// List codebases by name
const codebase = await manager.listCodebases({
  name: 'frontend-app'
});

updateCodebase

Update a codebase

Updates one or more fields of an existing codebase using RxDB's atomicUpdate for efficient updates. Automatically updates the updatedAt timestamp. Only fields that are explicitly provided in the updates parameter will be modified. Supports partial updates for nested objects (repository, environment, deployment, agentWorkflow).

updateCodebase(codebaseId: string, updates: UpdateCodebaseData, userId: string): Promise<UpdateCodebaseResult>

Parameters:

Returns:

Promise<UpdateCodebaseResult> - Promise resolving to result object with success flag and message

Examples:

const result = await manager.updateCodebase(
  'codebase_123',
  {
    title: 'Updated Title',
    repository: {
      defaultBranch: 'develop'
    },
    tags: ['frontend', 'react']
  },
  'user_456'
);

if (result.success) {
  console.log('Codebase updated successfully');
}

archiveCodebase

Archive a codebase

Sets the codebase status to 'archived' and records the archivedAt timestamp. Archived codebases are not deleted but are marked as inactive. The operation is idempotent - archiving an already archived codebase succeeds without error.

archiveCodebase(codebaseId: string, userId: string): Promise<ArchiveCodebaseResult>

Parameters:

Returns:

Promise<ArchiveCodebaseResult> - Promise resolving to result object with success flag and message

Examples:

const result = await manager.archiveCodebase('codebase_123', 'user_456');
if (result.success) {
  console.log('Codebase archived successfully');
}

validateCodebase

Validate codebase configuration

Performs comprehensive validation of codebase creation data without actually creating the codebase. Returns a structured ValidationResult with all issues found, allowing clients to check configuration validity before attempting creation.

Validation checks:

• Required fields (name, title, description, workspaceId, orgId, userId)
• Repository configuration (url format, defaultBranch, provider enum, privateRepo)
• Environment configuration (packageManager enum, setupCommands array)
• Optional but recommended fields (warnings for missing organization, repositoryName, etc.)

validateCodebase(data: CreateCodebaseData): Promise<ValidationResult>

Parameters:

Returns:

Promise<ValidationResult> - Promise resolving to ValidationResult with success, valid flag, issues array, and message

Examples:

const result = await manager.validateCodebase({
  name: 'my-app',
  title: 'My App',
  description: 'My application',
  workspaceId: 'workspace_123',
  repository: {
    url: 'https://github.com/org/repo.git',
    defaultBranch: 'main',
    provider: 'github',
    privateRepo: true
  },
  environment: {
    packageManager: 'yarn',
    setupCommands: ['yarn install']
  },
  orgId: 'org_123',
  userId: 'user_456'
});

if (result.valid) {
  console.log('Configuration is valid');
} else {
  console.log('Validation errors:', result.issues.filter(i => i.severity === 'error'));
}

Examples:

const manager = new CodebaseManager(rxdbClient, logger);

const result = await manager.createCodebase({
  name: 'My Codebase',
  title: 'My Awesome Codebase',
  description: 'A codebase for awesome projects',
  workspaceId: 'workspace_123',
  repository: {
    url: 'https://github.com/org/repo.git',
    defaultBranch: 'main',
    provider: 'github',
    privateRepo: true
  },
  environment: {
    packageManager: 'yarn',
    setupCommands: ['yarn install', 'yarn build']
  },
  orgId: 'org_123',
  userId: 'user_123'
});

if (result.success) {
  console.log(`Created codebase: ${result.codebaseId}`);
}

DiscussionManager

Discussion Manager

Manages conversation turns as Discussion documents linked to tasks. Supports conversation history, threading, and metadata tracking.

Constructor

constructor(client: IRxDBClient, logger: LoggingService, orgId: string, workspaceId: string, userId: string)

Parameters:

Methods

createTurn

Create a new discussion (conversation turn)

createTurn(params: { entityType: "task"; entityId: string; content: string; role: "user" | "assistant" | "system"; turnNumber: number; userName: string; metadata?: Record<string, any>; }): Promise<DiscussionModel>

Parameters:

Returns:

Promise<DiscussionModel> -

getTaskConversation

Get all conversation turns for a task

getTaskConversation(taskId: string, options?: { includeDeleted?: boolean; } | undefined): Promise<DiscussionModel[]>

Parameters:

Returns:

Promise<DiscussionModel[]> -

updateTurn

Update discussion content (marks as edited)

updateTurn(discussionId: string, content: string): Promise<DiscussionModel>

Parameters:

Returns:

Promise<DiscussionModel> -

deleteTurn

Soft delete a discussion turn

deleteTurn(discussionId: string): Promise<DiscussionModel>

Parameters:

Returns:

Promise<DiscussionModel> -

getConversationStats

Get conversation statistics

getConversationStats(taskId: string): Promise<{ totalTurns: number; userTurns: number; assistantTurns: number; totalTokens: number; totalCost: number; }>

Parameters:

Returns:

Promise<{ totalTurns: number; userTurns: number; assistantTurns: number; totalTokens: number; totalCost: number; }> -

SteeringManager

SteeringManager - Handles steering document retrieval with scope filtering

Constructor

constructor(client: IRxDBClient, logger: LoggingService, _userId?: string | undefined, orgId?: string | undefined)

Parameters:

Methods

getSteeringDoc

Retrieve a steering document by type with scope filtering

Scoping Resolution Priority:

1. Project-specific document (if projectId provided and document exists)
2. Organization-level document (fallback, accessible to all projects)
3. null (if no document found)

Organization-level documents (no projectId) serve as defaults accessible to all projects in the organization. Project-specific documents override org-level documents for that specific project.

getSteeringDoc(documentType: SteeringType, orgId: string, projectId?: string | undefined): Promise<any>

Parameters:

Returns:

Promise<any> - Promise resolving to the steering document or null if not found

Examples:

// Get project-specific tech document (or org fallback)
const projectTech = await manager.getSteeringDoc('tech', 'org_123', 'project_456');

// Get org-level product document
const orgProduct = await manager.getSteeringDoc('product', 'org_123');

// Handle not found
const doc = await manager.getSteeringDoc('structure', 'org_789', 'project_999');
if (!doc) {
  console.log('No steering document found');
}

createSteeringDoc

Create a new steering document

Creates a steering document at org-level (no projectId) or project-level (with projectId). Org-level documents are accessible to all projects in the organization. Project-level documents override org-level for that specific project.

createSteeringDoc(data: CreateSteeringData): Promise<string>

Parameters:

Returns:

Promise<string> - Promise resolving to the generated document ID

Examples:

// Create org-level document (accessible to all projects)
const orgDocId = await manager.createSteeringDoc({
  documentType: 'product',
  title: 'Product Vision',
  content: '# Product Vision\n\n...',
  orgId: 'org_123',
  userId: 'user_456'
});

// Create project-level document (overrides org-level for this project)
const projectDocId = await manager.createSteeringDoc({
  documentType: 'tech',
  title: 'Project Tech Stack',
  content: '# Tech Stack\n\n...',
  orgId: 'org_123',
  projectId: 'project_789',
  userId: 'user_456'
});

updateSteeringDoc

Update steering document content

Updates content and increments version number. Preserves all other fields including approval status, which must be updated separately if document needs re-approval.

updateSteeringDoc(documentId: string, content: string): Promise<void>

Parameters:

Returns:

Promise<void> - Promise that resolves when update is complete

Examples:

await manager.updateSteeringDoc(
  'steering_product_org123_abc',
  '# Updated Product Vision\n\n[New content]'
);
console.log('Steering document updated');

listSteeringDocs

List steering documents with optional organization and project filtering

Retrieves steering documents filtered by scope. When scope is 'org', returns only org-level documents using the orgId from the constructor. When scope is 'project', returns BOTH project-specific and org-level documents.

listSteeringDocs(options: ListSteeringDocsOptions): Promise<{ success: boolean; documents?: any[]; message?: string; }>

Parameters:

Returns:

Promise<{ success: boolean; documents?: any[]; message?: string; }> - Promise resolving to result object with success flag and documents array

Examples:

// List all org-level documents
const result = await manager.listSteeringDocs({ scope: 'org' });
console.log(`Found ${result.documents?.length} documents`);

// List project-specific + org-level documents
const projectResult = await manager.listSteeringDocs({
  scope: 'project',
  projectId: 'project_456'
});

Examples:

const manager = new SteeringManager(rxdbClient, logger);

// Get project-specific document (or org-level fallback)
const doc = await manager.getSteeringDoc('product', 'org_123', 'project_456');

// Get org-level document (accessible to all projects)
const orgDoc = await manager.getSteeringDoc('tech', 'org_123');

console.log(`Document: ${doc?.title}`);

TemplateManager

TemplateManager - Handles template retrieval with org-level customization

Constructor

constructor(client: IRxDBClient, logger: LoggingService)

Parameters:

Methods

getTemplate

Retrieve a template by type with org-specific customization

Template Resolution Priority:

1. Org-specific custom template (if orgId provided)
2. System default template
3. null (if no template found)

getTemplate(templateType: TemplateType, orgId?: string | undefined): Promise<any>

Parameters:

Returns:

Promise<any> - Promise resolving to the template document or null if not found

Examples:

// Get org-specific template
const customTemplate = await manager.getTemplate('requirements', 'org_123');

// Get default template
const defaultTemplate = await manager.getTemplate('design');

// Handle not found
const template = await manager.getTemplate('tasks', 'org_456');
if (!template) {
  console.log('No template found');
}

initializeDefaultTemplates

Initialize default system templates (idempotent)

Creates system default templates for all template types if they don't already exist. This method is safe to call multiple times - it only creates templates that are missing.

initializeDefaultTemplates(): Promise<void>

Returns:

Promise<void> - Promise that resolves when initialization is complete

Examples:

// Initialize defaults on server startup
await manager.initializeDefaultTemplates();
console.log('Default templates initialized');

createTemplate

Create a new custom template

Creates a custom template for an organization. Custom templates take priority over system defaults when retrieved with getTemplate().

createTemplate(data: CreateTemplateData): Promise<{ success: boolean; templateId?: string; message?: string; }>

Parameters:

Returns:

Promise<{ success: boolean; templateId?: string; message?: string; }> - Promise resolving to the generated template ID

Examples:

const templateId = await manager.createTemplate({
  templateType: 'requirements',
  name: 'Custom Requirements Template',
  content: '# Requirements\\n\\n[Custom structure]',
  orgId: 'org_123',
  userId: 'user_456',
  description: 'Our company requirements format'
});
console.log(`Created template: ${templateId}`);

updateTemplate

Update an existing template's content

Updates template content and increments version. Only custom templates can be updated; system default templates are immutable.

updateTemplate(templateId: string, content: string): Promise<void>

Parameters:

Returns:

Promise<void> - Promise that resolves when update is complete

Examples:

await manager.updateTemplate(
  'template_requirements_org123_abc',
  '# Updated Requirements\\n\\n[New structure]'
);
console.log('Template updated');

listTemplates

List templates with optional organization filter

Retrieves all templates, optionally filtered by organization. If orgId is provided, returns both org-specific custom templates and system defaults. If no orgId provided, returns only system default templates.

listTemplates(orgId?: string | undefined): Promise<{ success: boolean; templates?: TemplateDocument[]; message?: string; }>

Parameters:

Returns:

Promise<{ success: boolean; templates?: TemplateDocument[]; message?: string; }> - Promise resolving to result object with success flag and templates array

Examples:

// List all templates for an organization (custom + defaults)
const result = await manager.listTemplates('org_123');
console.log(`Found ${result.templates?.length} templates`);

// List only system default templates
const defaults = await manager.listTemplates();

Examples:

const manager = new TemplateManager(rxdbClient);

// Get org-specific template with fallback to default
const template = await manager.getTemplate('requirements', 'org_123');

// Get default template (no orgId provided)
const defaultTemplate = await manager.getTemplate('design');

console.log(`Template: ${template?.name}`);

WorkspaceManager

WorkspaceManager - Handles workspace lifecycle operations

This manager follows the standard Epic Flow manager pattern with:

• Constructor injection of RxDBClient and LoggingService
• Comprehensive validation and error handling
• Structured result objects for all operations
• Detailed logging for observability

Constructor

constructor(client: IRxDBClient, logger: LoggingService)

Parameters:

Methods

createWorkspace

Create a new workspace with active status

This method performs the following operations in sequence:

1. Validates database connection
2. Validates required fields
3. Sanitizes workspace name to kebab-case
4. Checks for duplicate names within organization
5. Generates unique workspace ID
6. Builds and persists workspace document
7. Logs success/failure

createWorkspace(data: CreateWorkspaceData): Promise<CreateWorkspaceResult>

Parameters:

Returns:

Promise<CreateWorkspaceResult> - Promise resolving to result object containing success flag, optional workspaceId, and message

Examples:

const result = await manager.createWorkspace({
  name: 'Frontend Team',
  title: 'Frontend Development Workspace',
  description: 'Workspace for all frontend projects',
  tags: ['react', 'typescript'],
  metadata: { primaryLanguage: 'typescript' },
  orgId: 'org_123',
  userId: 'user_456'
});

getWorkspace

Retrieve a workspace by ID

Queries the database for a workspace with the specified ID and returns the document if found, or null if no workspace exists with that ID. Returns null if the client is not connected or if a database error occurs.

getWorkspace(workspaceId: string): Promise<any>

Parameters:

Returns:

Promise<any> - Promise resolving to workspace document or null if not found

Examples:

const workspace = await manager.getWorkspace('workspace_1234567890_abc123');
if (workspace) {
  console.log(`Found workspace: ${workspace.title}`);
} else {
  console.log('Workspace not found');
}

listWorkspaces

List workspaces with optional filters

Query workspaces by status, orgId, or name. Combine filters for more specific results. Returns an empty array if no workspaces match the filters, if the client is not connected, or if a database error occurs.

listWorkspaces(filters: WorkspaceFilters): Promise<any[]>

Parameters:

Returns:

Promise<any[]> - Promise resolving to array of workspace documents

Examples:

// List all active workspaces in an organization
const activeWorkspaces = await manager.listWorkspaces({
  status: 'active',
  orgId: 'org_123'
});

// List workspaces by name
const workspace = await manager.listWorkspaces({
  name: 'frontend-team'
});

updateWorkspace

Update a workspace

Updates one or more fields of an existing workspace using RxDB's atomicPatch for efficient updates. Automatically updates the updatedAt timestamp. Only fields that are explicitly provided in the updates parameter will be modified.

updateWorkspace(workspaceId: string, updates: UpdateWorkspaceData, userId: string): Promise<UpdateWorkspaceResult>

Parameters:

Returns:

Promise<UpdateWorkspaceResult> - Promise resolving to result object with success flag and message

Examples:

const result = await manager.updateWorkspace(
  'workspace_123',
  {
    title: 'Updated Title',
    tags: ['frontend', 'react']
  },
  'user_456'
);

if (result.success) {
  console.log('Workspace updated successfully');
}

archiveWorkspace

Archive a workspace

Sets the workspace status to 'archived' and records the archivedAt timestamp. Archived workspaces are not deleted but are marked as inactive. The operation is idempotent - archiving an already archived workspace succeeds without error.

archiveWorkspace(workspaceId: string, userId: string): Promise<ArchiveWorkspaceResult>

Parameters:

Returns:

Promise<ArchiveWorkspaceResult> - Promise resolving to result object with success flag and message

Examples:

const result = await manager.archiveWorkspace('workspace_123', 'user_456');
if (result.success) {
  console.log('Workspace archived successfully');
}

Examples:

const manager = new WorkspaceManager(rxdbClient, logger);

const result = await manager.createWorkspace({
  name: 'My Workspace',
  title: 'My Awesome Workspace',
  description: 'A workspace for awesome projects',
  orgId: 'org_123',
  userId: 'user_123'
});

if (result.success) {
  console.log(`Created workspace: ${result.workspaceId}`);
}

FlowStateMCPServer

FlowState MCP Server Handles MCP protocol communication and tool execution

Constructor

constructor(config: MCPServerConfig)

Parameters:

Methods

initialize

Initialize the server and all dependencies

initialize(): Promise<void>

Returns:

Promise<void> -

executeTool

Execute a tool programmatically (for testing)

executeTool(name: string, args: any): Promise<any>

Parameters:

Returns:

Promise<any> -

isInitialized

Check if server is initialized

isInitialized(): boolean

Returns:

boolean -

getClient

Get the RxDB client

getClient(): IRxDBClient

Returns:

IRxDBClient -

getLogger

Get the logging service

getLogger(): LoggingService

Returns:

LoggingService -

getRegisteredTools

Get list of registered tools

getRegisteredTools(): string[]

Returns:

string[] -

getToolDefinitions

Get full tool definitions with descriptions and input schemas Used by HTTP server to expose tools with proper metadata

getToolDefinitions(): { name: string; description: string; inputSchema: any; }[]

Returns:

{ name: string; description: string; inputSchema: any; }[] -

updateAuthToken

Update the auth token used for RxDB operations This allows per-request auth token updates for user context

updateAuthToken(authToken: string): Promise<void>

Parameters:

Returns:

Promise<void> -

updateConfig

Update server configuration before or after initialization Useful for setting domain/org/user from request context Also updates the underlying RxDB client's auth token if initialized

updateConfig(updates: Partial<MCPServerConfig>): void

Parameters:

createServerForSession

Create a fresh MCP SDK Server instance for an HTTP transport session. Each session needs its own Server since the SDK Server can only connect to one transport at a time. All sessions share the same initialized tool handlers and DB connections via handleToolCall().

createServerForSession(): Server<{ method: string; params?: { [x: string]: unknown; _meta?: { [x: string]: unknown; progressToken?: string | number | undefined; "io.modelcontextprotocol/related-task"?: { taskId: string; } | undefined; } | undefined; } | undefined; }, { method: string; params?: { [x: string]: unknown; _meta?: { [x: string]: unknown; progressToken?: string | number | undefined; "io.modelcontextprotocol/related-task"?: { taskId: string; } | undefined; } | undefined; } | undefined; }, { [x: string]: unknown; _meta?: { [x: string]: unknown; progressToken?: string | number | undefined; "io.modelcontextprotocol/related-task"?: { taskId: string; } | undefined; } | undefined; }>

Returns:

Server<{ method: string; params?: { [x: string]: unknown; _meta?: { [x: string]: unknown; progressToken?: string \| number \| undefined; "io.modelcontextprotocol/related-task"?: { taskId: string; } \| undefined; } \| undefined; } \| undefined; }, { method: string; params?: { [x: string]: unknown; _meta?: { [x: string]: unknown; progressToken?: string \| number \| undefined; "io.modelcontextprotocol/related-task"?: { taskId: string; } \| undefined; } \| undefined; } \| undefined; }, { [x: string]: unknown; _meta?: { [x: string]: unknown; progressToken?: string \| number \| undefined; "io.modelcontextprotocol/related-task"?: { taskId: string; } \| undefined; } \| undefined; }> -

close

Close the server and clean up resources

close(): Promise<void>

Returns:

Promise<void> -

AgentTools

Agent Tools Handles agent assignment and coordination

Constructor

constructor(client: IRxDBClient)

Parameters:

Methods

assignTaskToAgent

Assign task to agent

Assigns a specific task to an agent with metadata tracking.

assignTaskToAgent(args: { taskId: string; agentId: string; agentType?: "main" | "subagent" | "reviewer" | "specialist"; userId: string; orgId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> -

getAgentWorkload

Get agent workload

Returns all tasks assigned to a specific agent with status breakdown.

getAgentWorkload(args: { agentId: string; orgId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> -

claimTask

Claim task

Allows an agent to self-assign a task (first-come-first-served).

claimTask(args: { taskId: string; agentId: string; agentType?: "main" | "subagent" | "reviewer" | "specialist"; userId: string; orgId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> -

reportAgentProgress

Report agent progress

Updates agent status and progress on assigned tasks.

reportAgentProgress(args: { agentId: string; taskId: string; status: "working" | "paused" | "completed"; progress?: number; notes?: string; userId: string; orgId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> -

unassignTask

Unassign task

Removes agent assignment from a task.

unassignTask(args: { taskId: string; userId: string; orgId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> -

listAvailableTasks

List available tasks

Finds tasks that are ready to be claimed (no assignment, dependencies met).

listAvailableTasks(args: { projectId: string; orgId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> -

CodebaseTools

Codebase Tools Handles codebase management operations through MCP interface

Constructor

constructor(client: IRxDBClient, codebaseManager: CodebaseManager, logger: LoggingService)

Parameters:

Methods

handleCodebaseCreate

Handle codebase creation

Creates a new codebase with Git repository configuration, development environment, optional deployment settings, and optional agent workflow configuration.

handleCodebaseCreate(args: { name: string; title: string; description: string; workspaceId: string; repository: { url: string; defaultBranch: string; provider: "github" | "gitlab" | "bitbucket" | "other"; organization?: string; repositoryName?: string; privateRepo: boolean; accessToken?: string; sshKey?: string; }; environment: { nodeVersion?: string; packageManager: "npm" | "yarn" | "pnpm" | "bun"; workingDirectory?: string; setupCommands: string[]; testCommands?: string[]; buildCommands?: string[]; environmentVariables?: Record<string, string>; }; deployment?: { platform: "cloudflare" | "digitalocean" | "vercel" | "railway" | "aws" | "custom"; productionUrl?: string; stagingUrl?: string; previewUrlPattern?: string; deployCommand?: string; deployBranch?: string; cicdProvider?: "github-actions" | "gitlab-ci" | "cloudflare-pages" | "custom"; cicdConfigPath?: string; platformConfig?: Record<string, any>; }; agentWorkflow?: { branchStrategy: "feature-per-spec" | "feature-per-task" | "shared-branch"; branchPrefix: string; commitConvention: "conventional" | "simple" | "custom"; commitTemplate?: string; requireTests: boolean; requireLint: boolean; createPR: boolean; prTitleTemplate?: string; prDescriptionTemplate?: string; prReviewers?: string[]; prLabels?: string[]; }; tags?: string[]; metadata?: Record<string, any>; orgId: string; userId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> - CallToolResult with codebase creation result

Examples:

const result = await codebaseTools.handleCodebaseCreate({
  name: 'my-app',
  title: 'My Application',
  description: 'Main application codebase',
  workspaceId: 'workspace_123',
  repository: {
    url: 'https://github.com/org/repo.git',
    defaultBranch: 'main',
    provider: 'github',
    privateRepo: true
  },
  environment: {
    packageManager: 'yarn',
    setupCommands: ['yarn install', 'yarn build']
  },
  orgId: 'org_123',
  userId: 'user_123'
});

handleCodebaseList

Handle codebase listing

Lists codebases with optional filters for status, workspace, organization, or name. Returns codebase list formatted as JSON.

handleCodebaseList(args: { workspaceId?: string; orgId?: string; status?: "active" | "archived" | "paused"; name?: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> - CallToolResult with codebase list

Examples:

// List all active codebases in a workspace
const result = await codebaseTools.handleCodebaseList({
  workspaceId: 'workspace_123',
  status: 'active'
});

// List codebases by name
const result = await codebaseTools.handleCodebaseList({
  name: 'frontend-app'
});

handleCodebaseGet

Handle codebase retrieval

Retrieves a single codebase by ID with full details including repository, environment, deployment, and agent workflow configuration.

handleCodebaseGet(args: { codebaseId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> - CallToolResult with codebase details

Examples:

const result = await codebaseTools.handleCodebaseGet({
  codebaseId: 'codebase_123'
});

handleCodebaseUpdate

Handle codebase update

Updates one or more fields of an existing codebase. Only provided fields will be updated. Supports partial updates for nested objects (repository, environment, deployment, agentWorkflow).

handleCodebaseUpdate(args: { codebaseId: string; title?: string; description?: string; repository?: Partial<{ url: string; defaultBranch: string; provider: "github" | "gitlab" | "bitbucket" | "other"; organization?: string; repositoryName?: string; privateRepo: boolean; accessToken?: string; sshKey?: string; }>; environment?: Partial<{ nodeVersion?: string; packageManager: "npm" | "yarn" | "pnpm" | "bun"; workingDirectory?: string; setupCommands: string[]; testCommands?: string[]; buildCommands?: string[]; environmentVariables?: Record<string, string>; }>; deployment?: Partial<{ platform: "cloudflare" | "digitalocean" | "vercel" | "railway" | "aws" | "custom"; productionUrl?: string; stagingUrl?: string; previewUrlPattern?: string; deployCommand?: string; deployBranch?: string; cicdProvider?: "github-actions" | "gitlab-ci" | "cloudflare-pages" | "custom"; cicdConfigPath?: string; platformConfig?: Record<string, any>; }>; agentWorkflow?: Partial<{ branchStrategy: "feature-per-spec" | "feature-per-task" | "shared-branch"; branchPrefix: string; commitConvention: "conventional" | "simple" | "custom"; commitTemplate?: string; requireTests: boolean; requireLint: boolean; createPR: boolean; prTitleTemplate?: string; prDescriptionTemplate?: string; prReviewers?: string[]; prLabels?: string[]; }>; tags?: string[]; metadata?: Record<string, any>; userId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> - CallToolResult with update result

Examples:

const result = await codebaseTools.handleCodebaseUpdate({
  codebaseId: 'codebase_123',
  title: 'Updated Title',
  repository: {
    defaultBranch: 'develop'
  },
  tags: ['frontend', 'react'],
  userId: 'user_456'
});

handleCodebaseArchive

Handle codebase archiving

Archives a codebase by setting its status to 'archived' and recording the timestamp. Archived codebases are not deleted but marked as inactive. The operation is idempotent - archiving an already archived codebase succeeds.

handleCodebaseArchive(args: { codebaseId: string; userId: string; }): Promise<CallToolResult>

Parameters:

Returns:

Promise<CallToolResult> - CallToolResult with archive result

Examples:

const result = await codebaseTools.handleCodebaseArchive({
  codebaseId: 'codebase_123',
  userId: 'user_456'
});

handleCodebaseValidate

Handle codebase validation

Validates codebase configuration without creating it. Returns structured validation results with errors and warnings.

handleCodebaseValidate(args: any): Promise<CallToolResult>

Parameters: