acp: Automatically install gemini under Zed's data dir (#37054)

Closes: https://github.com/zed-industries/zed/issues/37089

Instead of looking for the gemini command on `$PATH`, by default we'll
install our own copy on demand under our data dir, as we already do for
language servers and debug adapters. This also means we can handle
keeping the binary up to date instead of prompting the user to upgrade.

Notes:

- The download is only triggered if you open a new Gemini thread
- Custom commands from `agent_servers.gemini` in settings are respected
as before
- A new `agent_servers.gemini.ignore_system_version` setting is added,
similar to the existing settings for language servers. It's `true` by
default, and setting it to `false` disables the automatic download and
makes Zed search `$PATH` as before.
- If `agent_servers.gemini.ignore_system_version` is `false` and no
binary is found on `$PATH`, we'll fall back to automatic installation.
If it's `false` and a binary is found, but the version is older than
v0.2.1, we'll show an error.

Release Notes:

- acp: By default, Zed will now download and use a private copy of the
Gemini CLI binary, instead of searching your `$PATH`. To make Zed search
your `$PATH` for Gemini CLI before attempting to download it, use the
following setting:

```
{
  "agent_servers": {
    "gemini": {
      "ignore_system_version": false
    }
  }
}
```

crates/agent_servers/src/agent_servers.rs

@@ -13,12 +13,19 @@ pub use gemini::*;
 pub use settings::*;
 
 use acp_thread::AgentConnection;
+use acp_thread::LoadError;
 use anyhow::Result;
+use anyhow::anyhow;
+use anyhow::bail;
 use collections::HashMap;
+use gpui::AppContext as _;
 use gpui::{App, AsyncApp, Entity, SharedString, Task};
+use node_runtime::VersionStrategy;
 use project::Project;
 use schemars::JsonSchema;
+use semver::Version;
 use serde::{Deserialize, Serialize};
+use std::str::FromStr as _;
 use std::{
     any::Any,
     path::{Path, PathBuf},
@@ -31,23 +38,118 @@ pub fn init(cx: &mut App) {
     settings::init(cx);
 }
 
+pub struct AgentServerDelegate {
+    project: Entity<Project>,
+    status_tx: watch::Sender<SharedString>,
+}
+
+impl AgentServerDelegate {
+    pub fn new(project: Entity<Project>, status_tx: watch::Sender<SharedString>) -> Self {
+        Self { project, status_tx }
+    }
+
+    pub fn project(&self) -> &Entity<Project> {
+        &self.project
+    }
+
+    fn get_or_npm_install_builtin_agent(
+        self,
+        binary_name: SharedString,
+        package_name: SharedString,
+        entrypoint_path: PathBuf,
+        settings: Option<BuiltinAgentServerSettings>,
+        minimum_version: Option<Version>,
+        cx: &mut App,
+    ) -> Task<Result<AgentServerCommand>> {
+        if let Some(settings) = &settings
+            && let Some(command) = settings.clone().custom_command()
+        {
+            return Task::ready(Ok(command));
+        }
+
+        let project = self.project;
+        let fs = project.read(cx).fs().clone();
+        let Some(node_runtime) = project.read(cx).node_runtime().cloned() else {
+            return Task::ready(Err(anyhow!("Missing node runtime")));
+        };
+        let mut status_tx = self.status_tx;
+
+        cx.spawn(async move |cx| {
+            if let Some(settings) = settings && !settings.ignore_system_version.unwrap_or(true) {
+                if let Some(bin) = find_bin_in_path(binary_name.clone(), &project, cx).await {
+                    return Ok(AgentServerCommand { path: bin, args: Vec::new(), env: Default::default() })
+                }
+            }
+
+            cx.background_spawn(async move {
+                let node_path = node_runtime.binary_path().await?;
+                let dir = paths::data_dir().join("external_agents").join(binary_name.as_str());
+                fs.create_dir(&dir).await?;
+                let local_executable_path = dir.join(entrypoint_path);
+                let command = AgentServerCommand {
+                    path: node_path,
+                    args: vec![local_executable_path.to_string_lossy().to_string()],
+                    env: Default::default(),
+                };
+
+                let installed_version = node_runtime
+                    .npm_package_installed_version(&dir, &package_name)
+                    .await?
+                    .filter(|version| {
+                        Version::from_str(&version)
+                            .is_ok_and(|version| Some(version) >= minimum_version)
+                    });
+
+                status_tx.send("Checking for latest version…".into())?;
+                let latest_version = match node_runtime.npm_package_latest_version(&package_name).await
+                {
+                    Ok(latest_version) => latest_version,
+                    Err(e) => {
+                        if let Some(installed_version) = installed_version {
+                            log::error!("{e}");
+                            log::warn!("failed to fetch latest version of {package_name}, falling back to cached version {installed_version}");
+                            return Ok(command);
+                        } else {
+                            bail!(e);
+                        }
+                    }
+                };
+
+                let should_install = node_runtime
+                    .should_install_npm_package(
+                        &package_name,
+                        &local_executable_path,
+                        &dir,
+                        VersionStrategy::Latest(&latest_version),
+                    )
+                    .await;
+
+                if should_install {
+                    status_tx.send("Installing latest version…".into())?;
+                    node_runtime
+                        .npm_install_packages(&dir, &[(&package_name, &latest_version)])
+                        .await?;
+                }
+
+                Ok(command)
+            }).await.map_err(|e| LoadError::FailedToInstall(e.to_string().into()).into())
+        })
+    }
+}
+
 pub trait AgentServer: Send {
     fn logo(&self) -> ui::IconName;
     fn name(&self) -> SharedString;
-    fn empty_state_headline(&self) -> SharedString;
-    fn empty_state_message(&self) -> SharedString;
     fn telemetry_id(&self) -> &'static str;
 
     fn connect(
         &self,
         root_dir: &Path,
-        project: &Entity<Project>,
+        delegate: AgentServerDelegate,
         cx: &mut App,
     ) -> Task<Result<Rc<dyn AgentConnection>>>;
 
     fn into_any(self: Rc<Self>) -> Rc<dyn Any>;
-
-    fn install_command(&self) -> Option<&'static str>;
 }
 
 impl dyn AgentServer {
@@ -81,15 +183,6 @@ impl std::fmt::Debug for AgentServerCommand {
     }
 }
 
-pub enum AgentServerVersion {
-    Supported,
-    Unsupported {
-        error_message: SharedString,
-        upgrade_message: SharedString,
-        upgrade_command: String,
-    },
-}
-
 #[derive(Deserialize, Serialize, Clone, PartialEq, Eq, JsonSchema)]
 pub struct AgentServerCommand {
     #[serde(rename = "command")]
@@ -104,23 +197,16 @@ impl AgentServerCommand {
         path_bin_name: &'static str,
         extra_args: &[&'static str],
         fallback_path: Option<&Path>,
-        settings: Option<AgentServerSettings>,
+        settings: Option<BuiltinAgentServerSettings>,
         project: &Entity<Project>,
         cx: &mut AsyncApp,
     ) -> Option<Self> {
-        if let Some(agent_settings) = settings {
-            Some(Self {
-                path: agent_settings.command.path,
-                args: agent_settings
-                    .command
-                    .args
-                    .into_iter()
-                    .chain(extra_args.iter().map(|arg| arg.to_string()))
-                    .collect(),
-                env: agent_settings.command.env,
-            })
+        if let Some(settings) = settings
+            && let Some(command) = settings.custom_command()
+        {
+            Some(command)
         } else {
-            match find_bin_in_path(path_bin_name, project, cx).await {
+            match find_bin_in_path(path_bin_name.into(), project, cx).await {
                 Some(path) => Some(Self {
                     path,
                     args: extra_args.iter().map(|arg| arg.to_string()).collect(),
@@ -143,7 +229,7 @@ impl AgentServerCommand {
 }
 
 async fn find_bin_in_path(
-    bin_name: &'static str,
+    bin_name: SharedString,
     project: &Entity<Project>,
     cx: &mut AsyncApp,
 ) -> Option<PathBuf> {
@@ -173,11 +259,11 @@ async fn find_bin_in_path(
     cx.background_executor()
         .spawn(async move {
             let which_result = if cfg!(windows) {
-                which::which(bin_name)
+                which::which(bin_name.as_str())
             } else {
                 let env = env_task.await.unwrap_or_default();
                 let shell_path = env.get("PATH").cloned();
-                which::which_in(bin_name, shell_path.as_ref(), root_dir.as_ref())
+                which::which_in(bin_name.as_str(), shell_path.as_ref(), root_dir.as_ref())
             };
 
             if let Err(which::Error::CannotFindBinaryPath) = which_result {

crates/agent_servers/src/claude.rs

@@ -36,7 +36,7 @@ use util::{ResultExt, debug_panic};
 
 use crate::claude::mcp_server::{ClaudeZedMcpServer, McpConfig};
 use crate::claude::tools::ClaudeTool;
-use crate::{AgentServer, AgentServerCommand, AllAgentServersSettings};
+use crate::{AgentServer, AgentServerCommand, AgentServerDelegate, AllAgentServersSettings};
 use acp_thread::{AcpThread, AgentConnection, AuthRequired, LoadError, MentionUri};
 
 #[derive(Clone)]
@@ -51,26 +51,14 @@ impl AgentServer for ClaudeCode {
         "Claude Code".into()
     }
 
-    fn empty_state_headline(&self) -> SharedString {
-        self.name()
-    }
-
-    fn empty_state_message(&self) -> SharedString {
-        "How can I help you today?".into()
-    }
-
     fn logo(&self) -> ui::IconName {
         ui::IconName::AiClaude
     }
 
-    fn install_command(&self) -> Option<&'static str> {
-        Some("npm install -g @anthropic-ai/claude-code@latest")
-    }
-
     fn connect(
         &self,
         _root_dir: &Path,
-        _project: &Entity<Project>,
+        _delegate: AgentServerDelegate,
         _cx: &mut App,
     ) -> Task<Result<Rc<dyn AgentConnection>>> {
         let connection = ClaudeAgentConnection {
@@ -112,7 +100,7 @@ impl AgentConnection for ClaudeAgentConnection {
             )
             .await
             else {
-                return Err(LoadError::NotInstalled.into());
+                return Err(anyhow!("Failed to find Claude Code binary"));
             };
 
             let api_key =
@@ -232,6 +220,7 @@ impl AgentConnection for ClaudeAgentConnection {
                                     LoadError::Unsupported {
                                         command: command.path.to_string_lossy().to_string().into(),
                                         current_version: version.to_string().into(),
+                                        minimum_version: "1.0.0".into(),
                                     }
                                 } else {
                                     LoadError::Exited { status }

crates/agent_servers/src/custom.rs

@@ -1,9 +1,8 @@
-use crate::{AgentServerCommand, AgentServerSettings};
+use crate::{AgentServerCommand, AgentServerDelegate};
 use acp_thread::AgentConnection;
 use anyhow::Result;
-use gpui::{App, Entity, SharedString, Task};
+use gpui::{App, SharedString, Task};
 use language_models::provider::anthropic::AnthropicLanguageModelProvider;
-use project::Project;
 use std::{path::Path, rc::Rc};
 use ui::IconName;
 
@@ -14,11 +13,8 @@ pub struct CustomAgentServer {
 }
 
 impl CustomAgentServer {
-    pub fn new(name: SharedString, settings: &AgentServerSettings) -> Self {
-        Self {
-            name,
-            command: settings.command.clone(),
-        }
+    pub fn new(name: SharedString, command: AgentServerCommand) -> Self {
+        Self { name, command }
     }
 }
 
@@ -35,18 +31,10 @@ impl crate::AgentServer for CustomAgentServer {
         IconName::Terminal
     }
 
-    fn empty_state_headline(&self) -> SharedString {
-        "No conversations yet".into()
-    }
-
-    fn empty_state_message(&self) -> SharedString {
-        format!("Start a conversation with {}", self.name).into()
-    }
-
     fn connect(
         &self,
         root_dir: &Path,
-        _project: &Entity<Project>,
+        _delegate: AgentServerDelegate,
         cx: &mut App,
     ) -> Task<Result<Rc<dyn AgentConnection>>> {
         let server_name = self.name();
@@ -70,10 +58,6 @@ impl crate::AgentServer for CustomAgentServer {
         })
     }
 
-    fn install_command(&self) -> Option<&'static str> {
-        None
-    }
-
     fn into_any(self: Rc<Self>) -> Rc<dyn std::any::Any> {
         self
     }

crates/agent_servers/src/e2e_tests.rs

@@ -1,4 +1,4 @@
-use crate::AgentServer;
+use crate::{AgentServer, AgentServerDelegate};
 use acp_thread::{AcpThread, AgentThreadEntry, ToolCall, ToolCallStatus};
 use agent_client_protocol as acp;
 use futures::{FutureExt, StreamExt, channel::mpsc, select};
@@ -471,12 +471,8 @@ pub async fn init_test(cx: &mut TestAppContext) -> Arc<FakeFs> {
         #[cfg(test)]
         crate::AllAgentServersSettings::override_global(
             crate::AllAgentServersSettings {
-                claude: Some(crate::AgentServerSettings {
-                    command: crate::claude::tests::local_command(),
-                }),
-                gemini: Some(crate::AgentServerSettings {
-                    command: crate::gemini::tests::local_command(),
-                }),
+                claude: Some(crate::claude::tests::local_command().into()),
+                gemini: Some(crate::gemini::tests::local_command().into()),
                 custom: collections::HashMap::default(),
             },
             cx,
@@ -494,8 +490,10 @@ pub async fn new_test_thread(
     current_dir: impl AsRef<Path>,
     cx: &mut TestAppContext,
 ) -> Entity<AcpThread> {
+    let delegate = AgentServerDelegate::new(project.clone(), watch::channel("".into()).0);
+
     let connection = cx
-        .update(|cx| server.connect(current_dir.as_ref(), &project, cx))
+        .update(|cx| server.connect(current_dir.as_ref(), delegate, cx))
         .await
         .unwrap();
 

crates/agent_servers/src/gemini.rs

@@ -2,12 +2,11 @@ use std::rc::Rc;
 use std::{any::Any, path::Path};
 
 use crate::acp::AcpConnection;
-use crate::{AgentServer, AgentServerCommand};
+use crate::{AgentServer, AgentServerDelegate};
 use acp_thread::{AgentConnection, LoadError};
 use anyhow::Result;
-use gpui::{App, Entity, SharedString, Task};
+use gpui::{App, SharedString, Task};
 use language_models::provider::google::GoogleLanguageModelProvider;
-use project::Project;
 use settings::SettingsStore;
 
 use crate::AllAgentServersSettings;
@@ -26,29 +25,16 @@ impl AgentServer for Gemini {
         "Gemini CLI".into()
     }
 
-    fn empty_state_headline(&self) -> SharedString {
-        self.name()
-    }
-
-    fn empty_state_message(&self) -> SharedString {
-        "Ask questions, edit files, run commands".into()
-    }
-
     fn logo(&self) -> ui::IconName {
         ui::IconName::AiGemini
     }
 
-    fn install_command(&self) -> Option<&'static str> {
-        Some("npm install --engine-strict -g @google/gemini-cli@latest")
-    }
-
     fn connect(
         &self,
         root_dir: &Path,
-        project: &Entity<Project>,
+        delegate: AgentServerDelegate,
         cx: &mut App,
     ) -> Task<Result<Rc<dyn AgentConnection>>> {
-        let project = project.clone();
         let root_dir = root_dir.to_path_buf();
         let server_name = self.name();
         cx.spawn(async move |cx| {
@@ -56,12 +42,19 @@ impl AgentServer for Gemini {
                 settings.get::<AllAgentServersSettings>(None).gemini.clone()
             })?;
 
-            let Some(mut command) =
-                AgentServerCommand::resolve("gemini", &[ACP_ARG], None, settings, &project, cx)
-                    .await
-            else {
-                return Err(LoadError::NotInstalled.into());
-            };
+            let mut command = cx
+                .update(|cx| {
+                    delegate.get_or_npm_install_builtin_agent(
+                        Self::BINARY_NAME.into(),
+                        Self::PACKAGE_NAME.into(),
+                        format!("node_modules/{}/dist/index.js", Self::PACKAGE_NAME).into(),
+                        settings,
+                        Some("0.2.1".parse().unwrap()),
+                        cx,
+                    )
+                })?
+                .await?;
+            command.args.push("--experimental-acp".into());
 
             if let Some(api_key) = cx.update(GoogleLanguageModelProvider::api_key)?.await.ok() {
                 command
@@ -87,12 +80,8 @@ impl AgentServer for Gemini {
                         if !connection.prompt_capabilities().image {
                             return Err(LoadError::Unsupported {
                                 current_version: current_version.into(),
-                                command: format!(
-                                    "{} {}",
-                                    command.path.to_string_lossy(),
-                                    command.args.join(" ")
-                                )
-                                .into(),
+                                command: command.path.to_string_lossy().to_string().into(),
+                                minimum_version: Self::MINIMUM_VERSION.into(),
                             }
                             .into());
                         }
@@ -114,13 +103,16 @@ impl AgentServer for Gemini {
                     let (version_output, help_output) =
                         futures::future::join(version_fut, help_fut).await;
 
-                    let current_version = String::from_utf8(version_output?.stdout)?;
+                    let current_version = std::str::from_utf8(&version_output?.stdout)?
+                        .trim()
+                        .to_string();
                     let supported = String::from_utf8(help_output?.stdout)?.contains(ACP_ARG);
 
                     if !supported {
                         return Err(LoadError::Unsupported {
                             current_version: current_version.into(),
                             command: command.path.to_string_lossy().to_string().into(),
+                            minimum_version: Self::MINIMUM_VERSION.into(),
                         }
                         .into());
                     }
@@ -136,17 +128,11 @@ impl AgentServer for Gemini {
 }
 
 impl Gemini {
-    pub fn binary_name() -> &'static str {
-        "gemini"
-    }
+    const PACKAGE_NAME: &str = "@google/gemini-cli";
 
-    pub fn install_command() -> &'static str {
-        "npm install --engine-strict -g @google/gemini-cli@latest"
-    }
+    const MINIMUM_VERSION: &str = "0.2.1";
 
-    pub fn upgrade_command() -> &'static str {
-        "npm install -g @google/gemini-cli@latest"
-    }
+    const BINARY_NAME: &str = "gemini";
 }
 
 #[cfg(test)]

crates/agent_servers/src/settings.rs

@@ -1,3 +1,5 @@
+use std::path::PathBuf;
+
 use crate::AgentServerCommand;
 use anyhow::Result;
 use collections::HashMap;
@@ -12,16 +14,62 @@ pub fn init(cx: &mut App) {
 
 #[derive(Default, Deserialize, Serialize, Clone, JsonSchema, Debug)]
 pub struct AllAgentServersSettings {
-    pub gemini: Option<AgentServerSettings>,
-    pub claude: Option<AgentServerSettings>,
+    pub gemini: Option<BuiltinAgentServerSettings>,
+    pub claude: Option<BuiltinAgentServerSettings>,
 
     /// Custom agent servers configured by the user
     #[serde(flatten)]
-    pub custom: HashMap<SharedString, AgentServerSettings>,
+    pub custom: HashMap<SharedString, CustomAgentServerSettings>,
+}
+
+#[derive(Default, Deserialize, Serialize, Clone, JsonSchema, Debug, PartialEq)]
+pub struct BuiltinAgentServerSettings {
+    /// Absolute path to a binary to be used when launching this agent.
+    ///
+    /// This can be used to run a specific binary without automatic downloads or searching `$PATH`.
+    #[serde(rename = "command")]
+    pub path: Option<PathBuf>,
+    /// If a binary is specified in `command`, it will be passed these arguments.
+    pub args: Option<Vec<String>>,
+    /// If a binary is specified in `command`, it will be passed these environment variables.
+    pub env: Option<HashMap<String, String>>,
+    /// Whether to skip searching `$PATH` for an agent server binary when
+    /// launching this agent.
+    ///
+    /// This has no effect if a `command` is specified. Otherwise, when this is
+    /// `false`, Zed will search `$PATH` for an agent server binary and, if one
+    /// is found, use it for threads with this agent. If no agent binary is
+    /// found on `$PATH`, Zed will automatically install and use its own binary.
+    /// When this is `true`, Zed will not search `$PATH`, and will always use
+    /// its own binary.
+    ///
+    /// Default: true
+    pub ignore_system_version: Option<bool>,
+}
+
+impl BuiltinAgentServerSettings {
+    pub(crate) fn custom_command(self) -> Option<AgentServerCommand> {
+        self.path.map(|path| AgentServerCommand {
+            path,
+            args: self.args.unwrap_or_default(),
+            env: self.env,
+        })
+    }
+}
+
+impl From<AgentServerCommand> for BuiltinAgentServerSettings {
+    fn from(value: AgentServerCommand) -> Self {
+        BuiltinAgentServerSettings {
+            path: Some(value.path),
+            args: Some(value.args),
+            env: value.env,
+            ..Default::default()
+        }
+    }
 }
 
 #[derive(Deserialize, Serialize, Clone, JsonSchema, Debug, PartialEq)]
-pub struct AgentServerSettings {
+pub struct CustomAgentServerSettings {
     #[serde(flatten)]
     pub command: AgentServerCommand,
 }