@deepseek-ai/dsh-tool-pwsh-persistent 0.1.0-rc.8

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/shell/tool-pwsh-persistent/README.md
+README.md: a57c940801606c2eef450f0e54fecb434c62a406
+README.zh.md: 4bd7ecdad08e504daa3ff6283f8b77ac9428385f

package/README.md

@@ -0,0 +1,55 @@
+# @deepseek-ai/dsh-tool-pwsh-persistent
+
+English | [中文](README.zh.md)
+
+Model-facing `pwsh(command)` backed by one owner-scoped `ctx.terminals` shell. The package owns the tool contract and shell reuse; deployments select the terminal backend (a `terminal-bash` instance configured with `shellDialect: pwsh`) and sandbox policy. It is the Windows counterpart of `tool-bash-persistent`: same persistent-state contract, PowerShell dialect.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---:|---|
+| `backendType` | `shell` | Registered terminal 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 [`pwsh` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-pwsh-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 `pwsh` 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, `$env:` variables, functions, and background jobs persist across calls. Results exclude private completion markers, the shell prompt, and the echoed input line (PSReadLine renders submitted input back into the stream; the marker-anchored extraction and the wrapper-source strip remove it). A nonzero wrapped command appends `[exit code: N]` — the exact native exit code when the command ran a native program, `1` for a terminating PowerShell error. 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 (Windows forced termination reports exit 1 without a signal), 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 terminal has already dropped that prefix, the result says so explicitly. 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 terminal backend with a pwsh dialect (Windows ConPTY or a POSIX pwsh).
+- **Input echo is unavoidable**: PowerShell's PSReadLine renders submitted input back into the terminal stream, and there is no `stty -echo` equivalent. The marker-anchored extraction excludes the echo in complete results; the wrapper-source strip covers fallback paths, but a wrapper that wraps across the terminal width may leave a partial echo in partial-output results, bounded by `maxOutputChars`.
+- Raw ESC characters inside model commands are unsupported: PSReadLine consumes them before execution. The wrapper escapes the control bytes it needs (`[char]27`-built OSC markers, backtick escapes for the body).
+- A model redefinition of the `prompt` function removes the readiness marker; the shell then settles on the silence tier instead of the marker fast path.
+- There is no interactive stdin during a command: a foreground command that reads input blocks until the readiness timeout, which resets the shell.
+- SIGTSTP/SIGHUP are unavailable on Windows (backend-rejected); SIGINT is delivered as a console-wide Ctrl-C input write, which at a prompt cancels the pending line instead of signalling a process.
+- Under the Windows ACL sandbox's read-only mode, pwsh starts in ConstrainedLanguage, which may deny the bootstrap's `[Console]::` encoding pin and prompt marker. Commands can still settle through the printable prompt and silence tier, but non-ASCII output may follow the host code page.
+- The BEL-terminated OSC marker remains a readiness signal only; a BEL event channel to the model stays deferred, aligned with the current implementation.

package/README.zh.md

@@ -0,0 +1,55 @@
+# @deepseek-ai/dsh-tool-pwsh-persistent
+
+[English](README.md) | 中文
+
+模型侧 `pwsh(command)`，由一个 owner 作用域的 `ctx.terminals` shell 支撑。本包拥有工具契约与 shell 复用；部署方选择 terminal backend（配置 `shellDialect: pwsh` 的 `terminal-bash` 实例）与沙箱策略。它是 `tool-bash-persistent` 的 Windows 对应物：相同的持久状态契约，PowerShell 方言。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---:|---|
+| `backendType` | `shell` | 每个 Agent shell 使用的已注册 terminal backend。 |
+| `timeoutMs` | `300000` | 单条命令的墙钟上限；超时关闭 shell。 |
+| `maxOutputChars` | `16000` | 保留的命令输出字符上限；固定诊断文本在其后追加。 |
+| `description` | 持久 shell 描述 | 模型可见的环境契约。 |
+
+## 模型体验
+
+### 工具 schema
+
+#### 模型看到什么
+
+生成的 [`pwsh` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-pwsh-persistent)，含配置的 `description`。本插件不贡献独立的 system-prompt 段落；persona 与环境指引由部署方负责。
+
+#### Token 影响
+
+`pwsh` 可见期间每个请求有固定的 schema 成本。
+
+#### KV Cache 影响
+
+配置的 description 与 schema 不变时前缀稳定。
+
+### 工具结果
+
+#### 模型看到什么
+
+命令共享每个 Agent 的一个 shell，因此 cwd、`$env:` 变量、函数和后台任务跨调用保留。结果排除私有完成标记、shell 提示符与回显的输入行（PSReadLine 会把提交的输入渲染回输出流；marker 锚定提取与包装器原文剥离将其移除）。非零包装命令追加 `[exit code: N]` —— 命令运行原生程序时是精确的原生退出码，PowerShell 终止性错误为 `1`。shell 在报告状态前退出的，改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]` 或 `[shell exited]`（backend 两者都没有时；Windows 强杀按无 signal 的 exit 1 报告），然后重置并告知模型下一次调用从全新 shell 开始。长输出保留最早的前缀并附裁剪提示；若 PTY 已丢弃该前缀，结果会明确说明。超时返回有界的部分输出、关闭不确定的 shell 并报告重置。
+
+#### Token 影响
+
+数据相关。`maxOutputChars` 限制保留的命令输出；固定裁剪、前缀丢失、状态、超时与重置诊断可能扩展结果。
+
+#### KV Cache 影响
+
+追加式工具结果跟随可复用的请求前缀。
+
+## 已知限制与延后工作
+
+- 工具需要拥有 Agent 与一个真实支持 pwsh 方言的 terminal backend（Windows ConPTY 或 POSIX 上的 pwsh）。
+- **输入回显不可避免**：PowerShell 的 PSReadLine 会把提交的输入渲染回终端流，且没有 `stty -echo` 的对应物。完整结果中 marker 锚定提取排除回显；包装器原文剥离覆盖回退路径，但跨越终端宽度的包装器折行可能在部分输出结果中残留片段回显，受 `maxOutputChars` 约束。
+- 模型命令中的裸 ESC 字符不受支持：PSReadLine 会在执行前吞掉它们。包装器转义它需要的控制字节（`[char]27` 构造的 OSC 标记、body 的反引号转义）。
+- 模型重定义 `prompt` 函数会移除就绪标记；shell 随后退化为静默档而非 marker 快路径。
+- 命令执行期间没有交互 stdin：读取输入的前台命令会阻塞到就绪超时，随后重置 shell。
+- SIGTSTP/SIGHUP 在 Windows 不可用（backend 拒绝）；SIGINT 以控制台级 Ctrl-C 输入写入投递，在提示符处取消当前行而非向进程发信号。
+- 在 Windows ACL 沙箱的只读模式下，pwsh 以 ConstrainedLanguage 启动，可能拒绝引导代码通过 `[Console]::` 固定编码并写入 prompt marker。命令仍可通过可打印提示符和静默档结算，但非 ASCII 输出可能沿用宿主代码页。
+- BEL 终结的 OSC 标记仍只是就绪信号；面向模型的 BEL 事件通道保持延后，与当前实现对齐。

package/lib/index.js

@@ -0,0 +1,407 @@
+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 `pwsh` tool over the owner-scoped PTY seam.
+* @module @deepseek-ai/dsh-tool-pwsh-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 Select-String 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 pwsh shell was reset; the next pwsh call starts from the workspace with a fresh current directory and environment.";
+const SHELL_PROMPT = "__DSH_PERSISTENT_PWSH_PROMPT__ ";
+const TIMEOUT_CODE = "PERSISTENT_PWSH_TIMEOUT";
+const SCROLLBACK_PAGE_LINES = 1e3;
+const POLL_INTERVAL_MS = 25;
+const DEFAULT_DESCRIPTION = "Run commands in a persistent PowerShell 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_PWSH_START_${nonce}__`,
+		end: `__DSH_PERSISTENT_PWSH_END_${nonce}:`
+	};
+}
+/**
+* Escape a command body for embedding in the wrapper's double-quoted string.
+* Backtick escapes keep every character literal: backtick first so the
+* escapes this function inserts are never re-escaped, `$` so no expansion
+* happens at wrapper construction, and `\r\n`/ESC so multi-line commands and
+* raw control bytes ride one physical input line without PSReadLine mangling.
+* @param value - the model's PowerShell command text.
+* @returns the escaped double-quoted-string body.
+*/
+function quoteForPwsh(value) {
+	return value.replaceAll("`", "``").replaceAll("\"", "`\"").replaceAll("$", "`$").replaceAll("\r", "").replaceAll("\n", "`n").replaceAll("\x1B", "`e");
+}
+function wrapCommand(command, marker) {
+	const body = quoteForPwsh(command);
+	return `Write-Output '${marker.start}'; $LASTEXITCODE = $null; $__s = 1; try { Invoke-Expression "${body}"; $__ok = $? } catch { $__ok = $false }; if ($null -ne $LASTEXITCODE) { $__s = [int]$LASTEXITCODE } else { $__s = if ($__ok) { 0 } else { 1 } }; Write-Output ('${marker.end}' + $__s)`;
+}
+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, wrapper) {
+	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;
+	let captured = text.slice(start, end);
+	captured = captured.replaceAll(wrapper, "");
+	return {
+		text: captured.replace(/^\r?\n/, "").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, wrapper, 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, "").replaceAll(wrapper, "")),
+		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.terminals.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.terminals.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]");
+}
+/**
+* Render the exited-session result, reset the owner's shell, and reset the
+* message that tells the model the next call starts fresh.
+* @param shells - the owner-scoped registry to reset.
+* @param status - the exited session status (exit code and signal).
+* @returns the complete model-facing result.
+*/
+async function respondToSessionExit(ctx, shells, owner, id, status, marker, wrapped, fallback, fallbackTruncated, config) {
+	const snapshot = retainedScrollback(ctx, owner, id);
+	await shells.reset(owner, "persistent pwsh shell exited");
+	return [renderShellExitStatus(renderCaptured(partialOutput(snapshot, marker, wrapped, fallback, fallbackTruncated), config.maxOutputChars), status.exitCode, status.signal), SHELL_RESET_MESSAGE].filter((part) => part.length > 0).join("\n");
+}
+/**
+* The pwsh prompt function that overrides the backend bootstrap value with
+* this tool's own prompt. `[char]27`/`[char]7` build the OSC bytes at runtime
+* because raw ESC characters in submitted input are unreliable under
+* PSReadLine.
+*/
+const PWSH_PROMPT_SETUP = "function prompt { [Console]::Write([char]27 + ']133;D;' + [int]$LASTEXITCODE + [char]7); '__DSH_PERSISTENT_PWSH_PROMPT__ ' }";
+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.terminals.list(owner).some((snapshot) => snapshot.sessionId === id)) return;
+		await ctx.terminals.kill(owner, id, reason);
+	};
+	ctx.effect(() => async () => {
+		lifecycle.abort(/* @__PURE__ */ new Error("tool-pwsh-persistent disposed during shell creation"));
+		await Promise.allSettled([...creating]);
+		const closing = [...live].map(async ([owner, id]) => {
+			await close(owner, id, "tool-pwsh-persistent disposed");
+		});
+		await Promise.all(closing);
+		live.clear();
+	}, "tool-pwsh-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.terminals.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-pwsh-persistent owner cache cleanup");
+				}
+				const result = await ctx.terminals.startSend(owner, spawned.sessionId, {
+					text: PWSH_PROMPT_SETUP,
+					submit: true,
+					signal: combinedSignal
+				}).done;
+				if (result.sessionStatus.kind === "exited" || result.waitReason === "timeout") throw new Error("persistent pwsh shell did not accept initialization");
+				return spawned.sessionId;
+			} catch (error) {
+				await reset(owner, "persistent pwsh 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) {
+			const status = ctx.terminals.list(owner).find((session) => session.sessionId === id)?.status;
+			if (status?.kind === "exited") return await respondToSessionExit(ctx, shells, owner, id, status, marker, wrapped, fallback, fallbackTruncated, config);
+			let operation;
+			let result;
+			try {
+				operation = ctx.terminals.startSend(owner, id, {
+					text: first ? wrapped : "",
+					submit: first,
+					signal: commandDeadline.signal
+				});
+				first = false;
+				result = await operation.done;
+			} catch (error) {
+				await shells.reset(owner, "persistent pwsh 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.terminals.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, wrapped, fallback, fallbackTruncated), config.maxOutputChars);
+				await shells.reset(owner, "persistent pwsh 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 pwsh command aborted");
+				commandDeadline.signal.throwIfAborted();
+			}
+			if (latest.text.includes(marker.end)) {
+				const complete = commandOutput(retainedScrollback(ctx, owner, id, latest), marker, wrapped);
+				if (complete !== void 0) return renderCaptured(complete, config.maxOutputChars);
+			}
+			if (result.sessionStatus.kind === "exited") return await respondToSessionExit(ctx, shells, owner, id, result.sessionStatus, marker, wrapped, fallback, fallbackTruncated, config);
+			if (promptCompleted(result)) return renderCaptured(partialOutput(retainedScrollback(ctx, owner, id, latest), marker, wrapped, 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 `pwsh` tool.
+* @param ctx - plugin context carrying tools and the owner-scoped PTY service.
+* @param config - selected PTY backend and command deadline.
+*/
+function registerPersistentPwsh(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: "pwsh",
+		description: config.description,
+		parameters: { command: {
+			type: "string",
+			required: true,
+			description: "The PowerShell 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("pwsh 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-pwsh-persistent";
+const inject = ["tools", "terminals"];
+/** Runtime configuration schema for the persistent pwsh 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 `pwsh` 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-pwsh-persistent: backendType must be non-empty");
+	if (!Number.isSafeInteger(resolved.timeoutMs) || resolved.timeoutMs <= 0) throw new Error("tool-pwsh-persistent: timeoutMs must be a positive safe integer");
+	if (!Number.isSafeInteger(resolved.maxOutputChars) || resolved.maxOutputChars <= 0) throw new Error("tool-pwsh-persistent: maxOutputChars must be a positive safe integer");
+	if (resolved.description.trim().length === 0) throw new Error("tool-pwsh-persistent: description must be non-empty");
+	registerPersistentPwsh(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-pwsh-persistent`.
+* @module @deepseek-ai/dsh-tool-pwsh-persistent/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-pwsh-persistent";
+/** Cordis companion plugin name. */
+const name = "tool-pwsh-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 API 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 `pwsh` tool over the owner-scoped PTY seam.
+ * @module @deepseek-ai/dsh-tool-pwsh-persistent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "tool-pwsh-persistent";
+export declare const inject: string[];
+/** Configuration for the persistent pwsh 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 pwsh tool. */
+export declare const Config: z<Config>;
+/** Register one owner-scoped persistent `pwsh` 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-pwsh-persistent`.
+ * @module @deepseek-ai/dsh-tool-pwsh-persistent/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-pwsh-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,62 @@
+{
+  "name": "@deepseek-ai/dsh-tool-pwsh-persistent",
+  "description": "Model-facing owner-scoped persistent PowerShell tool backed by the Harness PTY service",
+  "version": "0.1.0-rc.8",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/shell/tool-pwsh-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": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-terminal": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.8",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "^1.0.6",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-terminal": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-pwsh-local": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-terminal-bash": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}