Files

Jason Woltje 12abdfe81d 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

4.0 KiB

Raw Blame History

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

All functionality exposed via APIs first
- REST endpoints for CRUD operations
- GraphQL for complex queries (optional)
- WebSocket for real-time updates
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
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)
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

#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.

4.0 KiB Raw Blame History