@spinejit/pi-timeout-policy0.4.0

pi-timeout-policy

English | 简体中文

为 Pi 的前台工具提供统一的超时策略。在 Pi 1.3 和 1.4 中，bash 的超时参数是可选的且没有默认值，grep 和 find 则完全没有超时参数，任何一条卡住的命令都会让 agent 无限期等待。安装本插件后：

未指定超时：60 秒。需要运行更久的命令：显式指定超时，上限 7200 秒（2 小时）。 当前回合不需要输出的命令：放进后台任务执行。需要比 Pi 存活更久的任务：交给 systemd 或 tmux。

bash(command="rg foo .")                     -> 60s
bash(command="cargo test", timeout=1800)    -> 1800s
bash(command="sleep 1", timeout=7201)       -> 拒绝
grep(pattern="foo", path=".")               -> 60s
grep(pattern="foo", path=".", timeout=600) -> 600s

为什么这样设计

• 只加超时策略，不替换 bash。 插件不替换内置的 bash，只在现有负责前台执行的工具之上叠加超时规则，因此 shell 设置、自定义渲染器、spawn 钩子和其他 bash 扩展都能照常工作。
• 每次前台等待都有上限。 前台调用不再允许无限超时。耗时较长的工作，要么显式申请不超过 2 小时的时间预算，要么通过 pi-background-job 放到后台执行。
• 模型直接看到规则。 工具 schema 中明确写出默认值和上限，超出范围的参数在执行前就会被 schema 校验直接拒绝。

特性

• bash 和 powershell：未传超时参数时默认设为 60 秒；显式传入的值必须在 (0, 7200] 区间内。
• grep 和 find：新增遵循同一规则的 timeout 参数。
• 安装本包不会开启 grep 或 find，当前启用的工具集合保持不变。
• 会话结束时自动还原对 schema 的修改，且仅还原仍保持本插件写入值的字段。

安装

pi install npm:@spinejit/pi-timeout-policy

Pi 已经在运行的话，重启它或执行 /reload。

不安装，仅在当前会话中试用：

pi -e npm:@spinejit/pi-timeout-policy

原理

Pi 没有提供原地包装某个工具当前实现的接口，因此覆盖层（overlay）针对两类工具采用不同的适配方式：

• 原生超时对齐（bash、powershell）：Pi 原生已提供 timeout 参数。session_start 时，插件将实时 schema 对齐到本策略：单位为秒，范围 0 < timeout <= 7200，并在参数描述中注明运行时默认 60 秒。session_shutdown 时，仅恢复仍保持本插件写入值的字段，既不会让后续会话继承这次修改，也不会覆盖第三方扩展对 schema 的改动。调用时若未传超时，由 tool_call 钩子自动补上 60；超出 (0, 7200] 的值在钩子执行前即被 schema 校验拒绝。实际执行仍由原来的工具实现负责，shell 设置、渲染器、spawn 钩子和其他 bash 扩展均不受影响。
• 信号包装（grep、find）：原生 schema 没有超时字段。session_start 时，覆盖层为其加上 timeout?: number，底层委托给 Pi 公开的工具工厂函数，让原实现的完成与截止时间赛跑。到达截止时间后立即让调用方返回，同时通过截止时触发的 AbortSignal 通知原实现终止子进程并完成清理。由于底层清理是协作式的而非强制杀进程，原实现可能在后台稍晚才彻底结束。注册发生在默认启用工具集确定之后，并立即恢复原有的启用集合，因此安装本包不会自动开启 grep/find。

合法范围内的显式正数超时会原样保留。上层传入的取消信号仍按取消处理，不会被当成超时。

前台超时的上限为 7200 秒（2 小时）；Node 定时器的上限（约 24.8 天）不能作为合理的等待预算。timeout <= 0 一律视为无效参数。

限制

• Pi 中同名的扩展工具遵循先注册者生效原则。若没有更早的扩展注册同名工具，本覆盖层可正常包装内置工具；若已有更早的同名覆盖，则无法继续叠加。
• 对于 grep 和 find，到达截止时间后 agent 会立即恢复执行，但停止底层搜索进程仍依赖协作式清理。

兼容性

已在 Pi 1.3.0 和 1.4.0、Node 22.23 下测试通过。要求 Node >= 22.19。Pi 相关包均声明为 "*" peer dependencies。

开发

npm test          # 超时规则和覆盖层辅助函数
npm run test:e2e  # 通过 PATH 上的 pi 加载插件

@spinejit 的其他插件

• pi-background-job：后台任务与输出监视，事件发生时自动通知 agent。
• pi-btw-cached：在主会话自己的请求上发起 /btw 侧问。
• pi-compact-tree：Pi 终端界面的紧凑过程树视图。

许可证

Apache-2.0，见 LICENSE。