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.

169 KB
Raw Blame
//! The agent-facing API: one layer behind both the MCP server (`muxin mcp`)
//! and the scriptable CLI (`muxin status --json`, `muxin install`, ...).
//!
//! Responses are compact and explicit on purpose: stable ids, plain state
//! strings, a one-line `summary` where it helps, and operation logs capped to a
//! tail. Errors carry a `code` an agent can branch on and, when we know it, a
//! `hint` with the exact fix.

use std::collections::{BTreeMap, HashSet};
use std::path::{Component, Path};
use std::sync::Arc;
use std::time::Duration;

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

use crate::fleet::Engine;
use crate::fleet::model::{GhCli, Job, Machine, Operation, Runner, Snapshot, WorkspaceCommand, WorkspaceInfo};
use crate::fleet::workspaces::{CreateWorkspace, ExecOptions, SyncDirection};
use crate::ops::{InstallMode, InstallRequest, NewMachine, RunnerAction};
use crate::util;

/// GitHub data older than this is refreshed before answering.
const GITHUB_MAX_AGE_SECS: i64 = 30;
const DEFAULT_TAIL: usize = 80;
const LOGS_TAIL: usize = 200;
const INSTALL_TIMEOUT_SECS: u64 = 900;
const ACTION_TIMEOUT_SECS: u64 = 180;
const CHECK_WAIT: Duration = Duration::from_secs(60);

// ---------------------------------------------------------------------------
// Errors

#[derive(Debug, Clone, Serialize)]
pub struct ApiError {
    /// "not_found" | "invalid" | "busy" | "github" | "unreachable" | "operation_failed" | "internal"
    pub code: &'static str,
    pub message: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
    /// For "operation_failed": the operation and the state it left things in.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub details: Option<serde_json::Value>,
}

impl ApiError {
    fn new(code: &'static str, message: impl Into<String>) -> ApiError {
        ApiError { code, message: message.into(), hint: None, details: None }
    }

    pub fn not_found(message: impl Into<String>) -> ApiError {
        ApiError::new("not_found", message)
    }

    pub fn invalid(message: impl Into<String>) -> ApiError {
        ApiError::new("invalid", message)
    }

    fn with_hint(mut self, hint: impl Into<String>) -> ApiError {
        self.hint = Some(hint.into());
        self
    }

    /// Exit code for the CLI: 2 for bad input, 1 for everything else.
    pub fn exit_code(&self) -> u8 {
        match self.code {
            "not_found" | "invalid" => 2,
            _ => 1,
        }
    }
}

impl std::fmt::Display for ApiError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.message)?;
        if let Some(h) = &self.hint {
            write!(f, " (hint: {h})")?;
        }
        Ok(())
    }
}

/// Maps a message from the ops layer onto an error code.
fn op_error(message: String) -> ApiError {
    let lower = message.to_ascii_lowercase();
    let code = if lower.contains("another operation") || lower.contains("still running") {
        "busy"
    } else if lower.contains("isn't in config.toml") || lower.contains("isn't in muxen") {
        "not_found"
    } else {
        "invalid"
    };
    ApiError::new(code, message)
}

pub type ApiResult<T> = Result<T, ApiError>;

/// Who's asking, so hints name the right next step: an MCP tool or a CLI command.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Surface {
    Mcp,
    Cli,
}

impl Surface {
    fn say(self, mcp: impl Into<String>, cli: impl Into<String>) -> String {
        match self {
            Surface::Mcp => mcp.into(),
            Surface::Cli => cli.into(),
        }
    }
}

// ---------------------------------------------------------------------------
// Requests. Doc comments here double as the tool documentation.

fn yes() -> bool {
    true
}

#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct StatusRequest {
    /// Check every machine over SSH and sync GitHub before answering (slower, up to ~45s per unreachable machine).
    pub refresh: bool,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MachineRequest {
    /// Machine id, e.g. "mac-studio".
    pub machine_id: String,
}

#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct RunnersRequest {
    /// Only runners on this machine.
    pub machine_id: Option<String>,
    /// Only runners in this state: working, idle, offline or unknown.
    pub state: Option<String>,
}

#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct CheckRequest {
    /// Check only this machine; omit to check all of them.
    pub machine_id: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ConnectMachineRequest {
    pub machine_id: String,
    /// false disconnects. Default true.
    #[serde(default = "default_true")]
    pub connected: bool,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RenameMachineRequest {
    /// Machine id, e.g. "mac-studio". It stays the same after the rename.
    pub machine_id: String,
    /// The new display name.
    pub name: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AddMachineRequest {
    /// Display name, e.g. "Mac Studio". The id is derived from it.
    pub name: String,
    /// An ssh destination ("[email protected]", an ~/.ssh/config alias) or "local" for this computer.
    pub host: String,
    /// Check the machine right away and return what was found (default true).
    #[serde(default = "yes")]
    pub check: bool,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InstallRunnersRequest {
    pub machine_id: String,
    /// GitHub org ("acme") or repo ("acme/api") to register with. Optional when exactly one is watched.
    #[serde(default)]
    pub scope: Option<String>,
    /// Runner names. When empty, `count` names like "<machine-id>-01" are picked.
    #[serde(default)]
    pub names: Vec<String>,
    /// How many runners to install when `names` is empty (default 1).
    #[serde(default)]
    pub count: Option<usize>,
    /// Extra labels; GitHub adds self-hosted, the OS and the architecture itself.
    #[serde(default)]
    pub labels: Vec<String>,
    /// Org runner group (org scopes only).
    #[serde(default)]
    pub runner_group: Option<String>,
    /// Legacy: false is the same as mode "background". Prefer `mode`.
    #[serde(default = "yes")]
    pub as_service: bool,
    /// "auto" (default): a service when the machine allows it, else Docker when available, else background.
    /// "service": launchd / systemd / Windows service (Linux needs passwordless sudo).
    /// "background": run.sh, no root needed, not restarted after a reboot.
    /// "docker": one container per runner from GitHub's actions-runner image, restarted by Docker.
    #[serde(default)]
    pub mode: Option<String>,
    /// mode "docker": image to use (default ghcr.io/actions/actions-runner:<latest runner version>).
    #[serde(default)]
    pub image: Option<String>,
    /// mode "docker": give jobs the host's Docker socket (root-equivalent access to the machine).
    #[serde(default)]
    pub docker_socket: bool,
    /// Wait for the install to finish (default true).
    #[serde(default = "yes")]
    pub wait: bool,
    /// How long to wait, in seconds (default 900).
    #[serde(default)]
    pub timeout_secs: Option<u64>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ActionName {
    Start,
    Stop,
    Restart,
    Logs,
    Remove,
}

impl std::str::FromStr for ActionName {
    type Err = ApiError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_ascii_lowercase().as_str() {
            "start" => Ok(ActionName::Start),
            "stop" => Ok(ActionName::Stop),
            "restart" => Ok(ActionName::Restart),
            "logs" | "log" => Ok(ActionName::Logs),
            "remove" | "rm" | "delete" => Ok(ActionName::Remove),
            other => Err(ApiError::invalid(format!("Unknown action \"{other}\". Use start, stop, restart, logs or remove."))),
        }
    }
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CancelRunRequest {
    /// A queued or running job (`list_jobs`); its whole workflow run is cancelled.
    pub job_id: u64,
    /// Wait for GitHub to accept it (default true).
    #[serde(default = "yes")]
    pub wait: bool,
    #[serde(default)]
    pub timeout_secs: Option<u64>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RunnerActionRequest {
    /// Runner id: "<machine-id>/<runner-name>", or "github/<name>" for a runner no machine lists.
    pub runner_id: String,
    pub action: ActionName,
    /// With action=remove: also delete the runner's folder on the machine.
    #[serde(default)]
    pub delete_files: bool,
    /// Wait for the action to finish (default true).
    #[serde(default = "yes")]
    pub wait: bool,
    /// How long to wait, in seconds (default 180).
    #[serde(default)]
    pub timeout_secs: Option<u64>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OperationRequest {
    pub operation_id: u64,
    /// How many log lines to return from the end (default 80).
    #[serde(default)]
    pub tail: Option<usize>,
}

#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct GitHubScopesRequest {
    /// Orgs ("acme") or repos ("acme/api") to start watching. Each is checked against GitHub first.
    pub add: Vec<String>,
    /// Orgs or repos to stop watching.
    pub remove: Vec<String>,
}

#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct UpdateSettingsRequest {
    /// How often the window polls GitHub, in seconds (min 10).
    pub github_poll_seconds: Option<u32>,
    /// How many recently pushed repos per org to scan for queued/running jobs (0-50).
    pub scan_repos: Option<u32>,
    /// Automatic machine checks, in minutes (0 = only on request).
    pub check_interval_minutes: Option<u32>,
    /// GitHub REST API base (GitHub Enterprise Server: https://HOST/api/v3).
    pub api_url: Option<String>,
}

// ---------------------------------------------------------------------------
// Responses

#[derive(Debug, Serialize)]
pub struct StatusResponse {
    pub summary: String,
    pub counts: Counts,
    pub github: GitHubOut,
    pub last_check_at: Option<DateTime<Utc>>,
    /// Problems worth acting on, most severe first. Read these first.
    pub attention: Vec<AttentionOut>,
    pub machines: Vec<MachineSummary>,
    pub inventory: InventoryOut,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
    pub demo: bool,
}

#[derive(Debug, Serialize)]
pub struct Counts {
    pub machines: usize,
    pub runners: usize,
    pub working: usize,
    pub idle: usize,
    pub offline: usize,
    pub unknown: usize,
    pub queued_jobs: usize,
    pub running_jobs: usize,
}

#[derive(Debug, Serialize)]
pub struct GitHubOut {
    /// At least one org or repo is watched.
    pub configured: bool,
    /// Runner states come live from GitHub (otherwise from the last machine check).
    pub live: bool,
    /// Where the token came from: "gh", "GITHUB_TOKEN", ...; null when none was found.
    pub token: Option<String>,
    pub login: Option<String>,
    pub watching: Vec<ScopeOut>,
    /// Orgs/repos named in runner configs on the machines that aren't watched yet.
    pub detected: Vec<String>,
    pub last_sync_at: Option<DateTime<Utc>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct ScopeOut {
    /// "org" or "repo"
    pub kind: String,
    pub name: String,
    pub runners: usize,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct AttentionOut {
    /// "error" | "warning" | "info"
    pub level: String,
    pub title: String,
    pub detail: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub machine_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub runner_id: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct InventoryOut {
    pub path: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct MachineSummary {
    pub id: String,
    pub name: String,
    pub host: String,
    /// "online" | "offline" (unreachable) | "unchecked" | "manual" (no host) | "disconnected" (on purpose: connect_machine)
    pub status: String,
    pub checking: bool,
    /// e.g. "darwin-arm64", "linux-x64", "windows-x64"
    pub platform: String,
    /// e.g. "3/7 working", "2 idle", "no runners"
    pub runners: String,
    pub runner_counts: RunnerCounts,
    pub cpu_pct: Option<f64>,
    pub mem_pct: Option<f64>,
    pub disk_free: Option<String>,
    pub disk_free_bytes: Option<u64>,
    pub uptime: Option<String>,
    /// Warnings and errors (info items don't count).
    pub problems: usize,
    /// Worst diagnostic level: "error" | "warning" | "unknown" | "info" | null
    pub worst: Option<String>,
    pub checked_at: Option<DateTime<Utc>>,
    /// The last time a check reached it.
    pub last_seen_at: Option<DateTime<Utc>>,
    /// What the last check said, word for word, when it failed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// Why it can't be reached, in plain words: `kind` is "offline" (shut
    /// down, asleep, off the network: nothing to fix), "refused", "auth",
    /// "unknown-host", "host-key" or "error"; `hint` is a command to try.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub unreachable: Option<crate::fleet::model::Unreachable>,
    /// It on the user's Tailscale network: whether Tailscale sees it online,
    /// and whether traffic to it goes peer-to-peer or through a relay.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tailnet: Option<crate::fleet::model::TailnetDevice>,
    /// A cloud machine Muxin created: provider, droplet id, region, size,
    /// USD an hour, what it has cost so far and since when it's been idle.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cloud: Option<CloudOut>,
    /// The machine it runs on (a VM or container there) or is reached
    /// through (relation "through"), with the container it runs in.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub parent: Option<crate::fleet::model::ParentMachine>,
    /// A VM Muxin made with vm_create (vm_destroy deletes it): host, os,
    /// version (the system id), container, created_at.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub vm: Option<crate::config::VmRef>,
}

#[derive(Debug, Clone, Serialize)]
pub struct CloudOut {
    /// "digitalocean"
    pub provider: String,
    pub droplet_id: u64,
    pub region: String,
    pub size: String,
    /// USD an hour, billed while it exists (powered off too).
    pub price_hourly: f64,
    pub created_at: Option<DateTime<Utc>>,
    /// USD since it was created.
    pub cost_so_far: f64,
    /// USD this month (UTC).
    pub this_month: f64,
    /// The most it costs in a month, in USD.
    pub price_monthly: f64,
    pub idle_since: Option<DateTime<Utc>>,
    /// "on", "off" (still billed) or "starting", as last seen; null until known.
    pub power: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct RunnerCounts {
    pub total: usize,
    pub working: usize,
    pub idle: usize,
    pub offline: usize,
    pub unknown: usize,
}

#[derive(Debug, Serialize)]
pub struct MachineDetail {
    #[serde(flatten)]
    pub summary: MachineSummary,
    pub os_version: Option<String>,
    pub cores: Option<u32>,
    pub load: Vec<f64>,
    pub mem_used_bytes: Option<u64>,
    pub mem_total_bytes: Option<u64>,
    pub disk_total_bytes: Option<u64>,
    pub notes: Option<String>,
    pub runners: Vec<RunnerOut>,
    pub diagnostics: Vec<DiagnosticOut>,
}

#[derive(Debug, Clone, Serialize)]
pub struct DiagnosticOut {
    /// "error" | "warning" | "unknown" | "info"
    pub level: String,
    pub code: String,
    pub message: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub runner_id: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct RunnerOut {
    pub id: String,
    pub name: String,
    pub machine_id: Option<String>,
    /// "working" | "idle" | "offline" | "unknown"
    pub state: String,
    /// Where `state` came from: "github" (live), "probe" (last machine check) or "none".
    pub source: String,
    /// Listed in config.toml (vs discovered on the machine or on GitHub).
    pub declared: bool,
    pub labels: Vec<String>,
    pub version: Option<String>,
    pub dir: Option<String>,
    pub service: Option<String>,
    pub service_state: Option<String>,
    pub registered_to: Option<String>,
    pub github_status: Option<String>,
    pub job: Option<JobOut>,
}

#[derive(Debug, Clone, Serialize)]
pub struct JobOut {
    pub id: u64,
    pub name: String,
    pub workflow: String,
    pub repo: String,
    pub branch: Option<String>,
    /// "queued" | "in_progress" | "waiting"
    pub status: String,
    pub labels: Vec<String>,
    pub runner_id: Option<String>,
    pub url: String,
    pub created_at: DateTime<Utc>,
    pub started_at: Option<DateTime<Utc>>,
    /// Seconds queued (queued jobs) or running (running jobs).
    pub age_secs: i64,
    /// Queued jobs: how many online runners have every label the job asks for.
    pub matching_online: usize,
}

#[derive(Debug, Serialize)]
pub struct JobsResponse {
    pub summary: String,
    pub queued: Vec<JobOut>,
    pub running: Vec<JobOut>,
    pub scanned_repos: Vec<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct OperationOut {
    pub id: u64,
    /// "install" | "start" | "stop" | "restart" | "remove" | "logs"
    pub kind: String,
    pub title: String,
    /// "running" | "succeeded" | "failed"
    pub status: String,
    pub machine_id: Option<String>,
    pub runner_id: Option<String>,
    pub started_at: DateTime<Utc>,
    pub finished_at: Option<DateTime<Utc>>,
    pub error: Option<String>,
    /// The last lines of output. "▸ " lines are Muxin's steps, "✓ " successes,
    /// "error: "/"warning: " problems; anything else is output from the machine.
    pub log_tail: Vec<String>,
    pub log_lines: usize,
    pub truncated: bool,
}

#[derive(Debug, Serialize)]
pub struct ActionResponse {
    pub operation: OperationOut,
    /// False when `wait` was off or the timeout passed; poll get_operation.
    pub finished: bool,
    pub machine: Option<MachineSummary>,
    /// Runners the operation touched, as they are now (empty after a remove).
    pub runners: Vec<RunnerOut>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct AddMachineResponse {
    pub machine_id: String,
    pub machine: Option<MachineDetail>,
    pub next: String,
}

#[derive(Debug, Serialize)]
pub struct ScopeResult {
    pub scope: String,
    /// "added" | "removed" | "already_watching" | "not_watching" | "failed"
    pub result: String,
    pub runners: Option<usize>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct ScopesResponse {
    pub results: Vec<ScopeResult>,
    pub watching: Vec<ScopeOut>,
}

#[derive(Debug, Serialize)]
pub struct SettingsOut {
    pub github_orgs: Vec<String>,
    pub github_repos: Vec<String>,
    pub github_poll_seconds: u32,
    pub scan_repos: u32,
    pub check_interval_minutes: u32,
    pub api_url: String,
    pub config_dir: String,
    pub inventory: String,
}

#[derive(Debug, Serialize)]
pub struct SshHostsResponse {
    /// Host aliases from ~/.ssh/config, usable as `host` in add_machine.
    pub hosts: Vec<String>,
    /// Computers on the user's tailnet (when Tailscale is installed and on
    /// here), online ones first.
    pub tailnet: Vec<TailnetHost>,
    /// Computers on this local network that aren't in Muxin yet: ones
    /// advertising ssh (`ssh: true`, add by `host`), and Macs with Remote
    /// Login off (`ssh: false`: it needs turning on there first).
    pub network: Vec<crate::fleet::discover::NetworkHost>,
}

#[derive(Debug, Clone, Serialize)]
pub struct TailnetHost {
    /// The device's own name, e.g. "box-SER".
    pub name: String,
    /// What to pass as add_machine's `host`: the user's ~/.ssh/config alias
    /// for it when there is one, else its MagicDNS name (reachable from
    /// anywhere on the tailnet).
    pub host: String,
    pub dns_name: String,
    /// "linux", "macOS", "windows", ...
    pub os: String,
    /// Whether Tailscale sees it online.
    pub online: bool,
    /// Already in Muxin, as this machine.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub machine_id: Option<String>,
}

/// Made-up suggestions for the demo's Add machine dialog.
fn demo_ssh_hosts() -> SshHostsResponse {
    let tail = |name: &str, os: &str| TailnetHost { name: name.into(), host: format!("{name}.tail0000.ts.net"), dns_name: format!("{name}.tail0000.ts.net."), os: os.into(), online: true, machine_id: None };
    let net = |name: &str, ssh: bool, mac: bool| crate::fleet::discover::NetworkHost { name: name.into(), host: format!("{name}.local"), addresses: vec!["192.168.1.60".into()], ssh, mac };
    SshHostsResponse {
        hosts: vec!["build-box".into(), "gpu-rig".into(), "nas".into()],
        tailnet: vec![tail("studio", "macOS"), tail("render-01", "linux")],
        network: vec![net("living-room-mac", false, true), net("pi-garage", true, false)],
    }
}

// ---------------------------------------------------------------------------
// Conversions

pub fn machine_summary(m: &Machine) -> MachineSummary {
    let p = m.probe.as_ref().filter(|p| p.ok);
    let problems = m.diagnostics.iter().filter(|d| matches!(d.level.as_str(), "warning" | "error")).count();
    let worst = ["error", "warning", "unknown", "info"]
        .into_iter()
        .find(|l| m.diagnostics.iter().any(|d| d.level == *l))
        .map(str::to_string);
    let s = &m.summary;
    let runners = if s.total == 0 {
        "no runners".to_string()
    } else if s.working > 0 {
        format!("{}/{} working", s.working, s.total)
    } else if s.idle == s.total {
        format!("{} idle", s.idle)
    } else if s.offline > 0 {
        format!("{}/{} offline", s.offline, s.total)
    } else {
        format!("{} unknown", s.unknown)
    };
    MachineSummary {
        id: m.id.clone(),
        name: m.name.clone(),
        host: m.host.clone(),
        status: m.status.clone(),
        checking: m.checking,
        platform: m.platform.clone(),
        runners,
        runner_counts: RunnerCounts { total: s.total, working: s.working, idle: s.idle, offline: s.offline, unknown: s.unknown },
        cpu_pct: p.and_then(|p| p.cpu_pct).map(round1),
        mem_pct: p.and_then(|p| Some(round1(p.mem_used? as f64 * 100.0 / p.mem_total?.max(1) as f64))),
        disk_free: p.and_then(|p| p.disk_free).map(util::bytes),
        disk_free_bytes: p.and_then(|p| p.disk_free),
        uptime: p.and_then(|p| p.uptime_sec).map(util::uptime),
        problems,
        worst,
        checked_at: m.probe.as_ref().map(|p| p.checked_at),
        last_seen_at: m.probe.as_ref().and_then(|p| p.last_seen_at),
        error: m.probe.as_ref().filter(|p| !p.ok).and_then(|p| p.error.clone()),
        unreachable: m.unreachable.clone(),
        tailnet: m.tailnet.clone(),
        cloud: m.cloud.as_ref().map(|c| CloudOut {
            provider: c.provider.clone(),
            droplet_id: c.id,
            region: c.region.clone(),
            size: c.size.clone(),
            price_hourly: c.price_hourly,
            created_at: c.created_at,
            cost_so_far: c.cost_so_far,
            this_month: c.this_month,
            price_monthly: c.price_monthly,
            idle_since: c.idle_since,
            power: c.power.clone(),
        }),
        parent: m.parent.clone(),
        vm: m.vm.clone(),
    }
}

fn machine_detail(s: &Snapshot, m: &Machine) -> MachineDetail {
    let p = m.probe.as_ref().filter(|p| p.ok);
    MachineDetail {
        summary: machine_summary(m),
        // An offline machine keeps what the last check that reached it found.
        os_version: m.probe.as_ref().and_then(|p| p.os_version.clone()),
        cores: p.and_then(|p| p.cores),
        load: p.map(|p| p.load.clone()).unwrap_or_default(),
        mem_used_bytes: p.and_then(|p| p.mem_used),
        mem_total_bytes: p.and_then(|p| p.mem_total),
        disk_total_bytes: p.and_then(|p| p.disk_total),
        notes: m.notes.clone(),
        runners: m.runner_ids.iter().filter_map(|id| s.runners.iter().find(|r| &r.id == id)).map(|r| runner_out(s, r)).collect(),
        diagnostics: m
            .diagnostics
            .iter()
            .map(|d| DiagnosticOut {
                level: d.level.clone(),
                code: d.code.clone(),
                message: d.message.clone(),
                hint: d.hint.clone(),
                runner_id: d.runner_id.clone(),
            })
            .collect(),
    }
}

fn runner_out(s: &Snapshot, r: &Runner) -> RunnerOut {
    let job = r.job_id.and_then(|id| s.jobs.running.iter().find(|j| j.id == id)).map(job_out);
    RunnerOut {
        id: r.id.clone(),
        name: r.name.clone(),
        machine_id: r.machine_id.clone(),
        state: r.state.clone(),
        source: r.source.clone(),
        declared: r.declared,
        labels: r.labels.clone(),
        version: r.local.as_ref().and_then(|l| l.version.clone()),
        dir: r.local.as_ref().map(|l| l.dir.clone()),
        service: r.local.as_ref().and_then(|l| l.service.clone()),
        service_state: r.local.as_ref().and_then(|l| l.service_state.clone()),
        registered_to: r
            .github
            .as_ref()
            .map(|g| g.scope.clone())
            .or_else(|| r.local.as_ref().and_then(|l| l.url.as_deref()).and_then(crate::github::scope_from_runner_url)),
        github_status: r.github.as_ref().map(|g| if g.busy { "busy".to_string() } else { g.status.clone() }),
        job,
    }
}

fn job_out(j: &Job) -> JobOut {
    let since = if j.status == "in_progress" { j.started_at.unwrap_or(j.created_at) } else { j.created_at };
    JobOut {
        id: j.id,
        name: j.name.clone(),
        workflow: j.workflow.clone(),
        repo: j.repo.clone(),
        branch: j.branch.clone(),
        status: j.status.clone(),
        labels: j.labels.clone(),
        runner_id: j.runner_id.clone(),
        url: j.url.clone(),
        created_at: j.created_at,
        started_at: j.started_at,
        age_secs: (Utc::now() - since).num_seconds().max(0),
        matching_online: j.matching_online,
    }
}

pub fn operation_out(o: &Operation, tail: usize) -> OperationOut {
    let start = o.log.len().saturating_sub(tail);
    OperationOut {
        id: o.id,
        kind: o.kind.clone(),
        title: o.title.clone(),
        status: o.status.clone(),
        machine_id: o.machine_id.clone(),
        runner_id: o.runner_id.clone(),
        started_at: o.started_at,
        finished_at: o.finished_at,
        error: o.error.clone(),
        log_tail: o.log[start..].to_vec(),
        log_lines: o.log.len(),
        truncated: start > 0,
    }
}

fn round1(v: f64) -> f64 {
    (v * 10.0).round() / 10.0
}

pub(crate) fn find_machine<'a>(s: &'a Snapshot, id: &str) -> ApiResult<&'a Machine> {
    s.machines.iter().find(|m| m.id == id || m.name.eq_ignore_ascii_case(id)).ok_or_else(|| {
        let ids: Vec<&str> = s.machines.iter().map(|m| m.id.as_str()).collect();
        ApiError::not_found(format!("No machine \"{id}\".")).with_hint(if ids.is_empty() {
            "No machines yet; add one first.".to_string()
        } else {
            format!("Known machine ids: {}", ids.join(", "))
        })
    })
}

fn find_runner<'a>(s: &'a Snapshot, id: &str) -> ApiResult<&'a Runner> {
    // Accept a bare runner name too, as long as it's unambiguous.
    if let Some(r) = s.runners.iter().find(|r| r.id == id) {
        return Ok(r);
    }
    let by_name: Vec<&Runner> = s.runners.iter().filter(|r| r.name.eq_ignore_ascii_case(id)).collect();
    match by_name.as_slice() {
        [one] => Ok(one),
        _ => {
            let close: Vec<&str> = s
                .runners
                .iter()
                .filter(|r| r.id.contains(id) || id.contains(r.name.as_str()))
                .map(|r| r.id.as_str())
                .take(8)
                .collect();
            Err(ApiError::not_found(format!("No runner \"{id}\".")).with_hint(if close.is_empty() {
                "Runner ids look like \"<machine-id>/<runner-name>\"; list_runners shows them all.".to_string()
            } else {
                format!("Did you mean: {}", close.join(", "))
            }))
        }
    }
}

// ---------------------------------------------------------------------------
// Freshness

/// Picks up other processes' changes, and syncs GitHub when it's stale.
async fn freshen(engine: &Arc<Engine>) -> Arc<Snapshot> {
    engine.refresh_from_disk();
    let s = engine.current();
    let stale = s.github.last_sync_at.is_none_or(|t| (Utc::now() - t).num_seconds() > GITHUB_MAX_AGE_SECS);
    // Unwatched GitHub still needs the token looked up once, or status reports it missing.
    let token_unknown = !s.github.configured && s.github.token_source.is_empty();
    if ((s.github.configured || s.demo) && stale) || token_unknown {
        engine.sync_github().await;
    }
    engine.current()
}

/// Waits until a machine has a check result and isn't being checked.
async fn wait_checked(engine: &Arc<Engine>, machine_id: &str, timeout: Duration) {
    let mut rx = engine.subscribe();
    let done = |s: &Snapshot| s.machines.iter().find(|m| m.id == machine_id).is_none_or(|m| !m.checking && m.probe.is_some());
    let _ = tokio::time::timeout(timeout, async {
        loop {
            if done(&rx.borrow_and_update()) {
                return;
            }
            if rx.changed().await.is_err() {
                return;
            }
        }
    })
    .await;
}

/// Waits for an operation to leave "running", calling `on_line` for every new log line.
/// Returns the operation as it is when it finishes or the timeout passes, or None if it's unknown.
pub async fn wait_operation(engine: &Arc<Engine>, id: u64, timeout: Duration, mut on_line: impl FnMut(&str)) -> Option<Operation> {
    let mut rx = engine.subscribe();
    let mut printed = 0;
    let deadline = tokio::time::Instant::now() + timeout;
    loop {
        let op = rx.borrow_and_update().operations.iter().find(|o| o.id == id).cloned()?;
        for line in op.log.iter().skip(printed) {
            on_line(line);
        }
        printed = op.log.len();
        if op.status != "running" {
            return Some(op);
        }
        match tokio::time::timeout_at(deadline, rx.changed()).await {
            Ok(Ok(())) => continue,
            _ => return Some(op),
        }
    }
}

// ---------------------------------------------------------------------------
// Read

pub async fn status(engine: &Arc<Engine>, req: StatusRequest, surface: Surface) -> ApiResult<StatusResponse> {
    let s = if req.refresh {
        engine.refresh_from_disk();
        engine.run_check(None).await;
        engine.sync_github().await;
        engine.current()
    } else {
        freshen(engine).await
    };
    Ok(status_from(&s, surface))
}

pub fn status_from(s: &Snapshot, surface: Surface) -> StatusResponse {
    let c = &s.counts;
    let g = &s.github;
    let token = (!g.token_source.is_empty()).then(|| g.token_source.clone());

    let gh_hint = if token.is_none() && !s.demo {
        Some("No GitHub token: run `gh auth login`, or set GITHUB_TOKEN.".to_string())
    } else if !g.configured {
        Some(match g.detected.first() {
            Some(d) => surface.say(
                format!("Not watching GitHub yet. Runner configs mention \"{d}\": call github_scopes with add=[\"{d}\"]."),
                format!("Not watching GitHub yet. Runner configs mention \"{d}\": run `muxin watch {d}`."),
            ),
            None => surface.say(
                "Not watching GitHub yet: call github_scopes with add=[\"<org>\"] or [\"owner/repo\"].",
                "Not watching GitHub yet: run `muxin watch <org>` (or owner/repo).",
            ),
        })
    } else {
        g.scopes.iter().find_map(|sc| sc.hint.clone())
    };

    let attention = s
        .attention
        .iter()
        .map(|a| {
            let target = a.action.as_ref().and_then(|x| x.target.clone());
            let kind = a.action.as_ref().map(|x| x.kind.as_str()).unwrap_or("");
            AttentionOut {
                level: a.level.clone(),
                title: a.title.clone(),
                detail: a.detail.clone(),
                machine_id: (kind == "machine").then(|| target.clone()).flatten(),
                runner_id: (kind == "runner").then_some(target).flatten(),
            }
        })
        .collect::<Vec<_>>();

    let never_checked = s.check.finished_at.is_none() && s.machines.iter().all(|m| m.probe.is_none());
    let summary = format!(
        "{} machine{}, {} runner{}: {} working, {} idle, {} offline{}. {} queued job{}, {} running.{}",
        c.machines,
        plural(c.machines),
        c.runners,
        plural(c.runners),
        c.working,
        c.idle,
        c.offline,
        if c.unknown > 0 { format!(", {} unknown", c.unknown) } else { String::new() },
        c.queued,
        plural(c.queued),
        c.running,
        match attention.len() {
            0 => " Nothing needs attention.".to_string(),
            n => format!(" {n} item{} need{} attention.", plural(n), if n == 1 { "s" } else { "" }),
        }
    );

    StatusResponse {
        summary,
        counts: Counts {
            machines: c.machines,
            runners: c.runners,
            working: c.working,
            idle: c.idle,
            offline: c.offline,
            unknown: c.unknown,
            queued_jobs: c.queued,
            running_jobs: c.running,
        },
        github: GitHubOut {
            configured: g.configured,
            live: g.live,
            token,
            login: g.login.clone(),
            watching: g.scopes.iter().map(|sc| ScopeOut { kind: sc.kind.clone(), name: sc.name.clone(), runners: sc.runners, error: sc.error.clone(), hint: sc.hint.clone() }).collect(),
            detected: g.detected.clone(),
            last_sync_at: g.last_sync_at,
            error: g.error.clone(),
            hint: gh_hint,
        },
        last_check_at: s.check.finished_at,
        attention,
        machines: s.machines.iter().map(machine_summary).collect(),
        inventory: InventoryOut { path: s.inventory.path.clone(), error: s.inventory.error.clone() },
        hint: never_checked.then(|| {
            surface.say(
                "No machine has been checked yet; call check_machines (or status with refresh=true).",
                "No machine has been checked yet; run `muxin status --refresh` (or `muxin check`).",
            )
        }),
        demo: s.demo,
    }
}

fn plural(n: usize) -> &'static str {
    if n == 1 { "" } else { "s" }
}

pub async fn machine(engine: &Arc<Engine>, req: MachineRequest) -> ApiResult<MachineDetail> {
    let s = freshen(engine).await;
    let m = find_machine(&s, &req.machine_id)?;
    Ok(machine_detail(&s, m))
}

pub async fn machines(engine: &Arc<Engine>) -> ApiResult<Vec<MachineSummary>> {
    let s = freshen(engine).await;
    Ok(s.machines.iter().map(machine_summary).collect())
}

pub async fn runners(engine: &Arc<Engine>, req: RunnersRequest) -> ApiResult<Vec<RunnerOut>> {
    let s = freshen(engine).await;
    if let Some(m) = &req.machine_id {
        find_machine(&s, m)?;
    }
    if let Some(st) = &req.state {
        if !matches!(st.as_str(), "working" | "idle" | "offline" | "unknown") {
            return Err(ApiError::invalid(format!("Unknown state \"{st}\". Use working, idle, offline or unknown.")));
        }
    }
    let machine_id = req.machine_id.as_ref().and_then(|m| find_machine(&s, m).ok()).map(|m| m.id.clone());
    Ok(s.runners
        .iter()
        .filter(|r| machine_id.as_ref().is_none_or(|m| r.machine_id.as_ref() == Some(m)))
        .filter(|r| req.state.as_ref().is_none_or(|st| &r.state == st))
        .map(|r| runner_out(&s, r))
        .collect())
}

pub async fn jobs(engine: &Arc<Engine>, surface: Surface) -> ApiResult<JobsResponse> {
    let s = freshen(engine).await;
    let stuck = s.jobs.queued.iter().filter(|j| j.matching_online == 0).count();
    Ok(JobsResponse {
        summary: format!(
            "{} queued{}, {} running, across {} scanned repo{}.",
            s.jobs.queued.len(),
            if stuck > 0 { format!(" ({stuck} with no online runner that matches)") } else { String::new() },
            s.jobs.running.len(),
            s.github.scanned_repos.len(),
            plural(s.github.scanned_repos.len())
        ),
        queued: s.jobs.queued.iter().map(job_out).collect(),
        running: s.jobs.running.iter().map(job_out).collect(),
        scanned_repos: s.github.scanned_repos.clone(),
        hint: (!s.github.configured && !s.demo).then(|| {
            surface.say(
                "Jobs come from GitHub: call github_scopes with add=[\"<org>\"] first.",
                "Jobs come from GitHub: run `muxin watch <org>` first.",
            )
        }),
    })
}

pub fn operations(engine: &Arc<Engine>) -> Vec<OperationOut> {
    engine.current().operations.iter().map(|o| operation_out(o, 0)).collect()
}

pub fn operation(engine: &Arc<Engine>, req: OperationRequest) -> ApiResult<OperationOut> {
    let s = engine.current();
    let o = s.operations.iter().find(|o| o.id == req.operation_id).ok_or_else(|| {
        ApiError::not_found(format!("No operation {} in this Muxin process.", req.operation_id))
            .with_hint("Operation ids are per process; list_operations shows the ones this server started.")
    })?;
    Ok(operation_out(o, req.tail.unwrap_or(DEFAULT_TAIL)))
}

pub fn settings(engine: &Arc<Engine>) -> SettingsOut {
    engine.refresh_from_disk();
    let s = engine.settings();
    let p = engine.paths();
    SettingsOut {
        github_orgs: s.github.orgs,
        github_repos: s.github.repos,
        github_poll_seconds: s.github_poll_seconds,
        scan_repos: s.github.scan_repos,
        check_interval_minutes: s.check_interval_minutes,
        api_url: s.github.api_url,
        config_dir: crate::config::display_path(&p.dir),
        inventory: engine.current().inventory.path.clone(),
    }
}

pub async fn ssh_hosts(engine: &Arc<Engine>) -> SshHostsResponse {
    // The demo makes its own up: nothing of this computer's shows in it.
    if engine.demo_world().is_some() {
        return demo_ssh_hosts();
    }
    let hosts = crate::ops::ssh_hosts();
    // Listening on the local network takes a moment; do it meanwhile.
    let listening = tokio::task::spawn_blocking(|| crate::fleet::discover::browse(Duration::from_millis(2500)));
    let mut tailnet = Vec::new();
    if let Some(t) = crate::fleet::tailscale::status().await.filter(|t| t.running()) {
        // Where each alias really goes, to list a device under the user's own
        // name for it.
        let resolved: Vec<(String, Option<String>)> = futures::future::join_all(hosts.iter().map(|h| async move { (h.clone(), ssh_hostname(h).await) })).await;
        let snap = engine.current();
        for p in t.peers.iter().filter(|p| p.is_computer()) {
            let alias = resolved
                .iter()
                .find(|(a, to)| {
                    let names: Vec<String> = std::iter::once(a.clone()).chain(to.clone()).collect();
                    t.find(&[], &names).is_some_and(|f| f.dns_name == p.dns_name)
                })
                .map(|(a, _)| a.clone());
            let host = alias.unwrap_or_else(|| p.dns_name.clone());
            let machine_id = snap
                .machines
                .iter()
                .find(|m| m.tailnet.as_ref().is_some_and(|d| d.dns_name == p.dns_name) || m.host.eq_ignore_ascii_case(&host))
                .map(|m| m.id.clone());
            tailnet.push(TailnetHost { name: p.host_name.clone(), host, dns_name: p.dns_name.clone(), os: p.os.clone(), online: p.online, machine_id });
        }
        tailnet.sort_by(|a, b| b.online.cmp(&a.online).then(a.name.to_ascii_lowercase().cmp(&b.name.to_ascii_lowercase())));
    }
    // What's on this network, minus this computer, the fleet, and the tailnet's list.
    let me = crate::config::local_hostname().to_ascii_lowercase();
    // This computer by its address too: its Bonjour name can differ from its hostname.
    let my_ip = std::net::UdpSocket::bind("0.0.0.0:0").and_then(|s| s.connect("1.1.1.1:53").and_then(|_| s.local_addr())).map(|a| a.ip().to_string()).ok();
    let snap = engine.current();
    let short = |s: &str| s.trim_end_matches('.').trim_end_matches(".local").to_ascii_lowercase();
    let network = listening
        .await
        .unwrap_or_default()
        .into_iter()
        .filter(|n| short(&n.host) != me && short(&n.name) != me && !my_ip.as_ref().is_some_and(|ip| n.addresses.contains(ip)))
        .filter(|n| {
            !snap.machines.iter().any(|m| {
                short(&m.host) == short(&n.host) || m.probe.as_ref().and_then(|p| p.hostname.as_deref()).is_some_and(|h| short(h) == short(&n.host) || short(h) == short(&n.name))
            })
        })
        .filter(|n| !tailnet.iter().any(|t| t.name.eq_ignore_ascii_case(&n.name) || short(&t.dns_name).split('.').next() == Some(short(&n.host).as_str())))
        .collect();
    SshHostsResponse { hosts, tailnet, network }
}

/// The host an ssh alias really connects to (its config's HostName).
async fn ssh_hostname(alias: &str) -> Option<String> {
    let out = tokio::time::timeout(Duration::from_secs(3), tokio::process::Command::new("ssh").args(["-G", alias]).output()).await.ok()?.ok()?;
    String::from_utf8_lossy(&out.stdout).lines().find_map(|l| l.strip_prefix("hostname ").map(|h| h.trim().to_string())).filter(|h| !h.is_empty())
}

// ---------------------------------------------------------------------------
// Act

pub async fn check(engine: &Arc<Engine>, req: CheckRequest) -> ApiResult<Vec<MachineSummary>> {
    engine.refresh_from_disk();
    let only = match &req.machine_id {
        Some(id) => {
            let s = engine.current();
            let m = find_machine(&s, id)?;
            if m.host.is_empty() {
                return Err(ApiError::invalid(format!("{} has no host in config.toml, so it can't be checked.", m.name)));
            }
            Some(m.id.clone())
        }
        None => None,
    };
    // This also waits out a check of the same machine that was already in flight.
    engine.run_check(only.clone().map(|id| vec![id])).await;
    engine.sync_github().await;
    let s = engine.current();
    Ok(s.machines.iter().filter(|m| only.as_ref().is_none_or(|id| &m.id == id)).map(machine_summary).collect())
}

pub async fn add_machine(engine: &Arc<Engine>, req: AddMachineRequest, surface: Surface) -> ApiResult<AddMachineResponse> {
    engine.refresh_from_disk();
    let id = engine.add_machine(NewMachine { name: req.name, host: req.host }).map_err(op_error)?;
    let machine = if req.check {
        wait_checked(engine, &id, CHECK_WAIT).await;
        let s = engine.current();
        s.machines.iter().find(|m| m.id == id).map(|m| machine_detail(&s, m))
    } else {
        None
    };
    let next = match machine.as_ref().map(|m| m.summary.status.as_str()) {
        Some("online") => surface.say(
            format!("Machine is reachable. Install runners with install_runners(machine_id=\"{id}\", count=N)."),
            format!("Machine is reachable. Install runners with `muxin install {id} --count N`."),
        ),
        Some("offline") => surface.say(
            "The machine didn't answer over ssh. Make sure key-based `ssh <host>` works without a password prompt, then call check_machines.",
            "The machine didn't answer over ssh. Make sure key-based `ssh <host>` works without a password prompt, then run `muxin check`.",
        ),
        _ => surface.say(format!("Call check_machines(machine_id=\"{id}\") to check it."), "Run `muxin check` to check it.".to_string()),
    };
    Ok(AddMachineResponse { machine_id: id, machine, next })
}

/// Disconnects from a machine (Muxin stops connecting to it, checking it and
/// looking at its sessions, which go on there) or connects again (and checks
/// it, waiting for that).
pub async fn connect_machine(engine: &Arc<Engine>, req: ConnectMachineRequest) -> ApiResult<MachineSummary> {
    engine.refresh_from_disk();
    let id = find_machine(&engine.current(), &req.machine_id)?.id.clone();
    engine.set_connected(&id, req.connected).map_err(op_error)?;
    if req.connected {
        engine.run_check(Some(vec![id.clone()])).await;
    }
    let s = engine.current();
    Ok(machine_summary(find_machine(&s, &id)?))
}

/// Gives a machine a new name; its id (and everything tied to it) stays.
pub async fn rename_machine(engine: &Arc<Engine>, req: RenameMachineRequest) -> ApiResult<MachineSummary> {
    engine.refresh_from_disk();
    let id = find_machine(&engine.current(), &req.machine_id)?.id.clone();
    engine.rename_machine(&id, &req.name).map_err(op_error)?;
    let s = engine.current();
    Ok(machine_summary(find_machine(&s, &id)?))
}

pub async fn remove_machine(engine: &Arc<Engine>, req: MachineRequest) -> ApiResult<MachineSummary> {
    engine.refresh_from_disk();
    let s = engine.current();
    let m = find_machine(&s, &req.machine_id)?.clone();
    engine.remove_machine(&m.id).map_err(op_error)?;
    // Its agent forgetting this app (when it was paired) finishes before a CLI run exits.
    engine.unpaired(&m.id).await;
    Ok(machine_summary(&m))
}

pub async fn install_runners(engine: &Arc<Engine>, req: InstallRunnersRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<ActionResponse> {
    let s = freshen(engine).await;
    let machine_id = find_machine(&s, &req.machine_id)?.id.clone();

    let scope = match req.scope.map(|x| x.trim().to_string()).filter(|x| !x.is_empty()) {
        Some(scope) => scope,
        None => {
            let settings = engine.settings();
            let watched: Vec<String> = settings.github.orgs.iter().chain(settings.github.repos.iter()).cloned().collect();
            match watched.as_slice() {
                [one] => one.clone(),
                [] => {
                    return Err(ApiError::invalid("Say which GitHub org or repo to register the runners with (scope).").with_hint(surface.say(
                        "Watch it first with github_scopes(add=[\"<org>\"]), or pass scope=\"<org>\" / \"owner/repo\".",
                        "Watch it first with `muxin watch <org>`, or pass --scope <org> / owner/repo.",
                    )));
                }
                many => return Err(ApiError::invalid(format!("Several orgs/repos are watched ({}); pass scope.", many.join(", ")))),
            }
        }
    };

    let names = if req.names.is_empty() {
        let count = req.count.unwrap_or(1);
        if count == 0 || count > 32 {
            return Err(ApiError::invalid("count must be between 1 and 32."));
        }
        engine.suggest_runner_names(&machine_id, count)
    } else {
        req.names
    };

    let mode = InstallMode::parse(req.mode.as_deref().unwrap_or("auto"), req.image, req.docker_socket).map_err(ApiError::invalid)?;
    let op = engine
        .install_runners(InstallRequest {
            machine_id: machine_id.clone(),
            scope,
            names: names.clone(),
            labels: req.labels,
            group: req.runner_group,
            as_service: req.as_service,
            mode,
        })
        .map_err(op_error)?;
    finish_action(engine, op, req.wait, req.timeout_secs.unwrap_or(INSTALL_TIMEOUT_SECS), DEFAULT_TAIL, Some(machine_id), names, surface, on_line).await
}

pub async fn runner_action(engine: &Arc<Engine>, req: RunnerActionRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<ActionResponse> {
    let s = freshen(engine).await;
    let runner = find_runner(&s, &req.runner_id)?.clone();

    // Control needs the runner's folder from a machine check; get one if this process has none.
    if let Some(mid) = &runner.machine_id {
        let unchecked = s.machines.iter().find(|m| &m.id == mid).is_some_and(|m| m.probe.is_none());
        if unchecked && req.action != ActionName::Remove {
            engine.run_check(Some(vec![mid.clone()])).await;
            wait_checked(engine, mid, CHECK_WAIT).await;
        }
    }

    let action = match req.action {
        ActionName::Start => RunnerAction::Start,
        ActionName::Stop => RunnerAction::Stop,
        ActionName::Restart => RunnerAction::Restart,
        ActionName::Logs => RunnerAction::Logs,
        ActionName::Remove => RunnerAction::Remove { delete_files: req.delete_files },
    };
    let op = engine.runner_action(&runner.id, action).map_err(op_error)?;
    let tail = if req.action == ActionName::Logs { LOGS_TAIL } else { DEFAULT_TAIL };
    let timeout = req.timeout_secs.unwrap_or(ACTION_TIMEOUT_SECS);
    finish_action(engine, op, req.wait, timeout, tail, runner.machine_id.clone(), vec![runner.name.clone()], surface, on_line).await
}

/// The DigitalOcean account, regions, sizes and defaults for a new cloud machine.
pub async fn cloud_options(engine: &Arc<Engine>) -> crate::cloud::CloudOptions {
    engine.cloud_options().await
}

/// What the cloud machines cost: each one, this month, by the month's end,
/// and the DigitalOcean account's bill when the sign-in may read it.
pub async fn cloud_usage(engine: &Arc<Engine>) -> crate::cloud::usage::CloudUsage {
    freshen(engine).await;
    engine.cloud_usage().await
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CloudCreateRequest {
    pub name: String,
    #[serde(default)]
    pub region: Option<String>,
    #[serde(default)]
    pub size: Option<String>,
    /// What it comes with, by id (cloud::setup::EXTRAS: tools, languages, agent CLIs, tailscale).
    #[serde(default)]
    pub install: Option<Vec<String>>,
    /// Wait until it's set up and added (default true; takes a few minutes).
    #[serde(default = "yes")]
    pub wait: bool,
    #[serde(default)]
    pub timeout_secs: Option<u64>,
}

/// Creates a DigitalOcean droplet and adds it to the machines.
pub async fn cloud_create(engine: &Arc<Engine>, req: CloudCreateRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<ActionResponse> {
    freshen(engine).await;
    let machine = crate::cloud::CloudCreate {
        name: req.name,
        region: req.region,
        size: req.size,
        install: req.install,
    };
    let op = engine.cloud_create(machine).map_err(op_error)?;
    finish_action(engine, op, req.wait, req.timeout_secs.unwrap_or(1800), DEFAULT_TAIL, None, Vec::new(), surface, on_line).await
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CloudMachineRequest {
    pub machine_id: String,
    /// For power: "on" or "off".
    #[serde(default)]
    pub power: Option<String>,
    #[serde(default = "yes")]
    pub wait: bool,
}

/// Destroys a cloud machine: deletes the droplet and removes it from Muxin.
pub async fn cloud_destroy(engine: &Arc<Engine>, req: CloudMachineRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<ActionResponse> {
    let s = freshen(engine).await;
    let m = find_machine(&s, &req.machine_id)?.clone();
    let op = engine.cloud_destroy(&m.id).map_err(op_error)?;
    finish_action(engine, op, req.wait, 300, DEFAULT_TAIL, Some(m.id), Vec::new(), surface, on_line).await
}

/// Powers a cloud machine on or off (it's still billed while off).
pub async fn cloud_power(engine: &Arc<Engine>, req: CloudMachineRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<ActionResponse> {
    let s = freshen(engine).await;
    let m = find_machine(&s, &req.machine_id)?.clone();
    let on = match req.power.as_deref() {
        Some("on") => true,
        Some("off") => false,
        _ => return Err(ApiError::invalid("power must be \"on\" or \"off\".")),
    };
    let op = engine.cloud_power(&m.id, on).map_err(op_error)?;
    finish_action(engine, op, req.wait, 300, DEFAULT_TAIL, Some(m.id), Vec::new(), surface, on_line).await
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ScheduleListRequest {
    #[serde(default)]
    pub machine_id: Option<String>,
}

/// The schedules on each online machine (or one), with each one's last run.
pub async fn schedule_list(engine: &Arc<Engine>, req: ScheduleListRequest) -> ApiResult<Vec<crate::fleet::schedules::MachineSchedules>> {
    let s = freshen(engine).await;
    let id = match &req.machine_id {
        Some(m) => Some(find_machine(&s, m)?.id.clone()),
        None => None,
    };
    Ok(engine.schedules(id.as_deref()).await)
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ScheduleSaveRequest {
    pub machine_id: String,
    /// Given: change that schedule.
    #[serde(default)]
    pub id: Option<String>,
    pub name: String,
    pub when: crate::fleet::schedules::When,
    #[serde(default)]
    pub command: Option<String>,
    #[serde(default)]
    pub agent: Option<String>,
    #[serde(default)]
    pub prompt: Option<String>,
    #[serde(default)]
    pub folder: Option<String>,
    #[serde(default = "yes")]
    pub enabled: bool,
}

/// Saves a schedule on a machine: new, or changed when `id` is given.
pub async fn schedule_save(engine: &Arc<Engine>, req: ScheduleSaveRequest) -> ApiResult<crate::fleet::schedules::Schedule> {
    let s = freshen(engine).await;
    let m = find_machine(&s, &req.machine_id)?.clone();
    let input = crate::fleet::schedules::ScheduleInput { id: req.id, name: req.name, when: req.when, command: req.command, agent: req.agent, prompt: req.prompt, folder: req.folder, enabled: req.enabled };
    engine.schedule_save(&m.id, input).await.map_err(|e| ApiError::new("operation_failed", e))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ScheduleRequest {
    pub machine_id: String,
    pub schedule_id: String,
    /// schedule_log: the run that started then (Unix seconds); default the newest.
    #[serde(default)]
    pub started: Option<i64>,
}

pub async fn schedule_delete(engine: &Arc<Engine>, req: ScheduleRequest) -> ApiResult<serde_json::Value> {
    let s = freshen(engine).await;
    let m = find_machine(&s, &req.machine_id)?.clone();
    engine.schedule_delete(&m.id, &req.schedule_id).await.map_err(|e| ApiError::new("operation_failed", e))?;
    Ok(serde_json::json!({ "deleted": req.schedule_id }))
}

pub async fn schedule_run(engine: &Arc<Engine>, req: ScheduleRequest) -> ApiResult<serde_json::Value> {
    let s = freshen(engine).await;
    let m = find_machine(&s, &req.machine_id)?.clone();
    engine.schedule_run(&m.id, &req.schedule_id).await.map_err(|e| ApiError::new("operation_failed", e))?;
    Ok(serde_json::json!({ "started": req.schedule_id, "next": "It runs in the background there. Read its output with schedule_log." }))
}

pub async fn schedule_log(engine: &Arc<Engine>, req: ScheduleRequest) -> ApiResult<crate::fleet::schedules::ScheduleLog> {
    let s = freshen(engine).await;
    let m = find_machine(&s, &req.machine_id)?.clone();
    engine.schedule_log(&m.id, &req.schedule_id, req.started).await.map_err(|e| ApiError::new("operation_failed", e))
}

/// The machines VMs can run on (Docker; Windows also needs Linux with KVM),
/// what each can run, and the defaults.
pub async fn vm_options(engine: &Arc<Engine>) -> crate::ops::vm::VmOptions {
    freshen(engine).await;
    engine.vm_options()
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct VmCreateRequest {
    pub name: String,
    /// A system id from vm_options: "windows-11", "ubuntu-24.04", ...
    pub system: String,
    #[serde(default)]
    pub host: Option<String>,
    #[serde(default)]
    pub cpus: Option<u32>,
    #[serde(default)]
    pub memory_gb: Option<u32>,
    #[serde(default)]
    pub disk_gb: Option<u32>,
    /// Agent CLIs to install on a Linux VM: claude, codex, gemini, opencode, amp, pi.
    #[serde(default)]
    pub install: Vec<String>,
    #[serde(default = "yes")]
    pub wait: bool,
    #[serde(default)]
    pub timeout_secs: Option<u64>,
}

/// Creates a VM on one of the user's machines and adds it to them.
pub async fn vm_create(engine: &Arc<Engine>, req: VmCreateRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<ActionResponse> {
    freshen(engine).await;
    let id = crate::util::slug(req.name.trim());
    let create = crate::ops::vm::VmCreate { name: req.name, system: req.system, host: req.host, cpus: req.cpus, memory_gb: req.memory_gb, disk_gb: req.disk_gb, install: req.install };
    let op = engine.vm_create(create).map_err(op_error)?;
    finish_action(engine, op, req.wait, req.timeout_secs.unwrap_or(600), DEFAULT_TAIL, Some(id), Vec::new(), surface, on_line).await
}

/// Destroys a VM Muxin made: its container and disk, and the machine in Muxin.
pub async fn vm_destroy(engine: &Arc<Engine>, req: CloudMachineRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<ActionResponse> {
    let s = freshen(engine).await;
    let m = find_machine(&s, &req.machine_id)?.clone();
    let op = engine.vm_destroy(&m.id).map_err(op_error)?;
    finish_action(engine, op, req.wait, 300, DEFAULT_TAIL, None, Vec::new(), surface, on_line).await
}

/// Powers a machine on or off: a cloud machine through its provider, or a VM
/// (or container) in Docker on another of the user's machines by starting or
/// stopping that container there.
pub async fn machine_power(engine: &Arc<Engine>, req: CloudMachineRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<ActionResponse> {
    let s = freshen(engine).await;
    let m = find_machine(&s, &req.machine_id)?.clone();
    let on = match req.power.as_deref() {
        Some("on") => true,
        Some("off") => false,
        _ => return Err(ApiError::invalid("power must be \"on\" or \"off\".")),
    };
    let op = engine.machine_power(&m.id, on).map_err(op_error)?;
    finish_action(engine, op, req.wait, 420, DEFAULT_TAIL, Some(m.id), Vec::new(), surface, on_line).await
}

/// Cancels the workflow run a queued or running job belongs to.
pub async fn cancel_run(engine: &Arc<Engine>, req: CancelRunRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<ActionResponse> {
    freshen(engine).await;
    let op = engine.cancel_run(req.job_id).map_err(op_error)?;
    finish_action(engine, op, req.wait, req.timeout_secs.unwrap_or(60), DEFAULT_TAIL, None, Vec::new(), surface, on_line).await
}

#[allow(clippy::too_many_arguments)]
async fn finish_action(
    engine: &Arc<Engine>,
    op: u64,
    wait: bool,
    timeout_secs: u64,
    tail: usize,
    machine_id: Option<String>,
    runner_names: Vec<String>,
    surface: Surface,
    on_line: impl FnMut(&str),
) -> ApiResult<ActionResponse> {
    let operation = if wait {
        wait_operation(engine, op, Duration::from_secs(timeout_secs.max(1)), on_line).await
    } else {
        engine.current().operations.iter().find(|o| o.id == op).cloned()
    }
    .ok_or_else(|| ApiError::new("internal", format!("Operation {op} disappeared.")))?;

    let s = engine.current();
    let finished = operation.status != "running";
    let names: HashSet<String> = runner_names.iter().map(|n| n.to_ascii_lowercase()).collect();
    let response = ActionResponse {
        finished,
        machine: machine_id.as_ref().and_then(|id| s.machines.iter().find(|m| &m.id == id)).map(machine_summary),
        runners: s.runners.iter().filter(|r| names.contains(&r.name.to_ascii_lowercase())).map(|r| runner_out(&s, r)).collect(),
        next: (!finished).then(|| {
            surface.say(
                format!("Still running. Poll get_operation(operation_id={op}) until status isn't \"running\"."),
                "Still running in the background; this command stopped waiting. Check the result with `muxin status`.",
            )
        }),
        operation: operation_out(&operation, tail),
    };

    if operation.status == "failed" {
        let message = operation.error.clone().unwrap_or_else(|| "The operation failed.".into());
        let hint = failure_hint(&message);
        return Err(ApiError {
            code: "operation_failed",
            message,
            hint,
            details: serde_json::to_value(&response).ok(),
        });
    }
    Ok(response)
}

/// A next step for common failures, when the message doesn't already carry one.
fn failure_hint(message: &str) -> Option<String> {
    let m = message.to_ascii_lowercase();
    if m.contains("admin:org") {
        Some("gh auth refresh -h github.com -s admin:org".into())
    } else if m.contains("sudo") {
        Some("Allow passwordless sudo for the runner user on that machine, or install with mode \"docker\" or \"background\".".into())
    } else if m.contains("timed out") || m.contains("connection refused") || m.contains("could not resolve") {
        Some("The machine didn't answer over ssh. Check that `ssh <host>` works without a password prompt.".into())
    } else {
        None
    }
}

pub async fn github_scopes(engine: &Arc<Engine>, req: GitHubScopesRequest) -> ApiResult<ScopesResponse> {
    engine.refresh_from_disk();
    let mut settings = engine.settings();
    let mut results = Vec::new();

    for raw in &req.remove {
        let name = crate::config::strip_github_url(raw);
        let before = settings.github.orgs.len() + settings.github.repos.len();
        settings.github.orgs.retain(|o| !o.eq_ignore_ascii_case(&name));
        settings.github.repos.retain(|r| !r.eq_ignore_ascii_case(&name));
        let removed = settings.github.orgs.len() + settings.github.repos.len() < before;
        results.push(ScopeResult {
            scope: name,
            result: if removed { "removed" } else { "not_watching" }.into(),
            runners: None,
            error: None,
            hint: None,
        });
    }

    for raw in &req.add {
        let name = crate::config::strip_github_url(raw);
        if name.is_empty() {
            continue;
        }
        let watched = settings.github.orgs.iter().chain(settings.github.repos.iter()).any(|x| x.eq_ignore_ascii_case(&name));
        if watched {
            results.push(ScopeResult { scope: name, result: "already_watching".into(), runners: None, error: None, hint: None });
            continue;
        }
        let t = engine.test_scope(&name).await;
        if t.error.is_none() {
            match t.kind {
                crate::github::ScopeKind::Repo => settings.github.repos.push(t.name.clone()),
                crate::github::ScopeKind::Org => settings.github.orgs.push(t.name.clone()),
            }
            results.push(ScopeResult { scope: t.name, result: "added".into(), runners: Some(t.runners), error: None, hint: None });
        } else {
            results.push(ScopeResult { scope: t.name, result: "failed".into(), runners: None, error: t.error, hint: t.hint });
        }
    }

    engine.update_settings(settings).map_err(ApiError::invalid)?;
    engine.sync_github().await;
    let s = engine.current();
    let watching = s
        .github
        .scopes
        .iter()
        .map(|sc| ScopeOut { kind: sc.kind.clone(), name: sc.name.clone(), runners: sc.runners, error: sc.error.clone(), hint: sc.hint.clone() })
        .collect();
    Ok(ScopesResponse { results, watching })
}

pub fn update_settings(engine: &Arc<Engine>, req: UpdateSettingsRequest) -> ApiResult<SettingsOut> {
    engine.refresh_from_disk();
    let mut s = engine.settings();
    if let Some(v) = req.github_poll_seconds {
        s.github_poll_seconds = v;
    }
    if let Some(v) = req.scan_repos {
        s.github.scan_repos = v;
    }
    if let Some(v) = req.check_interval_minutes {
        s.check_interval_minutes = v;
    }
    if let Some(v) = req.api_url {
        s.github.api_url = v;
    }
    engine.update_settings(s).map_err(ApiError::invalid)?;
    Ok(settings(engine))
}

// ---------------------------------------------------------------------------
// Workspaces: a persistent work environment on one of the user's machines.

const EXEC_DEFAULT_TIMEOUT_SECS: u64 = 600;
const EXEC_MAX_TIMEOUT_SECS: u64 = 3600;
const READ_DEFAULT_BYTES: usize = 256 * 1024;
const READ_MAX_BYTES: usize = 2 * 1024 * 1024;
const LIST_DEFAULT_DEPTH: u32 = 2;
const LIST_MAX_DEPTH: u32 = 10;
const HISTORY_IN_GET: usize = 20;

#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct WorkspaceCreateRequest {
    /// Machine id to use. Omit to let Muxin pick the least-loaded online machine that allows workspaces.
    pub machine_id: Option<String>,
    /// When picking a machine: platform prefix it must match, e.g. "linux", "linux-x64", "darwin-arm64", "windows".
    pub platform: Option<String>,
    /// Short label, e.g. "api-tests". Defaults to the repo name.
    pub name: Option<String>,
    /// Git URL, or "owner/repo" for GitHub, to clone into the workspace.
    pub repo: Option<String>,
    /// Branch, tag or commit to check out; "pull/123/head" for a pull request's code.
    #[serde(rename = "ref")]
    pub git_ref: Option<String>,
    /// New branch to create and switch to after checkout.
    pub branch: Option<String>,
    /// "host" (default): run directly on the machine as its ssh user. "docker": a fresh
    /// container per workspace with the folder mounted at /workspace.
    #[serde(default)]
    pub isolation: Option<String>,
    /// Docker image for isolation "docker", e.g. "node:22", "python:3.13", "rust:1".
    #[serde(default)]
    pub image: Option<String>,
    /// Share the machine's Docker socket with the container (docker-in-docker; root-equivalent).
    #[serde(default)]
    pub docker_socket: bool,
    /// A git checkout's folder on the machine (from local_checkouts): the workspace is a new git
    /// worktree of it, on `branch` (from `ref`, else the default branch), instead of a fresh clone,
    /// so several agents can work on one repository at once. Needs machine_id; not with docker.
    #[serde(default)]
    pub worktree_of: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceRequest {
    /// Workspace id, e.g. "ws-7f3a2c".
    pub workspace_id: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceExecRequest {
    pub workspace_id: String,
    /// Shell command, run with the machine user's login shell environment.
    pub command: String,
    /// Folder relative to the workspace to run in.
    #[serde(default)]
    pub cwd: Option<String>,
    /// Extra environment variables.
    #[serde(default)]
    pub env: BTreeMap<String, String>,
    /// Kill it after this many seconds (default 600, max 3600). Ignored with background.
    #[serde(default)]
    pub timeout_secs: Option<u64>,
    /// Start it detached (servers, watchers) and return right away with its pid and log file.
    #[serde(default)]
    pub background: bool,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceReadRequest {
    pub workspace_id: String,
    /// File path relative to the workspace.
    pub path: String,
    /// Read at most this many bytes (default 262144, max 2097152).
    #[serde(default)]
    pub max_bytes: Option<usize>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceWriteRequest {
    pub workspace_id: String,
    /// File path relative to the workspace; parent folders are created.
    pub path: String,
    /// Text content (UTF-8).
    pub content: String,
    /// Append instead of replacing.
    #[serde(default)]
    pub append: bool,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceFilesRequest {
    pub workspace_id: String,
    /// Folder relative to the workspace (default: the workspace itself).
    #[serde(default)]
    pub path: Option<String>,
    /// How deep to list (default 2, max 10).
    #[serde(default)]
    pub depth: Option<u32>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceSyncRequest {
    pub workspace_id: String,
    /// Folder on this computer. Relative paths are resolved against this process's working directory.
    pub local_path: String,
    /// "push" copies the local folder into the workspace; "pull" copies the workspace into the local folder.
    pub direction: SyncDirection,
    /// Also delete files on the receiving side that the sending side doesn't have.
    #[serde(default)]
    pub delete: bool,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceDestroyRequest {
    pub workspace_id: String,
    /// Keep the folder on the machine; only forget the workspace.
    #[serde(default)]
    pub keep_files: bool,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceAllowRequest {
    pub machine_id: String,
    /// Whether agents may create workspaces on the machine.
    pub allowed: bool,
}

#[derive(Debug, Clone, Serialize)]
pub struct WorkspaceOut {
    pub id: String,
    pub name: String,
    pub machine_id: String,
    pub machine_name: String,
    pub host: String,
    pub platform: String,
    /// Absolute path on the machine.
    pub path: String,
    pub repo: Option<String>,
    #[serde(rename = "ref")]
    pub git_ref: Option<String>,
    pub branch: Option<String>,
    pub owner: Option<String>,
    /// "host" or "docker".
    pub isolation: String,
    /// Docker image, for docker workspaces.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub image: Option<String>,
    /// Container name, for docker workspaces.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub container: Option<String>,
    /// Worktree workspaces: the checkout (a folder on the same machine) it's a git worktree of.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub worktree_of: Option<String>,
    /// What the work in it changed, as last looked at: branch, files and lines since the
    /// default branch, uncommitted files, and the branch's pull request with its checks.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub git: Option<crate::fleet::sessions::git::GitStatus>,
    /// "creating" | "ready" | "failed" | "destroying"
    pub status: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    pub created_at: DateTime<Utc>,
    pub last_used_at: DateTime<Utc>,
    /// Total commands run here.
    pub commands: usize,
    /// For a human at a terminal: opens a shell in the workspace.
    pub shell: String,
    pub last_command: Option<CommandOut>,
    /// Recent commands, newest last (workspace_get only).
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub history: Vec<CommandOut>,
}

#[derive(Debug, Clone, Serialize)]
pub struct CommandOut {
    pub command: String,
    pub exit_code: Option<i32>,
    pub started_at: DateTime<Utc>,
    pub duration_ms: u64,
    pub background: bool,
    pub timed_out: bool,
    pub by: Option<String>,
    pub output_tail: Vec<String>,
}

#[derive(Debug, Serialize)]
pub struct WorkspacesResponse {
    pub summary: String,
    pub workspaces: Vec<WorkspaceOut>,
    /// Machines that accept new workspaces (allowed, and not known to be unreachable).
    pub available_machines: Vec<String>,
}

#[derive(Debug, Serialize)]
pub struct WorkspaceCreated {
    pub workspace: WorkspaceOut,
    pub next: String,
}

#[derive(Debug, Serialize)]
pub struct ExecOut {
    pub workspace_id: String,
    pub command: String,
    /// The command's exit status; null when it timed out or runs in the background.
    pub exit_code: Option<i32>,
    pub stdout: String,
    pub stderr: String,
    pub duration_ms: u64,
    pub timed_out: bool,
    /// Output was longer than the cap; the middle was dropped.
    pub truncated: bool,
    pub background_pid: Option<u32>,
    /// Background commands: where their output goes, relative to the workspace.
    pub log_path: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct FileOut {
    pub workspace_id: String,
    pub path: String,
    pub size: u64,
    pub truncated: bool,
    /// Not text; `content` is empty.
    pub binary: bool,
    pub content: String,
}

#[derive(Debug, Serialize)]
pub struct WriteOut {
    pub workspace_id: String,
    pub path: String,
    /// File size after the write, in bytes.
    pub size: u64,
}

#[derive(Debug, Serialize)]
pub struct FileEntryOut {
    pub path: String,
    /// "file" | "dir" | "link"
    pub kind: String,
    pub size: u64,
}

#[derive(Debug, Serialize)]
pub struct FilesOut {
    pub workspace_id: String,
    pub path: String,
    pub entries: Vec<FileEntryOut>,
}

#[derive(Debug, Serialize)]
pub struct ChangesOut {
    pub workspace_id: String,
    /// `git status` and the uncommitted diff (capped), or a note when it isn't a git checkout.
    pub changes: String,
}

#[derive(Debug, Serialize)]
pub struct SyncOut {
    pub workspace_id: String,
    pub local_path: String,
    pub direction: SyncDirection,
    pub summary: String,
}

#[derive(Debug, Serialize)]
pub struct DestroyOut {
    pub workspace_id: String,
    pub kept_files: bool,
}

#[derive(Debug, Serialize)]
pub struct AllowOut {
    pub machine_id: String,
    pub workspaces_allowed: bool,
}

fn command_out(c: &WorkspaceCommand) -> CommandOut {
    CommandOut {
        command: c.command.clone(),
        exit_code: c.exit_code,
        started_at: c.started_at,
        duration_ms: c.duration_ms,
        background: c.background,
        timed_out: c.timed_out,
        by: c.by.clone(),
        output_tail: c.output_tail.clone(),
    }
}

pub fn workspace_out(w: &WorkspaceInfo, history: usize) -> WorkspaceOut {
    let start = w.history.len().saturating_sub(history);
    WorkspaceOut {
        id: w.id.clone(),
        name: w.name.clone(),
        machine_id: w.machine_id.clone(),
        machine_name: w.machine_name.clone(),
        host: w.host.clone(),
        platform: w.platform.clone(),
        path: w.path.clone(),
        repo: w.repo.clone(),
        git_ref: w.git_ref.clone(),
        branch: w.branch.clone(),
        isolation: w.isolation.clone(),
        image: w.image.clone(),
        container: w.container.clone(),
        worktree_of: w.worktree_of.clone(),
        git: w.git.clone(),
        owner: w.owner.clone(),
        status: w.status.clone(),
        error: w.error.clone(),
        created_at: w.created_at,
        last_used_at: w.last_used_at,
        commands: w.commands,
        shell: w.shell.clone(),
        last_command: w.history.last().map(command_out),
        history: if history == 0 { Vec::new() } else { w.history[start..].iter().map(command_out).collect() },
    }
}

/// Maps a message from the workspace backend onto an error code.
fn ws_error(message: String, surface: Surface) -> ApiError {
    let m = message.to_ascii_lowercase();
    let code = if m.contains("not implemented") || m.contains("implemented yet") {
        "internal"
    } else if m.contains("no workspace") || m.contains("unknown workspace") || m.contains("isn't in config.toml") || m.contains("no machine") || m.contains("not found") {
        "not_found"
    } else if m.contains("unreachable")
        || m.contains("timed out")
        || m.contains("connection refused")
        || m.contains("could not resolve")
        || m.contains("didn't answer")
        || m.contains("no route to host")
    {
        "unreachable"
    } else if m.contains("still being created") || m.contains("being destroyed") || m.contains("busy") {
        "busy"
    } else {
        "invalid"
    };
    let mut err = ApiError::new(code, message);
    if code == "unreachable" {
        err = err.with_hint("The machine didn't answer over ssh. Check that `ssh <host>` works without a password prompt, or pick another machine.");
    } else if m.contains("doesn't allow") || m.contains("not allowed") || m.contains("disabled") {
        err = err.with_hint(surface.say(
            "Turn workspaces on for that machine (workspace_allow, the toggle in the app, or `workspaces = true` in config.toml), or pick another machine.",
            "Turn workspaces on for that machine (`muxin workspace allow <machine-id>`, the toggle in the app, or `workspaces = true` in config.toml), or pick another machine.",
        ));
    } else if m.contains("rsync") {
        err = err.with_hint("Install rsync on both this computer and the machine.");
    } else if m.contains("docker isn't available") || m.contains("couldn't pull") || m.contains("couldn't start a container") {
        err = err.with_hint("Install Docker on that machine (and add the ssh user to the docker group), use isolation \"host\", or pick a machine where Docker works.");
    }
    err
}

/// The current workspaces, including ones other Muxin processes created.
fn current_workspaces(engine: &Arc<Engine>) -> Vec<WorkspaceInfo> {
    engine.refresh_from_disk();
    engine.workspaces()
}

fn find_workspace(engine: &Arc<Engine>, id: &str, surface: Surface) -> ApiResult<WorkspaceInfo> {
    let all = current_workspaces(engine);
    let id = id.trim();
    if let Some(w) = all.iter().find(|w| w.id == id) {
        return Ok(w.clone());
    }
    // A unique name works too, like machine names do.
    let by_name: Vec<&WorkspaceInfo> = all.iter().filter(|w| w.name.eq_ignore_ascii_case(id)).collect();
    if let [one] = by_name.as_slice() {
        return Ok((*one).clone());
    }
    Err(ApiError::not_found(format!("No workspace \"{id}\".")).with_hint(if all.is_empty() {
        surface.say("There are no workspaces; create one with workspace_create.", "There are no workspaces; create one with `muxin workspace create`.")
    } else {
        let known = all.iter().map(|w| w.id.as_str()).collect::<Vec<_>>().join(", ");
        surface.say(
            &format!("Known workspaces: {known}. Or create one with workspace_create."),
            &format!("Known workspaces: {known}. Or create one with `muxin workspace create`."),
        )
    }))
}

/// Paths inside a workspace must be relative and stay inside it.
fn workspace_path(raw: &str) -> ApiResult<String> {
    let p = raw.trim();
    let windows_abs = p.len() >= 2 && p.as_bytes()[1] == b':';
    if p.starts_with('/') || p.starts_with('\\') || p.starts_with('~') || windows_abs {
        return Err(ApiError::invalid(format!("\"{raw}\" isn't relative to the workspace.")).with_hint("Use a path relative to the workspace folder, e.g. \"src/main.rs\"."));
    }
    let mut depth: i32 = 0;
    for c in Path::new(&p.replace('\\', "/")).components() {
        match c {
            Component::ParentDir => depth -= 1,
            Component::Normal(_) => depth += 1,
            _ => {}
        }
        if depth < 0 {
            return Err(ApiError::invalid(format!("\"{raw}\" points outside the workspace.")));
        }
    }
    Ok(p.to_string())
}

pub async fn workspaces_list(engine: &Arc<Engine>) -> WorkspacesResponse {
    // Each one's branch and pull request (a merged one means its work is done).
    let s = engine.current();
    let mut machines: Vec<String> = current_workspaces(engine).iter().filter(|w| w.status == "ready" && s.machines.iter().any(|m| m.id == w.machine_id && !m.is_down())).map(|w| w.machine_id.clone()).collect();
    machines.sort();
    machines.dedup();
    look_at_stale_git(engine, machines.iter().map(String::as_str)).await;
    let all = engine.workspaces();
    let s = engine.current();
    // Unchecked machines count: creating a workspace checks the machine first.
    let available: Vec<String> = s.machines.iter().filter(|m| m.workspaces_allowed && !m.is_down()).map(|m| m.id.clone()).collect();
    let ready = all.iter().filter(|w| w.status == "ready").count();
    WorkspacesResponse {
        summary: format!(
            "{} workspace{} ({} ready). {} machine{} available for new ones{}.",
            all.len(),
            plural(all.len()),
            ready,
            available.len(),
            plural(available.len()),
            if available.is_empty() { "" } else { ": " }.to_string() + &available.join(", ")
        ),
        workspaces: all.iter().map(|w| workspace_out(w, 0)).collect(),
        available_machines: available,
    }
}

pub fn workspace_get(engine: &Arc<Engine>, req: WorkspaceRequest, surface: Surface) -> ApiResult<WorkspaceOut> {
    Ok(workspace_out(&find_workspace(engine, &req.workspace_id, surface)?, HISTORY_IN_GET))
}

pub async fn workspace_create(engine: &Arc<Engine>, req: WorkspaceCreateRequest, owner: &str, surface: Surface) -> ApiResult<WorkspaceCreated> {
    engine.refresh_from_disk();
    let machine = match req.machine_id.as_deref().map(str::trim).filter(|m| !m.is_empty()) {
        Some(id) => {
            let s = engine.current();
            let m = find_machine(&s, id)?;
            if !m.workspaces_allowed {
                return Err(ApiError::invalid(format!("{} doesn't allow workspaces.", m.name))
                    .with_hint(surface.say(
                        format!("Turn them on with workspace_allow(machine_id=\"{}\", allowed=true) if the user agrees, or pick another machine.", m.id),
                        format!("Turn them on with `muxin workspace allow {}`, or pick another machine.", m.id),
                    )));
            }
            Some(m.id.clone())
        }
        None => None,
    };
    let clean = |v: Option<String>| v.map(|x| x.trim().to_string()).filter(|x| !x.is_empty());
    let iso = crate::fleet::workspaces::WorkspaceIsolation {
        isolation: clean(req.isolation),
        image: clean(req.image),
        docker_socket: req.docker_socket,
    };
    let created = engine
        .create_workspace_with(
            CreateWorkspace {
                machine,
                platform: clean(req.platform),
                name: clean(req.name),
                repo: clean(req.repo),
                git_ref: clean(req.git_ref),
                branch: clean(req.branch),
                owner: Some(owner.to_string()),
                worktree_of: clean(req.worktree_of),
            },
            iso,
        )
        .await
        .map_err(|e| ws_error(e, surface))?;
    let id = &created.id;
    let next = surface.say(
        format!("Run commands with workspace_exec(workspace_id=\"{id}\", command=...). Review edits with workspace_changes. Call workspace_destroy(workspace_id=\"{id}\") when the task is done."),
        format!("Run commands with `muxin workspace exec {id} -- <command>`; review edits with `muxin workspace changes {id}`; destroy it with `muxin workspace rm {id}` when done."),
    );
    Ok(WorkspaceCreated { workspace: workspace_out(&created, 0), next })
}

pub async fn workspace_exec(engine: &Arc<Engine>, req: WorkspaceExecRequest, by: &str, surface: Surface) -> ApiResult<ExecOut> {
    let command = req.command.trim().to_string();
    if command.is_empty() {
        return Err(ApiError::invalid("command is empty."));
    }
    let timeout = req.timeout_secs.unwrap_or(EXEC_DEFAULT_TIMEOUT_SECS);
    if timeout == 0 || timeout > EXEC_MAX_TIMEOUT_SECS {
        return Err(ApiError::invalid(format!("timeout_secs must be between 1 and {EXEC_MAX_TIMEOUT_SECS}."))
            .with_hint(surface.say("For longer work, run it with background=true and read its log file.", "For longer work, run it with --background and read its log file.")));
    }
    for key in req.env.keys() {
        let valid = !key.is_empty() && !key.starts_with(|c: char| c.is_ascii_digit()) && key.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
        if !valid {
            return Err(ApiError::invalid(format!("\"{key}\" isn't a valid environment variable name.")));
        }
    }
    let cwd = req.cwd.as_deref().map(workspace_path).transpose()?.filter(|c| !c.is_empty() && c != ".");
    let w = find_workspace(engine, &req.workspace_id, surface)?;
    let result = engine
        .workspace_exec(
            &w.id,
            &command,
            ExecOptions {
                timeout_secs: Some(timeout),
                env: req.env.into_iter().collect(),
                cwd,
                background: req.background,
                by: Some(by.to_string()),
            },
        )
        .await
        .map_err(|e| ws_error(e, surface))?;
    let pid = result.background_pid.map(|p| p.to_string()).unwrap_or_else(|| "?".into());
    let next = if let Some(log) = &result.log_path {
        Some(surface.say(
            format!("Running in the background (pid {pid}). Read its output with workspace_read_file(path=\"{log}\") or workspace_exec(command=\"tail -n 50 {log}\")."),
            format!("Running in the background (pid {pid}). Read its output with `muxin workspace cat {} {log}`.", w.id),
        ))
    } else if result.timed_out {
        Some(surface.say(
            format!("Killed after {timeout}s. Raise timeout_secs (max {EXEC_MAX_TIMEOUT_SECS}) or run it with background=true."),
            format!("Killed after {timeout}s. Raise --timeout (max {EXEC_MAX_TIMEOUT_SECS}) or run it with --background."),
        ))
    } else {
        None
    };
    Ok(ExecOut {
        workspace_id: w.id,
        command,
        exit_code: result.exit_code,
        stdout: result.stdout,
        stderr: result.stderr,
        duration_ms: result.duration_ms,
        timed_out: result.timed_out,
        truncated: result.truncated,
        background_pid: result.background_pid,
        log_path: result.log_path,
        next,
    })
}

pub async fn workspace_read_file(engine: &Arc<Engine>, req: WorkspaceReadRequest, surface: Surface) -> ApiResult<FileOut> {
    let path = workspace_path(&req.path)?;
    if path.is_empty() {
        return Err(ApiError::invalid("path is empty."));
    }
    let max = req.max_bytes.unwrap_or(READ_DEFAULT_BYTES);
    if max == 0 || max > READ_MAX_BYTES {
        return Err(ApiError::invalid(format!("max_bytes must be between 1 and {READ_MAX_BYTES}.")));
    }
    let w = find_workspace(engine, &req.workspace_id, surface)?;
    let f = engine.workspace_read_file(&w.id, &path, max).await.map_err(|e| ws_error(e, surface))?;
    Ok(FileOut { workspace_id: w.id, path: f.path, size: f.size, truncated: f.truncated, binary: f.binary, content: f.content })
}

pub async fn workspace_write_file(engine: &Arc<Engine>, req: WorkspaceWriteRequest, surface: Surface) -> ApiResult<WriteOut> {
    let path = workspace_path(&req.path)?;
    if path.is_empty() || path.ends_with('/') {
        return Err(ApiError::invalid("path must name a file."));
    }
    let w = find_workspace(engine, &req.workspace_id, surface)?;
    let size = engine.workspace_write_file(&w.id, &path, &req.content, req.append).await.map_err(|e| ws_error(e, surface))?;
    Ok(WriteOut { workspace_id: w.id, path, size })
}

pub async fn workspace_list_files(engine: &Arc<Engine>, req: WorkspaceFilesRequest, surface: Surface) -> ApiResult<FilesOut> {
    let path = workspace_path(req.path.as_deref().unwrap_or(""))?;
    let depth = req.depth.unwrap_or(LIST_DEFAULT_DEPTH);
    if depth == 0 || depth > LIST_MAX_DEPTH {
        return Err(ApiError::invalid(format!("depth must be between 1 and {LIST_MAX_DEPTH}.")));
    }
    let w = find_workspace(engine, &req.workspace_id, surface)?;
    let entries = engine.workspace_list_files(&w.id, &path, depth).await.map_err(|e| ws_error(e, surface))?;
    Ok(FilesOut {
        workspace_id: w.id,
        path: if path.is_empty() { ".".into() } else { path },
        entries: entries.into_iter().map(|e| FileEntryOut { path: e.path, kind: e.kind, size: e.size }).collect(),
    })
}

pub async fn workspace_changes(engine: &Arc<Engine>, req: WorkspaceRequest, surface: Surface) -> ApiResult<ChangesOut> {
    let w = find_workspace(engine, &req.workspace_id, surface)?;
    let changes = engine.workspace_changes(&w.id).await.map_err(|e| ws_error(e, surface))?;
    Ok(ChangesOut { workspace_id: w.id, changes })
}

pub async fn workspace_sync(engine: &Arc<Engine>, req: WorkspaceSyncRequest, surface: Surface) -> ApiResult<SyncOut> {
    let raw = req.local_path.trim();
    if raw.is_empty() {
        return Err(ApiError::invalid("local_path is empty."));
    }
    let expanded = match raw.strip_prefix("~/") {
        Some(rest) => dirs::home_dir().map(|h| h.join(rest)).unwrap_or_else(|| raw.into()),
        None => std::path::PathBuf::from(raw),
    };
    let local = if expanded.is_absolute() {
        expanded
    } else {
        std::env::current_dir().map(|d| d.join(&expanded)).unwrap_or(expanded)
    };
    if req.direction == SyncDirection::Push && !local.is_dir() {
        return Err(ApiError::invalid(format!("{} isn't a folder on this computer.", local.display())));
    }
    let w = find_workspace(engine, &req.workspace_id, surface)?;
    let local_str = local.display().to_string();
    let summary = engine.workspace_sync(&w.id, &local_str, req.direction, req.delete).await.map_err(|e| ws_error(e, surface))?;
    Ok(SyncOut { workspace_id: w.id, local_path: local_str, direction: req.direction, summary })
}

pub async fn workspace_destroy(engine: &Arc<Engine>, req: WorkspaceDestroyRequest, surface: Surface) -> ApiResult<DestroyOut> {
    let w = find_workspace(engine, &req.workspace_id, surface)?;
    engine.destroy_workspace(&w.id, req.keep_files).await.map_err(|e| ws_error(e, surface))?;
    Ok(DestroyOut { workspace_id: w.id, kept_files: req.keep_files })
}

pub fn workspace_allow(engine: &Arc<Engine>, req: WorkspaceAllowRequest, surface: Surface) -> ApiResult<AllowOut> {
    engine.refresh_from_disk();
    let s = engine.current();
    let m = find_machine(&s, &req.machine_id)?;
    if m.host.is_empty() {
        return Err(ApiError::invalid(format!("{} has no host in config.toml, so it can't host workspaces.", m.name)));
    }
    let id = m.id.clone();
    engine.set_workspaces_allowed(&id, req.allowed).map_err(|e| ws_error(e, surface))?;
    Ok(AllowOut { machine_id: id, workspaces_allowed: req.allowed })
}

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

    fn demo() -> Arc<Engine> {
        Engine::new(Paths::resolve(Some(std::env::temp_dir().join("muxen-api-test")), None), true)
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn status_reads_the_demo_machines() {
        let engine = demo();
        let s = status(&engine, StatusRequest { refresh: true }, Surface::Mcp).await.unwrap();
        assert_eq!(s.counts.machines, 9);
        assert!(s.demo && s.github.live);
        assert!(s.summary.contains("9 machines"), "{}", s.summary);
        let harbor = s.machines.iter().find(|m| m.id == "harbor").unwrap();
        assert_eq!(harbor.status, "offline");
        assert!(harbor.error.is_some());
        assert!(s.attention.iter().any(|a| a.machine_id.as_deref() == Some("harbor")));

        let err = machine(&engine, MachineRequest { machine_id: "nope".into() }).await.unwrap_err();
        assert_eq!(err.code, "not_found");
        assert!(err.hint.unwrap().contains("forge"));
        let m = machine(&engine, MachineRequest { machine_id: "Forge".into() }).await.unwrap();
        assert_eq!(m.runners.len(), 3);
        assert!(runners(&engine, RunnersRequest { state: Some("busy".into()), ..Default::default() }).await.is_err());
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn adds_a_machine_and_controls_its_runner() {
        let engine = demo();
        engine.run_check(None).await;

        let added = add_machine(&engine, AddMachineRequest { name: "Beelink".into(), host: "beelink".into(), check: true }, Surface::Mcp).await.unwrap();
        assert_eq!(added.machine_id, "beelink");
        assert_eq!(added.machine.as_ref().unwrap().summary.status, "online");

        let mut lines = 0;
        let installed = install_runners(
            &engine,
            InstallRunnersRequest {
                machine_id: "beelink".into(),
                scope: None, // the demo watches exactly one org
                names: vec![],
                count: Some(1),
                labels: vec!["gpu".into()],
                runner_group: None,
                as_service: true,
                mode: None,
                image: None,
                docker_socket: false,
                wait: true,
                timeout_secs: Some(60),
            },
            Surface::Mcp,
            |_| lines += 1,
        )
        .await
        .unwrap();
        assert!(installed.finished && installed.operation.status == "succeeded", "{:?}", installed.operation);
        assert!(lines > 5);
        assert_eq!(installed.runners.len(), 1);
        let rid = installed.runners[0].id.clone();
        assert_eq!(rid, "beelink/beelink-01");

        let act = |action, wait| RunnerActionRequest { runner_id: rid.clone(), action, delete_files: true, wait, timeout_secs: Some(30) };
        let logs = runner_action(&engine, act(ActionName::Logs, true), Surface::Mcp, |_| {}).await.unwrap();
        assert!(!logs.operation.log_tail.is_empty());
        let stopped = runner_action(&engine, act(ActionName::Stop, true), Surface::Mcp, |_| {}).await.unwrap();
        assert_eq!(stopped.runners[0].state, "offline");
        let started = runner_action(&engine, act(ActionName::Start, false), Surface::Mcp, |_| {}).await.unwrap();
        assert!(!started.finished && started.next.is_some());
        let op = wait_operation(&engine, started.operation.id, Duration::from_secs(30), |_| {}).await.unwrap();
        assert_eq!(op.status, "succeeded");
        assert_eq!(operation(&engine, OperationRequest { operation_id: op.id, tail: Some(1) }).unwrap().log_tail.len(), 1);

        let removed = runner_action(&engine, act(ActionName::Remove, true), Surface::Mcp, |_| {}).await.unwrap();
        assert!(removed.runners.is_empty());
        remove_machine(&engine, MachineRequest { machine_id: "beelink".into() }).await.unwrap();
        assert!(!engine.current().machines.iter().any(|m| m.id == "beelink"));

        // Installing on the unreachable laptop fails as an operation, with a hint.
        let err = install_runners(
            &engine,
            InstallRunnersRequest {
                machine_id: "harbor".into(),
                scope: Some("acme".into()),
                names: vec!["laravel-01".into()],
                count: None,
                labels: vec![],
                runner_group: None,
                as_service: true,
                mode: None,
                image: None,
                docker_socket: false,
                wait: true,
                timeout_secs: Some(30),
            },
            Surface::Mcp,
            |_| {},
        )
        .await
        .unwrap_err();
        assert_eq!(err.code, "operation_failed");
        assert!(err.hint.is_some() && err.details.is_some());
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn hints_name_the_callers_next_step() {
        // A fresh demo engine: nothing checked yet.
        let engine = demo();
        let s = engine.current();
        assert!(status_from(&s, Surface::Mcp).hint.unwrap().contains("check_machines"));
        let cli = status_from(&s, Surface::Cli).hint.unwrap();
        assert!(cli.contains("muxin status --refresh") && !cli.contains("check_machines"), "{cli}");
    }

    #[test]
    fn workspace_paths_stay_inside() {
        assert_eq!(workspace_path("src/main.rs").unwrap(), "src/main.rs");
        assert_eq!(workspace_path("a/../b").unwrap(), "a/../b");
        assert_eq!(workspace_path("").unwrap(), "");
        for bad in ["/etc/passwd", "~/x", "../x", "a/../../x", "C:\\x", "\\\\server\\x"] {
            assert_eq!(workspace_path(bad).unwrap_err().code, "invalid", "{bad}");
        }
    }

    #[test]
    fn workspace_errors_map_to_codes() {
        assert_eq!(ws_error("No workspace \"ws-x\".".into(), Surface::Mcp).code, "not_found");
        assert_eq!(ws_error("ssh: connect to host x port 22: Operation timed out".into(), Surface::Mcp).code, "unreachable");
        assert_eq!(ws_error("Workspaces aren't implemented yet.".into(), Surface::Mcp).code, "internal");
        assert!(ws_error("Mac Studio doesn't allow workspaces.".into(), Surface::Cli).hint.unwrap().contains("muxin workspace allow"));
        let e = ws_error("Mac Studio doesn't allow workspaces.".into(), Surface::Mcp);
        assert_eq!(e.code, "invalid");
        assert!(e.hint.unwrap().contains("workspace_allow"));
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn workspace_requests_are_validated_before_the_backend() {
        let engine = demo();
        let exec = |command: &str, timeout: Option<u64>, cwd: Option<&str>| WorkspaceExecRequest {
            workspace_id: "ws-nope".into(),
            command: command.into(),
            cwd: cwd.map(str::to_string),
            env: BTreeMap::new(),
            timeout_secs: timeout,
            background: false,
        };
        assert_eq!(workspace_exec(&engine, exec("  ", None, None), "test", Surface::Mcp).await.unwrap_err().code, "invalid");
        assert_eq!(workspace_exec(&engine, exec("ls", Some(0), None), "test", Surface::Mcp).await.unwrap_err().code, "invalid");
        assert_eq!(workspace_exec(&engine, exec("ls", Some(99_999), None), "test", Surface::Mcp).await.unwrap_err().code, "invalid");
        assert_eq!(workspace_exec(&engine, exec("ls", None, Some("../..")), "test", Surface::Mcp).await.unwrap_err().code, "invalid");
        let mut bad_env = exec("ls", None, None);
        bad_env.env.insert("1BAD".into(), "x".into());
        assert_eq!(workspace_exec(&engine, bad_env, "test", Surface::Mcp).await.unwrap_err().code, "invalid");
        // Valid input, unknown workspace.
        let missing = workspace_exec(&engine, exec("ls", None, Some("src")), "test", Surface::Cli).await.unwrap_err();
        assert!(missing.hint.as_deref().unwrap_or_default().contains("muxin workspace create"), "{missing:?}");
        assert_eq!(missing.code, "not_found");

        let read = WorkspaceReadRequest { workspace_id: "ws-nope".into(), path: "/etc/hosts".into(), max_bytes: None };
        assert_eq!(workspace_read_file(&engine, read, Surface::Mcp).await.unwrap_err().code, "invalid");
        let files = WorkspaceFilesRequest { workspace_id: "ws-nope".into(), path: None, depth: Some(50) };
        assert_eq!(workspace_list_files(&engine, files, Surface::Mcp).await.unwrap_err().code, "invalid");
        let sync = WorkspaceSyncRequest {
            workspace_id: "ws-nope".into(),
            local_path: "/definitely/not/a/folder".into(),
            direction: SyncDirection::Push,
            delete: false,
        };
        assert_eq!(workspace_sync(&engine, sync, Surface::Mcp).await.unwrap_err().code, "invalid");
        let create = WorkspaceCreateRequest { machine_id: Some("nope".into()), ..Default::default() };
        assert_eq!(workspace_create(&engine, create, "test", Surface::Mcp).await.unwrap_err().code, "not_found");
        assert_eq!(workspace_allow(&engine, WorkspaceAllowRequest { machine_id: "nope".into(), allowed: true }, Surface::Mcp).unwrap_err().code, "not_found");
    }

    /// Needs the workspace backend (src/fleet/workspaces.rs); run with `cargo test -- --ignored`
    /// once it's implemented. Exercises the whole agent flow on the demo machines.
    #[tokio::test(flavor = "multi_thread")]
    #[ignore = "needs the workspace backend"]
    async fn workspace_flow_in_demo() {
        let engine = demo();
        engine.run_check(None).await;
        let created = workspace_create(
            &engine,
            WorkspaceCreateRequest { platform: Some("linux".into()), repo: Some("acme/api".into()), ..Default::default() },
            "test-agent",
            Surface::Mcp,
        )
        .await
        .unwrap();
        let id = created.workspace.id.clone();
        assert_eq!(created.workspace.status, "ready");
        assert_eq!(created.workspace.owner.as_deref(), Some("test-agent"));
        assert!(created.workspace.platform.starts_with("linux"));

        let ran = workspace_exec(
            &engine,
            WorkspaceExecRequest { workspace_id: id.clone(), command: "pwd".into(), cwd: None, env: BTreeMap::new(), timeout_secs: None, background: false },
            "test-agent",
            Surface::Mcp,
        )
        .await
        .unwrap();
        assert_eq!(ran.exit_code, Some(0));

        workspace_write_file(&engine, WorkspaceWriteRequest { workspace_id: id.clone(), path: "notes/a.txt".into(), content: "hi".into(), append: false }, Surface::Mcp)
            .await
            .unwrap();
        let read = workspace_read_file(&engine, WorkspaceReadRequest { workspace_id: id.clone(), path: "notes/a.txt".into(), max_bytes: None }, Surface::Mcp).await.unwrap();
        assert_eq!(read.content, "hi");
        let files = workspace_list_files(&engine, WorkspaceFilesRequest { workspace_id: id.clone(), path: None, depth: None }, Surface::Mcp).await.unwrap();
        assert!(!files.entries.is_empty());
        workspace_changes(&engine, WorkspaceRequest { workspace_id: id.clone() }, Surface::Mcp).await.unwrap();

        let got = workspace_get(&engine, WorkspaceRequest { workspace_id: id.clone() }, Surface::Mcp).unwrap();
        assert!(got.commands >= 1 && !got.history.is_empty());
        assert!(workspaces_list(&engine).await.workspaces.iter().any(|w| w.id == id));

        workspace_destroy(&engine, WorkspaceDestroyRequest { workspace_id: id.clone(), keep_files: false }, Surface::Mcp).await.unwrap();
        assert_eq!(workspace_get(&engine, WorkspaceRequest { workspace_id: id }, Surface::Mcp).unwrap_err().code, "not_found");
    }

    #[test]
    fn a_machine_that_is_not_signed_in_to_the_github_cli_is_asked_again() {
        let cli = |logged_in| Some(GhCli { installed: true, logged_in, ..Default::default() });
        assert!(gh_answer_stands(&cli(true)));
        // Signed out, not installed, and never looked at are all asked again:
        // signing in on the machine is what changes the answer.
        assert!(!gh_answer_stands(&cli(false)));
        assert!(!gh_answer_stands(&Some(GhCli::default())));
        assert!(!gh_answer_stands(&None));
    }
}

// ---------------------------------------------------------------------------
// Agent sessions: terminals running Claude Code, Codex, ... on fleet machines

use crate::fleet::sessions::{self, Control, SessionInfo, StartSession};

/// Session size for sessions started without a terminal attached.
const HEADLESS_COLS: u16 = 160;
const HEADLESS_ROWS: u16 = 48;
const READ_DEFAULT_LINES: u32 = 200;

#[derive(Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionListRequest {
    /// Only this machine.
    #[serde(default)]
    pub machine_id: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionStartRequest {
    pub machine_id: String,
    /// "claude", "codex", "opencode", "gemini", "amp", "pi" or "shell".
    pub agent: String,
    /// Folder on the machine to start in. Default: the home folder.
    #[serde(default)]
    pub cwd: Option<String>,
    #[serde(default)]
    pub title: Option<String>,
    /// First message for the agent.
    #[serde(default)]
    pub prompt: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionRequest {
    /// "<machine-id>/<name>", e.g. "beelink/claude-3f9a". A bare name works when unique.
    pub session_id: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionRenameRequest {
    pub session_id: String,
    /// The new title. Empty goes back to the one it started with.
    pub title: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionHandoffRequest {
    /// A session ("<machine-id>/<name>", or a unique name) or a box ("box-7k2m9q").
    pub session_id: String,
    /// The agent to hand the work to: claude, codex, opencode, gemini, amp or pi.
    pub agent: String,
    /// Keep the old session running too. Default false: it ends.
    #[serde(default)]
    pub keep: bool,
    /// Another machine to move the work to (its commits, uncommitted changes
    /// and new files) and continue there. Default: the session's own.
    #[serde(default)]
    pub machine_id: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionSendRequest {
    pub session_id: String,
    /// Text to type into the session.
    pub text: String,
    /// Press Enter after the text. Default true.
    #[serde(default = "default_true")]
    pub enter: bool,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionReadRequest {
    pub session_id: String,
    /// Lines of scrollback above the screen to include. Default 200.
    #[serde(default)]
    pub lines: Option<u32>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionActionRequest {
    pub session_id: String,
    /// commit, commit_push, pull_request, review, fix_comments, conflicts or recap.
    pub action: String,
}

#[derive(Debug, Serialize)]
pub struct SessionActionOut {
    pub session_id: String,
    pub action: String,
    /// What was typed into the agent.
    pub prompt: String,
}

fn default_true() -> bool {
    true
}

#[derive(Debug, Serialize)]
pub struct SessionHostOut {
    pub machine_id: String,
    pub machine: String,
    /// The Muxin agent's version there, once it's set up.
    pub agent: Option<String>,
    /// Agent CLIs found on the machine.
    pub agents: Vec<String>,
    pub error: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct SessionsOut {
    pub sessions: Vec<SessionInfo>,
    pub machines: Vec<SessionHostOut>,
}

#[derive(Debug, Serialize)]
pub struct SessionReadOut {
    pub session_id: String,
    pub status: String,
    pub exit_code: Option<i32>,
    pub busy: bool,
    /// The screen and recent scrollback as plain text.
    pub text: String,
}

#[derive(Debug, Serialize)]
pub struct SessionDoneOut {
    pub session_id: String,
    pub done: String,
}

fn session_error(message: String) -> ApiError {
    let m = message.to_ascii_lowercase();
    let code = if m.contains("no machine") || m.contains("no session") {
        "not_found"
    } else if m.contains("unreachable") || m.contains("timed out") || m.contains("connection refused") || m.contains("no route to host") {
        "unreachable"
    } else if m.contains("isn't a session id") || m.contains("unknown agent") || m.contains("isn't a folder") || m.contains("isn't a session action") || m.contains("is a shell") {
        "invalid"
    } else {
        "operation_failed"
    };
    let mut err = ApiError::new(code, message);
    if code == "unreachable" {
        err = err.with_hint("The machine didn't answer over ssh. Check that `ssh <host>` works without a password prompt.");
    }
    err
}

/// Machines to look at: one, or every machine that can be reached.
fn session_machines(engine: &Arc<Engine>, only: Option<&str>) -> ApiResult<Vec<Machine>> {
    let s = engine.current();
    match only {
        Some(id) => Ok(vec![find_machine(&s, id)?.clone()]),
        None => Ok(s.machines.iter().filter(|m| !m.host.is_empty() && !m.is_down()).cloned().collect()),
    }
}

/// Reads git on these machines (their sessions' and workspaces' folders)
/// unless that was just now.
async fn look_at_stale_git<'a>(engine: &Arc<Engine>, machine_ids: impl Iterator<Item = &'a str>) {
    let stale = machine_ids.filter(|id| engine.git_looked_at(id).is_none_or(|t| t.elapsed() > std::time::Duration::from_secs(20)));
    futures::future::join_all(stale.map(|id| engine.look_at_git(id))).await;
}

/// Lists agent sessions, re-reading the machines first.
pub async fn sessions_list(engine: &Arc<Engine>, req: SessionListRequest) -> ApiResult<SessionsOut> {
    let machines = session_machines(engine, req.machine_id.as_deref())?;
    let found = futures::future::join_all(machines.iter().map(|m| engine.refresh_sessions(&m.id))).await;
    // What each session's work changed (git), looked at now unless it was just now.
    look_at_stale_git(engine, machines.iter().zip(&found).filter(|(_, f)| f.as_ref().is_ok_and(|f| !f.sessions.is_empty())).map(|(m, _)| m.id.as_str())).await;
    let snapshot = engine.current();
    let mut out = SessionsOut { sessions: Vec::new(), machines: Vec::new() };
    for (m, f) in machines.iter().zip(found) {
        match f {
            Ok(f) => {
                // As published: with what each one changed.
                out.sessions.extend(f.sessions.into_iter().map(|s| snapshot.sessions.iter().find(|x| x.id == s.id).cloned().unwrap_or(s)));
                out.machines.push(SessionHostOut { machine_id: m.id.clone(), machine: m.name.clone(), agent: f.agent_version, agents: f.agents, error: f.error });
            }
            Err(e) => out.machines.push(SessionHostOut { machine_id: m.id.clone(), machine: m.name.clone(), agent: None, agents: Vec::new(), error: Some(e) }),
        }
    }
    Ok(out)
}

/// Resolves "<machine>/<name>", or a bare name that's unique across the machines.
async fn resolve_session(engine: &Arc<Engine>, id: &str) -> ApiResult<SessionInfo> {
    let id = id.trim();
    if let Some((machine, name)) = id.split_once('/') {
        let m = find_machine(&engine.current(), machine)?.clone();
        let found = engine.refresh_sessions(&m.id).await.map_err(session_error)?;
        return found.sessions.into_iter().find(|s| s.name == name).ok_or_else(|| {
            ApiError::not_found(format!("No session \"{name}\" on {}.", m.name)).with_hint("List sessions with session_list (`muxin session ls`).")
        });
    }
    let all = sessions_list(engine, SessionListRequest::default()).await?;
    let matches: Vec<SessionInfo> = all.sessions.into_iter().filter(|s| s.name == id).collect();
    match matches.len() {
        1 => Ok(matches.into_iter().next().unwrap()),
        0 => Err(ApiError::not_found(format!("No session \"{id}\".")).with_hint("Session ids look like <machine-id>/<name>; list them with session_list (`muxin session ls`).")),
        _ => Err(ApiError::invalid(format!("\"{id}\" is on more than one machine; use <machine-id>/{id}."))),
    }
}

pub async fn session_start(engine: &Arc<Engine>, req: SessionStartRequest) -> ApiResult<SessionInfo> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    if sessions::agent(&req.agent).is_none() {
        let ids: Vec<&str> = sessions::AGENTS.iter().map(|a| a.id).collect();
        return Err(ApiError::invalid(format!("Unknown agent \"{}\".", req.agent)).with_hint(format!("Use one of: {}.", ids.join(", "))));
    }
    engine
        .start_session(StartSession {
            machine_id: m.id,
            agent: req.agent.to_ascii_lowercase(),
            cwd: req.cwd.unwrap_or_default(),
            title: req.title,
            prompt: req.prompt,
            cols: HEADLESS_COLS,
            rows: HEADLESS_ROWS,
            // Only the app hosts terminals for sessions without the agent.
            direct: false,
            command: None,
            typed: None,
        })
        .await
        .map_err(session_error)
}

/// Asks a session's agent to commit, open a pull request, review, ...: types
/// that action's prompt (the user's, else Muxin's) into it.
pub async fn session_action(engine: &Arc<Engine>, req: SessionActionRequest) -> ApiResult<SessionActionOut> {
    let s = resolve_session(engine, &req.session_id).await?;
    let action = req.action.trim().to_string();
    let prompt = engine.session_action(&s.id, &action).await.map_err(session_error)?;
    Ok(SessionActionOut { session_id: s.id, action, prompt })
}

pub async fn session_send(engine: &Arc<Engine>, req: SessionSendRequest) -> ApiResult<SessionDoneOut> {
    if req.text.is_empty() && !req.enter {
        return Err(ApiError::invalid("Nothing to send: text is empty and enter is false."));
    }
    let s = resolve_session(engine, &req.session_id).await?;
    if s.status != "running" {
        return Err(ApiError::invalid(format!("{} has exited.", s.id)).with_hint("Restart it with session_restart (`muxin session restart`)."));
    }
    engine.control_session(&s.id, Control::Send { text: &req.text, enter: req.enter }).await.map_err(session_error)?;
    Ok(SessionDoneOut { session_id: s.id, done: "sent".into() })
}

pub async fn session_read(engine: &Arc<Engine>, req: SessionReadRequest) -> ApiResult<SessionReadOut> {
    let s = resolve_session(engine, &req.session_id).await?;
    let lines = req.lines.unwrap_or(READ_DEFAULT_LINES);
    let text = engine.control_session(&s.id, Control::Read { lines }).await.map_err(session_error)?;
    Ok(SessionReadOut { session_id: s.id, status: s.status, exit_code: s.exit_code, busy: s.busy, text })
}

/// What a session is waiting for: a choice (with the keys that pick each
/// option) or, when it's simply done, the end of what it said.
pub async fn session_question(engine: &Arc<Engine>, req: SessionRequest) -> ApiResult<crate::fleet::sessions::question::Question> {
    let s = resolve_session(engine, &req.session_id).await?;
    if s.status != "running" {
        return Err(ApiError::invalid(format!("{} has exited.", s.id)));
    }
    engine.session_question(&s.id).await.map_err(session_error)
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionAnswerRequest {
    pub session_id: String,
    /// One of session_question's options, by its key ("1", "2", or "#1" for a menu without numbers).
    pub choice: String,
}

/// Picks one of a waiting session's choices, as session_question listed them.
pub async fn session_answer(engine: &Arc<Engine>, req: SessionAnswerRequest) -> ApiResult<SessionDoneOut> {
    let s = resolve_session(engine, &req.session_id).await?;
    let q = engine.session_question(&s.id).await.map_err(session_error)?;
    if !q.options.iter().any(|o| o.key == req.choice) {
        let keys: Vec<String> = q.options.iter().map(|o| format!("{} ({})", o.key, o.label)).collect();
        return Err(ApiError::invalid(if keys.is_empty() { format!("{} isn't asking to choose anything right now.", s.id) } else { format!("No choice \"{}\": it offers {}.", req.choice, keys.join(", ")) }));
    }
    engine.answer_session(&s.id, &req.choice, q.selected.as_deref(), q.confirm).await.map_err(session_error)?;
    Ok(SessionDoneOut { session_id: s.id, done: "answered".into() })
}

pub async fn session_stop(engine: &Arc<Engine>, req: SessionRequest) -> ApiResult<SessionDoneOut> {
    let s = resolve_session(engine, &req.session_id).await?;
    engine.control_session(&s.id, Control::Stop).await.map_err(session_error)?;
    Ok(SessionDoneOut { session_id: s.id, done: "stopped".into() })
}

pub async fn session_restart(engine: &Arc<Engine>, req: SessionRequest) -> ApiResult<SessionDoneOut> {
    let s = resolve_session(engine, &req.session_id).await?;
    engine.control_session(&s.id, Control::Restart).await.map_err(session_error)?;
    Ok(SessionDoneOut { session_id: s.id, done: "restarted".into() })
}

pub async fn session_rename(engine: &Arc<Engine>, req: SessionRenameRequest) -> ApiResult<SessionInfo> {
    let s = resolve_session(engine, &req.session_id).await?;
    engine.rename_session(&s.id, &req.title).await.map_err(session_error)
}

/// Hands a session's work (or a box's) to another agent: a note in its folder
/// from the conversation so far, and the new agent started there on it.
pub async fn session_handoff(engine: &Arc<Engine>, req: SessionHandoffRequest) -> ApiResult<sessions::handoff::HandedOff> {
    let id = match engine.find_box(&req.session_id) {
        Ok(b) => b.id,
        Err(_) => resolve_session(engine, &req.session_id).await?.id,
    };
    engine.handoff_session(&id, &req.agent, req.keep, req.machine_id.as_deref()).await.map_err(session_error)
}

/// The program and arguments that attach this terminal to a session.
pub async fn session_attach(engine: &Arc<Engine>, req: SessionRequest) -> ApiResult<sessions::AttachCommand> {
    let s = resolve_session(engine, &req.session_id).await?;
    engine.attach_command(&s.id).map_err(session_error)
}

// ---------------------------------------------------------------------------
// Boxes: a task an agent works on in a container of its own

use crate::fleet::boxes::{BoxInfo, CreateBox};

fn box_error(message: String) -> ApiError {
    let m = message.to_ascii_lowercase();
    let code = if m.contains("no box called") || m.contains("no machine called") || m.contains("isn't in muxin") || m.contains("there's no box") {
        "not_found"
    } else if m.contains("unreachable") || m.contains("timed out") || m.contains("connection refused") || m.contains("no route to host") {
        "unreachable"
    } else if m.contains("can't run") || m.contains("isn't a repository") || m.contains("isn't a valid git") || m.contains("doesn't make boxes") {
        "invalid"
    } else {
        "operation_failed"
    };
    ApiError::new(code, message)
}

#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct BoxListRequest {
    /// Only this machine's boxes.
    pub machine_id: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct BoxesOut {
    pub boxes: Vec<BoxInfo>,
    /// Machines that couldn't be asked, and why.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub errors: Vec<SessionHostOut>,
}

/// Lists boxes, asking the machines first.
pub async fn box_list(engine: &Arc<Engine>, req: BoxListRequest) -> ApiResult<BoxesOut> {
    let machines = session_machines(engine, req.machine_id.as_deref())?;
    let found = futures::future::join_all(machines.iter().map(|m| engine.refresh_sessions(&m.id))).await;
    look_at_stale_git(engine, machines.iter().zip(&found).filter(|(_, f)| f.as_ref().is_ok_and(|f| !f.boxes.is_empty())).map(|(m, _)| m.id.as_str())).await;
    let errors = machines
        .iter()
        .zip(&found)
        .filter_map(|(m, f)| {
            let error = match f {
                Ok(f) => f.error.clone()?,
                Err(e) => e.clone(),
            };
            Some(SessionHostOut { machine_id: m.id.clone(), machine: m.name.clone(), agent: None, agents: Vec::new(), error: Some(error) })
        })
        .collect();
    let ids: Vec<&str> = machines.iter().map(|m| m.id.as_str()).collect();
    let boxes = engine.boxes().into_iter().filter(|b| ids.contains(&b.machine_id.as_str())).collect();
    Ok(BoxesOut { boxes, errors })
}

/// A box by id, asking the machines when this process hasn't seen it yet.
async fn resolve_box(engine: &Arc<Engine>, id: &str) -> ApiResult<BoxInfo> {
    if let Ok(b) = engine.find_box(id) {
        return Ok(b);
    }
    box_list(engine, BoxListRequest::default()).await?;
    engine.find_box(id).map_err(|e| box_error(e).with_hint("List boxes with box_list (`muxin box ls`)."))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BoxCreateRequest {
    /// "owner/name" on GitHub, or a git URL.
    pub repo: String,
    /// What the agent is asked to do.
    #[serde(default)]
    pub prompt: String,
    /// claude (default), codex, amp, opencode, gemini or pi.
    #[serde(default)]
    pub agent: Option<String>,
    /// Where it runs; default: the online machine with Docker and the most free memory.
    #[serde(default)]
    pub machine_id: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    /// The branch it works on; default "box/<name>".
    #[serde(default)]
    pub branch: Option<String>,
    /// What it starts from: a branch, tag, commit or "pull/<n>/head"; default the default branch.
    #[serde(default, rename = "ref")]
    pub git_ref: Option<String>,
    #[serde(default)]
    pub cpus: Option<u32>,
    #[serde(default)]
    pub memory_gb: Option<u32>,
    /// Pause after this many minutes without output from its agent (default 15; 0 never).
    #[serde(default)]
    pub idle_minutes: Option<u32>,
    #[serde(default = "yes")]
    pub wait: bool,
    #[serde(default)]
    pub timeout_secs: Option<u64>,
}

#[derive(Debug, Serialize)]
pub struct BoxCreatedOut {
    pub box_id: String,
    /// The box once it's made.
    #[serde(rename = "box", skip_serializing_if = "Option::is_none")]
    pub info: Option<BoxInfo>,
    pub operation: OperationOut,
    pub finished: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next: Option<String>,
}

/// Makes a box and starts its agent on the task.
pub async fn box_create(engine: &Arc<Engine>, req: BoxCreateRequest, surface: Surface, on_line: impl FnMut(&str)) -> ApiResult<BoxCreatedOut> {
    let s = freshen(engine).await;
    // A machine named here must be known; the engine checks the rest.
    let machine = match req.machine_id.as_deref().filter(|m| !m.trim().is_empty()) {
        Some(m) => Some(find_machine(&s, m)?.id.clone()),
        None => None,
    };
    // Whether a machine is online and has Docker takes a check.
    let unchecked = s.machines.iter().any(|m| m.probe.is_none() && machine.as_ref().is_none_or(|id| *id == m.id));
    if unchecked {
        engine.run_check(machine.clone().map(|id| vec![id])).await;
    }
    let create = CreateBox {
        repo: req.repo,
        prompt: req.prompt,
        agent: req.agent.unwrap_or_default(),
        machine,
        name: req.name,
        branch: req.branch,
        git_ref: req.git_ref,
        cpus: req.cpus,
        memory_gb: req.memory_gb,
        idle_minutes: req.idle_minutes,
    };
    let (op, id) = engine.box_create(create).map_err(box_error)?;
    let done = finish_action(engine, op, req.wait, req.timeout_secs.unwrap_or(900), DEFAULT_TAIL, None, Vec::new(), surface, on_line).await?;
    let next = done.next.or_else(|| {
        done.finished.then(|| {
            surface.say(
                format!("Its agent is working. Follow it with session_read(session_id) or box_list; ask it more with box_send(\"{id}\", text)."),
                format!("Its agent is working. Watch it with `muxin box attach {id}`; ask it more with `muxin box send {id} \"...\"`."),
            )
        })
    });
    Ok(BoxCreatedOut { info: engine.find_box(&id).ok(), box_id: id, operation: done.operation, finished: done.finished, next })
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BoxRequest {
    /// "box-ab12cd".
    pub box_id: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BoxSendRequest {
    pub box_id: String,
    /// What to ask its agent. Empty: just start it again.
    #[serde(default)]
    pub text: Option<String>,
}

/// Asks a box's agent something, starting the box again when it's paused.
pub async fn box_send(engine: &Arc<Engine>, req: BoxSendRequest) -> ApiResult<BoxInfo> {
    let b = resolve_box(engine, &req.box_id).await?;
    engine.box_send(&b.id, req.text.as_deref()).await.map_err(box_error)
}

pub async fn box_pause(engine: &Arc<Engine>, req: BoxRequest) -> ApiResult<BoxInfo> {
    let b = resolve_box(engine, &req.box_id).await?;
    engine.box_pause(&b.id).await.map_err(box_error)
}

pub async fn box_destroy(engine: &Arc<Engine>, req: BoxRequest) -> ApiResult<BoxInfo> {
    let b = resolve_box(engine, &req.box_id).await?;
    engine.box_destroy(&b.id).await.map_err(box_error)
}

/// The program and arguments that open a shell in a box in this terminal
/// (starting the box first when it's paused).
pub async fn box_shell(engine: &Arc<Engine>, req: BoxRequest) -> ApiResult<sessions::AttachCommand> {
    let b = resolve_box(engine, &req.box_id).await?;
    let s = engine.box_shell(&b.id, HEADLESS_COLS, HEADLESS_ROWS).await.map_err(box_error)?;
    engine.attach_command(&s.id).map_err(session_error)
}

/// The program and arguments that attach this terminal to a box's agent
/// (starting the box first when it's paused).
pub async fn box_attach(engine: &Arc<Engine>, req: BoxRequest) -> ApiResult<sessions::AttachCommand> {
    let mut b = resolve_box(engine, &req.box_id).await?;
    if b.session_id.is_none() {
        b = engine.box_send(&b.id, None).await.map_err(box_error)?;
    }
    let session = b.session_id.ok_or_else(|| ApiError::new("operation_failed", format!("{}'s agent didn't start.", b.id)))?;
    engine.attach_command(&session).map_err(session_error)
}

// ---------------------------------------------------------------------------
// GitHub: your repositories, issues and pull requests; code on your machines

use crate::fleet::model::Checkout;
use crate::github::hub;

fn github_error(message: String) -> ApiError {
    let lower = message.to_ascii_lowercase();
    let mut err = ApiError::new("github", message);
    if lower.contains("no github token") || lower.contains("rejected the token") || lower.contains("bad credentials") {
        err = err.with_hint("Sign in to GitHub: `gh auth login` (Muxin uses the GitHub CLI's login), or set GITHUB_TOKEN.");
    }
    err
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RepoRequest {
    /// "owner/name" or a GitHub URL.
    pub repo: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ItemRequest {
    /// An issue or pull request: its URL, or "owner/name#123".
    pub reference: String,
}

#[derive(Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CheckoutsRequest {
    /// Only this machine.
    #[serde(default)]
    pub machine_id: Option<String>,
    /// Only checkouts of this repository ("owner/name").
    #[serde(default)]
    pub repo: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GitRequest {
    pub machine_id: String,
    /// The checkout's folder on that machine.
    pub path: String,
    /// "fetch", "pull" (fast-forward only) or "push".
    pub action: String,
}

#[derive(Debug, Serialize)]
pub struct RepoOut {
    pub repo: hub::Repo,
    pub issues: Vec<hub::Item>,
    pub pulls: Vec<hub::Item>,
    pub runs: Vec<hub::Run>,
    /// Where it's checked out on your machines.
    pub checkouts: Vec<Checkout>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FavoriteRequest {
    /// "owner/name" or a GitHub URL.
    pub repo: String,
    /// false removes it from the favorites.
    #[serde(default = "yes")]
    pub favorite: bool,
}

#[derive(Debug, Serialize)]
pub struct AccountsOut {
    /// The account Muxin uses now: for the GitHub page, managing runners,
    /// and cloning into workspaces.
    pub using: Option<String>,
    /// "gh", or the environment variable the token came from (then switching
    /// between the GitHub CLI's accounts isn't possible); "" when none was found.
    pub token_source: String,
    /// When Muxin uses another machine's GitHub CLI login: that machine's id.
    pub machine_id: Option<String>,
    /// The accounts the GitHub CLI here is signed in to.
    pub accounts: Vec<crate::github::Account>,
    /// Other machines' GitHub CLI logins, usable instead.
    pub machines: Vec<MachineAccount>,
    /// The permissions (OAuth scopes) of the login in use; null when GitHub doesn't say.
    /// Watching an organization's runners needs "admin:org".
    pub scopes: Option<Vec<String>>,
    /// The organizations the login in use belongs to (candidates for github_scopes).
    pub orgs: Vec<String>,
    /// What to run to give the login the permission to read organization runners, when it lacks it.
    pub grant_command: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct MachineAccount {
    pub machine_id: String,
    pub machine: String,
    pub login: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct UseAccountRequest {
    /// A login the GitHub CLI here is signed in to; with machine_id, optional.
    #[serde(default)]
    pub login: String,
    /// Use this machine's GitHub CLI login instead of this computer's.
    #[serde(default)]
    pub machine_id: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct FavoritesOut {
    pub favorites: Vec<String>,
}

#[derive(Debug, Serialize)]
pub struct GitOut {
    pub output: String,
}

pub async fn github_inbox(engine: &Arc<Engine>) -> ApiResult<hub::Inbox> {
    if engine.is_demo() {
        return Ok(crate::demo::github::inbox());
    }
    let settings = engine.settings().github;
    engine.github().inbox(&settings).await.map_err(github_error)
}

/// Your repositories, favorites first, then most recently pushed.
pub async fn github_repos(engine: &Arc<Engine>) -> ApiResult<Vec<hub::Repo>> {
    let settings = engine.settings();
    let mut repos = if engine.is_demo() { crate::demo::github::repos() } else { engine.github().my_repos(&settings.github).await.map_err(github_error)? };
    for r in &mut repos {
        r.favorite = settings.favorite_repos.iter().any(|f| f.eq_ignore_ascii_case(&r.full_name));
    }
    repos.sort_by_key(|r| !r.favorite);
    Ok(repos)
}

/// The GitHub CLI's accounts, and which one Muxin uses (read fresh, so a
/// permission granted a moment ago shows).
pub async fn github_accounts(engine: &Arc<Engine>) -> ApiResult<AccountsOut> {
    if engine.is_demo() {
        let login = crate::demo::github::LOGIN.to_string();
        return Ok(AccountsOut {
            using: Some(login.clone()),
            token_source: "gh".into(),
            machine_id: None,
            accounts: vec![crate::github::Account { login, gh_active: true, ok: true, scopes: "repo, read:org, admin:org".into() }],
            machines: Vec::new(),
            scopes: Some(vec!["repo".into(), "read:org".into(), "admin:org".into()]),
            orgs: vec!["acme".into()],
            grant_command: None,
        });
    }
    let settings = engine.settings().github;
    let gh = engine.github();
    gh.reload_login();
    // Machines whose GitHub CLI login isn't known yet (a fresh CLI run) are asked.
    let unknown: Vec<String> = engine
        .current()
        .machines
        .iter()
        .filter(|m| m.host != "local" && m.gh.is_none() && m.status == "online")
        .map(|m| m.id.clone())
        .collect();
    let (accounts, viewer, orgs, _) = futures::join!(
        gh.accounts(&settings),
        gh.viewer(&settings),
        gh.my_orgs(&settings),
        futures::future::join_all(unknown.iter().map(|id| engine.refresh_sessions(id)))
    );
    let scopes = gh.scopes();
    let grant_command = scopes
        .as_ref()
        .filter(|s| !s.iter().any(|x| x == "admin:org"))
        .map(|_| format!("gh auth refresh -h {} -s admin:org", crate::fleet::workspaces::github_web_host(&settings.api_url)));
    let token_source = gh.token_source().await;
    let snapshot = engine.current();
    let machines: Vec<MachineAccount> = snapshot
        .machines
        .iter()
        .filter(|m| m.host != "local")
        .filter_map(|m| {
            let g = m.gh.as_ref().filter(|g| g.logged_in)?;
            Some(MachineAccount { machine_id: m.id.clone(), machine: m.name.clone(), login: g.account.clone()? })
        })
        .collect();
    let accounts = match accounts {
        Ok(a) => a,
        // A token from the environment, or a machine's login, works without the CLI here.
        Err(_) if (!token_source.is_empty() && token_source != "gh") || !machines.is_empty() => Vec::new(),
        Err(e) => return Err(ApiError::new("github", e).with_hint("gh auth login")),
    };
    let machine_id = Some(settings.account_machine).filter(|m| !m.is_empty());
    Ok(AccountsOut { using: viewer.ok().map(|v| v.login), token_source, machine_id, accounts, machines, scopes, orgs: orgs.unwrap_or_default(), grant_command })
}

/// Switches Muxin to another of the GitHub CLI's accounts (not the CLI's own active account).
pub async fn github_use_account(engine: &Arc<Engine>, req: UseAccountRequest) -> ApiResult<AccountsOut> {
    let login = req.login.trim().trim_start_matches('@').to_string();
    let mut settings = engine.settings();
    let source = engine.github().token_source().await;
    if !source.is_empty() && source != "gh" {
        return Err(ApiError::invalid(format!("Muxin is using the token in ${source}. Unset it to switch between the GitHub CLI's accounts.")));
    }
    let previous = settings.clone();
    if let Some(id) = req.machine_id.as_deref().filter(|m| !m.is_empty()) {
        let m = find_machine(&engine.current(), id)?.clone();
        if m.gh.is_none() && m.host != "local" {
            let _ = engine.refresh_sessions(&m.id).await;
        }
    }
    let snapshot = engine.current();
    let machine = match req.machine_id.as_deref().filter(|m| !m.is_empty()) {
        Some(id) => Some(find_machine(&snapshot, id)?).filter(|m| m.host != "local"),
        None => None,
    };
    match machine {
        Some(m) => {
            let Some(account) = m.gh.as_ref().filter(|g| g.logged_in).and_then(|g| g.account.clone()) else {
                return Err(ApiError::not_found(format!("The GitHub CLI on {} isn't signed in.", m.name)).with_hint("Sign it in from the machine's page, or run `gh auth login` there."));
            };
            if !login.is_empty() && !account.eq_ignore_ascii_case(&login) {
                return Err(ApiError::invalid(format!("{} is signed in to GitHub as {account}, not {login}.", m.name)));
            }
            settings.github.account = account;
            settings.github.account_machine = m.id.clone();
        }
        None => {
            let accounts = engine.github().accounts(&settings.github).await.map_err(|e| ApiError::new("github", e).with_hint("gh auth login"))?;
            let Some(account) = accounts.iter().find(|a| a.login.eq_ignore_ascii_case(&login)) else {
                let known: Vec<&str> = accounts.iter().map(|a| a.login.as_str()).collect();
                return Err(ApiError::not_found(format!("The GitHub CLI isn't signed in to \"{login}\" (it has: {}).", known.join(", "))).with_hint("gh auth login"));
            };
            settings.github.account = account.login.clone();
            settings.github.account_machine = String::new();
        }
    }
    engine.update_settings(settings).map_err(ApiError::invalid)?;
    // Make sure GitHub takes it; otherwise stay on the previous login.
    let wanted = engine.settings().github.account;
    let out = github_accounts(engine).await?;
    match out.using.as_deref() {
        Some(u) if u.eq_ignore_ascii_case(&wanted) => Ok(out),
        Some(u) => {
            let _ = engine.update_settings(previous);
            Err(ApiError::invalid(format!("That login turned out to be {u}, not {wanted}, so Muxin kept the previous one. Check which account gh is signed in to there.")))
        }
        None => {
            let _ = engine.update_settings(previous);
            Err(ApiError::new("github", "GitHub didn't accept that login, so Muxin kept the previous one.").with_hint("gh auth login"))
        }
    }
}

/// Adds a repository to the favorites, or removes it.
pub fn github_favorite(engine: &Arc<Engine>, req: FavoriteRequest) -> ApiResult<FavoritesOut> {
    let name = hub::repo_name(&req.repo).ok_or_else(|| ApiError::invalid(format!("\"{}\" isn't a GitHub repository; use owner/name.", req.repo)))?;
    let mut settings = engine.settings();
    settings.favorite_repos.retain(|f| !f.eq_ignore_ascii_case(&name));
    if req.favorite {
        settings.favorite_repos.push(name);
    }
    let saved = engine.update_settings(settings).map_err(ApiError::invalid)?;
    Ok(FavoritesOut { favorites: saved.favorite_repos })
}

pub async fn github_repo(engine: &Arc<Engine>, req: RepoRequest) -> ApiResult<RepoOut> {
    let name = hub::repo_name(&req.repo).ok_or_else(|| ApiError::invalid(format!("\"{}\" isn't a GitHub repository; use owner/name.", req.repo)))?;
    if engine.is_demo() {
        let repo = crate::demo::github::repo_named(&name).ok_or_else(|| ApiError::new("not_found", format!("No repository called {name} in the demo.")))?;
        let items = crate::demo::github::repo_items(&name);
        return Ok(RepoOut { repo, issues: items.issues, pulls: items.pulls, runs: crate::demo::github::runs(&name), checkouts: Vec::new() });
    }
    let settings = engine.settings().github;
    let gh = engine.github();
    let (repo, items, runs) = futures::join!(gh.repo(&settings, &name), gh.repo_items(&settings, &name), gh.repo_runs(&settings, &name));
    let mut repo = repo.map_err(github_error)?;
    repo.favorite = engine.settings().favorite_repos.iter().any(|f| f.eq_ignore_ascii_case(&repo.full_name));
    let items = items.map_err(github_error)?;
    let checkouts = engine.current().checkouts.iter().filter(|c| c.repo.as_deref().is_some_and(|r| r.eq_ignore_ascii_case(&name))).cloned().collect();
    Ok(RepoOut { repo, issues: items.issues, pulls: items.pulls, runs: runs.unwrap_or_default(), checkouts })
}

pub async fn github_item(engine: &Arc<Engine>, req: ItemRequest) -> ApiResult<hub::Detail> {
    let (repo, number) = hub::issue_ref(&req.reference)
        .ok_or_else(|| ApiError::invalid(format!("\"{}\" isn't an issue or pull request; use its URL or owner/name#123.", req.reference)))?;
    if engine.is_demo() {
        return crate::demo::github::detail(&repo, number).ok_or_else(|| ApiError::new("not_found", format!("No {repo}#{number} in the demo.")));
    }
    let settings = engine.settings().github;
    engine.github().detail(&settings, &repo, number).await.map_err(github_error)
}

#[derive(Debug, Serialize)]
pub struct GitSetupOut {
    pub machine_id: String,
    #[serde(flatten)]
    pub setup: crate::fleet::code::GitSetup,
    /// git has a name and email to commit with.
    pub can_commit: bool,
    /// How a push over HTTPS gets a GitHub login: "gh" (the machine's GitHub CLI),
    /// "other" (another credential helper or SSH keys; may work), or "none".
    pub push: String,
    /// The machine's GitHub CLI account, when it's signed in.
    pub gh_account: Option<String>,
    /// What `identity: true` sets: the GitHub account's name and its private noreply email.
    pub suggested_name: Option<String>,
    pub suggested_email: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GitStatusRequest {
    pub machine_id: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GitSetupRequest {
    pub machine_id: String,
    /// Set git's name and email (globally on the machine): the ones given, else the GitHub account's.
    #[serde(default)]
    pub identity: bool,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub email: Option<String>,
    /// Make git use the machine's GitHub CLI login for github.com (`gh auth setup-git`).
    #[serde(default)]
    pub credentials: bool,
}

/// The machine, with its GitHub CLI state known (asked for when it isn't yet).
///
/// Only "signed in" is taken as known. A machine with no sessions isn't re-read
/// on the timer, so what it said before the user signed in on it is still there
/// when they come back: asking again is what sees the sign-in. Asked now, not
/// when the timer would look at its CLIs again (every 10 minutes).
async fn machine_with_gh(engine: &Arc<Engine>, machine_id: &str) -> ApiResult<crate::fleet::model::Machine> {
    let m = find_machine(&engine.current(), machine_id)?.clone();
    if gh_answer_stands(&m.gh) {
        return Ok(m);
    }
    let _ = engine.refresh_tools(&m.id).await;
    Ok(find_machine(&engine.current(), &m.id)?.clone())
}

/// Whether a machine's GitHub CLI answer stands as it is (see `machine_with_gh`).
fn gh_answer_stands(gh: &Option<GhCli>) -> bool {
    gh.as_ref().is_some_and(|g| g.logged_in)
}

async fn git_out(engine: &Arc<Engine>, m: &crate::fleet::model::Machine, setup: crate::fleet::code::GitSetup) -> GitSetupOut {
    let gh_account = m.gh.as_ref().filter(|g| g.logged_in).and_then(|g| g.account.clone());
    let settings = engine.settings().github;
    let login = match gh_account.clone() {
        Some(l) => Some(l),
        None => engine.github().viewer(&settings).await.ok().map(|v| v.login),
    };
    let suggested = match login {
        Some(l) => engine.github().commit_identity(&settings, &l).await.ok(),
        None => None,
    };
    let push = if setup.uses_gh && gh_account.is_some() {
        "gh"
    } else if !setup.helpers.is_empty() || !setup.ssh_keys.is_empty() {
        "other"
    } else {
        "none"
    };
    GitSetupOut {
        machine_id: m.id.clone(),
        can_commit: setup.name.is_some() && setup.email.is_some(),
        push: push.into(),
        gh_account,
        suggested_name: suggested.as_ref().map(|s| s.0.clone()),
        suggested_email: suggested.map(|s| s.1),
        setup,
    }
}

/// Whether git on a machine can commit and push to GitHub.
pub async fn git_status(engine: &Arc<Engine>, machine_id: &str) -> ApiResult<GitSetupOut> {
    let m = machine_with_gh(engine, machine_id).await?;
    let setup = engine.git_setup_status(&m.id).await.map_err(|e| ApiError::new("operation_failed", e))?;
    Ok(git_out(engine, &m, setup).await)
}

/// Sets up git on a machine: identity and/or GitHub credentials through the GitHub CLI.
pub async fn git_setup(engine: &Arc<Engine>, req: GitSetupRequest) -> ApiResult<GitSetupOut> {
    if !req.identity && !req.credentials {
        return Err(ApiError::invalid("Nothing to set up: pass identity and/or credentials."));
    }
    let m = machine_with_gh(engine, &req.machine_id).await?;
    let identity = if req.identity {
        let (name, email) = match (req.name.clone(), req.email.clone()) {
            (Some(n), Some(e)) => (n, e),
            (n, e) => {
                let current = git_out(engine, &m, Default::default()).await;
                match (n.or(current.suggested_name), e.or(current.suggested_email)) {
                    (Some(n), Some(e)) => (n, e),
                    _ => return Err(ApiError::invalid("Couldn't find a GitHub name and email to use; pass name and email.")),
                }
            }
        };
        Some((name, email))
    } else {
        None
    };
    let setup = engine.git_setup_apply(&m.id, identity, req.credentials).await.map_err(|e| {
        let err = ApiError::new("operation_failed", e.clone());
        if e.contains("Sign in to the GitHub CLI") { err.with_hint("gh auth login") } else { err }
    })?;
    Ok(git_out(engine, &m, setup).await)
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DirectRequest {
    pub machine_id: String,
    /// true pairs and connects directly; false goes back to ssh only.
    pub enabled: bool,
}

/// How Muxin reaches a machine: directly (QUIC), a live ssh link, or none.
pub async fn machine_connection(engine: &Arc<Engine>, machine_id: &str) -> ApiResult<crate::fleet::connection::Connection> {
    let m = find_machine(&engine.current(), machine_id)?.clone();
    engine.connection(&m.id).await.map_err(|e| ApiError::new("unreachable", e))
}

/// Turns direct (QUIC) connections to a machine on or off.
pub async fn set_direct(engine: &Arc<Engine>, req: DirectRequest) -> ApiResult<crate::fleet::connection::Connection> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.set_direct(&m.id, req.enabled).await.map_err(|e| ApiError::new("operation_failed", e))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DesktopInputRequest {
    pub machine_id: String,
    /// One of the machine's displays (desktop_displays); default: the whole desktop or the main display.
    #[serde(default)]
    pub display: Option<String>,
    pub events: Vec<crate::fleet::desktop::DesktopEvent>,
}

/// What's on a machine's screen, or one of its displays (a JPEG, plus its size).
pub async fn desktop_screenshot(engine: &Arc<Engine>, machine_id: &str, display: Option<&str>) -> ApiResult<crate::fleet::desktop::Screenshot> {
    let m = find_machine(&engine.current(), machine_id)?.clone();
    engine.desktop_screenshot(&m.id, display).await.map_err(|e| ApiError::new("operation_failed", e))
}

/// Moves, clicks, scrolls and types on a machine's desktop.
pub async fn desktop_input(engine: &Arc<Engine>, req: DesktopInputRequest) -> ApiResult<serde_json::Value> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let n = engine.desktop_input(&m.id, req.display.as_deref(), &req.events).await.map_err(|e| ApiError::new("operation_failed", e))?;
    Ok(serde_json::json!({ "machine_id": m.id, "events": n, "next": "Take a desktop_screenshot to see the result." }))
}

/// A machine's monitors, virtual ones included.
pub async fn desktop_displays(engine: &Arc<Engine>, req: MachineRequest) -> ApiResult<Vec<crate::fleet::model::DisplayInfo>> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.displays(&m.id).await.map_err(|e| ApiError::new("operation_failed", e))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AddDisplayRequest {
    pub machine_id: String,
    /// Default 1920×1080.
    #[serde(default)]
    pub width: Option<u32>,
    #[serde(default)]
    pub height: Option<u32>,
    #[serde(default)]
    pub name: Option<String>,
}

/// Agents don't type the user's password: the app asks for it.
fn display_error(e: crate::fleet::desktop::AddDisplayError) -> ApiError {
    match e {
        crate::fleet::desktop::AddDisplayError::NeedsPassword(why) => ApiError::invalid(why)
            .with_hint("Ask the user to add or remove this monitor from the Muxin app (the machine's desktop › Add monitor); it asks for their password there."),
        crate::fleet::desktop::AddDisplayError::Failed(why) => ApiError::new("operation_failed", why),
    }
}

/// Adds a virtual monitor to a machine's desktop.
pub async fn desktop_add_display(engine: &Arc<Engine>, req: AddDisplayRequest) -> ApiResult<crate::fleet::model::DisplayInfo> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    // The main monitor's size unless told otherwise.
    let known = if m.displays.is_empty() && (req.width.is_none() || req.height.is_none()) { engine.displays(&m.id).await.unwrap_or_default() } else { m.displays.clone() };
    let screens: Vec<_> = known.iter().filter(|d| d.id != "all").collect();
    let main = screens.iter().find(|d| d.main).or(screens.first()).map(|d| (d.width.round() as u32, d.height.round() as u32)).unwrap_or((1920, 1080));
    let (w, h) = (req.width.unwrap_or(main.0), req.height.unwrap_or(main.1));
    engine.add_display(&m.id, w, h, req.name.as_deref()).await.map_err(display_error)
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SetDisplayRequest {
    pub machine_id: String,
    pub display: String,
    pub width: Option<u32>,
    pub height: Option<u32>,
    pub scale: Option<f64>,
}

/// Sets a monitor's size (one it offers: see `modes`) or the desktop's scale on it.
pub async fn desktop_set_display(engine: &Arc<Engine>, req: SetDisplayRequest) -> ApiResult<crate::fleet::model::DisplayInfo> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let size = req.width.zip(req.height);
    if size.is_none() && req.scale.is_none() {
        return Err(ApiError::new("invalid", "Pass width and height, or scale."));
    }
    engine.set_display(&m.id, &req.display, size, req.scale).await.map_err(|e| ApiError::new("operation_failed", e))?;
    let shown = engine.current().machines.iter().find(|x| x.id == m.id).and_then(|x| x.displays.iter().find(|d| d.id == req.display).cloned());
    shown.ok_or_else(|| ApiError::new("not_found", format!("{} isn't one of {}'s displays now.", req.display, m.name)))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RemoveDisplayRequest {
    pub machine_id: String,
    pub display: String,
}

/// Removes a virtual monitor Muxin added.
pub async fn desktop_remove_display(engine: &Arc<Engine>, req: RemoveDisplayRequest) -> ApiResult<serde_json::Value> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.remove_display(&m.id, &req.display).await.map_err(display_error)?;
    Ok(serde_json::json!({ "machine_id": m.id, "removed": req.display }))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct LogSourcesRequest {
    pub machine_id: String,
}

/// What a machine has to read: its system log, log files, containers, services.
pub async fn log_sources(engine: &Arc<Engine>, req: LogSourcesRequest) -> ApiResult<crate::fleet::logs::LogSources> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.log_sources(&m.id).await.map_err(|e| ApiError::new("operation_failed", e))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ReadLogsRequest {
    pub machine_id: String,
    /// system, kernel, file, docker or service.
    pub kind: String,
    /// The file's path, the container's name or id, the unit (empty for the system log).
    #[serde(default)]
    pub target: String,
    /// A service of the user's own (systemctl --user).
    #[serde(default)]
    pub user: bool,
    pub lines: Option<u64>,
    pub filter: Option<String>,
}

/// A log's last lines.
pub async fn logs_read(engine: &Arc<Engine>, req: ReadLogsRequest) -> ApiResult<serde_json::Value> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let source = crate::fleet::logs::LogSource { kind: req.kind.clone(), target: req.target.clone(), user: req.user, ..Default::default() };
    let lines = engine.read_logs(&m.id, &source, req.lines.unwrap_or(200), req.filter.as_deref()).await.map_err(|e| ApiError::new("operation_failed", e))?;
    Ok(serde_json::json!({ "machine_id": m.id, "kind": req.kind, "target": req.target, "lines": lines }))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ServicesRequest {
    pub machine_id: String,
}

/// A machine's services (systemd's on Linux, Homebrew's on a Mac) and Docker containers.
pub async fn machine_services(engine: &Arc<Engine>, req: ServicesRequest) -> ApiResult<crate::fleet::services::ServiceList> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.services(&m.id, true).await.map_err(|e| ApiError::new("operation_failed", e))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ServiceActionRequest {
    pub machine_id: String,
    /// A service's or container's name (as `machine_services` lists it).
    pub name: String,
    /// start, stop, restart; enable or disable (whether a systemd service starts at boot).
    pub action: String,
    /// Look among containers only.
    #[serde(default)]
    pub container: bool,
}

/// Starts, stops or restarts a service or container.
pub async fn service_action(engine: &Arc<Engine>, req: ServiceActionRequest) -> ApiResult<serde_json::Value> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let action: &'static str = match req.action.as_str() {
        "start" => "start",
        "stop" => "stop",
        "restart" => "restart",
        "enable" => "enable",
        "disable" => "disable",
        other => return Err(ApiError::new("invalid", format!("\"{other}\" isn't an action: start, stop, restart, enable or disable."))),
    };
    let list = engine.services(&m.id, false).await.map_err(|e| ApiError::new("operation_failed", e))?;
    let wanted = req.name.trim_end_matches(".service");
    let pool: Vec<_> = if req.container { list.containers } else { list.services.into_iter().chain(list.containers).collect() };
    let service = pool
        .into_iter()
        .find(|s| s.name == wanted || s.target == req.name)
        .ok_or_else(|| ApiError::new("not_found", format!("{} has no service or container called {}.", m.name, req.name)))?;
    engine.service_action(&m.id, &service, action).await.map_err(|e| match e {
        crate::fleet::desktop::AddDisplayError::NeedsPassword(_) => {
            ApiError::new("invalid", format!("{} wants the user's password for that (sudo).", m.name)).with_hint("Do it from the Muxin app (machine › Services), which asks for it.")
        }
        crate::fleet::desktop::AddDisplayError::Failed(why) => ApiError::new("operation_failed", why),
    })?;
    Ok(serde_json::json!({ "machine_id": m.id, "name": service.name, "kind": service.kind, "action": action, "ok": true }))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DockerRunRequest {
    pub machine_id: String,
    pub image: String,
    pub name: Option<String>,
    #[serde(default)]
    pub ports: Vec<String>,
    #[serde(default)]
    pub env: Vec<String>,
    #[serde(default)]
    pub volumes: Vec<String>,
    /// no, always, unless-stopped (default), on-failure.
    pub restart: Option<String>,
    pub command: Option<String>,
    /// Wait for it to finish (default true).
    pub wait: Option<bool>,
}

/// An operation's result: waited for (up to 30 minutes) unless `wait` is off.
async fn operation_result(engine: &Arc<Engine>, op: u64, wait: bool) -> ApiResult<OperationOut> {
    let done = if wait { wait_operation(engine, op, Duration::from_secs(30 * 60), |_| {}).await } else { None };
    let o = done.or_else(|| engine.current().operations.iter().find(|o| o.id == op).cloned()).ok_or_else(|| ApiError::new("internal", "The operation went missing."))?;
    Ok(operation_out(&o, DEFAULT_TAIL))
}

/// `docker run -d` on a machine (pulling the image first if needed).
pub async fn docker_run(engine: &Arc<Engine>, req: DockerRunRequest) -> ApiResult<OperationOut> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let run = crate::fleet::services::DockerRun {
        image: req.image,
        name: req.name.unwrap_or_default(),
        ports: req.ports,
        env: req.env,
        volumes: req.volumes,
        restart: req.restart.unwrap_or_else(|| "unless-stopped".into()),
        command: req.command.unwrap_or_default(),
    };
    let op = engine.docker_run(&m.id, run).map_err(|e| ApiError::new("invalid", e))?;
    operation_result(engine, op, req.wait.unwrap_or(true)).await
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DockerPullRequest {
    pub machine_id: String,
    pub image: String,
    pub wait: Option<bool>,
}

pub async fn docker_pull(engine: &Arc<Engine>, req: DockerPullRequest) -> ApiResult<OperationOut> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let op = engine.docker_pull(&m.id, &req.image).map_err(|e| ApiError::new("invalid", e))?;
    operation_result(engine, op, req.wait.unwrap_or(true)).await
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ComposeActionRequest {
    pub machine_id: String,
    /// The project's name, as machine_services lists it.
    pub project: String,
    /// up, down, restart or pull; with `service`: start, stop or restart.
    pub action: String,
    /// One of its services, to start, stop or restart just that one.
    pub service: Option<String>,
    pub wait: Option<bool>,
}

pub async fn compose_action(engine: &Arc<Engine>, req: ComposeActionRequest) -> ApiResult<OperationOut> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let list = engine.services(&m.id, false).await.map_err(|e| ApiError::new("operation_failed", e))?;
    let project = list.compose.into_iter().find(|p| p.name == req.project).ok_or_else(|| ApiError::new("not_found", format!("{} has no Compose project called {}.", m.name, req.project)))?;
    let op = match req.service.as_deref().filter(|s| !s.is_empty()) {
        Some(service) => engine.compose_service_action(&m.id, &project, service, &req.action),
        None => engine.compose_action(&m.id, &project, &req.action),
    }
    .map_err(|e| ApiError::new("invalid", e))?;
    operation_result(engine, op, req.wait.unwrap_or(true)).await
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct UsageRequest {
    /// The last N days (default 7, at most 400).
    pub days: Option<u32>,
    /// One machine; default: every machine that's online.
    pub machine_id: Option<String>,
}

#[derive(Debug, Serialize)]
pub struct UsageModel {
    pub tool: String,
    pub model: String,
    #[serde(flatten)]
    pub tokens: crate::fleet::usage::Tokens,
    /// At the API's list price; null when the model's price isn't known.
    pub cost: Option<f64>,
}

#[derive(Debug, Serialize)]
pub struct UsageMachine {
    pub machine_id: String,
    #[serde(flatten)]
    pub tokens: crate::fleet::usage::Tokens,
    pub cost: f64,
}

#[derive(Debug, Serialize)]
pub struct UsageOut {
    pub days: u32,
    /// What it'd all cost at list prices (models without a known price left out).
    pub total_cost: f64,
    pub prices_as_of: &'static str,
    pub models: Vec<UsageModel>,
    pub machines: Vec<UsageMachine>,
    /// Machines that couldn't say, and why.
    pub errors: Vec<serde_json::Value>,
}

/// What the agent CLIs (Claude Code, Codex) used, from their own logs on
/// each machine: tokens by model and machine, and the cost at list prices.
pub async fn usage(engine: &Arc<Engine>, req: UsageRequest) -> ApiResult<UsageOut> {
    let days = req.days.unwrap_or(7).clamp(1, 400);
    let results = match &req.machine_id {
        Some(id) => {
            let m = find_machine(&engine.current(), id)?.clone();
            vec![(m.id.clone(), engine.usage(&m.id, days).await)]
        }
        None => engine.usage_all(days).await,
    };
    let mut ok = Vec::new();
    let mut errors = Vec::new();
    for (id, r) in results {
        match r {
            Ok(u) => ok.push(u),
            Err(e) => errors.push(serde_json::json!({ "machine_id": id, "error": e })),
        }
    }
    let models: Vec<UsageModel> = crate::fleet::usage::by_model(&ok).into_iter().map(|(tool, model, tokens, cost)| UsageModel { tool, model, tokens, cost }).collect();
    let machines = ok
        .iter()
        .map(|u| {
            let mut tokens = crate::fleet::usage::Tokens::default();
            let mut cost = 0.;
            for h in &u.hours {
                tokens.add(&h.tokens);
                cost += crate::fleet::usage::cost(&h.model, &h.tokens).unwrap_or(0.);
            }
            UsageMachine { machine_id: u.machine_id.clone(), tokens, cost }
        })
        .collect();
    let total_cost = models.iter().filter_map(|m| m.cost).sum();
    Ok(UsageOut { days, total_cost, prices_as_of: crate::fleet::usage::PRICES_AS_OF, models, machines, errors })
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ProcessesRequest {
    pub machine_id: String,
}

/// A machine's processes (the busiest few hundred, with CPU and memory) and its GPUs.
pub async fn machine_processes(engine: &Arc<Engine>, req: ProcessesRequest) -> ApiResult<crate::fleet::procs::ProcessList> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.processes(&m.id).await.map_err(|e| ApiError::new("operation_failed", e))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ProcessSignalRequest {
    pub machine_id: String,
    pub pid: u32,
    /// "stop" (SIGTERM, the default) or "kill" (SIGKILL).
    #[serde(default)]
    pub signal: Option<String>,
}

/// Stops (SIGTERM) or kills (SIGKILL) a process on a machine.
pub async fn process_signal(engine: &Arc<Engine>, req: ProcessSignalRequest) -> ApiResult<serde_json::Value> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let action = match req.signal.as_deref().unwrap_or("stop") {
        "kill" | "KILL" => "kill",
        "stop" | "term" | "TERM" => "stop",
        other => return Err(ApiError::invalid(format!("\"{other}\" isn't a signal: stop or kill."))),
    };
    let process = crate::fleet::services::Service { kind: "process".into(), target: req.pid.to_string(), name: req.pid.to_string(), ..Default::default() };
    engine.service_action(&m.id, &process, action).await.map_err(|e| match e {
        crate::fleet::desktop::AddDisplayError::NeedsPassword(_) => ApiError::new("invalid", format!("{} wants the user's password for that: it's another user's process (sudo).", m.name)).with_hint("Do it from the Muxin app (machine › Services › Processes), which asks for it."),
        crate::fleet::desktop::AddDisplayError::Failed(e) => ApiError::new("operation_failed", e),
    })?;
    Ok(serde_json::json!({ "machine_id": m.id, "pid": req.pid, "done": if action == "kill" { "killed" } else { "stopped" } }))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RunRequest {
    pub machine_ids: Vec<String>,
    pub command: String,
    /// Seconds each may run (default 600, at most 3600).
    pub timeout_secs: Option<u64>,
    /// Wait for all of them (default true).
    pub wait: Option<bool>,
}

#[derive(Debug, Serialize)]
pub struct RunOut {
    pub machine_id: String,
    /// Absent when it couldn't start there (`error` says why).
    pub operation: Option<OperationOut>,
    /// The command's exit status, when it ran to the end.
    pub exit_code: Option<i32>,
    pub error: Option<String>,
}

/// Runs one shell command on several machines at once, in each one's login
/// shell from the home folder.
pub async fn run_on_machines(engine: &Arc<Engine>, req: RunRequest) -> ApiResult<Vec<RunOut>> {
    if req.machine_ids.is_empty() {
        return Err(ApiError::invalid("On which machines? Pass machine_ids."));
    }
    let s = engine.current();
    let ids: Vec<String> = req.machine_ids.iter().map(|id| find_machine(&s, id).map(|m| m.id.clone())).collect::<ApiResult<_>>()?;
    let timeout = req.timeout_secs.map(Duration::from_secs).unwrap_or(crate::fleet::command::DEFAULT_TIMEOUT);
    let started = engine.run_on_machines(&ids, &req.command, timeout);
    let wait = req.wait.unwrap_or(true);
    let mut out = Vec::new();
    for (machine_id, op) in started {
        match op {
            Ok(op) => {
                let o = if wait { wait_operation(engine, op, timeout + Duration::from_secs(30), |_| {}).await } else { None };
                let o = o.or_else(|| engine.current().operations.iter().find(|o| o.id == op).cloned()).ok_or_else(|| ApiError::new("internal", "The operation went missing."))?;
                let exit_code = match (o.status.as_str(), o.error.as_deref()) {
                    ("succeeded", _) => Some(0),
                    (_, Some(e)) => e.strip_prefix("Exited with status ").and_then(|c| c.trim_end_matches('.').parse().ok()),
                    _ => None,
                };
                let error = o.error.clone();
                out.push(RunOut { machine_id, operation: Some(operation_out(&o, DEFAULT_TAIL)), exit_code, error });
            }
            Err(e) => out.push(RunOut { machine_id, operation: None, exit_code: None, error: Some(e) }),
        }
    }
    Ok(out)
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WakeRequest {
    pub machine_id: String,
}

/// Wakes a machine that's asleep or off (Wake on LAN).
pub async fn wake_machine(engine: &Arc<Engine>, req: WakeRequest) -> ApiResult<serde_json::Value> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let from = engine.wake(&m.id).await.map_err(|e| ApiError::new("operation_failed", e))?;
    Ok(serde_json::json!({ "machine_id": m.id, "sent_from": from, "next": "Muxin checks it again in 20 and 40 seconds; call get_machine then." }))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PortsRequest {
    pub machine_id: String,
}

/// What's listening on a machine: each TCP port with its program or Docker
/// container, and for web servers the status and title of their front page.
pub async fn machine_ports(engine: &Arc<Engine>, req: PortsRequest) -> ApiResult<Vec<crate::fleet::ports::ListeningPort>> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.ports(&m.id).await.map_err(|e| ApiError::new("operation_failed", e))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ForwardRequest {
    pub machine_id: String,
    pub port: u16,
    /// The port on this computer (default: the same, or the next free one).
    pub local_port: Option<u16>,
}

/// Opens a machine's port on this computer (localhost), for as long as this
/// process runs.
pub async fn forward_port(engine: &Arc<Engine>, req: ForwardRequest) -> ApiResult<crate::fleet::ports::Forward> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.forward(&m.id, req.port, None, req.local_port).await.map_err(|e| ApiError::new("invalid", e))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RemoteDesktopRequest {
    pub machine_id: String,
    /// "rdp" or "vnc" (default: the one the machine has; RDP first, VNC on a Mac).
    #[serde(default)]
    pub protocol: Option<crate::fleet::remote_desktop::Protocol>,
}

/// Opens a machine's own remote desktop (RDP or VNC) in this computer's app
/// for it, through a port opened here for as long as this process runs.
pub async fn open_remote_desktop(engine: &Arc<Engine>, req: RemoteDesktopRequest) -> ApiResult<crate::fleet::remote_desktop::RemoteDesktop> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.open_remote_desktop(&m.id, req.protocol).await.map_err(|e| ApiError::new("invalid", e))
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ComposeProjectRequest {
    pub machine_id: String,
    /// The project's name, as machine_services lists it.
    pub project: String,
}

/// A Compose project's parts: its services (image, ports, what each waits
/// for, networks, volumes, health check) with their containers' state, and
/// its networks and volumes.
pub async fn compose_project(engine: &Arc<Engine>, req: ComposeProjectRequest) -> ApiResult<crate::fleet::services::ComposeGraph> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    let list = engine.services(&m.id, false).await.map_err(|e| ApiError::new("operation_failed", e))?;
    let project = list.compose.into_iter().find(|p| p.name == req.project).ok_or_else(|| ApiError::new("not_found", format!("{} has no Compose project called {}.", m.name, req.project)))?;
    engine.compose_describe(&m.id, &project).await.map_err(|e| ApiError::new("operation_failed", e))
}

/// Git checkouts on the machines, re-read first.
pub async fn checkouts(engine: &Arc<Engine>, req: CheckoutsRequest) -> ApiResult<Vec<Checkout>> {
    let machines = session_machines(engine, req.machine_id.as_deref())?;
    let _ = futures::future::join_all(machines.iter().map(|m| engine.refresh_checkouts(&m.id))).await;
    let want = req.repo.as_deref().and_then(hub::repo_name);
    Ok(engine
        .current()
        .checkouts
        .iter()
        .filter(|c| machines.iter().any(|m| m.id == c.machine_id))
        .filter(|c| want.as_deref().is_none_or(|w| c.repo.as_deref().is_some_and(|r| r.eq_ignore_ascii_case(w))))
        .cloned()
        .collect())
}

pub async fn checkout_git(engine: &Arc<Engine>, req: GitRequest) -> ApiResult<GitOut> {
    let m = find_machine(&engine.current(), &req.machine_id)?.clone();
    engine.checkout_git(&m.id, &req.path, &req.action).await.map(|output| GitOut { output }).map_err(|e| ApiError::new("operation_failed", e))
}

// ---------------------------------------------------------------------------
// Files: browsing folders on machines, and copying between them.

#[derive(Debug, Deserialize)]
pub struct ListFilesRequest {
    pub machine_id: String,
    /// A folder: "~", "~/build", "/srv/data". Default: the home folder.
    #[serde(default)]
    pub path: String,
}

pub async fn list_files(engine: &Arc<Engine>, req: ListFilesRequest) -> ApiResult<crate::fleet::files::Listing> {
    let s = engine.current();
    let m = find_machine(&s, &req.machine_id)?;
    engine.list_files(&m.id, &req.path).await.map_err(ApiError::invalid)
}

#[derive(Debug, Deserialize)]
pub struct CopyFilesRequest {
    /// The machine with the files.
    pub from: String,
    /// Files and folders on it ("~/build/app.tar.gz", "/srv/data/reports").
    pub paths: Vec<String>,
    /// The machine to copy them to.
    pub to: String,
    /// The folder there (made if missing). Files with the same names are replaced.
    pub to_dir: String,
    /// Wait for the copy to finish (default true).
    #[serde(default = "yes")]
    pub wait: bool,
    #[serde(default)]
    pub timeout_secs: Option<u64>,
}

#[derive(Debug, Serialize)]
pub struct CopyFilesResponse {
    /// One per source folder.
    pub operations: Vec<OperationOut>,
    pub finished: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next: Option<String>,
}

/// Splits "~/build/app" into ("~/build", "app"); a bare name is in the home folder.
pub fn split_path(path: &str) -> Result<(String, String), String> {
    let p = path.trim().trim_end_matches('/');
    if p.is_empty() || p == "~" {
        return Err("Name a file or folder to copy, not a whole home folder.".into());
    }
    match p.rsplit_once('/') {
        Some(("", name)) => Ok(("/".into(), name.into())),
        Some((dir, name)) => Ok((dir.into(), name.into())),
        None => Ok(("~".into(), p.into())),
    }
}

pub async fn copy_files(engine: &Arc<Engine>, req: CopyFilesRequest, surface: Surface, mut on_line: impl FnMut(&str)) -> ApiResult<CopyFilesResponse> {
    let s = engine.current();
    let from = find_machine(&s, &req.from)?.id.clone();
    let to = find_machine(&s, &req.to)?.id.clone();
    if req.paths.is_empty() {
        return Err(ApiError::invalid("Give at least one path to copy."));
    }
    // One copy per folder the files are in.
    let mut groups: Vec<(String, Vec<String>)> = Vec::new();
    for p in &req.paths {
        let (dir, name) = split_path(p).map_err(ApiError::invalid)?;
        match groups.iter_mut().find(|(d, _)| *d == dir) {
            Some((_, names)) => names.push(name),
            None => groups.push((dir, vec![name])),
        }
    }
    let mut ids = Vec::new();
    for (dir, names) in groups {
        let copy = crate::fleet::files::CopyRequest { from: from.clone(), dir, names, to: to.clone(), to_dir: req.to_dir.clone() };
        ids.push(engine.copy_files(copy).map_err(ApiError::invalid)?);
    }
    let timeout = Duration::from_secs(req.timeout_secs.unwrap_or(3600).max(1));
    let mut operations = Vec::new();
    for id in &ids {
        let op = if req.wait {
            wait_operation(engine, *id, timeout, &mut on_line).await
        } else {
            engine.current().operations.iter().find(|o| o.id == *id).cloned()
        }
        .ok_or_else(|| ApiError::new("internal", format!("Operation {id} disappeared.")))?;
        operations.push(op);
    }
    let finished = operations.iter().all(|o| o.status != "running");
    let response = CopyFilesResponse {
        operations: operations.iter().map(|o| operation_out(o, DEFAULT_TAIL)).collect(),
        finished,
        next: (!finished).then(|| {
            surface.say(
                "Still copying. Poll get_operation with each operation id until status isn't \"running\"; cancel_operation stops one.".to_string(),
                "Still copying in the background; this command stopped waiting.",
            )
        }),
    };
    if let Some(failed) = operations.iter().find(|o| o.status == "failed") {
        return Err(ApiError {
            code: "operation_failed",
            message: failed.error.clone().unwrap_or_else(|| "The copy failed.".into()),
            hint: None,
            details: serde_json::to_value(&response).ok(),
        });
    }
    Ok(response)
}

/// Stops a running operation that can be stopped (a copy).
pub fn cancel_operation(engine: &Arc<Engine>, req: OperationRequest) -> ApiResult<OperationOut> {
    if !engine.cancel_op(req.operation_id) {
        return Err(ApiError::invalid(format!("Operation {} isn't running, or can't be stopped.", req.operation_id)));
    }
    operation(engine, req)
}