Skip to main content

haest_core/
workspace.rs

1//! The workspace: the ONE door between haest and a file system or a shell.
2//! Every command a tool runs goes through [`Workspace::shell`] / [`Workspace::run`];
3//! every file operation through [`Workspace::fs`].
4//!
5//! Implementations live in `haest-workspace` (real disk + real bash, and a bashkit
6//! sandbox over a copy-on-write overlay). [`ShutWorkspace`] is the one with
7//! neither files nor a shell (a run that only talks, or only uses a host's own
8//! tools).
9//!
10//! PLUG POINT: implement [`Workspace`] to give the agent a different world.
11//! The loop hands it to every tool ([`AgentDeps`](crate::AgentDeps)'
12//! `workspace`). A sandbox also reports what it changed ([`ChangeSet`]) so a
13//! human can review and apply it.
14
15use std::{fmt, ops::Deref, path::PathBuf, sync::Arc, time::Duration};
16
17use async_trait::async_trait;
18use serde::{Deserialize, Serialize};
19use tokio_util::sync::CancellationToken;
20
21use crate::fs::{FsRef, ShutFs};
22
23crate::word_enum! {
24    /// What kind of world a [`Workspace`] is (the `workspace` setting's words).
25    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
26    #[non_exhaustive]
27    pub enum WorkspaceMode ("workspace mode") {
28        /// A simulated bash over a copy-on-write overlay of the project. Writes stay in memory.
29        Sandbox = "sandbox",
30        /// The real disk and the real bash.
31        Real = "real",
32        /// No files and no shell.
33        Shut = "shut",
34    }
35}
36
37/// How to run one command: where, until when, and the interrupt.
38///
39/// Built with [`ExecOptions::new`]; a workspace reads the fields.
40#[derive(Debug, Clone)]
41#[non_exhaustive]
42pub struct ExecOptions {
43    /// The working directory, absolute.
44    pub cwd: PathBuf,
45    /// The interrupt: when it fires, the command is stopped and what it
46    /// printed so far comes back.
47    pub cancel: CancellationToken,
48    /// How long the command may run before it is stopped.
49    pub timeout: Duration,
50}
51
52impl ExecOptions {
53    /// Run in `cwd` for at most `timeout`, with a fresh interrupt
54    /// ([`with_cancel`](Self::with_cancel) shares the caller's).
55    pub fn new(cwd: impl Into<PathBuf>, timeout: Duration) -> Self {
56        Self {
57            cwd: cwd.into(),
58            cancel: CancellationToken::new(),
59            timeout,
60        }
61    }
62
63    /// Stopped when `cancel` fires.
64    #[must_use]
65    pub fn with_cancel(mut self, cancel: CancellationToken) -> Self {
66        self.cancel = cancel;
67        self
68    }
69}
70
71/// How a command ended: what it printed, its exit code, and whether it ran
72/// out of time.
73#[derive(Debug, Clone, Default, PartialEq, Eq)]
74pub struct ExecResult {
75    /// Standard output, as text (invalid UTF-8 replaced).
76    pub stdout: String,
77    /// Standard error, as text; also where a workspace says why a command
78    /// could not run.
79    pub stderr: String,
80    /// The exit code: 0 for success; [`EXIT_NOT_FOUND`] for no such program.
81    pub exit_code: i32,
82    /// The command was stopped because [`ExecOptions::timeout`] ran out.
83    pub timed_out: bool,
84}
85
86impl ExecResult {
87    /// A command that succeeded (exit code 0) and printed `stdout`.
88    pub fn ok(stdout: impl Into<String>) -> Self {
89        Self {
90            stdout: stdout.into(),
91            ..Self::default()
92        }
93    }
94
95    /// A command that ended with `exit_code`, saying why on `stderr`.
96    ///
97    /// ```
98    /// use haest_core::workspace::{EXIT_NOT_FOUND, ExecResult};
99    ///
100    /// let missing = ExecResult::failed("upper: command not found\n", EXIT_NOT_FOUND);
101    /// assert_eq!((missing.stdout.as_str(), missing.exit_code), ("", EXIT_NOT_FOUND));
102    /// assert_eq!(ExecResult::ok("hi\n").exit_code, 0);
103    /// ```
104    pub fn failed(stderr: impl Into<String>, exit_code: i32) -> Self {
105        Self {
106            stderr: stderr.into(),
107            exit_code,
108            ..Self::default()
109        }
110    }
111}
112
113/// Exit code for "no such program", the shell convention every mode reports.
114pub const EXIT_NOT_FOUND: i32 = 127;
115
116/// Where a streamed command's output goes, chunk by chunk as it arrives:
117/// stdout and stderr interleaved, whole UTF-8 characters only.
118///
119/// Built from a closure (`OutputChunks::from(|text: &str| ..)`) and called
120/// like one (`on_output(text)`); cheap to clone.
121#[derive(Clone)]
122pub struct OutputChunks(Arc<dyn Fn(&str) + Send + Sync>);
123
124impl OutputChunks {
125    /// Output that goes to `f`.
126    pub fn new(f: impl Fn(&str) + Send + Sync + 'static) -> Self {
127        Self(Arc::new(f))
128    }
129}
130
131impl<F: Fn(&str) + Send + Sync + 'static> From<F> for OutputChunks {
132    fn from(f: F) -> Self {
133        Self::new(f)
134    }
135}
136
137impl Deref for OutputChunks {
138    type Target = dyn Fn(&str) + Send + Sync;
139
140    fn deref(&self) -> &Self::Target {
141        &*self.0
142    }
143}
144
145impl fmt::Debug for OutputChunks {
146    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
147        f.debug_tuple("OutputChunks").finish_non_exhaustive()
148    }
149}
150
151/// One path the sandbox changed: what a host lists for the human to review,
152/// and applies ([`ChangeSet`]).
153///
154/// Built with [`new`](Self::new) and [`with_conflict`](Self::with_conflict),
155/// so a part it gains later breaks no change set; its fields read as they are.
156///
157/// ```
158/// use haest_core::workspace::{Change, ChangeKind};
159///
160/// let c = Change::new("/src/a.rs", ChangeKind::Modified).with_conflict(true);
161/// assert!(c.conflict);
162/// assert_eq!(c.path, "/src/a.rs");
163/// ```
164#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
165#[non_exhaustive]
166pub struct Change {
167    /// Overlay path, e.g. /src/a.ts.
168    pub path: String,
169    /// Added, modified or deleted.
170    pub kind: ChangeKind,
171    /// Apply skips it and keeps it listed, because applying would go over
172    /// what the sandbox never saw: the real file (or its mode) changed since
173    /// the sandbox first touched it (the human's edit). So does a change
174    /// that removes a directory with a conflict under it. A change set may
175    /// find more at the apply, and skip those as conflicts too (the
176    /// sandbox's finds a change that would take along a file it shows under
177    /// another name the disk reads as the same).
178    pub conflict: bool,
179}
180
181impl Change {
182    /// `path` was `kind` in the sandbox, with no conflict.
183    pub fn new(path: impl Into<String>, kind: ChangeKind) -> Self {
184        Self {
185            path: path.into(),
186            kind,
187            conflict: false,
188        }
189    }
190
191    /// Whether apply must skip it ([`conflict`](Self::conflict)).
192    #[must_use]
193    pub fn with_conflict(mut self, conflict: bool) -> Self {
194        self.conflict = conflict;
195        self
196    }
197}
198
199crate::word_enum! {
200    /// What happened to a path in the sandbox.
201    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
202    pub enum ChangeKind ("change kind") {
203        /// It is new.
204        Added = "added",
205        /// Its contents changed.
206        Modified = "modified",
207        /// It was removed.
208        Deleted = "deleted",
209    }
210}
211
212crate::word_enum! {
213    /// Why a change was not applied. The words are the TS haest's (`ApplyFailure`
214    /// in `overlay-apply.ts`).
215    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
216    #[non_exhaustive]
217    pub enum ApplyFailureCode ("apply failure") {
218        /// A symlink on the real disk is on its way, so the write could land
219        /// outside the project.
220        OutsideProject = "outside-project",
221        /// The change is a symlink the sandbox made, or sits behind one: applying
222        /// never makes a link.
223        Symlink = "symlink",
224        /// The disk refused it (permissions, a full disk).
225        WriteFailed = "write-failed",
226    }
227}
228
229/// A change applying could not put on disk. It stays in the sandbox, still listed.
230///
231/// Built with [`new`](Self::new), so a part it gains later breaks no change
232/// set; its fields read as they are.
233#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
234#[non_exhaustive]
235pub struct FailedChange {
236    /// The change (its keys inline on the wire, beside `code` and `reason`).
237    #[serde(flatten)]
238    pub change: Change,
239    /// Why, as a word a host can act on.
240    pub code: ApplyFailureCode,
241    /// Why, for the human.
242    pub reason: String,
243}
244
245impl FailedChange {
246    /// `change` was not applied, for the reason `code`, said to the human as
247    /// `reason`.
248    pub fn new(change: Change, code: ApplyFailureCode, reason: impl Into<String>) -> Self {
249        Self {
250            change,
251            code,
252            reason: reason.into(),
253        }
254    }
255}
256
257/// What applying did with every change ([`ChangeSet::apply`]).
258#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
259pub struct ApplyReport {
260    /// Now on the real disk, and gone from the sandbox's list.
261    pub applied: Vec<Change>,
262    /// Conflicts: left alone so the human's edit survives.
263    pub skipped: Vec<Change>,
264    /// Not applied, each with why.
265    pub failed: Vec<FailedChange>,
266}
267
268/// What a sandbox changed, and putting it on the real disk.
269/// [`Workspace::changes`] hands it out; only a sandbox has one.
270#[async_trait]
271pub trait ChangeSet: Send + Sync {
272    /// Every path the sandbox changed and has not applied yet.
273    async fn list(&self) -> Vec<Change>;
274    /// A unified diff of one change.
275    async fn diff(&self, change: &Change) -> String;
276    /// Put every change on the real disk, but conflicts (skipped) and
277    /// changes that cannot be applied safely (failed, each with why). A
278    /// change that fails stops no other; the report says what happened to
279    /// each.
280    async fn apply(&self) -> ApplyReport;
281}
282
283crate::plug_ref! {
284    /// A [`ChangeSet`], shared: what [`Workspace::changes`] hands out.
285    pub struct ChangeSetRef(dyn ChangeSet);
286}
287
288/// The world the agent works in: a file system and a shell, one door for both.
289///
290/// Every tool reaches files through [`Workspace::fs`] and runs commands through
291/// [`Workspace::shell`] or [`Workspace::run`], so swapping the workspace swaps
292/// the world: the real disk, a sandbox whose writes stay in memory
293/// (`haest-workspace`), or nothing at all ([`ShutWorkspace`]).
294///
295/// Running a command never fails: a program that cannot start, a timeout and
296/// a cancel all come back as an [`ExecResult`] (a nonzero exit code, the
297/// reason on stderr, `timed_out` when [`ExecOptions::timeout`] ran out). A
298/// stopped command returns what it printed so far.
299///
300/// # Examples
301///
302/// A workspace whose files are in memory and whose only "shell" answers
303/// `pwd`:
304///
305/// ```
306/// use std::time::Duration;
307///
308/// use async_trait::async_trait;
309/// use haest_core::{
310///     ExecOptions, ExecResult, FsRef, MemFs, Workspace, WorkspaceMode,
311///     workspace::EXIT_NOT_FOUND,
312/// };
313///
314/// struct Tiny {
315///     fs: FsRef,
316/// }
317///
318/// #[async_trait]
319/// impl Workspace for Tiny {
320///     fn mode(&self) -> WorkspaceMode {
321///         WorkspaceMode::Sandbox
322///     }
323///     fn fs(&self) -> FsRef {
324///         self.fs.clone()
325///     }
326///     async fn shell(&self, command: &str, opts: ExecOptions) -> ExecResult {
327///         self.run(&[command.to_string()], opts).await
328///     }
329///     async fn run(&self, argv: &[String], opts: ExecOptions) -> ExecResult {
330///         match argv.first().map(String::as_str) {
331///             Some("pwd") => ExecResult::ok(format!("{}\n", opts.cwd.display())),
332///             _ => ExecResult::failed("command not found\n", EXIT_NOT_FOUND),
333///         }
334///     }
335///     fn prompt_note(&self) -> String {
336///         "Your shell knows only `pwd`.".into()
337///     }
338/// }
339///
340/// # #[tokio::main(flavor = "current_thread")]
341/// # async fn main() -> Result<(), haest_core::BoxError> {
342/// let ws = Tiny { fs: MemFs::new().into() };
343/// let opts = ExecOptions::new("/project", Duration::from_secs(5));
344/// assert_eq!(ws.shell("pwd", opts.clone()).await.stdout, "/project\n");
345/// assert_eq!(ws.shell("make", opts).await.exit_code, EXIT_NOT_FOUND);
346/// # Ok(())
347/// # }
348/// ```
349#[async_trait]
350pub trait Workspace: Send + Sync {
351    /// What kind of world this is.
352    fn mode(&self) -> WorkspaceMode;
353    /// The files the agent sees, the same files the shell sees.
354    fn fs(&self) -> FsRef;
355    /// A command line, interpreted by bash (real or simulated).
356    async fn shell(&self, command: &str, opts: ExecOptions) -> ExecResult;
357    /// Like [`Workspace::shell`], but the output goes to `on_output` as it
358    /// arrives and NOT into the result, which only says how the command ended:
359    /// a background job may print for hours. The default runs
360    /// [`Workspace::shell`] and hands the whole output over once it ends; a
361    /// workspace with real processes streams.
362    async fn shell_streaming(
363        &self,
364        command: &str,
365        opts: ExecOptions,
366        on_output: OutputChunks,
367    ) -> ExecResult {
368        let r = self.shell(command, opts).await;
369        for text in [&r.stdout, &r.stderr] {
370            if !text.is_empty() {
371                on_output(text);
372            }
373        }
374        ExecResult {
375            stdout: String::new(),
376            stderr: String::new(),
377            ..r
378        }
379    }
380    /// A program and its argv, no shell parsing: `argv[0]` is the program.
381    async fn run(&self, argv: &[String], opts: ExecOptions) -> ExecResult;
382    /// What the model must know about this workspace, for the system prompt;
383    /// empty when there is nothing to say.
384    fn prompt_note(&self) -> String;
385    /// The sandbox's in-memory edits to the project; None for every other mode.
386    fn changes(&self) -> Option<ChangeSetRef> {
387        None
388    }
389}
390
391crate::plug_ref! {
392    /// A [`Workspace`], shared: what [`SharedDeps::workspace`](crate::SharedDeps::workspace)
393    /// and every [`ToolContext`](crate::ToolContext) hold.
394    pub struct WorkspaceRef(dyn Workspace);
395}
396
397/// No files, no shell: every file call fails ([`ShutFs`]) and every command
398/// ends with [`EXIT_NOT_FOUND`]. The prompt note tells the model to work with
399/// the tools it was given.
400#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
401pub struct ShutWorkspace;
402
403const NO_SHELL: &str = "this workspace has no shell";
404
405fn no_shell() -> ExecResult {
406    ExecResult::failed(NO_SHELL, EXIT_NOT_FOUND)
407}
408
409#[async_trait]
410impl Workspace for ShutWorkspace {
411    fn mode(&self) -> WorkspaceMode {
412        WorkspaceMode::Shut
413    }
414    fn fs(&self) -> FsRef {
415        ShutFs.into()
416    }
417    async fn shell(&self, _: &str, _: ExecOptions) -> ExecResult {
418        no_shell()
419    }
420    async fn run(&self, _: &[String], _: ExecOptions) -> ExecResult {
421        no_shell()
422    }
423    fn prompt_note(&self) -> String {
424        "You have no file system and no shell here; work only with the tools you were given.".into()
425    }
426}
427
428#[cfg(test)]
429mod tests;