@deepseek-ai/dsh-tool-terminal 0.0.1-rc.5

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/tool-terminal/README.md
+README.md: f6fd4020d423425d7b20ad6bc21b4e009cf25c85
+README.zh.md: 827d179515779f87665a80920e72a11be051023f

package/README.md

@@ -0,0 +1,71 @@
+# @deepseek-ai/dsh-tool-terminal
+
+English | [中文](README.zh.md)
+
+Six model-facing tools over `ctx.terminals`: `terminal_open`, `terminal_send`, `terminal_read`, `terminal_signal`, `terminal_close`, and `terminal_list`. Every operation requires the exact initiating `Agent`, so a model cannot address another agent's terminal even if it learns the id.
+
+`terminal_send(run_in_background: true)` reuses `ctx.jobs`; job preflight and the PTY service's exclusive per-session send reservation occur before the job id is returned, completion is collected with `job_output`, and `job_kill` delivers `SIGINT` to the foreground process group. Foreground sends use terminal call/result cards. Background sends use a generic execute card; open, read, signal, close, and list use generic `execute`, `read`, `execute`, `delete`, and `read` cards respectively. None declares source locations.
+
+## Config
+
+| key | default | meaning |
+|---|---:|---|
+| `enableRunInBackground` | `true` | expose and accept `run_in_background`; false omits the schema field and rejects a forced undeclared argument |
+| `maxResultBytes` | `262144` | UTF-8 cap (minimum `64`) for each complete terminal result or PTY job output after wait, session, pagination, truncation, and task-status metadata |
+
+Both values are validated at load. The minimum result cap keeps every registry-issued session or job id visible in its creation acknowledgement. When a result exceeds `maxResultBytes`, rendering reserves space for control metadata and a truncation marker when they fit; cuts preserve UTF-8 boundaries. Each terminal definition's final-content callback applies the same cap after normalized pre-, around-, and post-execute policy failures, denials, short-circuits, replacements, or blocks; a structured multi-block policy result retains its shape.
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+The plugin contributes this fixed guidance section:
+
+##### Terminal guidance
+
+```markdown
+Use a terminal session only when work needs persistent terminal state or interactive stdin; prefer shell/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.
+```
+
+#### Token effect
+
+Small fixed input cost on every request while the plugin is active.
+
+#### KV Cache effect
+
+Prefix-stable while the registration scope and guidance text are unchanged.
+
+### Tool schemas
+
+#### What the model sees
+
+The six generated schemas are listed in the [`dsh-tool-terminal` catalog section](../../../docs/tool-catalog.md#deepseek-aidsh-tool-terminal). Their fixed schema tokens are present whenever this plugin is active; agent-scoped tool filtering may hide them.
+
+#### Token effect
+
+Fixed schema cost on requests where the tools are visible.
+
+#### KV Cache effect
+
+Prefix-stable while tool visibility and definitions are unchanged.
+
+### Tool results and task context
+
+#### What the model sees
+
+Spawn returns the id and bounded MOTD. Send/read return bounded terminal text plus readiness/history markers. Background mode returns a generic job id. Every terminal-owned or policy-produced single-text result is capped by `maxResultBytes` after normalized tool or pipeline errors, denials, short-circuits, replacements, blocks, and generic job status text. Structured multi-block policy results retain their shape. Results remain in session history until compaction; incremental task reads do not repeat consumed output. Programmatic callers receive typed session snapshots, bounded provider read/send DTOs, signal and close outcomes, or `{ kind: "background", jobId }`; Native rendering applies the presentation cap above.
+
+#### Token effect
+
+Terminal-owned and policy-produced single-text results are data-dependent and bounded by `maxResultBytes`; a policy that deliberately substitutes structured multi-block content owns that content's bound. Each returned result remains in history until compaction.
+
+#### KV Cache effect
+
+Append-only; new results follow the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+- No named key sequence, TUI, BEL, resize, auto-start, or cross-agent sharing schema is exposed.
+- Background mode requires both `@deepseek-ai/dsh-jobs` and its model-facing controller.

package/README.zh.md

@@ -0,0 +1,71 @@
+# @deepseek-ai/dsh-tool-terminal
+
+[English](README.md) | 中文
+
+基于 `ctx.terminals` 提供 6 个面向模型的工具：`terminal_open`、`terminal_send`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list`。每项操作都要求提供完全相同的发起 `Agent`，因此即使模型获知另一个 agent（智能体）的 id，也无法操作其终端。
+
+`terminal_send(run_in_background: true)` 会复用 `ctx.jobs`；任务预检和 PTY 服务对每个会话的独占发送预留都发生在返回 job id 之前。系统通过 `job_output` 收集完成结果，`job_kill` 则向前台进程组发送 `SIGINT`。前台发送使用终端调用／结果卡片。后台发送使用通用执行卡片；打开、读取、发送信号、关闭和列出操作则分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有操作都不声明源位置。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---:|---|
+| `enableRunInBackground` | `true` | 公开并接受 `run_in_background`；设为 false 时，schema 会省略该字段，并拒绝强行传入未声明的参数 |
+| `maxResultBytes` | `262144` | 每个完整终端结果或 PTY 任务输出的 UTF-8 上限（最小值 `64`）；在等待、会话、分页、截断和任务状态元数据全部加入后计算 |
+
+两个值都会在加载时验证。最小结果上限可保证注册表签发的每个会话或 job id 都能出现在创建确认中。结果超过 `maxResultBytes` 时，只要空间允许，渲染会为控制元数据和截断标记预留空间；截断会保留 UTF-8 边界。每个终端定义的最终内容回调都会应用同一个上限，涵盖经过规范化的 pre-execute、around-execute 与 post-execute 策略失败、拒绝、短路、替换或阻止；结构化的多块策略结果保留其结构。
+
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到的内容
+
+该插件贡献以下固定指引章节：
+
+##### 终端指引
+
+```markdown
+Use a terminal session only when work needs persistent terminal state or interactive stdin; prefer shell/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.
+```
+
+#### Token 影响
+
+插件活跃期间，每次请求都会产生少量固定输入成本。
+
+#### KV Cache 影响
+
+注册范围和指引文本不变时，前缀保持稳定。
+
+### 工具 schema
+
+#### 模型看到的内容
+
+6 个生成的 schema 列在 [`dsh-tool-terminal` 目录章节](../../../docs/tool-catalog.md#deepseek-aidsh-tool-terminal)中。此插件活跃时，请求中会包含它们的固定 schema token；按 agent 范围过滤工具时可能隐藏这些 schema。
+
+#### Token 影响
+
+工具可见的请求会产生固定的 schema 成本。
+
+#### KV Cache 影响
+
+工具可见性与定义不变时，前缀保持稳定。
+
+### 工具结果与任务上下文
+
+#### 模型看到的内容
+
+spawn 会返回 id 和有界 MOTD。发送／读取会返回有界终端文本以及就绪／历史标记。后台模式返回通用 job id。所有终端自身或策略产生的单文本结果，在经过规范化的工具或流水线错误、拒绝、短路、替换、阻止与通用任务状态文本之后，都受 `maxResultBytes` 限制。结构化的多块策略结果保留其结构。结果会保留在会话历史中直到压缩（compaction）；增量任务读取不会重复已经消费的输出。编程调用方会收到带类型的会话快照、有界的提供方读取／发送 DTO、信号与关闭结果，或 `{ kind: "background", jobId }`；Native 渲染会应用上述呈现上限。
+
+#### Token 影响
+
+终端自身与策略产生的单文本结果随数据变化，并受 `maxResultBytes` 限制；如果策略有意替换为结构化多块内容，则由该策略负责限制内容。每个返回结果都会保留在历史中直到压缩。
+
+#### KV Cache 影响
+
+仅追加；新结果位于可复用请求前缀之后。
+
+## 已知限制与暂缓事项
+
+- 不公开具名按键序列、TUI、BEL、调整大小、自动启动或跨 agent 共享 schema。
+- 后台模式同时依赖 `@deepseek-ai/dsh-jobs` 及其面向模型的控制器。

package/lib/index.js

@@ -0,0 +1,610 @@
+import z from "@deepseek-ai/schemastery";
+import { TerminalSessionId } from "@deepseek-ai/dsh-terminal";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { TextRetainer } from "@deepseek-ai/dsh-output-retention";
+//#region lib/types/render.js
+/** Model and UI rendering for persistent terminal tool results. */
+const encoder = new TextEncoder();
+const TRUNCATED = "\n[output truncated]";
+function byteLength(text) {
+	return encoder.encode(text).byteLength;
+}
+function retain(text, maxBytes, kind) {
+	const retainer = new TextRetainer({
+		kind,
+		maxBytes
+	});
+	retainer.push(text);
+	return retainer.finish().text;
+}
+function fitWithSuffix(content, suffix, maxBytes) {
+	const fixedBytes = byteLength(suffix);
+	if (fixedBytes >= maxBytes) return retain(suffix, maxBytes, "tail");
+	return `${retain(content, maxBytes - fixedBytes, "tail")}${suffix}`;
+}
+function fitWithPrefix(prefix, content, maxBytes) {
+	const fixed = `${prefix}${TRUNCATED}`;
+	const fixedBytes = byteLength(fixed);
+	if (fixedBytes >= maxBytes) return retain(fixed, maxBytes, "head");
+	return `${prefix}${retain(content, maxBytes - fixedBytes, "tail")}${TRUNCATED}`;
+}
+function boundBodyWithSuffix(content, metadata, upstreamTruncated, maxBytes) {
+	const complete = `${content}${`${metadata}${upstreamTruncated ? TRUNCATED : ""}`}`;
+	if (byteLength(complete) <= maxBytes) return complete;
+	return fitWithSuffix(content, `${metadata}${TRUNCATED}`, maxBytes);
+}
+/**
+* Bound one complete terminal acknowledgement while preserving UTF-8 cuts.
+* @param text - complete acknowledgement text.
+* @param maxBytes - positive final result cap.
+* @returns bounded text with a truncation marker when it fits.
+*/
+function boundTerminalText(text, maxBytes) {
+	if (byteLength(text) <= maxBytes) return text;
+	const markerBytes = byteLength(TRUNCATED);
+	if (markerBytes >= maxBytes) return retain(TRUNCATED, maxBytes, "tail");
+	return `${retain(text, maxBytes - markerBytes, "head")}${TRUNCATED}`;
+}
+/**
+* Render one created session and its bounded MOTD.
+* @param result - published spawn result.
+* @param maxBytes - complete UTF-8 result cap.
+* @returns Model-facing session acknowledgement.
+*/
+function renderSpawn(result, maxBytes) {
+	const prefix = `started terminal session ${result.name === void 0 ? result.sessionId : `${result.sessionId} (${result.name})`} [type: ${result.type}]\n`;
+	const motd = result.motd || "(no startup output)";
+	const complete = `${prefix}${motd}`;
+	return byteLength(complete) <= maxBytes ? complete : fitWithPrefix(prefix, motd, maxBytes);
+}
+/**
+* Render one settled interactive send.
+* @param result - settled send outcome.
+* @param maxBytes - complete UTF-8 result cap.
+* @returns Terminal output plus wait/session markers.
+*/
+function renderSend(result, maxBytes) {
+	const output = result.viewport || "(no new output)";
+	const status = result.sessionStatus.kind === "running" ? "running" : `exited code=${result.sessionStatus.exitCode ?? "null"} signal=${result.sessionStatus.signal ?? "null"}`;
+	return boundBodyWithSuffix(output, `\n[wait: ${result.waitReason}]\n[session: ${status}]`, result.truncated, maxBytes);
+}
+/**
+* Render one incremental background operation read.
+* @param read - consuming operation delta.
+* @returns Delta plus its upstream truncation marker. The generic task control
+*   applies the producer's complete-result cap after adding job status.
+*/
+function renderSendRead(read) {
+	const separator = read.delta.endsWith("\n") || read.delta.length === 0 ? "" : "\n";
+	return `${read.delta}${read.truncated ? `${separator}[output truncated]` : ""}`;
+}
+/**
+* Render one bounded historical page.
+* @param result - retained scrollback page.
+* @param maxBytes - complete UTF-8 result cap.
+* @returns Page text plus pagination and truncation markers.
+*/
+function renderRead(result, maxBytes) {
+	return boundBodyWithSuffix(result.text || "(no retained output)", `\n[lines: ${result.lineBegin}-${result.lineEnd} of ${result.totalLines}]`, result.truncated, maxBytes);
+}
+/**
+* Render owner-visible live sessions.
+* @param sessions - fresh owner-scoped snapshots.
+* @param maxBytes - complete UTF-8 result cap.
+* @returns One line per session or the empty marker.
+*/
+function renderList(sessions, maxBytes) {
+	if (sessions.length === 0) return "(no terminal sessions)";
+	return boundBodyWithSuffix(sessions.map((session) => {
+		const name = session.name === void 0 ? "" : ` (${session.name})`;
+		const pid = session.pid === void 0 ? "" : ` pid=${session.pid}`;
+		const status = session.status.kind === "running" ? "running" : `exited code=${session.status.exitCode ?? "null"} signal=${session.status.signal ?? "null"}`;
+		return `${session.sessionId}${name} [${session.type}] ${status}${pid}`;
+	}).join("\n"), "", false, maxBytes);
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Six model-facing persistent terminal tools. Owner identity comes from the exact
+* tool execution Agent; generic `ctx.jobs` owns background ids and collection.
+* @module @deepseek-ai/dsh-tool-terminal
+*/
+/** Cordis plugin name. */
+const name = "tool-terminal";
+/** Required capability, registry, and prompt services. */
+const inject = [
+	"terminals",
+	"tools",
+	"systemPrompt"
+];
+/** Default cap for one complete model-facing terminal result. */
+const DEFAULT_MAX_RESULT_BYTES = 256 * 1024;
+/** Smallest cap that preserves every counter-backed PTY and job id in its creation acknowledgement. */
+const MIN_MAX_RESULT_BYTES = 64;
+/** Schemastery configuration for the terminal tool consumer. */
+const Config = z.object({
+	enableRunInBackground: z.boolean().default(true),
+	maxResultBytes: z.number().step(1).min(64).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RESULT_BYTES)
+});
+const SESSION_STATUS_SCHEMA = { oneOf: [{
+	type: "object",
+	additionalProperties: false,
+	properties: { kind: {
+		type: "string",
+		required: true,
+		const: "running"
+	} }
+}, {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		kind: {
+			type: "string",
+			required: true,
+			const: "exited"
+		},
+		exitCode: {
+			required: true,
+			oneOf: [{ type: "integer" }, { type: "null" }]
+		},
+		signal: {
+			required: true,
+			oneOf: [{ type: "string" }, { type: "null" }]
+		}
+	}
+}] };
+const SESSION_SNAPSHOT_PROPERTIES = {
+	sessionId: {
+		type: "string",
+		required: true
+	},
+	name: { type: "string" },
+	type: {
+		type: "string",
+		required: true
+	},
+	pid: { type: "integer" },
+	status: {
+		...SESSION_STATUS_SCHEMA,
+		required: true
+	}
+};
+const SESSION_SNAPSHOT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: SESSION_SNAPSHOT_PROPERTIES
+};
+const BACKGROUND_TASK_OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		kind: {
+			type: "string",
+			required: true,
+			const: "background"
+		},
+		jobId: {
+			type: "string",
+			required: true
+		}
+	}
+};
+function requireAgent(agent) {
+	if (agent === void 0) throw new Error("terminal tools require an initiating agent");
+	return agent;
+}
+function sessionId(args) {
+	if (args.sessionId.length === 0) throw new Error("sessionId must be a non-empty string");
+	return TerminalSessionId(args.sessionId);
+}
+function textResult(text, maxBytes) {
+	return [{
+		type: "text",
+		text: boundTerminalText(text, maxBytes)
+	}];
+}
+function rawContentText(content) {
+	if (content.length !== 1) return void 0;
+	const block = content[0];
+	return block?.type === "text" ? block.text : void 0;
+}
+function sendDetail(result) {
+	return result.sessionStatus.kind === "running" ? `wait: ${result.waitReason}` : `session exited: ${result.sessionStatus.exitCode ?? result.sessionStatus.signal ?? "unknown"}`;
+}
+/** Register all terminal tools and the minimal usage guidance. */
+function apply(ctx, config = {}) {
+	const enableRunInBackground = config.enableRunInBackground ?? true;
+	const maxResultBytes = config.maxResultBytes ?? 262144;
+	if (!Number.isSafeInteger(maxResultBytes) || maxResultBytes < 64) throw new Error(`tool-terminal: maxResultBytes must be a safe integer of at least 64`);
+	const finalizeContent = (_exec, result) => {
+		const raw = rawContentText(result.content);
+		return raw === void 0 ? void 0 : textResult(raw, maxResultBytes);
+	};
+	ctx.systemPrompt.section({
+		name: "tool:pty",
+		order: 106,
+		text: "Use a terminal session only when work needs persistent terminal state or interactive stdin; prefer shell/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited."
+	});
+	ctx.tools.register(defineTool({
+		name: "terminal_open",
+		description: "Create a persistent, owner-isolated terminal session from a registered backend type. Use this for shell or REPL state that must survive across tool calls.",
+		parameters: {
+			type: {
+				type: "string",
+				required: true,
+				description: "Registered terminal backend type, usually \"shell\"."
+			},
+			name: {
+				type: "string",
+				description: "Optional owner-local display name such as \"main\" or \"gdb\"."
+			},
+			cwd: {
+				type: "string",
+				description: "Initial working directory. Defaults to the deployment workspace root."
+			}
+		},
+		finalizeContent,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					...SESSION_SNAPSHOT_PROPERTIES,
+					motd: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderSpawn(value, maxResultBytes)
+			}]
+		},
+		async execute(args, exec) {
+			if (args.type.length === 0) throw new Error("type must be a non-empty string");
+			return await ctx.terminals.spawn(requireAgent(exec.agent), {
+				type: args.type,
+				...args.name !== void 0 ? { name: args.name } : {},
+				...args.cwd !== void 0 ? { cwd: args.cwd } : {}
+			}, exec.signal);
+		},
+		presentCall: (args) => {
+			const parsed = args;
+			return {
+				card: "generic",
+				title: `Open terminal ${parsed.name ?? parsed.type}`,
+				kind: "execute"
+			};
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "terminal_send",
+		description: "Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit." + (enableRunInBackground ? " Background mode returns a job id for job_output/job_kill." : ""),
+		parameters: {
+			sessionId: {
+				type: "string",
+				required: true,
+				description: "Terminal session id returned by terminal_open or terminal_list."
+			},
+			text: {
+				type: "string",
+				required: true,
+				description: "UTF-8 text to write to the terminal."
+			},
+			submit: {
+				type: "boolean",
+				description: "Submit Enter after text (default true). Set false for control characters or incomplete REPL input."
+			},
+			...enableRunInBackground ? { run_in_background: {
+				type: "boolean",
+				description: "Return a job id immediately; collect with job_output or stop with job_kill."
+			} } : {}
+		},
+		finalizeContent,
+		output: {
+			schema: { oneOf: [BACKGROUND_TASK_OUTPUT_SCHEMA, {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						const: "foreground"
+					},
+					viewport: {
+						type: "string",
+						required: true
+					},
+					waitReason: {
+						type: "string",
+						required: true,
+						enum: [
+							"stdin_read",
+							"inferred_idle",
+							"timeout",
+							"session_exit"
+						]
+					},
+					sessionStatus: {
+						...SESSION_STATUS_SCHEMA,
+						required: true
+					},
+					truncated: {
+						type: "boolean",
+						required: true
+					}
+				}
+			}] },
+			render: (_args, value) => [{
+				type: "text",
+				text: value.kind === "background" ? `started background job ${value.jobId}` : renderSend(value, maxResultBytes)
+			}],
+			presentationMeta: (_args, value) => value.kind === "foreground" ? {
+				viewport: value.viewport,
+				waitReason: value.waitReason,
+				sessionStatus: value.sessionStatus,
+				truncated: value.truncated
+			} : null
+		},
+		async execute(args, exec) {
+			const owner = requireAgent(exec.agent);
+			const id = sessionId(args);
+			const request = {
+				text: args.text,
+				submit: args.submit ?? true
+			};
+			if (args.run_in_background === true) {
+				if (!enableRunInBackground) throw new Error("background terminal sends are disabled by tool-terminal configuration");
+				const jobs = ctx.get("jobs");
+				if (jobs === void 0) throw new Error("background terminal sends require @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs");
+				let cancelRequested = false;
+				return {
+					kind: "background",
+					jobId: jobs.start({
+						kind: "pty-send",
+						label: `${id}: ${args.text || "(input)"}`,
+						owner,
+						outputLimitBytes: maxResultBytes,
+						run: () => {
+							const operation = ctx.terminals.startSend(owner, id, request);
+							return {
+								cancel: () => {
+									cancelRequested = true;
+									operation.cancel();
+								},
+								done: operation.done.then((result) => ({
+									status: cancelRequested ? "killed" : "completed",
+									detail: sendDetail(result)
+								}), (error) => ({
+									status: "failed",
+									detail: String(error)
+								})),
+								readOutput: () => renderSendRead(operation.readOutput())
+							};
+						}
+					})
+				};
+			}
+			const result = await ctx.terminals.startSend(owner, id, {
+				...request,
+				signal: exec.signal
+			}).done;
+			if (exec.signal.aborted) throw new Error("terminal send aborted");
+			return {
+				kind: "foreground",
+				...result
+			};
+		},
+		presentCall(args) {
+			const parsed = args;
+			if (parsed.run_in_background === true) return {
+				card: "generic",
+				title: `Send to terminal ${parsed.sessionId} in background`,
+				kind: "execute",
+				rawInput: parsed.text
+			};
+			return {
+				card: "terminal",
+				title: parsed.text || "(send input)",
+				description: `Terminal ${parsed.sessionId}`
+			};
+		},
+		presentResult(args, result) {
+			if (args.run_in_background === true || result.isError) return void 0;
+			const raw = rawContentText(result.content);
+			return raw === void 0 ? void 0 : {
+				card: "terminal",
+				output: raw
+			};
+		}
+	}));
+	ctx.tools.register(defineTool({
+		name: "terminal_read",
+		description: "Read a bounded page of retained output from a persistent terminal without sending input.",
+		parameters: {
+			sessionId: {
+				type: "string",
+				required: true,
+				description: "Terminal session id."
+			},
+			offset: {
+				type: "number",
+				description: "Newest-relative line offset (default 0)."
+			},
+			count: {
+				type: "number",
+				description: "Requested line count (default 500; backend caps apply)."
+			}
+		},
+		finalizeContent,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					text: {
+						type: "string",
+						required: true
+					},
+					totalLines: {
+						type: "integer",
+						required: true
+					},
+					lineBegin: {
+						type: "integer",
+						required: true
+					},
+					lineEnd: {
+						type: "integer",
+						required: true
+					},
+					truncated: {
+						type: "boolean",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderRead(value, maxResultBytes)
+			}]
+		},
+		execute(args, exec) {
+			const result = ctx.terminals.read(requireAgent(exec.agent), sessionId(args), {
+				...args.offset !== void 0 ? { offset: args.offset } : {},
+				...args.count !== void 0 ? { count: args.count } : {}
+			});
+			return Promise.resolve(result);
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `Read terminal ${args.sessionId}`,
+			kind: "read",
+			rawInput: args
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "terminal_signal",
+		description: "Send an allowed signal to the current foreground process group of a persistent terminal.",
+		parameters: {
+			sessionId: {
+				type: "string",
+				required: true,
+				description: "Terminal session id."
+			},
+			signal: {
+				type: "string",
+				required: true,
+				enum: [
+					"SIGINT",
+					"SIGTERM",
+					"SIGKILL",
+					"SIGTSTP",
+					"SIGHUP"
+				],
+				description: "Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close."
+			}
+		},
+		finalizeContent,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					delivered: {
+						type: "boolean",
+						required: true,
+						const: true
+					},
+					targetPgid: {
+						type: "integer",
+						required: true
+					}
+				}
+			},
+			render: (args, value) => [{
+				type: "text",
+				text: `delivered ${args.signal} to foreground process group ${value.targetPgid}`
+			}]
+		},
+		async execute(args, exec) {
+			return ctx.terminals.signal(requireAgent(exec.agent), sessionId(args), args.signal);
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `Signal terminal ${args.sessionId}`,
+			kind: "execute",
+			rawInput: args
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "terminal_close",
+		description: "Close one persistent terminal and wait until its captured owned process tree is gone.",
+		parameters: { sessionId: {
+			type: "string",
+			required: true,
+			description: "Terminal session id."
+		} },
+		finalizeContent,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					sessionId: {
+						type: "string",
+						required: true
+					},
+					outcome: {
+						type: "string",
+						required: true,
+						enum: ["closed", "already-closing"]
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.outcome === "closed" ? `closed terminal session ${value.sessionId}` : `terminal session ${value.sessionId} was already closing`
+			}]
+		},
+		async execute(args, exec) {
+			const id = sessionId(args);
+			return {
+				sessionId: id,
+				outcome: await ctx.terminals.kill(requireAgent(exec.agent), id) ? "closed" : "already-closing"
+			};
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `Close terminal ${args.sessionId}`,
+			kind: "delete"
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "terminal_list",
+		description: "List persistent terminal sessions owned by the current agent.",
+		parameters: {},
+		finalizeContent,
+		output: {
+			schema: {
+				type: "array",
+				items: SESSION_SNAPSHOT_SCHEMA
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderList(value, maxResultBytes)
+			}]
+		},
+		execute(_args, exec) {
+			return Promise.resolve(ctx.terminals.list(requireAgent(exec.agent)));
+		},
+		presentCall: () => ({
+			card: "generic",
+			title: "List terminal sessions",
+			kind: "read"
+		})
+	}));
+}
+//#endregion
+export { Config, DEFAULT_MAX_RESULT_BYTES, MIN_MAX_RESULT_BYTES, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-tool-terminal`.
+* @module @deepseek-ai/dsh-tool-terminal/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-terminal";
+/** Cordis companion plugin name. */
+const name = "tool-terminal-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this stateless adapter contributes tools and prompt guidance, while PTY
+* lifecycle and background-job relationships remain owned by the services it composes.
+*/
+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,32 @@
+/**
+ * Six model-facing persistent terminal tools. Owner identity comes from the exact
+ * tool execution Agent; generic `ctx.jobs` owns background ids and collection.
+ * @module @deepseek-ai/dsh-tool-terminal
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+declare module '@deepseek-ai/dsh-jobs' {
+    interface JobKindMap {
+        'pty-send': 'pty-send';
+    }
+}
+/** Cordis plugin name. */
+export declare const name = "tool-terminal";
+/** Required capability, registry, and prompt services. */
+export declare const inject: string[];
+/** Default cap for one complete model-facing terminal result. */
+export declare const DEFAULT_MAX_RESULT_BYTES: number;
+/** Smallest cap that preserves every counter-backed PTY and job id in its creation acknowledgement. */
+export declare const MIN_MAX_RESULT_BYTES = 64;
+/** Model-facing terminal tool configuration. */
+export interface Config {
+    /** Expose `run_in_background` and accept background sends (default true). */
+    enableRunInBackground?: boolean;
+    /** Maximum UTF-8 bytes in one complete terminal or task-output result. */
+    maxResultBytes?: number;
+}
+/** Schemastery configuration for the terminal tool consumer. */
+export declare const Config: z<Config>;
+/** Register all terminal tools and the minimal usage guidance. */
+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-terminal`.
+ * @module @deepseek-ai/dsh-tool-terminal/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-terminal-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/render.d.ts

@@ -0,0 +1,81 @@
+/** Model and UI rendering for persistent terminal tool results. */
+interface RenderedSessionStatusRunning {
+    kind: 'running';
+}
+interface RenderedSessionStatusExited {
+    kind: 'exited';
+    exitCode: number | null;
+    signal: string | null;
+}
+type RenderedSessionStatus = RenderedSessionStatusRunning | RenderedSessionStatusExited;
+interface RenderedSessionSnapshot {
+    sessionId: string;
+    name?: string;
+    type: string;
+    pid?: number;
+    status: RenderedSessionStatus;
+}
+interface RenderedSpawnResult extends RenderedSessionSnapshot {
+    motd: string;
+}
+interface RenderedSendResult {
+    viewport: string;
+    waitReason: 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit';
+    sessionStatus: RenderedSessionStatus;
+    truncated: boolean;
+}
+interface RenderedSendRead {
+    delta: string;
+    truncated: boolean;
+}
+interface RenderedReadResult {
+    text: string;
+    totalLines: number;
+    lineBegin: number;
+    lineEnd: number;
+    truncated: boolean;
+}
+/**
+ * Bound one complete terminal acknowledgement while preserving UTF-8 cuts.
+ * @param text - complete acknowledgement text.
+ * @param maxBytes - positive final result cap.
+ * @returns bounded text with a truncation marker when it fits.
+ */
+export declare function boundTerminalText(text: string, maxBytes: number): string;
+/**
+ * Render one created session and its bounded MOTD.
+ * @param result - published spawn result.
+ * @param maxBytes - complete UTF-8 result cap.
+ * @returns Model-facing session acknowledgement.
+ */
+export declare function renderSpawn(result: RenderedSpawnResult, maxBytes: number): string;
+/**
+ * Render one settled interactive send.
+ * @param result - settled send outcome.
+ * @param maxBytes - complete UTF-8 result cap.
+ * @returns Terminal output plus wait/session markers.
+ */
+export declare function renderSend(result: RenderedSendResult, maxBytes: number): string;
+/**
+ * Render one incremental background operation read.
+ * @param read - consuming operation delta.
+ * @returns Delta plus its upstream truncation marker. The generic task control
+ *   applies the producer's complete-result cap after adding job status.
+ */
+export declare function renderSendRead(read: RenderedSendRead): string;
+/**
+ * Render one bounded historical page.
+ * @param result - retained scrollback page.
+ * @param maxBytes - complete UTF-8 result cap.
+ * @returns Page text plus pagination and truncation markers.
+ */
+export declare function renderRead(result: RenderedReadResult, maxBytes: number): string;
+/**
+ * Render owner-visible live sessions.
+ * @param sessions - fresh owner-scoped snapshots.
+ * @param maxBytes - complete UTF-8 result cap.
+ * @returns One line per session or the empty marker.
+ */
+export declare function renderList(sessions: readonly RenderedSessionSnapshot[], maxBytes: number): string;
+export {};
+//# sourceMappingURL=render.d.ts.map

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@deepseek-ai/dsh-tool-terminal",
+  "description": "Six model-facing persistent PTY tools with owner isolation and generic background-job integration",
+  "version": "0.0.1-rc.5",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/terminal/tool-terminal"
+  },
+  "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",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.4"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-terminal": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-output-retention": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-jobs": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "^1.0.6-rc.4",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2-rc.4",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-terminal": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-terminal-bash": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-output-retention": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-subprocess-local": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-jobs": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-jobs-local": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-tool-jobs": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4"
+  }
+}