Skip to content

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

notify: narrower, after review

Lars Talianed43a6c7b386
diff --git a/DESIGN.md b/DESIGN.md
index 896f506..5802090 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -182,9 +182,9 @@ Three tools, none of which an agent has to call unless it wants to message someo
`held`) and tier, e.g. "queued: alice/web-cursor is idle and turn-only, it sees this when alice next
prompts it". (`tincan send --fyi` doesn't wake: read at the next natural pause.) `notify` also pops it up on
the person's screen, for an approval or decision only they can make: osascript on macOS, notify-send on Linux,
- a PowerShell toast on Windows, at most one per sender a minute; a machine without a desktop says so. With
- `notify`, `to` may be a person (their own user included): then only the pop-up, on each of their machines that
- is on.
+ a PowerShell toast on Windows, at most one per person sending a minute, none for messages over 15 minutes old;
+ a machine without a desktop says so. With `notify`, `to` may be your own user: then only the pop-up, on each of
+ your machines that is on (an agent that needs its user).
- `check_inbox(wait_secs?)`: unread messages; can block waiting for a reply.
Agents never report what they are doing; tincan reads it from what they record anyway (`doing.rs`): the
diff --git a/README.md b/README.md
index d1ceeea..3ddb6ce 100644
--- a/README.md
+++ b/README.md
@@ -38,14 +38,15 @@ That's it. Ask any agent "who's on the team?", or tell it to ask someone's agent
wake up; Cursor, Gemini and Copilot at their next step. Claude sessions you already had open join without a
restart.
- **A tap on the shoulder when it matters.** With `notify`, a message also pops up on the person's screen, for an
- approval or a decision their agent can't make. Agents can reach their own user that way too.
+ approval or a decision their agent can't make. Agents can reach their own user that way too. (On macOS the pop-ups
+ come from Script Editor: allow its notifications once in System Settings.)
- **A menu bar icon** on macOS shows who's online and what they're doing.
- **No setup to maintain.** It runs in the background, updates itself, and the link keeps working.
```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 alice --notify "can you approve the deploy?" # pop it up on alice's screen
+tincan send alice/api-claude --notify "approve the deploy?" # and pop it up on alice's screen
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 a792f90..34c3cf6 100644
--- a/site/index.html
+++ b/site/index.html
@@ -190,7 +190,7 @@
<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>
- <dt>sven</dt><dd>with notify: a pop-up on sven's screen, for something only he can decide</dd>
+ <dt>you</dt><dd>with notify: a pop-up on your own screen, from an agent that needs you</dd>
</dl>
</section>
diff --git a/site/skill/SKILL.md b/site/skill/SKILL.md
index bc5894a..3b729ca 100644
--- a/site/skill/SKILL.md
+++ b/site/skill/SKILL.md
@@ -28,7 +28,8 @@ powershell -c "& ([scriptblock]::Create((irm https://larstalian.github.io/tincan
- `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.
+ `--from <your address>` so replies come back to you. `--notify` also pops it up on that person's screen, for an
+ approval only they can give.
- `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.
diff --git a/src/daemon/mail.rs b/src/daemon/mail.rs
index eb4ffe8..e4bfed0 100644
--- a/src/daemon/mail.rs
+++ b/src/daemon/mail.rs
@@ -113,9 +113,10 @@ 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 people = g.team.as_ref().map(|t| t.people()).unwrap_or_default();
- if notify && (to == self.person || people.iter().any(|p| p == to)) {
- // A person, not a session: just the notification, on each of their machines that is on now.
+ // Your own user, not a session: just the pop-up, on each of their machines that is on now. (To get a
+ // teammate's attention, message one of their sessions with notify.)
+ let own = notify && to == self.person;
+ if own {
let msg = Message {
id: Ulid::new().to_string(),
from: from_addr.clone(),
@@ -129,30 +130,25 @@ impl Daemon {
notify: true,
sent_at: now,
};
- res.ids.push(msg.id.clone());
- if to == self.person {
- let (shown, note) = self.notify(&msg);
- let state = if shown { "notified" } else { "not notified" };
- res.recipients.push(Recipient { address: to.to_string(), state: state.into(), note });
- }
+ let (sent, note) = self.notify(&msg);
+ let state = if sent { "notified" } else { "not notified" };
+ res.recipients.push(Recipient { address: format!("{to}@{}", self.machine), state: state.into(), note });
for m in g.team.iter().flat_map(|t| t.active()).filter(|m| m.person == to) {
// Machines we've never heard from (and this one) aren't in `remotes`.
let Some(online) = remotes.get(&m.endpoint).map(|r| r.online) else { continue };
let address = format!("{to}@{}", m.machine);
+ let note = if online {
+ format!("no answer from {}", m.machine)
+ } else {
+ format!("{} is offline", m.machine)
+ };
if online {
- let note = format!("no answer from {} yet", m.machine);
remote_jobs.push((res.recipients.len(), m.endpoint, m.machine.clone(), true, msg.clone()));
- res.recipients.push(Recipient { address, state: "not notified".into(), note });
- } else {
- let note = format!("not notified: {} is offline", m.machine);
- res.recipients.push(Recipient { address, state: "not notified".into(), note });
}
- }
- if res.recipients.is_empty() {
- bail!("none of {to}'s machines is online to show it");
+ res.recipients.push(Recipient { address, state: "not notified".into(), note });
}
}
- let targets = if res.ids.is_empty() { self.resolve(&g, &remotes, to, Some(&exclude))? } else { Vec::new() };
+ let targets = if own { Vec::new() } else { self.resolve(&g, &remotes, to, Some(&exclude))? };
for t in targets {
let msg = Message {
id: Ulid::new().to_string(),
@@ -209,11 +205,15 @@ impl Daemon {
for (i, name, verdict) in futures_join(sends).await {
let r = &mut res.recipients[i];
match verdict {
+ // A pop-up only (see above): nothing kept to retry.
+ Some((state, _)) if r.state == "not notified" && state == "retry" => {
+ r.note = format!("{name} is busy")
+ }
Some((state, note)) => {
r.state = state;
r.note = note;
}
- None if r.state == "not notified" => r.note = format!("not notified: no answer from {name}"),
+ None if r.state == "not notified" => r.note = format!("no answer from {name}"),
None => r.note = format!("queued: no answer from {name} yet; it will be retried"),
}
}
@@ -435,11 +435,12 @@ impl Daemon {
));
}
let Some((person, name)) = msg.to.split_once('/') else {
- if msg.to != self.person {
- bail!("{} is not on this machine", msg.to);
+ // Only your own machines pop up for you without a session.
+ if msg.to != self.person || sender != self.person {
+ bail!("a pop-up without a session is only for your own user");
}
- let (shown, note) = self.notify(&msg);
- return Ok((if shown { "notified" } else { "not notified" }.into(), note));
+ let (sent, note) = self.notify(&msg);
+ return Ok((if sent { "notified" } else { "not notified" }.into(), note));
};
if person != self.person {
bail!("{} is not on this machine", msg.to);
diff --git a/src/daemon/notify.rs b/src/daemon/notify.rs
index 8fbc3be..06a7cbe 100644
--- a/src/daemon/notify.rs
+++ b/src/daemon/notify.rs
@@ -9,25 +9,32 @@ use std::{
time::{Duration, Instant},
};
-/// At most one notification per sender in this time: a looping agent can't flood the screen.
+/// At most one notification per person sending in this time: a looping agent can't flood the screen.
const GAP: Duration = Duration::from_secs(60);
+/// Older than this (it waited in an outbox while this machine was off), it no longer pops up.
+const STALE_MS: i64 = 15 * 60 * 1000;
impl Daemon {
- /// Shows `msg` to this machine's person. Returns whether it was shown, and a note for the sender.
+ /// Shows `msg` to this machine's person. Returns whether it was handed to the system's notifications (which may
+ /// still hide it, say if the person turned them off), and a note for the sender.
pub(super) fn notify(&self, msg: &Message) -> (bool, String) {
+ if util::now_ms() - msg.sent_at > STALE_MS {
+ return (false, "not popped up: it's over 15 minutes old".into());
+ }
+ let person = msg.from.split('/').next().unwrap_or_default().to_string();
let title = match msg.to.split_once('/') {
Some((_, session)) => format!("{} → {session}", msg.from),
None => msg.from.clone(),
};
let mut shown = self.shown.lock().unwrap();
shown.retain(|_, at| at.elapsed() < GAP);
- if shown.contains_key(&msg.from) {
- return (false, format!("not shown: {} showed one from {} a moment ago", self.machine, msg.from));
+ if shown.contains_key(&person) {
+ return (false, format!("not popped up: {} had one from {person} a moment ago", self.machine));
}
let Some(mut cmd) = command(&title, &util::one_line(&msg.body, 200)) else {
- return (false, format!("not shown: {} can't show desktop notifications", self.machine));
+ return (false, format!("not popped up: {} has no desktop to show it on", self.machine));
};
- shown.insert(msg.from.clone(), Instant::now());
+ shown.insert(person, Instant::now());
std::thread::spawn(move || {
match cmd.stdin(Stdio::null()).stdout(Stdio::null()).stderr(Stdio::piped()).output() {
Ok(o) if o.status.success() => {}
@@ -35,7 +42,7 @@ impl Daemon {
Err(e) => log(&format!("notification failed: {e}")),
}
});
- (true, format!("shown on {}'s screen ({})", self.person, self.machine))
+ (true, format!("popped up for {} ({})", self.person, self.machine))
}
}
@@ -58,7 +65,9 @@ fn command(title: &str, body: &str) -> Option<Command> {
}
cmd.env("DBUS_SESSION_BUS_ADDRESS", format!("unix:path={bus}"));
}
- cmd.args(["--app-name=tincan", title, body]);
+ // Most notification servers read markup; `--` keeps a body starting with `-` from being taken for an option.
+ let text = |s: &str| s.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;");
+ cmd.args(["--app-name=tincan".into(), "--".into(), text(title), text(body)]);
Some(cmd)
}
diff --git a/src/main.rs b/src/main.rs
index 6bf4649..4696899 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -96,7 +96,7 @@ enum Cmd {
/// Don't wake the recipient; it reads this at its next natural pause
#[arg(long)]
fyi: bool,
- /// Also pop it up on the person's screen (then `<to>` may be just a person)
+ /// Also pop it up on the person's screen (then `<to>` may be your own name)
#[arg(long, conflicts_with = "fyi")]
notify: bool,
/// Send as this agent session here (e.g. one made with `tincan listen --as <name>`)
diff --git a/src/mcp.rs b/src/mcp.rs
index 005991c..50691c5 100644
--- a/src/mcp.rs
+++ b/src/mcp.rs
@@ -55,8 +55,8 @@ pub struct SendArgs {
/// Id of the message you are replying to.
#[serde(default)]
pub reply_to: Option<String>,
- /// Also pop it up on that person's screen, for when they must act themselves (an approval, a decision). Then `to`
- /// may be just a person, your own user included.
+ /// Also pop it up on that person's screen, for when they must act themselves (an approval, a decision). `to` may
+ /// then be your own user's name, to reach them.
#[serde(default)]
pub notify: Option<bool>,
}
diff --git a/src/proto.rs b/src/proto.rs
index d722720..3091c68 100644
--- a/src/proto.rs
+++ b/src/proto.rs
@@ -109,7 +109,7 @@ pub enum Request {
reply_to: Option<String>,
#[serde(default = "yes")]
wake: bool,
- /// Also show it on the person's screen. With it, `to` may be just a person.
+ /// Also pop it up on the person's screen. With it, `to` may be your own user.
#[serde(default)]
notify: bool,
},
@@ -245,7 +245,7 @@ pub struct Message {
pub reply_to: Option<String>,
pub body: String,
pub wake: bool,
- /// Show it on the person's screen too (and, sent to a person rather than a session, only there).
+ /// 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,
diff --git a/tests/e2e/two_machines.py b/tests/e2e/two_machines.py
index 0984686..2a81989 100644
--- a/tests/e2e/two_machines.py
+++ b/tests/e2e/two_machines.py
@@ -160,15 +160,15 @@ out = cli("alice", "send", "alex", "dinner at 8?")
check("a person is not an address: the error lists their agent sessions",
"messages go to agent sessions; alex's are:" in out and f"alex/{claude_name}" in out, out)
out = codex.tool("send_message", {"to": f"alex/{claude_name}", "message": "can you approve the deploy? (e2e test, ignore)", "notify": True}, meta)
-check("notify: the message also pops up on the person's screen", "shown on alex's screen (laptop)" in out, out)
+check("notify: the message also pops up on the person's screen", "popped up for alex (laptop)" in out, out)
log = shown("alex")
check("…naming who asks, which session, and the ask", f"alice/work-codex → {claude_name}" in log and "approve the deploy" in log, log)
-out = codex.tool("send_message", {"to": "alex", "message": "and the second one? (e2e test, ignore)", "notify": True}, meta)
-check("notify to a person: no session, and one pop-up per sender a minute", "not shown: laptop showed one from alice/work-codex" in out, out)
-out = cli("alice", "send", "alex", "--notify", "from alice's terminal (e2e test, ignore)")
-check("…another sender's does show", "shown on alex's screen" in out and "from alice's terminal" in shown("alex"), out)
+out = cli("alice", "send", f"alex/{claude_name}", "--notify", "and from the terminal (e2e test, ignore)")
+check("one pop-up per person a minute", "not popped up: laptop had one from alice" in out and "from the terminal" not in shown("alex"), out)
+out = codex.tool("send_message", {"to": "alex", "message": "x", "notify": True}, meta)
+check("a teammate's pop-up goes with a message to one of their sessions", "messages go to agent sessions" in out, out)
out = codex.tool("send_message", {"to": "alice", "message": "need your ok (e2e test, ignore)", "notify": True}, meta)
-check("an agent can tap its own user on the shoulder", "shown on alice's screen (desktop)" in out and "need your ok" in shown("alice"), out)
+check("an agent can tap its own user on the shoulder", "popped up for alice (desktop)" in out and "need your ok" in shown("alice"), out)
out = codex.tool("send_message", {"to": "alex/*", "message": "x", "notify": True}, meta)
check("notify doesn't go to groups", "not a group" in out, out)
# No waiting for presence: the terminal that just messaged alice can be answered at once.