{"_id":"@buddhilive/dsh-tool-terminal","name":"@buddhilive/dsh-tool-terminal","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-tool-terminal","description":"Six model-facing persistent PTY tools with owner isolation and generic background-job integration","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-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"},"license":"MIT","dependencies":{"@deepseek-ai/schemastery":"^3.18.2"},"peerDependencies":{"@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-terminal":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-output-retention":"^0.1.2-alpha.3","@buddhilive/dsh-system-prompt":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-jobs":"^0.1.2-alpha.3"},"devDependencies":{"@deepseek-ai/cordis-plugin-include":"^1.0.7","@deepseek-ai/cordis-plugin-loader":"^1.0.3","@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-terminal-bash":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-terminal":"^0.1.2-alpha.3","@buddhilive/dsh-output-retention":"^0.1.2-alpha.3","@buddhilive/dsh-sandbox":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-sandbox-policy":"^0.1.2-alpha.3","@buddhilive/dsh-subprocess-local":"^0.1.2-alpha.3","@buddhilive/dsh-system-prompt":"^0.1.2-alpha.3","@buddhilive/dsh-jobs":"^0.1.2-alpha.3","@buddhilive/dsh-jobs-local":"^0.1.2-alpha.3","@buddhilive/dsh-tool-jobs":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-tool-terminal@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-YlIzO1Poyg9Xpg4M45AP/1hlT40knviqK8LMfJw1YvyaJsI0dXEUzMMHDXr85JO//o/hNC5KvaX1GVoUCt8JSA==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-tool-terminal-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-tool-terminal-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-YlIzO1Poyg9Xpg4M45AP/1hlT40knviqK8LMfJw1YvyaJsI0dXEUzMMHDXr85JO//o/hNC5KvaX1GVoUCt8JSA==","shasum":"8ecc9dbe083de27583a7d3333626bdfd9d121ff5","tarball":"https://registry.npmjs.org/@buddhilive/dsh-tool-terminal/-/dsh-tool-terminal-0.1.2-alpha.3.tgz","fileCount":10,"unpackedSize":46664,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCwcF7gbwQZSUR1RTsq9m3GfHVTJnHTki3Xl3XvsX8R5QIgeuwHFiHLhJ15CXiBs9kB8wVUq3jjHJr1f2YNtmAjwrs="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-tool-terminal_0.1.2-alpha.3_1788166786914_0.04350800459103232"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:59:46.751Z","0.1.2-alpha.3":"2026-08-31T08:59:47.041Z","modified":"2026-08-31T08:59:47.290Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Six model-facing persistent PTY tools with owner isolation and generic background-job integration","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/terminal/tool-terminal"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"面向需要跨调用终端状态的 agent 的 6 个持久终端工具，带所有者隔离、有界结果与可选后台发送。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-tool-terminal\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-tool-terminal` 基于持久终端会话为模型提供 6 个工具：`terminal_open`、`terminal_send`、`terminal_read`、`terminal_signal`、`terminal_close` 与 `terminal_list`。每次调用都被限制在打开该会话的那个确切 agent（智能体）内，因此即使模型获知另一个 agent 的 id，也无法操作其终端。发送可以前台运行（返回带等待原因的有界输出），也可以通过任务服务后台运行（返回 job id，用 `job_output` 收集、用 `job_kill` 停止）。结果受 `maxResultBytes` 限制，并保留在会话历史中直到压缩（compaction）。一段简短指引会告诉模型：除非确实需要终端的持久状态或交互式 stdin，否则优先使用单次工具。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n当组合挂载了终端后端、且模型应当能跨调用使用终端状态时启用这些工具——逐步调试 gdb、在 REPL 中探索，或中断前台命令后回到 shell。指引章节会引导模型对确有界操作使用单次 bash、read、write 与 edit 工具。\n\n### 六个工具\n\n| 工具 | 作用 | 结果 |\n|---|---|---|\n| `terminal_open` | 按后端类型创建限定所有者范围的会话 | 会话 id、名称、类型、pid、状态与有界启动输出 |\n| `terminal_send` | 写入文本，可选地提交 Enter，并等待就绪——或启动后台任务 | 有界输出加等待与会话状态，或一个 job id |\n| `terminal_read` | 不发送输入，读取一页有界保留输出 | 带行分页元数据的文本 |\n| `terminal_signal` | 向前台进程组投递一个允许的信号 | `delivered` 加目标进程组 id |\n| `terminal_close` | 关闭会话并等待其进程树结束 | 已关闭或正在关闭的结果 |\n| `terminal_list` | 列出调用方的活跃会话 | 限定所有者范围的会话摘要 |\n\n### 组合方式\n\n```yaml\n- name: '@buddhilive/dsh-terminal'\n- name: '@buddhilive/dsh-terminal-bash'\n- name: '@buddhilive/dsh-tool-terminal'\n```\n\n工具需要 `ctx.terminals`——必须挂载一个后端——以及用于指引章节的系统提示词服务。后台发送还额外要求任务服务及其面向模型的控制器（`@buddhilive/dsh-tool-jobs`）。\n\n### 配置\n\n| 字段 | 默认值 | 含义 |\n|---|---|---|\n| `enableRunInBackground` | `true` | 公开并接受 `run_in_background`；设为 `false` 时移除 schema 字段并拒绝该参数 |\n| `maxResultBytes` | `262144` | 每个完整终端结果的 UTF-8 上限（最小值 `64`）；在等待、会话、分页、截断与任务状态元数据全部加入后计算 |\n\n生成的[配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-tool-terminal)与[工具目录](../../../docs/tool-catalog.zh.md#buddhilivedsh-tool-terminal)是配置字段与 schema 的穷尽式真源。\n\n### 后台发送\n\n`terminal_send(run_in_background: true)` 立即返回 job id，而不是等待。任务用 `job_output` 收集——它会等待并读取增量输出——用 `job_kill` 停止，后者向前台进程组投递真正的 `SIGINT`。缺少任务接口面时，后台模式会在写入输入之前失败。\n\n### 可观察结果与失败\n\n前台发送返回终端的新输出以及 `wait: <原因>` 与会话状态；`session_exit` 表示顶层 shell 已退出，而 `inferred_idle` 或 `timeout` 绝不证明前台命令已退出。用未注册的后端类型打开会话会失败。大于 `maxResultBytes` 的结果会在 UTF-8 边界处截断并附标记。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释工具背后的设计并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中说明。\n\n### 设计理念\n\n本包是薄适配层：6 个工具以执行 agent 作为所有者转发到 `ctx.terminals`，呈现层渲染有界结果。后台发送把在途操作注册到 `ctx.jobs`，由通用任务接口面负责等待、增量读取与 `SIGINT` 投递。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 6 个工具定义、schema、指引章节、后台任务集成 |\n| [`src/render.ts`](src/render.ts) | 结果渲染与完整结果的 UTF-8 上限 |\n\n### 结果上限\n\n每个终端自身的单文本结果都会在规范化后的工具或流水线错误、策略拒绝与短路、替换与阻止、以及通用任务状态文本之后，受 `maxResultBytes` 限制；截断保留 UTF-8 边界并为截断标记预留空间。结构化的多块策略结果保留其结构。64 字节的最小上限保证注册表签发的每个会话或 job id 都出现在创建确认中。\n\n### UI 呈现意图\n\n前台发送使用终端调用与结果卡片；后台发送与其他 5 个工具使用通用 `execute`、`read` 或 `delete` 卡片。所有工具都不输出源位置。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面。它们从生成的 schema 进入服务约定、后端与后台任务接口面。\n\n- [工具目录](../../../docs/tool-catalog.zh.md#buddhilivedsh-tool-terminal)——6 个生成的 schema 与结果形态。\n- [终端子系统参考](../../../docs/subsystems/terminal.zh.md)——工具背后的服务约定与共享类型。\n- [terminal 服务](../terminal/README.zh.md)——会话操作、所有者限制与清理语义。\n- [terminal-bash 后端](../terminal-bash/README.zh.md)——提供会话的随附 shell 后端。\n- [jobs 包映射](../../jobs/README.zh.md)——收集与停止后台发送的后台任务接口面。\n- [持久 PTY Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md)——能力设计与暂缓边界。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n### 系统提示词\n\n#### 模型看到什么\n\n该插件贡献以下固定指引章节：\n\n##### 终端指引\n\n```markdown\nUse 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.\n```\n\n#### Token 影响\n\n插件活跃期间，每次请求都会产生少量固定输入成本。\n\n#### KV Cache 影响\n\n注册范围与指引文本不变时，前缀保持稳定。\n\n### 工具 schema\n\n#### 模型看到什么\n\n6 个生成的 schema 列在 [`dsh-tool-terminal` 目录章节](../../../docs/tool-catalog.zh.md#buddhilivedsh-tool-terminal)中。此插件活跃时，请求中会包含它们的固定 schema token；按 agent 范围过滤工具时可能隐藏这些 schema。\n\n#### Token 影响\n\n工具可见的请求会产生固定的 schema 成本。\n\n#### KV Cache 影响\n\n工具可见性与定义不变时，前缀保持稳定。\n\n### 工具结果与任务上下文\n\n#### 模型看到什么\n\nspawn 返回 id 与有界启动输出。发送与读取返回有界终端文本以及就绪与历史标记。后台模式返回通用 job id。每个终端自身的单文本结果都受 `maxResultBytes` 限制；结果保留在会话历史中直到压缩，增量任务读取不会重复已经消费的输出。\n\n#### Token 影响\n\n终端自身的结果随数据变化，并受 `maxResultBytes` 限制；每个返回结果都保留在历史中直到压缩。\n\n#### KV Cache 影响\n\n仅追加；新结果位于可复用请求前缀之后。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明缺失的面向模型接口面。它们是当前包约束，不是任务积压。\n\n- **没有 TUI 或按键序列接口面**——具名按键序列、全屏 TUI 交互、BEL、调整大小与自动启动均未出现在任何 schema 中。\n- **后台模式要求任务接口面**——`run_in_background` 同时需要 `@buddhilive/dsh-jobs` 及其面向模型的控制器（`@buddhilive/dsh-tool-jobs`）；缺少时会拒绝该参数。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-f8dce954e3a55df044a7e1e18b366cd7"}