harn_hostlib/process/
real.rs

1//! Production [`ProcessSpawner`] implementation backed by
2//! `std::process::Command` + `harn_vm::process_sandbox`.
3
4use std::io::{self, Read, Write};
5use std::process::{Child, ChildStderr, ChildStdin, ChildStdout, Stdio};
6use std::sync::{Arc, LazyLock};
7use std::thread;
8use std::time::{Duration, Instant};
9
10use harn_vm::process_sandbox;
11
12use super::handle::{
13    EnvMode, ExitStatus, ProcessError, ProcessHandle, ProcessKiller, ProcessSpawner, SpawnSpec,
14    WaitOutcome,
15};
16
17/// Spawner that produces real OS processes via `std::process::Command`.
18pub struct RealSpawner;
19
20static REAL_SPAWNER: LazyLock<Arc<dyn ProcessSpawner>> =
21    LazyLock::new(|| Arc::new(RealSpawner) as Arc<dyn ProcessSpawner>);
22
23/// Returns the singleton real spawner used as the default.
24pub fn default_spawner() -> Arc<dyn ProcessSpawner> {
25    Arc::clone(&REAL_SPAWNER)
26}
27
28impl ProcessSpawner for RealSpawner {
29    fn spawn(&self, spec: SpawnSpec) -> Result<Box<dyn ProcessHandle>, ProcessError> {
30        if spec.program.is_empty() {
31            return Err(ProcessError::InvalidArgv(
32                "first element of argv must be a non-empty program name".to_string(),
33            ));
34        }
35
36        let mut command = process_sandbox::std_command_for(&spec.program, &spec.args)
37            .map_err(|e| ProcessError::SandboxSetup(format!("{e:?}")))?;
38
39        if let Some(cwd) = spec.cwd.as_ref() {
40            process_sandbox::enforce_process_cwd(cwd)
41                .map_err(|e| ProcessError::SandboxCwd(format!("{e:?}")))?;
42            command.current_dir(cwd);
43        }
44
45        match spec.env_mode {
46            // `Replace` starts from an empty environment, so nothing to strip.
47            EnvMode::Replace => {
48                command.env_clear();
49            }
50            // `InheritClean`/`Patch` inherit the full parent environment. Strip
51            // secret-bearing variables (provider `*_API_KEY`s, `GITHUB_TOKEN`,
52            // `HARN_CLOUD_API_KEY`, etc.) so build/test commands — and the model
53            // that reads their stdout as the tool result — never see them.
54            // Caller-supplied `env` below is applied afterward and is an
55            // explicit opt-in, so it is intentionally not filtered here.
56            EnvMode::InheritClean | EnvMode::Patch => {
57                for (key, _) in std::env::vars_os() {
58                    if let Some(name) = key.to_str() {
59                        if super::handle::is_sensitive_env_name(name) {
60                            command.env_remove(&key);
61                        }
62                    }
63                }
64            }
65        }
66        for (key, value) in &spec.env {
67            command.env(key, value);
68        }
69
70        // Point the child's temp dir at a sandbox-writable, workspace-local
71        // location so compiler linkers (rustc/cc/ld, Go, Swift, …) and other
72        // toolchains that honor TMPDIR/TMP/TEMP don't false-fail trying to write
73        // intermediates to the unwritable system /tmp under a restricted
74        // sandbox profile. Applied after the caller's `spec.env` so an explicit
75        // caller-set TMPDIR wins; only keys the caller did not set receive the
76        // overlay. No-op when the active profile is unrestricted or no writable
77        // workspace root is available. TMPDIR/TMP/TEMP are workspace paths, not
78        // secrets, so this does not widen the env-secret-scrub surface above.
79        for (key, value) in process_sandbox::active_workspace_tmpdir_env() {
80            if spec.env.contains_key(&key) {
81                continue;
82            }
83            command.env(key, value);
84        }
85
86        // Pin tool *message* output to a deterministic English/UTF-8 locale so
87        // downstream English-diagnostic matchers (deterministic syntax repair,
88        // error-signature grounding, completion/pass-fail classification) do not
89        // misfire for a non-Anglosphere user whose shell localizes compiler/test
90        // output. A user-inherited `LC_ALL` overrides `LC_MESSAGES`, so strip it
91        // first — unless the caller pinned it. Then apply the overlay with the
92        // same caller-wins rule as the TMPDIR overlay above.
93        if !spec
94            .env
95            .contains_key(process_sandbox::MESSAGE_LOCALE_OVERRIDE_ENV)
96        {
97            command.env_remove(process_sandbox::MESSAGE_LOCALE_OVERRIDE_ENV);
98        }
99        for (key, value) in process_sandbox::deterministic_message_locale_env() {
100            if spec.env.contains_key(&key) {
101                continue;
102            }
103            command.env(key, value);
104        }
105
106        if spec.configure_process_group {
107            configure_background_process_group(&mut command);
108        }
109
110        command.stdout(Stdio::piped());
111        command.stderr(Stdio::piped());
112        command.stdin(if spec.use_stdin {
113            Stdio::piped()
114        } else {
115            Stdio::null()
116        });
117
118        let child = command.spawn().map_err(|e| {
119            if let Some(violation) = process_sandbox::process_spawn_error(&e) {
120                return ProcessError::SandboxSpawn(format!("{violation:?}"));
121            }
122            ProcessError::Spawn(format!("{e}"))
123        })?;
124
125        let pid = child.id();
126        let pgid = child_process_group_id(pid);
127        let killer: Arc<dyn ProcessKiller> = Arc::new(RealKiller { pid });
128
129        Ok(Box::new(RealProcess {
130            pid,
131            pgid,
132            killer,
133            child: Some(child),
134            stdin: None,
135            stdout: None,
136            stderr: None,
137            stdin_taken: false,
138            stdout_taken: false,
139            stderr_taken: false,
140        }))
141    }
142}
143
144struct RealProcess {
145    pid: u32,
146    pgid: Option<u32>,
147    killer: Arc<dyn ProcessKiller>,
148    child: Option<Child>,
149    stdin: Option<ChildStdin>,
150    stdout: Option<ChildStdout>,
151    stderr: Option<ChildStderr>,
152    stdin_taken: bool,
153    stdout_taken: bool,
154    stderr_taken: bool,
155}
156
157impl RealProcess {
158    fn ensure_pipes_taken(&mut self) {
159        if let Some(child) = self.child.as_mut() {
160            if self.stdin.is_none() && !self.stdin_taken {
161                self.stdin = child.stdin.take();
162            }
163            if self.stdout.is_none() && !self.stdout_taken {
164                self.stdout = child.stdout.take();
165            }
166            if self.stderr.is_none() && !self.stderr_taken {
167                self.stderr = child.stderr.take();
168            }
169        }
170    }
171}
172
173impl ProcessHandle for RealProcess {
174    fn pid(&self) -> Option<u32> {
175        Some(self.pid)
176    }
177
178    fn process_group_id(&self) -> Option<u32> {
179        self.pgid
180    }
181
182    fn killer(&self) -> Arc<dyn ProcessKiller> {
183        Arc::clone(&self.killer)
184    }
185
186    fn take_stdin(&mut self) -> Option<Box<dyn Write + Send>> {
187        self.ensure_pipes_taken();
188        self.stdin_taken = true;
189        self.stdin
190            .take()
191            .map(|s| Box::new(s) as Box<dyn Write + Send>)
192    }
193
194    fn take_stdout(&mut self) -> Option<Box<dyn Read + Send>> {
195        self.ensure_pipes_taken();
196        self.stdout_taken = true;
197        self.stdout
198            .take()
199            .map(|s| Box::new(s) as Box<dyn Read + Send>)
200    }
201
202    fn take_stderr(&mut self) -> Option<Box<dyn Read + Send>> {
203        self.ensure_pipes_taken();
204        self.stderr_taken = true;
205        self.stderr
206            .take()
207            .map(|s| Box::new(s) as Box<dyn Read + Send>)
208    }
209
210    fn wait_with_timeout(
211        &mut self,
212        timeout: Option<Duration>,
213        interrupt: &dyn Fn() -> bool,
214    ) -> io::Result<WaitOutcome> {
215        let killer = Arc::clone(&self.killer);
216        let Some(child) = self.child.as_mut() else {
217            return Err(io::Error::other("child already reaped"));
218        };
219        let deadline = timeout.map(|timeout| Instant::now() + timeout);
220        loop {
221            match child.try_wait()? {
222                Some(status) => return Ok(WaitOutcome::Exited(decode_status(status))),
223                None => {
224                    if interrupt() {
225                        // Scope cancellation / deadline expiry: graceful
226                        // group termination (SIGTERM, grace, SIGKILL) shared
227                        // with the VM-side `process.*` builtins.
228                        harn_vm::op_interrupt::terminate_child_group(child);
229                        return Ok(WaitOutcome::Interrupted);
230                    }
231                    if deadline.is_some_and(|deadline| Instant::now() >= deadline) {
232                        // `killer.kill()` kills the process tree/group on
233                        // Unix. That path is a no-op on non-Unix targets, so
234                        // also kill the child handle directly
235                        // (TerminateProcess on Windows) to guarantee the
236                        // subsequent `child.wait()` cannot block forever on a
237                        // timed-out process.
238                        killer.kill();
239                        let _ = child.kill();
240                        let _ = child.wait();
241                        return Ok(WaitOutcome::TimedOut);
242                    }
243                    let sleep = deadline
244                        .map(|deadline| deadline.saturating_duration_since(Instant::now()))
245                        .unwrap_or(Duration::MAX)
246                        .min(Duration::from_millis(20));
247                    thread::sleep(sleep);
248                }
249            }
250        }
251    }
252
253    fn wait(&mut self) -> io::Result<ExitStatus> {
254        let child = self
255            .child
256            .as_mut()
257            .ok_or_else(|| io::Error::other("child already reaped"))?;
258        let status = child.wait()?;
259        Ok(decode_status(status))
260    }
261}
262
263struct RealKiller {
264    pid: u32,
265}
266
267impl ProcessKiller for RealKiller {
268    fn kill(&self) {
269        harn_vm::op_interrupt::signal_pid_tree_and_group(self.pid, 9);
270    }
271}
272
273#[cfg(unix)]
274fn decode_status(status: std::process::ExitStatus) -> ExitStatus {
275    use std::os::unix::process::ExitStatusExt;
276    if let Some(code) = status.code() {
277        ExitStatus::from_code(code)
278    } else if let Some(sig) = status.signal() {
279        ExitStatus::from_signal(sig)
280    } else {
281        ExitStatus {
282            code: None,
283            signal: None,
284        }
285    }
286}
287
288#[cfg(not(unix))]
289fn decode_status(status: std::process::ExitStatus) -> ExitStatus {
290    ExitStatus::from_code(status.code().unwrap_or(-1))
291}
292
293pub(crate) fn child_process_group_id(pid: u32) -> Option<u32> {
294    #[cfg(unix)]
295    {
296        extern "C" {
297            fn getpgid(pid: i32) -> i32;
298        }
299        let pgid = unsafe { getpgid(pid as i32) };
300        if pgid > 0 {
301            Some(pgid as u32)
302        } else {
303            None
304        }
305    }
306    #[cfg(not(unix))]
307    {
308        Some(pid)
309    }
310}
311
312pub(crate) fn configure_background_process_group(command: &mut std::process::Command) {
313    #[cfg(unix)]
314    unsafe {
315        use std::os::unix::process::CommandExt;
316        command.pre_exec(|| {
317            extern "C" {
318                fn setpgid(pid: i32, pgid: i32) -> i32;
319            }
320            if setpgid(0, 0) == -1 {
321                return Err(std::io::Error::last_os_error());
322            }
323            Ok(())
324        });
325    }
326    #[cfg(not(unix))]
327    {
328        let _ = command;
329    }
330}
harn_hostlib/process/real.rs

harn_hostlib/process/
real.rs
