merge-fwe: FW16 E5: AgentLink, the link host: start, move, stop and retry the agents' control server and publish its connection file

This commit is contained in:
aiongg
2026-11-16 12:40:26 +00:00
parent 463acfe5bd
commit 6c8a1861bd
3 changed files with 406 additions and 2 deletions
+247
View File
@@ -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<u16>,
/// 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<LinkProblem>,
}
fn problem_text<S: Serializer>(problem: &Option<LinkProblem>, s: S) -> Result<S::Ok, S::Error> {
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<Receiver<ControlRequest>>,
/// 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 `<id>-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<PathBuf>,
app: String,
running: Option<Running>,
/// The server the launch options started; while it is there, the settings change nothing.
launch: Option<Listening>,
/// The settings of the last sync that ran, once one ran.
applied: Option<Option<AgentSettings>>,
retry_at: Option<Instant>,
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<PathBuf>, app: impl Into<String>) -> 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<ControlRequest>), 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);
}
}
+4
View File
@@ -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};
+155 -2
View File
@@ -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}));
}