From 6c8a1861bdbd6fd8aeabcef5da0e7c925f1db42b Mon Sep 17 00:00:00 2001 From: aiongg Date: Mon, 16 Nov 2026 12:40:26 +0000 Subject: [PATCH] merge-fwe: FW16 E5: AgentLink, the link host: start, move, stop and retry the agents' control server and publish its connection file --- crates/automation/src/agents/link.rs | 247 +++++++++++++++++++++++++++ crates/automation/src/agents/mod.rs | 4 + crates/automation/tests/it/agents.rs | 157 ++++++++++++++++- 3 files changed, 406 insertions(+), 2 deletions(-) create mode 100644 crates/automation/src/agents/link.rs diff --git a/crates/automation/src/agents/link.rs b/crates/automation/src/agents/link.rs new file mode 100644 index 000000000..fea1cf8bd --- /dev/null +++ b/crates/automation/src/agents/link.rs @@ -0,0 +1,247 @@ +//! The link host: the control server an app runs for agents while its settings let them in. + +use std::fmt; +use std::path::{Path, PathBuf}; +use std::sync::mpsc::Receiver; +use std::time::{Duration, Instant}; + +use craft_ui::runtime::motion; +use craft_ui::runtime::windows::WindowHost; +use egui::ViewportId; +use serde::{Serialize, Serializer}; + +use super::{AgentSettings, Connection, TOKEN_FILE, remove_connection, write_connection}; +use crate::control::ControlRequest; +use crate::security; +use crate::server::{self, Listening}; + +/// How long after a failed start [`AgentLink::sync`] tries again with the same settings, so +/// freeing a taken port is enough. +pub const RETRY: Duration = Duration::from_secs(5); + +/// Why agents cannot connect, or what the app could not apply. `Display` is the English sentence +/// for logs and `ui.inspect`; the Agents page shows its own words. +#[derive(Clone, Debug, PartialEq, Eq)] +#[non_exhaustive] +pub enum LinkProblem { + /// Allow Agent Control is off. + NotAllowed, + /// The app has no settings folder (no home folder). + NoSettingsFolder, + /// The token file could not be read or written. + TokenFile(String), + /// The control server could not listen on `port`. + Listen { + /// The port asked for (0 is any). + port: u16, + /// Why. + error: String, + }, + /// The connection file could not be written; nothing listens without it. + Publish(String), + /// The app's own note ([`AgentLink::note`]), such as a folder it could not use. + App(String), +} + +impl fmt::Display for LinkProblem { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::NotAllowed => f.write_str("Agents can't connect: Allow Agent Control is off in the preferences file."), + Self::NoSettingsFolder => f.write_str("Agents can't connect: the app has no settings folder (no home folder)."), + Self::TokenFile(e) => write!(f, "Agents can't connect: the token file could not be written: {e}"), + Self::Listen { port, error } => write!(f, "Couldn't listen on 127.0.0.1:{port}: {error}"), + Self::Publish(e) => write!(f, "Couldn't publish the agent connection: {e}"), + Self::App(note) => f.write_str(note), + } + } +} + +/// Where the link stands, for the Agents page and `ui.inspect`. Serialised as +/// `{"port", "launchFlags", "error"}`, `error` being the problem's `Display` text. +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct AgentLinkStatus { + /// The port agents can connect on while the server runs. + pub port: Option, + /// The launch options (`--control`) manage the connection; the settings don't. + pub launch_flags: bool, + /// Why agents can't connect, or what could not be applied. + #[serde(rename = "error", serialize_with = "problem_text")] + pub problem: Option, +} + +fn problem_text(problem: &Option, s: S) -> Result { + match problem { + Some(p) => s.collect_str(p), + None => s.serialize_none(), + } +} + +/// What one [`AgentLink::sync`] did, for the app to follow. +#[derive(Debug, Default)] +#[non_exhaustive] +pub struct LinkUpdate { + /// A server started: its requests arrive here. The app drains it as its control channel. + pub requests: Option>, + /// The server that ran stopped: the app drops its control channel. + pub stopped: bool, + /// The settings applied or the link's state changed: the app rebuilds what agents may read and + /// write (its policy, its folders) from [`AgentLink::status`] and the settings. + pub changed: bool, +} + +/// The server while it runs; dropping it stops the server and removes the connection file. +struct Running { + server: Listening, + dir: PathBuf, + /// The `controlPort` setting it was started for (0 is any). + port_pref: u32, +} + +impl Drop for Running { + fn drop(&mut self) { + remove_connection(&self.dir, std::process::id()); + log::info!("agent connection on {} stopped", self.server.addr); + } +} + +/// The control server an app runs for agents while its settings let them in, and the connection +/// file the app's `-cli mcp` finds it by. The token stays in the settings folder across +/// launches ([`TOKEN_FILE`]). Dropping the link stops the server and removes the connection file +/// if this process wrote it. +pub struct AgentLink { + dir: Option, + app: String, + running: Option, + /// The server the launch options started; while it is there, the settings change nothing. + launch: Option, + /// The settings of the last sync that ran, once one ran. + applied: Option>, + retry_at: Option, + retry: Duration, + status: AgentLinkStatus, +} + +impl fmt::Debug for AgentLink { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("AgentLink").field("dir", &self.dir).field("status", &self.status).finish_non_exhaustive() + } +} + +impl AgentLink { + /// A link that keeps its token and connection file in `settings_dir` and names `app` (the + /// app's version string) in the connection file. Nothing runs until [`Self::sync`]. + pub fn new(settings_dir: Option, app: impl Into) -> Self { + Self { + dir: settings_dir, + app: app.into(), + running: None, + launch: None, + applied: None, + retry_at: None, + retry: RETRY, + status: AgentLinkStatus::default(), + } + } + + /// The server `--control` started: the status names its port and the launch options, and + /// [`Self::sync`] changes nothing. + pub fn from_launch(server: Listening) -> Self { + let mut link = Self::new(None, String::new()); + link.status = AgentLinkStatus { port: Some(server.addr.port()), launch_flags: true, problem: None }; + link.launch = Some(server); + link + } + + /// [`RETRY`] replaced by `delay`, so a test retries at once. + #[doc(hidden)] + pub fn retry_after(mut self, delay: Duration) -> Self { + self.retry = delay; + self + } + + /// Brings the server in line with `want` (`None`: agents may not connect): start it, restart it + /// on another port, stop it, or keep it while other settings change. Does nothing while `want` + /// equals the last call's and no retry of a failed start is due. + pub fn sync(&mut self, want: Option<&AgentSettings>, host: &WindowHost) -> LinkUpdate { + let mut update = LinkUpdate::default(); + if self.launch.is_some() { + return update; + } + let now = motion::now(); + let retry_due = self.retry_at.is_some_and(|at| now >= at); + if self.applied.as_ref().is_some_and(|applied| applied.as_ref() == want) && !retry_due { + return update; + } + let before = (self.status.clone(), self.applied.clone()); + self.applied = Some(want.cloned()); + self.retry_at = None; + self.status.problem = None; + if let Err(problem) = self.apply(want, host, &mut update) { + self.status.problem = Some(problem); + } + self.status.port = self.running.as_ref().map(|r| r.server.addr.port()); + update.changed = (&self.status, &self.applied) != (&before.0, &before.1); + update + } + + fn apply(&mut self, want: Option<&AgentSettings>, host: &WindowHost, update: &mut LinkUpdate) -> Result<(), LinkProblem> { + let Some(want) = want else { + update.stopped = self.running.take().is_some(); + return Ok(()); + }; + // Allow Agent Control off refuses every control server, this one as `--control`. + if !want.allow_agent_control { + update.stopped = self.running.take().is_some(); + return Err(LinkProblem::NotAllowed); + } + let Some(dir) = self.dir.clone() else { + update.stopped = self.running.take().is_some(); + return Err(LinkProblem::NoSettingsFolder); + }; + if self.running.as_ref().is_some_and(|r| r.port_pref == want.control_port) { + return Ok(()); + } + update.stopped = self.running.take().is_some(); + // The setting's range is 0..=65535; anything else picks a free port. + let port = u16::try_from(want.control_port).unwrap_or(0); + match self.start(&dir, port, want.control_port, host) { + Ok((running, requests)) => { + log::info!("agents can connect on {}", running.server.addr); + self.running = Some(running); + update.requests = Some(requests); + Ok(()) + } + Err(problem) => { + log::warn!("{problem}"); + self.retry_at = Some(motion::now() + self.retry); + host.repaint_in(ViewportId::ROOT, self.retry.as_secs_f64()); + Err(problem) + } + } + } + + /// The token from the settings folder (created `0600` when missing), the server, then the + /// connection file. Any failure leaves nothing running. + fn start(&self, dir: &Path, port: u16, port_pref: u32, host: &WindowHost) -> Result<(Running, Receiver), LinkProblem> { + let token_file = dir.join(TOKEN_FILE); + let token = security::server_token(None, Some(&token_file)).map_err(|e| LinkProblem::TokenFile(e.to_string()))?; + let (requests, server) = server::listen(port, token, host.clone()).map_err(|e| LinkProblem::Listen { port, error: e.to_string() })?; + let running = Running { server, dir: dir.to_path_buf(), port_pref }; + let connection = Connection::new(running.server.addr.port(), token_file, self.app.clone()); + write_connection(dir, &connection).map_err(|e| LinkProblem::Publish(e.to_string()))?; + Ok((running, requests)) + } + + /// Where the link stands. + pub fn status(&self) -> &AgentLinkStatus { + &self.status + } + + /// The app reports what it could not apply (a folder it could not use); shown until the next + /// change. + pub fn note(&mut self, problem: LinkProblem) { + self.status.problem = Some(problem); + } +} diff --git a/crates/automation/src/agents/mod.rs b/crates/automation/src/agents/mod.rs index 11366be2b..949740ed8 100644 --- a/crates/automation/src/agents/mod.rs +++ b/crates/automation/src/agents/mod.rs @@ -32,11 +32,15 @@ pub use settings::{AgentSettings, WhenAppClosed, agents_allowed, folder}; #[cfg(all(feature = "agents", not(target_arch = "wasm32")))] mod connection; +#[cfg(all(feature = "agents", feature = "ui", not(target_arch = "wasm32")))] +mod link; #[cfg(all(feature = "agents", not(target_arch = "wasm32")))] mod switch; #[cfg(all(feature = "agents", not(target_arch = "wasm32")))] pub use connection::{ CONNECTION_FILE, Connection, PROBE_TIMEOUT, TOKEN_FILE, probe, read_connection, remove_connection, remove_stale_connection, write_connection, }; +#[cfg(all(feature = "agents", feature = "ui", not(target_arch = "wasm32")))] +pub use link::{AgentLink, AgentLinkStatus, LinkProblem, LinkUpdate, RETRY}; #[cfg(all(feature = "agents", not(target_arch = "wasm32")))] pub use switch::{AgentSwitch, POLL, launcher_allows, mcp_flag}; diff --git a/crates/automation/tests/it/agents.rs b/crates/automation/tests/it/agents.rs index b0392dd49..f96204272 100644 --- a/crates/automation/tests/it/agents.rs +++ b/crates/automation/tests/it/agents.rs @@ -7,12 +7,15 @@ use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::time::Duration; use craft_automation::agents::{ - AgentSwitch, CONNECTION_FILE, Connection, TOKEN_FILE, agents_allowed, read_connection, remove_connection, remove_stale_connection, - write_connection, + AgentLink, AgentSettings, AgentSwitch, CONNECTION_FILE, Connection, LinkProblem, PROBE_TIMEOUT, TOKEN_FILE, agents_allowed, probe, read_connection, + remove_connection, remove_stale_connection, write_connection, }; +use craft_automation::server; use craft_host::Wake; use craft_ui::runtime::motion; +use craft_ui::runtime::windows::WindowHost; use craft_ui::testing::trial; +use egui::Context; fn temp_dir(tag: &str) -> tempfile::TempDir { tempfile::Builder::new().prefix(&format!("craft-agents-{tag}-")).tempdir().expect("a temp dir") @@ -144,3 +147,153 @@ fn a_damaged_foreign_or_stale_connection_file_counts_as_none() { remove_stale_connection(dir); assert!(!dir.join(CONNECTION_FILE).exists(), "nothing listens on {closed}"); } + +fn host() -> WindowHost { + WindowHost::of(&Context::default()) +} + +fn on(port: u32) -> AgentSettings { + AgentSettings { control_port: port, ..AgentSettings::default() } +} + +/// A port nothing listens on: bound, then closed. +fn free_port() -> u16 { + TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port() +} + +/// Off publishes nothing; on publishes the bound port and this process, and something answers there; a folder-only +/// change keeps the port and gives no new channel; off removes the file and frees the port. +#[trial] +fn turning_agents_on_publishes_a_reachable_connection_and_off_removes_it() { + let dir = temp_dir("link"); + let host = host(); + let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "MyApp 1.0"); + let off = link.sync(None, &host); + assert!(off.requests.is_none() && !off.stopped && !off.changed); + assert_eq!(read_connection(dir.path()).unwrap(), None); + + let started = link.sync(Some(&on(0)), &host); + assert!(started.requests.is_some() && started.changed); + let port = link.status().port.expect("listening"); + let c = read_connection(dir.path()).unwrap().expect("published"); + assert_eq!((c.port, c.pid, c.app.as_str()), (port, std::process::id(), "MyApp 1.0")); + assert!(probe(port, PROBE_TIMEOUT)); + let token = std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap(); + + let folders = AgentSettings { read_root: "/in".into(), ..on(0) }; + let kept = link.sync(Some(&folders), &host); + assert!(kept.requests.is_none() && !kept.stopped && kept.changed, "a folder change keeps the server"); + assert_eq!(link.status().port, Some(port)); + assert_eq!(std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap(), token); + + let stopped = link.sync(None, &host); + assert!(stopped.stopped && stopped.changed); + assert_eq!(link.status().port, None); + assert!(!dir.path().join(CONNECTION_FILE).exists()); + TcpListener::bind(("127.0.0.1", port)).expect("the port is free"); +} + +/// A new port restarts the server with the same token; a taken port is named, publishes nothing, and is tried again +/// without a setting change until it is free. +#[trial] +fn a_new_port_restarts_with_the_same_token_and_a_taken_port_is_retried() { + let dir = temp_dir("link-port"); + let host = host(); + let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "x").retry_after(Duration::ZERO); + assert!(link.sync(Some(&on(0)), &host).requests.is_some()); + let token = std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap(); + + let wanted = free_port(); + let moved = link.sync(Some(&on(u32::from(wanted))), &host); + assert!(moved.stopped && moved.requests.is_some()); + assert_eq!(link.status().port, Some(wanted)); + assert_eq!(read_connection(dir.path()).unwrap().expect("published").port, wanted); + assert_eq!(std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap(), token, "the token is kept across restarts"); + + let taken = TcpListener::bind("127.0.0.1:0").unwrap(); + let taken_port = taken.local_addr().unwrap().port(); + let failed = link.sync(Some(&on(u32::from(taken_port))), &host); + assert!(failed.stopped && failed.requests.is_none()); + assert!(matches!(link.status().problem, Some(LinkProblem::Listen { port, .. }) if port == taken_port), "{:?}", link.status()); + assert_eq!(link.status().port, None); + assert_eq!(read_connection(dir.path()).unwrap(), None, "nothing listens without a file, and no file without a listener"); + + // Still taken: the retry fails the same way and changes nothing. + let again = link.sync(Some(&on(u32::from(taken_port))), &host); + assert!(again.requests.is_none() && !again.changed); + drop(taken); + let retried = link.sync(Some(&on(u32::from(taken_port))), &host); + assert!(retried.requests.is_some() && retried.changed, "freeing the port is enough"); + assert_eq!(link.status().port, Some(taken_port)); + assert_eq!(link.status().problem, None); + assert_eq!(std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap(), token); +} + +/// Ten syncs with the same settings start one server. +#[trial] +fn an_unchanged_sync_starts_nothing() { + let dir = temp_dir("link-same"); + let host = host(); + let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "x"); + let updates: Vec<_> = (0..10).map(|_| link.sync(Some(&on(0)), &host)).collect(); + assert_eq!(updates.iter().filter(|u| u.requests.is_some()).count(), 1); + assert_eq!(updates.iter().filter(|u| u.changed).count(), 1); + assert!(updates.iter().all(|u| !u.stopped)); + assert!(link.status().port.is_some()); +} + +/// Allow Agent Control off, no settings folder and an unusable token file each keep agents out: no channel, no file, +/// and the port is free. +#[trial] +fn allow_agent_control_off_and_no_settings_folder_keep_agents_out() { + let host = host(); + let dir = temp_dir("link-off"); + let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "x"); + assert!(link.sync(Some(&on(0)), &host).requests.is_some()); + let port = link.status().port.expect("listening"); + let refused = link.sync(Some(&AgentSettings { allow_agent_control: false, ..on(0) }), &host); + assert!(refused.stopped && refused.requests.is_none()); + assert_eq!(link.status().problem, Some(LinkProblem::NotAllowed)); + assert!(!dir.path().join(CONNECTION_FILE).exists()); + TcpListener::bind(("127.0.0.1", port)).expect("the port is free"); + + let mut homeless = AgentLink::new(None, "x"); + assert!(homeless.sync(Some(&on(0)), &host).requests.is_none()); + assert_eq!(homeless.status().problem, Some(LinkProblem::NoSettingsFolder)); + + let bad = temp_dir("link-token"); + std::fs::create_dir(bad.path().join(TOKEN_FILE)).unwrap(); + let wanted = free_port(); + let mut link = AgentLink::new(Some(bad.path().to_path_buf()), "x"); + assert!(link.sync(Some(&on(u32::from(wanted))), &host).requests.is_none()); + assert!(matches!(link.status().problem, Some(LinkProblem::TokenFile(_))), "{:?}", link.status()); + assert!(!bad.path().join(CONNECTION_FILE).exists()); + TcpListener::bind(("127.0.0.1", wanted)).expect("nothing listens"); + let status = serde_json::to_value(link.status()).unwrap(); + assert!(status["error"].as_str().unwrap().starts_with("Agents can't connect: the token file"), "{status}"); +} + +/// Dropping the link stops its server and removes its connection file. +#[trial] +fn dropping_the_link_removes_its_connection_file() { + let dir = temp_dir("link-drop"); + let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "x"); + assert!(link.sync(Some(&on(0)), &host()).requests.is_some()); + let port = link.status().port.expect("listening"); + drop(link); + assert!(!dir.path().join(CONNECTION_FILE).exists()); + TcpListener::bind(("127.0.0.1", port)).expect("the port is free"); +} + +/// A server the launch options started is reported with its port, and the settings change nothing. +#[trial] +fn from_launch_reports_the_launch_flags() { + let (_requests, server) = server::listen(0, "0".repeat(64), host()).expect("started"); + let port = server.addr.port(); + let mut link = AgentLink::from_launch(server); + assert_eq!((link.status().port, link.status().launch_flags), (Some(port), true)); + let update = link.sync(None, &host()); + assert!(!update.stopped && !update.changed && update.requests.is_none()); + assert_eq!(link.status().port, Some(port)); + assert_eq!(serde_json::to_value(link.status()).unwrap(), serde_json::json!({"port": port, "launchFlags": true, "error": null})); +}