168 lines
6.8 KiB
Markdown
168 lines
6.8 KiB
Markdown
# 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 |
|