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>
118 lines
3.2 KiB
Markdown
118 lines
3.2 KiB
Markdown
# Design Documents
|
|
|
|
Technical design documents for major Mosaic Stack features.
|
|
|
|
## Purpose
|
|
|
|
Design documents serve as:
|
|
|
|
- **Blueprints** for implementation
|
|
- **Reference** for architectural decisions
|
|
- **Communication** between team members
|
|
- **Historical record** of design evolution
|
|
|
|
## Document Structure
|
|
|
|
Each design document should include:
|
|
|
|
1. **Problem Statement** — What are we solving?
|
|
2. **Architecture Overview** — High-level design with diagrams
|
|
3. **Database Schema** — Tables, indexes, relationships
|
|
4. **API Specifications** — Endpoints, request/response formats
|
|
5. **Implementation Plan** — Phased rollout with milestones
|
|
6. **Security & Performance** — Considerations and constraints
|
|
|
|
## Documents
|
|
|
|
### [Agent Orchestration Layer](./agent-orchestration.md)
|
|
|
|
**Status:** Design Phase
|
|
**Version:** 1.0
|
|
**Date:** 2025-01-29
|
|
|
|
Infrastructure for persistent task management and autonomous agent coordination. Enables long-running background work independent of user sessions.
|
|
|
|
**Key Features:**
|
|
|
|
- Task queue with priority scheduling
|
|
- Agent health monitoring and automatic recovery
|
|
- Checkpoint-based resumption for interrupted work
|
|
- Multi-workspace coordination with row-level security
|
|
|
|
---
|
|
|
|
### [Knowledge Module](./knowledge-module.md)
|
|
|
|
**Status:** Design Phase
|
|
**Version:** 1.0
|
|
**Date:** 2025-01-29
|
|
**Issues:** [Implementation Tracker](./knowledge-module-issues.md)
|
|
|
|
Native knowledge management with wiki-style linking, semantic search, and graph visualization. Enables teams and agents to capture, connect, and query organizational knowledge.
|
|
|
|
**Key Features:**
|
|
|
|
- Wiki-style `[[links]]` between entries
|
|
- Full-text and semantic (vector) search
|
|
- Interactive knowledge graph visualization
|
|
- Version history with diff view
|
|
- Tag-based organization
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
When creating a new design document:
|
|
|
|
1. Copy the structure from an existing document
|
|
2. Use ASCII diagrams for architecture (keep them simple)
|
|
3. Include code examples in TypeScript
|
|
4. Specify database schema in SQL (PostgreSQL dialect)
|
|
5. Add implementation phases with clear milestones
|
|
6. Update this README with a summary
|
|
|
|
---
|
|
|
|
### [Federation Architecture](./federation-architecture.md)
|
|
|
|
**Status:** Design Phase
|
|
**Version:** 0.0.1
|
|
**Date:** 2025-01-29
|
|
|
|
Multi-instance federation enabling cross-organization collaboration, work/personal separation, and enterprise control with data sovereignty.
|
|
|
|
**Key Features:**
|
|
|
|
- Peer-to-peer federation (every instance can be master and/or spoke)
|
|
- Authentik integration for enterprise SSO and RBAC
|
|
- Agent Federation Protocol for cross-instance queries and commands
|
|
- Data sovereignty (query in place, never replicate)
|
|
- Single pane of glass aggregating multiple instances
|
|
|
|
---
|
|
|
|
### [Multi-Tenant RLS](./multi-tenant-rls.md)
|
|
|
|
**Status:** Implemented
|
|
**Version:** 1.0
|
|
**Date:** 2025-01-29
|
|
|
|
PostgreSQL Row-Level Security for workspace isolation and defense-in-depth multi-tenancy.
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
When creating a new design document:
|
|
|
|
1. Copy the structure from an existing document
|
|
2. Use ASCII diagrams for architecture (keep them simple)
|
|
3. Include code examples in TypeScript
|
|
4. Specify database schema in SQL (PostgreSQL dialect)
|
|
5. Add implementation phases with clear milestones
|
|
6. Update this README with a summary
|
|
|
|
---
|
|
|
|
**Last Updated:** 2025-01-29
|