description: "The model-facing read, read_image, write, and edit tools for users and maintainers composing or debugging filesystem access for agents."

kind: "package-reference"

@deepseek-ai/dsh-tool-fs

English | 中文

Summary

Use dsh-tool-fs to let a model read UTF-8 files with line numbers, read supported images, create or atomically replace files, and apply targeted literal edits. Results are capped, and failures provide stable error codes and recovery instructions. Add dsh-fs-observation-policy when writes and edits must follow a successful read; without it, mutations remain atomic but are unconditional. Image reads require durable attachment storage and an image-capable routed model. Choose the sibling discovery package for glob or grep searches.

Use this package
Understand the implementation
Further Exploration
Model Experience
Known Limitations and Deferred Work
Dev Note

Use this package

Mount the tools after a ctx.fs backend and, for read-before-write/edit behavior, the policy plugin. The model then gets line-numbered reads, atomic writes and edits, and — with an attachment store mounted — image reads; every result is capped, and failures carry stable codes with recovery instructions.

Minimal composition

A backend, the policy plugin, then the tools; the attachment store is optional and enables read_image.

- name: '@deepseek-ai/dsh-fs-local'
- name: '@deepseek-ai/dsh-fs-observation-policy'
- name: '@deepseek-ai/dsh-tool-fs'

The policy plugin is optional: without it the tools run against the bare provider (unconditional write, overwrite, and edit with no observed-state). A deployment that loads these tools is expected to also load it, so the behavior is read-before-write/edit. read_image registers only while a durable ctx.attachments service is mounted; execution additionally refuses on a route whose exact model does not declare image input, so a text route's durable history stays free of image blocks.

The tools

Tool	Arguments	Behavior
`read`	`file_path`, `offset?`, `limit?`	Line-numbered UTF-8 content with a pagination footer; `offset` is 1-based and `limit` defaults to and caps at the configured `readLimit`
`read_image`	`file_path`	Reads and persists a PNG/JPEG/WebP/GIF source; an extension-less path (normalized attachment object paths included) is identified from its file signature; normalization can downscale it before the next model request, so the model need not create a thumbnail first
`write`	`file_path`, `content`	Creates or fully replaces a file; with the policy plugin, overwriting requires a prior `read` at the unchanged version, creating does not
`edit`	`file_path`, `old_string`, `new_string`, `replace_all?`	Literal replacement requiring a unique match unless `replace_all` is true; with the policy plugin, requires a prior `read` and an unchanged file

Field names are snake_case to match Claude Code and existing harness tool schemas. Successes return compact envelopes — a read window, an image reference, or a Created file/Updated file confirmation — and write/edit derive replayable diff-card metadata for UI presentation.

Configuration

All keys are optional; the defaults are the shipped read caps.

Key	Default	Meaning
`readLimit`	`2000`	Default and maximum lines returned by one `read` call
`readMaxLineLength`	`2000`	Characters kept per line before truncation
`readMaxBytes`	`51200`	Byte cap on one `read` call's selected lines; overflow ends the window with a capped footer
`readStreamMinSize`	`10485760`	Files at or above this size (or of unknown size) stream instead of loading whole into memory

The generated configuration catalog is the exhaustive source for every accepted field and its JSDoc.

Policy and sandbox behavior

Path authorization for read and read_image belongs entirely to ctx.fs; media-type declarations and file signatures only decide whether read_image accepts the bytes returned by that backend.

With the policy plugin mounted, write and edit obtain their guard from the fs/* intent slots, so an unread target or a stale observation fails with FS_NOT_OBSERVED or FS_STALE_VERSION and a recovery instruction. Under a confining backend (fs-sandbox), write/edit additionally advertise sandbox_permissions and justification; a denied mutation returns the [sandbox: file access denied under <mode> mode] marker with the same-turn escalation hint, and an approved retry may stamp a strictly wider mode for that one call.

Failures and recovery

Failures are normalized as Error: <message> with a structured code preserved for callers. Stable messages include file_path must be a non-empty string, limit must be less than or equal to <max>, cannot read "<path>": not found, cannot read "<path>": not a regular file, and the image-route refusal cannot read "<path>" as an image: model "<model>" does not declare image input; switch to an image-capable model to read images. FS_NOT_OBSERVED is normalized to cannot modify "<path>": file has not been read — read the file, then retry, independent of whether the policy or provider rejected the operation; FS_STALE_VERSION retains the provider's reason and appends — re-read the file, then retry. After the reread confirms absence, edit reports FS_NOT_FOUND instead of repeating a stale remedy, while write uses guarded creation.

Understand the implementation

Implementation internals — click to expand

This section explains the design decisions behind the tool suite and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package). ### Design concept The tools are the executor; policy is an event gate. The tools inject no policy service and inspect no cache — each mutation asks the single intent slot for its guard through `ctx.waterfall`, and each operation emits `fs/observed` only after it succeeded. Reads do exactly one provider `stat` (type and size routing plus the observed version); mutations do none, because the guard comes from the intent slot and the provider re-checks under its lock. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: `Config`, tool composition, `read_image` attachments gate | | [`src/read.ts`](src/read.ts) | `read` executor: one stat, streaming decision, window build, observation | | [`src/read-image.ts`](src/read-image.ts) | `read_image` executor: route and media-type gates, bounded bytes, attachment save | | [`src/write.ts`](src/write.ts) | `write` executor: intent waterfall, atomic write, observation | | [`src/edit.ts`](src/edit.ts) | `edit` executor: intent waterfall, literal edit, observation | | [`src/read-render.ts`](src/read-render.ts) | Cordis-free windowing and envelope formatting | | [`src/sandbox.ts`](src/sandbox.ts) | Escalation API shared by `write`/`edit`: policy resolution and denial-marker mapping | | [`src/error.ts`](src/error.ts) | Stable model-facing diagnostics for guarded-mutation failures | ### Per-tool flow All four tools share one flow shape: resolve the path with the calling session's cwd, run the applicable gate, perform exactly one provider operation, and emit `fs/observed` only after success. `read` and `read_image` pay one `stat` for type and size routing; `write` and `edit` pay none because their guard comes from the intent slot, and provider failures surface as typed `FsError` results. The per-tool executors live in `src/read.ts`, `src/read-image.ts`, `src/write.ts`, and `src/edit.ts`. ### Observation and concurrency `fs/observed` fires after the operation succeeded via a plain `ctx.emit`; a listener is contractually a synchronous, side-effect-only recorder, so async or fallible observation does not belong on this event. `read` opts into concurrent scheduling because its only mutation is the synchronous version recorder; recorder races fail closed when a later `write` or `edit` re-checks the version under its target lock, and both mutation tools remain exclusive.

Further Exploration

Read these pages when the package-level contract is not enough. They move from the tools to the contract, backends, and policy they compose with.

Filesystem subsystem — exhaustive provider contract, policy events, and error taxonomy.
dsh-fs — the ctx.fs contract these tools consume.
fs-local — the host-filesystem backend these tools run against.
fs-sandbox — the sandbox-enforcing backend that adds the escalation fields.
fs-observation-policy — the policy plugin that guards mutations through the fs/* events.
Generated tool catalog — the exhaustive schemas this package registers.

Model Experience

System prompt

What the model sees

At assembly time, each guidance section checks ctx.tools.get(name, scope) and renders only while its tool is visible to that agent. The write paragraph recommends edit only while edit is visible. The text below is unchanged when all three tools are available; restrictions, their removal, and tool registration changes take effect on the next assembly. The same check works for direct agent restrictions and subagent toolFilter, including PTC capabilities behind run_code. The read-before-mutation sentences in write/edit describe the observation policy, not a requirement to invoke the tool named read. They remain when read is hidden: the policy still guards mutations, and another observing operation, such as str_replace_editor with command: view, can establish the same file observation. Tool visibility does not disable that precondition.

Read guidance

Use the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.

Write guidance

Use the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-observation-policy requires it) and prefer edit for targeted changes.

Edit guidance

Use the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-observation-policy requires it), unless you just created or edited it in this session.

Token effect

Only a failing call adds these retained tokens.

KV Cache effect

Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.

Known Limitations and Deferred Work

These limits define when the tool suite is a poor fit or needs special operational care. They are current package constraints, not a general filesystem comparison or a task backlog.

No model-facing directory listing ships — ctx.fs.listDir serves provider code such as skill discovery, while the sibling dsh-tool-fs-search package supplies ripgrep-backed glob and grep rather than extending the filesystem seam.
read handles UTF-8 text files only — images use the separate read_image tool; PDF, audio, and video remain deferred. A directory target is FS_NOT_REGULAR_FILE.
Extension-declared media type — an extension selects the declared type and the attachment store's magic-byte validation stays authoritative; a correctly formatted image under a wrong extension is refused with the rename remedy rather than sniffed. Only a path with no extension is identified from its file signature.
Object paths re-enter source admission — read_image on a normalized attachment object re-admits its bytes as a new source, so a deployment whose maxImageBytes/maxMessageImageBytes sit below the normalized-image byte budget can refuse an object path that ctx.attachments.readImage still serves; shipped defaults keep the normalized budget (4 MiB) far under the source caps (20 MiB).
Inline image preview rides the UI composition — the tool-result card renders the image through the browser's tool.call.images slot, which the attachment presentation plugin fills; a UI without that plugin shows the result's envelope text instead.
No attachment-region tool — an agent may crop an image through another available tool when it has a filesystem path; a pasted or dragged image without a path cannot be re-read at higher resolution.
No timeout surface — read/write/edit take no timeout argument and declare no timeout budget; cancellation rides exec.signal only (provider rationale).

Dev Note

Working context for maintainers — click to expand

None.

Runtime invariant: No companion is published. This model-facing adapter has no independent lifecycle stream; execution relations are owned by the capability seam it calls.

README.md 19 KB パーマリンク 履歴 Raw

kind: "package-reference"

@deepseek-ai/dsh-tool-fs

Summary

Table of Contents

Use this package

Minimal composition

The tools

Configuration

Policy and sandbox behavior

Failures and recovery

Understand the implementation

Further Exploration

Model Experience

System prompt

What the model sees

Read guidance

Write guidance

Edit guidance

Token effect

KV Cache effect

Tool schemas

What the model sees

Token effect

KV Cache effect

Read result

What the model sees

Token effect

KV Cache effect

Image read result

What the model sees

Token effect

KV Cache effect

Write and edit results

What the model sees

Token effect

KV Cache effect

Tool errors

What the model sees

Token effect

KV Cache effect

Known Limitations and Deferred Work

Dev Note

README.md 19 KB

パーマリンク履歴 Raw