Skip to content

A modern terminal with a built-in multiplexer: close it and your sessions keep running. Run shells and tons of AI agents across your machines, then pick them up from desktop, browser, TUI and more. Written in Rust with no UI framework: interface drawn straight on the GPU. No Electron, GPUI or webview.

36.7 KB
Raw Blame
//! GUI facade over the agent-status core.
//!
//! Detection itself lives in `mux::agent_status` and runs in whichever
//! process *owns* a pane; this module only presents the results (panel
//! snapshots, settings-page metadata) and hosts the pieces that are
//! genuinely GUI concerns (the feature toggle, the login-shell PATH
//! probe, display names).
//!
//! Deliberately NOT re-exported: `engine::*`, `DetectionInput`,
//! `contract::parse`, `identify::*`. Only `mux::agent_status::reload_rules`
//! crosses the boundary (the panel's reload button). That makes GUI-side
//! double detection structurally impossible — a pane's status has exactly
//! one producer, the mux that owns it. Do not widen this surface.

pub(crate) use thinkterm_proto::{
    AgentEvidence, AgentState, ProgramBlockedKind, ProgramReport, ProgramReportState,
};

use crate::termwindow::ui::icons::BrandIcon;
use crate::ui::icons::SvgIcon;
use crate::workspace_threads::WorkspaceThreadWorkStatus;
use ::window::Appearance;
use mux::pane::{Pane, PaneId};
use mux::Mux;
use std::collections::HashMap;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Mutex;
use std::time::{Duration, Instant};

mod worktree;

/// Clickable controls in the Agents panel; carried by
/// `UIItemType::RightSidebarAgent`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum AgentPanelAction {
    /// The toolbar line says detection is off; clicking it opens the
    /// settings page that owns that switch, so the panel explains itself
    /// instead of just sitting empty.
    OpenSettings,
    /// Focus the pane running this agent (it lives in this window).
    Reveal(PaneId),
    /// The pane lives in another window: clicking deep-focuses its tab
    /// and pane, then activates the backing thread (workspace switch,
    /// window brought forward) via the left sidebar's activation path.
    RevealElsewhere(PaneId),
    /// Open or fold the sub-task list of the agent in this pane. Folded
    /// is the default: one line that counts them.
    ToggleSubtasks(PaneId),
    /// The toolbar button that opens the view menu: what to show, how to
    /// group and order it, and which parts of a report to show.
    ViewOptions,
}

/// Snapshot of one agent pane for the Agents panel.
#[derive(Clone, Debug)]
pub(crate) struct AgentPaneStatus {
    pub pane_id: PaneId,
    /// Manifest/contract agent id, e.g. "claude".
    pub agent_id: String,
    pub state: AgentState,
    #[allow(dead_code)]
    pub evidence: AgentEvidence,
    /// Kept for the upcoming session-resume integration (spawn spec).
    #[allow(dead_code)]
    pub session_id: Option<String>,
    /// Pane title with any leading progress marker stripped.
    pub title: String,
    /// Mux window hosting the pane, resolved once per snapshot.
    pub window_id: Option<mux::window::WindowId>,
    /// Human place name ("Project · Thread"), falling back to the raw
    /// workspace string. Resolved once per snapshot: the paint loop must
    /// not walk the thread store per row per frame.
    pub place: String,
    /// The workspace the pane belongs to, as the thread store names it.
    pub workspace: String,
    /// The machine its thread runs on, as
    /// `workspace_threads::thread_place_and_machine_for_workspace` keys it;
    /// empty for this device. Resolved with `place`, once per snapshot.
    pub machine: String,
    /// The git worktree its directory is in, when that is on this device.
    /// Resolved with `place`, once per snapshot.
    pub worktree: Option<worktree::Worktree>,
    /// What the program said about itself with OSC 7501, when it did.
    pub report: Option<ProgramReport>,
    /// Unix seconds when `state` last changed, on the detecting host's
    /// clock (approximate across hosts).
    pub since_unix: u64,
}

/// One-line result of the last panel action, painted under the toolbar.
/// Expires on its own: the message is an acknowledgement, not a pinned
/// banner, and it is process-global (every window shows it).
static PANEL_STATUS: Mutex<Option<(String, Instant)>> = Mutex::new(None);
const PANEL_STATUS_TTL: Duration = Duration::from_secs(6);

pub(crate) fn panel_status() -> Option<String> {
    let guard = PANEL_STATUS.lock().ok()?;
    let (message, at) = guard.as_ref()?;
    (at.elapsed() < PANEL_STATUS_TTL).then(|| message.clone())
}

pub(crate) fn set_panel_status(message: String) {
    if let Ok(mut slot) = PANEL_STATUS.lock() {
        *slot = Some((message, Instant::now()));
    }
}

pub(crate) fn enabled() -> bool {
    // Both gates: without the Lua master switch the detector never runs,
    // and a permanently-empty panel would just look broken.
    crate::native_settings::agent_panel_enabled()
        && config::configuration().agent_status_detection
}

/// Per-pane work status for the sidebar thread scan. `None` when the pane
/// runs no known agent — callers fall back to the native title/progress
/// signals, so the flag-off path stays identical to pre-agent behavior.
pub(crate) fn agent_work_status(pane: &dyn Pane) -> Option<WorkspaceThreadWorkStatus> {
    let status = pane.agent_status()?;
    // Three cases where the agent status says nothing about the pane's
    // work, and pinning Idle would mask the native title/progress signals:
    // an ended session, an Unknown verdict, and the Fallback tier — the
    // latter means "recognized agent, but neither screen nor contract
    // spoke", and the pane's own OSC 9;4 / title spinner may know better.
    if status.ended
        || status.state == AgentState::Unknown
        || status.evidence == AgentEvidence::Fallback
    {
        return None;
    }
    Some(match status.state {
        AgentState::Working => WorkspaceThreadWorkStatus::Running,
        // A program stopped on an error wants a look as much as one that
        // asked a question; the sidebar tells the two apart by colour.
        AgentState::Blocked | AgentState::Error => WorkspaceThreadWorkStatus::NeedsAttention,
        AgentState::Idle | AgentState::Unknown => WorkspaceThreadWorkStatus::Idle,
    })
}

/// While an agent spins, the panel repaints at animation rate; walking
/// every window's every tab per frame is wasted work when nothing
/// changed. Status changes call [`invalidate_agent_pane_cache`], so the
/// TTL only bounds staleness of titles/workspaces.
static AGENT_PANES_CACHE: Mutex<Option<(Instant, std::sync::Arc<Vec<AgentPaneStatus>>)>> =
    Mutex::new(None);
const AGENT_PANES_TTL: Duration = Duration::from_millis(200);

/// Called from the AgentStatusChanged repaint path so a state change is
/// visible on the very next paint rather than a TTL later.
pub(crate) fn invalidate_agent_pane_cache() {
    if let Ok(mut slot) = AGENT_PANES_CACHE.lock() {
        *slot = None;
    }
}

/// Snapshot for the Agents panel: every pane in the mux with a known
/// agent status — locally detected or mirrored from a remote server —
/// minus sessions that reported their own end.
pub(crate) fn list_agent_panes() -> Vec<AgentPaneStatus> {
    agent_panes().as_ref().clone()
}

/// The snapshot behind [`list_agent_panes`], shared rather than copied:
/// for the callers that only look. A new one replaces it on every status
/// change and otherwise every [`AGENT_PANES_TTL`], so while it is the same
/// `Arc` nothing in it has changed.
pub(crate) fn agent_panes() -> std::sync::Arc<Vec<AgentPaneStatus>> {
    if let Ok(guard) = AGENT_PANES_CACHE.lock() {
        if let Some((at, cached)) = guard.as_ref() {
            if at.elapsed() < AGENT_PANES_TTL {
                return std::sync::Arc::clone(cached);
            }
        }
    }
    let mux = Mux::get();
    // One pass over the window/tab topology instead of a full
    // `resolve_pane_id` scan per agent pane.
    let mut workspace_by_pane: HashMap<PaneId, (mux::window::WindowId, String)> = HashMap::new();
    for window_id in mux.iter_windows() {
        let Some(window) = mux.get_window(window_id) else {
            continue;
        };
        let workspace = window.get_workspace().to_string();
        for tab in window.iter() {
            for pane in tab.iter_all_panes() {
                workspace_by_pane.insert(pane.pane_id(), (window_id, workspace.clone()));
            }
        }
    }
    let panes: Vec<AgentPaneStatus> = mux
        .iter_panes()
        .into_iter()
        .filter_map(|pane| {
            let status = pane.agent_status()?;
            if status.ended {
                return None;
            }
            let (window_id, workspace) = match workspace_by_pane.get(&pane.pane_id()) {
                Some((window_id, workspace)) => (Some(*window_id), workspace.clone()),
                None => (None, String::new()),
            };
            let thread = if workspace.is_empty() {
                None
            } else {
                crate::workspace_threads::thread_place_and_machine_for_workspace(&workspace)
            };
            // Only this device's own files can say which worktree it is in:
            // for a thread of this device, with no ssh or mosh in front, in
            // a shell that does not report another machine.
            let here = thread
                .as_ref()
                .is_some_and(|(_, machine)| machine.is_empty())
                && !pane.foreground_program().is_some_and(|program| {
                    mux::foreground_program::is_remote_session_client(&program)
                })
                && pane
                    .copy_user_vars()
                    .get("WEZTERM_HOST")
                    .is_none_or(|host| worktree::names_this_machine(host));
            let worktree = if here {
                pane.get_current_working_dir(mux::pane::CachePolicy::AllowStale)
                    .and_then(|url| worktree::worktree_of(&url))
            } else {
                None
            };
            let (place, machine) = match thread {
                Some(thread) => thread,
                None if workspace.is_empty() => (String::new(), String::new()),
                None => (workspace.clone(), String::new()),
            };
            let raw_title = pane.get_title();
            let title =
                crate::termwindow::ui::status_icon::split_leading_legacy_progress_marker(
                    &raw_title,
                )
                .unwrap_or(&raw_title)
                .to_string();
            Some(AgentPaneStatus {
                pane_id: pane.pane_id(),
                agent_id: status.agent_id,
                state: status.state,
                evidence: status.evidence,
                session_id: status.session_id,
                title,
                window_id,
                place,
                workspace,
                machine,
                worktree,
                report: status.report,
                since_unix: status.since_unix,
            })
        })
        .collect();
    let panes = std::sync::Arc::new(panes);
    if let Ok(mut slot) = AGENT_PANES_CACHE.lock() {
        *slot = Some((Instant::now(), std::sync::Arc::clone(&panes)));
    }
    panes
}

/// The agents running in one workspace -- one thread's panes -- that
/// `keep` accepts, in display order. Served from the panel snapshot, and
/// only those kept are copied.
pub(crate) fn agents_in_workspace(
    workspace: &str,
    keep: impl Fn(&AgentPaneStatus) -> bool,
) -> Vec<AgentPaneStatus> {
    let mut agents: Vec<AgentPaneStatus> = agent_panes()
        .iter()
        .filter(|agent| agent.workspace == workspace && keep(agent))
        .cloned()
        .collect();
    sort_for_display(&mut agents);
    agents
}

/// Whether some agent in a workspace satisfies `test`, copying nothing:
/// asked per sidebar row per frame.
pub(crate) fn any_agent_in_workspace(
    workspace: &str,
    test: impl Fn(&AgentPaneStatus) -> bool,
) -> bool {
    agent_panes()
        .iter()
        .any(|agent| agent.workspace == workspace && test(agent))
}

/// Whether a pane holds a finished or failed result its program reported
/// that nobody has seen yet.
pub(crate) fn has_unseen_result(pane: &dyn Pane) -> bool {
    pane.agent_status_summary()
        .is_some_and(|summary| summary.unseen_result)
}

/// The state a panel row, a tab or a card shows for an agent: its own
/// report's finer word where it gave one -- `done` is a result waiting to be
/// seen, not merely idle.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum ShownState {
    Working,
    Blocked,
    Error,
    Done,
    Idle,
    Unknown,
}

impl AgentPaneStatus {
    /// The state as the sidebars' status filter and the Agents panel's
    /// groups name it: waiting and failed both need the user.
    pub(crate) fn work_status(&self) -> crate::workspace_threads::WorkspaceThreadWorkStatus {
        use crate::workspace_threads::WorkspaceThreadWorkStatus as Status;
        match self.shown_state() {
            ShownState::Working => Status::Running,
            ShownState::Blocked | ShownState::Error => Status::NeedsAttention,
            ShownState::Done => Status::FinishedUnseen,
            ShownState::Idle | ShownState::Unknown => Status::Idle,
        }
    }

    pub(crate) fn shown_state(&self) -> ShownState {
        match self.state {
            AgentState::Working => ShownState::Working,
            AgentState::Blocked => ShownState::Blocked,
            AgentState::Error => ShownState::Error,
            AgentState::Unknown => ShownState::Unknown,
            AgentState::Idle => match self.report.as_ref().map(|report| report.state) {
                Some(ProgramReportState::Done) => ShownState::Done,
                _ => ShownState::Idle,
            },
        }
    }
}

/// One line on why a program is waiting, failed or what it finished --
/// the reason the bell, a card and a notification give -- shaped by the
/// user's choice of what to show. `None` when there is nothing to say.
pub(crate) fn reason_line(agent: &AgentPaneStatus) -> Option<String> {
    let (kind, msg) = report_said(agent, crate::native_settings::agent_status_display());
    let kind = kind.map(|kind| crate::i18n::tr(blocked_kind_key(kind)));
    match (kind, msg) {
        (Some(kind), Some(msg)) => Some(format!("{kind} · {msg}")),
        (Some(kind), None) => Some(kind),
        (None, Some(msg)) => Some(msg.to_string()),
        (None, None) => None,
    }
}

/// How far an agent's report says it has got, when the user chose to see it.
pub(crate) fn report_progress(
    agent: &AgentPaneStatus,
    show: crate::native_settings::NativeAgentStatusDisplay,
) -> Option<u8> {
    agent
        .report
        .as_ref()
        .and_then(|report| report.progress)
        .filter(|_| show.progress)
}

/// What an agent's report says, as far as the user chose to see it: why it
/// waits, and what it is doing.
pub(crate) fn report_said(
    agent: &AgentPaneStatus,
    show: crate::native_settings::NativeAgentStatusDisplay,
) -> (Option<ProgramBlockedKind>, Option<&str>) {
    let report = agent.report.as_ref();
    (
        report
            .and_then(|report| report.kind)
            .filter(|_| show.reason),
        report
            .and_then(|report| report.msg.as_deref())
            .filter(|_| show.description),
    )
}

/// Why a thread wants a look, in its most pressing program's own words --
/// an error before a wait before a finished result. For the bell's list and
/// the system notification; `None` when no program in it said anything.
pub(crate) fn thread_reason(thread_id: &str) -> Option<String> {
    workspace_reason(&crate::workspace_threads::thread_workspace_name(thread_id)?)
}

/// [`thread_reason`], for the thread a workspace backs.
pub(crate) fn workspace_reason(workspace: &str) -> Option<String> {
    /// Long enough for a command line, short enough for a menu.
    const MAX_CHARS: usize = 80;
    let rank = |agent: &AgentPaneStatus| match agent.shown_state() {
        ShownState::Error => 0,
        ShownState::Blocked => 1,
        ShownState::Done => 2,
        _ => 3,
    };
    // The most pressing agent that said something: one that did not --
    // waiting by the look of its screen alone -- must not silence another
    // that did.
    let mut agents = agents_in_workspace(workspace, |agent| rank(agent) < 3);
    agents.sort_by_key(|agent| rank(agent));
    let reason = agents.iter().find_map(reason_line)?;
    Some(if reason.chars().count() > MAX_CHARS {
        let mut cut: String = reason.chars().take(MAX_CHARS - 1).collect();
        cut.push('…');
        cut
    } else {
        reason
    })
}

pub(crate) fn blocked_kind_key(kind: ProgramBlockedKind) -> &'static str {
    match kind {
        ProgramBlockedKind::Permission => "agent-kind-permission",
        ProgramBlockedKind::Question => "agent-kind-question",
        ProgramBlockedKind::Auth => "agent-kind-auth",
    }
}

/// Display order for the Agents panel: stable, and independent of which
/// Space is frontmost. An earlier version floated the active workspace's
/// rows to the top, which meant every Space switch reshuffled the list —
/// and rows trading places read as state changes. Group by the visible
/// place name instead, then agent, then pane id as the final tiebreak.
pub(crate) fn sort_for_display(agents: &mut [AgentPaneStatus]) {
    agents.sort_by(display_order);
}

/// The comparison behind [`sort_for_display`].
pub(crate) fn display_order(a: &AgentPaneStatus, b: &AgentPaneStatus) -> std::cmp::Ordering {
    a.place
        .to_lowercase()
        .cmp(&b.place.to_lowercase())
        .then_with(|| a.agent_id.cmp(&b.agent_id))
        .then_with(|| a.pane_id.cmp(&b.pane_id))
}

pub(crate) fn display_name(agent_id: &str) -> String {
    match agent_id {
        "claude" => "Claude Code",
        "codebuddy" => "CodeBuddy Code",
        "codex" => "Codex",
        "copilot" => "Copilot CLI",
        "cursor" => "Cursor Agent",
        "pi" => "Pi",
        "opencode" => "OpenCode",
        "kimi" => "Kimi Code",
        "omp" => "OMP",
        "soul" => "Soul",
        // A custom manifest or contract id has no curated name; the raw
        // id (title-cased) beats an indistinguishable generic "Agent".
        other => {
            let mut chars = other.chars();
            return match chars.next() {
                Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
                None => "Agent".to_string(),
            };
        }
    }
    .to_string()
}

/// An agent's brand mark, in whichever form suits the current theme.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum AgentIcon {
    /// A monochrome mark, tinted by the caller — so it inverts with the
    /// theme like every other icon in the UI.
    Mono(SvgIcon),
    /// A mark with real brand colors, painted as-is.
    Color(BrandIcon),
}

/// The brand mark for an agent, or `None` when we have no logo for it.
///
/// `agent_id` is not a closed set — a native contract or a user manifest
/// can name any agent — so callers must have a fallback glyph rather than
/// assuming a mark exists. Soul is a known id with no upstream logo and
/// lands in the same fallback. OMP has none either; a fork of Pi, it
/// borrows Pi's.
///
/// Colored marks are only used where they read on both themes. Kimi's
/// colored mark is a white glyph with a blue dot: fine on dark chrome,
/// all but invisible on light, so it drops to its monochrome form there.
/// Cursor, OpenCode, Pi and OpenAI (Codex) publish no colored mark at all
/// — their logos are monochrome by design.
pub(crate) fn brand_icon(agent_id: &str, appearance: Appearance) -> Option<AgentIcon> {
    let dark = !matches!(
        appearance,
        Appearance::Light | Appearance::LightHighContrast
    );
    Some(match agent_id {
        "claude" => AgentIcon::Color(BrandIcon::AgentClaude),
        "copilot" => AgentIcon::Color(BrandIcon::AgentCopilot),
        "kimi" if dark => AgentIcon::Color(BrandIcon::AgentKimi),
        "kimi" => AgentIcon::Mono(SvgIcon::AgentKimi),
        "codebuddy" => AgentIcon::Mono(SvgIcon::AgentCodeBuddy),
        "codex" => AgentIcon::Mono(SvgIcon::AgentCodex),
        "cursor" => AgentIcon::Mono(SvgIcon::AgentCursor),
        "opencode" => AgentIcon::Mono(SvgIcon::AgentOpenCode),
        "pi" | "omp" => AgentIcon::Mono(SvgIcon::AgentPi),
        _ => return None,
    })
}

/// How each supported agent is covered, for the settings Integrations list.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum IntegrationKind {
    /// Covered by bundled screen-rule manifests; nothing to install.
    ScreenRules,
    /// Speaks the native `THINKTERM_AGENT` protocol itself.
    Native,
    /// Deeper integration planned; no screen rules yet.
    Pending,
}

/// The supported agents shown in Settings → Agents → Integrations, in
/// display order: (agent id, PATH probe names, coverage).
pub(crate) const SUPPORTED_AGENTS: &[(&str, &[&str], IntegrationKind)] = &[
    ("claude", &["claude"], IntegrationKind::ScreenRules),
    ("codex", &["codex"], IntegrationKind::ScreenRules),
    ("copilot", &["copilot"], IntegrationKind::ScreenRules),
    ("cursor", &["cursor-agent", "cursor"], IntegrationKind::ScreenRules),
    ("pi", &["pi"], IntegrationKind::ScreenRules),
    ("opencode", &["opencode"], IntegrationKind::ScreenRules),
    ("kimi", &["kimi"], IntegrationKind::ScreenRules),
    (
        "codebuddy",
        &["codebuddy", "codebuddy-code", "cbc"],
        IntegrationKind::ScreenRules,
    ),
    ("omp", &["omp"], IntegrationKind::ScreenRules),
    ("soul", &["soul"], IntegrationKind::Native),
];

static PATH_PROBE: Mutex<Option<HashMap<&'static str, bool>>> = Mutex::new(None);

/// Directories searched when probing for agent executables. A GUI process
/// launched from Finder/Dock inherits launchd's minimal PATH (no
/// /opt/homebrew/bin, no ~/.local/bin), so the login shell's PATH is
/// merged in once per process, plus a few well-known install locations
/// as insurance for shells that only extend PATH interactively.
fn probe_dirs() -> &'static Vec<std::path::PathBuf> {
    use std::sync::OnceLock;
    static DIRS: OnceLock<Vec<std::path::PathBuf>> = OnceLock::new();
    DIRS.get_or_init(|| {
        let mut dirs: Vec<std::path::PathBuf> = Vec::new();
        let push_all = |value: &std::ffi::OsStr, dirs: &mut Vec<std::path::PathBuf>| {
            for dir in std::env::split_paths(value) {
                if !dir.as_os_str().is_empty() && !dirs.contains(&dir) {
                    dirs.push(dir);
                }
            }
        };
        if let Some(path) = std::env::var_os("PATH") {
            push_all(&path, &mut dirs);
        }
        #[cfg(unix)]
        {
            // Not `$SHELL`: env-bootstrap unconditionally removes it at
            // startup (stale after `chsh`), so reading it here would run
            // `/bin/sh -l` forever and never see the PATH set up by the
            // user's real shell rc (mise/asdf/nvm installs). get_shell()
            // resolves from the password database instead.
            let shell = portable_pty::CommandBuilder::new_default_prog().get_shell();
            if let Some(path) = login_shell_path(&shell) {
                push_all(std::ffi::OsStr::new(path.trim()), &mut dirs);
            }
            for fallback in ["/opt/homebrew/bin", "/usr/local/bin"] {
                let dir = std::path::PathBuf::from(fallback);
                if !dirs.contains(&dir) {
                    dirs.push(dir);
                }
            }
            let local_bin = config::HOME_DIR.join(".local").join("bin");
            if !dirs.contains(&local_bin) {
                dirs.push(local_bin);
            }
        }
        #[cfg(windows)]
        {
            // Where npm and winget put their launchers; both add themselves
            // to the user's PATH in the registry, which a GUI started before
            // the install does not see until the next login.
            let mut fallbacks = Vec::new();
            if let Some(appdata) = std::env::var_os("APPDATA") {
                fallbacks.push(std::path::PathBuf::from(appdata).join("npm"));
            }
            if let Some(local) = std::env::var_os("LOCALAPPDATA") {
                fallbacks.push(
                    std::path::PathBuf::from(local)
                        .join("Microsoft")
                        .join("WinGet")
                        .join("Links"),
                );
            }
            fallbacks.push(config::HOME_DIR.join(".local").join("bin"));
            for dir in fallbacks {
                if !dirs.contains(&dir) {
                    dirs.push(dir);
                }
            }
        }
        dirs
    })
}

/// The file names an agent called `name` can have on this platform. On
/// Windows a command is one of `name` plus a PATHEXT extension: winget and
/// installers ship `.exe`, npm ships `.cmd` (and a `.ps1` for PowerShell),
/// so probing `name.exe` alone reports an npm-installed agent as missing.
fn candidate_file_names(name: &str) -> Vec<String> {
    if cfg!(windows) {
        let pathext = std::env::var("PATHEXT").unwrap_or_default();
        windows_candidate_file_names(name, &pathext)
    } else {
        vec![name.to_string()]
    }
}

fn windows_candidate_file_names(name: &str, pathext: &str) -> Vec<String> {
    let mut exts: Vec<String> = pathext
        .split(';')
        .map(|ext| ext.trim().to_ascii_lowercase())
        .filter(|ext| ext.starts_with('.'))
        .collect();
    // What the launchers actually produce, whether or not PATHEXT lists it.
    for must in [".exe", ".cmd", ".bat", ".com", ".ps1"] {
        if !exts.iter().any(|ext| ext == must) {
            exts.push(must.to_string());
        }
    }
    exts.into_iter().map(|ext| format!("{name}{ext}")).collect()
}

/// The login shell's `$PATH`, bounded in time. Shell profiles can block
/// forever on interactive steps (`read`, a gpg pinentry, a keychain
/// unlock); an unbounded wait here would wedge the probe worker with the
/// `PATH_PROBE_RUNNING` latch held and hang every later `probe_dirs`
/// caller on the OnceLock, so a hung shell is killed and the fallback
/// dirs stand in.
#[cfg(unix)]
fn login_shell_path(shell: &str) -> Option<String> {
    use std::process::Stdio;
    use std::time::{Duration, Instant};
    const BUDGET: Duration = Duration::from_secs(5);

    let mut child = std::process::Command::new(shell)
        .args(["-l", "-c", "printf %s \"$PATH\""])
        .stdin(Stdio::null())
        .stdout(Stdio::piped())
        .stderr(Stdio::null())
        .spawn()
        .ok()?;
    // Read on a helper thread: a profile can spawn a background process
    // that inherits the pipe's write end, in which case a post-exit read
    // would block even though the shell itself is done.
    let stdout = child.stdout.take();
    let (tx, rx) = std::sync::mpsc::channel();
    std::thread::spawn(move || {
        let mut buf = String::new();
        if let Some(mut stdout) = stdout {
            use std::io::Read;
            let _ = stdout.read_to_string(&mut buf);
        }
        let _ = tx.send(buf);
    });
    let deadline = Instant::now() + BUDGET;
    loop {
        match child.try_wait() {
            Ok(Some(status)) => {
                if !status.success() {
                    return None;
                }
                // Bounded even here, for the inherited-write-end case;
                // losing the answer beats blocking the probe worker.
                return rx.recv_timeout(Duration::from_millis(500)).ok();
            }
            Ok(None) => {
                if Instant::now() >= deadline {
                    log::warn!(
                        "login shell {shell} did not produce $PATH within {BUDGET:?} \
                         (interactive profile step?); using fallback probe dirs"
                    );
                    let _ = child.kill();
                    let _ = child.wait();
                    return None;
                }
                std::thread::sleep(Duration::from_millis(50));
            }
            Err(_) => return None,
        }
    }
}

/// A PATH hit must be an executable *file*: a stray non-executable file
/// with an agent's name must not report the agent as installed.
fn is_executable_file(path: &std::path::Path) -> bool {
    let Ok(metadata) = path.metadata() else {
        return false;
    };
    if !metadata.is_file() {
        return false;
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        metadata.permissions().mode() & 0o111 != 0
    }
    #[cfg(not(unix))]
    true
}

/// Whether this agent's executable is reachable on the probe path. A pure
/// cache read: painting must never run the login shell or stat files.
/// Answers `false` until `refresh_path_probe`'s worker has reported.
pub(crate) fn agent_on_path(agent_id: &str) -> bool {
    PATH_PROBE
        .lock()
        .ok()
        .and_then(|guard| guard.as_ref().and_then(|map| map.get(agent_id).copied()))
        .unwrap_or(false)
}

static PATH_PROBE_RUNNING: AtomicBool = AtomicBool::new(false);

/// Re-run the executable probe on a worker thread (the login-shell PATH
/// merge can take seconds under a heavy shell profile, and must never
/// block the UI thread). Repaints all windows when the result lands.
pub(crate) fn refresh_path_probe() {
    if PATH_PROBE_RUNNING.swap(true, Ordering::AcqRel) {
        return;
    }
    std::thread::spawn(|| {
        // The latch must clear even if the probe panics (a stuck `true`
        // would silently freeze the Integrations list for the process
        // lifetime), so it lives in a drop guard.
        struct ProbeLatch;
        impl Drop for ProbeLatch {
            fn drop(&mut self) {
                PATH_PROBE_RUNNING.store(false, Ordering::Release);
            }
        }
        let _latch = ProbeLatch;
        let dirs = probe_dirs();
        let mut map = HashMap::new();
        for (id, names, _) in SUPPORTED_AGENTS {
            let found = dirs.iter().any(|dir| {
                names.iter().any(|name| {
                    candidate_file_names(name)
                        .iter()
                        .any(|file| is_executable_file(&dir.join(file)))
                })
            });
            map.insert(*id, found);
        }
        if let Ok(mut guard) = PATH_PROBE.lock() {
            *guard = Some(map);
        }
        promise::spawn::spawn_into_main_thread(async {
            // The settings window is the surface that reads this result,
            // and it is not in the frontend's known-windows list — it
            // must be invalidated explicitly.
            crate::settings_window::invalidate_open_settings_window();
            if let Some(front_end) = crate::frontend::try_front_end() {
                front_end.invalidate_all_windows();
            }
        })
        .detach();
    });
}

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

    /// npm ships `claude.cmd`, winget ships `.exe`; both must count, and a
    /// PATHEXT that omits one of them must not hide it.
    #[test]
    fn windows_candidates_cover_every_launcher_kind() {
        let names = super::windows_candidate_file_names("claude", ".COM;.EXE;.BAT;.CMD");
        assert_eq!(
            names,
            vec!["claude.com", "claude.exe", "claude.bat", "claude.cmd", "claude.ps1"]
        );
        let names = super::windows_candidate_file_names("claude", "");
        assert!(names.contains(&"claude.cmd".to_string()));
        assert!(names.contains(&"claude.exe".to_string()));
        assert!(!names.contains(&"claude".to_string()));
    }

    fn row(place: &str, agent: &str, pane_id: mux::pane::PaneId) -> super::AgentPaneStatus {
        super::AgentPaneStatus {
            pane_id,
            agent_id: agent.to_string(),
            state: super::AgentState::Idle,
            evidence: super::AgentEvidence::Screen,
            session_id: None,
            title: String::new(),
            window_id: None,
            place: place.to_string(),
            workspace: String::new(),
            machine: String::new(),
            worktree: None,
            report: None,
            since_unix: 0,
        }
    }

    /// A program's own report decides what the row says: `done` is a result
    /// to look at, not idle, and the reason leads with what it waits for.
    #[test]
    fn a_report_names_the_state_and_the_reason() {
        use thinkterm_proto::ProgramReport;
        let mut agent = row("alpha", "claude", 1);
        assert_eq!(agent.shown_state(), super::ShownState::Idle);
        assert_eq!(super::reason_line(&agent), None);

        let report = |state, kind, msg: Option<&str>| ProgramReport {
            state,
            kind,
            progress: None,
            app: Some("claude-code".to_string()),
            title: None,
            msg: msg.map(str::to_string),
            children: Vec::new(),
        };
        agent.report = Some(report(super::ProgramReportState::Done, None, Some("Fixed it")));
        assert_eq!(agent.shown_state(), super::ShownState::Done);
        assert_eq!(super::reason_line(&agent).as_deref(), Some("Fixed it"));

        agent.state = super::AgentState::Blocked;
        agent.report = Some(report(
            super::ProgramReportState::Blocked,
            Some(super::ProgramBlockedKind::Permission),
            Some("Bash: npm test"),
        ));
        assert_eq!(agent.shown_state(), super::ShownState::Blocked);
        let reason = super::reason_line(&agent).unwrap();
        assert!(reason.ends_with(" · Bash: npm test"), "{}", reason);
    }

    /// The panel order must not depend on which Space is frontmost:
    /// switching Spaces used to float that workspace's rows to the top,
    /// and the reshuffle read as agents changing state.
    #[test]
    fn display_order_is_stable_and_space_independent() {
        let mut agents = vec![
            row("Beta", "pi", 9),
            row("alpha", "claude", 4),
            row("Beta", "claude", 7),
            row("alpha", "claude", 2),
        ];
        super::sort_for_display(&mut agents);
        let order: Vec<_> = agents.iter().map(|a| a.pane_id).collect();
        assert_eq!(order, vec![2, 4, 7, 9]);

        // Same input in any order lands the same way.
        let mut shuffled = vec![
            row("alpha", "claude", 2),
            row("Beta", "claude", 7),
            row("Beta", "pi", 9),
            row("alpha", "claude", 4),
        ];
        super::sort_for_display(&mut shuffled);
        let again: Vec<_> = shuffled.iter().map(|a| a.pane_id).collect();
        assert_eq!(again, order);
    }

    /// Every agent we ship a logo for must resolve in both themes, and
    /// everything else must decline so the caller draws its fallback
    /// instead of drawing the wrong brand.
    #[test]
    fn brand_icon_covers_the_logos_we_vendor() {
        use super::{brand_icon, AgentIcon, Appearance};
        for appearance in [Appearance::Dark, Appearance::Light] {
            for id in [
                "claude", "codebuddy", "codex", "copilot", "cursor", "kimi", "omp", "opencode",
                "pi",
            ] {
                assert!(
                    brand_icon(id, appearance).is_some(),
                    "{id} should have a brand mark in {appearance:?}"
                );
            }
            for id in ["soul", "some-custom-agent", ""] {
                assert!(
                    brand_icon(id, appearance).is_none(),
                    "{id} should fall back in {appearance:?}"
                );
            }
        }

        // Kimi's colored mark is a white glyph: usable on dark chrome,
        // invisible on light, so light must get the monochrome form.
        assert!(matches!(
            brand_icon("kimi", Appearance::Dark),
            Some(AgentIcon::Color(_))
        ));
        assert!(matches!(
            brand_icon("kimi", Appearance::Light),
            Some(AgentIcon::Mono(_))
        ));
        // Claude and Copilot read on both, so they stay in color.
        for appearance in [Appearance::Dark, Appearance::Light] {
            for id in ["claude", "copilot"] {
                assert!(
                    matches!(brand_icon(id, appearance), Some(AgentIcon::Color(_))),
                    "{id} should stay colored in {appearance:?}"
                );
            }
        }
    }

    /// Every agent the settings list calls supported must have a tab icon
    /// of its own, or a pane's tab would keep the generic bot while its
    /// agents row says which agent it is. Soul is native and has no mark;
    /// it keeps the catch-all.
    #[test]
    fn every_supported_agent_has_a_tab_icon_card() {
        let catalog =
            thinkterm_tab_icons::Catalog::build(&Default::default(), |key| key.to_string());
        for (id, _, _) in super::SUPPORTED_AGENTS {
            let card = catalog.card_for(Some(id), None);
            if *id == "soul" {
                assert_eq!(card.id, "agent", "soul should keep the catch-all");
            } else {
                assert_eq!(card.id, *id, "{id} has no tab icon card");
            }
        }
    }

    #[test]
    fn display_name_falls_back_to_the_raw_id() {
        assert_eq!(display_name("claude"), "Claude Code");
        assert_eq!(display_name("codebuddy"), "CodeBuddy Code");
        assert_eq!(display_name("myagent"), "Myagent");
        assert_eq!(display_name(""), "Agent");
    }
}