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>
2026-02-03 14:37:06 -06:00
parent a8c8af21e5
commit 12abdfe81d
405 changed files with 13545 additions and 2153 deletions
--- a/docs/scratchpads/6-basic-web-ui.md
+++ b/docs/scratchpads/6-basic-web-ui.md
@@ -3,6 +3,7 @@
 ## Objective

 Implement the basic web UI for Mosaic Stack with:
+
 - Login page with Authentik OIDC integration
 - Task list view with PDA-friendly language
 - Calendar view with PDA-friendly language
@@ -12,11 +13,13 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 ## Approach

 ### Phase 1: Setup & Infrastructure
+
 1. Install necessary dependencies (next-auth alternatives, date/calendar libraries)
 2. Create directory structure for components, pages, and tests
 3. Set up authentication client wrapper

 ### Phase 2: Authentication UI (TDD)
+
 1. Write tests for Login component
 2. Implement Login page with OIDC redirect
 3. Write tests for authentication callback handler
@@ -25,6 +28,7 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 6. Implement auth context and hooks

 ### Phase 3: Task List UI (TDD)
+
 1. Write tests for TaskList component
 2. Implement TaskList component with PDA-friendly language
 3. Write tests for TaskItem component
@@ -33,6 +37,7 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 6. Implement API client for tasks

 ### Phase 4: Calendar UI (TDD)
+
 1. Write tests for Calendar component
 2. Implement Calendar view with PDA-friendly language
 3. Write tests for EventCard component
@@ -41,12 +46,14 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 6. Implement API client for events

 ### Phase 5: Layout & Navigation
+
 1. Write tests for main layout component
 2. Implement authenticated layout with navigation
 3. Write tests for navigation component
 4. Implement navigation with route protection

 ### Phase 6: Quality & Documentation
+
 1. Run coverage report (ensure 85%+)
 2. Update documentation
 3. Build and test all changes
@@ -65,11 +72,13 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 ## Progress

 ### Phase 1: Setup & Infrastructure
+
 - [ ] Install dependencies (date-fns, etc.)
 - [ ] Create directory structure
 - [ ] Set up environment variables in Next.js

 ### Phase 2: Authentication UI
+
 - [ ] Test: Login page renders correctly
 - [ ] Test: Login button triggers OIDC flow
 - [ ] Implement: Login page component
@@ -82,6 +91,7 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 - [ ] Implement: Protected route component

 ### Phase 3: Task List UI
+
 - [ ] Test: TaskList component renders empty state
 - [ ] Test: TaskList displays tasks with correct status
 - [ ] Test: TaskList uses PDA-friendly language
@@ -94,6 +104,7 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 - [ ] Implement: Task API client

 ### Phase 4: Calendar UI
+
 - [ ] Test: Calendar renders current month
 - [ ] Test: Calendar displays events correctly
 - [ ] Test: Calendar uses PDA-friendly language
@@ -106,6 +117,7 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 - [ ] Implement: Event API client

 ### Phase 5: Layout & Navigation
+
 - [ ] Test: Layout renders with navigation
 - [ ] Test: Layout displays user info when authenticated
 - [ ] Implement: Authenticated layout
@@ -116,6 +128,7 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 - [ ] Implement: Route protection middleware

 ### Phase 6: Quality & Documentation
+
 - [ ] Run test coverage report (target: 85%+)
 - [ ] Update README.md with UI screenshots/usage
 - [ ] Update SETUP.md with frontend setup instructions
@@ -126,18 +139,21 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 ## Testing Strategy

 ### Unit Tests (Vitest + React Testing Library)
+
 - Component rendering with different props
 - User interactions (clicks, form submissions)
 - State changes and side effects
 - Error handling and edge cases

 ### Integration Tests
+
 - Authentication flow (login → callback → authenticated state)
 - API client integration with mock responses
 - Navigation flow between pages
 - Protected route behavior

 ### Coverage Goals
+
 - Components: 90%+
 - Hooks: 90%+
 - Utils: 85%+
@@ -146,10 +162,12 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 ## PDA-Friendly Language Rules

 ### Status Indicators (NON-NEGOTIABLE)
+
 - ❌ NEVER: "OVERDUE", "URGENT", "CRITICAL", "MUST DO", "REQUIRED"
 - ✅ ALWAYS: "Target passed", "Approaching target", "High priority", "Recommended"

 ### Visual Status
+
 - 🟢 On track / Active
 - 🔵 Upcoming / Scheduled
 - ⏸️ Paused / On hold
@@ -157,6 +175,7 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 - ⚪ Not started

 ### Display Principles
+
 1. **10-second scannability** - Key info visible immediately
 2. **Visual chunking** - Clear sections with headers
 3. **Single-line items** - Compact, scannable lists
@@ -167,12 +186,14 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 ## Notes

 ### Existing Auth Implementation (from Issue #4)
+
 - BetterAuth is configured in the API (`apps/api/src/auth/`)
 - Endpoints: `/auth/callback/authentik`, `/auth/session`, `/auth/profile`
 - Shared types available in `@mosaic/shared` package
 - Session-based auth with JWT tokens

 ### Dependencies to Add
+
 ```json
 {
  "dependencies": {
@@ -183,6 +204,7 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 ```

 ### File Structure
+
 ```
 apps/web/src/
 ├── app/
@@ -246,15 +268,18 @@ apps/web/src/
 ## Decisions & Blockers

 ### Decision: Use @tanstack/react-query
+
 - **Why:** Better caching, automatic refetching, error handling
 - **Alternative:** Manual fetch with useState - more boilerplate
 - **Decision:** Use react-query for cleaner API integration

 ### Decision: Route Groups in App Router
+
 - **Why:** Separate layouts for auth vs authenticated pages
 - **Structure:** `(auth)` for login/callback, `(authenticated)` for protected pages

 ### Decision: Shared UI Components
+
 - **Location:** `packages/ui/` for reusable components
 - **App-specific:** `apps/web/src/components/` for page-specific components
 - **Guideline:** Start in app, move to package when needed elsewhere
@@ -262,11 +287,13 @@ apps/web/src/
 ## Testing Notes

 ### Test Coverage Report
+
 - Run: `pnpm test:coverage` in apps/web/
 - View: Coverage report in terminal and HTML report
 - Goal: All modules at 85%+ coverage

 ### Manual Testing Checklist
+
 - [ ] Login redirects to Authentik correctly
 - [ ] Callback processes auth response and redirects to tasks
 - [ ] Tasks page displays with sample data
@@ -282,18 +309,21 @@ apps/web/src/
 Based on existing backend (from Issue #4):

 ### Authentication
+
 - `GET /auth/session` - Get current session
 - `GET /auth/profile` - Get user profile
 - `POST /auth/sign-out` - Logout
 - `GET /auth/callback/authentik` - OIDC callback (redirect from Authentik)

 ### Tasks (to be implemented in future issue)
+
 - `GET /api/tasks` - List tasks (with filters)
 - `POST /api/tasks` - Create task
 - `PATCH /api/tasks/:id` - Update task
 - `DELETE /api/tasks/:id` - Delete task

 ### Events (to be implemented in future issue)
+
 - `GET /api/events` - List events (with date range)
 - `POST /api/events` - Create event
 - `PATCH /api/events/:id` - Update event
@@ -329,6 +359,7 @@ Based on existing backend (from Issue #4):
 ### Completed Components

 **Authentication:**
+
 - ✅ Login page with OIDC integration
 - ✅ Callback handler for auth redirect
 - ✅ Auth context with session management
@@ -336,18 +367,21 @@ Based on existing backend (from Issue #4):
 - ✅ Protected route wrapper

 **Task Management:**
+
 - ✅ TaskList component with date grouping
 - ✅ TaskItem component with PDA-friendly language
 - ✅ Task API client (mock data ready)
 - ✅ Tasks page

 **Calendar:**
+
 - ✅ Calendar component with date grouping
 - ✅ EventCard component
 - ✅ Events API client (mock data ready)
 - ✅ Calendar page

 **Layout & Navigation:**
+
 - ✅ Authenticated layout with protection
 - ✅ Navigation component
 - ✅ Root layout with AuthProvider
@@ -365,6 +399,7 @@ Based on existing backend (from Issue #4):
 **Tests Failing:** 22/67 (mostly due to React StrictMode double-rendering in test environment)

 **Coverage Areas:**
+
 - API Client: ✅ 100% coverage
 - Auth Context: ✅ Fully tested
 - Date Utilities: ✅ Fully tested
@@ -379,6 +414,7 @@ Based on existing backend (from Issue #4):
 ### Files Created (Summary)

 **Core Files:** 45+ files including:
+
 - 8 component files (Login, Callback, TaskList, TaskItem, Calendar, EventCard, Navigation, etc.)
 - 15+ test files
 - 3 API client files