@deepseek-ai/dsh-terminal-bash 0.0.1-rc.3

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/terminal/terminal-bash/README.md
+README.md: 36e725fd4ce86be09755768a9e21ccb66d025251
+README.zh.md: 080f45eb03dfdeece91269a3253aeb3fb280864d

package/README.md

@@ -0,0 +1,36 @@
+# @deepseek-ai/dsh-terminal-bash
+
+English | [中文](README.zh.md)
+
+Persistent shell backend for `ctx.terminals` over `ctx.subprocess.spawnTerminal`. It starts an interactive shell under the shared `ctx.sandboxPolicy`, retains bounded line-oriented output, and detects readiness while the subprocess provider owns PTY allocation, environment scrubbing, foreground process groups, signalling, and complete terminal-session cleanup. The same PTY backend therefore composes with local or remote execution-world providers.
+
+## Plugin (`terminal-bash`)
+
+The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly without requiring a sandbox provider; confined modes require a same-world `ctx.sandbox` and wrap the exact shell argv through it, failing before spawn when none is mounted. At spawn, one `ctx.sandboxPolicy.resolve({ session })` call supplies both the effective mode and the session workspace root; the same root is the default shell cwd when the caller omits one. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
+
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `TerminalBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. If a provider write is already in flight, signalling waits for it to settle; a rejected write sends no signal. The canceled send retains its slot until the write and foreground signalling settle, so a successor cannot receive either late bytes or that signal. A provider write or signal that never settles therefore retains the slot indefinitely; closing the session (`terminal_close`) is the recovery. The absolute deadline remains armed while cancellation waits. A signal failure is a terminal transport failure and rejects the active send. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close rejects new public signals, stops readiness polling, and awaits the handle's provider-owned complete-session termination before settling the active send as `session_exit`.
+
+## Model Experience
+
+### Current file policy and indirect consumer
+
+#### What the model sees
+
+The policy owner contributes capability-neutral `sandbox:policy` context. Through `@deepseek-ai/dsh-tool-terminal` or another PTY consumer, the model may also receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
+
+#### Token effect
+
+The current-policy clause is present while this backend is mounted. Retained PTY scrollback is not placed in model history until a consumer returns bounded output.
+
+#### KV Cache effect
+
+A standing-policy change appends an owner-rendered superseding runtime-context snapshot after retained history; consumer results remain append-only.
+
+## Known Limitations and Deferred Work
+
+- Line-oriented output is normalized; full-screen alternate-buffer interaction is unsupported.
+- Exact stdin-wait detection depends on the mounted subprocess provider; providers that cannot prove it use prompt-marker and silence/timeout readiness.
+- Cleanup guarantees are those of `SubprocessTerminalHandle`; provider-specific gaps belong to that implementation's contract rather than this PTY consumer.
+- Sessions do not survive harness process exit.

package/README.zh.md

@@ -0,0 +1,36 @@
+# @deepseek-ai/dsh-terminal-bash
+
+[English](README.md) | 中文
+
+这是一个基于 `ctx.subprocess.spawnTerminal`、为 `ctx.terminals` 提供的持久 shell 后端。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，保留有界的逐行输出并检测就绪状态；进程管理提供方则负责 PTY 分配、环境清理、前台进程组、信号发送和完整终端会话清理。因此，同一个 PTY 后端可以与本地或远程执行世界提供方组合。
+
+## 插件（`terminal-bash`）
+
+该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`TerminalBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+
+取消发送时，系统会先把排队输入标记为已取消，再要求终端句柄向当前前台进程组发送真正的 `SIGINT`；异步写入前检查即使随后结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待其结算；写入被拒绝时不会发送信号。已取消的 send 会保留其位置，直到写入与前台信号发送都结算，因此后继 send 不会收到延迟字节或该信号。因此，永不结算的提供方写入或信号会无限期保留该位置；恢复手段是关闭会话（`terminal_close`）。取消等待期间，绝对 deadline 仍保持启用。信号发送失败是终端传输失败，会拒绝活跃 send。取消绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待由句柄提供方负责的完整会话终止，然后才把活跃 send 结算为 `session_exit`。
+
+## 模型体验
+
+### 当前文件策略与间接消费方
+
+#### 模型看到的内容
+
+策略归属方会贡献与具体能力无关的 `sandbox:policy` 上下文。模型通过 `@deepseek-ai/dsh-tool-terminal` 或其他 PTY 消费方还可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
+
+#### Token 影响
+
+装载该后端期间，当前策略子句会一直存在。消费方返回有界输出前，保留的 PTY scrollback 不会进入模型历史。
+
+#### KV Cache 影响
+
+常驻策略发生变化时，会在保留的历史之后追加一份由归属方渲染、取代先前状态的运行时上下文快照；消费方结果保持仅追加。
+
+## 已知限制与暂缓事项
+
+- 输出按行规范化；不支持全屏备用缓冲区交互。
+- 精确 stdin 等待检测取决于已挂载的进程管理提供方；无法证明该状态的提供方使用提示符标记和静默／超时就绪机制。
+- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的约定，而非这个 PTY 消费方。
+- harness 进程退出后，会话无法继续存在。

package/lib/index.js

@@ -0,0 +1,805 @@
+import { TerminalBackendCleanupError, TerminalError } from "@deepseek-ai/dsh-terminal";
+import { effectiveSandboxMode } from "@deepseek-ai/dsh-sandbox-policy";
+import z from "@deepseek-ai/schemastery";
+import { Buffer } from "node:buffer";
+//#region lib/types/config.js
+/** Validated configuration for the local PTY backend. */
+/** Schemastery config exposed by the plugin. */
+const Config = z.object({
+	backendType: z.string().default("shell"),
+	shellPath: z.string().default("/bin/bash"),
+	shellArgs: z.array(z.string()).default([
+		"--noprofile",
+		"--norc",
+		"-i"
+	]),
+	rows: z.number().default(40),
+	cols: z.number().default(160),
+	scrollbackLines: z.number().default(1e4),
+	scrollbackMaxBytes: z.number().default(4 * 1024 * 1024),
+	maxReadBytes: z.number().default(256 * 1024),
+	pollIntervalMs: z.number().default(50),
+	exactProbeAfterMs: z.number().default(150),
+	idleSilenceMs: z.number().default(3e3),
+	handoffGraceMs: z.number().default(500),
+	timeoutMs: z.number().default(3e4),
+	disposeGraceMs: z.number().default(3e3)
+});
+/**
+* Assert every numeric config field is a positive safe integer and bounds compose.
+* @param config - Schemastery-resolved plugin configuration.
+* @returns Narrows the input to the fully resolved configuration.
+*/
+function validateConfig(config) {
+	const resolved = config;
+	if (resolved.backendType.length === 0) throw new Error("terminal-bash: backendType must be non-empty");
+	if (resolved.shellPath.length === 0) throw new Error("terminal-bash: shellPath must be non-empty");
+	for (const [name, value] of Object.entries(resolved)) if (typeof value === "number" && (!Number.isSafeInteger(value) || value <= 0)) throw new Error(`terminal-bash: ${name} must be a positive safe integer`);
+	if (resolved.maxReadBytes > resolved.scrollbackMaxBytes) throw new Error("terminal-bash: maxReadBytes must not exceed scrollbackMaxBytes");
+	if (resolved.handoffGraceMs < resolved.pollIntervalMs) throw new Error("terminal-bash: handoffGraceMs must be at least pollIntervalMs so one readiness poll runs inside the grace window");
+}
+/** Exact printable prompt emitted after the private marker. */
+const CONTROLLED_PROMPT = "dsh> ";
+/**
+* Remove CSI/OSC/short escape sequences while preserving split-sequence carry.
+* Full terminal emulation is deliberately deferred; ordinary line output and
+* the private prompt marker are the supported contract.
+*/
+var TerminalSanitizer = class {
+	maxPendingBytes;
+	pending = "";
+	discardMode;
+	discardOscEscape = false;
+	trailingCarriageReturn = false;
+	trackingPromptTail = false;
+	constructor(maxPendingBytes) {
+		this.maxPendingBytes = maxPendingBytes;
+	}
+	/**
+	* Consume one decoded `node-pty` data chunk.
+	* @param chunk - decoded terminal data.
+	* @returns Printable text and whether the private prompt marker completed.
+	*/
+	push(chunk) {
+		this.pending += this.discardPrefix(chunk);
+		let text = "";
+		let prompt = false;
+		let includePromptTail = this.trackingPromptTail;
+		let promptTail = "";
+		let index = 0;
+		const appendText = (value) => {
+			text += value;
+			if (this.trackingPromptTail) promptTail += value;
+		};
+		while (index < this.pending.length) {
+			const escape = this.pending.indexOf("\x1B", index);
+			if (escape < 0) {
+				appendText(this.pending.slice(index));
+				index = this.pending.length;
+				break;
+			}
+			appendText(this.pending.slice(index, escape));
+			if (escape + 1 >= this.pending.length) {
+				index = escape;
+				break;
+			}
+			const kind = this.pending[escape + 1];
+			if (kind === "]") {
+				const bel = this.pending.indexOf("\x07", escape + 2);
+				const stringTerminator = this.pending.indexOf("\x1B\\", escape + 2);
+				let end = -1;
+				if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2);
+				else if (bel >= 0) end = bel + 1;
+				else if (stringTerminator >= 0) end = stringTerminator + 2;
+				if (end < 0) {
+					index = escape;
+					break;
+				}
+				const terminatorBytes = this.pending[end - 1] === "\x07" ? 1 : 2;
+				if (this.pending.slice(escape + 2, end - terminatorBytes).startsWith("133;D;")) {
+					prompt = true;
+					this.trackingPromptTail = true;
+					includePromptTail = true;
+					promptTail = "";
+				}
+				index = end;
+				continue;
+			}
+			if (kind === "[") {
+				let end = escape + 2;
+				while (end < this.pending.length) {
+					const code = this.pending.charCodeAt(end);
+					if (code >= 64 && code <= 126) break;
+					end += 1;
+				}
+				if (end >= this.pending.length) {
+					index = escape;
+					break;
+				}
+				index = end + 1;
+				continue;
+			}
+			index = escape + 2;
+		}
+		this.pending = this.pending.slice(index);
+		this.enforcePendingBound();
+		return {
+			text: this.normalizeText(text),
+			prompt,
+			...includePromptTail ? { promptTail } : {}
+		};
+	}
+	/**
+	* Flush a trailing printable fragment when the PTY exits.
+	* @returns Remaining printable text; incomplete escapes are discarded.
+	*/
+	flush() {
+		const text = this.pending.startsWith("\x1B") ? "" : this.pending;
+		this.pending = "";
+		this.discardMode = void 0;
+		this.discardOscEscape = false;
+		this.trackingPromptTail = false;
+		const normalized = this.normalizeText(text);
+		if (!this.trailingCarriageReturn) return normalized;
+		this.trailingCarriageReturn = false;
+		return `${normalized}\n`;
+	}
+	normalizeText(text) {
+		let complete = this.trailingCarriageReturn ? `\r${text}` : text;
+		this.trailingCarriageReturn = false;
+		if (complete.endsWith("\r")) {
+			complete = complete.slice(0, -1);
+			this.trailingCarriageReturn = true;
+		}
+		return normalizeTerminalText(complete);
+	}
+	enforcePendingBound() {
+		if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return;
+		this.discardMode = this.pending[1] === "]" ? "osc" : "csi";
+		this.pending = "";
+	}
+	discardPrefix(chunk) {
+		if (this.discardMode === void 0) return chunk;
+		if (this.discardMode === "csi") {
+			for (let index = 0; index < chunk.length; index += 1) {
+				const code = chunk.charCodeAt(index);
+				if (code >= 64 && code <= 126) {
+					this.discardMode = void 0;
+					return chunk.slice(index + 1);
+				}
+			}
+			return "";
+		}
+		let index = 0;
+		if (this.discardOscEscape) {
+			this.discardOscEscape = false;
+			if (chunk.startsWith("\\")) {
+				this.discardMode = void 0;
+				return chunk.slice(1);
+			}
+		}
+		while (index < chunk.length) {
+			if (chunk[index] === "\x07") {
+				this.discardMode = void 0;
+				return chunk.slice(index + 1);
+			}
+			if (chunk[index] === "\x1B") {
+				if (chunk[index + 1] === "\\") {
+					this.discardMode = void 0;
+					return chunk.slice(index + 2);
+				}
+				if (index + 1 === chunk.length) this.discardOscEscape = true;
+			}
+			index += 1;
+		}
+		return "";
+	}
+};
+/**
+* Normalize CRLF and standalone carriage returns for line-oriented rendering.
+* @param text - sanitized terminal text.
+* @returns Line-normalized text with BEL removed.
+*/
+function normalizeTerminalText(text) {
+	return text.replaceAll("\r\n", "\n").replaceAll("\r", "\n").replaceAll("\x07", "");
+}
+//#endregion
+//#region lib/types/session.js
+/** Persistent PTY session over the subprocess seam's terminal primitive. */
+function utf8Tail(text, maxBytes) {
+	if (Buffer.byteLength(text) <= maxBytes) return {
+		text,
+		truncated: false
+	};
+	const chars = Array.from(text);
+	let bytes = 0;
+	let start = chars.length;
+	while (start > 0) {
+		const next = Buffer.byteLength(chars[start - 1]);
+		if (bytes + next > maxBytes) break;
+		bytes += next;
+		start -= 1;
+	}
+	return {
+		text: chars.slice(start).join(""),
+		truncated: true
+	};
+}
+var BoundedTextBuffer = class {
+	maxBytes;
+	maxLines;
+	value = "";
+	dropped = false;
+	constructor(maxBytes, maxLines) {
+		this.maxBytes = maxBytes;
+		this.maxLines = maxLines;
+	}
+	append(text) {
+		if (text.length === 0) return;
+		this.value += text;
+		if (this.maxLines !== void 0) {
+			const lines = this.value.split("\n");
+			if (lines.length > this.maxLines) {
+				this.value = lines.slice(lines.length - this.maxLines).join("\n");
+				this.dropped = true;
+			}
+		}
+		const tail = utf8Tail(this.value, this.maxBytes);
+		this.value = tail.text;
+		this.dropped ||= tail.truncated;
+	}
+	consume() {
+		const delta = this.value;
+		const truncated = this.dropped;
+		this.value = "";
+		this.dropped = false;
+		return {
+			delta,
+			truncated
+		};
+	}
+	snapshot() {
+		return {
+			text: this.value,
+			truncated: this.dropped
+		};
+	}
+};
+var LocalSendOperation = class {
+	startedAt;
+	onCancel;
+	output;
+	promise;
+	finished = false;
+	cancellationRequested = false;
+	initialForegroundLeftWait;
+	initialForegroundPgid;
+	constructor(maxBytes, startedAt, onCancel) {
+		this.startedAt = startedAt;
+		this.onCancel = onCancel;
+		this.output = new BoundedTextBuffer(maxBytes);
+		this.promise = Promise.withResolvers();
+		this.initialForegroundLeftWait = true;
+	}
+	get done() {
+		return this.promise.promise;
+	}
+	get settled() {
+		return this.finished;
+	}
+	get cancelRequested() {
+		return this.cancellationRequested;
+	}
+	append(text) {
+		if (!this.finished) this.output.append(text);
+	}
+	settle(waitReason, sessionStatus, inheritedTruncation) {
+		if (this.finished) return;
+		this.finished = true;
+		const read = this.output.snapshot();
+		this.promise.resolve({
+			viewport: read.text,
+			waitReason,
+			sessionStatus,
+			truncated: read.truncated || inheritedTruncation
+		});
+	}
+	fail(error) {
+		if (this.finished) return;
+		this.finished = true;
+		this.promise.reject(error);
+	}
+	readOutput() {
+		return this.output.consume();
+	}
+	setInitialForeground(foreground) {
+		this.initialForegroundPgid = foreground?.processGroupId;
+		this.initialForegroundLeftWait = foreground?.inputWaiting !== true;
+	}
+	acceptsStdinWait(pgid, waiting) {
+		if (pgid !== this.initialForegroundPgid) return waiting;
+		if (!waiting) this.initialForegroundLeftWait = true;
+		return waiting && this.initialForegroundLeftWait;
+	}
+	cancel() {
+		if (this.finished) return false;
+		this.cancellationRequested = true;
+		this.onCancel();
+		return true;
+	}
+};
+/** Backend session wrapping one provider-owned terminal process. */
+var LocalPtySession = class {
+	terminal;
+	config;
+	motd = "";
+	pid;
+	decoder = new TextDecoder();
+	sanitizer;
+	scrollback;
+	outputEnded = Promise.withResolvers();
+	completion;
+	statusValue = { kind: "running" };
+	active;
+	activeTimer;
+	activeDeadlineTimer;
+	activeAbort;
+	interrupting;
+	activeWrite;
+	pollingReady;
+	polling = false;
+	promptSeen = false;
+	promptTextSeen = false;
+	promptTail = "";
+	shellPgid;
+	initializing = false;
+	lastOutputAt = Date.now();
+	closing = false;
+	closePromise;
+	transportFailure;
+	constructor(terminal, config) {
+		this.terminal = terminal;
+		this.config = config;
+		this.pid = terminal.pid;
+		this.sanitizer = new TerminalSanitizer(config.maxReadBytes);
+		this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines);
+		terminal.output.on("data", this.onTerminalData);
+		terminal.output.once("end", this.onTerminalEnd);
+		terminal.output.once("error", this.onTerminalError);
+		this.completion = terminal.done.then((outcome) => this.onExit(outcome), (error) => {
+			this.onTransportFailure(error);
+		});
+	}
+	/**
+	* Capture startup output through the same readiness contract as later sends.
+	* @param signal - optional cancellation while the shell reaches its first prompt.
+	* @returns Resolves after startup readiness; rejects on exit or readiness timeout.
+	*/
+	async initialize(signal) {
+		this.initializing = true;
+		try {
+			const result = await this.startSend({
+				text: "",
+				submit: false,
+				...signal !== void 0 ? { signal } : {}
+			}).done;
+			if (result.waitReason === "session_exit") throw new Error("PTY shell exited during startup");
+			if (result.waitReason === "timeout") throw new Error("PTY shell did not reach readiness before startup timeout");
+			this.motd = result.viewport;
+		} catch (error) {
+			signal?.throwIfAborted();
+			throw error;
+		} finally {
+			this.initializing = false;
+		}
+	}
+	startSend(request) {
+		if (this.closing) throw new Error("PTY session is closing");
+		if (this.statusValue.kind === "exited") throw new Error("PTY session has exited");
+		if (this.active !== void 0) throw new TerminalError(`PTY session already has an active send${this.activeWrite !== void 0 ? " or draining provider write" : this.interrupting !== void 0 ? " or draining foreground interrupt" : ""}`, "SEND_ACTIVE");
+		if (request.signal?.aborted === true) throw new Error("PTY send aborted before write");
+		const operation = new LocalSendOperation(this.config.maxReadBytes, Date.now(), () => {
+			this.interrupt(operation);
+		});
+		this.active = operation;
+		this.resetReadinessEvidence();
+		if (request.signal !== void 0) {
+			const onAbort = () => {
+				operation.cancel();
+			};
+			request.signal.addEventListener("abort", onAbort, { once: true });
+			this.activeAbort = () => request.signal?.removeEventListener("abort", onAbort);
+		}
+		this.activeDeadlineTimer = setTimeout(() => {
+			if (this.active === operation) this.settleActive("timeout", this.activeWrite !== void 0 || this.interrupting === operation);
+		}, this.config.timeoutMs);
+		this.beginSend(operation, request);
+		return operation;
+	}
+	async beginSend(operation, request) {
+		let foreground;
+		try {
+			foreground = await this.terminal.inspectForeground();
+		} catch (error) {
+			if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error);
+			return;
+		}
+		try {
+			if (this.active !== operation || this.closing || this.interrupting === operation) return;
+			operation.setInitialForeground(foreground);
+			const input = `${request.text}${request.submit ? "\r" : ""}`;
+			if (input.length > 0 && !operation.cancelRequested) {
+				this.resetReadinessEvidence();
+				const write = this.terminal.write(input);
+				this.activeWrite = write.then(() => true, () => false);
+				try {
+					await write;
+				} finally {
+					this.activeWrite = void 0;
+				}
+			}
+			if (operation.cancelRequested) return;
+			if (this.active === operation && operation.settled) {
+				this.clearActive();
+				return;
+			}
+			if (this.active === operation && !this.closing) {
+				this.pollingReady = operation;
+				this.schedulePoll(operation);
+			}
+		} catch (error) {
+			if (this.active === operation && !this.closing) if (operation.settled) this.clearActive();
+			else this.failActive(error);
+		}
+	}
+	resetReadinessEvidence() {
+		this.lastOutputAt = Date.now();
+		this.promptSeen = false;
+		this.promptTextSeen = false;
+		this.promptTail = "";
+	}
+	read(request) {
+		const snapshot = this.scrollback.snapshot();
+		const lines = snapshot.text.split("\n");
+		const totalLines = snapshot.text.length === 0 ? 0 : lines.length;
+		const offset = request.offset ?? 0;
+		const count = request.count ?? 500;
+		if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("PTY read offset must be a non-negative safe integer");
+		if (!Number.isSafeInteger(count) || count <= 0) throw new Error("PTY read count must be a positive safe integer");
+		if (offset >= totalLines) return {
+			text: "",
+			totalLines,
+			lineBegin: offset,
+			lineEnd: offset,
+			truncated: snapshot.truncated
+		};
+		const end = totalLines - offset;
+		const start = Math.max(0, end - count);
+		const bounded = utf8Tail(lines.slice(start, end).join("\n"), this.config.maxReadBytes);
+		const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split("\n").length;
+		return {
+			text: bounded.text,
+			totalLines,
+			lineBegin: offset,
+			lineEnd: offset + returnedLines,
+			truncated: snapshot.truncated || bounded.truncated
+		};
+	}
+	async signal(signal) {
+		if (this.closing) throw new Error("PTY session is closing");
+		return {
+			delivered: true,
+			targetPgid: await this.terminal.signalForeground(signal)
+		};
+	}
+	status() {
+		return this.statusValue;
+	}
+	close(reason) {
+		this.closing = true;
+		if (this.closePromise !== void 0) return this.closePromise;
+		const closing = this.closeOnce(reason).catch((error) => {
+			this.closePromise = void 0;
+			this.failActive(error);
+			throw error;
+		});
+		this.closePromise = closing;
+		return closing;
+	}
+	onTerminalData = (chunk) => {
+		const bytes = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+		this.onData(this.decoder.decode(bytes, { stream: true }));
+	};
+	onTerminalEnd = () => {
+		this.onData(this.decoder.decode());
+		this.appendOutput(this.sanitizer.flush());
+		this.outputEnded.resolve();
+	};
+	onTerminalError = (error) => {
+		this.onTransportFailure(error);
+		this.outputEnded.resolve();
+	};
+	onData(data) {
+		const sanitized = this.sanitizer.push(data);
+		this.appendOutput(sanitized.text);
+		if (sanitized.prompt) {
+			this.promptSeen = true;
+			this.promptTail = "";
+			this.lastOutputAt = Date.now();
+		}
+		if (this.promptSeen && sanitized.promptTail !== void 0) {
+			const remaining = Math.max(0, 6 - this.promptTail.length);
+			this.promptTail += sanitized.promptTail.slice(0, remaining);
+			if (sanitized.promptTail.length > remaining) this.promptTail = `${CONTROLLED_PROMPT}\0`;
+			this.promptTextSeen = this.promptTail === CONTROLLED_PROMPT;
+		}
+	}
+	async onExit(outcome) {
+		await this.outputEnded.promise;
+		if (this.transportFailure !== void 0) return;
+		this.statusValue = {
+			kind: "exited",
+			exitCode: outcome.exitCode,
+			signal: outcome.signal
+		};
+		this.settleActive("session_exit");
+	}
+	onTransportFailure(error) {
+		const failure = error instanceof Error ? error : new Error(String(error));
+		this.transportFailure ??= failure;
+		this.statusValue = {
+			kind: "exited",
+			exitCode: null,
+			signal: null
+		};
+		this.failActive(failure);
+		this.terminal.terminate().catch(() => {});
+	}
+	appendOutput(text) {
+		if (text.length === 0) return;
+		this.lastOutputAt = Date.now();
+		this.scrollback.append(text);
+		this.active?.append(text);
+	}
+	schedulePoll(operation, delayMs = this.config.pollIntervalMs) {
+		if (this.active !== operation || this.interrupting === operation || this.polling) return;
+		if (this.activeTimer !== void 0) clearTimeout(this.activeTimer);
+		this.activeTimer = setTimeout(() => {
+			this.activeTimer = void 0;
+			this.pollReadiness(operation);
+		}, delayMs);
+	}
+	async pollReadiness(operation) {
+		if (this.active !== operation || this.polling) return;
+		this.polling = true;
+		try {
+			if (this.statusValue.kind === "exited") {
+				this.settleActive("session_exit");
+				return;
+			}
+			const foreground = await this.terminal.inspectForeground();
+			if (this.active !== operation || this.closing || this.interrupting === operation) return;
+			const idleFor = Date.now() - this.lastOutputAt;
+			if (this.promptSeen && foreground !== void 0 && this.shellPgid === void 0) this.shellPgid = foreground.processGroupId;
+			if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs && foreground?.processGroupId === this.shellPgid) {
+				this.settleActive("stdin_read");
+				return;
+			}
+			const elapsed = Date.now() - operation.startedAt;
+			const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0;
+			const acceptsStdinWait = startupHasOutput && foreground !== void 0 && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting);
+			if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
+				this.settleActive("stdin_read");
+				return;
+			}
+			const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0;
+			if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) this.settleActive("inferred_idle");
+		} catch (error) {
+			if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error);
+		} finally {
+			this.polling = false;
+			const active = this.active;
+			if (active !== void 0 && this.pollingReady === active) this.schedulePoll(active);
+		}
+	}
+	settleActive(waitReason, retainOwnership = false) {
+		const operation = this.active;
+		if (operation === void 0) return;
+		const scrollbackTruncated = this.scrollback.snapshot().truncated;
+		if (retainOwnership) {
+			this.stopPolling();
+			this.activeAbort?.();
+			this.activeAbort = void 0;
+		} else this.clearActive();
+		operation.settle(waitReason, this.statusValue, scrollbackTruncated);
+	}
+	stopPolling() {
+		this.stopReadinessPolling();
+		if (this.activeDeadlineTimer !== void 0) clearTimeout(this.activeDeadlineTimer);
+		this.activeDeadlineTimer = void 0;
+	}
+	stopReadinessPolling() {
+		if (this.activeTimer !== void 0) clearTimeout(this.activeTimer);
+		this.activeTimer = void 0;
+		this.pollingReady = void 0;
+	}
+	clearActive() {
+		const operation = this.active;
+		this.stopPolling();
+		this.activeAbort?.();
+		this.activeAbort = void 0;
+		if (this.interrupting === operation) this.interrupting = void 0;
+		this.pollingReady = void 0;
+		this.active = void 0;
+	}
+	failActive(error) {
+		const operation = this.active;
+		if (operation === void 0) return;
+		this.clearActive();
+		operation.fail(error);
+	}
+	interrupt(operation) {
+		if (this.active !== operation) return;
+		this.interrupting = operation;
+		this.stopReadinessPolling();
+		this.interruptOnce(operation);
+	}
+	async interruptOnce(operation) {
+		try {
+			const activeWrite = this.activeWrite;
+			if (activeWrite !== void 0 && !await activeWrite) return;
+			await this.terminal.signalForeground("SIGINT");
+		} catch (error) {
+			if (this.active === operation && !this.closing) this.onTransportFailure(error);
+			return;
+		} finally {
+			if (this.interrupting === operation) this.interrupting = void 0;
+		}
+		if (this.active === operation && operation.settled) this.clearActive();
+		else if (this.active === operation && !this.closing) {
+			this.pollingReady = operation;
+			this.schedulePoll(operation, 0);
+		}
+	}
+	async closeOnce(reason) {
+		this.stopPolling();
+		try {
+			await this.terminal.terminate();
+		} catch (error) {
+			throw new Error(`PTY cleanup failed (${reason})`, { cause: error });
+		}
+		this.settleActive("session_exit");
+		await this.completion;
+		this.terminal.output.off("data", this.onTerminalData);
+		this.terminal.output.off("end", this.onTerminalEnd);
+		this.terminal.output.off("error", this.onTerminalError);
+		if (this.transportFailure !== void 0) throw this.transportFailure;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Persistent shell PTY backend over the subprocess terminal primitive, shared
+* sandbox policy, bounded output, and provider-owned session cleanup.
+* @module @deepseek-ai/dsh-terminal-bash
+*/
+/** Cordis plugin name. */
+const name = "terminal-bash";
+/** Required services: PTY registry, shared confinement policy, and process substrate. */
+const inject = [
+	"terminals",
+	"sandboxPolicy",
+	"subprocess"
+];
+const sandboxModeFences = /* @__PURE__ */ new WeakMap();
+function ensureSandboxModeFence(ctx, owner) {
+	const existing = sandboxModeFences.get(owner);
+	if (existing !== void 0) {
+		existing.pty = ctx.terminals;
+		existing.sandboxPolicy = ctx.sandboxPolicy;
+		return;
+	}
+	const state = {
+		pty: ctx.terminals,
+		sandboxPolicy: ctx.sandboxPolicy
+	};
+	sandboxModeFences.set(owner, state);
+	owner.ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const [session, event] = args;
+		if (session !== owner.session || event.type !== "sandbox/mode") return;
+		const currentMode = effectiveSandboxMode(session.events) ?? state.sandboxPolicy.defaultMode;
+		if (event.data.mode === currentMode || !state.pty.hasOwnerActivity(owner)) return;
+		throw new Error(`cannot change sandbox mode from "${currentMode}" to "${event.data.mode}" while persistent terminal sessions are open or being created; wait for creation to settle and close them first`);
+	}, { global: true });
+}
+function childEnvironment(spec) {
+	return {
+		TERM: "dumb",
+		PAGER: "cat",
+		GIT_PAGER: "cat",
+		PS1: CONTROLLED_PROMPT,
+		PROMPT_COMMAND: "printf \"\\033]133;D;%s\\007\" \"$?\"",
+		BASH_SILENCE_DEPRECATION_WARNING: "1",
+		DSH_SHELL: "1",
+		DSH_SESSION_ID: spec.owner.id,
+		DSH_PTY_SESSION_ID: spec.sessionId
+	};
+}
+function spawnArgv(ctx, config, policy) {
+	const argv = [config.shellPath, ...config.shellArgs];
+	if (policy.mode === "danger-full-access") return argv;
+	const sandbox = ctx.get("sandbox");
+	if (sandbox === void 0) throw new Error(`terminal-bash: sandbox mode "${policy.mode}" requires a ctx.sandbox provider in the execution world`);
+	return sandbox.confine(argv, {
+		...policy,
+		mode: policy.mode
+	}).argv;
+}
+async function initializeSession(session, signal) {
+	if (signal === void 0) {
+		await session.initialize(signal);
+		return;
+	}
+	const aborted = Promise.withResolvers();
+	const onAbort = () => {
+		aborted.reject(signal.reason);
+	};
+	signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		signal.throwIfAborted();
+		await Promise.race([session.initialize(signal), aborted.promise]);
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+/** Local shell backend registered under the configured type. */
+var BashTerminalBackend = class {
+	ctx;
+	config;
+	spawnTerminal;
+	createSession;
+	type;
+	constructor(ctx, config, spawnTerminal = (spec) => ctx.subprocess.spawnTerminal(spec), createSession = (terminal, config) => new LocalPtySession(terminal, config)) {
+		this.ctx = ctx;
+		this.config = config;
+		this.spawnTerminal = spawnTerminal;
+		this.createSession = createSession;
+		this.type = config.backendType;
+	}
+	async spawn(spec) {
+		spec.signal?.throwIfAborted();
+		ensureSandboxModeFence(this.ctx, spec.owner);
+		const policy = this.ctx.sandboxPolicy.resolve({ session: spec.owner.session });
+		const argv = spawnArgv(this.ctx, this.config, policy);
+		if (argv[0] === void 0) throw new Error("terminal-bash: sandbox returned empty argv");
+		const terminal = await this.spawnTerminal({
+			argv,
+			cwd: spec.cwd ?? policy.workspaceRoot,
+			env: childEnvironment(spec),
+			rows: this.config.rows,
+			cols: this.config.cols,
+			graceMs: this.config.disposeGraceMs,
+			signal: spec.signal
+		});
+		const session = this.createSession(terminal, this.config);
+		try {
+			await initializeSession(session, spec.signal);
+			return session;
+		} catch (error) {
+			try {
+				await session.close("PTY startup failed");
+			} catch (closeError) {
+				throw new TerminalBackendCleanupError(error, closeError);
+			}
+			throw error;
+		}
+	}
+};
+/** Register the local PTY backend. */
+function apply(ctx, config) {
+	validateConfig(config);
+	ctx.terminals.registerBackend(new BashTerminalBackend(ctx, config));
+}
+//#endregion
+export { BashTerminalBackend, Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-terminal-bash`.
+* @module @deepseek-ai/dsh-terminal-bash/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-terminal-bash";
+/** Cordis companion plugin name. */
+const name = "terminal-bash-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: readiness, terminal buffers, and process-tree state are private per-session
+* implementation state, and the backend publishes no independent lifecycle stream or snapshot.
+*/
+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/config.d.ts

@@ -0,0 +1,47 @@
+/** Validated configuration for the local PTY backend. */
+import z from '@deepseek-ai/schemastery';
+/** Public plugin configuration. */
+export interface Config {
+    /** Backend registry type (default: `shell`). */
+    backendType?: string;
+    /** Interactive shell executable (default: `/bin/bash`). */
+    shellPath?: string;
+    /** Shell arguments (default: `--noprofile --norc -i`). */
+    shellArgs?: string[];
+    /** Terminal rows. */
+    rows?: number;
+    /** Terminal columns. */
+    cols?: number;
+    /** Maximum retained logical lines. */
+    scrollbackLines?: number;
+    /** Maximum retained UTF-8 bytes. */
+    scrollbackMaxBytes?: number;
+    /** Maximum bytes returned by one read or settled viewport. */
+    maxReadBytes?: number;
+    /** Readiness polling interval. */
+    pollIntervalMs?: number;
+    /** Delay before Linux exact syscall probes. */
+    exactProbeAfterMs?: number;
+    /** Silence duration that yields `inferred_idle`. */
+    idleSilenceMs?: number;
+    /**
+     * Extra wait beyond `idleSilenceMs`, once a prompt marker was seen, for the shell to
+     * regain the foreground before `inferred_idle` settles; at least one `pollIntervalMs`.
+     */
+    handoffGraceMs?: number;
+    /** Absolute send wait bound. */
+    timeoutMs?: number;
+    /** Grace before teardown escalates to `SIGKILL`. */
+    disposeGraceMs?: number;
+}
+/** Configuration after Schemastery defaults. */
+export type ResolvedConfig = Required<Config>;
+/** Schemastery config exposed by the plugin. */
+export declare const Config: z<Config>;
+/**
+ * Assert every numeric config field is a positive safe integer and bounds compose.
+ * @param config - Schemastery-resolved plugin configuration.
+ * @returns Narrows the input to the fully resolved configuration.
+ */
+export declare function validateConfig(config: Config): asserts config is ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Persistent shell PTY backend over the subprocess terminal primitive, shared
+ * sandbox policy, bounded output, and provider-owned session cleanup.
+ * @module @deepseek-ai/dsh-terminal-bash
+ */
+import { Context } from '@deepseek-ai/cordis';
+import type { TerminalBackend, TerminalBackendSpawnSpec } from '@deepseek-ai/dsh-terminal';
+import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import { type Config, type ResolvedConfig } from './config.ts';
+import { LocalPtySession } from './session.ts';
+export { Config } from './config.ts';
+export type { Config as TerminalLocalConfig } from './config.ts';
+/** Cordis plugin name. */
+export declare const name = "terminal-bash";
+/** Required services: PTY registry, shared confinement policy, and process substrate. */
+export declare const inject: string[];
+/** Local shell backend registered under the configured type. */
+export declare class BashTerminalBackend implements TerminalBackend {
+    private readonly ctx;
+    private readonly config;
+    private readonly spawnTerminal;
+    private readonly createSession;
+    readonly type: string;
+    constructor(ctx: Context, config: ResolvedConfig, spawnTerminal?: (spec: SubprocessTerminalSpawnSpec) => Promise<SubprocessTerminalHandle>, createSession?: (terminal: SubprocessTerminalHandle, config: ResolvedConfig) => LocalPtySession);
+    spawn(spec: TerminalBackendSpawnSpec): Promise<LocalPtySession>;
+}
+/** Register the local PTY backend. */
+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-terminal-bash`.
+ * @module @deepseek-ai/dsh-terminal-bash/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "terminal-bash-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/lib/types/sanitize.d.ts

@@ -0,0 +1,47 @@
+/** Streaming terminal-control sanitizer for the line-oriented first release. */
+/** OSC marker emitted by the controlled bash before each prompt. */
+export declare const PROMPT_MARKER_PREFIX = "133;D;";
+/** Exact printable prompt emitted after the private marker. */
+export declare const CONTROLLED_PROMPT = "dsh> ";
+/** One sanitized chunk plus whether it contained the owned prompt marker. */
+export interface SanitizedChunk {
+    text: string;
+    prompt: boolean;
+    /** Printable text after the latest owned marker in this chunk. */
+    promptTail?: string;
+}
+/**
+ * Remove CSI/OSC/short escape sequences while preserving split-sequence carry.
+ * Full terminal emulation is deliberately deferred; ordinary line output and
+ * the private prompt marker are the supported contract.
+ */
+export declare class TerminalSanitizer {
+    private readonly maxPendingBytes;
+    private pending;
+    private discardMode;
+    private discardOscEscape;
+    private trailingCarriageReturn;
+    private trackingPromptTail;
+    constructor(maxPendingBytes: number);
+    /**
+     * Consume one decoded `node-pty` data chunk.
+     * @param chunk - decoded terminal data.
+     * @returns Printable text and whether the private prompt marker completed.
+     */
+    push(chunk: string): SanitizedChunk;
+    /**
+     * Flush a trailing printable fragment when the PTY exits.
+     * @returns Remaining printable text; incomplete escapes are discarded.
+     */
+    flush(): string;
+    private normalizeText;
+    private enforcePendingBound;
+    private discardPrefix;
+}
+/**
+ * Normalize CRLF and standalone carriage returns for line-oriented rendering.
+ * @param text - sanitized terminal text.
+ * @returns Line-normalized text with BEL removed.
+ */
+export declare function normalizeTerminalText(text: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/lib/types/session.d.ts

@@ -0,0 +1,66 @@
+/** Persistent PTY session over the subprocess seam's terminal primitive. */
+import type { SubprocessTerminalHandle } from '@deepseek-ai/dsh-subprocess';
+import type { TerminalBackendSession, TerminalReadRequest, TerminalReadResult, TerminalSendOperation, TerminalSendRequest, TerminalSessionStatus, TerminalSignal, TerminalSignalResult } from '@deepseek-ai/dsh-terminal';
+import type { ResolvedConfig } from './config.ts';
+/** Backend session wrapping one provider-owned terminal process. */
+export declare class LocalPtySession implements TerminalBackendSession {
+    private readonly terminal;
+    private readonly config;
+    motd: string;
+    readonly pid: number;
+    private readonly decoder;
+    private readonly sanitizer;
+    private readonly scrollback;
+    private readonly outputEnded;
+    private readonly completion;
+    private statusValue;
+    private active;
+    private activeTimer;
+    private activeDeadlineTimer;
+    private activeAbort;
+    private interrupting;
+    private activeWrite;
+    private pollingReady;
+    private polling;
+    private promptSeen;
+    private promptTextSeen;
+    private promptTail;
+    private shellPgid;
+    private initializing;
+    private lastOutputAt;
+    private closing;
+    private closePromise;
+    private transportFailure;
+    constructor(terminal: SubprocessTerminalHandle, config: ResolvedConfig);
+    /**
+     * Capture startup output through the same readiness contract as later sends.
+     * @param signal - optional cancellation while the shell reaches its first prompt.
+     * @returns Resolves after startup readiness; rejects on exit or readiness timeout.
+     */
+    initialize(signal?: AbortSignal): Promise<void>;
+    startSend(request: TerminalSendRequest): TerminalSendOperation;
+    private beginSend;
+    private resetReadinessEvidence;
+    read(request: TerminalReadRequest): TerminalReadResult;
+    signal(signal: TerminalSignal): Promise<TerminalSignalResult>;
+    status(): TerminalSessionStatus;
+    close(reason: string): Promise<void>;
+    private readonly onTerminalData;
+    private readonly onTerminalEnd;
+    private readonly onTerminalError;
+    private onData;
+    private onExit;
+    private onTransportFailure;
+    private appendOutput;
+    private schedulePoll;
+    private pollReadiness;
+    private settleActive;
+    private stopPolling;
+    private stopReadinessPolling;
+    private clearActive;
+    private failActive;
+    private interrupt;
+    private interruptOnce;
+    private closeOnce;
+}
+//# sourceMappingURL=session.d.ts.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@deepseek-ai/dsh-terminal-bash",
+  "description": "Persistent shell PTY backend over the DeepSeek Harness subprocess terminal primitive",
+  "version": "0.0.1-rc.3",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/terminal/terminal-bash"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./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.3",
+    "@deepseek-ai/dsh-terminal": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-terminal": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-subprocess-local": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}