walrus_protocol/
lib.rs

1//! Walrus wire protocol types shared between gateway and client.
2
3use compact_str::CompactString;
4use serde::{Deserialize, Serialize};
5
6pub mod codec;
7
8/// Current protocol version.
9pub const PROTOCOL_VERSION: &str = "0.1";
10
11/// Messages sent by the client to the gateway.
12#[derive(Debug, Clone, Serialize, Deserialize)]
13#[serde(tag = "type", rename_all = "snake_case")]
14pub enum ClientMessage {
15    /// Send a message to an agent and receive a complete response.
16    Send {
17        /// Target agent identifier.
18        agent: CompactString,
19        /// Message content.
20        content: String,
21    },
22    /// Send a message to an agent and receive a streamed response.
23    Stream {
24        /// Target agent identifier.
25        agent: CompactString,
26        /// Message content.
27        content: String,
28    },
29    /// Clear the session history for an agent.
30    ClearSession {
31        /// Target agent identifier.
32        agent: CompactString,
33    },
34    /// List all registered agents.
35    ListAgents,
36    /// Get detailed info for a specific agent.
37    AgentInfo {
38        /// Agent name.
39        agent: CompactString,
40    },
41    /// List all memory entries.
42    ListMemory,
43    /// Get a specific memory entry by key.
44    GetMemory {
45        /// Memory key.
46        key: String,
47    },
48    /// Request download of a model's files with progress reporting.
49    Download {
50        /// HuggingFace model ID (e.g. "microsoft/Phi-3.5-mini-instruct").
51        model: CompactString,
52    },
53    /// Reload skills from disk.
54    ReloadSkills,
55    /// Add an MCP server to config and reload.
56    McpAdd {
57        /// Server name.
58        name: CompactString,
59        /// Command to spawn.
60        command: String,
61        /// Command arguments.
62        #[serde(default)]
63        args: Vec<String>,
64        /// Environment variables.
65        #[serde(default)]
66        env: std::collections::BTreeMap<String, String>,
67    },
68    /// Remove an MCP server from config and reload.
69    McpRemove {
70        /// Server name to remove.
71        name: CompactString,
72    },
73    /// Reload MCP servers from walrus.toml.
74    McpReload,
75    /// List connected MCP servers and their tools.
76    McpList,
77    /// Ping the server (keepalive).
78    Ping,
79}
80
81/// Messages sent by the gateway to the client.
82#[derive(Debug, Clone, Serialize, Deserialize)]
83#[serde(tag = "type", rename_all = "snake_case")]
84pub enum ServerMessage {
85    /// Complete response from an agent.
86    Response {
87        /// Source agent identifier.
88        agent: CompactString,
89        /// Response content.
90        content: String,
91    },
92    /// Start of a streamed response.
93    StreamStart {
94        /// Source agent identifier.
95        agent: CompactString,
96    },
97    /// A chunk of streamed content.
98    StreamChunk {
99        /// Chunk content.
100        content: String,
101    },
102    /// End of a streamed response.
103    StreamEnd {
104        /// Source agent identifier.
105        agent: CompactString,
106    },
107    /// Session cleared for an agent.
108    SessionCleared {
109        /// Agent whose session was cleared.
110        agent: CompactString,
111    },
112    /// List of registered agents.
113    AgentList {
114        /// Agent summaries.
115        agents: Vec<AgentSummary>,
116    },
117    /// Detailed agent information.
118    AgentDetail {
119        /// Agent name.
120        name: CompactString,
121        /// Agent description.
122        description: CompactString,
123        /// Registered tool names.
124        tools: Vec<CompactString>,
125        /// Skill tags.
126        skill_tags: Vec<CompactString>,
127        /// System prompt.
128        system_prompt: String,
129    },
130    /// List of memory entries.
131    MemoryList {
132        /// Key-value pairs.
133        entries: Vec<(String, String)>,
134    },
135    /// A single memory entry.
136    MemoryEntry {
137        /// Memory key.
138        key: String,
139        /// Memory value (None if not found).
140        value: Option<String>,
141    },
142    /// Download has started for a model.
143    DownloadStart {
144        /// Model being downloaded.
145        model: CompactString,
146    },
147    /// A file download has started.
148    DownloadFileStart {
149        /// Filename within the repo.
150        filename: String,
151        /// Total size in bytes.
152        size: u64,
153    },
154    /// Download progress for current file (delta, not cumulative).
155    DownloadProgress {
156        /// Bytes downloaded in this chunk (delta).
157        bytes: u64,
158    },
159    /// A file download has completed.
160    DownloadFileEnd {
161        /// Filename within the repo.
162        filename: String,
163    },
164    /// All downloads complete for a model.
165    DownloadEnd {
166        /// Model that was downloaded.
167        model: CompactString,
168    },
169    /// Error response.
170    Error {
171        /// Error code.
172        code: u16,
173        /// Error message.
174        message: String,
175    },
176    /// Skills were reloaded successfully.
177    SkillsReloaded {
178        /// Number of skills loaded.
179        count: usize,
180    },
181    /// MCP server added successfully.
182    McpAdded {
183        /// Server name.
184        name: CompactString,
185        /// Tools provided by this server.
186        tools: Vec<CompactString>,
187    },
188    /// MCP server removed successfully.
189    McpRemoved {
190        /// Server name.
191        name: CompactString,
192        /// Tools that were removed.
193        tools: Vec<CompactString>,
194    },
195    /// MCP servers reloaded from config.
196    McpReloaded {
197        /// Connected servers after reload.
198        servers: Vec<McpServerSummary>,
199    },
200    /// List of connected MCP servers.
201    McpServerList {
202        /// Connected servers.
203        servers: Vec<McpServerSummary>,
204    },
205    /// Pong response to client ping.
206    Pong,
207}
208
209/// Summary of a connected MCP server.
210#[derive(Debug, Clone, Serialize, Deserialize)]
211pub struct McpServerSummary {
212    /// Server name.
213    pub name: CompactString,
214    /// Tool names provided by this server.
215    pub tools: Vec<CompactString>,
216}
217
218/// Summary of a registered agent.
219#[derive(Debug, Clone, Serialize, Deserialize)]
220pub struct AgentSummary {
221    /// Agent name.
222    pub name: CompactString,
223    /// Agent description.
224    pub description: CompactString,
225}
walrus_protocol/lib.rs

walrus_protocol/
lib.rs
