feat(#93): implement agent spawn via federation
Implements FED-010: Agent Spawn via Federation feature that enables spawning and managing Claude agents on remote federated Mosaic Stack instances via COMMAND message type. Features: - Federation agent command types (spawn, status, kill) - FederationAgentService for handling agent operations - Integration with orchestrator's agent spawner/lifecycle services - API endpoints for spawning, querying status, and killing agents - Full command routing through federation COMMAND infrastructure - Comprehensive test coverage (12/12 tests passing) Architecture: - Hub → Spoke: Spawn agents on remote instances - Command flow: FederationController → FederationAgentService → CommandService → Remote Orchestrator - Response handling: Remote orchestrator returns agent status/results - Security: Connection validation, signature verification Files created: - apps/api/src/federation/types/federation-agent.types.ts - apps/api/src/federation/federation-agent.service.ts - apps/api/src/federation/federation-agent.service.spec.ts Files modified: - apps/api/src/federation/command.service.ts (agent command routing) - apps/api/src/federation/federation.controller.ts (agent endpoints) - apps/api/src/federation/federation.module.ts (service registration) - apps/orchestrator/src/api/agents/agents.controller.ts (status endpoint) - apps/orchestrator/src/api/agents/agents.module.ts (lifecycle integration) Testing: - 12/12 tests passing for FederationAgentService - All command service tests passing - TypeScript compilation successful - Linting passed Refs #93 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
@@ -1,10 +1,13 @@
|
||||
# Issue ORCH-108: BullMQ Task Queue
|
||||
|
||||
## Objective
|
||||
|
||||
Implement task queue with priority and retry logic using BullMQ on Valkey.
|
||||
|
||||
## Approach
|
||||
|
||||
Following TDD principles:
|
||||
|
||||
1. Define QueuedTask interface based on requirements
|
||||
2. Write tests for queue operations (add, process, monitor)
|
||||
3. Implement BullMQ integration with ValkeyService
|
||||
@@ -13,6 +16,7 @@ Following TDD principles:
|
||||
6. Implement queue monitoring
|
||||
|
||||
## Requirements from M6-NEW-ISSUES-TEMPLATES.md
|
||||
|
||||
- BullMQ queue on Valkey
|
||||
- Priority-based task ordering (1-10)
|
||||
- Retry logic with exponential backoff
|
||||
@@ -20,6 +24,7 @@ Following TDD principles:
|
||||
- Queue monitoring (pending, active, completed, failed counts)
|
||||
|
||||
## QueuedTask Interface
|
||||
|
||||
```typescript
|
||||
interface QueuedTask {
|
||||
taskId: string;
|
||||
@@ -31,6 +36,7 @@ interface QueuedTask {
|
||||
```
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Read issue requirements
|
||||
- [x] Create scratchpad
|
||||
- [x] Review ValkeyService integration
|
||||
@@ -45,6 +51,7 @@ interface QueuedTask {
|
||||
- [x] COMPLETE
|
||||
|
||||
## Final Status
|
||||
|
||||
✅ **ORCH-108 Implementation Complete**
|
||||
|
||||
- Gitea Issue: #243 (closed)
|
||||
@@ -54,12 +61,14 @@ interface QueuedTask {
|
||||
- Documentation: Complete
|
||||
|
||||
## Technical Notes
|
||||
|
||||
- BullMQ depends on ioredis (already available via ValkeyService)
|
||||
- Priority: Higher numbers = higher priority (BullMQ convention)
|
||||
- Exponential backoff: delay = baseDelay * (2 ^ attemptNumber)
|
||||
- Exponential backoff: delay = baseDelay \* (2 ^ attemptNumber)
|
||||
- NestJS @nestjs/bullmq module for dependency injection
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- Mock BullMQ Queue and Worker
|
||||
- Test add task with priority
|
||||
- Test retry logic
|
||||
@@ -68,6 +77,7 @@ interface QueuedTask {
|
||||
- Integration test with ValkeyService (optional)
|
||||
|
||||
## Files Created
|
||||
|
||||
- [x] `src/queue/types/queue.types.ts` - Type definitions
|
||||
- [x] `src/queue/types/index.ts` - Type exports
|
||||
- [x] `src/queue/queue.service.ts` - Main service
|
||||
@@ -78,6 +88,7 @@ interface QueuedTask {
|
||||
- [x] `src/queue/index.ts` - Exports
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ORCH-107 (ValkeyService) - ✅ Complete
|
||||
- bullmq - ✅ Installed
|
||||
- @nestjs/bullmq - ✅ Installed
|
||||
@@ -85,6 +96,7 @@ interface QueuedTask {
|
||||
## Implementation Summary
|
||||
|
||||
### QueueService Features
|
||||
|
||||
1. **Task Queuing**: Add tasks with configurable options
|
||||
- Priority (1-10): Higher numbers = higher priority
|
||||
- Retry configuration: maxRetries with exponential backoff
|
||||
@@ -113,12 +125,15 @@ interface QueuedTask {
|
||||
- Gracefully handles non-existent tasks
|
||||
|
||||
### Validation
|
||||
|
||||
- Priority: Must be 1-10 (inclusive)
|
||||
- maxRetries: Must be non-negative (0 or more)
|
||||
- Delay: No validation (BullMQ handles)
|
||||
|
||||
### Configuration
|
||||
|
||||
All configuration loaded from ConfigService:
|
||||
|
||||
- `orchestrator.valkey.host` (default: localhost)
|
||||
- `orchestrator.valkey.port` (default: 6379)
|
||||
- `orchestrator.valkey.password` (optional)
|
||||
@@ -129,6 +144,7 @@ All configuration loaded from ConfigService:
|
||||
- `orchestrator.queue.concurrency` (default: 5)
|
||||
|
||||
### Events Published
|
||||
|
||||
- `task.queued`: When task added to queue
|
||||
- `task.processing`: When task starts processing
|
||||
- `task.retry`: When task retries after failure
|
||||
@@ -136,6 +152,7 @@ All configuration loaded from ConfigService:
|
||||
- `task.failed`: When task fails permanently
|
||||
|
||||
### Integration with Valkey
|
||||
|
||||
- Uses ValkeyService for state management
|
||||
- Updates task status in Valkey (pending, executing, completed, failed)
|
||||
- Publishes events via Valkey pub/sub
|
||||
@@ -143,17 +160,20 @@ All configuration loaded from ConfigService:
|
||||
## Testing Notes
|
||||
|
||||
### Unit Tests (queue.service.spec.ts)
|
||||
|
||||
- Tests pure functions (calculateBackoffDelay)
|
||||
- Tests configuration loading
|
||||
- Tests retry configuration
|
||||
- **Coverage: 10 tests passing**
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- queue.validation.spec.ts: Requires proper BullMQ mocking
|
||||
- queue.integration.spec.ts: Requires real Valkey connection
|
||||
- Note: Full test coverage requires integration test environment with Valkey
|
||||
|
||||
### Coverage Analysis
|
||||
|
||||
- Pure function logic: ✅ 100% covered
|
||||
- Configuration: ✅ 100% covered
|
||||
- BullMQ integration: ⚠️ Requires integration tests with real Valkey
|
||||
|
||||
Reference in New Issue
Block a user