packages web server

Web server

Active contributors: Zachary BENSALEM

Purpose

@prime-agent/web-server turns Fleet HTTP requests into operations on the supported Prime Agent connection and maps runtime events back into browser-safe protocol frames. It is the only workspace package that imports the Prime Agent runtime packages. Its package boundary is in web/server/package.json.

The package exports handler functions and the PrimeBridge; it is not a standalone HTTP server. TanStack Start route wrappers in web/app/src/routes/api/ mount those handlers.

Directory layout

web/server/src/
├── prime-bridge.ts              # process-local session coordinator
├── daemon-runtime.ts             # daemon startup, attach, catalog calls
├── event-mapper.ts               # runtime events to ChatStreamEvent
├── handlers/                     # HTTP handler modules
├── project-registry.ts           # project and session assignments
├── prime-agent-presentation.ts   # presentation sidecar persistence
├── managed-plan-presentations.ts # plan sidecar persistence
├── managed-attachments.ts        # uploaded attachment storage
├── pending-dialogs.ts            # dialog promises and cancellation
├── ring-buffer.ts                 # bounded SSE replay
├── sse-replay.ts                 # replay filtering
├── prime-config.ts                # process-wide runtime configuration
└── wrap-api-handler.ts            # shared error envelope

Key abstractions

Abstraction	File	Description
PrimeBridge	web/server/src/prime-bridge.ts	Owns live connections, dispatch, dialogs, replay, forks, and presentation
WebAgentConnection	web/server/src/daemon-runtime.ts	Fleet's wrapper around an AgentConnection
EventMapperState	web/server/src/event-mapper.ts	Session-local transient and presentation mapping state
ProjectRegistry	web/server/src/project-registry.ts	Persists projects and session-to-project assignments
PendingDialogRegistry	web/server/src/pending-dialogs.ts	Keeps extension dialogs alive across SSE requests
RingBuffer	web/server/src/ring-buffer.ts	Bounded, sequence-numbered session event history
wrapApiHandler	web/server/src/wrap-api-handler.ts	Converts failures into sanitized Fleet errors

How it works

graph TD
    Route["web/app API route"] --> Handler["web/server handler"]
    Handler --> Bridge["PrimeBridge"]
    Bridge --> Connection["AgentConnection"]
    Connection --> Daemon["Pinned Prime daemon"]
    Daemon --> Connection
    Connection --> Mapper["event-mapper.ts"]
    Mapper --> Frame["ChatStreamEvent"]
    Frame --> Buffer["RingBuffer"]
    Frame --> Listener["NDJSON / SSE listeners"]

Loading

The first request lazily creates process-local runtime configuration and the bridge. web/server/src/singleton.ts keeps these objects available across Vite server reloads. The daemon is detached from the web process and owns the resident session workers. Fleet reattaches by persisted session path after a web process restart.

The bridge subscribes to the connection, maps events, persists presentation updates, pushes frames to listeners, and stores replayable frames in a per-session buffer. Active turns use the response stream from web/server/src/handlers/chat.ts; out-of-turn updates use web/server/src/handlers/chat-events.ts.

Integration points

• web/app/src/routes/api/ delegates HTTP methods to this package.
• web/protocol/src/ supplies all browser-safe request and response types.
• web/design/src/ renders the resulting messages, tools, panels, and presentation.
• packages/fleet-web/bin/fleet-prime.mjs starts the production bundle.
• The supported upstream AgentConnection and daemon protocol remain behind this package.

Entry points for modification

Add an endpoint in web/server/src/handlers/, export it from web/server/src/index.ts, and add a route wrapper in web/app/src/routes/api/. Change runtime lifecycle or session behavior in web/server/src/prime-bridge.ts; change browser-facing event shapes in web/server/src/event-mapper.ts and web/protocol/src/.

See PrimeBridge, event mapper, and HTTP handlers for focused details.

Key source files

File	Purpose
web/server/src/index.ts	Public server package exports
web/server/src/prime-bridge.ts	Session and stream coordinator
web/server/src/daemon-runtime.ts	Daemon connection lifecycle
web/server/src/event-mapper.ts	Event mapping and sanitization
web/server/src/handlers/	HTTP endpoint implementations
web/server/src/wrap-api-handler.ts	Error mapping and path scrubbing
web/server/src/prime-config.ts	Runtime settings and project registry