sjw1231
8f798da97d
Drop the preflight sandbox fence. It derived writable roots in the local process, so under the SSH provider it threw on remote additionalWritableRoots and compared remote targets against local temp roots; write and edit never fenced in the tool layer. The provider now refuses a denied operation at commit, and a commit whose first operation failed without any change rejects like a preflight refusal so the sandbox escalation path keeps its error code. Classify FS_ABORTED as unknown: a cancelled remote request rejects while the provider may still be writing, so no stat comparison can settle it. Document that a cancelled call receives the registry's abort result like every tool. Store no diff for creations, matching write, and bound the move source basis by diffBasisMaxBytes so persisted metadata never holds whole files; FsMoveOutcome.sourceBefore becomes nullable. Omit deletions from the call preview and from result diffs without a basis instead of rendering them as empty creations, and count distinct files in the preview title. Reject a NUL byte beyond the read sampling window in preflight, name targets by display path in atomic-write diagnostics, align the apply_patch guidance with the edit wording and mention delete and move, read the stopped flag and applied diffs tool-agnostically in the client models, skip the permission-bit snapshot under root, list fs/delete-intent in the tool catalog, and refresh the fs-patch description, group README, fs-sandbox summary, and ui-tool README.
3.8 KiB
description, kind
| description | kind |
|---|---|
| The filesystem package group: the ctx.fs provider contract, local and sandbox-enforcing backends, the read-before-edit policy plugin, and the model-facing file and search tools. | package-group |
packages/fs
English | 中文
Summary
The fs/ group gives agents durable, policy-governed access to files: the ctx.fs service contract in fs/, the host-filesystem and sandbox-enforcing backends in fs-local/ and fs-sandbox/, the read-before-edit policy in fs-observation-policy/, and the model-facing tools in tool-fs/ (read, read_image, write, edit, apply_patch) and tool-fs-search/ (glob, grep). A deployment mounts one backend, loads the policy for freshness-guarded mutations, and registers the tool packages the model should see; backends swap without touching the tools or the policy. File I/O takes no timeout by design: a deadline would kill work the OS still finishes, so cancellation is a best-effort signal at syscall boundaries.
Table of Contents
Packages
The packages below provide filesystem access and patch parsing; the subsystem reference owns the exhaustive contracts and the error taxonomy.
| Package | Role | ctx key |
|---|---|---|
fs/ |
ctx.fs service contract: execution-world paths, bounded text I/O, and atomic mutations with an optional version guard |
ctx.fs |
fs-patch/ |
Pure Codex-style patch parsing and hunk application | none |
fs-local/ |
Host-filesystem backend: reads, writes, edits, patches, deletes, and moves real files on the local machine | registers on ctx.fs |
fs-sandbox/ |
Sandbox-enforcing backend: fences every mutation by the per-call sandbox mode while reads pass through | registers on ctx.fs |
fs-observation-policy/ |
Read-before-edit policy: records observed presence or absence and guards mutations through the fs/* events |
fs/* listeners |
tool-fs/ |
Model-facing read, read_image, write, edit, and apply_patch tools plus their executor |
registers on ctx.tools |
tool-fs-search/ |
Model-facing glob and grep discovery tools backed by the packaged ripgrep binary |
registers on ctx.tools |
tool-str-replace-editor/ |
Standalone str_replace_editor tool: view, create, str_replace, and insert over ctx.fs |
registers on ctx.tools |
The policy is a plugin, not a service the tools inject: removing it leaves the bare provider's unconditional mutation behavior instead of breaking the tools. The mode fence in fs-sandbox and the read-before-edit gate compose. tool-fs-search deliberately does not extend the provider contract — search is a process-backed ripgrep workflow, so filesystem backends stay free of a universal search API.
Related documentation
Start with the subsystem reference for the shared vocabulary and error taxonomy, then the decisions that shaped the family.
- Filesystem subsystem — targets, outcomes, guards, policy events, and the error taxonomy.
- Cross-family fs sandbox reference — the shared sandbox mode fence over the filesystem seam.
- Portable execution world consumers decision — why filesystem and subprocess providers share one execution world.
Dev Note
Working context for maintainers — click to expand
None.