Skip to content

Reason Network: your team's coding agents, talking to each other. The engine behind `reason network`.

Agents reach one of a teammate's sessions, not all of them

Sven Myhrecdde7f1acc53
diff --git a/DESIGN.md b/DESIGN.md
index 092a96a..99ebb14 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -213,6 +213,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 without
any human input.
+- Fan-out guard, on both ends so an older or looser teammate can't flood you: an agent's `*`, `person/*` and
+ `repo:` messages reach only its own user's sessions (`send.groups = "team"` to allow more); teammates' group
+ messages are refused with a list of your sessions (`inbound.groups`); and one of their agents may start talking
+ to only one of your sessions in ten minutes, past that it's held (`inbound.fanout`). Replies and a person's
+ terminal don't count.
- Nothing is sent to any service we run. Relays see ciphertext only. With its own relay, a team's machines never
contact n0 either.
@@ -274,7 +279,10 @@ edits): Claude Code plugin or `claude mcp add --scope user` + hooks, `~/.codex/c
| `lan` | `true` | find teammates on the local network (mDNS) |
| `auto_update` | `true` | install new releases when they come out (checked every few hours) |
| `reason` | `false` | list your live Reason sessions (set by `tincan setup`) |
+| `send.groups` | `own` | where an agent's group messages go: `own` sessions or the whole `team` |
| `inbound` | accept | see above |
+| `inbound.groups` | `refuse` | teammates' agents' group messages: `accept`, `hold` or `refuse` |
+| `inbound.fanout` | `1` | how many of your sessions one teammate's agent may start talking to in ten minutes |
## Troubleshooting
diff --git a/src/config.rs b/src/config.rs
index 67dafc3..3b6440a 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -20,15 +20,36 @@ pub struct Config {
pub reason: bool,
/// Install new releases when they come out (the daemon checks every few hours).
pub auto_update: bool,
+ pub send: Outbound,
pub inbound: Inbound,
}
+/// What this machine's agents may send.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(default)]
+pub struct Outbound {
+ pub groups: Groups,
+}
+
+/// Where an agent's `*`, `person/*` and `repo:` messages go: `own` sessions only, or the whole `team`. A person
+/// sending from a terminal always reaches the team.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Groups {
+ #[default]
+ Own,
+ Team,
+}
+
/// What happens to messages from teammates' agents: `accept` delivers them, `hold` waits for you to approve
-/// (`tincan held`), `refuse` bounces them.
+/// (`tincan held`), `refuse` bounces them. `groups` is for their `*`, `<you>/*` and `repo:` messages, and `fanout`
+/// is how many of your sessions one of their agents may start talking to in ten minutes (past that they're held).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct Inbound {
pub default: Policy,
+ pub groups: Policy,
+ pub fanout: usize,
pub people: BTreeMap<String, Policy>,
}
@@ -51,6 +72,7 @@ impl Default for Config {
tray: true,
reason: false,
auto_update: true,
+ send: Outbound::default(),
inbound: Inbound::default(),
}
}
@@ -58,7 +80,7 @@ impl Default for Config {
impl Default for Inbound {
fn default() -> Self {
- Inbound { default: Policy::Accept, people: BTreeMap::new() }
+ Inbound { default: Policy::Accept, groups: Policy::Refuse, fanout: 1, people: BTreeMap::new() }
}
}
diff --git a/src/daemon/mail.rs b/src/daemon/mail.rs
index 7615566..e62b27d 100644
--- a/src/daemon/mail.rs
+++ b/src/daemon/mail.rs
@@ -4,11 +4,18 @@
//! with `Delivered`. Messages handed to a push channel are "in flight" meanwhile, so the inbox and hooks don't
//! show them a second time.
-use super::{Daemon, Inner, directory::Target, log};
-use crate::{agent, claude, config::Policy, proto::*, render, util};
+use super::{Daemon, Inner, Talked, directory::Target, log};
+use crate::{
+ agent, claude,
+ config::{Groups, Policy},
+ net::Remote,
+ proto::*,
+ render, util,
+};
use anyhow::{Result, anyhow, bail};
use iroh::EndpointId;
use std::{
+ collections::HashMap,
sync::Arc,
time::{Duration, Instant},
};
@@ -66,6 +73,9 @@ 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 (`send.groups` in \
+ ~/.tincan/config.toml). 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.";
@@ -109,7 +119,19 @@ 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 targets = self.resolve(&g, &remotes, to, Some(&exclude))?;
+ let mut targets = self.resolve(&g, &remotes, to, Some(&exclude))?;
+ if is_group(to) && !from_addr.ends_with("/terminal") && self.cfg.send.groups == Groups::Own {
+ 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 });
+ }
+ }
for t in targets {
let msg = Message {
id: Ulid::new().to_string(),
@@ -137,6 +159,8 @@ impl Daemon {
("queued".into(), "queued: the session is offline; delivered when it is back".into())
}
Target::Remote { machine, machine_name, online, .. } => {
+ // So that their answer to it doesn't count against their fan-out here.
+ fanout_ok(&mut g.talked, &msg.from, &msg.to, usize::MAX);
g.store.outbox_add(&machine.to_string(), &msg)?;
remote_jobs.push((res.recipients.len(), machine, machine_name.clone(), online, msg.clone()));
(
@@ -402,9 +426,38 @@ impl Daemon {
if !g.loop_ok(&msg.from, &msg.to) {
return Ok(("refused".into(), LOOP_NOTE.into()));
}
- let held = policy == Policy::Hold;
+ let group = msg.via.is_some() && !msg.from.ends_with("/terminal");
+ if group && self.cfg.inbound.groups == Policy::Refuse {
+ 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(", ")
+ ),
+ ));
+ }
+ let fanout = fanout_ok(&mut g.talked, &msg.from, &msg.to, self.cfg.inbound.fanout);
+ let held = policy == Policy::Hold || (group && self.cfg.inbound.groups == Policy::Hold) || !fanout;
g.store.insert(&msg, held)?;
match key {
+ _ if held && !fanout => (
+ "held".into(),
+ format!(
+ "held until {} approves it: this agent already started talking to another of their sessions in \
+ the last few minutes",
+ self.person
+ ),
+ ),
_ if held => ("held".into(), format!("held until {} approves it", self.person)),
Some(key) => self.deliver(&mut g, &key, vec![msg.clone()], msg.wake),
None => ("queued".into(), "queued: the session is offline; delivered when it is back".into()),
@@ -515,6 +568,39 @@ 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,
+ })
+}
+
+/// Records a message between agents on different machines; false if it would make `from` reach more than `limit`
+/// sessions in `LOOP_WINDOW`. Answering someone who wrote first, and a person's terminal, don't count.
+fn fanout_ok(talked: &mut Talked, from: &str, to: &str, limit: usize) -> bool {
+ let terminal = from.ends_with("/terminal") || to.ends_with("/terminal");
+ let answer = talked.get(to).is_some_and(|q| q.iter().any(|(t, p)| p == from && t.elapsed() < LOOP_WINDOW));
+ let q = talked.entry(from.to_string()).or_default();
+ q.retain(|(t, _)| t.elapsed() < LOOP_WINDOW);
+ let mut reached: Vec<&str> = q.iter().map(|(_, p)| p.as_str()).collect();
+ reached.sort();
+ reached.dedup();
+ if !terminal && !answer && !reached.contains(&to) && reached.len() >= limit {
+ return false;
+ }
+ q.push_back((Instant::now(), to.to_string()));
+ true
+}
+
fn is_group(to: &str) -> bool {
to == "*" || to.starts_with("repo:") || to.ends_with("/*")
}
@@ -557,3 +643,23 @@ where
}
out
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn fanout_holds_a_second_session_but_not_answers_or_terminals() {
+ let mut talked = Talked::new();
+ assert!(fanout_ok(&mut talked, "alice/api-claude", "sven/api-codex", 1));
+ assert!(fanout_ok(&mut talked, "alice/api-claude", "sven/api-codex", 1), "same session again");
+ assert!(!fanout_ok(&mut talked, "alice/api-claude", "sven/web-claude", 1), "a second session");
+ assert!(fanout_ok(&mut talked, "alice/web-cursor", "sven/web-claude", 1), "another sender has its own budget");
+
+ assert!(fanout_ok(&mut talked, "sven/docs-pi", "alice/docs-codex", usize::MAX));
+ assert!(fanout_ok(&mut talked, "alice/docs-codex", "sven/docs-pi", 0), "answering who wrote first");
+
+ assert!(fanout_ok(&mut talked, "alice/terminal", "sven/a", 0));
+ assert!(fanout_ok(&mut talked, "alice/api-claude", "sven/terminal", 0));
+ }
+}
diff --git a/src/daemon/mod.rs b/src/daemon/mod.rs
index 7361cbb..39c49c6 100644
--- a/src/daemon/mod.rs
+++ b/src/daemon/mod.rs
@@ -117,8 +117,12 @@ struct Inner {
polling: HashMap<String, usize>,
/// Recent agent-to-agent message times per (from, to), for the loop guard.
pairs: HashMap<(String, String), VecDeque<Instant>>,
+ /// Recent agent-to-agent messages per sender, with their recipient, for the fan-out guard.
+ talked: Talked,
}
+type Talked = HashMap<String, VecDeque<(Instant, String)>>;
+
/// A session running on this machine.
struct Live {
reg: SessionReg,
@@ -176,6 +180,7 @@ impl Daemon {
in_flight: HashMap::new(),
polling: HashMap::new(),
pairs: HashMap::new(),
+ talked: HashMap::new(),
}),
arrived: Notify::new(),
git_cache: Mutex::new(HashMap::new()),
diff --git a/tests/e2e/two_machines.py b/tests/e2e/two_machines.py
index c314b10..125a6f1 100644
--- a/tests/e2e/two_machines.py
+++ b/tests/e2e/two_machines.py
@@ -162,6 +162,16 @@ 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)
+cli("alex", "listen", "--as", "second", "--wait", "0")
+for _ in range(20):
+ out = codex.tool("send_message", {"to": "alex/second", "message": "a second session (e2e test, ignore)"}, meta)
+ if "no session called" not in out:
+ break
+ time.sleep(0.5)
+check("an agent starting on a second session of someone's is held", "held until alex approves it" in out, out)
+cli("alex", "reject", "--all")
out = cli("alex", "send", "nobody", "x")
check("unknown name fails helpfully", "no session called 'nobody'" in out, out)