@deepseek-ai/dsh-tool-fs 0.0.1-rc.1 → 0.0.1-rc.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/tool-fs/README.md
-README.md: 27b53aca50f470fe9ead4da27d87328264440ff7
-README.zh.md: 5bcf9c471d933702c46d50c56c9539cb9eede3ca
+README.md: 7e334f886747cd8dc566a572c699cd80c7cf62fe
+README.zh.md: b5eb5ae38aba049d77375d31d1509342a23f13fc

package/README.md

@@ -2,17 +2,20 @@
 
 English | [中文](README.zh.md)
 
-The **model-facing filesystem tools** — `read`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, and result formatting. It reads/writes/edits through the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) **directly**. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. Under a confining provider, the shared sandbox-policy service is required for per-session execution and the tool exposes escalation for filesystem mutations.
+The **model-facing filesystem tools** — `read`, `read_image`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, and result formatting. It reads/writes/edits through the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) **directly**. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. Under a confining provider, the shared sandbox-policy service is required for per-session execution and the tool exposes escalation for filesystem mutations.
 
 ```ts ignore-check
 // Default deployment: a ctx.fs provider, the policy plugin, then the tools.
 await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) // @deepseek-ai/dsh-fs-local
 await ctx.plugin(FsPolicy)                             // @deepseek-ai/dsh-fs-policy (policy gate)
-await ctx.plugin(ToolFs)                                  // this package — registers read/write/edit
+await ctx.plugin(LocalAttachmentStore, { dshHome })       // optional — enables durable read_image results
+await ctx.plugin(ToolFs)                                  // this package — read/write/edit, plus read_image with attachments
 ```
 
 `@deepseek-ai/dsh-fs-policy` is **optional**: omit it and the tools run against the bare provider (unconditional write/overwrite/edit, 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 — without one the deployment cannot commit image bytes, so the tool never appears. Execution additionally requires the exact routed model to declare `image` input (resolved through `ctx.llm.resolveModelInfo` from the session's latest request header, falling back to agent options); an unknown or text-only route gets a refusal result before any filesystem I/O, so a text route's durable history stays free of image blocks.
+
 ## Config
 
 All keys are optional; the defaults are the shipped read caps.
@@ -29,18 +32,20 @@ All keys are optional; the defaults are the shipped read caps.
 | Tool | Arguments | Behavior |
 |---|---|---|
 | `read` | `file_path`, `offset?`, `limit?` | Line-numbered UTF-8 content with a pagination footer. `offset` is 1-based; `limit` defaults to and caps at the configured `readLimit` (2000). |
+| `read_image` | `file_path` | Reads a PNG/JPEG/WebP/GIF file through the bounded byte seam, persists it through `ctx.attachments.saveImage`, and returns an image block beside a small metadata envelope. It succeeds only when the exact routed model declares image input. |
 | `write` | `file_path`, `content` | Create or fully replace a file. With the policy plugin: overwriting an existing file requires a prior `read` at the unchanged version; creating a new file does not. Without it: unconditional. |
 | `edit` | `file_path`, non-empty `old_string`, `new_string`, `replace_all?` | Literal replacement; unique match required unless `replace_all` is true. With the policy plugin: requires a prior `read` (any window) and the file unchanged since. Without it: unconditional. |
 
 Field names are snake_case to match Claude Code and existing harness tool schemas.
 
-Canonical successes are `read` → `{ path, offset, lines: [{ number, text }], totalLines }`, `write` → `{ path, operation: 'create' | 'update', before: string | null, after }`, and `edit` → `{ path, before, after }`. Native renderers preserve the line-numbered read and mutation acknowledgements below. `write`/`edit` derive replayable diff-card metadata, and `read` derives a replayable read-card window `{ path, offset, lines, totalLines, lang? }`, from these canonical values; the canonical values themselves are execution-local and are not added to `tool/result`, only the derived presentation metadata is persisted.
+Canonical successes are `read` → `{ path, offset, lines: [{ number, text }], totalLines }`, `read_image` → `{ path, image: { attachmentId, mediaType, bytes, width, height, name? } }`, `write` → `{ path, operation: 'create' | 'update', before: string | null, after }`, and `edit` → `{ path, before, after }`. Native renderers preserve the line-numbered read and mutation acknowledgements below. `write`/`edit` derive replayable diff-card metadata, and `read` derives a replayable read-card window `{ path, offset, lines, totalLines, lang? }`, from these canonical values; the canonical values themselves are execution-local and are not added to `tool/result`, only the derived presentation metadata is persisted.
 
 ## The tool is the executor; policy is an event gate
 
 The tools do **not** inject a policy service or inspect any cache. Each tool resolves the path via `ctx.fs.resolve(path, { cwd, signal })` — passing the calling agent's session cwd (`exec.agent.session.header.cwd`) so a relative path resolves against the session's workspace, matching `dsh-tool-bash`, and forwarding tool cancellation through resolution (see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)) — then:
 
 - **read** — one `ctx.fs.stat` (type + size routing + version), then `readText`/`streamText`, then builds the line window, then emits `fs/observed` with a plain `ctx.emit`. (1 stat.)
+- **read_image** — validates the argument, extension, attachment availability, deployment media types, and the image-capable route before any I/O; then one `ctx.fs.stat` (recording an `absent` observation for a missing target, like `read`), a bounded `ctx.fs.readBytes` capped at the smaller of `imageLimits.maxImageBytes` and `imageLimits.maxMessageImageBytes` (the result is one message carrying one image), `attachments.saveImage` (content-addressed, so the image block references a durably committed object by the time `tool/result` is appended), and finally `fs/observed`. (1 stat.)
 - **write** — `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` for the optional guard, then `ctx.fs.writeText(target, content, intent)`, then `fs/observed`. (0 stat.)
 - **edit** — `ctx.waterfall('fs/edit-intent', target, exec, () => undefined)` for the optional guard, then `ctx.fs.editText(target, edit, intent)`, then `fs/observed`. (0 stat.)
 
@@ -50,11 +55,11 @@ When `ctx.fs.sandboxMode` reports confinement, write/edit advertise `sandbox_per
 
 ## `fs/observed` is fire-and-forget
 
-`fs/observed` fires AFTER the read/write/edit already succeeded, via a plain `ctx.emit`. A listener is contractually a synchronous, side-effect-only recorder (`@deepseek-ai/dsh-fs-policy`'s is a `WeakMap.set`); the tool does not guard the emit, so a listener that throws would surface as the tool's `isError` result — async or fallible observation does not belong on this event.
+`fs/observed` fires AFTER the read/read_image/write/edit already succeeded, via a plain `ctx.emit`. A listener is contractually a synchronous, side-effect-only recorder (`@deepseek-ai/dsh-fs-policy`'s is a `WeakMap.set`); the tool does not guard the emit, so a listener that throws would surface as the tool's `isError` result — 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; both mutation tools remain exclusive. See the [parallel tool-call Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md).
 
-The package root exports only the Cordis plugin contract (`name`, `inject`, `Config`, and `apply`). Read rendering (line windowing + output formatting) lives in `src/read-render.ts` (Cordis-free, independently unit-tested); `src/read.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them.
+The package root exports only the Cordis plugin contract (`name`, `inject`, `Config`, and `apply`). Read rendering (line windowing + output formatting) lives in `src/read-render.ts` (Cordis-free, independently unit-tested); `src/read.ts`/`read-image.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them.
 
 ## Model Experience
 
@@ -94,7 +99,7 @@ Prefix-stable while the plugin scope and guidance text are unchanged. Tool restr
 
 #### What the model sees
 
-The model sees the generated [`read`, `write`, and `edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs), with snake_case arguments. Scoped tool restrictions can remove any definition for one agent.
+The model sees the generated [`read`, `read_image`, `write`, and `edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs), with snake_case arguments. `read_image` appears only while a durable attachment store is mounted; the schema itself is route-independent, and the strict gate refuses at execution. Scoped tool restrictions can remove any definition for one agent.
 
 #### Token effect
 
@@ -118,6 +123,20 @@ Read output is capped by `readLimit`, `readMaxLineLength`, and `readMaxBytes`; t
 
 Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
+### Image read result
+
+#### What the model sees
+
+A successful `read_image` returns `<path><displayPath></path>`, `<type>image</type>`, and a `<content>` envelope naming the media type, dimensions, and byte size, followed by the image itself as a native image block. The session log stores only the durable `sha256:` attachment reference; the routed provider re-reads and digest-verifies the bytes on each request.
+
+#### Token effect
+
+The image is billed on every later request until compaction. Each call is independently bounded by the attachment store's `maxImageBytes`/`maxImagePixels`; repeated successful calls accumulate history, and content addressing deduplicates only the stored bytes, not the per-request token cost.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ### Write and edit results
 
 #### What the model sees
@@ -136,7 +155,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, and `offset <offset> is out of range for "<path>" (<total> lines)`; provider and policy templates are quoted in their package READMEs. Guarded-mutation failures additionally carry their recovery instruction in the message, appended by this package's model-facing error wrapper: `FS_STALE_VERSION` gets `— re-read the file, then retry`, and `FS_NOT_OBSERVED` gets `— read the file, then retry`; the structured code is preserved. After that reread confirms absence, edit reports `FS_NOT_FOUND` instead of repeating a stale remedy, while write uses guarded creation.
+Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, `offset <offset> is out of range for "<path>" (<total> lines)`, `cannot read "<path>": read_image only accepts PNG/JPEG/WebP/GIF paths`, `cannot read "<path>" as an image: model "<model>" does not declare image input; switch to an image-capable model to read images`, and the mismatch repair `cannot read "<path>": the <ext> extension declares <type>, but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats`; provider and policy templates are quoted in their package READMEs. Guarded-mutation failures additionally carry their recovery instruction in the message, appended by this package's model-facing error wrapper: `FS_STALE_VERSION` gets `— re-read the file, then retry`, and `FS_NOT_OBSERVED` gets `— read the file, then retry`; the structured code is preserved. After that reread confirms absence, edit reports `FS_NOT_FOUND` instead of repeating a stale remedy, while write uses guarded creation.
 
 #### Token effect
 
@@ -149,5 +168,8 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies ripgrep-backed `glob` and `grep` rather than extending the filesystem seam.
-- **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`.
+- **`read` handles UTF-8 text files only** — images use the separate extension-routed `read_image` tool; PDF, audio, and video remain deferred. A directory target is `FS_NOT_REGULAR_FILE`.
+- **The route gate races a concurrent model switch** — `read_image` checks the latest routed model at execution; a switch committed between that check and the next request can leave an image block on a route that rejects image content. The Web host already refuses switching an image-bearing session to a text-only model; other front doors own their equivalent guard.
+- **Extension-declared media type** — the 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.
+- **No inline image preview on the tool-result card** — UI surfaces render the image result generically (the durable reference, not pixels); inline rendering is deferred to the UI packages.
 - **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only ([provider rationale](../README.md#no-timeouts-on-file-io)).

package/README.zh.md

@@ -2,17 +2,20 @@
 
 [English](README.md) | 中文
 
-**面向模型的文件系统工具**（`read`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON Schema、参数校验、提示词段、**读取窗口逻辑**和结果格式化。它**直接**通过 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）读取／写入／编辑。新鲜度／观察策略由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。使用施加沙箱限制的提供方时，逐会话执行需要共享沙箱策略服务，工具还会为文件系统变更提供升权路径。
+**面向模型的文件系统工具**（`read`、`read_image`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON Schema、参数校验、提示词段、**读取窗口逻辑**和结果格式化。它**直接**通过 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）读取／写入／编辑。新鲜度／观察策略由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。使用施加沙箱限制的提供方时，逐会话执行需要共享沙箱策略服务，工具还会为文件系统变更提供升权路径。
 
 ```ts ignore-check
 // Default deployment: a ctx.fs provider, the policy plugin, then the tools.
 await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) // @deepseek-ai/dsh-fs-local
 await ctx.plugin(FsPolicy)                             // @deepseek-ai/dsh-fs-policy (policy gate)
-await ctx.plugin(ToolFs)                                  // this package — registers read/write/edit
+await ctx.plugin(LocalAttachmentStore, { dshHome })       // optional — enables durable read_image results
+await ctx.plugin(ToolFs)                                  // this package — read/write/edit, plus read_image with attachments
 ```
 
 `@deepseek-ai/dsh-fs-policy` 是**可选的**：省略时，工具直接使用裸提供方（无条件写入/覆盖/编辑，无已观察状态）。加载这些工具的部署也应加载该插件，从而提供写入/编辑前读取行为。
 
+`read_image` 只在持久 `ctx.attachments` 服务已挂载时注册：没有它，部署无法持久提交图像字节，工具就不会出现。执行时还要求确切路由的模型声明 `image` 输入（通过 `ctx.llm.resolveModelInfo` 从会话最新请求 header 解析，缺失时回退到 agent 选项）；未知或纯文本路由在任何文件系统 I/O 之前就得到拒绝结果，因此文本路由的持久历史不会出现图像块。
+
 ## 配置
 
 所有键均为可选；默认值是随产品交付的读取上限。
@@ -29,18 +32,20 @@ await ctx.plugin(ToolFs)                                  // this package — re
 | 工具 | 参数 | 行为 |
 |---|---|---|
 | `read` | `file_path`、`offset?`、`limit?` | 带行号的 UTF-8 内容和分页 footer。`offset` 从 1 开始；`limit` 默认为配置的 `readLimit`（2000），上限也为该值。 |
+| `read_image` | `file_path` | 通过有界字节 seam 读取 PNG/JPEG/WebP/GIF 文件，经 `ctx.attachments.saveImage` 持久保存，并在小型元数据信封旁返回图像块。只有确切路由的模型声明图像输入时才会成功。 |
 | `write` | `file_path`、`content` | 创建文件或完整替换文件。有策略插件时：覆盖现有文件要求先在未变版本上执行 `read`；创建新文件不需要。没有插件时：无条件执行。 |
 | `edit` | `file_path`、非空 `old_string`、`new_string`、`replace_all?` | 字面量替换；除非 `replace_all` 为 true，否则要求唯一匹配。有策略插件时：要求先执行 `read`（任何窗口），且文件此后未变。没有插件时：无条件执行。 |
 
 字段名使用 snake_case，与 Claude Code 和现有 harness 工具 schema 一致。
 
-规范成功值分别为：`read` → `{ path, offset, lines: [{ number, text }], totalLines }`，`write` → `{ path, operation: 'create' | 'update', before: string | null, after }`，`edit` → `{ path, before, after }`。原生渲染器会保留下方带行号的读取结果和变更确认。`write`/`edit` 从这些规范值派生可回放的 diff 卡片元数据，`read` 派生可回放的读取卡片窗口 `{ path, offset, lines, totalLines, lang? }`；规范值本身仅限于本次执行，不会添加到 `tool/result`，只有派生出的呈现元数据会被持久化。
+规范成功值分别为：`read` → `{ path, offset, lines: [{ number, text }], totalLines }`，`read_image` → `{ path, image: { attachmentId, mediaType, bytes, width, height, name? } }`，`write` → `{ path, operation: 'create' | 'update', before: string | null, after }`，`edit` → `{ path, before, after }`。原生渲染器会保留下方带行号的读取结果和变更确认。`write`/`edit` 从这些规范值派生可回放的 diff 卡片元数据，`read` 派生可回放的读取卡片窗口 `{ path, offset, lines, totalLines, lang? }`；规范值本身仅限于本次执行，不会添加到 `tool/result`，只有派生出的呈现元数据会被持久化。
 
 ## 工具就是执行器；策略是事件门禁
 
 工具**不**注入策略服务，也不检查任何缓存。每个工具通过 `ctx.fs.resolve(path, { cwd, signal })` 解析路径；它会传入调用 agent（智能体）的会话 cwd（`exec.agent.session.header.cwd`），使相对路径以会话工作区为基准解析并与 `dsh-tool-bash` 一致，同时把工具取消转发到解析过程（见[每会话 cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)）。随后执行：
 
 - **read**：一次 `ctx.fs.stat`（用于类型、大小路由和版本），随后调用 `readText`/`streamText`，构建行窗口，再发出 `fs/observed`，使用普通 `ctx.emit`。（1 次 stat。）
+- **read_image**：在任何 I/O 之前校验参数、扩展名、附件可用性、部署接受的媒体类型和图像路由；随后一次 `ctx.fs.stat`（目标缺失时与 `read` 一样记录 `absent` 观察）、以 `imageLimits.maxImageBytes` 与 `imageLimits.maxMessageImageBytes` 中较小者为上限的有界 `ctx.fs.readBytes`（结果是携带一张图像的一条消息）、`attachments.saveImage`（内容寻址，因此在 `tool/result` 事件追加时图像块引用的对象已持久提交），最后发出 `fs/observed`。（1 次 stat。）
 - **write**：调用 `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` 取得可选防护，然后调用 `ctx.fs.writeText(target, content, intent)`，再发出 `fs/observed`。（0 次 stat。）
 - **edit**：调用 `ctx.waterfall('fs/edit-intent', target, exec, () => undefined)` 取得可选防护，然后调用 `ctx.fs.editText(target, edit, intent)`，再发出 `fs/observed`。（0 次 stat。）
 
@@ -50,11 +55,11 @@ await ctx.plugin(ToolFs)                                  // this package — re
 
 ## `fs/observed` 发后即忘
 
-`fs/observed` 在读取/写入/编辑已经成功之后，通过普通 `ctx.emit` 发出。监听器的约定是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。
+`fs/observed` 在 read/read_image/write/edit 已经成功之后，通过普通 `ctx.emit` 发出。监听器的约定是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。
 
 `read` 允许并发调度，因为其唯一变更是同步版本记录器。稍后的 `write` 或 `edit` 会在目标锁内重新检查版本，因此记录器竞态会以拒绝方式关闭；两个变更工具仍保持互斥。见[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。
 
-包根目录只导出 Cordis 插件约定（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。
+包根目录只导出 Cordis 插件约定（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`read-image.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。
 
 ## 模型体验
 
@@ -94,7 +99,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 #### 模型看到的内容
 
-模型会看到已生成的 [`read`、`write` 和 `edit` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs)，参数使用 snake_case。作用域工具限制可以为某个 agent 移除任一定义。
+模型会看到已生成的 [`read`、`read_image`、`write` 和 `edit` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs)，参数使用 snake_case。`read_image` 只在持久附件存储已挂载时出现；schema 本身与路由无关，严格门禁在执行时拒绝。作用域工具限制可以为某个 agent 移除任一定义。
 
 #### Token 影响
 
@@ -118,6 +123,20 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
 
+### 图像读取结果
+
+#### 模型看到的内容
+
+成功的 `read_image` 返回 `<path><displayPath></path>`、`<type>image</type>` 和写明媒体类型、尺寸与字节数的 `<content>` 信封，随后是作为原生图像块的图像本身。会话日志只存储持久的 `sha256:` 附件引用；路由到的提供方在每次请求时重新读取并校验字节摘要。
+
+#### Token 影响
+
+图像在之后每次请求中都会计费，直到压缩。每次调用都独立受附件存储的 `maxImageBytes`/`maxImagePixels` 约束；重复成功调用会在历史中累积，内容寻址只去重存储的字节，不去重每次请求的 token 成本。
+
+#### KV Cache 影响
+
+仅追加；新可见内容跟在可复用请求前缀之后，不会使既有 KV 缓存条目失效。
+
 ### 写入与编辑结果
 
 #### 模型看到的内容
@@ -136,7 +155,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 #### 模型看到的内容
 
-失败会规范化为 `Error: <message>`。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to <max>`、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "<path>": not found`、`cannot read "<path>": not a regular file` 和 `offset <offset> is out of range for "<path>" (<total> lines)`；提供方和策略模板在各自包的 README 中逐字列出。防护变更失败还会在消息中携带恢复指令，由本包面向模型的错误包装追加：`FS_STALE_VERSION` 追加 `— re-read the file, then retry`，`FS_NOT_OBSERVED` 追加 `— read the file, then retry`；结构化错误码保持不变。该次重新读取确认缺失后，edit 会报告 `FS_NOT_FOUND`，而不会重复陈旧恢复指令；write 则使用带防护的创建。
+失败会规范化为 `Error: <message>`。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to <max>`、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "<path>": not found`、`cannot read "<path>": not a regular file`、`offset <offset> is out of range for "<path>" (<total> lines)`、`cannot read "<path>": read_image only accepts PNG/JPEG/WebP/GIF paths`、`cannot read "<path>" as an image: model "<model>" does not declare image input; switch to an image-capable model to read images`，以及类型不匹配的修复消息 `cannot read "<path>": the <ext> extension declares <type>, but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats`；提供方和策略模板在各自包的 README 中逐字列出。防护变更失败还会在消息中携带恢复指令，由本包面向模型的错误包装追加：`FS_STALE_VERSION` 追加 `— re-read the file, then retry`，`FS_NOT_OBSERVED` 追加 `— read the file, then retry`；结构化错误码保持不变。该次重新读取确认缺失后，edit 会报告 `FS_NOT_FOUND`，而不会重复陈旧恢复指令；write 则使用带防护的创建。
 
 #### Token 影响
 
@@ -149,5 +168,8 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 ## 已知限制与暂缓事项
 
 - **未交付面向模型的目录列表工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 [`dsh-tool-fs-search`](../tool-fs-search/) 包则提供基于 ripgrep 的 `glob` 与 `grep`，而不是扩展文件系统 seam。
-- **`read` 只处理 UTF-8 文本文件**：二进制安全读取和 PDF/图像/多模态内容均延期处理；目录目标为 `FS_NOT_REGULAR_FILE`。
+- **`read` 只处理 UTF-8 文本文件**：图像使用独立的、按扩展名路由的 `read_image` 工具；PDF、音频和视频仍延期处理。目录目标为 `FS_NOT_REGULAR_FILE`。
+- **路由门禁与并发模型切换存在竞态**：`read_image` 在执行时检查最新路由的模型；在该检查与下一次请求之间提交的切换，可能让图像块落在拒绝图像内容的路由上。Web 宿主已拒绝把含图像的会话切到纯文本模型；其他前端拥有各自的等价防护。
+- **媒体类型按扩展名声明**：扩展名选择声明类型，附件存储的魔数校验保持权威；扩展名错误但格式正确的图像会得到改名修复提示，而不是被嗅探接受。
+- **工具结果卡片没有内嵌图像预览**：UI 表面以通用形式渲染图像结果（持久引用而非像素）；内嵌渲染延后到 UI 包处理。
 - **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见[提供方理由](../README.md#no-timeouts-on-file-io)）。

package/lib/index.js

@@ -3,6 +3,9 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 import { FsError } from "@deepseek-ai/dsh-fs";
 import { ESCALATION_TARGETS, approveEscalation, canonicalPath, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
 import { structuredPatch } from "diff";
+import { basename, extname } from "node:path";
+import { AttachmentError, AttachmentId } from "@deepseek-ai/dsh-attachment";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
 //#region lib/types/read-render.js
 /**
 * Pure read presentation: turn provider-decoded text into a bounded, line-numbered window and
@@ -256,6 +259,32 @@ function sessionResolveOptions(exec, requestedPath, policyWorkspaceRoot) {
 	};
 }
 //#endregion
+//#region lib/types/read-target.js
+/**
+* Shared path resolution and regular-file validation for model-facing read tools.
+* @module @deepseek-ai/dsh-tool-fs/src/read-target
+*/
+/**
+* Resolve a model-supplied path, observe absence, and require a regular file.
+* @param ctx - the plugin context providing filesystem resolution and observation events.
+* @param exec - the current tool execution, including session cwd and cancellation.
+* @param requestedPath - the raw path supplied to the tool.
+* @returns the resolved target and its single stat result.
+*/
+async function resolveRegularReadTarget(ctx, exec, requestedPath) {
+	const target = await ctx.fs.resolve(requestedPath, sessionResolveOptions(exec, requestedPath));
+	const info = await ctx.fs.stat(target, exec.signal);
+	if (info === void 0) {
+		ctx.emit("fs/observed", target, { kind: "absent" }, exec);
+		throw new FsError(`cannot read "${target.displayPath}": not found`, "FS_NOT_FOUND");
+	}
+	if (info.type !== "file") throw new FsError(`cannot read "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
+	return {
+		target,
+		info
+	};
+}
+//#endregion
 //#region lib/types/read.js
 /**
 * Model-facing UTF-8 read. It performs one provider stat for type, routing, and observed version,
@@ -387,13 +416,7 @@ function applyReadTool(ctx, caps) {
 		isConcurrencySafe: () => true,
 		async execute(args, exec) {
 			const input = parseReadArgs(args, caps.limit);
-			const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath));
-			const info = await ctx.fs.stat(target, exec.signal);
-			if (!info) {
-				ctx.emit("fs/observed", target, { kind: "absent" }, exec);
-				throw new FsError(`cannot read "${target.displayPath}": not found`, "FS_NOT_FOUND");
-			}
-			if (info.type !== "file") throw new FsError(`cannot read "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
+			const { target, info } = await resolveRegularReadTarget(ctx, exec, input.filePath);
 			const window = await buildWindow(info.size === void 0 || info.size >= caps.streamMinSize ? await ctx.fs.streamText(target, exec.signal) : [await ctx.fs.readText(target, exec.signal)], {
 				offset: input.offset,
 				limit: input.limit,
@@ -570,7 +593,7 @@ ${outcome.operation === "create" ? "Created" : "Updated"} file
 /**
 * Register the `write` tool and its system-prompt guidance.
 * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
-* @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
+* @param sandbox - the shared sandbox-escalation API (advertisement, mode stamping, denial mapping).
 */
 function applyWriteTool(ctx, sandbox) {
 	ctx.systemPrompt.section({
@@ -715,7 +738,7 @@ function formatEditOutput(displayPath, replaceAll) {
 /**
 * Register the `edit` tool and its system-prompt guidance.
 * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
-* @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
+* @param sandbox - the shared sandbox-escalation API (advertisement, mode stamping, denial mapping).
 */
 function applyEditTool(ctx, sandbox) {
 	ctx.systemPrompt.section({
@@ -827,9 +850,222 @@ function applyEditTool(ctx, sandbox) {
 	}));
 }
 //#endregion
+//#region lib/types/read-image.js
+/**
+* The model-facing `read_image` tool: reads a PNG/JPEG/WebP/GIF file, durably
+* commits its bytes through the attachment service (the same lifecycle as a
+* user-uploaded image), and returns an image block so the image enters model
+* context from the next request onward.
+*
+* The route gate is deliberately stricter than the host upload preflight: a
+* tool result enters durable session history, so emitting an image on a route
+* that cannot carry it would break that route's continuation. Unknown
+* capability therefore refuses instead of relying on the adapter guard.
+* @module @deepseek-ai/dsh-tool-fs/src/read-image
+*/
+/** Extensions `read_image` accepts; magic-byte validation at the attachment service stays authoritative. */
+const IMAGE_EXTENSIONS = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".gif": "image/gif"
+};
+/**
+* Map a model-supplied path to its declared image media type by extension.
+* @param filePath - the raw `file_path` argument (not yet resolved).
+* @returns the declared media type, or undefined when the path does not claim an image.
+*/
+function imageMediaTypeForPath(filePath) {
+	return IMAGE_EXTENSIONS[extname(filePath).toLowerCase()];
+}
+/**
+* Enforce the strict image-capability gate for the calling route. Resolves the
+* session's latest routed provider/model (request header config, then agent
+* options) and requires the exact resolved route to declare `image` input explicitly.
+* @param ctx - the plugin context used to resolve the optional `llm` service.
+* @param exec - the tool-execution context supplying the calling agent.
+* @param requestedPath - the raw, not-yet-resolved path rendered in refusal messages.
+*/
+async function assertImageCapableRoute(ctx, exec, requestedPath) {
+	const routed = exec.agent?.session.requestHeader()?.config;
+	const provider = routed?.provider ?? exec.agent?.options.provider;
+	const model = routed?.model ?? exec.agent?.options.model;
+	const llm = ctx.get("llm");
+	if (provider === void 0 || model === void 0 || llm === void 0) throw new Error(`cannot read "${requestedPath}" as an image: the current model route could not be resolved`);
+	const active = await llm.resolveModelInfo(provider, model, exec.signal);
+	if (active.inputModalities === void 0 || !active.inputModalities.includes("image")) throw new Error(`cannot read "${requestedPath}" as an image: model "${model}" does not declare image input; switch to an image-capable model to read images`);
+}
+/**
+* Re-brand a canonical image outcome into the durable attachment reference an
+* `ImageBlock` carries.
+* @param image - the canonical image metadata from the output schema.
+* @returns the branded attachment reference.
+*/
+function imageRefFromValue(image) {
+	return {
+		attachmentId: AttachmentId(image.attachmentId),
+		mediaType: image.mediaType,
+		bytes: image.bytes,
+		width: image.width,
+		height: image.height,
+		...image.name === void 0 ? {} : { name: image.name }
+	};
+}
+/**
+* Format an image read as the model-facing envelope beside its image block.
+* @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+* @param image - the canonical image metadata to summarize.
+* @returns the model-facing envelope; the image itself rides the adjacent image block.
+*/
+function formatImageReadOutput(displayPath, image) {
+	return `<path>${displayPath}</path>
+<type>image</type>
+<content>
+${image.mediaType} image, ${image.width}x${image.height} px, ${image.bytes} bytes
+</content>`;
+}
+/**
+* Project one canonical image read into its model-facing envelope and image.
+* @param value - the canonical image-read outcome.
+* @returns the two content blocks used by native and nested dispatches.
+*/
+function imageReadContent(value) {
+	return [{
+		type: "text",
+		text: formatImageReadOutput(value.path, value.image)
+	}, {
+		type: "image",
+		attachment: imageRefFromValue(value.image)
+	}];
+}
+/**
+* Register the `read_image` tool into the given context. The composing plugin
+* owns the attachments gate: `src/index.ts` calls this inside
+* `ctx.inject(['attachments'], …)` so the tool exists only while a durable
+* store is mounted. Execution still re-checks `ctx.get('attachments')` for
+* direct callers and gates on the calling route's declared image input.
+* @param ctx - the registration scope; execution uses its `fs` service plus
+*   the optional `attachments`/`llm` services.
+*/
+function applyReadImageTool(ctx) {
+	ctx.tools.register(defineTool({
+		name: "read_image",
+		description: "Read a PNG/JPEG/WebP/GIF file and return the image itself. Requires the current model to accept image input.",
+		parameters: { file_path: {
+			type: "string",
+			required: true,
+			description: "Path to the image file, resolved by the filesystem backend."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					path: {
+						type: "string",
+						required: true
+					},
+					image: {
+						type: "object",
+						additionalProperties: false,
+						required: true,
+						properties: {
+							attachmentId: {
+								type: "string",
+								required: true
+							},
+							mediaType: {
+								type: "string",
+								enum: [
+									"image/png",
+									"image/jpeg",
+									"image/webp",
+									"image/gif"
+								],
+								required: true
+							},
+							bytes: {
+								type: "integer",
+								required: true
+							},
+							width: {
+								type: "integer",
+								required: true
+							},
+							height: {
+								type: "integer",
+								required: true
+							},
+							name: { type: "string" }
+						}
+					}
+				}
+			},
+			render: (_args, value) => imageReadContent(value)
+		},
+		isConcurrencySafe: () => true,
+		async execute(args, exec) {
+			if (args.file_path.trim().length === 0) throw new Error("file_path must be a non-empty string");
+			const mediaType = imageMediaTypeForPath(args.file_path);
+			if (mediaType === void 0) throw new Error(`cannot read "${args.file_path}": read_image only accepts PNG/JPEG/WebP/GIF paths`);
+			const attachments = ctx.get("attachments");
+			if (attachments === void 0) throw new Error(`cannot read "${args.file_path}" as an image: no attachment service is mounted`);
+			if (!attachments.imageLimits.mediaTypes.includes(mediaType)) throw new Error(`cannot read "${args.file_path}": ${mediaType} images are not accepted by this deployment`);
+			await assertImageCapableRoute(ctx, exec, args.file_path);
+			const { target, info } = await resolveRegularReadTarget(ctx, exec, args.file_path);
+			const byteCap = Math.min(attachments.imageLimits.maxImageBytes, attachments.imageLimits.maxMessageImageBytes);
+			const data = await ctx.fs.readBytes(target, exec.signal, byteCap);
+			let ref;
+			try {
+				ref = await attachments.saveImage({
+					data,
+					mediaType,
+					name: basename(target.displayPath)
+				});
+			} catch (error) {
+				if (!(error instanceof AttachmentError) || error.code !== "IMAGE_TYPE_MISMATCH") throw error;
+				const extension = extname(target.displayPath).toLowerCase();
+				throw new Error(`cannot read "${target.displayPath}": the ${extension} extension declares ${mediaType}, but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats`, { cause: error });
+			}
+			ctx.emit("fs/observed", target, {
+				kind: "present",
+				version: info.version
+			}, exec);
+			const value = {
+				path: target.displayPath,
+				image: {
+					attachmentId: ref.attachmentId,
+					mediaType: ref.mediaType,
+					bytes: ref.bytes,
+					width: ref.width,
+					height: ref.height,
+					...ref.name === void 0 ? {} : { name: ref.name }
+				}
+			};
+			if (exec.parent !== void 0) exec.deferContext(createUserMessage({
+				content: imageReadContent(value),
+				source: {
+					kind: "plugin",
+					plugin: "tool-fs"
+				}
+			}));
+			return value;
+		},
+		presentCall(args) {
+			return {
+				card: "generic",
+				title: `Read image ${args.file_path}`,
+				kind: "read",
+				locations: [{ path: args.file_path }]
+			};
+		}
+	}));
+}
+//#endregion
 //#region lib/types/sandbox.js
 /**
-* The sandbox-escalation surface shared by the `write` and `edit` tools: the
+* The sandbox-escalation API shared by the `write` and `edit` tools: the
 * per-call policy resolution, the advertised escalation fields, and the denial-marker
 * mapping — all delegating the vocabulary and the fail-closed approval
 * sequence to `@deepseek-ai/dsh-sandbox` (the same pieces `@deepseek-ai/dsh-tool-bash`
@@ -840,11 +1076,11 @@ function applyEditTool(ctx, sandbox) {
 * @module @deepseek-ai/dsh-tool-fs/sandbox
 */
 /**
-* The filesystem escalation surface: advertisement gating, per-call policy
+* The filesystem escalation API: advertisement gating, per-call policy
 * resolution, the one-approved wider retry, and denial-marker mapping. A pure
 * product of `ctx` at plugin apply time.
 */
-var FsSandboxSurface = class {
+var FsSandboxController = class {
 	ctx;
 	/** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
 	escalationModes;
@@ -935,7 +1171,7 @@ var FsSandboxSurface = class {
 //#endregion
 //#region lib/types/index.js
 /**
-* Model-facing read, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
+* Model-facing read, read_image, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
 * read windows, formatting, and observation events, never a concrete provider. An optional
 * event policy supplies mutation guards; without one the tools use unconditional provider calls.
 * @module @deepseek-ai/dsh-tool-fs
@@ -958,7 +1194,7 @@ const Config = z.object({
 function assertPositiveInteger(name, value) {
 	if (!Number.isInteger(value) || value < 1) throw new Error(`tool-fs: ${name} must be a positive integer`);
 }
-/** Register the full `read`/`write`/`edit` filesystem tool suite. */
+/** Register the full `read`/`write`/`edit` filesystem tool suite, plus `read_image` while `attachments` is mounted. */
 function apply(ctx, config) {
 	const resolved = config;
 	assertPositiveInteger("readLimit", resolved.readLimit);
@@ -971,7 +1207,10 @@ function apply(ctx, config) {
 		maxBytes: resolved.readMaxBytes,
 		streamMinSize: resolved.readStreamMinSize
 	});
-	const sandbox = new FsSandboxSurface(ctx);
+	ctx.inject(["attachments"], (imageCtx) => {
+		applyReadImageTool(imageCtx);
+	});
+	const sandbox = new FsSandboxController(ctx);
 	applyWriteTool(ctx, sandbox);
 	applyEditTool(ctx, sandbox);
 }

package/lib/types/edit.d.ts

@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-tool-fs/src/edit
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { FsSandboxSurface } from './sandbox.ts';
+import type { FsSandboxController } from './sandbox.ts';
 /** Validated `edit` arguments after defaulting. */
 interface EditInput {
     filePath: string;
@@ -36,8 +36,8 @@ export declare function formatEditOutput(displayPath: string, replaceAll: boolea
 /**
  * Register the `edit` tool and its system-prompt guidance.
  * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
- * @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
+ * @param sandbox - the shared sandbox-escalation API (advertisement, mode stamping, denial mapping).
  */
-export declare function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void;
+export declare function applyEditTool(ctx: Context, sandbox: FsSandboxController): void;
 export {};
 //# sourceMappingURL=edit.d.ts.map

package/lib/types/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Model-facing read, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
+ * Model-facing read, read_image, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
  * read windows, formatting, and observation events, never a concrete provider. An optional
  * event policy supplies mutation guards; without one the tools use unconditional provider calls.
  * @module @deepseek-ai/dsh-tool-fs
@@ -22,6 +22,6 @@ export interface Config {
     readStreamMinSize?: number;
 }
 export declare const Config: z<Config>;
-/** Register the full `read`/`write`/`edit` filesystem tool suite. */
+/** Register the full `read`/`write`/`edit` filesystem tool suite, plus `read_image` while `attachments` is mounted. */
 export declare function apply(ctx: Context, config: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/read-image.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The model-facing `read_image` tool: reads a PNG/JPEG/WebP/GIF file, durably
+ * commits its bytes through the attachment service (the same lifecycle as a
+ * user-uploaded image), and returns an image block so the image enters model
+ * context from the next request onward.
+ *
+ * The route gate is deliberately stricter than the host upload preflight: a
+ * tool result enters durable session history, so emitting an image on a route
+ * that cannot carry it would break that route's continuation. Unknown
+ * capability therefore refuses instead of relying on the adapter guard.
+ * @module @deepseek-ai/dsh-tool-fs/src/read-image
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/** The canonical outcome declared by the `read_image` output schema. */
+export interface ImageReadValue {
+    path: string;
+    image: {
+        attachmentId: string;
+        mediaType: ImageMediaType;
+        bytes: number;
+        width: number;
+        height: number;
+        name?: string;
+    };
+}
+/**
+ * Map a model-supplied path to its declared image media type by extension.
+ * @param filePath - the raw `file_path` argument (not yet resolved).
+ * @returns the declared media type, or undefined when the path does not claim an image.
+ */
+export declare function imageMediaTypeForPath(filePath: string): ImageMediaType | undefined;
+/**
+ * Enforce the strict image-capability gate for the calling route. Resolves the
+ * session's latest routed provider/model (request header config, then agent
+ * options) and requires the exact resolved route to declare `image` input explicitly.
+ * @param ctx - the plugin context used to resolve the optional `llm` service.
+ * @param exec - the tool-execution context supplying the calling agent.
+ * @param requestedPath - the raw, not-yet-resolved path rendered in refusal messages.
+ */
+export declare function assertImageCapableRoute(ctx: Context, exec: ToolExecution, requestedPath: string): Promise<void>;
+/**
+ * Re-brand a canonical image outcome into the durable attachment reference an
+ * `ImageBlock` carries.
+ * @param image - the canonical image metadata from the output schema.
+ * @returns the branded attachment reference.
+ */
+export declare function imageRefFromValue(image: ImageReadValue['image']): ImageAttachmentRef;
+/**
+ * Format an image read as the model-facing envelope beside its image block.
+ * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+ * @param image - the canonical image metadata to summarize.
+ * @returns the model-facing envelope; the image itself rides the adjacent image block.
+ */
+export declare function formatImageReadOutput(displayPath: string, image: ImageReadValue['image']): string;
+/**
+ * Register the `read_image` tool into the given context. The composing plugin
+ * owns the attachments gate: `src/index.ts` calls this inside
+ * `ctx.inject(['attachments'], …)` so the tool exists only while a durable
+ * store is mounted. Execution still re-checks `ctx.get('attachments')` for
+ * direct callers and gates on the calling route's declared image input.
+ * @param ctx - the registration scope; execution uses its `fs` service plus
+ *   the optional `attachments`/`llm` services.
+ */
+export declare function applyReadImageTool(ctx: Context): void;
+//# sourceMappingURL=read-image.d.ts.map

package/lib/types/read-target.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared path resolution and regular-file validation for model-facing read tools.
+ * @module @deepseek-ai/dsh-tool-fs/src/read-target
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsInfo, FsTarget } from '@deepseek-ai/dsh-fs';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/**
+ * Resolve a model-supplied path, observe absence, and require a regular file.
+ * @param ctx - the plugin context providing filesystem resolution and observation events.
+ * @param exec - the current tool execution, including session cwd and cancellation.
+ * @param requestedPath - the raw path supplied to the tool.
+ * @returns the resolved target and its single stat result.
+ */
+export declare function resolveRegularReadTarget(ctx: Context, exec: ToolExecution, requestedPath: string): Promise<{
+    target: FsTarget;
+    info: FsInfo;
+}>;
+//# sourceMappingURL=read-target.d.ts.map

package/lib/types/sandbox.d.ts

@@ -1,5 +1,5 @@
 /**
- * The sandbox-escalation surface shared by the `write` and `edit` tools: the
+ * The sandbox-escalation API shared by the `write` and `edit` tools: the
  * per-call policy resolution, the advertised escalation fields, and the denial-marker
  * mapping — all delegating the vocabulary and the fail-closed approval
  * sequence to `@deepseek-ai/dsh-sandbox` (the same pieces `@deepseek-ai/dsh-tool-bash`
@@ -30,11 +30,11 @@ export interface EscalationSchemaFields {
     };
 }
 /**
- * The filesystem escalation surface: advertisement gating, per-call policy
+ * The filesystem escalation API: advertisement gating, per-call policy
  * resolution, the one-approved wider retry, and denial-marker mapping. A pure
  * product of `ctx` at plugin apply time.
  */
-export declare class FsSandboxSurface {
+export declare class FsSandboxController {
     private readonly ctx;
     /** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
     readonly escalationModes: readonly SandboxMode[];

package/lib/types/write.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { FsWriteOutcome } from '@deepseek-ai/dsh-fs';
-import type { FsSandboxSurface } from './sandbox.ts';
+import type { FsSandboxController } from './sandbox.ts';
 /**
  * Validate value constraints the schema DSL can't express: only a non-blank
  * `file_path` — an empty `content` is legitimate (it writes an empty file).
@@ -30,7 +30,7 @@ export declare function formatWriteOutput(displayPath: string, outcome: Pick<FsW
 /**
  * Register the `write` tool and its system-prompt guidance.
  * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
- * @param sandbox - the shared sandbox-escalation surface (advertisement, mode stamping, denial mapping).
+ * @param sandbox - the shared sandbox-escalation API (advertisement, mode stamping, denial mapping).
  */
-export declare function applyWriteTool(ctx: Context, sandbox: FsSandboxSurface): void;
+export declare function applyWriteTool(ctx: Context, sandbox: FsSandboxController): void;
 //# sourceMappingURL=write.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-fs",
   "description": "Model-facing filesystem tools (read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)",
-  "version": "0.0.1-rc.1",
+  "version": "0.0.1-rc.2",
   "publishConfig": {
     "access": "restricted"
   },
@@ -36,33 +36,35 @@
     "@deepseek-ai/schemastery": "^3.18.1-rc.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-fs": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-user-approval": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+    "@deepseek-ai/dsh-attachment": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-fs": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-user-approval": "^0.0.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-fs": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-fs-local": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-fs-policy": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-llm-deepseek": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-attachment": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-fs": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-fs-local": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-fs-policy": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-user-approval": "^0.0.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/dsh-user-approval": "^0.0.1-rc.1"
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.2"
   }
 }