Expand description
The wire protocol between byob clients (desktop window, browser tab) and the engine.
Every client, including the in-process desktop window, talks to the engine only through these messages, so the desktop and web UIs can never drift apart. Messages travel as JSON text frames over a WebSocket, or through channels when in-process.
Re-exports§
pub use artifact::Artifact;pub use artifact::ArtifactKind;pub use artifact::ArtifactRef;pub use artifact::ArtifactVersion;pub use connect::Detected;pub use connect::InferenceTest;pub use connect::Link;pub use connect::PRESETS;pub use connect::Preset;pub use connect::Problem;pub use delegation::Delegation;pub use delegation::DelegationState;pub use delegation::DelegationUpdate;pub use env::ContainerEnv;pub use env::EnvAction;pub use env::EnvSupport;pub use env::WorkspaceEnv;pub use media::MediaContent;pub use media::MediaKind;pub use media::MediaRef;pub use plugins::BackendInfo;pub use plugins::Extensions;pub use plugins::PluginAction;pub use plugins::PluginCard;pub use plugins::PluginInfo;pub use plugins::PluginLoadError;pub use plugins::PluginOrigin;pub use plugins::PluginScope;pub use plugins::PluginSetting;pub use plugins::PluginTest;pub use plugins::RendererDecl;pub use plugins::ServerInfo;pub use plugins::ServerState;pub use plugins::SlashItem;pub use plugins::SlashKind;pub use plugins::StarterDecl;pub use profiles::CAP_PROFILES;pub use profiles::ProfileList;pub use profiles::ProfileTest;pub use profiles::ProfileView;pub use queue::ChatQueue;pub use queue::QueuePause;pub use queue::QueuedMessage;pub use sites::LiveView;pub use sites::Site;pub use sites::ViewDecl;pub use sites::ViewRef;pub use usage::ChatUsage;pub use usage::Compaction;pub use version::PROTOCOL_MAJOR;pub use version::PROTOCOL_MINOR;pub use version::Welcome;pub use view::View;pub use view::ViewData;pub use workspace::ChatEndpoint;pub use workspace::ConfigScope;pub use workspace::ConfigView;pub use workspace::FolderList;pub use workspace::NewFolder;pub use workspace::WorkspaceSummary;
Modules§
- artifact
- Artifacts: files the model makes that live beside the conversation — a markdown report, a single-file HTML app, a chart, an image, any other text file — and that are versioned and exportable.
- connect
- Connecting byob to an inference endpoint: the state of the link, why it fails (in words a user can act on), a connection test, local servers found at startup, and presets for common setups.
- delegation
- Subagents: a
delegatetool step runs a child turn with its own context (a task and a system prompt, not the chat’s history). The step carries the child’s live transcript (Delegation);ServerMsg::Delegationstreams changes to it. A child’s tool steps can wait for approval like any other step and are answered with the sameClientMsg::Approve. - env
- Workspace environments as clients see them: whether byob loads the workspace’s own environment (flake.nix, pixi.toml, …), and whether its commands run in a container.
- media
- Media in the conversation: charts and images that tools made, and files users attached.
- plugins
- Plugins as clients see them: what a chat can use, where each plugin comes from, whether it is on, which settings it still needs, and what went wrong loading it.
- profiles
- Model profiles on the wire (13.9+, cap
CAP_PROFILES): the saved models, which role uses which, and what the engine found out about each. - queue
- Message queueing: follow-ups typed while a reply runs.
- sites
- Render sites: where plugins’ live views show in a client (13.3+, cap
CAP_VIEW_SITES). - tree
- The view tree (v1): declarative UI that plugins and the model send as JSON and every client
draws natively with its theme (
docs/views.mdis the authoring guide). - usage
- Context usage of a chat and its compactions.
- version
- Version negotiation and capabilities.
- view
- Open view payloads: something for a client to show that the protocol doesn’t need to know.
- web
- Web surfaces and their bridge (13.5+, cap
CAP_WEB_BRIDGE). - workspace
- Workspaces as clients see them, layered settings (global → workspace → chat), and the engine’s folder browser for picking a workspace folder from a browser.
Structs§
- Ask
- The special part of an approval card (see
Step::ask). - Chat
Cursor - Position in the recent-first chat list, for paging.
- Chat
Summary - A chat as shown in the sidebar.
- Choice
- The choices of a question card (see
Ask::choice). - Diff
Line - One line of a preview’s content or diff.
- Endpoint
Info - Capability summary of the inference endpoint, for a small header detail.
- Engine
State - What clients may know about the engine. Secrets (API keys) never leave the engine.
- Entry
- One message in the conversation as shown to users.
- Profile
- A saved model. Its key is in
secrets.jsonprofile_keys.<id>. - Step
- One tool call inside an assistant reply.
- Turn
Stats
Enums§
- Approval
Answer - A user’s answer to an approval request.
- Client
Msg - Client -> engine.
- Entry
Role - File
Change - A file-system effect of a tool call. Paths are for display (workspace-relative when possible).
- Line
Kind - Notice
Level - Preview
- A readable account of a tool call, built from its (untrusted, bounded) arguments.
- Server
Msg - Engine -> client(s).
- Step
Status - Tool
Access - How dangerous a tool call is; drives the permission gate. Mirrors
byob_tools::Access. - Tools
Mode - How turns pass tools to the model.
Constants§
- MAX_
ANSWER_ CHARS - Longest option or answer text (characters).
- MAX_
CHOICE_ OPTIONS - Most options on a question card.
- MAX_
FRAME_ BYTES - Hard cap on a single incoming frame, so a hostile peer can’t make us allocate unboundedly.
- MAX_
PREVIEW_ LINES - Most lines in a
Preview’s line lists. - MAX_
PREVIEW_ LINE_ CHARS - Most characters in one preview line or value.
Traits§
- Connection
- A client’s link to an engine, in-process or over a WebSocket. Never blocks.