Fleet Pi architecture

Fleet Pi is a TanStack Start web app with a Nitro-backed API, a React 19 UI, and a repo-local agent workspace. This page maps the runtime boundaries.

​

Topology

​

Layers

​

Browser client

React 19 with TanStack Router. AgentChat composes InputBar, MessageList, and the right-hand resources and workspace panels. Streaming chat, structured plan cards, and tool cards are rendered with the shared agent-elements integration from packages/hax-design (@workspace/hax-design), the single source of truth for Fleet Pi chat surfaces, the OpenUI kit, and shared Pi protocol types. State management:

• usePiChat orchestrates the NDJSON stream lifecycle, tool rendering, and queued steering / follow-up prompts.
• useChatStorage keeps minimal session metadata (sessionFile, sessionId) in localStorage so a refresh can hydrate the matching Pi session file.

​

apps/web — TanStack Start

The Vite dev server hosts file-based API routes under apps/web/src/routes/api/: Internal modules:

• lib/pi/server.ts — Pi runtime cache, createPiRuntime, queuePromptOnActiveSession, NDJSON encoding.
• lib/pi/server-chat-stream.ts — assistant turn lifecycle (beginAssistantTurn, handleSessionEvent, finalizeAssistantTurn).
• lib/pi/plan-mode.ts — mode allowlists and the plan-mode Pi extension.
• lib/pi/circuit-breaker.ts — opossum configuration around Bedrock invocations.
• lib/pi/run-provenance.ts — provenance recording around session and tool events.
• lib/workspace/server.ts and workspace-contract.ts — durable workspace contract, manifest, and section kinds.
• lib/pii/sanitizer.ts — input redaction before logging.
• lib/logger.ts — Pino logger with redaction and requestId correlation.

​

agent-workspace/

The durable adaptive layer. The workspace server reads memory, plans, skills, and artifacts directly from files so every change shows up in Git diffs. The contract is versioned (WORKSPACE_CONTRACT_VERSION = 1) and the canonical section set is fixed in workspace-contract.ts: instructions/, system/, memory/, plans/, skills/, evals/, artifacts/, scratch/, pi/, indexes/. Sections have kinds — canonical, temporary, or projection — that the workspace server enforces.

​

.pi/

Committed project Pi configuration. settings.json is a compatibility bridge that points Pi at workspace-native resource directories. Built-in Pi extensions and committed skills also live here.

​

External

Fleet Pi calls whichever model provider is configured — Google Gemini by default (gemini-3.5-flash), or any other supported provider (Amazon Bedrock, OpenAI, Anthropic, Mistral, Groq, Vertex, Ollama). Provider selection lives in .pi/settings.json; credentials live in .env. Amazon Bedrock specifically is wrapped by a process-wide opossum circuit breaker (bedrock-api). When you switch Fleet Pi to Bedrock, every Bedrock invocation passes through these settings: When the Bedrock breaker is open, requests fail fast with "Bedrock API is temporarily unavailable due to repeated failures. Please try again later.". Other providers fail through Pi’s standard error path (no breaker), so reliability tuning for non-Bedrock providers happens upstream in @earendil-works/pi-coding-agent. Daytona is an optional external service for authenticated user sandboxes — enabled by setting DAYTONA_API_KEY. See the API reference for the sandbox surface.

​

Packages

Key dependencies: @earendil-works/pi-coding-agent, @earendil-works/pi-ai, @tanstack/react-start, opossum, pino + pino-pretty, zod + @asteasolutions/zod-to-openapi, vitest, @playwright/test, husky + lint-staged. apps/web/src/routeTree.gen.ts is generated. Do not edit by hand.

​

Request lifecycle

1. The browser sends a chat message to /api/chat as JSON.
2. ChatRequestSchema (zod) validates the body.
3. sanitizePii redacts the message before logging.
4. createRequestLogger attaches a correlation requestId.
5. createPiRuntime returns a warm Pi runtime (TTL controlled by FLEET_PI_RUNTIME_TTL_MS) or builds one.
6. The Pi runtime invokes the configured model provider. Bedrock calls go through the opossum circuit breaker; other providers go through Pi’s standard provider path.
7. Events are forwarded as NDJSON via encodeEvent: start, delta, thinking, tool, plan, state, queue, compaction, retry, done, error.
8. createRunProvenanceRecorder records the session lifecycle and tool events.
9. On client refresh, POST /api/chat/resume or GET /api/chat/session hydrates the Pi session file.

​

Related