{"_id":"@buckeyestudio/toh-tool-pwsh-persistent","name":"@buckeyestudio/toh-tool-pwsh-persistent","dist-tags":{"next":"0.1.1-rc.2","latest":"0.1.1-rc.2"},"versions":{"0.1.1-rc.2":{"name":"@buckeyestudio/toh-tool-pwsh-persistent","description":"Model-facing owner-scoped persistent PowerShell tool backed by the Harness PTY service","version":"0.1.1-rc.2","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/shell/tool-pwsh-persistent"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./package.json":"./package.json"},"license":"MIT","author":{"name":"buckeyestudio"},"peerDependencies":{"@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-timeout":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/toh-terminal":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"dependencies":{"@buckeyestudio/schemastery":"^3.18.1"},"devDependencies":{"@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/cordis-plugin-loader":"^1.0.2","@buckeyestudio/cordis-plugin-include":"^1.0.6","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-terminal-bash":"^0.1.1-rc.2","@buckeyestudio/toh-terminal":"^0.1.1-rc.2","@buckeyestudio/toh-pwsh-local":"^0.1.1-rc.2","@buckeyestudio/toh-sandbox":"^0.1.1-rc.2","@buckeyestudio/toh-sandbox-policy":"^0.1.1-rc.2","@buckeyestudio/toh-session":"^0.1.1-rc.2","@buckeyestudio/toh-subprocess-local":"^0.1.1-rc.2","@buckeyestudio/toh-system-prompt":"^0.1.1-rc.2","@buckeyestudio/toh-timeout":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"_id":"@buckeyestudio/toh-tool-pwsh-persistent@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-GT8UD5qiD+vOLXWE+RO6ZGosfs9IWOE1V5lf8qKIxYPal0SNZRYwfX5ByGPyhe9HAOf4ALHXa/wTAerIL+j7oQ==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-tool-pwsh-persistent-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-tool-pwsh-persistent-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-GT8UD5qiD+vOLXWE+RO6ZGosfs9IWOE1V5lf8qKIxYPal0SNZRYwfX5ByGPyhe9HAOf4ALHXa/wTAerIL+j7oQ==","shasum":"fabd4538df80b94c1ca5c8d5a42a206bbc3833a3","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-tool-pwsh-persistent/-/toh-tool-pwsh-persistent-0.1.1-rc.2.tgz","fileCount":9,"unpackedSize":32152,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBvJbZgmCsAGBkAGgxcBrJJvsoR0eikrJ3FPlpe3l5N1AiEA+f2JapEcJ3mRjMrryayIPDx2+1w3SgtqdZPL5+Gzves="}]},"_npmUser":{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"},"directories":{},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/toh-tool-pwsh-persistent_0.1.1-rc.2_1787489573937_0.8020670863194237"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:52:53.807Z","0.1.1-rc.2":"2026-08-23T12:52:54.076Z","modified":"2026-08-23T12:52:54.276Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"Model-facing owner-scoped persistent PowerShell tool backed by the Harness PTY service","homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/shell/tool-pwsh-persistent"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# @buckeyestudio/toh-tool-pwsh-persistent\n\n[English](README.md) | 中文\n\n模型侧 `pwsh(command)`，由一个 owner 作用域的 `ctx.terminals` shell 支撑。本包拥有工具契约与 shell 复用；部署方选择 terminal backend（配置 `shellDialect: pwsh` 的 `terminal-bash` 实例）与沙箱策略。它是 `tool-bash-persistent` 的 Windows 对应物：相同的持久状态契约，PowerShell 方言。\n\n## 配置\n\n| 键 | 默认值 | 含义 |\n|---|---:|---|\n| `backendType` | `shell` | 每个 Agent shell 使用的已注册 terminal backend。 |\n| `timeoutMs` | `300000` | 单条命令的墙钟上限；超时关闭 shell。 |\n| `maxOutputChars` | `16000` | 保留的命令输出字符上限；固定诊断文本在其后追加。 |\n| `description` | 持久 shell 描述 | 模型可见的环境契约。 |\n\n## 模型体验\n\n### 工具 schema\n\n#### 模型看到什么\n\n生成的 [`pwsh` schema](../../../docs/tool-catalog.zh.md#buckeyestudiotoh-tool-pwsh-persistent)，含配置的 `description`。本插件不贡献独立的 system-prompt 段落；persona 与环境指引由部署方负责。\n\n#### Token 影响\n\n`pwsh` 可见期间每个请求有固定的 schema 成本。\n\n#### KV Cache 影响\n\n配置的 description 与 schema 不变时前缀稳定。\n\n### 工具结果\n\n#### 模型看到什么\n\n命令共享每个 Agent 的一个 shell，因此 cwd、`$env:` 变量、函数和后台任务跨调用保留。结果排除私有完成标记、shell 提示符与回显的输入行（PSReadLine 会把提交的输入渲染回输出流；marker 锚定提取与包装器原文剥离将其移除）。非零包装命令追加 `[exit code: N]` —— 命令运行原生程序时是精确的原生退出码，PowerShell 终止性错误为 `1`。shell 在报告状态前退出的，改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]` 或 `[shell exited]`（backend 两者都没有时；Windows 强杀按无 signal 的 exit 1 报告），然后重置并告知模型下一次调用从全新 shell 开始。长输出保留最早的前缀并附裁剪提示；若 PTY 已丢弃该前缀，结果会明确说明。超时返回有界的部分输出、关闭不确定的 shell 并报告重置。\n\n#### Token 影响\n\n数据相关。`maxOutputChars` 限制保留的命令输出；固定裁剪、前缀丢失、状态、超时与重置诊断可能扩展结果。\n\n#### KV Cache 影响\n\n追加式工具结果跟随可复用的请求前缀。\n\n## 已知限制与延后工作\n\n- 工具需要拥有 Agent 与一个真实支持 pwsh 方言的 terminal backend（Windows ConPTY 或 POSIX 上的 pwsh）。\n- **输入回显不可避免**：PowerShell 的 PSReadLine 会把提交的输入渲染回终端流，且没有 `stty -echo` 的对应物。完整结果中 marker 锚定提取排除回显；包装器原文剥离覆盖回退路径，但跨越终端宽度的包装器折行可能在部分输出结果中残留片段回显，受 `maxOutputChars` 约束。\n- 模型命令中的裸 ESC 字符不受支持：PSReadLine 会在执行前吞掉它们。包装器转义它需要的控制字节（`[char]27` 构造的 OSC 标记、body 的反引号转义）。\n- 模型重定义 `prompt` 函数会移除就绪标记；shell 随后退化为静默档而非 marker 快路径。\n- 命令执行期间没有交互 stdin：读取输入的前台命令会阻塞到就绪超时，随后重置 shell。\n- SIGTSTP/SIGHUP 在 Windows 不可用（backend 拒绝）；SIGINT 以控制台级 Ctrl-C 输入写入投递，在提示符处取消当前行而非向进程发信号。\n- 在 Windows ACL 沙箱的只读模式下，pwsh 以 ConstrainedLanguage 启动，可能拒绝引导代码通过 `[Console]::` 固定编码并写入 prompt marker。命令仍可通过可打印提示符和静默档结算，但非 ASCII 输出可能沿用宿主代码页。\n- BEL 终结的 OSC 标记仍只是就绪信号；面向模型的 BEL 事件通道保持延后，与当前实现对齐。\n","readmeFilename":"README.zh.md","_rev":"1-31da9d8301209f4fa09bc139b35155ad"}