Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

feat(host): record onboarding, pairing and how often phones connect

leepokai7d9df65d4cfa
diff --git a/host/src/analytics.rs b/host/src/analytics.rs
index d9b3f61d..df6cdf1c 100644
--- a/host/src/analytics.rs
+++ b/host/src/analytics.rs
@@ -4,20 +4,26 @@
//! What is collected and why: docs/features/analytics.md.
use crate::LockExt as _;
-use crate::api::devices::Caller;
use crate::hub::Hub;
use crate::store::Store;
use anyhow::Result;
use serde::Deserialize;
use serde_json::{Map, Value, json};
+use std::collections::HashMap;
use std::sync::{Arc, Mutex};
use std::time::{Duration, SystemTime};
use tokio::sync::{mpsc, oneshot};
pub mod errors;
+mod lifecycle;
+mod observe;
+pub mod reported;
mod session;
mod turns;
+pub use lifecycle::{KV_STARTED, Via, device_paired, host_started, phone_connected};
+pub use observe::{answered, observe_call};
+pub use reported::track;
pub use turns::{TurnOutcome, TurnSource, turn_finished};
const KV_ENABLED: &str = "analytics_enabled";
@@ -30,14 +36,28 @@ const FLUSH_EVERY: Duration = Duration::from_secs(30);
/// Unsent events kept while offline; the oldest go first.
const MAX_PENDING: usize = 500;
-/// Everything the host reports. Names follow the `object_verb` convention.
+/// Everything the host reports. Names follow the `object_verb` convention; each event's
+/// sender and properties: docs/reference/analytics-events.md.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Event {
AppOpened,
+ WindowOpened,
+ HostStarted,
OnboardingCompleted,
+ ComputerAccessFinished,
+ SignInStarted,
+ SignInFailed,
SignedIn,
SignedOut,
+ PairingCodeCreated,
+ DevicePaired,
+ AccessRequestDenied,
+ DeviceRevoked,
+ PhoneConnected,
+ StarPromptAnswered,
+ LinkOpened,
+ ScreenViewed,
BotCreated,
BotUpdated,
BotsReordered,
@@ -47,13 +67,28 @@ pub enum Event {
TurnFinished,
SessionReset,
PermissionAnswered,
+ ReactionAdded,
+ HandoffAnswered,
+ MemoryEdited,
RoutineSaved,
+ RoutineToggled,
RoutineDeleted,
RoutineRun,
+ VoiceCallStarted,
VoiceCallFinished,
RemoteScreenOpened,
+ ScreenTakenOver,
ConnectorInstalled,
+ ConnectorsImported,
+ ConnectorRemoved,
+ ConnectorSigninStarted,
SkillInstalled,
+ SkillRemoved,
+ CredentialSaved,
+ AgentSetupStarted,
+ AgentSignedIn,
+ SettingChanged,
+ HostUpdateInstalled,
/// Error tracking (`errors`): a panic or an uncaught error.
Exception,
}
@@ -62,9 +97,22 @@ impl Event {
fn name(self) -> &'static str {
match self {
Self::AppOpened => "app_opened",
+ Self::WindowOpened => "window_opened",
+ Self::HostStarted => "host_started",
Self::OnboardingCompleted => "onboarding_completed",
+ Self::ComputerAccessFinished => "computer_access_finished",
+ Self::SignInStarted => "sign_in_started",
+ Self::SignInFailed => "sign_in_failed",
Self::SignedIn => "signed_in",
Self::SignedOut => "signed_out",
+ Self::PairingCodeCreated => "pairing_code_created",
+ Self::DevicePaired => "device_paired",
+ Self::AccessRequestDenied => "access_request_denied",
+ Self::DeviceRevoked => "device_revoked",
+ Self::PhoneConnected => "phone_connected",
+ Self::StarPromptAnswered => "star_prompt_answered",
+ Self::LinkOpened => "link_opened",
+ Self::ScreenViewed => "screen_viewed",
Self::BotCreated => "bot_created",
Self::BotUpdated => "bot_updated",
Self::BotsReordered => "bots_reordered",
@@ -74,21 +122,31 @@ impl Event {
Self::TurnFinished => "turn_finished",
Self::SessionReset => "session_reset",
Self::PermissionAnswered => "permission_answered",
+ Self::ReactionAdded => "reaction_added",
+ Self::HandoffAnswered => "handoff_answered",
+ Self::MemoryEdited => "memory_edited",
Self::RoutineSaved => "routine_saved",
+ Self::RoutineToggled => "routine_toggled",
Self::RoutineDeleted => "routine_deleted",
Self::RoutineRun => "routine_run",
+ Self::VoiceCallStarted => "voice_call_started",
Self::VoiceCallFinished => "voice_call_finished",
Self::RemoteScreenOpened => "remote_screen_opened",
+ Self::ScreenTakenOver => "screen_taken_over",
Self::ConnectorInstalled => "connector_installed",
+ Self::ConnectorsImported => "connectors_imported",
+ Self::ConnectorRemoved => "connector_removed",
+ Self::ConnectorSigninStarted => "connector_signin_started",
Self::SkillInstalled => "skill_installed",
+ Self::SkillRemoved => "skill_removed",
+ Self::CredentialSaved => "credential_saved",
+ Self::AgentSetupStarted => "agent_setup_started",
+ Self::AgentSignedIn => "agent_signed_in",
+ Self::SettingChanged => "setting_changed",
+ Self::HostUpdateInstalled => "host_update_installed",
Self::Exception => "$exception",
}
}
-
- /// Events the computer's own apps report through `track` (the rest come from API calls).
- fn client_reported(self) -> bool {
- matches!(self, Self::AppOpened | Self::OnboardingCompleted | Self::SignedIn | Self::SignedOut)
- }
}
pub struct Analytics {
@@ -96,6 +154,8 @@ pub struct Analytics {
tx: mpsc::UnboundedSender<Msg>,
rx: Mutex<Option<mpsc::UnboundedReceiver<Msg>>>,
session: Mutex<session::Session>,
+ /// The UTC day each phone last connected (`phone_connected`), in memory only.
+ phones: Mutex<HashMap<String, chrono::NaiveDate>>,
}
enum Msg {
@@ -110,7 +170,13 @@ impl Analytics {
pub fn load(store: &Store) -> Self {
let enabled = store.kv_get(KV_ENABLED).as_deref() != Some("0");
let (tx, rx) = mpsc::unbounded_channel();
- Self { enabled: Mutex::new(enabled), tx, rx: Mutex::new(Some(rx)), session: Mutex::default() }
+ Self {
+ enabled: Mutex::new(enabled),
+ tx,
+ rx: Mutex::new(Some(rx)),
+ session: Mutex::default(),
+ phones: Mutex::default(),
+ }
}
pub fn state(&self) -> bool {
@@ -124,84 +190,19 @@ impl Analytics {
}
}
-/// `track`: an event the computer's own app reports (app opened, signed in, …).
-pub fn track(hub: &Hub, b: &Value) -> Result<()> {
- let event = Event::deserialize(&b["event"]).map_err(|_| anyhow::anyhow!("unknown event"))?;
- anyhow::ensure!(event.client_reported(), "unknown event");
- capture(hub, event, Map::new());
- Ok(())
+/// A phone's platform as the catalog names it.
+fn platform(p: &str) -> &'static str {
+ match p {
+ "ios" => "ios",
+ "android" => "android",
+ "macos" => "macos",
+ _ => "other",
+ }
}
-/// The event an API call stands for, with its properties, read before the call runs.
-pub fn observe(caller: &Caller, method: &str, b: &Value) -> Option<(Event, Map<String, Value>)> {
- let mut p = Map::new();
- let event = match method {
- "createBot" => {
- let group = b["kind"] == "group";
- p.insert("kind".into(), (if group { "group" } else { "bot" }).into());
- if group {
- p.insert("members".into(), b["members"].as_array().map_or(0, Vec::len).into());
- } else {
- p.insert("agent".into(), b["backend"].clone());
- p.insert("model".into(), b["model"].clone());
- }
- Event::BotCreated
- }
- "updateBot" => Event::BotUpdated,
- "reorderBots" => Event::BotsReordered,
- "deleteBot" => Event::BotDeleted,
- "send" => {
- let in_thread = b["threadId"].as_str().is_some_and(|t| !t.is_empty());
- p.insert("in_thread".into(), in_thread.into());
- p.insert("attachments".into(), b["attachments"].as_array().map_or(0, Vec::len).into());
- Event::MessageSent
- }
- "stop" => Event::TurnStopped,
- "newSession" => Event::SessionReset,
- "respondPermission" => Event::PermissionAnswered,
- "saveRoutine" => Event::RoutineSaved,
- "deleteRoutine" => Event::RoutineDeleted,
- "runRoutine" => Event::RoutineRun,
- "logCall" => {
- p.insert("seconds".into(), b["seconds"].as_u64().unwrap_or(0).into());
- Event::VoiceCallFinished
- }
- "screenPrepare" => Event::RemoteScreenOpened,
- "installConnector" => {
- // A catalog name is public; a custom connector's URL or command is not.
- let catalog = b["registryName"].as_str().unwrap_or("custom");
- p.insert("connector".into(), catalog.into());
- Event::ConnectorInstalled
- }
- "installSkill" => {
- p.insert("custom".into(), (!b["source"].is_string()).into());
- Event::SkillInstalled
- }
- _ => return None,
- };
- let client = if matches!(caller, Caller::Local) { "local" } else { "remote" };
- p.insert("client".into(), client.into());
- Some((event, p))
-}
-
-/// `observe` plus what only the store knows: a resent message (same `clientNonce`) is
-/// not a new one, and a message names its bot's agent.
-pub fn observe_call(hub: &Hub, caller: &Caller, method: &str, b: &Value) -> Option<(Event, Map<String, Value>)> {
- let (event, mut p) = observe(caller, method, b)?;
- if event == Event::MessageSent {
- let bot = b["botId"].as_str().unwrap_or_default();
- let nonce = b["clientNonce"].as_str().unwrap_or_default();
- if !nonce.is_empty() && hub.store.find_by_nonce(bot, nonce).is_some() {
- return None;
- }
- if let Ok(Some(row)) = hub.store.bot(bot) {
- p.insert("kind".into(), (if row.config.is_group() { "group" } else { "bot" }).into());
- if !row.config.is_group() {
- p.insert("agent".into(), row.config.backend.into());
- }
- }
- }
- Some((event, p))
+/// The platform of the paired phone `key` (`other` for one this computer doesn't have).
+fn platform_of(hub: &Hub, key: &str) -> &'static str {
+ platform(hub.store.device(key).as_ref().map_or("", |d| d.platform.as_str()))
}
/// Queues one event unless the owner turned analytics off. Signed in to a Codync account,
@@ -328,46 +329,6 @@ async fn send(batch: &[Value]) -> bool {
mod tests {
use super::*;
- #[test]
- fn observed_events_carry_no_content() {
- let b = json!({"botId": "b1", "text": "secret plan", "threadId": "e1", "attachments": ["u1", "u2"]});
- let (event, p) = observe(&Caller::Local, "send", &b).expect("send is tracked");
- assert_eq!(event, Event::MessageSent);
- assert_eq!(Value::Object(p.clone()), json!({"in_thread": true, "attachments": 2, "client": "local"}));
- assert!(!Value::Object(p).to_string().contains("secret"));
-
- let custom = json!({"name": "mine", "command": "/Users/me/bin/server"});
- let (_, p) = observe(&Caller::Local, "installConnector", &custom).expect("tracked");
- assert_eq!(p["connector"], "custom");
- assert!(observe(&Caller::Local, "history", &json!({})).is_none());
- }
-
- #[tokio::test]
- async fn a_resent_message_counts_once_and_names_its_agent() {
- let dir = std::env::temp_dir().join(format!("codync-analytics-{}", uuid::Uuid::new_v4()));
- std::fs::create_dir_all(&dir).unwrap();
- let store = Store::open(std::path::Path::new(":memory:")).unwrap();
- let hub = Hub::new(
- store,
- "h".into(),
- crate::remote::identity::Identity::load_or_create(&dir).unwrap(),
- "t".into(),
- 0,
- );
- let cfg = serde_json::from_value(json!({"id": "b1", "name": "b", "backend": "codex", "cwd": "/tmp"})).unwrap();
- hub.store.save_bot(&cfg).unwrap();
- let send = json!({"botId": "b1", "text": "hi", "clientNonce": "n1"});
-
- let (_, p) = observe_call(&hub, &Caller::Local, "send", &send).expect("a new message is tracked");
- assert_eq!((p["agent"].as_str(), p["kind"].as_str()), (Some("codex"), Some("bot")));
- let lane = crate::store::Lane::main("b1");
- hub.store
- .insert_entry(&lane, crate::store::EntryKind::User, 1, &json!({"text": "hi", "clientNonce": "n1"}))
- .unwrap();
- assert!(observe_call(&hub, &Caller::Local, "send", &send).is_none(), "a replay is the same message");
- std::fs::remove_dir_all(&dir).unwrap();
- }
-
#[test]
fn on_until_the_owner_turns_it_off() {
let store = Store::open(std::path::Path::new(":memory:")).unwrap();
@@ -381,11 +342,4 @@ mod tests {
// Same vector as the iPhone's AnalyticsTests.
assert_eq!(computer_tag("AAECAwQFBgcICQoLDA0ODw"), "2d6878bee20aba04");
}
-
- #[test]
- fn only_app_events_can_be_tracked_directly() {
- assert!(Event::deserialize(&json!("app_opened")).is_ok_and(Event::client_reported));
- assert!(!Event::deserialize(&json!("message_sent")).is_ok_and(Event::client_reported));
- assert!(Event::deserialize(&json!("anything_else")).is_err());
- }
}
diff --git a/host/src/analytics/lifecycle.rs b/host/src/analytics/lifecycle.rs
new file mode 100644
index 00000000..3842dfde
--- /dev/null
+++ b/host/src/analytics/lifecycle.rs
@@ -0,0 +1,95 @@
+//! Events outside API calls: the host's own start, a phone added, a phone connecting.
+
+use super::{Analytics, Event, capture, platform, platform_of};
+use crate::LockExt as _;
+use crate::hub::Hub;
+use serde_json::{Map, Value};
+
+/// The version this host last started as (`host_started.updated_from`); empty when the install
+/// was just made and hasn't started yet (`open_store`).
+pub const KV_STARTED: &str = "analytics_version";
+
+/// How a phone was added (`device_paired`).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Via {
+ /// A pairing code redeemed.
+ Qr,
+ /// An account access request approved.
+ Account,
+}
+
+/// `host_started`, once per start of the host; `service`: run by launchd, systemd or Windows' runner.
+pub fn host_started(hub: &Hub, service: bool) {
+ let version = env!("CARGO_PKG_VERSION");
+ let p = started(hub.store.kv_get(KV_STARTED).as_deref(), version, service);
+ if let Err(e) = hub.store.kv_set(KV_STARTED, version) {
+ tracing::warn!(error = format!("{e:#}"), "couldn't save the version this host started as");
+ }
+ capture(hub, Event::HostStarted, p);
+}
+
+/// `host_started`'s properties, from the version the host last started as (`None`: a host
+/// from before this was kept, which is neither new nor known to have changed).
+fn started(last: Option<&str>, version: &str, service: bool) -> Map<String, Value> {
+ let mut p = Map::new();
+ p.insert("first_run".into(), (last == Some("")).into());
+ if let Some(from) = last.filter(|v| !v.is_empty() && *v != version) {
+ p.insert("updated_from".into(), from.into());
+ }
+ p.insert("service".into(), service.into());
+ p
+}
+
+/// `device_paired`: a phone was added to this computer.
+pub fn device_paired(hub: &Hub, via: Via, device_platform: &str, automatic: bool) {
+ let mut p = Map::new();
+ p.insert("via".into(), (if via == Via::Qr { "qr" } else { "account" }).into());
+ p.insert("platform".into(), platform(device_platform).into());
+ p.insert("automatic".into(), automatic.into());
+ capture(hub, Event::DevicePaired, p);
+}
+
+/// `phone_connected`: a paired phone opened a channel, counted once per phone per UTC day.
+pub fn phone_connected(hub: &Hub, key: &str) {
+ if !hub.analytics.first_today(key, chrono::Utc::now().date_naive()) {
+ return;
+ }
+ let mut p = Map::new();
+ p.insert("platform".into(), platform_of(hub, key).into());
+ capture(hub, Event::PhoneConnected, p);
+}
+
+impl Analytics {
+ /// Whether `phone` connects for the first time on `day`. Memory only: a restart may count one more.
+ fn first_today(&self, phone: &str, day: chrono::NaiveDate) -> bool {
+ self.phones.locked().insert(phone.to_owned(), day) != Some(day)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::json;
+
+ #[test]
+ fn a_phone_counts_once_a_day() {
+ let store = crate::store::Store::open(std::path::Path::new(":memory:")).unwrap();
+ let a = Analytics::load(&store);
+ let day = chrono::NaiveDate::from_ymd_opt(2026, 10, 19).unwrap();
+ let next = day.succ_opt().unwrap();
+ assert!(a.first_today("k1", day));
+ assert!(!a.first_today("k1", day), "reconnecting the same day");
+ assert!(a.first_today("k2", day), "another phone");
+ assert!(a.first_today("k1", next), "the next day");
+ assert!(!a.first_today("k1", next));
+ }
+
+ #[test]
+ fn a_start_says_whether_it_is_new_or_updated() {
+ let p = |last, service| Value::Object(started(last, "2.20.0", service));
+ assert_eq!(p(Some(""), true), json!({"first_run": true, "service": true}));
+ assert_eq!(p(Some("2.19.3"), false), json!({"first_run": false, "updated_from": "2.19.3", "service": false}));
+ assert_eq!(p(Some("2.20.0"), true), json!({"first_run": false, "service": true}));
+ assert_eq!(p(None, true), json!({"first_run": false, "service": true}), "a host from before this was kept");
+ }
+}
diff --git a/host/src/analytics/observe.rs b/host/src/analytics/observe.rs
new file mode 100644
index 00000000..d710c01c
--- /dev/null
+++ b/host/src/analytics/observe.rs
@@ -0,0 +1,459 @@
+//! What an API call stands for: `api::dispatch` reports each successful call as one event.
+//! Values come from a request only when they are fixed names, booleans, counts or catalog ids.
+
+use super::{Event, platform_of};
+use crate::api::devices::Caller;
+use crate::hub::Hub;
+use crate::store::BotConfig;
+use serde_json::{Map, Value};
+
+/// Methods that stand for one event with one fixed property.
+const FIXED: [(&str, Event, &str, &str); 19] = [
+ ("saveMemory", Event::MemoryEdited, "action", "save"),
+ ("pinMemory", Event::MemoryEdited, "action", "pin"),
+ ("archiveMemory", Event::MemoryEdited, "action", "archive"),
+ ("forgetMemory", Event::MemoryEdited, "action", "forget"),
+ ("clearMemory", Event::MemoryEdited, "action", "clear"),
+ ("undoDream", Event::MemoryEdited, "action", "undo_dream"),
+ ("answerMemory", Event::MemoryEdited, "action", "answer"),
+ ("undoMemory", Event::MemoryEdited, "action", "undo"),
+ ("saveMemoryFile", Event::MemoryEdited, "action", "file_save"),
+ ("deleteMemoryFile", Event::MemoryEdited, "action", "file_delete"),
+ ("restoreMemoryFile", Event::MemoryEdited, "action", "file_restore"),
+ ("editHandoff", Event::HandoffAnswered, "action", "edit"),
+ ("keepConversation", Event::HandoffAnswered, "action", "keep"),
+ ("credentialSaveLogin", Event::CredentialSaved, "kind", "login"),
+ ("credentialSetOnePassword", Event::CredentialSaved, "kind", "onepassword"),
+ ("credentialUpdateConnector", Event::CredentialSaved, "kind", "connector"),
+ ("setComposioKey", Event::CredentialSaved, "kind", "composio"),
+ ("setVoiceKey", Event::CredentialSaved, "kind", "voice"),
+ ("setAgentEnv", Event::CredentialSaved, "kind", "agent_env"),
+];
+
+/// Switches the host owns (`setting_changed`): the method and the setting it names.
+const SETTINGS: [(&str, &str); 4] = [
+ ("setCloud", "remote_access"),
+ ("setApproval", "approval"),
+ ("setHostAutomaticUpdates", "automatic_updates"),
+ ("setScreenEnabled", "remote_screen"),
+];
+
+/// The event an API call stands for, with its properties, read before the call runs.
+pub fn observe(caller: &Caller, method: &str, b: &Value) -> Option<(Event, Map<String, Value>)> {
+ let mut p = Map::new();
+ let event = if let Some(&(_, event, key, value)) = FIXED.iter().find(|f| f.0 == method) {
+ // An empty key or token removes the saved one.
+ let cleared = matches!(method, "setComposioKey" | "setVoiceKey" | "credentialSetOnePassword")
+ && ["key", "token"].iter().all(|k| b[*k].as_str().is_none_or(|v| v.trim().is_empty()));
+ if cleared {
+ return None;
+ }
+ p.insert(key.into(), value.into());
+ event
+ } else if let Some(&(_, setting)) = SETTINGS.iter().find(|s| s.0 == method) {
+ let on = if method == "setApproval" { b["approval"] == "auto" } else { b["enabled"] == true };
+ p.insert("setting".into(), setting.into());
+ p.insert("on".into(), on.into());
+ Event::SettingChanged
+ } else {
+ call_event(method, b, &mut p)?
+ };
+ let client = if matches!(caller, Caller::Local) { "local" } else { "remote" };
+ p.insert("client".into(), client.into());
+ Some((event, p))
+}
+
+/// The rest of `observe`: one arm per method.
+fn call_event(method: &str, b: &Value, p: &mut Map<String, Value>) -> Option<Event> {
+ Some(match method {
+ "createBot" => {
+ let group = b["kind"] == "group";
+ p.insert("kind".into(), (if group { "group" } else { "bot" }).into());
+ if group {
+ p.insert("members".into(), b["members"].as_array().map_or(0, Vec::len).into());
+ } else {
+ p.insert("agent".into(), b["backend"].clone());
+ p.insert("model".into(), b["model"].clone());
+ }
+ Event::BotCreated
+ }
+ "updateBot" => Event::BotUpdated,
+ "reorderBots" => Event::BotsReordered,
+ "deleteBot" => Event::BotDeleted,
+ "send" => {
+ let in_thread = b["threadId"].as_str().is_some_and(|t| !t.is_empty());
+ p.insert("in_thread".into(), in_thread.into());
+ p.insert("attachments".into(), b["attachments"].as_array().map_or(0, Vec::len).into());
+ Event::MessageSent
+ }
+ "stop" => Event::TurnStopped,
+ "newSession" => Event::SessionReset,
+ "respondPermission" => Event::PermissionAnswered,
+ "react" => Event::ReactionAdded,
+ "saveRoutine" => Event::RoutineSaved,
+ "setRoutineEnabled" => {
+ p.insert("enabled".into(), b["enabled"].as_bool()?.into());
+ Event::RoutineToggled
+ }
+ "deleteRoutine" => Event::RoutineDeleted,
+ "runRoutine" => Event::RoutineRun,
+ "logCall" => {
+ p.insert("seconds".into(), b["seconds"].as_u64().unwrap_or(0).into());
+ Event::VoiceCallFinished
+ }
+ "screenPrepare" => Event::RemoteScreenOpened,
+ // Handing the screen back is not a takeover.
+ "screenTakeover" if b["on"] == true => Event::ScreenTakenOver,
+ "installConnector" => {
+ // A catalog name is public; a custom connector's URL or command is not.
+ let catalog = b["registryName"].as_str().unwrap_or("custom");
+ p.insert("connector".into(), catalog.into());
+ Event::ConnectorInstalled
+ }
+ // A Composio app: counted once its connection is active (`answered`).
+ "composioConnection" | "composioConnectFields" => {
+ p.insert("connector".into(), "composio".into());
+ Event::ConnectorInstalled
+ }
+ "importConnectors" => Event::ConnectorsImported,
+ "removeConnector" => Event::ConnectorRemoved,
+ "connectorSignIn" => Event::ConnectorSigninStarted,
+ "installSkill" => {
+ p.insert("custom".into(), (!b["source"].is_string()).into());
+ Event::SkillInstalled
+ }
+ "removeSkill" => Event::SkillRemoved,
+ "agentSetup" | "agentAuthenticate" => {
+ // An agent's catalog id; Node.js setup names none.
+ if let Some(agent) = b["backend"].as_str().filter(|a| !a.is_empty()) {
+ p.insert("agent".into(), agent.into());
+ }
+ if method == "agentSetup" { Event::AgentSetupStarted } else { Event::AgentSignedIn }
+ }
+ "installHostUpdate" => Event::HostUpdateInstalled,
+ "pairing" => Event::PairingCodeCreated,
+ // Approving is `device_paired`, from `cloud::decide`.
+ "decideAccessRequest" if b["approve"] == false => Event::AccessRequestDenied,
+ "revokeDevice" => Event::DeviceRevoked,
+ _ => return None,
+ })
+}
+
+/// `observe` plus what only the store knows: a resent message (same `clientNonce`) is
+/// not a new one, a message names its bot's agent, an edit the settings it changes, a
+/// permission answer the kind of option picked, and a phone its platform.
+pub fn observe_call(hub: &Hub, caller: &Caller, method: &str, b: &Value) -> Option<(Event, Map<String, Value>)> {
+ let (event, mut p) = observe(caller, method, b)?;
+ match event {
+ Event::MessageSent => {
+ let bot = b["botId"].as_str().unwrap_or_default();
+ let nonce = b["clientNonce"].as_str().unwrap_or_default();
+ if !nonce.is_empty() && hub.store.find_by_nonce(bot, nonce).is_some() {
+ return None;
+ }
+ if let Ok(Some(row)) = hub.store.bot(bot) {
+ p.insert("kind".into(), (if row.config.is_group() { "group" } else { "bot" }).into());
+ if !row.config.is_group() {
+ p.insert("agent".into(), row.config.backend.into());
+ }
+ }
+ }
+ Event::BotUpdated => {
+ if let Ok(Some(row)) = hub.store.bot(b["id"].as_str().unwrap_or_default()) {
+ p.insert("fields".into(), changed_fields(&row.config, b).into());
+ }
+ }
+ Event::PermissionAnswered => {
+ let card = hub.store.entry(b["entryId"].as_str().unwrap_or_default());
+ p.insert("choice".into(), choice(card.as_ref().map(|e| &e.data), &b["optionId"]).into());
+ }
+ _ => {}
+ }
+ if let Caller::Device { key, .. } = caller {
+ p.insert("platform".into(), platform_of(hub, key).into());
+ }
+ Some((event, p))
+}
+
+/// What only the answer tells: how many connectors an import added, and whether a Composio
+/// app is connected yet (its sign-in is polled until the connection is active). `None`: not an event.
+pub fn answered(event: Event, mut p: Map<String, Value>, answer: &Value) -> Option<Map<String, Value>> {
+ match event {
+ Event::ConnectorsImported => {
+ p.insert("count".into(), answer["items"].as_array().map_or(0, Vec::len).into());
+ }
+ Event::ConnectorInstalled
+ if p.get("connector").and_then(Value::as_str) == Some("composio") && answer["status"] != "active" =>
+ {
+ return None;
+ }
+ _ => {}
+ }
+ Some(p)
+}
+
+/// The bot settings a patch changes, by name (never their values), sorted.
+fn changed_fields(stored: &BotConfig, patch: &Value) -> Vec<String> {
+ let Ok(Value::Object(before)) = serde_json::to_value(stored) else { return vec![] };
+ let mut merged = before.clone();
+ for (k, v) in patch.as_object().into_iter().flatten() {
+ merged.insert(k.clone(), v.clone());
+ }
+ // Read back as a bot: unknown keys fall away, and a value written another way (`null` for
+ // `false`, `""` for the bot's own workspace) counts as unchanged.
+ let Ok(mut after) = serde_json::from_value::<BotConfig>(Value::Object(merged)) else { return vec![] };
+ if !after.is_group() && after.cwd.is_empty() {
+ after.cwd = crate::agent::workspace::path(&after.id).to_string_lossy().into_owned();
+ }
+ let Ok(Value::Object(after)) = serde_json::to_value(after) else { return vec![] };
+ let mut fields: Vec<String> = patch
+ .as_object()
+ .into_iter()
+ .flatten()
+ .map(|(k, _)| k)
+ .filter(|k| !matches!(k.as_str(), "id" | "createdAt") && after.get(*k) != before.get(*k))
+ .cloned()
+ .collect();
+ fields.sort();
+ fields
+}
+
+/// The kind of option a permission answer picked (ACP's `kind`), from its card.
+fn choice(card: Option<&Value>, option: &Value) -> &'static str {
+ let kind = card
+ .and_then(|c| c["options"].as_array())
+ .and_then(|o| o.iter().find(|o| !option.is_null() && o["optionId"] == *option))
+ .and_then(|o| o["kind"].as_str());
+ match kind {
+ Some("allow_once") => "allow_once",
+ Some("allow_always") => "allow_always",
+ Some("reject_once") => "reject_once",
+ Some("reject_always") => "reject_always",
+ _ => "other",
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::store::{Device, DeviceSource, Store};
+ use serde_json::json;
+
+ fn temp_hub() -> (std::sync::Arc<Hub>, std::path::PathBuf) {
+ let dir = std::env::temp_dir().join(format!("codync-analytics-{}", uuid::Uuid::new_v4()));
+ std::fs::create_dir_all(&dir).unwrap();
+ let store = Store::open(std::path::Path::new(":memory:")).unwrap();
+ let identity = crate::remote::identity::Identity::load_or_create(&dir).unwrap();
+ (Hub::new(store, "h".into(), identity, "t".into(), 0), dir)
+ }
+
+ fn props(method: &str, b: &Value) -> Option<(Event, Value)> {
+ observe(&Caller::Local, method, b).map(|(e, p)| (e, Value::Object(p)))
+ }
+
+ #[test]
+ fn observed_events_carry_no_content() {
+ let b = json!({"botId": "b1", "text": "secret plan", "threadId": "e1", "attachments": ["u1", "u2"]});
+ let (event, p) = props("send", &b).expect("send is tracked");
+ assert_eq!(event, Event::MessageSent);
+ assert_eq!(p, json!({"in_thread": true, "attachments": 2, "client": "local"}));
+ assert!(!p.to_string().contains("secret"));
+
+ let custom = json!({"name": "mine", "command": "/Users/me/bin/server"});
+ let (_, p) = props("installConnector", &custom).expect("tracked");
+ assert_eq!(p["connector"], "custom");
+ assert!(props("history", &json!({})).is_none());
+ assert!(props("memory", &json!({"botId": "b1"})).is_none(), "reading memory is not an edit");
+ assert!(props("memoryFile", &json!({"name": "notes.md"})).is_none());
+ }
+
+ #[test]
+ fn memory_handoff_and_credentials_name_a_fixed_action() {
+ let memory = props("saveMemory", &json!({"botId": "b1", "text": "likes tea"})).expect("an edit");
+ assert_eq!(memory, (Event::MemoryEdited, json!({"action": "save", "client": "local"})));
+ assert_eq!(
+ props("restoreMemoryFile", &json!({})).map(|(_, p)| p["action"].clone()),
+ Some(json!("file_restore"))
+ );
+ assert_eq!(props("undoDream", &json!({})).map(|(_, p)| p["action"].clone()), Some(json!("undo_dream")));
+ assert_eq!(
+ props("keepConversation", &json!({})),
+ Some((Event::HandoffAnswered, json!({"action": "keep", "client": "local"})))
+ );
+ assert_eq!(props("editHandoff", &json!({"text": "x"})).map(|(_, p)| p["action"].clone()), Some(json!("edit")));
+
+ let login = json!({"site": "example.com", "username": "me", "password": "hunter2"});
+ assert_eq!(
+ props("credentialSaveLogin", &login),
+ Some((Event::CredentialSaved, json!({"kind": "login", "client": "local"})))
+ );
+ assert_eq!(
+ props("setVoiceKey", &json!({"provider": "openai", "key": "sk-1"})).map(|(_, p)| p["kind"].clone()),
+ Some(json!("voice"))
+ );
+ assert_eq!(
+ props("setAgentEnv", &json!({"backend": "codex", "vars": {"K": "v"}})).map(|(_, p)| p["kind"].clone()),
+ Some(json!("agent_env"))
+ );
+ assert!(props("setComposioKey", &json!({"key": " "})).is_none(), "an empty key removes it");
+ assert!(props("credentialSetOnePassword", &json!({"token": ""})).is_none());
+ }
+
+ #[test]
+ fn settings_routines_screen_and_devices() {
+ let setting = |m: &str, b: Value| props(m, &b).map(|(e, p)| (e, p["setting"].clone(), p["on"].clone()));
+ assert_eq!(
+ setting("setCloud", json!({"enabled": true})),
+ Some((Event::SettingChanged, json!("remote_access"), json!(true)))
+ );
+ assert_eq!(setting("setApproval", json!({"approval": "auto"})).map(|s| s.2), Some(json!(true)));
+ assert_eq!(setting("setApproval", json!({"approval": "code"})).map(|s| s.2), Some(json!(false)));
+ assert_eq!(
+ setting("setHostAutomaticUpdates", json!({"enabled": false})).map(|s| s.1),
+ Some(json!("automatic_updates"))
+ );
+ assert_eq!(setting("setScreenEnabled", json!({"enabled": true})).map(|s| s.1), Some(json!("remote_screen")));
+
+ assert_eq!(
+ props("setRoutineEnabled", &json!({"botId": "b", "id": "r", "enabled": false})),
+ Some((Event::RoutineToggled, json!({"enabled": false, "client": "local"})))
+ );
+ assert_eq!(props("screenTakeover", &json!({"on": true})).map(|(e, _)| e), Some(Event::ScreenTakenOver));
+ assert!(props("screenTakeover", &json!({"on": false})).is_none(), "handing it back");
+ assert_eq!(props("pairing", &json!({})), Some((Event::PairingCodeCreated, json!({"client": "local"}))));
+ assert_eq!(
+ props("decideAccessRequest", &json!({"requestId": "req_1", "approve": false})).map(|(e, _)| e),
+ Some(Event::AccessRequestDenied)
+ );
+ assert!(
+ props("decideAccessRequest", &json!({"requestId": "req_1", "approve": true})).is_none(),
+ "approval is device_paired"
+ );
+ assert_eq!(
+ props("revokeDevice", &json!({"key": "k"})),
+ Some((Event::DeviceRevoked, json!({"client": "local"})))
+ );
+ assert_eq!(
+ props("installHostUpdate", &json!({"force": true})).map(|(e, _)| e),
+ Some(Event::HostUpdateInstalled)
+ );
+ }
+
+ #[test]
+ fn connectors_skills_and_agents() {
+ assert_eq!(
+ props("removeConnector", &json!({"id": "github"})),
+ Some((Event::ConnectorRemoved, json!({"client": "local"})))
+ );
+ assert_eq!(props("removeSkill", &json!({"id": "s"})).map(|(e, _)| e), Some(Event::SkillRemoved));
+ assert_eq!(props("connectorSignIn", &json!({"id": "c"})).map(|(e, _)| e), Some(Event::ConnectorSigninStarted));
+ let setup = props("agentSetup", &json!({"backend": "claude-acp", "step": "install"}));
+ assert_eq!(setup, Some((Event::AgentSetupStarted, json!({"agent": "claude-acp", "client": "local"}))));
+ assert_eq!(props("agentSetup", &json!({"step": "node"})).map(|(_, p)| p), Some(json!({"client": "local"})));
+ let signed = props("agentAuthenticate", &json!({"backend": "codex", "method": "chatgpt"}));
+ assert_eq!(signed, Some((Event::AgentSignedIn, json!({"agent": "codex", "client": "local"}))));
+
+ let (event, p) = observe(&Caller::Local, "importConnectors", &json!({"config": "{\"secret\": 1}"})).unwrap();
+ let p = answered(event, p, &json!({"items": [{"id": "a"}, {"id": "b"}]})).expect("an import");
+ assert_eq!(Value::Object(p), json!({"count": 2, "client": "local"}));
+
+ let (event, p) = observe(&Caller::Local, "composioConnection", &json!({"id": "ca_1"})).unwrap();
+ assert!(answered(event, p.clone(), &json!({"status": "initiated"})).is_none(), "still signing in");
+ let p = answered(event, p, &json!({"status": "active", "toolkit": "gmail"})).expect("connected");
+ assert_eq!(
+ (event, Value::Object(p)),
+ (Event::ConnectorInstalled, json!({"connector": "composio", "client": "local"}))
+ );
+ }
+
+ #[test]
+ fn a_bot_edit_names_the_settings_it_changes() {
+ let stored: BotConfig = serde_json::from_value(
+ json!({"id": "b1", "name": "Ada", "backend": "codex", "cwd": "/tmp", "model": "gpt-5"}),
+ )
+ .unwrap();
+ let patch = json!({"id": "b1", "name": "Ada", "model": "gpt-6", "pinned": true, "harnessMemory": null,
+ "sharedMemory": true, "secret": "x", "createdAt": 5});
+ assert_eq!(changed_fields(&stored, &patch), ["model", "pinned", "sharedMemory"]);
+ assert_eq!(changed_fields(&stored, &json!({"id": "b1", "name": "Ada"})), Vec::<String>::new());
+
+ // Clients send `""` for the bot's own workspace, which the store keeps as its path.
+ let own = crate::agent::workspace::path("b1").to_string_lossy().into_owned();
+ let stored: BotConfig =
+ serde_json::from_value(json!({"id": "b1", "name": "Ada", "backend": "codex", "cwd": own})).unwrap();
+ assert_eq!(changed_fields(&stored, &json!({"id": "b1", "cwd": "", "fastMode": true})), ["fastMode"]);
+ assert_eq!(changed_fields(&stored, &json!({"id": "b1", "cwd": "/tmp"})), ["cwd"]);
+ }
+
+ #[test]
+ fn a_permission_answer_names_the_kind_picked() {
+ let card = json!({"title": "rm -rf", "options": [
+ {"optionId": "a", "name": "Allow", "kind": "allow_once"},
+ {"optionId": "r", "name": "Always reject", "kind": "reject_always"},
+ {"optionId": "x", "name": "Odd", "kind": "something_new"}]});
+ assert_eq!(choice(Some(&card), &json!("a")), "allow_once");
+ assert_eq!(choice(Some(&card), &json!("r")), "reject_always");
+ assert_eq!(choice(Some(&card), &json!("x")), "other");
+ assert_eq!(choice(Some(&card), &Value::Null), "other");
+ assert_eq!(choice(None, &json!("a")), "other");
+ }
+
+ #[tokio::test]
+ async fn a_resent_message_counts_once_and_names_its_agent() {
+ let (hub, dir) = temp_hub();
+ let cfg = serde_json::from_value(json!({"id": "b1", "name": "b", "backend": "codex", "cwd": "/tmp"})).unwrap();
+ hub.store.save_bot(&cfg).unwrap();
+ let send = json!({"botId": "b1", "text": "hi", "clientNonce": "n1"});
+
+ let (_, p) = observe_call(&hub, &Caller::Local, "send", &send).expect("a new message is tracked");
+ assert_eq!((p["agent"].as_str(), p["kind"].as_str()), (Some("codex"), Some("bot")));
+ let lane = crate::store::Lane::main("b1");
+ hub.store
+ .insert_entry(&lane, crate::store::EntryKind::User, 1, &json!({"text": "hi", "clientNonce": "n1"}))
+ .unwrap();
+ assert!(observe_call(&hub, &Caller::Local, "send", &send).is_none(), "a replay is the same message");
+ std::fs::remove_dir_all(&dir).unwrap();
+ }
+
+ #[tokio::test]
+ async fn store_lookups_add_fields_choice_and_platform() {
+ let (hub, dir) = temp_hub();
+ let cfg = serde_json::from_value(json!({"id": "b1", "name": "b", "backend": "codex", "cwd": "/tmp"})).unwrap();
+ hub.store.save_bot(&cfg).unwrap();
+ let (_, p) =
+ observe_call(&hub, &Caller::Local, "updateBot", &json!({"id": "b1", "permission": "ask"})).unwrap();
+ assert_eq!(p["fields"], json!(["permission"]));
+
+ let card =
+ json!({"status": "pending", "options": [{"optionId": "o1", "name": "Allow", "kind": "allow_always"}]});
+ let e = hub
+ .store
+ .insert_entry(&crate::store::Lane::main("b1"), crate::store::EntryKind::Permission, 1, &card)
+ .unwrap();
+ let answer = json!({"entryId": e.id, "optionId": "o1"});
+
+ let phone = Caller::Device { key: "k1".into(), scopes: vec![] };
+ hub.store
+ .put_device(&Device {
+ key: "k1".into(),
+ name: "Kevin's phone".into(),
+ platform: "android".into(),
+ source: DeviceSource::Local,
+ grant_id: None,
+ scopes: vec![],
+ lease_until: None,
+ created_at: 0,
+ last_seen_at: None,
+ })
+ .unwrap();
+ let (event, p) = observe_call(&hub, &phone, "respondPermission", &answer).unwrap();
+ assert_eq!(
+ (event, Value::Object(p)),
+ (Event::PermissionAnswered, json!({"choice": "allow_always", "client": "remote", "platform": "android"}))
+ );
+ let stranger = Caller::Device { key: "gone".into(), scopes: vec![] };
+ let (_, p) = observe_call(&hub, &stranger, "stop", &json!({"botId": "b1"})).unwrap();
+ assert_eq!(p["platform"], "other");
+ std::fs::remove_dir_all(&dir).unwrap();
+ }
+}
diff --git a/host/src/analytics/reported.rs b/host/src/analytics/reported.rs
new file mode 100644
index 00000000..48258d58
--- /dev/null
+++ b/host/src/analytics/reported.rs
@@ -0,0 +1,274 @@
+//! `track`: the app-level events the desktop app and terminal UI report. Only the catalog's
+//! events and values get through (docs/reference/analytics-events.md): the host reads the body
+//! into these types and builds the properties from them, so no client text can slip in.
+
+use super::{Event, capture};
+use crate::hub::Hub;
+use anyhow::{Context as _, Result};
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+
+/// A `track` body: which app reports, and what.
+#[derive(Debug, PartialEq, Serialize, Deserialize)]
+pub struct Track {
+ /// Older desktop builds don't say.
+ #[serde(default)]
+ pub app: App,
+ #[serde(flatten)]
+ pub event: Reported,
+}
+
+/// The computer's app that reports.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum App {
+ #[default]
+ Desktop,
+ Tui,
+ #[serde(other)]
+ Other,
+}
+
+/// What `track` accepts, each with exactly its catalog properties; other keys are dropped.
+#[derive(Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "event", rename_all = "snake_case")]
+pub enum Reported {
+ AppOpened {
+ /// Opened by the login item (desktop).
+ #[serde(skip_serializing_if = "Option::is_none")]
+ at_login: Option<bool>,
+ },
+ WindowOpened,
+ OnboardingCompleted {
+ #[serde(skip_serializing_if = "Option::is_none")]
+ signed_in: Option<bool>,
+ },
+ ComputerAccessFinished {
+ /// Screen recording and control granted.
+ ready: bool,
+ onboarding: bool,
+ },
+ SignInStarted {
+ provider: Provider,
+ },
+ SignInFailed {
+ provider: Provider,
+ reason: SignInFailure,
+ },
+ SignedIn {
+ #[serde(skip_serializing_if = "Option::is_none")]
+ provider: Option<Provider>,
+ },
+ SignedOut,
+ StarPromptAnswered {
+ ask: Ask,
+ starred: bool,
+ },
+ LinkOpened {
+ link: Link,
+ },
+ ScreenViewed {
+ screen: Screen,
+ },
+ VoiceCallStarted {
+ engine: Engine,
+ },
+}
+
+// Value lists. A value a newer client adds arrives as `other` instead of being refused.
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Provider {
+ Apple,
+ Google,
+ Hosted,
+ #[serde(other)]
+ Other,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SignInFailure {
+ Cancelled,
+ Timeout,
+ Verification,
+ Error,
+ #[serde(other)]
+ Other,
+}
+
+/// Which time the GitHub star sheet asked.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Ask {
+ First,
+ Second,
+ #[serde(other)]
+ Other,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Link {
+ Github,
+ Docs,
+ Issues,
+ Discord,
+ AppStore,
+ Demo,
+ Tailscale,
+ Privacy,
+ Support,
+ InstallCommand,
+ #[serde(other)]
+ Other,
+}
+
+/// One screen, sheet or tab, named the same on every client that has it.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+#[expect(clippy::enum_variant_names, reason = "the catalog names the remote screen `remote_screen`")]
+pub enum Screen {
+ Bots,
+ State,
+ Chat,
+ Thread,
+ Trace,
+ BotDetails,
+ Memory,
+ Routines,
+ Marketplace,
+ Settings,
+ Computers,
+ Usage,
+ Account,
+ Pairing,
+ VoiceSettings,
+ RemoteScreen,
+ ComputerAccess,
+ Help,
+ #[serde(other)]
+ Other,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Engine {
+ OnDevice,
+ Openai,
+ Gemini,
+ Cloud,
+ #[serde(other)]
+ Other,
+}
+
+impl Track {
+ /// The body to send for `event`, as `app` (what the terminal UI posts).
+ pub fn body(app: App, event: Reported) -> Value {
+ serde_json::to_value(Self { app, event }).expect("plain enums and booleans always serialize")
+ }
+}
+
+/// `track`: an event the computer's own app reports (app opened, signed in, …).
+pub fn track(hub: &Hub, b: &Value) -> Result<()> {
+ let (event, properties) = read(b)?;
+ capture(hub, event, properties);
+ Ok(())
+}
+
+/// The event and its properties, rebuilt from the typed body.
+fn read(b: &Value) -> Result<(Event, Map<String, Value>)> {
+ let track = Track::deserialize(b).context("unknown event")?;
+ let Value::Object(mut p) = serde_json::to_value(&track)? else { anyhow::bail!("unknown event") };
+ let event = Event::deserialize(p.remove("event").unwrap_or_default()).context("unknown event")?;
+ Ok((event, p))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::json;
+
+ fn read_json(b: &Value) -> Option<(Event, Value)> {
+ read(b).ok().map(|(e, p)| (e, Value::Object(p)))
+ }
+
+ #[test]
+ fn an_older_desktop_body_still_counts() {
+ assert_eq!(read_json(&json!({"event": "app_opened"})), Some((Event::AppOpened, json!({"app": "desktop"}))));
+ assert_eq!(read_json(&json!({"event": "signed_in"})), Some((Event::SignedIn, json!({"app": "desktop"}))));
+ assert_eq!(
+ read_json(&json!({"event": "onboarding_completed"})),
+ Some((Event::OnboardingCompleted, json!({"app": "desktop"})))
+ );
+ assert_eq!(read_json(&json!({"event": "signed_out"})), Some((Event::SignedOut, json!({"app": "desktop"}))));
+ }
+
+ #[test]
+ fn only_catalog_events_and_values_get_through() {
+ assert!(read(&json!({"event": "message_sent"})).is_err(), "the host reports that one itself");
+ assert!(read(&json!({"event": "anything_else"})).is_err());
+ assert!(read(&json!({})).is_err());
+ assert!(read(&json!({"event": "computer_access_finished", "ready": true})).is_err(), "missing `onboarding`");
+
+ let newer = json!({"event": "screen_viewed", "app": "tui", "screen": "hologram"});
+ assert_eq!(read_json(&newer), Some((Event::ScreenViewed, json!({"app": "tui", "screen": "other"}))));
+ let unknown_app = json!({"event": "window_opened", "app": "watch"});
+ assert_eq!(read_json(&unknown_app), Some((Event::WindowOpened, json!({"app": "other"}))));
+
+ // Extra keys, content above all, never reach the event.
+ let noisy = json!({"event": "link_opened", "link": "discord", "url": "https://example.com/secret",
+ "text": "my prompt", "app": "desktop"});
+ let (_, p) = read_json(&noisy).unwrap();
+ assert_eq!(p, json!({"app": "desktop", "link": "discord"}));
+ let (_, p) = read_json(&json!({"event": "signed_out", "email": "[email protected]"})).unwrap();
+ assert_eq!(p, json!({"app": "desktop"}));
+ }
+
+ #[test]
+ fn every_reported_event_keeps_its_properties() {
+ let cases = [
+ (json!({"event": "app_opened", "app": "desktop", "at_login": true}), Event::AppOpened),
+ (json!({"event": "window_opened", "app": "desktop"}), Event::WindowOpened),
+ (
+ json!({"event": "onboarding_completed", "app": "desktop", "signed_in": false}),
+ Event::OnboardingCompleted,
+ ),
+ (
+ json!({"event": "computer_access_finished", "app": "desktop", "ready": true, "onboarding": false}),
+ Event::ComputerAccessFinished,
+ ),
+ (json!({"event": "sign_in_started", "app": "desktop", "provider": "apple"}), Event::SignInStarted),
+ (
+ json!({"event": "sign_in_failed", "app": "desktop", "provider": "hosted", "reason": "verification"}),
+ Event::SignInFailed,
+ ),
+ (json!({"event": "signed_in", "app": "desktop", "provider": "google"}), Event::SignedIn),
+ (json!({"event": "signed_out", "app": "desktop"}), Event::SignedOut),
+ (
+ json!({"event": "star_prompt_answered", "app": "desktop", "ask": "second", "starred": true}),
+ Event::StarPromptAnswered,
+ ),
+ (json!({"event": "link_opened", "app": "desktop", "link": "install_command"}), Event::LinkOpened),
+ (json!({"event": "screen_viewed", "app": "tui", "screen": "bot_details"}), Event::ScreenViewed),
+ (json!({"event": "voice_call_started", "app": "desktop", "engine": "on_device"}), Event::VoiceCallStarted),
+ ];
+ for (body, event) in cases {
+ let mut expected = body.clone();
+ let name = expected.as_object_mut().unwrap().remove("event").unwrap();
+ assert_eq!(name, event.name(), "the catalog name");
+ assert_eq!(read_json(&body), Some((event, expected)), "{body}");
+ }
+ }
+
+ #[test]
+ fn the_terminal_ui_body_reads_back() {
+ let body = Track::body(App::Tui, Reported::ScreenViewed { screen: Screen::Memory });
+ assert_eq!(body, json!({"event": "screen_viewed", "app": "tui", "screen": "memory"}));
+ assert_eq!(
+ Track::body(App::Tui, Reported::AppOpened { at_login: None }),
+ json!({"event": "app_opened", "app": "tui"})
+ );
+ }
+}
diff --git a/host/src/api/mod.rs b/host/src/api/mod.rs
index 0dc3362b..c65e5cb0 100644
--- a/host/src/api/mod.rs
+++ b/host/src/api/mod.rs
@@ -58,8 +58,8 @@ pub async fn dispatch(hub: &Arc<Hub>, caller: &Caller, method: &str, b: Value) -
devices::permit(caller, method)?;
let observed = crate::analytics::observe_call(hub, caller, method, &b);
let result = route(hub, caller, method, b).await;
- if result.is_ok()
- && let Some((event, properties)) = observed
+ if let (Ok(answer), Some((event, properties))) = (&result, observed)
+ && let Some(properties) = crate::analytics::answered(event, properties, answer)
{
crate::analytics::capture(hub, event, properties);
}
diff --git a/host/src/api/remote.rs b/host/src/api/remote.rs
index 04f09c34..fcaaf5b5 100644
--- a/host/src/api/remote.rs
+++ b/host/src/api/remote.rs
@@ -90,7 +90,8 @@ pub(super) async fn call(hub: &Arc<Hub>, caller: &Caller, method: &str, b: Value
"accessRequests" => json!({"requests": hub.cloud.requests_json()}),
"decideAccessRequest" => {
let approve = b["approve"].as_bool().ok_or_else(|| anyhow!("`approve` is required"))?;
- crate::remote::cloud::decide(hub, str_arg(&b, "requestId")?, approve).await?;
+ let id = str_arg(&b, "requestId")?;
+ crate::remote::cloud::decide(hub, id, approve, crate::remote::cloud::Approval::Code).await?;
json!({})
}
"unclaim" => {
diff --git a/host/src/bin/codync-hostw.rs b/host/src/bin/codync-hostw.rs
index eb8e3136..aab8d1ff 100644
--- a/host/src/bin/codync-hostw.rs
+++ b/host/src/bin/codync-hostw.rs
@@ -41,7 +41,8 @@ fn main() {
}
loop {
let mut command = std::process::Command::new(&host);
- command.args(&args).creation_flags(CREATE_NO_WINDOW);
+ // Tells the host it runs as the service (`service::started_by_service`).
+ command.args(&args).env("CODYNC_SERVICE", "1").creation_flags(CREATE_NO_WINDOW);
let log = data.as_ref().and_then(|d| {
std::fs::create_dir_all(d).ok()?;
std::fs::OpenOptions::new().create(true).append(true).open(d.join("host.log")).ok()
diff --git a/host/src/main.rs b/host/src/main.rs
index ad4bd609..b58bd83a 100644
--- a/host/src/main.rs
+++ b/host/src/main.rs
@@ -294,6 +294,8 @@ fn open_store() -> Result<(store::Store, String, String)> {
} else {
let v = uuid::Uuid::new_v4().to_string();
store.kv_set("host_id", &v)?;
+ // A new install, whichever command made it: its first start is `host_started.first_run`.
+ store.kv_set(analytics::KV_STARTED, "")?;
v
};
let token = match store.kv_get("token") {
@@ -521,6 +523,7 @@ async fn serve(bind: &str, port: u16) -> Result<()> {
tokio::task::spawn_blocking(backends::hydrate_path).await?;
let hub = hub::Hub::new(store, host_id, identity, token, port);
hub.start()?;
+ analytics::host_started(&hub, service::started_by_service());
background::start(&hub);
tracing::info!(version = env!("CARGO_PKG_VERSION"), bind, port, "codync-host listening");
// Peer addresses: some settings may only be changed from this computer.
diff --git a/host/src/remote/channel.rs b/host/src/remote/channel.rs
index 72d629d4..49a2f021 100644
--- a/host/src/remote/channel.rs
+++ b/host/src/remote/channel.rs
@@ -319,6 +319,7 @@ impl Online {
if let Err(error) = hub.store.touch_device(&key) {
tracing::warn!(error = format!("{error:#}"), "couldn't record when a device was last seen");
}
+ crate::analytics::phone_connected(&hub, &key);
Self(hub, key)
}
}
@@ -599,6 +600,7 @@ impl Channel {
return (close::NORMAL, "");
}
tracing::info!(device = self.key, platform, "device paired");
+ crate::analytics::device_paired(&self.hub, crate::analytics::Via::Qr, platform, false);
let name = crate::service::host_name();
self.send(json!({"id": id, "ok": {"computerId": self.hub.identity.computer_id(), "name": name}})).await;
(close::PAIRED, "paired")
diff --git a/host/src/remote/cloud.rs b/host/src/remote/cloud.rs
index 050ae64b..32382452 100644
--- a/host/src/remote/cloud.rs
+++ b/host/src/remote/cloud.rs
@@ -335,7 +335,7 @@ pub async fn pull(hub: &Hub, base: &str) -> Result<()> {
let ready: Vec<String> =
hub.cloud.requests.locked().iter().filter(|r| r.code.is_some()).map(|r| r.id.clone()).collect();
for id in ready {
- if let Err(e) = decide(hub, &id, true).await {
+ if let Err(e) = decide(hub, &id, true, Approval::Auto).await {
tracing::warn!(error = format!("{e:#}"), request_id = id, "couldn't auto-approve an access request");
}
}
@@ -516,7 +516,8 @@ async fn deny(hub: &Hub, base: &str, id: &str) {
/// `decideAccessRequest`: approving adds the device the user saw (its key, the SAS they
/// compared) with the grant the cloud returns; nothing else can add an account device.
-pub async fn decide(hub: &Hub, id: &str, approve: bool) -> Result<()> {
+/// `how`: the user compared the code, or the computer approves on its own (`Approval::Auto`).
+pub async fn decide(hub: &Hub, id: &str, approve: bool, how: Approval) -> Result<()> {
let base = base(hub)?;
let r =
hub.cloud.requests.locked().iter().find(|r| r.id == id).cloned().ok_or_else(|| anyhow!("unknown request"))?;
@@ -534,7 +535,7 @@ pub async fn decide(hub: &Hub, id: &str, approve: bool) -> Result<()> {
.as_str()
.filter(|g| g.starts_with("grt_"))
.ok_or_else(|| anyhow!("the cloud gave no grant"))?;
- hub.store.put_device(&Device {
+ let device = Device {
key: b64(&r.device_key),
name: r.device_name.chars().take(100).collect(),
platform: r.platform,
@@ -544,8 +545,10 @@ pub async fn decide(hub: &Hub, id: &str, approve: bool) -> Result<()> {
lease_until: Some(now_ms() + LEASE_MS),
created_at: now_ms(),
last_seen_at: None,
- })?;
+ };
+ hub.store.put_device(&device)?;
tracing::info!(grant_id = grant, "account device approved");
+ crate::analytics::device_paired(hub, crate::analytics::Via::Account, &device.platform, how == Approval::Auto);
hub.auth_changed();
Ok(())
}
@@ -735,7 +738,7 @@ mod tests {
let nh =
|id: &str| nonces.iter().find(|(p, _)| p.contains(id)).unwrap().1["nonce"].as_str().unwrap().to_owned();
assert_eq!(hub.cloud.requests_json()[0]["code"], Value::Null, "no code before the reveal");
- let early = decide(&hub, "req_ok", true).await.unwrap_err();
+ let early = decide(&hub, "req_ok", true, Approval::Code).await.unwrap_err();
assert!(early.is::<Conflict>(), "approve before the reveal is refused");
assert_eq!(hub.cloud.status().owner.unwrap().user_id, "user_1");
@@ -752,7 +755,7 @@ mod tests {
let nh_ok: [u8; 32] = crypto::unb64_n(&nh("req_ok")).unwrap();
assert_eq!(list[0]["code"], crypto::sas_code(&hub.identity.sign_pub(), &dk, &nd, &nh_ok));
- decide(&hub, "req_ok", true).await.unwrap();
+ decide(&hub, "req_ok", true, Approval::Code).await.unwrap();
let d = hub.store.device(&b64(&dk)).unwrap();
assert_eq!((d.source, d.grant_id.as_deref()), (DeviceSource::Account, Some("grt_new")));
assert_eq!(hub.cloud.requests_json().len(), 0);
diff --git a/host/src/service/mod.rs b/host/src/service/mod.rs
index 6ac69a5e..cdeae10d 100644
--- a/host/src/service/mod.rs
+++ b/host/src/service/mod.rs
@@ -19,11 +19,11 @@ use std::time::{Duration, Instant};
#[cfg(unix)]
mod unix;
#[cfg(unix)]
-pub use unix::{install, installed, require_executable, start, stop, uninstall};
+pub use unix::{install, installed, require_executable, start, started_by_service, stop, uninstall};
#[cfg(windows)]
mod windows;
#[cfg(windows)]
-pub use windows::{install, installed, require_executable, start, stop, uninstall};
+pub use windows::{install, installed, require_executable, start, started_by_service, stop, uninstall};
static BINARY_IDENTITY: OnceLock<(String, String)> = OnceLock::new();
diff --git a/host/src/service/unix.rs b/host/src/service/unix.rs
index 88dfe1a2..96d945a8 100644
--- a/host/src/service/unix.rs
+++ b/host/src/service/unix.rs
@@ -30,6 +30,18 @@ pub fn start() -> Result<()> {
}
}
+/// Whether launchd or systemd started this process as the installed service, not a terminal or
+/// the desktop app's development run.
+pub fn started_by_service() -> bool {
+ if cfg!(target_os = "macos") {
+ // launchd names the job; a process started from a terminal or an app has another name.
+ std::env::var("XPC_SERVICE_NAME").is_ok_and(|name| name == LABEL)
+ } else {
+ // systemd (248+) names the service's main process; a shell inherits its terminal's.
+ std::env::var("SYSTEMD_EXEC_PID").is_ok_and(|pid| pid == std::process::id().to_string())
+ }
+}
+
/// Refuse to replace one installation while restarting a service owned by another.
pub fn require_executable(expected: &Path) -> Result<()> {
let configured = if cfg!(target_os = "macos") {
diff --git a/host/src/service/windows.rs b/host/src/service/windows.rs
index 0a56532f..7712383f 100644
--- a/host/src/service/windows.rs
+++ b/host/src/service/windows.rs
@@ -19,6 +19,11 @@ const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
/// dies with it, and the service must outlive the app that installed it).
const CREATE_BREAKAWAY_FROM_JOB: u32 = 0x0100_0000;
+/// Whether the service runner (`codync-hostw.exe`) started this process; it sets `CODYNC_SERVICE`.
+pub fn started_by_service() -> bool {
+ std::env::var_os("CODYNC_SERVICE").is_some()
+}
+
/// Stops the running service. Its configuration stays for a later start; a
/// manually started `codync-host serve` is left alone.
pub fn stop() -> Result<()> {
diff --git a/host/src/tui/app/analytics.rs b/host/src/tui/app/analytics.rs
index e30a128d..0856e5be 100644
--- a/host/src/tui/app/analytics.rs
+++ b/host/src/tui/app/analytics.rs
@@ -1,19 +1,78 @@
-//! Usage analytics: the ^k toggle and `app_opened`. Sharing is on unless turned off.
+//! Usage analytics: the ^k toggle, `app_opened` and `screen_viewed`. Sharing is on unless turned off.
//! The TUI only talks to the host over its loopback API, so it can always decide for this computer.
use serde_json::{Value, json};
-use super::{After, App};
+use super::{After, App, Overlay, TraceMode};
+use crate::analytics::reported::{App as Reporter, Reported, Screen, Track};
+
+/// What this run has reported: the launch, the screen on top, the conversation and thread in view.
+#[derive(Default)]
+pub(super) struct Seen {
+ opened: bool,
+ screen: Option<Screen>,
+ chat: Option<String>,
+ thread: Option<String>,
+}
impl App {
/// Every `hello`: keep the setting; the first one of this run also reports the launch.
pub(super) fn analytics_hello(&mut self, v: &Value) {
self.analytics = v["analytics"].as_bool();
- if self.opened {
+ if self.seen.opened {
+ return;
+ }
+ self.seen.opened = true;
+ self.track(Reported::AppOpened { at_login: None });
+ }
+
+ /// Before each draw: `screen_viewed` for a screen just opened, and for each conversation and
+ /// reply thread opened (hiding one lets its next opening count).
+ pub(in crate::tui) fn report_screen(&mut self) {
+ if !self.seen.opened {
return;
}
- self.opened = true;
- self.call("track", json!({"event": "app_opened"}), After::Tracked);
+ let screen = self.screen_on_top();
+ if screen != self.seen.screen {
+ self.seen.screen = screen;
+ if let Some(screen) = screen {
+ self.track(Reported::ScreenViewed { screen });
+ }
+ }
+ // The full trace covers the conversation like a pushed screen: coming back isn't an opening.
+ if self.trace == TraceMode::Full {
+ return;
+ }
+ let chat = self.selected.clone().filter(|_| self.chat_visible());
+ if chat.is_some() && chat != self.seen.chat {
+ self.track(Reported::ScreenViewed { screen: Screen::Chat });
+ }
+ let thread = self.thread.clone().filter(|_| chat.is_some());
+ if thread.is_some() && thread != self.seen.thread {
+ self.track(Reported::ScreenViewed { screen: Screen::Thread });
+ }
+ (self.seen.chat, self.seen.thread) = (chat, thread);
+ }
+
+ /// The screen the user is on, other than the conversation: the topmost overlay that is
+ /// one, else the full trace.
+ fn screen_on_top(&self) -> Option<Screen> {
+ let overlay = self.overlays.iter().rev().find_map(|o| match o {
+ Overlay::Usage => Some(Screen::Usage),
+ Overlay::Pair(_) => Some(Screen::Pairing),
+ Overlay::Memory(_) => Some(Screen::Memory),
+ Overlay::Routines(_) => Some(Screen::Routines),
+ Overlay::Market(_) => Some(Screen::Marketplace),
+ Overlay::Help(_) => Some(Screen::Help),
+ Overlay::Form(f) if f.bot_id.is_some() => Some(Screen::BotDetails),
+ Overlay::Group(g) if g.group_id.is_some() => Some(Screen::BotDetails),
+ _ => None,
+ });
+ overlay.or_else(|| (self.trace == TraceMode::Full).then_some(Screen::Trace))
+ }
+
+ fn track(&self, event: Reported) {
+ self.call("track", Track::body(Reporter::Tui, event), After::Tracked);
}
/// ^k → Share usage analytics: flips it.
@@ -32,3 +91,54 @@ impl App {
});
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::super::{Width, test_app};
+ use super::*;
+
+ #[tokio::test]
+ async fn screens_count_as_they_open_and_chats_as_the_bot_changes() {
+ let mut app = test_app();
+ app.overlays.push(Overlay::Usage);
+ app.report_screen();
+ assert_eq!(app.seen.screen, None, "nothing before the first hello");
+ app.seen.opened = true;
+ app.report_screen();
+ assert_eq!(app.seen.screen, Some(Screen::Usage));
+ app.overlays.push(Overlay::Analytics(crate::tui::manage::AnalyticsSheet::default()));
+ app.report_screen();
+ assert_eq!(app.seen.screen, Some(Screen::Usage), "a sheet over it isn't a screen");
+
+ app.overlays.clear();
+ app.trace = TraceMode::Full;
+ app.report_screen();
+ assert_eq!(app.seen.screen, Some(Screen::Trace));
+
+ app.trace = TraceMode::Off;
+ (app.width, app.selected) = (Width::Wide, Some("a".into()));
+ app.report_screen();
+ assert_eq!((app.seen.screen, app.seen.chat.as_deref()), (None, Some("a")));
+ app.selected = Some("b".into());
+ app.report_screen();
+ assert_eq!(app.seen.chat.as_deref(), Some("b"));
+
+ app.thread = Some("r".into());
+ app.report_screen();
+ assert_eq!((app.seen.chat.as_deref(), app.seen.thread.as_deref()), (Some("b"), Some("r")));
+ app.thread = None;
+ app.report_screen();
+ assert_eq!(app.seen.thread, None, "closing it lets the next opening count");
+
+ app.trace = TraceMode::Full;
+ app.report_screen();
+ assert_eq!(app.seen.chat.as_deref(), Some("b"), "the full trace only covers the conversation");
+ app.trace = TraceMode::Off;
+ (app.width, app.chat_page) = (Width::Narrow, false);
+ app.report_screen();
+ assert_eq!(app.seen.chat, None, "back to the list lets reopening the same bot count");
+ app.chat_page = true;
+ app.report_screen();
+ assert_eq!(app.seen.chat.as_deref(), Some("b"));
+ }
+}
diff --git a/host/src/tui/app/mod.rs b/host/src/tui/app/mod.rs
index 00b72c29..f9e02eae 100644
--- a/host/src/tui/app/mod.rs
+++ b/host/src/tui/app/mod.rs
@@ -114,8 +114,8 @@ pub struct App {
pub hint: Option<(String, Instant)>,
/// Whether this computer shares usage analytics (`None`: before the first `hello`).
pub analytics: Option<bool>,
- /// The first `hello` of this run was handled (`app_opened`).
- opened: bool,
+ /// What usage analytics has reported this run (`app_opened`, `screen_viewed`).
+ seen: analytics::Seen,
}
impl App {
@@ -174,7 +174,7 @@ impl App {
floors: HashMap::new(),
hint: None,
analytics: None,
- opened: false,
+ seen: analytics::Seen::default(),
}
}
diff --git a/host/src/tui/mod.rs b/host/src/tui/mod.rs
index bd69c1a3..791f0cb5 100644
--- a/host/src/tui/mod.rs
+++ b/host/src/tui/mod.rs
@@ -102,6 +102,7 @@ pub async fn run(url: String, token: Option<String>) -> Result<()> {
}
if dirty && !in_shell {
app.tick();
+ app.report_screen();
term.draw(|f| view::draw(f, &mut app))?;
dirty = false;
}
diff --git a/host/src/tui/view/analytics.rs b/host/src/tui/view/analytics.rs
index a2ee783b..96407914 100644
--- a/host/src/tui/view/analytics.rs
+++ b/host/src/tui/view/analytics.rs
@@ -15,7 +15,7 @@ use super::style::theme;
const DETAILS: [(&str, &str); 7] = [
(
"Features you use",
- "Opening the app, creating or deleting a bot, sending a message (how many attachments, never the files), running a routine or a voice call, installing a connector. Each comes with the app version, the platform, and the bot's agent and model.",
+ "Opening the app and its screens, setting up and pairing (and whether you allow notifications), creating or deleting a bot, sending a message (how many attachments, never the files), running a routine or a voice call, installing a connector. Each comes with the app version, the platform, and the bot's agent and model.",
),
(
"Crashes and errors",