Skip to content

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

Agents never send to a group; only a person at a terminal does

Lars Talianabfc0a5bb579
diff --git a/DESIGN.md b/DESIGN.md
index 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 be
renamed by the agent. A new session in the same place with the same agent **inherits a stale name and its
unread 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 without
any 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 never
contact n0 either.
diff --git a/README.md b/README.md
index 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
```sh
tincan who # who's around and what their sessions are doing
tincan 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 agent
tincan listen --as terminal # replies to what you sent from this terminal
tincan link # the team link again
tincan setup # which agents are on tincan, and how messages are handled
diff --git a/site/index.html b/site/index.html
index 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.md
index 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. You
are 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, a
change 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 user
diff --git a/src/daemon/mail.rs b/src/daemon/mail.rs
index 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.rs
index 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.rs
index 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.rs
index 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.py
index 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", "→ ali
out = 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)