dsh-tool-docx 0.5.0

package/README.zh.md

@@ -0,0 +1,202 @@
+# dsh-tool-docx
+
+[English](README.md) | 中文 | [Русский](README.ru.md)
+
+面向模型的微软 Word（`.docx`）工具，用于 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)：`docx_read` 将文档提取为 Markdown 或结构化 JSON 块，`docx_create` 从 Markdown 生成新的 `.docx`，`docx_edit` 从 Markdown 替换文档内容并保留其 title/author/created 属性。`.docx` 是 ZIP 封装的 XML 部件，因此每个工具都通过有界的 `ctx.fs.readBytes` 原语读取整个包，并通过插件的 `fsBinary` 二进制写入服务（或原生提供 `writeBytes` 的宿主 `ctx.fs`）写入包——与文本工具使用相同的原子、沙箱围栏变更，且从不替换宿主自身的文件系统。
+
+本仓库是插件的**独立分发**。该插件是**为 DeepSeek Harness 编写的原创作品**——由本项目独立开发，最初在本地 `deepseek-harness` 检出中进行（harness 是它的运行目标），而非共享仓库中某个插件的副本。它接入 harness 的 `tools`、`fs` 与 `systemPrompt` 服务，并可针对已发布的 `@deepseek-ai/*` 包独立构建和测试，因此可以安装到任何 harness 检出中。
+
+## 需求
+
+- 一个文件系统 seam 提供**读取**原语 `fs.readBytes` 的 DeepSeek Harness 宿主（`0.1.0-rc.7` 线）——`readBytes` 自 `@deepseek-ai/dsh-fs@0.1.0-rc.7` 起已发布。**写入**侧（`writeBytes`）不在任何已发布的 `dsh-fs` 版本中，因此捆绑包会挂载插件的[二进制 fs 提供者](#二进制-fs-提供者)：一个独立的 `fsBinary` 服务，在不触碰 `ctx.fs` 的前提下实现 `writeBytes`（沙箱宿主下带围栏）。没有任何二进制写入器——既无 `fsBinary` 服务也无原生 `ctx.fs.writeBytes` 时——`docx_read` 仍可工作，而 `docx_create`/`docx_edit` 会以带类型的 `DOCX_HOST_FS_UNSUPPORTED` 错误失败并指明修复方式。
+- harness 提供 peer 服务（`0.1.0-rc.7` 线）：`cordis`、`dsh-tools`、`dsh-fs`、`dsh-llm`、`dsh-sandbox`、`dsh-sandbox-policy`、`dsh-system-prompt`、`dsh-invariants`、`dsh-user-approval`、`dsh-session`。
+
+## 安装
+
+官方安装路径是 harness 自带的插件管理器——一条命令即可将包安装到配置文件，profile 启动器会自动激活捆绑包的 [`cordis.patch.yml`](cordis.patch.yml) 层（包声明了 `dsh.bundle.patch`）：
+
+```sh
+dsh plugin --profile web add github:BroBFG/dsh-tool-docx#v0.5.0
+```
+
+`dsh plugin` 会在配置文件目录内运行 pnpm，并根据已安装状态协调 `dsh.profile.bundles`，因此无需其他任何操作——不需要 `allowBuilds` 条目（包自带构建好的 `lib/`，没有 build 脚本）、不需要手工编辑 `cordis.patch.yml`、不需要 `--patch` overlay。之后重启 harness。
+
+- **更新**：`dsh plugin --profile web update dsh-tool-docx`，或用新 tag 重新 `add`。
+- **移除**：`dsh plugin --profile web remove dsh-tool-docx`。
+- **本地开发**：`dsh plugin --profile web add ../dsh-tool-docx`（相对 spec 以调用目录为锚点）或 `dsh plugin --profile web add link:../dsh-tool-docx`。
+
+> npm 发布已计划但尚未提供；包以独立名称 `dsh-tool-docx` 发布（`dsh-tool-*` 生态惯例），不依赖 `@deepseek-ai` scope。
+
+## 工具
+
+| 工具 | 用途 |
+|---|---|
+| `docx_read(file_path, format?, max_chars?)` | 将文档正文提取为 Markdown（默认）或结构化 JSON 块以及 `docProps`。发出 `fs/observed`。 |
+| `docx_create(file_path, markdown, title?, author?)` | 从 Markdown 生成新的 `.docx`。受 `createIfAbsent` 保护：绝不盲目覆盖现有文件。 |
+| `docx_edit(file_path, markdown)` | 读取当前文档（校验其为 docx），保留 `docProps`，从完整 Markdown 重新生成正文，并以版本守卫写回（并发变更时返回 `DOCX_STALE`）。 |
+
+三个工具都针对调用代理的会话 cwd 解析相对路径，在变更前派发 `fs/write-intent` 瀑布（观察策略插件可以提供自己的 intent），并在完成时记录 `fs/observed`——因此沙箱围栏、升权字段和写前读取策略对 docx 变更的作用与对 `write`/`edit` 完全一致。
+
+## 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `maxDocxBytes` | 64 MiB | 整个 `.docx` 文件的字节上限（读取 + ZIP 展开）。 |
+| `maxMarkdownChars` | 1 000 000 | create/edit 的 Markdown 输入字符上限。 |
+| `maxReadChars` | 200 000 | `docx_read` 返回的 Markdown 字符上限。 |
+
+## 二进制 fs 提供者
+
+基础包的 `fs-sandbox` 行继续**原样**提供 `ctx.fs`。捆绑包在它旁边添加 docx 工具和一个二进制提供者，后者将二进制 `writeBytes` 原语注册为**独立的 `fsBinary` 服务**——宿主文件系统永远不会被替换，因此该插件不可能破坏 harness 启动；最坏情况下，没有提供者时变更类工具会报告 `DOCX_HOST_FS_UNSUPPORTED`：
+
+- **`dsh-tool-docx/fs-binary-sandbox-plugin`**（捆绑包挂载；沙箱宿主推荐）——注册的 `fsBinary.writeBytes` 与每次沙箱变更走**相同的按调用策略围栏**：`workspace-write` 包含检查、`read-only` 拒绝、`danger-full-access` 放行、拒绝时 `FS_SANDBOX_DENIED`（在工具层映射为 `DOCX_SANDBOX_DENIED`）。
+- **`dsh-tool-docx/fs-binary-local-plugin`**——注册**无围栏**的 `fsBinary.writeBytes`，用于最小环境（测试、headless 脚本）或宿主已在提供者之上围栏的场景。要改用它而不是沙箱版本，可在配置文件的 `cordis.patch.yml` 中覆盖捆绑包行：
+
+  ```yaml
+  - id: fs-binary-sandbox
+    disabled: true
+  - insert:
+      - id: fs-binary-local
+        name: dsh-tool-docx/fs-binary-local-plugin
+  ```
+
+两者都使用与 harness seam 相同的 probe → intent 守卫（`createIfAbsent` / `replaceIfVersion`）→ 原子发布流程：私有 owner-only staging 目录、fsync、然后原子发布（`createIfAbsent` 用硬链接 no-replace 原语），并按目标串行化。第一版省略 harness 的 Win32 DACL 保留仪式——替换文件继承暂存临时文件的所有者 ACL。
+
+对于想刻意把完整后端**挂载为 `ctx.fs`**（替换 `fs-sandbox`）的宿主，包还提供提供者类 `dsh-tool-docx/fs-binary-sandbox` 与 `dsh-tool-docx/fs-binary-local`；替换行的配方仍然适用：
+
+```yaml
+- id: fs-sandbox
+  disabled: true
+- insert:
+    - id: fs-binary-sandbox
+      name: dsh-tool-docx/fs-binary-sandbox
+    - id: tool-docx
+      name: dsh-tool-docx
+```
+
+## 设计说明
+
+- **提取**（`src/docx/extract.ts`）用 `fast-xml-parser` 遍历 `word/document.xml`：标题（`Heading1`–`Heading6`、`Title`）、粗体/斜体/删除线 run、通过 `word/numbering.xml` 的嵌套列表（bullet 与 decimal）、管道表格（合并单元格近似）、通过 `word/_rels/document.xml.rels` 的外部超链接，以及按计数占位的嵌入图片。不支持的构造降级为警告，绝不会失败。
+- **生成**（`src/docx/generate.ts`）用 `docx` 库渲染块模型：ATX 标题、带样式的行内 run、9 级 bullet/数字编号、管道表格和 `[text](url)` 外部超链接。`parseMarkdown`（src/markdown.ts）接受提取器输出的子集，因此读 → 改 → 写往返是稳定的。
+- **上限在 seam 层而非工具层强制**——整文件字节上限流入 `ctx.fs.readBytes`（`FS_TOO_LARGE` 映射为 `DOCX_TOO_LARGE`），ZIP 读取器对未压缩总量施加同一上限，因此压缩炸弹无法无界展开。
+- **沙箱对等**——`src/sandbox.ts` 镜像 `dsh-tool-fs` 的升权 API（仅在受限后端下暴露 `sandbox_permissions`/`justification`，拒绝标记映射）；提取共享控制器属于延后工作（见下文）。
+- **宿主文件系统契约**——`src/fs-binary.ts` 声明工具所需的二进制契约，并在调用时解析写入器：优先使用已挂载的 `fsBinary` 服务，否则使用原生提供 `writeBytes` 的宿主 `ctx.fs`。没有任何二进制写入器时，它抛出 `DOCX_HOST_FS_UNSUPPORTED` 并指明修复方式，而不是晦涩的 `fs.writeBytes is not a function`；`docx_read` 只需已发布的 `ctx.fs.readBytes`。
+
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到什么
+
+插件应用时注册一次下面的 `tool:docx-read` 段落：
+
+##### docx 指南段落
+
+```markdown
+MS Word .docx files are binary (ZIP+XML) and the read tool cannot read them. Use docx_read to extract a document as Markdown (default) or structured JSON blocks, docx_create to generate a new .docx from Markdown, and docx_edit to replace a document's content from Markdown while preserving its title/author/created properties. Legacy .doc is not supported — convert it to .docx first.
+```
+
+#### Token 影响
+
+插件挂载期间每次请求有固定的指南成本；作用域工具限制不影响该段落。
+
+#### KV Cache 影响
+
+在指南文本不变时前缀稳定。插件生命周期或文本变更可能从首个变更的提示词段开始使复用失效。
+
+### 工具 schema
+
+#### 模型看到什么
+
+生成的 `docx_read`、`docx_create` 和 `docx_edit` schema——参数与规范输出见上方[工具](#工具)表格汇总。字节/字符上限是部署设置而非模型参数；升权字段只在受限文件系统后端下出现。
+
+#### Token 影响
+
+每个挂载工具每次请求有固定的 schema 成本；配置禁用会同时移除 schema 和指南，而作用域限制只移除 schema。
+
+#### KV Cache 影响
+
+在定义与可见性不变时前缀稳定。配置启用、插件生命周期或作用域限制可能从首个变更的 schema token 开始使复用失效。
+
+### 读取结果
+
+#### 模型看到什么
+
+成功的 `docx_read` 渲染提取的 Markdown（或美化后的 JSON 块）。截断时追加 `\n… (truncated)`；失败是带类型的消息，例如 `file not found: <path>`、`the document is encrypted (password-protected); decryption is not supported`，或旧版提示 `legacy .doc format is not supported — convert the document to .docx first`。
+
+#### Token 影响
+
+数据相关结果由 `maxReadChars`（或调用的 `max_chars`）限制，并在压缩前重复发送。
+
+#### KV Cache 影响
+
+仅追加；新可见内容跟随可复用请求前缀，不会使既有 KV-cache 条目失效。
+
+### 创建/编辑结果
+
+#### 模型看到什么
+
+成功的创建/编辑渲染一个简短的 `<path>`/`<type>docx</type>` 信封并附带字节大小——绝不返回文档正文。近似警告（图片、合并单元格、代码块）携带在规范 `warnings` 数组中并以纯文本渲染。
+
+#### Token 影响
+
+只有保留的调用参数（含完整 Markdown 输入）和简短结果增加 token；生成的包字节绝不进入会话日志。
+
+#### KV Cache 影响
+
+仅追加；新可见内容跟随可复用请求前缀，不会使既有 KV-cache 条目失效。
+
+### 参数错误
+
+#### 模型看到什么
+
+空 `file_path` 变成 `Error: file_path must be a non-empty string`；markdown 超出输入上限变成 `Error: markdown exceeds the <n>-character limit`。
+
+#### Token 影响
+
+只有失败的调用增加这些保留 token。
+
+#### KV Cache 影响
+
+仅追加；新可见内容跟随可复用请求前缀，不会使既有 KV-cache 条目失效。
+
+## 已知限制与延后工作
+
+- **不支持旧版 `.doc`（OLE）**——二进制 OLE 需要 LibreOffice 或 Word COM 转换；工具返回 `DOCX_LEGACY_DOC` 并提示先转换为 `.docx`。
+- **不提取或嵌入图片**——`docx_read` 统计图片并输出占位符；`docx_create`/`docx_edit` 丢弃图片语法并给出警告。提取图片字节并在生成时嵌入属于延后工作。
+- **往返会重新生成文档**——样式、页面设置、页眉页脚和分节符不会被保留；编辑会用默认样式重建正文，只保留 title/author/created。版式保真不是往返的目标。
+- **合并单元格近似**——`gridSpan`/`vMerge` 降级为普通管道表格单元格并给出警告；脚注、尾注、文本框和分页符会被丢弃（含警告）。
+- **沙箱控制器与 `dsh-tool-fs` 重复**——提取共享的 `FsSandboxController` 属于延后工作；在此之前两份拷贝必须保持同步。
+- **Markdown 输入子集**——引用块、水平线、嵌套围栏和图片无法表示；它们降级为段落并给出警告（围栏代码变成代码样式段落）。
+
+## 开发
+
+```sh
+pnpm install
+pnpm typecheck   # tsc 检查 src/
+pnpm build       # tsc → lib/types + tsdown → lib/index.js, lib/invariant.js
+pnpm test        # vitest：单元转换测试 + 基于假 fs 的消费者测试
+pnpm pack        # 生成 npm tarball（files：lib/index.js、lib/invariant.js、lib/types/**/*.d.ts）
+```
+
+结构：
+
+- `src/docx/`——ZIP/XML 提取与 `docx` 库生成；
+- `src/tools/`——三个工具注册；
+- `src/fs-binary.ts`——二进制文件系统契约与调用时写入器解析（`fsBinary` 服务或原生 `ctx.fs.writeBytes`）；
+- `src/fs-binary-local.ts`、`src/fs-binary-sandbox.ts`、`src/fsio-bytes.ts`、`src/path-contains.ts`——二进制 fs 提供者类以及原子写入器与包含性辅助；
+- `src/fs-binary-sandbox-plugin.ts`、`src/fs-binary-local-plugin.ts`——注册 `fsBinary` 服务的命名空间插件（捆绑包的默认挂载）；
+- `tests/`——转换往返测试、提供者测试与针对已发布 `ToolRuntime` 服务的消费者测试（自 `dsh-tools@0.1.0-rc.7` 起导出）。
+
+## 与 deepseek-harness 的关系
+
+该插件是**为 DeepSeek Harness 编写的原创独立项目**——它接入 harness 的公开服务（`tools`、`fs`、`systemPrompt`），并在本地 `deepseek-harness` 检出中开发以对 harness 进行测试。它不是共享 `deepseek-harness` 仓库中某个插件的副本，也不属于该仓库；本仓库是规范的发行渠道。两点实现说明：
+
+1. `src/fs-binary.ts`（宿主契约 + 写入器解析）——二进制 `readBytes`/`writeBytes` 契约是插件设计的一部分。`readBytes` 自 `0.1.0-rc.7` 起已发布在 harness 的 `dsh-fs` 发布线中；`writeBytes` 没有，因此[二进制 fs 提供者](#二进制-fs-提供者)以独立的 `fsBinary` 服务提供它，而不是修补宿主；
+2. `tests/` 针对已发布的 `ToolRuntime` 服务运行（自 `dsh-tools@0.1.0-rc.7` 起导出），因此消费者测试走真实的注册表流水线而非本地替身。
+
+该插件完全在本仓库中针对已发布的 `@deepseek-ai/*` 包进行开发与维护；harness 检出只是用于集成验证的运行目标，不携带本插件的副本。
+
+## 许可证
+
+MIT © 2026 BroBFG。`src/sandbox.ts` 的部分内容、`src/fsio-bytes.ts` 中的原子写入模式与 `src/path-contains.ts` 中的包含性逻辑衍生自 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)（MIT，Copyright (c) 2026 DeepSeek）——见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# dsh-tool-docx bundle patch: mounts the plugin into a profile layer stack.
+# Applied as a bundle layer (after dsh-base and the mode bundle) when the
+# package is installed into a profile with `dsh plugin --profile <name> add`.
+#
+# The base bundle's `fs-sandbox` row keeps providing `ctx.fs` UNCHANGED. This
+# plugin adds two rows next to it: `fs-binary-sandbox` registers the binary
+# `writeBytes` primitive as a SEPARATE `fsBinary` service (fenced by the same
+# per-call policy as every sandbox mutation), and `tool-docx` mounts the docx
+# tool suite, which resolves the binary writer from `fsBinary` (or a host
+# `ctx.fs` that natively provides `writeBytes`) at call time. The host
+# filesystem is never replaced, so this bundle cannot break the harness boot —
+# at worst, without the provider, the mutating docx tools report
+# `DOCX_HOST_FS_UNSUPPORTED`.
+- insert:
+    - id: fs-binary-sandbox
+      name: dsh-tool-docx/fs-binary-sandbox-plugin
+    - id: tool-docx
+      name: dsh-tool-docx

package/lib/fs-binary-D0seEN6R.js

@@ -0,0 +1,63 @@
+import { HarnessError } from "@deepseek-ai/dsh-llm";
+import { FsError } from "@deepseek-ai/dsh-fs";
+//#region lib/types/error.js
+/**
+* Typed error vocabulary for the docx tools: a stable machine-routable code
+* distinct from the human-readable message, plus the mapping from the
+* filesystem seam's `FsError` codes.
+* @module dsh-tool-docx/error
+*/
+/** Typed docx failure. Extends {@link HarnessError} for a stable code and `cause` chaining. */
+var DocxError = class extends HarnessError {
+	code;
+	constructor(message, code, options) {
+		super(message, code, options);
+		this.code = code;
+	}
+};
+/** Map a filesystem-seam failure to the docx vocabulary; other errors pass through.
+* @param error - the thrown filesystem error (or any other value).
+* @returns the mapped `DocxError`, or the original value when it is not an `FsError`.
+*/
+function mapFsError(error) {
+	if (!(error instanceof FsError)) return error;
+	switch (error.code) {
+		case "FS_NOT_FOUND": return new DocxError(error.message, "DOCX_NOT_FOUND", { cause: error });
+		case "FS_NOT_REGULAR_FILE": return new DocxError(error.message, "DOCX_NOT_REGULAR_FILE", { cause: error });
+		case "FS_TOO_LARGE": return new DocxError(error.message, "DOCX_TOO_LARGE", { cause: error });
+		case "FS_NOT_OBSERVED": return new DocxError(error.message, "DOCX_EXISTS", { cause: error });
+		case "FS_STALE_VERSION": return new DocxError(error.message, "DOCX_STALE", { cause: error });
+		case "FS_ABORTED": return error;
+		default: return new DocxError(error.message, "DOCX_WRITE_ERROR", { cause: error });
+	}
+}
+//#endregion
+//#region lib/types/fs-binary.js
+/** The service name the plugin's binary providers register under. */
+const FS_BINARY_SERVICE = "fsBinary";
+/**
+* Resolve the binary writer for this context: the plugin's `fsBinary` service
+* when mounted, else a host `ctx.fs` that natively provides `writeBytes`.
+* @param ctx - the plugin context; `fsBinary` is resolved optionally.
+* @returns the bound writer, or `undefined` when no binary writer is mounted.
+*/
+function resolveWriteBytes(ctx) {
+	const fsBinary = ctx.get(FS_BINARY_SERVICE);
+	if (fsBinary?.writeBytes !== void 0) return fsBinary.writeBytes.bind(fsBinary);
+	const fs = ctx.fs;
+	if (typeof fs.writeBytes === "function") return fs.writeBytes.bind(fs);
+}
+/**
+* Resolve the binary writer or fail with the typed host-requirement error.
+* @param ctx - the plugin context.
+* @returns the bound writer.
+* @throws `DOCX_HOST_FS_UNSUPPORTED` when neither the `fsBinary` service nor a
+*   native `ctx.fs.writeBytes` is available.
+*/
+function requireWriteBytes(ctx) {
+	const writeBytes = resolveWriteBytes(ctx);
+	if (writeBytes === void 0) throw new DocxError(`the host filesystem seam lacks the binary writeBytes primitive — install the dsh-tool-docx bundle (dsh plugin --profile web add dsh-tool-docx), which mounts the ${FS_BINARY_SERVICE} provider, or use a deepseek-harness build that includes fs.writeBytes natively`, "DOCX_HOST_FS_UNSUPPORTED");
+	return writeBytes;
+}
+//#endregion
+export { mapFsError as i, requireWriteBytes as n, DocxError as r, FS_BINARY_SERVICE as t };

package/lib/fs-binary-local-n8Ls-bn_.js

@@ -0,0 +1,155 @@
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+import { chmod, link, mkdir, open, rename, rm } from "node:fs/promises";
+//#region lib/types/fsio-bytes.js
+/**
+* Minimal atomic binary write for the plugin's local filesystem provider.
+* Mirrors the deepseek-harness `fs-local` `writeFileAtomic` semantics — a
+* private owner-only staging directory, an exclusive temp file, fsync, then an
+* atomic publish; a `createIfAbsent` publish uses a hard-link no-replace
+* primitive so a concurrent creator wins (`FS_NOT_OBSERVED`) — for a
+* `Uint8Array` payload. The Win32 DACL-preservation ceremony of the harness
+* original is intentionally omitted in this first version (a replacement
+* inherits the temp file's owner-only ACL).
+* @module dsh-tool-docx/fsio-bytes
+*/
+function throwIfAborted(signal, verb) {
+	if (signal?.aborted) throw new FsError(`${verb} aborted`, "FS_ABORTED");
+}
+function isAbortError(error) {
+	return error instanceof Error && error.name === "AbortError";
+}
+function isEEXIST(error) {
+	return error instanceof Error && error.code === "EEXIST";
+}
+function isENOENT(error) {
+	return error instanceof Error && error.code === "ENOENT";
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Atomically write raw bytes to `absolutePath`: stage an owner-only temp file
+* in a private sibling directory, fsync, then publish. With `createIfAbsent`,
+* publish uses a hard link that fails if the target appeared concurrently
+* (`FS_NOT_OBSERVED`); otherwise the temp is renamed over the target.
+* @param absolutePath - destination path (typically a target key); missing
+* parent directories are created.
+* @param data - the raw bytes to write.
+* @param signal - cancellation checked before and during the write.
+* @param createIfAbsent - when provided, publish with the no-replace primitive
+* and reject a concurrent creator with `FS_NOT_OBSERVED`.
+*/
+async function writeFileAtomicBytes(absolutePath, data, signal, createIfAbsent) {
+	throwIfAborted(signal, "write");
+	const directory = dirname(absolutePath);
+	await mkdir(directory, { recursive: true });
+	throwIfAborted(signal, "write");
+	const stagingDir = join(directory, `.${basename(absolutePath)}.${process.pid}.${randomUUID()}.tmpdir`);
+	const tempPath = join(stagingDir, `${basename(absolutePath)}.tmp`);
+	let handle;
+	let stagingCreated = false;
+	try {
+		await mkdir(stagingDir, { mode: 448 });
+		stagingCreated = true;
+		await chmod(stagingDir, 448);
+		handle = await open(tempPath, "wx", 384);
+		await handle.chmod(384);
+		await handle.writeFile(Buffer.from(data), { ...signal ? { signal } : {} });
+		await handle.sync();
+		await handle.close();
+		handle = void 0;
+		throwIfAborted(signal, "write");
+		if (createIfAbsent !== void 0) try {
+			await link(tempPath, absolutePath);
+		} catch (error) {
+			if (isEEXIST(error) || isENOENT(error)) throw new FsError(`cannot overwrite existing "${createIfAbsent.displayPath}" without reading it first`, "FS_NOT_OBSERVED");
+			throw error;
+		}
+		else await rename(tempPath, absolutePath);
+		try {
+			await rm(stagingDir, {
+				recursive: true,
+				force: true
+			});
+		} catch (_cleanupFailure) {}
+	} catch (error) {
+		let failure = isAbortError(error) ? new FsError("write aborted", "FS_ABORTED") : error;
+		if (handle) try {
+			await handle.close();
+		} catch (closeError) {
+			failure = new FsError(`write failed (${errorMessage(failure)}) and temp close failed (${errorMessage(closeError)})`, "FS_NOT_FOUND", { cause: failure });
+		}
+		if (!stagingCreated) throw failure;
+		try {
+			await rm(stagingDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		throw failure;
+	}
+}
+//#endregion
+//#region lib/types/fs-binary-local.js
+/**
+* The plugin's own distribution of the harness's binary filesystem seam: a
+* local `ctx.fs` provider that adds the `writeBytes` primitive to the
+* published `@deepseek-ai/dsh-fs-local` backend. Mount this plugin as `ctx.fs`
+* (in place of `dsh-fs-local`) on a host whose filesystem seam lacks
+* `writeBytes`; the docx tools then run unchanged, with the same
+* probe → intent-guard → atomic-publish flow the harness seam provides.
+*
+* For a sandboxed host (a `SandboxedFileSystem` mounted as `ctx.fs`), mount
+* `dsh-tool-docx/fs-binary-sandbox` instead — it preserves the policy fence.
+* @module dsh-tool-docx/fs-binary-local
+*/
+/**
+* The probe → intent-guard → atomic-publish body shared by the plugin's binary
+* fs providers: stat the target, enforce the version/absence intent
+* (`FS_STALE_VERSION` / `FS_NOT_OBSERVED`), publish atomically, and report the
+* fresh version.
+* @param provider - the filesystem whose `stat` observes the target (the
+* provider itself, after any sandbox fence has run).
+* @param target - the (possibly fence-checked) target to write.
+* @param data - the raw bytes to write.
+* @param expected - the write intent guarding the write; omit for unconditional.
+* @param signal - cancellation.
+* @returns the create/update outcome with the fresh version.
+*/
+async function performByteWrite(provider, target, data, expected, signal) {
+	const existing = await provider.stat(target, signal);
+	if (existing !== void 0 && existing.type !== "file") throw new FsError(`cannot write "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
+	if (expected?.kind === "replaceIfVersion") {
+		if (existing === void 0 || existing.version !== expected.version) throw new FsError(`cannot write "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+	} else if (expected?.kind === "createIfAbsent" && existing !== void 0) throw new FsError(`cannot overwrite existing "${target.displayPath}" without reading it first`, "FS_NOT_OBSERVED");
+	await writeFileAtomicBytes(String(target.targetKey), data, signal, expected?.kind === "createIfAbsent" ? { displayPath: target.displayPath } : void 0);
+	const fresh = await provider.stat(target, signal);
+	if (fresh === void 0) throw new FsError(`cannot stat "${target.displayPath}" after write`, "FS_IO_ERROR");
+	return {
+		operation: existing === void 0 ? "create" : "update",
+		version: fresh.version
+	};
+}
+/**
+* The local filesystem backend with the binary write primitive. Inherits the
+* full published `LocalFileSystem` contract (text reads/writes, `readBytes`,
+* intent handling) and adds `writeBytes`. Per-targetKey operations are
+* serialized with a tail promise, mirroring the backend's own lock discipline.
+*/
+var DocxBinaryFileSystem = class extends LocalFileSystem {
+	byteLocks = /* @__PURE__ */ new Map();
+	withByteLock(key, op) {
+		const next = (this.byteLocks.get(key) ?? Promise.resolve()).then(op, op);
+		this.byteLocks.set(key, next.then(() => void 0, () => void 0));
+		return next;
+	}
+	/** Write raw bytes with an optional version/absence guard. */
+	async writeBytes(target, data, expected, signal) {
+		return this.withByteLock(String(target.targetKey), () => performByteWrite(this, target, data, expected, signal));
+	}
+};
+//#endregion
+export { performByteWrite as n, DocxBinaryFileSystem as t };

package/lib/fs-binary-local-plugin.js

@@ -0,0 +1,24 @@
+import { t as FS_BINARY_SERVICE } from "./fs-binary-D0seEN6R.js";
+import { n as performByteWrite } from "./fs-binary-local-n8Ls-bn_.js";
+//#region lib/types/fs-binary-local-plugin.js
+/**
+* `fs-binary-local-plugin` — the mount for minimal hosts without a sandbox
+* policy: a namespace plugin that registers the binary write primitive as the
+* SEPARATE `fsBinary` service, unfenced, over the host's own `ctx.fs`. The
+* host filesystem is left untouched. Sandboxed hosts should mount
+* `fs-binary-sandbox-plugin` instead, which applies the policy fence.
+* @module dsh-tool-docx/fs-binary-local-plugin
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "fs-binary-local";
+/** Services required: the host filesystem (reads/stat/resolve and the write body). */
+const inject = ["fs"];
+/**
+* Register the `fsBinary` service: unfenced binary writes over `ctx.fs`.
+* @param ctx - the plugin context; execution uses its `fs` service.
+*/
+function apply(ctx) {
+	ctx.provide(FS_BINARY_SERVICE, { writeBytes: (target, data, expected, signal) => performByteWrite(ctx.fs, target, data, expected, signal) });
+}
+//#endregion
+export { apply, inject, name };

package/lib/fs-binary-local.js

@@ -0,0 +1,2 @@
+import { n as performByteWrite, t as DocxBinaryFileSystem } from "./fs-binary-local-n8Ls-bn_.js";
+export { DocxBinaryFileSystem, DocxBinaryFileSystem as default, performByteWrite };

package/lib/fs-binary-sandbox-BobaE5Hr.js

@@ -0,0 +1,135 @@
+import { n as performByteWrite } from "./fs-binary-local-n8Ls-bn_.js";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { writableRoots } from "@deepseek-ai/dsh-sandbox";
+import { dirname, sep } from "node:path";
+import { stat } from "node:fs/promises";
+import { SandboxedFileSystem } from "@deepseek-ai/dsh-fs-sandbox";
+//#region lib/types/path-contains.js
+/**
+* Path-containment mechanics for the plugin's sandboxed filesystem provider —
+* ported from the deepseek-harness `fs-sandbox` package (MIT, see LICENSE):
+* the lexical fast path handles canonical spellings, and filesystem identity
+* supplies the conservative fallback for alias-equivalent roots (Windows 8.3
+* names, casing).
+* @module dsh-tool-docx/path-contains
+*/
+const MISSING_CODES = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR"]);
+function isMissing(error) {
+	const code = error.code;
+	return MISSING_CODES.has(code);
+}
+function comparablePath(path, caseSensitive) {
+	return caseSensitive ? path : path.toLowerCase();
+}
+function isLexicallyUnder(path, root, caseSensitive) {
+	const comparableTarget = comparablePath(path, caseSensitive);
+	const comparableRoot = comparablePath(root, caseSensitive);
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+async function statIfPresent(path) {
+	try {
+		return await stat(path, { bigint: true });
+	} catch (error) {
+		if (isMissing(error)) return void 0;
+		throw error;
+	}
+}
+function sameIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+* Determine whether a canonical target is a writable root or lies beneath it.
+* The lexical fast path handles normal canonical spellings; when spellings
+* differ, walk the target's existing ancestors and compare filesystem identity
+* with the root.
+* @param path - canonical target key, which may end in a missing suffix.
+* @param root - canonical writable root.
+* @param caseSensitive - whether lexical comparison preserves case; defaults
+* to the host filesystem convention used by supported platforms.
+* @returns whether the target is the root or a descendant of it.
+*/
+async function isPathUnder(path, root, caseSensitive = process.platform !== "win32") {
+	if (isLexicallyUnder(path, root, caseSensitive)) return true;
+	const rootInfo = await statIfPresent(root);
+	if (!rootInfo) return false;
+	let ancestor = path;
+	while (true) {
+		const ancestorInfo = await statIfPresent(ancestor);
+		if (ancestorInfo && sameIdentity(ancestorInfo, rootInfo)) return true;
+		const parent = dirname(ancestor);
+		if (parent === ancestor) return false;
+		ancestor = parent;
+	}
+}
+//#endregion
+//#region lib/types/fs-binary-sandbox.js
+/**
+* The sandbox-preserving binary fs provider: `DocxSandboxedFileSystem` extends
+* the published `@deepseek-ai/dsh-fs-sandbox` `SandboxedFileSystem` and adds the
+* binary `writeBytes` primitive through the SAME policy fence as the base's
+* `writeText`/`editText`. The fence itself (`checkWriteTarget`) is shared with
+* the `fs-binary-sandbox-plugin` namespace plugin, which registers it as the
+* separate `fsBinary` service — the recommended mount for sandboxed hosts,
+* because it never replaces the host's own `ctx.fs`.
+* @module dsh-tool-docx/fs-binary-sandbox
+*/
+/**
+* Enforce the per-call policy against `target` and return the exact target the
+* mutation must use — the same containment the base `SandboxedFileSystem`
+* applies to its mutations (`danger-full-access` passes unfenced, `read-only`
+* denies, `workspace-write` re-canonicalizes now and requires containment under
+* a writable root). Throws `FS_SANDBOX_DENIED` on refusal.
+* @param resolveTarget - resolves a display path to a fresh canonical target
+* (the provider's own `resolve`, so the checked identity is the mutated one).
+* @param policy - the per-call mode and workspace root.
+* @param target - the caller's resolved target.
+* @returns the fresh target the mutation must use.
+*/
+async function checkWriteTarget(resolveTarget, policy, target) {
+	const { mode } = policy;
+	if (mode === "danger-full-access") return target;
+	if (mode === "read-only") throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
+	const fresh = await resolveTarget(target.displayPath);
+	let contained = false;
+	for (const root of writableRoots(policy)) if (await isPathUnder(fresh.targetKey, root)) {
+		contained = true;
+		break;
+	}
+	if (!contained) throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+	return fresh;
+}
+/**
+* The sandboxed filesystem backend with the binary write primitive. Inherits
+* the full `SandboxedFileSystem` contract (local text/binary reads, fenced
+* `writeText`/`editText`) and adds fenced `writeBytes`: the per-call policy
+* fence runs first (the same containment check the base applies to mutations),
+* then the probe → intent-guard → atomic-publish body. Per-targetKey
+* operations are serialized with a tail promise. Intended for hosts that want
+* the full backend mounted AS `ctx.fs` (replacing `fs-sandbox` deliberately);
+* the default mount for sandboxed hosts is the `fs-binary-sandbox-plugin`,
+* which registers this same fenced write under the separate `fsBinary` service.
+*/
+var DocxSandboxedFileSystem = class extends SandboxedFileSystem {
+	byteLocks = /* @__PURE__ */ new Map();
+	withByteLock(key, op) {
+		const next = (this.byteLocks.get(key) ?? Promise.resolve()).then(op, op);
+		this.byteLocks.set(key, next.then(() => void 0, () => void 0));
+		return next;
+	}
+	/**
+	* Enforce the per-call policy against `target` and return the exact target
+	* the mutation must use, via the shared {@link checkWriteTarget}.
+	*/
+	async checkedWriteTarget(target, sandboxPolicy) {
+		return checkWriteTarget((path) => this.resolve(path), sandboxPolicy ?? this.ctx.sandboxPolicy.resolve(), target);
+	}
+	/** Write raw bytes with an optional version/absence guard, through the policy fence. */
+	async writeBytes(target, data, expected, signal, sandboxPolicy) {
+		const checked = await this.checkedWriteTarget(target, sandboxPolicy);
+		return this.withByteLock(String(checked.targetKey), () => performByteWrite(this, checked, data, expected, signal));
+	}
+};
+//#endregion
+export { checkWriteTarget as n, DocxSandboxedFileSystem as t };

package/lib/fs-binary-sandbox-plugin.js

@@ -0,0 +1,31 @@
+import { t as FS_BINARY_SERVICE } from "./fs-binary-D0seEN6R.js";
+import { n as performByteWrite } from "./fs-binary-local-n8Ls-bn_.js";
+import { n as checkWriteTarget } from "./fs-binary-sandbox-BobaE5Hr.js";
+//#region lib/types/fs-binary-sandbox-plugin.js
+/**
+* `fs-binary-sandbox-plugin` — the recommended mount for sandboxed hosts: a
+* namespace plugin that registers the binary write primitive as the SEPARATE
+* `fsBinary` service, fenced by the same per-call policy as the harness's
+* `fs-sandbox` mutations. The host's own `ctx.fs` (and its `fs-sandbox` row)
+* is left untouched, so this plugin can never break the host filesystem — at
+* worst the docx write tools report `DOCX_HOST_FS_UNSUPPORTED` when it is not
+* mounted.
+* @module dsh-tool-docx/fs-binary-sandbox-plugin
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "fs-binary-sandbox";
+/** Services required: the host filesystem (reads/stat/resolve) and the policy. */
+const inject = ["fs", "sandboxPolicy"];
+/**
+* Register the `fsBinary` service: fenced binary writes through the same
+* containment the sandbox applies to every mutation.
+* @param ctx - the plugin context; execution uses its `fs` and `sandboxPolicy`.
+*/
+function apply(ctx) {
+	ctx.provide(FS_BINARY_SERVICE, { writeBytes: (target, data, expected, signal, sandboxPolicy) => {
+		const policy = sandboxPolicy ?? ctx.sandboxPolicy.resolve();
+		return checkWriteTarget((path) => ctx.fs.resolve(path), policy, target).then((checked) => performByteWrite(ctx.fs, checked, data, expected, signal));
+	} });
+}
+//#endregion
+export { apply, inject, name };

package/lib/fs-binary-sandbox.js

@@ -0,0 +1,2 @@
+import { n as checkWriteTarget, t as DocxSandboxedFileSystem } from "./fs-binary-sandbox-BobaE5Hr.js";
+export { DocxSandboxedFileSystem, DocxSandboxedFileSystem as default, checkWriteTarget };