1use agent_client_protocol as acp;
2use anyhow::Result;
3use futures::{FutureExt as _, future::Shared};
4use gpui::{App, AppContext, Entity, SharedString, Task};
5use project::{Project, terminals::TerminalKind};
6use schemars::JsonSchema;
7use serde::{Deserialize, Serialize};
8use std::{
9 path::{Path, PathBuf},
10 sync::Arc,
11};
12use util::{ResultExt, get_system_shell, markdown::MarkdownInlineCode};
13
14use crate::{AgentTool, ToolCallEventStream};
15
16const COMMAND_OUTPUT_LIMIT: usize = 16 * 1024;
17
18/// Executes a shell one-liner and returns the combined output.
19///
20/// This tool spawns a process using the user's shell, reads from stdout and stderr (preserving the order of writes), and returns a string with the combined output result.
21///
22/// The output results will be shown to the user already, only list it again if necessary, avoid being redundant.
23///
24/// Make sure you use the `cd` parameter to navigate to one of the root directories of the project. NEVER do it as part of the `command` itself, otherwise it will error.
25///
26/// Do not use this tool for commands that run indefinitely, such as servers (like `npm run start`, `npm run dev`, `python -m http.server`, etc) or file watchers that don't terminate on their own.
27///
28/// Remember that each invocation of this tool will spawn a new shell process, so you can't rely on any state from previous invocations.
29#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
30pub struct TerminalToolInput {
31 /// The one-liner command to execute.
32 command: String,
33 /// Working directory for the command. This must be one of the root directories of the project.
34 cd: String,
35}
36
37pub struct TerminalTool {
38 project: Entity<Project>,
39 determine_shell: Shared<Task<String>>,
40}
41
42impl TerminalTool {
43 pub fn new(project: Entity<Project>, cx: &mut App) -> Self {
44 let determine_shell = cx.background_spawn(async move {
45 if cfg!(windows) {
46 return get_system_shell();
47 }
48
49 if which::which("bash").is_ok() {
50 log::info!("agent selected bash for terminal tool");
51 "bash".into()
52 } else {
53 let shell = get_system_shell();
54 log::info!("agent selected {shell} for terminal tool");
55 shell
56 }
57 });
58 Self {
59 project,
60 determine_shell: determine_shell.shared(),
61 }
62 }
63}
64
65impl AgentTool for TerminalTool {
66 type Input = TerminalToolInput;
67 type Output = String;
68
69 fn name(&self) -> SharedString {
70 "terminal".into()
71 }
72
73 fn kind(&self) -> acp::ToolKind {
74 acp::ToolKind::Execute
75 }
76
77 fn initial_title(&self, input: Result<Self::Input, serde_json::Value>) -> SharedString {
78 if let Ok(input) = input {
79 let mut lines = input.command.lines();
80 let first_line = lines.next().unwrap_or_default();
81 let remaining_line_count = lines.count();
82 match remaining_line_count {
83 0 => MarkdownInlineCode(first_line).to_string().into(),
84 1 => MarkdownInlineCode(&format!(
85 "{} - {} more line",
86 first_line, remaining_line_count
87 ))
88 .to_string()
89 .into(),
90 n => MarkdownInlineCode(&format!("{} - {} more lines", first_line, n))
91 .to_string()
92 .into(),
93 }
94 } else {
95 "Run terminal command".into()
96 }
97 }
98
99 fn run(
100 self: Arc<Self>,
101 input: Self::Input,
102 event_stream: ToolCallEventStream,
103 cx: &mut App,
104 ) -> Task<Result<Self::Output>> {
105 let language_registry = self.project.read(cx).languages().clone();
106 let working_dir = match working_dir(&input, &self.project, cx) {
107 Ok(dir) => dir,
108 Err(err) => return Task::ready(Err(err)),
109 };
110 let program = self.determine_shell.clone();
111 let command = if cfg!(windows) {
112 format!("$null | & {{{}}}", input.command.replace("\"", "'"))
113 } else if let Some(cwd) = working_dir
114 .as_ref()
115 .and_then(|cwd| cwd.as_os_str().to_str())
116 {
117 // Make sure once we're *inside* the shell, we cd into `cwd`
118 format!("(cd {cwd}; {}) </dev/null", input.command)
119 } else {
120 format!("({}) </dev/null", input.command)
121 };
122 let args = vec!["-c".into(), command];
123
124 let env = match &working_dir {
125 Some(dir) => self.project.update(cx, |project, cx| {
126 project.directory_environment(dir.as_path().into(), cx)
127 }),
128 None => Task::ready(None).shared(),
129 };
130
131 let env = cx.spawn(async move |_| {
132 let mut env = env.await.unwrap_or_default();
133 if cfg!(unix) {
134 env.insert("PAGER".into(), "cat".into());
135 }
136 env
137 });
138
139 let authorize = event_stream.authorize(self.initial_title(Ok(input.clone())), cx);
140
141 cx.spawn({
142 async move |cx| {
143 authorize.await?;
144
145 let program = program.await;
146 let env = env.await;
147 let terminal = self
148 .project
149 .update(cx, |project, cx| {
150 project.create_terminal(
151 TerminalKind::Task(task::SpawnInTerminal {
152 command: Some(program),
153 args,
154 cwd: working_dir.clone(),
155 env,
156 ..Default::default()
157 }),
158 cx,
159 )
160 })?
161 .await?;
162 let acp_terminal = cx.new(|cx| {
163 acp_thread::Terminal::new(
164 input.command.clone(),
165 working_dir.clone(),
166 terminal.clone(),
167 language_registry,
168 cx,
169 )
170 })?;
171 event_stream.update_terminal(acp_terminal.clone());
172
173 let exit_status = terminal
174 .update(cx, |terminal, cx| terminal.wait_for_completed_task(cx))?
175 .await;
176 let (content, content_line_count) = terminal.read_with(cx, |terminal, _| {
177 (terminal.get_content(), terminal.total_lines())
178 })?;
179
180 let (processed_content, finished_with_empty_output) = process_content(
181 &content,
182 &input.command,
183 exit_status.map(portable_pty::ExitStatus::from),
184 );
185
186 acp_terminal
187 .update(cx, |terminal, cx| {
188 terminal.finish(
189 exit_status,
190 content.len(),
191 processed_content.len(),
192 content_line_count,
193 finished_with_empty_output,
194 cx,
195 );
196 })
197 .log_err();
198
199 Ok(processed_content)
200 }
201 })
202 }
203}
204
205fn process_content(
206 content: &str,
207 command: &str,
208 exit_status: Option<portable_pty::ExitStatus>,
209) -> (String, bool) {
210 let should_truncate = content.len() > COMMAND_OUTPUT_LIMIT;
211
212 let content = if should_truncate {
213 let mut end_ix = COMMAND_OUTPUT_LIMIT.min(content.len());
214 while !content.is_char_boundary(end_ix) {
215 end_ix -= 1;
216 }
217 // Don't truncate mid-line, clear the remainder of the last line
218 end_ix = content[..end_ix].rfind('\n').unwrap_or(end_ix);
219 &content[..end_ix]
220 } else {
221 content
222 };
223 let content = content.trim();
224 let is_empty = content.is_empty();
225 let content = format!("```\n{content}\n```");
226 let content = if should_truncate {
227 format!(
228 "Command output too long. The first {} bytes:\n\n{content}",
229 content.len(),
230 )
231 } else {
232 content
233 };
234
235 let content = match exit_status {
236 Some(exit_status) if exit_status.success() => {
237 if is_empty {
238 "Command executed successfully.".to_string()
239 } else {
240 content.to_string()
241 }
242 }
243 Some(exit_status) => {
244 if is_empty {
245 format!(
246 "Command \"{command}\" failed with exit code {}.",
247 exit_status.exit_code()
248 )
249 } else {
250 format!(
251 "Command \"{command}\" failed with exit code {}.\n\n{content}",
252 exit_status.exit_code()
253 )
254 }
255 }
256 None => {
257 format!(
258 "Command failed or was interrupted.\nPartial output captured:\n\n{}",
259 content,
260 )
261 }
262 };
263 (content, is_empty)
264}
265
266fn working_dir(
267 input: &TerminalToolInput,
268 project: &Entity<Project>,
269 cx: &mut App,
270) -> Result<Option<PathBuf>> {
271 let project = project.read(cx);
272 let cd = &input.cd;
273
274 if cd == "." || cd.is_empty() {
275 // Accept "." or "" as meaning "the one worktree" if we only have one worktree.
276 let mut worktrees = project.worktrees(cx);
277
278 match worktrees.next() {
279 Some(worktree) => {
280 anyhow::ensure!(
281 worktrees.next().is_none(),
282 "'.' is ambiguous in multi-root workspaces. Please specify a root directory explicitly.",
283 );
284 Ok(Some(worktree.read(cx).abs_path().to_path_buf()))
285 }
286 None => Ok(None),
287 }
288 } else {
289 let input_path = Path::new(cd);
290
291 if input_path.is_absolute() {
292 // Absolute paths are allowed, but only if they're in one of the project's worktrees.
293 if project
294 .worktrees(cx)
295 .any(|worktree| input_path.starts_with(&worktree.read(cx).abs_path()))
296 {
297 return Ok(Some(input_path.into()));
298 }
299 } else if let Some(worktree) = project.worktree_for_root_name(cd, cx) {
300 return Ok(Some(worktree.read(cx).abs_path().to_path_buf()));
301 }
302
303 anyhow::bail!("`cd` directory {cd:?} was not in any of the project's worktrees.");
304 }
305}
306
307#[cfg(test)]
308mod tests {
309 use agent_settings::AgentSettings;
310 use editor::EditorSettings;
311 use fs::RealFs;
312 use gpui::{BackgroundExecutor, TestAppContext};
313 use pretty_assertions::assert_eq;
314 use serde_json::json;
315 use settings::{Settings, SettingsStore};
316 use terminal::terminal_settings::TerminalSettings;
317 use theme::ThemeSettings;
318 use util::test::TempTree;
319
320 use crate::ThreadEvent;
321
322 use super::*;
323
324 fn init_test(executor: &BackgroundExecutor, cx: &mut TestAppContext) {
325 zlog::init_test();
326
327 executor.allow_parking();
328 cx.update(|cx| {
329 let settings_store = SettingsStore::test(cx);
330 cx.set_global(settings_store);
331 language::init(cx);
332 Project::init_settings(cx);
333 ThemeSettings::register(cx);
334 TerminalSettings::register(cx);
335 EditorSettings::register(cx);
336 AgentSettings::register(cx);
337 });
338 }
339
340 #[gpui::test]
341 async fn test_interactive_command(executor: BackgroundExecutor, cx: &mut TestAppContext) {
342 if cfg!(windows) {
343 return;
344 }
345
346 init_test(&executor, cx);
347
348 let fs = Arc::new(RealFs::new(None, executor));
349 let tree = TempTree::new(json!({
350 "project": {},
351 }));
352 let project: Entity<Project> =
353 Project::test(fs, [tree.path().join("project").as_path()], cx).await;
354
355 let input = TerminalToolInput {
356 command: "cat".to_owned(),
357 cd: tree
358 .path()
359 .join("project")
360 .as_path()
361 .to_string_lossy()
362 .to_string(),
363 };
364 let (event_stream_tx, mut event_stream_rx) = ToolCallEventStream::test();
365 let result = cx
366 .update(|cx| Arc::new(TerminalTool::new(project, cx)).run(input, event_stream_tx, cx));
367
368 let auth = event_stream_rx.expect_authorization().await;
369 auth.response.send(auth.options[0].id.clone()).unwrap();
370 event_stream_rx.expect_terminal().await;
371 assert_eq!(result.await.unwrap(), "Command executed successfully.");
372 }
373
374 #[gpui::test]
375 async fn test_working_directory(executor: BackgroundExecutor, cx: &mut TestAppContext) {
376 if cfg!(windows) {
377 return;
378 }
379
380 init_test(&executor, cx);
381
382 let fs = Arc::new(RealFs::new(None, executor));
383 let tree = TempTree::new(json!({
384 "project": {},
385 "other-project": {},
386 }));
387 let project: Entity<Project> =
388 Project::test(fs, [tree.path().join("project").as_path()], cx).await;
389
390 let check = |input, expected, cx: &mut TestAppContext| {
391 let (stream_tx, mut stream_rx) = ToolCallEventStream::test();
392 let result = cx.update(|cx| {
393 Arc::new(TerminalTool::new(project.clone(), cx)).run(input, stream_tx, cx)
394 });
395 cx.run_until_parked();
396 let event = stream_rx.try_next();
397 if let Ok(Some(Ok(ThreadEvent::ToolCallAuthorization(auth)))) = event {
398 auth.response.send(auth.options[0].id.clone()).unwrap();
399 }
400
401 cx.spawn(async move |_| {
402 let output = result.await;
403 assert_eq!(output.ok(), expected);
404 })
405 };
406
407 check(
408 TerminalToolInput {
409 command: "pwd".into(),
410 cd: ".".into(),
411 },
412 Some(format!(
413 "```\n{}\n```",
414 tree.path().join("project").display()
415 )),
416 cx,
417 )
418 .await;
419
420 check(
421 TerminalToolInput {
422 command: "pwd".into(),
423 cd: "other-project".into(),
424 },
425 None, // other-project is a dir, but *not* a worktree (yet)
426 cx,
427 )
428 .await;
429
430 // Absolute path above the worktree root
431 check(
432 TerminalToolInput {
433 command: "pwd".into(),
434 cd: tree.path().to_string_lossy().into(),
435 },
436 None,
437 cx,
438 )
439 .await;
440
441 project
442 .update(cx, |project, cx| {
443 project.create_worktree(tree.path().join("other-project"), true, cx)
444 })
445 .await
446 .unwrap();
447
448 check(
449 TerminalToolInput {
450 command: "pwd".into(),
451 cd: "other-project".into(),
452 },
453 Some(format!(
454 "```\n{}\n```",
455 tree.path().join("other-project").display()
456 )),
457 cx,
458 )
459 .await;
460
461 check(
462 TerminalToolInput {
463 command: "pwd".into(),
464 cd: ".".into(),
465 },
466 None,
467 cx,
468 )
469 .await;
470 }
471}