Skip to content

armgit / muxin

Public Imported from GitHub
0

All your machines, one app. For you and your AI agents: agent sessions, desktops, files, logs and GitHub across your Macs, Linux and Windows machines, with an MCP server.

37.5 KB
Raw Blame
//! Agent sessions: terminals on fleet machines running an AI agent (Claude Code,
//! Codex, OpenCode, Pi, ...) or a plain shell.
//!
//! Sessions live in Muxin's own agent on each machine (`muxen-agent`,
//! the `agent/` crate), which Muxin installs when it connects. The agent
//! keeps them running when the window closes or the network drops, and anyone
//! can attach: the app's terminal, the CLI, or the user's own terminal. The
//! agent is the source of truth; the engine keeps the last discovery per
//! machine and refreshes it after changes and on a timer.

pub mod actions;
pub(crate) mod agent;
pub mod git;
pub mod handoff;
pub mod question;

use std::sync::Arc;
use std::time::Duration;

use chrono::{DateTime, TimeZone, Utc};
use serde::Serialize;
use serde_json::{Value, json};

use super::Engine;
use crate::config::MachineSpec;
use crate::ops::remote::{ps_quote, sh_quote, shell_for};
use crate::probe::{self, Shell};

/// Output this recent counts as "working" (agents animate while they think).
const BUSY_WINDOW_SECS: i64 = 6;
/// How often machines with live sessions are re-read.
pub const REFRESH_EVERY: Duration = Duration::from_secs(8);
/// Installed agent CLIs are looked up again after this long (it starts an
/// interactive shell on the machine, so not on every refresh).
const AGENTS_EVERY: chrono::Duration = chrono::Duration::minutes(10);

/// An agent CLI Muxin knows how to start.
pub struct AgentKind {
    pub id: &'static str,
    pub name: &'static str,
    /// The command to run; empty for a plain shell.
    pub command: &'static str,
    /// Accepts an initial prompt as its first argument.
    pub prompt_arg: bool,
}

pub const AGENTS: &[AgentKind] = &[
    AgentKind { id: "claude", name: "Claude Code", command: "claude", prompt_arg: true },
    AgentKind { id: "codex", name: "Codex", command: "codex", prompt_arg: true },
    AgentKind { id: "opencode", name: "OpenCode", command: "opencode", prompt_arg: false },
    AgentKind { id: "gemini", name: "Gemini CLI", command: "gemini", prompt_arg: false },
    AgentKind { id: "amp", name: "Amp", command: "amp", prompt_arg: false },
    AgentKind { id: "pi", name: "Pi", command: "pi", prompt_arg: true },
    AgentKind { id: "shell", name: "Shell", command: "", prompt_arg: false },
];

pub fn agent(id: &str) -> Option<&'static AgentKind> {
    AGENTS.iter().find(|a| a.id.eq_ignore_ascii_case(id))
}

/// An agent's command line with its first prompt, when its CLI takes one as
/// an argument; else the plain command and the prompt to type in once it's up.
pub fn launch_line(kind: &AgentKind, prompt: Option<&str>, windows: bool) -> (String, Option<String>) {
    let prompt = prompt.map(str::trim).filter(|p| !p.is_empty());
    match (kind.command, prompt) {
        ("", p) => (String::new(), p.map(str::to_string)),
        (c, Some(p)) if kind.prompt_arg => (format!("{c} {}", if windows { ps_quote(p) } else { sh_quote(p) }), None),
        (c, p) => (c.to_string(), p.map(str::to_string)),
    }
}

/// One session, as listed in the snapshot.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionInfo {
    /// `<machine-id>/<name>`.
    pub id: String,
    pub machine_id: String,
    /// The session's name on the machine, e.g. "claude-3f9a".
    pub name: String,
    /// Agent id ("claude", "codex", "shell", ...); empty when unknown.
    pub agent: String,
    pub agent_name: String,
    pub title: String,
    pub cwd: String,
    /// "running" or "exited".
    pub status: String,
    pub exit_code: Option<i32>,
    /// Printed output within the last few seconds of the last check: the agent is working.
    pub busy: bool,
    /// Unread notice ("waiting", "bell" or "exited") until the session is opened.
    pub attention: Option<String>,
    /// Terminals attached right now.
    pub clients: u32,
    pub created_at: Option<DateTime<Utc>>,
    pub last_output_at: Option<DateTime<Utc>>,
    /// Paste into your own terminal to attach. Empty when it can't be (not persistent).
    pub attach_command: String,
    /// Lives in the machine's agent, so it outlives the window. False for
    /// sessions on machines without an agent (Windows, for now), which run in
    /// the app's terminal and end with it.
    pub persistent: bool,
    /// What its work changed in its folder's git checkout (see git.rs).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub git: Option<git::GitStatus>,
    /// The box whose agent this is (see fleet::boxes).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub box_id: Option<String>,
}

/// What the last discovery found on one machine.
#[derive(Debug, Clone, Default)]
pub struct MachineSessions {
    #[cfg_attr(not(feature = "gui"), allow(dead_code))]
    pub checked_at: Option<DateTime<Utc>>,
    /// The agent's version, once it's set up there.
    pub agent_version: Option<String>,
    /// Ids of the agent CLIs found on PATH.
    pub agents: Vec<String>,
    pub agents_checked_at: Option<DateTime<Utc>>,
    /// The GitHub CLI there, looked up with the agent CLIs.
    pub gh: Option<crate::fleet::model::GhCli>,
    pub sessions: Vec<SessionInfo>,
    /// Its boxes (see fleet::boxes).
    pub boxes: Vec<crate::fleet::boxes::BoxInfo>,
    /// Recent bells and exits the agent saw, oldest first.
    pub events: Vec<RawEvent>,
    pub error: Option<String>,
}

/// A bell or an exit, as the agent reports it.
#[derive(Debug, Clone, PartialEq)]
pub struct RawEvent {
    pub at: i64,
    /// "bell" or "exited".
    pub kind: String,
    /// The session's name.
    pub session: String,
    /// Exit status for "exited".
    pub detail: String,
}

/// Something a session wants you to know: it rang the bell, went quiet after
/// working (finished, or waiting for an answer), or its agent exited.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionNotice {
    pub id: u64,
    pub session_id: String,
    pub machine_id: String,
    /// "waiting", "bell" or "exited".
    pub kind: String,
    pub title: String,
    pub message: String,
    pub at: DateTime<Utc>,
}

/// What `start_session` needs.
#[derive(Debug, Clone, Default)]
pub struct StartSession {
    pub machine_id: String,
    pub agent: String,
    /// Folder on the machine; "~" or empty for home.
    pub cwd: String,
    pub title: Option<String>,
    /// Initial prompt for the agent.
    pub prompt: Option<String>,
    pub cols: u16,
    pub rows: u16,
    /// Run straight over ssh in the app's terminal instead of in the agent
    /// (machines without one, Windows for now). Ends when the window closes.
    pub direct: bool,
    /// A command to run instead of the agent's own (direct sessions only).
    pub command: Option<String>,
    /// Text typed into the terminal once it's up, without pressing Enter: a
    /// command for the user to look at and run themselves.
    pub typed: Option<String>,
}

/// A session without the agent: what to run when its terminal opens.
#[derive(Debug, Clone)]
pub struct DirectSession {
    pub info: SessionInfo,
    run: String,
    windows: bool,
}

pub enum Control<'a> {
    Stop,
    Restart,
    Send { text: &'a str, enter: bool },
    Read { lines: u32 },
}

/// How to attach a terminal: a program and its arguments, run in a local PTY.
#[derive(Debug, Clone)]
pub struct AttachCommand {
    pub program: String,
    pub args: Vec<String>,
}

impl Engine {
    /// Sets up the machine's agent if needed, then re-reads its sessions (and,
    /// now and then, which agent CLIs are installed).
    pub async fn refresh_sessions(self: &Arc<Self>, machine_id: &str) -> Result<MachineSessions, String> {
        self.discover_sessions(machine_id, false).await
    }

    /// `refresh_sessions`, looking up the installed CLIs (and the GitHub CLI's
    /// login) now rather than when they're due: a sign-in there changes them.
    pub async fn refresh_tools(self: &Arc<Self>, machine_id: &str) -> Result<MachineSessions, String> {
        self.discover_sessions(machine_id, true).await
    }

    async fn discover_sessions(self: &Arc<Self>, machine_id: &str, tools: bool) -> Result<MachineSessions, String> {
        if let Some(world) = self.demo_world() {
            let found = self.sessions_of(machine_id).unwrap_or_else(|| world.sessions(machine_id));
            self.maybe_look_at_git(machine_id, Some(&found), &found);
            return Ok(found);
        }
        let (spec, probe) = self.machine(machine_id).ok_or_else(|| format!("No machine called {machine_id}."))?;
        if !spec.is_checkable() {
            return Err(format!("{} has no host to connect to.", spec.name));
        }
        spec.refuse_if_disconnected()?;
        let previous = self.sessions_of(&spec.id);
        let detect = tools || previous.as_ref().and_then(|p| p.agents_checked_at).is_none_or(|t| Utc::now() - t > AGENTS_EVERY);
        let agents: Vec<&str> = if detect { AGENTS.iter().map(|a| a.command).filter(|c| !c.is_empty()).collect() } else { Vec::new() };
        let result = match agent::ensure(&spec, probe.as_ref()).await {
            Ok(()) => agent::ctl(&spec, &json!({ "op": "discover", "agents": agents })).await,
            Err(e) => Err(e),
        };
        let found = match result {
            Ok(reply) => {
                let mut found = parse_discovery(&spec, &reply);
                // Agents before 0.1.1 keep sessions whose shell exited (or whose
                // agent quit cleanly); close those like the current one does.
                let done: Vec<String> = found.sessions.iter().filter(|s| closes_on_exit(s)).map(|s| s.name.clone()).collect();
                for name in &done {
                    let _ = agent::ctl(&spec, &json!({ "op": "stop", "name": name })).await;
                }
                found.sessions.retain(|s| !done.contains(&s.name));
                if found.agents_checked_at.is_none() {
                    // Not looked up this time: keep what we knew.
                    if let Some(p) = &previous {
                        found.agents = p.agents.clone();
                        found.agents_checked_at = p.agents_checked_at;
                        found.gh = p.gh.clone();
                    }
                }
                found
            }
            Err(e) => MachineSessions {
                checked_at: Some(Utc::now()),
                error: Some(e),
                // Keep what we knew; the machine may just be briefly unreachable.
                ..previous.clone().unwrap_or_default()
            },
        };
        self.set_sessions(&spec.id, found.clone());
        if found.error.is_none() {
            self.maybe_look_at_git(&spec.id, previous.as_ref(), &found);
        }
        // Working now: look again once it should have gone quiet, rather than
        // only trusting the agent to say so.
        if found.sessions.iter().any(|s| s.busy) {
            self.settle_sessions(&spec.id);
        }
        Ok(found)
    }

    /// One more look at a machine's sessions a moment after a busy one should
    /// have gone quiet (one pending look per machine).
    fn settle_sessions(self: &Arc<Self>, machine_id: &str) {
        static PENDING: std::sync::OnceLock<std::sync::Mutex<std::collections::HashSet<String>>> = std::sync::OnceLock::new();
        let pending = PENDING.get_or_init(Default::default);
        if !pending.lock().unwrap().insert(machine_id.to_string()) {
            return;
        }
        let (me, id) = (self.clone(), machine_id.to_string());
        tokio::spawn(async move {
            tokio::time::sleep(Duration::from_secs(BUSY_WINDOW_SECS as u64 + 1)).await;
            pending.lock().unwrap().remove(&id);
            let _ = me.refresh_sessions(&id).await;
        });
    }

    /// Starts an agent (or shell) in a new session and returns it.
    pub async fn start_session(self: &Arc<Self>, req: StartSession) -> Result<SessionInfo, String> {
        let kind = agent(&req.agent).ok_or_else(|| {
            format!("Unknown agent \"{}\". Use one of: {}.", req.agent, AGENTS.iter().map(|a| a.id).collect::<Vec<_>>().join(", "))
        })?;
        let (spec, probe) = self.machine(&req.machine_id).ok_or_else(|| format!("No machine called {}.", req.machine_id))?;
        let name = format!("{}-{}", kind.id, super::workspaces::random_id(4));
        let cwd = if req.cwd.trim().is_empty() { "~".to_string() } else { req.cwd.trim().to_string() };
        let title = req.title.clone().filter(|t| !t.trim().is_empty()).unwrap_or_else(|| default_title(kind, &cwd));
        // "Shell · home", "Shell · home 2", ... so sessions on a machine are told apart
        // (knowing which it has: the CLI starts without having asked).
        if self.sessions_of(&spec.id).is_none_or(|f| f.checked_at.is_none()) && self.demo_world().is_none() {
            let _ = self.refresh_sessions(&spec.id).await;
        }
        let taken: Vec<String> = self.sessions_of(&spec.id).map(|f| f.sessions.into_iter().map(|s| s.title).collect()).unwrap_or_default();
        let title = unique_title(&title, &taken);

        let windows = matches!(shell_for(&spec, probe.as_ref()), Shell::Powershell);
        if req.direct {
            return Ok(self.start_direct(&spec, kind, name, cwd, title, &req, windows));
        }
        if let Some(world) = self.demo_world() {
            let info = world.start_session(&spec, kind, &name, &cwd, &title);
            let mut found = self.sessions_of(&spec.id).unwrap_or_else(|| world.sessions(&spec.id));
            found.sessions.insert(0, info.clone());
            self.set_sessions(&spec.id, found);
            return Ok(info);
        }
        agent::ensure(&spec, probe.as_ref()).await?;

        // The agent's command line; the prompt rides along when the CLI takes one.
        let prompt = req.prompt.as_deref().map(str::trim).filter(|p| !p.is_empty());
        let run_line = match &req.command {
            Some(c) => c.clone(),
            None => launch_line(kind, prompt, windows).0,
        };
        let request = json!({
            "op": "start",
            "name": name,
            "agent": kind.id,
            "title": title,
            "cwd": cwd,
            "run": run_line,
            "cols": req.cols.clamp(40, 500),
            "rows": req.rows.clamp(10, 200),
        });
        agent::ctl(&spec, &request).await?;

        // A CLI without a prompt argument gets the prompt typed in once it's up.
        if let (Some(p), false) = (prompt, kind.prompt_arg || kind.command.is_empty()) {
            let me = self.clone();
            let id = format!("{}/{name}", spec.id);
            let p = p.to_string();
            tokio::spawn(async move {
                tokio::time::sleep(Duration::from_secs(3)).await;
                let _ = me.control_session(&id, Control::Send { text: &p, enter: true }).await;
            });
        }

        // Typed in for the user to run (Enter is theirs to press).
        if let Some(t) = req.typed.clone().filter(|t| !t.trim().is_empty()) {
            let me = self.clone();
            let id = format!("{}/{name}", spec.id);
            tokio::spawn(async move {
                tokio::time::sleep(Duration::from_millis(1500)).await;
                let _ = me.control_session(&id, Control::Send { text: &t, enter: false }).await;
            });
        }

        // A missing CLI or a broken login shell fails within moments.
        tokio::time::sleep(Duration::from_millis(700)).await;
        let found = self.refresh_sessions(&spec.id).await?;
        let session = found.sessions.into_iter().find(|s| s.name == name);
        match session {
            Some(s) if s.status == "running" => Ok(s),
            exited => {
                let id = format!("{}/{name}", spec.id);
                let output = self.control_session(&id, Control::Read { lines: 20 }).await.unwrap_or_default();
                let _ = self.control_session(&id, Control::Stop).await;
                let code = exited.and_then(|s| s.exit_code);
                let why = match code {
                    Some(127) => format!("{} isn't installed on {} (or isn't on its PATH).", kind.name, spec.name),
                    Some(c) => format!("{} exited right away with code {c} on {}.", kind.name, spec.name),
                    None => format!("{} exited right away on {}.", kind.name, spec.name),
                };
                let last = output.lines().rev().map(str::trim).find(|l| !l.is_empty() && !l.starts_with("[exited with code")).unwrap_or("");
                Err(if last.is_empty() { why } else { format!("{why} It said: {last}") })
            }
        }
    }

    /// Stops, restarts, types into or reads a session. `Read` returns the screen
    /// and scrollback text; the others return an empty string.
    /// What a waiting session is asking, read off its screen: a choice, or
    /// the end of what it said (see question.rs).
    pub async fn session_question(self: &Arc<Self>, id: &str) -> Result<question::Question, String> {
        let screen = self.control_session(id, Control::Read { lines: 60 }).await?;
        Ok(question::read(&screen))
    }

    /// Picks one of a waiting session's choices (`key`, as the question gave
    /// it; `selected`, the one its cursor was on; `confirm`, the menu wants
    /// Enter after a number), and marks it read.
    pub async fn answer_session(self: &Arc<Self>, id: &str, key: &str, selected: Option<&str>, confirm: bool) -> Result<(), String> {
        let (keys, enter) = question::keys_for(key, selected, confirm);
        self.control_session(id, Control::Send { text: &keys, enter }).await?;
        self.ack_session(id);
        Ok(())
    }

    pub async fn control_session(self: &Arc<Self>, id: &str, action: Control<'_>) -> Result<String, String> {
        if self.direct_session(id).is_some() {
            return match action {
                Control::Stop => {
                    self.remove_direct(id);
                    Ok(String::new())
                }
                Control::Restart => {
                    self.set_direct_status(id, "running");
                    Ok(String::new())
                }
                _ => Err(format!("{id} runs only in the Muxin window, so it can't be read or typed into from here.")),
            };
        }
        let (machine_id, name) = split_id(id)?;
        let (spec, probe) = self.machine(machine_id).ok_or_else(|| format!("No machine called {machine_id}."))?;
        if let Some(world) = self.demo_world() {
            let text = world.control_session(&spec.id, name, &action);
            if matches!(action, Control::Stop) {
                if let Some(mut found) = self.sessions_of(&spec.id) {
                    found.sessions.retain(|s| s.name != name);
                    self.set_sessions(&spec.id, found);
                }
            }
            return text;
        }
        agent::ensure(&spec, probe.as_ref()).await?;
        let request = match &action {
            Control::Stop => json!({ "op": "stop", "name": name }),
            Control::Restart => json!({ "op": "restart", "name": name }),
            Control::Send { text, enter } => json!({ "op": "send", "name": name, "text": text, "enter": enter }),
            Control::Read { lines } => json!({ "op": "read", "name": name, "lines": lines.clamp(&1, &50_000) }),
        };
        let reply = agent::ctl(&spec, &request).await?;
        if !matches!(action, Control::Read { .. }) {
            let me = self.clone();
            let machine = spec.id.clone();
            tokio::spawn(async move {
                // Give the agent a moment to react before re-reading.
                tokio::time::sleep(Duration::from_millis(400)).await;
                let _ = me.refresh_sessions(&machine).await;
            });
        }
        Ok(reply["text"].as_str().unwrap_or("").to_string())
    }

    /// Gives a session a new title (kept by the agent on its machine, so every
    /// Muxin sees it). An empty title goes back to the one it started with.
    pub async fn rename_session(self: &Arc<Self>, id: &str, title: &str) -> Result<SessionInfo, String> {
        let title = clean_title(title)?;
        if let Some(d) = self.direct_session(id) {
            let title = if title.is_empty() { agent(&d.info.agent).map(|k| default_title(k, &d.info.cwd)).unwrap_or_else(|| d.info.name.clone()) } else { title };
            return self.set_direct_title(id, &title).ok_or_else(|| format!("No session {id}."));
        }
        let (machine_id, name) = split_id(id)?;
        let (spec, probe) = self.machine(machine_id).ok_or_else(|| format!("No machine called {machine_id}."))?;
        if self.demo_world().is_some() {
            let mut found = self.sessions_of(&spec.id).ok_or_else(|| format!("No session {id}."))?;
            let s = found.sessions.iter_mut().find(|s| s.name == name).ok_or_else(|| format!("No session {id}."))?;
            s.title = if title.is_empty() { agent(&s.agent).map(|k| default_title(k, &s.cwd)).unwrap_or_else(|| s.name.clone()) } else { title };
            let renamed = s.clone();
            self.set_sessions(&spec.id, found);
            return Ok(renamed);
        }
        agent::ensure(&spec, probe.as_ref()).await?;
        agent::ctl(&spec, &json!({ "op": "rename", "name": name, "title": title })).await?;
        let found = self.refresh_sessions(&spec.id).await?;
        found.sessions.into_iter().find(|s| s.name == name).ok_or_else(|| format!("{id} ended."))
    }

    /// The command that attaches a terminal to a session from this computer.
    pub fn attach_command(&self, id: &str) -> Result<AttachCommand, String> {
        let (machine_id, name) = split_id(id)?;
        let (spec, _) = self.machine(machine_id).ok_or_else(|| format!("No machine called {machine_id}."))?;
        if let Some(d) = self.direct_session(id) {
            return Ok(direct_command(&spec, &d));
        }
        if spec.is_local() {
            let home = std::env::var("HOME").unwrap_or_default();
            let program = agent::REMOTE_PATH.replacen('~', &home, 1);
            return Ok(AttachCommand { program, args: vec!["attach".into(), name.into(), "--app".into()] });
        }
        // Same connection options as checks, but with a terminal.
        let mut args: Vec<String> = probe::ssh_args(&spec).into_iter().map(|a| if a == "-T" { "-tt".into() } else { a }).collect();
        args.push("--".into());
        args.push(if agent::is_windows(&spec) { agent::command(&spec, &format!("attach {name} --app")) } else { format!("{} attach {} --app", agent::REMOTE_PATH, sh_quote(name)) });
        Ok(AttachCommand { program: "ssh".into(), args })
    }

    fn start_direct(&self, spec: &MachineSpec, kind: &AgentKind, name: String, cwd: String, title: String, req: &StartSession, windows: bool) -> SessionInfo {
        let prompt = req.prompt.as_deref().map(str::trim).filter(|p| !p.is_empty());
        let run = match (&req.command, kind.command, prompt) {
            (Some(c), _, _) => c.clone(),
            (None, "", _) => String::new(),
            (None, c, Some(p)) if kind.prompt_arg => format!("{c} {}", if windows { ps_quote(p) } else { sh_quote(p) }),
            (None, c, _) => c.to_string(),
        };
        let info = SessionInfo {
            id: format!("{}/{name}", spec.id),
            machine_id: spec.id.clone(),
            agent: kind.id.to_string(),
            agent_name: kind.name.to_string(),
            title,
            cwd,
            status: "running".into(),
            exit_code: None,
            busy: false,
            attention: None,
            clients: 1,
            created_at: Some(Utc::now()),
            last_output_at: None,
            attach_command: String::new(),
            persistent: false,
            git: None,
            box_id: None,
            name,
        };
        self.add_direct(DirectSession { info: info.clone(), run, windows });
        info
    }

    /// Machines whose sessions should be re-read on the timer.
    /// (And with a box that isn't paused: it pauses on its machine, with no
    /// session left to say so.)
    pub(crate) fn machines_with_sessions(&self) -> Vec<String> {
        self.all_sessions().into_iter().filter(|(_, m)| !m.sessions.is_empty() || m.boxes.iter().any(|b| b.state != "paused")).map(|(id, _)| id).collect()
    }
}

/// Notices from a new discovery: events logged since `since`, and sessions that
/// went quiet after working. `before` is the previous discovery.
pub(crate) fn new_notices(before: &MachineSessions, after: &MachineSessions, since: i64, machine: &str) -> Vec<(String, String, String, String)> {
    let mut out = Vec::new();
    let find = |name: &str| after.sessions.iter().chain(before.sessions.iter()).find(|s| s.name == name);
    for e in after.events.iter().filter(|e| e.at > since) {
        let Some(s) = find(&e.session) else { continue };
        let who = if s.agent_name.is_empty() { "The session".to_string() } else { s.agent_name.clone() };
        let (title, kind) = match e.kind.as_str() {
            "bell" => (format!("{who} needs you"), "bell"),
            "exited" => match e.detail.as_str() {
                "" | "0" => (format!("{who} exited"), "exited"),
                code => (format!("{who} exited with code {code}"), "exited"),
            },
            _ => continue,
        };
        out.push((s.id.clone(), kind.to_string(), title, format!("{} · {machine}", s.title)));
    }
    // Working, then quiet: the agent finished or is waiting for an answer. Shells don't count.
    for s in &after.sessions {
        let was_busy = before.sessions.iter().any(|b| b.name == s.name && b.busy);
        if was_busy && !s.busy && s.status == "running" && !s.agent.is_empty() && s.agent != "shell" {
            out.push((s.id.clone(), "waiting".into(), format!("{} is waiting for you", s.agent_name), format!("{} · {machine}", s.title)));
        }
    }
    out
}

/// What a direct session's terminal runs: the agent in the user's login shell,
/// in its folder, over ssh (or locally).
fn direct_command(spec: &MachineSpec, d: &DirectSession) -> AttachCommand {
    let cwd = d.info.cwd.trim();
    if d.windows {
        let dir = match cwd {
            "" | "~" => "$HOME".to_string(),
            c => ps_quote(c),
        };
        let script = if d.run.is_empty() {
            format!("powershell -NoLogo -NoExit -Command \"Set-Location {dir}\"")
        } else {
            format!("powershell -NoLogo -Command \"Set-Location {dir}; {}\"", d.run.replace('"', "\\\""))
        };
        // This computer: PowerShell itself.
        if spec.is_local() {
            let mut args = vec!["-NoLogo".to_string()];
            if d.run.is_empty() {
                args.extend(["-NoExit".into(), "-Command".into(), format!("Set-Location {dir}")]);
            } else {
                args.extend(["-Command".into(), format!("Set-Location {dir}; {}", d.run)]);
            }
            return AttachCommand { program: "powershell".into(), args };
        }
        let mut args: Vec<String> = probe::ssh_args(spec).into_iter().map(|a| if a == "-T" { "-tt".into() } else { a }).collect();
        args.push("--".into());
        args.push(script);
        return AttachCommand { program: "ssh".into(), args };
    }
    let cd = match cwd {
        "" | "~" => "cd \"$HOME\"".to_string(),
        c if c.starts_with("~/") => format!("cd \"$HOME\"/{}", sh_quote(&c[2..])),
        c => format!("cd {}", sh_quote(c)),
    };
    let shell = "\"${SHELL:-/bin/sh}\"";
    let run = if d.run.is_empty() { format!("exec {shell} -l") } else { format!("exec {shell} -l -i -c {}", sh_quote(&d.run)) };
    let script = format!("{cd} || {{ echo \"No folder {cwd} on this machine.\"; exit 1; }}; {run}");
    if spec.is_local() {
        return AttachCommand { program: "/bin/sh".into(), args: vec!["-c".into(), script] };
    }
    let mut args: Vec<String> = probe::ssh_args(spec).into_iter().map(|a| if a == "-T" { "-tt".into() } else { a }).collect();
    args.push("--".into());
    args.push(format!("sh -c {}", sh_quote(&script)));
    AttachCommand { program: "ssh".into(), args }
}

/// An exited session that should just go away: a shell, or an agent that quit cleanly.
fn closes_on_exit(s: &SessionInfo) -> bool {
    s.status == "exited" && (s.agent == "shell" || s.exit_code == Some(0))
}

#[cfg(test)]
#[test]
fn titles_name_the_folder() {
    let shell = agent("shell").unwrap();
    for (cwd, title) in [("~", "Shell · home"), ("/home/adib", "Shell · home"), ("/Users/adib/", "Shell · home"), ("/root", "Shell · home"), ("~/code/api", "Shell · api"), ("/home/adib/openrunner", "Shell · openrunner")] {
        assert_eq!(default_title(shell, cwd), title, "{cwd}");
    }
}

/// `title`, or `title 2`, `title 3`, ... when a session already has it.
fn unique_title(title: &str, taken: &[String]) -> String {
    if !taken.iter().any(|t| t == title) {
        return title.to_string();
    }
    (2..).map(|n| format!("{title} {n}")).find(|t| !taken.contains(t)).unwrap_or_else(|| title.to_string())
}

/// A title as the user typed it, on one line. Empty is allowed (it means "the
/// one it started with").
fn clean_title(title: &str) -> Result<String, String> {
    let title = title.split_whitespace().collect::<Vec<_>>().join(" ");
    if title.chars().count() > 80 || title.chars().any(char::is_control) {
        return Err("That title is too long or has odd characters.".into());
    }
    Ok(title)
}

/// A short default title: the agent and the folder it works in.
fn default_title(kind: &AgentKind, cwd: &str) -> String {
    let path = cwd.trim_end_matches('/');
    // The home folder, however it's written: "~", /home/adib, /Users/adib, /root.
    let parts: Vec<&str> = path.split('/').collect();
    let home = path.is_empty() || path == "~" || path == "/root" || matches!(parts[..], ["", "home" | "Users", user] if !user.is_empty());
    let folder = if home { "home" } else { path.rsplit('/').next().filter(|f| !f.is_empty()).unwrap_or("home") };
    format!("{} · {folder}", kind.name)
}

fn split_id(id: &str) -> Result<(&str, &str), String> {
    id.split_once('/')
        .filter(|(m, n)| !m.is_empty() && !n.is_empty())
        .ok_or_else(|| format!("\"{id}\" isn't a session id; they look like <machine-id>/<name>, e.g. beelink/claude-3f9a."))
}

/// The paste-into-your-terminal attach command (detach with Ctrl-] then d).
fn user_attach_command(spec: &MachineSpec, name: &str) -> String {
    let attach = if agent::is_windows(spec) { agent::command(spec, &format!("attach {name}")) } else { format!("{} attach {name}", agent::REMOTE_PATH) };
    if spec.is_local() {
        return attach;
    }
    let mut ssh = String::from("ssh -t");
    if let Some(port) = spec.port {
        ssh.push_str(&format!(" -p {port}"));
    }
    let host = spec.host.trim();
    match spec.user.as_deref().filter(|u| !u.is_empty()) {
        Some(user) if !host.contains('@') => ssh.push_str(&format!(" {user}@{host}")),
        _ => ssh.push_str(&format!(" {host}")),
    }
    format!("{ssh} {attach}")
}

/// The agent's `discover` reply as what the engine keeps.
pub(crate) fn parse_discovery(spec: &MachineSpec, reply: &Value) -> MachineSessions {
    let now = reply["now"].as_i64().unwrap_or_else(|| Utc::now().timestamp());
    let ts = |v: &Value| v.as_i64().filter(|t| *t > 0).and_then(|t| Utc.timestamp_opt(t, 0).single());
    let mut found = MachineSessions {
        checked_at: Some(Utc::now()),
        agent_version: reply["version"].as_str().map(str::to_string),
        agents: reply["agents"]
            .as_array()
            .map(|a| a.iter().filter_map(|v| v.as_str()).filter_map(|c| AGENTS.iter().find(|k| k.command == c)).map(|k| k.id.to_string()).collect())
            .unwrap_or_default(),
        agents_checked_at: reply["agents_checked"].as_bool().unwrap_or(false).then(Utc::now),
        gh: reply["gh"].is_object().then(|| crate::fleet::model::GhCli {
            installed: reply["gh"]["installed"].as_bool().unwrap_or(false),
            logged_in: reply["gh"]["logged_in"].as_bool().unwrap_or(false),
            account: reply["gh"]["account"].as_str().map(str::to_string),
            path: reply["gh"]["path"].as_str().map(str::to_string),
        }),
        boxes: crate::fleet::boxes::parse(&spec.id, reply),
        ..Default::default()
    };
    for s in reply["sessions"].as_array().into_iter().flatten() {
        let name = s["name"].as_str().unwrap_or("").to_string();
        if name.is_empty() {
            continue;
        }
        let kind = s["agent"].as_str().and_then(agent).or_else(|| name.split('-').next().and_then(agent));
        let running = s["status"].as_str() == Some("running");
        let last_output = s["last_output"].as_i64();
        found.sessions.push(SessionInfo {
            id: format!("{}/{name}", spec.id),
            machine_id: spec.id.clone(),
            agent: kind.map(|k| k.id.to_string()).unwrap_or_default(),
            agent_name: kind.map(|k| k.name.to_string()).unwrap_or_default(),
            title: s["title"].as_str().filter(|t| !t.is_empty()).map(str::to_string).unwrap_or_else(|| name.clone()),
            cwd: s["cwd"].as_str().unwrap_or("").to_string(),
            status: if running { "running".into() } else { "exited".into() },
            exit_code: s["exit_code"].as_i64().map(|c| c as i32),
            // The same rule as the agent's (its "sessions" event comes when this turns false).
            busy: running && last_output.is_some_and(|a| now - a < BUSY_WINDOW_SECS),
            attention: None,
            clients: s["clients"].as_u64().unwrap_or(0) as u32,
            created_at: ts(&s["created"]),
            last_output_at: last_output.and_then(|t| Utc.timestamp_opt(t, 0).single()),
            attach_command: user_attach_command(spec, &name),
            persistent: true,
            git: None,
            box_id: crate::fleet::boxes::box_of_session(&name, &found.boxes).map(|b| b.id.clone()),
            name,
        });
    }
    for e in reply["events"].as_array().into_iter().flatten() {
        if let (Some(at), Some(kind), Some(session)) = (e["at"].as_i64(), e["kind"].as_str(), e["session"].as_str()) {
            found.events.push(RawEvent { at, kind: kind.into(), session: session.into(), detail: e["detail"].as_str().unwrap_or("").into() });
        }
    }
    // Newest first.
    found.sessions.sort_by_key(|s| std::cmp::Reverse(s.created_at));
    found
}

#[cfg(test)]
mod tests {
    use super::*;

    fn spec(host: &str) -> MachineSpec {
        let mut s: MachineSpec = toml::from_str(&format!("name = \"Beelink\"\nhost = \"{host}\"")).unwrap();
        s.id = "beelink".into();
        s
    }

    fn reply(now: i64, claude_output: i64, events: Value) -> Value {
        json!({
            "ok": true, "version": "0.1.0", "agents": ["claude", "codex"], "agents_checked": true, "now": now,
            "sessions": [
                { "name": "claude-ab12", "agent": "claude", "title": "Claude Code · app", "cwd": "/home/adib/app",
                  "created": 900, "status": "running", "exit_code": null, "last_output": claude_output, "clients": 1 },
                { "name": "shell-cd34", "agent": "shell", "title": "", "cwd": "/home/adib",
                  "created": 950, "status": "exited", "exit_code": 2, "last_output": 960, "clients": 0 }
            ],
            "events": events,
        })
    }

    #[test]
    fn parses_discovery() {
        let found = parse_discovery(&spec("beelink"), &reply(1000, 997, json!([])));
        assert_eq!(found.agent_version.as_deref(), Some("0.1.0"));
        assert_eq!(found.agents, vec!["claude", "codex"]);
        assert!(found.agents_checked_at.is_some());
        assert_eq!(found.sessions.len(), 2);
        let shell = &found.sessions[0];
        assert_eq!(shell.id, "beelink/shell-cd34");
        assert_eq!((shell.status.as_str(), shell.exit_code), ("exited", Some(2)));
        assert_eq!(shell.title, "shell-cd34");
        let claude = &found.sessions[1];
        assert_eq!(claude.agent_name, "Claude Code");
        assert!(claude.busy && claude.persistent);
        assert_eq!(claude.clients, 1);
        assert_eq!(claude.attach_command, "ssh -t beelink ~/.muxen/bin/muxen-agent attach claude-ab12");
    }

    #[test]
    fn notices_from_events_and_quiet_agents() {
        let before = parse_discovery(&spec("beelink"), &reply(1000, 998, json!([{ "at": 950, "kind": "bell", "session": "claude-ab12", "detail": "" }])));
        let after = parse_discovery(
            &spec("beelink"),
            &reply(1100, 1000, json!([
                { "at": 950, "kind": "bell", "session": "claude-ab12", "detail": "" },
                { "at": 1050, "kind": "exited", "session": "shell-cd34", "detail": "2" }
            ])),
        );
        let notices = new_notices(&before, &after, 950, "Beelink");
        let kinds: Vec<(&str, &str)> = notices.iter().map(|(id, kind, _, _)| (id.as_str(), kind.as_str())).collect();
        // The old bell doesn't repeat; the exit is new; Claude went quiet.
        assert_eq!(kinds, vec![("beelink/shell-cd34", "exited"), ("beelink/claude-ab12", "waiting")]);
        assert_eq!(notices[0].2, "Shell exited with code 2");
        assert_eq!(notices[1].2, "Claude Code is waiting for you");
        assert_eq!(notices[1].3, "Claude Code · app · Beelink");
    }

    #[test]
    fn titles_and_ids() {
        assert_eq!(default_title(agent("claude").unwrap(), "~/code/api/"), "Claude Code · api");
        assert_eq!(default_title(agent("shell").unwrap(), "~"), "Shell · home");
        assert!(split_id("beelink/claude-1").is_ok());
        assert!(split_id("claude-1").is_err());
        assert_eq!(user_attach_command(&spec("local"), "x"), "~/.muxen/bin/muxen-agent attach x");
        let taken = vec!["Shell · home".to_string(), "Shell · home 2".to_string()];
        assert_eq!(unique_title("Shell · home", &taken), "Shell · home 3");
        assert_eq!(unique_title("Shell · tmp", &taken), "Shell · tmp");
        assert_eq!(clean_title("  API\n server ").unwrap(), "API server");
        assert_eq!(clean_title("   ").unwrap(), "");
        assert!(clean_title(&"x".repeat(81)).is_err());
    }
}