1use std::collections::HashMap;
12use std::fmt::Write as _;
13use std::path::{Path, PathBuf};
14use std::time::Duration;
15
16use sa3p_parser::{Attributes, Instruction};
17use strsim::levenshtein;
18use thiserror::Error;
19
20#[derive(Debug, Error)]
21pub enum EngineError {
22 #[error("missing required attribute `{0}`")]
23 MissingAttribute(&'static str),
24 #[error("invalid integer for attribute `{name}`: {value}")]
25 InvalidInteger { name: &'static str, value: String },
26 #[error("operation is out of order: {0}")]
27 InvalidState(String),
28 #[error("invalid utf-8 payload")]
29 InvalidUtf8,
30 #[error("virtual filesystem error: {0}")]
31 Vfs(String),
32 #[error("terminal error: {0}")]
33 Terminal(String),
34}
35
36pub type Result<T> = std::result::Result<T, EngineError>;
37
38#[derive(Debug, Clone, PartialEq, Eq)]
39pub struct FileHash {
40 pub path: PathBuf,
41 pub sha256: String,
42}
43
44#[derive(Debug, Clone, PartialEq, Eq)]
45pub enum NodeKind {
46 File,
47 Directory,
48}
49
50#[derive(Debug, Clone, PartialEq, Eq)]
51pub struct TreeNode {
52 pub path: PathBuf,
53 pub kind: NodeKind,
54 pub descendant_file_count: usize,
55 pub modified_recently: bool,
56}
57
58pub trait VirtualFileSystem {
59 fn read(&self, path: &Path) -> Result<Vec<u8>>;
60 fn write_atomic(&self, path: &Path, bytes: &[u8]) -> Result<()>;
61 fn hash(&self, path: &Path) -> Result<String>;
62 fn cwd(&self) -> Result<PathBuf>;
63 fn list_tree(&self, path: &Path) -> Result<Vec<TreeNode>>;
64 fn recent_file_hashes(&self, limit: usize) -> Result<Vec<FileHash>>;
65}
66
67#[derive(Debug, Clone, Copy, PartialEq, Eq)]
68pub enum ProcessSignal {
69 SigInt,
70 SigTerm,
71 SigKill,
72}
73
74#[derive(Debug, Clone, PartialEq, Eq)]
75pub struct TerminalExecution {
76 pub output: String,
77 pub exit_code: Option<i32>,
78 pub cwd: PathBuf,
79 pub detached_pid: Option<u32>,
80}
81
82pub trait TerminalProvider {
83 fn run(&mut self, command: &str, timeout: Duration) -> Result<TerminalExecution>;
84 fn signal(&mut self, pid: u32, signal: ProcessSignal) -> Result<()>;
85 fn active_pids(&self) -> Vec<u32>;
86}
87
88#[derive(Debug, Clone, PartialEq, Eq)]
89pub struct StateHeader {
90 pub cwd: PathBuf,
91 pub recent_hashes: Vec<FileHash>,
92 pub active_pids: Vec<u32>,
93}
94
95impl StateHeader {
96 pub fn render(&self) -> String {
97 let mut out = String::new();
98 let _ = write!(&mut out, "[CWD: {}", self.cwd.display());
99
100 if self.recent_hashes.is_empty() {
101 out.push_str(" | RECENT_HASHES: none");
102 } else {
103 out.push_str(" | RECENT_HASHES: ");
104 for (idx, file_hash) in self.recent_hashes.iter().enumerate() {
105 if idx > 0 {
106 out.push_str(", ");
107 }
108 let _ = write!(
109 &mut out,
110 "{}#{}",
111 file_hash.path.display(),
112 shorten_hash(&file_hash.sha256)
113 );
114 }
115 }
116
117 if self.active_pids.is_empty() {
118 out.push_str(" | ACTIVE_PIDS: none]");
119 } else {
120 out.push_str(" | ACTIVE_PIDS: ");
121 for (idx, pid) in self.active_pids.iter().enumerate() {
122 if idx > 0 {
123 out.push_str(", ");
124 }
125 let _ = write!(&mut out, "{pid}");
126 }
127 out.push(']');
128 }
129
130 out
131 }
132}
133
134#[derive(Debug, Clone, PartialEq, Eq)]
135pub struct TurnResult {
136 pub state_header: StateHeader,
137 pub outputs: Vec<EngineOutput>,
138}
139
140#[derive(Debug, Clone, PartialEq, Eq)]
141pub enum EngineOutput {
142 ReadFile(ReadFileOutput),
143 WriteFile(WriteFileOutput),
144 ApplyEdit(ApplyEditOutput),
145 ListFiles(ListFilesOutput),
146 Terminal(TerminalExecution),
147 Signal(SignalOutput),
148 Warning(String),
149}
150
151#[derive(Debug, Clone, PartialEq, Eq)]
152pub struct ReadFileOutput {
153 pub path: PathBuf,
154 pub size_bytes: usize,
155 pub sha256: String,
156 pub requested_start: usize,
157 pub requested_end: usize,
158 pub served_start: usize,
159 pub served_end: usize,
160 pub total_lines: usize,
161 pub body: String,
162 pub warning: Option<String>,
163}
164
165impl ReadFileOutput {
166 pub fn fidelity_header(&self) -> String {
167 format!(
168 "[PATH: {} | SIZE: {} | SHA256: {} | LINES: {}-{}/{}]",
169 self.path.display(),
170 human_bytes(self.size_bytes),
171 shorten_hash(&self.sha256),
172 self.served_start,
173 self.served_end,
174 self.total_lines
175 )
176 }
177}
178
179#[derive(Debug, Clone, PartialEq, Eq)]
180pub struct WriteFileOutput {
181 pub path: PathBuf,
182 pub size_bytes: usize,
183 pub sha256: String,
184}
185
186#[derive(Debug, Clone, PartialEq, Eq)]
187pub enum EditTier {
188 Exact,
189 WhitespaceAgnostic,
190 ContextualAnchor,
191 NotApplied,
192}
193
194#[derive(Debug, Clone, PartialEq, Eq)]
195pub struct ApplyEditOutput {
196 pub path: PathBuf,
197 pub applied: bool,
198 pub tier: EditTier,
199 pub sha256: Option<String>,
200 pub format: Option<String>,
201 pub reason_code: Option<String>,
202 pub warning: Option<String>,
203}
204
205#[derive(Debug, Clone, PartialEq, Eq)]
206pub struct ListFilesOutput {
207 pub path: PathBuf,
208 pub lines: Vec<String>,
209}
210
211#[derive(Debug, Clone, PartialEq, Eq)]
212pub struct SignalOutput {
213 pub pid: u32,
214 pub signal: ProcessSignal,
215}
216
217pub const DEFAULT_MAX_LIST_LINES: usize = 300;
218pub const DEFAULT_DENSE_DIR_THRESHOLD: usize = 200;
219pub const DEFAULT_TERMINAL_TIMEOUT_SECS: u64 = 5;
220pub const DEFAULT_RECENT_HASH_LIMIT: usize = 5;
221
222pub const APPLY_EDIT_FORMAT_SEARCH_REPLACE_TAGS: &str = "search_replace_tags";
223pub const APPLY_EDIT_FORMAT_SEARCH_REPLACE_MARKERS: &str = "search_replace_markers";
224pub const APPLY_EDIT_FORMAT_SEARCH_REPLACE_XML_BLOCKS: &str = "search_replace_xml_blocks";
225pub const APPLY_EDIT_FORMAT_UNIFIED_DIFF: &str = "unified_diff";
226pub const APPLY_EDIT_FORMAT_RAW_TEXT: &str = "raw_text";
227
228pub const APPLY_EDIT_REASON_STALE_HASH: &str = "stale_hash";
229pub const APPLY_EDIT_REASON_EMPTY_EDIT: &str = "empty_edit";
230pub const APPLY_EDIT_REASON_PARSE_ERROR: &str = "parse_error";
231pub const APPLY_EDIT_REASON_NO_HUNKS: &str = "no_hunks";
232pub const APPLY_EDIT_REASON_NO_MATCH: &str = "no_match";
233
234pub const STATE_HEADER_FIELD_CWD: &str = "cwd";
235pub const STATE_HEADER_FIELD_RECENT_HASHES: &str = "recent_hashes";
236pub const STATE_HEADER_FIELD_ACTIVE_PIDS: &str = "active_pids";
237
238pub const APPLY_EDIT_SUPPORTED_FORMATS: &[&str] = &[
239 APPLY_EDIT_FORMAT_SEARCH_REPLACE_TAGS,
240 APPLY_EDIT_FORMAT_SEARCH_REPLACE_MARKERS,
241 APPLY_EDIT_FORMAT_SEARCH_REPLACE_XML_BLOCKS,
242 APPLY_EDIT_FORMAT_UNIFIED_DIFF,
243];
244
245pub const APPLY_EDIT_REASON_CODES: &[&str] = &[
246 APPLY_EDIT_REASON_STALE_HASH,
247 APPLY_EDIT_REASON_EMPTY_EDIT,
248 APPLY_EDIT_REASON_PARSE_ERROR,
249 APPLY_EDIT_REASON_NO_HUNKS,
250 APPLY_EDIT_REASON_NO_MATCH,
251];
252
253pub const STATE_HEADER_FIELDS: &[&str] = &[
254 STATE_HEADER_FIELD_CWD,
255 STATE_HEADER_FIELD_RECENT_HASHES,
256 STATE_HEADER_FIELD_ACTIVE_PIDS,
257];
258
259#[derive(Debug, Clone, PartialEq, Eq)]
260pub struct CapabilityDescriptor {
261 pub name: &'static str,
262 pub tag: &'static str,
263}
264
265#[derive(Debug, Clone, PartialEq, Eq)]
266pub struct CapabilityManifest {
267 pub commands: Vec<CapabilityDescriptor>,
268 pub apply_edit_formats: Vec<&'static str>,
269 pub apply_edit_reason_codes: Vec<&'static str>,
270 pub apply_edit_tiers: Vec<EditTier>,
271 pub state_header_fields: Vec<&'static str>,
272 pub max_list_lines: usize,
273 pub dense_dir_threshold: usize,
274 pub terminal_timeout: Duration,
275 pub recent_hash_limit: usize,
276}
277
278#[derive(Debug)]
279pub struct Engine<VFS, Terminal> {
280 vfs: VFS,
281 terminal: Terminal,
282 known_hashes: HashMap<PathBuf, String>,
283 pending: Option<PendingOperation>,
284 max_list_lines: usize,
285 dense_dir_threshold: usize,
286 terminal_timeout: Duration,
287 recent_hash_limit: usize,
288}
289
290impl<VFS, Terminal> Engine<VFS, Terminal>
291where
292 VFS: VirtualFileSystem,
293 Terminal: TerminalProvider,
294{
295 pub fn new(vfs: VFS, terminal: Terminal) -> Self {
296 Self {
297 vfs,
298 terminal,
299 known_hashes: HashMap::new(),
300 pending: None,
301 max_list_lines: DEFAULT_MAX_LIST_LINES,
302 dense_dir_threshold: DEFAULT_DENSE_DIR_THRESHOLD,
303 terminal_timeout: Duration::from_secs(DEFAULT_TERMINAL_TIMEOUT_SECS),
304 recent_hash_limit: DEFAULT_RECENT_HASH_LIMIT,
305 }
306 }
307
308 pub fn with_terminal_timeout(mut self, timeout: Duration) -> Self {
309 self.terminal_timeout = timeout;
310 self
311 }
312
313 pub fn with_list_budget(mut self, max_lines: usize, dense_threshold: usize) -> Self {
314 self.max_list_lines = max_lines;
315 self.dense_dir_threshold = dense_threshold;
316 self
317 }
318
319 pub fn capability_manifest(&self) -> CapabilityManifest {
320 self.capability_manifest_for(DEFAULT_CAPABILITIES)
321 }
322
323 pub fn capability_manifest_for(&self, capabilities: &[Capability]) -> CapabilityManifest {
324 let enabled = if capabilities.is_empty() {
325 DEFAULT_CAPABILITIES.to_vec()
326 } else {
327 capabilities.to_vec()
328 };
329
330 CapabilityManifest {
331 commands: enabled
332 .iter()
333 .map(|capability| CapabilityDescriptor {
334 name: capability.name(),
335 tag: capability.tag(),
336 })
337 .collect(),
338 apply_edit_formats: APPLY_EDIT_SUPPORTED_FORMATS.to_vec(),
339 apply_edit_reason_codes: APPLY_EDIT_REASON_CODES.to_vec(),
340 apply_edit_tiers: vec![
341 EditTier::Exact,
342 EditTier::WhitespaceAgnostic,
343 EditTier::ContextualAnchor,
344 EditTier::NotApplied,
345 ],
346 state_header_fields: STATE_HEADER_FIELDS.to_vec(),
347 max_list_lines: self.max_list_lines,
348 dense_dir_threshold: self.dense_dir_threshold,
349 terminal_timeout: self.terminal_timeout,
350 recent_hash_limit: self.recent_hash_limit,
351 }
352 }
353
354 pub fn execute_turn(&mut self, instructions: Vec<Instruction>) -> Result<TurnResult> {
355 let mut outputs = Vec::new();
356
357 for instruction in instructions {
358 self.apply_instruction(instruction, &mut outputs)?;
359 }
360
361 let state_header = StateHeader {
362 cwd: self.vfs.cwd()?,
363 recent_hashes: self.vfs.recent_file_hashes(self.recent_hash_limit)?,
364 active_pids: {
365 let mut pids = self.terminal.active_pids();
366 pids.sort_unstable();
367 pids
368 },
369 };
370
371 Ok(TurnResult {
372 state_header,
373 outputs,
374 })
375 }
376
377 fn apply_instruction(
378 &mut self,
379 instruction: Instruction,
380 outputs: &mut Vec<EngineOutput>,
381 ) -> Result<()> {
382 match instruction {
383 Instruction::Text(text) => {
384 if let Some(PendingOperation::ApplyEdit(edit)) = self.pending.as_mut() {
385 if edit.capture.is_none() {
386 edit.raw_body.extend_from_slice(text.as_bytes());
387 }
388 }
389 }
390 Instruction::StartTag { name, attributes } => {
391 self.handle_start_tag(&name, attributes, outputs)?;
392 }
393 Instruction::EndTag(name) => {
394 self.handle_end_tag(&name, outputs)?;
395 }
396 Instruction::WriteChunk(bytes) => {
397 let Some(PendingOperation::WriteFile(write)) = self.pending.as_mut() else {
398 return Err(EngineError::InvalidState(
399 "received WriteChunk outside <write_file>".to_string(),
400 ));
401 };
402 write.buffer.extend_from_slice(&bytes);
403 }
404 Instruction::RawChunk { tag, bytes } => match self.pending.as_mut() {
405 Some(PendingOperation::ApplyEdit(edit)) => match edit.capture {
406 Some(ApplyCapture::Search) if tag == "search" => {
407 edit.search.extend_from_slice(&bytes);
408 }
409 Some(ApplyCapture::Replace) if tag == "replace" => {
410 edit.replace.extend_from_slice(&bytes);
411 }
412 None => {
413 edit.raw_body.extend_from_slice(&bytes);
414 }
415 _ => {
416 return Err(EngineError::InvalidState(format!(
417 "unexpected raw chunk for <{tag}> while applying edit"
418 )));
419 }
420 },
421 Some(PendingOperation::Terminal(term)) if tag == "terminal" => {
422 term.command.extend_from_slice(&bytes);
423 }
424 _ => {
425 return Err(EngineError::InvalidState(format!(
426 "received raw chunk for <{tag}> without active matching context"
427 )));
428 }
429 },
430 }
431
432 Ok(())
433 }
434
435 fn handle_start_tag(
436 &mut self,
437 name: &str,
438 attributes: Attributes,
439 outputs: &mut Vec<EngineOutput>,
440 ) -> Result<()> {
441 match name {
442 "write_file" => {
443 self.ensure_no_pending("write_file")?;
444 let path = required_path(&attributes)?;
445 self.pending = Some(PendingOperation::WriteFile(PendingWrite {
446 path,
447 buffer: Vec::new(),
448 }));
449 }
450 "read_file" => {
451 let output = self.execute_read_file(&attributes)?;
452 outputs.push(EngineOutput::ReadFile(output));
453 }
454 "apply_edit" => {
455 self.ensure_no_pending("apply_edit")?;
456 let path = required_path(&attributes)?;
457 self.pending = Some(PendingOperation::ApplyEdit(PendingApplyEdit {
458 path,
459 search: Vec::new(),
460 replace: Vec::new(),
461 raw_body: Vec::new(),
462 capture: None,
463 }));
464 }
465 "search" => {
466 let Some(PendingOperation::ApplyEdit(edit)) = self.pending.as_mut() else {
467 return Err(EngineError::InvalidState(
468 "<search> must be nested under <apply_edit>".to_string(),
469 ));
470 };
471 edit.capture = Some(ApplyCapture::Search);
472 }
473 "replace" => {
474 let Some(PendingOperation::ApplyEdit(edit)) = self.pending.as_mut() else {
475 return Err(EngineError::InvalidState(
476 "<replace> must be nested under <apply_edit>".to_string(),
477 ));
478 };
479 edit.capture = Some(ApplyCapture::Replace);
480 }
481 "list_files" => {
482 let output = self.execute_list_files(&attributes)?;
483 outputs.push(EngineOutput::ListFiles(output));
484 }
485 "terminal" => {
486 self.ensure_no_pending("terminal")?;
487 let command = attributes
488 .get("cmd")
489 .or_else(|| attributes.get("command"))
490 .cloned()
491 .unwrap_or_default()
492 .into_bytes();
493 self.pending = Some(PendingOperation::Terminal(PendingTerminal { command }));
494 }
495 "terminal_signal" => {
496 let signal_output = self.execute_terminal_signal(&attributes)?;
497 outputs.push(EngineOutput::Signal(signal_output));
498 }
499 other => outputs.push(EngineOutput::Warning(format!(
500 "unsupported start tag <{other}> ignored"
501 ))),
502 }
503
504 Ok(())
505 }
506
507 fn handle_end_tag(&mut self, name: &str, outputs: &mut Vec<EngineOutput>) -> Result<()> {
508 match name {
509 "write_file" => {
510 let Some(PendingOperation::WriteFile(write)) = self.pending.take() else {
511 return Err(EngineError::InvalidState(
512 "</write_file> received without matching start".to_string(),
513 ));
514 };
515 let output = self.finalize_write(write)?;
516 outputs.push(EngineOutput::WriteFile(output));
517 }
518 "search" | "replace" => {
519 let Some(PendingOperation::ApplyEdit(edit)) = self.pending.as_mut() else {
520 return Err(EngineError::InvalidState(format!(
521 "</{name}> received without active <apply_edit>"
522 )));
523 };
524 edit.capture = None;
525 }
526 "apply_edit" => {
527 let Some(PendingOperation::ApplyEdit(edit)) = self.pending.take() else {
528 return Err(EngineError::InvalidState(
529 "</apply_edit> received without matching start".to_string(),
530 ));
531 };
532 let output = self.finalize_apply_edit(edit)?;
533 outputs.push(EngineOutput::ApplyEdit(output));
534 }
535 "terminal" => {
536 let Some(PendingOperation::Terminal(term)) = self.pending.take() else {
537 return Err(EngineError::InvalidState(
538 "</terminal> received without matching start".to_string(),
539 ));
540 };
541 let command =
542 String::from_utf8(term.command).map_err(|_| EngineError::InvalidUtf8)?;
543 let output = self.terminal.run(command.trim(), self.terminal_timeout)?;
544 outputs.push(EngineOutput::Terminal(output));
545 }
546 other => outputs.push(EngineOutput::Warning(format!(
547 "unsupported end tag </{other}> ignored"
548 ))),
549 }
550
551 Ok(())
552 }
553
554 fn finalize_write(&mut self, write: PendingWrite) -> Result<WriteFileOutput> {
555 self.vfs.write_atomic(&write.path, &write.buffer)?;
556 let sha256 = self.vfs.hash(&write.path)?;
557 self.known_hashes.insert(write.path.clone(), sha256.clone());
558
559 Ok(WriteFileOutput {
560 path: write.path,
561 size_bytes: write.buffer.len(),
562 sha256,
563 })
564 }
565
566 fn execute_read_file(&mut self, attributes: &Attributes) -> Result<ReadFileOutput> {
567 let path = required_path(attributes)?;
568 let requested_start = optional_usize(attributes, "start_line")?
569 .unwrap_or(1)
570 .max(1);
571 let requested_end =
572 optional_usize(attributes, "end_line")?.unwrap_or(requested_start + 200);
573
574 let bytes = self.vfs.read(&path)?;
575 let text = String::from_utf8(bytes.clone()).map_err(|_| EngineError::InvalidUtf8)?;
576 let sha256 = self.vfs.hash(&path)?;
577 self.known_hashes.insert(path.clone(), sha256.clone());
578
579 let all_lines: Vec<&str> = text.lines().collect();
580 let total_lines = all_lines.len();
581
582 let (served_start, served_end, warning) = if total_lines == 0 {
583 (0, 0, Some("file is empty; returning no lines".to_string()))
584 } else {
585 let served_start = requested_start.min(total_lines);
586 let served_end = requested_end.max(served_start).min(total_lines);
587 let warning = if served_start != requested_start || served_end != requested_end {
588 Some(format!(
589 "requested lines {}-{} adjusted to {}-{} (file has {} lines)",
590 requested_start, requested_end, served_start, served_end, total_lines
591 ))
592 } else {
593 None
594 };
595 (served_start, served_end, warning)
596 };
597
598 let body = if total_lines == 0 {
599 String::new()
600 } else {
601 let mut rendered = Vec::new();
602 for line_idx in served_start..=served_end {
603 let content = all_lines[line_idx - 1];
604 rendered.push(format!("[{line_idx}] {content}"));
605 }
606 rendered.join("\n")
607 };
608
609 Ok(ReadFileOutput {
610 path,
611 size_bytes: bytes.len(),
612 sha256,
613 requested_start,
614 requested_end,
615 served_start,
616 served_end,
617 total_lines,
618 body,
619 warning,
620 })
621 }
622
623 fn finalize_apply_edit(&mut self, edit: PendingApplyEdit) -> Result<ApplyEditOutput> {
624 let search = String::from_utf8(edit.search).map_err(|_| EngineError::InvalidUtf8)?;
625 let replace = String::from_utf8(edit.replace).map_err(|_| EngineError::InvalidUtf8)?;
626 let raw_body = String::from_utf8(edit.raw_body).map_err(|_| EngineError::InvalidUtf8)?;
627 let path = edit.path;
628 let edit_input = resolve_apply_edit_input(&search, &replace, &raw_body);
629
630 if let Some(previous_hash) = self.known_hashes.get(&path) {
631 let current_hash = self.vfs.hash(&path)?;
632 if previous_hash != ¤t_hash {
633 return Ok(ApplyEditOutput {
634 path,
635 applied: false,
636 tier: EditTier::NotApplied,
637 sha256: None,
638 format: edit_input.format,
639 reason_code: Some(APPLY_EDIT_REASON_STALE_HASH.to_string()),
640 warning: Some("[WARN: File modified externally. Please re-read.]".to_string()),
641 });
642 }
643 }
644
645 let original_bytes = self.vfs.read(&path)?;
646 let original = String::from_utf8(original_bytes).map_err(|_| EngineError::InvalidUtf8)?;
647
648 if let Some(reason_code) = edit_input.reason_code {
649 return Ok(ApplyEditOutput {
650 path,
651 applied: false,
652 tier: EditTier::NotApplied,
653 sha256: None,
654 format: edit_input.format,
655 reason_code: Some(reason_code),
656 warning: edit_input
657 .warning
658 .or_else(|| Some("invalid apply_edit payload".to_string())),
659 });
660 }
661
662 let apply_result = if let Some(hunks) = edit_input.diff_hunks {
663 apply_diff_hunks_with_tiers(&original, &hunks)
664 } else if let (Some(search), Some(replace)) =
665 (edit_input.search.as_deref(), edit_input.replace.as_deref())
666 {
667 apply_edit_with_tiers(&original, search, replace)
668 } else {
669 None
670 };
671 let Some((rewritten, tier)) = apply_result else {
672 return Ok(ApplyEditOutput {
673 path,
674 applied: false,
675 tier: EditTier::NotApplied,
676 sha256: None,
677 format: edit_input.format,
678 reason_code: Some(APPLY_EDIT_REASON_NO_MATCH.to_string()),
679 warning: Some("no suitable target block found for apply_edit".to_string()),
680 });
681 };
682
683 self.vfs.write_atomic(&path, rewritten.as_bytes())?;
684 let sha256 = self.vfs.hash(&path)?;
685 self.known_hashes.insert(path.clone(), sha256.clone());
686
687 Ok(ApplyEditOutput {
688 path,
689 applied: true,
690 tier,
691 sha256: Some(sha256),
692 format: edit_input.format,
693 reason_code: None,
694 warning: None,
695 })
696 }
697
698 fn execute_list_files(&self, attributes: &Attributes) -> Result<ListFilesOutput> {
699 let path = optional_path(attributes, "path")?.unwrap_or_else(|| PathBuf::from("."));
700 let mut nodes = self.vfs.list_tree(&path)?;
701 nodes.sort_by(|a, b| a.path.cmp(&b.path));
702
703 let mut lines = Vec::new();
704
705 for node in nodes {
706 if lines.len() >= self.max_list_lines {
707 lines.push("[... truncated due to token budget ...]".to_string());
708 break;
709 }
710
711 let mut line = match node.kind {
712 NodeKind::Directory => {
713 if node.descendant_file_count >= self.dense_dir_threshold {
714 format!(
715 "[dir] {}/ ({} files, omitted)",
716 node.path.display(),
717 node.descendant_file_count
718 )
719 } else {
720 format!("[dir] {}/", node.path.display())
721 }
722 }
723 NodeKind::File => format!("[file] {}", node.path.display()),
724 };
725
726 if node.modified_recently {
727 line.push_str(" (*)");
728 }
729
730 lines.push(line);
731 }
732
733 Ok(ListFilesOutput { path, lines })
734 }
735
736 fn execute_terminal_signal(&mut self, attributes: &Attributes) -> Result<SignalOutput> {
737 let pid_value = required_attr(attributes, "pid")?;
738 let pid = pid_value
739 .parse::<u32>()
740 .map_err(|_| EngineError::InvalidInteger {
741 name: "pid",
742 value: pid_value.to_string(),
743 })?;
744 let signal = match attributes
745 .get("signal")
746 .map(|v| v.to_ascii_uppercase())
747 .unwrap_or_else(|| "SIGINT".to_string())
748 .as_str()
749 {
750 "SIGINT" => ProcessSignal::SigInt,
751 "SIGTERM" => ProcessSignal::SigTerm,
752 "SIGKILL" => ProcessSignal::SigKill,
753 other => {
754 return Err(EngineError::InvalidState(format!(
755 "unsupported signal `{other}`"
756 )));
757 }
758 };
759
760 self.terminal.signal(pid, signal)?;
761 Ok(SignalOutput { pid, signal })
762 }
763
764 fn ensure_no_pending(&self, next: &str) -> Result<()> {
765 if self.pending.is_some() {
766 return Err(EngineError::InvalidState(format!(
767 "cannot start <{next}> while another command block is still open"
768 )));
769 }
770 Ok(())
771 }
772}
773
774#[derive(Debug)]
775enum PendingOperation {
776 WriteFile(PendingWrite),
777 ApplyEdit(PendingApplyEdit),
778 Terminal(PendingTerminal),
779}
780
781#[derive(Debug)]
782struct PendingWrite {
783 path: PathBuf,
784 buffer: Vec<u8>,
785}
786
787#[derive(Debug)]
788struct PendingApplyEdit {
789 path: PathBuf,
790 search: Vec<u8>,
791 replace: Vec<u8>,
792 raw_body: Vec<u8>,
793 capture: Option<ApplyCapture>,
794}
795
796#[derive(Debug, Clone, Copy)]
797enum ApplyCapture {
798 Search,
799 Replace,
800}
801
802#[derive(Debug)]
803struct PendingTerminal {
804 command: Vec<u8>,
805}
806
807#[derive(Debug, Clone, Copy, PartialEq, Eq)]
808pub enum Capability {
809 WriteFile,
810 ApplyEdit,
811 ReadFile,
812 ListFiles,
813 Terminal,
814}
815
816pub const DEFAULT_CAPABILITIES: &[Capability] = &[
817 Capability::WriteFile,
818 Capability::ApplyEdit,
819 Capability::ReadFile,
820 Capability::ListFiles,
821 Capability::Terminal,
822];
823
824impl Capability {
825 pub fn name(&self) -> &'static str {
826 match self {
827 Capability::WriteFile => "write_file",
828 Capability::ApplyEdit => "apply_edit",
829 Capability::ReadFile => "read_file",
830 Capability::ListFiles => "list_files",
831 Capability::Terminal => "terminal",
832 }
833 }
834
835 pub fn tag(&self) -> &'static str {
836 match self {
837 Capability::WriteFile => "<write_file path=\"...\"></write_file>",
838 Capability::ApplyEdit => {
839 "<apply_edit path=\"...\">[search/replace blocks or patch body]</apply_edit>"
840 }
841 Capability::ReadFile => "<read_file path=\"...\" start_line=\"..\" end_line=\"...\" />",
842 Capability::ListFiles => "<list_files path=\"...\" />",
843 Capability::Terminal => "<terminal>...</terminal> or <terminal cmd=\"...\" />",
844 }
845 }
846}
847
848pub fn generate_system_prompt(capabilities: &[Capability]) -> String {
849 let enabled: Vec<Capability> = if capabilities.is_empty() {
850 DEFAULT_CAPABILITIES.to_vec()
851 } else {
852 capabilities.to_vec()
853 };
854
855 let mut out = String::from(
856 "You are a Headless Operator. You do not use JSON for tools. You interact directly with the system using XML-style tags.\n",
857 );
858 out.push_str("Everything outside of a tag is considered internal monologue and will not be executed.\n\n");
859 out.push_str("Available Commands:\n");
860 for capability in &enabled {
861 out.push_str(capability.tag());
862 out.push('\n');
863 }
864 out.push_str("\nRules:\n");
865 out.push_str("1. Do not escape strings inside tags.\n");
866 out.push_str("2. Wait for [EXIT_CODE] or detached PID before assuming terminal completion.\n");
867 out.push_str("3. Use apply_edit for small changes and write_file for complete rewrites.\n");
868 out.push_str(
869 "4. apply_edit accepts XML search/replace blocks, SEARCH/REPLACE markers, or unified diff hunks.\n",
870 );
871 out
872}
873
874fn required_path(attributes: &Attributes) -> Result<PathBuf> {
875 optional_path(attributes, "path")?.ok_or(EngineError::MissingAttribute("path"))
876}
877
878fn optional_path(attributes: &Attributes, key: &'static str) -> Result<Option<PathBuf>> {
879 Ok(attributes.get(key).map(PathBuf::from))
880}
881
882fn required_attr<'a>(attributes: &'a Attributes, key: &'static str) -> Result<&'a str> {
883 attributes
884 .get(key)
885 .map(|value| value.as_str())
886 .ok_or(EngineError::MissingAttribute(key))
887}
888
889fn optional_usize(attributes: &Attributes, key: &'static str) -> Result<Option<usize>> {
890 let Some(value) = attributes.get(key) else {
891 return Ok(None);
892 };
893 let parsed = value
894 .parse::<usize>()
895 .map_err(|_| EngineError::InvalidInteger {
896 name: key,
897 value: value.clone(),
898 })?;
899 Ok(Some(parsed))
900}
901
902fn shorten_hash(hash: &str) -> String {
903 hash.chars().take(8).collect()
904}
905
906fn human_bytes(bytes: usize) -> String {
907 const KB: f64 = 1024.0;
908 const MB: f64 = KB * 1024.0;
909
910 let bytes_f = bytes as f64;
911 if bytes_f >= MB {
912 format!("{:.1}mb", bytes_f / MB)
913 } else if bytes_f >= KB {
914 format!("{:.1}kb", bytes_f / KB)
915 } else {
916 format!("{bytes}b")
917 }
918}
919
920fn apply_edit_with_tiers(
921 original: &str,
922 search: &str,
923 replace: &str,
924) -> Option<(String, EditTier)> {
925 if search.is_empty() {
926 return None;
927 }
928
929 if let Some(output) = apply_exact(original, search, replace) {
930 return Some((output, EditTier::Exact));
931 }
932
933 if let Some(output) = apply_whitespace_agnostic(original, search, replace) {
934 return Some((output, EditTier::WhitespaceAgnostic));
935 }
936
937 apply_contextual_anchor(original, search, replace)
938 .map(|output| (output, EditTier::ContextualAnchor))
939}
940
941#[derive(Debug, Clone, PartialEq, Eq)]
942struct DiffHunkReplacement {
943 search: String,
944 replace: String,
945}
946
947#[derive(Debug, Clone)]
948struct ResolvedApplyEditInput {
949 search: Option<String>,
950 replace: Option<String>,
951 diff_hunks: Option<Vec<DiffHunkReplacement>>,
952 format: Option<String>,
953 reason_code: Option<String>,
954 warning: Option<String>,
955}
956
957fn resolve_apply_edit_input(search: &str, replace: &str, raw_body: &str) -> ResolvedApplyEditInput {
958 if !search.is_empty() {
959 return ResolvedApplyEditInput {
960 search: Some(search.to_string()),
961 replace: Some(replace.to_string()),
962 diff_hunks: None,
963 format: Some(APPLY_EDIT_FORMAT_SEARCH_REPLACE_TAGS.to_string()),
964 reason_code: None,
965 warning: None,
966 };
967 }
968
969 let body = decode_basic_xml_entities(raw_body).trim().to_string();
970 if body.is_empty() {
971 return ResolvedApplyEditInput {
972 search: None,
973 replace: None,
974 diff_hunks: None,
975 format: None,
976 reason_code: Some(APPLY_EDIT_REASON_EMPTY_EDIT.to_string()),
977 warning: Some(
978 "apply_edit requires <search>/<replace> blocks or a non-empty patch body"
979 .to_string(),
980 ),
981 };
982 }
983
984 if let Some((parsed_search, parsed_replace)) = parse_search_replace_markers(&body) {
985 return ResolvedApplyEditInput {
986 search: Some(parsed_search),
987 replace: Some(parsed_replace),
988 diff_hunks: None,
989 format: Some(APPLY_EDIT_FORMAT_SEARCH_REPLACE_MARKERS.to_string()),
990 reason_code: None,
991 warning: None,
992 };
993 }
994
995 if let Some((parsed_search, parsed_replace)) = parse_apply_edit_xml_blocks(&body) {
996 return ResolvedApplyEditInput {
997 search: Some(parsed_search),
998 replace: Some(parsed_replace),
999 diff_hunks: None,
1000 format: Some(APPLY_EDIT_FORMAT_SEARCH_REPLACE_XML_BLOCKS.to_string()),
1001 reason_code: None,
1002 warning: None,
1003 };
1004 }
1005
1006 if let Some(hunks) = parse_unified_diff_hunks(&body) {
1007 if hunks.is_empty() {
1008 return ResolvedApplyEditInput {
1009 search: None,
1010 replace: None,
1011 diff_hunks: None,
1012 format: Some(APPLY_EDIT_FORMAT_UNIFIED_DIFF.to_string()),
1013 reason_code: Some(APPLY_EDIT_REASON_NO_HUNKS.to_string()),
1014 warning: Some(
1015 "unified diff was detected but no @@ hunk blocks were parsed".to_string(),
1016 ),
1017 };
1018 }
1019 return ResolvedApplyEditInput {
1020 search: None,
1021 replace: None,
1022 diff_hunks: Some(hunks),
1023 format: Some(APPLY_EDIT_FORMAT_UNIFIED_DIFF.to_string()),
1024 reason_code: None,
1025 warning: None,
1026 };
1027 }
1028
1029 ResolvedApplyEditInput {
1030 search: None,
1031 replace: None,
1032 diff_hunks: None,
1033 format: Some(APPLY_EDIT_FORMAT_RAW_TEXT.to_string()),
1034 reason_code: Some(APPLY_EDIT_REASON_PARSE_ERROR.to_string()),
1035 warning: Some("unsupported apply_edit body format".to_string()),
1036 }
1037}
1038
1039fn decode_basic_xml_entities(input: &str) -> String {
1040 input
1041 .replace("<", "<")
1042 .replace(">", ">")
1043 .replace("&", "&")
1044}
1045
1046fn parse_search_replace_markers(input: &str) -> Option<(String, String)> {
1047 let mut mode = 0_u8;
1048 let mut search = Vec::new();
1049 let mut replace = Vec::new();
1050 let mut saw_markers = false;
1051
1052 for line in input.lines() {
1053 let trimmed = line.trim();
1054 if trimmed.eq("<<<<<<< SEARCH") {
1055 mode = 1;
1056 saw_markers = true;
1057 continue;
1058 }
1059 if trimmed.eq("=======") && mode == 1 {
1060 mode = 2;
1061 continue;
1062 }
1063 if trimmed.eq(">>>>>>> REPLACE") && mode == 2 {
1064 mode = 0;
1065 continue;
1066 }
1067 match mode {
1068 1 => search.push(line),
1069 2 => replace.push(line),
1070 _ => {}
1071 }
1072 }
1073
1074 if !saw_markers {
1075 return None;
1076 }
1077 Some((search.join("\n"), replace.join("\n")))
1078}
1079
1080fn parse_apply_edit_xml_blocks(input: &str) -> Option<(String, String)> {
1081 let search = extract_tag_body(input, "search")?;
1082 let replace = extract_tag_body(input, "replace")?;
1083 Some((search, replace))
1084}
1085
1086fn extract_tag_body(input: &str, tag: &str) -> Option<String> {
1087 let open = format!("<{tag}>");
1088 let close = format!("</{tag}>");
1089 let start = input.find(&open)? + open.len();
1090 let end = input[start..].find(&close)? + start;
1091 Some(input[start..end].to_string())
1092}
1093
1094fn parse_unified_diff_hunks(input: &str) -> Option<Vec<DiffHunkReplacement>> {
1095 let lines = input.lines().collect::<Vec<_>>();
1096 let mut idx = 0usize;
1097 let mut hunks = Vec::new();
1098 let mut saw_hunk_header = false;
1099
1100 while idx < lines.len() {
1101 let line = lines[idx].trim_end_matches('\r');
1102 if line.starts_with("@@") {
1103 saw_hunk_header = true;
1104 idx = idx.saturating_add(1);
1105 let mut search_lines = Vec::new();
1106 let mut replace_lines = Vec::new();
1107
1108 while idx < lines.len() {
1109 let current = lines[idx].trim_end_matches('\r');
1110 if current.starts_with("@@") {
1111 break;
1112 }
1113 if current.starts_with("diff --git ")
1114 || current.starts_with("*** End Patch")
1115 || current.starts_with("*** Update File:")
1116 {
1117 break;
1118 }
1119 if current.eq("\\ No newline at end of file") {
1120 idx = idx.saturating_add(1);
1121 continue;
1122 }
1123 if let Some(rest) = current.strip_prefix('+') {
1124 if !current.starts_with("+++") {
1125 replace_lines.push(rest.to_string());
1126 }
1127 } else if let Some(rest) = current.strip_prefix('-') {
1128 if !current.starts_with("---") {
1129 search_lines.push(rest.to_string());
1130 }
1131 } else if let Some(rest) = current.strip_prefix(' ') {
1132 search_lines.push(rest.to_string());
1133 replace_lines.push(rest.to_string());
1134 }
1135 idx = idx.saturating_add(1);
1136 }
1137
1138 if !(search_lines.is_empty() && replace_lines.is_empty()) {
1139 hunks.push(DiffHunkReplacement {
1140 search: search_lines.join("\n"),
1141 replace: replace_lines.join("\n"),
1142 });
1143 }
1144 continue;
1145 }
1146 idx = idx.saturating_add(1);
1147 }
1148
1149 saw_hunk_header.then_some(hunks)
1150}
1151
1152fn apply_diff_hunks_with_tiers(
1153 original: &str,
1154 hunks: &[DiffHunkReplacement],
1155) -> Option<(String, EditTier)> {
1156 let mut current = original.to_string();
1157 let mut strongest_tier = EditTier::Exact;
1158 for hunk in hunks {
1159 let (next, tier) = apply_edit_with_tiers(¤t, &hunk.search, &hunk.replace)?;
1160 if edit_tier_rank(&tier) > edit_tier_rank(&strongest_tier) {
1161 strongest_tier = tier;
1162 }
1163 current = next;
1164 }
1165 Some((current, strongest_tier))
1166}
1167
1168const fn edit_tier_rank(tier: &EditTier) -> usize {
1169 match tier {
1170 EditTier::Exact => 0,
1171 EditTier::WhitespaceAgnostic => 1,
1172 EditTier::ContextualAnchor => 2,
1173 EditTier::NotApplied => 3,
1174 }
1175}
1176
1177fn apply_exact(original: &str, search: &str, replace: &str) -> Option<String> {
1178 let idx = original.find(search)?;
1179 let mut out = String::with_capacity(original.len() + replace.len());
1180 out.push_str(&original[..idx]);
1181 out.push_str(replace);
1182 out.push_str(&original[idx + search.len()..]);
1183 Some(out)
1184}
1185
1186fn apply_whitespace_agnostic(original: &str, search: &str, replace: &str) -> Option<String> {
1187 let original_lines = collect_line_spans(original);
1188 let search_lines: Vec<&str> = search.lines().collect();
1189 if search_lines.is_empty() || original_lines.len() < search_lines.len() {
1190 return None;
1191 }
1192
1193 for start in 0..=original_lines.len() - search_lines.len() {
1194 let window = &original_lines[start..start + search_lines.len()];
1195 if window
1196 .iter()
1197 .zip(search_lines.iter())
1198 .all(|(candidate, target)| candidate.text.trim() == target.trim())
1199 {
1200 let range_start = window.first()?.start;
1201 let range_end = window.last()?.end;
1202 return Some(splice(original, range_start, range_end, replace));
1203 }
1204 }
1205
1206 None
1207}
1208
1209fn apply_contextual_anchor(original: &str, search: &str, replace: &str) -> Option<String> {
1210 let original_lines = collect_line_spans(original);
1211 let search_lines: Vec<&str> = search.lines().collect();
1212 if search_lines.is_empty() || original_lines.is_empty() {
1213 return None;
1214 }
1215
1216 let window_len = search_lines.len().min(original_lines.len());
1217 let normalized_search = normalize_for_distance(search);
1218 let mut best: Option<(usize, usize, usize)> = None;
1219
1220 for start in 0..=original_lines.len() - window_len {
1221 let window = &original_lines[start..start + window_len];
1222 let joined = window
1223 .iter()
1224 .map(|line| line.text)
1225 .collect::<Vec<_>>()
1226 .join("\n");
1227 let score = levenshtein(&normalize_for_distance(&joined), &normalized_search);
1228
1229 match best {
1230 Some((best_score, _, _)) if score >= best_score => {}
1231 _ => best = Some((score, start, start + window_len - 1)),
1232 }
1233 }
1234
1235 let (score, line_start, line_end) = best?;
1236 let threshold = normalized_search.len().max(6) / 3;
1237 if score > threshold {
1238 return None;
1239 }
1240
1241 let range_start = original_lines[line_start].start;
1242 let range_end = original_lines[line_end].end;
1243 Some(splice(original, range_start, range_end, replace))
1244}
1245
1246fn normalize_for_distance(input: &str) -> String {
1247 input
1248 .lines()
1249 .map(|line| line.split_whitespace().collect::<Vec<_>>().join(" "))
1250 .collect::<Vec<_>>()
1251 .join("\n")
1252 .trim()
1253 .to_string()
1254}
1255
1256fn splice(original: &str, range_start: usize, range_end: usize, replace: &str) -> String {
1257 let mut out = String::with_capacity(original.len() + replace.len());
1258 out.push_str(&original[..range_start]);
1259 out.push_str(replace);
1260 out.push_str(&original[range_end..]);
1261 out
1262}
1263
1264#[derive(Debug)]
1265struct LineSpan<'a> {
1266 start: usize,
1267 end: usize,
1268 text: &'a str,
1269}
1270
1271fn collect_line_spans(input: &str) -> Vec<LineSpan<'_>> {
1272 let mut spans = Vec::new();
1273 let mut offset = 0usize;
1274
1275 for chunk in input.split_inclusive('\n') {
1276 let end = offset + chunk.len();
1277 let text = chunk.strip_suffix('\n').unwrap_or(chunk);
1278 spans.push(LineSpan {
1279 start: offset,
1280 end,
1281 text,
1282 });
1283 offset = end;
1284 }
1285
1286 if input.is_empty() {
1287 return spans;
1288 }
1289
1290 if !input.ends_with('\n') {
1291 if let Some(last) = spans.last_mut() {
1292 last.end = input.len();
1293 }
1294 }
1295
1296 spans
1297}
1298
1299#[cfg(test)]
1300mod tests {
1301 use super::*;
1302 use std::collections::BTreeMap;
1303 use std::sync::{Arc, Mutex};
1304
1305 #[derive(Clone, Default)]
1306 struct InMemoryVfs {
1307 files: Arc<Mutex<HashMap<PathBuf, Vec<u8>>>>,
1308 tree: Arc<Mutex<Vec<TreeNode>>>,
1309 }
1310
1311 impl InMemoryVfs {
1312 fn set_file(&self, path: &str, body: &str) {
1313 self.files
1314 .lock()
1315 .expect("lock")
1316 .insert(PathBuf::from(path), body.as_bytes().to_vec());
1317 }
1318
1319 fn get_file(&self, path: &str) -> String {
1320 String::from_utf8(
1321 self.files
1322 .lock()
1323 .expect("lock")
1324 .get(&PathBuf::from(path))
1325 .cloned()
1326 .unwrap_or_default(),
1327 )
1328 .expect("utf8")
1329 }
1330
1331 fn set_tree(&self, nodes: Vec<TreeNode>) {
1332 *self.tree.lock().expect("lock") = nodes;
1333 }
1334 }
1335
1336 impl VirtualFileSystem for InMemoryVfs {
1337 fn read(&self, path: &Path) -> Result<Vec<u8>> {
1338 self.files
1339 .lock()
1340 .expect("lock")
1341 .get(path)
1342 .cloned()
1343 .ok_or_else(|| EngineError::Vfs(format!("missing file {}", path.display())))
1344 }
1345
1346 fn write_atomic(&self, path: &Path, bytes: &[u8]) -> Result<()> {
1347 self.files
1348 .lock()
1349 .expect("lock")
1350 .insert(path.to_path_buf(), bytes.to_vec());
1351 Ok(())
1352 }
1353
1354 fn hash(&self, path: &Path) -> Result<String> {
1355 let bytes = self.read(path)?;
1356 Ok(simple_hash(&bytes))
1357 }
1358
1359 fn cwd(&self) -> Result<PathBuf> {
1360 Ok(PathBuf::from("/virtual"))
1361 }
1362
1363 fn list_tree(&self, _path: &Path) -> Result<Vec<TreeNode>> {
1364 Ok(self.tree.lock().expect("lock").clone())
1365 }
1366
1367 fn recent_file_hashes(&self, limit: usize) -> Result<Vec<FileHash>> {
1368 let files = self.files.lock().expect("lock");
1369 let mut entries: Vec<_> = files
1370 .iter()
1371 .map(|(path, body)| FileHash {
1372 path: path.clone(),
1373 sha256: simple_hash(body),
1374 })
1375 .collect();
1376 entries.sort_by(|a, b| a.path.cmp(&b.path));
1377 entries.truncate(limit);
1378 Ok(entries)
1379 }
1380 }
1381
1382 #[derive(Default)]
1383 struct MockTerminal {
1384 pids: Vec<u32>,
1385 last_command: Option<String>,
1386 }
1387
1388 impl TerminalProvider for MockTerminal {
1389 fn run(&mut self, command: &str, _timeout: Duration) -> Result<TerminalExecution> {
1390 self.last_command = Some(command.to_string());
1391 Ok(TerminalExecution {
1392 output: format!("ran: {command}"),
1393 exit_code: Some(0),
1394 cwd: PathBuf::from("/virtual"),
1395 detached_pid: None,
1396 })
1397 }
1398
1399 fn signal(&mut self, pid: u32, _signal: ProcessSignal) -> Result<()> {
1400 self.pids.retain(|existing| *existing != pid);
1401 Ok(())
1402 }
1403
1404 fn active_pids(&self) -> Vec<u32> {
1405 self.pids.clone()
1406 }
1407 }
1408
1409 #[test]
1410 fn write_file_chunks_commit_atomically() {
1411 let vfs = InMemoryVfs::default();
1412 let mut engine = Engine::new(vfs.clone(), MockTerminal::default());
1413
1414 let turn = engine
1415 .execute_turn(vec![
1416 Instruction::StartTag {
1417 name: "write_file".to_string(),
1418 attributes: BTreeMap::from([("path".to_string(), "src/main.rs".to_string())]),
1419 },
1420 Instruction::WriteChunk(b"fn main()".to_vec()),
1421 Instruction::WriteChunk(b" { println!(\"ok\"); }".to_vec()),
1422 Instruction::EndTag("write_file".to_string()),
1423 ])
1424 .expect("turn should run");
1425
1426 assert_eq!(
1427 vfs.get_file("src/main.rs"),
1428 "fn main() { println!(\"ok\"); }"
1429 );
1430 assert!(matches!(
1431 turn.outputs.as_slice(),
1432 [EngineOutput::WriteFile(WriteFileOutput { .. })]
1433 ));
1434 }
1435
1436 #[test]
1437 fn read_file_returns_fidelity_header_and_numbered_lines() {
1438 let vfs = InMemoryVfs::default();
1439 vfs.set_file("src/lib.rs", "a\nb\nc\nd\n");
1440 let mut engine = Engine::new(vfs, MockTerminal::default());
1441
1442 let turn = engine
1443 .execute_turn(vec![Instruction::StartTag {
1444 name: "read_file".to_string(),
1445 attributes: BTreeMap::from([
1446 ("path".to_string(), "src/lib.rs".to_string()),
1447 ("start_line".to_string(), "3".to_string()),
1448 ("end_line".to_string(), "9".to_string()),
1449 ]),
1450 }])
1451 .expect("turn should run");
1452
1453 let EngineOutput::ReadFile(output) = &turn.outputs[0] else {
1454 panic!("expected read output");
1455 };
1456
1457 assert_eq!(output.served_start, 3);
1458 assert_eq!(output.served_end, 4);
1459 assert_eq!(output.body, "[3] c\n[4] d");
1460 assert!(output.warning.is_some());
1461 assert!(output.fidelity_header().contains("PATH: src/lib.rs"));
1462 }
1463
1464 #[test]
1465 fn apply_edit_uses_whitespace_agnostic_matching() {
1466 let vfs = InMemoryVfs::default();
1467 vfs.set_file("src/lib.rs", "fn main() {\n println!(\"x\");\n}\n");
1468 let mut engine = Engine::new(vfs.clone(), MockTerminal::default());
1469
1470 let turn = engine
1471 .execute_turn(vec![
1472 Instruction::StartTag {
1473 name: "apply_edit".to_string(),
1474 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1475 },
1476 Instruction::StartTag {
1477 name: "search".to_string(),
1478 attributes: BTreeMap::new(),
1479 },
1480 Instruction::RawChunk {
1481 tag: "search".to_string(),
1482 bytes: b" println!(\"x\"); ".to_vec(),
1483 },
1484 Instruction::EndTag("search".to_string()),
1485 Instruction::StartTag {
1486 name: "replace".to_string(),
1487 attributes: BTreeMap::new(),
1488 },
1489 Instruction::RawChunk {
1490 tag: "replace".to_string(),
1491 bytes: b"println!(\"y\");".to_vec(),
1492 },
1493 Instruction::EndTag("replace".to_string()),
1494 Instruction::EndTag("apply_edit".to_string()),
1495 ])
1496 .expect("turn should run");
1497
1498 let EngineOutput::ApplyEdit(edit) = &turn.outputs[0] else {
1499 panic!("expected apply_edit output");
1500 };
1501
1502 assert!(edit.applied);
1503 assert_eq!(edit.tier, EditTier::WhitespaceAgnostic);
1504 assert!(vfs.get_file("src/lib.rs").contains("println!(\"y\");"));
1505 }
1506
1507 #[test]
1508 fn apply_edit_accepts_unified_diff_hunk_body() {
1509 let vfs = InMemoryVfs::default();
1510 vfs.set_file("src/lib.rs", "alpha\nbeta\ngamma\n");
1511 let mut engine = Engine::new(vfs.clone(), MockTerminal::default());
1512
1513 let turn = engine
1514 .execute_turn(vec![
1515 Instruction::StartTag {
1516 name: "apply_edit".to_string(),
1517 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1518 },
1519 Instruction::Text(
1520 "@@ -1,3 +1,3 @@\n alpha\n-beta\n+beta (edited)\n gamma\n".to_string(),
1521 ),
1522 Instruction::EndTag("apply_edit".to_string()),
1523 ])
1524 .expect("turn should run");
1525
1526 let EngineOutput::ApplyEdit(edit) = &turn.outputs[0] else {
1527 panic!("expected apply_edit output");
1528 };
1529
1530 assert!(edit.applied);
1531 assert_eq!(edit.format.as_deref(), Some("unified_diff"));
1532 assert!(vfs.get_file("src/lib.rs").contains("beta (edited)"));
1533 }
1534
1535 #[test]
1536 fn apply_edit_accepts_begin_patch_wrapper_body() {
1537 let vfs = InMemoryVfs::default();
1538 vfs.set_file("src/lib.rs", "alpha\nbeta\ngamma\n");
1539 let mut engine = Engine::new(vfs.clone(), MockTerminal::default());
1540
1541 let turn = engine
1542 .execute_turn(vec![
1543 Instruction::StartTag {
1544 name: "apply_edit".to_string(),
1545 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1546 },
1547 Instruction::Text(
1548 "*** Begin Patch\n*** Update File: src/lib.rs\n@@ -1,3 +1,3 @@\n alpha\n-beta\n+beta (edited)\n gamma\n*** End Patch\n".to_string(),
1549 ),
1550 Instruction::EndTag("apply_edit".to_string()),
1551 ])
1552 .expect("turn should run");
1553
1554 let EngineOutput::ApplyEdit(edit) = &turn.outputs[0] else {
1555 panic!("expected apply_edit output");
1556 };
1557
1558 assert!(edit.applied);
1559 assert_eq!(edit.format.as_deref(), Some("unified_diff"));
1560 assert!(vfs.get_file("src/lib.rs").contains("beta (edited)"));
1561 }
1562
1563 #[test]
1564 fn apply_edit_accepts_begin_patch_wrapper_with_absolute_update_file_path() {
1565 let vfs = InMemoryVfs::default();
1566 vfs.set_file("src/lib.rs", "alpha\nbeta\ngamma\n");
1567 let mut engine = Engine::new(vfs.clone(), MockTerminal::default());
1568
1569 let turn = engine
1570 .execute_turn(vec![
1571 Instruction::StartTag {
1572 name: "apply_edit".to_string(),
1573 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1574 },
1575 Instruction::Text(
1576 "*** Begin Patch\n*** Update File: /tmp/workspace/src/lib.rs\n@@ -1,3 +1,3 @@\n alpha\n-beta\n+beta (edited)\n gamma\n*** End Patch\n".to_string(),
1577 ),
1578 Instruction::EndTag("apply_edit".to_string()),
1579 ])
1580 .expect("turn should run");
1581
1582 let EngineOutput::ApplyEdit(edit) = &turn.outputs[0] else {
1583 panic!("expected apply_edit output");
1584 };
1585
1586 assert!(edit.applied);
1587 assert_eq!(edit.format.as_deref(), Some(APPLY_EDIT_FORMAT_UNIFIED_DIFF));
1588 assert!(vfs.get_file("src/lib.rs").contains("beta (edited)"));
1589 }
1590
1591 #[test]
1592 fn apply_edit_accepts_search_replace_markers_body() {
1593 let vfs = InMemoryVfs::default();
1594 vfs.set_file("src/lib.rs", "alpha\nbeta\ngamma\n");
1595 let mut engine = Engine::new(vfs.clone(), MockTerminal::default());
1596
1597 let turn = engine
1598 .execute_turn(vec![
1599 Instruction::StartTag {
1600 name: "apply_edit".to_string(),
1601 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1602 },
1603 Instruction::Text(
1604 "<<<<<<< SEARCH\nbeta\n=======\nbeta (edited)\n>>>>>>> REPLACE\n".to_string(),
1605 ),
1606 Instruction::EndTag("apply_edit".to_string()),
1607 ])
1608 .expect("turn should run");
1609
1610 let EngineOutput::ApplyEdit(edit) = &turn.outputs[0] else {
1611 panic!("expected apply_edit output");
1612 };
1613
1614 assert!(edit.applied);
1615 assert_eq!(edit.format.as_deref(), Some("search_replace_markers"));
1616 assert!(vfs.get_file("src/lib.rs").contains("beta (edited)"));
1617 }
1618
1619 #[test]
1620 fn apply_edit_accepts_xml_escaped_search_replace_markers_body() {
1621 let vfs = InMemoryVfs::default();
1622 vfs.set_file("src/lib.rs", "alpha\nbeta\ngamma\n");
1623 let mut engine = Engine::new(vfs.clone(), MockTerminal::default());
1624
1625 let turn = engine
1626 .execute_turn(vec![
1627 Instruction::StartTag {
1628 name: "apply_edit".to_string(),
1629 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1630 },
1631 Instruction::Text(
1632 "<<<<<<< SEARCH\nbeta\n=======\nbeta (escaped)\n>>>>>>> REPLACE\n".to_string(),
1633 ),
1634 Instruction::EndTag("apply_edit".to_string()),
1635 ])
1636 .expect("turn should run");
1637
1638 let EngineOutput::ApplyEdit(edit) = &turn.outputs[0] else {
1639 panic!("expected apply_edit output");
1640 };
1641
1642 assert!(edit.applied);
1643 assert_eq!(
1644 edit.format.as_deref(),
1645 Some(APPLY_EDIT_FORMAT_SEARCH_REPLACE_MARKERS)
1646 );
1647 assert!(vfs.get_file("src/lib.rs").contains("beta (escaped)"));
1648 }
1649
1650 #[test]
1651 fn apply_edit_accepts_xml_search_replace_blocks_in_raw_body() {
1652 let vfs = InMemoryVfs::default();
1653 vfs.set_file("src/lib.rs", "alpha\nbeta\ngamma\n");
1654 let mut engine = Engine::new(vfs.clone(), MockTerminal::default());
1655
1656 let turn = engine
1657 .execute_turn(vec![
1658 Instruction::StartTag {
1659 name: "apply_edit".to_string(),
1660 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1661 },
1662 Instruction::RawChunk {
1663 tag: "apply_edit".to_string(),
1664 bytes: b"<search>beta</search><replace>beta (edited)</replace>".to_vec(),
1665 },
1666 Instruction::EndTag("apply_edit".to_string()),
1667 ])
1668 .expect("turn should run");
1669
1670 let EngineOutput::ApplyEdit(edit) = &turn.outputs[0] else {
1671 panic!("expected apply_edit output");
1672 };
1673
1674 assert!(edit.applied);
1675 assert_eq!(edit.format.as_deref(), Some("search_replace_xml_blocks"));
1676 assert!(vfs.get_file("src/lib.rs").contains("beta (edited)"));
1677 }
1678
1679 #[test]
1680 fn apply_edit_reports_parse_error_reason_code_for_unsupported_raw_body() {
1681 let vfs = InMemoryVfs::default();
1682 vfs.set_file("src/lib.rs", "alpha\nbeta\ngamma\n");
1683 let mut engine = Engine::new(vfs, MockTerminal::default());
1684
1685 let turn = engine
1686 .execute_turn(vec![
1687 Instruction::StartTag {
1688 name: "apply_edit".to_string(),
1689 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1690 },
1691 Instruction::Text("totally unsupported patch format".to_string()),
1692 Instruction::EndTag("apply_edit".to_string()),
1693 ])
1694 .expect("turn should run");
1695
1696 let EngineOutput::ApplyEdit(edit) = &turn.outputs[0] else {
1697 panic!("expected apply_edit output");
1698 };
1699
1700 assert!(!edit.applied);
1701 assert_eq!(edit.reason_code.as_deref(), Some("parse_error"));
1702 assert_eq!(edit.format.as_deref(), Some("raw_text"));
1703 }
1704
1705 #[test]
1706 fn capability_manifest_reports_current_engine_contract() {
1707 let engine = Engine::new(InMemoryVfs::default(), MockTerminal::default())
1708 .with_terminal_timeout(Duration::from_secs(9))
1709 .with_list_budget(77, 33);
1710
1711 let manifest = engine.capability_manifest();
1712
1713 assert_eq!(
1714 manifest
1715 .commands
1716 .iter()
1717 .map(|command| command.name)
1718 .collect::<Vec<_>>(),
1719 vec![
1720 "write_file",
1721 "apply_edit",
1722 "read_file",
1723 "list_files",
1724 "terminal"
1725 ]
1726 );
1727 assert!(
1728 manifest
1729 .apply_edit_formats
1730 .contains(&APPLY_EDIT_FORMAT_SEARCH_REPLACE_MARKERS)
1731 );
1732 assert!(
1733 manifest
1734 .apply_edit_reason_codes
1735 .contains(&APPLY_EDIT_REASON_PARSE_ERROR)
1736 );
1737 assert_eq!(
1738 manifest.apply_edit_tiers,
1739 vec![
1740 EditTier::Exact,
1741 EditTier::WhitespaceAgnostic,
1742 EditTier::ContextualAnchor,
1743 EditTier::NotApplied,
1744 ]
1745 );
1746 assert_eq!(manifest.state_header_fields, STATE_HEADER_FIELDS);
1747 assert_eq!(manifest.max_list_lines, 77);
1748 assert_eq!(manifest.dense_dir_threshold, 33);
1749 assert_eq!(manifest.terminal_timeout, Duration::from_secs(9));
1750 assert_eq!(manifest.recent_hash_limit, DEFAULT_RECENT_HASH_LIMIT);
1751 }
1752
1753 #[test]
1754 fn apply_edit_warns_if_file_changed_since_last_read() {
1755 let vfs = InMemoryVfs::default();
1756 vfs.set_file("src/lib.rs", "alpha\nbeta\n");
1757 let mut engine = Engine::new(vfs.clone(), MockTerminal::default());
1758
1759 let _ = engine
1760 .execute_turn(vec![Instruction::StartTag {
1761 name: "read_file".to_string(),
1762 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1763 }])
1764 .expect("read should work");
1765
1766 vfs.set_file("src/lib.rs", "external\nchange\n");
1767
1768 let turn = engine
1769 .execute_turn(vec![
1770 Instruction::StartTag {
1771 name: "apply_edit".to_string(),
1772 attributes: BTreeMap::from([("path".to_string(), "src/lib.rs".to_string())]),
1773 },
1774 Instruction::StartTag {
1775 name: "search".to_string(),
1776 attributes: BTreeMap::new(),
1777 },
1778 Instruction::RawChunk {
1779 tag: "search".to_string(),
1780 bytes: b"beta".to_vec(),
1781 },
1782 Instruction::EndTag("search".to_string()),
1783 Instruction::StartTag {
1784 name: "replace".to_string(),
1785 attributes: BTreeMap::new(),
1786 },
1787 Instruction::RawChunk {
1788 tag: "replace".to_string(),
1789 bytes: b"gamma".to_vec(),
1790 },
1791 Instruction::EndTag("replace".to_string()),
1792 Instruction::EndTag("apply_edit".to_string()),
1793 ])
1794 .expect("apply should run");
1795
1796 let EngineOutput::ApplyEdit(edit) = &turn.outputs[0] else {
1797 panic!("expected apply_edit output");
1798 };
1799
1800 assert!(!edit.applied);
1801 assert_eq!(edit.tier, EditTier::NotApplied);
1802 assert!(
1803 edit.warning
1804 .as_deref()
1805 .unwrap_or_default()
1806 .contains("File modified externally")
1807 );
1808 }
1809
1810 #[test]
1811 fn list_files_omits_dense_directories_and_marks_recent() {
1812 let vfs = InMemoryVfs::default();
1813 vfs.set_tree(vec![
1814 TreeNode {
1815 path: PathBuf::from("src"),
1816 kind: NodeKind::Directory,
1817 descendant_file_count: 3,
1818 modified_recently: false,
1819 },
1820 TreeNode {
1821 path: PathBuf::from("src/lib.rs"),
1822 kind: NodeKind::File,
1823 descendant_file_count: 0,
1824 modified_recently: true,
1825 },
1826 TreeNode {
1827 path: PathBuf::from("node_modules"),
1828 kind: NodeKind::Directory,
1829 descendant_file_count: 2400,
1830 modified_recently: false,
1831 },
1832 ]);
1833
1834 let mut engine = Engine::new(vfs, MockTerminal::default()).with_list_budget(100, 200);
1835 let turn = engine
1836 .execute_turn(vec![Instruction::StartTag {
1837 name: "list_files".to_string(),
1838 attributes: BTreeMap::from([("path".to_string(), ".".to_string())]),
1839 }])
1840 .expect("list should run");
1841
1842 let EngineOutput::ListFiles(output) = &turn.outputs[0] else {
1843 panic!("expected list output");
1844 };
1845
1846 assert!(
1847 output
1848 .lines
1849 .iter()
1850 .any(|line| line.contains("node_modules") && line.contains("omitted"))
1851 );
1852 assert!(output.lines.iter().any(|line| line.contains("(*)")));
1853 }
1854
1855 #[test]
1856 fn terminal_executes_command_and_reports_state_header() {
1857 let vfs = InMemoryVfs::default();
1858 let terminal = MockTerminal {
1859 pids: vec![42, 7],
1860 ..Default::default()
1861 };
1862
1863 let mut engine = Engine::new(vfs, terminal);
1864 let turn = engine
1865 .execute_turn(vec![
1866 Instruction::StartTag {
1867 name: "terminal".to_string(),
1868 attributes: BTreeMap::new(),
1869 },
1870 Instruction::RawChunk {
1871 tag: "terminal".to_string(),
1872 bytes: b"echo hi".to_vec(),
1873 },
1874 Instruction::EndTag("terminal".to_string()),
1875 ])
1876 .expect("terminal turn should run");
1877
1878 assert!(matches!(
1879 turn.outputs.as_slice(),
1880 [EngineOutput::Terminal(TerminalExecution { .. })]
1881 ));
1882 assert_eq!(turn.state_header.active_pids, vec![7, 42]);
1883 assert!(turn.state_header.render().contains("CWD: /virtual"));
1884 }
1885
1886 #[test]
1887 fn terminal_supports_attribute_command_form() {
1888 let vfs = InMemoryVfs::default();
1889 let mut engine = Engine::new(vfs, MockTerminal::default());
1890
1891 let turn = engine
1892 .execute_turn(vec![
1893 Instruction::StartTag {
1894 name: "terminal".to_string(),
1895 attributes: BTreeMap::from([("cmd".to_string(), "echo attr".to_string())]),
1896 },
1897 Instruction::EndTag("terminal".to_string()),
1898 ])
1899 .expect("terminal command should run");
1900
1901 let EngineOutput::Terminal(output) = &turn.outputs[0] else {
1902 panic!("expected terminal output");
1903 };
1904 assert!(output.output.contains("ran: echo attr"));
1905 }
1906
1907 #[test]
1908 fn unknown_tags_emit_warnings_instead_of_silent_noops() {
1909 let vfs = InMemoryVfs::default();
1910 let mut engine = Engine::new(vfs, MockTerminal::default());
1911
1912 let turn = engine
1913 .execute_turn(vec![
1914 Instruction::StartTag {
1915 name: "mystery_tool".to_string(),
1916 attributes: BTreeMap::new(),
1917 },
1918 Instruction::EndTag("mystery_tool".to_string()),
1919 ])
1920 .expect("turn should run");
1921
1922 assert_eq!(turn.outputs.len(), 2);
1923 assert!(matches!(
1924 &turn.outputs[0],
1925 EngineOutput::Warning(message) if message.contains("unsupported start tag <mystery_tool>")
1926 ));
1927 assert!(matches!(
1928 &turn.outputs[1],
1929 EngineOutput::Warning(message) if message.contains("unsupported end tag </mystery_tool>")
1930 ));
1931 }
1932
1933 #[test]
1934 fn system_prompt_includes_enabled_commands() {
1935 let prompt = generate_system_prompt(&[Capability::ReadFile, Capability::Terminal]);
1936 assert!(prompt.contains("<read_file"));
1937 assert!(prompt.contains("<terminal>"));
1938 assert!(!prompt.contains("<write_file path"));
1939 }
1940
1941 fn simple_hash(input: &[u8]) -> String {
1942 let mut acc: u64 = 1469598103934665603;
1943 for b in input {
1944 acc ^= *b as u64;
1945 acc = acc.wrapping_mul(1099511628211);
1946 }
1947 format!("{acc:016x}")
1948 }
1949}