diff --git a/decisions/files-and-the-vfs.md b/decisions/files-and-the-vfs.md index 8ef5f8b50..a277d85e2 100644 --- a/decisions/files-and-the-vfs.md +++ b/decisions/files-and-the-vfs.md @@ -144,7 +144,7 @@ An operation on the files of the run's handle makes no claim and checks none, wh 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 the prompt's 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 a claims table knows the run's own identities alone. -The record of a run stays whole without the check, because each operation that a tool asks for through the files of its call is a recorded effect that the Harness performs in order (see the entry on a tool's file request). 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 list of operations has `StrReplace`, which replaces a text in one step, and a Rust Pack can ask for it. The C contract has no function for it, so the tools of `std` and `bash` cannot, and whether to add one is the owner's to decide. +The record of a run stays whole without the check, because each operation that a tool asks for through the files of its call is a recorded effect that the Harness performs in order (see the entry on a tool's file request). 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 ([runvil-plugin-std issue 4](https://github.com/cppalliance/runvil-plugin-std/issues/4)). The list of operations has `StrReplace`, which replaces a text in one step, and a Rust Pack can ask for it. The C contract has no function for it, so the tools of `std` and `bash` cannot, and whether to add one is the owner's to decide. The claims code stays in `runvil-vfs` with its tests, and only that crate can make a handle check claims, which a store does. The check on the Host's files can therefore return. diff --git a/decisions/tools-and-packs.md b/decisions/tools-and-packs.md index 4a785a414..8deda8eab 100644 --- a/decisions/tools-and-packs.md +++ b/decisions/tools-and-packs.md @@ -374,7 +374,7 @@ Loading happens in the Harness, and the Engine receives data: the tool catalog, `std` is a library Plugin. Its code is in the `runvil-plugin-std` repository, written against `runvil-plugin-sdk`, and Workshop loads its library from the Plugin directory ([Workshop: how the app is built](https://github.com/cppalliance/runvil-design/blob/master/decisions/workshop-app.md)). `std/read`, `std/dir`, `std/grep`, `std/write`, `std/replace`, and `std/rm` work, and `std/glob` answers a fixed text that says the tool is missing from this build. The model sees Cursor's names, such as `Read`, `Grep`, and `StrReplace`. The tool definitions are Cursor's with a recorded list of edits, except ListDir's, which is the crate's own. -Write, StrReplace, and Delete change the run's files, and each sets `changes_files`, so the Engine runs each of their calls alone, in the order the model listed them (see Tool calls). Write makes a file, or replaces the whole content of one, with one write, and the Host makes each absent directory on the way to the file. It refuses contents over 16 MiB, the most that one write of the contract takes. StrReplace reads a file and writes it back with one text in place of another. It refuses a directory and a file over 16 MiB, as Read does, the file must hold UTF-8 text, and the text to replace must occur exactly once unless the call sets `replace_all`. A failure states how many times the text occurs. The edit is a read and then a write, because the contract has no function that replaces text in one step, so it can lose a change that another task makes to the file between the two ([Files and the VFS](files-and-the-vfs.md)). Delete removes a file, or a link and not what the link leads to, and it refuses a directory. It asks what the path names before it asks for the removal, because the removal of the contract also takes an empty directory. +Write, StrReplace, and Delete change the run's files, and each sets `changes_files`, so the Engine runs each of their calls alone, in the order the model listed them (see Tool calls). Write makes a file, or replaces the whole content of one, with one write, and the Host makes each absent directory on the way to the file. It refuses contents over 16 MiB, the most that one write of the contract takes. StrReplace reads a file and writes it back with one text in place of another. It refuses a directory and a file over 16 MiB, as Read does, the file must hold UTF-8 text, and the text to replace must occur exactly once unless the call sets `replace_all`. When the text occurs zero times, or more than once without `replace_all`, the failure states how many times it occurs. The count is of the occurrences that do not overlap, taken from the start of the file, and a call with `replace_all` replaces those. A text that starts at more than one place does not occur once, even where the places overlap, as `ana` starts at two places in `banana`. When the count for such a text is one, a call without `replace_all` is refused with a sentence that says the text starts at more than one place, and that failure states no count. StrReplace refuses an edit that would leave the file over 16 MiB, the most that one write takes, and it refuses before it builds the edited text, because a call with `replace_all` could otherwise ask for far more memory than the file and its arguments hold. The edit is a read and then a write, because the contract has no function that replaces text in one step, so it can lose a change that another task makes to the file between the two ([Files and the VFS](files-and-the-vfs.md), [runvil-plugin-std issue 4](https://github.com/cppalliance/runvil-plugin-std/issues/4)). Delete removes a file, or a link and not what the link leads to, and it refuses a directory. It asks what the path names before it asks for the removal, because the removal of the contract also takes an empty directory. The two are requests of their own, so a directory with no entries that another task puts at the path between them is removed. A directory with entries is never removed. A removal in the contract that takes a file only would close that gap ([runvil-plugin-std issue 3](https://github.com/cppalliance/runvil-plugin-std/issues/3)). The Pack copies Cursor's text because the model was trained against that exact text, and a stored copy can be diffed against Cursor's. A stub answers as a success so that calls to the Pack exercise both success and failure from end to end. Walks skip `.git` and list the other dotfiles, because a model often needs to edit `.gitignore` and similar files. A walk leaves out a name that contains a control character and counts it, because a line feed in a name would forge a line of the answer. The shell is in a Pack of its own, `bash`, so a run that wants a shell declares it. @@ -442,6 +442,8 @@ Each of these items is still to be built. - **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. - **Shell state that lasts across calls.** A shell that saves its state to a file of the run and loads it at its next call. Each `bash/shell` call builds a new shell, so the working directory, variables, and functions of one call end with it. - **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. +- **Undecided: a removal that takes a file only.** A removal in the contract that refuses a directory, so that Delete needs no stat before it ([runvil-plugin-std issue 3](https://github.com/cppalliance/runvil-plugin-std/issues/3)). Delete asks what the path names and then asks for the removal, so a directory with no entries that another task puts at the path between the two is removed. The owner has yet to decide on it. +- **Undecided: an edit that keeps another task's change.** A way in the contract for a tool to edit a file without losing a change that another task makes to it, such as an edit as one operation or a write that fails when the file changed since the read ([runvil-plugin-std issue 4](https://github.com/cppalliance/runvil-plugin-std/issues/4)). StrReplace reads a file and then writes it back, so a change that another task makes to the file between the two is lost. 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`, `model_only_call`, and `changes_files`.