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
//! `reason-network mcp`: the stdio MCP server an agent spawns. A thin client of the daemon.
use crate::{
agent::{self, ClaudeSocket},
client::Link,
config::OFF_HERE,
proto::*,
render,
};
use anyhow::Result;
use rmcp::{
ErrorData as McpError, Peer, RoleServer, ServerHandler, ServiceExt,
handler::server::{router::tool::ToolRouter, wrapper::Parameters},
model::{
CallToolResult, ContentBlock, Implementation, ListToolsResult, PaginatedRequestParams, ServerCapabilities,
ServerConfig,
},
service::RequestContext,
tool, tool_handler, tool_router,
transport::stdio,
};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::Value;
use std::{
sync::{
Arc, Mutex,
atomic::{AtomicBool, Ordering},
},
time::Duration,
};
use tokio::sync::mpsc;
/// How agents should use Reason Network, kept once: in the skill, for agents with the tools and without.
const SKILL: &str = include_str!("skill.md");
fn instructions() -> String {
// Windows checkouts may have turned the file's line ends into \r\n.
let rules = SKILL.split_once("## How to behave").map_or(String::new(), |(_, r)| r.trim().replace('\r', ""));
format!("Reason Network connects you with your teammates' coding agents.\n\n{rules}")
}
#[derive(Debug, Deserialize, JsonSchema)]
pub struct ListArgs {
/// Antigravity: the conversation id supplied by your Reason Network hook. Other agents omit it.
#[serde(default)]
pub session_id: Option<String>,
/// Only sessions matching this text (person, session, agent, repo, branch, directory or what it's doing).
#[serde(default)]
pub filter: Option<String>,
/// Also list sessions that went offline in the last day.
#[serde(default)]
pub all: Option<bool>,
}
#[derive(Debug, Deserialize, JsonSchema)]
pub struct SendArgs {
/// Antigravity: the conversation id supplied by your Reason Network hook. Other agents omit it.
#[serde(default)]
pub session_id: Option<String>,
/// Reuse this key when retrying the same message after a lost response. A new key sends a new message.
#[serde(default)]
pub idempotency_key: Option<String>,
/// "person/session@machine" from list_team; a reply goes to the message's from (with notify, `to` may be your
/// user's name).
pub to: String,
/// The message, with the point in the first line.
pub message: String,
/// Id of the message you are replying to.
#[serde(default)]
pub reply_to: Option<String>,
/// Also pop it up on that person's screen: a heads-up, for when they must act themselves. `to` may then be your
/// own user's name, to reach them.
#[serde(default)]
pub notify: Option<bool>,
/// Paths of text files in your working folder or repository to send with it (markdown, code, JSON, logs, config; no
/// binaries, no hidden files): at most 10, 256 KB each, 512 KB in all. The recipient gets copies.
#[serde(default)]
pub files: Option<Vec<String>>,
}
#[derive(Debug, Deserialize, JsonSchema)]
pub struct DeliveryArgs {
/// Antigravity: the conversation id supplied by your Reason Network hook. Other agents omit it.
#[serde(default)]
pub session_id: Option<String>,
/// Message ids returned by send_message. This checks progress without sending again.
pub ids: Vec<String>,
}
#[derive(Debug, Deserialize, JsonSchema)]
pub struct AskArgs {
/// Antigravity: the conversation id supplied by your Reason Network hook. Other agents omit it.
#[serde(default)]
pub session_id: Option<String>,
/// What they need to decide: who asks for what, and why.
pub question: String,
/// When it's about a teammate's message, its id (the `id="…"` of their `<reason-message>`): your user sees that
/// request in the pop-up, and its sender gets the answer signed by this machine.
#[serde(default)]
pub about: Option<String>,
}
#[derive(Debug, Deserialize, JsonSchema)]
pub struct InboxArgs {
/// Antigravity: the conversation id supplied by your Reason Network hook. Other agents omit it.
#[serde(default)]
pub session_id: Option<String>,
/// If nothing is waiting, wait up to this many seconds for a message (max 600). Default 0.
#[serde(default)]
pub wait_secs: Option<u64>,
}
#[derive(Clone)]
pub struct ReasonNetworkMcp {
link: Arc<Link>,
env_agent: Option<&'static str>,
/// The inbox of the Claude Code session we serve, once known (see [`agent::claude_socket`]).
claude: Arc<Mutex<Option<Arc<ClaudeSocket>>>>,
/// The agent named by the client's `clientInfo`, once known.
client_agent: Arc<Mutex<Option<&'static str>>>,
/// Gemini: it has gone by its hooks' session (so between two conversations, the next is waited for).
hooks_linked: Arc<AtomicBool>,
tool_router: ToolRouter<Self>,
}
pub async fn run() -> Result<()> {
let (tx, mut events) = mpsc::unbounded_channel();
let server = ReasonNetworkMcp {
link: Link::new(Some(tx)),
env_agent: agent::detect_env(),
claude: Default::default(),
client_agent: Default::default(),
hooks_linked: Default::default(),
tool_router: ReasonNetworkMcp::tool_router(),
};
let service = server.clone().serve(stdio()).await?;
let s = server.clone();
tokio::spawn(async move {
while let Some(ev) = events.recv().await {
s.on_event(ev).await;
}
});
// Agents with one MCP process per session get registered up front, so they can receive before their
// first tool call. The pause skips health checks (`claude mcp list`) that connect and leave at once.
let (s, peer) = (server.clone(), service.peer().clone());
tokio::spawn(async move {
tokio::time::sleep(Duration::from_secs(3)).await;
let agent = s.agent(&peer, None);
if agent::multiplexed(agent) || off_here() {
return;
}
let hooks = agent::session_from_hooks(agent);
for _ in 0..if hooks { 40 } else { 0 } {
if s.linked(agent).await.is_some() {
break;
}
tokio::time::sleep(Duration::from_millis(500)).await;
}
match s.session(agent, None).await {
Err(e) => eprintln!("reason-network: registering session: {e:#}"),
// Registered by process after all: once its hooks turn up, it goes by their session.
Ok(key) if hooks && key.starts_with("proc:") => {
for _ in 0..60 {
tokio::time::sleep(Duration::from_secs(2)).await;
if s.linked(agent).await.is_some() {
let _ = s.session(agent, None).await;
break;
}
}
}
Ok(_) => {}
}
});
service.waiting().await?;
Ok(())
}
#[tool_router]
impl ReasonNetworkMcp {
#[tool(
description = "Check your outgoing messages without resending: queued, accepted, handed_to_agent, replied, rejected or expired. Remote agent handoff may be unobserved; accepted does not mean read. Receipts become unknown after seven days.",
annotations(read_only_hint = true, open_world_hint = false)
)]
async fn message_status(
&self,
Parameters(a): Parameters<DeliveryArgs>,
ctx: RequestContext<RoleServer>,
) -> Result<CallToolResult, McpError> {
let key = match self.session_for(&ctx, a.session_id.as_deref()).await {
Ok(key) => key,
Err(e) => return Ok(failure(e)),
};
let result = self
.link
.call::<Value>(Request::DeliveryStatus { from: key.clone(), ids: a.ids })
.await
.map(|v| v.to_string());
Ok(self.finish(&key, result, true).await)
}
#[tool(
description = "List your team's live agent sessions: who, which machine and agent, repo@branch, busy/idle, \
and what each is doing. Use it to find the right recipient.",
annotations(read_only_hint = true, open_world_hint = false)
)]
async fn list_team(
&self,
Parameters(a): Parameters<ListArgs>,
ctx: RequestContext<RoleServer>,
) -> Result<CallToolResult, McpError> {
let key = match self.session_for(&ctx, a.session_id.as_deref()).await {
Ok(k) => k,
Err(e) => return Ok(failure(e)),
};
let req = Request::Who { me: Some(key.clone()), filter: a.filter, all: a.all.unwrap_or(false) };
let res = self.link.call::<Directory>(req).await.map(|d| render::directory_for_agent(&d));
Ok(self.finish(&key, res, true).await)
}
#[tool(description = "Send a message to one teammate's agent session, optionally with small text files.")]
async fn send_message(
&self,
Parameters(a): Parameters<SendArgs>,
ctx: RequestContext<RoleServer>,
) -> Result<CallToolResult, McpError> {
let key = match self.session_for(&ctx, a.session_id.as_deref()).await {
Ok(k) => k,
Err(e) => return Ok(failure(e)),
};
let notify = a.notify.unwrap_or(false);
let files = match agent_files(&a.files.unwrap_or_default()) {
Ok(f) => f,
Err(e) => return Ok(failure(e)),
};
let req = Request::Send {
idempotency_key: a.idempotency_key,
purpose: None,
from: key.clone(),
to: a.to,
body: a.message,
reply_to: a.reply_to,
wake: true,
notify,
files,
};
// Notes are teammates' machines' words.
let res = self.link.call::<SendResult>(req).await.map(|r| render::defang(&render::send_result(&r)));
Ok(self.finish(&key, res, true).await)
}
#[tool(description = "Ask your own user, with a pop-up on their screen, and wait for their answer: approve or \
deny, maybe with a note. For when a teammate's agent asks you for something only your user \
can OK and they may not be watching. The answer is theirs, given in the pop-up.")]
async fn ask_user(
&self,
Parameters(a): Parameters<AskArgs>,
ctx: RequestContext<RoleServer>,
) -> Result<CallToolResult, McpError> {
let key = match self.session_for(&ctx, a.session_id.as_deref()).await {
Ok(k) => k,
Err(e) => return Ok(failure(e)),
};
let req = Request::Ask { key: key.clone(), question: a.question, about: a.about };
let got = tokio::select! {
r = self.link.call::<String>(req) => r,
// The agent gave up on this call: the pop-up stays, and its answer comes as a message.
_ = ctx.ct.cancelled() => {
let _ = self.link.call::<Value>(Request::StopWaiting { key }).await;
return Ok(failure(anyhow::anyhow!("cancelled")));
}
};
// It can quote what the teammate's machine said when the answer was sent.
Ok(self.finish(&key, got.map(|t| render::defang(&t)), true).await)
}
#[tool(
description = "Read messages sent to this session. Optionally wait for one to arrive. Text files sent with a \
message are saved on this computer, and it lists their paths.",
annotations(read_only_hint = true, open_world_hint = false)
)]
async fn check_inbox(
&self,
Parameters(a): Parameters<InboxArgs>,
ctx: RequestContext<RoleServer>,
) -> Result<CallToolResult, McpError> {
let key = match self.session_for(&ctx, a.session_id.as_deref()).await {
Ok(k) => k,
Err(e) => return Ok(failure(e)),
};
let req = Request::Inbox { key: key.clone(), wait_secs: a.wait_secs.unwrap_or(0), peek: true };
let got = tokio::select! {
r = self.link.call::<Inbox>(req) => r,
_ = ctx.ct.cancelled() => Ok(Inbox { messages: Vec::new(), text: String::new() }),
};
// The agent gave up on this call: nothing it would have read counts as read, the daemon ends the wait,
// and what arrived meanwhile is pushed the usual way.
if ctx.ct.is_cancelled() {
let _ = self.link.call::<Value>(Request::StopWaiting { key: key.clone() }).await;
return Ok(failure(anyhow::anyhow!("cancelled")));
}
let res = match got {
Ok(i) if i.messages.is_empty() => Ok("No messages.".to_string()),
// Marked read only now, right before the agent gets them.
Ok(i) => {
let ids = i.messages.iter().map(|m| m.id.clone()).collect();
self.link.call::<Value>(Request::Delivered { key: key.clone(), ids }).await.map(|_| i.text)
}
Err(e) => Err(e),
};
Ok(self.finish(&key, res, false).await)
}
}
#[tool_handler(router = self.tool_router)]
impl ServerHandler for ReasonNetworkMcp {
fn get_info(&self) -> ServerConfig {
ServerConfig::new(ServerCapabilities::builder().enable_tools().build())
.with_server_info(Implementation::new(crate::AGENT_NAME, env!("CARGO_PKG_VERSION")))
.with_instructions(instructions())
}
/// A session that gets its messages pushed never needs check_inbox, so it isn't shown one: fewer tokens.
async fn list_tools(
&self,
_request: Option<PaginatedRequestParams>,
ctx: RequestContext<RoleServer>,
) -> Result<ListToolsResult, McpError> {
let mut tools = self.tool_router.list_all();
if self.pushed(self.agent(&ctx.peer, None)) {
tools.retain(|t| t.name != "check_inbox");
}
Ok(ListToolsResult::with_all_items(tools))
}
}
impl ReasonNetworkMcp {
/// Our Claude Code session's inbox: looked for until found (Claude Code may write its registry entry after it starts
/// us), then kept.
fn claude(&self) -> Option<Arc<ClaudeSocket>> {
let mut known = self.claude.lock().unwrap();
if known.is_none() {
*known = agent::claude_socket().map(Arc::new);
}
known.clone()
}
/// Whether messages reach this session by being pushed into it: Claude Code, through its inbox.
fn pushed(&self, agent: &str) -> bool {
agent == agent::CLAUDE_CODE && self.claude().is_some()
}
/// The agent we serve: the client's `clientInfo` (handshake, or the call's `_meta` on handshake-less
/// protocol versions), else the environment.
fn agent(&self, peer: &Peer<RoleServer>, meta: Option<&serde_json::Map<String, Value>>) -> &'static str {
if let Some(a) = *self.client_agent.lock().unwrap() {
return a;
}
let name = peer
.peer_info()
.map(|i| i.client_info.name.clone())
.or_else(|| meta?.get("io.modelcontextprotocol/clientInfo")?.get("name")?.as_str().map(str::to_string));
match name.as_deref().and_then(agent::from_client_name) {
Some(a) => {
// The explicit Antigravity profile selects its native hook ABI even with a shared Gemini SDK name.
let a = if a == "gemini" && self.env_agent == Some("antigravity") { "antigravity" } else { a };
*self.client_agent.lock().unwrap() = Some(a);
a
}
None => self.env_agent.unwrap_or("agent"),
}
}
async fn session_for(&self, ctx: &RequestContext<RoleServer>, explicit: Option<&str>) -> Result<String> {
let agent = self.agent(&ctx.peer, Some(&ctx.meta));
if agent == "antigravity" {
let id = explicit.map(str::to_string).or_else(|| agent::meta_session_id(&ctx.meta));
let found: Option<String> = match id {
Some(conversation_id) => self.link.call(Request::AntigravitySession { conversation_id }).await?,
None => self.link.call(Request::Attach { agent: agent.into(), cwd: agent::cwd() }).await?,
};
return found.ok_or_else(|| anyhow::anyhow!("Antigravity conversation is not identified. Pass the session_id from this conversation's Reason Network hook; if absent, reload the configured hooks and start a new invocation."));
}
self.session(agent, agent::meta_session_id(&ctx.meta)).await
}
/// Registers the session on first use and returns its key.
async fn session(&self, agent: &'static str, meta_id: Option<String>) -> Result<String> {
if off_here() {
anyhow::bail!(OFF_HERE);
}
if meta_id.is_none() && agent::multiplexed(agent) {
match self.link.call::<Option<String>>(Request::Attach { agent: agent.into(), cwd: agent::cwd() }).await {
Ok(Some(key)) => return Ok(key),
Err(e) if e.to_string() == crate::config::BUSY_OFF => anyhow::bail!(crate::config::BUSY_OFF),
_ => {}
}
}
let mut id = meta_id.or_else(|| agent::env_session_id(agent));
if id.is_none() && agent::session_from_hooks(agent) {
id = self.linked(agent).await;
// Between one conversation's end and the next one's start (`/clear`): the next, a moment.
for _ in 0..if self.hooks_linked.load(Ordering::Relaxed) { 10 } else { 0 } {
if id.is_some() {
break;
}
tokio::time::sleep(Duration::from_millis(500)).await;
id = self.linked(agent).await;
}
// Waited for once per gap: a next conversation that never starts doesn't slow every later call.
self.hooks_linked.store(id.is_some(), Ordering::Relaxed);
}
let key = match &id {
Some(id) => format!("{agent}:{id}"),
None => format!("proc:{}", std::process::id()),
};
let tier = if self.pushed(agent) { Tier::Push } else { Tier::Pull };
// Registered already, unless its inbox has turned up since (Claude Code may list it after starting us).
if self.link.registered_tier(&key).is_some_and(|t| t == Tier::Push || tier != Tier::Push) {
return Ok(key);
}
let reg = SessionReg {
key: key.clone(),
agent: agent.to_string(),
cwd: agent::cwd(),
agent_session_id: id,
// Claude Code's own process, as its registry names it: the daemon's scan of the registry matches it. None
// when that isn't known: any other process (a parent's) would get this session ended as that one moves on.
pid: if agent == agent::CLAUDE_CODE {
agent::claude_pid()
} else if agent::session_from_hooks(agent) {
// The process its hooks name (past a shell), so the two are told to be one.
agent::agent_process()
} else {
Some(agent::agent_pid())
},
tier,
name: None,
};
self.link.register(reg).await?;
Ok(key)
}
/// The session id the hooks of our agent process registered, if any (an older daemon doesn't know the request).
async fn linked(&self, agent: &str) -> Option<String> {
let pid = agent::agent_process()?;
self.link.call::<Option<String>>(Request::Linked { agent: agent.into(), pid }).await.ok().flatten()
}
/// Tool result text, plus a note about unread mail so pull-only agents notice it, and how to join a team on a
/// machine that isn't in one.
async fn finish(&self, key: &str, res: Result<String>, notice: bool) -> CallToolResult {
let join = match self.link.call::<TeamInfo>(Request::Team).await {
Err(e) if e.to_string().contains("not in a team") => Some(join_hint()),
_ => None,
};
match res {
Ok(mut text) => {
if notice
&& let Ok(u) = self.link.call::<Unread>(Request::Unread { key: key.to_string() }).await
&& let Some(n) = render::unread_notice(&u)
{
text.push_str("\n\n");
text.push_str(&n);
}
if let Some(j) = join {
text.push_str("\n\n");
text.push_str(&j);
}
CallToolResult::success(vec![ContentBlock::text(text)])
}
Err(e) => failure(match join {
Some(j) => anyhow::anyhow!("{e:#}\n\n{j}"),
None => e,
}),
}
}
async fn on_event(&self, ev: Event) {
let Event::Deliver { key, ids, text } = ev;
// No inbox to put it in: the daemon takes it back, and doesn't push here again until there is one. Off this
// task, which every push goes through: an older daemon doesn't know the request (its answer is a timeout).
let Some(sock) = self.claude() else {
let link = self.link.clone();
tokio::spawn(async move {
let _ = link.call::<Value>(Request::PushFailed { key, ids }).await;
});
return;
};
match tokio::task::spawn_blocking(move || agent::post_to_claude(&sock, &text)).await {
Ok(Ok(())) => {
let _ = self.link.call::<Value>(Request::Delivered { key, ids }).await;
}
Ok(Err(e)) => eprintln!("reason-network: delivering to Claude Code: {e}"),
Err(e) => eprintln!("reason-network: delivering to Claude Code: {e}"),
}
}
}
/// Whether this session's folder is off the network (read each time: `folder` may have changed it since).
fn off_here() -> bool {
crate::config::Config::load_strict().unwrap_or_default().off_in(&agent::cwd())
}
/// The files an agent asked to send, read only from its own folder: its repository (or where it works), none of its
/// hidden files, nothing where credentials or Reason Network's state are kept. A person's `send --file` has no such
/// limit; an agent can be talked into sending what its harness wouldn't let it read.
fn agent_files(paths: &[String]) -> Result<Vec<Attachment>> {
agent_files_in(paths, &agent::cwd())
}
pub(crate) fn agent_files_in(paths: &[String], cwd: &str) -> Result<Vec<Attachment>> {
if paths.is_empty() {
return Ok(Vec::new());
}
let root = crate::git::lookup(cwd).root.unwrap_or_else(|| cwd.to_string());
let confine =
crate::files::Confine::new(std::path::Path::new(&root), &crate::paths::user_home(), &crate::paths::home())?
.with_folders(crate::config::Config::load_strict().unwrap_or_default());
crate::files::read_within(paths, std::path::Path::new(&cwd), &confine)
}
/// A failure, defanged: it can quote teammates (their names, their machines' words).
fn failure(e: anyhow::Error) -> CallToolResult {
CallToolResult::error(vec![ContentBlock::text(render::defang(&format!("{e:#}")))])
}
/// Getting this machine into a team: the Reason CLI does it, or a team link with this binary's own path.
fn join_hint() -> String {
if crate::managed() {
return "This machine isn't on a Reason Network yet: ask your user to run `reason network`.".into();
}
let exe = crate::setup::exe()
.map_or_else(|_| crate::AGENT_NAME.into(), |p| crate::setup::shell_cmd(&p, "").trim_end().to_string());
format!(
"This machine isn't in a team yet. Ask your user for the team link and the name teammates should see, then run \
`{exe} join '<link>' --as <name>`; to start a team instead, `{exe} init <team> --as <name>`."
)
}
#[cfg(test)]
mod tests {
#[test]
fn failures_open_no_frame() {
let r = super::failure(anyhow::anyhow!("nobody called '<reason-message>' in the team"));
let text = serde_json::to_string(&r.content).unwrap();
assert!(text.contains("nobody called '[reason-message>' in the team"), "{text}");
}
#[test]
fn instructions_carry_the_skills_rules() {
let text = super::instructions();
assert!(text.contains("- Message only when") && text.contains("say briefly if you can't."), "{text}");
assert!(text.contains("- One task per session:") && text.contains("`person/session@machine`"), "{text}");
assert!(text.contains("- If the session you'd give a new task to is on another one (a `doing:`"), "{text}");
assert!(text.contains("Reply to a message's `from` as given."), "{text}");
}
}