@deepseek-ai/dsh-subprocess-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/subprocess-ssh/README.md
+README.md: 15afa74f041e9944036c451dacaaedb53ecd9ff9
+README.zh.md: 3417f184fbcb702edeadf3b510663b1a9a58192f

package/README.md

@@ -0,0 +1,85 @@
+---
+description: "Managed SSH subprocess and terminal behavior for Bash, LSP and Node runtime consumers."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-subprocess-ssh
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-subprocess-ssh` implements `ctx.subprocess` using the shared SSH helper. Executable lookup, ordinary processes, fd 7 control traffic and terminal sessions run beside the SSH filesystem. Remote native process owners govern termination and quiescence; consumers continue to own command semantics, output limits and execution deadlines.
+
+## 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 its filesystem provider. It has no deployment configuration of its own. `resolveExecutable()` checks the remote executable namespace; fully specified spawn requests supply the remote cwd, environment, stream dispositions and cleanup grace.
+
+Ordinary spawn returns a handle while remote allocation proceeds. Piped stdin and the optional duplex control endpoint accept writes during allocation. Terminal allocation, writes, foreground inspection, signals and termination retain their asynchronous interfaces.
+
+A direct exit reported by `done` does not prove managed-range quiescence; `waitForExit()` observes that separately. Its optional signal bounds the entire observation, including pending allocation and termination, and cancellation returns `false` without stopping the process. An already confirmed empty range returns `true`; genuine observation failures reject. `terminate()` targets the same remote owner. Connection loss rejects unconfirmed work, and automatic replay never follows an ambiguous launch or mutation.
+
+-----
+
+Terminal shell facts and executable verification come from the remote helper. Lookup misses remain distinct from SSH failures. PTY creation forwards the caller's `terminalType`, and `resize()` updates the remote terminal without replacing its process.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The helper reserves and authenticates all required streams before launch. Stdout, stderr, stdin and fd 7 use separate SSH channels. Collected output publishes a final bounded raw-tail snapshot with whole-stream byte offsets, so network lag cannot change the completed observation. Optional spill files use the local provider’s private retained-output directory on the remote host.
+
+Remote execution delegates to [`subprocess-local`](../../subprocess/subprocess-local/README.md). Native process ownership and platform fallbacks therefore have the same meaning as local execution on that remote OS. SSH carries requests and observations; it does not itself confine the payload.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Subprocess subsystem](../../../docs/subsystems/subprocess.md) — spawn, collection, terminal and lifetime APIs.
+- [SSH sandbox provider](../sandbox-ssh/README.md) — remote file-effect confinement.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through Bash, terminal, LSP and ptc-runtime consumers, which present their existing results and remote paths.
+
+#### 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>
+
+- Completed spill files survive connection disposal and remain available until external temporary-file cleanup.
+- Callers must consume or close raw output streams. Destroying public stdout or stderr closes its matching transport, including when destruction precedes remote allocation. Independent channels allow control progress when stdout is paused, but do not remove per-stream backpressure or shared-network congestion.
+- Loss of the SSH connection leaves remote termination unconfirmed from the client; lease cleanup is a remote action, not a successful client acknowledgement.
+
+<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,85 @@
+---
+description: "面向 Bash、LSP 及 Node 运行时消费方，说明托管 SSH 子进程与终端行为。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-subprocess-ssh
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-subprocess-ssh` 使用共享 SSH 辅助进程实现 `ctx.subprocess`。可执行文件查找、普通进程、fd 7 控制流及终端会话与 SSH 文件系统在同一环境中运行。远端原生进程管理器负责终止与静止状态；消费方继续负责命令语义、输出上限与执行截止时限。
+
+## 目录
+
+- [使用本包](#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) 及其文件系统提供方一同挂载。本提供方没有独立部署配置。`resolveExecutable()` 检查远端可执行文件命名空间；完整的 spawn 请求提供远端 cwd、环境、流处置方式及清理宽限期。
+
+普通 spawn 在远端分配过程中返回句柄。管道 stdin 和可选双工控制端点在分配过程中接受写入。终端分配、写入、前台检查、信号及终止均保留异步接口。
+
+`done` 报告的直接进程退出并不证明托管进程范围已经静止；`waitForExit()` 单独观察该状态。其可选信号约束整个观察过程，包括等待分配和终止；取消返回 `false`，不会停止进程。已确认清空的范围返回 `true`，实际观察故障则拒绝。`terminate()` 针对同一个远端管理器。连接丢失会拒绝未确认的操作；启动或修改结果不明确时绝不自动重放。
+
+-----
+
+终端 shell 信息与可执行文件验证来自远端 helper。查找未命中与 SSH 故障分别报告。PTY 创建传递调用方的 `terminalType`，`resize()` 更新远端终端尺寸，不替换进程。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节 — 点击展开</summary>
+
+辅助进程在启动前预留并认证全部所需流。stdout、stderr、stdin 与 fd 7 使用独立 SSH 通道。收集输出会发布最终的有界原始字节尾部与完整流字节偏移，因此网络延迟不会改变已完成的观测。可选 spill 文件使用远端本地提供方的私有保留输出目录。
+
+远端执行委托给 [`subprocess-local`](../../subprocess/subprocess-local/README.zh.md)。因此，原生进程归属及平台降级方式与该远端操作系统上的本地执行具有相同含义。SSH 承载请求与观察结果，本身不限制程序权限。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [子进程子系统](../../../docs/subsystems/subprocess.zh.md) — spawn、输出收集、终端及生命周期 API。
+- [SSH 沙箱提供方](../sandbox-ssh/README.zh.md) — 远端文件效果限制。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接通过 Bash、终端、LSP 和 PTC 运行时消费方产生影响，由它们展示既有结果与远端路径。
+
+#### KV Cache 影响
+
+本提供方不贡献请求前缀内容。面向模型的工具与结果由消费方负责。
+
+## 已知限制与延后工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 已完成的 spill 文件在连接释放后继续保留，直至外部临时文件清理。
+- 调用方必须消费或关闭原始输出流。销毁公开的 stdout 或 stderr 会关闭对应传输，即使销毁发生在远端分配之前也是如此。独立通道允许在 stdout 暂停时继续传输控制消息，但不会消除逐流背压或共享网络拥塞。
+- SSH 连接丢失后，客户端无法确认远端终止；租期清理是远端动作，不等于客户端收到了成功确认。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+本包不发布不变式伴随入口。消息校验及所属文件系统、子进程和沙箱提供方执行可观察的约束；此适配器没有增加可独立观察的状态关系。
+
+</details>

package/lib/index.js

@@ -0,0 +1,437 @@
+import { Duplex, PassThrough } from "node:stream";
+import { SubprocessExecutableNotFoundError, SubprocessRuntime } from "@deepseek-ai/dsh-subprocess";
+import { OutputCollector } from "@deepseek-ai/dsh-subprocess-local/output";
+import { doneSchema, foregroundSchema, outputSnapshotFrameLimit, outputSnapshotSchema, preparedSchema, remotePath, streamEndpointSchema } from "@deepseek-ai/dsh-ssh/schemas";
+import { RemoteOperationError, SshRpcPeer } from "@deepseek-ai/dsh-ssh/protocol";
+import { z } from "zod";
+//#region lib/types/index.js
+/** Remote subprocess and PTY handles with independent SSH streams and helper-owned process lifetimes. */
+function environment(env) {
+	return env === void 0 ? void 0 : Object.fromEntries(Object.entries(env).map(([key, value]) => [key, value ?? null]));
+}
+var RemoteCleanupError = class extends AggregateError {};
+/** One remote ordinary process; stdin and control remain usable during asynchronous SSH allocation. */
+var RemoteProcess = class {
+	ssh;
+	spec;
+	stdin;
+	stdout;
+	stderr;
+	control;
+	collected;
+	done;
+	streamsClosed;
+	inbound = new PassThrough();
+	out = new PassThrough();
+	err = new PassThrough();
+	toControl = new PassThrough();
+	fromControl = new PassThrough();
+	controller = new AbortController();
+	started;
+	id;
+	sockets = [];
+	quiescent = false;
+	committed = false;
+	termination;
+	detachAbort;
+	spills = {};
+	updateCollection = {};
+	constructor(ssh, spec) {
+		this.ssh = ssh;
+		this.spec = spec;
+		this.stdin = spec.stdio.stdin === "pipe" ? this.inbound : void 0;
+		this.stdout = spec.stdio.stdout === "pipe" ? this.out : void 0;
+		this.stderr = spec.stdio.stderr === "pipe" ? this.err : void 0;
+		const requestedControl = spec.stdio.control;
+		this.control = requestedControl === void 0 ? void 0 : Duplex.from({
+			writable: this.toControl,
+			readable: this.fromControl
+		});
+		for (const stream of [
+			this.inbound,
+			this.out,
+			this.err,
+			this.toControl,
+			this.fromControl,
+			this.control
+		]) stream?.on("error", () => {});
+		const collect = (name, stream, mode) => {
+			if (mode === "pipe") return void 0;
+			if (mode === "inherit") {
+				stream.pipe(name === "stdout" ? process.stdout : process.stderr, { end: false });
+				return;
+			}
+			let collector = new OutputCollector(mode.maxBytes, void 0, name, "");
+			let base = 0;
+			let total = 0;
+			let finalized = false;
+			this.updateCollection[name] = (snapshot, final) => {
+				const bytes = Buffer.from(snapshot.tail, "base64");
+				if (bytes.length > mode.maxBytes || snapshot.totalBytes < bytes.length) throw new Error("SSH helper returned invalid collected output coordinates");
+				if (finalized) return;
+				if (snapshot.totalBytes < total) throw new Error("SSH helper rewound collected output");
+				finalized = final;
+				collector = new OutputCollector(mode.maxBytes, void 0, name, "");
+				collector.push(bytes);
+				base = snapshot.totalBytes - bytes.length;
+				total = snapshot.totalBytes;
+			};
+			return { readFrom: (offset) => {
+				const snapshot = collector.readFrom(offset - base);
+				return {
+					...snapshot,
+					nextOffset: snapshot.nextOffset + base,
+					...this.spills[name] === void 0 ? {} : { spillPath: this.spills[name] }
+				};
+			} };
+		};
+		const stdout = collect("stdout", this.out, spec.stdio.stdout);
+		const stderr = collect("stderr", this.err, spec.stdio.stderr);
+		this.collected = {
+			...stdout === void 0 ? {} : { stdout },
+			...stderr === void 0 ? {} : { stderr }
+		};
+		const onAbort = () => {
+			this.terminate();
+		};
+		spec.signal?.addEventListener("abort", onAbort, { once: true });
+		this.detachAbort = () => {
+			spec.signal?.removeEventListener("abort", onAbort);
+		};
+		this.started = this.start();
+		this.streamsClosed = this.started.then(async () => {
+			await Promise.all(this.sockets.map((socket) => socket.closed ? Promise.resolve() : new Promise((resolve) => {
+				socket.once("close", () => {
+					resolve();
+				});
+			})));
+		}, () => {});
+		this.done = this.started.then(async () => {
+			const result = await ssh.request("process.done", { id: this.id }, doneSchema, void 0, true);
+			await this.drainOutput();
+			this.spills = result.spills;
+			for (const name of ["stdout", "stderr"]) {
+				const snapshot = result.collected[name];
+				const finish = this.updateCollection[name];
+				if (snapshot === void 0 !== (finish === void 0)) throw new Error("SSH helper returned mismatched output collection modes");
+				if (snapshot !== void 0) finish?.(snapshot, true);
+			}
+			return {
+				exitCode: result.outcome.exitCode,
+				signal: result.outcome.signal
+			};
+		}).catch((error) => {
+			this.terminate();
+			for (const socket of this.sockets) socket.destroy();
+			for (const stream of [
+				this.inbound,
+				this.out,
+				this.err,
+				this.toControl,
+				this.fromControl
+			]) stream.destroy(error instanceof Error ? error : new Error(String(error)));
+			throw error;
+		});
+		this.done.catch(() => {});
+	}
+	async start() {
+		this.spec.signal?.throwIfAborted();
+		const prepared = await this.ssh.request("process.prepare", {
+			...this.spec,
+			signal: void 0,
+			env: environment(this.spec.env)
+		}, preparedSchema, this.controller.signal);
+		this.id = prepared.id;
+		try {
+			const sockets = await Promise.all(Object.entries(prepared.streams).map(async ([name, path]) => [name, await this.ssh.connectStream(path, this.controller.signal)]));
+			this.sockets = sockets.map(([, socket]) => socket);
+			for (const [name, socket] of sockets) {
+				if (name === "stdout" || name === "stderr") {
+					const mode = this.spec.stdio[name];
+					if (typeof mode === "object") new SshRpcPeer(socket, socket, outputSnapshotFrameLimit(mode.maxBytes), 1, (method, raw) => Promise.resolve().then(() => {
+						if (method !== "snapshot") throw new Error("Unexpected SSH output-stream operation");
+						this.updateCollection[name]?.(outputSnapshotSchema.parse(raw), false);
+						return null;
+					}));
+					else {
+						socket.end();
+						const output = name === "stdout" ? this.out : this.err;
+						const closeSocket = () => {
+							socket.destroy();
+						};
+						output.once("close", closeSocket);
+						socket.once("close", () => {
+							output.off("close", closeSocket);
+						});
+						if (output.destroyed) closeSocket();
+						else socket.pipe(output);
+					}
+				}
+				if (name === "stdin") this.inbound.pipe(socket);
+				if (name === "control") {
+					this.toControl.pipe(socket);
+					socket.pipe(this.fromControl);
+				}
+			}
+			this.controller.signal.throwIfAborted();
+			await this.ssh.request("process.start", { id: this.id }, z.object({}).strict(), this.controller.signal);
+			this.committed = true;
+		} catch (error) {
+			this.terminate();
+			await this.termination?.catch(() => {});
+			for (const socket of this.sockets) socket.destroy();
+			throw error;
+		}
+	}
+	terminate() {
+		if (this.quiescent || this.termination !== void 0) return;
+		if (!this.committed) this.controller.abort(/* @__PURE__ */ new Error("SSH process terminated before launch acknowledgement"));
+		if (this.id !== void 0) {
+			this.termination = this.ssh.request("process.terminate", { id: this.id }, z.null()).then(() => {
+				this.quiescent = true;
+				this.detachAbort();
+			}).catch((error) => {
+				this.ssh.dispose().catch(() => {});
+				throw error;
+			});
+			this.termination.catch(() => {});
+		}
+	}
+	closeStreams() {
+		for (const socket of this.sockets) socket.destroy();
+		for (const stream of [
+			this.inbound,
+			this.out,
+			this.err,
+			this.toControl,
+			this.fromControl,
+			this.control
+		]) stream?.destroy();
+	}
+	async waitForExit(signal) {
+		if (this.quiescent) return true;
+		if (signal?.aborted) return false;
+		if (signal === void 0) return this.observeExit();
+		const cancelled = Promise.withResolvers();
+		const abort = () => {
+			cancelled.resolve(false);
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		try {
+			return await Promise.race([this.observeExit(signal), cancelled.promise]);
+		} finally {
+			signal.removeEventListener("abort", abort);
+		}
+	}
+	async observeExit(signal) {
+		try {
+			await this.started;
+		} catch {
+			if (this.termination !== void 0) await this.termination;
+			this.quiescent = true;
+			this.detachAbort();
+			return true;
+		}
+		if (this.termination !== void 0) {
+			await this.termination;
+			return true;
+		}
+		const result = await this.ssh.request("process.wait", { id: this.id }, z.boolean(), signal, true);
+		if (result) {
+			this.quiescent = true;
+			this.detachAbort();
+		}
+		return result;
+	}
+	async drainOutput() {
+		const disposers = [];
+		const outputs = ["stdout", "stderr"].map((name) => {
+			if (typeof this.spec.stdio[name] === "object") return Promise.resolve();
+			const stream = name === "stdout" ? this.out : this.err;
+			if (stream.readableEnded || stream.destroyed) return Promise.resolve();
+			return new Promise((resolve) => {
+				const done = () => {
+					resolve();
+				};
+				for (const event of [
+					"end",
+					"close",
+					"error"
+				]) stream.once(event, done);
+				disposers.push(() => {
+					for (const event of [
+						"end",
+						"close",
+						"error"
+					]) stream.off(event, done);
+				});
+			});
+		});
+		let timer;
+		try {
+			await Promise.race([Promise.all(outputs), new Promise((resolve) => {
+				timer = setTimeout(resolve, this.spec.graceMs);
+			})]);
+		} finally {
+			clearTimeout(timer);
+			for (const dispose of disposers) dispose();
+		}
+	}
+};
+/** SSH provider paired with the SSH filesystem; the remote helper selects POSIX process ownership. */
+var SshSubprocessRuntime = class extends SubprocessRuntime {
+	static inject = ["ssh"];
+	live = /* @__PURE__ */ new Set();
+	terminals = /* @__PURE__ */ new Set();
+	terminalAllocations = /* @__PURE__ */ new Set();
+	lifetime = new AbortController();
+	constructor(ctx) {
+		super(ctx);
+		ctx.effect(() => async () => {
+			this.lifetime.abort(/* @__PURE__ */ new Error("SSH subprocess provider disposed"));
+			for (const handle of this.live) handle.terminate();
+			const errors = (await Promise.allSettled([
+				...[...this.live].map(async (handle) => {
+					try {
+						await handle.waitForExit();
+					} finally {
+						handle.closeStreams();
+					}
+				}),
+				...[...this.terminalAllocations].map((allocation) => allocation.catch((error) => {
+					if (error instanceof RemoteCleanupError) throw error;
+				})),
+				...[...this.terminals].map((handle) => handle.terminate())
+			])).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+			if (errors.length > 0) throw new AggregateError(errors, "SSH process cleanup could not be confirmed");
+		});
+	}
+	async resolveExecutable(command, env, signal) {
+		try {
+			return await this.ctx.ssh.request("executable", {
+				command,
+				env
+			}, remotePath, signal);
+		} catch (error) {
+			if (error instanceof RemoteOperationError && error.code === "SUBPROCESS_EXECUTABLE_NOT_FOUND") throw new SubprocessExecutableNotFoundError(error.message, { cause: error });
+			throw error;
+		}
+	}
+	terminalEnvironment(signal) {
+		return this.ctx.ssh.request("terminal.environment", {}, z.object({
+			platform: z.enum(["posix", "windows"]),
+			defaultShell: z.string().optional()
+		}).strict().transform((value) => ({
+			platform: value.platform,
+			...value.defaultShell === void 0 ? {} : { defaultShell: value.defaultShell }
+		})), signal);
+	}
+	spawn(spec) {
+		this.lifetime.signal.throwIfAborted();
+		spec.signal?.throwIfAborted();
+		const handle = new RemoteProcess(this.ctx.ssh, spec);
+		this.live.add(handle);
+		handle.done.then(() => handle.waitForExit()).then(() => handle.streamsClosed).then(() => {
+			this.live.delete(handle);
+		}).catch(() => {});
+		return handle;
+	}
+	async spawnTerminal(spec) {
+		this.lifetime.signal.throwIfAborted();
+		const signal = spec.signal === void 0 ? this.lifetime.signal : AbortSignal.any([spec.signal, this.lifetime.signal]);
+		signal.throwIfAborted();
+		const allocation = this.createTerminal(spec, signal);
+		this.terminalAllocations.add(allocation);
+		try {
+			return await allocation;
+		} finally {
+			this.terminalAllocations.delete(allocation);
+		}
+	}
+	async createTerminal(spec, signal) {
+		const ssh = this.ctx.ssh;
+		const prepared = await ssh.request("process.prepare", {
+			argv: spec.argv,
+			cwd: spec.cwd,
+			env: environment(spec.env),
+			graceMs: spec.graceMs,
+			terminal: {
+				rows: spec.rows,
+				cols: spec.cols,
+				terminalType: spec.terminalType
+			}
+		}, preparedSchema, signal);
+		const id = prepared.id;
+		let socket;
+		try {
+			signal.throwIfAborted();
+			socket = await ssh.connectStream(streamEndpointSchema.parse(prepared.streams.terminal), signal);
+			signal.throwIfAborted();
+			socket.end();
+			const output = new PassThrough();
+			socket.pipe(output);
+			const started = await ssh.request("process.start", { id }, z.object({ pid: z.number().int().positive() }).strict(), signal);
+			signal.throwIfAborted();
+			const done = ssh.request("process.done", { id }, doneSchema, void 0, true).then((result) => ({
+				exitCode: result.outcome.exitCode,
+				signal: result.outcome.signal
+			}));
+			done.catch(() => {});
+			let closing;
+			const abort = () => {
+				handle.terminate().catch(() => {
+					ssh.dispose().catch(() => {});
+				});
+			};
+			const handle = {
+				pid: started.pid,
+				output,
+				done,
+				resize: async (cols, rows) => {
+					await ssh.request("terminal.resize", {
+						id,
+						cols,
+						rows
+					}, z.null());
+				},
+				write: async (data) => {
+					await ssh.request("terminal.write", {
+						id,
+						value: data
+					}, z.null());
+				},
+				inspectForeground: async () => await ssh.request("terminal.inspect", { id }, foregroundSchema) ?? void 0,
+				signalForeground: (signal) => ssh.request("terminal.signal", {
+					id,
+					value: signal
+				}, z.number().int().positive()),
+				terminate: () => {
+					closing ??= ssh.request("process.terminate", { id }, z.null(), void 0, true).then(() => {
+						socket?.destroy();
+						output.destroy();
+						signal.removeEventListener("abort", abort);
+						this.terminals.delete(handle);
+					}).catch((error) => {
+						closing = void 0;
+						throw error;
+					});
+					return closing;
+				}
+			};
+			signal.addEventListener("abort", abort, { once: true });
+			this.terminals.add(handle);
+			return handle;
+		} catch (error) {
+			socket?.destroy();
+			try {
+				await ssh.request("process.terminate", { id }, z.null());
+			} catch (cleanupError) {
+				ssh.dispose().catch(() => {});
+				throw new RemoteCleanupError([error, cleanupError], "SSH terminal allocation failed and remote cleanup is unknown");
+			}
+			throw error;
+		}
+	}
+};
+//#endregion
+export { SshSubprocessRuntime, SshSubprocessRuntime as default };

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+import { Context } from '@deepseek-ai/cordis';
+import { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
+import type { SubprocessHandle, SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalEnvironment, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** SSH provider paired with the SSH filesystem; the remote helper selects POSIX process ownership. */
+export declare class SshSubprocessRuntime extends SubprocessRuntime {
+    static inject: string[];
+    private readonly live;
+    private readonly terminals;
+    private readonly terminalAllocations;
+    private readonly lifetime;
+    constructor(ctx: Context);
+    resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
+    terminalEnvironment(signal?: AbortSignal): Promise<SubprocessTerminalEnvironment>;
+    spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
+    private createTerminal;
+}
+export default SshSubprocessRuntime;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@deepseek-ai/dsh-subprocess-ssh",
+  "description": "Subprocess and terminal 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/subprocess-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/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-ssh": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-subprocess-local": "^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-subprocess": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.1"
+  }
+}