@deepseek-ai/dsh-tool-fs 0.1.3-alpha.2 → 0.1.5-alpha.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: 6da984ff436f3515b4798ddb47e3a15466672f9e
-README.zh.md: e4d1ef8483c2e644f2e6308e1965d87773278515
+README.md: 9d338a6227b7f02ef43fcbe97900b166cb722817
+README.zh.md: 0c34f840ad449847a649df8abdadec01f772f37b

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-tool-fs` provides the model-facing filesystem tools — `read`, `read_image`, `write`, and `edit` — and their executor. With them the model reads files with line numbers, creates or replaces them atomically, and applies targeted literal edits; results are capped and failures carry stable codes with recovery instructions, all backed by a mounted `ctx.fs` backend. The read-before-edit policy lives in a separate plugin (`dsh-fs-observation-policy`), so omitting it yields unconditional, still-atomic mutations. `read_image` appears while a durable attachment store is mounted and refuses execution unless the routed model declares image input. Choose this package when the model should read, create, replace, or edit UTF-8 text files; discovery (`glob`/`grep`) is a sibling package.
+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.
 
 ## Table of Contents
 
@@ -133,7 +133,7 @@ Read these pages when the package-level contract is not enough. They move from t
 
 #### What the model sees
 
-Every request in this plugin's registration scope receives the independently registered read, write, and edit guidance below. Scoped tool restrictions can hide schemas without removing these sections.
+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
 
@@ -155,11 +155,11 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 #### Token effect
 
-Fixed guidance cost per request while the plugin is active, even when a restriction hides one or more tools.
+Guidance cost follows the visible tools and their applicable cross-tool recommendations.
 
 #### KV Cache effect
 
-Prefix-stable while the plugin scope and guidance text are unchanged. Tool restrictions do not remove this section, but plugin activation or disposal may invalidate reuse from it.
+Prefix-stable while the visible tool set, plugin scope, and guidance text are unchanged. Restrictions or plugin lifecycle changes may invalidate reuse from the first changed section.
 
 ### Tool schemas
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-tool-fs` 提供面向模型的文件系统工具——`read`、`read_image`、`write` 与 `edit`——及其执行器。借助它们，模型可以带行号读取文件、原子地创建或替换文件，并执行有针对性的字面量编辑；结果都有上限，失败携带稳定错误码与恢复指令，所有文件操作都运行在已挂载的 `ctx.fs` 后端之上。编辑前读取策略位于独立插件（`dsh-fs-observation-policy`）中，因此省略它只会得到无条件、依然原子的变更。`read_image` 在持久附件存储已挂载时出现，并且只在路由模型声明图片输入时允许执行。当模型需要读取、创建、替换或编辑 UTF-8 文本文件时选择本包；发现工具（`glob`/`grep`）在同级包中。
+使用 `dsh-tool-fs` 可让模型带行号读取 UTF-8 文件、读取受支持的图片、创建或原子地替换文件，以及执行有针对性的字面量编辑。结果都有上限，失败会提供稳定错误码与恢复指令。当写入和编辑必须在成功读取后执行时，请添加 `dsh-fs-observation-policy`；省略它时，变更仍是原子的，但不受此条件约束。图片读取需要持久附件存储和支持图片输入的路由模型。glob 或 grep 搜索请选择同级的发现工具包。
 
 ## 目录
 
@@ -133,7 +133,7 @@ kind: "package-reference"
 
 #### 模型看到的内容
 
-该插件注册作用域内的每个请求都会收到下方独立注册的 read、write 与 edit 指导。作用域工具限制可以隐藏 schema，而不移除这些段。
+组装时，每个指导段落通过 `ctx.tools.get(name, scope)` 检查对应工具，仅在该 agent 可见时输出。write 段落仅在 edit 可见时推荐 edit。三个工具都可用时，下方原文保持不变；限制的施加、解除和工具注册变化在下次组装时生效。同一检查适用于直接限制 agent 和 subagent 的 `toolFilter`，也适用于通过 `run_code` 暴露的 PTC 能力。 write/edit 中的先读后改句子描述观察策略，并非要求调用名为 `read` 的工具。隐藏 `read` 时仍保留这些句子：策略继续保护修改操作，其他产生观察记录的操作（例如 `str_replace_editor` 的 `command: view`）也能建立同一文件观察记录。工具可见性不会禁用该前置条件。
 
 ##### Read 指导
 
@@ -155,11 +155,11 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 #### Token 影响
 
-插件启用期间，每个请求支付固定指导成本；即使限制隐藏了一个或多个工具也一样。
+指导成本取决于可见工具及其适用的跨工具推荐。
 
 #### KV Cache 影响
 
-只要插件作用域和指导文本不变，前缀就保持稳定。工具限制不会移除该段，但插件启用或 dispose（资源释放）可能从该段开始使复用失效。
+可见工具集合、插件作用域和指导文本不变时，前缀保持稳定。限制或插件生命周期变化可能从首个变化的段落开始使复用失效。
 
 ### 工具 schema
 

package/lib/index.js

@@ -318,7 +318,7 @@ function parseReadArgs(args, maxLimit) {
 	};
 }
 /**
-* Register the `read` tool and its system-prompt guidance.
+* Register the `read` tool and its scope-aware system-prompt guidance.
 * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
 * @param caps - the deployment's resolved read caps (plugin config after defaulting).
 */
@@ -326,7 +326,7 @@ function applyReadTool(ctx, caps) {
 	ctx.systemPrompt.section({
 		name: "tool:read",
 		order: ctx.systemPrompt.getSectionOrder("TOOL_READ"),
-		text: "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."
+		text: ({ scope }) => ctx.tools.get("read", scope) === void 0 ? "" : "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."
 	});
 	ctx.tools.register(defineTool({
 		name: "read",
@@ -583,7 +583,7 @@ ${outcome.operation === "create" ? "Created" : "Updated"} file
 </content>`;
 }
 /**
-* Register the `write` tool and its system-prompt guidance.
+* Register the `write` tool and its scope-aware 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 API (advertisement, mode stamping, denial mapping).
 */
@@ -591,7 +591,7 @@ function applyWriteTool(ctx, sandbox) {
 	ctx.systemPrompt.section({
 		name: "tool:write",
 		order: ctx.systemPrompt.getSectionOrder("TOOL_WRITE"),
-		text: "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."
+		text: ({ scope }) => ctx.tools.get("write", scope) === void 0 ? "" : "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)" + (ctx.tools.get("edit", scope) === void 0 ? "" : " and prefer edit for targeted changes") + "."
 	});
 	ctx.tools.register(defineTool({
 		name: "write",
@@ -728,7 +728,7 @@ function formatEditOutput(displayPath, replaceAll) {
 	return replaceAll ? `The file ${displayPath} has been updated. All occurrences were successfully replaced.` : `The file ${displayPath} has been updated successfully.`;
 }
 /**
-* Register the `edit` tool and its system-prompt guidance.
+* Register the `edit` tool and its scope-aware 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 API (advertisement, mode stamping, denial mapping).
 */
@@ -736,7 +736,7 @@ function applyEditTool(ctx, sandbox) {
 	ctx.systemPrompt.section({
 		name: "tool:edit",
 		order: ctx.systemPrompt.getSectionOrder("TOOL_EDIT"),
-		text: "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."
+		text: ({ scope }) => ctx.tools.get("edit", scope) === void 0 ? "" : "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."
 	});
 	ctx.tools.register(defineTool({
 		name: "edit",

package/lib/types/edit.d.ts

@@ -34,7 +34,7 @@ export declare function parseEditArgs(args: {
  */
 export declare function formatEditOutput(displayPath: string, replaceAll: boolean): string;
 /**
- * Register the `edit` tool and its system-prompt guidance.
+ * Register the `edit` tool and its scope-aware 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 API (advertisement, mode stamping, denial mapping).
  */

package/lib/types/read.d.ts

@@ -40,7 +40,7 @@ export declare function parseReadArgs(args: {
     limit?: number;
 }, maxLimit: number): ReadInput;
 /**
- * Register the `read` tool and its system-prompt guidance.
+ * Register the `read` tool and its scope-aware system-prompt guidance.
  * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
  * @param caps - the deployment's resolved read caps (plugin config after defaulting).
  */

package/lib/types/write.d.ts

@@ -28,7 +28,7 @@ export declare function parseWriteArgs(args: {
  */
 export declare function formatWriteOutput(displayPath: string, outcome: Pick<FsWriteOutcome, 'operation'>): string;
 /**
- * Register the `write` tool and its system-prompt guidance.
+ * Register the `write` tool and its scope-aware 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 API (advertisement, mode stamping, denial mapping).
  */

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.1.3-alpha.2",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -31,34 +31,36 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-attachment": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-fs": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "^0.1.5-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-attachment": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-fs": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-fs-observation-policy": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-fs-local": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm-deepseek": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-fs-observation-policy": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "^0.1.5-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-user-approval": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-scope": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-fs-local": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-code-runtime": "^0.1.5-alpha.2"
   }
 }