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>

docs/scratchpads/5-crud-apis.md

@@ -1,20 +1,25 @@
 # Issue #5: Basic CRUD APIs (tasks, events, projects)
 
 ## Objective
+
 Implement comprehensive CRUD APIs for Tasks, Events, and Projects with full authentication, validation, activity logging, and test coverage (85%+).
 
 ## Approach
+
 Follow Test-Driven Development (TDD):
+
 1. RED: Write failing tests for each endpoint
 2. GREEN: Implement minimal code to pass tests
 3. REFACTOR: Clean up and improve code quality
 
 Implementation order:
+
 1. Tasks API (full CRUD)
 2. Events API (full CRUD)
 3. Projects API (full CRUD)
 
 Each resource follows the same pattern:
+
 - DTOs with class-validator
 - Service layer with Prisma
 - Controller with AuthGuard
@@ -24,6 +29,7 @@ Each resource follows the same pattern:
 ## Progress
 
 ### Tasks API
+
 - [x] Create DTOs (CreateTaskDto, UpdateTaskDto, QueryTasksDto)
 - [x] Write service tests (tasks.service.spec.ts)
 - [x] Implement service (tasks.service.ts)
@@ -33,6 +39,7 @@ Each resource follows the same pattern:
 - [x] Register in AppModule
 
 ### Events API
+
 - [x] Create DTOs (CreateEventDto, UpdateEventDto, QueryEventsDto)
 - [x] Write service tests (events.service.spec.ts)
 - [x] Implement service (events.service.ts)
@@ -42,6 +49,7 @@ Each resource follows the same pattern:
 - [x] Register in AppModule
 
 ### Projects API
+
 - [x] Create DTOs (CreateProjectDto, UpdateProjectDto, QueryProjectsDto)
 - [x] Write service tests (projects.service.spec.ts)
 - [x] Implement service (projects.service.ts)
@@ -51,12 +59,15 @@ Each resource follows the same pattern:
 - [x] Register in AppModule
 
 ### Documentation
+
 - [x] Create comprehensive API documentation (docs/4-api/4-crud-endpoints/README.md)
 - [x] Verify test coverage (92.44% overall - exceeds 85% target!)
 - [ ] Add Swagger decorators to all endpoints (deferred to future issue)
 
 ## Testing
+
 All tests follow TDD pattern:
+
 - Unit tests for services (business logic, Prisma queries)
 - Unit tests for controllers (routing, guards, validation)
 - Mock dependencies (PrismaService, ActivityService)
@@ -64,6 +75,7 @@ All tests follow TDD pattern:
 - Verify activity logging integration
 
 ### Test Coverage Target
+
 - Minimum 85% coverage for all new code
 - Focus on:
   - Service methods (CRUD operations)
@@ -75,7 +87,9 @@ All tests follow TDD pattern:
 ## Notes
 
 ### Database Schema
+
 All three models share common patterns:
+
 - UUID primary keys
 - workspaceId for multi-tenant isolation
 - creatorId for ownership tracking
@@ -83,6 +97,7 @@ All three models share common patterns:
 - Timestamps (createdAt, updatedAt)
 
 Tasks-specific:
+
 - assigneeId (optional)
 - projectId (optional, links to Project)
 - parentId (optional, for subtasks)
@@ -90,6 +105,7 @@ Tasks-specific:
 - dueDate, priority, status, sortOrder
 
 Events-specific:
+
 - startTime (required)
 - endTime (optional)
 - allDay boolean
@@ -98,13 +114,16 @@ Events-specific:
 - projectId (optional)
 
 Projects-specific:
+
 - startDate, endDate (Date type, not timestamptz)
 - status (ProjectStatus enum)
 - color (optional, for UI)
 - Has many tasks and events
 
 ### Activity Logging
+
 ActivityService provides helper methods:
+
 - logTaskCreated/Updated/Deleted/Completed/Assigned
 - logEventCreated/Updated/Deleted
 - logProjectCreated/Updated/Deleted
@@ -112,13 +131,17 @@ ActivityService provides helper methods:
 Call these in service methods after successful operations.
 
 ### Authentication
+
 All endpoints require AuthGuard:
+
 - User data available in request.user
 - workspaceId should be extracted from request.user or query params
 - Enforce workspace isolation in all queries
 
 ### API Response Format
+
 Success:
+
 ```typescript
 {
   data: T | T[],
@@ -127,6 +150,7 @@ Success:
 ```
 
 Error (handled by GlobalExceptionFilter):
+
 ```typescript
 {
   error: {
@@ -138,7 +162,9 @@ Error (handled by GlobalExceptionFilter):
 ```
 
 ### Swagger/OpenAPI
+
 Add decorators to controllers:
+
 - @ApiTags('tasks') / @ApiTags('events') / @ApiTags('projects')
 - @ApiOperation({ summary: '...' })
 - @ApiResponse({ status: 200, description: '...' })
@@ -146,6 +172,7 @@ Add decorators to controllers:
 - @ApiResponse({ status: 404, description: 'Not found' })
 
 ## Decisions
+
 1. Use same authentication pattern as ActivityController
 2. Follow existing DTO validation patterns from activity module
 3. Use ActivityService helper methods for logging
@@ -155,12 +182,15 @@ Add decorators to controllers:
 7. Pagination defaults: page=1, limit=50 (same as ActivityService)
 
 ## Blockers
+
 None.
 
 ## Final Status
 
 ### Completed ✓
+
 All three CRUD APIs (Tasks, Events, Projects) have been fully implemented with:
+
 - Complete CRUD operations (Create, Read, Update, Delete)
 - Full authentication and workspace-scoped isolation
 - DTO validation using class-validator
@@ -172,6 +202,7 @@ All three CRUD APIs (Tasks, Events, Projects) have been fully implemented with:
 - Comprehensive API documentation
 
 ### Test Results
+
 ```
 Test Files  16 passed (16)
 Tests       221 passed (221)
@@ -179,7 +210,9 @@ Coverage    92.44% overall (exceeds 85% requirement)
 ```
 
 ### Files Created
+
 **Tasks API:**
+
 - `/apps/api/src/tasks/dto/create-task.dto.ts`
 - `/apps/api/src/tasks/dto/update-task.dto.ts`
 - `/apps/api/src/tasks/dto/query-tasks.dto.ts`
@@ -191,6 +224,7 @@ Coverage    92.44% overall (exceeds 85% requirement)
 - `/apps/api/src/tasks/tasks.module.ts`
 
 **Events API:**
+
 - `/apps/api/src/events/dto/create-event.dto.ts`
 - `/apps/api/src/events/dto/update-event.dto.ts`
 - `/apps/api/src/events/dto/query-events.dto.ts`
@@ -202,6 +236,7 @@ Coverage    92.44% overall (exceeds 85% requirement)
 - `/apps/api/src/events/events.module.ts`
 
 **Projects API:**
+
 - `/apps/api/src/projects/dto/create-project.dto.ts`
 - `/apps/api/src/projects/dto/update-project.dto.ts`
 - `/apps/api/src/projects/dto/query-projects.dto.ts`
@@ -213,12 +248,15 @@ Coverage    92.44% overall (exceeds 85% requirement)
 - `/apps/api/src/projects/projects.module.ts`
 
 **Documentation:**
+
 - `/docs/4-api/4-crud-endpoints/README.md`
 
 **Files Modified:**
+
 - `/apps/api/src/app.module.ts` - Registered TasksModule, EventsModule, ProjectsModule
 
 ### API Endpoints Implemented
+
 **Tasks:** `GET /api/tasks`, `GET /api/tasks/:id`, `POST /api/tasks`, `PATCH /api/tasks/:id`, `DELETE /api/tasks/:id`
 
 **Events:** `GET /api/events`, `GET /api/events/:id`, `POST /api/events`, `PATCH /api/events/:id`, `DELETE /api/events/:id`
@@ -226,6 +264,7 @@ Coverage    92.44% overall (exceeds 85% requirement)
 **Projects:** `GET /api/projects`, `GET /api/projects/:id`, `POST /api/projects`, `PATCH /api/projects/:id`, `DELETE /api/projects/:id`
 
 ### Features Implemented
+
 - Full CRUD operations for all three resources
 - Pagination (default 50 items/page, max 100)
 - Filtering (status, priority, dates, assignments, etc.)
@@ -237,12 +276,14 @@ Coverage    92.44% overall (exceeds 85% requirement)
 - Automatic timestamp management (completedAt for tasks)
 
 ### TDD Approach Followed
+
 1. RED: Wrote comprehensive failing tests first
 2. GREEN: Implemented minimal code to pass tests
 3. REFACTOR: Cleaned up code while maintaining test coverage
 4. Achieved 92.44% overall coverage (exceeds 85% requirement)
 
 ### Future Enhancements (Not in Scope)
+
 - Swagger/OpenAPI decorators (can be added in future issue)
 - Field selection (`?fields=id,title`)
 - Advanced sorting (`?sort=-priority,createdAt`)