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;