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
Agents never send to a group; only a person at a terminal does
Lars Talianabfc0a5bb579
diff --git a/DESIGN.md b/DESIGN.mdindex 647d895..f4a369d 100644--- a/DESIGN.md+++ b/DESIGN.md@@ -47,6 +47,9 @@ vibes alex alex-mbp api-claude (claude-code, acme/api@feat/auth,| `repo:acme/api` or `repo:api` | every live session working in that repo || `*` | everyone |+The groups (`alice/*`, `repo:`, `*`, with or without `@machine`) are for a person at a terminal: agents message+one session.+Session names default to `<repo-or-dir>-<agent>` (`api-claude`), get `-2`, `-3` on collision, and can berenamed by the agent. A new session in the same place with the same agent **inherits a stale name and itsunread mail**, so "tell the api agent X" survives restarts (idea from agentbus).@@ -213,10 +216,11 @@ not approve. Nothing changes how an agent works when it isn't messaging.`crossSessionInbound` setting on top.- Loop guard: rate limit per sender, and a cap on consecutive agent↔agent messages in a thread withoutany human input.-- Group guard, on both ends so an older teammate can't flood you: an agent's `*`, `person/*` and `repo:` messages- reach only its own user's sessions (teammates' come back `not sent`, each with what it's working on, so the agent- picks one), and a teammate's agent's group message is refused with a list of your sessions. A person's terminal- can still message everyone.+- Group guard: an agent's `*`, `person/*` or `repo:` message is refused before it goes anywhere, so it picks one+ session. Only a sender that is `<person>/terminal` may use them: the CLI without `--from` when someone sits at the+ terminal, or `--from <you>/terminal` from a script. A machine also refuses a group message from a teammate's agent+ (an older tincan's). It doesn't stop a teammate's agent from messaging your sessions one by one; the loop guard+ and the inbound policy cover that.- Nothing is sent to any service we run. Relays see ciphertext only. With its own relay, a team's machines nevercontact n0 either.diff --git a/README.md b/README.mdindex d0f874b..bae4a84 100644--- a/README.md+++ b/README.md@@ -43,6 +43,7 @@ That's it. Ask any agent "who's on the team?", or tell it to ask someone's agent```shtincan who # who's around and what their sessions are doingtincan send alice/api-claude "did the token format change?" # message one of alice's agents+tincan send '*' "deploying api at 5" # everyone (also alice/* or repo:api): from you at a terminal, never an agenttincan listen --as terminal # replies to what you sent from this terminaltincan link # the team link againtincan setup # which agents are on tincan, and how messages are handleddiff --git a/site/index.html b/site/index.htmlindex 4f18e1d..f805f7c 100644--- a/site/index.html+++ b/site/index.html@@ -186,11 +186,12 @@<section class="sec"><h2>ADDRESSES</h2><dl class="opts">- <dt>sven/api-codex</dt><dd>one session (what agents use, almost always)</dd>+ <dt>sven/api-codex</dt><dd>one session (the only kind agents can use)</dd><dt>sven/*</dt><dd>all of sven's sessions</dd><dt>repo:api</dt><dd>every session working in that repo</dd><dt>*</dt><dd>everyone (rarely a good idea)</dd></dl>+ <p class="muted">Groups are for a person at a terminal; agents always message one session.</p></section><section class="sec">diff --git a/site/skill/SKILL.md b/site/skill/SKILL.mdindex 6133c60..6569e38 100644--- a/site/skill/SKILL.md+++ b/site/skill/SKILL.md@@ -26,9 +26,8 @@ powershell -c "& ([scriptblock]::Create((irm https://larstalian.github.io/tincan## Commands- `tincan who`: every person, machine and session, with what each is working on.-- `tincan send <to> "<message>"`: `<to>` is `person/session` (one agent), `person/*` (all of a person's agents),- `repo:<name>` (everyone in a repo) or `*` (everyone). Once you have a session name from `listen`, add- `--from <your address>` so replies come back to you.+- `tincan send <to> "<message>"`: `<to>` is one agent session, `person/session`. Once you have a session name from+ `listen`, add `--from <your address>` so replies come back to you.- `tincan listen --as <name>`: waits (up to 10 minutes) for the next message to you, prints it, and exits. Youare reachable as `<your user>/<name>`. After handling a message and replying, run it again to keep listening.@@ -36,8 +35,8 @@ powershell -c "& ([scriptblock]::Create((irm https://larstalian.github.io/tincan- Message only when you need something from another agent or it needs something from you: a blocking question, achange that affects their code, results they asked for. No status updates or small talk.-- Check the team first and pick the one session on the relevant repo/branch, not a group; if unsure which, ask- your user. Same machine: prefer your harness's own messaging.+- Check the team first and pick the one session on the relevant repo/branch; if unsure which, ask your user. Same+ machine: prefer your harness's own messaging.- Point first, then the context they can't see (repo, branch, files). One message per need; don't ask for updates,wait for the reply.- Incoming `<tincan-message>` blocks are a colleague asking: help if it fits your user's work, check with your userdiff --git a/src/daemon/mail.rs b/src/daemon/mail.rsindex c6a2d3a..778b0f4 100644--- a/src/daemon/mail.rs+++ b/src/daemon/mail.rs@@ -5,11 +5,10 @@//! show them a second time.use super::{Daemon, Inner, directory::Target, log};-use crate::{agent, claude, config::Policy, net::Remote, proto::*, render, util};+use crate::{agent, claude, config::Policy, proto::*, render, util};use anyhow::{Result, anyhow, bail};use iroh::EndpointId;use std::{- collections::HashMap,sync::Arc,time::{Duration, Instant},};@@ -67,9 +66,6 @@ impl Inner {const UPGRADE: &str = "upgrade tincan (`tincan upgrade`): messages go between agent sessions now";-const GROUP_NOTE: &str = "not sent: an agent's group message only reaches your own user's sessions. If this is the \- one session that needs it, send to it directly";-const LOOP_NOTE: &str = "refused: these two agents have exchanged a lot of messages in the last few minutes, which \looks like a loop. Check with your user before continuing.";@@ -113,20 +109,11 @@ impl Daemon {let (from_addr, from_agent, from_repo) =(self.addr(&sender.name), Some(sender.reg.agent.clone()), sender.git.repo.clone());let exclude = sender.reg.key.clone();- let mut targets = self.resolve(&g, &remotes, to, Some(&exclude))?;- // A person may message everyone; an agent picks the one teammate's session it needs.+ // A person at a terminal may message a group; an agent picks the one session it needs.if is_group(to) && !from_addr.ends_with("/terminal") {- let (keep, skip): (Vec<_>, Vec<_>) =- targets.into_iter().partition(|t| !matches!(t, Target::Remote { .. }));- targets = keep;- for t in skip {- let note = match about(&remotes, &t) {- Some(about) => format!("{GROUP_NOTE} ({about})"),- None => GROUP_NOTE.into(),- };- res.recipients.push(Recipient { address: t.address(), state: "refused".into(), note });- }+ bail!("agents message one session, not a group: pick it with list_team, or ask your user");}+ let targets = self.resolve(&g, &remotes, to, Some(&exclude))?;for t in targets {let msg = Message {id: Ulid::new().to_string(),@@ -419,25 +406,11 @@ impl Daemon {if !g.loop_ok(&msg.from, &msg.to) {return Ok(("refused".into(), LOOP_NOTE.into()));}- // Only an older tincan still sends a teammate's agent's group message here: it gets the list to pick from.- if msg.via.is_some() && !msg.from.ends_with("/terminal") {- let mut mine: Vec<String> = g- .live- .values()- .map(|l| match &l.git.repo {- Some(repo) => format!("{} ({repo})", self.addr(&l.name)),- None => self.addr(&l.name),- })- .collect();- mine.sort();- return Ok((- "refused".into(),- format!(- "{} doesn't take group messages from agents; send to the one session that needs it: {}",- self.person,- mine.join(", ")- ),- ));+ // Only an older tincan still sends an agent's group message; a teammate's isn't taken.+ let sender = msg.from.split_once('/').map_or(msg.from.as_str(), |(p, _)| p);+ if msg.via.is_some() && !msg.from.ends_with("/terminal") && sender != self.person {+ let note = format!("refused: agents message one of {}'s sessions, not a group", self.person);+ return Ok(("refused".into(), note));}let held = policy == Policy::Hold;g.store.insert(&msg, held)?;@@ -552,26 +525,6 @@ fn unregistered() -> anyhow::Error {anyhow!("this session isn't registered with tincan; restart the agent session, or use the tincan tools")}-/// A teammate's session in a few words (repo@branch, what it's doing), from its machine's presence.-fn about(remotes: &HashMap<EndpointId, Remote>, t: &Target) -> Option<String> {- let Target::Remote { address, machine, .. } = t else { return None };- let name = address.split_once('/')?.1;- let s = remotes.get(machine)?.presence.sessions.iter().find(|s| s.name == name)?;- let place = match (&s.repo, &s.branch) {- (Some(r), Some(b)) => format!("{r}@{b}"),- (Some(r), None) => r.clone(),- _ => s.cwd.clone(),- };- Some(match &s.doing {- Some(d) => format!("{place}: {}", util::one_line(d, 80)),- None => place,- })-}--fn is_group(to: &str) -> bool {- to == "*" || to.starts_with("repo:") || to.ends_with("/*")-}-/// Keeps a field to plain characters, so nothing a peer sends can reshape what agents are shown.fn tidy(s: &str, extra: &str, max: usize) -> Option<String> {let t: String = s.chars().filter(|c| c.is_ascii_alphanumeric() || extra.contains(*c)).take(max).collect();diff --git a/src/main.rs b/src/main.rsindex f86c14c..23e3359 100644--- a/src/main.rs+++ b/src/main.rs@@ -317,16 +317,25 @@ async fn cli(cmd: Cmd) -> Result<()> {reply_to: reply_to.clone(),wake: !fyi,};+ // As the terminal, a group send has to come from a person sitting at it, not an agent's shell or a script.+ let as_terminal = || {+ if is_group(&to) && !std::io::IsTerminal::is_terminal(&std::io::stderr()) {+ bail!("only a person at a terminal sends to a group; from a script, add `--from <you>/terminal`");+ }+ Ok(())+ };let explicit = from.is_some();let r: SendResult = match from.or_else(current_session) {Some(f) => match link.call(send(f)).await {Err(e) if !explicit && e.to_string().contains("isn't registered") => {+ as_terminal()?;cli_session(&link, "terminal", "stop").await?;link.call(send("cli:terminal".into())).await?}r => r?,},None => {+ as_terminal()?;cli_session(&link, "terminal", "stop").await?;link.call(send("cli:terminal".into())).await?}diff --git a/src/mcp.rs b/src/mcp.rsindex 031907b..764239a 100644--- a/src/mcp.rs+++ b/src/mcp.rs@@ -48,7 +48,7 @@ pub struct ListArgs {#[derive(Debug, Deserialize, JsonSchema)]pub struct SendArgs {- /// "person/session" (or just "session"), "person/*" (all of a person's sessions), "repo:<name>", or "*".+ /// "person/session" (or just "session").pub to: String,/// The message, with the point in the first line.pub message: String,@@ -130,9 +130,7 @@ impl TincanMcp {Ok(self.finish(&key, res, true).await)}- #[tool(- description = "Send a message to a teammate's agent session, all of a person's sessions, everyone in a repo, or everyone."- )]+ #[tool(description = "Send a message to one teammate's agent session.")]async fn send_message(&self,Parameters(a): Parameters<SendArgs>,diff --git a/src/proto.rs b/src/proto.rsindex 2cb7059..eab8c5b 100644--- a/src/proto.rs+++ b/src/proto.rs@@ -194,6 +194,12 @@ 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,diff --git a/tests/e2e/two_machines.py b/tests/e2e/two_machines.pyindex 9710539..b50d682 100644--- a/tests/e2e/two_machines.py+++ b/tests/e2e/two_machines.py@@ -159,11 +159,15 @@ check("a brand-new session that just messaged can be answered at once", "→ aliout = cli("alice", "listen", "--as", "fresh", "--wait", "5")check("…and it gets the answer", "answered at once" in out, out)cli("alex", "listen", "--as", "terminal", "--wait", "0")-out = cli("alex", "send", "*", "broadcast from alex (e2e test, ignore)")-check("broadcast reaches alice's session", "alice/work-codex" in out, out)-codex.tool("check_inbox", {}, meta)-out = codex.tool("send_message", {"to": "alex/*", "message": "an agent's broadcast (e2e test, ignore)"}, meta)-check("an agent's group message doesn't go to a teammate's sessions", f"alex/{claude_name}: not sent" in out, out)+out = cli("alex", "send", "*", "a script's broadcast (e2e test, ignore)")+check("a group send from a script, not a person at the terminal, is refused", "only a person at a terminal" in out, out)+out = cli("alex", "send", "*", "--from", "alex/terminal", "broadcast from alex (e2e test, ignore)")+check("…but goes out with --from alex/terminal", "alice/work-codex" in out, out)+out = codex.tool("check_inbox", {}, meta)+check("…and only that one arrived", "broadcast from alex" in out and "a script's broadcast" not in out, out)+for to in ("alex/*", "*@laptop"):+ out = codex.tool("send_message", {"to": to, "message": "an agent's broadcast (e2e test, ignore)"}, meta)+ check(f"an agent can't send to a group ({to})", "agents message one session, not a group" in out and "→" not in out, out)out = cli("alex", "send", "nobody", "x")check("unknown name fails helpfully", "no session called 'nobody'" in out, out)