@qilin-agent/tool-bash-persistent 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,79 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/shell/tool-bash-persistent/README.md
+/:
+  en: 1516a333e77ca54a
+  zh: 53ef80da9cefd884
+/qilin-tool-bash-persistent:
+  en: 0b2f94e7a94335b6
+  zh: 0b95644899dbcdd7
+/qilin-tool-bash-persistent/summary:
+  en: c34db740c58468e2
+  zh: 712a34519dd66922
+/qilin-tool-bash-persistent/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-tool-bash-persistent/use-this-package:
+  en: ddec7cc1004498f8
+  zh: cd0cba22e570d1e9
+/qilin-tool-bash-persistent/use-this-package/when-to-choose-it:
+  en: c44e27f03b5bf48c
+  zh: a0bb453d130cf6ae
+/qilin-tool-bash-persistent/use-this-package/minimal-configuration:
+  en: 65386955f4a6a3a8
+  zh: 9fccd80dc540ab58
+/qilin-tool-bash-persistent/use-this-package/what-the-agent-can-rely-on:
+  en: b398f124ea7b77b0
+  zh: 50855e601e6c1b88
+/qilin-tool-bash-persistent/use-this-package/what-can-go-wrong:
+  en: d0d44ffa08f1a917
+  zh: ece228da0c0089aa
+/qilin-tool-bash-persistent/understand-the-implementation:
+  en: 8d94a7381bca3fa9
+  zh: f4bd2866fff6fa8d
+/qilin-tool-bash-persistent/understand-the-implementation/design-philosophy:
+  en: 61c39f52982612e3
+  zh: 92bc7e3c8d13a211
+/qilin-tool-bash-persistent/understand-the-implementation/source-map:
+  en: 857e036f41c913ac
+  zh: e9f383f7ee384c59
+/qilin-tool-bash-persistent/understand-the-implementation/command-flow:
+  en: 3b7bf7c20b266c31
+  zh: 85a325ef65fa7ac7
+/qilin-tool-bash-persistent/further-exploration:
+  en: 2f6547ad7a0e569c
+  zh: 2f9b5f19b3ebcc18
+/qilin-tool-bash-persistent/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-tool-bash-persistent/model-experience/tool-schema:
+  en: e4c7376d4f29dbd5
+  zh: 6b7a9eaf69c9ea53
+/qilin-tool-bash-persistent/model-experience/tool-schema/what-the-model-sees:
+  en: 17853846e6afc910
+  zh: 52805c18361c2650
+/qilin-tool-bash-persistent/model-experience/tool-schema/token-effect:
+  en: feee7dec91ae7329
+  zh: b62338fa72ad3b87
+/qilin-tool-bash-persistent/model-experience/tool-schema/kv-cache-effect:
+  en: 7d9323583a83cb95
+  zh: cc5daa6bce8450f8
+/qilin-tool-bash-persistent/model-experience/tool-results:
+  en: beaabb79f229692a
+  zh: 8573891441963be4
+/qilin-tool-bash-persistent/model-experience/tool-results/what-the-model-sees:
+  en: 7c197e9bb86cc044
+  zh: d8ffe918aab08250
+/qilin-tool-bash-persistent/model-experience/tool-results/token-effect:
+  en: 5dea04ce6a30ad48
+  zh: c2434253dc517d3d
+/qilin-tool-bash-persistent/model-experience/tool-results/kv-cache-effect:
+  en: ba6a48888c3361e5
+  zh: 3a8f648053555dc9
+/qilin-tool-bash-persistent/known-limitations-and-deferred-work:
+  en: dc5a908f2b2da040
+  zh: 3afceaabcf324771
+/qilin-tool-bash-persistent/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+---
+description: "The model-facing persistent bash tool for users and maintainers choosing, configuring, or debugging owner-scoped shell state that survives across calls."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/tool-bash-persistent
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This package gives an agent a `bash` tool whose cwd, exported variables, functions, and background jobs persist across calls. Each agent receives an isolated shell, and its commands run sequentially. Choose it for workflows that depend on cross-call state; use `qilin-tool-bash` when every command should start clean. Configure the PTY backend and per-command timeout; `exit`, timeout, or cancellation resets the shell, while interactive commands that wait for stdin may run until timeout.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Load this plugin in any composition where the agent should keep shell state between commands — for example long build sessions, activated environments, or scripts that export variables for later steps. It registers the `bash` tool and requires the `ctx.tools` and `ctx.terminals` services plus an owning agent session at execution time.
+
+### When to choose it
+
+Choose the persistent tool when work depends on cross-call state: a one-shot `qilin-tool-bash` call cannot remember a `cd` or an exported variable. Choose the one-shot tool when every command should start from a known, clean environment, or when the command is short and self-contained. Commands that need interactive stdin are unsupported here — a foreground child that reads input blocks until the command timeout — so interactive work belongs to the terminal tools.
+
+### Minimal configuration
+
+The default `shell` backend starts an interactive bash through `qilin-terminal-bash`; deployments may register another PTY backend and select it by name.
+
+```yaml
+- name: '@qilin-agent/terminal'
+- name: '@qilin-agent/terminal-bash'
+- name: '@qilin-agent/tool-bash-persistent'
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `backendType` | `shell` | Registered PTY backend used for each agent's shell |
+| `timeoutMs` | `300,000` | Wall-clock limit for one command; timeout closes the shell |
+| `maxOutputChars` | `16,000` | Maximum retained command-output characters; fixed diagnostics are added afterward |
+| `description` | `Run commands in a persistent bash shell. State, including the current directory and exported environment variables, persists across calls for this agent.` | Model-facing environment contract; deployments may describe their environment |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#qilin-agenttool-bash-persistent) is the exhaustive source for every accepted field and its JSDoc.
+
+### What the agent can rely on
+
+Commands share one shell per agent, so state persists until an `exit`, a timeout, or a reset — each of which closes the shell and tells the agent the next call starts from the workspace with a fresh directory and environment. Results exclude the private completion markers; every settled command appends `[Command finished with exit code N]`, and a shell that exits before reporting that status instead appends `[shell exited: code N]`, `[shell killed by signal: SIG]`, or `[shell exited]`, then resets. Long output keeps the earliest retained prefix plus a clipping notice; if the terminal has already dropped that prefix, the result says so explicitly rather than presenting a tail as complete output.
+
+### What can go wrong
+
+A call without an owning agent session fails with `bash requires an owning agent session`, and a composition without a PTY backend activates the tool but fails its first call with `no PTY backend registered for "shell"`. An interactive foreground child (for example a REPL) returns early with partial output only where the backend proves its stdin wait; elsewhere the call runs to `timeoutMs`, which closes the uncertain shell and reports the reset. Cancellation also resets and discards the result, even when a complete status marker is already observable.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the tool and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+- **One shell per owner, nothing shared.** The shell registry keys every session by the calling `Agent`, so concurrent agents never share state, and commands for the same agent are serialized through a per-owner queue.
+- **Marker-anchored extraction.** Each command is wrapped with unique start/end markers carrying the exit status; the tool polls the PTY scrollback and extracts the span between the real markers, so prompts and echoed input never leak into results.
+- **Reset, never repair.** Any uncertain state — an explicit `exit`, a timeout, a send failure, an abort — closes the shell and starts the next call fresh, because a half-known shell is worse than a clean one.
+- **Owner-scoped lifecycle.** Shells are created lazily on first use and killed on plugin disposal or owner teardown; the owner-scoped `ctx.terminals` service fences every operation to the owning agent.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: shell registry, command wrapping, scrollback polling, extraction and rendering |
+
+### Command flow
+
+A first command spawns the shell through `ctx.terminals.spawn`, disables input echo (`stty -echo`), and waits for readiness. Each command is then wrapped into one physical line — a printf of the start marker, the command body escaped with `$'…'`, and a printf of the end marker plus `$?` — so embedded newlines cannot leak terminal prompts into the result. The tool polls the scrollback in 1,000-line pages until the end marker appears, extracts the span, and renders it with any status marker. A timeout aborts the deadline, captures the partial output, and resets the shell.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the terminal family to the seam, the backends, and the design note behind owner-scoped sessions.
+
+- [terminal package map](../../terminal/README.md) — the persistent PTY capability family.
+- [terminal seam](../../terminal/terminal/README.md) — the `ctx.terminals` service behind the tool.
+- [terminal-bash backend](../../terminal/terminal-bash/README.md) — the default `shell` backend.
+- [tool-terminal](../../terminal/tool-terminal/README.md) — six model-facing terminal tools for interactive work.
+- [Persistent PTY sessions Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) — the owner-scoped session design and its rationale.
+- [Generated tool catalog](../../../docs/tool-catalog.md#qilin-agenttool-bash-persistent) — the exact `bash` argument schema.
+- [Generated configuration catalog](../../../docs/config-catalog.md#qilin-agenttool-bash-persistent) — every accepted config field and its source declaration.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The generated [`bash` schema](../../../docs/tool-catalog.md#qilin-agenttool-bash-persistent), including the configured `description`. The plugin contributes no standalone system-prompt section; the deployment owns persona and environment guidance.
+
+#### Token effect
+
+Fixed schema cost while `bash` is visible.
+
+#### KV Cache effect
+
+Prefix-stable while the configured description and schema remain unchanged.
+
+### Tool results
+
+#### What the model sees
+
+Commands share one shell per agent, so cwd, exported variables, activated environments, functions, and background jobs persist across calls. Results exclude private completion markers. When the shell reads stdin again without having printed the completion marker — after `exec`, an interrupt, or an interactive foreground child whose stdin wait the provider proves — the call returns the captured partial output, which can end with the backend's own prompt text. Every settled command appends `[Command finished with exit code N]`; a shell that exits before reporting that status instead appends `[shell exited: code N]`, `[shell killed by signal: SIG]`, or `[shell exited]` when the backend supplies neither, then resets and tells the model that the next call starts fresh. Long output keeps the earliest retained prefix plus a clipping notice. If the PTY has already dropped that prefix, the result says so explicitly instead of presenting a tail as complete output. Timeout returns bounded partial output followed by `[Command timed out or OOM]`, closes the uncertain shell, and reports the reset.
+
+#### Token effect
+
+Data-dependent. `maxOutputChars` bounds retained command output; fixed clipping, lost-prefix, status, timeout, and reset diagnostics can extend the result.
+
+#### KV Cache effect
+
+Append-only tool results follow the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the tool is a poor fit or needs special care. They are current package constraints, not a task backlog.
+
+- **The tool requires an owning agent and a real PTY backend** — agent-less calls and backends that cannot start an interactive shell fail.
+- **An interactive foreground child returns early with partial output only where the subprocess provider proves its stdin wait** — elsewhere the call runs to `timeoutMs`.
+- **Explicit `exit` and timeout discard shell state** — cancellation also resets and discards the result, even when a complete status marker is already observable; the next call starts a fresh shell.
+- **Environment facts such as network access and package mirrors belong in the configured `description`** — not this package's default.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,158 @@
+---
+description: "面向模型的持久 bash 工具，供选择、配置或排查跨调用保留的按所有者隔离 shell 状态的使用者与维护者阅读。"
+kind: "package-reference"
+---
+
+# @qilin-agent/tool-bash-persistent
+
+[English](README.md) | 中文
+
+## 概述
+
+本包为 agent（智能体）提供 `bash` 工具，使 cwd、导出的变量、函数与后台任务跨调用保留。每个 agent 都有隔离的 shell，其命令串行执行。需要跨调用状态的工作流应选择本包；每条命令都应从干净环境开始时使用 `qilin-tool-bash`。配置 PTY 后端与单条命令的超时；`exit`、超时或取消会重置 shell，而等待 stdin 的交互式命令可能一直运行到超时。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在 agent 需要在命令之间保持 shell 状态的任何组合中加载本插件——例如长时间构建会话、已激活的环境，或为后续步骤导出变量的脚本。它注册 `bash` 工具，需要 `ctx.tools` 与 `ctx.terminals` 服务，并在执行时需要拥有者 agent 会话。
+
+### 何时选择
+
+当工作依赖跨调用状态时选择持久工具：一次性 `qilin-tool-bash` 调用无法记住 `cd` 或导出的变量。当每条命令都应从已知、干净的环境开始，或命令又短又独立时，选择一次性工具。这里不支持需要交互 stdin 的命令——读取输入的前台子进程会一直阻塞到命令超时——因此交互工作属于 terminal 工具。
+
+### 最小配置
+
+默认的 `shell` 后端通过 `qilin-terminal-bash` 启动交互式 bash；部署方可以注册其他 PTY 后端并按名称选择。
+
+```yaml
+- name: '@qilin-agent/terminal'
+- name: '@qilin-agent/terminal-bash'
+- name: '@qilin-agent/tool-bash-persistent'
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `backendType` | `shell` | 用于每个 agent shell 的已注册 PTY 后端 |
+| `timeoutMs` | `300,000` | 单条命令的墙钟上限；超时关闭 shell |
+| `maxOutputChars` | `16,000` | 保留的命令输出字符上限；固定诊断信息在其后追加 |
+| `description` | `Run commands in a persistent bash shell. State, including the current directory and exported environment variables, persists across calls for this agent.` | 面向模型的环境约定；部署方可描述自己的环境 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#qilin-agenttool-bash-persistent)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+### agent 可以依赖什么
+
+命令共享每个 agent 一个 shell，因此状态一直保留到 `exit`、超时或重置——每一种都会关闭 shell 并告诉 agent 下一次调用从工作区的新目录与环境开始。结果排除私有完成标记；每条完成的命令都追加 `[Command finished with exit code N]`，而在报告该状态前就退出的 shell 改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]` 或 `[shell exited]`，然后重置。长输出保留最早的已保留前缀并附裁剪通知；若 terminal 已经丢弃该前缀，结果会明确说明，而不是把尾部当作完整输出呈现。
+
+### 可能出什么问题
+
+没有拥有者 agent 会话的调用会以 `bash requires an owning agent session` 失败，没有 PTY 后端的组合会激活该工具，但首次调用以 `no PTY backend registered for "shell"` 失败。交互式前台子进程（例如 REPL）只有在后端证明其 stdin 等待时才提前返回部分输出；否则调用一直运行到 `timeoutMs`，随后关闭不确定的 shell 并报告重置。取消也会重置并丢弃结果，即使完整状态标记已经可观察。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释工具背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+- **每个 owner 一个 shell，互不共享。** shell 注册表按调用方 `Agent` 为每个会话建键，因此并发 agent 永不共享状态，同一 agent 的命令通过按 owner 的队列串行化。
+- **标记锚定提取。** 每条命令都用携带退出状态的唯一起止标记包装；工具轮询 PTY scrollback 并提取真实标记之间的区间，因此提示符与回显输入永不泄漏进结果。
+- **重置，而非修复。** 任何不确定状态——显式 `exit`、超时、发送失败、中止——都会关闭 shell 并让下一次调用从全新状态开始，因为半知情的 shell 不如干净的 shell。
+- **按 owner 的生命周期。** shell 在首次使用时惰性创建，在插件释放或 owner 拆除时终止；按所有者隔离的 `ctx.terminals` 服务把每个操作都围栏到拥有它的 agent。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：shell 注册表、命令包装、scrollback 轮询、提取与渲染 |
+
+### 命令流程
+
+首条命令通过 `ctx.terminals.spawn` 生成 shell，禁用输入回显（`stty -echo`），并等待就绪。随后每条命令都包装成一行物理文本——printf 起始标记、用 `$'…'` 转义的命令体、printf 结束标记加 `$?`——因此内嵌换行无法把终端提示符泄漏进结果。工具以 1,000 行一页轮询 scrollback，直到出现结束标记，提取区间并连同任何状态标记一起渲染。超时会中止截止时间、捕获部分输出并重置 shell。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从 terminal 家族逐步进入 seam、后端，以及按所有者会话背后的设计笔记。
+
+- [terminal 包映射](../../terminal/README.zh.md)——持久 PTY 能力家族。
+- [terminal seam](../../terminal/terminal/README.zh.md)——工具背后的 `ctx.terminals` 服务。
+- [terminal-bash 后端](../../terminal/terminal-bash/README.zh.md)——默认的 `shell` 后端。
+- [tool-terminal](../../terminal/tool-terminal/README.zh.md)——面向交互工作的六个模型侧 terminal 工具。
+- [持久 PTY 会话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md)——按所有者会话的设计及其理由。
+- [生成的工具目录](../../../docs/tool-catalog.zh.md#qilin-agenttool-bash-persistent)——`bash` 参数 schema 的确切内容。
+- [生成的配置目录](../../../docs/config-catalog.zh.md#qilin-agenttool-bash-persistent)——每个受支持配置字段及其源声明。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 工具 schema
+
+#### 模型看到什么
+
+生成的 [`bash` schema](../../../docs/tool-catalog.zh.md#qilin-agenttool-bash-persistent)，包括配置的 `description`。本插件不贡献独立的系统提示词区段；人设与环境指引由部署方负责。
+
+#### Token 影响
+
+`bash` 可见期间产生固定 schema 开销。
+
+#### KV Cache 影响
+
+只要配置的描述与 schema 不变，前缀就保持稳定。
+
+### 工具结果
+
+#### 模型看到什么
+
+命令共享每个 agent 一个 shell，因此 cwd、导出的变量、已激活的环境、函数与后台任务都会跨调用保留。结果排除私有完成标记。当 shell 在没有打印完成标记的情况下再次读取 stdin——`exec`、中断，或提供方证明其 stdin 等待的交互式前台子进程之后——调用返回捕获的部分输出，它可能以后端自己的提示符文本结尾。每条完成的命令都追加 `[Command finished with exit code N]`；在报告该状态前就退出的 shell 改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]`，或后端两者都未提供时的 `[shell exited]`，然后重置并告诉模型下一次调用从全新状态开始。长输出保留最早的已保留前缀并附裁剪通知。若 PTY 已经丢弃该前缀，结果会明确说明，而不是把尾部当作完整输出呈现。超时返回有界部分输出并追加 `[Command timed out or OOM]`、关闭不确定的 shell 并报告重置。
+
+#### Token 影响
+
+依数据而定。`maxOutputChars` 限制保留的命令输出；固定的裁剪、丢失前缀、状态、超时与重置诊断可能延长结果。
+
+#### KV Cache 影响
+
+仅追加的工具结果位于可复用请求前缀之后。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明工具何时不合适或需要特别小心。它们是当前包约束，不是任务积压。
+
+- **工具需要拥有者 agent 与真实的 PTY 后端**——无 agent 的调用与无法启动交互 shell 的后端都会失败。
+- **交互式前台子进程只在子进程提供方证明其 stdin 等待时才提前返回部分输出**——否则调用一直运行到 `timeoutMs`。
+- **显式 `exit` 与超时会丢弃 shell 状态**——取消同样重置并丢弃结果，即使完整状态标记已经可观察；下一次调用启动全新 shell。
+- **网络访问与包镜像等环境事实属于配置的 `description`**——而不是本包的默认描述。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

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

package/lib/types/index.d.ts

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

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@qilin-agent/tool-bash-persistent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Model-facing owner-scoped persistent Bash tool backed by the Harness PTY service",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/shell/tool-bash-persistent"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/timeout": "3.1.3",
+    "@qilin-agent/tools": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/terminal": "3.1.3"
+  },
+  "dependencies": {
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin-plugin-include": "~1.0.8",
+    "@qilin-agent/kylin-plugin-loader": "~1.0.4",
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/agent-loop-testkit": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/terminal": "3.1.3",
+    "@qilin-agent/terminal-bash": "3.1.3",
+    "@qilin-agent/sandbox": "3.1.3",
+    "@qilin-agent/sandbox-policy": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/system-prompt": "3.1.3",
+    "@qilin-agent/subprocess-local": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/timeout": "3.1.3",
+    "@qilin-agent/session-projection": "3.1.3",
+    "@qilin-agent/tools": "3.1.3"
+  }
 }