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
@@ -261,11 +261,13 @@ PRISMA_LOG_QUERIES=false
|
||||
Environment variables are validated at application startup. Missing required variables will cause the application to fail with a clear error message.
|
||||
|
||||
**Required variables:**
|
||||
|
||||
- `DATABASE_URL`
|
||||
- `JWT_SECRET`
|
||||
- `NEXT_PUBLIC_APP_URL`
|
||||
|
||||
**Optional variables:**
|
||||
|
||||
- All OIDC settings (if using Authentik)
|
||||
- All Ollama settings (if using AI features)
|
||||
- Logging and monitoring settings
|
||||
|
||||
@@ -36,6 +36,7 @@ docker compose logs -f
|
||||
```
|
||||
|
||||
**Access Authentik:**
|
||||
|
||||
- URL: http://localhost:9000/if/flow/initial-setup/
|
||||
- Create admin account during initial setup
|
||||
|
||||
@@ -53,17 +54,17 @@ Sign up at [goauthentik.io](https://goauthentik.io) for managed Authentik.
|
||||
|
||||
4. **Configure Provider:**
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Name** | Mosaic Stack |
|
||||
| **Authorization flow** | default-provider-authorization-implicit-consent |
|
||||
| **Client type** | Confidential |
|
||||
| **Client ID** | (auto-generated, save this) |
|
||||
| **Client Secret** | (auto-generated, save this) |
|
||||
| **Redirect URIs** | `http://localhost:3001/auth/callback` |
|
||||
| **Scopes** | `openid`, `email`, `profile` |
|
||||
| **Subject mode** | Based on User's UUID |
|
||||
| **Include claims in id_token** | ✅ Enabled |
|
||||
| Field | Value |
|
||||
| ------------------------------ | ----------------------------------------------- |
|
||||
| **Name** | Mosaic Stack |
|
||||
| **Authorization flow** | default-provider-authorization-implicit-consent |
|
||||
| **Client type** | Confidential |
|
||||
| **Client ID** | (auto-generated, save this) |
|
||||
| **Client Secret** | (auto-generated, save this) |
|
||||
| **Redirect URIs** | `http://localhost:3001/auth/callback` |
|
||||
| **Scopes** | `openid`, `email`, `profile` |
|
||||
| **Subject mode** | Based on User's UUID |
|
||||
| **Include claims in id_token** | ✅ Enabled |
|
||||
|
||||
5. **Click "Create"**
|
||||
|
||||
@@ -77,12 +78,12 @@ Sign up at [goauthentik.io](https://goauthentik.io) for managed Authentik.
|
||||
|
||||
3. **Configure Application:**
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Name** | Mosaic Stack |
|
||||
| **Slug** | mosaic-stack |
|
||||
| **Provider** | Select "Mosaic Stack" (created in Step 2) |
|
||||
| **Launch URL** | `http://localhost:3000` |
|
||||
| Field | Value |
|
||||
| -------------- | ----------------------------------------- |
|
||||
| **Name** | Mosaic Stack |
|
||||
| **Slug** | mosaic-stack |
|
||||
| **Provider** | Select "Mosaic Stack" (created in Step 2) |
|
||||
| **Launch URL** | `http://localhost:3000` |
|
||||
|
||||
4. **Click "Create"**
|
||||
|
||||
@@ -99,6 +100,7 @@ OIDC_REDIRECT_URI=http://localhost:3001/auth/callback
|
||||
```
|
||||
|
||||
**Important Notes:**
|
||||
|
||||
- `OIDC_ISSUER` must end with a trailing slash `/`
|
||||
- Replace `<your-client-id>` and `<your-client-secret>` with actual values from Step 2
|
||||
- `OIDC_REDIRECT_URI` must exactly match what you configured in Authentik
|
||||
@@ -218,6 +220,7 @@ Customize Authentik's login page:
|
||||
**Cause:** Redirect URI in `.env` doesn't match Authentik configuration
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Ensure exact match (including http vs https)
|
||||
# In Authentik: http://localhost:3001/auth/callback
|
||||
@@ -229,6 +232,7 @@ Customize Authentik's login page:
|
||||
**Cause:** Incorrect client ID or secret
|
||||
|
||||
**Fix:**
|
||||
|
||||
1. Double-check Client ID and Secret in Authentik provider
|
||||
2. Copy values exactly (no extra spaces)
|
||||
3. Update `.env` with correct values
|
||||
@@ -239,6 +243,7 @@ Customize Authentik's login page:
|
||||
**Cause:** `OIDC_ISSUER` incorrect or Authentik not accessible
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# Ensure OIDC_ISSUER ends with /
|
||||
# Test discovery endpoint
|
||||
@@ -252,6 +257,7 @@ curl http://localhost:9000/application/o/mosaic-stack/.well-known/openid-configu
|
||||
**Cause:** User doesn't have permission in Authentik
|
||||
|
||||
**Fix:**
|
||||
|
||||
1. In Authentik, go to **Directory** → **Users**
|
||||
2. Select user
|
||||
3. Click **Assigned to applications**
|
||||
@@ -264,6 +270,7 @@ Or enable **Superuser privileges** for the user (development only).
|
||||
**Cause:** JWT expiration set too low
|
||||
|
||||
**Fix:**
|
||||
|
||||
```bash
|
||||
# In .env, increase expiration
|
||||
JWT_EXPIRATION=7d # 7 days instead of 24h
|
||||
|
||||
@@ -93,6 +93,7 @@ OIDC_REDIRECT_URI=http://localhost:3001/auth/callback
|
||||
```
|
||||
|
||||
**Bootstrap Credentials:**
|
||||
|
||||
- Username: `akadmin`
|
||||
- Password: Value of `AUTHENTIK_BOOTSTRAP_PASSWORD`
|
||||
|
||||
@@ -124,6 +125,7 @@ COMPOSE_PROFILES=full # Enable all optional services
|
||||
```
|
||||
|
||||
Available profiles:
|
||||
|
||||
- `authentik` - Authentik OIDC provider stack
|
||||
- `ollama` - Ollama LLM service
|
||||
- `full` - All optional services
|
||||
@@ -257,7 +259,7 @@ services:
|
||||
replicas: 2
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1.0'
|
||||
cpus: "1.0"
|
||||
memory: 1G
|
||||
|
||||
web:
|
||||
@@ -268,11 +270,12 @@ services:
|
||||
replicas: 2
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.5'
|
||||
cpus: "0.5"
|
||||
memory: 512M
|
||||
```
|
||||
|
||||
Deploy:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
||||
```
|
||||
@@ -311,9 +314,9 @@ services:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1.0'
|
||||
cpus: "1.0"
|
||||
reservations:
|
||||
cpus: '0.25'
|
||||
cpus: "0.25"
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
@@ -325,10 +328,10 @@ All services include health checks. Adjust timing if needed:
|
||||
services:
|
||||
postgres:
|
||||
healthcheck:
|
||||
interval: 30s # Check every 30s
|
||||
timeout: 10s # Timeout after 10s
|
||||
retries: 5 # Retry 5 times
|
||||
start_period: 60s # Wait 60s before first check
|
||||
interval: 30s # Check every 30s
|
||||
timeout: 10s # Timeout after 10s
|
||||
retries: 5 # Retry 5 times
|
||||
start_period: 60s # Wait 60s before first check
|
||||
```
|
||||
|
||||
## Logging Configuration
|
||||
@@ -349,6 +352,7 @@ services:
|
||||
### Centralized Logging
|
||||
|
||||
For production, consider:
|
||||
|
||||
- Loki + Grafana
|
||||
- ELK Stack (Elasticsearch, Logstash, Kibana)
|
||||
- Fluentd
|
||||
@@ -371,11 +375,13 @@ services:
|
||||
### Container Won't Start
|
||||
|
||||
Check logs:
|
||||
|
||||
```bash
|
||||
docker compose logs <service>
|
||||
```
|
||||
|
||||
Common issues:
|
||||
|
||||
- Port conflict: Change port in `.env`
|
||||
- Missing environment variable: Check `.env` file
|
||||
- Health check failing: Increase `start_period`
|
||||
@@ -383,6 +389,7 @@ Common issues:
|
||||
### Network Issues
|
||||
|
||||
Test connectivity between containers:
|
||||
|
||||
```bash
|
||||
# From API container to PostgreSQL
|
||||
docker compose exec api sh
|
||||
@@ -392,6 +399,7 @@ nc -zv postgres 5432
|
||||
### Volume Permission Issues
|
||||
|
||||
Fix permissions:
|
||||
|
||||
```bash
|
||||
# PostgreSQL volume
|
||||
docker compose exec postgres chown -R postgres:postgres /var/lib/postgresql/data
|
||||
@@ -400,6 +408,7 @@ docker compose exec postgres chown -R postgres:postgres /var/lib/postgresql/data
|
||||
### Out of Disk Space
|
||||
|
||||
Clean up:
|
||||
|
||||
```bash
|
||||
# Remove unused containers, networks, images
|
||||
docker system prune -a
|
||||
|
||||
Reference in New Issue
Block a user