SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Assistant: say when an installed agent can't start, and how to reinstall it (#9034) (#9655)
PaddleStroked61ec6048019
diff --git a/assets/locales/pending/agent-chat-cannot-start.json b/assets/locales/pending/agent-chat-cannot-start.jsonnew file mode 100644index 0000000000..933a7a1f9c--- /dev/null+++ b/assets/locales/pending/agent-chat-cannot-start.json@@ -0,0 +1,38 @@+{+ "en": {+ "ui.agent_chat_cannot_start": "Installed, but it does not start: {error}",+ "ui.agent_chat_reinstall": "{agent} is installed ({program}), but it did not start when SolidCraft checked it: {error}\nIts installation may be incomplete, or made for another kind of computer. Install it again with `{install}`, check that it prints its version in a terminal, then press Refresh."+ },+ "ar": {+ "ui.agent_chat_cannot_start": "مثبّت، لكنه لا يبدأ: {error}",+ "ui.agent_chat_reinstall": "{agent} مثبّت ({program})، لكنه لم يبدأ عندما فحصه SolidCraft: {error}\nقد يكون تثبيته غير مكتمل، أو مُعدًّا لنوع آخر من الحواسيب. ثبّته من جديد بالأمر `{install}`، وتحقّق من أنه يعرض رقم إصداره في الطرفية، ثم اضغط تحديث."+ },+ "de": {+ "ui.agent_chat_cannot_start": "Installiert, startet aber nicht: {error}",+ "ui.agent_chat_reinstall": "{agent} ist installiert ({program}), ist aber beim Prüfen durch SolidCraft nicht gestartet: {error}\nDie Installation ist vielleicht unvollständig oder für einen anderen Computertyp. Installieren Sie es erneut mit `{install}`, prüfen Sie, dass es im Terminal seine Version ausgibt, und klicken Sie dann auf Aktualisieren."+ },+ "fr": {+ "ui.agent_chat_cannot_start": "Installé, mais ne démarre pas : {error}",+ "ui.agent_chat_reinstall": "{agent} est installé ({program}), mais n'a pas démarré quand SolidCraft l'a vérifié : {error}\nSon installation est peut-être incomplète, ou prévue pour un autre type d'ordinateur. Réinstallez-le avec `{install}`, vérifiez qu'il affiche sa version dans un terminal, puis cliquez sur Actualiser."+ },+ "he": {+ "ui.agent_chat_cannot_start": "מותקן, אך אינו מופעל: {error}",+ "ui.agent_chat_reinstall": "{agent} מותקן ({program}), אך לא הופעל כאשר SolidCraft בדק אותו: {error}\nייתכן שההתקנה שלו חלקית, או שהיא מיועדת לסוג אחר של מחשב. יש להתקין אותו מחדש עם `{install}`, לוודא שהוא מציג את הגרסה שלו במסוף, ואז ללחוץ על רענון."+ },+ "ja": {+ "ui.agent_chat_cannot_start": "インストールされていますが、起動しません: {error}",+ "ui.agent_chat_reinstall": "{agent} はインストールされています ({program}) が、SolidCraft が確認したときに起動しませんでした: {error}\nインストールが不完全か、別の種類のコンピューター用の可能性があります。`{install}` で再インストールし、ターミナルでバージョンが表示されることを確認してから、再検索を押してください。"+ },+ "ko": {+ "ui.agent_chat_cannot_start": "설치되어 있지만 시작되지 않습니다: {error}",+ "ui.agent_chat_reinstall": "{agent}이(가) 설치되어 있지만({program}) SolidCraft가 확인할 때 시작되지 않았습니다: {error}\n설치가 완료되지 않았거나 다른 종류의 컴퓨터용일 수 있습니다. `{install}`(으)로 다시 설치하고, 터미널에서 버전이 출력되는지 확인한 뒤 새로 고침을 누르세요."+ },+ "vi": {+ "ui.agent_chat_cannot_start": "Đã cài đặt nhưng không khởi động được: {error}",+ "ui.agent_chat_reinstall": "{agent} đã được cài đặt ({program}) nhưng không khởi động khi SolidCraft kiểm tra: {error}\nBản cài đặt có thể chưa hoàn tất, hoặc dành cho loại máy tính khác. Hãy cài lại bằng `{install}`, kiểm tra rằng nó in ra phiên bản trong terminal, rồi nhấn Làm mới."+ },+ "zh": {+ "ui.agent_chat_cannot_start": "已安装,但无法启动:{error}",+ "ui.agent_chat_reinstall": "{agent} 已安装({program}),但 SolidCraft 检查时它没有启动:{error}\n它的安装可能不完整,或是为另一种计算机准备的。请用 `{install}` 重新安装,确认它能在终端中显示版本号,然后点击刷新。"+ }+}diff --git a/crates/ui-egui/src/agent_chat/agents.rs b/crates/ui-egui/src/agent_chat/agents.rsindex c05102b8df..f5ad5e0d72 100644--- a/crates/ui-egui/src/agent_chat/agents.rs+++ b/crates/ui-egui/src/agent_chat/agents.rs@@ -167,6 +167,10 @@ pub struct Entry {pub key: bool,/// API: seconds one model request may take (in range).pub request_timeout_s: u64,+ /// Found installed, but its program didn't start when asked its version: why (#9034).+ pub problem: Option<String>,+ /// Found installed: the command that installs it again.+ pub install: &'static str,}impl Entry {@@ -183,18 +187,31 @@ impl Entry {model: c.model.clone(),key: c.key,request_timeout_s: c.request_timeout_s.clamp(MIN_REQUEST_TIMEOUT_S, MAX_REQUEST_TIMEOUT_S),+ problem: None,+ install: "",}}- /// A short line under the name: the version, the model, or the command.+ /// A short line under the name: the version, the model, the command, or why it can't start.pub fn detail(&self) -> String {match self.kind {Kind::Api | Kind::Anthropic => format!("{} · {}", self.model, self.base_url),- Kind::Acp => match &self.version {- Some(v) => v.clone(),- None => super::panel::short_command(&self.argv.join(" ")),+ Kind::Acp => match (&self.problem, &self.version) {+ (Some(p), _) => crate::i18n::format("ui.agent_chat_cannot_start", &[("error", p)]),+ (None, Some(v)) => v.clone(),+ (None, None) => super::panel::short_command(&self.argv.join(" ")),},}}+ /// What to tell someone starting an agent that was found but didn't start (#9034): the reason,+ /// and how to install it again. `None` when nothing was seen wrong.+ pub fn problem_hint(&self) -> Option<String> {+ let problem = self.problem.as_deref()?;+ let program = self.argv.first().map(String::as_str).unwrap_or_default();+ Some(crate::i18n::format(+ "ui.agent_chat_reinstall",+ &[("agent", &self.name), ("program", program), ("error", problem), ("install", self.install)],+ ))+ }}/// Every agent the chat can use: the installed ones found, then the ones the user added.@@ -214,6 +231,8 @@ pub fn entries(app: &crate::SolveApp) -> Vec<Entry> {model: String::new(),key: false,request_timeout_s: DEFAULT_REQUEST_TIMEOUT_S,+ problem: f.problem.clone(),+ install: f.install,}));}out.extend(app.preferences.agents.iter().map(Entry::from_config));diff --git a/crates/ui-egui/src/agent_chat/discover.rs b/crates/ui-egui/src/agent_chat/discover.rsindex ace05c3c29..24792f42c5 100644--- a/crates/ui-egui/src/agent_chat/discover.rs+++ b/crates/ui-egui/src/agent_chat/discover.rs@@ -187,6 +187,11 @@ pub struct Found {pub argv: Vec<String>,pub version: Option<String>,pub login: Login,+ /// Why its program doesn't start (#9034): asked for `--version`, it failed without printing+ /// one, as the `opencode.exe` of an npm install whose setup script didn't run does on Windows.+ pub problem: Option<String>,+ /// Its one-line install hint, to reinstall it with.+ pub install: &'static str,}#[derive(Clone, Debug, Default)]@@ -288,8 +293,24 @@ pub(super) fn command_for(program: &Path) -> Command {cmd}-/// `program --version`'s first line, or `None` after `limit` (the probe is then stopped).-fn version(program: &Path, limit: Duration) -> Option<String> {+/// What `program --version` showed.+#[derive(Debug, Default, PartialEq)]+struct Probe {+ /// Its version number, from the first line it printed.+ version: Option<String>,+ /// Why it can't start: the system refused to start it, or it failed and printed nothing but+ /// an error. A probe that runs out of time says nothing either way (a slow machine).+ problem: Option<String>,+}++/// How long an agent is given to answer `--version`.+const PROBE_LIMIT: Duration = Duration::from_secs(3);++/// The longest reason kept from a failed probe.+const PROBLEM_CHARS: usize = 300;++/// Ask `program --version`; it is stopped after `limit`.+fn probe(program: &Path, limit: Duration) -> Probe {let mut cmd = command_for(program);#[cfg(windows)]{@@ -297,23 +318,50 @@ fn version(program: &Path, limit: Duration) -> Option<String> {// CREATE_NO_WINDOW: probing a console agent doesn't flash a terminal window.cmd.creation_flags(0x0800_0000);}- let mut child = cmd.arg("--version").stdin(Stdio::null()).stdout(Stdio::piped()).stderr(Stdio::null()).spawn().ok()?;+ let mut child = match cmd.arg("--version").stdin(Stdio::null()).stdout(Stdio::piped()).stderr(Stdio::piped()).spawn() {+ Ok(child) => child,+ // Windows: "not a valid Win32 application" (193), "not compatible with the version of+ // Windows you're running" (216); elsewhere: not allowed to run it, an unknown format.+ // Windows leaves the program's place in its message as `%1`.+ Err(e) => return Probe { version: None, problem: Some(cut(&e.to_string().replace("%1", &program.display().to_string()))) },+ };let start = Instant::now();- loop {+ let status = loop {match child.try_wait() {- Ok(Some(_)) => break,+ Ok(Some(status)) => break status,Ok(None) if start.elapsed() < limit => std::thread::sleep(Duration::from_millis(20)),_ => {let _ = child.kill();let _ = child.wait();- return None;+ return Probe::default();}}+ };+ let out = read_capped(child.stdout.take());+ if let Some(line) = out.lines().map(str::trim).find(|l| !l.is_empty()) {+ return Probe { version: Some(version_of(line)), problem: None };+ }+ if status.success() {+ return Probe::default();+ }+ // Through a `.cmd` shim, Windows' own refusal arrives on stderr with a failing exit code.+ let err = read_capped(child.stderr.take());+ let reason = err.lines().map(str::trim).find(|l| !l.is_empty()).map(str::to_string).unwrap_or_else(|| status.to_string());+ Probe { version: None, problem: Some(cut(&reason)) }+}++/// What a finished probe wrote on a pipe, up to 64 KiB.+fn read_capped(pipe: Option<impl std::io::Read>) -> String {+ let mut bytes = Vec::new();+ if let Some(p) = pipe {+ let _ = std::io::Read::read_to_end(&mut p.take(64 * 1024), &mut bytes);}- let mut out = String::new();- std::io::Read::read_to_string(&mut child.stdout.take()?, &mut out).ok()?;- let line = out.lines().map(str::trim).find(|l| !l.is_empty())?;- Some(version_of(line))+ String::from_utf8_lossy(&bytes).into_owned()+}++/// `text`, cut short.+fn cut(text: &str) -> String {+ text.chars().take(PROBLEM_CHARS).collect()}/// The version number in a `--version` line (`codex-cli 0.162.1`, `2.1.295 (Claude Code)`,@@ -342,10 +390,10 @@ fn login_of(k: &Known, home: Option<&Path>) -> Login {/// Look for every known agent. Blocking (each probe has a time limit): run it off the UI thread.pub fn detect() -> Detection {- detect_in(&search_dirs(), home().as_deref())+ detect_in(&search_dirs(), home().as_deref(), PROBE_LIMIT)}-fn detect_in(dirs: &[PathBuf], home: Option<&Path>) -> Detection {+fn detect_in(dirs: &[PathBuf], home: Option<&Path>, limit: Duration) -> Detection {let t0 = Instant::now();let mut d = Detection::default();for k in KNOWN {@@ -358,8 +406,8 @@ fn detect_in(dirs: &[PathBuf], home: Option<&Path>) -> Detection {let login = login_of(k, home);let mut argv = vec![path.to_string_lossy().into_owned()];argv.extend(k.args.iter().map(|a| a.to_string()));- let version = if k.reports_version { version(&path, Duration::from_secs(3)) } else { None };- d.found.push(Found { id: k.id, name: k.name, version, argv, login });+ let Probe { version, problem } = if k.reports_version { probe(&path, limit) } else { Probe::default() };+ d.found.push(Found { id: k.id, name: k.name, version, argv, login, problem, install: k.install });}d.took_ms = u64::try_from(t0.elapsed().as_millis()).unwrap_or(u64::MAX);d@@ -544,7 +592,7 @@ mod tests {};let ids = |d: &Detection| (d.found.iter().map(|f| f.id).collect::<Vec<_>>(), d.missing.iter().map(|m| m.id).collect::<Vec<_>>());- let none = detect_in(std::slice::from_ref(&root), None);+ let none = detect_in(std::slice::from_ref(&root), None, PROBE_LIMIT);let (found, missing) = ids(&none);assert!(found.is_empty());assert!(missing.contains(&"antigravity") && !missing.contains(&"gemini"), "{missing:?}");@@ -554,7 +602,7 @@ mod tests {run("gemini", "echo gemini 0.64.0");// A server that would take seconds to answer `--version`, which Antigravity is never asked.run("agy_acp_server.par", "sleep 30");- let both = detect_in(std::slice::from_ref(&root), None);+ let both = detect_in(std::slice::from_ref(&root), None, PROBE_LIMIT);let (found, missing) = ids(&both);assert_eq!(found, ["antigravity", "gemini"]);assert!(!missing.contains(&"antigravity") && !missing.contains(&"gemini"), "{missing:?}");@@ -573,6 +621,73 @@ mod tests {assert_eq!(KNOWN.first().map(|k| k.id), Some("claude"), "the Claude Code adapter is the default");}+ /// #9034: npm installed OpenCode without running its setup script, so the `opencode.exe` its+ /// `.cmd` shim starts is one Windows refuses. It is still found (its shim is there), with+ /// the system's reason and the command to install it again, while an agent that answers+ /// `--version`, or ends without a word but successfully, has no problem.+ #[test]+ fn an_agent_that_does_not_start_is_found_with_the_reason() {+ let root = std::env::temp_dir().join(format!("sc-agent-broken-{}", std::process::id()));+ let _ = std::fs::remove_dir_all(&root);+ std::fs::create_dir_all(&root).unwrap();+ #[cfg(windows)]+ {+ // npm's layout: the shim in the prefix, the program under node_modules.+ let bin = root.join("node_modules").join("opencode-ai").join("bin");+ std::fs::create_dir_all(&bin).unwrap();+ std::fs::write(bin.join("opencode.exe"), "not a program for this computer").unwrap();+ std::fs::write(root.join("opencode.cmd"), "@ECHO off\r\n\"%~dp0\\node_modules\\opencode-ai\\bin\\opencode.exe\" %*\r\n").unwrap();+ // Started directly, the system itself refuses it.+ std::fs::write(root.join("copilot.exe"), "not a program either").unwrap();+ std::fs::write(root.join("grok.cmd"), "@echo off\r\nexit /b 3\r\n").unwrap();+ std::fs::write(root.join("qwen.cmd"), "@echo off\r\necho 0.1.2\r\n").unwrap();+ std::fs::write(root.join("goose.cmd"), "@echo off\r\n").unwrap();+ }+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ let run = |name: &str, body: &str| {+ let path = root.join(name);+ std::fs::write(&path, format!("#!/bin/sh\n{body}\n")).unwrap();+ std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();+ };+ run("opencode", "echo 'cannot execute binary file: Exec format error' >&2; exit 126");+ // Not allowed to run: the system refuses it.+ std::fs::write(root.join("copilot"), "not a program").unwrap();+ std::fs::set_permissions(root.join("copilot"), std::fs::Permissions::from_mode(0o644)).unwrap();+ run("grok", "exit 3");+ run("qwen", "echo 0.1.2");+ run("goose", "true");+ }+ // A generous limit: on a loaded machine `cmd` alone can take longer than three seconds to+ // start, and a probe that runs out of time reports nothing.+ let d = detect_in(std::slice::from_ref(&root), None, Duration::from_secs(60));+ let found = |id: &str| d.found.iter().find(|f| f.id == id).unwrap_or_else(|| panic!("{id} not found: {:?}", d.found));++ let opencode = found("opencode");+ assert_eq!(opencode.version, None);+ assert!(opencode.problem.as_deref().is_some_and(|p| !p.trim().is_empty()), "{opencode:?}");+ assert_eq!(opencode.install, "npm install -g opencode-ai");+ assert_eq!(opencode.argv.get(1).map(String::as_str), Some("acp"), "still offered with its ACP arguments");+ let copilot = found("copilot");+ assert!(copilot.problem.as_deref().is_some_and(|p| !p.trim().is_empty()), "{copilot:?}");+ #[cfg(windows)]+ assert!(+ copilot.problem.as_deref().is_some_and(|p| (p.contains("216") || p.contains("193")) && p.contains("copilot.exe") && !p.contains("%1")),+ "the system's reason, naming the program: {copilot:?}"+ );+ // Silent but failing: the exit status is the reason.+ let grok = found("grok");+ assert!(grok.problem.as_deref().is_some_and(|p| p.contains('3')), "{grok:?}");++ let qwen = found("qwen");+ assert_eq!((qwen.version.as_deref(), qwen.problem.as_deref()), (Some("0.1.2"), None));+ let goose = found("goose");+ assert_eq!((goose.version.as_deref(), goose.problem.as_deref()), (None, None));+ assert!(d.found.iter().all(|f| f.problem.as_ref().is_none_or(|p| p.chars().count() <= PROBLEM_CHARS)));+ let _ = std::fs::remove_dir_all(root);+ }+/// A launcher can start SolidCraft with a PATH that lacks Node (#9297). On Windows, Node's/// install folders are searched after it, so `node` is found, and an agent started with these/// folders as its PATH (`command_for`) finds it too.@@ -623,7 +738,7 @@ mod tests {let agent = find_in("solidcraft-test-agent", &search_dirs()).unwrap();// Generous limits: both answer at once, but a whole test run on a loaded machine// can keep `env`, the shell and the script from starting within 3 s.- assert_eq!(version(&agent, Duration::from_secs(20)).as_deref(), Some("1.2.3"));+ assert_eq!(probe(&agent, Duration::from_secs(20)).version.as_deref(), Some("1.2.3"));let mut p = AgentProcess::spawn(&[agent.to_string_lossy().into_owned()], &root, &[], || {}).unwrap();let message = serde_json::json!({"id": 1, "method": "initialize"});p.send(&message);diff --git a/crates/ui-egui/src/agent_chat/mod.rs b/crates/ui-egui/src/agent_chat/mod.rsindex 30fb5b07f5..3275803696 100644--- a/crates/ui-egui/src/agent_chat/mod.rs+++ b/crates/ui-egui/src/agent_chat/mod.rs@@ -936,6 +936,11 @@ pub fn connect(app: &mut SolveApp, ctx: &egui::Context) {} else if cli.is_none() {chat.notice(tr("ui.agent_chat_no_cli"), true);}+ // Found, but it failed when asked its version (#9034): say why and how to reinstall it before+ // the system's own message arrives. It is still started, in case it only lacks `--version`.+ if let Some(hint) = entry.problem_hint() {+ chat.notice(hint, true);+ }let bridge = cli.zip(chat.tools_port).map(|(cli, port)| acp::McpBridge { cli, port });chat.tools_available = Some(bridge.is_some());let wake = ctx.clone();@@ -2225,7 +2230,7 @@ pub fn status(app: &SolveApp) -> Value {#[cfg(not(target_arch = "wasm32"))]let detection = c.detection.as_ref().map(|d| {json!({- "found": d.found.iter().map(|f| json!({"id": f.id, "name": f.name, "argv": f.argv, "version": f.version, "login": f.login.id()})).collect::<Vec<_>>(),+ "found": d.found.iter().map(|f| json!({"id": f.id, "name": f.name, "argv": f.argv, "version": f.version, "login": f.login.id(), "problem": f.problem})).collect::<Vec<_>>(),"missing": d.missing.iter().map(|m| json!({"id": m.id, "install": m.install})).collect::<Vec<_>>(),"ms": d.took_ms,})@@ -2242,7 +2247,7 @@ pub fn status(app: &SolveApp) -> Value {"openAtStart": app.preferences.agent_chat_open_at_start,"lastAgent": app.preferences.agent_last,"permissions": app.preferences.ai_permissions.id(),- "agents": agents::entries(app).iter().map(|e| json!({"id": e.id, "name": e.name, "kind": e.kind.id(), "found": e.found, "version": e.version, "login": e.login, "request_timeout_s": e.kind.is_api().then_some(e.request_timeout_s)})).collect::<Vec<_>>(),+ "agents": agents::entries(app).iter().map(|e| json!({"id": e.id, "name": e.name, "kind": e.kind.id(), "found": e.found, "version": e.version, "login": e.login, "problem": e.problem, "request_timeout_s": e.kind.is_api().then_some(e.request_timeout_s)})).collect::<Vec<_>>(),"currentAgent": agents::current(app).map(|e| e.id),"models": c.models.iter().map(|m| json!({"id": m.id, "name": m.name, "description": m.description})).collect::<Vec<_>>(),"model": c.model,diff --git a/crates/ui-egui/src/agent_chat/settings.rs b/crates/ui-egui/src/agent_chat/settings.rsindex 86b78a01ec..92d3b3bc77 100644--- a/crates/ui-egui/src/agent_chat/settings.rs+++ b/crates/ui-egui/src/agent_chat/settings.rs@@ -711,6 +711,8 @@ pub fn dialog(app: &mut SolveApp, ctx: &egui::Context) {model: s.model.trim().to_string(),key: false,request_timeout_s: s.request_timeout_s,+ problem: None,+ install: "",};let key = Some(s.key.trim().to_string()).filter(|k| !k.is_empty());let result = match url {diff --git a/crates/ui-egui/src/agent_chat/tests.rs b/crates/ui-egui/src/agent_chat/tests.rsindex de6a329915..c99c9c7ac1 100644--- a/crates/ui-egui/src/agent_chat/tests.rs+++ b/crates/ui-egui/src/agent_chat/tests.rs@@ -17,6 +17,8 @@ fn app_with_discovered_login() -> SolveApp {argv: vec!["qwen".into(), "--acp".into()],version: None,login: discover::Login::LooksLoggedIn,+ problem: None,+ install: "npm install -g @qwen-code/qwen-code",}],..Default::default()});@@ -2435,6 +2437,34 @@ fn a_connection_that_never_gets_ready_says_connection_failed_and_offers_retry()assert_eq!(app.agent_chat.state(), State::Failed);assert!(app.preferences.agent_last.is_empty(), "only an agent that started is remembered");+ // A found agent that failed its version check (#9034): the picker says it doesn't start, and+ // connecting says why and how to install it again, besides the system's own message.+ let mut app = SolveApp::new(solidcraft_engine::Session::default(), crate::Services::default());+ let reason = "This version of opencode.exe is not compatible with the version of Windows you're running.";+ app.agent_chat.detection = Some(discover::Detection {+ found: vec![discover::Found {+ id: "opencode",+ name: "OpenCode",+ argv: vec!["solidcraft-no-such-agent-9034".into(), "acp".into()],+ version: None,+ login: discover::Login::Unknown,+ problem: Some(reason.into()),+ install: "npm install -g opencode-ai",+ }],+ ..Default::default()+ });+ let entry = agents::current(&app).unwrap();+ assert!(entry.detail().contains(reason), "{}", entry.detail());+ connect(&mut app, &ctx);+ assert_eq!(app.agent_chat.state(), State::Failed);+ let told = |needle: &str| app.agent_chat.items.iter().any(|i| matches!(i, Item::Notice { text, error: true } if text.contains(needle)));+ assert!(told(reason) && told("npm install -g opencode-ai") && told("OpenCode"), "{:?}", app.agent_chat.items);+ assert_eq!(status(&app)["agents"][0]["problem"], reason);+ // One that answered has nothing to say.+ let mut fine = entry.clone();+ fine.problem = None;+ assert_eq!(fine.problem_hint(), None);+// No agent at all: the picker opens on what to install.let mut app = SolveApp::new(solidcraft_engine::Session::default(), crate::Services::default());app.agent_chat.detection = Some(discover::Detection::default());diff --git a/docs/agent-chat.md b/docs/agent-chat.mdindex 7341489c25..895b0a87cb 100644--- a/docs/agent-chat.md+++ b/docs/agent-chat.md@@ -187,7 +187,12 @@ doesn't change the last known login state.| GitHub Copilot CLI, Qwen Code, goose | listed with their install command when missing |The panel lists agents that aren't installed with their install command and a **Copy** button.-**Refresh** looks again after you install one. **Test** starts an agent briefly, asks it for a+**Refresh** looks again after you install one. An agent whose program is there but fails its+`--version` check without printing a version (an install that didn't finish, such as an npm+install whose setup script didn't run, or a program built for another kind of computer) is+still listed, marked **does not start** with the system's reason. Connecting to it first says+why and gives its install command; reinstall it until `--version` works in a terminal, then+press **Refresh**. A check that runs out of time is not counted as a failure. **Test** starts an agent briefly, asks it for asession and ends it again.### Flatpak