# PRD: MS22 Phase 2 — Named Agent Fleet ## Metadata - Owner: Jason Woltje - Date: 2026-03-04 - Status: in-progress - Mission: ms22-p2-named-agent-fleet-20260304 - Design Doc: `docs/design/MS22-DB-CENTRIC-ARCHITECTURE.md` - Depends On: MS22 Phase 1 (DB-Centric Architecture) — COMPLETE --- ## Problem Statement Mosaic Stack has the infrastructure for per-user containers and a knowledge layer, but no predefined agent personalities. Users start with a blank slate. For Jason's personal use case, the system needs named agents — jarvis, builder, medic — with distinct roles, personalities, and tool access that can collaborate through the shared knowledge layer and respond in dedicated Discord channels. Currently: - No agent registry exists in the database - No per-agent model configuration is possible - Discord channels are not routed to specific agents - Chat routing is model-agnostic (no agent context) --- ## Scope ### In Scope - `AgentTemplate` and `UserAgent` Prisma models - Admin CRUD endpoints for managing agent templates - User agent CRUD endpoints for personal agent instances - Agent chat proxy routing (select agent by name) - Discord channel → agent routing (#jarvis, #builder, #medic-alerts) - WebUI agent selector and agent detail view - Unit tests and E2E verification ### Non-Goals - Matrix observation rooms - Cross-agent quality gates - Team/multi-user agent sharing - Agent-to-agent communication - Token metering per agent --- ## User Stories ### US-001 As Jason, I can list my available agents in the WebUI so I know what's configured. ### US-002 As Jason, I can select an agent and chat with it directly via WebUI. ### US-003 As Jason, I can send a message in #jarvis on Discord and Jarvis responds. ### US-004 As Jason, I can send a message in #builder on Discord and Builder responds. ### US-005 As Jason, I can send a message in #medic-alerts and Medic responds. ### US-006 As an admin, I can create, update, and delete agent templates. ### US-007 As Jason, I can customize an agent's personality without affecting the shared template. ### US-008 As Jason, I can see which agents are active vs inactive at a glance. --- ## Functional Requirements - FR-1: The system SHALL provide an `AgentTemplate` model with: name, displayName, role, personality, primaryModel, fallbackModels, toolPermissions, discordChannel, isActive, isDefault - FR-2: The system SHALL provide a `UserAgent` model that extends or customizes an AgentTemplate per user - FR-3: The system SHALL seed three default templates on startup: jarvis (orchestrator/opus), builder (coding/codex), medic (monitoring/haiku) - FR-4: Admin endpoints SHALL exist at `GET/POST/PATCH/DELETE /admin/agent-templates` protected by AdminGuard - FR-5: User agent endpoints SHALL exist at `GET/POST/PATCH/DELETE /agents` protected by AuthGuard - FR-6: Agent status endpoints SHALL return active/inactive state per agent for the authenticated user - FR-7: The chat proxy SHALL route messages to the correct agent based on agent name or ID in the request - FR-8: Incoming Discord messages in a configured channel SHALL be routed to the matching agent - FR-9: The WebUI SHALL display a list of available agents with role, model, and status - FR-10: The WebUI SHALL allow selecting an agent and opening a chat session with it --- ## Non-Functional Requirements - All API endpoints must pass NestJS ValidationPipe (value imports for DTOs, not `import type`) - All new modules must be registered in `app.module.ts` - Prisma schema changes must include a migration file - Code must pass `pnpm turbo run lint typecheck build` before merge - Tests must pass `pnpm turbo run test` with no regressions - No direct pushes to main — PR + squash merge only --- ## Acceptance Criteria - [ ] `AgentTemplate` and `UserAgent` tables exist in production DB after migration - [ ] `GET /admin/agent-templates` returns jarvis, builder, medic (seeded) - [ ] `POST /admin/agent-templates` creates a new template (admin only, 403 for non-admin) - [ ] `GET /agents` returns the authenticated user's agents - [ ] `POST /agents` creates a user agent from a template - [ ] `GET /agents/:id/chat` proxies to the correct agent - [ ] Discord message in #jarvis channel routes to jarvis agent and responds - [ ] Discord message in #builder channel routes to builder agent and responds - [ ] WebUI shows agent list with name, role, model, status - [ ] WebUI allows selecting an agent and sending a message - [ ] All CI checks green on main after final PR merge --- ## Technical Considerations - DTOs must use value imports (never `import type`) for NestJS ValidationPipe compatibility — see MEMORY.md - `AgentTemplate.fallbackModels` and `toolPermissions` are stored as `Json` (Prisma) — treat as `string[]` in TypeScript - Discord routing requires mapping `discordChannel` string to a channel ID in OpenClaw config - Chat proxy must be stateless — agent selection passed per-request - Use `AdminGuard` from `src/auth/guards/admin.guard` for admin endpoints (existing pattern) - Use `AuthGuard` from `src/auth/guards/auth.guard` for user endpoints (existing pattern) --- ## Risks / Open Questions | Risk | Likelihood | Mitigation | | ------------------------------------------------------------ | ---------- | ------------------------------------------------- | | Discord channel ID mapping not yet configured in OpenClaw | Medium | Manual config step; document in MISSION-MANIFEST | | Agent routing adds latency to chat proxy | Low | Agent lookup is a single DB read; cache if needed | | `exactOptionalPropertyTypes` TS strictness on Prisma creates | Medium | Use conditional spread for optional fields | | Seed idempotency failure (duplicate name) | Low | Use `upsert` — already implemented | --- ## Success Metrics / Testing - Unit tests cover: AgentTemplateService CRUD, UserAgentService CRUD, chat routing logic - E2E test: send Discord message in #jarvis → verify response comes from jarvis agent - Manual smoke test: WebUI agent selector loads, chat works with selected agent - CI pipeline green on all three apps (api, web, orchestrator) --- ## Milestones / Delivery | Milestone | Tasks | Status | Target | | ----------------- | -------------- | ----------------------- | ---------- | | M1: Schema + Seed | P2-001, P2-002 | ✅ done (PR #675, #677) | 2026-03-04 | | M2: Admin CRUD | P2-003 | ✅ done (PR #678) | 2026-03-04 | | M3: User CRUD | P2-004 | ⬜ next | 2026-03-05 | | M4: Agent Routing | P2-005, P2-006 | ⬜ pending | 2026-03-05 | | M5: Discord + UI | P2-007, P2-008 | ⬜ pending | 2026-03-06 | | M6: Verification | P2-009, P2-010 | ⬜ pending | 2026-03-06 |