stack/docs/fleet/proposals/mosaic-platform-prd/PRD-jarvis-main-agent.md

PRD — HMI Main Agent ("Jarvis") · Workstream J

Status: DRAFT for ratification · Source of truth once landed: NORTH_STAR.yaml goals J1–J6 Depends on upstream: H2 (system-type profiles), A3a (card lifecycle), B1 (supervisor tick), F4/K1 (Matrix connector) Debate pass 2026-07-09: panel findings folded — see DEBATE-FINDINGS.md for dispositions.

Mission

Every Mosaic workspace 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. 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).
J-R16	Workspace lease (exactly-one fencing): Jarvis acquires workspace_lease(workspace_id, epoch) — a CAS row in product Postgres — before processing any turn. Every PA write, card, and approval carries the epoch; stale-epoch writes are rejected server-side; the connector re-checks the lease immediately before every outbound send. Takeover posts an in-room/in-channel epoch notice. Degraded mode (lease unobtainable) = mute-with-notice, never conversational-while-unfenced. Clean shutdown releases the lease. This primitive also excludes homelab/USC split-brain during adoption.
J-R17	Per-agent spend metering with a daily budget alarm for mosaic-agent@main; a main-agent crash-loop is a distinct, escalated supervisor condition (not a generic restart count).
J-R18	Resume protocol (promoted from open item): resume context is reconstructed from authoritative queries (board, heartbeats, workspace entities), with narrative summary layered on top; a session-start divergence check flags contradictions between narrative and authoritative state. Jarvis is never re-instantiated from its own lossy summaries alone.

PA toolchain (J2a workspace-internal · J2b external)

Split (debate P0 #2): phase-1 Jarvis operates only on workspace-internal entities — no external-write credential path exists until the permission relay (P2) is live. External integrations arrive in phase 2 as J2b, depends_on: [J2a, P2]. Test: in a phase-1 deployment, email:send is impossible (no credential provisioned), not merely unapproved.

ID	Requirement
J-R5	(J2a) Jarvis executes personal-assistant mutations directly in the user's workspace via the product API: tasks, events/calendar, knowledge entries, ideas. No delegation for PA ops (ratified D4).
J-R6	(J2b) External PA integrations (email, external calendars, helpdesk) are workspace-scoped integrations; raw credentials are held exclusively by the gateway — Jarvis receives scoped capability tokens, never provider secrets; 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 after the last verified X-R6 re-point (not at a nominal "X2 cutover" date). A per-phase, per-entity-type source-of-truth table in the J1 profile states which store is authoritative at every moment.
J-R19	Write-side trust rule: externally-sourced content (email bodies, bridged messages, webhook payloads) written into workspace entities or memory inherits source_trust=external transitively through summarization. Standing-instruction-shaped external content requires explicit user ratification before it becomes retrievable. This closes the injection→durable-memory channel.

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.
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. ratified_by=user authorizes dispatch only — it never substitutes for the reviewer-of-record merge gate.
J-R20	Card sets are drafted then published atomically with client idempotency keys (no partial card sets on crash). Card spec is immutable after publish; changes arrive as typed, ordered amendments with a revision counter; reviewer sign-offs pin the spec revision; scope-expanding amendments re-enter ratification.
J-R21	needs-decision lifecycle: a worker hitting genuine ambiguity sets needs-decision(question, options) on the card with a durable checkpoint (pushed branch + card note) — resume after days is a re-dispatch, not a context continuation. Jarvis relays the question to the user and writes the answer back as an amendment. This is the sanctioned clarification path; J-R8's no-chat rule stands.
J-R22	Jarvis-authored cards draw from a priority budget (quota per priority class per window) — priority inflation by the card author degrades the field for the whole fleet and is structurally capped, not policed by review.

Passive observability (J4)

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.) Delivered via the J6 event/wake router — per-agent polling is forbidden.
J-R23	Event/wake router (J6): one shared, level-triggered reconciler over durable state (heartbeats, card states, approval queue) wakes Jarvis on state change with hysteretic per-condition suppression (wake once, then only on change or declared backoff; suppression survives restarts). Wake turns are templated — fixed instruction frame, workspace data only in delimited, provenance-tagged data fields (closes the injection→system-role channel). Idempotent on source event id via the shared consumed-events table. Router is in the health floor; its cost model and latency bound are stated in the J6 card. Reconciles J-R2: an idle Jarvis costs nothing because waking is event-driven, not poll-driven.

Channel (J5)

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 (made measurable): distinct credential/quota pools for Jarvis and Mos are pinned in the J1 profile; scripted suite of ≥30 interleaved turns under full orchestrator load; TTFT p95 ≤ 1.2× idle baseline with bootstrap CI; 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. (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.
6. Fencing: start a second mosaic-agent@main by hand — it fails to acquire the workspace lease, posts a notice, and stays mute; zero duplicate writes or cards reach the workspace (J-R16).
7. Phase-1 credential surface: audit of a phase-1 install finds no external-provider credential readable by the Jarvis runtime (J2a/J2b split holds by construction).

Non-goals

• Jarvis executing code/infra changes (that is Mos + fleet).
• Horizontal sharding of the main agent (rejected in the Matrix charter: split-brain).
• Per-workspace fleets (post-MVP per ASM-6).

Open items (for Mos's planner)

• Context hygiene / resume protocol — promoted to J-R18 by the 2026-07-09 debate pass.
• 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.