1pub 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#[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 Self::Shell => ToolInteractionKind::Generic,
143 }
144 }
145
146 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#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
181#[serde(default, deny_unknown_fields)]
182pub struct LocalRunnerPolicy {
183 pub tools: BTreeSet<LocalTool>,
184 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 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 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 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 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 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#[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 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 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 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 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 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 tokio::task::spawn_blocking(move || {
544 grep_blocking(
545 &root,
546 &target,
547 ®ex,
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 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(¤t, &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 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
682fn 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: ®ex::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 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
808struct ToolRun {
810 content: String,
811 is_error: bool,
812 output: Vec<RunnerOutput>,
813}
814
815impl ToolRun {
816 fn text(content: String) -> Self {
819 Self {
820 output: vec![RunnerOutput::Stdout(content.clone())],
821 content,
822 is_error: false,
823 }
824 }
825
826 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 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 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 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 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 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 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 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 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 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}