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

3.5 KiB

Raw Blame History

AGENTS.md — Mosaic Stack

Guidelines for AI agents working on this codebase.

Quick Start

Read CLAUDE.md for project-specific patterns
Check this file for workflow and context management
Use TOOLS.md patterns (if present) before fumbling with CLIs

Context Management

Context = tokens = cost. Be smart.

Strategy	When
Spawn sub-agents	Isolated coding tasks, research, anything that can report back
Batch operations	Group related API calls, don't do one-at-a-time
Check existing patterns	Before writing new code, see how similar features were built
Minimize re-reading	Don't re-read files you just wrote
Summarize before clearing	Extract learnings to memory before context reset

Workflow (Non-Negotiable)

Code Changes

1. Branch    → git checkout -b feature/XX-description
2. Code      → TDD: write test (RED), implement (GREEN), refactor
3. Test      → pnpm test (must pass)
4. Push      → git push origin feature/XX-description
5. PR        → Create PR to develop (not main)
6. Review    → Wait for approval or self-merge if authorized
7. Close     → Close related issues via API

Never merge directly to develop without a PR.

Issue Management

# Get Gitea token
TOKEN="$(jq -r '.gitea.mosaicstack.token' ~/src/jarvis-brain/credentials.json)"

# Create issue
curl -s -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  "https://git.mosaicstack.dev/api/v1/repos/mosaic/stack/issues" \
  -d '{"title":"Title","body":"Description","milestone":54}'

# Close issue (REQUIRED after merge)
curl -s -X PATCH -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
  "https://git.mosaicstack.dev/api/v1/repos/mosaic/stack/issues/XX" \
  -d '{"state":"closed"}'

# Create PR (tea CLI works for this)
tea pulls create --repo mosaic/stack --base develop --head feature/XX-name \
  --title "feat(#XX): Title" --description "Description"

Commit Messages

<type>(#issue): Brief description

Detailed explanation if needed.

Closes #XX, #YY

Types: feat, fix, docs, test, refactor, chore

TDD Requirements

All code must follow TDD. This is non-negotiable.

RED — Write failing test first
GREEN — Minimal code to pass
REFACTOR — Clean up while tests stay green

Minimum 85% coverage for new code.

Token-Saving Tips

Sub-agents die after task — their context doesn't pollute main session
API over CLI when CLI needs TTY or confirmation prompts
One commit with all issue numbers, not separate commits per issue
Don't re-read files you just wrote
Batch similar operations — create all issues at once, close all at once

Key Files

File	Purpose
`CLAUDE.md`	Project overview, tech stack, conventions
`CONTRIBUTING.md`	Human contributor guide
`apps/api/prisma/schema.prisma`	Database schema
`docs/`	Architecture and setup docs

Model-agnostic. Works for Claude, MiniMax, GPT, Llama, etc.

3.5 KiB Raw Blame History