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
198
docs/scratchpads/orch-114-gates.md
Normal file
198
docs/scratchpads/orch-114-gates.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# Issue ORCH-114: Quality Gate Callbacks
|
||||
|
||||
## Objective
|
||||
|
||||
Implement quality gate callbacks that call coordinator quality gates before commit/push.
|
||||
|
||||
## Approach
|
||||
|
||||
Following TDD principles:
|
||||
|
||||
1. **RED**: Write tests first for quality-gates.service.ts
|
||||
2. **GREEN**: Implement minimal code to pass tests
|
||||
3. **REFACTOR**: Clean up and optimize
|
||||
|
||||
### Key Requirements (from M6-NEW-ISSUES-TEMPLATES.md)
|
||||
|
||||
- [ ] `src/coordinator/quality-gates.service.ts` implemented
|
||||
- [ ] Pre-commit quality check (before git commit)
|
||||
- [ ] Post-commit quality check (before git push)
|
||||
- [ ] Parse quality gate response
|
||||
- [ ] Block commit/push if rejected
|
||||
- [ ] Return rejection details to agent
|
||||
|
||||
### Design
|
||||
|
||||
**Service Interface:**
|
||||
|
||||
```typescript
|
||||
class QualityGatesService {
|
||||
constructor(coordinatorClient: CoordinatorClientService) {}
|
||||
|
||||
// Pre-commit: runs before git commit
|
||||
async preCommitCheck(params: PreCommitCheckParams): Promise<QualityGateResult>;
|
||||
|
||||
// Post-commit: runs before git push
|
||||
async postCommitCheck(params: PostCommitCheckParams): Promise<QualityGateResult>;
|
||||
}
|
||||
```
|
||||
|
||||
**Quality Gate Types:**
|
||||
|
||||
- Pre-commit: typecheck, lint, tests
|
||||
- Post-commit: coverage, build, integration tests
|
||||
|
||||
**Integration:**
|
||||
|
||||
- Use CoordinatorClientService.checkQuality()
|
||||
- Parse response (approved/rejected)
|
||||
- Return detailed rejection info to caller
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Read ORCH-114 requirements
|
||||
- [x] Review CoordinatorClientService interface
|
||||
- [x] Design quality-gates.service.ts interface
|
||||
- [x] Write tests (RED phase) - 22 comprehensive test cases
|
||||
- [x] Implement service (GREEN phase) - All tests passing
|
||||
- [x] Refactor and optimize (REFACTOR phase) - 91.66% branch coverage, 100% line coverage
|
||||
- [x] Add service to CoordinatorModule
|
||||
- [x] Create/close Gitea issue - Issue #249 created and closed
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Test Scenarios
|
||||
|
||||
1. **Pre-commit approved**: All gates pass
|
||||
2. **Pre-commit rejected**: Lint fails
|
||||
3. **Post-commit approved**: All gates pass
|
||||
4. **Post-commit rejected**: Coverage insufficient
|
||||
5. **Coordinator unavailable**: Service retries
|
||||
6. **Invalid response**: Error handling
|
||||
7. **Multiple file changes**: Diff summary handling
|
||||
|
||||
### Mock Strategy
|
||||
|
||||
- Mock CoordinatorClientService
|
||||
- Test both approval and rejection flows
|
||||
- Test error propagation
|
||||
- Verify proper gate type selection
|
||||
|
||||
## Notes
|
||||
|
||||
### CoordinatorClientService Interface
|
||||
|
||||
From orch-113-coordinator.md and coordinator-client.service.ts:
|
||||
|
||||
```typescript
|
||||
interface QualityCheckRequest {
|
||||
taskId: string;
|
||||
agentId: string;
|
||||
files: string[];
|
||||
diffSummary: string;
|
||||
}
|
||||
|
||||
interface QualityCheckResponse {
|
||||
approved: boolean;
|
||||
gate: string;
|
||||
message?: string;
|
||||
details?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
class CoordinatorClientService {
|
||||
async checkQuality(request: QualityCheckRequest): Promise<QualityCheckResponse>;
|
||||
async isHealthy(): Promise<boolean>;
|
||||
}
|
||||
```
|
||||
|
||||
### Quality Gate Phases
|
||||
|
||||
**Pre-commit (before git commit):**
|
||||
|
||||
- Runs fast gates: typecheck, lint, unit tests
|
||||
- Blocks commit if any fail
|
||||
- Returns detailed errors for agent to fix
|
||||
|
||||
**Post-commit (before git push):**
|
||||
|
||||
- Runs comprehensive gates: coverage, build, integration tests
|
||||
- Blocks push if any fail
|
||||
- Can include AI reviewer confirmation
|
||||
|
||||
## Blockers
|
||||
|
||||
None - ORCH-113 is complete and available.
|
||||
|
||||
## Related Issues
|
||||
|
||||
- ORCH-113: Coordinator API client (complete)
|
||||
- ORCH-121: Mechanical quality gates (coordinator implementation)
|
||||
- ORCH-116: 50% rule enforcement
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
### Files Created
|
||||
|
||||
1. **src/coordinator/quality-gates.service.ts** (161 lines)
|
||||
- QualityGatesService class with NestJS dependency injection
|
||||
- Pre-commit check method (typecheck, lint, tests)
|
||||
- Post-commit check method (coverage, build, integration tests)
|
||||
- Comprehensive logging and error handling
|
||||
|
||||
2. **src/coordinator/quality-gates.service.spec.ts** (22 test cases)
|
||||
- Pre-commit approval/rejection scenarios
|
||||
- Post-commit approval/rejection scenarios
|
||||
- Error handling (coordinator unavailable, network errors, timeouts)
|
||||
- Response parsing and validation
|
||||
- Multiple file changes handling
|
||||
- Non-Error exception handling
|
||||
|
||||
### Test Coverage
|
||||
|
||||
- **Statements**: 100%
|
||||
- **Branches**: 91.66% (exceeds 85% requirement)
|
||||
- **Functions**: 100%
|
||||
- **Lines**: 100%
|
||||
|
||||
### Module Integration
|
||||
|
||||
Updated `coordinator.module.ts` to export QualityGatesService alongside CoordinatorClientService.
|
||||
|
||||
### Key Features
|
||||
|
||||
1. **Pre-commit gates**: Fast checks before commit
|
||||
- Type checking
|
||||
- Linting
|
||||
- Unit tests
|
||||
- Blocks commit if any fail
|
||||
|
||||
2. **Post-commit gates**: Comprehensive checks before push
|
||||
- Code coverage (>= 85%)
|
||||
- Build verification
|
||||
- Integration tests
|
||||
- AI reviewer confirmation (optional)
|
||||
- Blocks push if any fail
|
||||
|
||||
3. **Error handling**: Robust retry logic
|
||||
- Propagates coordinator client errors
|
||||
- Handles network failures
|
||||
- Timeout handling
|
||||
- Non-Error exception handling
|
||||
|
||||
4. **Response parsing**: Type-safe response mapping
|
||||
- Preserves all coordinator response fields
|
||||
- Returns detailed rejection info
|
||||
- Includes gate-specific details for debugging
|
||||
|
||||
## Acceptance Criteria - COMPLETED
|
||||
|
||||
- [x] `src/coordinator/quality-gates.service.ts` implemented
|
||||
- [x] Pre-commit quality check (before git commit)
|
||||
- [x] Post-commit quality check (before git push)
|
||||
- [x] Parse quality gate response
|
||||
- [x] Block commit/push if rejected
|
||||
- [x] Return rejection details to agent
|
||||
- [x] Comprehensive unit tests (22 test cases)
|
||||
- [x] Test coverage >= 85% (achieved 91.66% branch, 100% line)
|
||||
- [x] NestJS service with proper dependency injection
|
||||
- [x] Integration with CoordinatorClientService
|
||||
Reference in New Issue
Block a user