1use agent_client_protocol as acp;
2use anyhow::Result;
3use futures::FutureExt as _;
4use gpui::{App, AppContext, Entity, SharedString, Task};
5use project::Project;
6use schemars::JsonSchema;
7use serde::{Deserialize, Serialize};
8use std::{
9 path::{Path, PathBuf},
10 rc::Rc,
11 sync::Arc,
12 time::Duration,
13};
14use util::markdown::MarkdownInlineCode;
15
16use crate::{AgentTool, ThreadEnvironment, ToolCallEventStream};
17
18const COMMAND_OUTPUT_LIMIT: u64 = 16 * 1024;
19
20/// Executes a shell one-liner and returns the combined output.
21///
22/// 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.
23///
24/// The output results will be shown to the user already, only list it again if necessary, avoid being redundant.
25///
26/// 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.
27///
28/// 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.
29///
30/// For potentially long-running commands, prefer specifying `timeout_ms` to bound runtime and prevent indefinite hangs.
31///
32/// Remember that each invocation of this tool will spawn a new shell process, so you can't rely on any state from previous invocations.
33#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
34pub struct TerminalToolInput {
35 /// The one-liner command to execute.
36 pub command: String,
37 /// Working directory for the command. This must be one of the root directories of the project.
38 pub cd: String,
39 /// Optional maximum runtime (in milliseconds). If exceeded, the running terminal task is killed.
40 pub timeout_ms: Option<u64>,
41}
42
43pub struct TerminalTool {
44 project: Entity<Project>,
45 environment: Rc<dyn ThreadEnvironment>,
46}
47
48impl TerminalTool {
49 pub fn new(project: Entity<Project>, environment: Rc<dyn ThreadEnvironment>) -> Self {
50 Self {
51 project,
52 environment,
53 }
54 }
55}
56
57impl AgentTool for TerminalTool {
58 type Input = TerminalToolInput;
59 type Output = String;
60
61 fn name() -> &'static str {
62 "terminal"
63 }
64
65 fn kind() -> acp::ToolKind {
66 acp::ToolKind::Execute
67 }
68
69 fn initial_title(
70 &self,
71 input: Result<Self::Input, serde_json::Value>,
72 _cx: &mut App,
73 ) -> SharedString {
74 if let Ok(input) = input {
75 let mut lines = input.command.lines();
76 let first_line = lines.next().unwrap_or_default();
77 let remaining_line_count = lines.count();
78 match remaining_line_count {
79 0 => MarkdownInlineCode(first_line).to_string().into(),
80 1 => MarkdownInlineCode(&format!(
81 "{} - {} more line",
82 first_line, remaining_line_count
83 ))
84 .to_string()
85 .into(),
86 n => MarkdownInlineCode(&format!("{} - {} more lines", first_line, n))
87 .to_string()
88 .into(),
89 }
90 } else {
91 "".into()
92 }
93 }
94
95 fn run(
96 self: Arc<Self>,
97 input: Self::Input,
98 event_stream: ToolCallEventStream,
99 cx: &mut App,
100 ) -> Task<Result<Self::Output>> {
101 let working_dir = match working_dir(&input, &self.project, cx) {
102 Ok(dir) => dir,
103 Err(err) => return Task::ready(Err(err)),
104 };
105
106 let authorize = event_stream.authorize(self.initial_title(Ok(input.clone()), cx), cx);
107 cx.spawn(async move |cx| {
108 authorize.await?;
109
110 let terminal = self
111 .environment
112 .create_terminal(
113 input.command.clone(),
114 working_dir,
115 Some(COMMAND_OUTPUT_LIMIT),
116 cx,
117 )
118 .await?;
119
120 let terminal_id = terminal.id(cx)?;
121 event_stream.update_fields(acp::ToolCallUpdateFields::new().content(vec![
122 acp::ToolCallContent::Terminal(acp::Terminal::new(terminal_id)),
123 ]));
124
125 let timeout = input.timeout_ms.map(Duration::from_millis);
126
127 let mut timed_out = false;
128 let wait_for_exit = terminal.wait_for_exit(cx)?;
129
130 match timeout {
131 Some(timeout) => {
132 let timeout_task = cx.background_spawn(async move {
133 smol::Timer::after(timeout).await;
134 });
135
136 futures::select! {
137 _ = wait_for_exit.clone().fuse() => {},
138 _ = timeout_task.fuse() => {
139 timed_out = true;
140 terminal.kill(cx)?;
141 wait_for_exit.await;
142 }
143 }
144 }
145 None => {
146 wait_for_exit.await;
147 }
148 };
149
150 // Check if user stopped - we check both:
151 // 1. The cancellation signal from RunningTurn::cancel (e.g. user pressed main Stop button)
152 // 2. The terminal's user_stopped flag (e.g. user clicked Stop on the terminal card)
153 let user_stopped_via_signal = event_stream.was_cancelled_by_user();
154 let user_stopped_via_terminal = terminal.was_stopped_by_user(cx).unwrap_or(false);
155 let user_stopped = user_stopped_via_signal || user_stopped_via_terminal;
156
157 let output = terminal.current_output(cx)?;
158
159 Ok(process_content(
160 output,
161 &input.command,
162 timed_out,
163 user_stopped,
164 ))
165 })
166 }
167}
168
169fn process_content(
170 output: acp::TerminalOutputResponse,
171 command: &str,
172 timed_out: bool,
173 user_stopped: bool,
174) -> String {
175 let content = output.output.trim();
176 let is_empty = content.is_empty();
177
178 let content = format!("```\n{content}\n```");
179 let content = if output.truncated {
180 format!(
181 "Command output too long. The first {} bytes:\n\n{content}",
182 content.len(),
183 )
184 } else {
185 content
186 };
187
188 let content = if user_stopped {
189 if is_empty {
190 "The user stopped this command. No output was captured before stopping.\n\n\
191 Since the user intentionally interrupted this command, ask them what they would like to do next \
192 rather than automatically retrying or assuming something went wrong.".to_string()
193 } else {
194 format!(
195 "The user stopped this command. Output captured before stopping:\n\n{}\n\n\
196 Since the user intentionally interrupted this command, ask them what they would like to do next \
197 rather than automatically retrying or assuming something went wrong.",
198 content
199 )
200 }
201 } else if timed_out {
202 if is_empty {
203 format!("Command \"{command}\" timed out. No output was captured.")
204 } else {
205 format!(
206 "Command \"{command}\" timed out. Output captured before timeout:\n\n{}",
207 content
208 )
209 }
210 } else {
211 let exit_code = output.exit_status.as_ref().and_then(|s| s.exit_code);
212 match exit_code {
213 Some(0) => {
214 if is_empty {
215 "Command executed successfully.".to_string()
216 } else {
217 content
218 }
219 }
220 Some(exit_code) => {
221 if is_empty {
222 format!("Command \"{command}\" failed with exit code {}.", exit_code)
223 } else {
224 format!(
225 "Command \"{command}\" failed with exit code {}.\n\n{content}",
226 exit_code
227 )
228 }
229 }
230 None => {
231 if is_empty {
232 "Command terminated unexpectedly. No output was captured.".to_string()
233 } else {
234 format!(
235 "Command terminated unexpectedly. Output captured:\n\n{}",
236 content
237 )
238 }
239 }
240 }
241 };
242 content
243}
244
245fn working_dir(
246 input: &TerminalToolInput,
247 project: &Entity<Project>,
248 cx: &mut App,
249) -> Result<Option<PathBuf>> {
250 let project = project.read(cx);
251 let cd = &input.cd;
252
253 if cd == "." || cd.is_empty() {
254 // Accept "." or "" as meaning "the one worktree" if we only have one worktree.
255 let mut worktrees = project.worktrees(cx);
256
257 match worktrees.next() {
258 Some(worktree) => {
259 anyhow::ensure!(
260 worktrees.next().is_none(),
261 "'.' is ambiguous in multi-root workspaces. Please specify a root directory explicitly.",
262 );
263 Ok(Some(worktree.read(cx).abs_path().to_path_buf()))
264 }
265 None => Ok(None),
266 }
267 } else {
268 let input_path = Path::new(cd);
269
270 if input_path.is_absolute() {
271 // Absolute paths are allowed, but only if they're in one of the project's worktrees.
272 if project
273 .worktrees(cx)
274 .any(|worktree| input_path.starts_with(&worktree.read(cx).abs_path()))
275 {
276 return Ok(Some(input_path.into()));
277 }
278 } else if let Some(worktree) = project.worktree_for_root_name(cd, cx) {
279 return Ok(Some(worktree.read(cx).abs_path().to_path_buf()));
280 }
281
282 anyhow::bail!("`cd` directory {cd:?} was not in any of the project's worktrees.");
283 }
284}
285
286#[cfg(test)]
287mod tests {
288 use super::*;
289
290 #[test]
291 fn test_process_content_user_stopped() {
292 let output = acp::TerminalOutputResponse::new("partial output".to_string(), false);
293
294 let result = process_content(output, "cargo build", false, true);
295
296 assert!(
297 result.contains("user stopped"),
298 "Expected 'user stopped' message, got: {}",
299 result
300 );
301 assert!(
302 result.contains("partial output"),
303 "Expected output to be included, got: {}",
304 result
305 );
306 assert!(
307 result.contains("ask them what they would like to do"),
308 "Should instruct agent to ask user, got: {}",
309 result
310 );
311 }
312
313 #[test]
314 fn test_process_content_user_stopped_empty_output() {
315 let output = acp::TerminalOutputResponse::new("".to_string(), false);
316
317 let result = process_content(output, "cargo build", false, true);
318
319 assert!(
320 result.contains("user stopped"),
321 "Expected 'user stopped' message, got: {}",
322 result
323 );
324 assert!(
325 result.contains("No output was captured"),
326 "Expected 'No output was captured', got: {}",
327 result
328 );
329 }
330
331 #[test]
332 fn test_process_content_timed_out() {
333 let output = acp::TerminalOutputResponse::new("build output here".to_string(), false);
334
335 let result = process_content(output, "cargo build", true, false);
336
337 assert!(
338 result.contains("timed out"),
339 "Expected 'timed out' message for timeout, got: {}",
340 result
341 );
342 assert!(
343 result.contains("build output here"),
344 "Expected output to be included, got: {}",
345 result
346 );
347 }
348
349 #[test]
350 fn test_process_content_timed_out_with_empty_output() {
351 let output = acp::TerminalOutputResponse::new("".to_string(), false);
352
353 let result = process_content(output, "sleep 1000", true, false);
354
355 assert!(
356 result.contains("timed out"),
357 "Expected 'timed out' for timeout, got: {}",
358 result
359 );
360 assert!(
361 result.contains("No output was captured"),
362 "Expected 'No output was captured' for empty output, got: {}",
363 result
364 );
365 }
366
367 #[test]
368 fn test_process_content_with_success() {
369 let output = acp::TerminalOutputResponse::new("success output".to_string(), false)
370 .exit_status(acp::TerminalExitStatus::new().exit_code(0));
371
372 let result = process_content(output, "echo hello", false, false);
373
374 assert!(
375 result.contains("success output"),
376 "Expected output to be included, got: {}",
377 result
378 );
379 assert!(
380 !result.contains("failed"),
381 "Success should not say 'failed', got: {}",
382 result
383 );
384 }
385
386 #[test]
387 fn test_process_content_with_success_empty_output() {
388 let output = acp::TerminalOutputResponse::new("".to_string(), false)
389 .exit_status(acp::TerminalExitStatus::new().exit_code(0));
390
391 let result = process_content(output, "true", false, false);
392
393 assert!(
394 result.contains("executed successfully"),
395 "Expected success message for empty output, got: {}",
396 result
397 );
398 }
399
400 #[test]
401 fn test_process_content_with_error_exit() {
402 let output = acp::TerminalOutputResponse::new("error output".to_string(), false)
403 .exit_status(acp::TerminalExitStatus::new().exit_code(1));
404
405 let result = process_content(output, "false", false, false);
406
407 assert!(
408 result.contains("failed with exit code 1"),
409 "Expected failure message, got: {}",
410 result
411 );
412 assert!(
413 result.contains("error output"),
414 "Expected output to be included, got: {}",
415 result
416 );
417 }
418
419 #[test]
420 fn test_process_content_with_error_exit_empty_output() {
421 let output = acp::TerminalOutputResponse::new("".to_string(), false)
422 .exit_status(acp::TerminalExitStatus::new().exit_code(1));
423
424 let result = process_content(output, "false", false, false);
425
426 assert!(
427 result.contains("failed with exit code 1"),
428 "Expected failure message, got: {}",
429 result
430 );
431 }
432
433 #[test]
434 fn test_process_content_unexpected_termination() {
435 let output = acp::TerminalOutputResponse::new("some output".to_string(), false);
436
437 let result = process_content(output, "some_command", false, false);
438
439 assert!(
440 result.contains("terminated unexpectedly"),
441 "Expected 'terminated unexpectedly' message, got: {}",
442 result
443 );
444 assert!(
445 result.contains("some output"),
446 "Expected output to be included, got: {}",
447 result
448 );
449 }
450
451 #[test]
452 fn test_process_content_unexpected_termination_empty_output() {
453 let output = acp::TerminalOutputResponse::new("".to_string(), false);
454
455 let result = process_content(output, "some_command", false, false);
456
457 assert!(
458 result.contains("terminated unexpectedly"),
459 "Expected 'terminated unexpectedly' message, got: {}",
460 result
461 );
462 assert!(
463 result.contains("No output was captured"),
464 "Expected 'No output was captured' for empty output, got: {}",
465 result
466 );
467 }
468}