Skip to main content

microclaw_engine/tools/
background_process.rs

1//! Background shell processes for long-running commands.
2//!
3//! `bash` with `run_in_background: true` starts a host process (dev server,
4//! file watcher, long test suite) and returns immediately with an id. The
5//! `bash_output` tool returns output produced since the previous read plus the
6//! exit status, and `bash_kill` stops the process. Processes are scoped to the
7//! session that started them. The registry belongs to a `ToolRegistry`, so
8//! every process still running is killed when that registry is dropped.
9
10use std::collections::HashMap;
11use std::path::Path;
12use std::sync::atomic::{AtomicBool, Ordering};
13use std::sync::{Arc, Mutex};
14
15use async_trait::async_trait;
16use serde_json::json;
17use tokio::io::AsyncReadExt;
18
19use microclaw_core::llm_types::ToolDefinition;
20use microclaw_core::text::floor_char_boundary;
21
22use super::{schema_object, Tool, ToolResult};
23
24/// Retained output per process; older bytes are dropped first.
25const MAX_BUFFERED_BYTES: usize = 512 * 1024;
26/// Output returned by a single `bash_output` call.
27const MAX_RETURNED_BYTES: usize = 30_000;
28/// Concurrent background processes per session.
29const MAX_PROCESSES_PER_SESSION: usize = 8;
30
31#[derive(Default)]
32struct OutputBuffer {
33    text: String,
34    /// Absolute offset of `text[0]` in the full output stream.
35    base: usize,
36    /// Absolute offset the agent has read up to.
37    cursor: usize,
38}
39
40impl OutputBuffer {
41    fn push(&mut self, chunk: &str) {
42        self.text.push_str(chunk);
43        if self.text.len() > MAX_BUFFERED_BYTES {
44            let excess = self.text.len() - MAX_BUFFERED_BYTES;
45            let cut = floor_char_boundary(&self.text, excess);
46            self.text.drain(..cut);
47            self.base += cut;
48        }
49    }
50
51    /// Return unread output (bounded) and whether earlier output was dropped.
52    fn take_unread(&mut self) -> (String, bool) {
53        let mut dropped = false;
54        if self.cursor < self.base {
55            self.cursor = self.base;
56            dropped = true;
57        }
58        let start = self.cursor - self.base;
59        let mut end = self.text.len();
60        if end - start > MAX_RETURNED_BYTES {
61            end = floor_char_boundary(&self.text, start + MAX_RETURNED_BYTES);
62        }
63        let out = self.text[start..end].to_string();
64        self.cursor = self.base + end;
65        (out, dropped)
66    }
67
68    fn has_unread(&self) -> bool {
69        self.base + self.text.len() > self.cursor
70    }
71}
72
73struct BackgroundProcess {
74    session: String,
75    command: String,
76    started_at: chrono::DateTime<chrono::Utc>,
77    output: Arc<Mutex<OutputBuffer>>,
78    exit_code: Arc<Mutex<Option<i32>>>,
79    kill_tx: Mutex<Option<tokio::sync::oneshot::Sender<()>>>,
80    /// The process's stdin, for `bash_input` (`None` once closed).
81    stdin: tokio::sync::Mutex<Option<tokio::process::ChildStdin>>,
82    /// A foreground `bash` call is still waiting for this process. Cleared
83    /// when the user moves it to the background ([`ProcessRegistry::detach_foreground`]).
84    foreground: AtomicBool,
85}
86
87impl BackgroundProcess {
88    fn is_foreground(&self) -> bool {
89        self.foreground.load(Ordering::SeqCst)
90    }
91
92    fn request_kill(&self) {
93        if let Some(tx) = lock(&self.kill_tx).take() {
94            let _ = tx.send(());
95        }
96    }
97}
98
99/// How a foreground command run through the registry ended.
100#[derive(Debug, Clone, PartialEq, Eq)]
101pub enum ForegroundOutcome {
102    /// The command finished; its combined output.
103    Exited { code: i32, output: String },
104    /// The user moved the command to the background; it keeps running under `id`.
105    Detached { id: String },
106    /// The timeout passed; the command was stopped.
107    TimedOut { output: String },
108}
109
110/// A background process as listed for the user (`/jobs`).
111#[derive(Debug, Clone, PartialEq, Eq)]
112pub struct BackgroundJob {
113    pub id: String,
114    pub command: String,
115    pub started_at: chrono::DateTime<chrono::Utc>,
116    /// `None` while running.
117    pub exit_code: Option<i32>,
118}
119
120/// Stops a foreground process whose `bash` call went away (the run was
121/// cancelled) while it was still in the foreground.
122struct ForegroundGuard<'a> {
123    registry: &'a ProcessRegistry,
124    id: String,
125    process: Arc<BackgroundProcess>,
126    done: bool,
127}
128
129impl Drop for ForegroundGuard<'_> {
130    fn drop(&mut self) {
131        if !self.done && self.process.is_foreground() {
132            self.process.request_kill();
133            lock(&self.registry.processes).remove(&self.id);
134        }
135    }
136}
137
138/// Background processes started through one tool registry.
139#[derive(Default)]
140pub struct ProcessRegistry {
141    processes: Mutex<HashMap<String, Arc<BackgroundProcess>>>,
142}
143
144impl Drop for ProcessRegistry {
145    fn drop(&mut self) {
146        let processes = self.processes.get_mut().unwrap_or_else(|e| e.into_inner());
147        for process in processes.values() {
148            process.request_kill();
149        }
150    }
151}
152
153/// SIGKILL the process group led by `pid` (see `process_group(0)`).
154fn kill_group(pid: Option<u32>) {
155    #[cfg(unix)]
156    if let Some(pid) = pid.and_then(|p| libc::pid_t::try_from(p).ok()) {
157        // SAFETY: plain syscall on a group id this registry created.
158        unsafe {
159            libc::killpg(pid, libc::SIGKILL);
160        }
161    }
162    #[cfg(not(unix))]
163    let _ = pid;
164}
165
166fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
167    mutex.lock().unwrap_or_else(|e| e.into_inner())
168}
169
170fn next_id() -> String {
171    let short = uuid::Uuid::new_v4().simple().to_string();
172    format!("bg_{}", &short[..8])
173}
174
175/// Session key used to scope background processes to the chat that owns them.
176pub fn session_key(input: &serde_json::Value) -> String {
177    super::auth_context_from_input(input)
178        .map(|auth| session_key_for(&auth.caller_channel, auth.caller_chat_id))
179        .unwrap_or_else(|| "shared".to_string())
180}
181
182/// The session key of one chat (see [`session_key`]).
183pub fn session_key_for(caller_channel: &str, chat_id: i64) -> String {
184    format!("{caller_channel}-{chat_id}")
185}
186
187impl ProcessRegistry {
188    /// Spawn `command` in `working_dir` on the host and register it.
189    pub fn spawn(
190        &self,
191        session: &str,
192        command: &str,
193        working_dir: &Path,
194        envs: &HashMap<String, String>,
195    ) -> Result<String, String> {
196        let spec = crate::internal::tool_runtime::command_runner::shell_command(command);
197        self.spawn_spec(session, command, &spec, working_dir, envs)
198    }
199
200    /// Spawn an already-built command line (e.g. wrapped by the local OS
201    /// sandbox) and register it.
202    pub fn spawn_spec(
203        &self,
204        session: &str,
205        command: &str,
206        spec: &crate::internal::tool_runtime::command_runner::CommandSpec,
207        working_dir: &Path,
208        envs: &HashMap<String, String>,
209    ) -> Result<String, String> {
210        let running = lock(&self.processes)
211            .values()
212            .filter(|p| p.session == session && !p.is_foreground() && lock(&p.exit_code).is_none())
213            .count();
214        if running >= MAX_PROCESSES_PER_SESSION {
215            return Err(format!(
216            "Too many background processes are running ({running}). Stop one with bash_kill first."
217        ));
218        }
219        self.spawn_inner(session, command, spec, working_dir, envs, false)
220            .map(|(id, _)| id)
221    }
222
223    /// Run a command in the foreground: wait until it exits, the timeout
224    /// passes (the command is stopped) or the user moves it to the background
225    /// with [`Self::detach_foreground`] (it keeps running as a background
226    /// process). Dropping the returned future stops a command that is still
227    /// in the foreground.
228    pub async fn run_foreground(
229        &self,
230        session: &str,
231        command: &str,
232        spec: &crate::internal::tool_runtime::command_runner::CommandSpec,
233        working_dir: &Path,
234        envs: &HashMap<String, String>,
235        timeout: std::time::Duration,
236    ) -> Result<ForegroundOutcome, String> {
237        let (id, process) = self.spawn_inner(session, command, spec, working_dir, envs, true)?;
238        let mut guard = ForegroundGuard {
239            registry: self,
240            id: id.clone(),
241            process: process.clone(),
242            done: false,
243        };
244        let deadline = tokio::time::Instant::now() + timeout;
245        loop {
246            if let Some(code) = *lock(&process.exit_code) {
247                guard.done = true;
248                lock(&self.processes).remove(&id);
249                return Ok(ForegroundOutcome::Exited {
250                    code,
251                    output: full_output(&process),
252                });
253            }
254            if !process.is_foreground() {
255                guard.done = true;
256                return Ok(ForegroundOutcome::Detached { id });
257            }
258            if tokio::time::Instant::now() >= deadline {
259                guard.done = true;
260                process.request_kill();
261                for _ in 0..100 {
262                    if lock(&process.exit_code).is_some() {
263                        break;
264                    }
265                    tokio::time::sleep(std::time::Duration::from_millis(20)).await;
266                }
267                lock(&self.processes).remove(&id);
268                return Ok(ForegroundOutcome::TimedOut {
269                    output: full_output(&process),
270                });
271            }
272            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
273        }
274    }
275
276    /// Move every foreground command of `session` to the background. Returns
277    /// their ids (empty when nothing was running in the foreground).
278    pub fn detach_foreground(&self, session: &str) -> Vec<String> {
279        let mut ids: Vec<String> = lock(&self.processes)
280            .iter()
281            .filter(|(_, p)| p.session == session && lock(&p.exit_code).is_none())
282            .filter(|(_, p)| p.foreground.swap(false, Ordering::SeqCst))
283            .map(|(id, _)| id.clone())
284            .collect();
285        ids.sort();
286        ids
287    }
288
289    /// Background processes of `session`, oldest first.
290    pub fn jobs(&self, session: &str) -> Vec<BackgroundJob> {
291        let mut jobs: Vec<BackgroundJob> = lock(&self.processes)
292            .iter()
293            .filter(|(_, p)| p.session == session && !p.is_foreground())
294            .map(|(id, p)| BackgroundJob {
295                id: id.clone(),
296                command: p.command.clone(),
297                started_at: p.started_at,
298                exit_code: *lock(&p.exit_code),
299            })
300            .collect();
301        jobs.sort_by(|a, b| a.started_at.cmp(&b.started_at).then(a.id.cmp(&b.id)));
302        jobs
303    }
304
305    /// The last `max_bytes` of a background process's output, without
306    /// moving the agent's read cursor.
307    pub fn output_tail(&self, session: &str, id: &str, max_bytes: usize) -> Result<String, String> {
308        let process = self.lookup(session, id)?;
309        let output = lock(&process.output);
310        let text = output.text.as_str();
311        let start = if text.len() > max_bytes {
312            let mut cut = text.len() - max_bytes;
313            while !text.is_char_boundary(cut) {
314                cut += 1;
315            }
316            cut
317        } else {
318            0
319        };
320        Ok(text[start..].to_string())
321    }
322
323    /// Stop a background process. Returns its status line.
324    pub async fn kill(&self, session: &str, id: &str) -> Result<String, String> {
325        let process = self.lookup(session, id)?;
326        if lock(&process.exit_code).is_some() {
327            return Ok(format!("{id} already finished; {}", status_line(&process)));
328        }
329        process.request_kill();
330        for _ in 0..50 {
331            if lock(&process.exit_code).is_some() {
332                break;
333            }
334            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
335        }
336        Ok(format!("Stopped {id}; {}", status_line(&process)))
337    }
338
339    fn spawn_inner(
340        &self,
341        session: &str,
342        command: &str,
343        spec: &crate::internal::tool_runtime::command_runner::CommandSpec,
344        working_dir: &Path,
345        envs: &HashMap<String, String>,
346        foreground: bool,
347    ) -> Result<(String, Arc<BackgroundProcess>), String> {
348        let mut cmd =
349            crate::internal::tool_runtime::command_runner::build_command(spec, Some(working_dir));
350        for (k, v) in envs {
351            cmd.env(k, v);
352        }
353        // A foreground command gets no stdin, like the plain foreground path
354        // (a command that reads it sees end-of-input instead of hanging).
355        let stdin = if foreground {
356            std::process::Stdio::null()
357        } else {
358            std::process::Stdio::piped()
359        };
360        cmd.stdout(std::process::Stdio::piped())
361            .stderr(std::process::Stdio::piped())
362            .stdin(stdin)
363            .kill_on_drop(true);
364        // Its own process group, so bash_kill stops the whole command
365        // (`cd app && npm run dev` leaves node as a grandchild that holds the
366        // output pipes), not only the shell.
367        #[cfg(unix)]
368        cmd.process_group(0);
369        let mut child = cmd.spawn().map_err(|e| {
370            if foreground {
371                format!("Failed to execute command: {e}")
372            } else {
373                format!("Failed to start background command: {e}")
374            }
375        })?;
376        let stdin = child.stdin.take();
377        let pid = child.id();
378
379        let id = next_id();
380        let output = Arc::new(Mutex::new(OutputBuffer::default()));
381        let exit_code = Arc::new(Mutex::new(None));
382        let (kill_tx, mut kill_rx) = tokio::sync::oneshot::channel::<()>();
383
384        let readers: Vec<_> = [
385            child
386                .stdout
387                .take()
388                .map(|s| Box::new(s) as Box<dyn tokio::io::AsyncRead + Unpin + Send>),
389            child
390                .stderr
391                .take()
392                .map(|s| Box::new(s) as Box<dyn tokio::io::AsyncRead + Unpin + Send>),
393        ]
394        .into_iter()
395        .flatten()
396        .map(|mut stream| {
397            let output = output.clone();
398            tokio::spawn(async move {
399                let mut buf = vec![0u8; 8192];
400                loop {
401                    match stream.read(&mut buf).await {
402                        Ok(0) | Err(_) => break,
403                        Ok(n) => lock(&output).push(&String::from_utf8_lossy(&buf[..n])),
404                    }
405                }
406            })
407        })
408        .collect();
409
410        {
411            let exit_code = exit_code.clone();
412            tokio::spawn(async move {
413                let status = tokio::select! {
414                    status = child.wait() => status.ok().and_then(|s| s.code()).unwrap_or(-1),
415                    _ = &mut kill_rx => {
416                        kill_group(pid);
417                        let _ = child.kill().await;
418                        -9
419                    }
420                };
421                // A process that left the group can keep the pipes open;
422                // after a kill, do not wait for it.
423                for reader in readers {
424                    if status == -9 {
425                        let _ =
426                            tokio::time::timeout(std::time::Duration::from_secs(2), reader).await;
427                    } else {
428                        let _ = reader.await;
429                    }
430                }
431                *lock(&exit_code) = Some(status);
432            });
433        }
434
435        let process = Arc::new(BackgroundProcess {
436            session: session.to_string(),
437            command: command.to_string(),
438            started_at: chrono::Utc::now(),
439            output,
440            exit_code,
441            kill_tx: Mutex::new(Some(kill_tx)),
442            stdin: tokio::sync::Mutex::new(stdin),
443            foreground: AtomicBool::new(foreground),
444        });
445        lock(&self.processes).insert(id.clone(), process.clone());
446        Ok((id, process))
447    }
448
449    fn lookup(&self, session: &str, id: &str) -> Result<Arc<BackgroundProcess>, String> {
450        let registry = lock(&self.processes);
451        match registry.get(id) {
452            Some(process) if process.session == session && !process.is_foreground() => {
453                Ok(process.clone())
454            }
455            _ => {
456                let known: Vec<_> = registry
457                    .iter()
458                    .filter(|(_, p)| p.session == session && !p.is_foreground())
459                    .map(|(id, p)| format!("{id} ({})", p.command))
460                    .collect();
461                let hint = if known.is_empty() {
462                    "No background processes exist in this session.".to_string()
463                } else {
464                    format!("Known processes: {}", known.join(", "))
465                };
466                Err(format!("Unknown background process '{id}'. {hint}"))
467            }
468        }
469    }
470}
471
472/// Everything a process printed that is still buffered (all of it unless it
473/// passed [`MAX_BUFFERED_BYTES`]).
474fn full_output(process: &BackgroundProcess) -> String {
475    let output = lock(&process.output);
476    if output.base > 0 {
477        format!(
478            "(earlier output was dropped; only the most recent output is retained)\n{}",
479            output.text
480        )
481    } else {
482        output.text.clone()
483    }
484}
485
486fn status_line(process: &BackgroundProcess) -> String {
487    let elapsed = (chrono::Utc::now() - process.started_at)
488        .num_seconds()
489        .max(0);
490    match *lock(&process.exit_code) {
491        Some(code) => format!("status: exited with code {code} (after {elapsed}s)"),
492        None => format!("status: running ({elapsed}s)"),
493    }
494}
495
496/// Write to a background process's stdin: answer prompts, drive a REPL or an
497/// interactive CLI started with `run_in_background`.
498pub struct BashInputTool(pub Arc<ProcessRegistry>);
499
500/// How long `bash_input` waits for the process to answer.
501const INPUT_SETTLE_MS: u64 = 400;
502
503#[async_trait]
504impl Tool for BashInputTool {
505    fn name(&self) -> &str {
506        "bash_input"
507    }
508
509    fn definition(&self) -> ToolDefinition {
510        ToolDefinition {
511            name: "bash_input".into(),
512            description: "Send text to the stdin of a background process started with bash run_in_background (a REPL, a debugger, a command waiting for an answer), then return the output it produced. Include a trailing newline to submit a line. Set close to true to send end-of-input. The process has no terminal, so start REPLs in a line-oriented, unbuffered mode (e.g. `python3 -u -i`, `node -i`).".into(),
513            input_schema: schema_object(
514                json!({
515                    "id": {
516                        "type": "string",
517                        "description": "Background process id returned by bash (e.g. bg_1a2b3c4d)"
518                    },
519                    "input": {
520                        "type": "string",
521                        "description": "Text to write; usually ends with \\n"
522                    },
523                    "close": {
524                        "type": "boolean",
525                        "description": "Close stdin after writing (end of input)"
526                    },
527                    "wait_ms": {
528                        "type": "integer",
529                        "description": "How long to wait for output before returning (default 400, max 10000)"
530                    }
531                }),
532                &["id"],
533            ),
534        }
535    }
536
537    async fn execute(&self, input: serde_json::Value) -> ToolResult {
538        let session = session_key(&input);
539        let Some(id) = input.get("id").and_then(|v| v.as_str()) else {
540            return ToolResult::error("Missing 'id' parameter".into());
541        };
542        let process = match self.0.lookup(&session, id) {
543            Ok(process) => process,
544            Err(msg) => return ToolResult::error(msg),
545        };
546        let text = input.get("input").and_then(|v| v.as_str()).unwrap_or("");
547        let close = input
548            .get("close")
549            .and_then(|v| v.as_bool())
550            .unwrap_or(false);
551        {
552            let mut stdin = process.stdin.lock().await;
553            let Some(pipe) = stdin.as_mut() else {
554                return ToolResult::error(format!("{id}: stdin is already closed"));
555            };
556            if !text.is_empty() {
557                use tokio::io::AsyncWriteExt;
558                if let Err(e) = pipe.write_all(text.as_bytes()).await {
559                    return ToolResult::error(format!(
560                        "{id}: could not write to stdin ({e}); {}",
561                        status_line(&process)
562                    ));
563                }
564                let _ = pipe.flush().await;
565            }
566            if close {
567                *stdin = None;
568            }
569        }
570        let wait = input
571            .get("wait_ms")
572            .and_then(|v| v.as_u64())
573            .unwrap_or(INPUT_SETTLE_MS)
574            .min(10_000);
575        tokio::time::sleep(std::time::Duration::from_millis(wait)).await;
576        let (output, dropped) = lock(&process.output).take_unread();
577        let mut text = format!("{}\n", status_line(&process));
578        if dropped {
579            text.push_str("[earlier output was dropped]\n");
580        }
581        if output.is_empty() {
582            text.push_str("(no new output yet; read it later with bash_output)");
583        } else {
584            text.push_str(&output);
585        }
586        ToolResult::success(text)
587    }
588}
589
590pub struct BashOutputTool(pub Arc<ProcessRegistry>);
591
592#[async_trait]
593impl Tool for BashOutputTool {
594    fn name(&self) -> &str {
595        "bash_output"
596    }
597
598    fn definition(&self) -> ToolDefinition {
599        ToolDefinition {
600            name: "bash_output".into(),
601            description: "Read new output from a background process started with bash run_in_background. Returns output produced since the previous read and whether the process is still running. Omit id to list this session's background processes.".into(),
602            input_schema: schema_object(
603                json!({
604                    "id": {
605                        "type": "string",
606                        "description": "Background process id returned by bash (e.g. bg_1a2b3c4d)"
607                    },
608                    "filter": {
609                        "type": "string",
610                        "description": "Optional regex; only matching output lines are returned"
611                    }
612                }),
613                &[],
614            ),
615        }
616    }
617
618    async fn execute(&self, input: serde_json::Value) -> ToolResult {
619        let session = session_key(&input);
620        let Some(id) = input.get("id").and_then(|v| v.as_str()) else {
621            let registry = lock(&self.0.processes);
622            let mut rows: Vec<_> = registry
623                .iter()
624                .filter(|(_, p)| p.session == session && !p.is_foreground())
625                .map(|(id, p)| {
626                    (
627                        p.started_at,
628                        format!("{id}  {}  {}", status_line(p), p.command),
629                    )
630                })
631                .collect();
632            rows.sort();
633            return if rows.is_empty() {
634                ToolResult::success("No background processes in this session.".into())
635            } else {
636                ToolResult::success(
637                    rows.into_iter()
638                        .map(|(_, row)| row)
639                        .collect::<Vec<_>>()
640                        .join("\n"),
641                )
642            };
643        };
644        let process = match self.0.lookup(&session, id) {
645            Ok(p) => p,
646            Err(msg) => return ToolResult::error(msg),
647        };
648        let filter = match input.get("filter").and_then(|v| v.as_str()) {
649            Some(raw) => match regex::Regex::new(raw) {
650                Ok(re) => Some(re),
651                Err(e) => return ToolResult::error(format!("Invalid filter regex: {e}")),
652            },
653            None => None,
654        };
655        let (mut text, dropped) = lock(&process.output).take_unread();
656        if let Some(re) = filter {
657            text = text
658                .lines()
659                .filter(|line| re.is_match(line))
660                .collect::<Vec<_>>()
661                .join("\n");
662        }
663        let more = lock(&process.output).has_unread();
664        let mut out = format!("{id}  {}\n", status_line(&process));
665        if dropped {
666            out.push_str("(older output was dropped; only the most recent output is retained)\n");
667        }
668        if text.is_empty() {
669            out.push_str("(no new output)");
670        } else {
671            out.push_str(&text);
672        }
673        if more {
674            out.push_str("\n... (more output available; call bash_output again)");
675        }
676        ToolResult::success(out)
677    }
678}
679
680pub struct BashKillTool(pub Arc<ProcessRegistry>);
681
682#[async_trait]
683impl Tool for BashKillTool {
684    fn name(&self) -> &str {
685        "bash_kill"
686    }
687
688    fn definition(&self) -> ToolDefinition {
689        ToolDefinition {
690            name: "bash_kill".into(),
691            description: "Stop a background process started with bash run_in_background.".into(),
692            input_schema: schema_object(
693                json!({
694                    "id": {
695                        "type": "string",
696                        "description": "Background process id returned by bash"
697                    }
698                }),
699                &["id"],
700            ),
701        }
702    }
703
704    async fn execute(&self, input: serde_json::Value) -> ToolResult {
705        let session = session_key(&input);
706        let Some(id) = input.get("id").and_then(|v| v.as_str()) else {
707            return ToolResult::error("Missing 'id' parameter".into());
708        };
709        match self.0.kill(&session, id).await {
710            Ok(status) => ToolResult::success(status),
711            Err(msg) => ToolResult::error(msg),
712        }
713    }
714}
715
716#[cfg(test)]
717mod tests {
718    use super::*;
719
720    #[cfg(unix)]
721    fn shell(command: &str) -> crate::internal::tool_runtime::command_runner::CommandSpec {
722        crate::internal::tool_runtime::command_runner::shell_command(command)
723    }
724
725    #[cfg(unix)]
726    #[tokio::test]
727    async fn foreground_run_returns_combined_output_and_exit_code() {
728        let dir = tempfile::tempdir().unwrap();
729        let registry = ProcessRegistry::default();
730        let outcome = registry
731            .run_foreground(
732                "s",
733                "echo out; echo err >&2; exit 3",
734                &shell("echo out; echo err >&2; exit 3"),
735                dir.path(),
736                &HashMap::new(),
737                std::time::Duration::from_secs(10),
738            )
739            .await
740            .unwrap();
741        let ForegroundOutcome::Exited { code, output } = outcome else {
742            panic!("expected exit, got {outcome:?}");
743        };
744        assert_eq!(code, 3);
745        assert!(output.contains("out") && output.contains("err"), "{output}");
746        // A finished foreground command is not a background job.
747        assert!(registry.jobs("s").is_empty());
748    }
749
750    #[cfg(unix)]
751    #[tokio::test]
752    async fn foreground_run_gets_no_stdin() {
753        let dir = tempfile::tempdir().unwrap();
754        let registry = ProcessRegistry::default();
755        // `cat` with an open stdin would wait until the timeout.
756        let outcome = registry
757            .run_foreground(
758                "s",
759                "cat",
760                &shell("cat; echo done"),
761                dir.path(),
762                &HashMap::new(),
763                std::time::Duration::from_secs(10),
764            )
765            .await
766            .unwrap();
767        assert!(
768            matches!(&outcome, ForegroundOutcome::Exited { code: 0, output } if output.contains("done")),
769            "{outcome:?}"
770        );
771    }
772
773    #[cfg(unix)]
774    #[tokio::test]
775    async fn foreground_run_times_out_and_stops_the_command() {
776        let dir = tempfile::tempdir().unwrap();
777        let registry = ProcessRegistry::default();
778        let outcome = registry
779            .run_foreground(
780                "s",
781                "sleep",
782                &shell("echo before; sleep 30"),
783                dir.path(),
784                &HashMap::new(),
785                std::time::Duration::from_millis(300),
786            )
787            .await
788            .unwrap();
789        assert!(
790            matches!(&outcome, ForegroundOutcome::TimedOut { output } if output.contains("before")),
791            "{outcome:?}"
792        );
793        assert!(registry.jobs("s").is_empty());
794    }
795
796    #[cfg(unix)]
797    #[tokio::test]
798    async fn detached_foreground_command_keeps_running_as_a_job() {
799        let dir = tempfile::tempdir().unwrap();
800        let registry = Arc::new(ProcessRegistry::default());
801        let run = {
802            let registry = registry.clone();
803            let cwd = dir.path().to_path_buf();
804            tokio::spawn(async move {
805                registry
806                    .run_foreground(
807                        "s",
808                        "slow",
809                        &shell("echo started; sleep 30"),
810                        &cwd,
811                        &HashMap::new(),
812                        std::time::Duration::from_secs(60),
813                    )
814                    .await
815            })
816        };
817        // Wait until it runs, then detach it; another session sees nothing.
818        let mut detached = Vec::new();
819        for _ in 0..100 {
820            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
821            assert!(registry.detach_foreground("other").is_empty());
822            detached = registry.detach_foreground("s");
823            if !detached.is_empty() {
824                break;
825            }
826        }
827        assert_eq!(detached.len(), 1);
828        let outcome = tokio::time::timeout(std::time::Duration::from_secs(5), run)
829            .await
830            .expect("the foreground call returns once detached")
831            .unwrap()
832            .unwrap();
833        assert_eq!(
834            outcome,
835            ForegroundOutcome::Detached {
836                id: detached[0].clone()
837            }
838        );
839        let jobs = registry.jobs("s");
840        assert_eq!(jobs.len(), 1);
841        assert_eq!(jobs[0].exit_code, None);
842        for _ in 0..100 {
843            if registry
844                .output_tail("s", &jobs[0].id, 100)
845                .unwrap()
846                .contains("started")
847            {
848                break;
849            }
850            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
851        }
852        assert!(registry
853            .output_tail("s", &jobs[0].id, 100)
854            .unwrap()
855            .contains("started"));
856        assert!(registry.output_tail("other", &jobs[0].id, 100).is_err());
857        let status = registry.kill("s", &jobs[0].id).await.unwrap();
858        assert!(status.starts_with("Stopped"), "{status}");
859        assert_eq!(registry.jobs("s")[0].exit_code, Some(-9));
860    }
861
862    #[cfg(unix)]
863    #[tokio::test]
864    async fn dropping_a_foreground_run_stops_the_command() {
865        let dir = tempfile::tempdir().unwrap();
866        let marker = dir.path().join("still-running");
867        let registry = ProcessRegistry::default();
868        let command = format!("sleep 1; touch {}", marker.display());
869        let _ = tokio::time::timeout(
870            std::time::Duration::from_millis(200),
871            registry.run_foreground(
872                "s",
873                &command,
874                &shell(&command),
875                dir.path(),
876                &HashMap::new(),
877                std::time::Duration::from_secs(30),
878            ),
879        )
880        .await;
881        tokio::time::sleep(std::time::Duration::from_millis(1500)).await;
882        assert!(!marker.exists(), "the cancelled command kept running");
883        assert!(registry.jobs("s").is_empty());
884    }
885
886    #[test]
887    fn output_buffer_tracks_cursor_and_drops_oldest() {
888        let mut buf = OutputBuffer::default();
889        buf.push("hello ");
890        buf.push("world");
891        assert_eq!(buf.take_unread(), ("hello world".to_string(), false));
892        assert!(!buf.has_unread());
893        buf.push(&"x".repeat(MAX_BUFFERED_BYTES + 10));
894        let (text, dropped) = buf.take_unread();
895        assert!(dropped);
896        assert_eq!(text.len(), MAX_RETURNED_BYTES);
897        assert!(buf.has_unread());
898    }
899
900    #[cfg(unix)]
901    #[tokio::test]
902    async fn bash_input_drives_an_interactive_process() {
903        let dir = tempfile::tempdir().unwrap();
904        let auth = json!({"caller_channel": "test", "caller_chat_id": 7, "control_chat_ids": []});
905        let session = session_key(&json!({"__microclaw_auth": auth.clone()}));
906        let registry = Arc::new(ProcessRegistry::default());
907        let input_tool = BashInputTool(registry.clone());
908        // A line-oriented "REPL": echoes each line upper-cased until EOF.
909        let id = registry
910            .spawn(
911                &session,
912                "while read line; do echo \"got:$line\" | tr a-z A-Z; done; echo bye",
913                dir.path(),
914                &HashMap::new(),
915            )
916            .unwrap();
917        let first = input_tool
918            .execute(json!({"id": id, "input": "hello\n", "wait_ms": 1000, "__microclaw_auth": auth.clone()}))
919            .await;
920        assert!(!first.is_error, "{}", first.content);
921        assert!(first.content.contains("GOT:HELLO"), "{}", first.content);
922        let last = input_tool
923            .execute(json!({"id": id, "input": "again\n", "close": true, "wait_ms": 1000, "__microclaw_auth": auth.clone()}))
924            .await;
925        assert!(last.content.contains("GOT:AGAIN"), "{}", last.content);
926        assert!(last.content.contains("bye"), "{}", last.content);
927        let closed = input_tool
928            .execute(json!({"id": id, "input": "x\n", "__microclaw_auth": auth}))
929            .await;
930        assert!(closed.is_error);
931    }
932
933    #[cfg(unix)]
934    #[tokio::test]
935    async fn background_process_streams_output_and_can_be_killed() {
936        let dir = tempfile::tempdir().unwrap();
937        let input = |extra: serde_json::Value| {
938            let mut value = json!({
939                "__microclaw_auth": {
940                    "caller_channel": "test",
941                    "caller_chat_id": 1,
942                    "control_chat_ids": []
943                }
944            });
945            if let (Some(map), Some(extra)) = (value.as_object_mut(), extra.as_object()) {
946                map.extend(extra.clone());
947            }
948            value
949        };
950        let session = session_key(&input(json!({})));
951        let registry = Arc::new(ProcessRegistry::default());
952        let output_tool = BashOutputTool(registry.clone());
953        let kill_tool = BashKillTool(registry.clone());
954        let id = registry
955            .spawn(
956                &session,
957                "echo started; sleep 30",
958                dir.path(),
959                &HashMap::new(),
960            )
961            .unwrap();
962        let mut seen = String::new();
963        for _ in 0..100 {
964            let result = output_tool.execute(input(json!({"id": id}))).await;
965            seen.push_str(&result.content);
966            if seen.contains("started") {
967                break;
968            }
969            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
970        }
971        assert!(seen.contains("started"), "{seen}");
972        assert!(seen.contains("running"));
973
974        let listed = output_tool.execute(input(json!({}))).await;
975        assert!(listed.content.contains(&id));
976
977        let killed = kill_tool.execute(input(json!({"id": id}))).await;
978        assert!(killed.content.contains("exited"), "{}", killed.content);
979
980        let other_session = output_tool
981            .execute(json!({"id": id, "__microclaw_auth": {"caller_channel": "other", "caller_chat_id": 2, "control_chat_ids": []}}))
982            .await;
983        assert!(other_session.is_error);
984    }
985
986    #[cfg(unix)]
987    #[tokio::test]
988    async fn dropping_the_registry_kills_running_processes() {
989        let dir = tempfile::tempdir().unwrap();
990        let registry = Arc::new(ProcessRegistry::default());
991        let id = registry
992            .spawn("s", "sleep 30", dir.path(), &HashMap::new())
993            .unwrap();
994        let process = registry.lookup("s", &id).unwrap();
995        drop(registry);
996        for _ in 0..100 {
997            if lock(&process.exit_code).is_some() {
998                break;
999            }
1000            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
1001        }
1002        assert!(
1003            lock(&process.exit_code).is_some(),
1004            "process should be killed"
1005        );
1006    }
1007}