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
2026-02-03 14:37:06 -06:00
parent a8c8af21e5
commit 12abdfe81d
405 changed files with 13545 additions and 2153 deletions

View File

@@ -2,7 +2,15 @@
name: mosaic-plugin-tasks
description: Integration with Mosaic Stack's Tasks API for task management. Use when the user wants to create, list, update, complete, or delete tasks, including queries like "add task", "create task", "what's in progress", "high priority tasks", "mark task as done", "overdue tasks", "show my tasks", or "delete task".
homepage: https://git.mosaicstack.dev/mosaic/stack
metadata: {"clawdbot":{"emoji":"✅","requires":{"bins":["node"],"env":["MOSAIC_API_TOKEN","MOSAIC_WORKSPACE_ID"]},"primaryEnv":"MOSAIC_API_TOKEN"}}
metadata:
{
"clawdbot":
{
"emoji": "✅",
"requires": { "bins": ["node"], "env": ["MOSAIC_API_TOKEN", "MOSAIC_WORKSPACE_ID"] },
"primaryEnv": "MOSAIC_API_TOKEN",
},
}
---
# Mosaic Tasks
@@ -25,6 +33,7 @@ node scripts/tasks.cjs create \
```
Natural language examples:
- "Add task: review PR #123"
- "Create a high priority task to fix the login bug"
- "Add a task to update documentation, due Friday"
@@ -53,6 +62,7 @@ node scripts/tasks.cjs list --overdue
```
Natural language examples:
- "What tasks are in progress?"
- "Show me high priority tasks"
- "What do I need to do today?"
@@ -67,6 +77,7 @@ node scripts/tasks.cjs get TASK_ID
```
Natural language examples:
- "Show me task details for abc-123"
- "What's the status of the deployment task?"
@@ -87,6 +98,7 @@ node scripts/tasks.cjs update TASK_ID \
```
Natural language examples:
- "Mark task abc-123 as done"
- "Set PR review task to in progress"
- "Change priority of deployment task to high"
@@ -100,6 +112,7 @@ node scripts/tasks.cjs delete TASK_ID
```
Natural language examples:
- "Delete task abc-123"
- "Remove the duplicate deployment task"
- "Delete all completed tasks from last month"
@@ -150,10 +163,12 @@ node scripts/tasks.cjs list --overdue
```
This filters to:
- `dueDate < current_datetime`
- `status NOT IN (COMPLETED, ARCHIVED)`
Natural language examples:
- "What tasks are overdue?"
- "Show me late tasks"
- "Which tasks missed their deadline?"
@@ -212,6 +227,7 @@ Tasks can transition to any status at any time based on needs.
## Environment
The script reads configuration from:
- `MOSAIC_API_URL` (default: http://localhost:3001)
- `MOSAIC_WORKSPACE_ID` (required)
- `MOSAIC_API_TOKEN` (required for authentication)
@@ -221,6 +237,7 @@ Ensure these are set in the environment or `.env` file.
## Error Handling
Common errors:
- **401 Unauthorized**: Missing or invalid API token
- **403 Forbidden**: Insufficient workspace permissions (tasks require MEMBER role to create/update, ADMIN to delete)
- **404 Not Found**: Task ID doesn't exist in this workspace
@@ -239,6 +256,7 @@ Task operations require different permission levels:
## Integration with Projects
Tasks can be linked to projects via `projectId`. This enables:
- Filtering tasks by project
- Project-based task organization
- Tracking project progress through task completion