From 6d3460c19dda16b05a68cf23a95a3ec32c221ea1 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Sun, 15 Nov 2026 11:08:22 -0800 Subject: [PATCH 01/23] Record the decisions on file operations and tool state The decision pages and the comments now give one reason for synchronous file operations: the storage is synchronous by nature, and the run waits for each operation. The pages record that a tool's file operations become `Vfs` effects, that a remote system is a tool's job, that a tool keeps no state between calls, and that each `bash/shell` call gets a shell of its own. The engine, files, and tasks pages also gain the owner's reasons for entries that had none, and lose the open questions that those reasons answer. - The planned-work items `An async VFS` and `The store as a tool` are removed, and the database mount has a synchronous backend. - A thread of its own for bash, with a wake function in the contract, is now an item marked undecided. - The pages still describe a tool that calls its `Access` and a contract that reads only, because the code works that way today. - No code changes. Each edit under `crates` is a comment or one line of `AGENTS.md`. --- .../runner/src/effect_loop.rs | 8 ++-- crates/harness-internal/runner/src/lib.rs | 4 +- .../harness-internal/runner/src/performers.rs | 4 +- crates/runvil-internal/runtime/src/execute.rs | 7 ++-- crates/runvil-internal/vfs/AGENTS.md | 1 + .../runvil-internal/vfs/src/traits/backend.rs | 12 +++--- crates/runvil-plugin/src/lib.rs | 4 +- decisions/engine.md | 37 ++++++++++++------- decisions/files-and-the-vfs.md | 31 ++++++++++++---- decisions/harness-and-host.md | 4 +- decisions/tasks-and-fanout.md | 7 +++- decisions/tools-and-packs.md | 20 +++++++--- 12 files changed, 93 insertions(+), 46 deletions(-) diff --git a/crates/harness-internal/runner/src/effect_loop.rs b/crates/harness-internal/runner/src/effect_loop.rs index 6bb448059..62cd546d8 100644 --- a/crates/harness-internal/runner/src/effect_loop.rs +++ b/crates/harness-internal/runner/src/effect_loop.rs @@ -10,10 +10,10 @@ //! future: the loop starts no task, so a run is one future that any //! executor can drive. When an effect's future lands, the loop appends the //! answer's record and resumes the run with it, then steps again. A Vfs -//! effect has no future: it is one operation on a store of the run, which -//! is memory, so the loop performs the operation inline through the -//! effect's view, appends the answer's record, and resumes the run at -//! once. A run has the store it starts with and one more for each prompt +//! effect has no future: it is one operation on a store of the run, and +//! file operations are synchronous by design, so the loop performs the +//! operation inline through the effect's view, appends the answer's +//! record, and resumes the run at once. A run has the store it starts with and one more for each prompt //! an `execute` runs, and the effect's record names its store, so the //! loop reads the view and never which store it reaches. It resumes every //! Vfs effect of a step this way and then steps once, so the loop awaits diff --git a/crates/harness-internal/runner/src/lib.rs b/crates/harness-internal/runner/src/lib.rs index 90e5dea75..c59579dd9 100644 --- a/crates/harness-internal/runner/src/lib.rs +++ b/crates/harness-internal/runner/src/lib.rs @@ -32,7 +32,9 @@ //! no task, so any executor can drive a run. Performers must not block //! while polled: one that blocks stalls every other effect of the run, //! and a performer with blocking or CPU-heavy work hands it to the -//! Host's own runtime. The crate's async needs come from `futures-util`, +//! Host's own runtime. A file operation is the exception: it is +//! synchronous by design and holds the run until it returns. The +//! crate's async needs come from `futures-util`, //! and `tokio` and `tokio-util` appear only under `[dev-dependencies]` //! (enforced by the Harness tokio ban in `cargo test -p build-xtask`). //! - The Harness reads each [`RunSetup`] field once per run: the run's diff --git a/crates/harness-internal/runner/src/performers.rs b/crates/harness-internal/runner/src/performers.rs index c26034ad3..67af7a7cc 100644 --- a/crates/harness-internal/runner/src/performers.rs +++ b/crates/harness-internal/runner/src/performers.rs @@ -18,8 +18,8 @@ //! run, and the run's stop and cancel with them. A performer with blocking //! or CPU-heavy work hands it to the Host's own runtime and awaits the //! result. A `Vfs` effect has no performer: it is one operation on a -//! store of the run, which is memory, so the loop answers it inline -//! through the Engine's store operation. +//! store of the run, and file operations are synchronous by design, so +//! the loop answers it inline through the Engine's store operation. //! //! The runner supplies the tool performer itself: the run's snapshot of //! the Host's Packs, taken at preparation. The Host supplies the diff --git a/crates/runvil-internal/runtime/src/execute.rs b/crates/runvil-internal/runtime/src/execute.rs index 514143dcf..57a7a8ce3 100644 --- a/crates/runvil-internal/runtime/src/execute.rs +++ b/crates/runvil-internal/runtime/src/execute.rs @@ -73,9 +73,10 @@ use crate::lua::{VfsOp, VfsOutcome}; /// Line bounds arrive as `i64` and convert to `usize`. A read that gives /// an `end` and omits `start` is refused as an invalid range. /// -/// The function is synchronous because the store is memory, with nothing -/// to wait on. The caller can run it inline, on the thread that runs its -/// effect loop. +/// The function is synchronous because every file operation is: the +/// storage underneath is synchronous by nature. The caller runs it +/// inline, on the thread that runs its effect loop, and the run waits +/// for it. /// /// # Errors /// Returns the store's own structured failure for the operation (path diff --git a/crates/runvil-internal/vfs/AGENTS.md b/crates/runvil-internal/vfs/AGENTS.md index 58a24acef..7f7cc271f 100644 --- a/crates/runvil-internal/vfs/AGENTS.md +++ b/crates/runvil-internal/vfs/AGENTS.md @@ -2,3 +2,4 @@ - The machinery modules hold no run concepts. A `Store` is generic machinery (an empty memory backend under its own claims ledger, which any access's identity can view), so it lives with the handle; the mode gate stays at the crate root. - Origin labels are the most specific available: a section name for a chain, a tool id for a tool, a fixture name for a test. +- Backends and `Access` are synchronous, because storage is synchronous by nature. Both stay synchronous: an async form of either is ruled out. diff --git a/crates/runvil-internal/vfs/src/traits/backend.rs b/crates/runvil-internal/vfs/src/traits/backend.rs index 71346808f..fde39ce9f 100644 --- a/crates/runvil-internal/vfs/src/traits/backend.rs +++ b/crates/runvil-internal/vfs/src/traits/backend.rs @@ -8,11 +8,13 @@ use crate::stat::{Entry, FileType, Stat}; /// A storage backend behind the virtual filesystem. /// -/// Operations are synchronous because the Lua VM and the single thread -/// that drives a run are both synchronous. They work on raw bytes. A -/// backend must be `Send`, and `Sync` is optional, because `VfsRef` -/// serializes access to it. Storage is reachable only through an access -/// object that `acquire` binds to one identity. +/// Operations are synchronous because storage is synchronous by nature: +/// memory, and the standard library's file calls. Each one holds its +/// caller until it returns, so a backend over slow storage slows every +/// caller. Operations work on raw bytes. A backend must be `Send`, and +/// `Sync` is optional, because `VfsRef` serializes access to it. Storage +/// is reachable only through an access object that `acquire` binds to one +/// identity. pub trait Vfs: Send { /// Acquires an access object bound to the identity in `cx`. /// diff --git a/crates/runvil-plugin/src/lib.rs b/crates/runvil-plugin/src/lib.rs index c4fcae895..9e3dd1514 100644 --- a/crates/runvil-plugin/src/lib.rs +++ b/crates/runvil-plugin/src/lib.rs @@ -90,7 +90,9 @@ //! resolution it answers at once unless the Pack's state has changed. //! - [`Pack::call`] must not block while polled. Every effect of a run //! is polled on the same task, so blocking or CPU-heavy work goes to the -//! Host's runtime. +//! Host's runtime. A file operation through the call's access is the +//! exception: it is synchronous by design and holds the run until it +//! returns. //! - [`Pack::call`] must not panic. A panicking call's effect is //! answered `Dropped`, and the panic is logged. //! - [`Pack::call`] marks the trust of every output correctly: output diff --git a/decisions/engine.md b/decisions/engine.md index 2fbe4a3bd..f5ee3f870 100644 --- a/decisions/engine.md +++ b/decisions/engine.md @@ -66,6 +66,8 @@ The caller answers effects one at a time, in any order. Parallel work in a fanou The first `Run::step` makes the start checks, in this order. The prompt and every prompt it links declare `runvil: 0`. The arguments are one JSON object that matches the prompt's `args:` declaration ([The prompt language](prompt-language.md)): `Run::new` reads the text and keeps a mismatch for this check, which returns it with the code `args_invalid` and no location. The params meet what each of those prompts requires: each Pack under a `uses:` is `Usable` in the roster that the caller passed to `RunParams::with_packs`, and the model in each role that a prompt declares meets that prompt's requirements for the role. A requirements failure has the code `requirements_unmet`, and its message names every gap. +`Run::new` returns a `Run` and never an error, so every failure of a run, a failed start check included, reaches the caller in one place: the `result` of `Step::Done`. The caller handles a failed run there already, and a failure out of `Run::new` would need a second path that records and reports the same thing. `Run::step` and `Run::resume` return no error either. The owner's reason: "having one place for the error is better than two". + The checks cover the linked prompts because a run may execute any of them. The owner's reason: "we want to know up front if the prompt can run or not". Within each kind of gap, the message lists the gaps of the run's own prompt first and then those of each linked prompt in the order of their names. A line about a linked prompt's gap starts with that prompt's name, as in `- review.md: missing required Pack: web`, and a Pack that two prompts declare has one line. The failure's location is in the first prompt that caused a gap, on the `uses:` key for a Pack and on the `models:` key for a model. ### A step returns its effects and its events as values @@ -104,6 +106,8 @@ The fields of `Step::Done` are `result`, `events`, and `unread`. `result` is a ` A prompt declines its task by returning its reason from Lua, so the run completes and `result` is `Ok` with that text. A prompt that fails a check of its own, such as an `assert` on the range of an argument, raises a Lua error, and the run ends with the code `lua_runtime`, whichever section raised it ([The prompt language](prompt-language.md)). The code `requirements_unmet` belongs to the start checks alone. The code `args_invalid` belongs to the start check of the run's arguments and to an `execute` whose arguments the executed prompt's declaration refuses. +A prompt has the contract of a tool: it takes one JSON object and returns text. A tool reports a failure inside its result, as text with an error flag, and it has no way to say that it declined, so a decline is ordinary result text. The run's `Ok` and `Err` are that flag, and the Engine sets `Err` only for a fault that it can identify itself, such as an unmet requirement. MCP states the rule for a tool in its [CallToolResult](https://modelcontextprotocol.io/specification/2026-07-28/schema#calltoolresult) schema: "Any errors that originate from the tool SHOULD be reported inside the result object, with `isError` set to true, not as an MCP protocol-level error response." The owner's reason: "I don't want to innovate here." The owner's goal for a prompt's input and output contracts: "as standard as possible, so they can fit into the existing LLM ecosystem". + ### A run where every chain waits ends as `stalled` or as `internal` A run stalls when no chain is ready to run, all its awaited effects have their answers, and its main chain waits on something other than its inbox. The Engine then ends it. When tasks wait on their inboxes, the error has the code `stalled` and names them. Otherwise the error is `internal`, because only an Engine fault produces that state. @@ -165,6 +169,8 @@ The `store` functions are in place before the preludes on the owner's instructio The Engine starts every Lua block as a coroutine. A call that waits, such as `models.infer`, is a short Lua function that yields a table. The Engine parses the table into a typed request, and answers it at once, or issues an effect and records what the chain waits on. Later it resumes the coroutine with an `(ok, result)` pair. A yield from author code fails the block with the message "scripts may not yield directly". The functions that yield are written in Lua, because a yield across the C boundary fails. +Each block is its own coroutine because the loop over a section's blocks is Rust. The scheduler starts a block, and when the block's coroutine ends, it decides what follows: the section's next block, the end of the chain, or a jump. A coroutine ends when its function returns, so a loop in Rust needs one coroutine for each block. A loop in Lua could run a whole section in one coroutine, and `require` runs a library's blocks that way, because it starts inside a running block, where a Rust function cannot call Lua that yields. The section loop stays in Rust. The owner's rule: "key rules we keep in Rust". The owner's view of the Lua loop: "I don't see the point of putting it in Lua". One coroutine for each block was not a choice between the two forms. The owner's words: "It just kind of happened that way." + One thread runs a whole run. A run needs only one, because every Lua block executes fast. ### The Engine uses mlua's synchronous API on Lua 5.5 @@ -185,6 +191,8 @@ The Engine resumes a block with a success or a failure. Every answer variant is The trampoline is Lua because a Rust function can yield only with mlua's `async` feature, and its call to a Lua function that yields fails. In the wider division, Lua in the prompt decides policy, such as compaction, and Rust runs the mechanics ([Model calls and conversations](models-and-conversations.md)). +The loop's rules are in Rust because the loop works on the message list, and the list is a Rust object. A model's reply reaches the step function as a value that the trampoline passes along and cannot read, and the step appends the records itself, so the Engine can keep data in the list that Lua never reads. The owner's reason: "we need to be able to manipulate the messages object. The messages object is in Rust". The owner expects to need this for requests to OpenAI endpoints and to Anthropic endpoints, which is planned work, and says of what the Engine then does with the list: "Lua can't see it." The Rust state machine also meets the owner's request that "the rules are unit-testable without a VM". The other calls with rules of their own, `tasks.fanout`, the `tasks` waits, and `require`, are Lua, and they work on values that Lua holds: task handles, results, and section code. + ### A chain reads everything about its prompt from the prompt it runs The Engine reads a chain's prompt from the chain. A section lookup, `sys.section_count`, the round cap of `models.loop`, and the file name in an error each come from the prompt that the chain runs. A `call` chain and a task keep the prompt and the store of the chain that started them. @@ -214,6 +222,10 @@ A caller changes a limit by assigning a field of `RunLimits::default()` and pass The fields are public because `RunLimits` is a plain `Copy` value whose only invariant is in its `NonZero` types. The call depth cap is a constant of the Engine with the value 8, and a deeper `call`, `execute`, or task fails with the code `call_depth_exceeded`. Every prompt of a run counts against the run's one set of limits: a task that an executed prompt spawns takes a slot under `max_concurrency` and counts toward `max_idle_tasks`, as a task of the run's own prompt does. +The cap is 8 because that is more depth than the owner expects a prompt to need. The owner compares it with Cursor, which the owner recalls as allowing about five levels, a figure that nobody has checked, and says of nesting there: "I've only ever gone to three." The cap is a constant, where the other limits are fields of `RunLimits`, because no Host has needed to change it. The owner's reason: "I just don't see a need for it yet." A field for it is a small change, in the owner's words: "it's trivial to make it configurable". + +The default values of the limits are arbitrary, and so is the interval of the cancel hook, 10,000 instructions. No measurement chose a number, and the owner did not pick them. The owner's rule is that each resource has a limit, and the value is secondary. The owner's view of the values: "8 sounds good", "64 meg sounds about right", and "10,000 seems alright". A value may change freely, because, in the owner's words, "this thing's not in production yet". + ### A Lua block may run any number of instructions, and a hook polls the cancel flag Each Lua VM has a hook that fires every 10,000 instructions and reads the run's cancel flag, and a set flag aborts the block. An endless loop in a prompt therefore runs until the caller cancels the run. The owner's reason: "If the user codes an infinite loop that's their problem". @@ -226,7 +238,11 @@ The Engine's quotas are both on `log`: a count of events and a count of bytes. A `Error` is a struct in `runvil-types` with the public fields `code`, `message`, `prose`, `at`, and `facts`. `ErrorCode` is an enum of codes, each with a number and a tag such as `lua_runtime` (201). The hundreds digit names the family: 1xx parse, 2xx Lua, 3xx tasks, 4xx model, 5xx tools, 6xx store, 7xx run, and 8xx caller. The enum's docs add: "A number is never reused." The root `AGENTS.md` makes `Error` the one error type of the Engine and Harness crates, with `VfsError` as the main exception. -`Error`, `ErrorCode`, and `ErrorFact` omit the `#[non_exhaustive]` attribute, so a code that the Engine adds breaks the build of a Host whose `match` on `ErrorCode` names every variant. +The crates share one `Error` because they once had dozens of error types, and every one that a facade exported was another public item. One record made the code easier to read and to change, and it keeps the public surface small. The owner's reason: "There was a proliferation of error types and unifying them into one made the code much easier to understand and easier to work on". On the surface: "one is better than 52 in this case". The 52 is the owner's count of the error types before the change and is unchecked: a search of the code as it was on 2026-11-01 finds about 40 by their derives and impls. The `runvil` facade lists 61 types today. The owner limits the rule to this API: "for unified public harness and engine API, it's better to just have one error", and of the rule elsewhere, "that might not be generally true". + +The owner has made no decision about how the codes are grouped. `call_depth_exceeded` is 204, in the Lua family. Before the codes had numbers, a depth failure was reported under the same kind as the Lua log quotas, which is the likely reason it has the number after `lua_quota`. The grouping and the numbers may change while Runvil has no users. The owner's reason: "there's no users that are comparing error codes yet, so it's easy to change". A code that moves to another family takes a new number, so a move keeps the rule that a number is never reused. + +`Error`, `ErrorCode`, and `ErrorFact` omit the `#[non_exhaustive]` attribute, so a code that the Engine adds breaks the build of a Host whose `match` on `ErrorCode` names every variant. No decision closed the three types. The owner's rule of 2026-10-15 keeps `Step`, `Effect`, and `EffectAnswer` closed and marks every other facade type `#[non_exhaustive]`, and the error types arrived after it without the attribute. The owner's words: "it just happened", and "we should probably mark the type as non-exhaustive". Adding the attribute is planned work. ### An error's `message` includes each cause once, and its `prose` is the text a model reads @@ -289,9 +305,10 @@ The owner's goal: "I want as many internal crates as possible and I want maximum - **An `execute` that returns at once.** A Lua `execute_async` call that starts another prompt as a task and returns its handle. Today `execute` runs a listed prompt as a blocking child chain, and its caller waits for the result. - **Replay.** Harness code that runs a recorded run a second time and compares the records of the two runs. Today the Engine attaches a `Provenance` to each effect and event, and `Effect::record` and `EffectAnswer::record` return the JSON that a run log stores. -- **The store as a tool.** The `store` API as a tool, which would move the `Vfs` effect out of the Engine. Today the Engine issues a `Vfs` effect for each `store.*` call. +- **A tool's file operations as `Vfs` effects.** A `Vfs` effect for each file operation of a tool, on the file system the caller gave the run, under the call's identity ([Files and the VFS](files-and-the-vfs.md)). Today a `Vfs` effect is one `store` operation, and a `ToolCall` effect holds the call's file access. - **The round id on `ModelTurnFailed`.** A round id in the `ModelTurnFailed` event, so that a Host can drop exactly the failed round's streamed pieces. Today the Engine writes the round id in a round's thinking, reply, and tool-call events. - **Bounds on JSON conversion.** A size budget at every site that converts a Lua table. Today `json.encode` and `var` writes have a size budget, other sites in the Lua crate convert a table of any size, and one encode runs as a single Rust callback between cancel polls. +- **`#[non_exhaustive]` on the error types.** The attribute on `ErrorCode`, and on `Error` and `ErrorFact` if the owner extends it to them, so that a new code leaves a Host's build intact. Today the three types are closed, and at least one function outside `runvil-types`, `kind_of` in `runvil-lua`, names every code with no catch-all arm, so it would need one or a move into `runvil-types`. ## 10. Open questions @@ -299,18 +316,12 @@ Each question asks for the reason behind a part of the design. **The run** -1. Why does `Run::new` always succeed, while the first `step` makes the start checks? -2. Why is the cancel a flag in `RunParams`, where `Run` could have a method for it? -3. Why does a prompt that declines its task complete, while an unmet requirement ends the run with an error? +1. Why is the cancel a flag in `RunParams`, where `Run` could have a method for it? -**Lua and limits** + **Status: unconfirmed.** The owner does not remember the reason and did not design the cancel system. The commit that removed `Run::cancel` and `Run::cancel_handle` on 2026-10-31 (`b00e53bc`) says that the caller cancels through the flag, and it gives no reason for choosing the flag over a method. The text below is a reconstruction from the code, written on 2026-11-14. It explains the design, and it may differ from the reason the design was chosen. -4. Why does each Lua block run as its own coroutine, when one coroutine could run a whole section? -5. Why is `models.loop` the one suspending call whose rules run in Rust? -6. Why is the call depth cap 8, and why is `call_depth_exceeded` in the Lua family of codes? -7. Why are the defaults 8 concurrent tasks, 64 MiB of Lua memory, and 1024 log events, and why does the cancel hook fire every 10,000 instructions? + **What the code shows.** `Run::step` holds the run until it returns, so a method on `Run` cannot be called while a step runs Lua. The caller makes the flag before the run exists, and the Harness watches the same flag while it prepares the run. A chain inside the run stops one task with `tasks.cancel`, which is a request and not a flag. -**Errors and the surface** + **The likely reason.** A cancel comes from outside the run, often from another thread and sometimes during a step, so only a shared flag can deliver it. The two methods were then second routes to the same flag. -8. Why do all Engine and Harness crates report failures as one `Error` type? -9. Why are `Error`, `ErrorCode`, and `ErrorFact` closed, when a new code then breaks the build of a Host whose `match` on `ErrorCode` names every variant? + **Still open.** Whether that is the reason, and whether `CancelHandle::child()` has a use now that a task is canceled with `tasks.cancel`. diff --git a/decisions/files-and-the-vfs.md b/decisions/files-and-the-vfs.md index f4c0c0680..c2b50ad96 100644 --- a/decisions/files-and-the-vfs.md +++ b/decisions/files-and-the-vfs.md @@ -10,6 +10,10 @@ The Engine installs a `store` table in the Lua VM of every section entry. The pr The owner's reason: "Store is always present, its a core feature of the Runvil language because its the way to move data between sections and handle fanout." +The store holds files because a prompt is often a pipeline: a stage runs inference over the files of the stage before it and writes new files. The owner's description: "there's files created at every stage of the pipeline". The files stay for the whole run so that a person can follow the data from stage to stage. The owner's reason: "we want those files to persist during the run so that they can be inspected". The owner's convention for a prompt author is to write a new file at each stage and leave the earlier one as it is: "You want to create a new one from an old one, and this way you can inspect the data flow." The store leaves the convention to the author: `write` replaces a file, and `append` and `str_replace` change one. The files are text because, in the owner's words, "Markdown is the language of AI". State has to live outside Lua, because the Engine discards a section's VM when the section ends, and `var` passes values to the next section in a form that converts as JSON. The owner's reason for files beside `var`: "JSON's unsatisfying because it's not Markdown". + +The inspection that the owner means happens during the run, at a breakpoint or at any stage. With the evidence in file A and the inference over it in file B, "if we get a breakpoint now we can see A and B", where a B written as a series of edits to A would leave only the event log to show the earlier text. The owner's reason: "Having it in the store means there's a blob there." No debugger exists yet: one that rebuilds each store from the run's records is planned work, and today the record is the only view of a store from outside the run. + ### The `store` table has a fixed set of functions, and a prompt composes the rest The functions are `write`, `append`, `read`, `read_numbered`, `str_replace`, `delete`, `glob`, and `exists`. `store.str_replace` replaces an anchor text that must occur exactly once, because an edit by anchor is the pattern that works for models. `store.delete` succeeds on an absent path. @@ -60,7 +64,7 @@ A table fixed at construction makes routing immutable and a handle cheap to clon Every method of `Vfs` and `VfsAccess` is a blocking call, file content is bytes, and `Access` adds the text operations. A `VfsRef` locks its backend for each call, so a backend must be `Send` and may leave locking to the handle. -The traits are synchronous because the backends are synchronous by nature: memory and the standard library's file system calls. Lua is synchronous as well, and that is beside the point. An async VFS is planned work. +The traits are synchronous because the backends are synchronous by nature: memory and the standard library's file system calls. Lua is synchronous as well, and that is beside the point. The owner's reason: "at the end of the day, the operating system calls are synchronous. So we keep the storage operations synchronous." `Access` is synchronous for the same reason. ## 3. Real and virtual roots @@ -76,6 +80,8 @@ The Engine makes a store for each run, and the store starts empty. Every chain t The owner's reason: "Every prompt starts with a, a memory store that's completely empty. And that's the only type of store there is. And it doesn't map to any file system path in the virtual file system." With no way in from outside, a run's result depends only on its prompt, its arguments, and the answers to its effects. +The owner holds the two halves of this rule with different confidence. Data enters a run as its arguments and leaves as its result, and the owner is sure of that: "we don't want to use the store as a way of getting data in and out of the prompt from the host", and "Using the argument list and using the return value instead of the input and output files, that was definitely the right move." Keeping the store out of reach of a model's file tools is less certain. The owner made that choice for `execute`: "The problem with execute is that the prompt that we're calling needs to map itself into the virtual file system, and I couldn't think of a place to put it." The owner's view of the choice on 2026-11-15: "it was a big simplification that was useful for execute. I'm not sure that it was the right one." A prompt can give a model access to its store today with an adhoc tool whose handler calls a `store` function ([Tools and Packs](tools-and-packs.md)). That is no exception to the rule that a tool sees no file of the store: the handler is the prompt's own Lua and makes an ordinary `store` call on its chain's store, where the file access of a Pack tool reaches the handle alone. The owner does not want that to become the way a model reaches the store, and wants no second set of tools for it: "There's no reason to make a separate set of store tools. That just burdens the model." The owner's rule, stated on 2026-11-15, is that a model that reaches the store uses the file tools it already has, because "We want as few tools as possible" and "Models already know how to use Bash." That would put the store inside the file system that a tool sees, which the design in this section rules out, so it is a change that nobody has designed yet. + ### Each `execute` gives the prompt it runs a new, empty store The Engine makes a store for the chain of each `execute` ([The prompt language](prompt-language.md)). The store is empty and has a claims table of its own. The executed prompt's `call` chains and tasks share it, and a prompt that the child executes in turn gets another. The caller and the child see none of each other's store files: one path in the two stores is two files, and the caller finds no file of the child after the `execute` returns. A second `execute` of the same prompt starts with an empty store again. @@ -90,6 +96,12 @@ The rule is the owner's, quoted in the entry "A store call is one `Access` call Those operations act on the link itself because a `remove` that followed the link would delete the link's target. `RealBackend` is part of `runvil-vfs` itself: the file system calls it uses belong to the standard library, so the backend fits the crate's zero-dependency rule ([Crates, build, and CI](https://github.com/cppalliance/runvil-design/blob/master/decisions/crates-build-and-ci.md)). +### A mount is for storage that answers quickly, and a remote system is a tool's job + +A Host may mount any backend, a slow one included. Every file operation holds its run until the backend returns, so a run that works on a network drive, or in a folder that a cloud service syncs, waits for that storage, and its stop and its cancel wait with it. A feature that needs a timeout, a retry, a sign-in, or a rule for storage that goes away is a Pack's tool, which the Harness can drop while it waits ([Tools and Packs](tools-and-packs.md)). + +The owner's rule for slow storage: "we should allow it, but if the performance suffers, then it suffers." For a remote system: "If you want to access those remote systems, then you need to do it through MCP". The tool then decides, in the owner's words, "what do you do if the volume goes offline, like in the middle of it". + ## 4. What a run may read and write ### Each handle has one policy, which answers Allow, Deny, or Ask @@ -144,6 +156,12 @@ The Engine forks an identity for each Pack tool call and passes its `Access`, ro When an operation inside a tool call conflicts, the `Access` returns `VfsError::Conflict` to the Pack, which decides how to answer the call. For the `std` Pack, a library Plugin, the loader passes the conflict on as a file error of the C contract, and the Pack converts it into a sentence that tells the model to call the tool again. In the shell of the `bash` Pack the same file error fails the command that read the file, and the model reads the reason in the command's output. The Engine resumes the chain with the Pack's answer. The Engine ends the run only for a conflict in a `store` call: the fatal rule applies only to answers of `Effect::Vfs`. +### A tool's file operations will be effects, and today a tool performs them itself + +Today a tool performs each file operation itself, through the `Access` of its call or through the file functions of the C contract, and the run's record holds none of them. The owner has decided that each one becomes an effect: the tool asks, the Engine issues a `Vfs` effect under the call's identity, the Harness performs and records it, and the tool goes on with the answer. The owner's rule: "every VFS operation that's performed by a tool has to turn into an effect in the engine." + +The reason is the record. The owner's questions about the present design: "how's replay gonna work? How are we gonna do replay? How are we gonna handle debugging?" One ordered record of a run exists only if the Harness sees every effect and every answer ([The Harness and the Host API](harness-and-host.md)), and a tool's file operations are the part of a run that it misses today. The change is still to be built (see Planned work). Until it is, the ways a tool reaches files stay as they are, and the next one arrives in the new form. + ## 6. Errors ### `VfsError` is the one error type, and each variant has a stable tag @@ -162,10 +180,12 @@ An error has three readers: Rust code matches the variant, Lua code branches on A `store` function yields its operation, and the Engine issues one `Effect::Vfs` for it ([The Engine](engine.md)). The Harness performs the effect at once, before it waits for any other effect. The Engine reports an event for each call, such as `VfsWriteSucceeded`, which names the section and omits the path and the store. The run's record holds every store operation: each `Vfs` effect record with the id of its store and its operation, and each answer record with its outcome, in order. The record is the only view of a store outside its run, and the records of one store are enough to rebuild it. -The Harness performs the call inline because the store is memory: a `Vfs` effect is one operation that touches no disk, so it has no future for the effect loop to wait on. The Harness performs the operation through the effect's view and holds no way to the store between effects. It answers every `Vfs` effect of a step this way and then steps the run once. VFS operations from different chains run one at a time, in the order the Engine issues them. +The Harness performs the call inline because file operations are synchronous by design: the storage underneath is synchronous, so a `Vfs` effect has no future for the effect loop to wait on, and the run waits for the operation. The owner's reason: "all file I/O synchronizes the, the harness, and that's in line with our design." The Harness performs the operation through the effect's view and holds no way to the store between effects. It answers every `Vfs` effect of a step this way and then steps the run once. VFS operations from different chains run one at a time, in the order the Engine issues them. Store operations are effects for the owner's reason: "We want to be able to debug prompts and replay them and see how the contents of the store evolves". The record holds every store call with its arguments and its outcome, the Harness sees each call before it happens, and a replay, which is planned work, would issue the same effects again. +The `store` functions stay in the Engine. A plan to serve them from a tool is dropped. It was a restructuring of the code to make the Engine smaller, and in the owner's words, "This has nothing to do with capabilities." The owner's verdict on the plan: "That turned out to be not a good idea". Turning the store into a tool was more work, in the owner's words "to turn it into a tool and to create all the rigmarole", and the store is part of the language: "It just needs to be a language feature." The owner's rule is that a feature that is deeply part of the language stays in the Engine. + ### A `Vfs` effect and its record name the store by a chain id `Effect::Vfs` has a `store` field, a `ChainId`, and the effect's record holds it beside the operation, as in `{"Vfs":{"store":"0","op":{...}}}`. The id `0`, the root chain's, names the store that the run starts with. A store that an `execute` made has the id of the executed prompt's chain, such as `0.0`, and every operation on that store has this id, whichever chain of the executed prompt made the call. @@ -180,10 +200,8 @@ A run has one way in, its arguments, and one way out, its result. The owner's re ## 8. Planned work -- **The store as a tool.** The `store` functions would become calls of a tool, which would remove the `Vfs` effect. Today each `store` call is one `Vfs` effect. -- **An async VFS.** The backend traits would become async, which would work well with Turso and with Bashkit, and the step follows the store tool. Today every method of `Vfs` and `VfsAccess` is a blocking call, and the shell of the `bash` Pack ships on the blocking calls. -- **File changes for a Plugin's tools.** Functions of the C contract with which a tool writes, deletes, and renames a run's files. Contract 0.4 has file functions that stat, list, and read, so the Write, StrReplace, and Delete tools of `std` are stubs and the shell of `bash` refuses each change, while `Access` has the operations and a Rust Pack can call them ([Tools and Packs](tools-and-packs.md)). -- **A database mount.** A mount would show an agent's run database as files, once the VFS is async. The backends that ship are `MemoryBackend` and `RealBackend`. +- **A tool's file operations as effects.** Each file operation of a tool, a read as well as a change, as a `Vfs` effect that the Engine issues under the call's identity and the Harness performs and records. A tool call becomes an async function whose file methods return futures: the tool asks, its call waits, and a later step of the call receives the answer. The Write, StrReplace, and Delete tools of `std` and the writes of the `bash` shell arrive with it. Today contract 0.4 has file functions that stat, list, and read, each of which returns when its operation is done, a Rust Pack calls the `Access` of its call, and the record holds none of these operations ([Tools and Packs](tools-and-packs.md)). +- **A database mount.** A mount would show an agent's run database as files. Its backend is synchronous like every other, so a backend over a database client with an async interface drives that client on a thread of its own. The backends that ship are `MemoryBackend` and `RealBackend`. - **Replay.** Replay would read a run's records back into a run, and a debugger would rebuild each store of a run from the same records, at any step. Today the Harness records each `Vfs` effect and its answer. - **Glob across mounts.** A glob would also search the backends mounted below the mount that matches its pattern. Today a glob runs inside that one mount and skips a backend mounted below it. @@ -193,7 +211,6 @@ Each question asks for the reason behind a part of the design. **The store API** -1. Why does a run store its bulk state as files? 2. Why does `store.delete` succeed on an absent path? 3. Why do store calls report one pair of event kinds for each operation? diff --git a/decisions/harness-and-host.md b/decisions/harness-and-host.md index 9689470a9..a9d5d499a 100644 --- a/decisions/harness-and-host.md +++ b/decisions/harness-and-host.md @@ -118,13 +118,13 @@ The run's first step checks the run's requirements. For a shortfall, such as a P The effect loop polls the future of every effect in flight inside the one future that `Harness::run` returned, on whichever thread polls that future. -The design sets a rule for every performer, which is a broker, a Pack, or a timer: return to the poll quickly, and send blocking work to the Host's own runtime. A performer that blocks stalls every other effect of the run, and the run's stop and cancel with them. +The design sets a rule for every performer, which is a broker, a Pack, or a timer: return to the poll quickly, and send blocking work to the Host's own runtime. A performer that blocks stalls every other effect of the run, and the run's stop and cancel with them. The rule covers a performer's own work, such as a network request or a long computation. A file operation is synchronous by design, and the run waits for each one ([Files and the VFS](files-and-the-vfs.md)). ### The Harness answers each `Vfs` effect inline, on the thread that polls the run A `Vfs` effect is one operation on a store of the run. A run has the store that it starts with, and one more for each `execute` ([Files and the VFS](files-and-the-vfs.md)). The loop performs the operation itself and resumes the run before it waits again. Store operations from different chains run one at a time, in the order the Engine issued them. The Harness reaches a run's store only to perform the one operation of a `Vfs` effect. It puts nothing in the store before a run and reads nothing from it after. -The loop performs the operation itself because the store is memory, so the call touches no disk and has nothing to wait on. The owner's rule: "Every prompt starts with a, a memory store that's completely empty. And that's the only type of store there is. And it doesn't map to any file system path in the virtual file system." With no way in from outside, a run's result depends only on its prompt, its arguments, and its answers. +The loop performs the operation itself because file operations are synchronous by design, so the call has nothing for the loop to wait on. The owner's reason: "all file I/O synchronizes the, the harness, and that's in line with our design. Our whole design of Runvil is a single-threaded. It's cooperative asynchrony." A store is memory. The owner's rule: "Every prompt starts with a, a memory store that's completely empty. And that's the only type of store there is. And it doesn't map to any file system path in the virtual file system." With no way in from outside, a run's result depends only on its prompt, its arguments, and its answers. ### The loop answers `Dropped` for a performer that panics diff --git a/decisions/tasks-and-fanout.md b/decisions/tasks-and-fanout.md index 461596dab..0eeddeb24 100644 --- a/decisions/tasks-and-fanout.md +++ b/decisions/tasks-and-fanout.md @@ -94,6 +94,8 @@ The form exists only in the Lua of `tasks.fanout`: both forms of the call yield One limit covers the whole run. A limit inside each fanout would multiply when fanouts nest, since 8 arms that each run 8 arms are 64 live tasks, and it would leave tasks from `tasks.spawn` unbounded. The Harness has a separate limit of 10 Pack tool calls in flight ([Tools and Packs](tools-and-packs.md)), because one shared limit would couple the task limit and the call limit. +The value 8 is arbitrary, here and for `max_idle_tasks` ([The Engine](engine.md)). No measurement chose it, and the owner did not pick it. The owner's rule is that each resource has a limit, and the value is secondary. The owner's view of the value: "8 sounds good". A value may change freely, because, in the owner's words, "this thing's not in production yet". + ### A spawned task starts at admission, in spawn order, after the chains that resume A spawn forks the file identity, assigns the task id, and queues the chain. Admission is the moment the scheduler starts a queued chain. The chain gets its Lua VM then, and until then `tasks.status` reports `blocked` as `queued`. The scheduler runs an admission pass each time its queue of ready chains is empty. The pass admits chains that resume from a wait first, then spawned chains in spawn order. @@ -118,6 +120,8 @@ A `call` child, an `execute` child, and a spawned task each run one level deeper A fanout arm counts as a level, so the depth of a recursion accumulates across a fanout, where it would otherwise start again in each arm. An `execute` counts as a level too, so the cap also ends a recursion between prompts that execute each other ([The prompt language](prompt-language.md)). +The cap is 8 because that is more depth than the owner expects a prompt to need ([The Engine](engine.md)). The owner compares it with Cursor, which the owner recalls as allowing about five levels, a figure that nobody has checked, and says of nesting there: "I've only ever gone to three." The cap is a constant, where the other limits are fields of `RunLimits`, because no Host has needed to change it. The owner's reason: "I just don't see a need for it yet." + ## 5. Determinism ### The same seed, start time, and answers produce the same run @@ -162,7 +166,7 @@ A task can therefore return a result and remain open for follow-ups with its con `RunLimits::max_idle_tasks` is 8 by default. A reply that makes a ninth idle task closes another: the one idle longest among those whose own tasks have all ended, or the one idle longest of all. The closed task ends as `done` with its latest reply as its result. -The cap bounds memory: an idle task still has its Lua VM, which the Engine is unable to rebuild from the task's conversation. The closed task ends as `done` because its owner is still alive and can still take that reply, while `abandoned` means that the owner ended. +The cap bounds memory: an idle task still has its Lua VM, which the Engine is unable to rebuild from the task's conversation. The closed task ends as `done` because its owner is still alive and can still take that reply, while `abandoned` means that the owner ended. The value 8 is arbitrary, as it is for `max_concurrency`. ## 7. Planned work @@ -184,4 +188,3 @@ Each question asks for the reason behind a part of the design. 3. Why does every task have an inbox? 4. Why is the model-first form limited to `tasks.fanout`? -5. Why is 8 the value of `max_concurrency`, of `max_idle_tasks`, and of the depth cap? diff --git a/decisions/tools-and-packs.md b/decisions/tools-and-packs.md index dd8d6a9b9..a723cb1df 100644 --- a/decisions/tools-and-packs.md +++ b/decisions/tools-and-packs.md @@ -288,15 +288,21 @@ The owner's rule: "The tool can't keep the access. ... it has to give it up, aft ### The rules that every `Pack::call` follows -1. Return to the poll quickly. A call sends blocking or CPU-heavy work to the Host's runtime, because the Harness polls every effect of a run on the same task. +1. Return to the poll quickly. A call sends blocking or CPU-heavy work to the Host's runtime, because the Harness polls every effect of a run on the same task. A file operation is the exception: it is synchronous by design, and the run waits for it. 2. Report failure as an `Error`. The Harness answers a panicking call as `Dropped` and logs the panic. 3. Mark as untrusted any output that embeds data an attacker can influence. 4. Expect to be dropped. The Harness drops the call's future on a stop, on a cancel, and when the calling task ends. 5. Finish independently of the run's other calls. A call that waits for a sibling queued behind the limit of 10 can stall the run. +### A tool keeps nothing from one call that changes what a later call returns + +A tool's result depends on the call's arguments, the run's files, and what the tool reaches outside the run. Whatever one call would leave for a later call goes into the run's files, and the record holds those once a tool's file operations are effects ([Files and the VFS](files-and-the-vfs.md)). A connection or a client that a Pack's factory shares between runs changes no result, so the rule leaves it alone. + +The owner's rule: "Tools are not allowed to have internal states, and if they do, they have to be recorded." The reason is replay, which feeds each recorded tool result back to the Engine and runs no tool. The owner's words: "On a replay, the, the shell tool is not invoked. The shell tool never executes." A run that went on live after a replay would call a tool that holds none of the state its earlier calls left. The shell of the `bash` Pack is the one shipped tool that keeps such state today, and the owner has decided that each of its calls gets a shell of its own (see Planned work). + ### File operations through the access are synchronous -A Rust Pack's tool reads and writes files through the access of its `ToolContext`, and each operation runs inside the call. The reason is that the Harness is independent of any particular async runtime, so each part of the context has to be independent of tokio. The shipped Rust Packs, `web` and `mcp`, leave the access unused. The shipped tools that touch files are in the library Plugins `std` and `bashkit`, and they read through the file functions of the contract, which the loader answers from the same access. +A Rust Pack's tool reads and writes files through the access of its `ToolContext`, and each operation runs inside the call and holds the run until it returns. File operations are synchronous by design, because the storage underneath is synchronous ([Files and the VFS](files-and-the-vfs.md)). The Harness is also independent of any particular async runtime, so each part of the context has to be independent of tokio. The shipped Rust Packs, `web` and `mcp`, leave the access unused. The shipped tools that touch files are in the library Plugins `std` and `bashkit`, and they read through the file functions of the contract, which the loader answers from the same access. A long file job yields so that the Harness can cancel it. Grep, in the `std` library, ends its step after every 32 files or directories, or after 2 MiB read, so a stop or a cancel drops a long search between two steps. @@ -358,7 +364,7 @@ The Pack copies Cursor's text because the model was trained against that exact t `bash` is the Pack of a library Plugin. The bashkit Plugin has a repository of its own, `runvil-plugin-bashkit`, and is written against `runvil-plugin-sdk`. It reports the name `bashkit` and inserts one Pack, `runvil/bash`. The Pack has one tool, `bash/shell`, and the model sees it as `Shell`, which is Cursor's name for its shell tool. The definition is Cursor's, with a recorded list of edits. Workshop loads the Plugin's library from the Plugin directory, beside the library of `std` ([Workshop: how the app is built](https://github.com/cppalliance/runvil-design/blob/master/decisions/workshop-app.md)). The built-in chat prompt requires `bash` under `uses:` and offers it. -The shell is a bash interpreter from the `bashkit` crate, and it runs inside the run. Every command is built into bashkit, so the shell works without a child process and without a network. A run has one session, which the first call makes, and the working directory, variables, and functions that one command leaves are there for the next call. A call that the Host abandons takes the shell with it, and the next call starts a fresh session, because a script that is cut off partway may leave the shell in a state that an ordinary command would avoid. A command ends after 30 seconds, or after the `block_until_ms` of its call when that is less. The answer is the exit code and the output, marked untrusted. +The shell is a bash interpreter from the `bashkit` crate, and it runs inside the run. Every command is built into bashkit, so the shell works without a child process and without a network. A run has one session, which the first call makes, and the working directory, variables, and functions that one command leaves are there for the next call. A call that the Host abandons takes the shell with it, and the next call starts a fresh session, because a script that is cut off partway may leave the shell in a state that an ordinary command would avoid. The owner has decided that each call gets a shell of its own (see Planned work). A command ends after 30 seconds, or after the `block_until_ms` of its call when that is less. The answer is the exit code and the output, marked untrusted. The shell's files are the run's files. The shell lives across calls, and a tool call lends its files only while one of its steps runs, so the call that runs a script performs each of the shell's reads through the contract's file functions. Every read goes through the Host, so the run's policy applies. A step ends after 32 reads, as a Grep step ends after 32 files, so the Host can abandon a script between two steps. A command that alters a file fails with one fixed sentence, because contract 0.4 reads only. The Pack's plan calls this the first of two stages, and the second stage adds writing. @@ -411,11 +417,13 @@ The Pack uses `rmcp`'s own HTTP client, which refuses redirects, so the client s Each of these items is still to be built. - **One Plugin API.** `plugin-web` and `plugin-mcp` written against the C contract and inserted with `insert_plugin`, so that a Pack compiled into the Host goes through the same contract as a Pack from a library and the two `install` functions, which is what both Plugins are, go away. The contract first needs what the two Packs use and contract 0.4 lacks: for `mcp`, a configuration for its list of servers, the call's origin, and the `describes_tools` flag, for `web`, the Host's search provider, and for both, the Host's runtime handle, a Pack inserted as unavailable with a reason, a call that waits on work outside its step, and error causes. -- **File changes through the C contract.** Functions with which a Plugin's tool writes, deletes, and renames the run's files, where contract 0.4 has `file_stat`, `file_list`, and `file_read`. The `std` tools Write, StrReplace, and Delete and the `bash` shell wait for them, and the Rust API has the change operations on the call's file access, which the shipped Rust Packs leave unused. -- **The `std` tools that are stubs.** Write, StrReplace, Delete, and Glob, each of which answers a fixed text that says the tool is missing from this build. The first three wait for the file changes above. +- **File operations as effects.** A tool call as an async function whose file methods return futures, so that each file operation of a tool, a read as well as a change, is an effect that the Harness records ([Files and the VFS](files-and-the-vfs.md)). A file function of the contract then asks for an operation, and a later step of the call receives the answer. The `std` tools Write, StrReplace, and Delete and the writes of the `bash` shell arrive with it. Today contract 0.4 has `file_stat`, `file_list`, and `file_read`, each of which returns when its operation is done, and the Rust API has the change operations on the call's file access, which the shipped Rust Packs leave unused. +- **The `std` tools that are stubs.** Write, StrReplace, Delete, and Glob, each of which answers a fixed text that says the tool is missing from this build. The first three wait for the file operations above. - **Approval by a person.** The step that asks the operator to approve a file change. When the run's policy answers `Ask`, the file system refuses the operation with `VfsError::ApprovalRequired` and a reason, which a library Pack's tool receives as a denied file error with the same reason, and a run under Workshop cannot reach that error, because the shipped tools read files only and Workshop's runs use `AllowAll`. - **Ignore files.** Applying `.gitignore`, so that Grep skips a folder such as `target/` and spends its budget of 100,000 files elsewhere. Walks skip `.git` and names that contain a control character. -- **Writing and a thread of its own for the `bash` shell.** Shell commands that alter the run's files, which wait for the file changes above, and bash on a thread of the Plugin's own, with a wake function in the contract. Bash runs inside the steps of its call, so a heavy script holds its step, and a stop with it, until the script ends or reaches one of bashkit's limits, and while a script sleeps the Host steps the call with nothing to do. +- **A shell for each call.** Each `bash/shell` call with a new shell that starts at the root of the run's files, so the working directory, variables, and functions of one call end with it. The owner's reason: "Its the easiest to implement and doesn't expand the API surface." A shell that saves its state to a file of the run and loads it at its next call is a later step. Today a run has one session, which every call of the run shares. +- **Writing for the `bash` shell.** Shell commands that alter the run's files, which wait for the file operations above. +- **Undecided: a thread of its own for bash.** Bash on a thread of the Plugin's own, with a wake function in the contract. Bash runs inside the steps of its call, so a heavy script holds its step, and a stop with it, until the script ends or reaches one of bashkit's limits, and while a script sleeps the Host steps the call with nothing to do. The owner has yet to decide on it. - **Subagent tools.** The tools of `runvil/subagents`, and the wrapping of text that one model writes for another. The Pack only reserves its name. - **MCP in the Dynamic Set.** The `mcp` Pack rendering its servers' tools into the Dynamic Set, which retires its own two tools, along with local servers and OAuth. The Pack offers its own two tools, for remote servers. - **Filters and labels.** An offer narrowed by a hint such as read-only, and labels on `ToolInfo`, modeled on MCP's, for a future Ask mode. An offer names each tool or Pack, and the `ToolInfo` flags are `structured_output`, `survives_stop`, `describes_tools`, and `model_only_call`. From b61a7e812d0f107810c734b935e0a353c2d7b5ea Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Tue, 17 Nov 2026 18:22:01 -0800 Subject: [PATCH 02/23] Add the plan for tool file operations as effects The plan sends each file operation of a tool through the Engine as an effect that the Harness performs and records. It gives the `store` calls of Lua and the file operations of a tool one list of operations, and it moves the Plugin contract to 0.5. The file holds the decisions, the steps for four repositories, and the order of the work. Plan: /plan/2026-11-16-1-tool-file-effects.plan.md --- plan/2026-11-16-1-tool-file-effects.plan.md | 455 ++++++++++++++++++++ 1 file changed, 455 insertions(+) create mode 100644 plan/2026-11-16-1-tool-file-effects.plan.md diff --git a/plan/2026-11-16-1-tool-file-effects.plan.md b/plan/2026-11-16-1-tool-file-effects.plan.md new file mode 100644 index 000000000..6a33e14ae --- /dev/null +++ b/plan/2026-11-16-1-tool-file-effects.plan.md @@ -0,0 +1,455 @@ +--- +name: Tool File Effects +overview: Make every file operation of a tool an effect that the Harness performs and records, with a tool call as an async function whose file methods return futures. Lua's store calls and a tool's file operations share one list of operations and one kind of effect. The conflict check applies to a store alone, and the Host's files have none. The contract moves to 0.5, std gets Write, StrReplace, and Delete, and the bash shell gets a shell for each call and can change files. +todos: + - id: plan-copy + content: "Package 0: copy this plan to runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md, commit it alone, and push" + status: pending + - id: bash-shell-per-call + content: "bashkit: give each Shell call a new shell, remove the session, and update shell.json, EDITS.md, the docs, and the tests (Step 1)" + status: pending + - id: contract-reads + content: "plugin-api: contract 0.5 with a request and an answer for stat, list, and read; SDK file methods as futures; fake Host that answers across steps; header, C layout, example, README (Step 2)" + status: pending + - id: contract-changes + content: "plugin-api: write, append, mkdir, remove, rename, copy; the changes-files flag; two new error kinds; a test tree that calls can change (Step 3)" + status: pending + - id: contract-stop + content: "Push plugin-api to origin. The owner merges it into cppalliance/runvil-plugin-api right after Phase 2; note the merged commit for the pins" + status: pending + - id: vfs-op-list + content: "harness: one VfsOp with fifteen operations, VfsOutcome, and Access::perform in runvil-vfs, moved from runvil-lua with the store's line logic (Step 4)" + status: pending + - id: engine-vfs-asker + content: "harness: Effect::Vfs says who asked, Run::request_file, the receipt answer for a tool, the records, and the facade listings (Step 5, Engine)" + status: pending + - id: runner-files + content: "harness: ToolFiles and ToolContext::files(), the per-call desk, the loop's new arm, inline performing, and tests with a Rust fixture Pack (Step 5, runner)" + status: pending + - id: engine-ordered + content: "harness: ToolInfo::changes_files and the batch rule that runs a file-changing tool by itself, with tests (Step 6)" + status: pending + - id: host-files-unchecked + content: "harness: a handle that a Host builds makes and checks no claims, a store keeps its claims, and the tests of a conflict on the Host's files change with the rule (Step 7)" + status: pending + - id: loader-05 + content: "harness: pin contract 0.5 at the merged commit; loader file functions, Steps, and session; the test Plugin on 0.5; end-to-end tests; the measurement of 100,000 reads through the test Plugin, written into the plan (Step 8, after the merge)" + status: pending + - id: remove-access + content: "harness: remove access from Effect::ToolCall, ToolContext, and ToolPerformer, and rewrite the tests that used it (Step 9)" + status: pending + - id: pages + content: "harness: update the decision pages and the Engine definition in AGENTS.md in the commits that change the code they describe, and record the owner's reasons for where the conflict check applies and for the one list of operations" + status: pending + - id: std-async + content: "std: pin SDK 0.5, make Source async, convert Read, ListDir, and Grep, and update the rule on long jobs in AGENTS.md (Step 10, after the merge)" + status: pending + - id: std-writes + content: "std: implement Write, StrReplace, and Delete with the changes-files flag, schemas, EDITS.md, AGENTS.md, and tests (Steps 11 to 13)" + status: pending + - id: bash-futures + content: "bashkit: pin SDK 0.5 and rebuild the driver over file futures, dropping requests whose asker is gone and settling before a call ends (Step 14, after the merge)" + status: pending + - id: bash-writes + content: "bashkit: forward the six changes, answer chmod and set-time in the Plugin, refuse writes under /dev/, flag Shell, and update schema, docs, and tests (Step 15)" + status: pending + - id: pack-entries + content: "Package G: update the bash and std entries of the tools page in runvil-harness, after Packages E and F" + status: pending + - id: findings + content: "Package G: complete What the build found in the plan copy from the package reports, and mark the todos done" + status: pending +isProject: false +--- + +# Tool file operations as effects + +## Start here + +This section is for an agent that starts with this file and no earlier conversation. + +- The workspace is `c:\Users\Vinnie\cursor`. Each repository named in this plan is a folder in it, and the shell is PowerShell on Windows. +- All of the code in this plan is still to be written. The newest commit in each repository is from 2026-11-15, and it changed comments and pages. +- Read the `AGENTS.md` of each repository before you change it. +- In `runvil-harness`, read [runvil-harness/decisions/files-and-the-vfs.md](runvil-harness/decisions/files-and-the-vfs.md), [runvil-harness/decisions/tools-and-packs.md](runvil-harness/decisions/tools-and-packs.md), [runvil-harness/decisions/engine.md](runvil-harness/decisions/engine.md), and [runvil-harness/decisions/harness-and-host.md](runvil-harness/decisions/harness-and-host.md). They state the code as it is, with the decisions of 2026-11-15. The decisions of 2026-11-16 and 2026-11-17 in this plan are newer than the pages, and this plan is the authority for them. +- For background written for a newcomer, read `cabinet/_output/report-tool-file-effects-plan.md` in the workspace. Where that report and this plan differ, this plan is right. + +The repositories: + +- `runvil-harness`: the Engine, the Harness, and the decision pages. `origin` is the owner's fork. +- `runvil-plugin-api`: the C contract and the SDK. `origin` is the owner's fork, and `upstream` is `cppalliance/runvil-plugin-api`. Local `master` tracks `upstream/master`. +- `runvil-plugin-std`: the `std` Pack. `origin` is the owner's fork, and `upstream` is `cppalliance/runvil-plugin-std`. Local `master` tracks `upstream/master`. +- `runvil-plugin-bashkit`: the `bash` Pack. `origin` is `cppalliance/runvil-plugin-bashkit`. +- `runvil-workshop`: the Host application. It stays as it is. + +## Rules for all work + +- Every commit goes on `master`, the one branch in use. After a commit passes its checks, push it with `git push origin master`. Pushing to `upstream`, merging, and tagging are the owner's. +- Before the first change in a repository, run `git status`. A tree with changes from outside this plan means stop and report. +- One step is one commit, unless the step says otherwise. Every commit builds and passes every check in the repository's `AGENTS.md`. In `runvil-harness`, a commit runs a format check, and a push runs the wording scan, clippy, and `cargo deny`. +- Write each commit message by `c:\Users\Vinnie\cursor\.cursor\rules\commit.mdc`, with its text free of any mention of this plan. End it with one trailer line: `Plan: /plan/2026-11-16-1-tool-file-effects.plan.md` in `runvil-harness`, and `Plan: runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md` in every other repository. +- A file that goes is moved to `c:\Users\Vinnie\cursor\cabinet\_trash\`. That move is the one way a file leaves a repository. +- Each change leaves one form of each thing. Compatibility code, aliases, and fallbacks stay out, and a test of a rule that goes is removed with the rule. +- Comments, crate docs, READMEs, error messages, and pages state the rule as it is, with its history left out. After the last commit of a package, search the lines you added for `no longer`, `formerly`, `previously`, `used to`, `legacy`, `deprecat`, `migrat`, `replaced`, `renamed`, and `changed`, and reword each hit. +- In the Engine crates, which are `runvil-engine` and the crates under `crates/runvil-internal`, docs and names say "the caller" for the code that steps a run. `node --test tools/docs-claims.mjs` checks this. +- A commit in `runvil-harness` edits the decision pages for every rule it changes. Quote the owner exactly. The quotes for the decisions of 2026-11-16 and 2026-11-17 are in this plan. +- When the code and this plan disagree, or a step fails as written, stop and report what you found. A small difference that the code settles goes into your report. +- End each package with a report: each commit with its hash and subject, each check with its result, and each point where the work differed from this plan. + +## Work packages + +The work is cut into packages, so that one agent holds one repository at a time. Each package can go to a fresh agent together with this file. The handoff is one sentence that names this file and the package: "Read the plan from 'Start here' through 'State', then do Package C." For Packages D, E, and F the sentence adds the merged hash. + +- Package 0, the plan copy. Copy this file to `runvil-harness/plan/2026-11-16-1-tool-file-effects.plan.md`, commit it alone, and push. Every later package works from that copy. +- Package A, in `runvil-plugin-bashkit`: Step 1. +- Package B, in `runvil-plugin-api`: Steps 2 and 3. It ends with a push to `origin` and a report that gives the hash of its last commit. +- The owner's merge. When Package B has reported, the owner merges into `cppalliance/runvil-plugin-api` and names the commit that is on `upstream/master`. That hash goes under "State". +- Package C, in `runvil-harness`: Steps 4, 5, 6, and 7, in that order. It needs nothing from the contract, so it can run while Packages A and B run. +- Package D, in `runvil-harness`: Steps 8 and 9. It needs Package C and the merged hash. Its report starts with the numbers of the measurement in Step 8. +- Package E, in `runvil-plugin-std`: Steps 10 to 13. It needs the merged hash. +- Package F, in `runvil-plugin-bashkit`: Steps 14 and 15. It needs Package A and the merged hash. +- Package G, in `runvil-harness`, after every other package. It updates the `bash` and `std` entries of the tools page, completes "What the build found" in the plan copy from the reports of the packages, and marks the todos done. + +Packages A, B, and C are in three repositories and can run at the same time, after Package 0. Packages D, E, and F can run at the same time for the same reason. Two packages in one repository run one after the other. + +A fault in the contract that a later package finds goes back to `runvil-plugin-api` as a new commit. The owner merges it, the new hash goes under "State", and each repository that has pinned the contract moves its pin in a commit of its own. + +Packages D, E, and F each start by confirming the merged hash: `git fetch upstream` in `runvil-plugin-api`, then `git branch -r --contains `, which must list `upstream/master`. + +## State + +Whoever hands out the packages keeps this section current in the plan copy. + +- Merged contract commit on `cppalliance/runvil-plugin-api`: waiting for the owner +- Packages finished: none yet + +## What this plan builds + +A tool asks for a file operation and waits. The Engine issues an effect for it, the Harness performs it with one blocking call and records it, and a later step of the tool gets the answer. + +```mermaid +sequenceDiagram + participant Tool + participant Sdk + participant Loader + participant EffectLoop + participant Engine + participant Access + Tool->>Sdk: await a file method + Sdk->>Loader: file function, then RV_PENDING + Loader->>EffectLoop: request on the ToolFiles of the call + EffectLoop->>Engine: request_file with the id of the call + Engine-->>EffectLoop: next step issues a Vfs effect + EffectLoop->>Access: perform, one blocking call + EffectLoop->>Engine: record the answer and resume + EffectLoop-->>Loader: the outcome + Loader->>Sdk: next step with the answer + Sdk-->>Tool: the method returns +``` + +A `store` call from Lua is a `Vfs` effect today and stays one. The two share one list of operations, and the effect says who asked. + +## Decided on 2026-11-15 + +- Storage and `Access` stay synchronous. The Harness performs each file effect inline, with one blocking call. +- The `ToolCall` effect stays open until the tool returns its result. The Harness reports each file request through a new method on `Run`. +- The file-changing tools of one model reply run one after another, in the order the model listed them. A tool declares that it changes files. +- Each Shell call gets a new shell. +- Every commit goes to `master` and is pushed to `origin`, with a message written by `.cursor/rules/commit.mdc`. + +## Decided on 2026-11-16 + +- Lua's `store` functions and a tool's file functions are two views of one list of operations, and the Engine uses the `Vfs` effect for both. The effect says who asked: the prompt's Lua, or a tool call. This replaces the effect kind and the operation type that this plan first gave to a tool. The owner's reason: "in principle, the store is just a virtual directory in the file system that is unique to a prompt." +- `store.mount` is left out of this plan. The owner's words: "I am not sure about the store.mount feature." A tool's file operations reach the Host's files alone, as today, and a store stays Lua's. A store therefore has Lua parties alone, and every conflict in one ends the run, as today. + +## Decided on 2026-11-17 + +- The conflict check applies to a store alone. A conflict in a store ends the run with the code `determinism`, as today. The Host's files have no conflict check: an operation on them makes no claim and checks none, whoever asked for it, the prompt's own `tools.call` included. This replaces the rule of 2026-11-16, under which a conflict on the Host's files ended the run unless a model asked for both operations, and went back to the tool as an error when a model did. + - The owner's reason: "maybe the determinism error should only apply to store operations? and we should otherwise try to behave like regular harnesses, so that two subagents which conflict on file access can just work it out". + - On the prompt's own `tools.call`, the owner's words: "I think I am ok with Lua's own tools.call on Host files being unchecked. We can always put it back in later." + - The store is the prompt's own memory, and every party in it is Lua, so the check stays there. The Host's files are the outside world: with a real folder mounted, another program can change a file, and the claims table knows the run's own identities alone. + - Two tasks that work on one file both succeed. A reader in one task holds back no writer in another, and the later write is the content. + - Replay stays whole, because every file operation is a recorded effect that the Harness performs in order. + - One gap is known. A tool that edits a file as a read followed by a write can lose an edit that another task makes between the two. The VFS has an operation that replaces text in one step, `StrReplace`. A Rust Pack can ask for it through `ToolFiles`, and the C contract has no function for it, so the tools of `std` and `bash` cannot. Whether to add that function is the owner's to decide, and it is outside this plan. +- The owner merges the contract into `cppalliance/runvil-plugin-api` right after Phase 2, when its two steps are pushed. The loader is built after the merge, and the measurement runs once, in the loader's step, through the test Plugin. This replaces the decision of 2026-11-16 to prove the contract before the merge, which held uncommitted work in `runvil-harness` across the merge and made the `std` and `bash` Packs wait for the harness. Nothing uses the contract yet, so a fault that turns up later costs one more commit there and a move of each pin. The owner's words: "yes merge the contract right after phase 2". + +## Choices this plan makes + +Each one is a default that is easy to change before the work starts. + +- Names: `Run::request_file`, `VfsAsker`, `VfsReceipt`, `EffectAnswer::VfsReceipt`, `ToolFiles`, `ToolContext::files()`, `ToolInfo::changes_files`. +- What the record holds. Each `Vfs` record names who asked and which files the operation worked on: a store, by the id of its chain, or the Host's files. A write or an append records its bytes, as text when they are UTF-8 and as hex otherwise. An answer for Lua records the whole result, as today, because a replay resumes Lua with it. An answer for a tool records a size, the number of bytes of a read or the number of entries of a listing, and a stat's answer records the stat. The tool's own result is in the record as the answer of its `ToolCall`. A failure records its kind and message. The record holds no hash. Confidence: medium, because no reader of these records exists yet. +- The Engine reports no event for a tool's file operation. The effect record and the answer record are the view. A `store` call keeps its events. +- `runvil-vfs` is std only, and its manifest test enforces that, so `VfsOp` and `VfsOutcome` derive no serde there. The Engine's record code keeps a private serde form of each, which writes what the record holds today. The other place for the two types is `runvil-types`, with the function that performs an operation outside `runvil-vfs`. Confidence: medium, because the record form of `VfsOp` is serde's own today. +- `store.delete` succeeds on an absent path, and a tool's remove fails with `NotFound`. They are two operations of the list, `Delete` and `Remove`, so the record shows which one ran. +- The switch that turns the claims check off is private to `runvil-vfs`. A handle that a Host builds checks nothing, and a store asks for the check when it is made. The claims code and its tests stay, so that turning the check back on is one line. Confidence: medium, because the construction of a handle was read and the change is still to be built. +- The contract allows one request outstanding for each call. The SDK queues further requests and sends them in order. +- The contract has nine file functions and no `exists`, because a stat answers it. +- The shell answers `chmod` and `set_modified_time` inside the Plugin (Phase 5). Confidence: low, because bashkit's use of them is read from its source and untested. +- The SDK gets no adapter for synchronous tools. + +## Out of scope + +Glob in `std`, Workshop's pins, the classroom tutorial, `store.mount` and any other way for a tool to reach a store, approvals, a wake function, and a contract function for an edit as one operation. A coarser operation for Grep stays out unless the measurement of Step 8 calls for one, and then the owner decides. Workshop moves its four pins in one later change, because one build holds one version of the contract. + +## Phase 1 - bashkit: a shell for each call + +This phase is Step 1. It stays on SDK 0.4 and lands alone. Files: [runvil-plugin-bashkit/crates/plugin-bashkit/src/session.rs](runvil-plugin-bashkit/crates/plugin-bashkit/src/session.rs), [runvil-plugin-bashkit/crates/plugin-bashkit/src/pack.rs](runvil-plugin-bashkit/crates/plugin-bashkit/src/pack.rs), [runvil-plugin-bashkit/crates/plugin-bashkit/src/shell.rs](runvil-plugin-bashkit/crates/plugin-bashkit/src/shell.rs), [runvil-plugin-bashkit/crates/plugin-bashkit/schemas/shell.json](runvil-plugin-bashkit/crates/plugin-bashkit/schemas/shell.json). + +- Remove `Session` and `turn`, and the `session` field of `BashPack`. `shell::call` builds a `Shell` for its call and drops it when the call ends. +- `shell.json`: the session bullet becomes "Each call starts a new shell at the root of the run's files. A `cd`, a variable, or a function lasts for that call alone." The bullet about calls sharing one session goes. `working_directory` defaults to the root of the run's files. The first line says "in a bash shell". +- The time-limit message in `shell.rs` loses its sentence about the session. +- `schemas/EDITS.md`, the crate docs in `lib.rs`, and `AGENTS.md` say the same. In `AGENTS.md`, the line that begins "Each call is to get a shell of its own" becomes the rule as built. The `bash` entry of the tools page changes in Package G, so that one agent at a time works in `runvil-harness`. +- Tests: a `cd` or a variable from one call is gone in the next. The tests of turns on the session go. + +## Phase 2 - runvil-plugin-api: contract 0.5 and the SDK + +Files: [runvil-plugin-api/crates/runvil-plugin-sys/src/lib.rs](runvil-plugin-api/crates/runvil-plugin-sys/src/lib.rs), [runvil-plugin-api/crates/runvil-plugin-sdk/src/tool.rs](runvil-plugin-api/crates/runvil-plugin-sdk/src/tool.rs), [runvil-plugin-api/crates/runvil-plugin-sdk/src/entry/tool.rs](runvil-plugin-api/crates/runvil-plugin-sdk/src/entry/tool.rs), [runvil-plugin-api/crates/runvil-plugin-sdk/src/entry/file.rs](runvil-plugin-api/crates/runvil-plugin-sdk/src/entry/file.rs), [runvil-plugin-api/crates/runvil-plugin-sdk/src/testing.rs](runvil-plugin-api/crates/runvil-plugin-sdk/src/testing.rs) and its `testing` folder. + +### Step 2 - reads as a request and an answer + +`RV_API_MINOR` becomes 5, and both crates become 0.5.0. Each file function only takes a request, and the answer arrives in the next step's arguments: + +```rust +#[repr(C)] +pub struct RvFileAnswer { + pub size: u32, + pub status: RvStatus, // RV_OK, or RV_ERR_FILE with `error` filled + pub stat: RvStat, // for file_stat + pub entries: RvDirEntries, // for file_list + pub bytes: RvBytes, // for file_read + pub error: RvFileError, +} + +// In RvToolCallArgs, in their present positions: +pub file_stat: unsafe extern "C" fn(ctx: *mut c_void, path: RvStr) -> RvStatus, +pub file_list: unsafe extern "C" fn(ctx: *mut c_void, path: RvStr) -> RvStatus, +pub file_read: unsafe extern "C" fn(ctx: *mut c_void, path: RvStr, offset: u64, len: u64) -> RvStatus, +// Added after file_read: the answer to the request the call's last step made, or NULL. +pub answer: *const RvFileAnswer, +``` + +Rules for the contract's comment: + +- A call has one request outstanding at a time. A second request in one step is a misuse, and so is a request in a step that calls `finish`. +- A step that made a request returns `RV_PENDING`. The Host sends that call its next step when the answer is ready, and no step before then. +- The answer, and what it points to, is valid for the step that receives it. The Plugin copies what it keeps. +- When the Host abandons a call, an operation it had taken either happened in full or did not happen. +- A file function returns `RV_OK` when the Host took the request and `RV_ERR_MISUSE` for a misuse, and it fills nothing. The sentence of the present comment that says only a file function returns `RV_ERR_FILE` changes, because that status now arrives in the answer. +- The sentence of the present comment that says `RV_PENDING` is not a way to wait changes too: a step that made a request waits for its answer by returning `RV_PENDING`. +- `RV_FILE_ERROR_CONFLICT` and its comment stay as they are. This Host checks no conflict on the files a tool reaches, so it sends that kind to no tool. + +SDK: + +- `ToolCall::stat`, `list`, `read`, and `read_range` return futures that are `Send`. Each copies its path when it is made. +- `CallState` holds a queue behind a `std::sync::Mutex` in place of the step pointer: requests not yet sent, whether one is with the Host, and answers not yet taken. +- In `entry/tool.rs`, each step copies `args.answer` into the queue before it polls the tool's future. After a poll that returns `Pending`, the step sends the oldest queued request through the step's file function. Sending after the poll means a tool that finishes or panics in that poll leaves no request with the Host. +- A file future dropped before its request went out sends nothing. Dropped later, the operation still happens and its answer is discarded. The docs say both. +- The `unsafe` stays in `entry` and `testing`, and the crate still builds on Rust 1.85. + +Fake Host: a `Call` keeps the outstanding request and its answer between steps, and it checks the new misuses. The loader copies its words for each misuse in Phase 3. + +Also: `cargo xtask header`, the tables in `tests/c-layout`, `examples/hello-plugin`, `README.md`, and the file rule in `AGENTS.md`. The dependency lines in the README name the tag `api-v0.5.0`, and the owner creates that tag after the merge. + +### Step 3 - changes and the flag + +- `file_write(ctx, path, bytes)`, `file_append(ctx, path, bytes)`, `file_mkdir(ctx, path, recursive)`, `file_remove(ctx, path, recursive)`, `file_rename(ctx, from, to)`, and `file_copy(ctx, from, to)`, added after `answer`. Their answer holds a status alone. `RV_MAX_WRITE` is 16 MiB. `recursive` is a `u32` that is 0 or 1, and bytes longer than `RV_MAX_WRITE` are a misuse. +- A remove of a path that is absent answers `RV_FILE_ERROR_NOT_FOUND`. +- Two error kinds: `RV_FILE_ERROR_ALREADY_EXISTS` (7) and `RV_FILE_ERROR_NOT_EMPTY` (8). +- `RvToolInfo.reserved` becomes `flags`, and `RV_TOOL_CHANGES_FILES` is bit 0. A set bit outside the defined ones is a misuse. +- SDK: `ToolCall::write`, `append`, `mkdir`, `remove`, `rename`, `copy`, `ToolInfo::changes_files()`, and the two new `FileErrorKind` values. +- `testing::Files` becomes a tree that the calls of one `PackRun` share and can change, and a test reads it back after a call. `Files::fails` makes every operation on its path fail, a change included, so that a test can show a write that the Host refuses. Phases 4 and 5 need this for their tests. + +Then push to `origin`. The owner merges the contract at this point, and the later pins use the commit that is on `cppalliance/runvil-plugin-api` after the owner's merge. + +## Phase 3 - runvil-harness + +Each commit keeps the workspace building, and each edits the decision pages for what it changes. Engine docs say "the caller", as `tools/docs-claims.mjs` requires. + +### Step 4 - one list of operations, in `runvil-vfs` + +`VfsOp` and `VfsOutcome` move from [runvil-harness/crates/runvil-internal/lua/src/protocol](runvil-harness/crates/runvil-internal/lua/src/protocol) to a new module of [runvil-harness/crates/runvil-internal/vfs/src](runvil-harness/crates/runvil-internal/vfs/src) beside `stat.rs`, and they grow to the whole list. `Access::perform` in `handle/operations.rs` runs one operation. The line-range logic of `run_store_op`, in `engine_globals_store.rs` of `runvil-lua`, moves with it, and the facade's `perform_vfs_op` calls `Access::perform`. The rule that an anchor occurs exactly once is in `runvil-vfs` already. + +The eight operations that exist keep their names and the form of their records: + +- `Write`: creates a file or replaces its content. Lua uses it for `store.write`, and the contract for `file_write`. +- `Append`: adds to the end of a file and creates the file when needed. Lua uses it for `store.append`, and the contract for `file_append`. +- `Read`: a range of lines as text. Lua uses it for `store.read`. +- `ReadNumbered`: a range of lines with their numbers. Lua uses it for `store.read_numbered`. +- `StrReplace`: replaces a text that occurs exactly once in a file. Lua uses it for `store.str_replace`. +- `Delete`: removes what a path names, and succeeds when the path is absent. Lua uses it for `store.delete`. +- `Glob`: the paths that match a pattern. Lua uses it for `store.glob`. +- `Exists`: whether a path exists. Lua uses it for `store.exists`. + +Seven operations join them: + +- `Stat`: the type and the length of what a path names. The contract uses it for `file_stat`. +- `List`: the entries of a directory. The contract uses it for `file_list`. +- `ReadRange`: a range of bytes. The contract uses it for `file_read`. +- `Mkdir`: creates a directory, with its parents on request. The contract uses it for `file_mkdir`. +- `Remove`: removes a file or a directory, with its content on request, and fails with `VfsError::NotFound` when the path is absent. The contract uses it for `file_remove`. +- `Rename`: moves a file or a directory. The contract uses it for `file_rename`. +- `Copy`: copies one file. The contract uses it for `file_copy`. + +The list has fifteen operations. Lua uses eight and a tool uses nine, and `Write` and `Append` are on both sides. The Engine and the Harness handle the whole list from the start, so either side gains an operation later by adding one function. + +One field changes: the `contents` of `Write` and `Append` becomes bytes, where it is a string today, because a tool writes bytes. Lua passes the bytes of its string, and the record writes them as the text it writes today. `VfsOutcome` gains the results the new operations need: a stat, a list of entries, and bytes, beside the unit, text, paths, and bool it has. + +### Step 5 - a tool's requests as `Vfs` effects, beside the old access + +Step 5 is two commits. The first holds the Engine changes, with the runner adjusted so that the workspace builds: its match on `Effect::Vfs` takes the new field. The second holds the Rust Plugin API, the runner's desk and loop arm, and the tests under `Harness::run`. + +Engine, in [runvil-harness/crates/runvil-internal/runtime/src/execute/run/effect.rs](runvil-harness/crates/runvil-internal/runtime/src/execute/run/effect.rs), [runvil-harness/crates/runvil-internal/runtime/src/execute/run.rs](runvil-harness/crates/runvil-internal/runtime/src/execute/run.rs), and `effects.rs`, `apply.rs`, `drive.rs`, `tool_call.rs` under [runvil-harness/crates/runvil-internal/runtime/src/execute/scheduler](runvil-harness/crates/runvil-internal/runtime/src/execute/scheduler): + +```rust +// Run +pub fn request_file(&mut self, call: EffectId, op: VfsOp); +// Effect: `asker` takes the place of today's `store` field +Vfs { asker: VfsAsker, access: Arc, op: VfsOp }, +pub enum VfsAsker { + /// A `store` call of the prompt's Lua, on the store made for this chain. + Lua { store: ChainId }, + /// The open tool call with this id, on the Host's files. + Tool { call: EffectId }, +} +// EffectAnswer +Vfs(Result), // when Lua asked, as today +VfsReceipt(Result), // when a tool asked +``` + +- Without `store.mount` the asker settles the files: Lua works on its chain's store, and a tool works on the Host's files. The effect needs no second field for the files. +- `ToolCallContinuation` keeps the call's `Arc`. +- `request_file` for an awaited tool call issues a `Vfs` effect whose asker is that call, under the calling chain, with the call's access, and the next `step` returns it. For a call whose chain stopped waiting it does nothing. For any other id it ends the run with an `internal` error, as a bad answer does. +- A new continuation for a tool's `Vfs` effect resumes no chain, like a fired timer. Its `Dropped` answer does nothing either. A failure in its answer goes to the tool and leaves the run alone. +- A `Vfs` effect that Lua asked for is answered with the whole outcome and resumes the Lua code, as today. +- `VfsReceipt` is what the record keeps of a tool's outcome: a stat, a bool, a count of entries or paths, a count of bytes, or done. It covers all fifteen operations, because a Rust Pack may ask for any of them through `ToolFiles`. The loop hands the full outcome to the tool, so the Engine gets no copy of the bytes of a read. +- `Effect::record` and `EffectAnswer::record` gain the forms listed under "Choices this plan makes". The record of a `Vfs` effect that Lua asked for stays byte for byte as it is. A test that names the effect's `store` field changes with the field. The record of one that a tool asked for names the tool call by its effect id, where the other names its store. +- `request_file` on a run that has returned `Done` does nothing. +- An answer of the other form, such as `Vfs` for an effect that a tool asked for, ends the run with an `internal` error, as an answer of the wrong kind does today. +- The facade in [runvil-harness/crates/runvil-engine/src/lib.rs](runvil-harness/crates/runvil-engine/src/lib.rs) re-exports the new items, and `cargo + xtask api --bless` updates both `public-api.txt` listings. The `runvil` facade and `runvil-plugin` re-export `VfsOp`, `VfsOutcome`, and `ToolFiles` as well, because a Pack names them through `ToolContext::files()`. + +Rust Plugin API, in [runvil-harness/crates/runvil-plugin/src/context.rs](runvil-harness/crates/runvil-plugin/src/context.rs): + +```rust +pub trait ToolFiles: Send + Sync { + fn request(&self, op: VfsOp) -> BoxFuture<'_, Result>; +} +``` + +`ToolContext::files()` lends it. `testing::TestCall` answers each request at once from a file system of its own. + +Runner, in [runvil-harness/crates/harness-internal/runner/src/effect_loop.rs](runvil-harness/crates/harness-internal/runner/src/effect_loop.rs), `performers.rs`, `packs.rs`, and a new `tool_files.rs`: + +- Each tool call gets a desk that implements `ToolFiles`: a queue of its requests with the waker of each, plus a run-wide queue of the calls that asked. +- `wake()` gains an arm that returns the next request. It checks the queue before and after it polls the calls in flight. +- For a request from a call still in flight, the loop calls `run.request_file`. A request from a call that has landed or was aborted is dropped. +- A `Vfs` effect that a tool asked for is answered inline: `access.perform(&op)`, then the answer record, then `run.resume` with the receipt, then the full outcome goes to the call's desk and wakes the call. A withdrawn one is answered `Dropped` unperformed, on the path that exists for store effects. The loop performs the operation inside a guard that turns a panic in a backend into `VfsError::Backend`, as `contained` in the loader does today. +- A `Vfs` effect that Lua asked for is answered as today. +- `ToolPerformer::call` gains the desk, and `RunPacks::call` puts it in the `ToolContext`. + +Tests: the Engine's rules above, one each, and a Rust fixture Pack that reads and writes through `cx.files()` under `Harness::run`, with the records checked, and with a stop and a cancel while a request is pending. + +### Step 6 - file-changing tools run in order + +The Host's files have no conflict check, so this order is what keeps two changes of one reply from interleaving: each changing call finishes before the next one starts. + +- `ToolInfo::changes_files` in `runvil-types`, and `ToolBinding::changes_files()` in `runvil-lua`. A render keeps the catalog's value, as it keeps `survives_stop`. +- One more arm in `dispatch_tool_calls` in `tool_call.rs`, so that such a call ends the batch before it and the loop sends it alone, as it sends an adhoc tool: + +```rust +Ok(ToolRoute::Adhoc(_) | ToolRoute::Discovery(_)) => break, +Ok(ToolRoute::Catalog(binding)) if binding.changes_files() => break, +``` + +- Tests: two edits to one file in one reply both apply, in the order listed. A reader listed before a changer finishes first. Tools without the flag still overlap. + +### Step 7 - no conflict check on the Host's files + +Files: `handle.rs`, `handle/access.rs`, and `handle/store_view.rs` under [runvil-harness/crates/runvil-internal/vfs/src](runvil-harness/crates/runvil-internal/vfs/src), the tests beside them, and the tests outside the crate that expect a conflict on the Host's files. + +- The `Volume` of a handle says whether it checks claims. `Access::admit` in `handle/access.rs` skips the claim when it does not, and it still refuses an operation of a scope that has ended. +- A handle from `VfsRef::new` or `VfsRefBuilder::build` checks no claims. `Store::new` asks for the check through a setting that is private to the crate. No public item is added. +- Identities, scopes, forks, and joins stay as they are, because a store view takes its order from them. +- The claims code, the case folding of claim keys, and the claims tests of `runvil-vfs` stay. Those tests build their handles with the private setting. The owner may turn the check back on: "We can always put it back in later." +- A `store` conflict ends the run with `determinism`, as before, and `classify_vfs_failure` stays as it is. +- Tests outside `runvil-vfs` that expect a conflict between two accesses of the Host's files change to expect that both operations run. The compiler does not find them, so search the tests for `Conflict` and `conflict`, starting with `execute/tests/tool_call_access.rs` of the runtime and the `vfs.rs` suites of `runvil` and `runvil-engine`. A test of a conflict in a store stays. +- New tests, with the Rust fixture Pack. Two tasks whose models write one path both succeed, and the later write is the content. A task whose model reads a path holds back no write of another task. A prompt's own `tools.call` and a model's call on one path both succeed. A `store` conflict ends the run as before. +- The docs of the methods of `Access` say that a conflict is refused on a handle that checks claims. + +### Step 8 - the loader and the test Plugin on 0.5 + +This step follows the owner's merge. Files: [runvil-harness/Cargo.toml](runvil-harness/Cargo.toml), `file.rs`, `call.rs`, `session.rs`, `pack.rs` under [runvil-harness/crates/harness-internal/plugin-loader/src](runvil-harness/crates/harness-internal/plugin-loader/src), and [runvil-harness/crates/harness-internal/test-plugin/src/lib.rs](runvil-harness/crates/harness-internal/test-plugin/src/lib.rs). + +- Pin `runvil-plugin-sys` 0.5 at the merged commit: in [runvil-harness/Cargo.toml](runvil-harness/Cargo.toml), the line takes `version = "0.5.0"` and the merged commit as `rev`, with the `git` address it has today, and `Cargo.lock` follows. +- Each file function records one `VfsOp` in the step's session. The misuses and their words are the fake Host's, in `runvil-plugin-api/crates/runvil-plugin-sdk/src/testing`. +- `Steps` holds the call's `ToolFiles`, the request in progress, and the answer to lend. Its `poll` first polls a request in progress, and returns `Pending` without waking itself while that request waits. It then sends one step with `answer` set. A step that made a request starts that request and polls it at once. A step that returns `RV_PENDING` with no request wakes itself, as today. +- `describe` in `file.rs` maps the two new kinds. `contained` leaves the loader, because the loop performs the operations. +- `pack.rs` reads `RV_TOOL_CHANGES_FILES` into `ToolInfo::changes_files`. +- The test Plugin reports 0.5. Its `stat`, `list`, and `read` tools take two steps, and it gains a tool for each change, flagged. It also gains a tool that reads many small files in one call, for the measurement. +- End-to-end tests under `Harness::run`: each operation, a denied one, two tasks that write one path, and a cancel between a request and its answer. +- The measurement. A test that is ignored by default calls the test Plugin's tool that reads many small files, for 100,000 reads under `Harness::run` with `MemoryRecorder`, and prints the elapsed time and the record count. The numbers go into the plan copy under "What the build found", in this step's commit, and into the report of Package D. They say whether Grep needs a coarser operation, which would be an addition to the contract, and the owner decides. + +### Step 9 - remove the old access + +Remove `access` from `Effect::ToolCall`, `ToolContext::access`, the access argument of `ToolPerformer::call`, and the `Access` re-export of `runvil-plugin`. Rewrite the tests that used them: `execute/tests/tool_call_access.rs` in the runtime, `tests/it/tool_context.rs` in the runner, and the `vfs.rs` suites of `runvil` and `runvil-engine`. The drivers in `examples/greeter.rs` and the two `scenario.rs` files answer a `Vfs` effect that a tool asked for. Bless both listings. + +### Pages + +Packages C and D edit these pages in the commits of the steps they describe. Package G edits the entries of the shipped Packs on the tools page: the `bash` entry says that each call has a shell of its own and that the shell can change files, the `std` entry says that Write, StrReplace, and Delete work, and the planned-work items for these go. + +- [runvil-harness/decisions/engine.md](runvil-harness/decisions/engine.md): `Run` has five calls. The Engine still has five effect kinds, and the entry for `Effect::Vfs` says who asked and what each record holds. The sentence "`EffectAnswer` has one variant for each effect kind, plus `Dropped`" changes with Step 5, because the `Vfs` kind then has two answers: `Vfs` when Lua asked and `VfsReceipt` when a tool asked. +- [runvil-harness/AGENTS.md](runvil-harness/AGENTS.md): the definition of the Engine lists "a store operation" among the work it issues effects for. With Step 5 it says a file operation, which covers a `store` call and a tool's request. +- [runvil-harness/decisions/files-and-the-vfs.md](runvil-harness/decisions/files-and-the-vfs.md): the entry on a tool call's identity, the entry that says a tool's operations will be effects, and the two entries on the `Vfs` effect and its record. The entries on identities and conflicts say that the claims check applies to a store alone and that the Host's files have none, with the owner's reasons from 2026-11-17, which answers open question 4. +- [runvil-harness/decisions/tools-and-packs.md](runvil-harness/decisions/tools-and-packs.md): tool calls in order, `ToolContext`, the contract section, the entry on a call's file identity, which loses its conflict rule, and open question 7. +- [runvil-harness/decisions/harness-and-host.md](runvil-harness/decisions/harness-and-host.md): the loop answers every `Vfs` effect inline, for Lua and for a tool, and what the records hold. +- `tasks-and-fanout.md` and `testing-and-debugging.md`: one sentence each, on the order of file requests and on the fake Host's tree. + +## Phase 4 - runvil-plugin-std + +This phase waits for the owner's merge, which follows Phase 2, and it needs no code from Phase 3. Files: [runvil-plugin-std/crates/plugin-std/src/source.rs](runvil-plugin-std/crates/plugin-std/src/source.rs), [runvil-plugin-std/crates/plugin-std/src/pack.rs](runvil-plugin-std/crates/plugin-std/src/pack.rs), `read.rs`, `dir.rs`, `dir/walk.rs`, `grep/find.rs`, `fake.rs`, and the `schemas` folder. + +- Step 10. Pin SDK 0.5: in `Cargo.toml`, the line for `runvil-plugin-sdk` takes `version = "0.5.0"` and the merged commit as `rev`, and `Cargo.lock` follows. The methods of `Source` become `async fn`. `read::call`, `read_file`, `dir::call`, `list_directory`, `walk`, `Search::root_file`, and `Search::visit` become async, and `walk` takes the `Source` in place of its closure. Grep keeps its pause every 32 entries and drops the one every 2 MiB. +- Step 11. Write: one `write`, flagged `changes_files`. Contents over the SDK's write limit fail with a sentence that names the limit. +- Step 12. StrReplace: read the file under the 16 MiB ceiling that Read has, require UTF-8, find `old_string`, and write the result. It needs exactly one match unless `replace_all` is set, and a failure states the count. +- Step 13. Delete: a `stat`, then one `remove`. The stat comes first because a directory is refused with a sentence. +- Each step updates its schema text, `schemas/EDITS.md`, the crate docs, and its tests, which use the SDK's fake Host or `FakeSource`. The `std` entry of the tools page changes in Package G. +- [runvil-plugin-std/AGENTS.md](runvil-plugin-std/AGENTS.md) changes with the steps. Step 10 takes "every 2 MiB read" out of the rule on long jobs. Steps 11 to 13 widen the rule on `Source` from reads to every file operation, and they remove the line that says what Write, StrReplace, and Delete wait for. + +## Phase 5 - runvil-plugin-bashkit on 0.5 + +This phase follows Phase 1 and waits for the owner's merge. Files: [runvil-plugin-bashkit/crates/plugin-bashkit/src/files.rs](runvil-plugin-bashkit/crates/plugin-bashkit/src/files.rs) and `session.rs`, `pack.rs`, `shell.rs`, `schemas/shell.json` beside it. + +Step 14 - the driver over futures. Changes are still refused. The step starts with the pin: in `Cargo.toml`, the line for `runvil-plugin-sdk` takes `version = "0.5.0"` and the merged commit as `rev`, and `Cargo.lock` follows. + +- `FileRequest::serve` becomes async and awaits the SDK's future. +- `drive` keeps the operations in progress in its own frame and polls them before it polls the script. +- It drops a request whose asker is gone, tested with `reply.is_closed()`. bashkit abandons a file operation at its `timeout` builtin, at `kill`, and in a failed pipeline. +- It waits for the operations in progress before the call ends. +- The count of 32 becomes a cap on polls of the script in one step. + +Step 15 - writes. + +- `write_file`, `append_file`, `mkdir`, `remove`, `rename`, and `copy` forward to the SDK, and `READ_ONLY` goes. +- The shell reports mode 0o644 for a file and 0o755 for a directory. `chmod` succeeds when it sets the mode the shell reports for that path and fails with one fixed sentence otherwise. `set_modified_time` succeeds and stores no time, because the run's files report no times. `symlink` and `mkfifo` answer `Unsupported`, as `read_link` does today. +- A write to a path under `/dev/` is refused, because bashkit 0.21.0 on Windows sends a redirect to `/dev/stdout` to the file system. The `AGENTS.md` of this repository asks for a link to an upstream issue beside a workaround, and the owner supplies that link. +- `Shell` is flagged `changes_files`, and `shell.json` says that a reply's Shell calls run one after another, in the order listed. +- Tests: a redirect, `>>`, `tee`, `sed -i`, `cp -r`, `mv`, `rm -r`, `mkdir -p`, `touch`, `mktemp`, and a write that the Host refuses. +- `schemas/EDITS.md`, the crate docs, and `AGENTS.md` follow. The `bash` entry of the tools page changes in Package G. + +## Order of work + +The section "Work packages" maps this order onto packages. + +- Phases 1 and 2 start together, and so do Steps 4 to 7, which need nothing from the contract. +- The owner merges the contract when Phase 2 is pushed. +- After the merge, Steps 8 and 9, Phase 4, and Phase 5 are in three repositories and can run side by side. Step 8 follows Step 7. + +## Verification + +- `runvil-plugin-api`: `cargo test --workspace --all-features`, clippy with `CARGO_BUILD_WARNINGS=deny`, `cargo fmt --all --check`, the docs build with `RUSTDOCFLAGS="-D warnings"`, and `cargo +1.85 check -p runvil-plugin-sys -p runvil-plugin-sdk --all-features`. +- `runvil-harness`: `cargo nextest run --locked --workspace --all-features`, clippy, fmt, both docs builds, `cargo + xtask api --check`, `cargo dylint`, `cargo test -p build-xtask`, and `node --test tools/docs-claims.mjs`. +- `runvil-plugin-std` and `runvil-plugin-bashkit`: the test, clippy, fmt, docs, and release-build commands in each `AGENTS.md`. + +## What the build found + +This section starts empty. Step 8 adds its numbers to it in the plan copy, and Package G completes it from the reports of the packages. From ef6b34080f593a343ceaa5858e35530ba5427799 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Tue, 17 Nov 2026 18:57:49 -0800 Subject: [PATCH 03/23] Move `VfsOp` to `runvil-vfs` as one list of operations A `store` call and a file request of a tool are two views of one list of file operations, so the list is now in `runvil-vfs`, where `Access::perform` runs one operation. `VfsOp` and `VfsOutcome` leave `runvil-lua`, `VfsOp` grows from eight operations to fifteen, and the line bounds of the two text reads move with them into `handle/lines.rs`. `runvil-vfs` stays std only, so the records write both types through private serde forms in `vfs_record.rs`. - `EffectRecord::Vfs` and `AnswerRecord::Vfs` keep the real types and write them with `serialize_with` and `deserialize_with` through `VfsOpRecord` and `VfsOutcomeRecord`. The JSON of a store record is the same as before. - Both types stay `#[non_exhaustive]`, so the record code has a fallback arm. An operation or an outcome with no record form records as `null`, a kind of file with no name records as `other`, and none of the three reads back. - The `contents` of `Write` and `Append` is `Vec`. A record writes UTF-8 bytes as text under `contents` and other bytes as hex under `contents_hex`. `parse_store` still requires UTF-8 text and passes its bytes. - `perform_vfs_op` takes `&VfsOp` and calls `Access::perform`. `run_store_op` is removed. - The `runvil` facade re-exports `VfsOp` and `VfsOutcome`, because `Access::perform` names them and the surface check refuses a name that the facade does not re-export. - `Delete` succeeds on an absent path and `Remove` fails with `VfsError::NotFound`. `Access::remove` maps the result of a private `remove_present`. - `store_value` gives Lua nil for a stat, a listing, or bytes, because no `store` function returns them. - A stat records each time as whole seconds and nanoseconds from the Unix epoch, with negative seconds before it. - No code issues one of the seven new operations as an effect. The tests reach them through `Access::perform` and through the record forms. - `VfsOp` has no `Deserialize`, so the runner test that rebuilds a store from its records reads the record JSON in `recorded_op`. - `decisions/files-and-the-vfs.md` has a new entry on the one list, with the reason of the owner. Plan: /plan/2026-11-16-1-tool-file-effects.plan.md --- crates/build-xtask/src/facade_shape-tests.rs | 2 +- .../runner/src/effect_loop.rs | 2 +- .../runner/tests/it/effect_loop-vfs.rs | 53 +- crates/runvil-engine/examples/greeter.rs | 2 +- crates/runvil-engine/public-api.txt | 37 +- crates/runvil-engine/src/lib.rs | 16 +- .../tests/suite/support/scenario.rs | 2 +- crates/runvil-engine/tests/suite/vfs.rs | 8 +- .../lua/src/engine_globals_store.rs | 170 +---- crates/runvil-internal/lua/src/lib.rs | 10 +- crates/runvil-internal/lua/src/protocol.rs | 5 +- .../lua/src/protocol/answer.rs | 31 +- .../lua/src/protocol/parse/store.rs | 10 +- .../lua/src/protocol/render.rs | 12 +- .../lua/src/protocol/request.rs | 100 +-- crates/runvil-internal/lua/src/test_vm.rs | 10 +- crates/runvil-internal/lua/src/tests.rs | 2 +- .../lua/src/tests/store_errors.rs | 8 +- crates/runvil-internal/runtime/src/error.rs | 2 +- .../runtime/src/error/tests.rs | 2 +- crates/runvil-internal/runtime/src/execute.rs | 19 +- .../runtime/src/execute/run.rs | 4 +- .../runtime/src/execute/run/effect-tests.rs | 2 +- .../runtime/src/execute/run/effect.rs | 25 +- .../runtime/src/execute/run/tests-inbox.rs | 2 +- .../runtime/src/execute/run/tests-reply.rs | 2 +- .../runtime/src/execute/run/tests-send.rs | 2 +- .../runtime/src/execute/run/tests-steer.rs | 2 +- .../runtime/src/execute/run/tests.rs | 4 +- .../src/execute/run/vfs_record-tests.rs | 327 ++++++++++ .../runtime/src/execute/run/vfs_record.rs | 585 ++++++++++++++++++ .../runtime/src/execute/scheduler/apply.rs | 11 +- .../runtime/src/execute/scheduler/dispatch.rs | 3 +- .../runtime/src/execute/scheduler/effects.rs | 4 +- .../src/execute/scheduler/test_hooks.rs | 4 +- .../runtime/src/execute/tests/effects.rs | 7 +- .../src/execute/tests/execute/store.rs | 5 +- .../runtime/src/execute/tests/preludes.rs | 4 +- .../tests/suite/exec_flow/store_failures.rs | 4 +- .../runtime/src/execute/tests/waits.rs | 2 +- crates/runvil-internal/runtime/src/lua.rs | 14 +- .../runtime/src/lua/tests/errors-tables.rs | 2 +- .../runtime/src/lua/tests/shims.rs | 6 +- .../runtime/src/test_support.rs | 3 +- .../runtime/src/test_support/scenario.rs | 4 +- crates/runvil-internal/vfs/README.md | 2 +- crates/runvil-internal/vfs/src/handle.rs | 1 + .../runvil-internal/vfs/src/handle/lines.rs | 117 ++++ .../vfs/src/handle/operations.rs | 66 +- .../runvil-internal/vfs/src/handle/tests.rs | 1 + .../vfs/src/handle/tests/perform.rs | 309 +++++++++ crates/runvil-internal/vfs/src/lib.rs | 6 +- crates/runvil-internal/vfs/src/vfs_op.rs | 165 +++++ crates/runvil/public-api.txt | 64 ++ crates/runvil/src/lib.rs | 7 +- decisions/engine.md | 2 +- decisions/files-and-the-vfs.md | 6 + 57 files changed, 1863 insertions(+), 414 deletions(-) create mode 100644 crates/runvil-internal/runtime/src/execute/run/vfs_record-tests.rs create mode 100644 crates/runvil-internal/runtime/src/execute/run/vfs_record.rs create mode 100644 crates/runvil-internal/vfs/src/handle/lines.rs create mode 100644 crates/runvil-internal/vfs/src/handle/tests/perform.rs create mode 100644 crates/runvil-internal/vfs/src/vfs_op.rs diff --git a/crates/build-xtask/src/facade_shape-tests.rs b/crates/build-xtask/src/facade_shape-tests.rs index 8bec77011..9df73f95a 100644 --- a/crates/build-xtask/src/facade_shape-tests.rs +++ b/crates/build-xtask/src/facade_shape-tests.rs @@ -186,7 +186,7 @@ fn a_re_export_rooted_outside_the_facade_dependencies_is_rejected() { ), ("pub use std::sync::Arc;", 1), ("pub use ::serde::Serialize;", 1), - ("pub use runvil_lua::VfsOp;", 1), + ("pub use runvil_lua::RosterEntry;", 1), ] { assert_one(text, line, RULE); } diff --git a/crates/harness-internal/runner/src/effect_loop.rs b/crates/harness-internal/runner/src/effect_loop.rs index 62cd546d8..4e2ccdcef 100644 --- a/crates/harness-internal/runner/src/effect_loop.rs +++ b/crates/harness-internal/runner/src/effect_loop.rs @@ -877,7 +877,7 @@ impl Flights { reason = "the view is taken by value so that it drops with the operation" )] fn answer_vfs(access: Arc, op: VfsOp) -> EffectAnswer { - EffectAnswer::Vfs(perform_vfs_op(&access, op)) + EffectAnswer::Vfs(perform_vfs_op(&access, &op)) } /// A panic payload's message, when it carries one. diff --git a/crates/harness-internal/runner/tests/it/effect_loop-vfs.rs b/crates/harness-internal/runner/tests/it/effect_loop-vfs.rs index 7e0627fe1..67386fa4e 100644 --- a/crates/harness-internal/runner/tests/it/effect_loop-vfs.rs +++ b/crates/harness-internal/runner/tests/it/effect_loop-vfs.rs @@ -275,6 +275,54 @@ async fn a_step_with_a_vfs_effect_records_its_inline_answer_before_the_next_effe ); } +/// The operation a store's `Vfs` effect record holds, read from the +/// record's JSON alone: one object keyed by the operation's name, with +/// the arguments of the `store` call as its fields. +fn recorded_op(op: &serde_json::Value) -> VfsOp { + let (name, fields) = op + .as_object() + .and_then(|keyed| keyed.iter().next()) + .expect("an operation records as one object keyed by its name"); + let text = |field: &str| { + fields[field] + .as_str() + .unwrap_or_else(|| panic!("{name} records `{field}` as text: {fields}")) + .to_owned() + }; + let line = |field: &str| fields[field].as_i64(); + match name.as_str() { + "Write" => VfsOp::Write { + path: text("path"), + contents: text("contents").into_bytes(), + }, + "Append" => VfsOp::Append { + path: text("path"), + contents: text("contents").into_bytes(), + }, + "Read" => VfsOp::Read { + path: text("path"), + start: line("start"), + end: line("end"), + }, + "ReadNumbered" => VfsOp::ReadNumbered { + path: text("path"), + start: line("start"), + end: line("end"), + }, + "StrReplace" => VfsOp::StrReplace { + path: text("path"), + old: text("old"), + new: text("new"), + }, + "Delete" => VfsOp::Delete { path: text("path") }, + "Glob" => VfsOp::Glob { + pattern: text("pattern"), + }, + "Exists" => VfsOp::Exists { path: text("path") }, + other => panic!("no `store` call records as {other}"), + } +} + /// A section that writes, appends to, edits, and deletes store files, /// reads the deleted one under a `pcall`, and returns what it reads back /// of the file it kept. @@ -326,9 +374,8 @@ async fn a_runs_vfs_records_rebuild_its_store() { if answer.payload["Vfs"].get("Ok").is_none() { continue; } - let op: VfsOp = serde_json::from_value(vfs["op"].clone()) - .expect("a Vfs effect's record holds its operation whole"); - perform_vfs_op(&files, op).expect("an operation the store performed applies again"); + perform_vfs_op(&files, &recorded_op(&vfs["op"])) + .expect("an operation the store performed applies again"); applied += 1; } assert_eq!(applied, 6, "every operation but the refused read"); diff --git a/crates/runvil-engine/examples/greeter.rs b/crates/runvil-engine/examples/greeter.rs index 49cc97995..72857ab9b 100644 --- a/crates/runvil-engine/examples/greeter.rs +++ b/crates/runvil-engine/examples/greeter.rs @@ -44,7 +44,7 @@ pub fn answer(effect: Effect) -> EffectAnswer { match effect { // The view reaches the one store the effect names, so the loop // performs the operation without reading which store that is. - Effect::Vfs { access, op, .. } => EffectAnswer::Vfs(perform_vfs_op(&access, op)), + Effect::Vfs { access, op, .. } => EffectAnswer::Vfs(perform_vfs_op(&access, &op)), Effect::Chat { .. } => { let reply = CompletionResult::Text("hi there".to_owned()); EffectAnswer::Chat(Completion::from_result(reply, "canned").map(Box::new)) diff --git a/crates/runvil-engine/public-api.txt b/crates/runvil-engine/public-api.txt index 074cc3759..ec96af7bf 100644 --- a/crates/runvil-engine/public-api.txt +++ b/crates/runvil-engine/public-api.txt @@ -222,8 +222,8 @@ derives runvil_engine::vfs::ScopeHandle: Clone, Debug derives runvil_engine::vfs::Stat: Clone, Debug, Eq, Hash, PartialEq derives runvil_engine::vfs::Verdict: Clone, Debug, Eq, PartialEq derives runvil_engine::vfs::VfsError: Clone, Debug, Eq, PartialEq -derives runvil_engine::vfs::VfsOp: Clone, Debug, Deserialize, Eq, PartialEq, Serialize -derives runvil_engine::vfs::VfsOutcome: Clone, Debug, Deserialize, Eq, PartialEq, Serialize +derives runvil_engine::vfs::VfsOp: Clone, Debug, Eq, PartialEq +derives runvil_engine::vfs::VfsOutcome: Clone, Debug, Eq, PartialEq derives runvil_engine::vfs::VfsPath: Clone, Debug, Eq, Hash, PartialEq derives runvil_engine::vfs::VfsPathBuf: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd derives runvil_engine::vfs::VfsRef: Clone, Debug, Default @@ -502,6 +502,7 @@ pub fn runvil_engine::vfs::Access::exists(&self, path: &str) -> core::result::Re pub fn runvil_engine::vfs::Access::glob(&self, pattern: &str) -> core::result::Result, runvil_engine::vfs::VfsError> pub fn runvil_engine::vfs::Access::list(&self, path: &str) -> core::result::Result, runvil_engine::vfs::VfsError> pub fn runvil_engine::vfs::Access::mkdir(&self, path: &str, recursive: bool) -> core::result::Result<(), runvil_engine::vfs::VfsError> +pub fn runvil_engine::vfs::Access::perform(&self, op: &runvil_engine::vfs::VfsOp) -> core::result::Result pub fn runvil_engine::vfs::Access::read(&self, path: &str) -> core::result::Result, runvil_engine::vfs::VfsError> pub fn runvil_engine::vfs::Access::read_range(&self, path: &str, offset: u64, len: u64) -> core::result::Result, runvil_engine::vfs::VfsError> pub fn runvil_engine::vfs::Access::read_string(&self, path: &str) -> core::result::Result @@ -570,7 +571,7 @@ pub fn runvil_engine::vfs::VfsRefBuilder::mount(self, prefix: &str, backend: imp pub fn runvil_engine::vfs::VfsRefBuilder::on_op(self, sink: impl core::ops::function::Fn(runvil_engine::vfs::OpEvent<'_>) + core::marker::Send + core::marker::Sync + 'static) -> runvil_engine::vfs::VfsRefBuilder pub fn runvil_engine::vfs::VfsRefBuilder::policy(self, policy: impl runvil_engine::vfs::Policy + core::marker::Sync + 'static) -> runvil_engine::vfs::VfsRefBuilder pub fn runvil_engine::vfs::make_store_error(error: &runvil_engine::vfs::VfsError) -> runvil_engine::Error -pub fn runvil_engine::vfs::perform_vfs_op(access: &runvil_engine::vfs::Access, op: runvil_engine::vfs::VfsOp) -> core::result::Result +pub fn runvil_engine::vfs::perform_vfs_op(access: &runvil_engine::vfs::Access, op: &runvil_engine::vfs::VfsOp) -> core::result::Result pub mod runvil_engine::cancel pub mod runvil_engine::effect pub mod runvil_engine::event @@ -1113,14 +1114,22 @@ pub runvil_engine::vfs::VfsError::Unsupported { .. } pub runvil_engine::vfs::VfsError::Unsupported::detail: alloc::string::String pub runvil_engine::vfs::VfsError::Unsupported::path: alloc::string::String pub runvil_engine::vfs::VfsOp::Append { .. } -pub runvil_engine::vfs::VfsOp::Append::contents: alloc::string::String +pub runvil_engine::vfs::VfsOp::Append::contents: alloc::vec::Vec pub runvil_engine::vfs::VfsOp::Append::path: alloc::string::String +pub runvil_engine::vfs::VfsOp::Copy { .. } +pub runvil_engine::vfs::VfsOp::Copy::from: alloc::string::String +pub runvil_engine::vfs::VfsOp::Copy::to: alloc::string::String pub runvil_engine::vfs::VfsOp::Delete { .. } pub runvil_engine::vfs::VfsOp::Delete::path: alloc::string::String pub runvil_engine::vfs::VfsOp::Exists { .. } pub runvil_engine::vfs::VfsOp::Exists::path: alloc::string::String pub runvil_engine::vfs::VfsOp::Glob { .. } pub runvil_engine::vfs::VfsOp::Glob::pattern: alloc::string::String +pub runvil_engine::vfs::VfsOp::List { .. } +pub runvil_engine::vfs::VfsOp::List::path: alloc::string::String +pub runvil_engine::vfs::VfsOp::Mkdir { .. } +pub runvil_engine::vfs::VfsOp::Mkdir::path: alloc::string::String +pub runvil_engine::vfs::VfsOp::Mkdir::recursive: bool pub runvil_engine::vfs::VfsOp::Read { .. } pub runvil_engine::vfs::VfsOp::Read::end: core::option::Option pub runvil_engine::vfs::VfsOp::Read::path: alloc::string::String @@ -1129,17 +1138,35 @@ pub runvil_engine::vfs::VfsOp::ReadNumbered { .. } pub runvil_engine::vfs::VfsOp::ReadNumbered::end: core::option::Option pub runvil_engine::vfs::VfsOp::ReadNumbered::path: alloc::string::String pub runvil_engine::vfs::VfsOp::ReadNumbered::start: core::option::Option +pub runvil_engine::vfs::VfsOp::ReadRange { .. } +pub runvil_engine::vfs::VfsOp::ReadRange::len: u64 +pub runvil_engine::vfs::VfsOp::ReadRange::offset: u64 +pub runvil_engine::vfs::VfsOp::ReadRange::path: alloc::string::String +pub runvil_engine::vfs::VfsOp::Remove { .. } +pub runvil_engine::vfs::VfsOp::Remove::path: alloc::string::String +pub runvil_engine::vfs::VfsOp::Remove::recursive: bool +pub runvil_engine::vfs::VfsOp::Rename { .. } +pub runvil_engine::vfs::VfsOp::Rename::from: alloc::string::String +pub runvil_engine::vfs::VfsOp::Rename::to: alloc::string::String +pub runvil_engine::vfs::VfsOp::Stat { .. } +pub runvil_engine::vfs::VfsOp::Stat::path: alloc::string::String pub runvil_engine::vfs::VfsOp::StrReplace { .. } pub runvil_engine::vfs::VfsOp::StrReplace::new: alloc::string::String pub runvil_engine::vfs::VfsOp::StrReplace::old: alloc::string::String pub runvil_engine::vfs::VfsOp::StrReplace::path: alloc::string::String pub runvil_engine::vfs::VfsOp::Write { .. } -pub runvil_engine::vfs::VfsOp::Write::contents: alloc::string::String +pub runvil_engine::vfs::VfsOp::Write::contents: alloc::vec::Vec pub runvil_engine::vfs::VfsOp::Write::path: alloc::string::String pub runvil_engine::vfs::VfsOutcome::Bool(..) pub runvil_engine::vfs::VfsOutcome::Bool::0: bool +pub runvil_engine::vfs::VfsOutcome::Bytes(..) +pub runvil_engine::vfs::VfsOutcome::Bytes::0: alloc::vec::Vec +pub runvil_engine::vfs::VfsOutcome::Entries(..) +pub runvil_engine::vfs::VfsOutcome::Entries::0: alloc::vec::Vec pub runvil_engine::vfs::VfsOutcome::Paths(..) pub runvil_engine::vfs::VfsOutcome::Paths::0: alloc::vec::Vec +pub runvil_engine::vfs::VfsOutcome::Stat(..) +pub runvil_engine::vfs::VfsOutcome::Stat::0: runvil_engine::vfs::Stat pub runvil_engine::vfs::VfsOutcome::Text(..) pub runvil_engine::vfs::VfsOutcome::Text::0: alloc::string::String pub runvil_engine::vfs::VfsOutcome::Unit diff --git a/crates/runvil-engine/src/lib.rs b/crates/runvil-engine/src/lib.rs index 60882d964..2d037c0f0 100644 --- a/crates/runvil-engine/src/lib.rs +++ b/crates/runvil-engine/src/lib.rs @@ -136,14 +136,12 @@ pub mod prompt { pub mod vfs { //! A run's files: the virtual filesystem the caller gives a run for - //! its tool calls, the policy that decides what they may change, and - //! the operations of the run's own stores, the one a run starts with - //! and one for each prompt it executes, which sit outside that - //! filesystem and which the caller reaches only through the view of - //! a store effect. - - pub use runvil_lua::VfsOp; - pub use runvil_lua::VfsOutcome; + //! its tool calls, the policy that decides what they may change, the + //! file operations as values with what each returns, and the run's + //! own stores, the one a run starts with and one for each prompt it + //! executes, which sit outside that filesystem and which the caller + //! reaches only through the view of a store effect. + pub use runvil_lua::make_store_error; pub use runvil_runtime::perform_vfs_op; pub use runvil_vfs::Access; @@ -168,6 +166,8 @@ pub mod vfs { pub use runvil_vfs::Vfs; pub use runvil_vfs::VfsAccess; pub use runvil_vfs::VfsError; + pub use runvil_vfs::VfsOp; + pub use runvil_vfs::VfsOutcome; pub use runvil_vfs::VfsPath; pub use runvil_vfs::VfsPathBuf; pub use runvil_vfs::VfsRef; diff --git a/crates/runvil-engine/tests/suite/support/scenario.rs b/crates/runvil-engine/tests/suite/support/scenario.rs index 441b25360..c62b40383 100644 --- a/crates/runvil-engine/tests/suite/support/scenario.rs +++ b/crates/runvil-engine/tests/suite/support/scenario.rs @@ -341,7 +341,7 @@ impl Driver { fn answer(&mut self, effect: Effect) -> TestResult { Ok(match effect { - Effect::Vfs { access, op, .. } => EffectAnswer::Vfs(perform_vfs_op(&access, op)), + Effect::Vfs { access, op, .. } => EffectAnswer::Vfs(perform_vfs_op(&access, &op)), Effect::Timer { .. } => EffectAnswer::Timer, Effect::Render { offered, .. } => EffectAnswer::Render(offered), Effect::Chat { binding, .. } => { diff --git a/crates/runvil-engine/tests/suite/vfs.rs b/crates/runvil-engine/tests/suite/vfs.rs index 0504a553b..4cf1ed07d 100644 --- a/crates/runvil-engine/tests/suite/vfs.rs +++ b/crates/runvil-engine/tests/suite/vfs.rs @@ -60,7 +60,7 @@ fn drive(vfs: &VfsRef, source: &str, tool: Perform) -> TestResult { for IssuedEffect { id, effect, .. } in effects { let answer = match effect { Effect::Vfs { access, op, .. } => { - let outcome = perform_vfs_op(&access, op); + let outcome = perform_vfs_op(&access, &op); views.push(access); EffectAnswer::Vfs(outcome) } @@ -241,11 +241,11 @@ fn a_store_view_is_the_callers_one_way_to_the_runs_store_and_refuses_every_opera let ops = [ VfsOp::Write { path: path(), - contents: "late".to_owned(), + contents: b"late".to_vec(), }, VfsOp::Append { path: path(), - contents: "late".to_owned(), + contents: b"late".to_vec(), }, VfsOp::Read { path: path(), @@ -271,7 +271,7 @@ fn a_store_view_is_the_callers_one_way_to_the_runs_store_and_refuses_every_opera assert_eq!(ran.views.len(), 2, "the write's view and the read's"); for view in &ran.views { for op in &ops { - let refused = perform_vfs_op(view, op.clone()); + let refused = perform_vfs_op(view, op); assert!( matches!(refused, Err(VfsError::ScopeEnded { .. })), "{op:?}: {refused:?}" diff --git a/crates/runvil-internal/lua/src/engine_globals_store.rs b/crates/runvil-internal/lua/src/engine_globals_store.rs index a35c2f38f..25353a96d 100644 --- a/crates/runvil-internal/lua/src/engine_globals_store.rs +++ b/crates/runvil-internal/lua/src/engine_globals_store.rs @@ -1,14 +1,11 @@ -//! Store operations: the body of each `store.*` operation over a store -//! view, the line bounds of the two reads, and the model-facing message of -//! each store failure. +//! Store failures: the failure a store operation's error becomes, and the +//! model-facing message of each one. `Access::perform` of `runvil-vfs` +//! runs the operation itself. -use std::fmt::Write as _; - -use runvil_vfs::{Access, VfsError}; +use runvil_vfs::{VfsError, VfsOp}; use crate::error::Error; use crate::error_value::make_store_error; -use crate::protocol::{VfsOp, VfsOutcome}; /// The store failure `cause` with `message` in place of its own text. #[must_use] @@ -18,15 +15,6 @@ pub fn make_store_failure_error(cause: &VfsError, message: String) -> Error { error } -/// Whether a store read prefixes each line with its absolute line number. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -enum LineNumbers { - /// The file's text verbatim. - Omitted, - /// Each line right-aligned behind its number and `"| "`. - Prefixed, -} - /// The model-facing message for a failed store operation: what failed and, /// when there is a fix, how to make it, so the text a model reads names /// both. The operation supplies the wording its call surface promises (a @@ -98,153 +86,3 @@ pub fn store_error_message(op: &VfsOp, error: &VfsError) -> String { _ => "store operation failed".to_owned(), } } - -/// Executes one validated store operation against the store view `view`: -/// what the request a `store.*` call yields comes to once it is performed. -/// -/// # Errors -/// Returns the [`VfsError`] the operation produces: path or pattern -/// validation, not-found, anchor, range, or conflict. -pub fn run_store_op(view: &Access, op: VfsOp) -> std::result::Result { - match op { - VfsOp::Write { path, contents } => view - .write(&path, contents.as_bytes()) - .map(|()| VfsOutcome::Unit), - VfsOp::Append { path, contents } => view - .append(&path, contents.as_bytes()) - .map(|()| VfsOutcome::Unit), - VfsOp::Read { path, start, end } => { - read_store(view, &path, start, end).map(VfsOutcome::Text) - } - VfsOp::ReadNumbered { path, start, end } => { - read_store_numbered(view, &path, start, end).map(VfsOutcome::Text) - } - VfsOp::StrReplace { path, old, new } => view - .str_replace(&path, &old, &new) - .map(|()| VfsOutcome::Unit), - VfsOp::Delete { path } => view.remove(&path, false).map(|_| VfsOutcome::Unit), - VfsOp::Glob { pattern } => view.glob(&pattern).map(VfsOutcome::Paths), - VfsOp::Exists { path } => view.exists(&path).map(VfsOutcome::Bool), - } -} - -/// Reads the file at `path` under the optional line bounds `store.read` -/// and `store.read_numbered` share, numbering lines as `numbers` says. -/// -/// No `start` reads the whole file; a present `start` slices a 1-based -/// inclusive line range. A negative bound converts to 0, which the range -/// validation rejects with the same error a zero bound produces, and an -/// `end` without a `start` is refused rather than silently ignored. -fn read_store_bounded( - view: &Access, - path: &str, - start: Option, - end: Option, - numbers: LineNumbers, -) -> std::result::Result { - let render: fn(&[&str], usize) -> String = match numbers { - LineNumbers::Prefixed => number_lines_from, - LineNumbers::Omitted => |lines, _| lines.join("\n"), - }; - match start { - None if end.is_some() => Err(VfsError::InvalidRange { - path: path.to_owned(), - reason: "start is required when end is given", - }), - None if numbers == LineNumbers::Omitted => view.read_string(path), - None => with_read_range(view, path, 1, None, render), - Some(start) => { - let start = usize::try_from(start).unwrap_or(0); - let end = end.map(|line| usize::try_from(line).unwrap_or(0)); - with_read_range(view, path, start, end, render) - } - } -} - -/// Runs the `store.read` operation. -fn read_store( - view: &Access, - path: &str, - start: Option, - end: Option, -) -> std::result::Result { - read_store_bounded(view, path, start, end, LineNumbers::Omitted) -} - -/// Runs the `store.read_numbered` operation. -fn read_store_numbered( - view: &Access, - path: &str, - start: Option, - end: Option, -) -> std::result::Result { - read_store_bounded(view, path, start, end, LineNumbers::Prefixed) -} - -/// Reads and resolves one line range while its owned contents remain live. -fn with_read_range( - view: &Access, - path: &str, - start: usize, - end: Option, - render: impl FnOnce(&[&str], usize) -> String, -) -> std::result::Result { - let contents = view.read_string(path)?; - let lines: Vec<&str> = contents.lines().collect(); - let Some((start, end)) = resolve_line_range(path, lines.len(), start, end)? else { - return Ok(String::new()); - }; - Ok(render(&lines[start - 1..end], start)) -} - -/// Resolves 1-based inclusive bounds against `line_count` into the -/// effective `(start, end)`, or `None` when the range falls entirely past -/// the last line. Evaluation order is fixed: a `start` below 1 is an -/// error; a `start` past the last line reads as empty; an omitted `end` -/// means the last line, and a given `end` clamps down to it; an `end` -/// before `start` at that point is an error. -fn resolve_line_range( - path: &str, - line_count: usize, - start: usize, - end: Option, -) -> std::result::Result, VfsError> { - if start == 0 { - return Err(VfsError::InvalidRange { - path: path.to_owned(), - reason: "start must be at least 1", - }); - } - if start > line_count { - return Ok(None); - } - let end = end.unwrap_or(line_count).min(line_count); - if end < start { - return Err(VfsError::InvalidRange { - path: path.to_owned(), - reason: "end must not be before start", - }); - } - Ok(Some((start, end))) -} - -/// Renders `lines` numbered absolutely from `start`, each number -/// right-aligned to the width of the largest emitted number, followed by -/// `"| "`; lines are joined with `"\n"` and there is no trailing newline. -fn number_lines_from(lines: &[&str], start: usize) -> String { - if lines.is_empty() { - return String::new(); - } - let last = start + lines.len() - 1; - let width = last.to_string().len(); - let mut out = String::new(); - for (index, line) in lines.iter().enumerate() { - if index > 0 { - out.push('\n'); - } - let number = start + index; - // Writing to a String is infallible, so the result is discarded. - let _ = write!(out, "{number:>width$}| {line}"); - } - out -} diff --git a/crates/runvil-internal/lua/src/lib.rs b/crates/runvil-internal/lua/src/lib.rs index 73022c6e6..2823bdc7f 100644 --- a/crates/runvil-internal/lua/src/lib.rs +++ b/crates/runvil-internal/lua/src/lib.rs @@ -61,8 +61,8 @@ //! //! Most of this crate's public items exist for `runvil-runtime`'s //! executor, which drives the VM and the coroutine protocol; the facade -//! re-exports the store protocol ([`VfsOp`], [`VfsOutcome`], -//! [`make_store_error`]) and the roster entry ([`RosterEntry`]); +//! re-exports the store failure's constructor ([`make_store_error`]) and +//! the roster entry ([`RosterEntry`]); //! `crates/runvil-engine/public-api.txt` holds the full surface. The //! `test_support` module, built for this crate's tests and under the //! `test-support` feature, holds what tests reach beyond that surface. @@ -140,9 +140,7 @@ pub use crate::collection::render_item; pub use crate::compactors::{OverflowReason, UsageAnchor, output_reserve, precheck}; pub use crate::dispatch::{ScriptReport, ToolDispatch, prepare_dispatch, prepare_model_dispatch}; pub use crate::engine_globals::install_ui; -pub use crate::engine_globals_store::{ - make_store_failure_error, run_store_op, store_error_message, -}; +pub use crate::engine_globals_store::{make_store_failure_error, store_error_message}; pub use crate::error::{ QuotaResource, make_context_exhausted_error, make_internal_at_error, make_internal_error, make_lua_quota_error, make_lua_runtime_error, make_task_canceled_error, @@ -160,7 +158,7 @@ pub use crate::prose::ProseState; pub use crate::protocol::{ AdhocToolOutcome, Answer, Blocked, ChatOutcome, ChatResult, ContentPart, MessageContent, MessageRecord, ModelCall, NonEmpty, RecordRole, Request, TaskDelivery, TaskPhase, TaskStatus, - ToolCallOutcome, ToolCallRecord, VfsOp, VfsOutcome, YieldParse, + ToolCallOutcome, ToolCallRecord, YieldParse, }; pub use crate::scope::{OfferMode, OfferedTool, Offers, RenderedTools, ToolCallCounts}; pub use crate::section::{ diff --git a/crates/runvil-internal/lua/src/protocol.rs b/crates/runvil-internal/lua/src/protocol.rs index 0587cb839..c607a890b 100644 --- a/crates/runvil-internal/lua/src/protocol.rs +++ b/crates/runvil-internal/lua/src/protocol.rs @@ -10,7 +10,7 @@ //! per-message contract. //! //! The submodules split the protocol along that boundary: `request` the -//! request vocabulary (the [`Request`] and [`VfsOp`] enums), `record` the +//! request vocabulary (the [`Request`] enum), `record` the //! message-record types a chat request is built from and their //! validation, `answer` the answer vocabulary (the [`Answer`] enum and its //! payload types), `parse` the yield-to-request validation, and `render` @@ -28,11 +28,10 @@ mod tests; pub use answer::{ Answer, Blocked, ChatOutcome, ChatResult, TaskDelivery, TaskPhase, TaskStatus, ToolCallOutcome, - VfsOutcome, }; pub use non_empty::NonEmpty; pub use parse::YieldParse; pub(crate) use record::parse_record; pub use record::{ContentPart, MessageContent, MessageRecord, RecordRole, ToolCallRecord}; pub(crate) use render::{Retained, render_envelope}; -pub use request::{AdhocToolOutcome, ModelCall, Request, VfsOp}; +pub use request::{AdhocToolOutcome, ModelCall, Request}; diff --git a/crates/runvil-internal/lua/src/protocol/answer.rs b/crates/runvil-internal/lua/src/protocol/answer.rs index 174b68cc1..ed0d066b1 100644 --- a/crates/runvil-internal/lua/src/protocol/answer.rs +++ b/crates/runvil-internal/lua/src/protocol/answer.rs @@ -4,37 +4,12 @@ use runvil_types::error::ErrorCode; use runvil_types::ids::TaskId; use runvil_types::metrics::ToolCallEvent; +use runvil_vfs::VfsOutcome; use crate::bindings::ToolOutputKind; use crate::compactors::OverflowReason; use crate::error::{Error, Result, tool}; -/// The result of one [`VfsOp`](super::VfsOp) run against a store view of -/// the run. -/// -/// The Lua program receives it as the return value of its `store.*` call. -/// Operations that change the store, such as writes and deletes, produce -/// `Unit`, which the program receives as nil. -/// -/// The run log records a successful store answer as this value, so its -/// JSON form is part of the log format. In serde's externally tagged form, -/// `Unit` is the bare string `"Unit"` and every other variant is a one-key -/// object, such as `{"Text": "..."}`, `{"Paths": ["a.txt"]}`, or -/// `{"Bool": true}`. -#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] -#[non_exhaustive] -pub enum VfsOutcome { - /// The operation succeeded, and the program receives nil. - Unit, - /// The text that `read` or `read_numbered` returns: the whole file, or - /// only the requested line range. - Text(String), - /// The paths that match a `glob` pattern, in sorted order. - Paths(Vec), - /// Whether the path exists, for `exists`. - Bool(bool), -} - /// One dispatched `tools.call`'s successful answer: a bound tool's output, /// classified by the binding's declared [`ToolOutputKind`] so the envelope /// resumes the right Lua shape (plain text as a Lua string, structured @@ -318,6 +293,8 @@ pub enum Answer { /// texts than calls means the scheduler stopped at the call after the /// last one answered. ToolCallsResult(Vec), - /// The outcome of a `store` request: the operation's return value. + /// The outcome of a `store` request, which the call returns: nil for + /// an operation that changes the store, the text of a read, the paths + /// of a glob, or the answer of an existence check. Store(VfsOutcome), } diff --git a/crates/runvil-internal/lua/src/protocol/parse/store.rs b/crates/runvil-internal/lua/src/protocol/parse/store.rs index 716d095a2..25bcc2561 100644 --- a/crates/runvil-internal/lua/src/protocol/parse/store.rs +++ b/crates/runvil-internal/lua/src/protocol/parse/store.rs @@ -2,8 +2,9 @@ //! arguments. use mlua::Value; +use runvil_vfs::VfsOp; -use crate::protocol::{Request, VfsOp}; +use crate::protocol::Request; use super::{FieldFailure, call_error, call_string}; @@ -38,17 +39,18 @@ fn call_optional_line( } /// Parses a `store` request: the operation name and its author-supplied -/// arguments. Every wrong shape is the call's error. +/// arguments. Every wrong shape is the call's error. The contents of a +/// write or an append are text, and the operation holds the text's bytes. pub(super) fn parse_store(table: &mlua::Table) -> std::result::Result { let op = call_string(table, "store_op")?; let op = match op.as_str() { "write" => VfsOp::Write { path: call_string(table, "path")?, - contents: call_string(table, "contents")?, + contents: call_string(table, "contents")?.into_bytes(), }, "append" => VfsOp::Append { path: call_string(table, "path")?, - contents: call_string(table, "contents")?, + contents: call_string(table, "contents")?.into_bytes(), }, "read" => VfsOp::Read { path: call_string(table, "path")?, diff --git a/crates/runvil-internal/lua/src/protocol/render.rs b/crates/runvil-internal/lua/src/protocol/render.rs index 152b36f6a..6b61601bc 100644 --- a/crates/runvil-internal/lua/src/protocol/render.rs +++ b/crates/runvil-internal/lua/src/protocol/render.rs @@ -3,12 +3,13 @@ use mlua::{Lua, LuaSerdeExt, MultiValue, Table, Value}; use runvil_types::error::Error; +use runvil_vfs::VfsOutcome; use crate::error::authored; use crate::error_value::error_table; use crate::tools::adhoc_handler; -use super::answer::{Answer, TaskDelivery, TaskPhase, TaskStatus, ToolCallOutcome, VfsOutcome}; +use super::answer::{Answer, TaskDelivery, TaskPhase, TaskStatus, ToolCallOutcome}; /// An answer's typed error and the error table rendered from it. /// [`SectionVm::resume_block_coro_answer`](crate::SectionVm::resume_block_coro_answer) @@ -60,14 +61,17 @@ fn task_id_sequence(lua: &Lua, tasks: &[runvil_types::ids::TaskId]) -> mlua::Res Ok(sequence) } -/// Renders a store op's return value: nil for the mutating ops, the text -/// for reads, a sequence table for glob, a boolean for exists. +/// Renders a store op's return value: the text for reads, a sequence +/// table for glob, a boolean for exists, and nil for the mutating ops. No +/// `store` function returns a stat, a listing, or bytes, so an outcome of +/// those kinds renders as nil too. fn store_value(lua: &Lua, outcome: VfsOutcome) -> mlua::Result { Ok(match outcome { - VfsOutcome::Unit => Value::Nil, VfsOutcome::Text(text) => Value::String(lua.create_string(&text)?), VfsOutcome::Paths(paths) => Value::Table(lua.create_sequence_from(paths)?), VfsOutcome::Bool(exists) => Value::Boolean(exists), + // `Unit`, and every outcome no `store` function returns. + _ => Value::Nil, }) } diff --git a/crates/runvil-internal/lua/src/protocol/request.rs b/crates/runvil-internal/lua/src/protocol/request.rs index 99930ee51..2dd8eb507 100644 --- a/crates/runvil-internal/lua/src/protocol/request.rs +++ b/crates/runvil-internal/lua/src/protocol/request.rs @@ -1,6 +1,7 @@ //! The request vocabulary: the validated suspending Engine calls a shim can -//! yield and the store operations they hold. The message-record types the -//! chat request is built from are in `record`. +//! yield. A store call holds its operation as a `VfsOp` of `runvil-vfs`. +//! The message-record types the chat request is built from are in +//! `record`. //! //! An adhoc tool call spans two requests. The first is the ordinary //! [`Request::ToolCall`], which the scheduler answers with the handler. @@ -14,6 +15,7 @@ use std::time::Duration; use runvil_model_client::model::ModelBinding; use runvil_types::ids::TaskId; +use runvil_vfs::VfsOp; use super::non_empty::NonEmpty; use super::record::ToolCallRecord; @@ -233,7 +235,10 @@ pub enum Request { /// `store.*(...)`: one run-scoped store operation as a leaf yield. /// Every operation takes this path, with no inline fast path. Store { - /// The validated operation and its author-supplied arguments. + /// The validated operation and its author-supplied arguments: one + /// of the eight operations a `store` function names. The parse + /// checks each argument's shape, and the operation checks line + /// ranges when it runs. op: VfsOp, }, } @@ -267,92 +272,3 @@ pub enum AdhocToolOutcome { /// at the call site, so no error crosses the boundary here. Raised, } - -/// One `store.*` call from a prompt script: which operation it is and the -/// arguments the script passed. -/// -/// The parse checks each argument's shape; the operation checks line -/// ranges when it runs. -/// -/// This type carries the full arguments of one of the eight `store.*` -/// calls. The separate `vfs::Op` names only the kind of file operation -/// (`Read`, `Write`, `Rename`, and so on), which a policy matches on and a -/// watcher is told about. -/// -/// The read bounds are `i64`. A negative bound converts to 0 when the -/// operation runs, so the range check rejects it with the same error a -/// zero bound produces. -/// -/// The type holds only plain data, so an effect record can carry an -/// operation through serde intact. -#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] -#[non_exhaustive] -pub enum VfsOp { - /// `store.write(path, contents)`: creates or overwrites the file at - /// `path` with `contents`. - Write { - /// The author-supplied logical path. - path: String, - /// The author-supplied file contents. - contents: String, - }, - /// `store.append(path, contents)`: appends `contents` to the file at - /// `path`, creating the file if it is absent. - Append { - /// The author-supplied logical path. - path: String, - /// The author-supplied text to append. - contents: String, - }, - /// `store.read(path, start?, end?)`: reads the file at `path` as text. - /// - /// With both bounds omitted, it reads the whole file. With `start`, it - /// reads a 1-based inclusive line range. An `end` given alone is an - /// error. - Read { - /// The author-supplied logical path. - path: String, - /// The optional 1-based first line. - start: Option, - /// The optional 1-based last line. - end: Option, - }, - /// `store.read_numbered(path, start?, end?)`: reads like `store.read` - /// and prefixes each line with its absolute line number. The bounds - /// work the same way. - ReadNumbered { - /// The author-supplied logical path. - path: String, - /// The optional 1-based first line. - start: Option, - /// The optional 1-based last line. - end: Option, - }, - /// `store.str_replace(path, old, new)`: replaces `old` with `new` in the - /// file at `path`. - StrReplace { - /// The author-supplied logical path. - path: String, - /// The anchor text, required to occur exactly once. - old: String, - /// The replacement text. - new: String, - }, - /// `store.delete(path)`: removes the file or empty directory at `path`; - /// a directory that still holds entries is refused. Deleting a missing - /// path succeeds. - Delete { - /// The author-supplied logical path. - path: String, - }, - /// `store.glob(pattern)`: lists the paths that match `pattern`. - Glob { - /// The author-supplied glob pattern. - pattern: String, - }, - /// `store.exists(path)`: reports whether `path` exists. - Exists { - /// The author-supplied logical path. - path: String, - }, -} diff --git a/crates/runvil-internal/lua/src/test_vm.rs b/crates/runvil-internal/lua/src/test_vm.rs index d54a8ee2a..99c87c42c 100644 --- a/crates/runvil-internal/lua/src/test_vm.rs +++ b/crates/runvil-internal/lua/src/test_vm.rs @@ -26,7 +26,7 @@ use crate::error::{Result, UNNAMED_FILE, make_lua_runtime_error}; use crate::tests::recording::null_emitter; use crate::{ Answer, CoroStep, LuaBlockResult, LuaProgram, OfferedTool, Request, RosterEntry, SectionRead, - SectionVm, ToolSet, YieldParse, make_store_failure_error, run_store_op, store_error_message, + SectionVm, ToolSet, YieldParse, make_store_failure_error, store_error_message, }; /// The one guard-nonce seed of every test VM. @@ -111,13 +111,13 @@ pub(crate) fn drive_block( CoroStep::Yielded(thread, values) => (thread, values), }; let answer = match vm.request_from_yield(&values) { - YieldParse::Request(Request::Store { op }) => run_store_op(&view, op.clone()) - .map(Answer::Store) - .map_err(|cause| { + YieldParse::Request(Request::Store { op }) => { + view.perform(&op).map(Answer::Store).map_err(|cause| { let failure = make_store_failure_error(&cause, store_error_message(&op, &cause)); place(failure, UNNAMED_FILE, vm.call_line()) - }), + }) + } YieldParse::Request(other) => { panic!("the block driver answers store requests alone, got {other:?}") } diff --git a/crates/runvil-internal/lua/src/tests.rs b/crates/runvil-internal/lua/src/tests.rs index 3e5839717..939c32e68 100644 --- a/crates/runvil-internal/lua/src/tests.rs +++ b/crates/runvil-internal/lua/src/tests.rs @@ -12,7 +12,7 @@ use mlua::{Lua, Value}; use runvil_model_client::model::ModelSet; use runvil_types::emitter::Emitter; use runvil_types::tools::{ToolId, ToolInfo}; -use runvil_vfs::Access; +use runvil_vfs::{Access, VfsOp, VfsOutcome}; use serde_json::{Value as Json, json}; use self::recording::{Observation, Recorder, boundary, null_emitter}; diff --git a/crates/runvil-internal/lua/src/tests/store_errors.rs b/crates/runvil-internal/lua/src/tests/store_errors.rs index ea0a2befb..5171fca87 100644 --- a/crates/runvil-internal/lua/src/tests/store_errors.rs +++ b/crates/runvil-internal/lua/src/tests/store_errors.rs @@ -286,7 +286,7 @@ fn store_error_values_carry_reason_fields_and_message_for_each_reason() { case.error ); }; - let op = crate::VfsOp::Read { + let op = VfsOp::Read { path: "x".to_owned(), start: None, end: None, @@ -315,10 +315,10 @@ fn store_error_messages_use_the_operations_wording() { path: "a**b".to_owned(), reason: PathReason::Wildcard, }; - let glob = crate::VfsOp::Glob { + let glob = VfsOp::Glob { pattern: "a**b".to_owned(), }; - let read = crate::VfsOp::Read { + let read = VfsOp::Read { path: "a**b".to_owned(), start: None, end: None, @@ -343,7 +343,7 @@ fn a_raised_store_error_renders_an_integer_count_and_the_prose() { anchor: "TODO".to_owned(), count: 3, }; - let op = crate::VfsOp::StrReplace { + let op = VfsOp::StrReplace { path: "notes.md".to_owned(), old: "TODO".to_owned(), new: "DONE".to_owned(), diff --git a/crates/runvil-internal/runtime/src/error.rs b/crates/runvil-internal/runtime/src/error.rs index ac896e9bc..6660ec98e 100644 --- a/crates/runvil-internal/runtime/src/error.rs +++ b/crates/runvil-internal/runtime/src/error.rs @@ -175,7 +175,7 @@ pub(crate) fn make_files_error(cause: &runvil_vfs::VfsError) -> Error { /// One store operation's failure: the store's code and facts, and the /// model-facing message rendered with the operation for its wording. -pub(crate) fn make_store_op_error(op: &crate::lua::VfsOp, cause: &runvil_vfs::VfsError) -> Error { +pub(crate) fn make_store_op_error(op: &runvil_vfs::VfsOp, cause: &runvil_vfs::VfsError) -> Error { runvil_lua::make_store_failure_error(cause, crate::lua::store_error_message(op, cause)) } diff --git a/crates/runvil-internal/runtime/src/error/tests.rs b/crates/runvil-internal/runtime/src/error/tests.rs index 0443ff2e0..dcddb5000 100644 --- a/crates/runvil-internal/runtime/src/error/tests.rs +++ b/crates/runvil-internal/runtime/src/error/tests.rs @@ -269,7 +269,7 @@ fn a_store_failure_takes_the_stores_code_and_facts_under_its_own_message() { anchor: "TODO".to_owned(), count: 2, }; - let op = crate::lua::VfsOp::StrReplace { + let op = runvil_vfs::VfsOp::StrReplace { path: "notes.md".to_owned(), old: "TODO".to_owned(), new: "DONE".to_owned(), diff --git a/crates/runvil-internal/runtime/src/execute.rs b/crates/runvil-internal/runtime/src/execute.rs index 57a7a8ce3..938f05da7 100644 --- a/crates/runvil-internal/runtime/src/execute.rs +++ b/crates/runvil-internal/runtime/src/execute.rs @@ -59,19 +59,17 @@ pub use run::{ Effect, EffectAnswer, EffectId, IssuedEffect, PackToolSets, Round, Run, Step, ToolCallOrigin, ToolCaller, }; -// The store vocabulary a `Vfs` effect holds and its answer returns, for -// the Engine's own store handling; other crates name it from `runvil_lua`. -use crate::lua::{VfsOp, VfsOutcome}; +use runvil_vfs::{Access, VfsError, VfsOp, VfsOutcome}; /// Performs the store operation of an [`Effect::Vfs`] and returns its answer. /// /// `access` is the store view the effect carries: a view of the calling /// chain's store under the chain's identity, made when the effect is /// dispatched. -/// Each [`VfsOp`] maps onto one `Access` call on that view, so the caller -/// answers a `Vfs` effect exactly as the Engine's own test drivers do. -/// Line bounds arrive as `i64` and convert to `usize`. A read that gives -/// an `end` and omits `start` is refused as an invalid range. +/// The function runs `op` with [`Access::perform`] on that view, so the +/// caller answers a `Vfs` effect exactly as the Engine's own test drivers +/// do. Line bounds arrive as `i64` and convert to `usize`. A read that +/// gives an `end` and omits `start` is refused as an invalid range. /// /// The function is synchronous because every file operation is: the /// storage underneath is synchronous by nature. The caller runs it @@ -83,11 +81,8 @@ use crate::lua::{VfsOp, VfsOutcome}; /// validation, not-found, anchor, range, or conflict). /// When the caller resumes the run with that answer, the Engine raises /// the failure at the prompt author's call site. -pub fn perform_vfs_op( - access: &runvil_vfs::Access, - op: VfsOp, -) -> std::result::Result { - crate::lua::run_store_op(access, op) +pub fn perform_vfs_op(access: &Access, op: &VfsOp) -> std::result::Result { + access.perform(op) } #[cfg(test)] diff --git a/crates/runvil-internal/runtime/src/execute/run.rs b/crates/runvil-internal/runtime/src/execute/run.rs index e074ba041..c421ea903 100644 --- a/crates/runvil-internal/runtime/src/execute/run.rs +++ b/crates/runvil-internal/runtime/src/execute/run.rs @@ -8,7 +8,8 @@ //! [`ToolCallOrigin`] and [`ToolCaller`] it re-exports from //! `runvil-types` - comes from the `effect` child module and is //! re-exported here. The records of effects and answers stay in that -//! module; the caller reads them as JSON. +//! module, with the record forms of a file operation and its outcome in +//! `vfs_record`; the caller reads them as JSON. use std::fmt; use std::sync::Arc; @@ -18,6 +19,7 @@ use runvil_types::event::Event; use runvil_types::ids::Provenance; mod effect; +mod vfs_record; #[cfg(test)] pub(crate) use effect::{AnswerRecord, ChatAnswerRecord, EffectRecord}; diff --git a/crates/runvil-internal/runtime/src/execute/run/effect-tests.rs b/crates/runvil-internal/runtime/src/execute/run/effect-tests.rs index 0c83b9c0c..766fafb9b 100644 --- a/crates/runvil-internal/runtime/src/execute/run/effect-tests.rs +++ b/crates/runvil-internal/runtime/src/execute/run/effect-tests.rs @@ -442,7 +442,7 @@ fn every_kinds_public_record_is_json_that_round_trips_exactly() { access: access(), op: VfsOp::Write { path: "note.md".to_owned(), - contents: "hello".to_owned(), + contents: b"hello".to_vec(), }, }, Effect::Timer { diff --git a/crates/runvil-internal/runtime/src/execute/run/effect.rs b/crates/runvil-internal/runtime/src/execute/run/effect.rs index 3c5dc922d..b5474fe6a 100644 --- a/crates/runvil-internal/runtime/src/execute/run/effect.rs +++ b/crates/runvil-internal/runtime/src/execute/run/effect.rs @@ -31,11 +31,10 @@ use runvil_types::ids::{ChainId, RoundId}; use runvil_types::packs::PackId; use runvil_types::tools::{OutputTrust, ToolId, ToolInfo, ToolOutput}; pub use runvil_types::tools::{ToolCallOrigin, ToolCaller}; -use runvil_vfs::{Access, VfsError}; +use runvil_vfs::{Access, VfsError, VfsOp, VfsOutcome}; use serde::{Deserialize, Serialize}; use serde_json::Value; -use crate::lua::{VfsOp, VfsOutcome}; use crate::model::{Completion, CompletionResult, Message, ToolSchema}; use crate::model::{ModelBinding, Temperature}; @@ -420,7 +419,14 @@ pub(crate) enum EffectRecord { /// records that name one store, in order, are every operation on /// that store. store: ChainId, - /// The validated operation. + /// The validated operation, written in its record form: one + /// object keyed by the operation's name. The bytes of a write or + /// an append are text under `contents` when they are UTF-8, and + /// hex under `contents_hex` otherwise. + #[serde( + serialize_with = "super::vfs_record::serialize_op", + deserialize_with = "super::vfs_record::deserialize_op" + )] op: VfsOp, }, /// One sleep. @@ -524,8 +530,17 @@ pub(crate) enum AnswerRecord { /// The tool call's outcome. ToolCall(std::result::Result), /// The outcome of the operation on the effect's store view: the - /// [`VfsOutcome`] itself on success, or the failure's record. - Vfs(std::result::Result), + /// whole [`VfsOutcome`] on success, written in its record form, or + /// the failure's record. `Unit` is the bare string `"Unit"`, and + /// every other outcome is a one-key object, such as + /// `{"Text":"..."}`, `{"Paths":["a.txt"]}`, or `{"Bool":true}`. + Vfs( + #[serde( + serialize_with = "super::vfs_record::serialize_answer", + deserialize_with = "super::vfs_record::deserialize_answer" + )] + std::result::Result, + ), /// The timer fired. Timer, /// The caller gave up on the effect and dropped it. diff --git a/crates/runvil-internal/runtime/src/execute/run/tests-inbox.rs b/crates/runvil-internal/runtime/src/execute/run/tests-inbox.rs index 47ba44ebd..976c463df 100644 --- a/crates/runvil-internal/runtime/src/execute/run/tests-inbox.rs +++ b/crates/runvil-internal/runtime/src/execute/run/tests-inbox.rs @@ -8,9 +8,9 @@ use runvil_prompt::test_support::{PromptSource, prompt}; use runvil_types::ids::{ChainId, TaskId}; +use runvil_vfs::VfsOutcome; use super::*; -use crate::lua::VfsOutcome; /// The main chain's task, `0`. pub(super) fn main_task() -> TaskId { diff --git a/crates/runvil-internal/runtime/src/execute/run/tests-reply.rs b/crates/runvil-internal/runtime/src/execute/run/tests-reply.rs index 0e014f074..ed9c3c466 100644 --- a/crates/runvil-internal/runtime/src/execute/run/tests-reply.rs +++ b/crates/runvil-internal/runtime/src/execute/run/tests-reply.rs @@ -15,12 +15,12 @@ use std::num::NonZeroUsize; use runvil_prompt::test_support::prompt; use runvil_types::error::ErrorFact; use runvil_types::ids::{AbandonReason, ChainId, TaskId}; +use runvil_vfs::VfsOutcome; use serde_json::json; use super::inbox::{answer_store, done, main_task, pending, run_of_sections}; use super::*; use crate::execute::RunLimits; -use crate::lua::VfsOutcome; /// The `index`th task the main chain spawned. fn spawned(index: u32) -> TaskId { diff --git a/crates/runvil-internal/runtime/src/execute/run/tests-send.rs b/crates/runvil-internal/runtime/src/execute/run/tests-send.rs index fc2ac9717..92be67670 100644 --- a/crates/runvil-internal/runtime/src/execute/run/tests-send.rs +++ b/crates/runvil-internal/runtime/src/execute/run/tests-send.rs @@ -9,11 +9,11 @@ use runvil_types::error::ErrorFact; use runvil_types::ids::{ChainId, TaskId}; +use runvil_vfs::VfsOutcome; use serde_json::json; use super::inbox::{answer_store, done, main_task, pending, run_of_sections}; use super::*; -use crate::lua::VfsOutcome; /// The `index`th task the main chain spawned. fn spawned(index: u32) -> TaskId { diff --git a/crates/runvil-internal/runtime/src/execute/run/tests-steer.rs b/crates/runvil-internal/runtime/src/execute/run/tests-steer.rs index bdd057242..fabc13f9f 100644 --- a/crates/runvil-internal/runtime/src/execute/run/tests-steer.rs +++ b/crates/runvil-internal/runtime/src/execute/run/tests-steer.rs @@ -18,11 +18,11 @@ use runvil_prompt::test_support::prompt; use runvil_types::ids::{ChainId, TaskId}; use runvil_types::models::{ModelRole, ThinkingMode}; use runvil_types::tools::{ToolCatalog, ToolId, ToolInfo, ToolOutput}; +use runvil_vfs::VfsOutcome; use serde_json::json; use super::inbox::{done, main_task}; use super::*; -use crate::lua::VfsOutcome; use crate::model::{Completion, CompletionResult, ToolCall}; use crate::test_support::scenario::{chat_answer, pass_through, test_model_with}; use crate::test_support::scripted_chat::text; diff --git a/crates/runvil-internal/runtime/src/execute/run/tests.rs b/crates/runvil-internal/runtime/src/execute/run/tests.rs index 2c3ccc2ae..0e45c62d8 100644 --- a/crates/runvil-internal/runtime/src/execute/run/tests.rs +++ b/crates/runvil-internal/runtime/src/execute/run/tests.rs @@ -13,10 +13,10 @@ use runvil_types::error::ErrorCode; use runvil_types::event::{Event, ReplyOrigin}; use runvil_types::ids::{ChainId, RoundId}; use runvil_types::tools::ToolId; +use runvil_vfs::{VfsOp, VfsOutcome}; use serde_json::json; use super::*; -use crate::lua::VfsOp; use crate::model::Message; use crate::model::ModelBinding; use crate::test_support::scenario::{TEST_SEED, only_effect, round_trip, test_binding}; @@ -321,7 +321,7 @@ fn an_orphaned_effects_real_answer_is_discarded_and_still_counts_as_the_answer() assert!(matches!(run.step(), Step::Pending { .. })); // The caller performed the operation before it learned of the cancel: // its answer is the effect's one answer, discarded rather than applied. - run.resume(id, EffectAnswer::Vfs(Ok(crate::lua::VfsOutcome::Unit))); + run.resume(id, EffectAnswer::Vfs(Ok(VfsOutcome::Unit))); assert!( matches!( run.step(), diff --git a/crates/runvil-internal/runtime/src/execute/run/vfs_record-tests.rs b/crates/runvil-internal/runtime/src/execute/run/vfs_record-tests.rs new file mode 100644 index 000000000..41f711372 --- /dev/null +++ b/crates/runvil-internal/runtime/src/execute/run/vfs_record-tests.rs @@ -0,0 +1,327 @@ +//! The record forms of a file operation and of its outcome: each of the +//! operations records as one object keyed by its name and reads back +//! identical, the bytes of a write record as text when they are UTF-8 and +//! as hex otherwise, each outcome records whole and reads back identical, +//! a time before the Unix epoch keeps its place, and a form that names no +//! operation or outcome is refused. + +use std::fmt; + +use serde::de::DeserializeOwned; + +use super::*; + +/// An operation behind the record form [`serialize_op`] writes. +#[derive(Debug, PartialEq, Serialize, Deserialize)] +struct Op(#[serde(serialize_with = "serialize_op", deserialize_with = "deserialize_op")] VfsOp); + +/// An operation's answer behind the record form [`serialize_answer`] +/// writes, with a failure as its text. +#[derive(Debug, PartialEq, Serialize, Deserialize)] +struct Answer( + #[serde( + serialize_with = "serialize_answer", + deserialize_with = "deserialize_answer" + )] + Result, +); + +/// Asserts that `value` records as exactly `line`, and that `line` reads +/// back as `value`. +#[track_caller] +fn assert_records_as(value: &T, line: &str) +where + T: Serialize + DeserializeOwned + PartialEq + fmt::Debug, +{ + assert_eq!( + serde_json::to_string(value).expect("a record form serializes"), + line + ); + let back: T = serde_json::from_str(line).expect("a record form reads back"); + assert_eq!(&back, value, "{line}"); +} + +/// The error of reading `line` as a `T`. +#[track_caller] +fn refusal(line: &str) -> String { + serde_json::from_str::(line) + .expect_err("the line reads as no record form") + .to_string() +} + +/// The path the operations of the record cases name. +fn path() -> String { + "a.md".to_owned() +} + +#[test] +fn each_operation_of_a_store_call_records_as_one_object_keyed_by_its_name() { + let cases = [ + ( + VfsOp::Write { + path: path(), + contents: b"hello".to_vec(), + }, + r#"{"Write":{"path":"a.md","contents":"hello"}}"#, + ), + ( + VfsOp::Append { + path: path(), + contents: b"more".to_vec(), + }, + r#"{"Append":{"path":"a.md","contents":"more"}}"#, + ), + ( + VfsOp::Read { + path: path(), + start: Some(2), + end: None, + }, + r#"{"Read":{"path":"a.md","start":2,"end":null}}"#, + ), + ( + VfsOp::ReadNumbered { + path: path(), + start: None, + end: None, + }, + r#"{"ReadNumbered":{"path":"a.md","start":null,"end":null}}"#, + ), + ( + VfsOp::StrReplace { + path: path(), + old: "one".to_owned(), + new: "two".to_owned(), + }, + r#"{"StrReplace":{"path":"a.md","old":"one","new":"two"}}"#, + ), + ( + VfsOp::Delete { path: path() }, + r#"{"Delete":{"path":"a.md"}}"#, + ), + ( + VfsOp::Glob { + pattern: "*.md".to_owned(), + }, + r#"{"Glob":{"pattern":"*.md"}}"#, + ), + ( + VfsOp::Exists { path: path() }, + r#"{"Exists":{"path":"a.md"}}"#, + ), + ]; + for (op, line) in cases { + assert_records_as(&Op(op), line); + } +} + +#[test] +fn each_operation_only_a_tool_asks_for_records_as_one_object_keyed_by_its_name() { + let cases = [ + (VfsOp::Stat { path: path() }, r#"{"Stat":{"path":"a.md"}}"#), + ( + VfsOp::List { + path: "docs".to_owned(), + }, + r#"{"List":{"path":"docs"}}"#, + ), + ( + VfsOp::ReadRange { + path: path(), + offset: 4, + len: u64::MAX, + }, + r#"{"ReadRange":{"path":"a.md","offset":4,"len":18446744073709551615}}"#, + ), + ( + VfsOp::Mkdir { + path: "docs".to_owned(), + recursive: true, + }, + r#"{"Mkdir":{"path":"docs","recursive":true}}"#, + ), + ( + VfsOp::Remove { + path: "docs".to_owned(), + recursive: false, + }, + r#"{"Remove":{"path":"docs","recursive":false}}"#, + ), + ( + VfsOp::Rename { + from: path(), + to: "b.md".to_owned(), + }, + r#"{"Rename":{"from":"a.md","to":"b.md"}}"#, + ), + ( + VfsOp::Copy { + from: path(), + to: "b.md".to_owned(), + }, + r#"{"Copy":{"from":"a.md","to":"b.md"}}"#, + ), + ]; + for (op, line) in cases { + assert_records_as(&Op(op), line); + } +} + +#[test] +fn the_bytes_of_a_write_record_as_text_when_they_are_utf8_and_as_hex_otherwise() { + assert_records_as( + &Op(VfsOp::Write { + path: "note.md".to_owned(), + contents: "caf\u{e9} \u{2713}".as_bytes().to_vec(), + }), + "{\"Write\":{\"path\":\"note.md\",\"contents\":\"caf\u{e9} \u{2713}\"}}", + ); + assert_records_as( + &Op(VfsOp::Write { + path: "blob.bin".to_owned(), + contents: vec![0xff, 0x00, 0x0a, b'a'], + }), + r#"{"Write":{"path":"blob.bin","contents_hex":"ff000a61"}}"#, + ); + assert_records_as( + &Op(VfsOp::Append { + path: "blob.bin".to_owned(), + contents: vec![0x80], + }), + r#"{"Append":{"path":"blob.bin","contents_hex":"80"}}"#, + ); + assert_records_as( + &Op(VfsOp::Write { + path: "empty.md".to_owned(), + contents: Vec::new(), + }), + r#"{"Write":{"path":"empty.md","contents":""}}"#, + ); +} + +#[test] +fn a_form_that_names_no_operation_is_refused() { + for (line, reason) in [ + ("null", "names no file operation"), + ( + r#"{"Write":{"path":"a","contents_hex":"abc"}}"#, + "two digits for each byte, got 3 digits", + ), + ( + r#"{"Write":{"path":"a","contents_hex":"zz"}}"#, + "no hex digit", + ), + ( + "{\"Write\":{\"path\":\"a\",\"contents_hex\":\"\u{e9}\u{e9}\"}}", + "no hex digit", + ), + (r#"{"Shred":{"path":"a"}}"#, "unknown variant"), + ] { + let refused = refusal::(line); + assert!(refused.contains(reason), "{line}: {refused}"); + } +} + +/// The metadata of a three-byte file, with no mode or times. +fn bare_stat() -> Stat { + Stat::new(FileType::File, 3) +} + +#[test] +fn every_outcome_records_whole() { + let cases = [ + (VfsOutcome::Unit, r#"{"Ok":"Unit"}"#), + ( + VfsOutcome::Text("the read".to_owned()), + r#"{"Ok":{"Text":"the read"}}"#, + ), + ( + VfsOutcome::Paths(vec!["a.txt".to_owned(), "b.txt".to_owned()]), + r#"{"Ok":{"Paths":["a.txt","b.txt"]}}"#, + ), + (VfsOutcome::Bool(true), r#"{"Ok":{"Bool":true}}"#), + ( + VfsOutcome::Stat(bare_stat()), + r#"{"Ok":{"Stat":{"file_type":"file","size":3,"mode":null,"modified":null,"created":null}}}"#, + ), + ( + VfsOutcome::Entries(vec![ + Entry::new("a.md", bare_stat()), + Entry::new("sub", Stat::new(FileType::Directory, 0)) + .with_description(Some("notes".to_owned())), + ]), + r#"{"Ok":{"Entries":[{"name":"a.md","stat":{"file_type":"file","size":3,"mode":null,"modified":null,"created":null},"description":null},{"name":"sub","stat":{"file_type":"directory","size":0,"mode":null,"modified":null,"created":null},"description":"notes"}]}}"#, + ), + ( + VfsOutcome::Bytes(b"abc".to_vec()), + r#"{"Ok":{"Bytes":{"contents":"abc"}}}"#, + ), + ( + VfsOutcome::Bytes(vec![0xff, 0x00]), + r#"{"Ok":{"Bytes":{"contents_hex":"ff00"}}}"#, + ), + ]; + for (outcome, line) in cases { + assert_records_as(&Answer(Ok(outcome)), line); + } + assert_records_as(&Answer(Err("gone".to_owned())), r#"{"Err":"gone"}"#); +} + +#[test] +fn a_stat_records_its_mode_and_its_times_on_either_side_of_the_epoch() { + let stat = Stat::new(FileType::Symlink, 9) + .with_mode(Some(0o755)) + .with_modified(Some(UNIX_EPOCH + Duration::from_millis(1500))) + .with_created(Some(UNIX_EPOCH - Duration::from_millis(1500))); + assert_records_as( + &Answer(Ok(VfsOutcome::Stat(stat))), + r#"{"Ok":{"Stat":{"file_type":"symlink","size":9,"mode":493,"modified":{"secs":1,"nanos":500000000},"created":{"secs":-2,"nanos":500000000}}}}"#, + ); + let whole = Stat::new(FileType::File, 0) + .with_modified(Some(UNIX_EPOCH)) + .with_created(Some(UNIX_EPOCH - Duration::from_secs(3))); + assert_records_as( + &Answer(Ok(VfsOutcome::Stat(whole))), + r#"{"Ok":{"Stat":{"file_type":"file","size":0,"mode":null,"modified":{"secs":0,"nanos":0},"created":{"secs":-3,"nanos":0}}}}"#, + ); +} + +#[test] +fn every_kind_of_file_records_under_its_own_name() { + for (file_type, name) in [ + (FileType::File, "file"), + (FileType::Directory, "directory"), + (FileType::Symlink, "symlink"), + (FileType::Fifo, "fifo"), + (FileType::Socket, "socket"), + (FileType::CharDevice, "char_device"), + (FileType::BlockDevice, "block_device"), + ] { + let line = format!( + r#"{{"Ok":{{"Stat":{{"file_type":"{name}","size":0,"mode":null,"modified":null,"created":null}}}}}}"# + ); + assert_records_as( + &Answer(Ok(VfsOutcome::Stat(Stat::new(file_type, 0)))), + &line, + ); + } +} + +#[test] +fn a_form_that_names_no_outcome_is_refused() { + for (line, reason) in [ + (r#"{"Ok":null}"#, "names no outcome"), + ( + r#"{"Ok":{"Stat":{"file_type":"other","size":0,"mode":null,"modified":null,"created":null}}}"#, + "names no kind of file", + ), + ( + r#"{"Ok":{"Bytes":{"contents_hex":"f"}}}"#, + "two digits for each byte, got 1 digits", + ), + (r#"{"Ok":{"Lines":3}}"#, "unknown variant"), + ] { + let refused = refusal::(line); + assert!(refused.contains(reason), "{line}: {refused}"); + } +} diff --git a/crates/runvil-internal/runtime/src/execute/run/vfs_record.rs b/crates/runvil-internal/runtime/src/execute/run/vfs_record.rs new file mode 100644 index 000000000..ae9332c66 --- /dev/null +++ b/crates/runvil-internal/runtime/src/execute/run/vfs_record.rs @@ -0,0 +1,585 @@ +//! The record forms of a file operation and of its outcome. +//! +//! `runvil-vfs` is std only, so its [`VfsOp`] and [`VfsOutcome`] have no +//! serde form of their own. A `Vfs` effect's record and its answer's +//! record write them through the private forms here, and read them back. +//! +//! An operation records in serde's externally tagged form: one object +//! keyed by the operation's name, such as +//! `{"Read":{"path":"a.md","start":null,"end":null}}`. The bytes of a +//! write or an append record as text under `contents` when they are +//! UTF-8, and as lowercase hex under `contents_hex` otherwise. An outcome +//! records the same way: `Unit` is the bare string `"Unit"`, and every +//! other outcome is a one-key object, such as `{"Text":"..."}`, +//! `{"Paths":["a.txt"]}`, or `{"Bool":true}`. +//! +//! [`VfsOp`], [`VfsOutcome`], and the kind of a file are +//! `#[non_exhaustive]`. An operation or an outcome this module has no +//! form for records as `null`, and a kind of file it does not name +//! records as `other`. None of the three reads back. + +use std::fmt::Write as _; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use runvil_vfs::{Entry, FileType, Stat, VfsOp, VfsOutcome}; +use serde::de::Error as _; +use serde::{Deserialize, Deserializer, Serialize, Serializer}; + +/// Bytes as a record holds them: as text when they are UTF-8, and as hex +/// otherwise. Flattened into an operation's record, the variant's name +/// is the key the bytes sit under. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +enum BytesRecord { + /// UTF-8 bytes, as their text. + #[serde(rename = "contents")] + Text(String), + /// Bytes that are not UTF-8, as two lowercase hex digits for each. + #[serde(rename = "contents_hex")] + Hex(String), +} + +impl BytesRecord { + /// The record form of `bytes`. + fn of(bytes: Vec) -> BytesRecord { + match String::from_utf8(bytes) { + Ok(text) => BytesRecord::Text(text), + Err(not_text) => { + let bytes = not_text.as_bytes(); + let mut hex = String::with_capacity(bytes.len() * 2); + for byte in bytes { + // Writing to a String is infallible, so the result is + // discarded. + let _ = write!(hex, "{byte:02x}"); + } + BytesRecord::Hex(hex) + } + } + } + + /// The bytes this record holds. + /// + /// # Errors + /// Returns a sentence that names the fault when the hex holds a + /// character that is no hex digit, or an odd number of digits. + fn into_bytes(self) -> Result, String> { + const NOT_HEX: &str = "recorded hex holds a character that is no hex digit"; + let hex = match self { + BytesRecord::Text(text) => return Ok(text.into_bytes()), + BytesRecord::Hex(hex) => hex, + }; + if !hex.bytes().all(|byte| byte.is_ascii_hexdigit()) { + return Err(NOT_HEX.to_owned()); + } + if !hex.len().is_multiple_of(2) { + return Err(format!( + "recorded hex must hold two digits for each byte, got {} digits", + hex.len() + )); + } + hex.as_bytes() + .chunks(2) + .map(|pair| { + std::str::from_utf8(pair) + .ok() + .and_then(|digits| u8::from_str_radix(digits, 16).ok()) + .ok_or_else(|| NOT_HEX.to_owned()) + }) + .collect() + } +} + +/// A [`VfsOp`] as a record holds it: the same operation, with the bytes +/// of a write or an append as a [`BytesRecord`]. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +enum VfsOpRecord { + /// `VfsOp::Write`. + Write { + /// The path of the file. + path: String, + /// The bytes the file holds afterward. + #[serde(flatten)] + contents: BytesRecord, + }, + /// `VfsOp::Append`. + Append { + /// The path of the file. + path: String, + /// The bytes to add. + #[serde(flatten)] + contents: BytesRecord, + }, + /// `VfsOp::Read`. + Read { + /// The path of the file. + path: String, + /// The optional 1-based first line. + start: Option, + /// The optional 1-based last line. + end: Option, + }, + /// `VfsOp::ReadNumbered`. + ReadNumbered { + /// The path of the file. + path: String, + /// The optional 1-based first line. + start: Option, + /// The optional 1-based last line. + end: Option, + }, + /// `VfsOp::StrReplace`. + StrReplace { + /// The path of the file. + path: String, + /// The anchor text. + old: String, + /// The replacement text. + new: String, + }, + /// `VfsOp::Delete`. + Delete { + /// The path to remove. + path: String, + }, + /// `VfsOp::Glob`. + Glob { + /// The glob pattern. + pattern: String, + }, + /// `VfsOp::Exists`. + Exists { + /// The path to test. + path: String, + }, + /// `VfsOp::Stat`. + Stat { + /// The path to describe. + path: String, + }, + /// `VfsOp::List`. + List { + /// The path of the directory. + path: String, + }, + /// `VfsOp::ReadRange`. + ReadRange { + /// The path of the file. + path: String, + /// The byte the read starts at. + offset: u64, + /// The most bytes the read returns. + len: u64, + }, + /// `VfsOp::Mkdir`. + Mkdir { + /// The path of the directory. + path: String, + /// Whether the missing parent directories are created too. + recursive: bool, + }, + /// `VfsOp::Remove`. + Remove { + /// The path to remove. + path: String, + /// Whether a directory goes with everything under it. + recursive: bool, + }, + /// `VfsOp::Rename`. + Rename { + /// The path to move. + from: String, + /// The path it moves to. + to: String, + }, + /// `VfsOp::Copy`. + Copy { + /// The path of the file to copy. + from: String, + /// The path of the copy. + to: String, + }, +} + +impl VfsOpRecord { + /// The record form of `op`, or `None` for an operation this module + /// has no form for. + fn of(op: &VfsOp) -> Option { + Some(match op.clone() { + VfsOp::Write { path, contents } => VfsOpRecord::Write { + path, + contents: BytesRecord::of(contents), + }, + VfsOp::Append { path, contents } => VfsOpRecord::Append { + path, + contents: BytesRecord::of(contents), + }, + VfsOp::Read { path, start, end } => VfsOpRecord::Read { path, start, end }, + VfsOp::ReadNumbered { path, start, end } => { + VfsOpRecord::ReadNumbered { path, start, end } + } + VfsOp::StrReplace { path, old, new } => VfsOpRecord::StrReplace { path, old, new }, + VfsOp::Delete { path } => VfsOpRecord::Delete { path }, + VfsOp::Glob { pattern } => VfsOpRecord::Glob { pattern }, + VfsOp::Exists { path } => VfsOpRecord::Exists { path }, + VfsOp::Stat { path } => VfsOpRecord::Stat { path }, + VfsOp::List { path } => VfsOpRecord::List { path }, + VfsOp::ReadRange { path, offset, len } => VfsOpRecord::ReadRange { path, offset, len }, + VfsOp::Mkdir { path, recursive } => VfsOpRecord::Mkdir { path, recursive }, + VfsOp::Remove { path, recursive } => VfsOpRecord::Remove { path, recursive }, + VfsOp::Rename { from, to } => VfsOpRecord::Rename { from, to }, + VfsOp::Copy { from, to } => VfsOpRecord::Copy { from, to }, + _ => return None, + }) + } + + /// The operation this record holds. + /// + /// # Errors + /// Returns a sentence that names the fault when the bytes of a write + /// or an append are hex that does not decode. + fn into_op(self) -> Result { + Ok(match self { + VfsOpRecord::Write { path, contents } => VfsOp::Write { + path, + contents: contents.into_bytes()?, + }, + VfsOpRecord::Append { path, contents } => VfsOp::Append { + path, + contents: contents.into_bytes()?, + }, + VfsOpRecord::Read { path, start, end } => VfsOp::Read { path, start, end }, + VfsOpRecord::ReadNumbered { path, start, end } => { + VfsOp::ReadNumbered { path, start, end } + } + VfsOpRecord::StrReplace { path, old, new } => VfsOp::StrReplace { path, old, new }, + VfsOpRecord::Delete { path } => VfsOp::Delete { path }, + VfsOpRecord::Glob { pattern } => VfsOp::Glob { pattern }, + VfsOpRecord::Exists { path } => VfsOp::Exists { path }, + VfsOpRecord::Stat { path } => VfsOp::Stat { path }, + VfsOpRecord::List { path } => VfsOp::List { path }, + VfsOpRecord::ReadRange { path, offset, len } => VfsOp::ReadRange { path, offset, len }, + VfsOpRecord::Mkdir { path, recursive } => VfsOp::Mkdir { path, recursive }, + VfsOpRecord::Remove { path, recursive } => VfsOp::Remove { path, recursive }, + VfsOpRecord::Rename { from, to } => VfsOp::Rename { from, to }, + VfsOpRecord::Copy { from, to } => VfsOp::Copy { from, to }, + }) + } +} + +/// The kind of a file as a record holds it. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +enum FileTypeRecord { + /// A regular file. + File, + /// A directory. + Directory, + /// A symbolic link. + Symlink, + /// A named pipe. + Fifo, + /// A socket. + Socket, + /// A character device. + CharDevice, + /// A block device. + BlockDevice, + /// A kind this module does not name. + Other, +} + +impl FileTypeRecord { + /// The record form of `file_type`. + fn of(file_type: FileType) -> FileTypeRecord { + match file_type { + FileType::File => FileTypeRecord::File, + FileType::Directory => FileTypeRecord::Directory, + FileType::Symlink => FileTypeRecord::Symlink, + FileType::Fifo => FileTypeRecord::Fifo, + FileType::Socket => FileTypeRecord::Socket, + FileType::CharDevice => FileTypeRecord::CharDevice, + FileType::BlockDevice => FileTypeRecord::BlockDevice, + _ => FileTypeRecord::Other, + } + } + + /// The kind this record holds. + /// + /// # Errors + /// Returns a sentence that names the fault for `other`, which stands + /// for no one kind. + fn into_file_type(self) -> Result { + Ok(match self { + FileTypeRecord::File => FileType::File, + FileTypeRecord::Directory => FileType::Directory, + FileTypeRecord::Symlink => FileType::Symlink, + FileTypeRecord::Fifo => FileType::Fifo, + FileTypeRecord::Socket => FileType::Socket, + FileTypeRecord::CharDevice => FileType::CharDevice, + FileTypeRecord::BlockDevice => FileType::BlockDevice, + FileTypeRecord::Other => { + return Err("a recorded file type of `other` names no kind of file".to_owned()); + } + }) + } +} + +/// The nanoseconds in one second. +const NANOS_PER_SECOND: u32 = 1_000_000_000; + +/// A point in time as a record holds it: `secs` whole seconds after the +/// Unix epoch, negative for a time before it, and `nanos` nanoseconds +/// after that second. Both are integers, so the time reads back exactly. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +struct TimeRecord { + /// Whole seconds after the Unix epoch. + secs: i64, + /// Nanoseconds after that second, below one second. + nanos: u32, +} + +impl TimeRecord { + /// The record form of `time`. A time further from the epoch than + /// `i64` seconds records as the furthest second. + fn of(time: SystemTime) -> TimeRecord { + let whole = |seconds: u64| i64::try_from(seconds).unwrap_or(i64::MAX); + match time.duration_since(UNIX_EPOCH) { + Ok(after) => TimeRecord { + secs: whole(after.as_secs()), + nanos: after.subsec_nanos(), + }, + Err(before) => { + let before = before.duration(); + let secs = -whole(before.as_secs()); + match before.subsec_nanos() { + 0 => TimeRecord { secs, nanos: 0 }, + nanos => TimeRecord { + secs: secs.saturating_sub(1), + nanos: NANOS_PER_SECOND - nanos, + }, + } + } + } + } + + /// The time this record holds. + /// + /// # Errors + /// Returns a sentence that names the fault for a time the platform's + /// clock cannot represent. + fn into_time(self) -> Result { + let second = match u64::try_from(self.secs) { + Ok(after) => UNIX_EPOCH.checked_add(Duration::from_secs(after)), + Err(_) => UNIX_EPOCH.checked_sub(Duration::from_secs(self.secs.unsigned_abs())), + }; + second + .and_then(|second| second.checked_add(Duration::new(0, self.nanos))) + .ok_or_else(|| { + format!( + "a recorded time of {} seconds and {} nanoseconds is outside the clock's range", + self.secs, self.nanos + ) + }) + } +} + +/// A [`Stat`] as a record holds it. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +struct StatRecord { + /// What kind of node this is. + file_type: FileTypeRecord, + /// Size in bytes. + size: u64, + /// POSIX mode bits, when the backend tracks them. + mode: Option, + /// Last modification time, when the backend tracks it. + modified: Option, + /// Creation time, when the backend tracks it. + created: Option, +} + +impl StatRecord { + /// The record form of `stat`. + fn of(stat: &Stat) -> StatRecord { + StatRecord { + file_type: FileTypeRecord::of(stat.file_type), + size: stat.size, + mode: stat.mode, + modified: stat.modified.map(TimeRecord::of), + created: stat.created.map(TimeRecord::of), + } + } + + /// The metadata this record holds. + /// + /// # Errors + /// Returns a sentence that names the fault for a kind of file or a + /// time that does not read back. + fn into_stat(self) -> Result { + let modified = self.modified.map(TimeRecord::into_time).transpose()?; + let created = self.created.map(TimeRecord::into_time).transpose()?; + Ok(Stat::new(self.file_type.into_file_type()?, self.size) + .with_mode(self.mode) + .with_modified(modified) + .with_created(created)) + } +} + +/// An [`Entry`] as a record holds it. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +struct EntryRecord { + /// The entry's name within its directory. + name: String, + /// The entry's metadata. + stat: StatRecord, + /// The annotation shown beside the entry, when it has one. + description: Option, +} + +impl EntryRecord { + /// The record form of `entry`. + fn of(entry: &Entry) -> EntryRecord { + EntryRecord { + name: entry.name.clone(), + stat: StatRecord::of(&entry.stat), + description: entry.description.clone(), + } + } + + /// The entry this record holds. + /// + /// # Errors + /// Returns a sentence that names the fault when the entry's metadata + /// does not read back. + fn into_entry(self) -> Result { + Ok(Entry::new(self.name, self.stat.into_stat()?).with_description(self.description)) + } +} + +/// A [`VfsOutcome`] as a record holds it: the whole outcome. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +enum VfsOutcomeRecord { + /// `VfsOutcome::Unit`. + Unit, + /// `VfsOutcome::Text`. + Text(String), + /// `VfsOutcome::Paths`. + Paths(Vec), + /// `VfsOutcome::Bool`. + Bool(bool), + /// `VfsOutcome::Stat`. + Stat(StatRecord), + /// `VfsOutcome::Entries`. + Entries(Vec), + /// `VfsOutcome::Bytes`. + Bytes(BytesRecord), +} + +impl VfsOutcomeRecord { + /// The record form of `outcome`, or `None` for an outcome this module + /// has no form for. + fn of(outcome: &VfsOutcome) -> Option { + Some(match outcome.clone() { + VfsOutcome::Unit => VfsOutcomeRecord::Unit, + VfsOutcome::Text(text) => VfsOutcomeRecord::Text(text), + VfsOutcome::Paths(paths) => VfsOutcomeRecord::Paths(paths), + VfsOutcome::Bool(flag) => VfsOutcomeRecord::Bool(flag), + VfsOutcome::Stat(stat) => VfsOutcomeRecord::Stat(StatRecord::of(&stat)), + VfsOutcome::Entries(entries) => { + VfsOutcomeRecord::Entries(entries.iter().map(EntryRecord::of).collect()) + } + VfsOutcome::Bytes(bytes) => VfsOutcomeRecord::Bytes(BytesRecord::of(bytes)), + _ => return None, + }) + } + + /// The outcome this record holds. + /// + /// # Errors + /// Returns a sentence that names the fault when a stat, an entry, or + /// hex bytes do not read back. + fn into_outcome(self) -> Result { + Ok(match self { + VfsOutcomeRecord::Unit => VfsOutcome::Unit, + VfsOutcomeRecord::Text(text) => VfsOutcome::Text(text), + VfsOutcomeRecord::Paths(paths) => VfsOutcome::Paths(paths), + VfsOutcomeRecord::Bool(flag) => VfsOutcome::Bool(flag), + VfsOutcomeRecord::Stat(stat) => VfsOutcome::Stat(stat.into_stat()?), + VfsOutcomeRecord::Entries(entries) => VfsOutcome::Entries( + entries + .into_iter() + .map(EntryRecord::into_entry) + .collect::>()?, + ), + VfsOutcomeRecord::Bytes(bytes) => VfsOutcome::Bytes(bytes.into_bytes()?), + }) + } +} + +/// Writes `op` as its record form, for a record's `serialize_with`. +/// +/// # Errors +/// Returns the serializer's own error. +pub(super) fn serialize_op(op: &VfsOp, serializer: S) -> Result { + VfsOpRecord::of(op).serialize(serializer) +} + +/// Reads an operation back from its record form, for a record's +/// `deserialize_with`. +/// +/// # Errors +/// Returns the deserializer's error for a value that is no operation's +/// record form, `null` included, or whose hex bytes do not decode. +pub(super) fn deserialize_op<'de, D: Deserializer<'de>>( + deserializer: D, +) -> Result { + Option::::deserialize(deserializer)? + .ok_or_else(|| D::Error::custom("a recorded `null` names no file operation"))? + .into_op() + .map_err(D::Error::custom) +} + +/// Writes `answer`, an operation's whole outcome or its failure, with the +/// outcome in its record form, for a record's `serialize_with`. +/// +/// # Errors +/// Returns the serializer's own error. +pub(super) fn serialize_answer( + answer: &Result, + serializer: S, +) -> Result +where + S: Serializer, + E: Serialize, +{ + answer + .as_ref() + .map(VfsOutcomeRecord::of) + .serialize(serializer) +} + +/// Reads an operation's whole outcome, or its failure, back from the form +/// [`serialize_answer`] writes, for a record's `deserialize_with`. +/// +/// # Errors +/// Returns the deserializer's error for a value of another form, or for +/// an outcome that does not read back: `null`, a kind of file of `other`, +/// a time outside the clock's range, or hex bytes that do not decode. +pub(super) fn deserialize_answer<'de, D, E>( + deserializer: D, +) -> Result, D::Error> +where + D: Deserializer<'de>, + E: Deserialize<'de>, +{ + match Result::, E>::deserialize(deserializer)? { + Ok(Some(record)) => record.into_outcome().map(Ok).map_err(D::Error::custom), + Ok(None) => Err(D::Error::custom( + "a recorded `null` names no outcome of a file operation", + )), + Err(failure) => Ok(Err(failure)), + } +} + +#[cfg(test)] +#[path = "vfs_record-tests.rs"] +mod tests; diff --git a/crates/runvil-internal/runtime/src/execute/scheduler/apply.rs b/crates/runvil-internal/runtime/src/execute/scheduler/apply.rs index 39675265e..1164375d9 100644 --- a/crates/runvil-internal/runtime/src/execute/scheduler/apply.rs +++ b/crates/runvil-internal/runtime/src/execute/scheduler/apply.rs @@ -21,12 +21,10 @@ use runvil_types::error::{ErrorCode, place}; use runvil_types::event_lifecycle::{self as lifecycle, Lifecycle}; use runvil_types::ids::{RoundId, TaskId}; use runvil_types::tools::ToolOutput; -use runvil_vfs::{ExecId, VfsError}; +use runvil_vfs::{ExecId, VfsError, VfsOp, VfsOutcome}; use crate::execute::infer::accept_infer; -use crate::lua::{ - Answer, ModelCall, ToolCallOutcome, VfsOp, VfsOutcome, prepare_dispatch, prepare_model_dispatch, -}; +use crate::lua::{Answer, ModelCall, ToolCallOutcome, prepare_dispatch, prepare_model_dispatch}; use crate::model::Completion; use crate::{Error, Result, error}; @@ -63,8 +61,9 @@ fn vfs_observations(op: &VfsOp) -> Option<(Lifecycle, Lifecycle)> { lifecycle::VFS_EXISTS_SUCCEEDED, lifecycle::VFS_EXISTS_FAILED, ), - // Any op `runvil-lua` adds behind its `#[non_exhaustive]` - // `VfsOp` before this crate names it reports nothing. + // An operation no `store` function names reports nothing, and so + // does any op `runvil-vfs` adds behind its `#[non_exhaustive]` + // `VfsOp` before this crate names it. _ => return None, }; Some(pair) diff --git a/crates/runvil-internal/runtime/src/execute/scheduler/dispatch.rs b/crates/runvil-internal/runtime/src/execute/scheduler/dispatch.rs index f9cf87644..df9787e0e 100644 --- a/crates/runvil-internal/runtime/src/execute/scheduler/dispatch.rs +++ b/crates/runvil-internal/runtime/src/execute/scheduler/dispatch.rs @@ -20,10 +20,11 @@ use std::sync::Arc; use runvil_types::error::place; use runvil_types::event::ReplyOrigin; +use runvil_vfs::VfsOp; use crate::execute::run::Effect; use crate::execute::section_context::TaskSeed; -use crate::lua::{Answer, LibraryKey, Request, VfsOp}; +use crate::lua::{Answer, LibraryKey, Request}; use crate::model::{Message, ModelBinding}; use crate::section_pos::{SectionIndex, SectionPos}; use crate::{Result, error}; diff --git a/crates/runvil-internal/runtime/src/execute/scheduler/effects.rs b/crates/runvil-internal/runtime/src/execute/scheduler/effects.rs index 5cd79dc27..f4d99a9a8 100644 --- a/crates/runvil-internal/runtime/src/execute/scheduler/effects.rs +++ b/crates/runvil-internal/runtime/src/execute/scheduler/effects.rs @@ -25,10 +25,10 @@ use std::collections::HashMap; use runvil_types::event::ReplyOrigin; use runvil_types::ids::{Provenance, RoundId, TaskId}; -use runvil_vfs::ExecId; +use runvil_vfs::{ExecId, VfsOp}; use crate::execute::run::{Effect, EffectId, IssuedEffect, Round}; -use crate::lua::{ScriptReport, ToolBinding, VfsOp}; +use crate::lua::{ScriptReport, ToolBinding}; use crate::model::ModelBinding; use super::ChainIndex; diff --git a/crates/runvil-internal/runtime/src/execute/scheduler/test_hooks.rs b/crates/runvil-internal/runtime/src/execute/scheduler/test_hooks.rs index a42e852ec..559321bde 100644 --- a/crates/runvil-internal/runtime/src/execute/scheduler/test_hooks.rs +++ b/crates/runvil-internal/runtime/src/execute/scheduler/test_hooks.rs @@ -10,11 +10,11 @@ use std::sync::Arc; use std::sync::atomic::Ordering; use runvil_types::ids::{ChainId, TaskId}; -use runvil_vfs::Origin; +use runvil_vfs::{Origin, VfsOp}; use crate::Result; use crate::execute::run::EffectId; -use crate::lua::{Answer, Request, ToolSet, VfsOp}; +use crate::lua::{Answer, Request, ToolSet}; use crate::section_pos::{SectionIndex, SectionPos}; use super::chain::ChainStart; diff --git a/crates/runvil-internal/runtime/src/execute/tests/effects.rs b/crates/runvil-internal/runtime/src/execute/tests/effects.rs index 3e8421a7e..1c0163320 100644 --- a/crates/runvil-internal/runtime/src/execute/tests/effects.rs +++ b/crates/runvil-internal/runtime/src/execute/tests/effects.rs @@ -12,7 +12,7 @@ use runvil_prompt::test_support::{one_section, prompt}; use runvil_types::event::ReplyOrigin; use runvil_types::ids::{ChainId, RoundId}; use runvil_types::packs::PackId; -use runvil_vfs::Store; +use runvil_vfs::{Store, VfsOp}; use super::fixtures::echo_tool; use super::models_loop::{loop_model_name, loop_scenario}; @@ -21,7 +21,6 @@ use super::*; use crate::execute::run::{ AnswerRecord, EffectRecord, PackToolSets, Round, ToolCallOrigin, ToolCaller, }; -use crate::lua::{VfsOp, run_store_op}; use crate::test_support::rig::Rig; use crate::test_support::scenario::{fresh_store_view, round_trip}; @@ -210,7 +209,7 @@ fn a_store_operation_issues_exactly_one_store_effect() { store: ChainId::root(), op: VfsOp::Write { path: "notes.md".to_owned(), - contents: "kept".to_owned(), + contents: b"kept".to_vec(), }, }, EffectRecord::Vfs { @@ -290,7 +289,7 @@ fn a_runs_store_effect_records_rebuild_its_store() -> std::result::Result<(), Vf for (effect, answer) in trace.effects() { if let (EffectRecord::Vfs { op, .. }, AnswerRecord::Vfs(Ok(outcome))) = (effect, answer) { assert_eq!( - &run_store_op(&rebuilt, op.clone())?, + &rebuilt.perform(op)?, outcome, "{op:?} gives the outcome the run recorded" ); diff --git a/crates/runvil-internal/runtime/src/execute/tests/execute/store.rs b/crates/runvil-internal/runtime/src/execute/tests/execute/store.rs index 0e8cba513..95308b9e5 100644 --- a/crates/runvil-internal/runtime/src/execute/tests/execute/store.rs +++ b/crates/runvil-internal/runtime/src/execute/tests/execute/store.rs @@ -12,7 +12,6 @@ use runvil_vfs::Store; use super::*; use crate::execute::run::{AnswerRecord, EffectRecord}; -use crate::lua::run_store_op; use crate::test_support::rig::Rig; use crate::test_support::scenario::fresh_store_view; @@ -206,7 +205,9 @@ fn the_vfs_records_of_each_store_id_rebuild_that_store() { fresh_store_view(&Store::new(), "a rebuilt store").expect("a new store gives a view") }); assert_eq!( - &run_store_op(view, op.clone()).expect("the recorded operation succeeds again"), + &view + .perform(op) + .expect("the recorded operation succeeds again"), outcome, "{op:?} on store {store} gives the outcome the run recorded" ); diff --git a/crates/runvil-internal/runtime/src/execute/tests/preludes.rs b/crates/runvil-internal/runtime/src/execute/tests/preludes.rs index 361b4a22e..730508fd2 100644 --- a/crates/runvil-internal/runtime/src/execute/tests/preludes.rs +++ b/crates/runvil-internal/runtime/src/execute/tests/preludes.rs @@ -12,11 +12,11 @@ use runvil_types::ids::ChainId; use runvil_types::packs::{PackId, Prelude}; +use runvil_vfs::VfsOp; use super::fixtures::echo_tool; use super::*; use crate::execute::run::{EffectRecord, ToolCallOrigin, ToolCaller}; -use crate::lua::VfsOp; /// A prelude contributed by the Pack `id`. pub(super) fn prelude(id: &str, source: &str) -> Prelude { Prelude::new(PackId::parse(id).expect("a valid Pack id"), source) @@ -289,7 +289,7 @@ fn write_then_read(path: &str, text: &str) -> Vec { store: ChainId::root(), op: VfsOp::Write { path: path.to_owned(), - contents: text.to_owned(), + contents: text.as_bytes().to_vec(), }, }, EffectRecord::Vfs { diff --git a/crates/runvil-internal/runtime/src/execute/tests/suite/exec_flow/store_failures.rs b/crates/runvil-internal/runtime/src/execute/tests/suite/exec_flow/store_failures.rs index 8e4508c24..0dc247d62 100644 --- a/crates/runvil-internal/runtime/src/execute/tests/suite/exec_flow/store_failures.rs +++ b/crates/runvil-internal/runtime/src/execute/tests/suite/exec_flow/store_failures.rs @@ -2,8 +2,8 @@ //! uncaught run errors, the line a store view's failure is placed on, and //! write conflicts from library code. -use runvil_lua::VfsOp; use runvil_types::error::ErrorCode; +use runvil_vfs::VfsOp; use super::*; @@ -59,7 +59,7 @@ fn a_store_view_failure_is_placed_on_the_store_calls_line() { .scheduler_for_test() .dispatch_store_past_the_scopes_end_for_test(VfsOp::Write { path: "a.txt".to_owned(), - contents: "x".to_owned(), + contents: b"x".to_vec(), }) .expect_err("an ended scope refuses the store view"); assert_eq!(error.code, ErrorCode::ScopeEnded, "{error:?}"); diff --git a/crates/runvil-internal/runtime/src/execute/tests/waits.rs b/crates/runvil-internal/runtime/src/execute/tests/waits.rs index e96a317d3..62beb5eb2 100644 --- a/crates/runvil-internal/runtime/src/execute/tests/waits.rs +++ b/crates/runvil-internal/runtime/src/execute/tests/waits.rs @@ -8,13 +8,13 @@ //! `TaskCanceled` exactly once. use runvil_types::event::Event; +use runvil_vfs::VfsOp; use super::context::task; use super::scheduler::{asks, is_timer, scheduler_scenario}; use super::tasks::TaskRecorder; use super::*; use crate::execute::scheduler::test_hooks::TaskState; -use crate::lua::VfsOp; use crate::test_support::rig::Rig; /// A prompt whose first section drives the tasks it spawns over the diff --git a/crates/runvil-internal/runtime/src/lua.rs b/crates/runvil-internal/runtime/src/lua.rs index b98d61d87..640a9caed 100644 --- a/crates/runvil-internal/runtime/src/lua.rs +++ b/crates/runvil-internal/runtime/src/lua.rs @@ -21,16 +21,14 @@ pub(crate) use runvil_lua::{ LibraryBlock, LibraryKey, LuaBlockResult, MessageList, ModelCall, NonEmpty, OfferMode, OfferedTool, OverflowReason, ProseState, RenderedTools, Request, RosterEntry, ScriptReport, SectionRead, SectionText, SectionVm, TaskDelivery, TaskPhase, TaskStatus, ToolBinding, - ToolCallCounts, ToolCallOutcome, ToolCallRecord, ToolSet, Uninjected, UsageAnchor, VfsOp, - VfsOutcome, YieldParse, current_catalog_packs, current_dynamic_set, current_static_set, - install_preludes, install_ui, output_reserve, precheck, prepare_dispatch, - prepare_model_dispatch, project_messages, render_item, wire_name_of, + ToolCallCounts, ToolCallOutcome, ToolCallRecord, ToolSet, Uninjected, UsageAnchor, YieldParse, + current_catalog_packs, current_dynamic_set, current_static_set, install_preludes, install_ui, + output_reserve, precheck, prepare_dispatch, prepare_model_dispatch, project_messages, + render_item, wire_name_of, }; -// The store operation behind `execute::perform_vfs_op`, the entry point -// a caller answers a `Vfs` effect through, and the -// model-facing message renderers a store failure carries. -pub(crate) use runvil_lua::{run_store_op, store_error_message}; +// The model-facing message a store failure carries. +pub(crate) use runvil_lua::store_error_message; #[cfg(test)] mod tests; diff --git a/crates/runvil-internal/runtime/src/lua/tests/errors-tables.rs b/crates/runvil-internal/runtime/src/lua/tests/errors-tables.rs index 53403b8e6..9ebcfefec 100644 --- a/crates/runvil-internal/runtime/src/lua/tests/errors-tables.rs +++ b/crates/runvil-internal/runtime/src/lua/tests/errors-tables.rs @@ -85,7 +85,7 @@ fn an_engine_failure_answered_through_the_envelope_is_the_table_its_code_names() anchor: "TODO".to_owned(), count: 2, }; - let op = crate::lua::VfsOp::StrReplace { + let op = runvil_vfs::VfsOp::StrReplace { path: "notes.md".to_owned(), old: "TODO".to_owned(), new: "DONE".to_owned(), diff --git a/crates/runvil-internal/runtime/src/lua/tests/shims.rs b/crates/runvil-internal/runtime/src/lua/tests/shims.rs index 02303f7b9..afc23a81d 100644 --- a/crates/runvil-internal/runtime/src/lua/tests/shims.rs +++ b/crates/runvil-internal/runtime/src/lua/tests/shims.rs @@ -5,11 +5,11 @@ //! leading model handle, and a model handle's fields and lack of methods. use runvil_types::metrics::ToolCallEvent; +use runvil_vfs::{VfsOp, VfsOutcome}; use serde_json::json; use crate::lua::{ - AdhocToolOutcome, Answer, ChatOutcome, ChatResult, Request, ToolCallOutcome, VfsOp, VfsOutcome, - YieldParse, + AdhocToolOutcome, Answer, ChatOutcome, ChatResult, Request, ToolCallOutcome, YieldParse, }; use crate::model::ModelSet; @@ -240,7 +240,7 @@ fn an_adhoc_tool_handler_runs_inside_the_block_coroutine() { op: VfsOp::Write { path, contents }, } => { assert_eq!(path, "grab.txt"); - assert_eq!(contents, "hi"); + assert_eq!(contents, b"hi"); } other => panic!("the handler's store call yields from the block, got {other:?}"), } diff --git a/crates/runvil-internal/runtime/src/test_support.rs b/crates/runvil-internal/runtime/src/test_support.rs index 8a83354bd..927333931 100644 --- a/crates/runvil-internal/runtime/src/test_support.rs +++ b/crates/runvil-internal/runtime/src/test_support.rs @@ -31,7 +31,6 @@ use runvil_types::event::Event; use runvil_types::tools::make_tool_error; use crate::execute::{Effect, EffectAnswer, EffectId, IssuedEffect, Run, Step}; -use crate::lua::run_store_op; #[cfg(test)] pub(crate) mod recording; @@ -118,7 +117,7 @@ pub fn perform_locally( ErrorCode::ToolOther, format!("no tool is bound as {alias} in this test"), ))), - Effect::Vfs { access, op, .. } => EffectAnswer::Vfs(run_store_op(access, op.clone())), + Effect::Vfs { access, op, .. } => EffectAnswer::Vfs(access.perform(op)), Effect::Timer { .. } => EffectAnswer::Timer, } } diff --git a/crates/runvil-internal/runtime/src/test_support/scenario.rs b/crates/runvil-internal/runtime/src/test_support/scenario.rs index 42ab21a85..204a0ffad 100644 --- a/crates/runvil-internal/runtime/src/test_support/scenario.rs +++ b/crates/runvil-internal/runtime/src/test_support/scenario.rs @@ -38,7 +38,7 @@ use crate::Error; use crate::execute::{ AnswerRecord, Effect, EffectAnswer, EffectId, EffectRecord, Run, RunLimits, RunParams, }; -use crate::lua::{ToolBinding, run_store_op}; +use crate::lua::ToolBinding; use crate::model::{ ModelBinding, ModelId, ModelInfo, ModelRole, ModelSet, ThinkingMode, make_completion_error, }; @@ -182,7 +182,7 @@ impl Answers { "the tool the call names has no implementation in the test driver's tool table", ))), }, - Effect::Vfs { access, op, .. } => EffectAnswer::Vfs(run_store_op(access, op.clone())), + Effect::Vfs { access, op, .. } => EffectAnswer::Vfs(access.perform(op)), Effect::Timer { .. } => EffectAnswer::Timer, } } diff --git a/crates/runvil-internal/vfs/README.md b/crates/runvil-internal/vfs/README.md index 1de0666bb..b926753bc 100644 --- a/crates/runvil-internal/vfs/README.md +++ b/crates/runvil-internal/vfs/README.md @@ -1,3 +1,3 @@ # Virtual filesystem -This crate is Runvil's virtual filesystem: canonical paths, the claims that order concurrent access, the mount router, memory and real-filesystem backends, the store, and the policy gate on edits. Its library depends on nothing but std and sits at the bottom of the dependency stack. The real-filesystem backend keeps every path and every followed link inside its root. +This crate is Runvil's virtual filesystem: canonical paths, the claims that order concurrent access, the mount router, memory and real-filesystem backends, the store, the file operations as values, and the policy gate on edits. Its library depends on nothing but std and sits at the bottom of the dependency stack. The real-filesystem backend keeps every path and every followed link inside its root. diff --git a/crates/runvil-internal/vfs/src/handle.rs b/crates/runvil-internal/vfs/src/handle.rs index f452ddb63..87fc308d1 100644 --- a/crates/runvil-internal/vfs/src/handle.rs +++ b/crates/runvil-internal/vfs/src/handle.rs @@ -41,6 +41,7 @@ mod case_fold; mod claims; mod claims_tree; mod forward; +mod lines; mod operations; mod prune; mod region; diff --git a/crates/runvil-internal/vfs/src/handle/lines.rs b/crates/runvil-internal/vfs/src/handle/lines.rs new file mode 100644 index 000000000..c50726989 --- /dev/null +++ b/crates/runvil-internal/vfs/src/handle/lines.rs @@ -0,0 +1,117 @@ +//! A text read under line bounds: the whole file or a 1-based inclusive +//! range of its lines, plain or with each line behind its number. + +use std::fmt::Write as _; + +use super::Access; +use crate::error::VfsError; + +/// Whether a text read prefixes each line with its absolute line number. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum LineNumbers { + /// The file's text verbatim. + Omitted, + /// Each line right-aligned behind its number and `"| "`. + Prefixed, +} + +/// Reads the file at `path` through `access` under optional line bounds, +/// numbering the lines as `numbers` says. +/// +/// No `start` reads the whole file; a present `start` slices a 1-based +/// inclusive line range. A negative bound converts to 0, which the range +/// validation rejects with the same error a zero bound produces, and an +/// `end` without a `start` is refused rather than silently ignored. +pub(super) fn read_lines( + access: &Access, + path: &str, + start: Option, + end: Option, + numbers: LineNumbers, +) -> Result { + let render: fn(&[&str], usize) -> String = match numbers { + LineNumbers::Prefixed => number_lines_from, + LineNumbers::Omitted => |lines, _| lines.join("\n"), + }; + match start { + None if end.is_some() => Err(VfsError::InvalidRange { + path: path.to_owned(), + reason: "start is required when end is given", + }), + None if numbers == LineNumbers::Omitted => access.read_string(path), + None => with_read_range(access, path, 1, None, render), + Some(start) => { + let start = usize::try_from(start).unwrap_or(0); + let end = end.map(|line| usize::try_from(line).unwrap_or(0)); + with_read_range(access, path, start, end, render) + } + } +} + +/// Reads and resolves one line range while its owned contents remain live. +fn with_read_range( + access: &Access, + path: &str, + start: usize, + end: Option, + render: impl FnOnce(&[&str], usize) -> String, +) -> Result { + let contents = access.read_string(path)?; + let lines: Vec<&str> = contents.lines().collect(); + let Some((start, end)) = resolve_line_range(path, lines.len(), start, end)? else { + return Ok(String::new()); + }; + Ok(render(&lines[start - 1..end], start)) +} + +/// Resolves 1-based inclusive bounds against `line_count` into the +/// effective `(start, end)`, or `None` when the range falls entirely past +/// the last line. Evaluation order is fixed: a `start` below 1 is an +/// error; a `start` past the last line reads as empty; an omitted `end` +/// means the last line, and a given `end` clamps down to it; an `end` +/// before `start` at that point is an error. +fn resolve_line_range( + path: &str, + line_count: usize, + start: usize, + end: Option, +) -> Result, VfsError> { + if start == 0 { + return Err(VfsError::InvalidRange { + path: path.to_owned(), + reason: "start must be at least 1", + }); + } + if start > line_count { + return Ok(None); + } + let end = end.unwrap_or(line_count).min(line_count); + if end < start { + return Err(VfsError::InvalidRange { + path: path.to_owned(), + reason: "end must not be before start", + }); + } + Ok(Some((start, end))) +} + +/// Renders `lines` numbered absolutely from `start`, each number +/// right-aligned to the width of the largest emitted number, followed by +/// `"| "`; lines are joined with `"\n"` and there is no trailing newline. +fn number_lines_from(lines: &[&str], start: usize) -> String { + if lines.is_empty() { + return String::new(); + } + let last = start + lines.len() - 1; + let width = last.to_string().len(); + let mut out = String::new(); + for (index, line) in lines.iter().enumerate() { + if index > 0 { + out.push('\n'); + } + let number = start + index; + // Writing to a String is infallible, so the result is discarded. + let _ = write!(out, "{number:>width$}| {line}"); + } + out +} diff --git a/crates/runvil-internal/vfs/src/handle/operations.rs b/crates/runvil-internal/vfs/src/handle/operations.rs index 31a1485a1..1ae7c679a 100644 --- a/crates/runvil-internal/vfs/src/handle/operations.rs +++ b/crates/runvil-internal/vfs/src/handle/operations.rs @@ -1,15 +1,58 @@ //! The capability's file operations: each gates its path, admits its -//! claims, and fires its event before it reaches the backend. +//! claims, and fires its event before it reaches the backend. One +//! [`VfsOp`] runs as the operation it names. use super::Access; use super::claims::Claims; +use super::lines::{LineNumbers, read_lines}; use super::store_view::{strip_root, validate_store_path}; use crate::error::{PathReason, VfsError}; use crate::glob::validate_glob_pattern; use crate::stat::{Entry, Stat}; use crate::traits::Op; +use crate::vfs_op::{VfsOp, VfsOutcome}; impl Access { + /// Runs `op`, one operation of the list, and returns its outcome. + /// + /// Each operation is one method of this access, under the checks that + /// method makes. `Read` and `ReadNumbered` read the file as UTF-8 + /// text and apply their line bounds. `Delete` succeeds on an absent + /// path, and `Remove` fails on one. + /// + /// # Errors + /// Returns the error of the method the operation names. A `Read` or a + /// `ReadNumbered` also returns [`VfsError::InvalidRange`] for a + /// `start` below 1, an `end` before `start`, or an `end` given with no + /// `start`. A `Remove` returns [`VfsError::NotFound`] when the path is + /// absent. + pub fn perform(&self, op: &VfsOp) -> Result { + let done = |()| VfsOutcome::Unit; + match op { + VfsOp::Write { path, contents } => self.write(path, contents).map(done), + VfsOp::Append { path, contents } => self.append(path, contents).map(done), + VfsOp::Read { path, start, end } => { + read_lines(self, path, *start, *end, LineNumbers::Omitted).map(VfsOutcome::Text) + } + VfsOp::ReadNumbered { path, start, end } => { + read_lines(self, path, *start, *end, LineNumbers::Prefixed).map(VfsOutcome::Text) + } + VfsOp::StrReplace { path, old, new } => self.str_replace(path, old, new).map(done), + VfsOp::Delete { path } => self.remove(path, false).map(|_| VfsOutcome::Unit), + VfsOp::Glob { pattern } => self.glob(pattern).map(VfsOutcome::Paths), + VfsOp::Exists { path } => self.exists(path).map(VfsOutcome::Bool), + VfsOp::Stat { path } => self.stat(path).map(VfsOutcome::Stat), + VfsOp::List { path } => self.list(path).map(VfsOutcome::Entries), + VfsOp::ReadRange { path, offset, len } => { + self.read_range(path, *offset, *len).map(VfsOutcome::Bytes) + } + VfsOp::Mkdir { path, recursive } => self.mkdir(path, *recursive).map(done), + VfsOp::Remove { path, recursive } => self.remove_present(path, *recursive).map(done), + VfsOp::Rename { from, to } => self.rename(from, to).map(done), + VfsOp::Copy { from, to } => self.copy(from, to).map(done), + } + } + /// Reads the bytes of the file at `path`, exactly as stored. /// /// # Errors @@ -123,6 +166,19 @@ impl Access { /// operation, or when the backend fails. A recursive removal claims /// the whole subtree under `path`. pub fn remove(&self, path: &str, recursive: bool) -> Result { + match self.remove_present(path, recursive) { + Ok(()) => Ok(true), + // The backend trait reports an absent path as NotFound; the + // public capability confirms the absence instead. + Err(VfsError::NotFound { .. }) => Ok(false), + Err(err) => Err(err), + } + } + + /// Removes the file, link, or directory at `path` under the checks of + /// [`Access::remove`], and reports an absent path as the backend + /// does, with [`VfsError::NotFound`]. + fn remove_present(&self, path: &str, recursive: bool) -> Result<(), VfsError> { let path = self.gate(Op::Delete, path)?; if recursive { self.admit(Claims::claim_subtree, &path)?; @@ -130,13 +186,7 @@ impl Access { self.admit(Claims::claim_write, &path)?; } self.fire(Op::Delete, &path); - match self.inner().remove(&path, recursive) { - Ok(()) => Ok(true), - // The backend trait reports an absent path as NotFound; the - // public capability confirms the absence instead. - Err(VfsError::NotFound { .. }) => Ok(false), - Err(err) => Err(err), - } + self.inner().remove(&path, recursive) } /// Reports whether anything exists at `path`. diff --git a/crates/runvil-internal/vfs/src/handle/tests.rs b/crates/runvil-internal/vfs/src/handle/tests.rs index 7cc782595..c996473ed 100644 --- a/crates/runvil-internal/vfs/src/handle/tests.rs +++ b/crates/runvil-internal/vfs/src/handle/tests.rs @@ -17,6 +17,7 @@ use crate::traits::{AcquireContext, Op, Policy, Verdict}; mod claims; mod happens_before; mod operations; +mod perform; mod read_range; mod refusals; mod regions; diff --git a/crates/runvil-internal/vfs/src/handle/tests/perform.rs b/crates/runvil-internal/vfs/src/handle/tests/perform.rs new file mode 100644 index 000000000..7d3f187c8 --- /dev/null +++ b/crates/runvil-internal/vfs/src/handle/tests/perform.rs @@ -0,0 +1,309 @@ +//! Tests for `Access::perform`: each operation of the list runs as the +//! method it names and returns that method's outcome, a text read applies +//! its line bounds, `Delete` and `Remove` differ on an absent path, and a +//! store view reports an operation's error in the caller's form. + +use super::*; +use crate::{FileType, Stat, Store, VfsOp, VfsOutcome}; + +/// The path every single-file case works on. +const FILE: &str = "/docs/a.md"; + +/// A write of `text` to `path`. +fn write(path: &str, text: &str) -> VfsOp { + VfsOp::Write { + path: path.to_owned(), + contents: text.as_bytes().to_vec(), + } +} + +/// A read of `path` under the line bounds `start` and `end`. +fn read(path: &str, start: Option, end: Option) -> VfsOp { + VfsOp::Read { + path: path.to_owned(), + start, + end, + } +} + +/// A numbered read of `path` under the line bounds `start` and `end`. +fn read_numbered(path: &str, start: Option, end: Option) -> VfsOp { + VfsOp::ReadNumbered { + path: path.to_owned(), + start, + end, + } +} + +/// The text `op`, a read, returns through `access`. +fn text_of(access: &Access, op: &VfsOp) -> Result { + match access.perform(op)? { + VfsOutcome::Text(text) => Ok(text), + other => panic!("a read returns text, got {other:?}"), + } +} + +/// The refusal of `op`, a read whose line bounds are invalid: its path +/// and its reason. +#[track_caller] +fn range_refusal(access: &Access, op: &VfsOp) -> (String, &'static str) { + match access.perform(op) { + Err(VfsError::InvalidRange { path, reason }) => (path, reason), + other => panic!("expected an invalid range, got {other:?}"), + } +} + +#[test] +fn each_operation_runs_as_the_method_it_names_and_returns_its_outcome() -> Result<(), VfsError> { + let access = access(&VfsRef::default())?; + let done = Ok(VfsOutcome::Unit); + let path = || FILE.to_owned(); + + let mkdir = VfsOp::Mkdir { + path: "/docs".to_owned(), + recursive: false, + }; + assert_eq!(access.perform(&mkdir), done); + assert_eq!(access.perform(&write(FILE, "one\ntwo")), done); + let append = VfsOp::Append { + path: path(), + contents: b"\nthree".to_vec(), + }; + assert_eq!(access.perform(&append), done); + assert_eq!( + access.perform(&read(FILE, None, None)), + Ok(VfsOutcome::Text("one\ntwo\nthree".to_owned())) + ); + assert_eq!( + access.perform(&read_numbered(FILE, Some(2), Some(3))), + Ok(VfsOutcome::Text("2| two\n3| three".to_owned())) + ); + let replace = VfsOp::StrReplace { + path: path(), + old: "two".to_owned(), + new: "TWO".to_owned(), + }; + assert_eq!(access.perform(&replace), done); + assert_eq!( + access.perform(&VfsOp::Exists { path: path() }), + Ok(VfsOutcome::Bool(true)) + ); + assert_eq!( + access.perform(&VfsOp::Stat { path: path() }), + Ok(VfsOutcome::Stat(Stat::new(FileType::File, 13))) + ); + let listed = access.perform(&VfsOp::List { + path: "/docs".to_owned(), + })?; + let VfsOutcome::Entries(entries) = listed else { + panic!("a listing returns entries, got {listed:?}"); + }; + let names: Vec<&str> = entries.iter().map(|entry| entry.name.as_str()).collect(); + assert_eq!(names, ["a.md"]); + let range = VfsOp::ReadRange { + path: path(), + offset: 4, + len: 3, + }; + assert_eq!( + access.perform(&range), + Ok(VfsOutcome::Bytes(b"TWO".to_vec())) + ); + let glob = VfsOp::Glob { + pattern: "/docs/*.md".to_owned(), + }; + assert_eq!(access.perform(&glob), Ok(VfsOutcome::Paths(vec![path()]))); + + let copy = VfsOp::Copy { + from: path(), + to: "/docs/b.md".to_owned(), + }; + assert_eq!(access.perform(©), done); + let rename = VfsOp::Rename { + from: "/docs/b.md".to_owned(), + to: "/docs/c.md".to_owned(), + }; + assert_eq!(access.perform(&rename), done); + assert_eq!(access.glob("/docs/*")?, [FILE, "/docs/c.md"]); + let remove = VfsOp::Remove { + path: "/docs/c.md".to_owned(), + recursive: false, + }; + assert_eq!(access.perform(&remove), done); + assert_eq!(access.perform(&VfsOp::Delete { path: path() }), done); + assert_eq!(access.glob("/docs/*")?, Vec::::new()); + Ok(()) +} + +#[test] +fn a_write_and_a_byte_read_hold_bytes_that_are_not_text() -> Result<(), VfsError> { + let access = access(&VfsRef::default())?; + let bytes = vec![0xff, 0x00, b'a']; + let write = VfsOp::Write { + path: "/blob.bin".to_owned(), + contents: bytes.clone(), + }; + access.perform(&write)?; + let whole = VfsOp::ReadRange { + path: "/blob.bin".to_owned(), + offset: 0, + len: u64::MAX, + }; + assert_eq!(access.perform(&whole), Ok(VfsOutcome::Bytes(bytes))); + // A text read of the same file is refused, at the first byte that is + // not UTF-8. + assert_eq!( + access.perform(&read("/blob.bin", None, None)), + Err(VfsError::NotUtf8 { + path: "/blob.bin".to_owned(), + valid_up_to: 0, + }) + ); + Ok(()) +} + +#[test] +fn delete_succeeds_on_an_absent_path_and_remove_fails_on_one() -> Result<(), VfsError> { + let access = access(&VfsRef::default())?; + let gone = || "/gone.md".to_owned(); + assert_eq!( + access.perform(&VfsOp::Delete { path: gone() }), + Ok(VfsOutcome::Unit) + ); + for recursive in [false, true] { + assert_eq!( + access.perform(&VfsOp::Remove { + path: gone(), + recursive, + }), + Err(VfsError::NotFound { path: gone() }), + "recursive: {recursive}" + ); + } + Ok(()) +} + +#[test] +fn remove_takes_a_directory_that_holds_entries_only_on_request() -> Result<(), VfsError> { + let access = access(&VfsRef::default())?; + access.write("/docs/a.md", b"kept")?; + let remove = |recursive| VfsOp::Remove { + path: "/docs".to_owned(), + recursive, + }; + assert_eq!( + access.perform(&remove(false)), + Err(VfsError::DirectoryNotEmpty { + path: "/docs".to_owned(), + }) + ); + assert_eq!(access.read("/docs/a.md")?, b"kept"); + assert_eq!(access.perform(&remove(true)), Ok(VfsOutcome::Unit)); + assert!(!access.exists("/docs")?); + Ok(()) +} + +#[test] +fn a_read_takes_a_one_based_inclusive_range_of_lines() -> Result<(), VfsError> { + let access = access(&VfsRef::default())?; + access.write("/f.txt", b"a\nb\nc\nd\n")?; + let lines = |start, end| text_of(&access, &read("/f.txt", start, end)); + assert_eq!( + lines(None, None)?, + "a\nb\nc\nd\n", + "the whole file verbatim" + ); + assert_eq!(lines(Some(2), Some(3))?, "b\nc"); + assert_eq!(lines(Some(3), None)?, "c\nd", "no end means the last line"); + assert_eq!( + lines(Some(2), Some(99))?, + "b\nc\nd", + "an end past the last line is the last line" + ); + assert_eq!(lines(Some(4), Some(4))?, "d"); + assert_eq!( + lines(Some(5), None)?, + "", + "a start past the last line reads nothing" + ); + Ok(()) +} + +#[test] +fn a_read_refuses_invalid_line_bounds_with_the_reason() -> Result<(), VfsError> { + let access = access(&VfsRef::default())?; + access.write("/f.txt", b"a\nb\nc")?; + let refused = |start, end| range_refusal(&access, &read("/f.txt", start, end)); + let at = |reason| ("/f.txt".to_owned(), reason); + assert_eq!(refused(Some(0), None), at("start must be at least 1")); + assert_eq!( + refused(Some(-3), Some(2)), + at("start must be at least 1"), + "a negative bound is refused as a zero bound is" + ); + assert_eq!( + refused(Some(3), Some(2)), + at("end must not be before start") + ); + assert_eq!( + refused(Some(2), Some(-1)), + at("end must not be before start") + ); + assert_eq!( + refused(None, Some(2)), + at("start is required when end is given") + ); + assert_eq!( + range_refusal(&access, &read_numbered("/f.txt", None, Some(2))), + at("start is required when end is given"), + "a numbered read takes the same bounds" + ); + Ok(()) +} + +#[test] +fn a_numbered_read_prefixes_each_line_with_its_number_in_the_file() -> Result<(), VfsError> { + let access = access(&VfsRef::default())?; + let lines: Vec = (1..=11).map(|line| format!("line {line}")).collect(); + access.write("/f.txt", lines.join("\n").as_bytes())?; + let numbered = |start, end| text_of(&access, &read_numbered("/f.txt", start, end)); + assert_eq!( + numbered(Some(9), Some(11))?, + " 9| line 9\n10| line 10\n11| line 11", + "each number is right-aligned to the widest one" + ); + assert_eq!(numbered(Some(2), Some(3))?, "2| line 2\n3| line 3"); + assert!( + numbered(None, None)?.starts_with(" 1| line 1\n 2| line 2\n"), + "no bounds numbers the whole file" + ); + assert_eq!(numbered(Some(12), None)?, ""); + Ok(()) +} + +#[test] +fn a_store_view_reports_an_operations_error_in_the_callers_form() -> Result<(), VfsError> { + let view = Store::new().view(&access(&VfsRef::default())?)?; + assert_eq!( + view.perform(&VfsOp::Remove { + path: "gone.md".to_owned(), + recursive: false, + }), + Err(VfsError::NotFound { + path: "gone.md".to_owned(), + }) + ); + assert_eq!( + view.perform(&read("gone.md", Some(1), Some(2))), + Err(VfsError::NotFound { + path: "gone.md".to_owned(), + }) + ); + view.perform(&write("notes.md", "one\ntwo"))?; + assert_eq!( + range_refusal(&view, &read("notes.md", Some(0), None)), + ("notes.md".to_owned(), "start must be at least 1") + ); + assert_eq!(text_of(&view, &read("notes.md", Some(2), None))?, "two"); + Ok(()) +} diff --git a/crates/runvil-internal/vfs/src/lib.rs b/crates/runvil-internal/vfs/src/lib.rs index 92f2641a3..e444d6836 100644 --- a/crates/runvil-internal/vfs/src/lib.rs +++ b/crates/runvil-internal/vfs/src/lib.rs @@ -1,7 +1,9 @@ //! The Runvil virtual filesystem and the editor mode policy over it. //! //! The machinery modules hold canonical paths, the claims model, the -//! mount router, the operation-observation seam, and the backends. The +//! mount router, the operation-observation seam, the backends, and the +//! file operations as values: a [`VfsOp`] is one operation with its +//! arguments, and [`Access::perform`] runs it. The //! crate root holds runvil policy: [`ModePolicy`], the editor mode //! gate. The machinery modules hold no runvil policy (no run //! concepts). A [`Store`] is generic machinery: an empty set of files in @@ -31,6 +33,7 @@ mod stat; #[cfg(test)] mod test_support; mod traits; +mod vfs_op; use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; @@ -43,6 +46,7 @@ pub use real::{RealBackend, Writability}; pub use router::VfsRefBuilder; pub use stat::{Entry, FileType, Stat}; pub use traits::{AcquireContext, AllowAll, ExecId, Op, Policy, Verdict, Vfs, VfsAccess}; +pub use vfs_op::{VfsOp, VfsOutcome}; /// The default handle has one mount: an empty in-memory backend at `/`. impl Default for VfsRef { diff --git a/crates/runvil-internal/vfs/src/vfs_op.rs b/crates/runvil-internal/vfs/src/vfs_op.rs new file mode 100644 index 000000000..526f6cf4b --- /dev/null +++ b/crates/runvil-internal/vfs/src/vfs_op.rs @@ -0,0 +1,165 @@ +//! The file operations as values: [`VfsOp`], one operation with its +//! arguments, and [`VfsOutcome`], what a performed operation returns. + +use crate::stat::{Entry, Stat}; +#[cfg(doc)] +use crate::{Access, Op, VfsError}; + +/// One file operation with its arguments, which [`Access::perform`] runs. +/// +/// The list serves two askers. The `store` functions of a prompt's Lua +/// use the first eight operations. A tool uses `Write`, `Append`, and the +/// last seven. +/// +/// The separate [`Op`] names only the kind of a file operation (`Read`, +/// `Write`, `Rename`, and so on), which a policy matches on and a watcher +/// is told about. +/// +/// The line bounds of `Read` and `ReadNumbered` are `i64`. A negative +/// bound converts to 0 when the operation runs, so the range check +/// rejects it with the same error a zero bound produces. +/// +/// The type holds only plain data, so an operation can be kept, compared, +/// and written to a record. +#[derive(Debug, Clone, PartialEq, Eq)] +#[non_exhaustive] +pub enum VfsOp { + /// Creates the file at `path`, or replaces its content, with + /// `contents`. + Write { + /// The path of the file. + path: String, + /// The bytes the file holds afterward. + contents: Vec, + }, + /// Adds `contents` to the end of the file at `path`, and creates the + /// file when it is absent. + Append { + /// The path of the file. + path: String, + /// The bytes to add. + contents: Vec, + }, + /// Reads the file at `path` as text. + /// + /// With both bounds omitted, it reads the whole file. With `start`, it + /// reads a 1-based inclusive range of lines. An `end` given alone is + /// an error. + Read { + /// The path of the file. + path: String, + /// The optional 1-based first line. + start: Option, + /// The optional 1-based last line. + end: Option, + }, + /// Reads like `Read` and prefixes each line with its line number in + /// the file. The bounds work the same way. + ReadNumbered { + /// The path of the file. + path: String, + /// The optional 1-based first line. + start: Option, + /// The optional 1-based last line. + end: Option, + }, + /// Replaces `old` with `new` in the file at `path`. + StrReplace { + /// The path of the file. + path: String, + /// The anchor text, which must occur exactly once. + old: String, + /// The replacement text. + new: String, + }, + /// Removes the file or empty directory at `path`, and succeeds when + /// the path is absent. A directory that still holds entries is + /// refused. + Delete { + /// The path to remove. + path: String, + }, + /// Lists the paths that match `pattern`. + Glob { + /// The glob pattern. + pattern: String, + }, + /// Reports whether anything exists at `path`. + Exists { + /// The path to test. + path: String, + }, + /// Returns the type and the length of what `path` names. + Stat { + /// The path to describe. + path: String, + }, + /// Lists the entries of the directory at `path`. + List { + /// The path of the directory. + path: String, + }, + /// Reads up to `len` bytes of the file at `path`, from the byte + /// `offset` on. + ReadRange { + /// The path of the file. + path: String, + /// The byte the read starts at. + offset: u64, + /// The most bytes the read returns. + len: u64, + }, + /// Creates the directory at `path`. + Mkdir { + /// The path of the directory. + path: String, + /// Whether to create the missing parent directories too. + recursive: bool, + }, + /// Removes the file or directory at `path`, and fails with + /// [`VfsError::NotFound`] when the path is absent. + Remove { + /// The path to remove. + path: String, + /// Whether to remove a directory that holds entries, with + /// everything under it. + recursive: bool, + }, + /// Moves the file or directory at `from` to `to`. + Rename { + /// The path to move. + from: String, + /// The path it moves to. + to: String, + }, + /// Copies the file at `from` to `to`. + Copy { + /// The path of the file to copy. + from: String, + /// The path of the copy. + to: String, + }, +} + +/// What one performed [`VfsOp`] returns. +#[derive(Debug, Clone, PartialEq, Eq)] +#[non_exhaustive] +pub enum VfsOutcome { + /// The operation succeeded and returns nothing: a write, an append, a + /// replacement, a delete, a directory creation, a removal, a rename, + /// or a copy. + Unit, + /// The text of a `Read` or a `ReadNumbered`: the whole file, or the + /// requested range of lines. + Text(String), + /// The paths that match the pattern of a `Glob`, in sorted order. + Paths(Vec), + /// Whether the path of an `Exists` exists. + Bool(bool), + /// The metadata of the path of a `Stat`. + Stat(Stat), + /// The entries of the directory of a `List`. + Entries(Vec), + /// The bytes of a `ReadRange`. + Bytes(Vec), +} diff --git a/crates/runvil/public-api.txt b/crates/runvil/public-api.txt index 888286a87..a4e5eb8ac 100644 --- a/crates/runvil/public-api.txt +++ b/crates/runvil/public-api.txt @@ -15,6 +15,8 @@ #[non_exhaustive] pub enum runvil::vfs::PathReason #[non_exhaustive] pub enum runvil::vfs::Verdict #[non_exhaustive] pub enum runvil::vfs::VfsError +#[non_exhaustive] pub enum runvil::vfs::VfsOp +#[non_exhaustive] pub enum runvil::vfs::VfsOutcome #[non_exhaustive] pub enum runvil::vfs::Writability #[non_exhaustive] pub struct runvil::RunLimits { .. } #[non_exhaustive] pub struct runvil::ToolId(/* private fields */) @@ -143,6 +145,8 @@ auto runvil::vfs::ScopeHandle: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindS auto runvil::vfs::Stat: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil::vfs::Verdict: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil::vfs::VfsError: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe +auto runvil::vfs::VfsOp: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe +auto runvil::vfs::VfsOutcome: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil::vfs::VfsPath: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil::vfs::VfsPathBuf: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil::vfs::VfsRef: Freeze, !RefUnwindSafe, Send, Sync, Unpin, !UnwindSafe @@ -243,6 +247,8 @@ derives runvil::vfs::ScopeHandle: Clone, Debug derives runvil::vfs::Stat: Clone, Debug, Eq, Hash, PartialEq derives runvil::vfs::Verdict: Clone, Debug, Eq, PartialEq derives runvil::vfs::VfsError: Clone, Debug, Eq, PartialEq +derives runvil::vfs::VfsOp: Clone, Debug, Eq, PartialEq +derives runvil::vfs::VfsOutcome: Clone, Debug, Eq, PartialEq derives runvil::vfs::VfsPath: Clone, Debug, Eq, Hash, PartialEq derives runvil::vfs::VfsPathBuf: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd derives runvil::vfs::VfsRef: Clone, Debug, Default @@ -558,6 +564,7 @@ pub fn runvil::vfs::Access::exists(&self, path: &str) -> core::result::Result core::result::Result, runvil::vfs::VfsError> pub fn runvil::vfs::Access::list(&self, path: &str) -> core::result::Result, runvil::vfs::VfsError> pub fn runvil::vfs::Access::mkdir(&self, path: &str, recursive: bool) -> core::result::Result<(), runvil::vfs::VfsError> +pub fn runvil::vfs::Access::perform(&self, op: &runvil::vfs::VfsOp) -> core::result::Result pub fn runvil::vfs::Access::read(&self, path: &str) -> core::result::Result, runvil::vfs::VfsError> pub fn runvil::vfs::Access::read_range(&self, path: &str, offset: u64, len: u64) -> core::result::Result, runvil::vfs::VfsError> pub fn runvil::vfs::Access::read_string(&self, path: &str) -> core::result::Result @@ -1151,6 +1158,63 @@ pub runvil::vfs::VfsError::ScopeEnded::path: alloc::string::String pub runvil::vfs::VfsError::Unsupported { .. } pub runvil::vfs::VfsError::Unsupported::detail: alloc::string::String pub runvil::vfs::VfsError::Unsupported::path: alloc::string::String +pub runvil::vfs::VfsOp::Append { .. } +pub runvil::vfs::VfsOp::Append::contents: alloc::vec::Vec +pub runvil::vfs::VfsOp::Append::path: alloc::string::String +pub runvil::vfs::VfsOp::Copy { .. } +pub runvil::vfs::VfsOp::Copy::from: alloc::string::String +pub runvil::vfs::VfsOp::Copy::to: alloc::string::String +pub runvil::vfs::VfsOp::Delete { .. } +pub runvil::vfs::VfsOp::Delete::path: alloc::string::String +pub runvil::vfs::VfsOp::Exists { .. } +pub runvil::vfs::VfsOp::Exists::path: alloc::string::String +pub runvil::vfs::VfsOp::Glob { .. } +pub runvil::vfs::VfsOp::Glob::pattern: alloc::string::String +pub runvil::vfs::VfsOp::List { .. } +pub runvil::vfs::VfsOp::List::path: alloc::string::String +pub runvil::vfs::VfsOp::Mkdir { .. } +pub runvil::vfs::VfsOp::Mkdir::path: alloc::string::String +pub runvil::vfs::VfsOp::Mkdir::recursive: bool +pub runvil::vfs::VfsOp::Read { .. } +pub runvil::vfs::VfsOp::Read::end: core::option::Option +pub runvil::vfs::VfsOp::Read::path: alloc::string::String +pub runvil::vfs::VfsOp::Read::start: core::option::Option +pub runvil::vfs::VfsOp::ReadNumbered { .. } +pub runvil::vfs::VfsOp::ReadNumbered::end: core::option::Option +pub runvil::vfs::VfsOp::ReadNumbered::path: alloc::string::String +pub runvil::vfs::VfsOp::ReadNumbered::start: core::option::Option +pub runvil::vfs::VfsOp::ReadRange { .. } +pub runvil::vfs::VfsOp::ReadRange::len: u64 +pub runvil::vfs::VfsOp::ReadRange::offset: u64 +pub runvil::vfs::VfsOp::ReadRange::path: alloc::string::String +pub runvil::vfs::VfsOp::Remove { .. } +pub runvil::vfs::VfsOp::Remove::path: alloc::string::String +pub runvil::vfs::VfsOp::Remove::recursive: bool +pub runvil::vfs::VfsOp::Rename { .. } +pub runvil::vfs::VfsOp::Rename::from: alloc::string::String +pub runvil::vfs::VfsOp::Rename::to: alloc::string::String +pub runvil::vfs::VfsOp::Stat { .. } +pub runvil::vfs::VfsOp::Stat::path: alloc::string::String +pub runvil::vfs::VfsOp::StrReplace { .. } +pub runvil::vfs::VfsOp::StrReplace::new: alloc::string::String +pub runvil::vfs::VfsOp::StrReplace::old: alloc::string::String +pub runvil::vfs::VfsOp::StrReplace::path: alloc::string::String +pub runvil::vfs::VfsOp::Write { .. } +pub runvil::vfs::VfsOp::Write::contents: alloc::vec::Vec +pub runvil::vfs::VfsOp::Write::path: alloc::string::String +pub runvil::vfs::VfsOutcome::Bool(..) +pub runvil::vfs::VfsOutcome::Bool::0: bool +pub runvil::vfs::VfsOutcome::Bytes(..) +pub runvil::vfs::VfsOutcome::Bytes::0: alloc::vec::Vec +pub runvil::vfs::VfsOutcome::Entries(..) +pub runvil::vfs::VfsOutcome::Entries::0: alloc::vec::Vec +pub runvil::vfs::VfsOutcome::Paths(..) +pub runvil::vfs::VfsOutcome::Paths::0: alloc::vec::Vec +pub runvil::vfs::VfsOutcome::Stat(..) +pub runvil::vfs::VfsOutcome::Stat::0: runvil::vfs::Stat +pub runvil::vfs::VfsOutcome::Text(..) +pub runvil::vfs::VfsOutcome::Text::0: alloc::string::String +pub runvil::vfs::VfsOutcome::Unit pub runvil::vfs::Writability::ReadOnly pub runvil::vfs::Writability::ReadWrite pub struct runvil::Error { .. } diff --git a/crates/runvil/src/lib.rs b/crates/runvil/src/lib.rs index 40a9a6361..7fb88ae0f 100644 --- a/crates/runvil/src/lib.rs +++ b/crates/runvil/src/lib.rs @@ -205,8 +205,9 @@ pub mod vfs { //! A run's files: the handle to the virtual filesystem a Host gives //! each run for its tool calls, real directories among its mounts, //! the policy that decides what those calls may change, the access - //! each tool call receives through its context, and the origin each - //! file operation carries to say who asked for it. No store of a run + //! each tool call receives through its context, the file operations + //! as values that an access performs, and the origin each file + //! operation carries to say who asked for it. No store of a run //! is part of that filesystem: each run has an empty store of its //! own, and one more for each prompt it executes, which a Host //! neither fills nor reads. @@ -233,6 +234,8 @@ pub mod vfs { pub use runvil_engine::vfs::Vfs; pub use runvil_engine::vfs::VfsAccess; pub use runvil_engine::vfs::VfsError; + pub use runvil_engine::vfs::VfsOp; + pub use runvil_engine::vfs::VfsOutcome; pub use runvil_engine::vfs::VfsPath; pub use runvil_engine::vfs::VfsPathBuf; pub use runvil_engine::vfs::VfsRef; diff --git a/decisions/engine.md b/decisions/engine.md index f5ee3f870..58a9f2930 100644 --- a/decisions/engine.md +++ b/decisions/engine.md @@ -130,7 +130,7 @@ A `Round` has only these two values, because a caller needs only a round's id an ### `Effect::Vfs` is one `store` operation -The Engine issues a `Vfs` effect for each `store.*` call. Its fields are `store`, the id of the store that the call works on, `access`, the calling chain's view of that store, and `op`, a `VfsOp` with the call's arguments. A caller answers it with `perform_vfs_op(&access, op)`, a synchronous function ([Files and the VFS](files-and-the-vfs.md)). +The Engine issues a `Vfs` effect for each `store.*` call. Its fields are `store`, the id of the store that the call works on, `access`, the calling chain's view of that store, and `op`, a `VfsOp` with the call's arguments. A caller answers it with `perform_vfs_op(&access, &op)`, a synchronous function that runs the operation with `Access::perform` ([Files and the VFS](files-and-the-vfs.md)). A run has more than one store when a prompt executes another, so the effect names its store. The `store` field is a `ChainId`: `0`, the id of the root chain, for the store that a run starts with, and the id of an executed prompt's chain, such as `0.0`, for a store that an `execute` made. The view alone would be enough to perform the operation, and the id is there for the record. diff --git a/decisions/files-and-the-vfs.md b/decisions/files-and-the-vfs.md index c2b50ad96..2920a8cf1 100644 --- a/decisions/files-and-the-vfs.md +++ b/decisions/files-and-the-vfs.md @@ -48,6 +48,12 @@ For each `store` call the Engine derives a store view from the calling chain's s The store follows one rule: it offers a subset of the operations of the VFS. A store is a value and not a mount of a handle, because one scope has to hold many stores. A child prompt that `execute` runs gets a store of its own, and it runs in its caller's scope under its caller's identity. The owner's rule: "prompts passed to execute or execute_async should get their own store which is completely isolated from the caller's store. they cannot see each others' paths or claims." +### One list of operations serves the `store` functions and a tool's file requests + +`runvil-vfs` defines the file operations as values. A `VfsOp` is one operation with its arguments, `Access::perform` runs it on an `Access`, and a `VfsOutcome` is what it returns. The `store` functions use `Write`, `Append`, `Read`, `ReadNumbered`, `StrReplace`, `Delete`, `Glob`, and `Exists`, and each `store` call is one of them. The list also has the operations that a tool asks for: `Stat`, `List`, `ReadRange`, `Mkdir`, `Remove`, `Rename`, and `Copy`, beside `Write` and `Append`. `Write` and `Append` hold bytes, because a tool writes bytes, and a `store` call passes the bytes of its text. `Delete` succeeds on an absent path, and `Remove` fails on one with `VfsError::NotFound`. They are two operations, so a run's record shows which one ran. + +The owner's reason for one list: "in principle, the store is just a virtual directory in the file system that is unique to a prompt." A `store` call and a tool's file request are two views of the same operations, and the Engine and the Harness handle the whole list, so either side gains an operation by adding one function. A `store` call reaches the list as an effect today, and a tool's request will once a tool's file operations are effects (see Planned work). + ### Virtual paths have one POSIX form on every operating system A virtual path is rooted and uses forward slashes on every operating system. An `Access` canonicalizes each path when it receives it, so the policy, the claims table, and the backend see one spelling. A path without a leading `/` is relative to `/`. From 2116c853c0e4fe02fec04167ec807d29a454d56b Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Tue, 17 Nov 2026 19:18:36 -0800 Subject: [PATCH 04/23] Issue a tool's file request as a `Vfs` effect A tool that needs a file operation now asks through the run, so that the record of the run holds the operation. `Run::request_file` issues the operation as an `Effect::Vfs` whose `asker` is the open tool call, with the access that `ToolCallContinuation` keeps, and the caller answers it with `EffectAnswer::VfsReceipt`. The `store` field of `Effect::Vfs` becomes `asker`, a `VfsAsker`, and the record of a `store` call keeps its JSON. - `Continuation::ToolVfs` keys the effect under the chain that awaits the call, so the abort of the chain withdraws the effect with the call. Its answer resumes no chain: a receipt, a failure, and `Dropped` all return from `apply_answer` with no change. - `VfsAsker` and `VfsReceipt` are `#[non_exhaustive]`, so a `match` in another crate needs a wildcard arm. - `EffectRecord::Vfs` flattens the asker into one key beside `op`: `store` for the Lua of the prompt, and `call`, the effect id, for a tool call. `AnswerRecord::VfsReceipt` writes the receipt through `VfsReceiptRecord`. - The mismatch arms of `apply_answer` are now one arm that lists every `Continuation` and every `EffectAnswer` but `Dropped`. The function stays under the size limit, and a new variant of either enum still fails the build there. - `request_file` is in `drive.rs` beside `resume`, because both end the run through the private `end`. - A request for a call whose chain stopped waiting does nothing. A request for an id with no awaited tool call ends the run with an internal error. A request after `Done` does nothing. - `EffectAnswer::Vfs` for the effect of a tool, and `EffectAnswer::VfsReceipt` for a `store` call, end the run with the internal error of a wrong kind. - `VfsReceipt::of` gives a byte count for `Text` and `Bytes`, a `Count` for `Paths` and `Entries`, the value for a stat and a bool, and `Done` for the rest. - The effect is stamped when `request_file` runs, and the next `step` returns it before the effects that the step issues. - No caller reports a request. The loop in `effect_loop.rs` only takes the new field. - `Effect::ToolCall` still holds `access`. - No test covers a request on a run before its first `step`. Plan: /plan/2026-11-16-1-tool-file-effects.plan.md --- AGENTS.md | 2 +- .../runner/src/effect_loop.rs | 8 +- crates/runvil-engine/public-api.txt | 25 +- crates/runvil-engine/src/lib.rs | 5 + crates/runvil-internal/runtime/README.md | 2 +- crates/runvil-internal/runtime/src/execute.rs | 21 +- .../runtime/src/execute/run.rs | 53 +- .../src/execute/run/effect-tests-files.rs | 130 +++++ .../runtime/src/execute/run/effect-tests.rs | 21 +- .../runtime/src/execute/run/effect.rs | 197 ++++++-- .../runtime/src/execute/run/tests-files.rs | 464 ++++++++++++++++++ .../runtime/src/execute/run/tests.rs | 10 +- .../runtime/src/execute/run/vfs_record.rs | 139 +++++- .../runtime/src/execute/scheduler/apply.rs | 65 ++- .../runtime/src/execute/scheduler/dispatch.rs | 6 +- .../runtime/src/execute/scheduler/drive.rs | 45 +- .../runtime/src/execute/scheduler/effects.rs | 131 ++++- .../src/execute/scheduler/tool_call.rs | 14 +- .../runtime/src/execute/tests/effects.rs | 9 +- .../src/execute/tests/execute/store.rs | 15 +- .../runtime/src/execute/tests/preludes.rs | 15 +- crates/runvil-internal/runtime/src/lib.rs | 8 +- decisions/engine.md | 36 +- decisions/files-and-the-vfs.md | 2 +- decisions/harness-and-host.md | 2 +- 25 files changed, 1265 insertions(+), 160 deletions(-) create mode 100644 crates/runvil-internal/runtime/src/execute/run/effect-tests-files.rs create mode 100644 crates/runvil-internal/runtime/src/execute/run/tests-files.rs diff --git a/AGENTS.md b/AGENTS.md index 79697e108..68c7664b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ Multi-crate Rust workspace for the Engine, the Harness that runs it, and the Rus Seven terms have exactly one meaning each, everywhere in this repository: code comments, docs, rulebooks, and plans. Write them capitalized. -- **Engine**: the `runvil-*` crates. The Engine parses a prompt and steps a run. Whenever a run needs a model reply, a Pack's render of the tools a section offers it, a Pack tool's result, a timer, or a store operation, the Engine emits an effect and waits for its caller to answer it. In production the caller is the Harness. +- **Engine**: the `runvil-*` crates. The Engine parses a prompt and steps a run. Whenever a run needs a model reply, a Pack's render of the tools a section offers it, a Pack tool's result, a timer, or a file operation, the Engine emits an effect and waits for its caller to answer it. In production the caller is the Harness. - **Harness**: the `runvil` crate, which is the one crate a Host depends on, and the `harness-*` crates. The Harness steps the Engine, performs every effect, returns each answer, and records every run through the recorder the Host supplies. Production code runs prompts only through the Harness. - **Host**: an application that runs prompts through the Harness, such as Workshop or Papergate. The Host makes every policy decision. It may also use the Engine's parser and types to read prompts and show events. - **Pack**: code which installs an optional native prelude, an optional Lua prelude, and zero or more tools. diff --git a/crates/harness-internal/runner/src/effect_loop.rs b/crates/harness-internal/runner/src/effect_loop.rs index 4e2ccdcef..31fe7044e 100644 --- a/crates/harness-internal/runner/src/effect_loop.rs +++ b/crates/harness-internal/runner/src/effect_loop.rs @@ -495,11 +495,11 @@ impl Driver { .queue(id, provenance.clone(), survives_stop, Box::pin(call)); return None; } - // The effect's record, written before this call, names the - // store, and the view reaches no other, so the store's id has - // no use here. + // The effect's record, written before this call, names who + // asked. The loop reports no request of a tool to the run, so + // the prompt's Lua asked, and the view reaches its store alone. Effect::Vfs { - store: _, + asker: _, access, op, } => return Some((access, op)), diff --git a/crates/runvil-engine/public-api.txt b/crates/runvil-engine/public-api.txt index ec96af7bf..780774983 100644 --- a/crates/runvil-engine/public-api.txt +++ b/crates/runvil-engine/public-api.txt @@ -1,5 +1,7 @@ #[non_exhaustive] pub enum runvil_engine::OutputTrust #[non_exhaustive] pub enum runvil_engine::effect::ToolCaller +#[non_exhaustive] pub enum runvil_engine::effect::VfsAsker +#[non_exhaustive] pub enum runvil_engine::effect::VfsReceipt #[non_exhaustive] pub enum runvil_engine::event::Event #[non_exhaustive] pub enum runvil_engine::event::ReplyOrigin #[non_exhaustive] pub enum runvil_engine::ids::AbandonReason @@ -74,6 +76,8 @@ auto runvil_engine::effect::IssuedEffect: Freeze, !RefUnwindSafe, Send, Sync, Un auto runvil_engine::effect::Round: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil_engine::effect::ToolCallOrigin: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil_engine::effect::ToolCaller: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe +auto runvil_engine::effect::VfsAsker: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe +auto runvil_engine::effect::VfsReceipt: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil_engine::event::Event: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil_engine::event::ReplyOrigin: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe auto runvil_engine::ids::AbandonReason: Freeze, RefUnwindSafe, Send, Sync, Unpin, UnwindSafe @@ -164,6 +168,8 @@ derives runvil_engine::effect::IssuedEffect: Debug derives runvil_engine::effect::Round: Clone, Copy, Debug, Eq, PartialEq derives runvil_engine::effect::ToolCallOrigin: Clone, Debug, Deserialize, Eq, PartialEq, Serialize derives runvil_engine::effect::ToolCaller: Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize +derives runvil_engine::effect::VfsAsker: Clone, Debug, Eq, PartialEq +derives runvil_engine::effect::VfsReceipt: Clone, Debug, Eq, PartialEq derives runvil_engine::event::Event: Clone, Debug, Deserialize, PartialEq, Serialize derives runvil_engine::event::ReplyOrigin: Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize derives runvil_engine::ids::AbandonReason: Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize @@ -319,6 +325,7 @@ pub fn runvil_engine::Prompt::parse(finder: &dyn runvil_engine::PromptFinder, na pub fn runvil_engine::PromptFinder::find(&self, name: &str) -> core::result::Result pub fn runvil_engine::Run::deliver(&mut self, text: alloc::string::String) -> alloc::vec::Vec pub fn runvil_engine::Run::new(prompt: alloc::sync::Arc, args: &str, params: runvil_engine::RunParams) -> runvil_engine::Run +pub fn runvil_engine::Run::request_file(&mut self, call: runvil_engine::effect::EffectId, op: runvil_engine::vfs::VfsOp) pub fn runvil_engine::Run::resume(&mut self, id: runvil_engine::effect::EffectId, answer: runvil_engine::effect::EffectAnswer) pub fn runvil_engine::Run::step(&mut self) -> runvil_engine::Step pub fn runvil_engine::RunParams::new(seed: runvil_engine::RunSeed, started_at: runvil_engine::Timestamp) -> runvil_engine::RunParams @@ -362,6 +369,7 @@ pub fn runvil_engine::effect::Round::new(id: runvil_engine::ids::RoundId, origin pub fn runvil_engine::effect::ToolCallOrigin::new(section: impl core::convert::Into, caller: runvil_engine::effect::ToolCaller) -> runvil_engine::effect::ToolCallOrigin pub fn runvil_engine::effect::ToolCallOrigin::with_entry(self, entry: impl core::convert::Into) -> runvil_engine::effect::ToolCallOrigin pub fn runvil_engine::effect::ToolCallOrigin::with_model(self, model: impl core::convert::Into) -> runvil_engine::effect::ToolCallOrigin +pub fn runvil_engine::effect::VfsReceipt::of(outcome: &runvil_engine::vfs::VfsOutcome) -> runvil_engine::effect::VfsReceipt pub fn runvil_engine::event::Event::provenance(&self) -> &runvil_engine::ids::Provenance pub fn runvil_engine::event::Event::section(&self) -> &str pub fn runvil_engine::ids::AbandonReason::why(self) -> &'static str @@ -718,8 +726,8 @@ pub runvil_engine::effect::Effect::ToolCall::survives_stop: bool pub runvil_engine::effect::Effect::ToolCall::tool: runvil_engine::ToolId pub runvil_engine::effect::Effect::Vfs { .. } pub runvil_engine::effect::Effect::Vfs::access: alloc::sync::Arc +pub runvil_engine::effect::Effect::Vfs::asker: runvil_engine::effect::VfsAsker pub runvil_engine::effect::Effect::Vfs::op: runvil_engine::vfs::VfsOp -pub runvil_engine::effect::Effect::Vfs::store: runvil_engine::ids::ChainId pub runvil_engine::effect::EffectAnswer::Chat(..) pub runvil_engine::effect::EffectAnswer::Chat::0: core::result::Result, runvil_engine::Error> pub runvil_engine::effect::EffectAnswer::Dropped @@ -730,6 +738,8 @@ pub runvil_engine::effect::EffectAnswer::ToolCall(..) pub runvil_engine::effect::EffectAnswer::ToolCall::0: core::result::Result pub runvil_engine::effect::EffectAnswer::Vfs(..) pub runvil_engine::effect::EffectAnswer::Vfs::0: core::result::Result +pub runvil_engine::effect::EffectAnswer::VfsReceipt(..) +pub runvil_engine::effect::EffectAnswer::VfsReceipt::0: core::result::Result pub runvil_engine::effect::IssuedEffect::effect: runvil_engine::effect::Effect pub runvil_engine::effect::IssuedEffect::id: runvil_engine::effect::EffectId pub runvil_engine::effect::IssuedEffect::provenance: runvil_engine::ids::Provenance @@ -744,6 +754,19 @@ pub runvil_engine::effect::ToolCallOrigin::model: core::option::Option pub runvil_engine::event::Event::AssistantReply::metrics: core::option::Option diff --git a/crates/runvil-engine/src/lib.rs b/crates/runvil-engine/src/lib.rs index 2d037c0f0..e4e564ed8 100644 --- a/crates/runvil-engine/src/lib.rs +++ b/crates/runvil-engine/src/lib.rs @@ -6,6 +6,9 @@ //! prompt it lists with `execute`, inside the same run. //! [`Run::step`] returns [`Step::Pending`] with the effects the run waits on. //! The caller performs each effect and hands its answer to [`Run::resume`]. +//! A tool whose call is open asks the caller for each file operation it +//! needs, and the caller reports the request with [`Run::request_file`], +//! so the run issues that operation as an effect too. //! The run ends at [`Step::Done`] with its result: the final text, or the //! [`Error`] that ended it. A cancel is the error whose code //! is [`ErrorCode::Canceled`]. @@ -64,6 +67,8 @@ pub mod effect { pub use runvil_runtime::Round; pub use runvil_runtime::ToolCallOrigin; pub use runvil_runtime::ToolCaller; + pub use runvil_runtime::VfsAsker; + pub use runvil_runtime::VfsReceipt; } pub mod event { diff --git a/crates/runvil-internal/runtime/README.md b/crates/runvil-internal/runtime/README.md index c0f1b3ee9..fd8434e1e 100644 --- a/crates/runvil-internal/runtime/README.md +++ b/crates/runvil-internal/runtime/README.md @@ -1,3 +1,3 @@ # Engine executor -This crate is the Engine's executor: it runs a parsed prompt as a deterministic state machine. Each model round, Pack render, Pack tool call, `store` operation, and timer leaves the executor as an effect for the Harness to perform and answer, and every boundary is reported as an event. A run ends with its result: the final text, or the error that ended it, where a cancel is the error whose code is `Canceled`. Adhoc tool calls, `GetDynamicTools` calls, and refused discovery calls run inside the Engine and are reported only as events. A prompt runs another prompt its frontmatter lists with `execute`, as a chain of the same run. The Engine makes each run an empty store of its own, and one more for each prompt the run executes, in memory and outside the filesystem the run's tool calls work in, and a store is reached only through the view of each `store` effect on it. Given the same prompt, arguments, and `RunParams` inputs, its seed and start time included, and the same answers delivered in the same order at the same steps, a run produces the same effects, events, and result. +This crate is the Engine's executor: it runs a parsed prompt as a deterministic state machine. Each model round, Pack render, Pack tool call, file operation, and timer leaves the executor as an effect for the Harness to perform and answer, and every boundary is reported as an event. A file operation is a `store` call of the prompt's Lua, or a file request of an open tool call that the caller reports to the run. A run ends with its result: the final text, or the error that ended it, where a cancel is the error whose code is `Canceled`. Adhoc tool calls, `GetDynamicTools` calls, and refused discovery calls run inside the Engine and are reported only as events. A prompt runs another prompt its frontmatter lists with `execute`, as a chain of the same run. The Engine makes each run an empty store of its own, and one more for each prompt the run executes, in memory and outside the filesystem the run's tool calls work in, and a store is reached only through the view of each `store` effect on it. Given the same prompt, arguments, and `RunParams` inputs, its seed and start time included, and the same answers delivered in the same order at the same steps, a run produces the same effects, events, and result. diff --git a/crates/runvil-internal/runtime/src/execute.rs b/crates/runvil-internal/runtime/src/execute.rs index 938f05da7..2df80d892 100644 --- a/crates/runvil-internal/runtime/src/execute.rs +++ b/crates/runvil-internal/runtime/src/execute.rs @@ -57,16 +57,17 @@ pub use params::{RunLimits, RunParams}; pub(crate) use run::{AnswerRecord, ChatAnswerRecord, EffectRecord}; pub use run::{ Effect, EffectAnswer, EffectId, IssuedEffect, PackToolSets, Round, Run, Step, ToolCallOrigin, - ToolCaller, + ToolCaller, VfsAsker, VfsReceipt, }; use runvil_vfs::{Access, VfsError, VfsOp, VfsOutcome}; -/// Performs the store operation of an [`Effect::Vfs`] and returns its answer. +/// Performs the operation of an [`Effect::Vfs`] and returns its outcome. /// -/// `access` is the store view the effect carries: a view of the calling -/// chain's store under the chain's identity, made when the effect is -/// dispatched. -/// The function runs `op` with [`Access::perform`] on that view, so the +/// `access` is the access the effect carries: for a `store` call, a view +/// of the calling chain's store under the chain's identity, made when the +/// effect is dispatched, and for a tool's request, the tool call's own +/// access. +/// The function runs `op` with [`Access::perform`] on that access, so the /// caller answers a `Vfs` effect exactly as the Engine's own test drivers /// do. Line bounds arrive as `i64` and convert to `usize`. A read that /// gives an `end` and omits `start` is refused as an invalid range. @@ -77,10 +78,10 @@ use runvil_vfs::{Access, VfsError, VfsOp, VfsOutcome}; /// for it. /// /// # Errors -/// Returns the store's own structured failure for the operation (path -/// validation, not-found, anchor, range, or conflict). -/// When the caller resumes the run with that answer, the Engine raises -/// the failure at the prompt author's call site. +/// Returns the operation's own structured failure (path validation, +/// not-found, anchor, range, or conflict). +/// When the caller resumes the run with that answer to a `store` call, +/// the Engine raises the failure at the prompt author's call site. pub fn perform_vfs_op(access: &Access, op: &VfsOp) -> std::result::Result { access.perform(op) } diff --git a/crates/runvil-internal/runtime/src/execute/run.rs b/crates/runvil-internal/runtime/src/execute/run.rs index c421ea903..e2b2fa579 100644 --- a/crates/runvil-internal/runtime/src/execute/run.rs +++ b/crates/runvil-internal/runtime/src/execute/run.rs @@ -3,8 +3,9 @@ //! documented on the `runvil-engine` facade's crate page and its `effect` and //! `cancel` modules. //! -//! The effect vocabulary - [`Effect`] with its [`Round`] and -//! [`PackToolSets`], [`EffectAnswer`], [`EffectId`], and the +//! The effect vocabulary - [`Effect`] with its [`Round`], +//! [`PackToolSets`], and [`VfsAsker`], [`EffectAnswer`] with its +//! [`VfsReceipt`], [`EffectId`], and the //! [`ToolCallOrigin`] and [`ToolCaller`] it re-exports from //! `runvil-types` - comes from the `effect` child module and is //! re-exported here. The records of effects and answers stay in that @@ -17,13 +18,17 @@ use std::sync::Arc; use runvil_types::error::Error; use runvil_types::event::Event; use runvil_types::ids::Provenance; +use runvil_vfs::VfsOp; mod effect; mod vfs_record; #[cfg(test)] pub(crate) use effect::{AnswerRecord, ChatAnswerRecord, EffectRecord}; -pub use effect::{Effect, EffectAnswer, EffectId, PackToolSets, Round, ToolCallOrigin, ToolCaller}; +pub use effect::{ + Effect, EffectAnswer, EffectId, PackToolSets, Round, ToolCallOrigin, ToolCaller, VfsAsker, + VfsReceipt, +}; use crate::prompt::Prompt; @@ -40,11 +45,13 @@ use super::scheduler::Scheduler; pub enum Step { /// The run continues. Pending { - /// The effects this step issued, in issue order, each with the - /// provenance of the task that built it, for the caller to perform - /// and answer through [`Run::resume`]. An empty list means the run - /// waits on effects an earlier step issued, or, when - /// `waiting_for_input` is set, on the main chain's next message. + /// The effects issued since the previous step, in issue order, + /// each with the provenance of the task that built it, for the + /// caller to perform and answer through [`Run::resume`]: those + /// [`Run::request_file`] issued for a tool's file requests, then + /// those this step issued. An empty list means the run waits on + /// effects an earlier step issued, or, when `waiting_for_input` + /// is set, on the main chain's next message. effects: Vec, /// The events reported since the previous step, in order, less /// those [`Run::deliver`] already returned. @@ -207,9 +214,12 @@ impl Run { /// /// Each answer must match the kind of its effect: a chat answer for a /// `Chat` effect, a tool answer for a `ToolCall` effect, and so on. A - /// mismatch is an internal error that ends the run. So is an answer for - /// an id the run never issued, or a second answer for one effect. An - /// answer for an effect whose chain stopped waiting is discarded. + /// `Vfs` effect takes [`EffectAnswer::Vfs`] when the prompt's Lua + /// asked for it and [`EffectAnswer::VfsReceipt`] when a tool call + /// did. A mismatch is an internal error that ends the run. So is an + /// answer for an id the run never issued, or a second answer for one + /// effect. An answer for an effect whose chain stopped waiting is + /// discarded. /// /// `resume` cannot fail: a bad answer ends the run with an internal /// error, which the result of [`Step::Done`] holds, instead of @@ -234,6 +244,27 @@ impl Run { self.scheduler.deliver_message(text) } + /// Reports one file request of an open tool call: the tool behind the + /// `ToolCall` effect `call` asks for `op`. + /// + /// The run issues the operation as an [`Effect::Vfs`] whose asker is + /// the call, under the task that made the call and with the call's + /// own access, and the next `step` returns it. The caller performs + /// the operation, hands the whole outcome to the tool, and answers + /// the effect with [`EffectAnswer::VfsReceipt`]. That answer resumes + /// no chain, and a failure in it ends nothing: the tool call stays + /// open until the caller answers it with the tool's result. + /// + /// A request for a call whose chain stopped waiting, one a step + /// listed as withdrawn, is discarded. A request for any other id is a + /// caller error that ends the run with an internal error, as a bad + /// answer does: an id the run never issued, a call already answered, + /// or an effect that is no tool call. A run that has returned `Done` + /// ignores the request. + pub fn request_file(&mut self, call: EffectId, op: VfsOp) { + self.scheduler.request_file(call, op); + } + /// Whether the run's result is decided: it has reported its end /// event, or found at its first step that it cannot start. For the /// suites that pin when a run is decided apart from what its steps diff --git a/crates/runvil-internal/runtime/src/execute/run/effect-tests-files.rs b/crates/runvil-internal/runtime/src/execute/run/effect-tests-files.rs new file mode 100644 index 000000000..1f26ead23 --- /dev/null +++ b/crates/runvil-internal/runtime/src/execute/run/effect-tests-files.rs @@ -0,0 +1,130 @@ +//! The records of a file operation that a tool call asked for: the +//! effect's record names the call by its effect id where a `store` call's +//! names its store, the answer's record holds the receipt of the outcome +//! and never the content, and a receipt is the count of an outcome's +//! bytes, entries, or paths. + +use runvil_vfs::{Entry, FileType, Stat}; + +use super::*; + +/// A fresh access over an empty memory filesystem. +fn access() -> Arc { + Arc::new( + runvil_vfs::VfsRef::default() + .acquire(runvil_vfs::Origin::new("effect record fixture")) + .expect("the stock backend acquires"), + ) +} + +#[test] +fn a_tools_file_effect_records_its_call_where_a_store_call_records_its_store() { + let op = || VfsOp::Write { + path: "note.md".to_owned(), + contents: b"hello".to_vec(), + }; + let asked_by_a_tool = Effect::Vfs { + asker: VfsAsker::Tool { call: EffectId(7) }, + access: access(), + op: op(), + }; + assert_eq!( + serde_json::to_string(&asked_by_a_tool.to_record()).expect("a record serializes"), + r#"{"Vfs":{"call":7,"op":{"Write":{"path":"note.md","contents":"hello"}}}}"# + ); + let asked_by_lua = Effect::Vfs { + asker: VfsAsker::Lua { + store: ChainId::root(), + }, + access: access(), + op: op(), + }; + assert_eq!( + serde_json::to_string(&asked_by_lua.to_record()).expect("a record serializes"), + r#"{"Vfs":{"store":"0","op":{"Write":{"path":"note.md","contents":"hello"}}}}"# + ); + for effect in [asked_by_a_tool, asked_by_lua] { + let record = effect.to_record(); + let text = serde_json::to_string(&record).expect("a record serializes"); + let back: EffectRecord = serde_json::from_str(&text).expect("a record reads back"); + assert_eq!(back, record, "{text}"); + } +} + +#[test] +fn a_vfs_record_that_names_no_asker_does_not_read_back() { + let read = serde_json::from_str::(r#"{"Vfs":{"op":{"Delete":{"path":"a"}}}}"#); + assert!(read.is_err(), "{read:?}"); +} + +#[test] +fn a_receipt_answer_records_the_receipt_and_never_the_content() { + let stat = Stat::new(FileType::File, 3); + let cases = [ + (VfsReceipt::Done, r#"{"VfsReceipt":{"Ok":"Done"}}"#), + ( + VfsReceipt::Bytes(12), + r#"{"VfsReceipt":{"Ok":{"Bytes":12}}}"#, + ), + (VfsReceipt::Count(3), r#"{"VfsReceipt":{"Ok":{"Count":3}}}"#), + ( + VfsReceipt::Bool(true), + r#"{"VfsReceipt":{"Ok":{"Bool":true}}}"#, + ), + ( + VfsReceipt::Stat(stat), + r#"{"VfsReceipt":{"Ok":{"Stat":{"file_type":"file","size":3,"mode":null,"modified":null,"created":null}}}}"#, + ), + ]; + for (receipt, line) in cases { + let record = EffectAnswer::VfsReceipt(Ok(receipt)).to_record(); + assert_eq!( + serde_json::to_string(&record).expect("a receipt answer records"), + line + ); + assert_eq!(answer_round_trip(&record), record); + } +} + +#[test] +fn a_failed_receipt_answer_records_the_vfs_errors_tag_and_display_text() { + let error = VfsError::NotFound { + path: "/gone.md".to_owned(), + }; + let record = EffectAnswer::VfsReceipt(Err(error)).to_record(); + assert_eq!( + serde_json::to_string(&record).expect("a receipt answer records"), + r#"{"VfsReceipt":{"Err":{"kind":"not_found","message":"not found: /gone.md"}}}"# + ); + assert_eq!(answer_round_trip(&record), record); +} + +#[test] +fn a_receipt_is_the_outcome_with_a_count_in_place_of_its_content() { + let stat = Stat::new(FileType::Directory, 0); + let entries = vec![ + Entry::new("a.md", Stat::new(FileType::File, 1)), + Entry::new("b.md", Stat::new(FileType::File, 2)), + ]; + let cases = [ + (VfsOutcome::Unit, VfsReceipt::Done), + ( + VfsOutcome::Text("h\u{e9}llo".to_owned()), + VfsReceipt::Bytes(6), + ), + ( + VfsOutcome::Bytes(vec![0xff, 0x00, 0x01]), + VfsReceipt::Bytes(3), + ), + ( + VfsOutcome::Paths(vec!["a.md".to_owned(), "b.md".to_owned()]), + VfsReceipt::Count(2), + ), + (VfsOutcome::Entries(entries), VfsReceipt::Count(2)), + (VfsOutcome::Bool(false), VfsReceipt::Bool(false)), + (VfsOutcome::Stat(stat.clone()), VfsReceipt::Stat(stat)), + ]; + for (outcome, receipt) in cases { + assert_eq!(VfsReceipt::of(&outcome), receipt, "{outcome:?}"); + } +} diff --git a/crates/runvil-internal/runtime/src/execute/run/effect-tests.rs b/crates/runvil-internal/runtime/src/execute/run/effect-tests.rs index 766fafb9b..62023fefb 100644 --- a/crates/runvil-internal/runtime/src/execute/run/effect-tests.rs +++ b/crates/runvil-internal/runtime/src/execute/run/effect-tests.rs @@ -10,7 +10,8 @@ //! depend on, the public JSON record of every kind is the typed record's //! JSON and reads back identical, and an effect or answer record reads //! from its JSON form. The store answer's records are in the `store` -//! child. +//! child, and the records of a file operation that a tool call asked for +//! are in the `files` child. use std::fmt; @@ -25,6 +26,8 @@ use serde_json::json; use super::*; use crate::test_support::scenario::test_binding; +#[path = "effect-tests-files.rs"] +mod files; #[path = "effect-tests-store.rs"] mod store; @@ -438,13 +441,23 @@ fn every_kinds_public_record_is_json_that_round_trips_exactly() { survives_stop: false, }, Effect::Vfs { - store: ChainId::root().child(3), + asker: VfsAsker::Lua { + store: ChainId::root().child(3), + }, access: access(), op: VfsOp::Write { path: "note.md".to_owned(), contents: b"hello".to_vec(), }, }, + Effect::Vfs { + asker: VfsAsker::Tool { call: EffectId(7) }, + access: access(), + op: VfsOp::Write { + path: "/blob.bin".to_owned(), + contents: vec![0xff, 0x00], + }, + }, Effect::Timer { duration: Duration::from_millis(500), }, @@ -464,6 +477,10 @@ fn every_kinds_public_record_is_json_that_round_trips_exactly() { EffectAnswer::Render(tools_pack("Shout the value.", "shout")), EffectAnswer::ToolCall(Ok(ToolOutput::untrusted(""))), EffectAnswer::Vfs(Ok(VfsOutcome::Paths(vec!["a.txt".to_owned()]))), + EffectAnswer::VfsReceipt(Ok(VfsReceipt::Bytes(12))), + EffectAnswer::VfsReceipt(Err(VfsError::NotFound { + path: "/gone.md".to_owned(), + })), EffectAnswer::Timer, EffectAnswer::Dropped, ]; diff --git a/crates/runvil-internal/runtime/src/execute/run/effect.rs b/crates/runvil-internal/runtime/src/execute/run/effect.rs index b5474fe6a..e2a290f10 100644 --- a/crates/runvil-internal/runtime/src/execute/run/effect.rs +++ b/crates/runvil-internal/runtime/src/execute/run/effect.rs @@ -11,7 +11,9 @@ //! and *what it means*; the Harness performs it. A section entry's first //! model round that offers catalog tools first issues a render, whose //! answer the Engine merges into the entry's frozen sets before it issues -//! the round. +//! the round. A file operation that an open tool call asks for is an +//! effect too: the caller reports the request, and the run issues it as a +//! `Vfs` effect whose [`VfsAsker`] is the call. //! //! An [`Effect`] may hold a live handle (a filesystem access) and so does //! not serialize itself. [`Effect::record`] projects it onto a JSON value, @@ -31,7 +33,7 @@ use runvil_types::ids::{ChainId, RoundId}; use runvil_types::packs::PackId; use runvil_types::tools::{OutputTrust, ToolId, ToolInfo, ToolOutput}; pub use runvil_types::tools::{ToolCallOrigin, ToolCaller}; -use runvil_vfs::{Access, VfsError, VfsOp, VfsOutcome}; +use runvil_vfs::{Access, Stat, VfsError, VfsOp, VfsOutcome}; use serde::{Deserialize, Serialize}; use serde_json::Value; @@ -121,6 +123,83 @@ impl PackToolSets { } } +/// Who asked for the operation of an [`Effect::Vfs`]. The asker settles +/// the files the operation works on: the prompt's Lua works on its +/// chain's store, and a tool call works on the filesystem the caller gave +/// the run. +/// +/// The enum is `#[non_exhaustive]`, so a `match` on it outside this crate +/// needs a wildcard arm. +#[derive(Debug, Clone, PartialEq, Eq)] +#[non_exhaustive] +pub enum VfsAsker { + /// A `store` call of the prompt's Lua, on the store made for this + /// chain. + Lua { + /// Which store the operation is on: the id of the chain the store + /// was made for. That is the root chain's id, `0`, for the store + /// the run starts with, and for a store an `execute` made, the id + /// of the chain that runs the executed prompt. Two operations on + /// one path are on the same file only when this id is the same. + store: ChainId, + }, + /// The open tool call with this id, on the filesystem the caller gave + /// the run. + Tool { + /// The id of the tool call's [`ToolCall`](Effect::ToolCall) + /// effect. + call: EffectId, + }, +} + +/// What a run's record keeps of the outcome of a file operation that a +/// tool call asked for: a count where the outcome holds content. +/// +/// The caller hands the tool the whole [`VfsOutcome`] and answers the +/// effect with the receipt, so the run holds no copy of the bytes of a +/// read. The tool's own result is the answer of its +/// [`ToolCall`](Effect::ToolCall) effect. +/// +/// The enum is `#[non_exhaustive]`, so a `match` on it outside this crate +/// needs a wildcard arm. +#[derive(Debug, Clone, PartialEq, Eq)] +#[non_exhaustive] +pub enum VfsReceipt { + /// The operation succeeded and returned nothing. + Done, + /// The operation returned this many bytes: the text of a `Read` or a + /// `ReadNumbered`, or the bytes of a `ReadRange`. + Bytes(u64), + /// The operation returned this many items: the entries of a `List`, + /// or the paths of a `Glob`. + Count(u64), + /// Whether the path of an `Exists` exists. + Bool(bool), + /// The metadata of the path of a `Stat`. + Stat(Stat), +} + +impl VfsReceipt { + /// Returns the receipt of `outcome`: the outcome itself where it is a + /// stat, a bool, or nothing, and the count of its bytes, entries, or + /// paths otherwise. + #[must_use] + pub fn of(outcome: &VfsOutcome) -> VfsReceipt { + let count = |len: usize| u64::try_from(len).unwrap_or(u64::MAX); + match outcome { + VfsOutcome::Text(text) => VfsReceipt::Bytes(count(text.len())), + VfsOutcome::Bytes(bytes) => VfsReceipt::Bytes(count(bytes.len())), + VfsOutcome::Paths(paths) => VfsReceipt::Count(count(paths.len())), + VfsOutcome::Entries(entries) => VfsReceipt::Count(count(entries.len())), + VfsOutcome::Bool(flag) => VfsReceipt::Bool(*flag), + VfsOutcome::Stat(stat) => VfsReceipt::Stat(stat.clone()), + // `Unit`, and any outcome `runvil-vfs` adds behind its + // `#[non_exhaustive]` `VfsOutcome` before this crate names it. + _ => VfsReceipt::Done, + } + } +} + /// One piece of work the Engine asks the caller to perform. /// /// The enum is closed on purpose: it has no `#[non_exhaustive]`, so the @@ -200,34 +279,40 @@ pub enum Effect { /// sees. survives_stop: bool, }, - /// One operation on a store of the run, issued for one of the eight - /// `store.*` calls a prompt can make. + /// One file operation, which the caller performs with + /// `Access::perform` on `access`. `asker` says who asked for it, and + /// with that which files it works on and which answer it takes. /// - /// A store is the run's own: the Engine makes it empty, in memory. - /// The run starts with one, which is gone when the run ends, and each - /// `execute` makes one more for the prompt it runs, which is gone - /// when that prompt's chain ends. A store is no part of the - /// filesystem the caller gave the run, so no path of that filesystem - /// reaches it, and a tool, which reaches files through the access of - /// its [`ToolCall`](Effect::ToolCall) effect, sees none of it. - /// `access` is a view of the calling chain's store under the chain's - /// identity, which the Engine makes at dispatch, and it is the - /// caller's one way to that store. + /// The prompt's Lua asks with one of the eight `store.*` calls, and + /// the operation works on a store of the run. A store is the run's + /// own: the Engine makes it empty, in memory. The run starts with + /// one, which is gone when the run ends, and each `execute` makes one + /// more for the prompt it runs, which is gone when that prompt's + /// chain ends. A store is no part of the filesystem the caller gave + /// the run, so no path of that filesystem reaches it, and a tool sees + /// none of it. `access` is then a view of the calling chain's store + /// under the chain's identity, which the Engine makes at dispatch, + /// and it is the caller's one way to that store. The caller answers + /// with [`EffectAnswer::Vfs`], the whole outcome. + /// + /// An open tool call asks through the caller: the caller reports the + /// tool's request with `Run::request_file`, and the operation works + /// on the filesystem the caller gave the run. `access` is then the + /// call's own, the one its [`ToolCall`](Effect::ToolCall) effect + /// holds. The caller hands the whole outcome to the tool and answers + /// with [`EffectAnswer::VfsReceipt`]. /// /// The caller must use the access exactly as given, for this one /// operation. When the caller drops the access does not affect /// the run's correctness. Store claims follow happens-before order /// within the run's scope. The run ends that scope at `Done` or when - /// the run is dropped, and after that the view refuses every operation. + /// the run is dropped, and after that the access refuses every + /// operation. Vfs { - /// Which store the operation is on: the id of the chain the store - /// was made for. That is the root chain's id, `0`, for the store - /// the run starts with, and for a store an `execute` made, the id - /// of the chain that runs the executed prompt. Two operations on - /// one path are on the same file only when this id is the same. - store: ChainId, - /// The chain's store view: an access with the chain's identity - /// that reaches only that store. + /// Who asked for the operation. + asker: VfsAsker, + /// The access the operation runs on: the chain's view of its + /// store, or the tool call's own access. access: Arc, /// The validated operation. op: VfsOp, @@ -336,8 +421,8 @@ impl Effect { args: args.clone(), origin: origin.clone(), }, - Effect::Vfs { store, op, .. } => EffectRecord::Vfs { - store: store.clone(), + Effect::Vfs { asker, op, .. } => EffectRecord::Vfs { + asker: asker.clone(), op: op.clone(), }, Effect::Timer { duration } => EffectRecord::Timer { @@ -412,13 +497,21 @@ pub(crate) enum EffectRecord { /// section's script or the model whose round asked for it. origin: ToolCallOrigin, }, - /// One operation on a store of the run. + /// One file operation. Vfs { - /// Which store the operation is on: the id of the chain the store - /// was made for, `0` for the store the run starts with. The - /// records that name one store, in order, are every operation on - /// that store. - store: ChainId, + /// Who asked, written as one key beside the operation. A `store` + /// call of the prompt's Lua writes `store`, the id of the chain + /// the store was made for, `0` for the store the run starts with: + /// the records that name one store, in order, are every operation + /// on that store. A tool call writes `call`, the id of its + /// `ToolCall` effect, and its operation worked on the filesystem + /// the caller gave the run. + #[serde( + flatten, + serialize_with = "super::vfs_record::serialize_asker", + deserialize_with = "super::vfs_record::deserialize_asker" + )] + asker: VfsAsker, /// The validated operation, written in its record form: one /// object keyed by the operation's name. The bytes of a write or /// an append are text under `contents` when they are UTF-8, and @@ -436,7 +529,8 @@ pub(crate) enum EffectRecord { }, } -/// The answer to one [`Effect`]: one variant per effect kind, plus +/// The answer to one [`Effect`]: one variant per effect kind, a second +/// one for a `Vfs` effect that a tool call asked for, plus /// [`Dropped`](EffectAnswer::Dropped) for an effect the caller gave up on. /// Every effect receives exactly one answer. /// @@ -460,9 +554,15 @@ pub enum EffectAnswer { /// The tool's own output or its own failure, before the Engine applies /// its trust rule. ToolCall(std::result::Result), - /// The outcome of the operation on the effect's store view, or the - /// store's own structured failure. + /// The answer to a `Vfs` effect that the prompt's Lua asked for: the + /// whole outcome of the operation on the effect's store view, or the + /// store's own structured failure. The `store` call resumes with it. Vfs(std::result::Result), + /// The answer to a `Vfs` effect that a tool call asked for: the + /// receipt of the operation's outcome, or the operation's failure. + /// It resumes no chain: the caller has handed the outcome, or the + /// failure, to the tool, whose call stays open. + VfsReceipt(std::result::Result), /// The timer fired. Timer, /// The caller gave up on the effect and dropped it, for example @@ -482,11 +582,13 @@ impl EffectAnswer { /// `"Dropped"`, and it round-trips exactly through `serde_json`. A /// failure is recorded as `{"kind":..,"message":..}`: its stable tag and /// its text, which is the prose of a model or tool failure and the - /// display text of a store failure. A completion is recorded as its reply or - /// its requested tool names beside the model and finish reason, and a - /// render as its rendered tools whole. The round's request and response - /// bodies travel as debug events, and its metrics travel in the turn's - /// event. + /// display text of a file operation's failure. A completion is recorded + /// as its reply or its requested tool names beside the model and finish + /// reason, and a render as its rendered tools whole. A `Vfs` answer is + /// recorded as the whole outcome, and a `VfsReceipt` answer as the + /// receipt, such as `{"VfsReceipt":{"Ok":{"Bytes":12}}}`. The round's + /// request and response bodies travel as debug events, and its metrics + /// travel in the turn's event. #[must_use] pub fn record(&self) -> Value { wire_value(&self.to_record()) @@ -509,6 +611,10 @@ impl EffectAnswer { Ok(outcome) => Ok(outcome.clone()), Err(error) => Err(FailureRecord::new(error.tag(), error.to_string())), }), + EffectAnswer::VfsReceipt(result) => AnswerRecord::VfsReceipt(match result { + Ok(receipt) => Ok(receipt.clone()), + Err(error) => Err(FailureRecord::new(error.tag(), error.to_string())), + }), EffectAnswer::Timer => AnswerRecord::Timer, EffectAnswer::Dropped => AnswerRecord::Dropped, } @@ -541,6 +647,17 @@ pub(crate) enum AnswerRecord { )] std::result::Result, ), + /// The outcome of an operation that a tool call asked for, as its + /// receipt: `"Done"`, or a one-key object such as `{"Bytes":12}`, + /// `{"Count":3}`, `{"Bool":true}`, or `{"Stat":{..}}`. A failure is + /// its record. + VfsReceipt( + #[serde( + serialize_with = "super::vfs_record::serialize_receipt", + deserialize_with = "super::vfs_record::deserialize_receipt" + )] + std::result::Result, + ), /// The timer fired. Timer, /// The caller gave up on the effect and dropped it. @@ -553,7 +670,7 @@ pub(crate) enum AnswerRecord { /// `kind` is the stable tag of the failure's kind: the model code's tag for /// a model round (such as `malformed_response`), the tool code's tag for a /// tool call (such as `tool_invalid_arguments`), or the `VfsError` tag for a -/// store operation (such as `not_found`). `message` is the failure's +/// file operation (such as `not_found`). `message` is the failure's /// display text, which for a model round or a tool call is the prose the /// model read. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] diff --git a/crates/runvil-internal/runtime/src/execute/run/tests-files.rs b/crates/runvil-internal/runtime/src/execute/run/tests-files.rs new file mode 100644 index 000000000..e814df88e --- /dev/null +++ b/crates/runvil-internal/runtime/src/execute/run/tests-files.rs @@ -0,0 +1,464 @@ +//! A tool's file requests at the run's boundary: `Run::request_file` +//! issues each one as a `Vfs` effect whose asker is the open tool call, +//! under the task that made the call and with the call's own access, and +//! the next step returns it ahead of the effects that step issues. Its +//! answer, a receipt, a failure, or a drop, resumes no chain and reports +//! no event, and the call stays open. A request for a call whose chain +//! stopped waiting is discarded, one for any other id ends the run, and +//! so does a `Vfs` answer of the other form. The chain's abort withdraws +//! the effect with its call, and `Done` waits for its answer. + +use runvil_prompt::test_support::prompt; +use runvil_types::tools::{ToolCatalog, ToolInfo, ToolOutput}; +use runvil_vfs::{Access, Origin, VfsError, VfsRef}; + +use super::*; + +/// A run of the prompt whose sections are `sections`, with `tools/echo` +/// as its whole catalog and `vfs` as the files its tool calls work in. +#[track_caller] +fn files_run(sections: &[(&str, &str)], vfs: &VfsRef) -> Run { + let source = prompt("", sections); + let parsed = Prompt::parse(&|_: &str| Ok(source.clone()), "prompt") + .expect("the files test prompt parses"); + let echo = ToolInfo::new( + ToolId::parse("tools/echo").expect("a valid tool id"), + "Echoes its value.", + json!({ "type": "object" }), + ); + let catalog = ToolCatalog::new([echo]).expect("one tool is a valid catalog"); + let params = run_params().with_tools(catalog).with_vfs(vfs.clone()); + Run::new(Arc::new(parsed), "{}", params) +} + +/// A run whose one section calls `tools/echo` once and returns its +/// answer. +#[track_caller] +fn one_call_run(vfs: &VfsRef) -> Run { + files_run(&[("Only", "return tools.call('tools/echo', {})")], vfs) +} + +/// A main section that spawns `Worker`, whose one tool call stays out, +/// and then runs `after`. +fn beside_a_worker(after: &str) -> [(&'static str, String); 2] { + [ + ( + "Main", + format!("local t = tasks.spawn('../Worker')\nstore.exists('one')\n{after}"), + ), + ("Worker", "return tools.call('tools/echo', {})".to_owned()), + ] +} + +/// [`files_run`] over [`beside_a_worker`]`(after)`. +#[track_caller] +fn worker_run(after: &str, vfs: &VfsRef) -> Run { + let sections = beside_a_worker(after); + let sections: Vec<(&str, &str)> = sections + .iter() + .map(|(name, lua)| (*name, lua.as_str())) + .collect(); + files_run(§ions, vfs) +} + +/// A write of `text` to `path`. +fn write(path: &str, text: &str) -> VfsOp { + VfsOp::Write { + path: path.to_owned(), + contents: text.as_bytes().to_vec(), + } +} + +/// Steps `run` and returns what the pending step issued, reported, and +/// withdrew. +#[track_caller] +fn stepped(run: &mut Run) -> (Vec, Vec, Vec) { + match run.step() { + Step::Pending { + effects, + events, + withdrawn, + .. + } => (effects, events, withdrawn), + other @ Step::Done { .. } => panic!("the run goes on: {other:?}"), + } +} + +/// Asserts that the next step of `run` issues, reports, and withdraws +/// nothing: the run still waits on what is out. +#[track_caller] +fn assert_still_waiting(run: &mut Run) { + let (effects, events, withdrawn) = stepped(run); + assert!(effects.is_empty(), "nothing new is issued: {effects:?}"); + assert!(events.is_empty(), "nothing is reported: {events:?}"); + assert!(withdrawn.is_empty(), "nothing is withdrawn: {withdrawn:?}"); +} + +/// Steps `run` to its end and returns its result. +#[track_caller] +fn finished(run: &mut Run) -> Result { + match run.step() { + Step::Done { result, .. } => result, + other @ Step::Pending { .. } => panic!("the run is over: {other:?}"), + } +} + +/// The tool call among `effects`: its id, its provenance, and its access. +#[track_caller] +fn tool_call(effects: &[IssuedEffect]) -> (EffectId, Provenance, Arc) { + effects + .iter() + .find_map(|issued| match &issued.effect { + Effect::ToolCall { access, .. } => { + Some((issued.id, issued.provenance.clone(), Arc::clone(access))) + } + _ => None, + }) + .unwrap_or_else(|| panic!("the step issued a tool call: {effects:?}")) +} + +/// The one `store` effect among `effects`. +#[track_caller] +fn store_call(effects: &[IssuedEffect]) -> EffectId { + effects + .iter() + .find_map(|issued| match &issued.effect { + Effect::Vfs { + asker: VfsAsker::Lua { .. }, + .. + } => Some(issued.id), + _ => None, + }) + .unwrap_or_else(|| panic!("the step issued a store call: {effects:?}")) +} + +/// The answer of a tool that returns `text`. +fn echoed(text: &str) -> EffectAnswer { + EffectAnswer::ToolCall(Ok(ToolOutput::trusted(text))) +} + +/// The answer to a `store.exists` that finds nothing. +fn absent() -> EffectAnswer { + EffectAnswer::Vfs(Ok(VfsOutcome::Bool(false))) +} + +/// Asserts that `error` is the internal error whose message holds +/// `phrase`. +#[track_caller] +fn assert_internal(error: &Error, phrase: &str) { + assert_eq!(error.code, ErrorCode::Internal, "{error:?}"); + let message = error.located_message(); + assert!(message.contains(phrase), "{message}"); +} + +#[test] +fn a_file_request_is_issued_as_a_vfs_effect_with_the_calls_access_and_the_call_stays_open() +-> Result<(), VfsError> { + let vfs = VfsRef::default(); + let mut run = one_call_run(&vfs); + let (effects, ..) = stepped(&mut run); + let (call, made_by, call_access) = tool_call(&effects); + + let op = write("/note.md", "from the tool"); + run.request_file(call, op.clone()); + let (effects, events, withdrawn) = stepped(&mut run); + let [issued] = effects.as_slice() else { + panic!("the request is the step's one effect: {effects:?}"); + }; + let Effect::Vfs { + asker, + access, + op: issued_op, + } = &issued.effect + else { + panic!("the request is a Vfs effect: {issued:?}"); + }; + assert_eq!(*asker, VfsAsker::Tool { call }); + assert_eq!(*issued_op, op); + assert_eq!( + access.id(), + call_access.id(), + "the operation runs under the call's own identity" + ); + assert_eq!( + issued.provenance.task, made_by.task, + "the effect is stamped under the task that made the call" + ); + assert!(issued.provenance.seq > made_by.seq, "{issued:?}"); + assert!(events.is_empty() && withdrawn.is_empty()); + + // The caller performs the operation, hands the outcome to the tool, + // and answers with the receipt. The chain stays parked on the call. + let outcome = access.perform(issued_op)?; + assert_eq!(outcome, VfsOutcome::Unit); + run.resume( + issued.id, + EffectAnswer::VfsReceipt(Ok(VfsReceipt::of(&outcome))), + ); + assert_still_waiting(&mut run); + + run.resume(call, echoed("echoed")); + assert_eq!(finished(&mut run).as_deref(), Ok("echoed")); + let after = vfs.acquire(Origin::new("the caller's own access"))?; + assert_eq!(after.read_string("/note.md")?, "from the tool"); + Ok(()) +} + +#[test] +fn the_answer_to_a_tools_file_effect_resumes_no_chain_whether_a_failure_or_a_drop() { + let mut run = one_call_run(&VfsRef::default()); + let (effects, ..) = stepped(&mut run); + let (call, ..) = tool_call(&effects); + for path in ["/a.md", "/b.md", "/c.md"] { + run.request_file(call, write(path, "x")); + } + let (effects, ..) = stepped(&mut run); + let [first, second, third] = effects.as_slice() else { + panic!("each request is one effect, in request order: {effects:?}"); + }; + // A conflict in the answer to a `store` call ends the run. In the + // answer to a tool's request it is the tool's to handle. + let conflict = VfsError::Conflict { + path: "/a.md".to_owned(), + detail: "two identities claimed /a.md".to_owned(), + }; + run.resume(first.id, EffectAnswer::VfsReceipt(Err(conflict))); + assert_still_waiting(&mut run); + run.resume(second.id, EffectAnswer::Dropped); + assert_still_waiting(&mut run); + let missing = VfsError::NotFound { + path: "/c.md".to_owned(), + }; + run.resume(third.id, EffectAnswer::VfsReceipt(Err(missing))); + assert_still_waiting(&mut run); + + run.resume(call, echoed("the call still answers")); + assert_eq!( + finished(&mut run).as_deref(), + Ok("the call still answers"), + "no answer to a file effect ended or resumed the run" + ); +} + +#[test] +fn a_file_effect_goes_out_ahead_of_the_effects_its_step_issues() { + let mut run = worker_run( + "store.exists('two')\n\ + local _task, _ok, result = tasks.join_any({ t })\n\ + return result", + &VfsRef::default(), + ); + let (effects, ..) = stepped(&mut run); + let (call, made_by, _) = tool_call(&effects); + let first_store = store_call(&effects); + + // The request arrives before the step that runs the main chain on. + run.request_file(call, write("/note.md", "x")); + run.resume(first_store, absent()); + let (effects, ..) = stepped(&mut run); + let [file, store] = effects.as_slice() else { + panic!("the file effect, then the main chain's next store call: {effects:?}"); + }; + assert!( + matches!(&file.effect, Effect::Vfs { asker: VfsAsker::Tool { call: asked }, .. } if *asked == call), + "{file:?}" + ); + assert_eq!( + file.provenance.task, made_by.task, + "the worker's task made the call, so the effect is stamped under it" + ); + assert_ne!(file.provenance.task, store.provenance.task); + assert!( + matches!( + &store.effect, + Effect::Vfs { + asker: VfsAsker::Lua { .. }, + .. + } + ), + "{store:?}" + ); + + run.resume(file.id, EffectAnswer::VfsReceipt(Ok(VfsReceipt::Done))); + run.resume(store.id, absent()); + // The main chain goes on to wait for the worker, whose call is open. + let (effects, _, withdrawn) = stepped(&mut run); + assert!(effects.is_empty(), "nothing new is issued: {effects:?}"); + assert!(withdrawn.is_empty(), "nothing is withdrawn: {withdrawn:?}"); + run.resume(call, echoed("echoed")); + assert_eq!(finished(&mut run).as_deref(), Ok("echoed")); +} + +#[test] +fn a_file_request_for_a_call_whose_chain_stopped_waiting_is_discarded() { + let mut run = worker_run( + "tasks.cancel(t)\n\ + tasks.join_any({ t })\n\ + store.exists('two')\n\ + return 'main done'", + &VfsRef::default(), + ); + let (effects, ..) = stepped(&mut run); + let (call, ..) = tool_call(&effects); + run.resume(store_call(&effects), absent()); + // The main chain cancels the worker, which withdraws its call, and + // goes on to a second store call. + let (effects, _, withdrawn) = stepped(&mut run); + assert_eq!(withdrawn, [call]); + let second_store = store_call(&effects); + + run.request_file(call, write("/late.md", "x")); + assert_still_waiting(&mut run); + + run.resume(call, EffectAnswer::Dropped); + run.resume(second_store, absent()); + assert_eq!(finished(&mut run).as_deref(), Ok("main done")); +} + +/// Asserts that `run`, whose one outstanding effect is `outstanding`, +/// was ended by a file request that named no open tool call. +#[track_caller] +fn assert_ended_as_no_call(run: &mut Run, outstanding: EffectId) { + let (effects, events, withdrawn) = stepped(run); + assert!(effects.is_empty(), "no effect is issued: {effects:?}"); + assert!(ended(&events), "the request ended the run: {events:?}"); + assert_eq!(withdrawn, [outstanding]); + run.resume(outstanding, EffectAnswer::Dropped); + let error = finished(run).expect_err("the request fails the run"); + assert_internal(&error, "no outstanding tool call"); +} + +#[test] +fn a_file_request_for_an_id_that_names_no_open_tool_call_ends_the_run_with_an_internal_error() { + let op = || write("/note.md", "x"); + + // An id the run never issued. + let mut run = one_call_run(&VfsRef::default()); + let (effects, ..) = stepped(&mut run); + let (call, ..) = tool_call(&effects); + run.request_file(EffectId(call.0 + 99), op()); + assert_ended_as_no_call(&mut run, call); + + // The id of an effect that is no tool call. + let mut run = files_run(&[("Only", "return store.exists('x')")], &VfsRef::default()); + let (effects, ..) = stepped(&mut run); + let store = store_call(&effects); + run.request_file(store, op()); + assert_ended_as_no_call(&mut run, store); + + // A call whose answer already arrived. + let mut run = files_run( + &[( + "Only", + "tools.call('tools/echo', {})\nreturn tools.call('tools/echo', {})", + )], + &VfsRef::default(), + ); + let (effects, ..) = stepped(&mut run); + let (answered, ..) = tool_call(&effects); + run.resume(answered, echoed("first")); + let (effects, ..) = stepped(&mut run); + let (open, ..) = tool_call(&effects); + run.request_file(answered, op()); + assert_ended_as_no_call(&mut run, open); +} + +#[test] +fn a_vfs_answer_of_the_other_form_ends_the_run_with_an_internal_error() { + // The whole outcome for an operation that a tool call asked for. + let mut run = one_call_run(&VfsRef::default()); + let (effects, ..) = stepped(&mut run); + let (call, ..) = tool_call(&effects); + run.request_file(call, write("/note.md", "x")); + let (file, _) = only_effect(run.step()); + run.resume(file, EffectAnswer::Vfs(Ok(VfsOutcome::Unit))); + let (_, events, withdrawn) = stepped(&mut run); + assert!(ended(&events), "the mismatch ended the run: {events:?}"); + assert_eq!(withdrawn, [call]); + run.resume(call, EffectAnswer::Dropped); + let error = finished(&mut run).expect_err("the mismatch fails the run"); + assert_internal(&error, "effect's own kind"); + + // A receipt for an operation that the prompt's Lua asked for. + let mut run = files_run(&[("Only", "return store.exists('x')")], &VfsRef::default()); + let (store, _) = only_effect(run.step()); + run.resume(store, EffectAnswer::VfsReceipt(Ok(VfsReceipt::Bool(false)))); + let error = finished(&mut run).expect_err("the mismatch fails the run"); + assert_internal(&error, "effect's own kind"); +} + +#[test] +fn a_file_request_on_a_run_that_has_returned_done_does_nothing() { + let mut run = files_run(&[("Only", "return 'x'")], &VfsRef::default()); + assert_eq!(finished(&mut run).as_deref(), Ok("x")); + run.request_file(EffectId(0), write("/note.md", "x")); + let Step::Done { result, events, .. } = run.step() else { + panic!("a finished run stays finished"); + }; + assert!( + events.is_empty(), + "the request reported nothing: {events:?}" + ); + assert_internal( + &result.expect_err("a finished run cannot be stepped"), + "cannot be stepped again", + ); +} + +#[test] +fn a_chains_abort_withdraws_a_tools_file_effect_with_its_call_and_done_waits_for_both() { + let mut run = worker_run( + "tasks.cancel(t)\n\ + tasks.join_any({ t })\n\ + return 'main done'", + &VfsRef::default(), + ); + let (effects, ..) = stepped(&mut run); + let (call, ..) = tool_call(&effects); + let store = store_call(&effects); + run.request_file(call, write("/note.md", "x")); + let (file, _) = only_effect(run.step()); + + // The main chain cancels the worker while the worker's call and the + // call's file effect are both out, and then returns. + run.resume(store, absent()); + let (effects, events, withdrawn) = stepped(&mut run); + assert!(effects.is_empty(), "{effects:?}"); + assert!(ended(&events), "the main chain returned: {events:?}"); + assert_eq!( + withdrawn, + [call, file], + "the worker's abort withdraws its call and the call's file effect" + ); + run.resume(call, EffectAnswer::Dropped); + assert_still_waiting(&mut run); + run.resume(file, EffectAnswer::Dropped); + assert_eq!(finished(&mut run).as_deref(), Ok("main done")); +} + +#[test] +fn a_call_answered_before_its_file_effect_ends_its_access_and_leaves_the_effect_owed_an_answer() { + let mut run = one_call_run(&VfsRef::default()); + let (effects, ..) = stepped(&mut run); + let (call, ..) = tool_call(&effects); + let op = write("/late.md", "x"); + run.request_file(call, op.clone()); + let (file, effect) = only_effect(run.step()); + let Effect::Vfs { access, .. } = effect else { + panic!("the request is a Vfs effect: {effect:?}"); + }; + + // The call's answer ends the call's identity, so the operation is + // refused from then on. + run.resume(call, echoed("echoed")); + assert!( + matches!(access.perform(&op), Err(VfsError::ScopeEnded { .. })), + "the call's access refuses the late operation" + ); + let (effects, events, withdrawn) = stepped(&mut run); + assert!(effects.is_empty(), "{effects:?}"); + assert!(ended(&events), "the chain returned: {events:?}"); + assert_eq!(withdrawn, [file], "the run's end withdraws the file effect"); + run.resume(file, EffectAnswer::Dropped); + assert_eq!(finished(&mut run).as_deref(), Ok("echoed")); +} diff --git a/crates/runvil-internal/runtime/src/execute/run/tests.rs b/crates/runvil-internal/runtime/src/execute/run/tests.rs index 0e45c62d8..0b8e1330e 100644 --- a/crates/runvil-internal/runtime/src/execute/run/tests.rs +++ b/crates/runvil-internal/runtime/src/execute/run/tests.rs @@ -23,6 +23,8 @@ use crate::test_support::scenario::{TEST_SEED, only_effect, round_trip, test_bin #[path = "tests-drops.rs"] mod drops; +#[path = "tests-files.rs"] +mod files; #[path = "tests-inbox.rs"] mod inbox; #[path = "tests-reply.rs"] @@ -178,7 +180,9 @@ fn a_store_effect_records_its_store_and_operation_and_drops_the_access_handle() .expect("the stock backend acquires"), ); let effect = Effect::Vfs { - store: ChainId::root().child(2), + asker: VfsAsker::Lua { + store: ChainId::root().child(2), + }, access, op: VfsOp::Read { path: "notes.md".to_owned(), @@ -190,7 +194,9 @@ fn a_store_effect_records_its_store_and_operation_and_drops_the_access_handle() assert_eq!( record, EffectRecord::Vfs { - store: ChainId::root().child(2), + asker: VfsAsker::Lua { + store: ChainId::root().child(2), + }, op: VfsOp::Read { path: "notes.md".to_owned(), start: Some(1), diff --git a/crates/runvil-internal/runtime/src/execute/run/vfs_record.rs b/crates/runvil-internal/runtime/src/execute/run/vfs_record.rs index ae9332c66..561404110 100644 --- a/crates/runvil-internal/runtime/src/execute/run/vfs_record.rs +++ b/crates/runvil-internal/runtime/src/execute/run/vfs_record.rs @@ -1,4 +1,5 @@ -//! The record forms of a file operation and of its outcome. +//! The record forms of a file operation, of who asked for it, and of its +//! outcome. //! //! `runvil-vfs` is std only, so its [`VfsOp`] and [`VfsOutcome`] have no //! serde form of their own. A `Vfs` effect's record and its answer's @@ -13,6 +14,12 @@ //! other outcome is a one-key object, such as `{"Text":"..."}`, //! `{"Paths":["a.txt"]}`, or `{"Bool":true}`. //! +//! The asker records as one key beside the operation: `store`, the id of +//! the chain the store was made for, when the prompt's Lua asked, and +//! `call`, the id of the tool call's effect, when a tool call asked. The +//! outcome of an operation that a tool call asked for records as its +//! [`VfsReceipt`]: `"Done"`, or a one-key object such as `{"Bytes":12}`. +//! //! [`VfsOp`], [`VfsOutcome`], and the kind of a file are //! `#[non_exhaustive]`. An operation or an outcome this module has no //! form for records as `null`, and a kind of file it does not name @@ -21,10 +28,13 @@ use std::fmt::Write as _; use std::time::{Duration, SystemTime, UNIX_EPOCH}; +use runvil_types::ids::ChainId; use runvil_vfs::{Entry, FileType, Stat, VfsOp, VfsOutcome}; use serde::de::Error as _; use serde::{Deserialize, Deserializer, Serialize, Serializer}; +use super::effect::{EffectId, VfsAsker, VfsReceipt}; + /// Bytes as a record holds them: as text when they are UTF-8, and as hex /// otherwise. Flattened into an operation's record, the variant's name /// is the key the bytes sit under. @@ -515,6 +525,133 @@ impl VfsOutcomeRecord { } } +/// Who asked for an operation, as a record holds it. Flattened into the +/// effect's record, the variant's name is the one key that says who. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +enum VfsAskerRecord { + /// A `store` call of the prompt's Lua: the id of the chain the store + /// was made for. + #[serde(rename = "store")] + Lua(ChainId), + /// A tool call: the id of its effect. + #[serde(rename = "call")] + Tool(u64), +} + +/// A [`VfsReceipt`] as a record holds it. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +enum VfsReceiptRecord { + /// `VfsReceipt::Done`. + Done, + /// `VfsReceipt::Bytes`. + Bytes(u64), + /// `VfsReceipt::Count`. + Count(u64), + /// `VfsReceipt::Bool`. + Bool(bool), + /// `VfsReceipt::Stat`. + Stat(StatRecord), +} + +impl VfsReceiptRecord { + /// The record form of `receipt`. + fn of(receipt: &VfsReceipt) -> VfsReceiptRecord { + match receipt { + VfsReceipt::Done => VfsReceiptRecord::Done, + VfsReceipt::Bytes(count) => VfsReceiptRecord::Bytes(*count), + VfsReceipt::Count(count) => VfsReceiptRecord::Count(*count), + VfsReceipt::Bool(flag) => VfsReceiptRecord::Bool(*flag), + VfsReceipt::Stat(stat) => VfsReceiptRecord::Stat(StatRecord::of(stat)), + } + } + + /// The receipt this record holds. + /// + /// # Errors + /// Returns a sentence that names the fault when a stat does not read + /// back. + fn into_receipt(self) -> Result { + Ok(match self { + VfsReceiptRecord::Done => VfsReceipt::Done, + VfsReceiptRecord::Bytes(count) => VfsReceipt::Bytes(count), + VfsReceiptRecord::Count(count) => VfsReceipt::Count(count), + VfsReceiptRecord::Bool(flag) => VfsReceipt::Bool(flag), + VfsReceiptRecord::Stat(stat) => VfsReceipt::Stat(stat.into_stat()?), + }) + } +} + +/// Writes `asker` as the one key that says who asked, for a flattened +/// field's `serialize_with`. +/// +/// # Errors +/// Returns the serializer's own error. +pub(super) fn serialize_asker( + asker: &VfsAsker, + serializer: S, +) -> Result { + let record = match asker { + VfsAsker::Lua { store } => VfsAskerRecord::Lua(store.clone()), + VfsAsker::Tool { call } => VfsAskerRecord::Tool(call.get()), + }; + record.serialize(serializer) +} + +/// Reads who asked back from the key [`serialize_asker`] writes, for a +/// flattened field's `deserialize_with`. +/// +/// # Errors +/// Returns the deserializer's error for a record that holds neither key. +pub(super) fn deserialize_asker<'de, D: Deserializer<'de>>( + deserializer: D, +) -> Result { + Ok(match VfsAskerRecord::deserialize(deserializer)? { + VfsAskerRecord::Lua(store) => VfsAsker::Lua { store }, + VfsAskerRecord::Tool(call) => VfsAsker::Tool { + call: EffectId(call), + }, + }) +} + +/// Writes `answer`, the receipt of an operation's outcome or its failure, +/// with the receipt in its record form, for a record's `serialize_with`. +/// +/// # Errors +/// Returns the serializer's own error. +pub(super) fn serialize_receipt( + answer: &Result, + serializer: S, +) -> Result +where + S: Serializer, + E: Serialize, +{ + answer + .as_ref() + .map(VfsReceiptRecord::of) + .serialize(serializer) +} + +/// Reads the receipt of an operation's outcome, or its failure, back from +/// the form [`serialize_receipt`] writes, for a record's +/// `deserialize_with`. +/// +/// # Errors +/// Returns the deserializer's error for a value of another form, or for a +/// stat that does not read back. +pub(super) fn deserialize_receipt<'de, D, E>( + deserializer: D, +) -> Result, D::Error> +where + D: Deserializer<'de>, + E: Deserialize<'de>, +{ + match Result::::deserialize(deserializer)? { + Ok(record) => record.into_receipt().map(Ok).map_err(D::Error::custom), + Err(failure) => Ok(Err(failure)), + } +} + /// Writes `op` as its record form, for a record's `serialize_with`. /// /// # Errors diff --git a/crates/runvil-internal/runtime/src/execute/scheduler/apply.rs b/crates/runvil-internal/runtime/src/execute/scheduler/apply.rs index 1164375d9..7aff9debf 100644 --- a/crates/runvil-internal/runtime/src/execute/scheduler/apply.rs +++ b/crates/runvil-internal/runtime/src/execute/scheduler/apply.rs @@ -15,7 +15,10 @@ //! error, whatever it was parked on; for a render, that is the round's //! canceled answer. A tool call's answer, of either kind, also ends the //! call's identity: what the tool did is joined back into the chain, and -//! the call's access refuses every later operation. +//! the call's access refuses every later operation. The answer to a file +//! operation that a tool call asked for, a receipt, a failure, or a drop, +//! resumes no chain and reports nothing: the tool has the outcome, and +//! the chain still awaits the tool call. use runvil_types::error::{ErrorCode, place}; use runvil_types::event_lifecycle::{self as lifecycle, Lifecycle}; @@ -101,11 +104,15 @@ impl Scheduler { /// Every answer to a tool call, `Dropped` included, first ends the /// call's identity through [`Scheduler::end_tool_call`], so whatever /// the tool did happens before the chain's next step and nothing it - /// tries after is admitted. + /// tries after is admitted. The answer to a file operation that a + /// tool call asked for changes nothing, a failure and a drop + /// included. /// /// # Errors /// Returns an `Internal` failure when the answer's kind does not match - /// the effect's, when a batched call's answer finds no open slot to + /// the effect's, a `Vfs` answer for an operation that a tool call + /// asked for and a `VfsReceipt` answer for one that Lua asked for + /// included, when a batched call's answer finds no open slot to /// fill, or when the chain it resumes has no suspended block. /// Returns a `Determinism` failure when a store answer reports a /// claims-model conflict: the run ends on the spot rather than @@ -115,7 +122,7 @@ impl Scheduler { let Pending { chain, resume } = parked; let slot = match &resume { Continuation::ToolCall(call) => { - self.end_tool_call(chain, call.exec); + self.end_tool_call(chain, call.exec()); match call.site { CallSite::Batch { slot, .. } => Some(slot), CallSite::Script | CallSite::Model { .. } => None, @@ -125,10 +132,17 @@ impl Scheduler { | Continuation::Chat(_) | Continuation::Render(_) | Continuation::Vfs(_) + | Continuation::ToolVfs | Continuation::Timer(_) => None, }; let answer = match (resume, answer) { (Continuation::Timer(task), EffectAnswer::Dropped) => return self.drop_timer(&task), + // The outcome went to the tool, and so did a failure, so + // neither it nor a drop moves a chain: the chain waits on the + // tool call. + (Continuation::ToolVfs, EffectAnswer::VfsReceipt(_) | EffectAnswer::Dropped) => { + return Ok(()); + } (_, EffectAnswer::Dropped) => Err(Error::canceled()), (Continuation::Infer(round), EffectAnswer::Chat(result)) => self .with_chain(chain, |ops| ops.accept_infer(round, result)) @@ -155,40 +169,25 @@ impl Scheduler { } } (Continuation::Timer(task), EffectAnswer::Timer) => return self.fire_timer(&task), + // Every pair the arms above left: an answer of another kind + // than its effect's, the whole outcome for an operation a tool + // asked for and a receipt for one Lua asked for among them. + // Both lists name every variant, so a new one fails the build + // here. ( - Continuation::Infer(_) | Continuation::Chat(_), - EffectAnswer::Render(_) - | EffectAnswer::ToolCall(_) - | EffectAnswer::Vfs(_) - | EffectAnswer::Timer, - ) - | ( - Continuation::Render(_), - EffectAnswer::Chat(_) - | EffectAnswer::ToolCall(_) - | EffectAnswer::Vfs(_) - | EffectAnswer::Timer, - ) - | ( - Continuation::ToolCall(_), - EffectAnswer::Chat(_) - | EffectAnswer::Render(_) - | EffectAnswer::Vfs(_) - | EffectAnswer::Timer, - ) - | ( - Continuation::Vfs(_), + Continuation::Infer(_) + | Continuation::Chat(_) + | Continuation::Render(_) + | Continuation::ToolCall(_) + | Continuation::Vfs(_) + | Continuation::ToolVfs + | Continuation::Timer(_), EffectAnswer::Chat(_) | EffectAnswer::Render(_) | EffectAnswer::ToolCall(_) + | EffectAnswer::Vfs(_) + | EffectAnswer::VfsReceipt(_) | EffectAnswer::Timer, - ) - | ( - Continuation::Timer(_), - EffectAnswer::Chat(_) - | EffectAnswer::Render(_) - | EffectAnswer::ToolCall(_) - | EffectAnswer::Vfs(_), ) => { return Err(error::make_internal_error( "an effect's answer must be of the effect's own kind", diff --git a/crates/runvil-internal/runtime/src/execute/scheduler/dispatch.rs b/crates/runvil-internal/runtime/src/execute/scheduler/dispatch.rs index df9787e0e..fdcb73527 100644 --- a/crates/runvil-internal/runtime/src/execute/scheduler/dispatch.rs +++ b/crates/runvil-internal/runtime/src/execute/scheduler/dispatch.rs @@ -22,7 +22,7 @@ use runvil_types::error::place; use runvil_types::event::ReplyOrigin; use runvil_vfs::VfsOp; -use crate::execute::run::Effect; +use crate::execute::run::{Effect, VfsAsker}; use crate::execute::section_context::TaskSeed; use crate::lua::{Answer, LibraryKey, Request}; use crate::model::{Message, ModelBinding}; @@ -369,7 +369,9 @@ impl ChainOps<'_> { ) })?); let effect = Effect::Vfs { - store: held.made_for.clone(), + asker: VfsAsker::Lua { + store: held.made_for.clone(), + }, access: view, op: op.clone(), }; diff --git a/crates/runvil-internal/runtime/src/execute/scheduler/drive.rs b/crates/runvil-internal/runtime/src/execute/scheduler/drive.rs index 496b6289c..c783c1ac3 100644 --- a/crates/runvil-internal/runtime/src/execute/scheduler/drive.rs +++ b/crates/runvil-internal/runtime/src/execute/scheduler/drive.rs @@ -2,8 +2,9 @@ //! answer`, run until no chain can proceed without an answer or a message //! from the caller. The step applies the messages `Run::deliver` queued, //! checks that the run can start and starts its first chain on its first -//! call, drains the ready queue, and returns the effects the drain issued -//! with the events it reported. +//! call, drains the ready queue, and returns the effects issued since the +//! last step, those `Run::request_file` issued for a tool's file requests +//! and then those the drain issued, with the events it reported. //! An empty ready queue with no parked effect and no queued chain that can //! be admitted is a stall, which ends the run rather than hangs, unless the //! main chain waits on its inbox: then the step reports `waiting_for_input`, @@ -18,15 +19,16 @@ use runvil_types::error::{ErrorCode, make_failure_error, place}; use runvil_types::event_lifecycle; use runvil_types::ids::AbandonReason; +use runvil_vfs::VfsOp; -use crate::execute::run::{EffectAnswer, EffectId, Step}; +use crate::execute::run::{Effect, EffectAnswer, EffectId, Step, VfsAsker}; use crate::prompt::Prompt; use crate::{Error, Result, error}; use super::chain::ChainStep; -use super::effects::Arrival; +use super::effects::{Arrival, Asking}; use super::inbox::main_task; -use super::{Phase, Scheduler}; +use super::{Continuation, Phase, Scheduler}; impl Scheduler { /// Drains the ready queue and returns the step's outcome: the effects @@ -164,6 +166,39 @@ impl Scheduler { } } + /// Applies one file request of the open tool call `call`: issues `op` + /// as a `Vfs` effect whose asker is the call, under the chain that + /// awaits the call and with the call's own access, for the next step + /// to return. No chain parks on the effect. + /// + /// A request for an effect whose chain stopped waiting is discarded. + /// A request that names no outstanding tool call, because the run + /// never issued the id, its answer already arrived, or it is an + /// effect of another kind, ends the run with an internal error, as an + /// answer for an unknown id does. A run that has returned `Done` + /// ignores every request. + pub(crate) fn request_file(&mut self, call: EffectId, op: VfsOp) { + if matches!(self.phase, Phase::Done) { + return; + } + match self.effects.asking(call) { + Asking::Awaited(chain, access) => { + let effect = Effect::Vfs { + asker: VfsAsker::Tool { call }, + access, + op, + }; + self.with_chain(chain, |ops| { + ops.issue(effect, Continuation::ToolVfs); + }); + } + Asking::Orphaned => {} + Asking::NotACall => self.end(Err(error::make_internal_error( + "a file request named an effect that is no outstanding tool call of the run", + ))), + } + } + /// Checks that the run can start: the version gate of the run's prompt /// and then of each prompt it links, in the order of their names, then /// the caller's arguments, then what those prompts require of the diff --git a/crates/runvil-internal/runtime/src/execute/scheduler/effects.rs b/crates/runvil-internal/runtime/src/execute/scheduler/effects.rs index f4d99a9a8..3a6825e71 100644 --- a/crates/runvil-internal/runtime/src/execute/scheduler/effects.rs +++ b/crates/runvil-internal/runtime/src/execute/scheduler/effects.rs @@ -18,14 +18,19 @@ //! itself holds none of this: it describes the work, the continuation //! describes what the work means to the chain. //! +//! A file operation that an open tool call asks for is keyed under the +//! chain that awaits the call, though no chain waits on it: the chain's +//! end withdraws it with the call, and its answer resumes nothing. +//! //! [`EffectAnswer`]: super::EffectAnswer //! [`Answer`]: super::Answer use std::collections::HashMap; +use std::sync::Arc; use runvil_types::event::ReplyOrigin; use runvil_types::ids::{Provenance, RoundId, TaskId}; -use runvil_vfs::{ExecId, VfsOp}; +use runvil_vfs::{Access, ExecId, VfsOp}; use crate::execute::run::{Effect, EffectId, IssuedEffect, Round}; use crate::lua::{ScriptReport, ToolBinding}; @@ -58,11 +63,16 @@ pub(super) enum Continuation { /// dispatch body (counts already taken at dispatch, then the /// succeeded/failed event, the trust rule, and the `ToolResult`). ToolCall(ToolCallContinuation), - /// A [`Vfs`](Effect::Vfs) effect: the operation the chain - /// yielded, from which the answer's succeeded/failed observation, its - /// failure's model-facing message, and its make_determinism_error classification - /// render under the call surface the author used. + /// A [`Vfs`](Effect::Vfs) effect the chain's Lua asked for: the + /// operation the chain yielded, from which the answer's + /// succeeded/failed observation, its failure's model-facing message, + /// and its make_determinism_error classification render under the + /// call surface the author used. Vfs(VfsOp), + /// A [`Vfs`](Effect::Vfs) effect an open tool call asked for: its + /// answer resumes no chain and reports nothing, because the caller + /// hands the outcome to the tool, whose call the chain still awaits. + ToolVfs, /// The internal timer behind a timed wait, naming the timer's task: the /// firing completes that task's entry and wakes its waiting owner; no /// chain resumes. @@ -72,7 +82,7 @@ pub(super) enum Continuation { /// What a bound `tool_call`'s answer is applied with: the binding the call /// resolved to (its alias, output kind, and trust rules), the coordinates /// the `ToolResult` reports under, the call's site, and the call's -/// identity the answer joins. +/// access, whose identity the answer joins. #[derive(Debug)] pub(super) struct ToolCallContinuation { /// The binding the alias resolved to at dispatch. @@ -81,10 +91,18 @@ pub(super) struct ToolCallContinuation { pub(super) report: ScriptReport, /// Who asked for the call, and where its answer goes. pub(super) site: CallSite, - /// The call's own identity, forked from the chain's access at - /// dispatch. The answer, or the call's abort, ends it and joins it - /// back into the chain. - pub(super) exec: ExecId, + /// The call's own access, forked from the chain's at dispatch. Each + /// file operation the tool asks for is issued with it. The answer, or + /// the call's abort, ends its identity and joins it back into the + /// chain. + pub(super) access: Arc, +} + +impl ToolCallContinuation { + /// The call's own identity, which its answer or its abort ends. + pub(super) fn exec(&self) -> ExecId { + self.access.id() + } } /// Who asked for one tool call, and where its answer goes. Only a @@ -168,6 +186,19 @@ pub(super) enum Arrival { Unknown, } +/// What a file request finds of the effect it names as its tool call. +#[derive(Debug)] +pub(super) enum Asking { + /// A chain awaits the tool call: that chain, and the call's access. + Awaited(ChainIndex, Arc), + /// The chain stopped waiting on the effect, so the request is + /// discarded. + Orphaned, + /// The id names no outstanding tool call: the run never issued it, + /// its answer already arrived, or it is an effect of another kind. + NotACall, +} + /// The effect table and the step's outgoing queue. #[derive(Default)] pub(super) struct EffectTable { @@ -231,11 +262,24 @@ impl EffectTable { } } + /// What a file request finds of `call`, the effect it names as its + /// tool call, which stays in the table. + pub(super) fn asking(&self, call: EffectId) -> Asking { + match self.outstanding.get(&call) { + Some(Outstanding::Awaited(Pending { + chain, + resume: Continuation::ToolCall(held), + })) => Asking::Awaited(*chain, Arc::clone(&held.access)), + Some(Outstanding::Orphaned) => Asking::Orphaned, + Some(Outstanding::Awaited(_)) | None => Asking::NotACall, + } + } + /// Orphans `id`, whose chain stopped waiting, and lists it as /// withdrawn: the caller still owes the answer, which is discarded on /// arrival. Only a tool call has an identity to end, so only a tool /// call returns its chain and identity; a `chat` round, an `infer`, a - /// render, a store operation, and a timer return `None`. An id with no + /// render, a file operation, and a timer return `None`. An id with no /// entry stays unknown, so an answer for it still fails loudly, and an /// orphan stays as it is. pub(super) fn orphan(&mut self, id: EffectId) -> Option<(ChainIndex, ExecId)> { @@ -247,11 +291,12 @@ impl EffectTable { }; self.withdrawn.push(id); match resume { - Continuation::ToolCall(call) => Some((chain, call.exec)), + Continuation::ToolCall(call) => Some((chain, call.exec())), Continuation::Infer(_) | Continuation::Chat(_) | Continuation::Render(_) | Continuation::Vfs(_) + | Continuation::ToolVfs | Continuation::Timer(_) => None, } } @@ -329,9 +374,12 @@ mod tests { //! exactly one answer, an orphan's answer is discarded, unknown ids and //! second answers are reported, every orphaned effect is withdrawn, in id //! order, and teardown withdraws every outstanding one, a step lists only - //! withdrawals still owed an answer, and an effect orphaned in its own - //! step still goes out with that step. + //! withdrawals still owed an answer, an effect orphaned in its own + //! step still goes out with that step, a file request finds its tool + //! call only while a chain awaits it, and a tool's file operation is + //! keyed under the call's chain. + use std::sync::Arc; use std::time::Duration; use runvil_types::ids::{ChainId, Provenance, RoundId, TaskId}; @@ -340,7 +388,7 @@ mod tests { use serde_json::json; use super::super::ChainIndex; - use super::{Arrival, CallSite, Continuation, EffectTable, ToolCallContinuation}; + use super::{Arrival, Asking, CallSite, Continuation, EffectTable, ToolCallContinuation}; use crate::execute::run::{Effect, EffectId}; use crate::lua::{ScriptReport, ToolBinding}; @@ -396,11 +444,62 @@ mod tests { binding, report: ScriptReport { turn: 0 }, site: CallSite::Script, - exec, + access: Arc::new(access), }); (table.issue(chain, provenance(), timer(), resume), exec) } + #[test] + fn a_file_request_finds_an_awaited_tool_call_with_its_chain_and_its_access() { + let mut table = EffectTable::default(); + let (call, exec) = issue_tool_call(&mut table, chain(4)); + let Asking::Awaited(awaiting, access) = table.asking(call) else { + panic!("the call is awaited"); + }; + assert_eq!(awaiting, chain(4)); + assert_eq!(access.id(), exec, "the access is the call's own"); + assert!( + matches!(table.arrive(call), Arrival::Awaited(_)), + "the lookup left the call in the table" + ); + } + + #[test] + fn a_file_request_finds_no_call_in_an_orphan_another_kind_or_an_unknown_id() { + let mut table = EffectTable::default(); + let (orphan, _) = issue_tool_call(&mut table, chain(0)); + table.orphan(orphan); + assert!(matches!(table.asking(orphan), Asking::Orphaned)); + let round = issue_round(&mut table, chain(0)); + assert!( + matches!(table.asking(round), Asking::NotACall), + "a model round is no tool call" + ); + let file = table.issue(chain(0), provenance(), timer(), Continuation::ToolVfs); + assert!( + matches!(table.asking(file), Asking::NotACall), + "a tool's file operation is no tool call" + ); + let (answered, _) = issue_tool_call(&mut table, chain(0)); + assert!(matches!(table.arrive(answered), Arrival::Awaited(_))); + assert!( + matches!(table.asking(answered), Asking::NotACall), + "an answered call is gone" + ); + assert!(matches!(table.asking(EffectId(99)), Asking::NotACall)); + } + + #[test] + fn a_tools_file_operation_is_awaited_by_the_calls_chain_and_orphans_with_no_identity() { + let mut table = EffectTable::default(); + let (call, _) = issue_tool_call(&mut table, chain(2)); + let file = table.issue(chain(2), provenance(), timer(), Continuation::ToolVfs); + assert_eq!(table.awaited_by(chain(2)), [call, file]); + assert_eq!(table.orphan(file), None, "it has no identity of its own"); + let (_, withdrawn) = table.take_step(); + assert_eq!(withdrawn, [file]); + } + #[test] fn an_issued_effect_is_awaited_until_its_one_answer_arrives() { let mut table = EffectTable::default(); diff --git a/crates/runvil-internal/runtime/src/execute/scheduler/tool_call.rs b/crates/runvil-internal/runtime/src/execute/scheduler/tool_call.rs index 46e170d8a..fa0c0f98f 100644 --- a/crates/runvil-internal/runtime/src/execute/scheduler/tool_call.rs +++ b/crates/runvil-internal/runtime/src/execute/scheduler/tool_call.rs @@ -40,6 +40,14 @@ //! closes the innermost open call and reports it. An adhoc call never //! issues leaf work of its own. //! +//! While a bound call is open, its tool asks for file operations through +//! the caller, which reports each request to the run. The run-level +//! `request_file` issues the operation as a `Vfs` effect whose asker is +//! the call, under the chain that awaits the call and with the call's own +//! access, which the call's continuation keeps, so the operation runs +//! under the call's identity. The chain stays parked on the call: the +//! answer to such an effect resumes nothing. +//! //! A discovery call is decided in full before any preparer runs (the //! freeze-before-preparer guarantee). A direct call to a Dynamic Set tool, //! and every malformed discovery call, is answered with refusal text that @@ -603,20 +611,20 @@ impl ChainOps<'_> { prompt_origin(&prompt, &binding.id().to_string(), chain.blocks(&prompt)), ) .map_err(|cause| error::make_files_error(&cause))?; - let exec = access.id(); + let access = Arc::new(access); let effect = Effect::ToolCall { tool: binding.id().clone(), alias: binding.alias().to_owned(), args, origin, - access: Arc::new(access), + access: Arc::clone(&access), survives_stop: binding.survives_stop(), }; let resume = Continuation::ToolCall(ToolCallContinuation { binding, report, site, - exec, + access, }); self.issue(effect, resume); Ok(()) diff --git a/crates/runvil-internal/runtime/src/execute/tests/effects.rs b/crates/runvil-internal/runtime/src/execute/tests/effects.rs index 1c0163320..9920b7586 100644 --- a/crates/runvil-internal/runtime/src/execute/tests/effects.rs +++ b/crates/runvil-internal/runtime/src/execute/tests/effects.rs @@ -19,7 +19,7 @@ use super::models_loop::{loop_model_name, loop_scenario}; use super::scheduler::scheduler_scenario; use super::*; use crate::execute::run::{ - AnswerRecord, EffectRecord, PackToolSets, Round, ToolCallOrigin, ToolCaller, + AnswerRecord, EffectRecord, PackToolSets, Round, ToolCallOrigin, ToolCaller, VfsAsker, }; use crate::test_support::rig::Rig; use crate::test_support::scenario::{fresh_store_view, round_trip}; @@ -202,18 +202,21 @@ fn a_store_operation_issues_exactly_one_store_effect() { let rig = Rig::run(loop_scenario(source)); assert_eq!(rig.trace().text(), "kept"); + let root_store = VfsAsker::Lua { + store: ChainId::root(), + }; assert_eq!( rig.issued(), vec![ EffectRecord::Vfs { - store: ChainId::root(), + asker: root_store.clone(), op: VfsOp::Write { path: "notes.md".to_owned(), contents: b"kept".to_vec(), }, }, EffectRecord::Vfs { - store: ChainId::root(), + asker: root_store, op: VfsOp::Read { path: "notes.md".to_owned(), start: None, diff --git a/crates/runvil-internal/runtime/src/execute/tests/execute/store.rs b/crates/runvil-internal/runtime/src/execute/tests/execute/store.rs index 95308b9e5..97362ba56 100644 --- a/crates/runvil-internal/runtime/src/execute/tests/execute/store.rs +++ b/crates/runvil-internal/runtime/src/execute/tests/execute/store.rs @@ -11,7 +11,7 @@ use runvil_types::ids::ChainId; use runvil_vfs::Store; use super::*; -use crate::execute::run::{AnswerRecord, EffectRecord}; +use crate::execute::run::{AnswerRecord, EffectRecord, VfsAsker}; use crate::test_support::rig::Rig; use crate::test_support::scenario::fresh_store_view; @@ -197,7 +197,13 @@ fn the_vfs_records_of_each_store_id_rebuild_that_store() { // new store for each store id the records name. let mut rebuilt: BTreeMap = BTreeMap::new(); for (effect, answer) in trace.effects() { - let (EffectRecord::Vfs { store, op }, AnswerRecord::Vfs(Ok(outcome))) = (effect, answer) + let ( + EffectRecord::Vfs { + asker: VfsAsker::Lua { store }, + op, + }, + AnswerRecord::Vfs(Ok(outcome)), + ) = (effect, answer) else { continue; }; @@ -349,7 +355,10 @@ fn a_store_made_for_an_execute_names_the_executed_chain_whichever_of_its_chains_ .effects() .iter() .filter_map(|(effect, _)| match effect { - EffectRecord::Vfs { store, .. } => Some(store.to_string()), + EffectRecord::Vfs { + asker: VfsAsker::Lua { store }, + .. + } => Some(store.to_string()), _ => None, }) .collect(); diff --git a/crates/runvil-internal/runtime/src/execute/tests/preludes.rs b/crates/runvil-internal/runtime/src/execute/tests/preludes.rs index 730508fd2..f76319fee 100644 --- a/crates/runvil-internal/runtime/src/execute/tests/preludes.rs +++ b/crates/runvil-internal/runtime/src/execute/tests/preludes.rs @@ -16,7 +16,7 @@ use runvil_vfs::VfsOp; use super::fixtures::echo_tool; use super::*; -use crate::execute::run::{EffectRecord, ToolCallOrigin, ToolCaller}; +use crate::execute::run::{EffectRecord, ToolCallOrigin, ToolCaller, VfsAsker}; /// A prelude contributed by the Pack `id`. pub(super) fn prelude(id: &str, source: &str) -> Prelude { Prelude::new(PackId::parse(id).expect("a valid Pack id"), source) @@ -142,7 +142,7 @@ fn a_prelude_that_catches_its_store_call_installs_and_leaves_the_store_untouched assert_eq!( records(&trace), vec![EffectRecord::Vfs { - store: ChainId::root(), + asker: root_store(), op: VfsOp::Exists { path: "seeded.txt".to_owned(), }, @@ -281,19 +281,26 @@ fn a_library_a_fanout_arm_and_a_spawned_task_all_see_a_prelude_global() { ); } +/// The asker of a `store` call on the store the run starts with. +fn root_store() -> VfsAsker { + VfsAsker::Lua { + store: ChainId::root(), + } +} + /// The two store effects of a prelude function that writes `text` to /// `path` and reads it back. fn write_then_read(path: &str, text: &str) -> Vec { vec![ EffectRecord::Vfs { - store: ChainId::root(), + asker: root_store(), op: VfsOp::Write { path: path.to_owned(), contents: text.as_bytes().to_vec(), }, }, EffectRecord::Vfs { - store: ChainId::root(), + asker: root_store(), op: VfsOp::Read { path: path.to_owned(), start: None, diff --git a/crates/runvil-internal/runtime/src/lib.rs b/crates/runvil-internal/runtime/src/lib.rs index f939aa520..1c0361134 100644 --- a/crates/runvil-internal/runtime/src/lib.rs +++ b/crates/runvil-internal/runtime/src/lib.rs @@ -3,9 +3,11 @@ //! //! A run walks the prompt's top-level sections top to bottom, the preamble //! first when the prompt has one. It issues each model round, Pack render, Pack tool call, -//! `store` call, and timer as an [`Effect`] the +//! file operation, and timer as an [`Effect`] the //! Harness performs and answers, and reports every boundary as an event -//! returned from `step`. Other crates reach these items through the +//! returned from `step`. A file operation is a `store` call of the +//! prompt's Lua, or a request of an open tool call that the caller +//! reports with [`Run::request_file`]. Other crates reach these items through the //! `runvil-engine` facade. //! //! ## Invariants @@ -37,5 +39,5 @@ use crate::error::{Error, Result}; // `runvil_runtime::X`, not a module path. pub use crate::execute::{ Effect, EffectAnswer, EffectId, IssuedEffect, PackToolSets, Round, Run, RunLimits, RunParams, - Step, ToolCallOrigin, ToolCaller, perform_vfs_op, + Step, ToolCallOrigin, ToolCaller, VfsAsker, VfsReceipt, perform_vfs_op, }; diff --git a/decisions/engine.md b/decisions/engine.md index 58a9f2930..222520bf2 100644 --- a/decisions/engine.md +++ b/decisions/engine.md @@ -1,6 +1,6 @@ # The Engine: design decisions -This page covers the Engine as a library: parsing a prompt, the run state machine, effects and their answers, run limits, the one error type, the public surface, and the internal crates. The Engine is a Rust library that parses a prompt file and runs it as a state machine. `Prompt::parse` compiles each Lua block and returns a `Prompt`, which also holds every prompt that it lists for `execute`, and `Run::new` builds a `Run` from it. Each `Run::step` runs the prompt's Lua until the run waits for answers and returns the effects the run needs: model rounds, Pack renders, Pack tool calls, `store` operations, and timers. The caller performs each effect and passes its answer to `Run::resume`. A run ends with its final text or with one `Error`. Private crates contain the code, and `runvil-engine` re-exports the names a caller uses. +This page covers the Engine as a library: parsing a prompt, the run state machine, effects and their answers, run limits, the one error type, the public surface, and the internal crates. The Engine is a Rust library that parses a prompt file and runs it as a state machine. `Prompt::parse` compiles each Lua block and returns a `Prompt`, which also holds every prompt that it lists for `execute`, and `Run::new` builds a `Run` from it. Each `Run::step` runs the prompt's Lua until the run waits for answers and returns the effects the run needs: model rounds, Pack renders, Pack tool calls, file operations, and timers. The caller performs each effect and passes its answer to `Run::resume`. A run ends with its final text or with one `Error`. Private crates contain the code, and `runvil-engine` re-exports the names a caller uses. ## 1. The Engine and its caller @@ -10,9 +10,9 @@ An effect is a Rust value that describes one piece of outside work, such as a mo The Engine returns this work as values so that it is independent of any runtime and is a deterministic function of its inputs. -### The Engine returns model rounds, Pack work, store operations, and timers as effects, and performs the rest itself +### The Engine returns model rounds, Pack work, file operations, and timers as effects, and performs the rest itself -The variants of `Effect` are `Chat` for one model round, `Render` for a Pack's rendering of offered tools, `ToolCall` for one call of a Pack's tool, `Vfs` for one `store` operation, and `Timer` for one sleep. [Tools and Packs](tools-and-packs.md) covers `Render` and `ToolCall`. +The variants of `Effect` are `Chat` for one model round, `Render` for a Pack's rendering of offered tools, `ToolCall` for one call of a Pack's tool, `Vfs` for one file operation, and `Timer` for one sleep. A file operation is a `store` call of the prompt's Lua, or a file request of an open tool call. [Tools and Packs](tools-and-packs.md) covers `Render` and `ToolCall`. The Engine performs these kinds of work itself and reports each as an event: an adhoc tool call, a `GetDynamicTools` call, and a refused discovery call. @@ -56,12 +56,18 @@ A heading outside the set and a heading absent from the file get the same answer ## 3. The run state machine -### A caller steps a run with `Run::new`, `Run::step`, `Run::resume`, and `Run::deliver` +### A caller steps a run with `Run::new`, `Run::step`, `Run::resume`, `Run::deliver`, and `Run::request_file` -`Run::new(prompt, args, params)` builds a run, and `args` is the text of the run's arguments, one JSON object. The run holds `prompt` and every prompt it links, so a caller passes the prompt that `Prompt::parse` returned. `Run::step` advances it until it needs an answer and returns a `Step`. `Run::resume(id, answer)` delivers the answer to one effect. `Run::deliver(text)` queues a message for the main chain's inbox ([The Harness and the Host API](harness-and-host.md)). A chain is the Engine's record of one sequence of sections: the main walk, a `call` child, an `execute` child, or a task ([Tasks and fanout](tasks-and-fanout.md)). `Run` is `Send` and owns its prompt through an `Arc`. +`Run::new(prompt, args, params)` builds a run, and `args` is the text of the run's arguments, one JSON object. The run holds `prompt` and every prompt it links, so a caller passes the prompt that `Prompt::parse` returned. `Run::step` advances it until it needs an answer and returns a `Step`. `Run::resume(id, answer)` delivers the answer to one effect. `Run::deliver(text)` queues a message for the main chain's inbox ([The Harness and the Host API](harness-and-host.md)). `Run::request_file(call, op)` reports one file request of an open tool call, and the next `Run::step` returns the operation as a `Vfs` effect. A chain is the Engine's record of one sequence of sections: the main walk, a `call` child, an `execute` child, or a task ([Tasks and fanout](tasks-and-fanout.md)). `Run` is `Send` and owns its prompt through an `Arc`. The caller answers effects one at a time, in any order. Parallel work in a fanout depends on that: the caller resumes one arm while the effects of the other arms are in flight. +### A tool call stays open while its tool asks for files + +The `ToolCall` effect stays open until the caller answers it with the tool's result. While it is open, the tool asks its caller for each file operation it needs, and the caller reports each request with `Run::request_file(call, op)`, where `call` is the id of the `ToolCall` effect. The Engine issues the operation as a `Vfs` effect whose asker is that call, under the task that made the call and with the call's own file access. A request for a call whose chain stopped waiting does nothing. A request for any other id ends the run with an `internal` error, as a bad answer does. A request on a run that has returned `Step::Done` does nothing. + +The request goes through the Engine so that the run's record holds every file operation of a tool, in order with the rest of the run. The owner's rule: "every VFS operation that's performed by a tool has to turn into an effect in the engine." The call stays open because the tool's result is still to come: the file operation is a step of the call, and the call's one answer is that result. + ### `Run::new` always succeeds, and the first `step` checks that the run can start The first `Run::step` makes the start checks, in this order. The prompt and every prompt it links declare `runvil: 0`. The arguments are one JSON object that matches the prompt's `args:` declaration ([The prompt language](prompt-language.md)): `Run::new` reads the text and keeps a mismatch for this check, which returns it with the code `args_invalid` and no location. The params meet what each of those prompts requires: each Pack under a `uses:` is `Usable` in the roster that the caller passed to `RunParams::with_packs`, and the model in each role that a prompt declares meets that prompt's requirements for the role. A requirements failure has the code `requirements_unmet`, and its message names every gap. @@ -84,9 +90,9 @@ The Harness matches these values. With `#[non_exhaustive]` it would need wildcar ### Every effect gets exactly one answer, and `Dropped` is an answer -`EffectAnswer` has one variant for each effect kind, plus `Dropped`. A caller that abandons an effect answers it `Dropped`, and the chain that waited resumes with the canceled error. `Run::step` returns `Step::Done` once the caller has answered every issued effect, so a store operation still in progress finishes inside the run's file scope. +`EffectAnswer` has one variant for each effect kind, a second one for the `Vfs` kind, and `Dropped`. A `Vfs` effect takes `Vfs` when the prompt's Lua asked for it and `VfsReceipt` when a tool call did. A caller that abandons an effect answers it `Dropped`, and the chain that waited resumes with the canceled error. `Run::step` returns `Step::Done` once the caller has answered every issued effect, so a file operation still in progress finishes inside the run's file scope. -These caller mistakes end the run with an `internal` error: an answer of the wrong kind, an answer for an unknown id, and a second answer for one effect. The Engine discards an answer for an effect whose chain stopped waiting. +These caller mistakes end the run with an `internal` error: an answer of the wrong kind, a `Vfs` answer of the other form, an answer for an unknown id, and a second answer for one effect. The Engine discards an answer for an effect whose chain stopped waiting. ### A step lists the effects it withdraws @@ -128,17 +134,21 @@ One counter numbers every model round of a run in issue order, and loop rounds a A `Round` has only these two values, because a caller needs only a round's id and whether the round is user-facing. -### `Effect::Vfs` is one `store` operation +### `Effect::Vfs` is one file operation, and it says who asked -The Engine issues a `Vfs` effect for each `store.*` call. Its fields are `store`, the id of the store that the call works on, `access`, the calling chain's view of that store, and `op`, a `VfsOp` with the call's arguments. A caller answers it with `perform_vfs_op(&access, &op)`, a synchronous function that runs the operation with `Access::perform` ([Files and the VFS](files-and-the-vfs.md)). +The Engine issues a `Vfs` effect for each `store.*` call, and for each file request of an open tool call that the caller reports with `Run::request_file`. Its fields are `asker`, `access`, and `op`, a `VfsOp` with the operation's arguments. `asker` is a `VfsAsker`: `Lua` for a `store` call, with the id of the store that the call works on, and `Tool` for a tool's request, with the effect id of the tool call. The asker settles the files. A `store` call works on its chain's store, and `access` is the calling chain's view of that store. A tool's request works on the file system the caller gave the run, and `access` is the call's own file access. A caller performs the operation with `Access::perform`, or with `perform_vfs_op(&access, &op)`, a synchronous function that calls it ([Files and the VFS](files-and-the-vfs.md)). -A run has more than one store when a prompt executes another, so the effect names its store. The `store` field is a `ChainId`: `0`, the id of the root chain, for the store that a run starts with, and the id of an executed prompt's chain, such as `0.0`, for a store that an `execute` made. The view alone would be enough to perform the operation, and the id is there for the record. +A caller answers a `store` call with `EffectAnswer::Vfs`, the whole `VfsOutcome`, and the `store` call resumes with it. It answers a tool's request with `EffectAnswer::VfsReceipt`, once it has handed the whole outcome to the tool. A `VfsReceipt` is a stat, a bool, a count of entries or paths, a count of bytes, or done, and `VfsReceipt::of` makes one from an outcome. The Engine gets the receipt alone, so it holds no copy of the bytes of a read. The answer to a tool's request resumes no chain, and a failure in it goes to the tool and leaves the run alone, because the chain waits on the tool call and the tool decides what a failed operation means. The Engine reports no event for a tool's file operation: the effect record and the answer record are the view. A `store` call keeps its events. -Lua says `store`, and the names below the Lua layer say `Vfs`, because every one of these operations is a VFS operation made through a view of a store. +A run has more than one store when a prompt executes another, so the effect of a `store` call names its store. The id is a `ChainId`: `0`, the id of the root chain, for the store that a run starts with, and the id of an executed prompt's chain, such as `0.0`, for a store that an `execute` made. The view alone would be enough to perform the operation, and the id is there for the record. + +Lua says `store`, and the names below the Lua layer say `Vfs`, because every one of these operations is a VFS operation: one made through a view of a store, or one made through the access of a tool call. ### `Effect::record` and `EffectAnswer::record` return JSON for the run log -`Effect::record` returns the effect as a `serde_json::Value`, minus its live handles. A `ToolCall` record omits the file access, a `Vfs` record omits the view and keeps the store's id beside the operation, and a `Timer` record stores seconds, though the effect has a `Duration`. `EffectAnswer::record` returns the answer's outcome, and a failure is an object with a `kind`, the tag of its `ErrorCode` or `VfsError`, and a `message`. +`Effect::record` returns the effect as a `serde_json::Value`, minus its live handles. A `ToolCall` record omits the file access, and a `Timer` record stores seconds, though the effect has a `Duration`. A `Vfs` record omits the access and keeps who asked beside the operation: the id of the store for a `store` call, as in `{"Vfs":{"store":"0","op":{...}}}`, and the effect id of the tool call for a tool's request, as in `{"Vfs":{"call":7,"op":{...}}}`. A write or an append records its bytes as text when they are UTF-8 and as hex otherwise. + +`EffectAnswer::record` returns the answer's outcome, and a failure is an object with a `kind`, the tag of its `ErrorCode` or `VfsError`, and a `message`. A `Vfs` answer records the whole outcome, because a replay resumes Lua with it. A `VfsReceipt` answer records the receipt: a size in place of content, the number of bytes of a read or the number of entries of a listing, and the stat of a stat. The tool's own result is in the record as the answer of its `ToolCall`. The record holds no hash. ## 5. Inside a step: chains, section VMs, and requests @@ -305,7 +315,7 @@ The owner's goal: "I want as many internal crates as possible and I want maximum - **An `execute` that returns at once.** A Lua `execute_async` call that starts another prompt as a task and returns its handle. Today `execute` runs a listed prompt as a blocking child chain, and its caller waits for the result. - **Replay.** Harness code that runs a recorded run a second time and compares the records of the two runs. Today the Engine attaches a `Provenance` to each effect and event, and `Effect::record` and `EffectAnswer::record` return the JSON that a run log stores. -- **A tool's file operations as `Vfs` effects.** A `Vfs` effect for each file operation of a tool, on the file system the caller gave the run, under the call's identity ([Files and the VFS](files-and-the-vfs.md)). Today a `Vfs` effect is one `store` operation, and a `ToolCall` effect holds the call's file access. +- **A `ToolCall` effect with no file access.** A tool call whose every file operation is a `Vfs` effect, so that the `ToolCall` effect holds no access of its own ([Files and the VFS](files-and-the-vfs.md)). Today a `ToolCall` effect holds the call's file access beside the `Vfs` effects of the call's requests, and a tool that uses that access performs an operation outside the run's record. - **The round id on `ModelTurnFailed`.** A round id in the `ModelTurnFailed` event, so that a Host can drop exactly the failed round's streamed pieces. Today the Engine writes the round id in a round's thinking, reply, and tool-call events. - **Bounds on JSON conversion.** A size budget at every site that converts a Lua table. Today `json.encode` and `var` writes have a size budget, other sites in the Lua crate convert a table of any size, and one encode runs as a single Rust callback between cancel polls. - **`#[non_exhaustive]` on the error types.** The attribute on `ErrorCode`, and on `Error` and `ErrorFact` if the owner extends it to them, so that a new code leaves a Host's build intact. Today the three types are closed, and at least one function outside `runvil-types`, `kind_of` in `runvil-lua`, names every code with no catch-all arm, so it would need one or a move into `runvil-types`. diff --git a/decisions/files-and-the-vfs.md b/decisions/files-and-the-vfs.md index 2920a8cf1..1be2a1e24 100644 --- a/decisions/files-and-the-vfs.md +++ b/decisions/files-and-the-vfs.md @@ -194,7 +194,7 @@ The `store` functions stay in the Engine. A plan to serve them from a tool is dr ### A `Vfs` effect and its record name the store by a chain id -`Effect::Vfs` has a `store` field, a `ChainId`, and the effect's record holds it beside the operation, as in `{"Vfs":{"store":"0","op":{...}}}`. The id `0`, the root chain's, names the store that the run starts with. A store that an `execute` made has the id of the executed prompt's chain, such as `0.0`, and every operation on that store has this id, whichever chain of the executed prompt made the call. +The `Vfs` effect of a `store` call names its store in its `asker`, by a `ChainId`, and the effect's record holds that id beside the operation, as in `{"Vfs":{"store":"0","op":{...}}}`. The id `0`, the root chain's, names the store that the run starts with. A store that an `execute` made has the id of the executed prompt's chain, such as `0.0`, and every operation on that store has this id, whichever chain of the executed prompt made the call. The record names the store because an executed prompt reports under its caller's task, and two stores can each have a file at one path. Without the id, a reader of the log could not tell the caller's `a.md` from the child's, and neither store could be rebuilt. With it, the records of each store rebuild that store. The id is a chain id because a chain id is the same in every run with the same inputs and answers ([Tasks and fanout](tasks-and-fanout.md)), which a replay needs. diff --git a/decisions/harness-and-host.md b/decisions/harness-and-host.md index a9d5d499a..3c0c589f9 100644 --- a/decisions/harness-and-host.md +++ b/decisions/harness-and-host.md @@ -6,7 +6,7 @@ This page covers the `runvil` crate, `Host`, `RunSetup`, one Harness for each ru ### The Engine emits effects, the Harness performs them, and the Host decides policy -The root `AGENTS.md` defines the terms. The Engine, the `runvil-*` crates, parses a prompt, steps a run, and emits an effect each time the run needs a model reply, a Pack's render of the tools a section offers it, a Pack tool's result, a timer, or a store operation. The Harness, the `runvil` crate and the `harness-*` crates, steps the Engine, performs every effect, and records every run. A Host is an application such as Workshop, and it "makes every policy decision". +The root `AGENTS.md` defines the terms. The Engine, the `runvil-*` crates, parses a prompt, steps a run, and emits an effect each time the run needs a model reply, a Pack's render of the tools a section offers it, a Pack tool's result, a timer, or a file operation. The Harness, the `runvil` crate and the `harness-*` crates, steps the Engine, performs every effect, and records every run. A Host is an application such as Workshop, and it "makes every policy decision". The Harness owns the effect loop because one ordered record of a run exists only if the Harness sees every effect and every answer. Replay and resume, which are planned work, depend on the same condition. From 2d6113901f91aaffa90d4ef6766b501446d2265a Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Tue, 17 Nov 2026 19:54:38 -0800 Subject: [PATCH 05/23] Let a Pack ask for files through `ToolContext::files` A tool of a Rust Pack can ask for a file operation and wait for the outcome, so that the record of the run holds the operation. `ToolContext::files` lends a `ToolFiles`, the effect loop opens a `CallDesk` for each tool call, and `wake` returns each request for `report_request` to pass to `request_file`. The loop performs the `Vfs` effect that the run issues for the request, resumes the run with `EffectAnswer::VfsReceipt`, and hands the whole outcome to the desk. - A `CallDesk` sits in the `InFlight` entry of its call, so the loop finds a desk only while the call is in flight. A call in `Waiting` holds its desk and has not asked. - `Asked` is one queue for the run, with one entry for each request. `wake` polls it before and after `poll_landed`, because a tool asks while the loop polls it. - The desk gives each outcome to the oldest ticket in `sent`. This holds because the run issues the effects of one call in the order of the `request_file` calls, and the loop answers them in that order. - `answer_vfs` gives `EffectAnswer::Vfs` to every asker but `VfsAsker::Tool`, because the asker enum is `#[non_exhaustive]`. - `ToolContext::new` and the `call` of `ToolPerformer` take the files as a last argument. `ToolContext` has a manual `fmt::Debug` that leaves the files out, because `dyn ToolFiles` has no `Debug` bound. - A request goes out at the first poll of its future. A future dropped before the loop takes its request removes the request. A future dropped later leaves the operation with the loop, and the desk discards the outcome. - `report_request` drops the request of a call that has no desk. `answer_vfs` answers `Dropped`, with the operation not performed, for a `Vfs` effect whose call has no desk. - `perform_contained` turns a panic inside `access.perform` into `VfsError::Backend` with the text `the file operation panicked`. The path for Lua calls `perform_vfs_op` with no such guard. - A stop or a cancel that arrives after the record of a tool's `Vfs` effect does not prevent the operation. The loop performs it, records the receipt, and then drops the call. - `TestCall` answers each request at its first poll through `AnsweredAtOnce`, on the filesystem of its access. - `runvil-plugin` re-exports `VfsOp` and `VfsOutcome`, and `runvil::plugin` re-exports `ToolFiles`. - `ToolContext::access` stays, and an operation through it is outside the record. - Only test fixtures ask through the files: `FilesPack`, `Asks`, and the tests of `TestCall`. The loader of library Packs is not in this diff. - No test under the Harness covers a call that returns with a request still out, or a request whose future the tool drops. Plan: /plan/2026-11-16-1-tool-file-effects.plan.md --- .../runner/src/effect_loop-tests.rs | 2 + .../runner/src/effect_loop.rs | 228 +++++-- crates/harness-internal/runner/src/lib.rs | 7 + .../runner/src/packs-tests.rs | 101 ++- crates/harness-internal/runner/src/packs.rs | 5 +- .../harness-internal/runner/src/performers.rs | 21 +- .../runner/src/tool_files-tests.rs | 212 ++++++ .../harness-internal/runner/src/tool_files.rs | 255 ++++++++ .../runner/tests/it/effect_loop-cap.rs | 2 + .../runner/tests/it/harness-files.rs | 618 ++++++++++++++++++ .../runner/tests/it/harness.rs | 9 +- .../runner/tests/it/performers.rs | 2 + .../runner/tests/it/support.rs | 8 +- crates/runvil-plugin/src/context.rs | 134 +++- crates/runvil-plugin/src/lib.rs | 19 +- crates/runvil-plugin/src/pack.rs | 17 +- crates/runvil-plugin/src/testing.rs | 33 +- crates/runvil-plugin/tests/it/test_call.rs | 62 +- crates/runvil/public-api.txt | 5 +- crates/runvil/src/lib.rs | 6 +- decisions/files-and-the-vfs.md | 22 +- decisions/harness-and-host.md | 8 +- decisions/tasks-and-fanout.md | 2 +- decisions/testing-and-debugging.md | 2 +- decisions/tools-and-packs.md | 24 +- 25 files changed, 1657 insertions(+), 147 deletions(-) create mode 100644 crates/harness-internal/runner/src/tool_files-tests.rs create mode 100644 crates/harness-internal/runner/src/tool_files.rs create mode 100644 crates/harness-internal/runner/tests/it/harness-files.rs diff --git a/crates/harness-internal/runner/src/effect_loop-tests.rs b/crates/harness-internal/runner/src/effect_loop-tests.rs index 9a86e9cfc..8819eb1d9 100644 --- a/crates/harness-internal/runner/src/effect_loop-tests.rs +++ b/crates/harness-internal/runner/src/effect_loop-tests.rs @@ -17,6 +17,7 @@ use runvil_engine::{ BoxFuture, Error, ErrorCode, Prompt, Run, RunParams, RunSeed, Step, Timestamp, }; use runvil_engine::{ToolCatalog, ToolId, ToolInfo, ToolOutput}; +use runvil_plugin::ToolFiles; use serde_json::{Value, json}; use super::{STALLED, drive}; @@ -113,6 +114,7 @@ impl ToolPerformer for Unused { _access: Arc, _origin: ToolCallOrigin, _args: Value, + _files: Arc, ) -> BoxFuture<'static, Result> { unreachable!("the loop never sees the lost run's tool call") } diff --git a/crates/harness-internal/runner/src/effect_loop.rs b/crates/harness-internal/runner/src/effect_loop.rs index 31fe7044e..933725945 100644 --- a/crates/harness-internal/runner/src/effect_loop.rs +++ b/crates/harness-internal/runner/src/effect_loop.rs @@ -10,25 +10,45 @@ //! future: the loop starts no task, so a run is one future that any //! executor can drive. When an effect's future lands, the loop appends the //! answer's record and resumes the run with it, then steps again. A Vfs -//! effect has no future: it is one operation on a store of the run, and -//! file operations are synchronous by design, so the loop performs the -//! operation inline through the effect's view, appends the answer's -//! record, and resumes the run at once. A run has the store it starts with and one more for each prompt -//! an `execute` runs, and the effect's record names its store, so the -//! loop reads the view and never which store it reaches. It resumes every -//! Vfs effect of a step this way and then steps once, so the loop awaits -//! an answer only when it answered nothing inline. Vfs operations from -//! different chains run one at a time in issue order. +//! effect has no future: it is one file operation, and file operations +//! are synchronous by design, so the loop performs the operation inline +//! through the effect's access, appends the answer's record, and resumes +//! the run at once. It resumes every Vfs effect of a step this way and +//! then steps once, so the loop awaits an answer only when it answered +//! nothing inline. Vfs operations run one at a time in issue order, +//! whichever chain or tool call asked for each. +//! +//! The prompt's Lua asks for a Vfs effect with a `store` call, and the +//! operation works on a store of the run. A run has the store it starts +//! with and one more for each prompt an `execute` runs, and the effect's +//! record names its store, so the loop reads the view and never which +//! store it reaches. The loop answers with the operation's whole outcome. +//! +//! A tool call asks through its files, the desk the loop lends it. Each +//! request joins the run's queue of the calls that asked, which the loop +//! reads beside the effects in flight, before and after it polls them. +//! For a request from a call still in flight, the loop reports the +//! operation to the run with `Run::request_file` and steps, and the run +//! issues it as a Vfs effect whose asker is the call. The loop performs +//! it on the run's filesystem through the call's own access, inside a +//! guard that turns a panic of the Host's policy or backend into a +//! backend failure, appends the answer's record, resumes the run with +//! the receipt of the outcome, and hands the whole outcome to the call's +//! desk, which wakes the call. The tool call stays in flight throughout. +//! A request from a call that has landed or was aborted is dropped, and a +//! Vfs effect whose call has gone since it asked is answered `Dropped` +//! unperformed. //! //! An effect the step withdraws is answered `Dropped` without being //! performed, and a withdrawn effect an earlier step issued is aborted //! and answered `Dropped`, so the step that decides the run leaves the //! loop nothing to perform. //! -//! The loop waits on four things at once: the run's cancel flag, the stop +//! The loop waits on five things at once: the run's cancel flag, the stop //! a Host raises through [`RunControl::stop_round`](crate::RunControl::stop_round), //! the messages a Host sends through -//! [`RunControl::send`](crate::RunControl::send), and the next effect to +//! [`RunControl::send`](crate::RunControl::send), the next file request +//! of a tool call, and the next effect to //! land. A cancel aborts every effect in flight, //! answers each `Dropped`, and steps the run, which reads the same flag, //! to `Done`. A stop aborts every effect in flight except tool calls that @@ -90,18 +110,20 @@ use std::task::{Context, Poll, Waker}; use futures_util::future::{AbortHandle, Abortable, Aborted, FutureExt as _}; use futures_util::stream::{FuturesUnordered, StreamExt as _}; use runvil_engine::cancel::CancelHandle; -use runvil_engine::effect::{Effect, EffectAnswer, EffectId, IssuedEffect}; +use runvil_engine::effect::{Effect, EffectAnswer, EffectId, IssuedEffect, VfsAsker, VfsReceipt}; use runvil_engine::event::Event; use runvil_engine::ids::{Provenance, TaskId}; -use runvil_engine::vfs::{Access, VfsOp, perform_vfs_op}; +use runvil_engine::vfs::{Access, VfsError, VfsOp, VfsOutcome, perform_vfs_op}; use runvil_engine::{BoxFuture, Error, ErrorCode}; use runvil_engine::{Run, Step}; +use runvil_plugin::ToolFiles; use tracing::Instrument as _; use crate::harness::{RunControl, SendQueue, StopSignal}; use crate::performers::{InferenceBroker, Timer, ToolPerformer}; use crate::recorder::{Record, RecordKind, RunId, RunRecorder, make_recorder_error, refused}; use crate::setup::RunSetup; +use crate::tool_files::{Asked, CallDesk}; /// The message of the failure a stalled run ends with. const STALLED: &str = "the effect loop has nothing to await for a pending run"; @@ -167,6 +189,7 @@ pub(crate) async fn drive( recorder: Arc::clone(&setup.recorder), run_id, flights: Flights::new(setup.max_tool_calls_in_flight), + asked: Arc::new(Asked::default()), cancel: control.cancel_handle().clone(), stop: Arc::clone(control.stop_signal()), sends: Arc::clone(control.send_queue()), @@ -191,6 +214,9 @@ struct Driver { /// tool calls waiting for a slot. Dropping the driver drops their futures, so /// nothing a performer holds outlives the drive however it ends. flights: Flights, + /// The tool calls that asked for a file operation, one entry for each + /// request the loop has not taken off its call's desk. + asked: Arc, cancel: CancelHandle, stop: Arc, /// The messages the Host sent that the loop has not delivered yet. @@ -208,10 +234,20 @@ enum Woken { Stop, /// The Host sent these messages, oldest first. Sent(Vec), + /// This tool call asked for a file operation. + Asked(EffectId), /// An effect's future landed with its answer. Landed(EffectId, Provenance, EffectAnswer), } +/// A Vfs effect, which the loop answers inline: who asked for it, the +/// access it runs on, and the operation. +struct InlineVfs { + asker: VfsAsker, + access: Arc, + op: VfsOp, +} + impl Driver { async fn drive(&mut self) -> Result { let early = self.sends.take(); @@ -287,9 +323,8 @@ impl Driver { // answered here; every other kind goes in flight. // The run is not stepped between inline answers: // the whole batch is resumed, then stepped once. - if let Some((access, op)) = self.perform(id, provenance, issued.effect) { - let answer = answer_vfs(access, op); - self.answer(id, provenance, answer).await?; + if let Some(vfs) = self.perform(id, provenance, issued.effect) { + self.answer_vfs(id, provenance, vfs).await?; answered = true; } } @@ -337,7 +372,8 @@ impl Driver { /// Waits for the next answer, then answers every effect already /// landed behind it, or acts on a cancel or a stop as soon as one is - /// raised, or delivers what the Host sent. + /// raised, or delivers what the Host sent, or reports a tool call's + /// file request to the run. /// /// Before a delivery, a stop raised before the messages were sent is /// handled, so a Host that stops and then sends gets the stop, and @@ -355,6 +391,10 @@ impl Driver { self.answer_landed().await?; self.deliver(texts).await } + Woken::Asked(call) => { + self.report_request(call); + Ok(()) + } Woken::Landed(id, provenance, answer) => { self.answer(id, &provenance, answer).await?; self.answer_landed().await @@ -362,6 +402,59 @@ impl Driver { } } + /// Reports the oldest file request of tool call `call` to the run, + /// which issues it as a Vfs effect at the next step. A call that has + /// landed or was aborted has no desk, and a request whose future was + /// dropped has left its desk, so neither is reported. + fn report_request(&mut self, call: EffectId) { + let Some(op) = self.flights.desk(call).and_then(|desk| desk.next_request()) else { + return; + }; + self.run.request_file(call, op); + } + + /// Answers one Vfs effect inline: performs the operation through the + /// effect's access, records the answer, and resumes the run with it. + /// + /// A tool call that asked gets the whole outcome at its desk, which + /// wakes it, once the run has the outcome's receipt. When that call + /// has landed or was aborted since it asked, the effect is answered + /// `Dropped` unperformed. Any other asker is the prompt's Lua, whose + /// `store` call takes the whole outcome as the answer. + /// + /// The access is this function's own, so it drops when the function + /// returns, and the Harness holds no way to a store between effects. + /// The drop is hygiene only: claims follow happens-before within the + /// run's scope, and the run ends that scope at `Done` however long + /// any access is held. + async fn answer_vfs( + &mut self, + id: EffectId, + provenance: &Provenance, + vfs: InlineVfs, + ) -> Result<(), Error> { + let InlineVfs { asker, access, op } = vfs; + // `VfsAsker` is `#[non_exhaustive]`. An asker the Engine adds + // takes the whole outcome here until this loop names it, and the + // run ends with an internal error should that be the wrong form. + let VfsAsker::Tool { call } = asker else { + let answer = EffectAnswer::Vfs(perform_vfs_op(&access, &op)); + return self.answer(id, provenance, answer).await; + }; + let Some(desk) = self.flights.desk(call).cloned() else { + return self.drop_effect(id, provenance).await; + }; + let outcome = perform_contained(&access, &op); + let receipt = match &outcome { + Ok(outcome) => Ok(VfsReceipt::of(outcome)), + Err(error) => Err(error.clone()), + }; + self.answer(id, provenance, EffectAnswer::VfsReceipt(receipt)) + .await?; + desk.deliver(outcome); + Ok(()) + } + /// Acts on a raised stop: drops whatever is in flight but the tool /// calls that survive stops, which may be nothing, then lowers the /// stop. Returns whether it answered any effect, since each answer @@ -373,16 +466,19 @@ impl Driver { Ok(self.flights.len() < owed) } - /// Waits for the cancel flag, a raised stop, a sent message, or the - /// next effect to land, checked in that order, so a stop drops a round - /// whose answer or message arrived beside it. Every arm is - /// event-driven: the cancel, the stop, and a send wake the loop as they - /// are raised and a future wakes it as it lands, so a fully suspended - /// run costs no wakeups while it waits. + /// Waits for the cancel flag, a raised stop, a sent message, a tool + /// call's file request, or the next effect to land, checked in that + /// order, so a stop drops a round whose answer or message arrived + /// beside it. The requests are checked a second time once the effects + /// in flight are polled, because a tool call asks while it is polled. + /// Every arm is event-driven: the cancel, the stop, a send, and a + /// request wake the loop as they are raised and a future wakes it as + /// it lands, so a fully suspended run costs no wakeups while it waits. async fn wake(&mut self) -> Woken { let mut canceled = self.cancel.canceled(); let stop = &self.stop; let sends = &self.sends; + let asked = &self.asked; let flights = &mut self.flights; poll_fn(|cx| { if Pin::new(&mut canceled).poll(cx).is_ready() { @@ -394,9 +490,13 @@ impl Driver { if let Poll::Ready(texts) = sends.poll_sent(cx) { return Poll::Ready(Woken::Sent(texts)); } - flights - .poll_landed(cx) - .map(|(id, provenance, answer)| Woken::Landed(id, provenance, answer)) + if let Poll::Ready(call) = asked.poll_next(cx) { + return Poll::Ready(Woken::Asked(call)); + } + if let Poll::Ready((id, provenance, answer)) = flights.poll_landed(cx) { + return Poll::Ready(Woken::Landed(id, provenance, answer)); + } + asked.poll_next(cx).map(Woken::Asked) }) .await } @@ -442,15 +542,17 @@ impl Driver { /// flight, where a tool call may wait for a slot, and returns `None`. /// The performer is called inside its future, so a performer that /// panics as it is called is caught like one that panics as it runs. + /// A tool call gets a desk of its own, through which its tool asks + /// for file operations while the call is in flight. /// - /// A Vfs effect goes nowhere and is handed back as the access and - /// operation it carries, for the caller to answer inline. + /// A Vfs effect goes nowhere and is handed back as it is, for the + /// caller to answer inline. fn perform( &mut self, id: EffectId, provenance: &Provenance, effect: Effect, - ) -> Option<(Arc, VfsOp)> { + ) -> Option { let (kind, answer): (Kind, BoxFuture<'static, EffectAnswer>) = match effect { Effect::Chat { binding, @@ -488,21 +590,19 @@ impl Driver { survives_stop, } => { let performer = Arc::clone(&self.tool); + let desk = CallDesk::open(id, &self.asked); + let files: Arc = Arc::clone(&desk) as _; let call = async move { - EffectAnswer::ToolCall(performer.call(tool, alias, access, origin, args).await) + let output = performer + .call(tool, alias, access, origin, args, files) + .await; + EffectAnswer::ToolCall(output) }; self.flights - .queue(id, provenance.clone(), survives_stop, Box::pin(call)); + .queue(id, provenance.clone(), survives_stop, desk, Box::pin(call)); return None; } - // The effect's record, written before this call, names who - // asked. The loop reports no request of a tool to the run, so - // the prompt's Lua asked, and the view reaches its store alone. - Effect::Vfs { - asker: _, - access, - op, - } => return Some((access, op)), + Effect::Vfs { asker, access, op } => return Some(InlineVfs { asker, access, op }), Effect::Timer { duration } => { let timer = Arc::clone(&self.timer); let sleep = async move { @@ -630,12 +730,17 @@ struct InFlight { /// Whether the effect is a tool call that survives stops, which a /// stop leaves alone. survives_stop: bool, + /// The desk of a tool call, through which its tool asks for file + /// operations. It goes when the call lands or is aborted. + desk: Option>, } -/// A tool call waiting for a slot: its performer future, not yet polled. +/// A tool call waiting for a slot: its performer future, not yet polled, +/// and its desk. struct Waiting { provenance: Provenance, survives_stop: bool, + desk: Arc, answer: BoxFuture<'static, EffectAnswer>, } @@ -696,18 +801,19 @@ impl Flights { kind: Kind, answer: BoxFuture<'static, EffectAnswer>, ) { - self.launch(id, provenance, kind, false, answer); + self.launch(id, provenance, kind, false, None, answer); } /// Queues `answer`, the performer future of tool call `id`, under /// `provenance`, then starts waiting calls, lowest id first, while /// fewer than `cap` tool calls are in flight. `survives_stop` marks a - /// call that survives stops. + /// call that survives stops, and `desk` is the call's desk. fn queue( &mut self, id: EffectId, provenance: Provenance, survives_stop: bool, + desk: Arc, answer: BoxFuture<'static, EffectAnswer>, ) { self.waiting.insert( @@ -715,12 +821,19 @@ impl Flights { Waiting { provenance, survives_stop, + desk, answer, }, ); self.fill(); } + /// The desk of tool call `call`, while the call is in flight. A call + /// that waits for a slot has not started, so it has asked for nothing. + fn desk(&self, call: EffectId) -> Option<&Arc> { + self.effects.get(&call)?.desk.as_ref() + } + /// Starts waiting calls, lowest id first, while fewer than `cap` tool /// calls are in flight. fn fill(&mut self) { @@ -738,6 +851,7 @@ impl Flights { call.provenance, Kind::ToolCall, call.survives_stop, + Some(call.desk), call.answer, ); running += 1; @@ -748,13 +862,14 @@ impl Flights { /// `provenance` as `kind`, inside a span that records the effect id, /// the task path, and the task-local sequence, so a run's effects /// trace as a group. `survives_stop` marks a tool call that survives - /// stops. + /// stops, and `desk` is a tool call's desk. fn launch( &mut self, id: EffectId, provenance: Provenance, kind: Kind, survives_stop: bool, + desk: Option>, answer: BoxFuture<'static, EffectAnswer>, ) { let span = tracing::info_span!( @@ -774,6 +889,7 @@ impl Flights { abort, kind, survives_stop, + desk, }, ); } @@ -863,21 +979,17 @@ impl Flights { } } -/// Answers one Vfs effect inline: performs `op` on the effect's store -/// through the view the effect carries and returns the answer to record -/// and resume the run with. -/// -/// The view is this function's own parameter, so it drops when the -/// function returns, and the Harness holds no way to a store between -/// effects. The drop is hygiene only: claims follow happens-before within -/// the run's scope, and the run ends that scope at `Done` however long any -/// access is held. -#[expect( - clippy::needless_pass_by_value, - reason = "the view is taken by value so that it drops with the operation" -)] -fn answer_vfs(access: Arc, op: VfsOp) -> EffectAnswer { - EffectAnswer::Vfs(perform_vfs_op(&access, &op)) +/// Performs `op`, an operation a tool call asked for, on `access`, and +/// turns a panic inside it into a backend failure. The policy and the +/// backends behind the access of a tool call are the Host's own code, and +/// a panic there must reach the tool as a failed operation, where it +/// would otherwise unwind through the run's future. +fn perform_contained(access: &Access, op: &VfsOp) -> Result { + std::panic::catch_unwind(AssertUnwindSafe(|| access.perform(op))).unwrap_or_else(|_| { + Err(VfsError::Backend { + message: "the file operation panicked".to_owned(), + }) + }) } /// A panic payload's message, when it carries one. diff --git a/crates/harness-internal/runner/src/lib.rs b/crates/harness-internal/runner/src/lib.rs index c59579dd9..fbc1c798c 100644 --- a/crates/harness-internal/runner/src/lib.rs +++ b/crates/harness-internal/runner/src/lib.rs @@ -44,6 +44,12 @@ //! of a Vfs effect, through that effect's view. It puts nothing in a //! store before a run and reads nothing from one after: a run takes its //! input as arguments and hands back its result. +//! - A tool call asks for a file operation through the files of its +//! context. The Harness reports each request to the run, performs the +//! Vfs effect the run issues for it on the run's filesystem, records +//! it, and hands the outcome to the call, so the record holds every +//! operation a tool asks for this way. It drops the request of a call +//! that has landed or was aborted. //! - The recorder is written in loop order: a step's events before the //! step's effects are issued, each effect before its performer starts, //! each answer before the run resumes with it, and each sent message's @@ -92,6 +98,7 @@ mod prompt_finders; pub mod recorder; mod recorder_memory; mod setup; +mod tool_files; pub use display_chain::display_chain; pub use harness::{Harness, RunControl, RunReport}; diff --git a/crates/harness-internal/runner/src/packs-tests.rs b/crates/harness-internal/runner/src/packs-tests.rs index 33ed1bd93..272bab488 100644 --- a/crates/harness-internal/runner/src/packs-tests.rs +++ b/crates/harness-internal/runner/src/packs-tests.rs @@ -18,12 +18,12 @@ use runvil_engine::cancel::CancelHandle; use runvil_engine::effect::{ToolCallOrigin, ToolCaller}; use runvil_engine::make_tool_error; use runvil_engine::packs::RosterEntry; -use runvil_engine::vfs::{Origin, VfsRef}; +use runvil_engine::vfs::{Origin, VfsError, VfsOp, VfsOutcome, VfsRef}; use runvil_engine::{Error, ErrorCode}; use runvil_engine::{Prompt, Run, RunParams, RunSeed, Step, Timestamp}; use runvil_plugin::{ BoxFuture, HostServices, Pack, PackFactory, PackId, PackInfo, PackRegistry, ServiceKey, - ToolContext, ToolId, ToolInfo, ToolOutput, + ToolContext, ToolFiles, ToolId, ToolInfo, ToolOutput, }; use serde_json::{Value, json}; @@ -683,8 +683,75 @@ fn preludes_follow_the_prompts_declaration_order_and_carry_the_pack_id() { assert_eq!(order, ["third", "second", "first"]); } -/// Calls `tool` through `run` from a script and returns its result. +/// The files of a call whose tool asks for no file operation. +struct NoFiles; + +impl ToolFiles for NoFiles { + fn request(&self, op: VfsOp) -> BoxFuture<'_, Result> { + unreachable!("no tool of this call asks for a file operation: {op:?}") + } +} + +/// Files that note each operation asked of them and answer it at once +/// with `true`. +#[derive(Default)] +struct NotedFiles { + asked: Mutex>, +} + +impl ToolFiles for NotedFiles { + fn request(&self, op: VfsOp) -> BoxFuture<'_, Result> { + self.asked.lock().unwrap().push(op); + Box::pin(async { Ok(VfsOutcome::Bool(true)) }) + } +} + +/// Asks its call's files whether `/probe` exists and answers with what +/// they said. +struct Asks; + +impl Pack for Asks { + fn tools(&self) -> Vec { + vec![listed_tool("asks/probe")] + } + + fn call<'a>( + &'a self, + cx: ToolContext<'a>, + _args: Value, + ) -> BoxFuture<'a, Result> { + Box::pin(async move { + let probe = VfsOp::Exists { + path: "/probe".to_owned(), + }; + let outcome = cx.files().request(probe).await; + Ok(ToolOutput::trusted(format!("{outcome:?}"))) + }) + } +} + +/// Makes an [`Asks`]. +#[expect( + clippy::unnecessary_wraps, + reason = "the Make signature fixes the return type" +)] +fn asks(_name: &PackId, _config: &Value, _wide: &HostServices) -> Result, Error> { + Ok(Arc::new(Asks)) +} + +/// Calls `tool` through `run` from a script, lending the call no files +/// to ask, and returns its result. async fn call(run: &dyn ToolPerformer, tool: &str) -> Result { + call_with(run, tool, Arc::new(NoFiles)).await +} + +/// Calls `tool` through `run` from a script, lending the call `files`, +/// and returns its result. +async fn call_with( + run: &dyn ToolPerformer, + tool: &str, + files: Arc, +) -> Result { let access = VfsRef::default().acquire(Origin::new("host test")).unwrap(); let origin = ToolCallOrigin::new("Only", ToolCaller::Script); let tool = ToolId::parse(tool).unwrap(); @@ -694,10 +761,38 @@ async fn call(run: &dyn ToolPerformer, tool: &str) -> Result Arc::new(access), origin, json!({}), + files, ) .await } +#[tokio::test] +async fn a_call_is_lent_the_files_the_caller_gave_for_it() { + let host = host_with( + &HostServices::new(), + &[(info("runvil/asks"), asks, Value::Null)], + ); + let run = begin(&host, BTreeMap::new(), &prompt("")); + let files = Arc::new(NotedFiles::default()); + + let output = call_with(&run, "asks/probe", Arc::clone(&files) as _) + .await + .expect("the call answers"); + + assert_eq!( + output.text(), + "Ok(Bool(true))", + "the tool got the files' answer" + ); + assert_eq!( + *files.asked.lock().unwrap(), + [VfsOp::Exists { + path: "/probe".to_owned(), + }], + "the tool's request reached the files of its own call" + ); +} + #[tokio::test] async fn a_call_goes_to_the_pack_its_tool_ids_first_segment_names() { let host = host(&[ diff --git a/crates/harness-internal/runner/src/packs.rs b/crates/harness-internal/runner/src/packs.rs index 94abd891d..5b7b3789b 100644 --- a/crates/harness-internal/runner/src/packs.rs +++ b/crates/harness-internal/runner/src/packs.rs @@ -55,7 +55,7 @@ use runvil_engine::vfs::Access; use runvil_engine::{BoxFuture, Error, ErrorCode}; use runvil_engine::{ToolCatalog, ToolId, ToolInfo, ToolOutput, make_tool_error}; use runvil_plugin::{ - Pack, PackFactory, PackId, PackInfo, PackRegistry, RenderContext, ToolContext, + Pack, PackFactory, PackId, PackInfo, PackRegistry, RenderContext, ToolContext, ToolFiles, }; use serde_json::Value; @@ -570,6 +570,7 @@ impl ToolPerformer for RunPacks { access: Arc, origin: ToolCallOrigin, args: Value, + files: Arc, ) -> BoxFuture<'static, Result> { let pack = self.usable(&tool.pack()).cloned(); Box::pin(async move { @@ -584,7 +585,7 @@ impl ToolPerformer for RunPacks { format!("tool `{alias}` ({tool}) belongs to no usable Pack of this run"), )); }; - let cx = ToolContext::new(&tool, &access, &origin); + let cx = ToolContext::new(&tool, &access, &origin, files.as_ref()); pack.call(cx, args).await }) } diff --git a/crates/harness-internal/runner/src/performers.rs b/crates/harness-internal/runner/src/performers.rs index 67af7a7cc..30a9d2704 100644 --- a/crates/harness-internal/runner/src/performers.rs +++ b/crates/harness-internal/runner/src/performers.rs @@ -17,9 +17,10 @@ //! block while polled: one that blocks stalls every other effect of the //! run, and the run's stop and cancel with them. A performer with blocking //! or CPU-heavy work hands it to the Host's own runtime and awaits the -//! result. A `Vfs` effect has no performer: it is one operation on a -//! store of the run, and file operations are synchronous by design, so -//! the loop answers it inline through the Engine's store operation. +//! result. A `Vfs` effect has no performer: it is one file operation, on +//! a store of the run or, for a tool call that asked through its files, +//! on the run's filesystem, and file operations are synchronous by +//! design, so the loop answers it inline. //! //! The runner supplies the tool performer itself: the run's snapshot of //! the Host's Packs, taken at preparation. The Host supplies the @@ -35,6 +36,7 @@ use runvil_engine::model::{ use runvil_engine::vfs::Access; use runvil_engine::{BoxFuture, Error, Timestamp}; use runvil_engine::{ToolId, ToolInfo, ToolOutput}; +use runvil_plugin::ToolFiles; use serde_json::Value; /// The model inference the Host supplies to the Harness. @@ -73,8 +75,9 @@ pub trait InferenceBroker: Send + Sync { } /// Performs a `ToolCall` effect: resolves `tool` to an implementation and -/// calls it with `args`, lending it the call's `access` and `origin`. Also -/// performs a `Render` effect: the tools each offered Pack shows the model. +/// calls it with `args`, lending it the call's `access`, `origin`, and +/// `files`. Also performs a `Render` effect: the tools each offered Pack +/// shows the model. /// /// Each method returns a [`BoxFuture`] for the Harness to poll. The future /// is `Send` and `'static`. It can move between threads, and it owns the @@ -84,8 +87,11 @@ pub trait ToolPerformer: Send + Sync { /// its canonical id for a script call, for the performer's own /// diagnostics; `tool` is the identity it resolves. `access` is the /// call's own filesystem access and `origin` says who made the call. - /// The returned future owns both until it finishes, and drops them - /// when it finishes or is dropped. + /// `files` is the call's desk at the effect loop: the tool asks it for + /// each file operation, and the loop performs and records the + /// operation and resolves the request. The returned future owns all + /// three until it finishes, and drops them when it finishes or is + /// dropped. fn call( &self, tool: ToolId, @@ -93,6 +99,7 @@ pub trait ToolPerformer: Send + Sync { access: Arc, origin: ToolCallOrigin, args: Value, + files: Arc, ) -> BoxFuture<'static, Result>; /// Renders the tools the section entry `entry` offered from each Pack diff --git a/crates/harness-internal/runner/src/tool_files-tests.rs b/crates/harness-internal/runner/src/tool_files-tests.rs new file mode 100644 index 000000000..fdcd4addb --- /dev/null +++ b/crates/harness-internal/runner/src/tool_files-tests.rs @@ -0,0 +1,212 @@ +//! Tests for a tool call's desk: a request goes out at its future's first +//! poll and announces its call, an outcome wakes and resolves the oldest +//! request the loop took, a dropped future's request is never reported +//! or has its outcome discarded, and the run's queue wakes the loop. + +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::task::Wake; + +use runvil_engine::{Prompt, Run, RunParams, RunSeed, Step, Timestamp}; + +use super::*; + +/// Counts the times it is woken. +#[derive(Default)] +struct Woken(AtomicUsize); + +impl Wake for Woken { + fn wake(self: Arc) { + self.0.fetch_add(1, Ordering::SeqCst); + } +} + +impl Woken { + fn count(&self) -> usize { + self.0.load(Ordering::SeqCst) + } +} + +/// A waker that counts on `woken`. +fn waker_of(woken: &Arc) -> Waker { + Waker::from(Arc::clone(woken)) +} + +/// An effect id to open a desk under. Only a run makes an `EffectId`, so +/// this is the id of the one effect a small run issues. +fn call_id() -> EffectId { + let source = "---\nname: t\ndescription: d\nrunvil: 0\n---\n\n\ + ## Only\n\n```lua\nreturn store.exists('x')\n```\n"; + let prompt = Prompt::parse(&|_: &str| Ok(source.to_owned()), "prompt") + .expect("the fixture prompt parses"); + let params = RunParams::new(RunSeed::from_bytes([7; 32]), Timestamp::UNIX_EPOCH); + let mut run = Run::new(Arc::new(prompt), "{}", params); + let Step::Pending { effects, .. } = run.step() else { + panic!("the fixture run issues one effect"); + }; + let [issued] = effects.as_slice() else { + panic!("the fixture run issues one effect: {effects:?}"); + }; + issued.id +} + +/// A write of `text` to `path`. +fn write(path: &str, text: &str) -> VfsOp { + VfsOp::Write { + path: path.to_owned(), + contents: text.as_bytes().to_vec(), + } +} + +/// Polls `request` once with a waker that counts on `woken`. +fn poll( + request: &mut BoxFuture<'_, Result>, + woken: &Arc, +) -> Poll> { + request + .as_mut() + .poll(&mut Context::from_waker(&waker_of(woken))) +} + +/// Whether the run's queue holds a call now. +fn announced(asked: &Asked) -> Option { + match asked.poll_next(&mut Context::from_waker(Waker::noop())) { + Poll::Ready(call) => Some(call), + Poll::Pending => None, + } +} + +#[test] +fn a_request_goes_out_at_its_first_poll_and_resolves_with_the_outcome_the_loop_delivers() { + let asked = Arc::new(Asked::default()); + let call = call_id(); + let desk = CallDesk::open(call, &asked); + let woken = Arc::new(Woken::default()); + + let mut request = desk.request(write("/a.md", "a")); + assert!( + desk.next_request().is_none(), + "an unpolled request is not out" + ); + assert_eq!(announced(&asked), None); + + assert!(poll(&mut request, &woken).is_pending()); + assert_eq!(announced(&asked), Some(call), "the call is announced once"); + assert_eq!(announced(&asked), None); + assert_eq!(desk.next_request(), Some(write("/a.md", "a"))); + assert!(desk.next_request().is_none()); + assert!(poll(&mut request, &woken).is_pending(), "no outcome yet"); + assert_eq!(woken.count(), 0); + + desk.deliver(Ok(VfsOutcome::Unit)); + assert_eq!(woken.count(), 1, "the outcome wakes the request's future"); + assert_eq!( + poll(&mut request, &woken), + Poll::Ready(Ok(VfsOutcome::Unit)) + ); + assert!( + matches!( + poll(&mut request, &woken), + Poll::Ready(Err(VfsError::Backend { .. })) + ), + "a resolved request has no second outcome" + ); +} + +#[test] +fn the_requests_of_one_call_resolve_in_the_order_they_went_out() { + let asked = Arc::new(Asked::default()); + let call = call_id(); + let desk = CallDesk::open(call, &asked); + let woken = Arc::new(Woken::default()); + let mut first = desk.request(write("/first.md", "1")); + let mut second = desk.request(write("/second.md", "2")); + // The second future is polled first, so its request is the older. + assert!(poll(&mut second, &woken).is_pending()); + assert!(poll(&mut first, &woken).is_pending()); + assert_eq!(announced(&asked), Some(call)); + assert_eq!(announced(&asked), Some(call), "one entry for each request"); + + assert_eq!(desk.next_request(), Some(write("/second.md", "2"))); + assert_eq!(desk.next_request(), Some(write("/first.md", "1"))); + let missing = VfsError::NotFound { + path: "/second.md".to_owned(), + }; + desk.deliver(Err(missing.clone())); + assert!(poll(&mut first, &woken).is_pending(), "its outcome is next"); + assert_eq!(poll(&mut second, &woken), Poll::Ready(Err(missing))); + desk.deliver(Ok(VfsOutcome::Bool(true))); + assert_eq!( + poll(&mut first, &woken), + Poll::Ready(Ok(VfsOutcome::Bool(true))) + ); +} + +#[test] +fn a_request_whose_future_is_dropped_before_the_loop_takes_it_is_never_reported() { + let asked = Arc::new(Asked::default()); + let call = call_id(); + let desk = CallDesk::open(call, &asked); + let woken = Arc::new(Woken::default()); + let mut dropped = desk.request(write("/dropped.md", "x")); + let mut kept = desk.request(write("/kept.md", "y")); + assert!(poll(&mut dropped, &woken).is_pending()); + assert!(poll(&mut kept, &woken).is_pending()); + drop(dropped); + + // The run's queue still holds the dropped request's entry, and the + // desk hands the loop the request that is left. + assert_eq!(announced(&asked), Some(call)); + assert_eq!(desk.next_request(), Some(write("/kept.md", "y"))); + assert_eq!(announced(&asked), Some(call)); + assert!(desk.next_request().is_none(), "the dropped request is gone"); + desk.deliver(Ok(VfsOutcome::Unit)); + assert_eq!(poll(&mut kept, &woken), Poll::Ready(Ok(VfsOutcome::Unit))); +} + +#[test] +fn the_outcome_of_a_request_whose_future_is_dropped_after_the_loop_took_it_is_discarded() { + let asked = Arc::new(Asked::default()); + let desk = CallDesk::open(call_id(), &asked); + let woken = Arc::new(Woken::default()); + let mut dropped = desk.request(write("/dropped.md", "x")); + let mut kept = desk.request(write("/kept.md", "y")); + assert!(poll(&mut dropped, &woken).is_pending()); + assert!(poll(&mut kept, &woken).is_pending()); + assert_eq!(desk.next_request(), Some(write("/dropped.md", "x"))); + assert_eq!(desk.next_request(), Some(write("/kept.md", "y"))); + drop(dropped); + + // The operation still happened. Its outcome reaches no one, and the + // next outcome is the kept request's. + desk.deliver(Ok(VfsOutcome::Bool(false))); + assert_eq!(woken.count(), 0, "no future waits on the first outcome"); + assert!(poll(&mut kept, &woken).is_pending()); + desk.deliver(Ok(VfsOutcome::Unit)); + assert_eq!(woken.count(), 1); + assert_eq!(poll(&mut kept, &woken), Poll::Ready(Ok(VfsOutcome::Unit))); + desk.deliver(Ok(VfsOutcome::Unit)); + assert_eq!( + woken.count(), + 1, + "an outcome no request is owed wakes no one" + ); +} + +#[test] +fn a_request_wakes_a_loop_that_waits_on_the_empty_queue() { + let asked = Arc::new(Asked::default()); + let call = call_id(); + let desk = CallDesk::open(call, &asked); + let loop_woken = Arc::new(Woken::default()); + assert!( + asked + .poll_next(&mut Context::from_waker(&waker_of(&loop_woken))) + .is_pending() + ); + + let mut request = desk.request(write("/a.md", "a")); + assert_eq!(loop_woken.count(), 0, "an unpolled request wakes no one"); + assert!(poll(&mut request, &Arc::new(Woken::default())).is_pending()); + assert_eq!(loop_woken.count(), 1); + assert_eq!(announced(&asked), Some(call)); +} diff --git a/crates/harness-internal/runner/src/tool_files.rs b/crates/harness-internal/runner/src/tool_files.rs new file mode 100644 index 000000000..72437e872 --- /dev/null +++ b/crates/harness-internal/runner/src/tool_files.rs @@ -0,0 +1,255 @@ +//! A tool call's files at the effect loop: the desk through which one +//! call asks for file operations, and the run-wide queue of the calls +//! that asked. +//! +//! Each tool call gets a [`CallDesk`], which is the `ToolFiles` of the +//! call's `ToolContext`. A request joins the desk when its future is +//! first polled, and the call's id joins the run's [`Asked`] queue, which +//! wakes the effect loop. The loop takes the call's oldest request off +//! the desk and reports it to the run, and the run issues it as a `Vfs` +//! effect whose asker is the call. The loop performs that effect inline, +//! records its answer, and hands the whole outcome to the desk, which +//! wakes the request's future. The run issues the effects of one call in +//! the order the loop reported its requests, so the desk matches each +//! outcome to the oldest request it sent. +//! +//! A request whose future is dropped before the loop takes it is never +//! reported. One dropped later stays reported, so the loop still performs +//! it while its call is in flight, and the desk discards its outcome. A +//! desk lives as long as its call is in flight: the loop drops what a +//! call that has landed or was aborted still asks for. + +use std::collections::{HashMap, VecDeque}; +use std::future::Future; +use std::pin::Pin; +use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; +use std::task::{Context, Poll, Waker}; + +use runvil_engine::BoxFuture; +use runvil_engine::effect::EffectId; +use runvil_engine::vfs::{VfsError, VfsOp, VfsOutcome}; +use runvil_plugin::ToolFiles; + +/// The run-wide queue of the tool calls that asked for a file operation: +/// one entry for each request, oldest first. +#[derive(Default)] +pub(crate) struct Asked { + queue: Mutex, +} + +/// The calls that asked, and the effect loop's waker. +#[derive(Default)] +struct AskedQueue { + /// The id of the call behind each request the loop has not taken. + calls: VecDeque, + /// The loop's waker, kept from the last poll that found no call. + waker: Option, +} + +impl Asked { + /// Adds `call`, which made one more request, and wakes the loop. + fn push(&self, call: EffectId) { + let waker = { + let mut queue = lock(&self.queue); + queue.calls.push_back(call); + queue.waker.take() + }; + if let Some(waker) = waker { + waker.wake(); + } + } + + /// Polls for the call behind the oldest request the loop has not + /// taken. An empty queue keeps `cx`'s waker for the next request. + pub(crate) fn poll_next(&self, cx: &mut Context<'_>) -> Poll { + let mut queue = lock(&self.queue); + if let Some(call) = queue.calls.pop_front() { + return Poll::Ready(call); + } + queue.waker = Some(cx.waker().clone()); + Poll::Pending + } +} + +/// One tool call's desk: the requests the call made, from the first poll +/// of each one's future until that future takes its outcome or is +/// dropped. +pub(crate) struct CallDesk { + /// The id of the call's `ToolCall` effect. + call: EffectId, + /// The run's queue of the calls that asked. + asked: Arc, + requests: Mutex, +} + +/// The requests of one desk. +#[derive(Default)] +struct Requests { + /// The ticket the next request takes. + next: u64, + /// The requests the loop has not taken, oldest first. + queued: VecDeque<(u64, VfsOp)>, + /// The requests the loop reported to the run, oldest first, each + /// owed an outcome. + sent: VecDeque, + /// Each request a future still waits on: its waker until its outcome + /// arrives, then the outcome. + waiting: HashMap, +} + +/// What a request's future waits with. +enum Waiting { + /// The waker of the future's last poll. + For(Waker), + /// The outcome, which the future's next poll takes. + Answered(Result), +} + +impl CallDesk { + /// Opens the desk of tool call `call`, whose requests are announced + /// on `asked`. + pub(crate) fn open(call: EffectId, asked: &Arc) -> Arc { + Arc::new(CallDesk { + call, + asked: Arc::clone(asked), + requests: Mutex::default(), + }) + } + + /// Takes the call's oldest request for the loop to report to the run, + /// and notes that it is owed an outcome. `None` when every request + /// was taken or dropped. + pub(crate) fn next_request(&self) -> Option { + let mut requests = lock(&self.requests); + let (ticket, op) = requests.queued.pop_front()?; + requests.sent.push_back(ticket); + Some(op) + } + + /// Hands `outcome` to the oldest request the loop reported, and wakes + /// the future that waits on it. The outcome of a request whose future + /// was dropped is discarded. + pub(crate) fn deliver(&self, outcome: Result) { + let waker = { + let mut requests = lock(&self.requests); + let Some(ticket) = requests.sent.pop_front() else { + return; + }; + let Some(waiting) = requests.waiting.get_mut(&ticket) else { + return; + }; + match std::mem::replace(waiting, Waiting::Answered(outcome)) { + Waiting::For(waker) => Some(waker), + Waiting::Answered(_) => None, + } + }; + if let Some(waker) = waker { + waker.wake(); + } + } + + /// Queues `op` as a new request, with `waker` to wake at its outcome, + /// announces the call on the run's queue, and returns the request's + /// ticket. + fn ask(&self, op: VfsOp, waker: &Waker) -> u64 { + let ticket = { + let mut requests = lock(&self.requests); + let ticket = requests.next; + requests.next += 1; + requests.queued.push_back((ticket, op)); + requests.waiting.insert(ticket, Waiting::For(waker.clone())); + ticket + }; + self.asked.push(self.call); + ticket + } + + /// Takes the outcome of request `ticket`, or keeps `waker` to wake at + /// its arrival. + fn take(&self, ticket: u64, waker: &Waker) -> Option> { + let mut requests = lock(&self.requests); + match requests.waiting.remove(&ticket)? { + Waiting::Answered(outcome) => Some(outcome), + Waiting::For(_) => { + requests.waiting.insert(ticket, Waiting::For(waker.clone())); + None + } + } + } + + /// Forgets request `ticket`, whose future was dropped: a request the + /// loop has not taken leaves the queue, and the outcome of one it has + /// taken has no one to reach. + fn forget(&self, ticket: u64) { + let mut requests = lock(&self.requests); + requests.queued.retain(|(queued, _)| *queued != ticket); + requests.waiting.remove(&ticket); + } +} + +impl ToolFiles for CallDesk { + fn request(&self, op: VfsOp) -> BoxFuture<'_, Result> { + Box::pin(Request { + desk: self, + stage: Stage::Unsent(op), + }) + } +} + +/// One request's future. +struct Request<'a> { + desk: &'a CallDesk, + stage: Stage, +} + +/// How far one request has come. +enum Stage { + /// Not polled yet: the operation to ask for. + Unsent(VfsOp), + /// At the desk under this ticket. + Asked(u64), + /// Resolved. + Done, +} + +impl Future for Request<'_> { + type Output = Result; + + fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { + let request = self.get_mut(); + match std::mem::replace(&mut request.stage, Stage::Done) { + Stage::Unsent(op) => { + request.stage = Stage::Asked(request.desk.ask(op, cx.waker())); + Poll::Pending + } + Stage::Asked(ticket) => { + if let Some(outcome) = request.desk.take(ticket, cx.waker()) { + return Poll::Ready(outcome); + } + request.stage = Stage::Asked(ticket); + Poll::Pending + } + Stage::Done => Poll::Ready(Err(VfsError::Backend { + message: "a file request was polled after it resolved".to_owned(), + })), + } + } +} + +impl Drop for Request<'_> { + fn drop(&mut self) { + if let Stage::Asked(ticket) = self.stage { + self.desk.forget(ticket); + } + } +} + +/// Poison-safe lock: a panic in a tool leaves the queues as they were, +/// and the loop still drains them. +fn lock(mutex: &Mutex) -> MutexGuard<'_, T> { + mutex.lock().unwrap_or_else(PoisonError::into_inner) +} + +#[cfg(test)] +#[path = "tool_files-tests.rs"] +mod tests; diff --git a/crates/harness-internal/runner/tests/it/effect_loop-cap.rs b/crates/harness-internal/runner/tests/it/effect_loop-cap.rs index 4f3fed561..8e3247049 100644 --- a/crates/harness-internal/runner/tests/it/effect_loop-cap.rs +++ b/crates/harness-internal/runner/tests/it/effect_loop-cap.rs @@ -23,6 +23,7 @@ use runvil_engine::model::{ use runvil_engine::vfs::Access; use runvil_engine::{BoxFuture, Prompt, Run, RunParams, Timestamp}; use runvil_engine::{ToolCatalog, ToolId, ToolInfo, ToolOutput}; +use runvil_plugin::ToolFiles; use serde_json::{Value, json}; use tokio::sync::{Notify, Semaphore}; @@ -134,6 +135,7 @@ impl ToolPerformer for ParkingTool { _access: Arc, _origin: ToolCallOrigin, args: Value, + _files: Arc, ) -> BoxFuture<'static, Result> { let name = args["name"].as_str().unwrap_or_default().to_owned(); let gate = Arc::clone(&self.gate); diff --git a/crates/harness-internal/runner/tests/it/harness-files.rs b/crates/harness-internal/runner/tests/it/harness-files.rs new file mode 100644 index 000000000..c57da702c --- /dev/null +++ b/crates/harness-internal/runner/tests/it/harness-files.rs @@ -0,0 +1,618 @@ +//! A tool call's file operations under `Harness::run`: a Rust Pack reads +//! and writes through its call's files, and each operation is a `Vfs` +//! effect that names the call, recorded with its receipt between the +//! call's effect and its answer; an operation that fails, or whose +//! policy panics, reaches the tool and the record as the failure and the +//! run goes on; two calls in flight at once each get the outcomes of +//! their own requests; and a stop or a cancel raised while a call's +//! requests are pending drops the call. A request whose effect went out +//! before the loop saw the stop or the cancel is performed and recorded, +//! the effect of a request the loop reported as it was raised is +//! answered `Dropped` unperformed, and a request the loop had not taken +//! is never issued. + +use std::sync::Arc; + +use harness_runner::recorder::{MemoryRecorder, Record, RecordKind}; +use harness_runner::{Packs, RunControl, RunSetup}; +use runvil_engine::Error; +use runvil_engine::vfs::{MemoryBackend, Op, Origin, Policy, Verdict, VfsPath, VfsRef}; +use runvil_plugin::{ + BoxFuture, Pack, PackFactory, PackId, PackInfo, ToolContext, ToolFiles, ToolId, ToolInfo, + ToolOutput, VfsOp, VfsOutcome, +}; +use serde_json::{Value, json}; + +use super::{PATIENCE, PendingTimer, hooked_recorder, launch, setup}; +use crate::scripted::ScriptedBroker; +use crate::support::{assert_canceled, registry}; + +/// The fixture Pack `files`: `files/copy` reads one file through its +/// call's files and writes what it read to another, and `files/pair` +/// runs the hook its factory was given and then asks for two writes at +/// once. +const FILES_PACK: PackInfo = PackInfo::new("tests/files"); + +/// What `files/pair` runs as it starts, before it asks for anything. +type OnPair = Arc; + +struct FilesPack { + tools: Vec, + on_pair: OnPair, +} + +/// The fixture Pack's factory, whose `files/pair` runs `on_pair` as it +/// starts. +fn files_pack(on_pair: impl Fn() + Send + Sync + 'static) -> impl PackFactory { + let on_pair: OnPair = Arc::new(on_pair); + move |name: &PackId| -> Result, Error> { + let tool = |tool: &str, description: &str| { + ToolInfo::new( + ToolId::parse(&format!("{name}/{tool}")).unwrap(), + description, + json!({ "type": "object", "properties": {} }), + ) + }; + Ok(Arc::new(FilesPack { + tools: vec![ + tool("copy", "Copy one file to another."), + tool("pair", "Write two files at once."), + ], + on_pair: Arc::clone(&on_pair), + })) + } +} + +/// A Host holding the fixture Pack, whose `files/pair` runs `on_pair` as +/// it starts. +fn files_host(on_pair: impl Fn() + Send + Sync + 'static) -> Packs { + let mut packs = registry(&[]); + packs.insert(FILES_PACK, files_pack(on_pair)).unwrap(); + Packs::new(packs) +} + +/// The operation that writes `text` to `path`. +fn write(path: &str, text: &str) -> VfsOp { + VfsOp::Write { + path: path.to_owned(), + contents: text.as_bytes().to_vec(), + } +} + +/// Reads the file `args.from` names through `files` and writes what it +/// read to the one `args.to` names. Answers with the text it copied, or +/// with the failure of the operation that failed. +async fn copy(files: &dyn ToolFiles, args: &Value) -> ToolOutput { + let path = |name: &str| args[name].as_str().unwrap_or_default().to_owned(); + let read = VfsOp::Read { + path: path("from"), + start: None, + end: None, + }; + let text = match files.request(read).await { + Ok(VfsOutcome::Text(text)) => text, + Ok(other) => return ToolOutput::trusted(format!("a read answered {other:?}")), + Err(error) => return ToolOutput::trusted(format!("failed: {error}")), + }; + match files.request(write(&path("to"), &text)).await { + Ok(_) => ToolOutput::trusted(text), + Err(error) => ToolOutput::trusted(format!("failed: {error}")), + } +} + +impl Pack for FilesPack { + fn tools(&self) -> Vec { + self.tools.clone() + } + + fn call<'a>( + &'a self, + cx: ToolContext<'a>, + args: Value, + ) -> BoxFuture<'a, Result> { + Box::pin(async move { + let files = cx.files(); + if cx.tool().name() == "copy" { + return Ok(copy(files, &args).await); + } + (self.on_pair)(); + let (first, second) = tokio::join!( + files.request(write("/first.md", "1")), + files.request(write("/second.md", "2")), + ); + Ok(ToolOutput::trusted(format!("{first:?}|{second:?}"))) + }) + } +} + +/// Panics on every read under `/broken` and allows every other +/// operation. +struct BrokenReads; + +impl Policy for BrokenReads { + fn check(&self, op: Op, path: &VfsPath) -> Verdict { + let path = path.as_str(); + assert!( + !(matches!(op, Op::Read) && path.starts_with("/broken")), + "the policy broke on {path}" + ); + Verdict::Allow + } +} + +/// A prompt that copies `/in.md` to `/out.md` with the fixture tool, then +/// asks it to copy a file that is absent and one whose read panics in the +/// Host's policy, and returns the three answers. +const COPIES: &str = "---\nname: copies\ndescription: d\nrunvil: 0\n\ + uses:\n - tests/files\n---\n\n\ + ## Only\n\n```lua\n\ + local function copy(from, to)\n\ + \x20 return tools.call('files/copy', { from = from, to = to })\n\ + end\n\ + return table.concat({\n\ + \x20 copy('/in.md', '/out.md'),\n\ + \x20 copy('/absent.md', '/never.md'),\n\ + \x20 copy('/broken/a.md', '/never.md'),\n\ + }, '|')\n```\n"; + +/// A prompt that calls `files/pair` under a `pcall`, writes to its store, +/// and returns how the call ended. The store write keeps the section +/// going after a dropped call, so the run has not ended when a file +/// effect of that call goes out. +const PAIRS: &str = "---\nname: pairs\ndescription: d\nrunvil: 0\n\ + uses:\n - tests/files\n---\n\n\ + ## Only\n\n```lua\n\ + local ok, err = pcall(tools.call, 'files/pair')\n\ + store.write('after.md', 'kept')\n\ + return tostring(ok) .. ':' .. err.kind\n```\n"; + +/// The effect record of the file operation `op` that tool call `call` +/// asked for. +fn file_effect(call: u64, op: &Value) -> Value { + json!({ "Vfs": { "call": call, "op": op } }) +} + +/// The answer record of a file operation that failed as `kind`, saying +/// `message`. +fn failed(kind: &str, message: &str) -> Value { + json!({ "VfsReceipt": { "Err": { "kind": kind, "message": message } } }) +} + +/// The recorded form of the operation that reads the whole of `path`. +fn read_op(path: &str) -> Value { + json!({ "Read": { "path": path, "start": null, "end": null } }) +} + +/// The recorded form of the operation that writes `text` to `path`. +fn write_op(path: &str, text: &str) -> Value { + json!({ "Write": { "path": path, "contents": text } }) +} + +/// For each tool call of `records`, in call order: its effect id beside +/// the payloads of the effect and answer records that sit between the +/// call's effect record and its answer record. +fn inside_each_call(records: &[Record]) -> Vec<(u64, Vec)> { + let is_call = |record: &Record| { + record.kind == RecordKind::Effect && record.payload.get("ToolCall").is_some() + }; + records + .iter() + .enumerate() + .filter(|(_, record)| is_call(record)) + .map(|(position, call)| { + let id = call.effect_id.expect("an effect record holds its id"); + let answers_call = + |record: &Record| record.kind == RecordKind::Answer && record.effect_id == Some(id); + let inside = records[position + 1..] + .iter() + .take_while(|record| !answers_call(record)) + .filter(|record| record.kind != RecordKind::Event) + .map(|record| record.payload.clone()) + .collect(); + (id, inside) + }) + .collect() +} + +#[tokio::test] +async fn a_tool_reads_and_writes_through_its_files_and_each_operation_is_recorded_inside_its_call() +{ + let vfs = VfsRef::builder() + .mount("/", MemoryBackend::new()) + .policy(BrokenReads) + .build(); + let seed = vfs.acquire(Origin::new("tool files seed")).unwrap(); + seed.write("/in.md", b"seeded").unwrap(); + drop(seed); + let recorder = Arc::new(MemoryRecorder::new()); + let harness = launch( + files_host(|| ()), + PendingTimer::default(), + COPIES, + RunSetup { + vfs: vfs.clone(), + ..setup(recorder.clone(), ScriptedBroker::replying()) + }, + ); + + let report = harness.run().await.expect("the run is reported"); + + assert_eq!( + report.result, + Ok([ + "seeded", + "failed: not found: /absent.md", + "failed: backend failure: the file operation panicked", + ] + .join("|")), + "each call got the outcome of each operation it asked for, a failure included, and \ + the run went on" + ); + let files = vfs.acquire(Origin::new("tool files test")).unwrap(); + assert_eq!( + files.read_string("/out.md"), + Ok("seeded".to_owned()), + "the Host reads the tool's copy from the setup's filesystem after the run" + ); + assert_eq!( + files.exists("/never.md"), + Ok(false), + "a copy whose read failed wrote nothing" + ); + + let calls = inside_each_call(&recorder.records(report.run_id)); + let [(copied, _), (absent, _), (broken, _)] = calls.as_slice() else { + panic!("the run made three tool calls: {calls:?}"); + }; + assert_eq!( + calls, + [ + ( + *copied, + vec![ + file_effect(*copied, &read_op("/in.md")), + json!({ "VfsReceipt": { "Ok": { "Bytes": 6 } } }), + file_effect(*copied, &write_op("/out.md", "seeded")), + json!({ "VfsReceipt": { "Ok": "Done" } }), + ] + ), + ( + *absent, + vec![ + file_effect(*absent, &read_op("/absent.md")), + failed("not_found", "not found: /absent.md"), + ] + ), + ( + *broken, + vec![ + file_effect(*broken, &read_op("/broken/a.md")), + failed("backend", "backend failure: the file operation panicked"), + ] + ), + ], + "each operation is a Vfs effect that names its call, answered with a receipt or the \ + failure, between the call's effect record and its answer record" + ); +} + +/// A prompt whose two tasks each copy a file of their own with the +/// fixture tool, so two calls ask for files while both are in flight, +/// and which returns both answers. +const COPIES_TWICE: &str = "---\nname: copies-twice\ndescription: d\nrunvil: 0\n\ + uses:\n - tests/files\n---\n\n\ + ## Main\n\n```lua\n\ + local left = tasks.spawn('../Left')\n\ + local right = tasks.spawn('../Right')\n\ + local results = tasks.join({ left, right })\n\ + return results[1].result .. '|' .. results[2].result\n```\n\n\ + ## Left\n\n```lua\n\ + return tools.call('files/copy', { from = '/left.md', to = '/left.out' })\n```\n\n\ + ## Right\n\n```lua\n\ + return tools.call('files/copy', { from = '/right.md', to = '/right.out' })\n```\n"; + +/// The operations of the file effects in `records` that name the tool +/// call whose `from` argument is `from`, in record order. +fn asked_by_the_copy_of(records: &[Record], from: &str) -> Vec { + let call = records + .iter() + .find(|record| record.payload["ToolCall"]["args"]["from"] == from) + .and_then(|record| record.effect_id) + .expect("the run copied the file"); + records + .iter() + .filter(|record| is_call_file_effect(record) && record.payload["Vfs"]["call"] == call) + .map(|record| record.payload["Vfs"]["op"].clone()) + .collect() +} + +#[tokio::test] +async fn two_calls_in_flight_at_once_each_get_the_outcomes_of_their_own_requests() { + let vfs = VfsRef::default(); + let seed = vfs.acquire(Origin::new("tool files seed")).unwrap(); + seed.write("/left.md", b"left").unwrap(); + seed.write("/right.md", b"right").unwrap(); + drop(seed); + let recorder = Arc::new(MemoryRecorder::new()); + let harness = launch( + files_host(|| ()), + PendingTimer::default(), + COPIES_TWICE, + RunSetup { + vfs: vfs.clone(), + ..setup(recorder.clone(), ScriptedBroker::replying()) + }, + ); + + let report = harness.run().await.expect("the run is reported"); + + assert_eq!( + report.result, + Ok("left|right".to_owned()), + "each call read the file it asked for" + ); + let files = vfs.acquire(Origin::new("tool files test")).unwrap(); + assert_eq!(files.read_string("/left.out"), Ok("left".to_owned())); + assert_eq!(files.read_string("/right.out"), Ok("right".to_owned())); + + let records = recorder.records(report.run_id); + let first_request = records + .iter() + .position(is_call_file_effect) + .expect("the calls asked for files"); + let calls_out = records[..first_request] + .iter() + .filter(|record| record.payload.get("ToolCall").is_some()) + .count(); + assert_eq!( + calls_out, 2, + "both calls were in flight when the first request went out" + ); + for (from, to, text) in [ + ("/left.md", "/left.out", "left"), + ("/right.md", "/right.out", "right"), + ] { + assert_eq!( + asked_by_the_copy_of(&records, from), + [read_op(from), write_op(to, text)], + "the record holds the two operations of the copy of {from} under its own call" + ); + } +} + +/// What a test raises on its run while a call's requests are pending. +#[derive(Clone, Copy)] +enum Raise { + Stop, + Cancel, +} + +impl Raise { + fn on(self, control: &RunControl) { + match self { + Raise::Stop => control.stop_round(), + Raise::Cancel => control.cancel(), + } + } +} + +/// When a test raises its stop or cancel. +#[derive(Clone, Copy, PartialEq, Eq)] +enum At { + /// As `files/pair` starts, before it asks for its two writes. The + /// loop takes the call's first request off its desk and reports it to + /// the run, and then sees what was raised. + TheAsk, + /// As the loop records the effect of the call's first request, before + /// it performs it. The second request is still at the call's desk. + TheFirstEffect, +} + +/// Whether `record` is the effect record of a file operation that a tool +/// call asked for. +fn is_call_file_effect(record: &Record) -> bool { + record.kind == RecordKind::Effect && record.payload["Vfs"].get("call").is_some() +} + +/// What a run of [`PAIRS`] left behind. +struct PairRun { + result: Result, + /// The id of the run's one `ToolCall` effect. + call: u64, + /// The run's effect and answer records, as [`trail`] shows them. + trail: Value, + /// Whether the setup's filesystem holds `/first.md`, and whether it + /// holds `/second.md`. + written: (bool, bool), +} + +/// Runs [`PAIRS`] on a Host holding the fixture Pack and raises `raise` +/// on the run at `at`. +async fn pair_run(raise: Raise, at: At) -> PairRun { + let records = Arc::new(MemoryRecorder::new()); + let (recorder, slot) = hooked_recorder(&records, move |record, control| { + if at == At::TheFirstEffect && is_call_file_effect(record) { + raise.on(control); + } + }); + let asking = Arc::clone(&slot); + let on_pair = move || { + if at == At::TheAsk { + raise.on(asking.get().expect("the run's control is in the slot")); + } + }; + let vfs = VfsRef::default(); + let harness = launch( + files_host(on_pair), + PendingTimer::default(), + PAIRS, + RunSetup { + vfs: vfs.clone(), + ..setup(recorder, ScriptedBroker::replying()) + }, + ); + slot.set(harness.control()).unwrap(); + + let report = tokio::time::timeout(PATIENCE, harness.run()) + .await + .expect("the run ends in time") + .expect("the run is reported"); + let (call, trail) = trail(&records.records(report.run_id)); + let files = vfs.acquire(Origin::new("tool files test")).unwrap(); + let written = ( + files.exists("/first.md").unwrap(), + files.exists("/second.md").unwrap(), + ); + PairRun { + result: report.result, + call, + trail, + written, + } +} + +/// The id of the one tool call of `records`, beside the run's effect and +/// answer records in order, each as its kind, its effect id counted from +/// the call's, and its payload. The call's own effect record shows as +/// `"ToolCall"`. +fn trail(records: &[Record]) -> (u64, Value) { + let call = records + .iter() + .find(|record| record.payload.get("ToolCall").is_some()) + .and_then(|record| record.effect_id) + .expect("the run made a tool call"); + let trail = records + .iter() + .filter(|record| record.kind != RecordKind::Event) + .map(|record| { + let kind = if record.kind == RecordKind::Effect { + "effect" + } else { + "answer" + }; + let id = record.effect_id.expect("the record holds its effect's id"); + let payload = match record.payload.get("ToolCall") { + Some(_) => json!("ToolCall"), + None => record.payload.clone(), + }; + json!([kind, id - call, payload]) + }) + .collect(); + (call, trail) +} + +/// The effect record, as [`trail`] shows it, of the first write of +/// `files/pair`: the first effect after the call's own, naming `call`. +fn first_write(call: u64) -> Value { + json!(["effect", 1, file_effect(call, &write_op("/first.md", "1"))]) +} + +/// The two records, as [`trail`] shows them, of the store write that +/// follows the dropped call in [`PAIRS`]. +fn store_write_after() -> [Value; 2] { + let effect = json!({ "Vfs": { "store": "0", "op": write_op("after.md", "kept") } }); + [ + json!(["effect", 2, effect]), + json!(["answer", 2, { "Vfs": { "Ok": "Unit" } }]), + ] +} + +#[tokio::test] +async fn a_stop_raised_as_a_call_asks_drops_the_call_and_answers_its_file_effect_dropped_unperformed() + { + let run = pair_run(Raise::Stop, At::TheAsk).await; + + assert_eq!( + run.result, + Ok("false:canceled".to_owned()), + "the pcall caught the dropped call and the run went on to its end" + ); + let [store_effect, store_answer] = store_write_after(); + assert_eq!( + run.trail, + json!([ + ["effect", 0, "ToolCall"], + ["answer", 0, "Dropped"], + first_write(run.call), + ["answer", 1, "Dropped"], + store_effect, + store_answer, + ]), + "the stop dropped the call, the file effect the run issued for the request the loop \ + had reported is answered Dropped, and the second request is never issued" + ); + assert_eq!(run.written, (false, false), "neither write was performed"); +} + +#[tokio::test] +async fn a_stop_raised_as_a_file_effect_goes_out_performs_it_and_drops_the_calls_later_request() { + let run = pair_run(Raise::Stop, At::TheFirstEffect).await; + + assert_eq!( + run.result, + Ok("false:canceled".to_owned()), + "the pcall caught the dropped call and the run went on to its end" + ); + let [store_effect, store_answer] = store_write_after(); + assert_eq!( + run.trail, + json!([ + ["effect", 0, "ToolCall"], + first_write(run.call), + ["answer", 1, { "VfsReceipt": { "Ok": "Done" } }], + ["answer", 0, "Dropped"], + store_effect, + store_answer, + ]), + "the effect that had gone out is performed and answered with its receipt, then the \ + stop drops the call, and the second request is never issued" + ); + assert_eq!( + run.written, + (true, false), + "the first write was performed and the second was not" + ); +} + +#[tokio::test] +async fn a_cancel_raised_as_a_call_asks_ends_the_run_canceled_with_its_file_effect_dropped_unperformed() + { + let run = pair_run(Raise::Cancel, At::TheAsk).await; + + assert_canceled(&run.result); + assert_eq!( + run.trail, + json!([ + ["effect", 0, "ToolCall"], + first_write(run.call), + ["answer", 1, "Dropped"], + ["answer", 0, "Dropped"], + ]), + "the file effect the run issued for the reported request is answered Dropped with \ + the call, and the second request is never issued" + ); + assert_eq!(run.written, (false, false), "neither write was performed"); +} + +#[tokio::test] +async fn a_cancel_raised_as_a_file_effect_goes_out_performs_it_and_ends_the_run_canceled() { + let run = pair_run(Raise::Cancel, At::TheFirstEffect).await; + + assert_canceled(&run.result); + assert_eq!( + run.trail, + json!([ + ["effect", 0, "ToolCall"], + first_write(run.call), + ["answer", 1, { "VfsReceipt": { "Ok": "Done" } }], + ["answer", 0, "Dropped"], + ]), + "the effect that had gone out is performed and answered with its receipt, then the \ + cancel drops the call, and the second request is never issued" + ); + assert_eq!( + run.written, + (true, false), + "the first write was performed and the second was not" + ); +} diff --git a/crates/harness-internal/runner/tests/it/harness.rs b/crates/harness-internal/runner/tests/it/harness.rs index 025cb7ba9..27ddb8628 100644 --- a/crates/harness-internal/runner/tests/it/harness.rs +++ b/crates/harness-internal/runner/tests/it/harness.rs @@ -13,9 +13,10 @@ //! `stop_cap` child module, how what a stop reaches depends on when the //! loop sees it in the `stop_timing` child module, the messages a Host //! sends the main chain in the `inbox` child module, a run whose prompt -//! executes a prompt it lists in the `execute` child module, and the runs -//! that end before they start and the one error `run` returns in the -//! `errors` child module. +//! executes a prompt it lists in the `execute` child module, the file +//! operations a tool call asks for through its files in the `files` child +//! module, and the runs that end before they start and the one error +//! `run` returns in the `errors` child module. use std::future::Future; use std::path::PathBuf; @@ -40,6 +41,8 @@ use crate::support::{PendingTimer, host_over, parsed}; mod errors; #[path = "harness-execute.rs"] mod execute; +#[path = "harness-files.rs"] +mod files; #[path = "harness-inbox.rs"] mod inbox; #[path = "harness-stop.rs"] diff --git a/crates/harness-internal/runner/tests/it/performers.rs b/crates/harness-internal/runner/tests/it/performers.rs index 0b7f105f6..6881fdd87 100644 --- a/crates/harness-internal/runner/tests/it/performers.rs +++ b/crates/harness-internal/runner/tests/it/performers.rs @@ -15,6 +15,7 @@ use runvil_engine::cancel::CancelHandle; use runvil_engine::effect::ToolCallOrigin; use runvil_engine::vfs::Access; use runvil_engine::{BoxFuture, Timestamp, ToolId, ToolOutput}; +use runvil_plugin::ToolFiles; use serde_json::{Value, json}; use crate::support::{ @@ -113,6 +114,7 @@ impl ToolPerformer for DelayedTool { _access: Arc, _origin: ToolCallOrigin, _args: Value, + _files: Arc, ) -> BoxFuture<'static, Result> { let delay = self.delay; let text = self.text; diff --git a/crates/harness-internal/runner/tests/it/support.rs b/crates/harness-internal/runner/tests/it/support.rs index 56f708ecf..6788f386b 100644 --- a/crates/harness-internal/runner/tests/it/support.rs +++ b/crates/harness-internal/runner/tests/it/support.rs @@ -22,7 +22,7 @@ use runvil_engine::vfs::Access; use runvil_engine::{BoxFuture, Error, ErrorCode}; use runvil_engine::{Prompt, Run, RunParams, RunSeed, Timestamp}; use runvil_engine::{ToolCatalog, ToolId, ToolInfo, ToolOutput}; -use runvil_plugin::{Pack, PackId, PackInfo, PackRegistry}; +use runvil_plugin::{Pack, PackId, PackInfo, PackRegistry, ToolFiles}; use serde_json::{Value, json}; /// The fixed seed every fixture run and recorded meta takes. @@ -183,6 +183,7 @@ impl ToolPerformer for Unused { _access: Arc, _origin: ToolCallOrigin, _args: Value, + _files: Arc, ) -> BoxFuture<'static, Result> { unreachable!("this test issues no ToolCall effect") } @@ -212,6 +213,7 @@ impl ToolPerformer for TextTool { _access: Arc, _origin: ToolCallOrigin, _args: Value, + _files: Arc, ) -> BoxFuture<'static, Result> { let text = self.0; Box::pin(async move { Ok(ToolOutput::trusted(text)) }) @@ -229,6 +231,7 @@ impl ToolPerformer for PendingTool { _access: Arc, _origin: ToolCallOrigin, _args: Value, + _files: Arc, ) -> BoxFuture<'static, Result> { Box::pin(std::future::pending()) } @@ -246,6 +249,7 @@ impl ToolPerformer for PanickingTool { _access: Arc, _origin: ToolCallOrigin, _args: Value, + _files: Arc, ) -> BoxFuture<'static, Result> { Box::pin(std::future::poll_fn( |_cx| -> Poll> { @@ -270,6 +274,7 @@ impl ToolPerformer for ClosingTool { _access: Arc, _origin: ToolCallOrigin, _args: Value, + _files: Arc, ) -> BoxFuture<'static, Result> { let recorder = Arc::clone(&self.recorder); let run_id = self.run_id; @@ -409,6 +414,7 @@ impl ToolPerformer for GatedTool { _access: Arc, _origin: ToolCallOrigin, _args: Value, + _files: Arc, ) -> BoxFuture<'static, Result> { let gate = Arc::clone(&self.gate); Box::pin(async move { diff --git a/crates/runvil-plugin/src/context.rs b/crates/runvil-plugin/src/context.rs index 6a4f8faa3..5ca94267c 100644 --- a/crates/runvil-plugin/src/context.rs +++ b/crates/runvil-plugin/src/context.rs @@ -1,43 +1,99 @@ -//! [`ToolContext`], what one tool call receives, and [`RenderContext`], -//! what a render learns about its section entry. +//! [`ToolContext`], what one tool call receives, [`ToolFiles`], through +//! which the call asks for file operations, and [`RenderContext`], what a +//! render learns about its section entry. +use std::fmt; + +use runvil_types::future::BoxFuture; use runvil_types::models::ModelInfo; use runvil_types::tools::{ToolCallOrigin, ToolId}; -use runvil_vfs::Access; +use runvil_vfs::{Access, VfsError, VfsOp, VfsOutcome}; + +/// The files of one tool call: the call asks for a file operation and +/// waits for its outcome. +/// +/// The Harness reports each request to the run, which issues it as an +/// effect. The Harness performs the operation on the run's filesystem +/// with one blocking call, under the call's own identity and the run's +/// policy, records it, and resolves the request with the whole outcome. +/// So a run's record holds every operation a tool asks for here, in +/// order, and a later poll of the call receives the answer. +/// +/// The operations are the ones [`VfsOp`] lists, with paths rooted at `/` +/// of the filesystem the Host gave the run. No path reaches a store. +pub trait ToolFiles: Send + Sync { + /// Asks for `op` and resolves with its outcome. + /// + /// The request goes out when the returned future is first polled. + /// A future dropped before that sends nothing. Dropping it later + /// takes nothing back: the Harness still performs the operation + /// while the call is in flight, and the outcome is discarded. A + /// call may wait on several requests at once, and the Harness + /// performs them one after another, in the order they went out. + /// + /// The future resolves only while the Harness polls the call, so a + /// call awaits it in its own future and never blocks on it. + /// + /// # Errors + /// Resolves with the [`VfsError`] of an operation that failed: a path + /// that is absent or refused, a policy that denies the operation, or + /// a backend that fails. + fn request(&self, op: VfsOp) -> BoxFuture<'_, Result>; +} /// What one tool call lends its Pack: facts about that call alone, the -/// called tool's id, the call's filesystem access, and who made the call. +/// called tool's id, the call's files, the call's filesystem access, and +/// who made the call. /// -/// The access is the call's own identity, forked from the calling chain's, -/// so the chain's earlier work happens before the call's operations and -/// the call's operations before the chain's next step. Calls a model asks -/// for in one round fork their identities from the chain together, so they -/// are concurrent with each other: one call's write to a path conflicts -/// with a sibling's read or write of it, as between fanout arms. It is -/// rooted at `/`. The context borrows everything for the call alone, so a -/// Pack cannot store the access, move it into a spawned task or thread, -/// or keep it past the call. +/// The files and the access reach one filesystem under one identity, the +/// call's own, forked from the calling chain's, so the chain's earlier +/// work happens before the call's operations and the call's operations +/// before the chain's next step. Calls a model asks for in one round fork +/// their identities from the chain together, so they are concurrent with +/// each other: one call's write to a path conflicts with a sibling's read +/// or write of it, as between fanout arms. Both are rooted at `/`. An +/// operation asked for through [`files`](ToolContext::files) is in the +/// run's record, and one made through [`access`](ToolContext::access) is +/// outside it. The context borrows everything for the call alone, so a +/// Pack cannot store the files or the access, move them into a spawned +/// task or thread, or keep them past the call. /// /// A call gets no services. A Plugin's `install` keeps the Host-wide /// services its Pack needs in the Pack's /// [`PackFactory`](crate::PackFactory), which hands them to each run's /// instance it makes at [`new_pack`](crate::PackFactory::new_pack). -#[derive(Debug)] pub struct ToolContext<'a> { tool: &'a ToolId, access: &'a Access, origin: &'a ToolCallOrigin, + files: &'a dyn ToolFiles, +} + +impl fmt::Debug for ToolContext<'_> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("ToolContext") + .field("tool", &self.tool) + .field("access", &self.access) + .field("origin", &self.origin) + .finish_non_exhaustive() + } } impl<'a> ToolContext<'a> { - /// Facts about one call: the tool id, its access, and its origin. The - /// Harness builds one per call. + /// Facts about one call: the tool id, its access, its origin, and + /// its files. The Harness builds one per call. #[must_use] - pub fn new(tool: &'a ToolId, access: &'a Access, origin: &'a ToolCallOrigin) -> Self { + pub fn new( + tool: &'a ToolId, + access: &'a Access, + origin: &'a ToolCallOrigin, + files: &'a dyn ToolFiles, + ) -> Self { Self { tool, access, origin, + files, } } @@ -48,7 +104,15 @@ impl<'a> ToolContext<'a> { self.tool } - /// The call's filesystem access, rooted at `/`. + /// The call's files, through which it asks for each file operation + /// as an effect the Harness performs and records. + #[must_use] + pub fn files(&self) -> &'a dyn ToolFiles { + self.files + } + + /// The call's filesystem access, rooted at `/`. An operation made + /// through it runs inside the call and is outside the run's record. #[must_use] pub fn access(&self) -> &'a Access { self.access @@ -90,21 +154,31 @@ impl<'a> RenderContext<'a> { #[cfg(test)] mod tests { - //! Tests for the contexts a Pack receives: a tool call's getters, and - //! the facts a render learns. + //! Tests for the contexts a Pack receives: a tool call's getters and + //! its `Debug` form, and the facts a render learns. use std::num::NonZeroU32; + use runvil_types::future::BoxFuture; use runvil_types::models::{ModelId, ModelInfo, ThinkingMode}; use runvil_types::tools::{ToolCallOrigin, ToolCaller, ToolId}; - use runvil_vfs::{Access, Origin, VfsRef}; + use runvil_vfs::{Access, Origin, VfsError, VfsOp, VfsOutcome, VfsRef}; - use super::{RenderContext, ToolContext}; + use super::{RenderContext, ToolContext, ToolFiles}; fn fetch() -> ToolId { ToolId::parse("web/fetch").expect("a two-segment tool id parses") } + /// Files that answer every request with nothing, at once. + struct NoFiles; + + impl ToolFiles for NoFiles { + fn request(&self, _op: VfsOp) -> BoxFuture<'_, Result> { + Box::pin(std::future::ready(Ok(VfsOutcome::Unit))) + } + } + fn fresh_access() -> Access { VfsRef::default() .acquire(Origin::new("context test")) @@ -118,14 +192,28 @@ mod tests { #[test] fn each_getter_returns_the_value_the_context_was_built_from() { let (tool, access, origin) = (fetch(), fresh_access(), model_origin()); - let cx = ToolContext::new(&tool, &access, &origin); + let files = NoFiles; + let cx = ToolContext::new(&tool, &access, &origin, &files); assert!(std::ptr::eq(cx.tool(), &raw const tool)); assert!(std::ptr::eq(cx.access(), &raw const access)); assert!(std::ptr::eq(cx.origin(), &raw const origin)); + assert!(std::ptr::addr_eq(cx.files(), &raw const files)); assert_eq!(cx.tool().name(), "fetch"); assert_eq!(cx.origin().caller, ToolCaller::Model); } + #[test] + fn a_tool_context_shows_its_tool_and_origin_in_debug_and_not_its_files() { + let (tool, access, origin) = (fetch(), fresh_access(), model_origin()); + let shown = format!("{:?}", ToolContext::new(&tool, &access, &origin, &NoFiles)); + assert!(shown.starts_with("ToolContext { tool: "), "{shown}"); + assert!( + shown.contains("\"fetch\"") && shown.contains("section: \"Fetch\""), + "{shown}" + ); + assert!(shown.ends_with(".. }"), "{shown}"); + } + #[test] fn a_render_context_holds_the_entry_and_the_model_it_was_built_with() { let model = ModelInfo::new( diff --git a/crates/runvil-plugin/src/lib.rs b/crates/runvil-plugin/src/lib.rs index 9e3dd1514..72bca63b7 100644 --- a/crates/runvil-plugin/src/lib.rs +++ b/crates/runvil-plugin/src/lib.rs @@ -41,7 +41,9 @@ //! makes each run's [`Pack`] instance: the Harness calls //! [`PackFactory::new_pack`] for each Pack a run holds, and the instance //! drops when the run ends. [`Pack::call`] performs one tool call with the -//! [`ToolContext`] the Harness lends it. +//! [`ToolContext`] the Harness lends it, and asks for each file operation +//! through the context's [`ToolFiles`], as a [`VfsOp`] that resolves with +//! its [`VfsOutcome`]. //! [`Pack::render`] returns the tools the model sees, given the tools a //! section offered from the Pack and the [`RenderContext`] that names the //! section entry and its model. @@ -90,9 +92,14 @@ //! resolution it answers at once unless the Pack's state has changed. //! - [`Pack::call`] must not block while polled. Every effect of a run //! is polled on the same task, so blocking or CPU-heavy work goes to the -//! Host's runtime. A file operation through the call's access is the -//! exception: it is synchronous by design and holds the run until it -//! returns. +//! Host's runtime. A file operation is the exception: it is synchronous +//! by design, and the run waits for it. The Harness performs each +//! operation a call asks for through [`ToolContext::files`] with one +//! blocking call, and an operation through the call's access holds the +//! run until it returns. +//! - A call asks for a file operation through [`ToolContext::files`], so +//! the run's record holds it. An operation through the call's access is +//! outside the record. //! - [`Pack::call`] must not panic. A panicking call's effect is //! answered `Dropped`, and the panic is logged. //! - [`Pack::call`] marks the trust of every output correctly: output @@ -115,7 +122,7 @@ mod service; #[cfg(feature = "test-support")] pub mod testing; -pub use context::{RenderContext, ToolContext}; +pub use context::{RenderContext, ToolContext, ToolFiles}; pub use pack::{Pack, PackFactory, PackInfo}; pub use registry::{PackOrigin, PackRegistry}; pub use service::{HostServices, ServiceId, ServiceKey, TOKIO_RUNTIME}; @@ -127,4 +134,4 @@ pub use runvil_types::packs::PackId; pub use runvil_types::tools::{ OutputTrust, ToolCallOrigin, ToolCaller, ToolId, ToolInfo, ToolOutput, make_tool_error, }; -pub use runvil_vfs::{Access, Entry, FileType, PathReason, Stat, VfsError}; +pub use runvil_vfs::{Access, Entry, FileType, PathReason, Stat, VfsError, VfsOp, VfsOutcome}; diff --git a/crates/runvil-plugin/src/pack.rs b/crates/runvil-plugin/src/pack.rs index 3ee60b079..00c1cc200 100644 --- a/crates/runvil-plugin/src/pack.rs +++ b/crates/runvil-plugin/src/pack.rs @@ -66,18 +66,21 @@ pub trait Pack: Send + Sync { /// Performs one tool call. /// - /// `cx` names the called tool and lends the call's filesystem access - /// and its origin. What the call needs from the Host's services, its - /// factory took at `install` and shares with the instance. `args` is - /// the JSON the model or the script passed. + /// `cx` names the called tool and lends the call's files, its + /// filesystem access, and its origin. What the call needs from the + /// Host's services, its factory took at `install` and shares with the + /// instance. `args` is the JSON the model or the script passed. /// /// # Invariants /// /// - `call` must not block while polled. The Harness polls every /// effect of a run on the same task, so blocking or CPU-heavy work - /// goes to the Host's runtime, without the access. Operations - /// through [`ToolContext::access`] run inside the call; on real - /// directories they block the poll briefly. + /// goes to the Host's runtime, without the files or the access. A + /// call awaits each operation it asks for through + /// [`ToolContext::files`], and the Harness performs it between two + /// polls of the call. Operations through [`ToolContext::access`] + /// run inside the call; on real directories they block the poll + /// briefly. /// - `call` must not panic. If it does, the Harness answers its effect /// `Dropped` and logs the panic. /// - `call` marks the trust of every output correctly. Output that diff --git a/crates/runvil-plugin/src/testing.rs b/crates/runvil-plugin/src/testing.rs index 227f730da..476edd43a 100644 --- a/crates/runvil-plugin/src/testing.rs +++ b/crates/runvil-plugin/src/testing.rs @@ -1,24 +1,39 @@ //! [`TestCall`]: lends a [`ToolContext`] to a Plugin crate's own tests. +use runvil_types::future::BoxFuture; use runvil_types::tools::{ToolCallOrigin, ToolCaller, ToolId}; -use runvil_vfs::{Access, Origin, VfsRef}; +use runvil_vfs::{Access, Origin, VfsError, VfsOp, VfsOutcome, VfsRef}; -use crate::ToolContext; +use crate::{ToolContext, ToolFiles}; /// One tool call a test makes directly, without a Harness. /// -/// It owns everything a [`ToolContext`] borrows: the called tool's id, an -/// access over a fresh in-memory filesystem, and an origin naming the +/// It owns everything a [`ToolContext`] borrows: the called tool's id, a +/// fresh in-memory filesystem of its own, and an origin naming the /// section `Test` and a caller that is the script unless -/// [`with_caller`](TestCall::with_caller) names another. A test calls the -/// Pack's factory for the instance it calls. +/// [`with_caller`](TestCall::with_caller) names another. The context's +/// files and its access reach that one filesystem, so a test seeds a file +/// through either and reads it back through the other. A request through +/// the files is answered at once: its future is ready at its first poll. +/// A test calls the Pack's factory for the instance it calls. #[derive(Debug)] pub struct TestCall { tool: ToolId, - access: Access, + files: AnsweredAtOnce, origin: ToolCallOrigin, } +/// The files of a [`TestCall`]: each request is performed where it is +/// made, on the call's own in-memory filesystem. +#[derive(Debug)] +struct AnsweredAtOnce(Access); + +impl ToolFiles for AnsweredAtOnce { + fn request(&self, op: VfsOp) -> BoxFuture<'_, Result> { + Box::pin(std::future::ready(self.0.perform(&op))) + } +} + impl TestCall { /// A call of `tool` from the script of the section `Test`, over a /// fresh in-memory filesystem. @@ -38,7 +53,7 @@ impl TestCall { let origin = ToolCallOrigin::new("Test", ToolCaller::Script); TestCall { tool, - access, + files: AnsweredAtOnce(access), origin, } } @@ -54,6 +69,6 @@ impl TestCall { /// Lends the context to one call. #[must_use] pub fn context(&self) -> ToolContext<'_> { - ToolContext::new(&self.tool, &self.access, &self.origin) + ToolContext::new(&self.tool, &self.files.0, &self.origin, &self.files) } } diff --git a/crates/runvil-plugin/tests/it/test_call.rs b/crates/runvil-plugin/tests/it/test_call.rs index 302141935..dcbfb2dcb 100644 --- a/crates/runvil-plugin/tests/it/test_call.rs +++ b/crates/runvil-plugin/tests/it/test_call.rs @@ -1,13 +1,71 @@ //! `TestCall`: the context a Plugin crate's own test lends a call it makes -//! directly. +//! directly, whose files answer each request at once from the call's own +//! filesystem. + +use std::task::{Context, Poll, Waker}; use runvil_plugin::testing::TestCall; -use runvil_plugin::{ToolCaller, ToolId}; +use runvil_plugin::{ToolCaller, ToolId, VfsError, VfsOp, VfsOutcome}; fn inspect() -> ToolId { ToolId::parse("acme/inspect").expect("a two-segment tool id parses") } +/// The outcome of `op`, asked for through `call`'s files and taken at the +/// request's first poll. +fn asked(call: &TestCall, op: VfsOp) -> Result { + let mut request = call.context().files().request(op); + match request + .as_mut() + .poll(&mut Context::from_waker(Waker::noop())) + { + Poll::Ready(outcome) => outcome, + Poll::Pending => panic!("a test call answers each request at once"), + } +} + +#[test] +fn a_test_calls_files_answer_each_request_at_once_from_the_calls_own_filesystem() { + let call = TestCall::new(inspect()); + let write = VfsOp::Write { + path: "/notes.md".to_owned(), + contents: b"asked for".to_vec(), + }; + assert_eq!(asked(&call, write), Ok(VfsOutcome::Unit)); + assert_eq!( + call.context() + .access() + .read("/notes.md") + .expect("the access reads what the files wrote"), + b"asked for" + ); + + call.context() + .access() + .write("/seeded.md", b"seeded") + .expect("the in-memory filesystem accepts a write"); + let read = VfsOp::ReadRange { + path: "/seeded.md".to_owned(), + offset: 0, + len: 64, + }; + assert_eq!( + asked(&call, read), + Ok(VfsOutcome::Bytes(b"seeded".to_vec())) + ); + + let missing = VfsOp::Remove { + path: "/gone.md".to_owned(), + recursive: false, + }; + assert_eq!( + asked(&call, missing), + Err(VfsError::NotFound { + path: "/gone.md".to_owned(), + }) + ); +} + #[test] fn a_test_call_lends_its_tool_a_script_origin_and_a_working_filesystem() { let call = TestCall::new(inspect()); diff --git a/crates/runvil/public-api.txt b/crates/runvil/public-api.txt index a4e5eb8ac..aaa2a4c54 100644 --- a/crates/runvil/public-api.txt +++ b/crates/runvil/public-api.txt @@ -543,9 +543,11 @@ pub fn runvil::plugin::PackRegistry::list(&self) -> impl core::iter::traits::ite pub fn runvil::plugin::PackRegistry::new() -> runvil::plugin::PackRegistry pub fn runvil::plugin::RenderContext::new(entry: &'a str, model: &'a runvil::model::ModelInfo) -> Self pub fn runvil::plugin::ToolContext::access(&self) -> &'a runvil::vfs::Access -pub fn runvil::plugin::ToolContext::new(tool: &'a runvil::ToolId, access: &'a runvil::vfs::Access, origin: &'a runvil::effect::ToolCallOrigin) -> Self +pub fn runvil::plugin::ToolContext::files(&self) -> &'a dyn runvil::plugin::ToolFiles +pub fn runvil::plugin::ToolContext::new(tool: &'a runvil::ToolId, access: &'a runvil::vfs::Access, origin: &'a runvil::effect::ToolCallOrigin, files: &'a dyn runvil::plugin::ToolFiles) -> Self pub fn runvil::plugin::ToolContext::origin(&self) -> &'a runvil::effect::ToolCallOrigin pub fn runvil::plugin::ToolContext::tool(&self) -> &'a runvil::ToolId +pub fn runvil::plugin::ToolFiles::request(&self, op: runvil::vfs::VfsOp) -> runvil::BoxFuture<'_, core::result::Result> pub fn runvil::prompt::ArgsSchema::as_json(&self) -> &serde_json::value::Value pub fn runvil::prompt::Frontmatter::args(&self) -> &runvil::prompt::ArgsSchema pub fn runvil::prompt::Frontmatter::description(&self) -> &str @@ -1271,6 +1273,7 @@ pub trait runvil::harness::RunRecorder: core::marker::Send + core::marker::Sync pub trait runvil::harness::Timer: core::marker::Send + core::marker::Sync pub trait runvil::plugin::Pack: core::marker::Send + core::marker::Sync pub trait runvil::plugin::PackFactory: core::marker::Send + core::marker::Sync +pub trait runvil::plugin::ToolFiles: core::marker::Send + core::marker::Sync pub trait runvil::vfs::Policy: core::marker::Send pub trait runvil::vfs::Vfs: core::marker::Send pub trait runvil::vfs::VfsAccess: core::marker::Send diff --git a/crates/runvil/src/lib.rs b/crates/runvil/src/lib.rs index 7fb88ae0f..bcf59b772 100644 --- a/crates/runvil/src/lib.rs +++ b/crates/runvil/src/lib.rs @@ -111,8 +111,9 @@ pub mod plugin { //! instance of it, the registry a Host's Plugins insert Packs into, //! where each of its Packs came from, the services map a Host fills //! for its Plugins with the keys that name its services, and what a - //! tool call and a render are lent. The Plugin crates themselves are - //! the Host's own dependencies. + //! tool call and a render are lent, the files through which a tool + //! call asks for file operations among them. The Plugin crates + //! themselves are the Host's own dependencies. pub use runvil_plugin::HostServices; pub use runvil_plugin::Pack; @@ -125,6 +126,7 @@ pub mod plugin { pub use runvil_plugin::ServiceKey; pub use runvil_plugin::TOKIO_RUNTIME; pub use runvil_plugin::ToolContext; + pub use runvil_plugin::ToolFiles; } pub mod effect { diff --git a/decisions/files-and-the-vfs.md b/decisions/files-and-the-vfs.md index 1be2a1e24..fa991950a 100644 --- a/decisions/files-and-the-vfs.md +++ b/decisions/files-and-the-vfs.md @@ -52,7 +52,7 @@ The store follows one rule: it offers a subset of the operations of the VFS. A s `runvil-vfs` defines the file operations as values. A `VfsOp` is one operation with its arguments, `Access::perform` runs it on an `Access`, and a `VfsOutcome` is what it returns. The `store` functions use `Write`, `Append`, `Read`, `ReadNumbered`, `StrReplace`, `Delete`, `Glob`, and `Exists`, and each `store` call is one of them. The list also has the operations that a tool asks for: `Stat`, `List`, `ReadRange`, `Mkdir`, `Remove`, `Rename`, and `Copy`, beside `Write` and `Append`. `Write` and `Append` hold bytes, because a tool writes bytes, and a `store` call passes the bytes of its text. `Delete` succeeds on an absent path, and `Remove` fails on one with `VfsError::NotFound`. They are two operations, so a run's record shows which one ran. -The owner's reason for one list: "in principle, the store is just a virtual directory in the file system that is unique to a prompt." A `store` call and a tool's file request are two views of the same operations, and the Engine and the Harness handle the whole list, so either side gains an operation by adding one function. A `store` call reaches the list as an effect today, and a tool's request will once a tool's file operations are effects (see Planned work). +The owner's reason for one list: "in principle, the store is just a virtual directory in the file system that is unique to a prompt." A `store` call and a tool's file request are two views of the same operations, and the Engine and the Harness handle the whole list, so either side gains an operation by adding one function. Each of the two reaches the list as a `Vfs` effect, which says who asked ([The Engine](engine.md)). ### Virtual paths have one POSIX form on every operating system @@ -158,15 +158,17 @@ Scopes let a Host write files before a run and read them after it, and let concu ### A tool call works under its own identity, which the Engine ends with the call -The Engine forks an identity for each Pack tool call and passes its `Access`, rooted at `/` of the run's handle, in the `ToolCall` effect ([Tools and Packs](tools-and-packs.md)). The `Access` reaches the files of the handle and no store, and a Rust Pack calls the `Access` itself. For a Pack that follows the C contract, the loader keeps the `Access` and answers the contract's file functions from it: `file_stat`, `file_list`, and `file_read`. Contract 0.4 reads only, so the tools of `std` and `bash` read files. When the Harness answers the call or the Engine aborts it, `ScopeHandle::end_access` joins the identity into the calling chain, and every later operation through that `Access` fails with `ScopeEnded`. The Engine ends the identity because a call that it aborted could otherwise still write. +The Engine forks an identity for each Pack tool call. The identity's `Access`, rooted at `/` of the run's handle, reaches the files of the handle and no store, and every file operation of the call runs on it ([Tools and Packs](tools-and-packs.md)). The Engine passes the `Access` in each `Vfs` effect that it issues for a request of the call, and the Harness performs the operation on it. The `ToolCall` effect holds the same `Access`: a Rust Pack can call it itself, and for a Pack that follows the C contract, the loader keeps it and answers the contract's file functions from it: `file_stat`, `file_list`, and `file_read`. Contract 0.4 reads only, so the tools of `std` and `bash` read files. When the Harness answers the call or the Engine aborts it, `ScopeHandle::end_access` joins the identity into the calling chain, and every later operation through that `Access` fails with `ScopeEnded`. The Engine ends the identity because a call that it aborted could otherwise still write. -When an operation inside a tool call conflicts, the `Access` returns `VfsError::Conflict` to the Pack, which decides how to answer the call. For the `std` Pack, a library Plugin, the loader passes the conflict on as a file error of the C contract, and the Pack converts it into a sentence that tells the model to call the tool again. In the shell of the `bash` Pack the same file error fails the command that read the file, and the model reads the reason in the command's output. The Engine resumes the chain with the Pack's answer. The Engine ends the run only for a conflict in a `store` call: the fatal rule applies only to answers of `Effect::Vfs`. +When an operation of a tool call conflicts, the tool receives `VfsError::Conflict`, as the outcome of its request or from the `Access`, and its Pack decides how to answer the call. For the `std` Pack, a library Plugin, the loader passes the conflict on as a file error of the C contract, and the Pack converts it into a sentence that tells the model to call the tool again. In the shell of the `bash` Pack the same file error fails the command that read the file, and the model reads the reason in the command's output. The Engine resumes the chain with the Pack's answer. The Engine ends the run only for a conflict in a `store` call: the fatal rule applies to the answer of a `Vfs` effect that the prompt's Lua asked for, and a failure in the answer of one that a tool asked for goes to the tool alone. -### A tool's file operations will be effects, and today a tool performs them itself +### A tool's file request is a `Vfs` effect, which the Harness performs and records -Today a tool performs each file operation itself, through the `Access` of its call or through the file functions of the C contract, and the run's record holds none of them. The owner has decided that each one becomes an effect: the tool asks, the Engine issues a `Vfs` effect under the call's identity, the Harness performs and records it, and the tool goes on with the answer. The owner's rule: "every VFS operation that's performed by a tool has to turn into an effect in the engine." +A tool asks for a file operation and waits for the outcome. A Rust Pack's tool asks through the files of its call ([Tools and Packs](tools-and-packs.md)). The Harness reports the request to the Engine, the Engine issues a `Vfs` effect under the call's identity, the Harness performs and records it, and the tool goes on with the answer ([The Engine](engine.md)). The owner's rule: "every VFS operation that's performed by a tool has to turn into an effect in the engine." -The reason is the record. The owner's questions about the present design: "how's replay gonna work? How are we gonna do replay? How are we gonna handle debugging?" One ordered record of a run exists only if the Harness sees every effect and every answer ([The Harness and the Host API](harness-and-host.md)), and a tool's file operations are the part of a run that it misses today. The change is still to be built (see Planned work). Until it is, the ways a tool reaches files stay as they are, and the next one arrives in the new form. +The reason is the record. The owner's questions about a tool that performs its file operations itself: "how's replay gonna work? How are we gonna do replay? How are we gonna handle debugging?" One ordered record of a run exists only if the Harness sees every effect and every answer ([The Harness and the Host API](harness-and-host.md)). + +Two ways to a file stay outside the record: an operation that a Rust Pack performs itself on the `Access` of its call, and a file function of contract 0.4, which the loader answers from that `Access`. The contract is to ask as the Rust API does, and the `Access` then leaves a tool's reach (see Planned work). ## 6. Errors @@ -186,18 +188,20 @@ An error has three readers: Rust code matches the variant, Lua code branches on A `store` function yields its operation, and the Engine issues one `Effect::Vfs` for it ([The Engine](engine.md)). The Harness performs the effect at once, before it waits for any other effect. The Engine reports an event for each call, such as `VfsWriteSucceeded`, which names the section and omits the path and the store. The run's record holds every store operation: each `Vfs` effect record with the id of its store and its operation, and each answer record with its outcome, in order. The record is the only view of a store outside its run, and the records of one store are enough to rebuild it. -The Harness performs the call inline because file operations are synchronous by design: the storage underneath is synchronous, so a `Vfs` effect has no future for the effect loop to wait on, and the run waits for the operation. The owner's reason: "all file I/O synchronizes the, the harness, and that's in line with our design." The Harness performs the operation through the effect's view and holds no way to the store between effects. It answers every `Vfs` effect of a step this way and then steps the run once. VFS operations from different chains run one at a time, in the order the Engine issues them. +The Harness performs the call inline because file operations are synchronous by design: the storage underneath is synchronous, so a `Vfs` effect has no future for the effect loop to wait on, and the run waits for the operation. The owner's reason: "all file I/O synchronizes the, the harness, and that's in line with our design." The Harness performs the operation through the effect's view and holds no way to the store between effects. It answers every `Vfs` effect of a step this way and then steps the run once. VFS operations run one at a time, in the order the Engine issues them, whether a `store` call or a tool's request asked for each. Store operations are effects for the owner's reason: "We want to be able to debug prompts and replay them and see how the contents of the store evolves". The record holds every store call with its arguments and its outcome, the Harness sees each call before it happens, and a replay, which is planned work, would issue the same effects again. The `store` functions stay in the Engine. A plan to serve them from a tool is dropped. It was a restructuring of the code to make the Engine smaller, and in the owner's words, "This has nothing to do with capabilities." The owner's verdict on the plan: "That turned out to be not a good idea". Turning the store into a tool was more work, in the owner's words "to turn it into a tool and to create all the rigmarole", and the store is part of the language: "It just needs to be a language feature." The owner's rule is that a feature that is deeply part of the language stays in the Engine. -### A `Vfs` effect and its record name the store by a chain id +### A `Vfs` effect and its record name a store by a chain id, and a tool call by its effect id The `Vfs` effect of a `store` call names its store in its `asker`, by a `ChainId`, and the effect's record holds that id beside the operation, as in `{"Vfs":{"store":"0","op":{...}}}`. The id `0`, the root chain's, names the store that the run starts with. A store that an `execute` made has the id of the executed prompt's chain, such as `0.0`, and every operation on that store has this id, whichever chain of the executed prompt made the call. The record names the store because an executed prompt reports under its caller's task, and two stores can each have a file at one path. Without the id, a reader of the log could not tell the caller's `a.md` from the child's, and neither store could be rebuilt. With it, the records of each store rebuild that store. The id is a chain id because a chain id is the same in every run with the same inputs and answers ([Tasks and fanout](tasks-and-fanout.md)), which a replay needs. +The `Vfs` effect of a tool's request names the tool call, by the id of its `ToolCall` effect, and the record holds that id beside the operation, as in `{"Vfs":{"call":7,"op":{...}}}`. Its files are the files of the run's handle, which the record leaves unnamed because a run has one handle. The effect record holds the operation with the bytes of a write, and the answer record holds a receipt in place of content, such as the number of bytes of a read ([The Engine](engine.md)). + ### A run's store ends with the run, and the files of its tools last as long as the Host's mounts A run's store is memory: it is empty when the run starts and is gone when the run ends, so no run finds a file of an earlier run in its store. The store of an executed prompt is gone sooner, when that prompt ends. A prompt that built a file returns the file's text, as in `return store.read('report.md')`. The files of a run's tools are in the mounts of the run's handle: a `MemoryBackend` drops with its handle, and the files below a `RealBackend::rooted` mount are in a real directory, which outlasts the run. Workshop builds a default `VfsRef` for each run, so the files of a Workshop run's tools exist in memory until the run ends, and Workshop's workspace document is a separate file ([Workshop: how the app is built](https://github.com/cppalliance/runvil-design/blob/master/decisions/workshop-app.md)). @@ -206,7 +210,7 @@ A run has one way in, its arguments, and one way out, its result. The owner's re ## 8. Planned work -- **A tool's file operations as effects.** Each file operation of a tool, a read as well as a change, as a `Vfs` effect that the Engine issues under the call's identity and the Harness performs and records. A tool call becomes an async function whose file methods return futures: the tool asks, its call waits, and a later step of the call receives the answer. The Write, StrReplace, and Delete tools of `std` and the writes of the `bash` shell arrive with it. Today contract 0.4 has file functions that stat, list, and read, each of which returns when its operation is done, a Rust Pack calls the `Access` of its call, and the record holds none of these operations ([Tools and Packs](tools-and-packs.md)). +- **The contract's file operations as effects.** Each file operation of a library Pack's tool, a read as well as a change, as a `Vfs` effect, as a request of a Rust Pack's tool is. A file function of the contract asks, its call waits, and a later step of the call receives the answer. The Write, StrReplace, and Delete tools of `std` and the writes of the `bash` shell arrive with it, and the `Access` of a call then leaves the `ToolCall` effect and the Rust API. Today contract 0.4 has file functions that stat, list, and read, each of which returns when its operation is done, the loader answers them from the `Access` of the call, and the record holds none of these operations ([Tools and Packs](tools-and-packs.md)). - **A database mount.** A mount would show an agent's run database as files. Its backend is synchronous like every other, so a backend over a database client with an async interface drives that client on a thread of its own. The backends that ship are `MemoryBackend` and `RealBackend`. - **Replay.** Replay would read a run's records back into a run, and a debugger would rebuild each store of a run from the same records, at any step. Today the Harness records each `Vfs` effect and its answer. - **Glob across mounts.** A glob would also search the backends mounted below the mount that matches its pattern. Today a glob runs inside that one mount and skips a backend mounted below it. diff --git a/decisions/harness-and-host.md b/decisions/harness-and-host.md index 3c0c589f9..2cb7b135a 100644 --- a/decisions/harness-and-host.md +++ b/decisions/harness-and-host.md @@ -122,7 +122,11 @@ The design sets a rule for every performer, which is a broker, a Pack, or a time ### The Harness answers each `Vfs` effect inline, on the thread that polls the run -A `Vfs` effect is one operation on a store of the run. A run has the store that it starts with, and one more for each `execute` ([Files and the VFS](files-and-the-vfs.md)). The loop performs the operation itself and resumes the run before it waits again. Store operations from different chains run one at a time, in the order the Engine issued them. The Harness reaches a run's store only to perform the one operation of a `Vfs` effect. It puts nothing in the store before a run and reads nothing from it after. +A `Vfs` effect is one file operation, and the effect says who asked for it: the prompt's Lua or a tool call ([The Engine](engine.md)). The loop performs the operation itself and resumes the run before it waits again. The operations run one at a time, in the order the Engine issued them, whichever chain or tool call asked for each. + +The prompt's Lua asks with a `store` call, and the operation works on a store of the run. A run has the store that it starts with, and one more for each `execute` ([Files and the VFS](files-and-the-vfs.md)). The Harness reaches a run's store only to perform the one operation of a `Vfs` effect. It puts nothing in the store before a run and reads nothing from it after. + +A tool call asks through the files of its context ([Tools and Packs](tools-and-packs.md)). The loop reads the requests of the calls in flight beside their answers and reports each one to the run with `Run::request_file`. The run issues the request as a `Vfs` effect that names the call, and the loop performs it on the file system of `RunSetup.vfs`, under the call's own identity and the Host's policy. The loop then resumes the run with a receipt of the outcome and hands the whole outcome to the call, which stays in flight throughout. A call that has landed or was dropped gets no further operation: the loop drops a request it still makes, and answers `Dropped`, unperformed, a `Vfs` effect that the run issued for it. A panic of the Host's policy or storage inside an operation reaches the tool as a failed operation, and the run goes on. The loop performs the operation itself because file operations are synchronous by design, so the call has nothing for the loop to wait on. The owner's reason: "all file I/O synchronizes the, the harness, and that's in line with our design. Our whole design of Runvil is a single-threaded. It's cooperative asynchrony." A store is memory. The owner's rule: "Every prompt starts with a, a memory store that's completely empty. And that's the only type of store there is. And it doesn't map to any file system path in the virtual file system." With no way in from outside, a run's result depends only on its prompt, its arguments, and its answers. @@ -184,7 +188,7 @@ A Host sees a run's events through its recorder: `append` is the only call in wh ### The Harness writes every event, effect, and answer in loop order -The loop writes a step's events before it starts the step's effects, each effect before its performer starts, and each answer before the run resumes with it. Every effect record has exactly one answer record, and a dropped effect's answer is `Dropped`. The loop also records an effect that the same step issued and withdrew. The records are the only view of a run's store outside the run: each `Vfs` effect record holds its operation, and its answer record holds the outcome, which is enough to rebuild the store. A recorder that returns an error stops its run. +The loop writes a step's events before it starts the step's effects, each effect before its performer starts, and each answer before the run resumes with it. Every effect record has exactly one answer record, and a dropped effect's answer is `Dropped`. The loop also records an effect that the same step issued and withdrew. The records are the only view of a run's store outside the run: each `Vfs` effect record holds its operation, and its answer record holds the outcome, which is enough to rebuild the store. The record of a `Vfs` effect that a tool call asked for names the call and holds the operation, with the bytes of a write. Its answer record holds a receipt, such as the number of bytes of a read, and the tool's own result is the answer record of its `ToolCall` ([The Engine](engine.md)). A recorder that returns an error stops its run. The loop records a withdrawn effect because each `Chat` record names an earlier round by id, in its `after` field. With every effect recorded, the `Chat` records of one message list, in record order, are exactly its sends, and every `after` names a recorded round. diff --git a/decisions/tasks-and-fanout.md b/decisions/tasks-and-fanout.md index 0eeddeb24..3cb085338 100644 --- a/decisions/tasks-and-fanout.md +++ b/decisions/tasks-and-fanout.md @@ -126,7 +126,7 @@ The cap is 8 because that is more depth than the owner expects a prompt to need ### The same seed, start time, and answers produce the same run -For each run the Harness generates a random seed, reads the clock, and passes both to the Engine in `RunParams`. With the same two values and the same answers in the same order, the Engine emits the same effects, events, and ids. The order of answers is an input. Among waiting tool calls, the Harness starts the one with the lowest effect id ([Tools and Packs](tools-and-packs.md)), and `Run` lacks a call that reports a start. That choice therefore affects the Engine only through the order of answers, so a replay (see Planned work) is independent of the Harness's start order. Three results depend on the order of answers: which task `tasks.join_any` returns, whether a timed wait runs out, and how far a canceled task got. The guide adds a fourth: where a `tasks.send` message applies in a task's work. +For each run the Harness generates a random seed, reads the clock, and passes both to the Engine in `RunParams`. With the same two values, and the same answers and file requests in the same order, the Engine emits the same effects, events, and ids. The order of answers is an input. So is the order of the file requests that the Harness reports for open tool calls, each of which the Engine issues as an effect at its next step ([The Engine](engine.md)). Among waiting tool calls, the Harness starts the one with the lowest effect id ([Tools and Packs](tools-and-packs.md)), and `Run` lacks a call that reports a start. That choice therefore affects the Engine only through the order of answers, so a replay (see Planned work) is independent of the Harness's start order. Three results depend on the order of answers: which task `tasks.join_any` returns, whether a timed wait runs out, and how far a canceled task got. The guide adds a fourth: where a `tasks.send` message applies in a task's work. Because of this rule, replay is a job for the Harness: the Engine is deterministic, so the Harness can match a recorded run exactly. The rule covers Lua's table walks too. The Engine's `pairs` and `next` walk a table in sorted order, where the order of stock Lua's walk depends on a hash seed. diff --git a/decisions/testing-and-debugging.md b/decisions/testing-and-debugging.md index 7ccf61168..84ee88b28 100644 --- a/decisions/testing-and-debugging.md +++ b/decisions/testing-and-debugging.md @@ -90,7 +90,7 @@ The fixtures exist because the inline tests leave a gap: a complete document, wr ### A Plugin crate tests its tools without a Harness, and the loader's tests load a fixture library -The `test-support` feature of `runvil-plugin` exports a helper for one test call, which owns a tool id, an access to a fresh in-memory file system, and an origin, and lends a `ToolContext`. The Rust Plugins `plugin-web` and `plugin-mcp` use it. It exists because the dependency rules refuse a `plugin-*` crate that names the facade or the file-system crate. +The `test-support` feature of `runvil-plugin` exports a helper for one test call, which owns a tool id, an access to a fresh in-memory file system, and an origin, and lends a `ToolContext`. The files of that context answer each request at once from the same file system, with no Harness in between. The Rust Plugins `plugin-web` and `plugin-mcp` use it. It exists because the dependency rules refuse a `plugin-*` crate that names the facade or the file-system crate. A Plugin that follows the C contract tests through the test support of the Plugin SDK, which the SDK's own `test-support` feature exports. It is a fake Host: it sends `RV_PLUGIN_LOAD` to the Plugin's entry point, sends `RV_PACK_NEW`, runs one tool call to its end, and supplies the file tree that the call reads. The fake Host checks each call that the Plugin makes back the way the loader does, so a Plugin that passes there loads in the Harness. The `std` Plugin and the bashkit Plugin test their tools this way. diff --git a/decisions/tools-and-packs.md b/decisions/tools-and-packs.md index a723cb1df..2564efb54 100644 --- a/decisions/tools-and-packs.md +++ b/decisions/tools-and-packs.md @@ -280,15 +280,15 @@ The Harness calls `new_pack` while it prepares the run, so a factory returns qui `Pack::tools` returns the Pack's tool list, which the Harness reads once per run. `Pack::call` performs one tool call. `Pack::ready` resolves when the tool list is complete. `Pack::render` shapes the offered tools for a model. -### `ToolContext` lends each call the tool id, a file access, and the call's origin +### `ToolContext` lends each call the tool id, its files, a file access, and the call's origin -`ToolContext::tool` returns the id of the called tool. `ToolContext::access` returns the call's file access, rooted at `/` of the file system that the Host gave the run. It reaches no store, so a tool sees no file that `store.write` wrote ([Files and the VFS](files-and-the-vfs.md)). `ToolContext::origin` says which section and which caller made the call. The context lends each of them only until the call ends, so the Rust compiler rejects a Pack that stores the access. +`ToolContext::tool` returns the id of the called tool. `ToolContext::files` returns the call's files, a `ToolFiles`: the call asks for one operation of the `VfsOp` list with `request` and awaits its `VfsOutcome`. `ToolContext::access` returns the call's file access, on which the call performs an operation itself. Both work under the call's own identity, on paths rooted at `/` of the file system that the Host gave the run. Neither reaches a store, so a tool sees no file that `store.write` wrote ([Files and the VFS](files-and-the-vfs.md)). `ToolContext::origin` says which section and which caller made the call. The context lends each of them only until the call ends, so the Rust compiler rejects a Pack that stores the files or the access. The owner's rule: "The tool can't keep the access. ... it has to give it up, after the call is done". A Rust Pack reads the services it needs at `install` and stores them in its factory. ### The rules that every `Pack::call` follows -1. Return to the poll quickly. A call sends blocking or CPU-heavy work to the Host's runtime, because the Harness polls every effect of a run on the same task. A file operation is the exception: it is synchronous by design, and the run waits for it. +1. Return to the poll quickly. A call sends blocking or CPU-heavy work to the Host's runtime, because the Harness polls every effect of a run on the same task. A call awaits a file operation that it asks for through its files, and the Harness performs it between two polls of the call. An operation on the call's access is the exception: it is synchronous by design, and the run waits for it inside the poll. 2. Report failure as an `Error`. The Harness answers a panicking call as `Dropped` and logs the panic. 3. Mark as untrusted any output that embeds data an attacker can influence. 4. Expect to be dropped. The Harness drops the call's future on a stop, on a cancel, and when the calling task ends. @@ -296,19 +296,23 @@ The owner's rule: "The tool can't keep the access. ... it has to give it up, aft ### A tool keeps nothing from one call that changes what a later call returns -A tool's result depends on the call's arguments, the run's files, and what the tool reaches outside the run. Whatever one call would leave for a later call goes into the run's files, and the record holds those once a tool's file operations are effects ([Files and the VFS](files-and-the-vfs.md)). A connection or a client that a Pack's factory shares between runs changes no result, so the rule leaves it alone. +A tool's result depends on the call's arguments, the run's files, and what the tool reaches outside the run. Whatever one call would leave for a later call goes into the run's files, and the record holds each change that a tool asks for through the files of its call ([Files and the VFS](files-and-the-vfs.md)). A connection or a client that a Pack's factory shares between runs changes no result, so the rule leaves it alone. The owner's rule: "Tools are not allowed to have internal states, and if they do, they have to be recorded." The reason is replay, which feeds each recorded tool result back to the Engine and runs no tool. The owner's words: "On a replay, the, the shell tool is not invoked. The shell tool never executes." A run that went on live after a replay would call a tool that holds none of the state its earlier calls left. The shell of the `bash` Pack is the one shipped tool that keeps such state today, and the owner has decided that each of its calls gets a shell of its own (see Planned work). -### File operations through the access are synchronous +### A tool asks for a file operation, and the Harness performs and records it -A Rust Pack's tool reads and writes files through the access of its `ToolContext`, and each operation runs inside the call and holds the run until it returns. File operations are synchronous by design, because the storage underneath is synchronous ([Files and the VFS](files-and-the-vfs.md)). The Harness is also independent of any particular async runtime, so each part of the context has to be independent of tokio. The shipped Rust Packs, `web` and `mcp`, leave the access unused. The shipped tools that touch files are in the library Plugins `std` and `bashkit`, and they read through the file functions of the contract, which the loader answers from the same access. +A Rust Pack's tool asks for a file operation through the files of its `ToolContext` and awaits the outcome. The Harness reports the request to the Engine, which issues it as a `Vfs` effect that names the call. The Harness performs the operation, records it and its answer, and wakes the call with the outcome ([The Harness and the Host API](harness-and-host.md)). The call stays in progress the whole time, and its one answer is still the tool's result. A request goes out when the call first polls it, the Harness performs the requests of one call in the order they went out, and it drops what a call that has ended still asks for. The owner's rule: "every VFS operation that's performed by a tool has to turn into an effect in the engine." + +The operation itself is synchronous, because the storage underneath is synchronous ([Files and the VFS](files-and-the-vfs.md)): the Harness performs it with one blocking call. The Harness is also independent of any particular async runtime, so each part of the context has to be independent of tokio. A request is a future that the Harness itself wakes, so a tool awaits it on any runtime. + +An operation on the access of the `ToolContext` runs inside the call, holds the run until it returns, and stays out of the record. The shipped Rust Packs, `web` and `mcp`, use neither the files nor the access. The shipped tools that touch files are in the library Plugins `std` and `bashkit`, and they read through the file functions of the contract, which the loader answers from the call's access (see Planned work). A long file job yields so that the Harness can cancel it. Grep, in the `std` library, ends its step after every 32 files or directories, or after 2 MiB read, so a stop or a cancel drops a long search between two steps. ### The run's mode policy decides each file change that a tool makes -A tool performs every file operation on the call's access, and the file system applies the run's mode policy to each one. In Ask mode it refuses each change, and in Plan mode it accepts changes to markdown paths. A `store` call is outside the policy, because the run's store is no part of the file system that tools work in. Workshop's runs use the file system's default policy, `AllowAll` ([Files and the VFS](files-and-the-vfs.md)). +Every file operation of a tool runs on the call's access, whether the Harness performs it for the tool or the tool performs it itself, and the file system applies the run's mode policy to each one. In Ask mode it refuses each change, and in Plan mode it accepts changes to markdown paths. A `store` call is outside the policy, because the run's store is no part of the file system that tools work in. Workshop's runs use the file system's default policy, `AllowAll` ([Files and the VFS](files-and-the-vfs.md)). The check is in the file system because every operation passes through the access, so the check covers every tool, including each tool written later. @@ -417,12 +421,12 @@ The Pack uses `rmcp`'s own HTTP client, which refuses redirects, so the client s Each of these items is still to be built. - **One Plugin API.** `plugin-web` and `plugin-mcp` written against the C contract and inserted with `insert_plugin`, so that a Pack compiled into the Host goes through the same contract as a Pack from a library and the two `install` functions, which is what both Plugins are, go away. The contract first needs what the two Packs use and contract 0.4 lacks: for `mcp`, a configuration for its list of servers, the call's origin, and the `describes_tools` flag, for `web`, the Host's search provider, and for both, the Host's runtime handle, a Pack inserted as unavailable with a reason, a call that waits on work outside its step, and error causes. -- **File operations as effects.** A tool call as an async function whose file methods return futures, so that each file operation of a tool, a read as well as a change, is an effect that the Harness records ([Files and the VFS](files-and-the-vfs.md)). A file function of the contract then asks for an operation, and a later step of the call receives the answer. The `std` tools Write, StrReplace, and Delete and the writes of the `bash` shell arrive with it. Today contract 0.4 has `file_stat`, `file_list`, and `file_read`, each of which returns when its operation is done, and the Rust API has the change operations on the call's file access, which the shipped Rust Packs leave unused. -- **The `std` tools that are stubs.** Write, StrReplace, Delete, and Glob, each of which answers a fixed text that says the tool is missing from this build. The first three wait for the file operations above. +- **The contract's file functions as requests.** A file function of the contract that asks for an operation, with the answer handed to a later step of the call, so that each file operation of a library Pack's tool, a read as well as a change, is an effect that the Harness records, as a Rust Pack's request through the files of its call is ([Files and the VFS](files-and-the-vfs.md)). The `std` tools Write, StrReplace, and Delete and the writes of the `bash` shell arrive with it, and the file access then leaves `ToolContext`. Today contract 0.4 has `file_stat`, `file_list`, and `file_read`, each of which returns when its operation is done, and the loader answers them from the call's file access, outside the run's record. +- **The `std` tools that are stubs.** Write, StrReplace, Delete, and Glob, each of which answers a fixed text that says the tool is missing from this build. The first three wait for the file functions above. - **Approval by a person.** The step that asks the operator to approve a file change. When the run's policy answers `Ask`, the file system refuses the operation with `VfsError::ApprovalRequired` and a reason, which a library Pack's tool receives as a denied file error with the same reason, and a run under Workshop cannot reach that error, because the shipped tools read files only and Workshop's runs use `AllowAll`. - **Ignore files.** Applying `.gitignore`, so that Grep skips a folder such as `target/` and spends its budget of 100,000 files elsewhere. Walks skip `.git` and names that contain a control character. - **A shell for each call.** Each `bash/shell` call with a new shell that starts at the root of the run's files, so the working directory, variables, and functions of one call end with it. The owner's reason: "Its the easiest to implement and doesn't expand the API surface." A shell that saves its state to a file of the run and loads it at its next call is a later step. Today a run has one session, which every call of the run shares. -- **Writing for the `bash` shell.** Shell commands that alter the run's files, which wait for the file operations above. +- **Writing for the `bash` shell.** Shell commands that alter the run's files, which wait for the file functions above. - **Undecided: a thread of its own for bash.** Bash on a thread of the Plugin's own, with a wake function in the contract. Bash runs inside the steps of its call, so a heavy script holds its step, and a stop with it, until the script ends or reaches one of bashkit's limits, and while a script sleeps the Host steps the call with nothing to do. The owner has yet to decide on it. - **Subagent tools.** The tools of `runvil/subagents`, and the wrapping of text that one model writes for another. The Pack only reserves its name. - **MCP in the Dynamic Set.** The `mcp` Pack rendering its servers' tools into the Dynamic Set, which retires its own two tools, along with local servers and OAuth. The Pack offers its own two tools, for remote servers. From 48ec63d02aa007e39eb3c74f8ed3a1705a0da753 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Tue, 17 Nov 2026 20:08:53 -0800 Subject: [PATCH 06/23] Run each call that changes files alone and in order The changes that one model reply asks for must apply one at a time, in the order the model listed them. `ToolInfo` gets the flag `changes_files`, `ToolBinding` copies it, and `dispatch_tool_calls` stops the batch before a call to a flagged tool, so the loop sends that call alone. - The new arm in `dispatch_tool_calls` uses the path of an adhoc call: a batch that stops short makes the loop send the next call alone. The scheduler gets no new state. - `bind` in `scope.rs` takes `changes_files` from the catalog for a catalog tool, as it takes `survives_stop`, so a render cannot change the flag. A tool that only a render names keeps the flag that the render gives it. - `ToolInfo` has no serde default for `changes_files`, so JSON without the key does not read back as a `ToolInfo`. The two tests that pin the JSON of a `ToolInfo` now hold the key. - `ToolBinding` and the fixture `FnTool` hold four flags each, and each expects `clippy::struct_excessive_bools` with a reason. - A flagged call is issued after every call listed before it has its answer, and the calls listed after it are issued after its own answer. The calls on each side of it still go out together. - A call that a script makes with `tools.call` is one call in each case, so the flag does not affect it. - The loader sets no flag. `pack-tests.rs` asserts that `changes_files` is false for the tools of a library Pack. - No shipped Pack sets the flag. Only the fixtures set it: `files/append` of `FilesPack` and `edit_tool`. - No test covers a flagged tool in the Dynamic Set. Plan: /plan/2026-11-16-1-tool-file-effects.plan.md --- .../plugin-loader/src/pack-tests.rs | 3 +- .../runner/tests/it/harness-files-order.rs | 197 ++++++++++++++++++ .../runner/tests/it/harness-files.rs | 75 ++++--- .../runner/tests/it/harness.rs | 7 +- crates/runvil-engine/public-api.txt | 2 + crates/runvil-internal/lua/src/bindings.rs | 23 +- .../runtime/src/execute/run/effect-tests.rs | 2 +- .../src/execute/scheduler/tool_call.rs | 13 +- .../runtime/src/execute/scope-tests.rs | 28 +-- .../runtime/src/execute/scope.rs | 1 + .../tests/parallel_tool_calls-changes.rs | 115 ++++++++++ .../src/execute/tests/parallel_tool_calls.rs | 5 +- .../runtime/src/test_support/tools.rs | 16 +- .../runvil-internal/types/src/tools-tests.rs | 15 +- .../runvil-internal/types/src/tools/info.rs | 29 ++- crates/runvil-plugin/src/lib.rs | 4 + crates/runvil-plugin/src/pack.rs | 3 + crates/runvil/public-api.txt | 2 + decisions/tools-and-packs.md | 12 +- 19 files changed, 491 insertions(+), 61 deletions(-) create mode 100644 crates/harness-internal/runner/tests/it/harness-files-order.rs create mode 100644 crates/runvil-internal/runtime/src/execute/tests/parallel_tool_calls-changes.rs diff --git a/crates/harness-internal/plugin-loader/src/pack-tests.rs b/crates/harness-internal/plugin-loader/src/pack-tests.rs index 6866ccddb..229a8a31b 100644 --- a/crates/harness-internal/plugin-loader/src/pack-tests.rs +++ b/crates/harness-internal/plugin-loader/src/pack-tests.rs @@ -92,7 +92,8 @@ fn an_instance_holds_the_tools_the_plugin_added_under_the_pack_id() { tools.iter().all(|tool| !tool.structured_output && !tool.survives_stop && !tool.describes_tools - && !tool.model_only_call), + && !tool.model_only_call + && !tool.changes_files), "the contract carries no tool flags" ); } diff --git a/crates/harness-internal/runner/tests/it/harness-files-order.rs b/crates/harness-internal/runner/tests/it/harness-files-order.rs new file mode 100644 index 000000000..8d2e6514f --- /dev/null +++ b/crates/harness-internal/runner/tests/it/harness-files-order.rs @@ -0,0 +1,197 @@ +//! The order of one reply's tool calls when a tool changes files: two +//! changes to one file both apply, in the order the model listed them; a +//! call listed before a change is answered before the change starts, and +//! one listed after it starts once the change is answered; and calls +//! that change no file are still in flight together. + +use std::collections::HashMap; +use std::sync::Arc; + +use harness_runner::RunSetup; +use harness_runner::recorder::{MemoryRecorder, Record, RecordKind}; +use runvil_engine::model::{Completion, CompletionResult, ToolCall}; +use runvil_engine::vfs::{Origin, VfsRef}; +use serde_json::{Value, json}; + +use super::files::files_host; +use super::{PendingTimer, launch, setup}; +use crate::scripted::{MODEL, ScriptedBroker, reply}; + +/// A prompt that offers the fixture Pack's reader and its changing tool +/// to one model loop and returns once the loop ends. +const LOOPS: &str = "---\nname: orders\ndescription: d\nrunvil: 0\n\ + uses:\n - tests/files\n---\n\n\ + ## Only\n\n```lua\n\ + tools.offer('files/cat')\n\ + tools.offer('files/append')\n\ + messages:user('go')\n\ + models.loop()\n\ + return 'done'\n```\n"; + +/// The reader's wire name, as the model calls it. +const CAT: &str = "files_cat"; + +/// The changing tool's wire name, as the model calls it. +const APPEND: &str = "files_append"; + +/// A broker whose model asks for `calls` in its first round, each a +/// tool's wire name beside its arguments, and replies with text in every +/// later round. +fn asking(calls: Vec<(&'static str, Value)>) -> ScriptedBroker { + ScriptedBroker::new(move |round, _messages| { + let calls = calls.clone(); + Box::pin(async move { + if round.id.get() > 0 { + return reply("done"); + } + let calls = calls + .into_iter() + .enumerate() + .map(|(index, (name, args))| ToolCall::from_parts(format!("c{index}"), name, args)) + .collect::, _>>()?; + Completion::from_result(CompletionResult::ToolCalls(calls), MODEL).map(Box::new) + }) + }) +} + +/// When each tool call of `records` started and ended, in record order: +/// `start