feat: AI Swarm Mode - Multi-agent parallel task execution

[Suhaib3100]

Fixes #279

Summary

Implements the foundation for AI Swarm Mode - enabling a master agent to spawn and orchestrate multiple worker agents in separate browser windows for parallel task execution.

Use Case

User: "Research and compare the top 5 CRM solutions"

Master Agent (Coordinator)
├── Decomposes task into 5 parallel subtasks
├── Spawns 5 worker windows
├── Monitors progress
└── Synthesizes final report
    │
    ├── Worker 1: Research Salesforce
    ├── Worker 2: Research HubSpot
    ├── Worker 3: Research Pipedrive
    ├── Worker 4: Research Zoho
    └── Worker 5: Research Monday

Components Added

Core (apps/server/src/swarm/)

Component	Description
types.ts	SwarmState, WorkerState, SwarmRequest, SwarmResult, message types
constants.ts	SWARM_LIMITS, SWARM_TIMEOUTS, default configs
coordinator/swarm-registry.ts	Tracks active swarms and workers
coordinator/task-planner.ts	LLM-based task decomposition
coordinator/swarm-coordinator.ts	Main orchestrator for swarm lifecycle
worker/worker-lifecycle.ts	Spawn, monitor, terminate workers
messaging/swarm-bus.ts	EventEmitter-based pub/sub communication
aggregation/result-aggregator.ts	Merges worker results

API (apps/server/src/api/routes/swarm.ts)

Method	Endpoint	Description
POST	/swarm	Create and execute swarm
POST	/swarm/create	Create swarm only
POST	/swarm/:id/execute	Execute existing swarm
GET	/swarm/:id	Get status
GET	/swarm/:id/stream	SSE for real-time updates
DELETE	/swarm/:id	Terminate swarm

Key Features

• Task Decomposition: LLM automatically breaks complex tasks into parallel subtasks
• Worker Management: Spawn workers in separate windows with health monitoring
• Retry Logic: Exponential backoff for failed workers (max 3 retries)
• Progress Tracking: Real-time updates via SSE streaming
• Result Aggregation: Merge worker results with partial failure support
• Output Formats: JSON, Markdown, or HTML

Commits

1. feat(swarm): add core types and constants
2. feat(swarm): add SwarmRegistry for tracking active swarms
3. feat(swarm): add SwarmMessagingBus for inter-agent communication
4. feat(swarm): add WorkerLifecycleManager for worker management
5. feat(swarm): add TaskPlanner for LLM-based task decomposition
6. feat(swarm): add ResultAggregator for merging worker results
7. feat(swarm): add SwarmCoordinator as main orchestrator
8. feat(swarm): add HTTP API routes for swarm management
9. docs(swarm): add design document and update exports

Next Steps

• Integration with main server
• Worker agent implementation
• UI components for swarm visualization
• Chromium-side SwarmWindowManager for resource isolation

[github-actions]

All contributors have signed the CLA. Thank you!
_{Posted by the CLA Assistant Lite bot.}

[Suhaib3100]

I have read the CLA Document and I hereby sign the CLA

[greptile-apps]

Greptile Overview

Greptile Summary

Implements a comprehensive AI Swarm Mode feature that enables parallel task execution across multiple browser windows. The architecture is well-designed with clear separation of concerns:

• Core Components: SwarmRegistry tracks state, TaskPlanner decomposes tasks via LLM, WorkerLifecycleManager manages worker windows, SwarmMessagingBus handles inter-agent communication, and ResultAggregator merges results
• API Layer: HTTP endpoints with SSE streaming for real-time progress updates
• Type Safety: Comprehensive TypeScript types with Zod validation schemas

Key Issues Found:

1. Import Path Error (syntax): result-aggregator.ts has incorrect import path for SwarmRegistry
2. Retry Logic Bug (logic): Worker retry count is reset when respawning, breaking retry limit enforcement
3. Resource Leak (logic): SSE keepAlive interval not cleared on terminal events
4. Architecture Violation (style): index.ts barrel export violates CLAUDE.md guideline against bundling all exports

Strengths:

• Clean architecture with proper dependency injection
• Comprehensive error handling and logging
• Well-documented with inline comments
• Proper event-driven design for monitoring
• Health monitoring with heartbeat and progress tracking

Confidence Score: 4/5

• Safe to merge with minor fixes needed for import path and retry logic
• Score of 4 reflects solid architecture and implementation with 2 syntax/logic bugs that need fixing: incorrect import path will cause runtime error, and retry logic bug could lead to infinite retries. Resource leak is less critical but should be addressed. Style violation (index.ts) doesn't block merge but should be cleaned up per project guidelines.
• Pay close attention to result-aggregator.ts (import fix required) and worker-lifecycle.ts (retry logic fix required)

Important Files Changed

Filename	Overview
apps/server/src/swarm/worker/worker-lifecycle.ts	Worker lifecycle management with health monitoring; has retry logic bug where retryCount is reset on respawn
apps/server/src/swarm/aggregation/result-aggregator.ts	Result aggregation with formatting options; has incorrect import path for SwarmRegistry
apps/server/src/swarm/coordinator/swarm-coordinator.ts	Main orchestrator with proper phase management and event emission - no issues
apps/server/src/api/routes/swarm.ts	HTTP API routes with SSE streaming; potential resource leak in keepAlive interval cleanup
apps/server/src/swarm/index.ts	Barrel export file that violates CLAUDE.md guideline against index.ts exports

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as Swarm API Routes
    participant Coord as SwarmCoordinator
    participant Registry as SwarmRegistry
    participant Planner as TaskPlanner
    participant Lifecycle as WorkerLifecycleManager
    participant Bus as SwarmMessagingBus
    participant Bridge as ControllerBridge
    participant Workers as Worker Windows
    participant Aggregator as ResultAggregator

    Client->>API: POST /swarm {task, maxWorkers}
    API->>Coord: createAndExecute(request)
    
    Note over Coord: Phase 1: Planning
    Coord->>Registry: create(task, config)
    Registry-->>Coord: swarm object
    Coord->>Registry: updateState(swarmId, 'planning')
    Coord->>Planner: decompose(task, config)
    Planner->>Planner: LLM generates subtasks
    Planner-->>Coord: WorkerTask[]
    
    Note over Coord: Phase 2: Spawning Workers
    Coord->>Registry: updateState(swarmId, 'spawning')
    loop For each task
        Coord->>Lifecycle: spawnWorker(swarmId, task)
        Lifecycle->>Registry: addWorker(swarmId, worker)
        Lifecycle->>Bridge: sendRequest('create_window')
        Bridge-->>Lifecycle: {windowId}
        Lifecycle->>Bus: startHealthMonitoring()
        Lifecycle-->>Coord: worker object
        Coord->>Coord: emit('worker_spawned')
    end
    
    Note over Coord: Phase 3: Execution & Monitoring
    Coord->>Registry: updateState(swarmId, 'executing')
    Coord->>Coord: emit('swarm_started')
    Coord->>Bus: subscribeToMaster(swarmId)
    
    loop Worker Execution
        Workers->>Bus: sendToMaster('task_progress')
        Bus->>Coord: message received
        Coord->>Registry: updateWorkerProgress()
        Coord->>Coord: emit('worker_progress')
        
        Workers->>Bus: sendToMaster('task_complete')
        Bus->>Coord: message received
        Coord->>Registry: setWorkerResult()
        Coord->>Coord: emit('worker_completed')
    end
    
    Note over Coord: Phase 4: Aggregation
    Coord->>Registry: updateState(swarmId, 'aggregating')
    Coord->>Coord: emit('aggregation_started')
    Coord->>Aggregator: aggregate(swarmId, format)
    Aggregator->>Registry: getWorkers(swarmId)
    Registry-->>Aggregator: Worker[]
    Aggregator->>Aggregator: calculateMetrics()
    Aggregator->>Aggregator: simpleAggregate() or LLM synthesize()
    Aggregator-->>Coord: AggregatedResult
    
    Coord->>Registry: updateState(swarmId, 'completed')
    Coord->>Coord: emit('swarm_completed')
    Coord-->>API: SwarmResult
    API-->>Client: {success: true, data: result}

Loading

[greptile-apps]

_{4 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Potential resource leak - keepAlive interval may not be cleared if stream closes via the earlier terminal event path (lines 206-211)

When stream.close() is called in the terminal event handler, the keepAlive interval continues running. Consider clearing it before closing:

if (
  event.type === 'swarm_completed' ||
  event.type === 'swarm_failed'
) {
  clearInterval(keepAlive)
  stream.close()
}

Prompt To Fix With AI

This is a comment left during a code review.
Path: apps/server/src/api/routes/swarm.ts
Line: 219:234

Comment:
Potential resource leak - `keepAlive` interval may not be cleared if stream closes via the earlier terminal event path (lines 206-211)

When `stream.close()` is called in the terminal event handler, the `keepAlive` interval continues running. Consider clearing it before closing:

```typescript
if (
  event.type === 'swarm_completed' ||
  event.type === 'swarm_failed'
) {
  clearInterval(keepAlive)
  stream.close()
}
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Retry logic mutates existing worker object, potentially causing issues when spawning new worker with same ID

When retrying, the code increments retryCount on the existing worker object then calls spawnWorker() which creates a fresh worker with retryCount: 0. The retry count won't persist correctly.

Prompt To Fix With AI

This is a comment left during a code review.
Path: apps/server/src/swarm/worker/worker-lifecycle.ts
Line: 247:251

Comment:
Retry logic mutates existing worker object, potentially causing issues when spawning new worker with same ID

When retrying, the code increments `retryCount` on the existing worker object then calls `spawnWorker()` which creates a fresh worker with retryCount: 0. The retry count won't persist correctly.

How can I resolve this? If you propose a fix, please make it concise.

[Suhaib3100]

Thanks for the review! Both issues have been fixed in commit 1640b9e:

1. Resource leak in SSE stream (swarm.ts)

• Now calling clearInterval(keepAlive) and unsubscribe() before stream.close() on terminal events

2. Retry count persistence (worker-lifecycle.ts)

• Storing the incremented retry count in a variable before respawning
• Applying the preserved retryCount to the new worker after spawn

Both fixes ensure proper cleanup and correct retry behavior.

[Suhaib3100]

I have read the CLA Document and I hereby sign the CLA