Reason Network: your team's coding agents, talking to each other. The engine behind `reason network`.
Rust agent-to-agentai-agentsclaude-codecodexcoding-agentscursorgrokirohmcpmcp-servermulti-agentpeer-to-peerreason
//! The local API between the daemon and its clients (`reason network mcp`, the CLI, hooks): one JSON object per line
//! over `~/.Reason Network/Reason Network.sock`. Requests carry an `id` and get a [`Reply`] with the same id; a connection that
//! registered sessions also receives [`Event`]s for them.
use serde::{Deserialize, Serialize};
use serde_json::Value;
/// How quickly a session sees a message (ordered fastest first).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Tier {
/// Injected into the conversation right away; wakes the session if it is idle.
Push,
/// Injected at the next tool call or when the turn ends; an idle session waits for its human.
Turn,
/// Seen only when the agent checks its inbox.
Pull,
/// Not on Reason Network: cannot receive.
None,
}
impl Tier {
pub fn as_str(self) -> &'static str {
match self {
Tier::Push => "push",
Tier::Turn => "turn",
Tier::Pull => "pull",
Tier::None => "none",
}
}
pub fn parse(s: &str) -> Tier {
match s {
"push" => Tier::Push,
"turn" => Tier::Turn,
"pull" => Tier::Pull,
_ => Tier::None,
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SessionReg {
/// Stable id for this agent session: `<agent>:<agent's session id>`, or `proc:<pid>` when the agent gives none.
pub key: String,
pub agent: String,
pub cwd: String,
#[serde(default)]
pub agent_session_id: Option<String>,
/// The agent's process, used to match Claude Code's own session registry.
#[serde(default)]
pub pid: Option<u32>,
pub tier: Tier,
#[serde(default)]
pub name: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HookCall {
#[serde(default)]
pub through_reason: Option<bool>,
pub agent: String,
/// `start`, `prompt`, `tool`, `stop`, `end`, or `doing` (only reports what the session is doing).
pub event: String,
pub session_id: String,
#[serde(default)]
pub cwd: Option<String>,
#[serde(default)]
pub pid: Option<u32>,
/// False when this event can't show the agent anything (so mail stays for a later event).
#[serde(default = "yes")]
pub mail: bool,
/// The agent's transcript, which says what the session is doing.
#[serde(default)]
pub transcript: Option<String>,
/// What the session is doing, from agents that say so themselves (the opencode plugin).
#[serde(default)]
pub doing: Option<String>,
/// One of the person's own mailboxes, kept for good: a name they gave with `reason network listen --as` (the
/// terminal always is one). Other `cli` sessions, such as the Reason CLI's one-off ask sessions, are sessions like
/// any other. Older clients leave it out.
#[serde(default)]
pub keep: bool,
/// The session's name, for sessions that pick one (`reason network listen --as`).
#[serde(default)]
pub name: Option<String>,
/// Every folder the agent says the session is in (besides `cwd`): one turned off keeps it off.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub dirs: Vec<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "op", rename_all = "snake_case")]
pub enum Request {
Register {
session: SessionReg,
},
SetStatus {
key: String,
#[serde(default)]
doing: Option<String>,
#[serde(default)]
name: Option<String>,
},
Who {
#[serde(default)]
me: Option<String>,
#[serde(default)]
filter: Option<String>,
#[serde(default)]
all: bool,
},
/// From an agent session: its key (or, for agents that reply through the CLI, its address or name).
Send {
/// Reuse for the same logical send, including after a lost response. Scoped to the sending session.
#[serde(default)]
idempotency_key: Option<String>,
/// Local analytics only; never included in the peer message.
#[serde(default, deserialize_with = "crate::usage::purpose")]
purpose: Option<String>,
from: String,
to: String,
body: String,
#[serde(default)]
reply_to: Option<String>,
#[serde(default = "yes")]
wake: bool,
/// Also pop it up on the person's screen. With it, `to` may be your own user.
#[serde(default)]
notify: bool,
/// Small text files carried in the message (the client reads them from the sender's paths).
#[serde(default)]
files: Vec<Attachment>,
},
/// A session's unread messages. With `peek` nothing is marked read: the client acknowledges with `Delivered`
/// after showing the messages, so nothing is lost if it goes away first.
Inbox {
key: String,
#[serde(default)]
wait_secs: u64,
#[serde(default)]
peek: bool,
},
/// A session's unread messages, counted.
Unread {
key: String,
},
/// Asks this machine's person with a pop-up, for the session `key`, and waits (up to 10 minutes) for the answer.
Ask {
key: String,
question: String,
/// A teammate's message the question is about: shown with it, and sent the answer, signed.
#[serde(default)]
about: Option<String>,
},
/// The client gave up on this session's `Inbox` or `Ask` wait (the agent cancelled it): end it, and push what it
/// was waiting for the usual way.
StopWaiting {
key: String,
},
/// The client injected these messages into its agent's conversation.
Delivered {
key: String,
ids: Vec<String>,
},
/// The client couldn't push these messages into its agent's conversation (it knows no inbox for it): they stay
/// unread.
PushFailed {
key: String,
ids: Vec<String>,
},
/// An agent hook fired (`reason network hook`): keeps hook-only sessions alive and returns mail to inject.
Hook(HookCall),
/// For agents whose MCP calls carry no session id (Cursor, opencode): the hook-known session of this agent
/// that is most likely making the call.
Attach {
agent: String,
cwd: String,
},
/// For agents that give their MCP servers no session id, only their hooks (Gemini): the session id the hooks of
/// agent process `pid` registered, if any.
Linked {
agent: String,
pid: u32,
},
CreateTeam {
name: String,
person: String,
#[serde(default)]
relay: Option<String>,
/// A Reason sign-in proof for this machine: then the name is the proof's.
#[serde(default)]
proof: Option<String>,
},
Join {
ticket: String,
person: String,
#[serde(default)]
proof: Option<String>,
},
/// Attach or refresh this machine's Reason sign-in proof.
Proof {
jws: String,
},
Invite {
#[serde(default)]
me: bool,
#[serde(default = "day")]
hours: u64,
},
Team,
/// Local aggregate counters, read only by clients that opt into usage reporting.
Usage,
/// App-managed Antigravity sidecar subscribes to native delivery events on this connection.
AntigravityAttach,
/// Resolve an explicit native conversation only after its hook registered it.
AntigravitySession {
conversation_id: String,
},
/// Local delivery health, without message contents.
Diagnostics,
/// Delivery progress for this session's own outgoing messages; never returns their bodies.
DeliveryStatus {
from: String,
ids: Vec<String>,
},
/// The team link, which anyone can use to join; `new` replaces it.
Link {
#[serde(default)]
new: bool,
},
/// Remove a person (all their machines) or one machine from the team.
Remove {
who: String,
},
Leave {
/// Leave even if no teammate is online to hear it (they'll need to `reason network remove` this machine).
#[serde(default)]
force: bool,
},
SetRelay {
#[serde(default)]
url: Option<String>,
},
Held,
/// Approve (`release`) or drop held messages; no ids means all of them.
Settle {
#[serde(default)]
ids: Vec<String>,
release: bool,
},
Shutdown,
}
fn day() -> u64 {
24
}
fn yes() -> bool {
true
}
/// `*`, `person/*` or `repo:<name>`, on any machine (`…@machine`): for a person at a terminal, never an agent.
pub fn is_group(to: &str) -> bool {
let to = to.rsplit_once('@').map_or(to, |(s, _)| s);
to == "*" || to.starts_with("repo:") || to.ends_with("/*")
}
#[derive(Debug, Serialize, Deserialize)]
pub struct Frame<T> {
pub id: u64,
#[serde(flatten)]
pub body: T,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct Reply {
pub id: u64,
pub ok: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub result: Option<Value>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error: Option<String>,
/// A proven pre-dispatch send refusal, or a team failure (see [error_code]).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub code: Option<String>,
}
impl Reply {
pub fn ok(id: u64, result: Value) -> Self {
Reply { id, ok: true, result: Some(result), error: None, code: None }
}
pub fn err(id: u64, e: anyhow::Error) -> Self {
let error = format!("{e:#}");
let code = match e.downcast_ref::<SendError>() {
Some(send) => send.not_dispatched.then_some("send_not_dispatched"),
None => error_code(&error),
};
Reply { id, ok: false, result: None, code: code.map(String::from), error: Some(error) }
}
}
/// A send's failure phase comes from its side effects, never from its error text.
#[derive(Debug)]
pub struct SendError {
pub cause: anyhow::Error,
pub not_dispatched: bool,
}
impl std::fmt::Display for SendError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.cause)
}
}
impl std::error::Error for SendError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
// Display already carries the cause's first message; keep the remaining chain without repeating it.
self.cause.source()
}
}
/// The failures a client acts on, by what the message says (as every build says it, a joiner hears an inviting machine's
/// own words): `same_account_needs_owner` when one of the person's own computers should let this one in, `name_taken`
/// when the name is someone else's in the team.
pub fn error_code(error: &str) -> Option<&'static str> {
if error.contains(crate::team::SAME_ACCOUNT) {
Some(crate::team::SAME_ACCOUNT)
} else if error.contains("is already in this team") {
Some("name_taken")
} else {
None
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "event", rename_all = "snake_case")]
pub enum Event {
/// Inject `text` into the conversation of session `key`, then acknowledge with [`Request::Delivered`].
Deliver { key: String, ids: Vec<String>, text: String },
}
/// A person's answer in an `ask_user` pop-up about a teammate's request, signed by the machine they gave it on: it
/// names the request, so it can't be passed off as the answer to another.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Approval {
/// The request (a message id) and the session that sent it.
pub about: String,
pub asker: String,
pub approver: String,
pub approved: bool,
/// What the person saw: the agent's question and the request.
pub question: String,
pub request: String,
pub note: String,
pub at: i64,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Message {
pub id: String,
/// The agent session it came from (`person/session`).
pub from: String,
pub from_agent: Option<String>,
pub from_repo: Option<String>,
/// The resolved recipient address.
pub to: String,
/// The address as the sender typed it, when it was a group (`*`, `repo:api`, `alex/*`).
pub via: Option<String>,
pub reply_to: Option<String>,
pub body: String,
pub wake: bool,
/// Pop it up on the person's screen too (and, sent to your own user rather than a session, only that).
#[serde(default)]
pub notify: bool,
pub sent_at: i64,
/// A person's signed answer to the request this replies to (`ask_user` with `about`).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub approval: Option<Box<crate::team::Signed<Approval>>>,
/// Small text files that came with it. An engine from before files drops this field, so a sender only puts it on
/// a message for a machine whose presence says it takes files.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub files: Vec<Attachment>,
}
/// A small text file carried in a message.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct Attachment {
pub name: String,
/// The text: on the wire, in the outbox and while held. Empty once it is saved in the recipient's inbox folder.
#[serde(default)]
pub content: String,
/// Where it is saved on this computer: only in what the daemon tells its own clients, never taken from a peer.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub path: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Registered {
pub name: String,
pub address: String,
pub unread: u32,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Directory {
pub team: Option<String>,
pub person: String,
pub machine: String,
pub machines: Vec<MachineInfo>,
pub sessions: Vec<SessionInfo>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MachineInfo {
pub person: String,
pub machine: String,
pub endpoint: String,
pub is_me: bool,
pub online: bool,
/// `direct` or `relay` while connected.
pub link: Option<String>,
pub rtt_ms: Option<u64>,
pub last_seen: Option<i64>,
/// The person is verified (it's per person, the same on each of their machines): a machine of theirs carries a
/// Reason sign-in proof for their name, good now.
#[serde(default)]
pub verified: bool,
/// This machine carries such a proof itself.
#[serde(default)]
pub has_proof: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TeamInfo {
/// The team's id, 32 hex digits (the Reason CLI and connector route by it).
#[serde(default, rename = "team_id")]
pub id: String,
pub name: String,
/// `name` again, under the name `team --json` gives it.
#[serde(default)]
pub team_name: String,
pub relay: Option<String>,
/// Whether this machine is on its relay right now (`None` while the network isn't up).
#[serde(default)]
pub relay_connected: Option<bool>,
pub person: String,
pub machine: String,
pub machines: Vec<MachineInfo>,
/// What this engine takes beyond what every version does (`files`), for local clients that pass such things on
/// for others. Older engines leave it out.
#[serde(default)]
pub features: Vec<String>,
/// Per-day totals of messages sent and received on this machine, returned to local clients on the socket: sent
/// once the receiving machine took them, received once in a mailbox here (a held one once approved). For the days
/// (UTC) from six before today to tomorrow that had any. Older engines leave it out.
#[serde(default)]
pub messages: Vec<DayCount>,
/// The UDP port the network is on (`None` while it isn't up). Older engines leave it out.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub udp: Option<UdpPort>,
}
/// The UDP port direct paths come in on, and the one `port` in the config asked for, if any.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct UdpPort {
pub port: u16,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub fixed: Option<u16>,
/// `fixed` couldn't be bound, so `port` is a random one.
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub fell_back: bool,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DayCount {
/// `YYYY-MM-DD`, UTC.
pub day: String,
pub sent: u64,
pub received: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LinkInfo {
pub team: String,
/// A page with the one command to run (the ticket rides in the `#fragment`, which never reaches the server).
pub url: String,
pub ticket: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InviteInfo {
/// Four words, like `plum-tiger-lake-orbit`. For a team with its own relay, the long form (a code would need n0's
/// address lookup to find this machine).
pub code: String,
/// The same invite as a long `rn1-…` string, for when the inviting machine will be offline.
pub ticket: String,
pub hours: u64,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct HookReply {
pub address: Option<String>,
/// Messages to put in the agent's context, framed.
pub text: Option<String>,
/// Their ids, to acknowledge with `Delivered` once shown.
#[serde(default)]
pub ids: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SessionInfo {
pub address: String,
pub name: String,
pub person: String,
pub machine: String,
pub agent: String,
pub cwd: String,
pub repo: Option<String>,
pub branch: Option<String>,
/// `busy`, `idle`, `live` (running, activity unknown) or `offline`.
pub status: String,
/// When `status` last changed (for `offline`: last seen), ms since epoch.
pub since: Option<i64>,
pub doing: Option<String>,
pub tier: Tier,
pub unread: u32,
pub is_me: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SendResult {
pub ids: Vec<String>,
pub recipients: Vec<Recipient>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Recipient {
pub address: String,
/// `pushed`, `queued` or `inbox`.
pub state: String,
pub note: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Inbox {
pub messages: Vec<Message>,
/// The messages framed for an agent's context.
pub text: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Unread {
pub count: u32,
pub from: Vec<String>,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_team_reply_names_the_team_by_id_and_name() {
let t = TeamInfo {
id: "00112233445566778899aabbccddeeff".into(),
name: "vibes".into(),
team_name: "vibes".into(),
relay: None,
relay_connected: None,
person: "alex".into(),
machine: "mbp".into(),
machines: vec![],
features: vec![],
messages: vec![DayCount { day: "2026-10-20".into(), sent: 3, received: 1 }],
udp: Some(UdpPort { port: 41641, fixed: Some(41641), fell_back: false }),
};
let v = serde_json::to_value(&t).unwrap();
assert_eq!(v["team_id"], "00112233445566778899aabbccddeeff");
assert_eq!((v["team_name"].as_str(), v["name"].as_str()), (Some("vibes"), Some("vibes")));
assert_eq!(v["messages"], serde_json::json!([{"day": "2026-10-20", "sent": 3, "received": 1}]));
// A reply from a daemon before these fields still reads.
let old: TeamInfo =
serde_json::from_value(serde_json::json!({"name": "vibes", "relay": null, "person": "alex",
"machine": "mbp", "machines": []}))
.unwrap();
assert_eq!((old.id.as_str(), old.name.as_str()), ("", "vibes"));
assert!(old.messages.is_empty());
assert_eq!(v["udp"], serde_json::json!({"port": 41641, "fixed": 41641}));
assert!(old.udp.is_none());
}
#[test]
fn error_replies_carry_a_code_the_reason_cli_acts_on() {
let reply = |m: &str| serde_json::to_value(Reply::err(7, anyhow::anyhow!(m.to_string()))).unwrap();
assert_eq!(
reply("'alex' is already in this team; join with another name (--as)"),
serde_json::json!({"id": 7, "ok": false, "error": "'alex' is already in this team; join with another name (--as)",
"code": "name_taken"})
);
let same = "only one of alex's own computers lets this one in as alex (same_account_needs_owner)";
assert_eq!(reply(same)["code"], "same_account_needs_owner");
// Anything else, and every success, has none.
assert_eq!(reply("this sign-in proof expired; sign in again").get("code"), None);
assert_eq!(serde_json::to_value(Reply::ok(7, serde_json::json!(1))).unwrap().get("code"), None);
}
#[test]
fn send_codes_follow_the_typed_phase_and_preserve_the_error_chain() {
for not_dispatched in [true, false] {
let cause = anyhow::anyhow!("disk full").context("saving receipt");
let text = format!("{cause:#}");
let error: anyhow::Error = SendError { cause, not_dispatched }.into();
assert_eq!(format!("{error:#}"), text);
let reply = serde_json::to_value(Reply::err(7, error)).unwrap();
assert_eq!(reply["error"], text);
assert_eq!(reply.get("code").and_then(Value::as_str), not_dispatched.then_some("send_not_dispatched"));
}
// A send failure cannot acquire a team or retry code from text in an underlying error.
for text in ["send_not_dispatched", "alex is already in this team", crate::team::SAME_ACCOUNT] {
let error = SendError { cause: anyhow::anyhow!(text), not_dispatched: false };
let reply = serde_json::to_value(Reply::err(7, error.into())).unwrap();
assert_eq!(reply["error"], text);
assert_eq!(reply.get("code"), None);
}
assert_eq!(Reply::err(7, anyhow::anyhow!("send_not_dispatched")).code, None);
}
}