12abdfe81d
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>
90 lines
4.0 KiB
Markdown
90 lines
4.0 KiB
Markdown
# Architecture Decision Records (ADRs)
|
|
|
|
## ADR-001: API-First with Agent-Agnostic Design
|
|
|
|
**Date:** 2025-01-29
|
|
**Status:** Accepted
|
|
**Deciders:** Jason, Jarvis
|
|
|
|
### Context
|
|
|
|
Mosaic Stack needs to integrate with AI agents (currently ClawdBot, formerly MoltBot). The question is how tightly to couple the platform with the agent layer.
|
|
|
|
### Decision
|
|
|
|
**Mosaic Stack will be API-first and agent-agnostic.**
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Users │
|
|
│ (Web UI, Mobile, CLI, API clients) │
|
|
└─────────────────────┬───────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Mosaic Stack │
|
|
│ │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
|
│ │ Knowledge │ │ Tasks/Gantt │ │ Agent Orchestration │ │
|
|
│ │ Module │ │ Module │ │ Module │ │
|
|
│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
|
|
│ │ │ │ │
|
|
│ └────────────────┼─────────────────────┘ │
|
|
│ ▼ │
|
|
│ REST/GraphQL APIs │
|
|
└─────────────────────────┬───────────────────────────────────┘
|
|
│
|
|
┌───────────────┼───────────────┐
|
|
▼ ▼ ▼
|
|
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
│ ClawdBot │ │ Other │ │ Direct │
|
|
│ Skills │ │ Agents │ │ API Use │
|
|
└──────────┘ └──────────┘ └──────────┘
|
|
```
|
|
|
|
### Implications
|
|
|
|
1. **All functionality exposed via APIs first**
|
|
- REST endpoints for CRUD operations
|
|
- GraphQL for complex queries (optional)
|
|
- WebSocket for real-time updates
|
|
|
|
2. **Agent skills are thin wrappers**
|
|
- ClawdBot skills (`mosaic-skill-*`) wrap Mosaic APIs
|
|
- Skills handle: auth, tool definitions, response formatting
|
|
- Business logic lives in Mosaic, not skills
|
|
|
|
3. **Mosaic works standalone**
|
|
- Web UI is fully functional without any agent
|
|
- Users can choose to use agents or not
|
|
- Different agents can integrate (ClawdBot, custom, future)
|
|
|
|
4. **Agent layer is swappable**
|
|
- Not locked to ClawdBot
|
|
- Could use Claude directly, OpenAI agents, or custom
|
|
- Mosaic is the source of truth
|
|
|
|
### Consequences
|
|
|
|
**Positive:**
|
|
|
|
- Platform independence
|
|
- Multiple integration paths
|
|
- Clear separation of concerns
|
|
- Easier testing (API-level tests)
|
|
|
|
**Negative:**
|
|
|
|
- Extra network hop for agent access
|
|
- Need to maintain both API and skill code
|
|
- Slightly more initial work
|
|
|
|
### Related Issues
|
|
|
|
- #22: Brain query API endpoint (API-first ✓)
|
|
- #23-26: mosaic-plugin-_ → rename to mosaic-skill-_ (thin wrappers)
|
|
|
|
---
|
|
|
|
_Future ADRs will be added to this document._
|