Skip to main content

microclaw_engine/tools/
apply_patch.rs

1//! `apply_patch`: add, delete, move and edit several files in one call.
2//!
3//! The patch uses the plain-text envelope coding models are trained on:
4//!
5//! ```text
6//! *** Begin Patch
7//! *** Add File: src/new.rs
8//! +fn main() {}
9//! *** Update File: src/lib.rs
10//! *** Move to: src/core.rs
11//! @@ fn parse
12//!  context line
13//! -removed line
14//! +added line
15//! *** Delete File: old.txt
16//! *** End Patch
17//! ```
18//!
19//! Every operation is checked (paths, the stale-read guard, hunk matching)
20//! before anything is written, so a patch applies completely or not at all.
21//! Hunks are located after the previous hunk of the same file, first by
22//! exact lines, then ignoring trailing whitespace, then ignoring surrounding
23//! whitespace; an `@@ <text>` header first moves past the line containing
24//! `<text>`.
25
26use std::path::{Path, PathBuf};
27
28use async_trait::async_trait;
29use serde_json::json;
30
31use crate::config::WorkingDirIsolation;
32use microclaw_core::llm_types::ToolDefinition;
33
34use super::{schema_object, Tool, ToolResult};
35
36pub struct ApplyPatchTool {
37    working_dir: PathBuf,
38    working_dir_isolation: WorkingDirIsolation,
39    diff_max_lines: usize,
40    governance_guard: crate::internal::tool_runtime::path_guard::GovernanceGuard,
41    file_state: std::sync::Arc<super::file_state::FileStateTable>,
42}
43
44impl ApplyPatchTool {
45    pub fn new_with_isolation(
46        working_dir: &str,
47        working_dir_isolation: WorkingDirIsolation,
48    ) -> Self {
49        Self {
50            working_dir: PathBuf::from(working_dir),
51            working_dir_isolation,
52            diff_max_lines: microclaw_core::diff::DEFAULT_DIFF_MAX_LINES,
53            governance_guard: Default::default(),
54            file_state: Default::default(),
55        }
56    }
57
58    pub fn with_file_state(
59        mut self,
60        file_state: std::sync::Arc<super::file_state::FileStateTable>,
61    ) -> Self {
62        self.file_state = file_state;
63        self
64    }
65
66    pub fn with_diff_max_lines(mut self, max_lines: usize) -> Self {
67        self.diff_max_lines = max_lines;
68        self
69    }
70
71    pub fn with_governance_guard(
72        mut self,
73        guard: crate::internal::tool_runtime::path_guard::GovernanceGuard,
74    ) -> Self {
75        self.governance_guard = guard;
76        self
77    }
78}
79
80/// One parsed file operation.
81#[derive(Debug, Clone, PartialEq, Eq)]
82enum Op {
83    Add {
84        path: String,
85        content: String,
86    },
87    Delete {
88        path: String,
89    },
90    Update {
91        path: String,
92        move_to: Option<String>,
93        hunks: Vec<Hunk>,
94    },
95}
96
97#[derive(Debug, Clone, PartialEq, Eq, Default)]
98struct Hunk {
99    /// Text after `@@`, used to locate the hunk.
100    anchor: Option<String>,
101    old: Vec<String>,
102    new: Vec<String>,
103    /// `*** End of File`: the hunk must match at the end of the file.
104    at_eof: bool,
105}
106
107const BEGIN: &str = "*** Begin Patch";
108const END: &str = "*** End Patch";
109const ADD: &str = "*** Add File: ";
110const DELETE: &str = "*** Delete File: ";
111const UPDATE: &str = "*** Update File: ";
112const MOVE: &str = "*** Move to: ";
113const EOF_MARKER: &str = "*** End of File";
114
115fn parse_patch(text: &str) -> Result<Vec<Op>, String> {
116    let lines: Vec<&str> = text.trim().lines().collect();
117    let (first, last) = (lines.first().copied(), lines.last().copied());
118    if first.map(str::trim) != Some(BEGIN) {
119        return Err(format!("The patch must start with `{BEGIN}`"));
120    }
121    if last.map(str::trim) != Some(END) {
122        return Err(format!("The patch must end with `{END}`"));
123    }
124    let body = &lines[1..lines.len() - 1];
125    let mut ops = Vec::new();
126    let mut i = 0;
127    while i < body.len() {
128        let line = body[i];
129        if let Some(path) = line.strip_prefix(ADD) {
130            i += 1;
131            let mut content = String::new();
132            while i < body.len() && !body[i].starts_with("*** ") {
133                let Some(added) = body[i].strip_prefix('+') else {
134                    return Err(format!(
135                        "Line {}: every line of an added file must start with `+`",
136                        i + 2
137                    ));
138                };
139                content.push_str(added);
140                content.push('\n');
141                i += 1;
142            }
143            ops.push(Op::Add {
144                path: path.trim().to_string(),
145                content,
146            });
147        } else if let Some(path) = line.strip_prefix(DELETE) {
148            ops.push(Op::Delete {
149                path: path.trim().to_string(),
150            });
151            i += 1;
152        } else if let Some(path) = line.strip_prefix(UPDATE) {
153            i += 1;
154            let mut move_to = None;
155            if let Some(target) = body.get(i).and_then(|l| l.strip_prefix(MOVE)) {
156                move_to = Some(target.trim().to_string());
157                i += 1;
158            }
159            let mut hunks: Vec<Hunk> = Vec::new();
160            let mut current: Option<Hunk> = None;
161            while i < body.len() {
162                let line = body[i];
163                if line.trim() == EOF_MARKER {
164                    current.get_or_insert_with(Hunk::default).at_eof = true;
165                    i += 1;
166                    continue;
167                }
168                if line.starts_with("*** ") {
169                    break;
170                }
171                if let Some(anchor) = line.strip_prefix("@@") {
172                    if let Some(hunk) = current.take() {
173                        hunks.push(hunk);
174                    }
175                    let anchor = anchor.trim();
176                    current = Some(Hunk {
177                        anchor: (!anchor.is_empty()).then(|| anchor.to_string()),
178                        ..Hunk::default()
179                    });
180                    i += 1;
181                    continue;
182                }
183                let hunk = current.get_or_insert_with(Hunk::default);
184                match line.chars().next() {
185                    Some('+') => hunk.new.push(line[1..].to_string()),
186                    Some('-') => hunk.old.push(line[1..].to_string()),
187                    Some(' ') => {
188                        hunk.old.push(line[1..].to_string());
189                        hunk.new.push(line[1..].to_string());
190                    }
191                    // A bare empty line inside a hunk is an empty context line.
192                    None => {
193                        hunk.old.push(String::new());
194                        hunk.new.push(String::new());
195                    }
196                    Some(_) => {
197                        return Err(format!(
198                            "Line {}: hunk lines must start with ` `, `-` or `+` (got {line:?})",
199                            i + 2
200                        ))
201                    }
202                }
203                i += 1;
204            }
205            if let Some(hunk) = current.take() {
206                hunks.push(hunk);
207            }
208            hunks.retain(|h| !(h.old.is_empty() && h.new.is_empty()));
209            if hunks.is_empty() && move_to.is_none() {
210                return Err(format!("`{UPDATE}{}` has no changes", path.trim()));
211            }
212            ops.push(Op::Update {
213                path: path.trim().to_string(),
214                move_to,
215                hunks,
216            });
217        } else if line.trim().is_empty() {
218            i += 1;
219        } else {
220            return Err(format!(
221                "Line {}: expected `{ADD}`, `{DELETE}` or `{UPDATE}`, got {line:?}",
222                i + 2
223            ));
224        }
225    }
226    if ops.is_empty() {
227        return Err("The patch contains no file operations".into());
228    }
229    for op in &ops {
230        let path = match op {
231            Op::Add { path, .. } | Op::Delete { path } | Op::Update { path, .. } => path,
232        };
233        if path.is_empty() {
234            return Err("A file operation is missing its path".into());
235        }
236    }
237    Ok(ops)
238}
239
240/// Find `needle` in `lines` at or after `from`. Tries exact, then
241/// trailing-whitespace-insensitive, then whitespace-insensitive matching.
242fn find_lines(lines: &[String], needle: &[String], from: usize, at_eof: bool) -> Option<usize> {
243    if needle.is_empty() {
244        return Some(lines.len());
245    }
246    if needle.len() > lines.len() {
247        return None;
248    }
249    let last_start = lines.len() - needle.len();
250    let candidates: Vec<usize> = if at_eof {
251        vec![last_start]
252    } else {
253        (from.min(last_start + 1)..=last_start).collect()
254    };
255    let normalizers: [fn(&str) -> &str; 3] = [|s| s, str::trim_end, str::trim];
256    for normalize in normalizers {
257        for &start in &candidates {
258            if lines[start..start + needle.len()]
259                .iter()
260                .zip(needle)
261                .all(|(a, b)| normalize(a) == normalize(b))
262            {
263                return Some(start);
264            }
265        }
266    }
267    None
268}
269
270fn apply_hunks(path: &str, content: &str, hunks: &[Hunk]) -> Result<String, String> {
271    let had_trailing_newline = content.ends_with('\n') || content.is_empty();
272    let mut lines: Vec<String> = content.lines().map(str::to_string).collect();
273    let mut cursor = 0;
274    for (index, hunk) in hunks.iter().enumerate() {
275        if let Some(anchor) = &hunk.anchor {
276            match lines[cursor.min(lines.len())..]
277                .iter()
278                .position(|l| l.contains(anchor.as_str()))
279            {
280                Some(offset) => {
281                    // Context lines may include the anchor line itself.
282                    cursor += offset;
283                    if hunk
284                        .old
285                        .first()
286                        .is_none_or(|first| first.trim() != anchor.trim())
287                    {
288                        cursor += 1;
289                    }
290                }
291                None => {
292                    return Err(format!(
293                        "{path}: hunk {} anchor `@@ {anchor}` was not found",
294                        index + 1
295                    ))
296                }
297            }
298        }
299        let Some(start) = find_lines(&lines, &hunk.old, cursor, hunk.at_eof) else {
300            let preview: Vec<&str> = hunk.old.iter().take(3).map(String::as_str).collect();
301            return Err(format!(
302                "{path}: hunk {} does not match the file (looking for {:?}{}). Read the file again and resend the patch with exact context lines.",
303                index + 1,
304                preview,
305                if hunk.old.len() > 3 { ", …" } else { "" }
306            ));
307        };
308        lines.splice(start..start + hunk.old.len(), hunk.new.iter().cloned());
309        cursor = start + hunk.new.len();
310    }
311    let mut out = lines.join("\n");
312    if had_trailing_newline && !out.is_empty() {
313        out.push('\n');
314    }
315    Ok(out)
316}
317
318/// A fully checked change to one path.
319struct Planned {
320    /// Path as written in the patch (for diffs and messages).
321    display: String,
322    target: PathBuf,
323    /// `None` = delete the target.
324    new_content: Option<String>,
325    old_content: String,
326    /// Also remove this path (the source of a move).
327    remove_source: Option<PathBuf>,
328    verb: &'static str,
329}
330
331impl ApplyPatchTool {
332    fn resolve(&self, working_dir: &Path, path: &str) -> Result<PathBuf, String> {
333        let resolved = super::resolve_tool_path(working_dir, path);
334        crate::internal::tool_runtime::path_guard::check_path(&resolved.to_string_lossy())?;
335        self.governance_guard.check_write(&resolved)?;
336        Ok(resolved)
337    }
338
339    async fn read_fresh(&self, path: &Path, display: &str) -> Result<String, String> {
340        let content = tokio::fs::read_to_string(path)
341            .await
342            .map_err(|e| format!("{display}: cannot read the file: {e}"))?;
343        self.file_state.check_fresh(path, content.as_bytes())?;
344        Ok(content)
345    }
346
347    async fn plan(&self, working_dir: &Path, ops: Vec<Op>) -> Result<Vec<Planned>, String> {
348        let mut planned: Vec<Planned> = Vec::new();
349        let mut touched: Vec<PathBuf> = Vec::new();
350        let mut claim = |path: &PathBuf, display: &str| {
351            if touched.contains(path) {
352                Err(format!(
353                    "{display}: the patch changes this file more than once"
354                ))
355            } else {
356                touched.push(path.clone());
357                Ok(())
358            }
359        };
360        for op in ops {
361            match op {
362                Op::Add { path, content } => {
363                    let target = self.resolve(working_dir, &path)?;
364                    claim(&target, &path)?;
365                    if tokio::fs::try_exists(&target).await.unwrap_or(false) {
366                        return Err(format!(
367                            "{path}: already exists; use `{UPDATE}{path}` to change it"
368                        ));
369                    }
370                    planned.push(Planned {
371                        display: path,
372                        target,
373                        new_content: Some(content),
374                        old_content: String::new(),
375                        remove_source: None,
376                        verb: "added",
377                    });
378                }
379                Op::Delete { path } => {
380                    let target = self.resolve(working_dir, &path)?;
381                    claim(&target, &path)?;
382                    let old_content = self.read_fresh(&target, &path).await?;
383                    planned.push(Planned {
384                        display: path,
385                        target,
386                        new_content: None,
387                        old_content,
388                        remove_source: None,
389                        verb: "deleted",
390                    });
391                }
392                Op::Update {
393                    path,
394                    move_to,
395                    hunks,
396                } => {
397                    let source = self.resolve(working_dir, &path)?;
398                    claim(&source, &path)?;
399                    let old_content = self.read_fresh(&source, &path).await?;
400                    let new_content = apply_hunks(&path, &old_content, &hunks)?;
401                    let (display, target, remove_source) = match move_to {
402                        Some(dest) => {
403                            let target = self.resolve(working_dir, &dest)?;
404                            claim(&target, &dest)?;
405                            if tokio::fs::try_exists(&target).await.unwrap_or(false) {
406                                return Err(format!("{dest}: move target already exists"));
407                            }
408                            (dest, target, Some(source))
409                        }
410                        None => (path, source, None),
411                    };
412                    let verb = if remove_source.is_some() {
413                        "moved"
414                    } else {
415                        "updated"
416                    };
417                    planned.push(Planned {
418                        display,
419                        target,
420                        new_content: Some(new_content),
421                        old_content,
422                        remove_source,
423                        verb,
424                    });
425                }
426            }
427        }
428        Ok(planned)
429    }
430}
431
432#[async_trait]
433impl Tool for ApplyPatchTool {
434    fn name(&self) -> &str {
435        "apply_patch"
436    }
437
438    fn definition(&self) -> ToolDefinition {
439        ToolDefinition {
440            name: "apply_patch".into(),
441            description: "Add, delete, move and edit files in one atomic call. Use it for changes that span several files or several places in a file. The patch format:\n\n*** Begin Patch\n*** Add File: path/new.txt\n+every line of the new file starts with +\n*** Update File: path/existing.rs\n*** Move to: path/renamed.rs   (optional)\n@@ optional line that appears just before the change, e.g. a function signature\n unchanged context line (leading space)\n-removed line\n+added line\n*** Delete File: path/obsolete.txt\n*** End Patch\n\nGive 1-3 context lines around each change so it can be located; hunks of one file apply in order. All operations are checked before anything is written: if one fails, nothing changes. Edits are refused when a file changed on disk after you last read it. Paths are relative to the working directory.".into(),
442            input_schema: schema_object(
443                json!({
444                    "patch": {
445                        "type": "string",
446                        "description": "The full patch text, from `*** Begin Patch` to `*** End Patch`"
447                    }
448                }),
449                &["patch"],
450            ),
451        }
452    }
453
454    async fn execute(&self, input: serde_json::Value) -> ToolResult {
455        let Some(patch) = input
456            .get("patch")
457            .or_else(|| input.get("input"))
458            .and_then(|v| v.as_str())
459        else {
460            return ToolResult::error("Missing 'patch' parameter".into());
461        };
462        let ops = match parse_patch(patch) {
463            Ok(ops) => ops,
464            Err(msg) => return ToolResult::error(format!("Invalid patch: {msg}")),
465        };
466        let working_dir =
467            super::resolve_tool_working_dir(&self.working_dir, self.working_dir_isolation, &input);
468        let planned = match self.plan(&working_dir, ops).await {
469            Ok(planned) => planned,
470            Err(msg) if msg.contains("modified on disk") => {
471                return ToolResult::error(format!("{msg} No files were changed."))
472                    .with_error_type("stale_read")
473            }
474            Err(msg) => {
475                return ToolResult::error(format!(
476                    "{}. No files were changed.",
477                    msg.trim_end_matches('.')
478                ))
479            }
480        };
481
482        let mut summary = Vec::new();
483        let mut diffs = Vec::new();
484        for change in &planned {
485            let outcome = match &change.new_content {
486                Some(content) => {
487                    if let Some(parent) = change.target.parent() {
488                        if let Err(e) = tokio::fs::create_dir_all(parent).await {
489                            return ToolResult::error(format!(
490                                "{}: cannot create its directory: {e}",
491                                change.display
492                            ));
493                        }
494                    }
495                    tokio::fs::write(&change.target, content).await
496                }
497                None => tokio::fs::remove_file(&change.target).await,
498            };
499            if let Err(e) = outcome {
500                return ToolResult::error(format!(
501                    "{}: write failed: {e}. Earlier operations of this patch were already applied: {}",
502                    change.display,
503                    if summary.is_empty() { "none".to_string() } else { summary.join(", ") }
504                ));
505            }
506            if let Some(source) = &change.remove_source {
507                let _ = tokio::fs::remove_file(source).await;
508            }
509            match &change.new_content {
510                Some(content) => self.file_state.record(&change.target, content.as_bytes()),
511                None => self.file_state.record(&change.target, b""),
512            }
513            let new = change.new_content.as_deref().unwrap_or("");
514            let verb = change.verb;
515            let diff =
516                microclaw_core::diff::unified_diff(&change.old_content, new, self.diff_max_lines);
517            summary.push(match &diff {
518                Some(d) => format!("{verb} {} ({})", change.display, d.stats()),
519                None => format!("{verb} {}", change.display),
520            });
521            if let Some(d) = diff {
522                diffs.push((change.display.clone(), d));
523            }
524        }
525        let mut result = ToolResult::success(format!("Applied patch: {}", summary.join(", ")));
526        if !diffs.is_empty() {
527            result = result.with_metadata(microclaw_core::diff::file_diffs_metadata(&diffs));
528        }
529        result
530    }
531}
532
533#[cfg(test)]
534mod tests {
535    use super::*;
536
537    fn tool(dir: &Path) -> ApplyPatchTool {
538        ApplyPatchTool::new_with_isolation(dir.to_str().unwrap(), WorkingDirIsolation::Direct)
539    }
540
541    async fn run(dir: &Path, patch: &str) -> ToolResult {
542        tool(dir).execute(json!({ "patch": patch })).await
543    }
544
545    #[tokio::test]
546    async fn adds_updates_moves_and_deletes_files() {
547        let dir = tempfile::tempdir().unwrap();
548        std::fs::write(
549            dir.path().join("lib.rs"),
550            "fn a() {\n    1\n}\n\nfn b() {\n    2\n}\n",
551        )
552        .unwrap();
553        std::fs::write(dir.path().join("old.txt"), "bye\n").unwrap();
554        std::fs::write(dir.path().join("name.txt"), "x\ny\n").unwrap();
555        let result = run(
556            dir.path(),
557            "*** Begin Patch
558*** Add File: src/new.rs
559+fn main() {}
560*** Update File: lib.rs
561@@ fn b() {
562-    2
563+    20
564*** Update File: name.txt
565*** Move to: renamed.txt
566 x
567-y
568+z
569*** Delete File: old.txt
570*** End Patch",
571        )
572        .await;
573        assert!(!result.is_error, "{}", result.content);
574        assert_eq!(
575            std::fs::read_to_string(dir.path().join("src/new.rs")).unwrap(),
576            "fn main() {}\n"
577        );
578        assert_eq!(
579            std::fs::read_to_string(dir.path().join("lib.rs")).unwrap(),
580            "fn a() {\n    1\n}\n\nfn b() {\n    20\n}\n"
581        );
582        assert_eq!(
583            std::fs::read_to_string(dir.path().join("renamed.txt")).unwrap(),
584            "x\nz\n"
585        );
586        assert!(!dir.path().join("name.txt").exists());
587        assert!(!dir.path().join("old.txt").exists());
588        let diffs = result
589            .metadata
590            .as_ref()
591            .and_then(|m| m.get(microclaw_core::diff::FILE_DIFFS_METADATA_KEY))
592            .and_then(|v| v.as_array())
593            .unwrap();
594        assert_eq!(diffs.len(), 4);
595    }
596
597    #[tokio::test]
598    async fn a_failing_hunk_changes_nothing() {
599        let dir = tempfile::tempdir().unwrap();
600        std::fs::write(dir.path().join("a.txt"), "one\ntwo\n").unwrap();
601        let result = run(
602            dir.path(),
603            "*** Begin Patch
604*** Add File: b.txt
605+new
606*** Update File: a.txt
607-three
608+four
609*** End Patch",
610        )
611        .await;
612        assert!(result.is_error);
613        assert!(
614            result.content.contains("does not match"),
615            "{}",
616            result.content
617        );
618        assert!(result.content.contains("No files were changed"));
619        assert!(!dir.path().join("b.txt").exists());
620        assert_eq!(
621            std::fs::read_to_string(dir.path().join("a.txt")).unwrap(),
622            "one\ntwo\n"
623        );
624    }
625
626    #[tokio::test]
627    async fn whitespace_tolerant_matching_and_ordered_hunks() {
628        let dir = tempfile::tempdir().unwrap();
629        std::fs::write(
630            dir.path().join("a.py"),
631            "x = 1  \ny = 2\nz = 1\ny = 2\nz = 1\n",
632        )
633        .unwrap();
634        let result = run(
635            dir.path(),
636            "*** Begin Patch
637*** Update File: a.py
638-x = 1
639+x = 10
640@@ z = 1
641 y = 2
642-z = 1
643+z = 30
644*** End Patch",
645        )
646        .await;
647        assert!(!result.is_error, "{}", result.content);
648        // The trailing-space line matched loosely; the anchor skipped the
649        // first `z = 1`, so the second hunk changed the later one.
650        assert_eq!(
651            std::fs::read_to_string(dir.path().join("a.py")).unwrap(),
652            "x = 10\ny = 2\nz = 1\ny = 2\nz = 30\n"
653        );
654    }
655
656    #[tokio::test]
657    async fn refuses_stale_files_and_existing_add_targets() {
658        let dir = tempfile::tempdir().unwrap();
659        std::fs::write(dir.path().join("a.txt"), "one\n").unwrap();
660        let tool = tool(dir.path());
661        tool.file_state.record(&dir.path().join("a.txt"), b"older");
662        let stale = tool
663            .execute(json!({"patch": "*** Begin Patch\n*** Update File: a.txt\n-one\n+two\n*** End Patch"}))
664            .await;
665        assert!(stale.is_error);
666        assert_eq!(stale.error_type.as_deref(), Some("stale_read"));
667        let exists = tool
668            .execute(json!({"patch": "*** Begin Patch\n*** Add File: a.txt\n+x\n*** End Patch"}))
669            .await;
670        assert!(exists.is_error);
671        assert!(exists.content.contains("already exists"));
672    }
673
674    #[test]
675    fn rejects_malformed_patches() {
676        assert!(parse_patch("*** Update File: a\n-x\n+y").is_err());
677        assert!(parse_patch("*** Begin Patch\n*** End Patch").is_err());
678        assert!(parse_patch("*** Begin Patch\n*** Add File: a\nno plus\n*** End Patch").is_err());
679        assert!(parse_patch("*** Begin Patch\n*** Update File: a\n*** End Patch").is_err());
680        assert!(parse_patch("*** Begin Patch\nhello\n*** End Patch").is_err());
681    }
682
683    #[test]
684    fn end_of_file_hunks_match_at_the_end() {
685        let out = apply_hunks(
686            "a",
687            "x\nend\nx\nend\n",
688            &[Hunk {
689                anchor: None,
690                old: vec!["end".into()],
691                new: vec!["END".into()],
692                at_eof: true,
693            }],
694        )
695        .unwrap();
696        assert_eq!(out, "x\nend\nx\nEND\n");
697    }
698}