Skip to content

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

feat: measure network usage without changing encrypted peer delivery (#174)

reason-machines-staging[bot]050ed80fda0e
diff --git a/Cargo.lock b/Cargo.lock
index 402a496..ad461f9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2757,7 +2757,7 @@ dependencies = [
[[package]]
name = "reason-network"
-version = "0.12.13"
+version = "0.12.14"
dependencies = [
"anyhow",
"blake3",
diff --git a/Cargo.toml b/Cargo.toml
index 60f1c33..7fe9ae6 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "reason-network"
-version = "0.12.13"
+version = "0.12.14"
edition = "2024"
description = "Reason Network: the team directory and message bus behind reason network, for coding agents across machines"
license = "MIT OR Apache-2.0"
diff --git a/README.md b/README.md
index 4162a43..b72d1d4 100644
--- a/README.md
+++ b/README.md
@@ -154,3 +154,27 @@ at Reason.
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=reason-machines/reason-network&type=date&legend=top-left" />
</picture>
</a>
+
+## Usage measurement
+
+The engine keeps optional aggregate usage counters in a separate local SQLite file.
+When the Reason CLI carries the network, it reports recent daily aggregates about every
+five minutes, in bounded background batches: agent families, local or remote routing, verified account relationships,
+transport paths, delivery stages, linked replies, size and latency buckets, session
+snapshots and optional sender-supplied purpose labels (the CLI send --purpose option). The engine does not upload these
+itself. Standalone engines without the CLI keep their counters locally.
+
+Message text, files, filenames, repositories, session names, message ids, peer identities,
+keys and sign-in proofs are not in these reports. The existing P2P encryption and wire
+protocol are unchanged. Set DO_NOT_TRACK=1 when running a Reason command to keep the
+aggregates local, including in its background relay; DO_NOT_TRACK=0 restores reporting.
+Reports are associated with the reporting Reason account and engine, so they are usage
+metadata, not anonymous data. Unknown classifications stay unknown.
+
+Collection uses a bounded, non-blocking queue and its own database worker. Analytics
+failures do not refuse or delay message delivery. Counts are best effort: queue overflow,
+bounded dimension capacity, missing reports, old engines, and a crash before persistence
+can leave gaps. Persisted cumulative snapshots survive restarts and retries; a replaced
+counter database gets a new generation. Collection-limit drops are reported. Acceptance
+is not agent consumption, and a reply is not proof of task completion. A hosted relay
+copying mail into a server inbox does not count as a handoff to that assistant.
diff --git a/src/daemon/ask.rs b/src/daemon/ask.rs
index fc03e44..a1716eb 100644
--- a/src/daemon/ask.rs
+++ b/src/daemon/ask.rs
@@ -220,6 +220,7 @@ impl Daemon {
/// This person's own session (`<person>/terminal`), registered the way the CLI registers it.
async fn terminal(self: &Arc<Self>) -> String {
let call = HookCall {
+ through_reason: Some(false),
agent: "cli".into(),
event: "stop".into(),
session_id: "terminal".into(),
diff --git a/src/daemon/mail.rs b/src/daemon/mail.rs
index abec420..b3ab0c5 100644
--- a/src/daemon/mail.rs
+++ b/src/daemon/mail.rs
@@ -148,6 +148,11 @@ impl Daemon {
.ok_or_else(unregistered)?;
let (from_addr, from_agent, from_repo) =
(self.addr(&sender.name), Some(sender.reg.agent.clone()), sender.git.repo.clone());
+ let sender_origin = match sender.through_reason {
+ Some(true) => "hosted",
+ Some(false) => "local",
+ None => "unknown",
+ };
let exclude = sender.reg.key.clone();
// It talks to teammates: its name stays its own.
self.reached(&mut g, &exclude);
@@ -216,6 +221,52 @@ impl Daemon {
// The receipt names it as its answer will show here: a teammate's terminal with its machine.
let shown = t.shown_address();
let here = !matches!(t, Target::Remote { .. });
+ let target_agent = match &t {
+ Target::Session { key: Some(key), .. } => g.live.get(key).map(|l| l.reg.agent.as_str()),
+ Target::Session { key: None, .. } => None,
+ Target::Remote { address, machine, .. } => remotes
+ .get(machine)
+ .and_then(|r| r.presence.sessions.iter().find(|s| &s.address == address))
+ .map(|s| s.agent.as_str()),
+ };
+ let mut dims = crate::usage::Dimensions {
+ source: crate::usage::family(from_agent.as_deref().unwrap_or("unknown")),
+ target: target_agent.map(crate::usage::family).unwrap_or_else(|| "unknown".into()),
+ locality: if here { "local" } else { "remote" }.into(),
+ origin: sender_origin.into(),
+ relationship: if here && g.team.as_ref().is_some_and(|t| t.has_proof(&self.key.public())) {
+ "same"
+ } else {
+ "unknown"
+ }
+ .into(),
+ transport: if here { "local" } else { "unknown" }.into(),
+ ..Default::default()
+ };
+ if let Target::Remote { machine, .. } = &t {
+ if let Some(link) = net.as_ref().and_then(|n| n.link_info(machine)) {
+ dims.transport = if link.relay { "relay" } else { "direct" }.into();
+ let mut latency = dims.clone();
+ latency.bucket = crate::usage::duration(link.rtt_ms).into();
+ self.usage.count("rtt_ms", latency, 1);
+ }
+ if let Some(team) = &g.team
+ && let (Some(ours), Some(theirs)) = (team.proof(&self.key.public()), team.proof(machine))
+ {
+ dims.relationship = if ours.sub == theirs.sub { "same" } else { "different" }.into();
+ }
+ }
+ self.usage.start(&msg.id, dims.clone(), msg.reply_to.as_deref(), false);
+ self.usage.count("attempted", dims.clone(), 1);
+ let mut sized = dims.clone();
+ sized.bucket = crate::usage::size(body.len()).into();
+ self.usage.count("body_bytes", sized, 1);
+ let mut attached = dims.clone();
+ attached.bucket = crate::usage::number(files.len()).into();
+ self.usage.count("attachments", attached, 1);
+ let mut attachment_size = dims.clone();
+ attachment_size.bucket = crate::usage::size(files.iter().map(|f| f.content.len()).sum()).into();
+ self.usage.count("attachment_bytes", attachment_size, 1);
let (state, mut note): (String, String) = match t {
_ if !matches!(t, Target::Remote { .. }) && !g.loop_ok(&msg.from, &msg.to) => {
("refused".into(), LOOP_NOTE.into())
@@ -241,6 +292,15 @@ impl Daemon {
}
}
};
+ if state == "refused" {
+ self.usage.stage(&msg.id, "rejected");
+ } else if here {
+ self.usage.stage(&msg.id, "accepted");
+ self.usage.count("received", dims.clone(), 1);
+ }
+ if state == "queued" {
+ self.usage.count("queued", dims, 1);
+ }
// Counting never stops a message. One to another machine counts once that machine takes it.
if here && state != "refused" {
let _ = g.store.count(now, Counted::Sent);
@@ -451,6 +511,9 @@ impl Daemon {
/// A session's MCP server had no inbox to push `ids` into: they are unread again, for the session to read when it
/// checks, and nothing is pushed through it until it registers knowing one (or Claude Code lists one to post into).
pub(super) fn push_failed(&self, key: &str, ids: &[String]) {
+ for id in ids {
+ self.usage.stage(id, "push_failed");
+ }
let mut g = self.inner.lock().unwrap();
for id in ids {
g.in_flight.remove(id);
@@ -475,7 +538,10 @@ impl Daemon {
}
match res {
Ok(Ok(())) => {
- let _ = g.store.mark_read(&ids, util::now_ms());
+ let changed = g.store.mark_read(&ids, util::now_ms()).unwrap_or_default();
+ for id in &changed {
+ this.usage.stage(id, "delivered");
+ }
}
Ok(Err(e)) => log(&format!("delivering to Claude session {}: {e}", this.logged(&g, &key))),
Err(e) => log(&format!("delivering to Claude session {}: {e}", this.logged(&g, &key))),
@@ -530,7 +596,10 @@ impl Daemon {
}
match res {
Ok(()) => {
- let _ = g.store.mark_read(&ids, util::now_ms());
+ let changed = g.store.mark_read(&ids, util::now_ms()).unwrap_or_default();
+ for id in &changed {
+ this.usage.stage(id, "delivered");
+ }
if let Some(l) = g.live.get_mut(&key) {
l.retry = None;
}
@@ -643,6 +712,13 @@ impl Daemon {
let kept = held && g.store.session_by_name(name)?.is_some_and(|r| r.kept());
// Counted once, when it is new here; a held one once approved.
if g.store.insert(&mut msg, held)? && !held {
+ let dims = crate::usage::Dimensions {
+ source: msg.from_agent.as_deref().map(crate::usage::family).unwrap_or_else(|| "unknown".into()),
+ locality: "remote".into(),
+ ..Default::default()
+ };
+ self.usage.start(&msg.id, dims.clone(), msg.reply_to.as_deref(), true);
+ self.usage.count("received", dims, 1);
let _ = g.store.count(util::now_ms(), Counted::Received);
}
let (state, note) = match key {
@@ -701,7 +777,12 @@ impl Daemon {
let messages = g.pending(&address)?;
if !messages.is_empty() && !peek {
let ids: Vec<String> = messages.iter().map(|m| m.id.clone()).collect();
- g.store.mark_read(&ids, util::now_ms())?;
+ let changed = g.store.mark_read(&ids, util::now_ms())?;
+ if g.live.get(&key).is_some_and(|l| l.through_reason == Some(false)) {
+ for id in &changed {
+ self.usage.stage(id, "delivered");
+ }
+ }
}
messages
};
diff --git a/src/daemon/mod.rs b/src/daemon/mod.rs
index d9d6720..88a1039 100644
--- a/src/daemon/mod.rs
+++ b/src/daemon/mod.rs
@@ -118,6 +118,7 @@ fn log(msg: &str) {
}
pub struct Daemon {
+ usage: crate::usage::Usage,
person: String,
machine: String,
cfg: Config,
@@ -168,6 +169,7 @@ struct Inner {
/// A session running on this machine.
struct Live {
+ through_reason: Option<bool>,
reg: SessionReg,
name: String,
/// The client connection (`reason network mcp`) that owns it; `None` for sessions known only through hooks.
@@ -211,8 +213,21 @@ pub fn load_key() -> Result<SecretKey> {
}
impl Daemon {
+ pub(crate) fn usage_transport(&self, metric: &'static str, relay: bool, rtt: u64) {
+ let mut dims = crate::usage::Dimensions { locality: "remote".into(), ..Default::default() };
+ if metric == "path_changed" {
+ dims.transport = if relay { "relay" } else { "direct" }.into();
+ }
+ self.usage.count(metric, dims.clone(), 1);
+ if rtt > 0 {
+ dims.bucket = crate::usage::duration(rtt).into();
+ self.usage.count("rtt_ms", dims, 1);
+ }
+ }
fn open() -> Result<Self> {
- Self::with(Config::load(), Store::open(&paths::db(), paths::inbox())?, load_key()?)
+ let mut daemon = Self::with(Config::load(), Store::open(&paths::db(), paths::inbox())?, load_key()?)?;
+ daemon.usage = crate::usage::Usage::open(paths::home().join("usage.sqlite"));
+ Ok(daemon)
}
fn with(cfg: Config, store: Store, key: SecretKey) -> Result<Self> {
@@ -221,6 +236,7 @@ impl Daemon {
// In a team, who we are is what the signed roster says, whatever the config file says.
let member = team.as_ref().and_then(|t| t.member(&key.public()).cloned());
Ok(Daemon {
+ usage: Default::default(),
person: member.as_ref().map_or_else(|| cfg.person(), |m| m.person.clone()),
machine: member.map_or_else(util::hostname, |m| m.machine),
key,
@@ -324,6 +340,16 @@ impl Daemon {
}
async fn handle(self: &Arc<Self>, conn: u64, req: Request) -> Result<Value> {
+ let operation = match &req {
+ Request::Who { .. } => Some("who"),
+ Request::Send { .. } => Some("send"),
+ Request::Inbox { .. } => Some("inbox"),
+ Request::Ask { .. } => Some("ask"),
+ _ => None,
+ };
+ if let Some(operation) = operation {
+ self.usage.count("tool", crate::usage::Dimensions { bucket: operation.into(), ..Default::default() }, 1);
+ }
Ok(match req {
Request::Register { session } => {
let git = self.git(&session.cwd).await;
@@ -331,7 +357,12 @@ impl Daemon {
}
Request::SetStatus { key, doing, name } => json!(self.set_status(&key, doing, name)?),
Request::Who { me, filter, all } => json!(self.who(me, filter, all).await?),
- Request::Send { from, to, body, reply_to, wake, notify, files } => {
+ Request::Send { from, to, body, reply_to, wake, notify, files, purpose } => {
+ let dims = crate::usage::Dimensions {
+ bucket: purpose.unwrap_or_else(|| "unknown".into()),
+ ..Default::default()
+ };
+ self.usage.count("purpose", dims, 1);
json!(self.send(from, &to, &body, reply_to, wake, notify, None, files).await?)
}
Request::Inbox { key, wait_secs, peek } => json!(self.inbox(key, wait_secs.min(MAX_WAIT), peek).await?),
@@ -341,9 +372,16 @@ impl Daemon {
self.stop_waiting(&key).await;
Value::Null
}
- Request::Delivered { ids, .. } => {
+ Request::Delivered { key, ids } => {
let mut g = self.inner.lock().unwrap();
- g.store.mark_read(&ids, util::now_ms())?;
+ let changed = g.store.mark_read(&ids, util::now_ms())?;
+ // Hosted relays acknowledge a handover to a server inbox, not agent consumption.
+ let handed_to_agent = g.live.get(&key).is_some_and(|l| l.through_reason == Some(false));
+ for id in &changed {
+ if handed_to_agent {
+ self.usage.stage(id, "delivered");
+ }
+ }
for id in &ids {
g.in_flight.remove(id);
}
@@ -363,6 +401,7 @@ impl Daemon {
Request::Proof { jws } => json!(self.attach_proof(&jws)?),
Request::Invite { me, hours } => json!(self.invite(me, hours).await?),
Request::Team => json!(self.team_info()?),
+ Request::Usage => json!(self.usage.snapshot()),
Request::Link { new } => json!(self.link(new).await?),
Request::Remove { who } => json!(self.remove(&who)?),
Request::Leave { force } => json!(self.leave(force).await?),
diff --git a/src/daemon/sessions.rs b/src/daemon/sessions.rs
index b23d91d..daf1797 100644
--- a/src/daemon/sessions.rs
+++ b/src/daemon/sessions.rs
@@ -116,9 +116,15 @@ impl Daemon {
self.take_over(g, &name, &key)?;
let attached = conn.is_some() || reg.tier == Tier::Push || reg.agent == "cli";
let mcp_push = conn.is_some() && reg.tier == Tier::Push;
+ self.usage.count(
+ "registered",
+ crate::usage::Dimensions { source: crate::usage::family(&reg.agent), ..Default::default() },
+ 1,
+ );
g.live.insert(
key.clone(),
Live {
+ through_reason: Some(conn.is_none() && reg.agent == "reason"),
reg,
name,
conn,
@@ -317,7 +323,8 @@ impl Daemon {
/// A hook fired in an agent: keep its session alive, track busy/idle, hand back mail to inject.
pub(super) async fn hook(self: &Arc<Self>, h: HookCall) -> Result<HookReply> {
- let HookCall { agent, event, session_id, cwd, pid, mail, transcript, doing, name, dirs, keep } = h;
+ let HookCall { agent, event, session_id, cwd, pid, mail, transcript, doing, name, dirs, keep, through_reason } =
+ h;
let (agent, event) = (agent.as_str(), event.as_str());
let key = format!("{agent}:{session_id}");
let now = util::now_ms();
@@ -398,6 +405,7 @@ impl Daemon {
}
return Ok(HookReply::default());
}
+ l.through_reason = through_reason;
l.last_hook = Some(now);
l.reg.tier = l.reg.tier.min(self.hook_tier(agent, l.push_failed));
if pid.is_some() {
@@ -781,6 +789,7 @@ mod tests {
d.set_status("claude-code:a", Some(format!("{line} then fix CI")), None).unwrap();
join(&d, claude("b"));
let doing = HookCall {
+ through_reason: Some(false),
agent: "claude-code".into(),
event: "doing".into(),
session_id: "b".into(),
@@ -829,6 +838,7 @@ mod tests {
async fn a_conversation_coming_back_through_its_hooks_gets_its_name_too() {
let d = Arc::new(super::super::test_daemon(Default::default()));
let call = |id: &str| HookCall {
+ through_reason: Some(false),
agent: "claude-code".into(),
event: "start".into(),
session_id: id.into(),
@@ -860,6 +870,7 @@ mod tests {
join(&d, named("hermes:p:1", "hermes", None));
for event in ["prompt", "tool", "stop"] {
d.hook(HookCall {
+ through_reason: Some(false),
agent: "hermes".into(),
event: event.into(),
session_id: "p:1".into(),
@@ -955,6 +966,7 @@ mod tests {
settled(&mut d);
let d = Arc::new(d);
let cli = |id: &str, keep: bool| HookCall {
+ through_reason: Some(false),
agent: "cli".into(),
event: "stop".into(),
session_id: id.into(),
@@ -1112,6 +1124,7 @@ mod tests {
async fn a_run_only_its_hooks_ever_saw_keeps_no_name() {
let d = Arc::new(super::super::test_daemon(Default::default()));
let call = |id: &str, event: &str| HookCall {
+ through_reason: Some(false),
agent: "claude-code".into(),
event: event.into(),
session_id: id.into(),
@@ -1144,6 +1157,7 @@ mod tests {
fn gemini(id: &str, event: &str) -> HookCall {
HookCall {
+ through_reason: Some(false),
agent: "gemini".into(),
event: event.into(),
session_id: id.into(),
@@ -1482,6 +1496,7 @@ mod tests {
assert_eq!(d.inner.lock().unwrap().live[TERMINAL].name, "terminal");
// The terminal's commands go on as before.
let call = HookCall {
+ through_reason: Some(false),
agent: "cli".into(),
event: "stop".into(),
session_id: "terminal".into(),
@@ -1657,6 +1672,7 @@ mod tests {
};
let d = Arc::new(super::super::test_daemon(cfg));
let call = |id: &str, event: &str, dirs: &[&str]| HookCall {
+ through_reason: Some(false),
agent: "cursor".into(),
event: event.into(),
session_id: id.into(),
diff --git a/src/daemon/teamops.rs b/src/daemon/teamops.rs
index a4bef67..dc8fa67 100644
--- a/src/daemon/teamops.rs
+++ b/src/daemon/teamops.rs
@@ -135,11 +135,18 @@ impl Daemon {
}
pub fn outbox_for(&self, id: &EndpointId) -> Vec<Message> {
- self.inner.lock().unwrap().store.outbox_for(&id.to_string(), util::now_ms()).unwrap_or_default()
+ let (messages, expired) =
+ self.inner.lock().unwrap().store.outbox_for(&id.to_string(), util::now_ms()).unwrap_or_default();
+ if expired > 0 {
+ self.usage.count("expired", Default::default(), expired as u64);
+ }
+ messages
}
pub fn outbox_done(&self, id: &str, taken: bool) {
- let _ = self.inner.lock().unwrap().store.outbox_done(id, taken);
+ if self.inner.lock().unwrap().store.outbox_done(id, taken).unwrap_or(false) {
+ self.usage.stage(id, if taken { "accepted" } else { "rejected" });
+ }
}
/// Takes in a teammate's copy of the team state, passing it on if it taught us something.
@@ -260,7 +267,7 @@ impl Daemon {
person,
machine: self.machine.clone(),
machines: Vec::new(),
- features: vec![crate::files::FEATURE.into()],
+ features: vec![crate::files::FEATURE.into(), "usage-v1".into()],
messages: Vec::new(),
udp: None,
})
@@ -378,7 +385,7 @@ impl Daemon {
person: person.clone(),
machine: self.machine.clone(),
machines: Vec::new(),
- features: vec![crate::files::FEATURE.into()],
+ features: vec![crate::files::FEATURE.into(), "usage-v1".into()],
messages: Vec::new(),
udp: None,
};
@@ -505,6 +512,24 @@ impl Daemon {
let team = self
.team_state()
.ok_or_else(|| anyhow!("not in a team yet: `{CLI} init <team>` or `{CLI} join <invite>`"))?;
+ {
+ let g = self.inner.lock().unwrap();
+ let mut dims =
+ crate::usage::Dimensions { bucket: crate::usage::number(g.live.len()).into(), ..Default::default() };
+ self.usage.count("active_sessions", dims.clone(), 1);
+ let families: std::collections::HashSet<_> =
+ g.live.values().map(|l| crate::usage::family(&l.reg.agent)).collect();
+ dims.bucket = crate::usage::number(families.len()).into();
+ self.usage.count("agent_families", dims, 1);
+ }
+ let peers = crate::usage::Dimensions {
+ bucket: crate::usage::number(
+ self.net().map(|n| n.remotes().values().filter(|r| r.online).count()).unwrap_or(0),
+ )
+ .into(),
+ ..Default::default()
+ };
+ self.usage.count("reachable_peers", peers, 1);
Ok(TeamInfo {
id: team.id.clone(),
name: team.whole_name(),
@@ -514,7 +539,7 @@ impl Daemon {
person: self.person.clone(),
machine: self.machine.clone(),
machines: self.machines(),
- features: vec![crate::files::FEATURE.into()],
+ features: vec![crate::files::FEATURE.into(), "usage-v1".into()],
messages: self.inner.lock().unwrap().store.counts(util::now_ms()).unwrap_or_default(),
udp: self.net().map(|n| n.udp()),
})
diff --git a/src/hook.rs b/src/hook.rs
index 764ff33..3c618c1 100644
--- a/src/hook.rs
+++ b/src/hook.rs
@@ -86,6 +86,7 @@ async fn handle(
let key = format!("{agent}:{session_id}");
let req = Request::Hook(HookCall {
+ through_reason: Some(false),
agent: agent.to_string(),
event: ev.to_string(),
session_id,
diff --git a/src/main.rs b/src/main.rs
index fea70f1..a3845bf 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -24,6 +24,7 @@ mod setup;
mod store;
mod team;
mod tray;
+mod usage;
mod util;
mod wizard;
@@ -140,6 +141,9 @@ enum Cmd {
/// It comes from the agent session whose shell runs it, `--from <session>`, or from a plain terminal,
/// `<you>/terminal` (read replies with `listen --as terminal`)
Send {
+ /// Optional self-reported analytics category (review, delegate, status, question, handoff, other).
+ #[arg(long)]
+ purpose: Option<String>,
to: String,
/// The message; read from stdin when omitted or `-`
message: Vec<String>,
@@ -374,6 +378,7 @@ async fn cli_session(link: &std::sync::Arc<Link>, id: &str, event: &str) -> Resu
cwd = terminal_cwd(cwd, here_off(), agent_shell())?;
}
let req = Request::Hook(HookCall {
+ through_reason: Some(false),
agent: "cli".into(),
event: event.into(),
session_id: id.into(),
@@ -432,7 +437,7 @@ async fn cli(cmd: Cmd) -> Result<()> {
print!("{}", shown(&render::directory(&d, false, render::Paint::terminal())));
}
}
- Cmd::Send { to, message, reply_to, fyi, notify, from, files } => {
+ Cmd::Send { to, message, reply_to, fyi, notify, from, files, purpose } => {
// An agent in a folder that is off sends nothing, as no session (nor its files).
if agent_shell() && here_off() {
bail!(config::OFF_HERE);
@@ -455,6 +460,7 @@ async fn cli(cmd: Cmd) -> Result<()> {
// Messages come from agent sessions: `--from`'s, this agent's, or from a plain terminal, `<you>/terminal`.
// An agent shell Reason Network doesn't know (its tools aren't loaded) counts as a terminal.
let send = |from: String| Request::Send {
+ purpose: purpose.clone(),
from,
to: to.clone(),
body: body.clone(),
diff --git a/src/mcp.rs b/src/mcp.rs
index 61f3763..04865fe 100644
--- a/src/mcp.rs
+++ b/src/mcp.rs
@@ -192,6 +192,7 @@ impl ReasonNetworkMcp {
Err(e) => return Ok(failure(e)),
};
let req = Request::Send {
+ purpose: None,
from: key.clone(),
to: a.to,
body: a.message,
diff --git a/src/net.rs b/src/net.rs
index 3129c80..c7c7f30 100644
--- a/src/net.rs
+++ b/src/net.rs
@@ -510,7 +510,7 @@ async fn log_relay(endpoint: Endpoint) {
}
/// Says in the log when a connection to a teammate moves between a direct path and the relay, and the new one's rtt.
-async fn log_paths(conn: Connection) {
+async fn log_paths(conn: Connection, daemon: std::sync::Weak<Daemon>) {
let peer = conn.remote_id().fmt_short().to_string();
let kind = |relay: bool| if relay { "relay" } else { "direct" };
let mut lists = conn.paths_stream();
@@ -522,6 +522,9 @@ async fn log_paths(conn: Connection) {
&& from != relay
{
log(&format!("{peer}: path {} -> {} (rtt {} ms)", kind(from), kind(relay), p.rtt().as_millis()));
+ if let Some(d) = daemon.upgrade() {
+ d.usage_transport("path_changed", relay, p.rtt().as_millis() as u64);
+ }
}
was = Some(relay);
}
@@ -1053,7 +1056,8 @@ impl Net {
links.insert(peer, Link { id, tx: tx.clone(), conn: conn.clone(), dialer, since: Instant::now() });
}
log(&format!("connected to {} ({})", peer.fmt_short(), if outgoing { "out" } else { "in" }));
- let paths = tokio::spawn(log_paths(conn.clone()));
+ daemon.usage_transport("reconnected", false, 0);
+ let paths = tokio::spawn(log_paths(conn.clone(), self.daemon.clone()));
let writer = tokio::spawn(async move {
while let Some(w) = rx.recv().await {
diff --git a/src/proto.rs b/src/proto.rs
index d59809a..6f7a8bf 100644
--- a/src/proto.rs
+++ b/src/proto.rs
@@ -57,6 +57,8 @@ pub struct SessionReg {
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HookCall {
+ #[serde(default)]
+ pub through_reason: Option<bool>,
pub agent: String,
/// `start`, `prompt`, `tool`, `stop`, `end`, or `doing` (only reports what the session is doing).
pub event: String,
@@ -110,6 +112,9 @@ pub enum Request {
},
/// From an agent session: its key (or, for agents that reply through the CLI, its address or name).
Send {
+ /// Local analytics only; never included in the peer message.
+ #[serde(default, deserialize_with = "crate::usage::purpose")]
+ purpose: Option<String>,
from: String,
to: String,
body: String,
@@ -201,6 +206,8 @@ pub enum Request {
hours: u64,
},
Team,
+ /// Local aggregate counters, read only by clients that opt into usage reporting.
+ Usage,
/// The team link, which anyone can use to join; `new` replaces it.
Link {
#[serde(default)]
diff --git a/src/store.rs b/src/store.rs
index ed4faf8..6019deb 100644
--- a/src/store.rs
+++ b/src/store.rs
@@ -385,20 +385,21 @@ impl Store {
}
/// Undelivered messages for a machine; older than a week are given up on.
- pub fn outbox_for(&self, target: &str, now: i64) -> Result<Vec<Message>> {
- self.db.execute("DELETE FROM outbox WHERE created_at < ?1", [now - 7 * 86_400_000])?;
+ pub fn outbox_for(&self, target: &str, now: i64) -> Result<(Vec<Message>, usize)> {
+ let expired = self.db.execute("DELETE FROM outbox WHERE created_at < ?1", [now - 7 * 86_400_000])?;
let mut st = self.db.prepare_cached("SELECT msg FROM outbox WHERE target = ?1 ORDER BY created_at, rowid")?;
let rows = st.query_map([target], |r| r.get::<_, String>(0))?;
- Ok(rows.filter_map(|r| r.ok().and_then(|s| serde_json::from_str(&s).ok())).collect())
+ Ok((rows.filter_map(|r| r.ok().and_then(|s| serde_json::from_str(&s).ok())).collect(), expired))
}
/// The receiving machine answered for a message: it leaves the outbox, and counts as sent if that machine took it
/// (once, however many answers come).
- pub fn outbox_done(&self, id: &str, taken: bool) -> Result<()> {
- if self.db.execute("DELETE FROM outbox WHERE id = ?1", [id])? == 1 && taken {
+ pub fn outbox_done(&self, id: &str, taken: bool) -> Result<bool> {
+ let removed = self.db.execute("DELETE FROM outbox WHERE id = ?1", [id])? == 1;
+ if removed && taken {
let _ = self.count(crate::util::now_ms(), Counted::Sent);
}
- Ok(())
+ Ok(removed)
}
/// Adds one to today's count (by UTC day). Only numbers are kept, and only for the last few days.
@@ -462,12 +463,15 @@ impl Store {
Ok(())
}
- pub fn mark_read(&self, ids: &[String], now: i64) -> Result<()> {
+ pub fn mark_read(&self, ids: &[String], now: i64) -> Result<Vec<String>> {
let mut st = self.db.prepare_cached("UPDATE messages SET read_at = ?2 WHERE id = ?1 AND read_at IS NULL")?;
+ let mut changed = Vec::new();
for id in ids {
- st.execute(params![id, now])?;
+ if st.execute(params![id, now])? > 0 {
+ changed.push(id.clone());
+ }
}
- Ok(())
+ Ok(changed)
}
/// A renamed session keeps its unread mail.
@@ -731,7 +735,7 @@ mod tests {
store.outbox_done("01TAKEN", true).unwrap();
store.outbox_done("01TAKEN", true).unwrap();
store.outbox_done("01REFUSED", false).unwrap();
- assert!(store.outbox_for("peer", util::now_ms() + 8 * 86_400_000).unwrap().is_empty());
+ assert!(store.outbox_for("peer", util::now_ms() + 8 * 86_400_000).unwrap().0.is_empty());
assert_eq!(totals(&store), (1, 0));
// Received: held, it counts once approved. Dropped, then sent again after a lost answer, it counts once.
store.insert(&mut with_files("01HELD", "lars/api"), true).unwrap();
@@ -913,7 +917,7 @@ mod tests {
let bodies = |ms: Vec<Message>| ms.into_iter().map(|m| m.body).collect::<Vec<_>>();
assert_eq!(bodies(store.unread("lars/api").unwrap()), ["do X", "never mind X"]);
assert_eq!(bodies(store.held().unwrap()), ["do X", "never mind X"]);
- assert_eq!(bodies(store.outbox_for("peer", 1_000).unwrap()), ["do X", "never mind X"]);
+ assert_eq!(bodies(store.outbox_for("peer", 1_000).unwrap().0), ["do X", "never mind X"]);
}
fn temp_inbox() -> PathBuf {
diff --git a/src/usage.rs b/src/usage.rs
new file mode 100644
index 0000000..f1fa870
--- /dev/null
+++ b/src/usage.rs
@@ -0,0 +1,301 @@
+//! Optional aggregate analytics. The messaging path only try_sends bounded events;
+//! a separate thread owns its own SQLite database. No network, message text, files,
+//! addresses, repository names or peer identities enter this module.
+use rusqlite::{Connection, params};
+use serde::{Deserialize, Serialize};
+use std::{
+ collections::{BTreeMap, HashMap},
+ path::PathBuf,
+ sync::{
+ Arc, Mutex,
+ atomic::{AtomicU64, Ordering},
+ mpsc::{self, SyncSender},
+ },
+ time::{Duration, Instant},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
+pub struct Dimensions {
+ pub source: String,
+ pub target: String,
+ pub locality: String,
+ pub origin: String,
+ pub relationship: String,
+ pub transport: String,
+ pub bucket: String,
+}
+impl Default for Dimensions {
+ fn default() -> Self {
+ Self {
+ source: "unknown".into(),
+ target: "unknown".into(),
+ locality: "unknown".into(),
+ origin: "unknown".into(),
+ relationship: "unknown".into(),
+ transport: "unknown".into(),
+ bucket: "none".into(),
+ }
+ }
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Row {
+ pub metric: String,
+ #[serde(flatten)]
+ pub dimensions: Dimensions,
+ pub value: u64,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Day {
+ pub day: String,
+ pub rows: Vec<Row>,
+ pub dropped: u64,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Report {
+ pub version: u8,
+ pub generation: String,
+ #[serde(rename = "engineVersion")]
+ pub engine_version: String,
+ pub platform: String,
+ pub days: Vec<Day>,
+}
+// IDs exist only in this bounded in-memory correlation map, never in SQLite/reports.
+struct Pending {
+ dims: Dimensions,
+ at: Instant,
+ accepted: bool,
+ delivered: bool,
+ is_reply: bool,
+ depth: usize,
+ reply_ms: Option<u64>,
+}
+
+enum Event {
+ Count(&'static str, Dimensions, u64),
+ Start(String, Dimensions, Option<String>, Instant, bool),
+ Stage(String, &'static str, Instant),
+}
+#[derive(Default)]
+pub struct Usage {
+ tx: Option<SyncSender<Event>>,
+ report: Arc<Mutex<Option<Report>>>,
+ dropped: Arc<AtomicU64>,
+}
+
+pub fn family(name: &str) -> String {
+ let name = name.to_ascii_lowercase();
+ if name == "unknown" || name.is_empty() {
+ return "unknown".into();
+ }
+ let result = if name.contains("chatgpt") {
+ "chatgpt"
+ } else if name.contains("muse") {
+ "muse"
+ } else if name.contains("hermes") {
+ "hermes"
+ } else if name.contains("antigravity") {
+ "antigravity"
+ } else if name == "cli" {
+ "cli"
+ } else {
+ crate::agent::from_client_name(&name).unwrap_or("other")
+ };
+ if matches!(
+ result,
+ "cmd"
+ | "claude-code"
+ | "claude-desktop"
+ | "codex"
+ | "cursor"
+ | "gemini"
+ | "grok"
+ | "muse"
+ | "chatgpt"
+ | "opencode"
+ | "copilot"
+ | "pi"
+ | "reason"
+ | "hermes"
+ | "antigravity"
+ | "devin"
+ | "amp"
+ | "zed"
+ | "dsh"
+ | "zcode"
+ | "cli"
+ ) {
+ result.into()
+ } else {
+ "other".into()
+ }
+}
+pub fn duration(ms: u64) -> &'static str {
+ if ms < 100 {
+ "lt100"
+ } else if ms < 1000 {
+ "lt1000"
+ } else if ms < 10000 {
+ "lt10000"
+ } else if ms < 60000 {
+ "lt60000"
+ } else if ms < 600000 {
+ "lt600000"
+ } else {
+ "gte600000"
+ }
+}
+pub fn size(bytes: usize) -> &'static str {
+ if bytes < 1024 {
+ "lt1024"
+ } else if bytes < 16384 {
+ "lt16384"
+ } else if bytes < 65536 {
+ "lt65536"
+ } else {
+ "gte65536"
+ }
+}
+pub fn number(n: usize) -> &'static str {
+ match n {
+ 0 => "0",
+ 1 => "1",
+ 2 => "2",
+ 3..=5 => "3-5",
+ 6..=10 => "6-10",
+ _ => "11+",
+ }
+}
+impl Usage {
+ pub fn open(path: PathBuf) -> Self {
+ let (tx, rx) = mpsc::sync_channel(2048);
+ let report = Arc::new(Mutex::new(None));
+ let snapshot = report.clone();
+ let dropped = Arc::new(AtomicU64::new(0));
+ let lost = dropped.clone();
+ // Failure disables analytics, never the engine. Own database avoids message-store locks.
+ if std::thread::Builder::new().name("network-usage".into()).spawn(move || {
+ let run = || -> anyhow::Result<()> {
+ let mut db = Connection::open(&path)?;
+ #[cfg(unix)] crate::util::chmod(&path, 0o600)?;
+ db.busy_timeout(Duration::from_millis(100))?;
+ db.execute_batch("PRAGMA journal_mode=WAL; CREATE TABLE IF NOT EXISTS meta (id INTEGER PRIMARY KEY CHECK(id=1), generation TEXT NOT NULL); CREATE TABLE IF NOT EXISTS counters(day TEXT NOT NULL, metric TEXT NOT NULL, dimensions TEXT NOT NULL, value INTEGER NOT NULL, PRIMARY KEY(day,metric,dimensions));")?;
+ db.execute("INSERT OR IGNORE INTO meta VALUES(1,?1)", [ulid::Ulid::generate().to_string()])?;
+ let generation: String = db.query_row("SELECT generation FROM meta WHERE id=1", [], |r| r.get(0))?;
+ let mut pending: HashMap<String,Pending> = HashMap::new();
+ let mut counts: BTreeMap<(String,String,Dimensions),u64> = BTreeMap::new();
+ let mut persisted = db.prepare("SELECT day,metric,dimensions,value FROM counters WHERE day >= date('now','-7 days')")?;
+ for row in persisted.query_map([], |r| Ok((r.get::<_,String>(0)?,r.get::<_,String>(1)?,r.get::<_,String>(2)?,r.get::<_,i64>(3)?.max(0) as u64)))? {
+ let (day,metric,dims,value)=row?;
+ if let Ok(dims) = serde_json::from_str(&dims) {counts.insert((day,metric,dims),value);}
+ }
+ drop(persisted);
+ let mut last_flush = Instant::now();
+ let mut dirty = false;
+ let mut last_day = String::new();
+ loop {
+ let event = rx.recv_timeout(Duration::from_secs(5));
+ let day: String = db.query_row("SELECT date('now')", [], |r| r.get(0))?;
+ let mut add = |metric:&str, dims:Dimensions, value:u64| {
+ let key=(day.clone(),metric.to_owned(),dims);
+ let key=if counts.contains_key(&key) || counts.keys().filter(|(d,_,_)| d==&day).count()<256 {key}
+ else {(day.clone(),"dropped".into(),Dimensions::default())};
+ dirty = true;
+ let n=counts.entry(key).or_default(); *n=n.saturating_add(value).min(100_000_000);
+ };
+ let overflow = lost.swap(0, Ordering::Relaxed);
+ if overflow > 0 { add("dropped", Dimensions::default(), overflow); }
+ match event {
+ Ok(Event::Count(metric,dims,n))=>add(metric,dims,n),
+ Ok(Event::Start(id,dims,reply,at,incoming))=> {
+ let depth = reply.as_ref().and_then(|id|pending.get(id)).map_or(if reply.is_some() { 0 } else { 1 }, |p|if p.depth == 0 {0} else {p.depth.saturating_add(1)});
+ let reply_ms = reply.as_ref().and_then(|id|pending.get(id)).filter(|p|p.accepted).map(|parent|at.saturating_duration_since(parent.at).as_millis() as u64);
+ if incoming && let Some(ms) = reply_ms {
+ let mut d=dims.clone(); d.bucket=duration(ms).into(); add("reply_ms",d,1);
+ }
+ if pending.len() >= 2048 {pending.retain(|_,v|v.at.elapsed()<Duration::from_secs(60));}
+ if pending.len()<2048 {pending.insert(id,Pending {dims,at,accepted:false,delivered:false,is_reply:reply.is_some(),depth,reply_ms});} else {add("dropped",Dimensions::default(),1);}
+ },
+ Ok(Event::Stage(id,stage,observed))=>if let Some(Pending {dims,at,accepted,delivered,is_reply,depth,reply_ms})=pending.get_mut(&id) {
+ let duplicate=match stage {"accepted"=>std::mem::replace(accepted,true),"delivered"=>std::mem::replace(delivered,true),_=>false};
+ if !duplicate {
+ add(stage,dims.clone(),1);
+ if stage == "accepted" {
+ if *is_reply { add("reply",dims.clone(),1); }
+ if let Some(ms) = reply_ms { let mut d=dims.clone(); d.bucket=duration(*ms).into(); add("reply_ms",d,1); }
+ let mut exchange = dims.clone(); exchange.bucket = if *depth == 0 { "unknown" } else { number(*depth) }.into();
+ add("exchange_length",exchange,1);
+ }
+ if matches!(stage,"accepted"|"delivered") {
+ let mut d=dims.clone(); d.bucket=duration(observed.saturating_duration_since(*at).as_millis() as u64).into();
+ add(if stage=="accepted" {"delivery_ms"} else {"queue_age_ms"},d,1);
+ }
+ }
+ } else { add(stage, Dimensions::default(), 1); },
+ Err(mpsc::RecvTimeoutError::Disconnected)=>break,
+ Err(mpsc::RecvTimeoutError::Timeout)=>{},
+ }
+ if last_flush.elapsed() >= Duration::from_secs(5) || snapshot.lock().map(|s|s.is_none()).unwrap_or(false) {
+ let oldest:String=db.query_row("SELECT date('now','-7 days')",[],|r|r.get(0))?;
+ counts.retain(|(d,_,_),_| d>=&oldest && d<=&day);
+ pending.retain(|_,v|v.at.elapsed()<Duration::from_secs(24*3600));
+ let mut days:BTreeMap<String,Day>=BTreeMap::new();
+ days.entry(day.clone()).or_insert(Day{day:day.clone(),rows:Vec::new(),dropped:0});
+ for ((day,metric,dimensions),value) in &counts {
+ let entry=days.entry(day.clone()).or_insert(Day{day:day.clone(),rows:Vec::new(),dropped:0});
+ if metric=="dropped" {entry.dropped=entry.dropped.saturating_add(*value);} else {entry.rows.push(Row{metric:metric.clone(),dimensions:dimensions.clone(),value:*value});}
+ }
+ // Publish only persisted snapshots: an upload must never get ahead of the
+ // restart baseline. Full disks affect analytics only.
+ let mut persist=||->anyhow::Result<()> {
+ let tx=db.transaction()?;
+ tx.execute("DELETE FROM counters WHERE day < date('now','-7 days')",[])?;
+ for ((day,metric,dims),value) in &counts {tx.execute("INSERT INTO counters VALUES(?1,?2,?3,?4) ON CONFLICT(day,metric,dimensions) DO UPDATE SET value=excluded.value WHERE counters.value <> excluded.value",params![day,metric,serde_json::to_string(dims)?,*value as i64])?;}
+ tx.commit()?;Ok(())
+ };
+ if (dirty || day != last_day)
+ && persist().is_ok() { dirty = false; }
+ if !dirty
+ && let Ok(mut target)=snapshot.lock() {*target=Some(Report{version:1,generation:generation.clone(),engine_version:env!("CARGO_PKG_VERSION").into(),platform:match std::env::consts::OS {"macos"=>"macos","linux"=>"linux","windows"=>"windows",_=>"other"}.into(),days:days.into_values().collect()});}
+ if dirty && let Ok(mut target) = snapshot.lock() { *target = None; }
+ last_day = day;
+ last_flush=Instant::now();
+ }
+ }
+ Ok(())
+ };
+ let _=run();
+ // A stopped collector must not keep advertising an old snapshot as fresh.
+ if let Ok(mut target) = snapshot.lock() { *target = None; }
+ }).is_err() {return Self::default();}
+ Self { tx: Some(tx), report, dropped }
+ }
+ fn event(&self, event: Event) {
+ if let Some(tx) = &self.tx
+ && tx.try_send(event).is_err()
+ {
+ self.dropped.fetch_add(1, Ordering::Relaxed);
+ }
+ }
+ pub fn count(&self, metric: &'static str, dims: Dimensions, value: u64) {
+ self.event(Event::Count(metric, dims, value));
+ }
+ pub fn start(&self, id: &str, dims: Dimensions, reply: Option<&str>, incoming: bool) {
+ self.event(Event::Start(id.into(), dims, reply.map(str::to_owned), Instant::now(), incoming));
+ }
+ pub fn stage(&self, id: &str, stage: &'static str) {
+ self.event(Event::Stage(id.into(), stage, Instant::now()));
+ }
+ pub fn snapshot(&self) -> Option<Report> {
+ self.report.try_lock().ok().and_then(|s| s.clone())
+ }
+}
+
+/// A malformed optional label must not refuse the message. Only this finite
+/// vocabulary reaches aggregate counters; arbitrary input is discarded locally.
+pub fn purpose<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
+ let value = serde_json::Value::deserialize(d)?;
+ Ok(value.as_str().and_then(|s| match s {
+ "review" | "delegate" | "status" | "question" | "handoff" | "other" => Some(s.to_owned()),
+ _ => None,
+ }))
+}
diff --git a/tests/e2e/two_machines.py b/tests/e2e/two_machines.py
index 4918cb7..82ed460 100644
--- a/tests/e2e/two_machines.py
+++ b/tests/e2e/two_machines.py
@@ -14,6 +14,9 @@ BIN = os.path.join(ROOT, "target", "debug", "reason-network")
D = tempfile.mkdtemp(prefix="reason-network-e2e-")
H = {"alex": os.path.join(D, "alex"), "alice": os.path.join(D, "alice")}
MACHINE = {"alex": "laptop", "alice": "desktop"}
+# A stable fixture folder: long worktree names are legitimately shortened by the engine.
+SESSION_REPO = os.path.join(D, "project")
+os.makedirs(SESSION_REPO)
FAKE_CODEX = os.path.join(D, "fake-codex.sh")
QUEUE_LOG = os.path.join(D, "codex-queue.log")
# Stands in for osascript / notify-send, so the test shows nothing on screen: each machine logs what it would show.
@@ -370,13 +373,13 @@ check("…and a folder in it stays off", "sub is still off: it is in" in out, ou
time.sleep(3)
# --- sessions on both machines ---
-claude = Mcp("alex", "claude-code", strip_claude=False, cwd=ROOT)
+claude = Mcp("alex", "claude-code", strip_claude=False, cwd=SESSION_REPO)
hidden = Mcp("alex", "claude-code", strip_claude=True, cwd=PRIVATE)
codex = Mcp("alice", "codex-mcp-client", strip_claude=True, cwd=os.path.join(D, "work"))
meta = {"sessionId": "11111111-aaaa", "threadId": "11111111-aaaa"}
time.sleep(7) # Claude's session registers after 3s; presence propagates every 2s
out = codex.tool("list_team", {}, meta)
-claude_name = os.path.basename(ROOT).lower() + "-claude"
+claude_name = "project-claude"
check("alice's agent sees alex's session across machines", claude_name in out and "alex (verified) · laptop" in out, out)
check("list_team gives no team link, and says who invites people", "rn1-" not in out and "your user runs `reason-network invite`" in out, out)
check("…but not the one in alex's folder that is off", "private-claude" not in out, out)
@@ -573,8 +576,8 @@ out = codex.tool("check_inbox", {}, meta)
check("…the 39 arrive", out.count("quota ") == 39 and "one more" not in out, out[-500:])
# --- Codex hooks: session via hooks, delivery via codex queue ---
-start = hook("alice", "codex", "session-start", {"session_id": "22222222-bbbb", "cwd": ROOT, "hook_event_name": "SessionStart"})
-codex_name = os.path.basename(ROOT).lower() + "-codex"
+start = hook("alice", "codex", "session-start", {"session_id": "22222222-bbbb", "cwd": SESSION_REPO, "hook_event_name": "SessionStart"})
+codex_name = "project-codex"
check("codex SessionStart hook introduces the session", "SessionStart" in start and f"alice/{codex_name}" in start, start)
time.sleep(3)
out = cli("alex", "send", f"alice/{codex_name}", "please rebase on main")
@@ -582,7 +585,7 @@ check("message to a hooked codex session goes to codex queue", "queued into the
time.sleep(1.5)
log = open(QUEUE_LOG).read() if os.path.exists(QUEUE_LOG) else ""
check("codex queue got the thread and the message", "queue --thread 22222222-bbbb --message" in log and "please rebase on main" in log, log)
-out = hook("alice", "codex", "post-tool-use", {"session_id": "22222222-bbbb", "cwd": ROOT, "hook_event_name": "PostToolUse"})
+out = hook("alice", "codex", "post-tool-use", {"session_id": "22222222-bbbb", "cwd": SESSION_REPO, "hook_event_name": "PostToolUse"})
check("a message delivered by codex queue isn't injected again by the hook", out == "", out)
# --- hold policy ---