mosaicstack/stack
1
0
Fork 0
Code Issues 82 Pull Requests 1 Actions Packages Projects Releases 15 Wiki Activity

docs(fleet): refine Mosaic Platform PRD per Jason's review (R1–R7)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details

Browse Source 
Post-review refinements to the DRAFT PRD set (decisions D1–D12 unchanged):

- R1: PRD-permission-relay is now self-contained — its cited design source
  (guard-rails-capability-permissions.md) is absent from origin/main, so the
  essential model (prepare-freely/execute-with-approval, permission levels,
  resource:action grants) is folded in as the authoritative spec.
- R2: Phase-1 conversation channel is tmux/CLI via the f4 Phase-1 tmux
  connector (operator issues /remote-control); Matrix room (J5/K1) is Phase 2.
- R3: Jarvis is a Level-0 orchestrator (delegation + subagents, never executes
  coding/infra); AC-NS-8 latency isolation is a separate-model-capacity
  guarantee, not just a separate process (NS-10, AC-NS-8, ASM-5).
- R4: jarvis-brain reframed as the P0 (prototype) Mosaic Stack; tenant-1
  migration targets the proper stack storage layer (vector DB + enhanced
  memory + flat-file backends). Agent memory/runbooks migrate live into the
  memory subsystem and are NOT frozen; repo retires read-only only after both
  PA data and agent memory are verified migrated (X2/X-R7).
- R5: homelab→USC promotion is an explicit owner sign-off gate, not an
  automated metric (X deployment-scope).
- R6: verified K1 is covered by f4-matrix-connector.md Phase 2 (no new doc).
- R7: clarified always-available Opus ≠ standing cost (idle = no bill) (J-R2).
- Also normalized PRD-backlog-providers.md and PRD-webui-fleet-control.md with
  prettier (whitespace-only) — they were non-conformant as originally pushed
  and would have re-broken repo-wide format:check on merge.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMoEx7hfdFGjUiCHuN1RRi
This commit is contained in:
Jason Woltje
2026-07-09 14:50:54 -05:00
parent d1f69bfd37
commit 6b8c3c5d3a
7 changed files with 153 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/fleet/proposals/mosaic-platform-prd/PRD-jarvis-main-agent.md
View File

@@ -7,56 +7,62 @@
Every Mosaic system gets exactly one always-on human-machine-interface agent — default alias **Jarvis**, unit `mosaic-agent@main.service` — that owns the human relationship: conversation, idea development, schedule, email, tasks, knowledge. It delegates all engineering/research/ops work to the orchestrator (**Mos**, `mosaic-agent@orchestrator.service`) through the Mosaic Backlog, and reports fleet status to the user without ever interrupting the orchestrator.
Jarvis is a **Level-0 orchestrator**: it accomplishes its own work through _delegation and subagents_, never by executing coding/infra tasks itself. PA mutations (tasks/events/knowledge) are direct API calls; everything heavier is either a spawned subagent (research, drafting, analysis) or a backlog card handed to Mos (engineering/infra/fleet). This keeps the main agent's context conversational and light.
This solves the observed failure mode: a busy orchestrator that can't respond, accumulates conversational context rot, and derails over time. Post-split, the orchestrator's context is execution-only.
Because Jarvis and Mos are **separate agents with separate model capacity** (D11: Jarvis on Opus, Mos on Fable; independent inference quota), orchestrator load cannot degrade conversational latency — the isolation in AC-NS-8 is a capacity guarantee, not merely a separate process.
## Requirements
### Persona & runtime (J1)
| ID | Requirement |
|---|---|
| J-R1 | Jarvis is provisioned from the personal-assistant persona baseline via system-type profiles (H2/H3); alias, model tier, host, and channel are profile fields, not code. |
| J-R2 | Default model tier **Opus** (ratified D11); the orchestrator's tier is independent. |
| J-R3 | Jarvis survives reboot under systemd (`mosaic-agent@main`), participates in the fleet heartbeat protocol, and is counted in the supervisor's health floor. |
| J-R4 | Persona customization is update-surviving per H4 (override layer wins on merge). |
| ID | Requirement |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| J-R1 | Jarvis is provisioned from the personal-assistant persona baseline via system-type profiles (H2/H3); alias, model tier, host, and channel are profile fields, not code. |
| J-R2 | Default model tier **Opus** (ratified D11); the orchestrator's tier is independent. Always-_available_ ≠ always-_billed_: Opus is provisioned 24/7 but cost is per-interaction — an idle Jarvis (no user turn in flight) incurs no model spend, so "always-on" carries no standing token bill. |
| J-R3 | Jarvis survives reboot under systemd (`mosaic-agent@main`), participates in the fleet heartbeat protocol, and is counted in the supervisor's health floor. |
| J-R4 | Persona customization is update-surviving per H4 (override layer wins on merge). |
### PA toolchain (J2)
| ID | Requirement |
|---|---|
| J-R5 | Jarvis executes personal-assistant mutations **directly** in the user's workspace via the product API: tasks, events/calendar, knowledge entries, ideas, tickets. No delegation for PA ops (ratified D4). |
| ID | Requirement |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| J-R5 | Jarvis executes personal-assistant mutations **directly** in the user's workspace via the product API: tasks, events/calendar, knowledge entries, ideas, tickets. No delegation for PA ops (ratified D4). |
| J-R6 | External PA integrations (email, external calendars, helpdesk) are workspace-scoped integrations with credentials in the product credential vault; actions flagged `requires_approval` route through the permission relay (workstream P). |
| J-R7 | Until tenant-1 migration (X2) completes, Jarvis may read/write the jarvis-brain flat files as a transitional adapter; the adapter is deleted at X2 cutover. |
| J-R7 | Until tenant-1 migration (X2) completes, Jarvis may read/write the jarvis-brain flat files as a transitional adapter; the adapter is deleted at X2 cutover. |
### Delegation contract (J3)
| ID | Requirement |
|---|---|
| J-R8 | The Jarvis→Mos handoff is **only** via Mosaic Backlog cards: goal, acceptance criteria, priority, depends_on, advisory budget. Never via chat messages to the orchestrator. |
| J-R9 | Jarvis translates conversation outcomes into card sets; ambiguity is resolved with the user *before* card creation — the orchestrator receives only decision-complete work. |
| J-R10 | Card authorship is attributed (author=main-agent, ratified-by=user where applicable) for audit. |
| ID | Requirement |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| J-R8 | The Jarvis→Mos handoff is **only** via Mosaic Backlog cards: goal, acceptance criteria, priority, depends_on, advisory budget. Never via chat messages to the orchestrator. |
| J-R9 | Jarvis translates conversation outcomes into card sets; ambiguity is resolved with the user _before_ card creation — the orchestrator receives only decision-complete work. |
| J-R10 | Card authorship is attributed (author=main-agent, ratified-by=user where applicable) for audit. |
| J-R11 | Authority line: Mos holds all execution and merge authority (NS-4). Jarvis relays the user's GO/NO-GO gates as card state, and never acquires fleet mutation, merge, or dispatch rights. |
### Passive observability (J4)
| ID | Requirement |
|---|---|
| ID | Requirement |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| J-R12 | Jarvis answers "what's the fleet doing" from read-only sources: heartbeat files, `mosaic fleet ps` JSON, backlog card states, CI status. Zero messages to the orchestrator for status. |
| J-R13 | Jarvis proactively surfaces to the user: blocked cards, failed CI on user-ratified missions, approval requests pending, budget advisories. (PDA-friendly phrasing per SOUL.md.) |
| J-R13 | Jarvis proactively surfaces to the user: blocked cards, failed CI on user-ratified missions, approval requests pending, budget advisories. (PDA-friendly phrasing per SOUL.md.) |
### Channel (J5)
| ID | Requirement |
|---|---|
| J-R14 | Jarvis's conversation lives in a dedicated Matrix room on the self-hosted homeserver via `OrchestratorConnector(matrix)` (K1). Matrix-first: no Discord channel is created for Jarvis (ratified D1). |
| J-R15 | Multi-platform user reach arrives via mautrix bridges (K2); Jarvis's code path is Matrix-only. |
| ID | Requirement |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| J-R14 | **Phase 2 (target channel):** Jarvis's conversation lives in a dedicated Matrix room on the self-hosted homeserver via `OrchestratorConnector(matrix)` (K1 = f4 Phase 2). Matrix-first: no Discord channel is created for Jarvis (ratified D1). |
| J-R14a | **Phase 1 (interim channel, ratified):** Jarvis runs on the **tmux/CLI connector** — the f4 Phase-1 default connector. The operator launches the `mosaic-agent@main` tmux session and issues `/remote-control` to grant interactive access; this is the day-one conversation surface. No Discord, no Matrix dependency in Phase 1 (keeps D1 intact and unblocks J1–J4 before K1 lands). |
| J-R15 | Multi-platform user reach arrives via mautrix bridges (K2); Jarvis's code path is Matrix-only (from Phase 2 onward). |
## Acceptance criteria
1. AC-NS-8: user converses with Jarvis under full orchestrator load; latency unaffected; orchestrator receives zero conversational traffic.
2. AC-NS-9: a conversationally-agreed mission round-trips (cards → drained → completed → reported by Jarvis) with no chat handoff.
3. Kill the orchestrator mid-conversation: Jarvis conversation is unaffected; Jarvis reports the outage from heartbeat state.
4. `!sys`-equivalent admin verbs work in the Matrix room (status/logs/clear/restart of the main agent).
3. Kill the orchestrator mid-conversation: Jarvis conversation is unaffected; Jarvis reports the outage from heartbeat state. (Directly exercises the separate-capacity guarantee.)
4. `!sys`-equivalent admin verbs work in Jarvis's active channel — the tmux/CLI session in Phase 1, the Matrix room in Phase 2 (status/logs/clear/restart of the main agent).
5. **Phase-1 channel:** operator launches the `mosaic-agent@main` tmux session, issues `/remote-control`, and holds a full conversation with Jarvis over CLI with no Matrix/Discord dependency.
## Non-goals
@@ -67,4 +73,4 @@ This solves the observed failure mode: a busy orchestrator that can't respond, a
## Open items (for Mos's planner)
- Context hygiene: Jarvis's durable memory is the workspace (tasks/knowledge/ideas); define its resume protocol (KICKSTART-equivalent) so `/clear` is cheap. ASSUMPTION: mirror the MOS-KICKSTART two-file pattern until the product grows a native session-resume feature.
- Reconcile the old `apps/api` matrix-bot-sdk workspace bridge with the F4 connector design (one Matrix stack, not two).
- Reconcile the old `apps/api` matrix-bot-sdk workspace bridge with the F4 connector design (one Matrix stack, not two). NOTE (verified 2026-07-09): no matrix dependency remains in `apps/api` on `origin/main` — this item is likely already moot; confirm before K1 build.