@deepseek-ai/dsh-tool-bash-persistent 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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/pty/tool-bash-persistent/README.md
+README.md: cfb3acf41803f5b06ecb3f56ee8ffc29ce9147b1
+README.zh.md: cf35a212159e7d12e1bdaa146b32b397d916a912

package/README.md

@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-tool-bash-persistent
+
+English | [中文](README.zh.md)
+
+Model-facing `bash(command)` backed by one owner-scoped `ctx.pty` shell. The package owns the tool contract and shell reuse; deployments select the PTY backend and sandbox policy.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---:|---|
+| `backendType` | `shell` | Registered PTY backend used for each Agent shell. |
+| `timeoutMs` | `300000` | Wall-clock limit for one command; timeout closes the shell. |
+| `maxOutputChars` | `16000` | Maximum retained command-output characters; fixed diagnostics are added afterward. |
+| `description` | Persistent-shell description | Model-facing environment contract. |
+
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The generated [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash-persistent), including the configured `description`. The plugin contributes no standalone system-prompt section; the deployment owns persona and environment guidance.
+
+#### Token effect
+
+Fixed schema cost while `bash` is visible.
+
+#### KV Cache effect
+
+Prefix-stable while the configured description and schema remain unchanged.
+
+### Tool results
+
+#### What the model sees
+
+Commands share one shell per Agent, so cwd, exported variables, activated environments, functions, and background jobs persist across calls. Results exclude private completion markers and the shell prompt. A nonzero wrapped command appends `[exit code: N]`; a shell that exits before reporting that status instead appends `[shell exited: code N]`, `[shell killed by signal: SIG]`, or `[shell exited]` when the backend supplies neither, then resets and tells the model that the next call starts fresh. Long output keeps the earliest retained prefix plus a clipping notice. If the PTY has already dropped that prefix, the result says so explicitly instead of presenting a tail as complete output. Timeout returns bounded partial output, closes the uncertain shell, and reports the reset.
+
+#### Token effect
+
+Data-dependent. `maxOutputChars` bounds retained command output; fixed clipping, lost-prefix, status, timeout, and reset diagnostics can extend the result.
+
+#### KV Cache effect
+
+Append-only tool results follow the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+- The tool requires an owning Agent and a real PTY backend.
+- Explicit `exit` and timeout discard shell state. Cancellation also resets and discards the result, even when a complete status marker is already observable; the next call starts a fresh shell.
+- Environment facts such as network access and package mirrors belong in the configured `description`, not this package's default.

package/README.zh.md

@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-tool-bash-persistent
+
+[English](README.md) | 中文
+
+模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具约定和 shell 复用；PTY 后端与沙箱策略由部署选择。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---:|---|
+| `backendType` | `shell` | 每个 Agent shell 使用的已注册 PTY 后端。 |
+| `timeoutMs` | `300000` | 单条命令的墙钟时间上限；超时会关闭 shell。 |
+| `maxOutputChars` | `16000` | 命令输出最多保留的字符数；固定诊断会在此后追加。 |
+| `description` | 持久 shell 描述 | 面向模型的环境约定。 |
+
+## 模型体验
+
+### 工具 schema
+
+#### 模型所见
+
+生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash-persistent)，其中包含配置的 `description`。本插件不贡献独立系统提示词段；persona 与环境指导由部署负责。
+
+#### Token 影响
+
+`bash` 可见时产生固定的 schema 成本。
+
+#### KV Cache 影响
+
+配置的描述与 schema 不变时前缀稳定。
+
+### 工具结果
+
+#### 模型所见
+
+每个 Agent 的命令共享一个 shell，因此 cwd、导出的环境变量、已激活环境、函数和后台任务会跨调用保留。结果不包含私有完成标记和 shell 提示符。经封装的命令以非零状态结束时，结果会追加 `[exit code: N]`；若 shell 在报告该状态前退出，则改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]`，或在后端既未提供退出码也未提供信号时追加 `[shell exited]`；随后重置 shell，并告知模型下次调用从新 shell 开始。长输出保留仍可读取的最早前缀并追加截断提示；若 PTY 已丢弃真正的开头，结果会明确说明，而不是把尾部伪装成完整输出。超时返回有界的部分输出、关闭状态不确定的 shell，并报告该重置。
+
+#### Token 影响
+
+随数据变化。`maxOutputChars` 限制保留的命令输出；固定的截断、前缀丢失、状态、超时与重置诊断可能使结果更长。
+
+#### KV Cache 影响
+
+工具结果以追加方式位于可复用请求前缀之后。
+
+## 已知限制与延后工作
+
+- 工具需要拥有它的 Agent 和真实 PTY 后端。
+- 显式 `exit` 与超时会丢弃 shell 状态。取消同样会重置 shell 并丢弃结果，即使已经能观察到完整状态标记也是如此；下次调用创建新 shell。
+- 网络访问、软件包镜像等环境事实应写入配置的 `description`，而非包默认描述。

package/lib/index.js

@@ -0,0 +1,378 @@
+import { randomUUID } from "node:crypto";
+import z from "@deepseek-ai/schemastery";
+import { deadline, timeoutOf } from "@deepseek-ai/dsh-timeout";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+/**
+* Model-facing persistent `bash` tool over the owner-scoped PTY seam.
+* @module @deepseek-ai/dsh-tool-bash-persistent
+*/
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+const TRUNCATED_MESSAGE = "<response clipped><NOTE>To save on context only part of this file has been shown to you. You should retry this tool after you have searched inside the file with `grep -n` in order to find the line numbers of what you are looking for.</NOTE>";
+const LOST_PREFIX_MESSAGE = "<response clipped><NOTE>The beginning of this command output was dropped by the terminal scrollback limit. The following text is the earliest retained output.</NOTE>\n";
+const SHELL_RESET_MESSAGE = "The persistent bash shell was reset; the next bash call starts from the workspace with a fresh current directory and environment.";
+const SHELL_PROMPT = "__DSH_PERSISTENT_BASH_PROMPT__ ";
+const TIMEOUT_CODE = "PERSISTENT_BASH_TIMEOUT";
+const SCROLLBACK_PAGE_LINES = 1e3;
+const POLL_INTERVAL_MS = 25;
+const DEFAULT_DESCRIPTION = "Run commands in a persistent bash shell. State, including the current directory and exported environment variables, persists across calls for this agent.";
+function maybeTruncate(content, maxOutputChars, incomplete = false) {
+	if (content.length <= maxOutputChars && !incomplete) return content;
+	return content.length <= maxOutputChars ? content + TRUNCATED_MESSAGE : content.slice(0, maxOutputChars) + TRUNCATED_MESSAGE;
+}
+function markers() {
+	const nonce = randomUUID();
+	return {
+		start: `__DSH_PERSISTENT_BASH_START_${nonce}__`,
+		end: `__DSH_PERSISTENT_BASH_END_${nonce}:`
+	};
+}
+function quoteForBash(value) {
+	return `$'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'").replaceAll("\r", "\\r").replaceAll("\n", "\\n")}'`;
+}
+function wrapCommand(command, marker) {
+	return `printf '%s\\n' ${quoteForBash(marker.start)}; eval -- ${quoteForBash(command)}; __dsh_persistent_bash_status=$?; printf '%s%s\\n' ${quoteForBash(marker.end)} "$__dsh_persistent_bash_status"`;
+}
+function stripPrompt(text) {
+	let result = text.replace(/\r?\n$/, "");
+	while (result.endsWith(SHELL_PROMPT)) result = result.slice(0, -31);
+	return result.endsWith("\n") ? result.slice(0, -1) : result;
+}
+function commandOutput(snapshot, marker) {
+	const text = snapshot.text;
+	const end = text.lastIndexOf(marker.end);
+	const status = /^(\d+)\r?\n/.exec(text.slice(end + marker.end.length))?.[1];
+	if (status === void 0) return void 0;
+	const startMarker = text.lastIndexOf(marker.start, end);
+	const start = startMarker < 0 ? 0 : startMarker + marker.start.length;
+	return {
+		text: stripPrompt(text.slice(start, end).replace(/^\r?\n/, "")),
+		incomplete: startMarker < 0,
+		exitCode: Number(status)
+	};
+}
+function promptCompleted(result) {
+	return result.viewport.endsWith(SHELL_PROMPT) || result.viewport.endsWith(`${SHELL_PROMPT}\r\n`) || result.viewport.endsWith(`${SHELL_PROMPT}\n`);
+}
+function partialOutput(snapshot, marker, fallback, fallbackTruncated = false) {
+	const startMarker = snapshot.text.lastIndexOf(marker.start);
+	if (startMarker >= 0) return {
+		text: stripPrompt(snapshot.text.slice(startMarker + marker.start.length).replace(/^\r?\n/, "")),
+		incomplete: false
+	};
+	const fallbackStart = fallback.lastIndexOf(marker.start);
+	const afterStart = fallbackStart < 0 ? fallback : fallback.slice(fallbackStart + marker.start.length).replace(/^\r?\n/, "");
+	const fallbackEnd = afterStart.lastIndexOf(marker.end);
+	return {
+		text: stripPrompt((fallbackEnd < 0 ? afterStart : afterStart.slice(0, fallbackEnd)).replaceAll(SHELL_PROMPT, "")),
+		incomplete: fallbackTruncated || fallbackStart < 0
+	};
+}
+async function pause() {
+	await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+}
+function nextScrollbackOffset(page, offset) {
+	if (page.text.length === 0 || page.lineEnd <= offset) return void 0;
+	return page.lineEnd;
+}
+function retainedScrollback(ctx, owner, id, latest = ctx.pty.read(owner, id, {
+	offset: 0,
+	count: SCROLLBACK_PAGE_LINES
+})) {
+	const pages = latest.text.length === 0 ? [] : [latest.text];
+	let offset = latest.lineEnd;
+	let truncated = latest.truncated;
+	while (true) {
+		if (offset >= latest.totalLines) break;
+		const page = ctx.pty.read(owner, id, {
+			offset,
+			count: SCROLLBACK_PAGE_LINES
+		});
+		truncated ||= page.truncated;
+		if (page.text.length > 0) pages.unshift(page.text);
+		const next = nextScrollbackOffset(page, offset);
+		if (next === void 0 || next >= page.totalLines) break;
+		offset = next;
+	}
+	return {
+		text: pages.join("\n"),
+		truncated
+	};
+}
+function renderCaptured(output, maxOutputChars) {
+	const rendered = maybeTruncate(output.text, maxOutputChars, output.incomplete);
+	return appendStatusMarker(output.incomplete && output.text.length > 0 ? LOST_PREFIX_MESSAGE + rendered : rendered, output.exitCode !== void 0 && output.exitCode !== 0 ? `[exit code: ${output.exitCode}]` : void 0);
+}
+function appendStatusMarker(content, marker) {
+	if (marker === void 0) return content;
+	return content.length === 0 ? marker : `${content}\n${marker}`;
+}
+function renderShellExitStatus(content, exitCode, signal) {
+	return appendStatusMarker(content, signal !== null ? `[shell killed by signal: ${signal}]` : exitCode !== null ? `[shell exited: code ${exitCode}]` : "[shell exited]");
+}
+function persistentShells(ctx, config) {
+	const pending = /* @__PURE__ */ new WeakMap();
+	const live = /* @__PURE__ */ new Map();
+	const creating = /* @__PURE__ */ new Set();
+	const ownerCleanupInstalled = /* @__PURE__ */ new WeakSet();
+	const lifecycle = new AbortController();
+	const close = async (owner, id, reason) => {
+		if (!ctx.pty.list(owner).some((snapshot) => snapshot.sessionId === id)) return;
+		await ctx.pty.kill(owner, id, reason);
+	};
+	ctx.effect(() => async () => {
+		lifecycle.abort(/* @__PURE__ */ new Error("tool-bash-persistent disposed during shell creation"));
+		await Promise.allSettled([...creating]);
+		const closing = [...live].map(async ([owner, id]) => {
+			await close(owner, id, "tool-bash-persistent disposed");
+		});
+		await Promise.all(closing);
+		live.clear();
+	}, "tool-bash-persistent shell cleanup");
+	const reset = async (owner, reason) => {
+		pending.delete(owner);
+		const id = live.get(owner);
+		live.delete(owner);
+		if (id !== void 0) await close(owner, id, reason);
+	};
+	const get = (owner, signal) => {
+		const existing = pending.get(owner);
+		if (existing !== void 0) return existing;
+		const combinedSignal = AbortSignal.any([signal, lifecycle.signal]);
+		const tracked = (async () => {
+			try {
+				const cwd = owner.session.header.cwd;
+				const spawned = await ctx.pty.spawn(owner, {
+					type: config.backendType,
+					...cwd === void 0 ? {} : { cwd }
+				}, combinedSignal);
+				live.set(owner, spawned.sessionId);
+				if (!ownerCleanupInstalled.has(owner)) {
+					ownerCleanupInstalled.add(owner);
+					owner.ctx.effect(() => () => {
+						pending.delete(owner);
+						live.delete(owner);
+					}, "tool-bash-persistent owner cache cleanup");
+				}
+				const result = await ctx.pty.startSend(owner, spawned.sessionId, {
+					text: `stty -echo; PS1=${quoteForBash(SHELL_PROMPT)}`,
+					submit: true,
+					signal: combinedSignal
+				}).done;
+				if (result.sessionStatus.kind === "exited" || result.waitReason === "timeout") throw new Error("persistent bash shell did not accept initialization");
+				return spawned.sessionId;
+			} catch (error) {
+				await reset(owner, "persistent bash initialization failed");
+				throw error;
+			}
+		})().finally(() => {
+			creating.delete(tracked);
+		});
+		creating.add(tracked);
+		pending.set(owner, tracked);
+		return tracked;
+	};
+	return {
+		get,
+		reset
+	};
+}
+async function executeCommand(ctx, shells, owner, command, config, upstream) {
+	const env_1 = {
+		stack: [],
+		error: void 0,
+		hasError: false
+	};
+	try {
+		const commandDeadline = __addDisposableResource(env_1, deadline(upstream, config.timeoutMs, TIMEOUT_CODE), false);
+		const id = await shells.get(owner, commandDeadline.signal);
+		const marker = markers();
+		const wrapped = wrapCommand(command, marker);
+		let first = true;
+		let fallback = "";
+		let fallbackTruncated = false;
+		while (true) {
+			let operation;
+			let result;
+			try {
+				operation = ctx.pty.startSend(owner, id, {
+					text: first ? wrapped : "",
+					submit: first,
+					signal: commandDeadline.signal
+				});
+				first = false;
+				result = await operation.done;
+			} catch (error) {
+				await shells.reset(owner, "persistent bash send failed");
+				throw error;
+			}
+			const incremental = operation.readOutput();
+			fallback = incremental.delta.length > 0 ? fallback + incremental.delta : result.viewport;
+			fallbackTruncated ||= incremental.truncated || result.truncated;
+			const latest = ctx.pty.read(owner, id, {
+				offset: 0,
+				count: SCROLLBACK_PAGE_LINES
+			});
+			const timedOut = timeoutOf(commandDeadline.signal, TIMEOUT_CODE);
+			if (timedOut !== void 0) {
+				const partial = renderCaptured(partialOutput(retainedScrollback(ctx, owner, id, latest), marker, fallback, fallbackTruncated), config.maxOutputChars);
+				await shells.reset(owner, "persistent bash command timed out");
+				return [
+					`Your command timed out after ${Math.round(timedOut.timeoutMs / 1e3)} seconds or experienced an OOM error. Below is partial output:`,
+					partial,
+					SHELL_RESET_MESSAGE
+				].join("\n");
+			}
+			if (commandDeadline.signal.aborted) {
+				await shells.reset(owner, "persistent bash command aborted");
+				commandDeadline.signal.throwIfAborted();
+			}
+			if (latest.text.includes(marker.end)) {
+				const complete = commandOutput(retainedScrollback(ctx, owner, id, latest), marker);
+				if (complete !== void 0) return renderCaptured(complete, config.maxOutputChars);
+			}
+			if (result.sessionStatus.kind === "exited") {
+				const snapshot = retainedScrollback(ctx, owner, id, latest);
+				await shells.reset(owner, "persistent bash shell exited");
+				return [renderShellExitStatus(renderCaptured(partialOutput(snapshot, marker, fallback, fallbackTruncated), config.maxOutputChars), result.sessionStatus.exitCode, result.sessionStatus.signal), SHELL_RESET_MESSAGE].filter((part) => part.length > 0).join("\n");
+			}
+			if (promptCompleted(result)) return renderCaptured(partialOutput(retainedScrollback(ctx, owner, id, latest), marker, fallback, fallbackTruncated), config.maxOutputChars);
+			await pause();
+		}
+	} catch (e_1) {
+		env_1.error = e_1;
+		env_1.hasError = true;
+	} finally {
+		__disposeResources(env_1);
+	}
+}
+/**
+* Register the model-facing persistent `bash` tool.
+* @param ctx - plugin context carrying tools and the owner-scoped PTY service.
+* @param config - selected PTY backend and command deadline.
+*/
+function registerPersistentBash(ctx, config) {
+	const shells = persistentShells(ctx, config);
+	const queues = /* @__PURE__ */ new WeakMap();
+	const serialized = async (owner, operation) => {
+		const run = (queues.get(owner) ?? Promise.resolve()).then(operation, operation);
+		const tail = run.then(() => void 0, () => void 0);
+		queues.set(owner, tail);
+		try {
+			return await run;
+		} finally {
+			if (queues.get(owner) === tail) queues.delete(owner);
+		}
+	};
+	ctx.tools.register(defineTool({
+		name: "bash",
+		description: config.description,
+		parameters: { command: {
+			type: "string",
+			required: true,
+			description: "The bash command to run. Relative path is preferred in the command."
+		} },
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(args, exec) {
+			if (args.command.trim().length === 0) throw new Error("command must be a non-empty string");
+			const owner = exec.agent;
+			if (owner === void 0) throw new Error("bash requires an owning agent session");
+			return serialized(owner, async () => {
+				exec.signal.throwIfAborted();
+				return executeCommand(ctx, shells, owner, args.command, config, exec.signal);
+			});
+		},
+		presentCall: (args) => ({
+			card: "terminal",
+			title: args.command
+		})
+	}));
+}
+const name = "tool-bash-persistent";
+const inject = ["tools", "pty"];
+/** Runtime configuration schema for the persistent Bash tool. */
+const Config = z.object({
+	backendType: z.string().default("shell"),
+	timeoutMs: z.number().default(3e5),
+	maxOutputChars: z.number().default(16e3),
+	description: z.string().default(DEFAULT_DESCRIPTION)
+});
+/** Register one owner-scoped persistent `bash` tool. */
+function apply(ctx, config) {
+	const resolved = {
+		backendType: config.backendType ?? "shell",
+		timeoutMs: config.timeoutMs ?? 3e5,
+		maxOutputChars: config.maxOutputChars ?? 16e3,
+		description: config.description ?? DEFAULT_DESCRIPTION
+	};
+	if (resolved.backendType.trim().length === 0) throw new Error("tool-bash-persistent: backendType must be non-empty");
+	if (!Number.isSafeInteger(resolved.timeoutMs) || resolved.timeoutMs <= 0) throw new Error("tool-bash-persistent: timeoutMs must be a positive safe integer");
+	if (!Number.isSafeInteger(resolved.maxOutputChars) || resolved.maxOutputChars <= 0) throw new Error("tool-bash-persistent: maxOutputChars must be a positive safe integer");
+	if (resolved.description.trim().length === 0) throw new Error("tool-bash-persistent: description must be non-empty");
+	registerPersistentBash(ctx, resolved);
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-tool-bash-persistent`.
+* @module @deepseek-ai/dsh-tool-bash-persistent/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-bash-persistent";
+/** Cordis companion plugin name. */
+const name = "tool-bash-persistent-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the adapter's private owner-to-shell cache has no
+* observable event or data relation. Lifecycle tests prove its cleanup without
+* adding a public surface solely for an invariant.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Model-facing persistent `bash` tool over the owner-scoped PTY seam.
+ * @module @deepseek-ai/dsh-tool-bash-persistent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "tool-bash-persistent";
+export declare const inject: string[];
+/** Configuration for the persistent Bash tool. */
+export interface Config {
+    /** PTY backend used for each owner-isolated persistent shell (default `shell`). */
+    backendType?: string;
+    /** Wall-clock limit for one command (default 300000). */
+    timeoutMs?: number;
+    /** Maximum returned command-output characters before clipping (default 16000). */
+    maxOutputChars?: number;
+    /** Model-facing tool description; deployments may describe their environment. */
+    description?: string;
+}
+/** Runtime configuration schema for the persistent Bash tool. */
+export declare const Config: z<Config>;
+/** Register one owner-scoped persistent `bash` tool. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-bash-persistent`.
+ * @module @deepseek-ai/dsh-tool-bash-persistent/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-bash-persistent-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@deepseek-ai/dsh-tool-bash-persistent",
+  "description": "Model-facing owner-scoped persistent Bash tool backed by the Harness PTY service",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/pty/tool-bash-persistent"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-pty": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "^1.0.5-rc.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^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-pty": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-pty-local": "^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-subprocess-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}