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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
//! Command line: `serve`, `version`, `ps --json`.
//!
//! The protocol is fixed at build time (`protocol::PROTOCOL`); `version` prints it.
use std::path::{Path, PathBuf};
use crate::protocol::{FEATURES, PROTOCOL};
/// How many random pipe names a Windows host tries before it gives up.
#[cfg(windows)]
const PIPE_NAME_TRIES: usize = 3;
/// tmux's default `history-limit`.
const DEFAULT_HISTORY_LIMIT: usize = 2000;
const USAGE: &str =
"usage: harness-pty serve --home <dir> [--history-limit N] | version | ps --json";
/// The version this host reports. A release stamps it with the CLI's version (`HARNESS_PTY_VERSION`, set by
/// windows.yml's release mode) instead of editing Cargo.toml, which would put the lockfile out of date for
/// `--locked`.
pub const VERSION: &str = release_version(option_env!("HARNESS_PTY_VERSION"));
pub const fn release_version(given: Option<&'static str>) -> &'static str {
match given {
Some(version) if !version.is_empty() => version,
_ => env!("CARGO_PKG_VERSION"),
}
}
pub fn version_line() -> String {
serde_json::json!({"version": VERSION, "protocol": PROTOCOL, "features": FEATURES}).to_string()
}
#[derive(Debug, PartialEq, Eq)]
pub enum Command {
Serve {
home: PathBuf,
history_limit: usize,
/// Whether a Windows host started in a job may start a copy of itself outside it.
/// `--no-reexec` (that copy's own flag) turns it off.
reexec: bool,
},
Version,
PeerAccount {
peer_port: u16,
own_port: u16,
daemon_pid: u32,
},
Ps,
}
pub fn parse(args: &[String]) -> Result<Command, String> {
let mut args = args.iter().map(String::as_str);
match args.next() {
Some("version") => Ok(Command::Version),
Some("ps") => match args.next() {
Some("--json") => Ok(Command::Ps),
_ => Err("ps needs --json".into()),
},
Some("peer-account") => {
let (mut peer_port, mut own_port, mut daemon_pid) = (None, None, None);
while let Some(arg) = args.next() {
let value = args.next().ok_or("peer-account flags need values")?;
let bad = || format!("peer-account: {arg} takes a number");
match arg {
"--peer-port" => peer_port = Some(value.parse().map_err(|_| bad())?),
"--own-port" => own_port = Some(value.parse().map_err(|_| bad())?),
"--daemon-pid" => daemon_pid = Some(value.parse().map_err(|_| bad())?),
_ => return Err(USAGE.into()),
}
}
match (peer_port, own_port, daemon_pid) {
(Some(peer_port @ 1..), Some(own_port @ 1..), Some(daemon_pid)) => {
Ok(Command::PeerAccount {
peer_port,
own_port,
daemon_pid,
})
}
_ => Err("peer-account needs --peer-port, --own-port and --daemon-pid".into()),
}
}
Some("serve") => {
let mut home = None;
let mut history_limit = DEFAULT_HISTORY_LIMIT;
let mut reexec = true;
while let Some(arg) = args.next() {
match arg {
"--no-reexec" => reexec = false,
"--home" => {
home = Some(PathBuf::from(
args.next().ok_or("--home needs a directory")?,
))
}
"--history-limit" => {
history_limit = args
.next()
.and_then(|n| n.parse().ok())
.ok_or("--history-limit needs a number")?
}
other => return Err(format!("unknown argument {other}")),
}
}
Ok(Command::Serve {
home: home.ok_or("serve needs --home")?,
history_limit,
reexec,
})
}
_ => Err(USAGE.into()),
}
}
pub fn main() {
let args: Vec<String> = std::env::args().skip(1).collect();
match parse(&args) {
Ok(Command::Version) => println!("{}", version_line()),
Ok(Command::Ps) => ps(),
Ok(Command::PeerAccount {
peer_port,
own_port,
daemon_pid,
}) => peer_account(peer_port, own_port, daemon_pid),
Ok(Command::Serve {
home,
history_limit,
reexec,
}) => {
// Before anything else the host does: the daemon starts it with no stdio, so the log
// file is where its diagnostics go (stderr still has them for a host run by hand).
crate::logfile::install(&home);
log::info!(
"harness-pty {} (protocol {PROTOCOL}) serving {} (pid {})",
VERSION,
home.display(),
std::process::id()
);
if let Err(err) = serve(&home, history_limit, reexec) {
log::error!("harness-pty: {err}");
log::logger().flush();
std::process::exit(1);
}
}
Err(err) => {
eprintln!("{err}\n{USAGE}");
std::process::exit(2);
}
}
}
/// `peer-account`: `yes` or `no: <why>` on Windows; elsewhere exit 3, where the daemon has its own
/// lookup (cli/src/lib/peerAccount.ts).
fn peer_account(peer_port: u16, own_port: u16, daemon_pid: u32) {
#[cfg(windows)]
match crate::peer::ask(peer_port, own_port, daemon_pid) {
crate::peer::Verdict::Yes => println!("yes"),
crate::peer::Verdict::No(why) => println!("no: {why}"),
}
#[cfg(not(windows))]
{
let _ = (peer_port, own_port, daemon_pid);
println!("{{\"unsupported\":true}}");
std::process::exit(3);
}
}
/// `ps --json`: `{"rows":[…]}` on Windows; elsewhere `{"unsupported":true}`, exit 3 (the daemon
/// reads `ps` there).
fn ps() {
#[cfg(windows)]
match crate::ps::snapshot() {
Ok(rows) => println!("{}", serde_json::json!({ "rows": rows })),
Err(err) => {
eprintln!("harness-pty: process table: {err}");
std::process::exit(1);
}
}
#[cfg(not(windows))]
{
println!("{{\"unsupported\":true}}");
std::process::exit(3);
}
}
/// Create `<home>/run` if it is missing, the owner's alone: mode 0700 on Unix; on Windows a
/// protected DACL that lets only the user in (and that what is created inside inherits), set on
/// a run directory that already exists as well, before anything is written in it.
fn run_dir(home: &Path) -> std::io::Result<PathBuf> {
let run = home.join("run");
#[cfg(unix)]
{
use std::os::unix::fs::DirBuilderExt;
std::fs::DirBuilder::new()
.recursive(true)
.mode(0o700)
.create(&run)?;
}
#[cfg(windows)]
{
std::fs::create_dir_all(home)?;
crate::transport::windows::secure_dir(&run)?;
}
Ok(run)
}
/// Bind the endpoint, publish the discovery file, and serve until killed. Returns at once, with
/// success, when another host already serves this home (or, on Windows, when a copy of this host
/// started outside the job this one is in serves it: `breakaway`).
pub fn serve(home: &Path, history_limit: usize, reexec: bool) -> std::io::Result<()> {
#[cfg(windows)]
if reexec && leave_job(home, history_limit) {
log::info!("a copy of this host started outside its job serves; exiting");
return Ok(());
}
#[cfg(windows)]
{
use windows_sys::Win32::System::Console::SetConsoleCtrlHandler;
// The daemon starts this host in a new process group. Windows then makes its
// Ctrl+C-ignore setting inheritable, so ConPTY children keep running after ETX.
// Clear it in the serving host before any pseudoconsole or pane is created.
if unsafe { SetConsoleCtrlHandler(None, 0) } == 0 {
return Err(std::io::Error::last_os_error());
}
}
#[cfg(not(windows))]
let _ = reexec;
let run = run_dir(home)?;
// Before the endpoint and the pane counter: one host per home.
let Some(_lock) = crate::host_lock::take(&run)? else {
log::info!("another host serves this home; exiting");
return Ok(());
};
// This host is the home's: it alone rotates the log (logfile.rs).
crate::logfile::own_rotation();
#[cfg(unix)]
let bound = {
use crate::transport::unix;
// Owner-only from its creation, so no other user can connect before the chmod. The umask
// is the process's: set while this is the only thread, restored before panes are spawned.
let old = unsafe { libc::umask(0o177) };
let bound = unix::bind(&unix::socket_path(&run));
unsafe { libc::umask(old) };
bound
};
// A new random name each start (transport/windows.rs): a name another process holds is one it
// happened on, so the next is tried; the home's lock, not the name, keeps one host per home.
#[cfg(windows)]
let bound = {
use crate::transport::{Bound, windows};
let mut bound = windows::bind(&windows::pipe_name_for(home)?);
for _ in 1..PIPE_NAME_TRIES {
if !matches!(bound, Ok(Bound::Taken)) {
break;
}
log::warn!("the pipe name drawn is taken; drawing another");
bound = windows::bind(&windows::pipe_name_for(home)?);
}
bound
};
match bound? {
crate::transport::Bound::Listening(listener) => {
publish_and_serve(listener, &run, history_limit)
}
// This host holds the home's lock, so no other host of this home has the endpoint:
// another process squats on the name (on Windows, on every random name drawn). The
// discovery file (a dead host's) may point at it; set it aside so no client follows it.
crate::transport::Bound::Taken => {
set_discovery_aside(&run);
Err(std::io::Error::new(
std::io::ErrorKind::AddrInUse,
"pipe name held by another process",
))
}
}
}
/// Move this build's `pty-host-<instance>.json` to `.json.stale`, when there is one.
fn set_discovery_aside(run: &Path) {
let file = crate::discovery::file_path(run);
let mut aside = file.clone().into_os_string();
aside.push(".stale");
match crate::files::rename(&file, Path::new(&aside)) {
Err(err) if err.kind() != std::io::ErrorKind::NotFound => {
log::error!("cannot set the old discovery file aside: {err}")
}
_ => {}
}
}
/// Windows: start a copy of this host outside the job it is in, if it is in one. True when the
/// copy serves and this process should exit.
#[cfg(windows)]
fn leave_job(home: &Path, history_limit: usize) -> bool {
use crate::breakaway::{Left, in_job, spawn_copy};
let in_job = in_job().unwrap_or_else(|err| {
log::warn!("cannot tell whether the host is in a job: {err}");
false
});
let args: Vec<std::ffi::OsString> = vec![
"serve".into(),
"--home".into(),
home.as_os_str().to_owned(),
"--history-limit".into(),
history_limit.to_string().into(),
"--no-reexec".into(),
];
let left = crate::breakaway::leave_job(
in_job,
|flags| spawn_copy(&args, flags),
|warning| log::warn!("{warning}"),
);
matches!(left, Left::BrokeAway | Left::Detached)
}
fn publish_and_serve<L: crate::transport::Listener>(
listener: L,
run: &Path,
history_limit: usize,
) -> std::io::Result<()> {
let info = crate::server::HostInfo {
token: uuid::Uuid::new_v4().to_string(),
instance: crate::instance::current(),
version: VERSION.to_owned(),
pid: std::process::id(),
};
// Before the host is published: a host that cannot keep its pane counter must not serve.
let (panes, events) =
crate::panes::Panes::persistent(history_limit, info.instance.clone(), run)?;
crate::discovery::write(
run,
&crate::discovery::Discovery {
protocol: PROTOCOL,
instance: info.instance.clone(),
endpoint: listener.endpoint(),
pid: info.pid,
version: info.version.clone(),
token: info.token.clone(),
},
)?;
log::info!("listening as {} on {}", info.instance, listener.endpoint());
let published = (crate::discovery::file_path(run), listener.endpoint());
// Once: the connection that was granted it and its reply's deadline (server.rs) may both call it;
// the second waits in `call_once` while the first exits.
let once = std::sync::Once::new();
let on_shutdown = std::sync::Arc::new(move || {
once.call_once(|| {
let (discovery, endpoint) = &published;
// The discovery file first: a client must not find a host that is about to be gone.
// This host holds the home's lock, so the file is its own. The pane counter and the
// lock stay: pane ids never repeat for the home and protocol.
let _ = std::fs::remove_file(discovery);
#[cfg(unix)]
let _ = std::fs::remove_file(endpoint);
#[cfg(not(unix))]
let _ = endpoint;
std::process::exit(0);
})
});
crate::server::run(listener, panes, events, info, on_shutdown)
}
#[cfg(test)]
mod tests {
use super::*;
fn args(a: &[&str]) -> Vec<String> {
a.iter().map(|s| s.to_string()).collect()
}
#[test]
fn version_line_is_json_with_protocol() {
let v: serde_json::Value = serde_json::from_str(&version_line()).unwrap();
assert_eq!(v["version"], VERSION);
assert_eq!(v["protocol"], PROTOCOL);
assert_eq!(v["features"], serde_json::json!(["seed"]));
}
#[test]
fn a_release_build_reports_the_cli_release_version() {
// The release builds the host with the CLI's version, so its folder runtime\pty\<version>\ and the
// `version` in its discovery file are the version current-pty names. A plain build keeps the crate's.
assert_eq!(release_version(Some("0.3.120")), "0.3.120");
assert_eq!(release_version(None), env!("CARGO_PKG_VERSION"));
// An unset workflow input arrives as an empty string, never as a version.
assert_eq!(release_version(Some("")), env!("CARGO_PKG_VERSION"));
}
#[test]
fn parses_commands() {
assert_eq!(parse(&args(&["version"])), Ok(Command::Version));
assert_eq!(parse(&args(&["ps", "--json"])), Ok(Command::Ps));
assert_eq!(
parse(&args(&[
"peer-account",
"--peer-port",
"5000",
"--own-port",
"18473",
"--daemon-pid",
"42"
])),
Ok(Command::PeerAccount {
peer_port: 5000,
own_port: 18473,
daemon_pid: 42
})
);
assert!(parse(&args(&["peer-account", "--peer-port", "5000"])).is_err());
assert!(
parse(&args(&[
"peer-account",
"--peer-port",
"0",
"--own-port",
"1",
"--daemon-pid",
"1"
]))
.is_err()
);
assert!(
parse(&args(&[
"peer-account",
"--peer-port",
"x",
"--own-port",
"1",
"--daemon-pid",
"1"
]))
.is_err()
);
assert!(
parse(&args(&[
"peer-account",
"--peer-port",
"70000",
"--own-port",
"1",
"--daemon-pid",
"1"
]))
.is_err()
);
assert_eq!(
parse(&args(&["serve", "--home", "/h"])),
Ok(Command::Serve {
home: "/h".into(),
history_limit: DEFAULT_HISTORY_LIMIT,
reexec: true,
})
);
assert_eq!(
parse(&args(&["serve", "--history-limit", "50", "--home", "/h"])),
Ok(Command::Serve {
home: "/h".into(),
history_limit: 50,
reexec: true,
})
);
assert_eq!(
parse(&args(&["serve", "--home", "/h", "--no-reexec"])),
Ok(Command::Serve {
home: "/h".into(),
history_limit: DEFAULT_HISTORY_LIMIT,
reexec: false,
})
);
assert!(parse(&args(&["serve"])).is_err());
assert!(parse(&args(&["serve", "--home"])).is_err());
assert!(parse(&args(&["serve", "--home", "/h", "--x"])).is_err());
assert!(parse(&args(&["ps"])).is_err());
assert!(parse(&args(&[])).is_err());
}
#[test]
fn run_dir_is_created() {
let home = tempfile::tempdir().unwrap();
let run = run_dir(&home.path().join("nested")).unwrap();
assert!(run.is_dir());
#[cfg(windows)]
{
use crate::transport::windows::file_dacl;
// Only the user, inherited by what is made inside.
file_dacl(&run).assert_users_alone(true);
// A run directory that exists already is made the user's alone as well.
let open = home.path().join("open");
std::fs::create_dir_all(open.join("run")).unwrap();
assert!(!file_dacl(&open.join("run")).protected);
run_dir(&open).unwrap();
file_dacl(&open.join("run")).assert_users_alone(true);
// A file made in it has nobody else's entries either.
std::fs::write(open.join("run").join("x"), "x").unwrap();
file_dacl(&open.join("run").join("x")).assert_only_user_entries();
}
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
assert_eq!(
std::fs::metadata(&run).unwrap().permissions().mode() & 0o777,
0o700
);
}
}
}