Skip to main content
Fleet Prime Agent is an independent UI and product layer over the external, TUI-first Prime Agent runtime. The web stack is the interface; the stock upstream prime-agent package is the execution engine.

Process boundary

Layers

Two boundary rules keep the layers honest:
  • Browser code (web/app) never imports prime-agent. It consumes web/protocol contracts over HTTP (NDJSON and SSE) only.
  • web/server owns the daemon connection, event mapping, session attachment, pending dialogs, and replay buffers.

PrimeBridge

PrimeBridge in web/server is the daemon client and Fleet session registry. Per session it keeps a BridgeSession and a ring buffer of the last 500 stream frames for SSE replay. On the Rust daemon, Fleet does not bind the engine’s extension UI, so engine-side confirm/select/input dialogs and notify/setStatus/setWidget updates do not reach the browser. The browser answers any tool-Question frame automatically with a skip. event-mapper.ts is a pure function from engine AgentSessionEvents to browser-safe ChatStreamEvents. Unknown engine events are ignored with a compile-time exhaustiveness tripwire until Fleet defines a presentation for them.

The daemon

web/server connects to the engine through the upstream daemon rather than in-process calls. On startup it probes the default daemon socket and, if needed, spawns the pinned Rust runtime with --mode daemon. If the socket is owned by a daemon that is not a Rust daemon with the pinned protocol, the server refuses to attach and reports the mismatch instead of silently using an incompatible engine.

The launcher

fleet-agent (alias fleet-prime) is a small Node wrapper:
  • fleet-agent [--host <host>] [--port <port>] serves the production web bundle on 127.0.0.1:3000 by default and sets PRIME_AGENT_WORKSPACE_ROOT to the directory you launched from.
  • fleet-agent agent <args> runs the pinned Prime Agent Rust binary directly.
  • Before either mode starts, it downloads and verifies the pinned runtime if it is not already cached, unless FLEET_PRIME_AGENT_BIN points at another binary.
  • If the production bundle is missing but a source checkout with dependencies exists, it falls back to the Vite dev server with a warning.

Runtime pin

PRIME_AGENT_RUNTIME.json records the pinned Rust runtime version with per-platform archive and executable SHA-256 checksums, plus the upstream npm package tarball and SHA-256 that packages/fleet-web and web/server depend on. Upstream source is never vendored or patched inside this repository. See Runtime pin and releases.
Last modified on November 8, 2026