Turtle
7c385c957c
# Conflicts: # .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml # apps/web/tsconfig.json # packages/client/ui-tool/README.i18n.yaml # packages/client/ui-tool/README.md # packages/client/ui-tool/README.zh.md # packages/client/ui-tool/src/client/tool/models/raw-tool-call.ts # packages/client/ui-tool/tests/diff-card.client.spec.tsx # packages/client/ui-tool/tests/terminal-card.client.spec.tsx # packages/fs/tool-fs-search/README.i18n.yaml # packages/fs/tool-fs/README.i18n.yaml # packages/fs/tool-fs/README.md # packages/fs/tool-fs/README.zh.md # packages/fs/tool-fs/src/sandbox.ts # packages/goal/tool-goal/README.i18n.yaml # packages/goal/tool-goal/tests/tool-goal.spec.ts # snapshots/session/headless.snapshot.ts # tsconfig.host.json
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) 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
Seven packages play the filesystem roles; 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-local/ |
Host-filesystem backend: reads, writes, and edits real files on the local machine | registers on ctx.fs |
fs-sandbox/ |
Sandbox-enforcing backend: fences writes and edits 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 write/edit through the fs/* events |
fs/* listeners |
tool-fs/ |
Model-facing read, read_image, write, and edit 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.