Skip to main content

arabica_runner/
lib.rs

1//! Runner environment boundary and concrete execution backends.
2//!
3//! This crate owns real tool execution, ordered stdout/stderr, cancellation,
4//! filesystem confinement, and future process/container/remote runners. It
5//! does not call model APIs or own sessions, memory, or UI concerns.
6
7pub mod definitions;
8pub mod output;
9pub mod shell;
10pub mod shell_classifier;
11
12pub use definitions::{
13    definition, delete_file_definition, edit_files_definition, find_files_definition,
14    grep_definition, list_dir_definition, read_file_definition, shell_definition, tool_definitions,
15    write_file_definition,
16};
17pub use output::{MAX_TOOL_OUTPUT_CHARS, truncate_output};
18pub use shell::ShellPolicy;
19pub use shell_classifier::classify_shell_interaction;
20
21use std::collections::{BTreeSet, HashSet};
22use std::error::Error;
23use std::fmt::{Display, Formatter};
24use std::path::{Component, Path, PathBuf};
25
26use arabica_model::{ContentBlock, ToolCallItem, ToolResultItem};
27use arabica_protocol::{RunId, ToolInteractionKind};
28use serde::{Deserialize, Serialize};
29
30const MAX_LOCAL_READ_BYTES: u64 = 1024 * 1024;
31
32#[derive(Clone, Debug, Eq, PartialEq)]
33pub enum RunnerOutput {
34    Stdout(String),
35    Stderr(String),
36}
37
38#[derive(Clone, Debug, Eq, PartialEq)]
39pub struct RunnerError {
40    message: String,
41}
42
43impl RunnerError {
44    pub fn new(message: impl Into<String>) -> Self {
45        Self {
46            message: message.into(),
47        }
48    }
49}
50
51impl Display for RunnerError {
52    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
53        self.message.fmt(formatter)
54    }
55}
56
57impl Error for RunnerError {}
58
59#[derive(Clone, Debug, Eq, PartialEq)]
60pub struct ToolExecutionRequest {
61    pub run_id: RunId,
62    pub call: ToolCallItem,
63}
64
65#[derive(Clone, Debug, Eq, PartialEq)]
66pub struct ToolExecutionResult {
67    pub result: ToolResultItem,
68    pub output: Vec<RunnerOutput>,
69}
70
71#[allow(async_fn_in_trait)]
72pub trait RunnerEnvironment {
73    fn classify(&self, _call: &ToolCallItem) -> ToolInteractionKind {
74        ToolInteractionKind::Generic
75    }
76
77    async fn execute(
78        &mut self,
79        request: ToolExecutionRequest,
80    ) -> Result<ToolExecutionResult, RunnerError>;
81    async fn cancel(&mut self, run_id: &RunId) -> Result<bool, RunnerError>;
82}
83
84#[derive(Debug, Default)]
85pub struct NoopRunner;
86
87impl RunnerEnvironment for NoopRunner {
88    async fn execute(
89        &mut self,
90        _request: ToolExecutionRequest,
91    ) -> Result<ToolExecutionResult, RunnerError> {
92        Err(RunnerError::new("no execution environment is configured"))
93    }
94
95    async fn cancel(&mut self, _run_id: &RunId) -> Result<bool, RunnerError> {
96        Ok(false)
97    }
98}
99
100/// One tool the local runner can execute.
101///
102/// A tool absent from the active [`LocalRunnerPolicy`] is treated as unknown:
103/// it is neither advertised nor executable, and a model that names it anyway
104/// gets the same error as for a tool that does not exist. Enabling execution is
105/// therefore an explicit decision by the host, not a consequence of the model
106/// guessing a name.
107#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
108#[serde(rename_all = "snake_case")]
109pub enum LocalTool {
110    ReadFile,
111    ListDir,
112    Grep,
113    FindFiles,
114    WriteFile,
115    EditFiles,
116    DeleteFile,
117    Shell,
118}
119
120impl LocalTool {
121    pub const fn name(self) -> &'static str {
122        match self {
123            Self::ReadFile => "read_file",
124            Self::ListDir => "list_dir",
125            Self::Grep => "grep",
126            Self::FindFiles => "find_files",
127            Self::WriteFile => "write_file",
128            Self::EditFiles => "edit_files",
129            Self::DeleteFile => "delete_file",
130            Self::Shell => "shell",
131        }
132    }
133
134    pub const fn interaction(self) -> ToolInteractionKind {
135        match self {
136            Self::ReadFile | Self::ListDir | Self::Grep | Self::FindFiles => {
137                ToolInteractionKind::Inspection
138            }
139            Self::WriteFile | Self::EditFiles | Self::DeleteFile => ToolInteractionKind::Mutation,
140            // A command's effect depends on its text; the runner classifies
141            // each call from the command instead of from the tool name.
142            Self::Shell => ToolInteractionKind::Generic,
143        }
144    }
145
146    /// Whether this tool is one of the mutually exclusive edit formats.
147    ///
148    /// Exactly one may be enabled at a time: offering a model two ways to
149    /// modify a file makes it choose before it edits, and that choice is one
150    /// more thing to get wrong. A second format (an `apply_patch` style whole
151    /// diff) is meant to be compared against this one, not offered beside it.
152    pub const fn is_edit_format(self) -> bool {
153        matches!(self, Self::EditFiles)
154    }
155
156    fn from_name(name: &str) -> Option<Self> {
157        [
158            Self::ReadFile,
159            Self::ListDir,
160            Self::Grep,
161            Self::FindFiles,
162            Self::WriteFile,
163            Self::EditFiles,
164            Self::DeleteFile,
165            Self::Shell,
166        ]
167        .into_iter()
168        .find(|tool| tool.name() == name)
169    }
170}
171
172/// Which tools a [`LocalRunner`] advertises and will execute, plus the output
173/// bounds that keep a single tool result from exhausting the context window.
174///
175/// The policy deserializes from a config file (`[runner]` in TOML, say), so a
176/// host can load it; loading and merging files is the host's job. A host that
177/// layers project configuration over user configuration must only let the
178/// project tighten it: a repository that could enable `shell` or empty
179/// `shell.scrub_env` could run code or read the user's credentials.
180#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
181#[serde(default, deny_unknown_fields)]
182pub struct LocalRunnerPolicy {
183    pub tools: BTreeSet<LocalTool>,
184    /// Prefix each `read_file` line with its 1-based number. Off in the legacy
185    /// policy because the benchmark campaigns recorded output without it.
186    pub read_line_numbers: bool,
187    pub max_read_bytes: u64,
188    pub max_list_entries: usize,
189    pub max_grep_matches: usize,
190    pub max_find_results: usize,
191    pub max_match_line_chars: usize,
192    pub shell: ShellPolicy,
193}
194
195impl LocalRunnerPolicy {
196    /// The pre-existing surface: read and write, no line numbers. Keeping this
197    /// the default preserves the behavior every recorded campaign depends on.
198    pub fn legacy() -> Self {
199        Self {
200            tools: BTreeSet::from([LocalTool::ReadFile, LocalTool::WriteFile]),
201            read_line_numbers: false,
202            max_read_bytes: MAX_LOCAL_READ_BYTES,
203            max_list_entries: 1_000,
204            max_grep_matches: 200,
205            max_find_results: 500,
206            max_match_line_chars: 300,
207            shell: ShellPolicy::default(),
208        }
209    }
210
211    /// Inspection only: nothing in this set can change the workspace, so a host
212    /// may run it without asking the user.
213    pub fn read_only() -> Self {
214        Self {
215            tools: BTreeSet::from([
216                LocalTool::ReadFile,
217                LocalTool::ListDir,
218                LocalTool::Grep,
219                LocalTool::FindFiles,
220            ]),
221            read_line_numbers: true,
222            ..Self::legacy()
223        }
224    }
225
226    /// Read-only exploration plus the mutation tools a coding agent needs.
227    ///
228    /// Shell is deliberately absent: it cannot be confined to the root, so a
229    /// host adds it only when it can ask the user first.
230    pub fn coding() -> Self {
231        Self {
232            tools: BTreeSet::from([
233                LocalTool::ReadFile,
234                LocalTool::ListDir,
235                LocalTool::Grep,
236                LocalTool::FindFiles,
237                LocalTool::WriteFile,
238                LocalTool::EditFiles,
239                LocalTool::DeleteFile,
240            ]),
241            ..Self::read_only()
242        }
243    }
244
245    /// Enabled edit formats. More than one is a configuration error; see
246    /// [`LocalTool::is_edit_format`].
247    pub fn edit_formats(&self) -> Vec<LocalTool> {
248        self.tools
249            .iter()
250            .copied()
251            .filter(|tool| tool.is_edit_format())
252            .collect()
253    }
254
255    /// Reject a policy that is internally inconsistent.
256    ///
257    /// A host must call this after loading a policy from a file: serde checks
258    /// shape, not meaning.
259    pub fn validate(&self) -> Result<(), RunnerError> {
260        let formats = self.edit_formats();
261        if formats.len() > 1 {
262            return Err(RunnerError::new(format!(
263                "at most one edit format may be enabled, found {}",
264                formats
265                    .iter()
266                    .map(|tool| tool.name())
267                    .collect::<Vec<_>>()
268                    .join(", ")
269            )));
270        }
271        for (name, value) in [
272            ("max_list_entries", self.max_list_entries),
273            ("max_grep_matches", self.max_grep_matches),
274            ("max_find_results", self.max_find_results),
275            ("max_match_line_chars", self.max_match_line_chars),
276        ] {
277            if value == 0 {
278                return Err(RunnerError::new(format!("{name} must be positive")));
279            }
280        }
281        if self.max_read_bytes == 0 {
282            return Err(RunnerError::new("max_read_bytes must be positive"));
283        }
284        self.shell.validate()
285    }
286
287    #[must_use]
288    pub fn with_tool(mut self, tool: LocalTool) -> Self {
289        self.tools.insert(tool);
290        self
291    }
292
293    pub fn allows(&self, tool: LocalTool) -> bool {
294        self.tools.contains(&tool)
295    }
296}
297
298impl Default for LocalRunnerPolicy {
299    fn default() -> Self {
300        Self::legacy()
301    }
302}
303
304/// Real local execution environment confined to one existing filesystem root.
305#[derive(Debug)]
306pub struct LocalRunner {
307    root: PathBuf,
308    policy: LocalRunnerPolicy,
309    active_runs: HashSet<RunId>,
310    canonical_root: std::sync::OnceLock<PathBuf>,
311}
312
313impl LocalRunner {
314    pub fn new(root: impl Into<PathBuf>) -> Self {
315        Self::with_policy(root, LocalRunnerPolicy::legacy())
316    }
317
318    pub fn with_policy(root: impl Into<PathBuf>, policy: LocalRunnerPolicy) -> Self {
319        Self {
320            root: root.into(),
321            policy,
322            active_runs: HashSet::new(),
323            canonical_root: std::sync::OnceLock::new(),
324        }
325    }
326
327    pub fn root(&self) -> &Path {
328        &self.root
329    }
330
331    pub fn policy(&self) -> &LocalRunnerPolicy {
332        &self.policy
333    }
334
335    fn enabled_tool(&self, name: &str) -> Option<LocalTool> {
336        LocalTool::from_name(name).filter(|tool| self.policy.allows(*tool))
337    }
338
339    /// Resolve a regular file inside the root, refusing symbolic links and any
340    /// path that escapes. Returns the canonical path and its size.
341    async fn resolve_regular_file(
342        &self,
343        path: &str,
344        tool: &str,
345    ) -> Result<(PathBuf, u64), RunnerError> {
346        let relative = validate_local_path(path)?;
347        let root = self.canonical_root().await?;
348        let unresolved_target = root.join(relative);
349        let unresolved_metadata = tokio::fs::symlink_metadata(&unresolved_target)
350            .await
351            .map_err(|error| RunnerError::new(format!("local file unavailable: {error}")))?;
352        if unresolved_metadata.file_type().is_symlink() {
353            return Err(RunnerError::new(format!("{tool} refuses symbolic links")));
354        }
355        let target = tokio::fs::canonicalize(unresolved_target)
356            .await
357            .map_err(|error| RunnerError::new(format!("local file unavailable: {error}")))?;
358        if !target.starts_with(&root) {
359            return Err(RunnerError::new("local file path escapes runner root"));
360        }
361        let metadata = tokio::fs::metadata(&target)
362            .await
363            .map_err(|error| RunnerError::new(format!("local file unavailable: {error}")))?;
364        if !metadata.is_file() {
365            return Err(RunnerError::new("local path is not a regular file"));
366        }
367        Ok((target, metadata.len()))
368    }
369
370    /// Resolve a file this runner may read whole, enforcing the size cap.
371    ///
372    /// `tool` names the caller so a refusal says which tool refused. `read_file`
373    /// keeps its original wording because recorded campaigns contain it.
374    async fn resolve_readable_file(&self, path: &str, tool: &str) -> Result<PathBuf, RunnerError> {
375        let (target, size) = self.resolve_regular_file(path, tool).await?;
376        let limit = self.policy.max_read_bytes;
377        if size > limit {
378            return Err(RunnerError::new(format!(
379                "{tool} exceeds the {limit}-byte limit"
380            )));
381        }
382        Ok(target)
383    }
384
385    async fn resolve_existing_file(&self, path: &str) -> Result<PathBuf, RunnerError> {
386        self.resolve_readable_file(path, "read_file").await
387    }
388
389    async fn read_file(&self, arguments: &serde_json::Value) -> Result<String, RunnerError> {
390        let path = arguments
391            .get("path")
392            .and_then(serde_json::Value::as_str)
393            .ok_or_else(|| RunnerError::new("read_file.path must be a string"))?;
394        let target = self.resolve_existing_file(path).await?;
395        let content = tokio::fs::read_to_string(&target)
396            .await
397            .map_err(|error| RunnerError::new(format!("read_file failed: {error}")))?;
398        if !self.policy.read_line_numbers {
399            return Ok(content);
400        }
401        // Line numbers let an edit tool report a near-miss by location and give
402        // the model a stable way to talk about a region it has not copied.
403        use std::fmt::Write;
404        let mut numbered = String::with_capacity(content.len().saturating_add(64));
405        for (index, line) in content.lines().enumerate() {
406            if index > 0 {
407                numbered.push('\n');
408            }
409            let _ = write!(numbered, "{:>6}\t{line}", index + 1);
410        }
411        Ok(numbered)
412    }
413
414    async fn write_file(&self, arguments: &serde_json::Value) -> Result<String, RunnerError> {
415        let path = arguments
416            .get("path")
417            .and_then(serde_json::Value::as_str)
418            .ok_or_else(|| RunnerError::new("write_file.path must be a string"))?;
419        let content = arguments
420            .get("content")
421            .and_then(serde_json::Value::as_str)
422            .ok_or_else(|| RunnerError::new("write_file.content must be a string"))?;
423        let relative = validate_local_path(path)?;
424        let root = self.canonical_root().await?;
425        let target = root.join(relative);
426        let parent = tokio::fs::canonicalize(
427            target
428                .parent()
429                .ok_or_else(|| RunnerError::new("write_file path has no parent"))?,
430        )
431        .await
432        .map_err(|error| RunnerError::new(format!("write_file parent unavailable: {error}")))?;
433        if !parent.starts_with(&root) {
434            return Err(RunnerError::new("write_file path escapes runner root"));
435        }
436        if let Ok(metadata) = tokio::fs::symlink_metadata(&target).await
437            && metadata.file_type().is_symlink()
438        {
439            return Err(RunnerError::new("write_file refuses symbolic links"));
440        }
441        tokio::fs::write(&target, content)
442            .await
443            .map_err(|error| RunnerError::new(format!("write_file failed: {error}")))?;
444        Ok(format!(
445            "wrote {} bytes to {}",
446            content.len(),
447            target.display()
448        ))
449    }
450
451    async fn canonical_root(&self) -> Result<PathBuf, RunnerError> {
452        if let Some(root) = self.canonical_root.get() {
453            return Ok(root.clone());
454        }
455        let root = tokio::fs::canonicalize(&self.root)
456            .await
457            .map_err(|error| RunnerError::new(format!("local runner root unavailable: {error}")))?;
458        let _ = self.canonical_root.set(root.clone());
459        Ok(root)
460    }
461
462    /// Resolve an optional relative `path` argument against the root. A missing
463    /// argument means the root itself, because `validate_local_path` rejects
464    /// `.` and an agent should not have to spell the root differently.
465    async fn resolve_directory(
466        &self,
467        arguments: &serde_json::Value,
468    ) -> Result<PathBuf, RunnerError> {
469        let root = self.canonical_root().await?;
470        let Some(path) = arguments.get("path").and_then(serde_json::Value::as_str) else {
471            return Ok(root);
472        };
473        let relative = validate_local_path(path)?;
474        let target = tokio::fs::canonicalize(root.join(relative))
475            .await
476            .map_err(|error| RunnerError::new(format!("local directory unavailable: {error}")))?;
477        if !target.starts_with(&root) {
478            return Err(RunnerError::new("local path escapes runner root"));
479        }
480        Ok(target)
481    }
482
483    async fn list_dir(&self, arguments: &serde_json::Value) -> Result<String, RunnerError> {
484        let target = self.resolve_directory(arguments).await?;
485        let mut reader = tokio::fs::read_dir(&target)
486            .await
487            .map_err(|error| RunnerError::new(format!("list_dir failed: {error}")))?;
488        let mut names = Vec::new();
489        while let Some(entry) = reader
490            .next_entry()
491            .await
492            .map_err(|error| RunnerError::new(format!("list_dir failed: {error}")))?
493        {
494            let mut name = entry
495                .file_name()
496                .into_string()
497                .unwrap_or_else(|os| os.to_string_lossy().into_owned());
498            let file_type = entry
499                .file_type()
500                .await
501                .map_err(|error| RunnerError::new(format!("list_dir failed: {error}")))?;
502            // Symbolic links are marked and never followed, matching read_file
503            // and write_file.
504            if file_type.is_symlink() {
505                name.push('@');
506            } else if file_type.is_dir() {
507                name.push('/');
508            }
509            names.push(name);
510        }
511        if names.is_empty() {
512            return Ok("(empty directory)".to_owned());
513        }
514        names.sort();
515        let total = names.len();
516        names.truncate(self.policy.max_list_entries);
517        if total > names.len() {
518            names.push(format!(
519                "...[{} more entries; narrow the path]...",
520                total - names.len() + 1
521            ));
522        }
523        Ok(names.join("\n"))
524    }
525
526    async fn grep(&self, arguments: &serde_json::Value) -> Result<String, RunnerError> {
527        let pattern = arguments
528            .get("pattern")
529            .and_then(serde_json::Value::as_str)
530            .ok_or_else(|| RunnerError::new("grep.pattern must be a string"))?;
531        let regex = regex::Regex::new(pattern).map_err(|error| {
532            RunnerError::new(format!(
533                "grep.pattern is not a valid regular expression: {error}"
534            ))
535        })?;
536        let root = self.canonical_root().await?;
537        let target = self.resolve_directory(arguments).await?;
538        let max_matches = self.policy.max_grep_matches;
539        let max_line_chars = self.policy.max_match_line_chars;
540        let max_bytes = self.policy.max_read_bytes;
541        // The walker and its file reads are blocking, so they must not run on a
542        // runtime worker that also drives the model request.
543        tokio::task::spawn_blocking(move || {
544            grep_blocking(
545                &root,
546                &target,
547                &regex,
548                max_matches,
549                max_line_chars,
550                max_bytes,
551            )
552        })
553        .await
554        .map_err(|error| RunnerError::new(format!("grep failed: {error}")))?
555    }
556
557    async fn find_files(&self, arguments: &serde_json::Value) -> Result<String, RunnerError> {
558        let glob = arguments
559            .get("glob")
560            .and_then(serde_json::Value::as_str)
561            .ok_or_else(|| RunnerError::new("find_files.glob must be a string"))?;
562        let matcher = globset::GlobBuilder::new(glob)
563            .literal_separator(true)
564            .build()
565            .map_err(|error| {
566                RunnerError::new(format!("find_files.glob is not a valid glob: {error}"))
567            })?
568            .compile_matcher();
569        let root = self.canonical_root().await?;
570        let target = self.resolve_directory(arguments).await?;
571        let max_results = self.policy.max_find_results;
572        tokio::task::spawn_blocking(move || {
573            find_files_blocking(&root, &target, &matcher, max_results)
574        })
575        .await
576        .map_err(|error| RunnerError::new(format!("find_files failed: {error}")))?
577    }
578
579    /// Apply a batch of exact string replacements across one or more files.
580    ///
581    /// Every edit is validated and applied in memory before anything is
582    /// written, so a batch that fails validation changes nothing on disk. Two
583    /// edits to the same file apply in order, and the second sees the result of
584    /// the first. Writing is still per file, so an I/O failure part way through
585    /// can leave earlier files written; the result reports what was applied.
586    async fn edit_files(&self, arguments: &serde_json::Value) -> Result<String, RunnerError> {
587        let edits = arguments
588            .get("edits")
589            .and_then(serde_json::Value::as_array)
590            .ok_or_else(|| RunnerError::new("edit_files.edits must be an array"))?;
591        if edits.is_empty() {
592            return Err(RunnerError::new("edit_files.edits must not be empty"));
593        }
594        let mut pending: Vec<(PathBuf, String)> = Vec::new();
595        let mut applied: Vec<String> = Vec::new();
596        for (index, edit) in edits.iter().enumerate() {
597            let at = index + 1;
598            let field = |name: &str| -> Result<String, RunnerError> {
599                edit.get(name)
600                    .and_then(serde_json::Value::as_str)
601                    .map(str::to_owned)
602                    .ok_or_else(|| {
603                        RunnerError::new(format!("edit_files.edits[{at}].{name} must be a string"))
604                    })
605            };
606            let path = field("path")?;
607            let old_string = field("old_string")?;
608            let new_string = field("new_string")?;
609            let replace_all = edit
610                .get("replace_all")
611                .and_then(serde_json::Value::as_bool)
612                .unwrap_or(false);
613            if old_string.is_empty() {
614                return Err(RunnerError::new(format!(
615                    "edit_files.edits[{at}].old_string must not be empty; use write_file to create or replace a whole file"
616                )));
617            }
618            if old_string == new_string {
619                return Err(RunnerError::new(format!(
620                    "edit_files.edits[{at}] leaves {path} unchanged"
621                )));
622            }
623            let target = self.resolve_readable_file(&path, "edit_files").await?;
624            let current = match pending.iter().find(|(known, _)| known == &target) {
625                Some((_, content)) => content.clone(),
626                None => tokio::fs::read_to_string(&target)
627                    .await
628                    .map_err(|error| RunnerError::new(format!("edit_files failed: {error}")))?,
629            };
630            let matches = current.matches(old_string.as_str()).count();
631            if matches == 0 {
632                return Err(RunnerError::new(format!(
633                    "edit_files.edits[{at}] found no match in {path}{}",
634                    near_miss_hint(&current, &old_string)
635                )));
636            }
637            if matches > 1 && !replace_all {
638                return Err(RunnerError::new(format!(
639                    "edit_files.edits[{at}] matched {matches} times in {path}; extend old_string until it is unique, or set replace_all"
640                )));
641            }
642            let updated = if replace_all {
643                current.replace(old_string.as_str(), &new_string)
644            } else {
645                current.replacen(old_string.as_str(), &new_string, 1)
646            };
647            let count = if replace_all { matches } else { 1 };
648            match pending.iter_mut().find(|(known, _)| known == &target) {
649                Some((_, content)) => *content = updated,
650                None => pending.push((target, updated)),
651            }
652            applied.push(format!(
653                "{path}: {count} replacement{}",
654                if count == 1 { "" } else { "s" }
655            ));
656        }
657        for (target, content) in &pending {
658            tokio::fs::write(target, content).await.map_err(|error| {
659                RunnerError::new(format!(
660                    "edit_files failed while writing {}: {error}",
661                    target.display()
662                ))
663            })?;
664        }
665        Ok(applied.join("\n"))
666    }
667
668    async fn delete_file(&self, arguments: &serde_json::Value) -> Result<String, RunnerError> {
669        let path = arguments
670            .get("path")
671            .and_then(serde_json::Value::as_str)
672            .ok_or_else(|| RunnerError::new("delete_file.path must be a string"))?;
673        // Deleting does not read the file, so the read size cap must not apply.
674        let (target, _) = self.resolve_regular_file(path, "delete_file").await?;
675        tokio::fs::remove_file(&target)
676            .await
677            .map_err(|error| RunnerError::new(format!("delete_file failed: {error}")))?;
678        Ok(format!("deleted {path}"))
679    }
680}
681
682/// Point at the likely intended region when an exact match fails.
683///
684/// The usual cause is that the model reproduced the surrounding text from
685/// memory rather than from the file, so the first line is usually right even
686/// when the rest drifted.
687fn near_miss_hint(content: &str, old_string: &str) -> String {
688    let Some(first) = old_string.lines().next().map(str::trim) else {
689        return String::new();
690    };
691    if first.is_empty() {
692        return String::new();
693    }
694    let lines = content
695        .lines()
696        .enumerate()
697        .filter(|(_, line)| line.trim() == first)
698        .map(|(index, _)| (index + 1).to_string())
699        .take(5)
700        .collect::<Vec<_>>();
701    if lines.is_empty() {
702        return String::new();
703    }
704    format!(
705        "; its first line appears at line{} {}, so check the surrounding context and whitespace",
706        if lines.len() == 1 { "" } else { "s" },
707        lines.join(", ")
708    )
709}
710
711fn grep_blocking(
712    root: &Path,
713    target: &Path,
714    regex: &regex::Regex,
715    max_matches: usize,
716    max_line_chars: usize,
717    max_bytes: u64,
718) -> Result<String, RunnerError> {
719    let mut matches = Vec::new();
720    let mut truncated = false;
721    for entry in ignore::WalkBuilder::new(target).build().flatten() {
722        if !entry.file_type().is_some_and(|kind| kind.is_file()) {
723            continue;
724        }
725        let Ok(metadata) = entry.metadata() else {
726            continue;
727        };
728        if metadata.len() > max_bytes {
729            continue;
730        }
731        // A file that is not UTF-8 is binary for this purpose; skipping it is
732        // cheaper and safer than scanning for NUL bytes.
733        let Ok(content) = std::fs::read_to_string(entry.path()) else {
734            continue;
735        };
736        let mut display: Option<String> = None;
737        for (index, line) in content.lines().enumerate() {
738            if !regex.is_match(line) {
739                continue;
740            }
741            if matches.len() >= max_matches {
742                truncated = true;
743                break;
744            }
745            let file_display = display.get_or_insert_with(|| {
746                entry
747                    .path()
748                    .strip_prefix(root)
749                    .unwrap_or(entry.path())
750                    .display()
751                    .to_string()
752            });
753            let mut text = line.trim_end().to_owned();
754            if text.chars().count() > max_line_chars {
755                text = text.chars().take(max_line_chars).collect::<String>() + "...";
756            }
757            matches.push(format!("{file_display}:{}:{text}", index + 1));
758        }
759        if truncated {
760            break;
761        }
762    }
763    if matches.is_empty() {
764        return Ok("(no matches)".to_owned());
765    }
766    if truncated {
767        matches.push(format!(
768            "...[stopped at {max_matches} matches; narrow the pattern or path]..."
769        ));
770    }
771    Ok(matches.join("\n"))
772}
773
774fn find_files_blocking(
775    root: &Path,
776    target: &Path,
777    matcher: &globset::GlobMatcher,
778    max_results: usize,
779) -> Result<String, RunnerError> {
780    let mut paths = Vec::new();
781    let mut truncated = false;
782    for entry in ignore::WalkBuilder::new(target).build().flatten() {
783        if !entry.file_type().is_some_and(|kind| kind.is_file()) {
784            continue;
785        }
786        let relative = entry.path().strip_prefix(root).unwrap_or(entry.path());
787        if !matcher.is_match(relative) {
788            continue;
789        }
790        if paths.len() >= max_results {
791            truncated = true;
792            break;
793        }
794        paths.push(relative.display().to_string());
795    }
796    if paths.is_empty() {
797        return Ok("(no files matched)".to_owned());
798    }
799    paths.sort();
800    if truncated {
801        paths.push(format!(
802            "...[stopped at {max_results} files; narrow the glob]..."
803        ));
804    }
805    Ok(paths.join("\n"))
806}
807
808/// One tool call's result before it is wrapped for the Runtime.
809struct ToolRun {
810    content: String,
811    is_error: bool,
812    output: Vec<RunnerOutput>,
813}
814
815impl ToolRun {
816    /// A successful non-shell tool: its text is both the result and the one
817    /// stdout chunk, exactly as before this type existed.
818    fn text(content: String) -> Self {
819        Self {
820            output: vec![RunnerOutput::Stdout(content.clone())],
821            content,
822            is_error: false,
823        }
824    }
825
826    /// A shell call keeps its streams separate, so the Runtime can map them
827    /// one-for-one to `command.output` Events, and fails on a non-zero exit.
828    fn shell(outcome: shell::ShellOutcome) -> Self {
829        let mut output = Vec::new();
830        if !outcome.stdout.is_empty() {
831            output.push(RunnerOutput::Stdout(outcome.stdout));
832        }
833        if !outcome.stderr.is_empty() {
834            output.push(RunnerOutput::Stderr(outcome.stderr));
835        }
836        Self {
837            content: outcome.content,
838            is_error: outcome.is_error,
839            output,
840        }
841    }
842
843    fn failure(error: RunnerError) -> Self {
844        let message = error.to_string();
845        Self {
846            content: format!("error: {message}"),
847            is_error: true,
848            output: vec![RunnerOutput::Stderr(message)],
849        }
850    }
851}
852
853impl RunnerEnvironment for LocalRunner {
854    fn classify(&self, call: &ToolCallItem) -> ToolInteractionKind {
855        match self.enabled_tool(&call.name) {
856            // Memory retention only: this classification must never decide
857            // whether a command may run.
858            Some(LocalTool::Shell) => call
859                .arguments
860                .get("command")
861                .and_then(serde_json::Value::as_str)
862                .map_or(ToolInteractionKind::Generic, classify_shell_interaction),
863            Some(tool) => tool.interaction(),
864            None => ToolInteractionKind::Generic,
865        }
866    }
867
868    async fn execute(
869        &mut self,
870        request: ToolExecutionRequest,
871    ) -> Result<ToolExecutionResult, RunnerError> {
872        self.active_runs.insert(request.run_id.clone());
873        let arguments = &request.call.arguments;
874        let execution = match self.enabled_tool(&request.call.name) {
875            Some(LocalTool::ReadFile) => self.read_file(arguments).await.map(ToolRun::text),
876            Some(LocalTool::WriteFile) => self.write_file(arguments).await.map(ToolRun::text),
877            Some(LocalTool::ListDir) => self.list_dir(arguments).await.map(ToolRun::text),
878            Some(LocalTool::Grep) => self.grep(arguments).await.map(ToolRun::text),
879            Some(LocalTool::FindFiles) => self.find_files(arguments).await.map(ToolRun::text),
880            Some(LocalTool::EditFiles) => self.edit_files(arguments).await.map(ToolRun::text),
881            Some(LocalTool::DeleteFile) => self.delete_file(arguments).await.map(ToolRun::text),
882            Some(LocalTool::Shell) => match self.canonical_root().await {
883                Ok(root) => shell::run(&root, &self.policy.shell, arguments)
884                    .await
885                    .map(ToolRun::shell),
886                Err(error) => Err(error),
887            },
888            // A disabled tool is reported exactly like one that does not exist:
889            // the model was never told about it, and the reply must not reveal
890            // that the capability could be switched on.
891            None => Err(RunnerError::new(format!(
892                "unknown local tool: {}",
893                request.call.name
894            ))),
895        };
896        self.active_runs.remove(&request.run_id);
897        let ToolRun {
898            content,
899            is_error,
900            output,
901        } = execution.unwrap_or_else(ToolRun::failure);
902        Ok(ToolExecutionResult {
903            result: ToolResultItem {
904                id: None,
905                call_id: request.call.call_id,
906                name: Some(request.call.name),
907                content: vec![ContentBlock::text(content)],
908                is_error,
909            },
910            output,
911        })
912    }
913
914    async fn cancel(&mut self, run_id: &RunId) -> Result<bool, RunnerError> {
915        Ok(self.active_runs.remove(run_id))
916    }
917}
918
919fn validate_local_path(path: &str) -> Result<&Path, RunnerError> {
920    let path = Path::new(path);
921    if path.as_os_str().is_empty() || path.is_absolute() {
922        return Err(RunnerError::new(
923            "local path must be non-empty and relative",
924        ));
925    }
926    if path
927        .components()
928        .any(|component| !matches!(component, Component::Normal(_)))
929    {
930        return Err(RunnerError::new(
931            "local path must not contain '.', '..', or root components",
932        ));
933    }
934    Ok(path)
935}
936
937#[cfg(test)]
938mod tests {
939    use super::*;
940
941    /// Create an empty directory unique to one test.
942    async fn temp_root(label: &str) -> PathBuf {
943        let unique = std::time::SystemTime::now()
944            .duration_since(std::time::UNIX_EPOCH)
945            .expect("clock is valid")
946            .as_nanos();
947        let root = std::env::temp_dir().join(format!("arabica-runner-{label}-{unique}"));
948        tokio::fs::create_dir(&root)
949            .await
950            .expect("test root is created");
951        root
952    }
953
954    async fn call(runner: &mut LocalRunner, name: &str, arguments: serde_json::Value) -> String {
955        let result = runner
956            .execute(ToolExecutionRequest {
957                run_id: RunId::new("run-1"),
958                call: ToolCallItem {
959                    id: None,
960                    call_id: "call-1".to_owned(),
961                    name: name.to_owned(),
962                    arguments,
963                    provider_state: None,
964                },
965            })
966            .await
967            .expect("execution is reported");
968        match result.result.content.first() {
969            Some(ContentBlock::Text { text }) => text.clone(),
970            other => panic!("unexpected tool content: {other:?}"),
971        }
972    }
973
974    #[tokio::test]
975    async fn the_legacy_policy_hides_the_tools_it_does_not_enable() {
976        let root = temp_root("legacy").await;
977        let mut runner = LocalRunner::new(&root);
978        // A disabled tool must be indistinguishable from one that never
979        // existed, so a model cannot discover switched-off capabilities.
980        for name in ["list_dir", "grep", "find_files", "no_such_tool"] {
981            assert_eq!(
982                call(&mut runner, name, serde_json::json!({})).await,
983                format!("error: unknown local tool: {name}")
984            );
985        }
986        assert_eq!(
987            tool_definitions(&LocalRunnerPolicy::legacy())
988                .iter()
989                .map(|definition| definition.name.clone())
990                .collect::<Vec<_>>(),
991            vec!["read_file".to_owned(), "write_file".to_owned()]
992        );
993        tokio::fs::remove_dir_all(root).await.expect("cleanup");
994    }
995
996    #[tokio::test]
997    async fn the_read_only_policy_cannot_change_the_workspace() {
998        let root = temp_root("read-only").await;
999        let mut runner = LocalRunner::with_policy(&root, LocalRunnerPolicy::read_only());
1000        assert_eq!(
1001            call(
1002                &mut runner,
1003                "write_file",
1004                serde_json::json!({"path": "new.txt", "content": "blocked"})
1005            )
1006            .await,
1007            "error: unknown local tool: write_file"
1008        );
1009        assert!(!root.join("new.txt").exists());
1010        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1011    }
1012
1013    #[tokio::test]
1014    async fn read_file_numbers_lines_only_when_the_policy_asks() {
1015        let root = temp_root("line-numbers").await;
1016        tokio::fs::write(root.join("two.txt"), "alpha\nbeta\n")
1017            .await
1018            .expect("fixture is written");
1019
1020        let mut legacy = LocalRunner::new(&root);
1021        assert_eq!(
1022            call(
1023                &mut legacy,
1024                "read_file",
1025                serde_json::json!({"path": "two.txt"})
1026            )
1027            .await,
1028            "alpha\nbeta\n"
1029        );
1030
1031        let mut numbered = LocalRunner::with_policy(&root, LocalRunnerPolicy::read_only());
1032        assert_eq!(
1033            call(
1034                &mut numbered,
1035                "read_file",
1036                serde_json::json!({"path": "two.txt"})
1037            )
1038            .await,
1039            "     1\talpha\n     2\tbeta"
1040        );
1041        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1042    }
1043
1044    #[tokio::test]
1045    async fn list_dir_marks_directories_and_defaults_to_the_root() {
1046        let root = temp_root("list").await;
1047        tokio::fs::create_dir(root.join("src"))
1048            .await
1049            .expect("directory is created");
1050        tokio::fs::write(root.join("Cargo.toml"), "[package]")
1051            .await
1052            .expect("fixture is written");
1053        let mut runner = LocalRunner::with_policy(&root, LocalRunnerPolicy::read_only());
1054        assert_eq!(
1055            call(&mut runner, "list_dir", serde_json::json!({})).await,
1056            "Cargo.toml\nsrc/"
1057        );
1058        assert_eq!(
1059            call(&mut runner, "list_dir", serde_json::json!({"path": "src"})).await,
1060            "(empty directory)"
1061        );
1062        assert_eq!(
1063            call(&mut runner, "list_dir", serde_json::json!({"path": "../"})).await,
1064            "error: local path must not contain '.', '..', or root components"
1065        );
1066        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1067    }
1068
1069    #[tokio::test]
1070    async fn grep_reports_matches_by_path_and_line() {
1071        let root = temp_root("grep").await;
1072        tokio::fs::write(root.join("a.txt"), "first\nneedle here\n")
1073            .await
1074            .expect("fixture is written");
1075        tokio::fs::write(root.join("b.txt"), "nothing\n")
1076            .await
1077            .expect("fixture is written");
1078        let mut runner = LocalRunner::with_policy(&root, LocalRunnerPolicy::read_only());
1079        assert_eq!(
1080            call(
1081                &mut runner,
1082                "grep",
1083                serde_json::json!({"pattern": "need.e"})
1084            )
1085            .await,
1086            "a.txt:2:needle here"
1087        );
1088        assert_eq!(
1089            call(
1090                &mut runner,
1091                "grep",
1092                serde_json::json!({"pattern": "absent"})
1093            )
1094            .await,
1095            "(no matches)"
1096        );
1097        assert!(
1098            call(&mut runner, "grep", serde_json::json!({"pattern": "("}))
1099                .await
1100                .starts_with("error: grep.pattern is not a valid regular expression")
1101        );
1102        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1103    }
1104
1105    #[tokio::test]
1106    async fn find_files_matches_globs_without_crossing_separators() {
1107        let root = temp_root("find").await;
1108        tokio::fs::create_dir(root.join("src"))
1109            .await
1110            .expect("directory is created");
1111        tokio::fs::write(root.join("src/lib.rs"), "")
1112            .await
1113            .expect("fixture is written");
1114        tokio::fs::write(root.join("top.rs"), "")
1115            .await
1116            .expect("fixture is written");
1117        let mut runner = LocalRunner::with_policy(&root, LocalRunnerPolicy::read_only());
1118        assert_eq!(
1119            call(
1120                &mut runner,
1121                "find_files",
1122                serde_json::json!({"glob": "*.rs"})
1123            )
1124            .await,
1125            "top.rs"
1126        );
1127        assert_eq!(
1128            call(
1129                &mut runner,
1130                "find_files",
1131                serde_json::json!({"glob": "**/*.rs"})
1132            )
1133            .await,
1134            "src/lib.rs\ntop.rs"
1135        );
1136        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1137    }
1138
1139    #[tokio::test]
1140    async fn edit_files_applies_a_batch_in_order_across_files() {
1141        let root = temp_root("edit-batch").await;
1142        tokio::fs::write(root.join("a.txt"), "alpha one\n")
1143            .await
1144            .expect("fixture is written");
1145        tokio::fs::write(root.join("b.txt"), "beta\n")
1146            .await
1147            .expect("fixture is written");
1148        let mut runner = LocalRunner::with_policy(&root, LocalRunnerPolicy::coding());
1149        let report = call(
1150            &mut runner,
1151            "edit_files",
1152            serde_json::json!({"edits": [
1153                {"path": "a.txt", "old_string": "alpha", "new_string": "ALPHA"},
1154                {"path": "b.txt", "old_string": "beta", "new_string": "BETA"},
1155                {"path": "a.txt", "old_string": "ALPHA one", "new_string": "done"}
1156            ]}),
1157        )
1158        .await;
1159        assert_eq!(
1160            report,
1161            "a.txt: 1 replacement\nb.txt: 1 replacement\na.txt: 1 replacement"
1162        );
1163        // The third edit matched text the first one produced, so edits to one
1164        // file must see each other before anything is written.
1165        assert_eq!(
1166            tokio::fs::read_to_string(root.join("a.txt"))
1167                .await
1168                .expect("file is readable"),
1169            "done\n"
1170        );
1171        assert_eq!(
1172            tokio::fs::read_to_string(root.join("b.txt"))
1173                .await
1174                .expect("file is readable"),
1175            "BETA\n"
1176        );
1177        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1178    }
1179
1180    #[tokio::test]
1181    async fn a_failed_edit_leaves_every_file_untouched() {
1182        let root = temp_root("edit-atomic").await;
1183        tokio::fs::write(root.join("a.txt"), "alpha\n")
1184            .await
1185            .expect("fixture is written");
1186        tokio::fs::write(root.join("b.txt"), "beta beta\n")
1187            .await
1188            .expect("fixture is written");
1189        let mut runner = LocalRunner::with_policy(&root, LocalRunnerPolicy::coding());
1190        // The first edit is valid and the second is ambiguous. Neither may land.
1191        let report = call(
1192            &mut runner,
1193            "edit_files",
1194            serde_json::json!({"edits": [
1195                {"path": "a.txt", "old_string": "alpha", "new_string": "ALPHA"},
1196                {"path": "b.txt", "old_string": "beta", "new_string": "BETA"}
1197            ]}),
1198        )
1199        .await;
1200        assert!(
1201            report.contains("matched 2 times in b.txt"),
1202            "unexpected report: {report}"
1203        );
1204        assert_eq!(
1205            tokio::fs::read_to_string(root.join("a.txt"))
1206                .await
1207                .expect("file is readable"),
1208            "alpha\n"
1209        );
1210        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1211    }
1212
1213    #[tokio::test]
1214    async fn a_missing_match_points_at_the_intended_line() {
1215        let root = temp_root("edit-near-miss").await;
1216        tokio::fs::write(root.join("a.txt"), "fn main() {\n    body();\n}\n")
1217            .await
1218            .expect("fixture is written");
1219        let mut runner = LocalRunner::with_policy(&root, LocalRunnerPolicy::coding());
1220        let report = call(
1221            &mut runner,
1222            "edit_files",
1223            serde_json::json!({"edits": [{
1224                "path": "a.txt",
1225                "old_string": "fn main() {\n  body();\n}",
1226                "new_string": "fn main() {}"
1227            }]}),
1228        )
1229        .await;
1230        assert!(
1231            report.contains("found no match in a.txt")
1232                && report.contains("first line appears at line 1"),
1233            "unexpected report: {report}"
1234        );
1235        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1236    }
1237
1238    #[tokio::test]
1239    async fn delete_file_is_confined_and_refuses_links() {
1240        let root = temp_root("delete").await;
1241        tokio::fs::write(root.join("gone.txt"), "bye")
1242            .await
1243            .expect("fixture is written");
1244        let mut runner = LocalRunner::with_policy(&root, LocalRunnerPolicy::coding());
1245        assert_eq!(
1246            call(
1247                &mut runner,
1248                "delete_file",
1249                serde_json::json!({"path": "gone.txt"})
1250            )
1251            .await,
1252            "deleted gone.txt"
1253        );
1254        assert!(!root.join("gone.txt").exists());
1255        assert_eq!(
1256            call(
1257                &mut runner,
1258                "delete_file",
1259                serde_json::json!({"path": "../outside.txt"})
1260            )
1261            .await,
1262            "error: local path must not contain '.', '..', or root components"
1263        );
1264        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1265    }
1266
1267    #[test]
1268    fn the_coding_policy_offers_exactly_one_edit_format() {
1269        let policy = LocalRunnerPolicy::coding();
1270        assert_eq!(policy.edit_formats(), vec![LocalTool::EditFiles]);
1271        assert_eq!(
1272            tool_definitions(&policy)
1273                .iter()
1274                .map(|definition| definition.name.clone())
1275                .collect::<Vec<_>>(),
1276            vec![
1277                "read_file",
1278                "list_dir",
1279                "grep",
1280                "find_files",
1281                "write_file",
1282                "edit_files",
1283                "delete_file"
1284            ]
1285        );
1286    }
1287
1288    fn shell_policy() -> LocalRunnerPolicy {
1289        LocalRunnerPolicy::coding().with_tool(LocalTool::Shell)
1290    }
1291
1292    async fn run_tool(
1293        runner: &mut LocalRunner,
1294        name: &str,
1295        arguments: serde_json::Value,
1296    ) -> ToolExecutionResult {
1297        runner
1298            .execute(ToolExecutionRequest {
1299                run_id: RunId::new("run-1"),
1300                call: ToolCallItem {
1301                    id: None,
1302                    call_id: "call-1".to_owned(),
1303                    name: name.to_owned(),
1304                    arguments,
1305                    provider_state: None,
1306                },
1307            })
1308            .await
1309            .expect("execution is reported")
1310    }
1311
1312    #[tokio::test]
1313    async fn shell_is_unavailable_unless_the_host_adds_it() {
1314        let root = temp_root("shell-off").await;
1315        let mut runner = LocalRunner::with_policy(&root, LocalRunnerPolicy::coding());
1316        assert_eq!(
1317            call(&mut runner, "shell", serde_json::json!({"command": "true"})).await,
1318            "error: unknown local tool: shell"
1319        );
1320        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1321    }
1322
1323    #[cfg(unix)]
1324    #[tokio::test]
1325    async fn shell_reports_status_and_keeps_streams_separate() {
1326        let root = temp_root("shell-status").await;
1327        let mut runner = LocalRunner::with_policy(&root, shell_policy());
1328        let failed = run_tool(
1329            &mut runner,
1330            "shell",
1331            serde_json::json!({"command": "echo out; echo err >&2; exit 3"}),
1332        )
1333        .await;
1334        assert!(failed.result.is_error, "a non-zero exit is a tool error");
1335        assert_eq!(
1336            failed.result.content,
1337            vec![ContentBlock::text(
1338                "exit code 3\nstdout:\nout\n\nstderr:\nerr\n"
1339            )]
1340        );
1341        assert_eq!(
1342            failed.output,
1343            vec![
1344                RunnerOutput::Stdout("out\n".to_owned()),
1345                RunnerOutput::Stderr("err\n".to_owned())
1346            ]
1347        );
1348
1349        let succeeded = run_tool(
1350            &mut runner,
1351            "shell",
1352            serde_json::json!({"command": "printf ok"}),
1353        )
1354        .await;
1355        assert!(!succeeded.result.is_error);
1356        assert_eq!(
1357            succeeded.result.content,
1358            vec![ContentBlock::text("exit code 0\nstdout:\nok")]
1359        );
1360        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1361    }
1362
1363    #[cfg(unix)]
1364    #[tokio::test]
1365    async fn a_timeout_kills_every_process_the_command_started() {
1366        let root = temp_root("shell-timeout").await;
1367        let mut runner = LocalRunner::with_policy(&root, shell_policy());
1368        // `sleep` runs as a grandchild in the background; killing only `sh`
1369        // would leave it running for 30 seconds.
1370        let started = std::time::Instant::now();
1371        let result = run_tool(
1372            &mut runner,
1373            "shell",
1374            serde_json::json!({
1375                "command": "sleep 30 & echo $! > grandchild.pid; wait",
1376                "timeout_sec": 1
1377            }),
1378        )
1379        .await;
1380        // Without this bound a broken kill only makes the test slow: waiting
1381        // for `sh` would outlast the sleep, and the grandchild would then be
1382        // gone for the wrong reason.
1383        assert!(
1384            started.elapsed() < std::time::Duration::from_secs(10),
1385            "the timeout did not stop the call: took {:?}",
1386            started.elapsed()
1387        );
1388        assert!(result.result.is_error);
1389        let pid = tokio::fs::read_to_string(root.join("grandchild.pid"))
1390            .await
1391            .expect("the command recorded its background pid");
1392        let mut alive = true;
1393        for _ in 0..20 {
1394            alive = std::process::Command::new("kill")
1395                .args(["-0", pid.trim()])
1396                .status()
1397                .expect("kill runs")
1398                .success();
1399            if !alive {
1400                break;
1401            }
1402            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
1403        }
1404        assert!(!alive, "the background grandchild {} survived", pid.trim());
1405        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1406    }
1407
1408    #[cfg(unix)]
1409    #[tokio::test]
1410    async fn shell_runs_non_interactively() {
1411        let root = temp_root("shell-env").await;
1412        let mut runner = LocalRunner::with_policy(&root, shell_policy());
1413        assert_eq!(
1414            call(
1415                &mut runner,
1416                "shell",
1417                serde_json::json!({"command": "printf '%s %s %s' \"$PAGER\" \"$GIT_PAGER\" \"$GIT_TERMINAL_PROMPT\""})
1418            )
1419            .await,
1420            "exit code 0\nstdout:\ncat cat 0"
1421        );
1422        tokio::fs::remove_dir_all(root).await.expect("cleanup");
1423    }
1424
1425    #[test]
1426    fn credentials_are_scrubbed_by_name_segment() {
1427        let policy = ShellPolicy {
1428            scrub_env: vec!["PROVIDER_SPECIAL".to_owned()],
1429            allow_env: vec!["GITHUB_TOKEN".to_owned()],
1430            ..ShellPolicy::default()
1431        };
1432        for scrubbed in [
1433            "OPENAI__API_KEY",
1434            "GLM_APIKEY",
1435            "DEEPSEEK_APIKEY",
1436            "AWS_SECRET_ACCESS_KEY",
1437            "CODEX_GITHUB_PERSONAL_ACCESS_TOKEN",
1438            "DB_PASSWORD",
1439            "PROVIDER_SPECIAL",
1440            "HTTP_AUTHORIZATION",
1441            "BEARER_AUTH",
1442            "AWS_ACCESSKEY",
1443            "GITHUB_PAT",
1444            "RELEASE_SIGNING",
1445            "SSH_PRIVATEKEY",
1446        ] {
1447            assert!(policy.scrubs(scrubbed), "{scrubbed} must be removed");
1448        }
1449        for kept in [
1450            "PATH",
1451            "HOME",
1452            "MONKEY",
1453            "KEYCHAIN_PATH",
1454            "SSH_AUTH_SOCK",
1455            "GITHUB_TOKEN",
1456        ] {
1457            assert!(!policy.scrubs(kept), "{kept} must be kept");
1458        }
1459    }
1460
1461    #[test]
1462    fn the_policy_loads_from_toml_and_is_validated() {
1463        let policy: LocalRunnerPolicy = toml::from_str(
1464            r#"
1465            tools = ["read_file", "grep", "edit_files", "shell"]
1466            read_line_numbers = true
1467            max_grep_matches = 50
1468
1469            [shell]
1470            default_timeout_secs = 30
1471            max_timeout_secs = 120
1472            scrub_env = ["MY_PROVIDER_KEY_VAR"]
1473            "#,
1474        )
1475        .expect("the example parses");
1476        policy.validate().expect("the example is consistent");
1477        assert!(policy.allows(LocalTool::Shell));
1478        assert_eq!(policy.max_grep_matches, 50);
1479        assert_eq!(policy.shell.default_timeout_secs, 30);
1480        // Unset fields keep their defaults.
1481        assert_eq!(policy.max_find_results, 500);
1482
1483        let unknown = toml::from_str::<LocalRunnerPolicy>("tools = [\"read_file\"]\nshel = {}");
1484        assert!(
1485            unknown.is_err(),
1486            "a misspelled key must not be silently ignored"
1487        );
1488
1489        let unknown_tool = toml::from_str::<LocalRunnerPolicy>("tools = [\"rm_rf\"]");
1490        assert!(
1491            unknown_tool.is_err(),
1492            "an unknown tool name must be rejected"
1493        );
1494
1495        let inconsistent: LocalRunnerPolicy =
1496            toml::from_str("[shell]\ndefault_timeout_secs = 300\nmax_timeout_secs = 60")
1497                .expect("shape is valid");
1498        assert!(inconsistent.validate().is_err());
1499    }
1500
1501    #[tokio::test]
1502    async fn local_runner_writes_only_inside_its_root() {
1503        let unique = std::time::SystemTime::now()
1504            .duration_since(std::time::UNIX_EPOCH)
1505            .expect("clock is valid")
1506            .as_nanos();
1507        let root = std::env::temp_dir().join(format!("structure-local-runner-{unique}"));
1508        tokio::fs::create_dir(&root)
1509            .await
1510            .expect("test root is created");
1511        let mut runner = LocalRunner::new(&root);
1512        let result = runner
1513            .execute(ToolExecutionRequest {
1514                run_id: RunId::new("run-1"),
1515                call: ToolCallItem {
1516                    id: None,
1517                    call_id: "call-1".to_owned(),
1518                    name: "write_file".to_owned(),
1519                    arguments: serde_json::json!({
1520                        "path": "created.txt",
1521                        "content": "written by LocalRunner"
1522                    }),
1523                    provider_state: None,
1524                },
1525            })
1526            .await
1527            .expect("execution is reported");
1528        assert!(!result.result.is_error);
1529        assert_eq!(
1530            tokio::fs::read_to_string(root.join("created.txt"))
1531                .await
1532                .expect("written file is readable"),
1533            "written by LocalRunner"
1534        );
1535
1536        let escaped = runner
1537            .execute(ToolExecutionRequest {
1538                run_id: RunId::new("run-2"),
1539                call: ToolCallItem {
1540                    id: None,
1541                    call_id: "call-2".to_owned(),
1542                    name: "write_file".to_owned(),
1543                    arguments: serde_json::json!({
1544                        "path": "../escaped.txt",
1545                        "content": "blocked"
1546                    }),
1547                    provider_state: None,
1548                },
1549            })
1550            .await
1551            .expect("policy failure is a tool result");
1552        assert!(escaped.result.is_error);
1553        tokio::fs::remove_dir_all(root)
1554            .await
1555            .expect("test root is removed");
1556    }
1557
1558    #[tokio::test]
1559    async fn local_runner_reads_only_regular_files_inside_its_root() {
1560        let unique = std::time::SystemTime::now()
1561            .duration_since(std::time::UNIX_EPOCH)
1562            .expect("clock is valid")
1563            .as_nanos();
1564        let root = std::env::temp_dir().join(format!("structure-local-reader-{unique}"));
1565        tokio::fs::create_dir(&root)
1566            .await
1567            .expect("test root is created");
1568        tokio::fs::write(root.join("input.txt"), "evidence")
1569            .await
1570            .expect("fixture is written");
1571        let mut runner = LocalRunner::new(&root);
1572        let result = runner
1573            .execute(ToolExecutionRequest {
1574                run_id: RunId::new("run-read"),
1575                call: ToolCallItem {
1576                    id: None,
1577                    call_id: "call-read".to_owned(),
1578                    name: "read_file".to_owned(),
1579                    arguments: serde_json::json!({"path": "input.txt"}),
1580                    provider_state: None,
1581                },
1582            })
1583            .await
1584            .expect("read is reported");
1585        assert!(!result.result.is_error);
1586        assert_eq!(result.result.content, vec![ContentBlock::text("evidence")]);
1587
1588        tokio::fs::remove_dir_all(root)
1589            .await
1590            .expect("test root is removed");
1591    }
1592}