Assistant: say when an installed agent can't start, and how to reinstall it (#9034) (#9655)

* claim: #9034

* Assistant: say when an installed agent can't start, and how to reinstall it (#9034)

An agent whose program is found but fails its `--version` check without
printing a version (npm's opencode.exe left as a placeholder when the
package's setup script did not run, which Windows refuses with "not
compatible with the version of Windows you're running") was listed like
a working one, and connecting only said "The agent stopped." with the
system's message.

Discovery now keeps why the program did not start: the spawn error
(Windows' `%1` replaced with the program) or, through a `.cmd` shim, the
first stderr line or the exit status. A probe that times out still says
nothing. The picker shows "Installed, but it does not start: ...", and
connecting first explains it with the agent's install command and Refresh.
The control channel status carries `problem`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
PaddleStrokeandClaude Opus 5.5 authored and GitHub committed 2026-10-31 01:52:59 +00:00
1 parent c4538c53e1
commit d61ec60480
7 files changed
+238 -24

No files matched your search

@@ -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}` 重新安装,确认它能在终端中显示版本号,然后点击刷新。"
}
}
+23 -4
View File
@@ -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));
+132 -17
View File
@@ -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 };
}
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))
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);
}
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);
+7 -2
View File
@@ -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,
@@ -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 {
+30
View File
@@ -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());
+6 -1
View File
@@ -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 a
session and ends it again.
### Flatpak