mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

feat(#93): implement agent spawn via federation

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

91
CONTRIBUTING.md
View File

@@ -78,15 +78,15 @@ Thank you for your interest in contributing to Mosaic Stack! This document provi
### Quick Reference Commands
| Command | Description |
|---------|-------------|
| `pnpm dev` | Start all development servers |
| `pnpm dev:api` | Start API only |
| `pnpm dev:web` | Start Web only |
| `docker compose up -d` | Start Docker services |
| `docker compose logs -f` | View Docker logs |
| `pnpm prisma:studio` | Open Prisma Studio GUI |
| `make help` | View all available commands |
| Command | Description |
| ------------------------ | ----------------------------- |
| `pnpm dev` | Start all development servers |
| `pnpm dev:api` | Start API only |
| `pnpm dev:web` | Start Web only |
| `docker compose up -d` | Start Docker services |
| `docker compose logs -f` | View Docker logs |
| `pnpm prisma:studio` | Open Prisma Studio GUI |
| `make help` | View all available commands |
## Code Style Guidelines
@@ -104,6 +104,7 @@ We use **Prettier** for consistent code formatting:
- **End of line:** LF (Unix style)
Run the formatter:
```bash
pnpm format # Format all files
pnpm format:check # Check formatting without changes
@@ -121,6 +122,7 @@ pnpm lint:fix # Auto-fix linting issues
### TypeScript
All code must be **strictly typed** TypeScript:
- No `any` types allowed
- Explicit type annotations for function returns
- Interfaces over type aliases for object shapes
@@ -130,14 +132,14 @@ All code must be **strictly typed** TypeScript:
**Never** use demanding or stressful language in UI text:
| ❌ AVOID | ✅ INSTEAD |
|---------|------------|
| OVERDUE | Target passed |
| URGENT | Approaching target |
| MUST DO | Scheduled for |
| CRITICAL | High priority |
| ❌ AVOID | ✅ INSTEAD |
| ----------- | -------------------- |
| OVERDUE | Target passed |
| URGENT | Approaching target |
| MUST DO | Scheduled for |
| CRITICAL | High priority |
| YOU NEED TO | Consider / Option to |
| REQUIRED | Recommended |
| REQUIRED | Recommended |
See [docs/3-architecture/3-design-principles/1-pda-friendly.md](./docs/3-architecture/3-design-principles/1-pda-friendly.md) for complete design principles.
@@ -147,13 +149,13 @@ We follow a Git-based workflow with the following branch types:
### Branch Types
| Prefix | Purpose | Example |
|--------|---------|---------|
| `feature/` | New features | `feature/42-user-dashboard` |
| `fix/` | Bug fixes | `fix/123-auth-redirect` |
| `docs/` | Documentation | `docs/contributing` |
| `refactor/` | Code refactoring | `refactor/prisma-queries` |
| `test/` | Test-only changes | `test/coverage-improvements` |
| Prefix | Purpose | Example |
| ----------- | ----------------- | ---------------------------- |
| `feature/` | New features | `feature/42-user-dashboard` |
| `fix/` | Bug fixes | `fix/123-auth-redirect` |
| `docs/` | Documentation | `docs/contributing` |
| `refactor/` | Code refactoring | `refactor/prisma-queries` |
| `test/` | Test-only changes | `test/coverage-improvements` |
### Workflow
@@ -190,14 +192,14 @@ References: #123
### Types
| Type | Description |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation changes |
| `test` | Adding or updating tests |
| Type | Description |
| ---------- | --------------------------------------- |
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation changes |
| `test` | Adding or updating tests |
| `refactor` | Code refactoring (no functional change) |
| `chore` | Maintenance tasks, dependencies |
| `chore` | Maintenance tasks, dependencies |
### Examples
@@ -233,17 +235,20 @@ Clarified pagination and filtering parameters.
### Before Creating a PR
1. **Ensure tests pass**
```bash
pnpm test
pnpm build
```
2. **Check code coverage** (minimum 85%)
```bash
pnpm test:coverage
```
3. **Format and lint**
```bash
pnpm format
pnpm lint
@@ -256,6 +261,7 @@ Clarified pagination and filtering parameters.
### Creating a Pull Request
1. Push your branch to the remote
```bash
git push origin feature/my-feature
```
@@ -294,6 +300,7 @@ Clarified pagination and filtering parameters.
#### TDD Workflow: Red-Green-Refactor
1. **RED** - Write a failing test first
```bash
# Write test for new functionality
pnpm test:watch # Watch it fail
@@ -302,6 +309,7 @@ Clarified pagination and filtering parameters.
```
2. **GREEN** - Write minimal code to pass the test
```bash
# Implement just enough to pass
pnpm test:watch # Watch it pass
@@ -327,11 +335,11 @@ Clarified pagination and filtering parameters.
### Test Types
| Type | Purpose | Tool |
|------|---------|------|
| **Unit tests** | Test functions/methods in isolation | Vitest |
| **Integration tests** | Test module interactions (service + DB) | Vitest |
| **E2E tests** | Test complete user workflows | Playwright |
| Type | Purpose | Tool |
| --------------------- | --------------------------------------- | ---------- |
| **Unit tests** | Test functions/methods in isolation | Vitest |
| **Integration tests** | Test module interactions (service + DB) | Vitest |
| **E2E tests** | Test complete user workflows | Playwright |
### Running Tests
@@ -347,6 +355,7 @@ pnpm test:e2e # Playwright E2E tests
### Coverage Verification
After implementation:
```bash
pnpm test:coverage
# Open coverage/index.html in browser
@@ -369,15 +378,16 @@ https://git.mosaicstack.dev/mosaic/stack/issues
### Issue Labels
| Category | Labels |
|----------|--------|
| Priority | `p0` (critical), `p1` (high), `p2` (medium), `p3` (low) |
| Type | `api`, `web`, `database`, `auth`, `plugin`, `ai`, `devops`, `docs`, `testing` |
| Status | `todo`, `in-progress`, `review`, `blocked`, `done` |
| Category | Labels |
| -------- | ----------------------------------------------------------------------------- |
| Priority | `p0` (critical), `p1` (high), `p2` (medium), `p3` (low) |
| Type | `api`, `web`, `database`, `auth`, `plugin`, `ai`, `devops`, `docs`, `testing` |
| Status | `todo`, `in-progress`, `review`, `blocked`, `done` |
### Documentation
Check existing documentation first:
- [README.md](./README.md) - Project overview
- [CLAUDE.md](./CLAUDE.md) - Comprehensive development guidelines
- [docs/](./docs/) - Full documentation suite
@@ -402,6 +412,7 @@ Check existing documentation first:
**Thank you for contributing to Mosaic Stack!** Every contribution helps make this platform better for everyone.
For more details, see:
- [Project README](./README.md)
- [Development Guidelines](./CLAUDE.md)
- [API Documentation](./docs/4-api/)