@deepseek-ai/dsh-fs-ssh 0.1.6-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/ssh/fs-ssh/README.md
+README.md: 1f403796792611abc438f140356e442fbb357cde
+README.zh.md: 7e77afe6c87ed7725dea87215c9a3647d650ae95

package/README.md

@@ -0,0 +1,80 @@
+---
+description: "Remote filesystem semantics for consumers sharing files with SSH subprocesses."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-fs-ssh
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-fs-ssh` provides `ctx.fs` in the SSH helper’s filesystem. File tools read and mutate the same files that remote Bash, terminals, language servers and Node programs see. Remote canonicalization, version guards and atomic mutations use the local filesystem implementations installed beside the helper.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this provider with [`dsh-ssh`](../ssh/README.md) and `sandboxPolicy`; use its paired SSH subprocess and sandbox providers for execution. This provider has no configuration fields: connection identity and the default workspace belong to `dsh-ssh`, while file-effect mode belongs to `sandboxPolicy`.
+
+`resolve()` canonicalizes paths on the remote host. `processPath()` and `fileUrl()` name files in that same remote namespace; they do not grant host-side access. File URLs encode literal percent signs, backslashes and newlines without changing the filename. `processPathFromHostPath()` returns `undefined`, so consumers requiring an installed executable or bootstrap must supply a remote artifact explicitly.
+
+Reads preserve the shared filesystem error codes. Writes and edits send the resolved per-call policy to the helper, which canonicalizes the workspace and enforces it beside the atomic mutation. Lost transport reports an I/O failure; a mutation may already have committed and is not retried automatically.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The helper reuses [`fs-local`](../../fs/fs-local/README.md) and [`fs-sandbox`](../../fs/fs-sandbox/README.md), preserving symlink identity, stale-version rejection, diff bases and publication semantics. UTF-8 streaming uses bounded pull requests and closes its remote iterator when the consumer stops early.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Filesystem subsystem](../../../docs/subsystems/filesystem.md) — shared operations and error meanings.
+- [SSH connection](../ssh/README.md) — deployment and disconnection behavior.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through existing filesystem consumers, which present remote paths and file contents while owning every tool and prompt.
+
+#### KV Cache effect
+
+This provider contributes no request-prefix content. Its consumers own model-visible tools and results.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Whole-text reads and individual byte windows are limited to 8 MiB by the helper. Use text streaming or multiple byte windows for larger reads; other JSON transfers also obey the connection’s frame cap.
+- Remote file URLs are execution coordinates, not host filesystem handles or Web download links.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+No invariant companion is published. Wire validation and the owning filesystem, subprocess and sandbox providers enforce the observable obligations; this adapter adds no independently observed state relation.
+
+</details>

package/README.zh.md

@@ -0,0 +1,80 @@
+---
+description: "面向与 SSH 子进程共享文件的消费方，说明远端文件系统语义。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-fs-ssh
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-fs-ssh` 在 SSH 辅助进程的文件系统中提供 `ctx.fs`。文件工具读写的文件与远端 Bash、终端、语言服务器和 Node 程序看到的文件一致。远端路径规范化、版本保护及原子修改使用辅助程序旁安装的本地文件系统实现。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延后工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+将本提供方与 [`dsh-ssh`](../ssh/README.zh.md) 及 `sandboxPolicy` 一同挂载，并使用配套 SSH 子进程与沙箱提供方执行程序。本提供方没有配置字段：连接身份和默认工作区属于 `dsh-ssh`，文件效果模式属于 `sandboxPolicy`。
+
+`resolve()` 在远端主机上规范化路径。`processPath()` 与 `fileUrl()` 在同一个远端命名空间中标识文件，并不授予主机侧访问能力。文件 URL 对字面的百分号、反斜杠和换行进行编码，保留原文件名。`processPathFromHostPath()` 返回 `undefined`，因此需要已安装可执行文件或引导程序的消费方必须显式提供远端产物。
+
+读取保留共享文件系统错误码。写入和编辑将已解析的逐次调用策略发送给辅助程序，由其规范化工作区并在原子修改所在位置执行策略。传输丢失报告 I/O 失败；修改可能已经提交，不会自动重试。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节 — 点击展开</summary>
+
+辅助程序复用 [`fs-local`](../../fs/fs-local/README.zh.md) 与 [`fs-sandbox`](../../fs/fs-sandbox/README.zh.md)，保留符号链接身份、陈旧版本拒绝、差异基线及发布语义。UTF-8 流使用有界拉取请求，在消费方提前停止时关闭远端迭代器。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [文件系统子系统](../../../docs/subsystems/filesystem.zh.md) — 共享操作及错误含义。
+- [SSH 连接](../ssh/README.zh.md) — 部署与断连行为。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接通过现有文件系统消费方产生影响，由它们展示远端路径及文件内容，并负责每个工具与提示。
+
+#### KV Cache 影响
+
+本提供方不贡献请求前缀内容。面向模型的工具与结果由消费方负责。
+
+## 已知限制与延后工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 辅助程序将整段文本读取及单次字节窗口限制为 8 MiB。更大的读取需使用文本流或多个字节窗口；其他 JSON 传输也受连接消息大小上限约束。
+- 远端文件 URL 是执行坐标，不是主机文件系统句柄或 Web 下载链接。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+本包不发布不变式伴随入口。消息校验及所属文件系统、子进程和沙箱提供方执行可观察的约束；此适配器没有增加可独立观察的状态关系。
+
+</details>

package/lib/index.js

@@ -0,0 +1,121 @@
+import { posix } from "node:path";
+import { pathToFileURL } from "node:url";
+import { FileSystem, FsError } from "@deepseek-ai/dsh-fs";
+import { RemoteOperationError } from "@deepseek-ai/dsh-ssh/protocol";
+import { editResultSchema, entriesSchema, infoSchema, pathInfoSchema, targetSchema, textStreamIdSchema, writeResultSchema } from "@deepseek-ai/dsh-ssh/schemas";
+import { z } from "zod";
+//#region lib/types/index.js
+/** Filesystem provider preserving remote identities and helper-owned atomic mutations. */
+const errorCodes = {
+	FS_NOT_FOUND: true,
+	FS_NOT_DIRECTORY: true,
+	FS_NOT_TEXT: true,
+	FS_NOT_REGULAR_FILE: true,
+	FS_TOO_LARGE: true,
+	FS_PERMISSION_DENIED: true,
+	FS_SANDBOX_DENIED: true,
+	FS_IO_ERROR: true,
+	FS_STALE_VERSION: true,
+	FS_NOT_OBSERVED: true,
+	FS_AMBIGUOUS_EDIT: true,
+	FS_EDIT_NOT_FOUND: true,
+	FS_ABORTED: true
+};
+/** Remote filesystem paired with the SSH subprocess and sandbox providers. */
+var SshFileSystem = class extends FileSystem {
+	static inject = ["ssh", "sandboxPolicy"];
+	get sandboxMode() {
+		return this.ctx.sandboxPolicy.defaultMode;
+	}
+	async resolve(path, opts) {
+		return await this.call("fs.resolve", {
+			path,
+			cwd: opts?.cwd
+		}, targetSchema, opts?.signal);
+	}
+	processPath(target) {
+		return String(target.targetKey);
+	}
+	fileUrl(target) {
+		return pathToFileURL(this.processPath(target)).href;
+	}
+	contains(parent, child) {
+		const path = posix.relative(this.processPath(parent), this.processPath(child));
+		return path === "" || !path.startsWith("../") && path !== ".." && !posix.isAbsolute(path);
+	}
+	async stat(target, signal) {
+		return await this.call("fs.stat", { target }, infoSchema.nullable(), signal) ?? void 0;
+	}
+	async lstat(path, opts, signal) {
+		return await this.call("fs.lstat", {
+			path,
+			cwd: opts?.cwd
+		}, pathInfoSchema.nullable(), signal) ?? void 0;
+	}
+	readText(target, signal) {
+		return this.call("fs.readText", { target }, z.string(), signal);
+	}
+	async streamText(target, signal) {
+		const id = await this.call("fs.stream", { target }, textStreamIdSchema, signal);
+		const call = this.call.bind(this);
+		return (async function* () {
+			let ended = false;
+			try {
+				while (!ended) {
+					signal?.throwIfAborted();
+					const next = await call("fs.next", { id }, z.object({
+						done: z.boolean(),
+						value: z.string()
+					}).strict(), signal);
+					ended = next.done;
+					if (next.value.length > 0) yield next.value;
+				}
+			} finally {
+				if (!ended) await call("fs.streamClose", { id }, z.null()).catch(() => {});
+			}
+		})();
+	}
+	async readBytes(target, signal, maxBytes) {
+		return Buffer.from(await this.call("fs.readBytes", {
+			target,
+			maxBytes
+		}, z.base64(), signal), "base64");
+	}
+	async readByteRange(target, range, signal) {
+		return Buffer.from(await this.call("fs.readRange", {
+			target,
+			...range
+		}, z.base64(), signal), "base64");
+	}
+	async listDir(target, signal) {
+		return await this.call("fs.list", { target }, entriesSchema, signal);
+	}
+	async writeText(target, content, expected, signal, sandboxPolicy) {
+		const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+		return await this.call("fs.write", {
+			target,
+			content,
+			expected,
+			policy
+		}, writeResultSchema, signal);
+	}
+	async editText(target, edit, expected, signal, sandboxPolicy) {
+		const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+		return await this.call("fs.edit", {
+			target,
+			edit,
+			expected,
+			policy
+		}, editResultSchema, signal);
+	}
+	async call(method, params, schema, signal) {
+		try {
+			return await this.ctx.ssh.request(method, params, schema, signal);
+		} catch (error) {
+			if (error instanceof RemoteOperationError && error.code !== void 0 && Object.hasOwn(errorCodes, error.code)) throw new FsError(error.message, error.code, { cause: error });
+			throw new FsError(error instanceof Error ? error.message : String(error), signal?.aborted ? "FS_ABORTED" : "FS_IO_ERROR", { cause: error });
+		}
+	}
+};
+//#endregion
+export { SshFileSystem, SshFileSystem as default };

package/lib/types/index.d.ts

@@ -0,0 +1,34 @@
+import { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsTarget, FsVersion, FsWriteIntent, FsWriteOutcome } from '@deepseek-ai/dsh-fs';
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
+/** Remote filesystem paired with the SSH subprocess and sandbox providers. */
+export declare class SshFileSystem extends FileSystem {
+    static inject: string[];
+    get sandboxMode(): SandboxMode;
+    resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<FsTarget>;
+    processPath(target: FsTarget): string;
+    fileUrl(target: FsTarget): string;
+    contains(parent: FsTarget, child: FsTarget): boolean;
+    stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
+    lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
+    readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
+    streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
+    readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
+    readByteRange(target: FsTarget, range: {
+        offset: number;
+        length: number;
+    }, signal?: AbortSignal): Promise<Uint8Array>;
+    listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
+    writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsWriteOutcome>;
+    editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: FsVersion;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsEditOutcome>;
+    private call;
+}
+export default SshFileSystem;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deepseek-ai/dsh-fs-ssh",
+  "description": "Filesystem provider over the shared POSIX SSH helper",
+  "version": "0.1.6-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/ssh/fs-ssh"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-ssh": "^0.1.6-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-ssh": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1"
+  }
+}