> ## 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 agent runtime, AI layer, coding agent, and web surface fit together.

Fleet Prime Agent is a stack of layered packages. Each layer has one job and talks to the next through a narrow interface.

## The layers

```mermaid theme={null}
flowchart LR
  web[Qredence web UI] --> server[Web server / adapter]
  server --> coding[Coding agent runtime]
  coding --> agent[Agent runtime]
  agent --> ai[AI layer]
  ai --> providers[19 providers]
```

* **`packages/agent`** — the agent runtime. Defines the event stream (`AgentEvent`), tool interface (`AgentTool`), and protocol contract.
* **`packages/ai`** — the AI layer. Wraps every provider (OpenAI, Anthropic, Bedrock, Gemini, and 15 more) behind a single interface, plus a generated model registry with cost, context window, reasoning support, and thinking levels.
* **`packages/coding-agent`** — the coding-agent runtime. Sessions, tools (`ipython`, shell, edit, grep, find), skills, extensions, refinement, compaction, subagents (`rlm`), CLI, and the daemon protocol all live here.
* **`packages/tui`** — the interactive terminal client.
* **`web/`** — the Qredence UI, its server adapter, its design system, and its wire protocol.

## Key contracts

Everything crosses layers through a small number of typed contracts:

* **`AgentSessionEvent`** — what a session emits: `message_start`, `message_update`, `message_end`, `tool_execution_start`, `tool_execution_update`, `tool_execution_end`.
* **`ChatStreamEvent`** — the NDJSON events the web adapter emits to browsers: `start`, `delta`, `tool`, `thinking`, `plan`, `state`, `queue`, `compaction`, `retry`, `done`, `error`.
* **`AgentMessage`** — the message payload written to session transcripts.
* **`AgentTool`** — the interface every tool implements (`execute`, `prepareArguments`, `beforeToolCall`, `afterToolCall`).
* **Daemon protocol** — `DAEMON_PROTOCOL_VERSION` plus `DAEMON_SCHEMA_REVISION` gate wire changes; new commands must be negotiated as capabilities before use.

See [Streaming protocol](/fleet-prime-agent/concepts/streaming-protocol) for the wire format and [Daemon protocol](/fleet-prime-agent/reference/daemon-protocol) for versioning rules.

## Web app boundary

Only the web server adapter (`web/server/src/event-mapper.ts`) is allowed to import `@earendil-works/*` agent packages. Browser code never imports agent code directly; it consumes `ChatStreamEvent` over NDJSON and `AgentSessionEvent` over SSE, and renders every tool call as a card using the BEUI components in `web/design`.

## What runs where

* **Same process as the CLI:** by default the agent runtime runs in the same Node process as the CLI. Good for scripts and one-shot runs.
* **Daemon:** for long-lived work, run the agent as a daemon. CLI, TUI, and web all attach through `DaemonClient` and share sessions. See [Daemon](/fleet-prime-agent/interfaces/daemon).
* **IPython kernel:** every session gets its own persistent Python kernel provisioned lazily by `prime-agent-runtime`. That kernel is what makes state (variables, open files, network connections) survive across tool calls.
* **Subagents:** `rlm(...)` calls inside a kernel spawn real child agent processes managed by `SubagentRuntimeHost`. See [Subagents (RLM)](/fleet-prime-agent/concepts/rlm-subagents).