Packages and boundaries
Introduction
Section titled “Introduction”The kit is split so that each concern has one home and one direction of dependency. Knowing the layers tells you which package to install, and the ports tell you what you are expected to provide.
Dependency direction
Section titled “Dependency direction”Dependencies point one way: apps, then packages, then chat-protocol. No package imports an app. No environment coupling lives inside a package: clipboard, storage, file access and transport enter through a port the app supplies.
web app desktop app mobile app your host app | | | | +--------------+--------+--------+-----------------+ | @pilotoo/ui (or chat-ui) ---> @pilotoo/chat-core | chat-protocol ^ +---------------------------------------+ | | @pilotoo/server (NestJS) @pilotoo/local-server (SQLite) | | +--------> @pilotoo/agent-runtime <---+| Layer | Packages | Role |
|---|---|---|
| Contract | chat-protocol |
Commands, events, errors and replay as Zod schemas. |
| Client brain | chat-core |
View model, reducers, session, catalog clients and the transport port. |
| Client UI | ui, chat-ui |
ui: DOM components and design tokens. chat-ui: React Native components, also rendered on the web. |
| Runtime | agent-runtime |
Graph factory, tool and skill registries, agent definitions, profiles, providers, knowledge. |
| Server | server, local-server |
The runtime behind a streaming gateway, on PostgreSQL or on SQLite. |
| Voice | voice, voice-native |
Speech, with every engine behind a port. |
Each package is described in Packages.
A port is an interface the kit declares. Out means the kit calls you; in means you call the kit.
| Port | Direction | You provide it when |
|---|---|---|
ChatTransport |
out | Always on the client. The socket.io transport is included. |
ClipboardProvider |
out | You are on mobile, or want something other than the DOM default. |
| Client tool registry | in | Your client serves tools to the agent. |
IdentityResolver |
out | You have your own sign-in. Default: everyone is the local owner. |
| Tool registry | in | Always, to give the agent tools. |
ModelResolver |
out | You need a model the providers do not cover. |
AgentDefinitionSource, AgentDefinitionStore |
out | Your tenants manage agents in your own storage. |
ModelProfileSource |
out | Profiles live outside files. |
SkillSource |
out | You project stored skills into the skill folder. |
KnowledgeSource |
out | The agent should retrieve passages. |
UsageSink |
out | You record token usage. Default: one debug log line per run. |
AttachmentStore |
out | You store attachments yourself. Default: S3 when configured. |
The option for each server-side port is documented in Server.
Two runtime variants
Section titled “Two runtime variants”The same agent-runtime package serves two hosts.
Server gateway (@pilotoo/server). NestJS with a Socket.IO gateway. Checkpoints, the conversation catalog and tenant agents live in PostgreSQL. Profiles, providers, system agents and templates are files in the operator’s folder. Identity comes from the host and scopes every query.
Local backend (@pilotoo/local-server). One process on the user’s machine, started by the desktop shell. The execution backend is the user’s file system and shell, definitions are a directory, identity is a fixed local value, and the transport is a socket to localhost. The client packages cannot tell the difference. See Local backend.