sjw1231
cc2718bede
A new Agent Note owns the shipped defaults and the original apply_patch note keeps its opt-in decision with a supersession link; the policy README, the tool-catalog note, the filesystem page, and the fs group README state the current defaults without evaluation figures. The PTC overlay sets `applyPatch: false` so the SDK and Desktop PTC tool sets match without a parity exception; the fixed-budget compaction scenarios pin the tool set in their live patches too; the apply-patch composition drops its no-op override. The upgrade guide scopes the change to base-backed profiles, the README refusal example is one every composition can produce, the integration suite names its deployments by guard, and the keyless SDK smoke edits a file the model never read through the shipped profile.
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, optionally 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.