> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the Fleet Prime Agent browser UI, web server, PrimeBridge, and the pinned upstream Prime Agent runtime fit together.

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

```
browser ─ EventSource/fetch ─▶ TanStack Start (web/app /api routes)
                                   │  thin wrappers
                                   ▼
                         web/server handlers
                                   │
                                   ▼
                              PrimeBridge
                                   │  daemon client and Fleet session registry
                                   ├─ sessions: Map<sessionId, BridgeSession>
                                   ├─ ringBuffers: Map<sessionId, RingBuffer>   (500 frames)
                                   ├─ pendingDialogs: PendingDialogRegistry     (60s timeout)
                                   └─ kernelReady: Promise<void>
                                             │
                                             ▼
                              prime-agent daemon/runtime
                                   ├─ daemon session create/resume ─▶ AgentSession
                                   ├─ daemon session catalog ─▶ JSONL transcripts
                                   └─ managed IPython kernel
```

## Layers

| Layer     | Location                                  | Role                                                                                                          |
| --------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Interface | `web/app` (TanStack Start) + `web/design` | Routes, chat UI, tool cards, design system. Talks HTTP only.                                                  |
| Contract  | `web/protocol`                            | `chat-protocol.ts` stream frames and the Fleet contract types shared by browser and server.                   |
| Adapter   | `web/server`                              | `prime-bridge.ts`, `event-mapper.ts`, and the HTTP handlers. The only web package that imports `prime-agent`. |
| Engine    | pinned `prime-agent` package              | Sessions, tools, providers, daemon protocol, IPython kernel.                                                  |
| Launcher  | `packages/fleet-prime`                    | The `fleet-agent` binary: resolves the pinned runtime and serves the production web bundle.                   |

Two boundary rules keep the layers honest:

* Browser code (`web/app`, `web/design`) 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`, a ring buffer of the last 500 stream frames for SSE replay, and a pending-dialog registry with a 60-second timeout. It binds an `ExtensionUIContext` per session so engine-side `confirm`/`select`/`input` dialogs become `tool-Question` frames that the browser answers through `POST /api/chat/question`, and `notify`/`setStatus`/`setWidget` become `state` frames.

`event-mapper.ts` is a pure function from engine `AgentSessionEvent`s to browser-safe `ChatStreamEvent`s. 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 runtime with `--mode daemon`. If the socket is owned by a daemon that is not the pinned version, 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 engine CLI directly.
* 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 upstream package, version, tarball URL, and SHA-256. `packages/fleet-prime` and `web/server` consume the same pinned tarball. Upstream source is never vendored or patched inside this repository. See [Runtime pin and releases](/fleet-prime-agent/guides/upgrading-the-runtime).