Documentation Index
Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt
Use this file to discover all available pages before exploring further.
crates/protocol is the public contract for Pioneer. It defines the JSON-RPC envelopes, method names, request payloads, response payloads, notification payloads, domain DTOs, and generated JSON Schema documents.
Clients should depend on the protocol, not on gateway internals. The gateway may reorganize storage, scheduling, or runtime code without changing how clients call turn/start, listen for item/completed, install MCP servers, or update provider keys.
This crate is the line between “implementation” and “product API.” If a field appears here, desktop, future mobile apps, custom clients, tests, and generated schemas can start depending on it.
Why This Layer Exists
Pioneer is designed to support more than one client. The desktop app is first, but the gateway should also be usable from mobile clients, CLIs, automation scripts, and third-party protocol clients. That only works if the public API is explicit and generated from one source of truth. The protocol crate also prevents accidental coupling. A client should not importpioneer-crud to understand a turn. It should receive Turn, TurnItem, and notification payloads from pioneer-protocol.
Transport Contract
Pioneer uses JSON-RPC 2.0 over WebSocket. Requests have a method name frompioneer_protocol::constants::methods, an id, and typed params. Responses return either a typed result or a JSON-RPC error. Notifications use method names from pioneer_protocol::constants::events and have no response id.
RequestId is a typed protocol value with fixed length validation. This avoids treating client correlation ids as arbitrary unbounded strings.
Method Groups
| Group | Examples |
|---|---|
| Workspaces | workspace/list, workspace/create, workspace/default |
| Threads | thread/start, thread/get, thread/history, thread/tree, folder operations |
| Turns | turn/start, turn/cancel, turn/get, turn/items, turn/timeline |
| Providers | provider/list, provider/models/list, provider/set_api_key, provider/delete_api_key |
| Skills | skills/list, skills/install, skills/update, skills/uninstall, skills/health, upload and policy methods |
| MCP | mcp/list, mcp/install, mcp/policy/set, mcp/server/restart, mcp/uninstall, mcp/server/details |
| Tasks | task/create, task/get, task/list, task/tree, task/events, task/wait, task/cancel, task/reschedule, task/detach, task/pause, task/resume, task/agenda, task/deliveries |
Notification Groups
The protocol includes notifications for thread changes, turn lifecycle, item lifecycle, tool retry and recovery, context compression, skills changes, MCP status/catalog changes, task events, delivery state, and write locks. The gateway treats durable agent events as the source for many notifications. A client can render live progress without knowing whether an event originated from the provider stream, a built-in tool, an MCP tool, a skill runtime tool, or the task scheduler.Schema Generation
Protocol schemas are generated from Rust types and written underschemas/. The schema export helpers live in the protocol crate. When a protocol type changes, the Rust type and generated schema should be updated together.
The architecture goal is simple: API review should happen at the protocol boundary. If a type is client-visible, it belongs in crates/protocol. If it is only used by one implementation layer, keep it in that layer.
Versioning Discipline
The current project is still early, so breaking protocol changes can happen. Even so, developers should treat field names, enum variants, method constants, and notification payloads as user-facing architecture. A storage refactor should not force a protocol change unless the product behavior changes too.Change Guidelines
When changing protocol types, ask three questions:- Is this field truly client-visible, or is it an implementation detail?
- Does the gateway have enough information to populate it consistently?
- Does the schema output need to change together with the Rust type?
Related Pages
- Gateway explains where protocol methods are dispatched.
- Persistence Layer explains how protocol-visible state maps to durable records.
- Tasks And Subagents, MCP Architecture, and Skills Architecture explain large protocol surfaces.