Skip to content

fix: pi/omp tool guardrails are configurable; bash-timeout injection off by default - #3366

Merged
ranxianglei merged 4 commits into
masterfrom
fix/pi-guardrail-knobs
Oct 16, 2026
Merged

ranxianglei merged 4 commits into
masterfrom
fix/pi-guardrail-knobs

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 16, 2026 •

Copy link
Copy Markdown
Owner

ai: zhipuai-lb/glm-5.3

什么坏了(#3331 审查 D-1)

pi/omp 插件的工具守卫(wireToolGuardrails,#3066 从 billion-context-pi 迁移)是硬编码无开关:bash 60s 超时注入、工具输出 50KB 截断、相同调用重复 5 次熔断,三个行为全部没有旋钮——想关任何一个只能改代码。

修复:三个旋钮,默认值不变

BILI_GUARDRAIL_BASH_TIMEOUT / BILI_GUARDRAIL_MAX_OUTPUT_BYTES / BILI_GUARDRAIL_REPETITION(env > config 文件 guardrails.* > 默认):

旋钮 默认 说明
guardrails.bashTimeout 60(维持 #3066 owner 原意) 模型没写 timeout 时注入的秒数。无人看管的 bash 曾把 pi 会话挂死一整天,这个注入是故意的防护;设 N 调秒数,设 0 关闭注入(恢复 pi 原生无默认行为)
guardrails.maxOutputBytes 50000(不变) 0 = 不截断
guardrails.repetition true(不变) false/0 = 关熔断

owner 反馈后已把默认改回 60:最初版本曾默认不注入(理由:pi schema 本身无宿主默认、静默注入会杀合法长任务),但 #3066 的注入是有意为之的防挂死防护,默认关闭等于下架了它。现在默认行为与 #3066 完全一致,只是从此可以一行配置关掉/调参——这才是 D-1 真正缺的东西(kill switch)。

实现要点:60 的默认值只放在 knobs.ts 的 guardrailBashTimeout(),wireToolGuardrails 保持纯透传(undefined=不注入)——否则 =0 映射成 undefined 后又会被内部兜底改回 60,显式关闭就失效了。测试同时钉住这两层契约。

测试

  • tests/tool-guardrails-pi.test.ts 40/40(新增:透传契约、knob 默认 60、0 端到端关闭、注入/不覆盖显式 timeout)
  • tests/knobs-config-precedence.test.ts 14/14(env > file > 默认 三层优先级)
  • tsc 干净;文档 5 处同步(CONFIGURATION.md / zh-CN / process.yaml / config.ts 类型注释 / pi.ts 调用点注释),CONFIGURATION 表由 yaml seed 重新生成

来自 #3331 区间审查(D-1)。

…t injection off by default

#3066 wired the bcp guardrails (50KB output cap, repetition loop-breaker,
60s bash-timeout injection) straight into the pi/omp plugin bundles with
hardcoded defaults and no way to turn them off: GuardrailOptions existed
but the single call site passed nothing.

The bash-timeout injection is a behavior change pi users cannot expect —
pi's bash tool schema declares timeout an optional per-call override with
no host-side default, so silently injecting 60s killed legitimate long
runs (builds, installs, test suites) with no knob to recover. Output cap
and repetition breaker stay on by default (bounded, reversible, and they
annotate rather than kill), but are now configurable.

All three now resolve env > config file > default through knobs.ts, with
a guardrails.{bashTimeout,maxOutputBytes,repetition} config group, seeds
in website/config-reference, and en/zh CONFIGURATION tables:
- BILI_GUARDRAIL_BASH_TIMEOUT / guardrails.bashTimeout: unset = no
  injection (new default); N = inject N seconds when the call omits timeout
- BILI_GUARDRAIL_MAX_OUTPUT_BYTES / guardrails.maxOutputBytes: 50000
  default, 0 disables the cap
- BILI_GUARDRAIL_REPETITION / guardrails.repetition: true default

The default flip on bashTimeout is deliberate and flagged for owner
review — availability over performance per AGENTS.md 7.3.
@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: fix/pi-guardrail-knobs (c5a249f)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3991-pr.3366.686e7a2

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr3366.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

查重结论

查重: 不重复。 检索 open+closed issue/PR("guardrail"、"bash timeout"):仅历史相关项——#3088(工具守卫从 bcp 移植)、#3170–#3174(guardrail handler 测试回归修复)、bcp 侧 #421/#426(50KB 上限调整);无其他「守卫无开关 / bash 超时注入」在途条目。本 PR 是 #3331 区间审查 D-1 的唯一修复项(#3361/#3368/#3357 分别是同批的 A-1/F-1/E-1,机制互不相干)。

初审进展(方向关已过,发现一个 CI 红)

  1. 方向判定:通过。 D-1 根因已在 197-master range review | 197-master区间审查 #3331 独立核实(src/agent/pi.ts 无参调用 wireToolGuardrails(pi) + resolveBashTimeout 内置 60s 兜底),本 PR 修法与之对齐:决策上收 knobs 层(env > file > default)、删除 DEFAULT_TOOL_BASH_TIMEOUT、接线传三参。代码层已核对:tNumLoose 复用既有分层解析器,布尔 env 写法与 persistEnabled/autoModeForgeEnabled(默认开类旋钮)完全同构,非新造风格。
  2. 行为变更确认(bashTimeout 60s → 不注入):默认翻转成立——pi 原生语义是「timeout 为可选逐调用覆盖、宿主无默认」,静默强杀构建/安装/测试类长任务比不设限更糟;截断与熔断保持默认开(有界、可逆)。恢复 迁移billion-context-pi中的timeout 输出截断后自动dump到临时文件到本仓库 #3066 行为的逃生门 BILI_GUARDRAIL_BASH_TIMEOUT=60 已落档 en+zh。此项属默认值变更,合并前请 owner 最终过目(见最终八问回复)。
  3. CI 红定位(docs-sync):PR 手改了 CONFIGURATION*.md 与 process.yaml seed,但没跑 node tools/gen-config-docs.mjs generate——生成器会重排 env 表顺序并补 website/main.js + website/docs/index.html 的 i18n 条目,缺了这些生成物 diff 即红。连带后果:docs-sync 是 test/static-gates lane 的 needs 前置,本 head 上一个测试都没跑(matrix 全 skipped)。
  4. 处置:按「小问题直接修」纪律,我直接在 PR 分支补独立 commit 跑生成器对齐,并把 master 领先的 9 个提交合进来(均不触碰本 PR 文件,零冲突面),push 后让 CI 重跑完整测试矩阵。随后给结构化八问终审结论。

The guardrails entries were hand-edited into CONFIGURATION.md/zh-CN.md and
website/config-reference/process.yaml without running tools/gen-config-docs.mjs
generate — so the committed md drifted from the generator output (backticks in
one description, env-table row order/defaults) and website/main.js +
website/docs/index.html never got the new tt.guardrails entries at all. This
commit is the generator's own output for the same seed: no content change.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

终审结论:可合并(默认值翻转请 owner 拍板)

CI 证据(新 head dbc7eva82,GitHub API 实查):docs-sync ✅、config-surface-guard ✅、docs-coverage ✅、kernel/pi-subagents/lane/version/lock-sync/test-import-graph/unused-exports/build-artifact 全绿,完整 hermetic 测试矩阵 6 分片全过(ubuntu22×3 + ubuntu24 + windows22×2 + static-gates/ubuntu24)。e2e/real-client lane 按 #3295 三层 CI 规则无 ci:full 标签时 skip,属预期。上一轮 35555b2d0 上零测试运行的问题已消除。

docs-sync 处理说明(透明化):该红是本 issue 早前一轮处理时已在本分支补了独立 commit dbc7eba82(跑 tools/gen-config-docs.mjs generate 对齐生成物:env 表行归位到字母序、去掉一处反引号漂移、补 website/main.js + docs/index.html 的 tt.guardrails i18n 条目,无内容变更)。本轮我独立复核:临时 worktree 里重跑 generate + check-coverage,输出与提交树字节一致(幂等证明),CI 亦转绿。master 领先的 9 个提交(#3282/#3288/#3345 系)与本 PR 文件零交集,PR 保持 conflict-free,未再往分支塞 merge commit,保持最小足迹——合并前如需更新 base,GitHub 侧操作即可,非阻塞。

结构化八问

  1. 是什么问题:pi/omp 插件的三个工具守卫(输出截断/重复熔断/bash 超时注入)从 迁移billion-context-pi中的timeout 输出截断后自动dump到临时文件到本仓库 #3066 起全部硬编码无开关,且 bash 60s 超时静默注入违背 pi 原生语义(构建/安装/测试类长任务被杀,用户不知情)。
  2. 什么原因导致的:GuardrailOptions 接口存在但唯一调用点 src/agent/pi.ts 无参调用,决策从未接到配置层;resolveBashTimeout 内置 60s 兜底把「宿主无默认超时」的 pi 语义悄悄改写。根因是接线缺失,不是守卫机制本身有错。
  3. 影响范围与严重程度:所有 bili pi/bili omp 用户。旧行为下:任何未写 timeout 的 bash 调用一律 60s 强杀(特定条件下有问题——长任务必中,且不可见);截断/熔断为体验级保护。本 PR 后:仅显式配置的用户行为变化,默认用户脱离强杀。
  4. 怎么修复的:决策上收 knobs 层(env > config file > default,复用既有 tNumLoose 分层解析器),新增 guardrails.{bashTimeout,maxOutputBytes,repetition} 三键 + 三个 BILI_GUARDRAIL_* env;删除 DEFAULT_TOOL_BASH_TIMEOUT 常量(全树零残留,已 grep 验证);pi.ts 调用点传三参。布尔 env 写法与 persistEnabled/autoModeForgeEnabled 同构,非新造风格。
  5. 是否有回归问题:0 处无意回归。逐项清点触碰路径既有行为:输出截断默认 50KB 不变、重复熔断 warn3/abort5 不变、显式逐调用 timeout 永远优先(有测试钉死)、knobs.ts 纯新增函数不动既有旋钮、config.ts 加可选字段不影响存量配置解析、双压缩模式绑定/thinking 签名路径/WIRE_RULES 台账均未触碰。唯一语义变化即下述披露项。
  6. 是否破坏缓存:不涉及。守卫作用于插件进程内 tool_call/tool_result 事件,不碰压缩状态、前缀缓存接缝或增量游标。
  7. 是否改了设计方向:否。守卫机制本身原样保留,只是把硬编码常量换成既有的三级配置解析——架构方向与仓库惯例一致。
  8. 是否引入了新的配置:是,一组三个键(合规:config.ts 接口+注释、process.yaml seed、CONFIGURATION en+zh 双表、website 生成物齐备,config-surface-guard/docs-coverage/docs-sync 三门全绿):
    • guardrails.bashTimeout / BILI_GUARDRAIL_BASH_TIMEOUT:默认不注入;N>0 = 模型没写 timeout 时注入 N 秒
    • guardrails.maxOutputBytes / BILI_GUARDRAIL_MAX_OUTPUT_BYTES:默认 50000;0 = 不截断
    • guardrails.repetition / BILI_GUARDRAIL_REPETITION:默认 true;false/0 = 关熔断

行为变更清单(有意,合并前请 owner 确认)

测试有效性

新增断言有牙:「undefined=不注入」直接钉死本次回归(谁再把内置兜底加回来必挂);「配置 90 注入 90」「显式 600 不被覆盖」钉住两边界;precedence 测试覆盖三键的默认/文件层/env 覆盖/0=off 全组合。被替换的旧测试钉的是被有意废弃的行为,替换正确。一个已知取舍:pi.ts 工厂那一行胶水(createBiliPlugin→三个 knob 函数)没有工厂级单测(mock 接线测试测的是 wireToolGuardrails 本体而非真实工厂)——一行调用点由 typecheck 兜签名,风险可接受,不作为阻塞项。

判定:代码、文档、测试、CI 四关全过,diff 干净(9 文件全为目的相关 + 独立标注的 docs 修复 commit),可合并;唯一待办是 owner 对 bashTimeout 默认翻转点头。

… unsupervised bash hung pi sessions for a day)

Owner feedback on #3366: the 60s injection was deliberate (#3066) — an
unsupervised bash call could hang a pi session for a whole day, and the
host schema provides no default. Default OFF was the wrong call: it
traded a rare, visible, silent work-loss failure (killed long runs) for
a common one (dead sessions) and unshipped an intentional protection.

- guardrailBashTimeout(): env > config > 60 (was: > undefined).
  0 or negative still disables injection (pi-native), N tunes seconds.
- The default lives ONLY in knobs — wireToolGuardrails stays pass-through
  (undefined = no injection) so BILI_GUARDRAIL_BASH_TIMEOUT=0 disables
  end-to-end; a re-default inside the guardrail would silently override
  the explicit off.
- Docs/comments updated (CONFIGURATION.md, zh-CN, process.yaml, config.ts,
  pi.ts, tool-guardrails.ts header): state the owner intent and the 0-out.
- Tests: default-60 + 0-disables asserted both at the knob layer and
  through the wire seam; pass-through test keeps the no-re-default
  contract pinned.

tool-guardrails-pi 40/40, knobs-config-precedence 14/14, tsc clean.
@ranxianglei
ranxianglei merged commit 95013a5 into master Oct 16, 2026
40 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.489-master.95013a5 (rolling master tag).

npm install -g billion-context@0.0.489-master.95013a5  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant