Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

13.8 KB
Raw Blame
//! A harness's graphics live in the user's browser. SSH returns an authenticated web-app
//! destination; only the invoking terminal process may launch a local browser.

use std::io::IsTerminal;
use std::process::Stdio;
use std::time::Duration;
use tokio_tungstenite::tungstenite::http::Uri;

use crate::{app::App, fleet::Agent};

pub const USAGE: &str = "usage: hn view [-pcw] [-t harness]";

#[derive(Default, Debug)]
pub struct Options { pub print: bool, pub copy: bool, pub web: bool, pub target: Option<String> }
impl Options {
    pub fn parse(args: &[String]) -> Result<Self, String> {
        let mut out = Self::default();
        let mut args = args.iter();
        while let Some(arg) = args.next() {
            match arg.as_str() {
                "-t" => out.target = Some(args.next().filter(|s| !s.is_empty()).ok_or(USAGE)?.clone()),
                "-p" | "--print" => out.print = true,
                "-c" | "--copy" => out.copy = true,
                "-w" | "--web" => out.web = true,
                _ if arg.starts_with('-') && arg.len() > 1 && arg[1..].chars().all(|c| "pcw".contains(c)) => {
                    out.print |= arg.contains('p'); out.copy |= arg.contains('c'); out.web |= arg.contains('w');
                }
                _ => return Err(USAGE.into()),
            }
        }
        Ok(out)
    }
}

fn valid_url(value: &str) -> bool {
    if value.chars().any(|c| c.is_control() || c.is_whitespace()) || value.contains('\\') { return false }
    let Ok(uri) = value.split('#').next().unwrap_or("").parse::<Uri>() else { return false };
    matches!(uri.scheme_str(), Some("http" | "https")) && uri.host().is_some_and(|h| !h.is_empty())
        && !uri.authority().is_some_and(|a| a.as_str().contains('@'))
}

fn encode(value: &str) -> String {
    let mut out = String::new();
    for b in value.bytes() {
        if b.is_ascii_alphanumeric() || b"-._~".contains(&b) { out.push(b as char) }
        else { use std::fmt::Write; let _ = write!(out, "%{b:02X}"); }
    }
    out
}

pub fn web_link(base: &str, machine: &str, agent: &str) -> Result<String, String> {
    if !valid_url(base) || base.contains(['?', '#']) || machine.is_empty() || agent.is_empty() {
        return Err("the daemon has no browser address — update Harness on this machine".into())
    }
    let uri: Uri = base.parse().map_err(|_| "invalid browser address")?;
    if uri.path() != "/" && !uri.path().is_empty() {
        return Err("the daemon browser address must point to the website root".into())
    }
    if uri.scheme_str() != Some("https") && !matches!(uri.host(), Some("localhost" | "127.0.0.1" | "[::1]" | "::1")) {
        return Err("the browser address must use HTTPS (HTTP is allowed for localhost development)".into())
    }
    Ok(format!("{}/?viewer=1&machine={}&agent={}", base.trim_end_matches('/'), encode(machine), encode(agent)))
}

pub fn destination(agent: &Agent, local: &str, web: &str, remote: bool) -> Result<String, String> {
    if agent.viewer_url.is_empty() && agent.viewer_name.is_empty() {
        return Err(if agent.viewer_error.is_empty() { "this harness has no viewer".into() } else { agent.viewer_error.clone() })
    }
    // A peer's loopback URL is owned by a particular daemon connection and can disappear when
    // that connection closes. Use the browser's own authenticated connection for every peer.
    if !remote && agent.machine_id == local && !agent.viewer_url.is_empty() {
        if !valid_url(&agent.viewer_url) { return Err("the harness returned an invalid viewer address".into()) }
        return Ok(agent.viewer_url.clone())
    }
    web_link(web, &agent.machine_id, &agent.id)
}

pub fn ssh() -> bool {
    ["SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY"].iter().any(|k| std::env::var_os(k).is_some_and(|v| !v.is_empty()))
}

async fn open(url: &str) -> bool {
    if !valid_url(url) || ssh() { return false }
    if cfg!(target_os = "linux") && ["DISPLAY", "WAYLAND_DISPLAY"].iter().all(|k| std::env::var_os(k).is_none_or(|v| v.is_empty())) { return false }
    let mut command = crate::sys::url_opener();
    let Ok(mut child) = command.arg(url).stdin(Stdio::null()).stdout(Stdio::null()).stderr(Stdio::null()).kill_on_drop(true).spawn() else { return false };
    matches!(tokio::time::timeout(Duration::from_secs(5), child.wait()).await, Ok(Ok(status)) if status.success())
}

pub fn show(app: &mut App, key: (String, String), options: Options) {
    use crate::measure::Outcome;
    let Some(agent) = app.fleet.agent(&key.0, &key.1) else { return app.error("can't find harness") };
    // viewer_open (measure.rs), as the Desktop counts its viewer pane opened for the person: the
    // browser opening it, or its link shown to open (over SSH); failed when it could not open, or
    // with the harness's launch error. Opening is not rendering. A copied link or a shell asking for
    // it (`hn view -p`) opens nothing.
    let launch_error = !agent.viewer_error.is_empty();
    let opens = opens_for_person(app.capture.is_some(), &options);
    let url = match destination(agent, &app.fleet.local_id, &app.viewer_web_url, options.web || options.copy || (app.capture.is_none() && ssh())) {
        Ok(url) => url,
        Err(e) => { if opens && launch_error { crate::measure::once(app, "viewer_open", Outcome::Failed) } return app.error(e) }
    };
    if app.capture.is_some() || options.print { app.print("Viewer", vec![url]); return }
    if options.copy {
        crate::clipboard::store(&url);
        app.say("Viewer link sent to the terminal clipboard", crate::theme::ONLINE);
        return
    }
    if ssh() {
        show_link(app, &url);
        crate::measure::once(app, "viewer_open", if launch_error { Outcome::Failed } else { Outcome::Ok });
        return
    }
    let measured = crate::measure::begin(app, "viewer_open");
    app.spawn(async move { let opened = open(&url).await; (url, opened) }, move |app, (url, opened)| {
        measured.finish(app, if opened && !launch_error { Outcome::Ok } else { Outcome::Failed });
        if opened { app.say("Opened viewer in your browser", crate::theme::ONLINE) } else { show_link(app, &url) }
    });
}

/// Whether showing a viewer opens it for the person: not a shell's capture, `-p` or a copied link.
fn opens_for_person(captured: bool, options: &Options) -> bool { !captured && !options.print && !options.copy }

fn show_link(app: &mut App, url: &str) {
    app.print("Viewer", vec!["Open this link in your browser:".into(), url.into(), String::new(), "Use :view -c to copy the browser link. Sign in and link this machine if asked.".into()]);
}

pub async fn cli(port: u16, args: &[String], socket: Option<&str>, name: Option<&str>) -> i32 {
    if args == ["--help"] || args == ["-h"] { println!("{USAGE}\nOpen the current harness's viewer. Over SSH, prints a browser link.\n-p  Print only   -c  Copy browser link   -w  Use authenticated browser app"); return 0 }
    let options = match Options::parse(args) { Ok(o) => o, Err(e) => { eprintln!("{e}"); return 2 } };
    let remote = options.web || options.copy || ssh();
    let result = if crate::ipc::alive(socket, name) {
        let Some(path) = crate::ipc::chosen(socket, name) else { eprintln!("hn: no client running"); return 1 };
        let mut words = vec!["open-viewer".into(), "-p".into()];
        if remote { words.push("-w".into()) }
        if let Some(t) = &options.target { words.extend(["-t".into(), t.clone()]) }
        match tokio::task::spawn_blocking(move || crate::ipc::ask(&path, &words)).await {
            Ok(Some((out, err, 0))) if err.is_empty() && out.len() == 1 => Ok(out[0].clone()),
            Ok(Some((_, err, _))) => Err(err.join("\n")),
            _ => Err("could not reach the hn client".into()),
        }
    } else { standalone(port, &options, remote).await };
    let url = match result { Ok(url) if valid_url(&url) => url, Ok(_) => { eprintln!("hn: invalid viewer address"); return 1 }, Err(e) => { eprintln!("hn: {e}"); return 1 } };
    if options.copy && std::io::stdout().is_terminal() { crate::clipboard::store(&url) }
    if !options.print && !options.copy && !ssh() && open(&url).await { return 0 }
    // Plain output remains usable with any terminal and in scripts; terminal apps can recognize
    // the URL without an OSC extension. Never start a browser process on an SSH host.
    println!("{url}");
    if !options.print && !options.copy { eprintln!("Open this link in your browser. Sign in and link the machine if asked.") }
    0
}

async fn standalone(port: u16, options: &Options, remote: bool) -> Result<String, String> {
    let target = options.target.as_deref().ok_or("no current hn pane — use hn view -t <harness>")?;
    let status = crate::daemon::http_json(port, "GET", "/api/status", None).await.map_err(|_| "the daemon is not running — harness start")?;
    let (local, machines) = crate::cli::machines(port).await?;
    let mut all = Vec::new();
    for (id, name, online) in machines {
        if !online { continue }
        let wanted = match target.split_once(':') {
            Some((m, a)) if m == id || m == name => a,
            Some(_) => continue,
            None => target,
        };
        for agent in crate::cli::roster(port, &id).await {
            let exact = agent.id == wanted || agent.name == wanted;
            if exact || agent.name.starts_with(wanted) { all.push((exact, agent)) }
        }
    }
    if all.iter().any(|(exact, _)| *exact) { all.retain(|(exact, _)| *exact) }
    match all.as_slice() {
        [(_, agent)] => destination(agent, &local, status.get("webUrl").and_then(serde_json::Value::as_str).unwrap_or(""), remote),
        [] => Err(format!("can't find harness: {target}")),
        _ => Err(format!("more than one harness: {target} — use -t machine:agent-id")),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    #[test]
    fn addresses_are_data_and_ssh_never_uses_remote_loopback() {
        let a = crate::fleet::agent_from("remote", &json!({"id":"a /?&é", "viewerUrl":"http://127.0.0.1:19777/?file=model.glb", "viewerName":"3D Viewer"}), None);
        assert_eq!(destination(&a, "remote", "https://harness.example", false).unwrap(), a.viewer_url);
        let expected = "https://harness.example/?viewer=1&machine=remote&agent=a%20%2F%3F%26%C3%A9";
        assert_eq!(destination(&a, "remote", "https://harness.example/", true).unwrap(), expected);
        assert_eq!(destination(&a, "local", "https://harness.example", false).unwrap(), expected);
        for url in ["javascript:alert(1)", "file:///tmp/a", "https://a\nInjected", "https://user:pass@host/", "https://a/\\x", "https://a/a b"] { assert!(!valid_url(url), "{url}") }
        assert!(web_link("http://example.com", "m", "a").is_err());
        assert!(web_link("http://127.0.0.1:19778", "m", "a").is_ok());
        assert!(web_link("https://harness.example?x=1", "m", "a").is_err());
        assert!(web_link("https://harness.example/workspace", "m", "a").is_err());
        for base in ["http://localhost:19682", "http://[::1]:19682", "https://harness.example/"] {
            assert!(web_link(base, "m", "a").is_ok(), "{base}");
        }
        for base in ["", "https://", "https://harness.example/#token", "https://user@host", "file:///tmp/test", "--help"] {
            assert!(web_link(base, "m", "a").is_err(), "{base}");
        }
    }
    /// viewer_open counts a viewer opened for the person, as the Desktop's pane: never a copied link
    /// or a shell's `-p`; a harness's launch error is a failed open.
    #[tokio::test]
    async fn only_a_viewer_opened_for_the_person_is_measured() {
        assert!(opens_for_person(false, &Options::default()));
        assert!(opens_for_person(false, &Options { web: true, ..Options::default() }));
        assert!(!opens_for_person(false, &Options { copy: true, ..Options::default() }));
        assert!(!opens_for_person(false, &Options { print: true, ..Options::default() }));
        assert!(!opens_for_person(true, &Options::default()));
        let (sink, _) = tokio::sync::mpsc::unbounded_channel();
        let mut app = App::new(19814, sink, (80, 24));
        app.viewer_web_url = "https://harness.example".into();
        app.fleet.local_id = "m".into();
        app.fleet.machines.push(crate::fleet::Machine { shared: false, id: "m".into(), name: "m".into(), local: true, status: "running".into(), reach: crate::fleet::Reach::Ready });
        app.follow_account(true);
        // (A copied link is not shown here: it would be written to the terminal running the tests.)
        for (id, row) in [("printed", json!({"id": "printed", "viewerName": "3D Viewer"})), ("broken", json!({"id": "broken", "viewerError": "the viewer did not start"}))] {
            let agent = crate::fleet::agent_from("m", &row, None);
            app.fleet.agents.insert(agent.key(), agent);
            show(&mut app, ("m".into(), id.into()), Options { print: id == "printed", ..Options::default() });
        }
        crate::measure::tick(&mut app);
        let viewer: Vec<&serde_json::Value> = app.measure.sent.iter().filter(|v| v["flow"] == "viewer_open").collect();
        assert_eq!(viewer.len(), 2, "the broken one's start and failure, nothing for the printed link: {viewer:?}");
        assert_eq!(viewer[1]["outcome"], "failed");
    }

    #[test]
    fn no_viewer_is_an_error_and_waiting_viewer_gets_its_own_page() {
        let mut a = crate::fleet::agent_from("m", &json!({"id":"a"}), None);
        assert!(destination(&a, "m", "https://harness.example", false).is_err());
        a.viewer_name = "3D Viewer".into();
        assert_eq!(destination(&a, "m", "https://harness.example", false).unwrap(), "https://harness.example/?viewer=1&machine=m&agent=a");
        assert!(Options::parse(&["--unknown".into()]).is_err());
        assert!(Options::parse(&["-t".into()]).is_err());
        let o = Options::parse(&["-pcw".into(), "-t".into(), "name with spaces".into()]).unwrap();
        assert!(o.print && o.copy && o.web);
        assert_eq!(o.target.as_deref(), Some("name with spaces"));
    }
}