From 35555b2d0d2c0cd7b7bd1bdc00cc009ee6629783 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Fri, 16 Oct 2026 14:36:41 +0800 Subject: [PATCH 1/4] fix: pi/omp tool guardrails resolve through config knobs; bash-timeout injection off by default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #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. --- CONFIGURATION.md | 7 ++++++ CONFIGURATION.zh-CN.md | 7 ++++++ src/agent/pi.ts | 10 +++++++-- src/agent/tool-guardrails.ts | 30 +++++++++++++++++++------- src/config.ts | 13 +++++++++++ src/knobs.ts | 28 ++++++++++++++++++++++++ tests/knobs-config-precedence.test.ts | 26 ++++++++++++++++++++++ tests/tool-guardrails-pi.test.ts | 26 ++++++++++++++++++++-- website/config-reference/process.yaml | 31 +++++++++++++++++++++++++++ 9 files changed, 166 insertions(+), 12 deletions(-) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index e6a77f5502..5aa0b2dc2d 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -156,6 +156,10 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed | `network.receiveBodyBytes` | number | 5368709120 | BILI_RECEIVE_BODY_BYTES | Max inbound wire bytes read into memory per request before a 413 at the receive stage. Raised from a hardcoded 100 MiB to 5 GiB (#3128 owner decision) so multi-gigabyte single requests are accepted instead of the socket being reset. Also the threshold above which a decoded request consumes one of two shared large-decode admission slots. WebSocket lanes keep the fixed 100 MiB surface. | | `network.decodedBodyBytes` | number | 10737418240 | BILI_DECODED_BODY_BYTES | Max DECODED bytes after content-encoding expansion (gzip/deflate/br/zstd), checked incrementally during decode (decode-stage 413). Default is 2x the receive budget, mirroring the legacy decode=2x-wire relationship; guards against decompression bombs. | | `network.outboundBodyBytes` | number | 5368709120 | BILI_OUTBOUND_BODY_BYTES | Max rebuilt request bytes forwarded upstream (forward-stage 413), counted as UTF-8 bytes of the final body string. Checked before the fetch so an over-budget rebuild never reaches the upstream watchdog allocation. | +| `guardrails` | object | {} (all defaults) | — | Tool-output guardrails for the pi/omp plugin bundles (#3066). | +| `guardrails.bashTimeout` | number | unset (no injection) | BILI_GUARDRAIL_BASH_TIMEOUT | Seconds injected as the bash tool's `timeout` when the model omits it (#3331). OFF by default: pi's bash schema declares timeout an optional per-call override with no host default — silently injecting 60s (the pre-#3331 behavior) killed legitimate long runs like builds and installs. Positive N opts back into injecting N seconds. | +| `guardrails.maxOutputBytes` | number | 50000 | BILI_GUARDRAIL_MAX_OUTPUT_BYTES | Combined text-output byte cap per tool result in the pi/omp plugin (0 disables the cap). Over-cap output is truncated head-first with a notice pointing at the host-saved full output. | +| `guardrails.repetition` | boolean | true | BILI_GUARDRAIL_REPETITION | Identical-call loop-breaker for the pi/omp plugin (warn at 3, abort at 5 consecutive byte-identical calls). false / env 0 disables it. | | `persist` | object | {} (all defaults) | — | Session persistence to disk under the XDG state dir. | | `persist.enabled` | boolean | true | BILI_PERSIST | Master switch for writing session records to disk (0/false turns it off). | | `persist.zstd` | boolean | false | BILI_PERSIST_ZSTD | Zstd-compress persisted session files (1/true enables). | @@ -1643,6 +1647,9 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes | `BILI_LOG_MASK_HOSTS` | `maskHosts` | true | | `BILI_MAX_SESSIONS` | `sessions.max` | 256 | | `BILI_MAX_SHRINK_PER_COMPRESS` | `network.maxShrinkPerCompress` | unset | +| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | unset (no injection) | +| `BILI_GUARDRAIL_MAX_OUTPUT_BYTES` | `guardrails.maxOutputBytes` | 50000 (0 disables the cap) | +| `BILI_GUARDRAIL_REPETITION` | `guardrails.repetition` | true | | `BILI_MCP_PROXY` | `native.attachUrl` | unset (discover per lane) | | `BILI_MITM` | `mitm.enabled` | true | | `BILI_MITM_DOMAINS` | `mitm.domains` | [] | diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index 46e0b056e1..e1d8b1bbe1 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -156,6 +156,10 @@ | `network.receiveBodyBytes` | number | 5368709120 | BILI_RECEIVE_BODY_BYTES | 单请求读入内存的入站 wire 字节上限,超限在 receive 阶段返回 413。由硬编码 100 MiB 提升到 5 GiB(#3128 owner 决定),使多 GB 单请求被接受而非断连。同时也是解码请求占用两个共享大解码准入槽位的阈值。WebSocket lane 保持固定 100 MiB 表面。 | | `network.decodedBodyBytes` | number | 10737418240 | BILI_DECODED_BODY_BYTES | content-encoding 解压(gzip/deflate/br/zstd)后的解码字节上限,解码过程中增量检查(decode 阶段 413)。默认为接收预算的 2 倍,沿用旧的 decode=2×wire 关系;用于防解压炸弹。 | | `network.outboundBodyBytes` | number | 5368709120 | BILI_OUTBOUND_BODY_BYTES | 转发到上游的重建请求字节上限(forward 阶段 413),按最终 body 字符串的 UTF-8 字节计。在 fetch 之前检查,超预算的重建不会触发上游看门狗分配。 | +| `guardrails` | object | {} (all defaults) | — | pi/omp 插件包的工具输出守卫(#3066)。 | +| `guardrails.bashTimeout` | number | unset(不注入) | BILI_GUARDRAIL_BASH_TIMEOUT | 模型未写 `timeout` 时注入到 bash 工具的秒数(#3331)。默认不注入:pi 的 bash schema 把 timeout 声明为可选的逐调用覆盖、无宿主默认值——#3331 之前静默注入 60s 会杀掉构建/安装这类合法长任务。设为正整数 N 即恢复注入 N 秒。 | +| `guardrails.maxOutputBytes` | number | 50000 | BILI_GUARDRAIL_MAX_OUTPUT_BYTES | pi/omp 插件中每个工具结果的文本输出合计字节上限(0 禁用)。超限输出从头截断并附指向宿主已存完整输出的提示。 | +| `guardrails.repetition` | boolean | true | BILI_GUARDRAIL_REPETITION | pi/omp 插件的同一调用循环破除器(连续 3 次警告、5 次中止,按字节全同判定)。false 或 env 0 关闭。 | | `persist` | object | {} (all defaults) | — | 会话落盘持久化(XDG state 目录之下)。 | | `persist.enabled` | boolean | true | BILI_PERSIST | 会话记录落盘总开关(0/false 关闭)。 | | `persist.zstd` | boolean | false | BILI_PERSIST_ZSTD | zstd 压缩持久化会话文件(1/true 启用)。 | @@ -1642,6 +1646,9 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报 | `BILI_LOG_MASK_HOSTS` | `maskHosts` | true | | `BILI_MAX_SESSIONS` | `sessions.max` | 256 | | `BILI_MAX_SHRINK_PER_COMPRESS` | `network.maxShrinkPerCompress` | unset | +| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | unset(不注入) | +| `BILI_GUARDRAIL_MAX_OUTPUT_BYTES` | `guardrails.maxOutputBytes` | 50000(0 禁用截断) | +| `BILI_GUARDRAIL_REPETITION` | `guardrails.repetition` | true | | `BILI_MCP_PROXY` | `native.attachUrl` | unset (discover per lane) | | `BILI_MITM` | `mitm.enabled` | true | | `BILI_MITM_DOMAINS` | `mitm.domains` | [] | diff --git a/src/agent/pi.ts b/src/agent/pi.ts index fd5acad393..c0bdd215ac 100644 --- a/src/agent/pi.ts +++ b/src/agent/pi.ts @@ -19,7 +19,7 @@ import { asciiHeaderValue, detectProxyBase, destinationRoutedThroughProxy, fetch import { createForkAdopter } from "./fork-adopt.js"; import { logHostEvent } from "./host-log.js"; import { plainHttpTrusted } from "../private-host.js"; -import { allowPrivateHttpProviders } from "../knobs.js"; +import { allowPrivateHttpProviders, guardrailBashTimeout, guardrailMaxOutputBytes, guardrailRepetition } from "../knobs.js"; export type Ctx = { sessionManager?: { getSessionId?: () => string; getHeader?: () => unknown; getBranch?: () => unknown } | undefined; @@ -743,7 +743,13 @@ export function createBiliPlugin(agentOverride?: string, opts?: { retryIntervalM const agent = agentName(agentOverride); const state: RegisterState = { retryIntervalMs: opts?.retryIntervalMs ?? RETRY_INTERVAL_MS }; // #3066: tool-output guardrails (output cap / bash timeout / repetition loop-break); host-independent, wired for pi + omp. - wireToolGuardrails(pi); + // #3331: resolve through knobs (env > config file > default) — bash-timeout + // injection is opt-in, cap and repetition stay on by default. + wireToolGuardrails(pi, { + bashTimeout: guardrailBashTimeout(), + maxBytes: guardrailMaxOutputBytes(), + repetition: guardrailRepetition(), + }); // #2336: one successful agent-providers report per plugin instance; // retried on later session_starts while the proxy base is unknown // (native mode resolves it asynchronously). diff --git a/src/agent/tool-guardrails.ts b/src/agent/tool-guardrails.ts index bcf2a5276f..27f75fa15d 100644 --- a/src/agent/tool-guardrails.ts +++ b/src/agent/tool-guardrails.ts @@ -1,13 +1,17 @@ // Tool-output guardrails migrated from billion-context-pi (#3066); wired into -// createBiliPlugin for pi and omp, defaults mirror standalone bcp (60s / 50KB / -// repetition warn=3 abort=5). The temp-file dump on bash timeout/oversize is -// done by the PI HOST (path surfaced via result details.fullOutputPath) — we -// only reference it in the cap notice and never write the file ourselves. +// createBiliPlugin for pi and omp via knobs (env > config file > default). +// Defaults since #3331: output cap 50KB ON, repetition loop-breaker ON, +// bash-timeout injection OFF (pi's bash tool schema declares `timeout` an +// optional per-call override with no host-side default — silently injecting +// 60s killed legitimate long runs like builds/installs; opt back in with +// BILI_GUARDRAIL_BASH_TIMEOUT / guardrails.bashTimeout). The temp-file dump on +// bash timeout/oversize is done by the PI HOST (path surfaced via result +// details.fullOutputPath) — we only reference it in the cap notice and never +// write the file ourselves. import { createHash } from "node:crypto"; import type { ExtensionAPI } from "./pi.js"; -const DEFAULT_TOOL_BASH_TIMEOUT = 60; const DEFAULT_TOOL_OUTPUT_MAX_BYTES = 50_000; const REPETITION_GUARD_DEFAULTS = { warn: 3, abort: 5 } as const; @@ -44,13 +48,19 @@ function isBashToolCall(e: ToolCallEventLike): boolean { return e.toolName === "bash"; } +/** When `defaultTimeout` is a positive number and the call omitted `timeout`, + * return `defaultTimeout` (inject it). Any other defaultTimeout (undefined, + * 0, negative, NaN) means NO injection — the call goes out exactly as the + * model wrote it. There is no built-in fallback: the decision lives with the + * knobs layer (#3331 — pi's bash tool documents timeout as optional with no + * host default; injecting one silently is a behavior change for pi users). */ export function resolveBashTimeout( input: { timeout?: number }, defaultTimeout: number | undefined, ): number | undefined { if (input.timeout !== undefined) return undefined; - const d = defaultTimeout ?? DEFAULT_TOOL_BASH_TIMEOUT; - if (!Number.isFinite(d) || d <= 0) return undefined; + const d: number | undefined = defaultTimeout; + if (d === undefined || !Number.isFinite(d) || d <= 0) return undefined; return d; } @@ -205,7 +215,11 @@ function buildRepetitionAbortNotice(toolName: string, count: number): string { } export interface GuardrailOptions { + /** Seconds to inject as `timeout` when a bash call omits it. undefined = + * no injection (default; pi-native semantics). */ bashTimeout?: number; + /** Combined text-output byte cap per tool result. undefined = 50KB + * default; 0 = no cap. */ maxBytes?: number; repetition?: boolean | { enabled?: boolean; warn?: number; abort?: number }; } @@ -226,7 +240,7 @@ export function wireToolGuardrails(pi: ExtensionAPI, opts: GuardrailOptions = {} const trackers = new Map(); const pendingWarns = new Map(); const repCfg = resolveRepetition(opts.repetition); - const bashTimeout = opts.bashTimeout ?? DEFAULT_TOOL_BASH_TIMEOUT; + const bashTimeout = opts.bashTimeout; // undefined = no injection (knobs decide) const maxBytes = opts.maxBytes ?? DEFAULT_TOOL_OUTPUT_MAX_BYTES; pi.on("tool_call", (event, rawCtx) => { diff --git a/src/config.ts b/src/config.ts index 0f37546780..f0426c5649 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1827,6 +1827,19 @@ type FileConfig = { codexCompact?: string; /** Auto-mode classifier local-forge switch (#2740) — env BILI_AUTO_MODE_FORGE. */ autoModeForge?: { enabled?: boolean }; + /** pi/omp plugin tool-output guardrails (#3066). `bashTimeout` injects N + * seconds as the bash `timeout` when the model omits it — OFF by default + * (#3331: pi's bash schema declares timeout optional with no host default; + * silently injecting 60s killed legitimate long runs like builds). + * `maxOutputBytes` caps combined text tool output (default 50000, 0 = no + * cap). `repetition: false` disables the identical-call loop-breaker. + * Env BILI_GUARDRAIL_BASH_TIMEOUT / BILI_GUARDRAIL_MAX_OUTPUT_BYTES / + * BILI_GUARDRAIL_REPETITION win over all. */ + guardrails?: { + bashTimeout?: number; + maxOutputBytes?: number; + repetition?: boolean; + }; /** CCR retrieval TTL in ms (#2030) — was BILI_CCR_RETRIEVAL_TTL_MS (default 600000). */ ccrRetrievalTtlMs?: number; /** Large-decompress temp-file cap (#2030) — was BILI_DECOMPRESS_TMP_CAP (default 50). */ diff --git a/src/knobs.ts b/src/knobs.ts index 0ff62c4a55..a2aa127fc4 100644 --- a/src/knobs.ts +++ b/src/knobs.ts @@ -224,6 +224,34 @@ export function autoModeForgeEnabled(): boolean { return loadConfigFile().autoModeForge?.enabled !== false; } +// --- pi/omp plugin tool guardrails (#3066, #3331) — read in the pi/omp host +// process, so the env tier is what the launcher forwards; the FILE tier reads +// the same state dir's config the proxy reads. --- + +/** BILI_GUARDRAIL_BASH_TIMEOUT > guardrails.bashTimeout > undefined (no + * injection). Positive N = inject N seconds as the bash `timeout` when the + * model omits it. Default OFF: pi's bash tool schema documents `timeout` as + * an optional per-call override with no host default — injecting one is a + * behavior change pi users don't expect (#3331); opt back in explicitly. */ +export function guardrailBashTimeout(): number | undefined { + const n = tNumLoose("BILI_GUARDRAIL_BASH_TIMEOUT", loadConfigFile().guardrails?.bashTimeout); + return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined; +} + +/** BILI_GUARDRAIL_MAX_OUTPUT_BYTES > guardrails.maxOutputBytes > 50000 (50KB). 0 disables the cap. */ +export function guardrailMaxOutputBytes(): number | undefined { + const n = tNumLoose("BILI_GUARDRAIL_MAX_OUTPUT_BYTES", loadConfigFile().guardrails?.maxOutputBytes); + if (!Number.isFinite(n)) return 50_000; + return n > 0 ? Math.floor(n) : undefined; // 0 or negative = no cap +} + +/** BILI_GUARDRAIL_REPETITION > guardrails.repetition > true (identical-call loop-breaker, warn 3 / abort 5). */ +export function guardrailRepetition(): boolean { + const envRaw = process.env.BILI_GUARDRAIL_REPETITION; + if (envRaw !== undefined) return !(envRaw === "0" || envRaw === "false"); + return loadConfigFile().guardrails?.repetition !== false; +} + /** BILI_PERSIST_ZSTD > persist.zstd > false (#1080 owner decision: plain JSON default). */ export function persistZstdEnabled(): boolean { const envRaw = process.env.BILI_PERSIST_ZSTD; diff --git a/tests/knobs-config-precedence.test.ts b/tests/knobs-config-precedence.test.ts index c3463e7f26..51a2798c11 100644 --- a/tests/knobs-config-precedence.test.ts +++ b/tests/knobs-config-precedence.test.ts @@ -412,6 +412,32 @@ test("#2984 allowPrivateHttpProviders: positive env judgment, file tier, env win clearConfig(); }); +test("#3331 guardrail knobs: bash-timeout default OFF, file tier, env wins; cap/repetition defaults on", () => { + clearConfig(); + assert.equal(knobs.guardrailBashTimeout(), undefined, "default: no injection (pi-native)"); + assert.equal(knobs.guardrailMaxOutputBytes(), 50_000, "default cap 50KB"); + assert.equal(knobs.guardrailRepetition(), true, "loop-breaker default on"); + + setConfig({ guardrails: { bashTimeout: 45, maxOutputBytes: 12345, repetition: false } }); + assert.equal(knobs.guardrailBashTimeout(), 45, "file tier"); + assert.equal(knobs.guardrailMaxOutputBytes(), 12345, "file tier"); + assert.equal(knobs.guardrailRepetition(), false, "file tier"); + + withEnv({ BILI_GUARDRAIL_BASH_TIMEOUT: "120" }, () => { + assert.equal(knobs.guardrailBashTimeout(), 120, "env wins"); + }); + withEnv({ BILI_GUARDRAIL_BASH_TIMEOUT: "0" }, () => { + assert.equal(knobs.guardrailBashTimeout(), undefined, "0 = off, even with the file tier on"); + }); + withEnv({ BILI_GUARDRAIL_MAX_OUTPUT_BYTES: "0" }, () => { + assert.equal(knobs.guardrailMaxOutputBytes(), undefined, "0 disables the cap"); + }); + withEnv({ BILI_GUARDRAIL_REPETITION: "0" }, () => { + assert.equal(knobs.guardrailRepetition(), false, "env off beats file off/on alike"); + }); + clearConfig(); +}); + test("teardown", () => { if (previousConfigFile === undefined) delete process.env.BILI_CONFIG_FILE; else process.env.BILI_CONFIG_FILE = previousConfigFile; diff --git a/tests/tool-guardrails-pi.test.ts b/tests/tool-guardrails-pi.test.ts index 8b225981d7..f7d6c09cf1 100644 --- a/tests/tool-guardrails-pi.test.ts +++ b/tests/tool-guardrails-pi.test.ts @@ -34,8 +34,9 @@ test("resolveBashTimeout returns undefined when the default is disabled (0 / neg assert.equal(resolveBashTimeout({}, Number.NaN), undefined); }); -test("resolveBashTimeout falls back to the 60s built-in default when default is undefined", () => { - assert.equal(resolveBashTimeout({}, undefined), 60); +test("resolveBashTimeout does NOT inject when the default is undefined (no built-in fallback, #3331)", () => { + assert.equal(resolveBashTimeout({}, undefined), undefined); + assert.equal(resolveBashTimeout({ timeout: undefined }, undefined), undefined); }); test("capToolOutput leaves small output untouched (returns undefined)", () => { @@ -173,6 +174,27 @@ test("wireToolGuardrails applies the documented 50KB default when maxBytes is un assert.ok(Buffer.byteLength(t, "utf8") < 60 * 1024, "payload must be truncated near the 50KB default"); }); +test("wireToolGuardrails injects NO bash timeout by default (#3331 — pi-native semantics)", () => { + const w = wireRepetition(); + const call = { toolName: "bash", toolCallId: "b1", input: { command: "npm install" } as { command: string; timeout?: number } }; + w.call(call); + assert.equal(call.input.timeout, undefined, "no default timeout may be injected when the knob is unset"); +}); + +test("wireToolGuardrails injects the configured bashTimeout when the model omitted timeout", () => { + const w = wireRepetition({ bashTimeout: 90 }); + const call = { toolName: "bash", toolCallId: "b1", input: { command: "npm install" } as { command: string; timeout?: number } }; + w.call(call); + assert.equal(call.input.timeout, 90); +}); + +test("wireToolGuardrails never overrides an explicit per-call timeout", () => { + const w = wireRepetition({ bashTimeout: 90 }); + const call = { toolName: "bash", toolCallId: "b2", input: { command: "sleep", timeout: 600 } }; + w.call(call); + assert.equal(call.input.timeout, 600); +}); + test("wireToolGuardrails keeps an explicit maxBytes: 0 as disable", () => { const onResult = wireFor({ maxBytes: 0 }); assert.equal(onResult(readResult("x".repeat(300 * 1024))), undefined); diff --git a/website/config-reference/process.yaml b/website/config-reference/process.yaml index b25df247b9..ed861e46b9 100644 --- a/website/config-reference/process.yaml +++ b/website/config-reference/process.yaml @@ -131,6 +131,37 @@ entries: group: process desc_en: "Max rebuilt request bytes forwarded upstream (forward-stage 413), counted as UTF-8 bytes of the final body string. Checked before the fetch so an over-budget rebuild never reaches the upstream watchdog allocation." desc_zh: "转发到上游的重建请求字节上限(forward 阶段 413),按最终 body 字符串的 UTF-8 字节计。在 fetch 之前检查,超预算的重建不会触发上游看门狗分配。" + - key: guardrails + type: object + default: "{} (all defaults)" + group: process + id: tt.guardrails + site_group: proc + desc_en: "Tool-output guardrails for the pi/omp plugin bundles (#3066)." + desc_zh: "pi/omp 插件包的工具输出守卫(#3066)。" + site_en: "guardrails — pi/omp plugin tool-output guardrails: bashTimeout unset · maxOutputBytes 50000 · repetition true." + site_zh: "guardrails —— pi/omp 插件工具输出守卫:bashTimeout 不注入 · maxOutputBytes 50000 · repetition true。" + - key: guardrails.bashTimeout + type: number + default: "unset (no injection)" + env: BILI_GUARDRAIL_BASH_TIMEOUT + group: process + desc_en: "Seconds injected as the bash tool's timeout when the model omits it (#3331). OFF by default: pi's bash schema declares timeout an optional per-call override with no host default — silently injecting 60s (the pre-#3331 behavior) killed legitimate long runs like builds and installs. Positive N opts back into injecting N seconds." + desc_zh: "模型未写 timeout 时注入到 bash 工具的秒数(#3331)。默认不注入:pi 的 bash schema 把 timeout 声明为可选的逐调用覆盖、无宿主默认值——#3331 之前静默注入 60s 会杀掉构建/安装这类合法长任务。设为正整数 N 即恢复注入 N 秒。" + - key: guardrails.maxOutputBytes + type: number + default: "50000" + env: BILI_GUARDRAIL_MAX_OUTPUT_BYTES + group: process + desc_en: "Combined text-output byte cap per tool result in the pi/omp plugin (0 disables the cap). Over-cap output is truncated head-first with a notice pointing at the host-saved full output." + desc_zh: "pi/omp 插件中每个工具结果的文本输出合计字节上限(0 禁用)。超限输出从头截断并附指向宿主已存完整输出的提示。" + - key: guardrails.repetition + type: boolean + default: "true" + env: BILI_GUARDRAIL_REPETITION + group: process + desc_en: "Identical-call loop-breaker for the pi/omp plugin (warn at 3, abort at 5 consecutive byte-identical calls). false / env 0 disables it." + desc_zh: "pi/omp 插件的同一调用循环破除器(连续 3 次警告、5 次中止,按字节全同判定)。false 或 env 0 关闭。" - key: persist type: object default: "{} (all defaults)" From dbc7eba829c91fe09592ec0b1b384f731f11bb4a Mon Sep 17 00:00:00 2001 From: awork Date: Fri, 16 Oct 2026 14:51:01 +0800 Subject: [PATCH 2/4] docs: regenerate config docs from the yaml seed (fixes docs-sync) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- CONFIGURATION.md | 8 ++++---- CONFIGURATION.zh-CN.md | 8 ++++---- website/docs/index.html | 1 + website/main.js | 2 ++ 4 files changed, 11 insertions(+), 8 deletions(-) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 5aa0b2dc2d..73dafccd14 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -157,7 +157,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed | `network.decodedBodyBytes` | number | 10737418240 | BILI_DECODED_BODY_BYTES | Max DECODED bytes after content-encoding expansion (gzip/deflate/br/zstd), checked incrementally during decode (decode-stage 413). Default is 2x the receive budget, mirroring the legacy decode=2x-wire relationship; guards against decompression bombs. | | `network.outboundBodyBytes` | number | 5368709120 | BILI_OUTBOUND_BODY_BYTES | Max rebuilt request bytes forwarded upstream (forward-stage 413), counted as UTF-8 bytes of the final body string. Checked before the fetch so an over-budget rebuild never reaches the upstream watchdog allocation. | | `guardrails` | object | {} (all defaults) | — | Tool-output guardrails for the pi/omp plugin bundles (#3066). | -| `guardrails.bashTimeout` | number | unset (no injection) | BILI_GUARDRAIL_BASH_TIMEOUT | Seconds injected as the bash tool's `timeout` when the model omits it (#3331). OFF by default: pi's bash schema declares timeout an optional per-call override with no host default — silently injecting 60s (the pre-#3331 behavior) killed legitimate long runs like builds and installs. Positive N opts back into injecting N seconds. | +| `guardrails.bashTimeout` | number | unset (no injection) | BILI_GUARDRAIL_BASH_TIMEOUT | Seconds injected as the bash tool's timeout when the model omits it (#3331). OFF by default: pi's bash schema declares timeout an optional per-call override with no host default — silently injecting 60s (the pre-#3331 behavior) killed legitimate long runs like builds and installs. Positive N opts back into injecting N seconds. | | `guardrails.maxOutputBytes` | number | 50000 | BILI_GUARDRAIL_MAX_OUTPUT_BYTES | Combined text-output byte cap per tool result in the pi/omp plugin (0 disables the cap). Over-cap output is truncated head-first with a notice pointing at the host-saved full output. | | `guardrails.repetition` | boolean | true | BILI_GUARDRAIL_REPETITION | Identical-call loop-breaker for the pi/omp plugin (warn at 3, abort at 5 consecutive byte-identical calls). false / env 0 disables it. | | `persist` | object | {} (all defaults) | — | Session persistence to disk under the XDG state dir. | @@ -1641,15 +1641,15 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes | `BILI_FAKE_COMPLETION_RETRIES` | `fakeCompletion.retries` | 0 (opt-in) | | `BILI_FOLD_RECONCILE` | `compress.reconcile` | "repair" | | `BILI_FORK_ADOPTION` | `forkAdoption` | false | +| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | unset (no injection) | +| `BILI_GUARDRAIL_MAX_OUTPUT_BYTES` | `guardrails.maxOutputBytes` | 50000 | +| `BILI_GUARDRAIL_REPETITION` | `guardrails.repetition` | true | | `BILI_IMAGE_BILLING` | `imageBilling` | auto (resolves to pixels) | | `BILI_IMAGE_TOKEN_CAP` | `imageTokenCap` | unset (uncapped) | | `BILI_KEEP_ALIVE_TIMEOUT_MS` | `network.keepAliveTimeoutMs` | 5000 | | `BILI_LOG_MASK_HOSTS` | `maskHosts` | true | | `BILI_MAX_SESSIONS` | `sessions.max` | 256 | | `BILI_MAX_SHRINK_PER_COMPRESS` | `network.maxShrinkPerCompress` | unset | -| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | unset (no injection) | -| `BILI_GUARDRAIL_MAX_OUTPUT_BYTES` | `guardrails.maxOutputBytes` | 50000 (0 disables the cap) | -| `BILI_GUARDRAIL_REPETITION` | `guardrails.repetition` | true | | `BILI_MCP_PROXY` | `native.attachUrl` | unset (discover per lane) | | `BILI_MITM` | `mitm.enabled` | true | | `BILI_MITM_DOMAINS` | `mitm.domains` | [] | diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index e1d8b1bbe1..bc8975454a 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -157,7 +157,7 @@ | `network.decodedBodyBytes` | number | 10737418240 | BILI_DECODED_BODY_BYTES | content-encoding 解压(gzip/deflate/br/zstd)后的解码字节上限,解码过程中增量检查(decode 阶段 413)。默认为接收预算的 2 倍,沿用旧的 decode=2×wire 关系;用于防解压炸弹。 | | `network.outboundBodyBytes` | number | 5368709120 | BILI_OUTBOUND_BODY_BYTES | 转发到上游的重建请求字节上限(forward 阶段 413),按最终 body 字符串的 UTF-8 字节计。在 fetch 之前检查,超预算的重建不会触发上游看门狗分配。 | | `guardrails` | object | {} (all defaults) | — | pi/omp 插件包的工具输出守卫(#3066)。 | -| `guardrails.bashTimeout` | number | unset(不注入) | BILI_GUARDRAIL_BASH_TIMEOUT | 模型未写 `timeout` 时注入到 bash 工具的秒数(#3331)。默认不注入:pi 的 bash schema 把 timeout 声明为可选的逐调用覆盖、无宿主默认值——#3331 之前静默注入 60s 会杀掉构建/安装这类合法长任务。设为正整数 N 即恢复注入 N 秒。 | +| `guardrails.bashTimeout` | number | unset (no injection) | BILI_GUARDRAIL_BASH_TIMEOUT | 模型未写 timeout 时注入到 bash 工具的秒数(#3331)。默认不注入:pi 的 bash schema 把 timeout 声明为可选的逐调用覆盖、无宿主默认值——#3331 之前静默注入 60s 会杀掉构建/安装这类合法长任务。设为正整数 N 即恢复注入 N 秒。 | | `guardrails.maxOutputBytes` | number | 50000 | BILI_GUARDRAIL_MAX_OUTPUT_BYTES | pi/omp 插件中每个工具结果的文本输出合计字节上限(0 禁用)。超限输出从头截断并附指向宿主已存完整输出的提示。 | | `guardrails.repetition` | boolean | true | BILI_GUARDRAIL_REPETITION | pi/omp 插件的同一调用循环破除器(连续 3 次警告、5 次中止,按字节全同判定)。false 或 env 0 关闭。 | | `persist` | object | {} (all defaults) | — | 会话落盘持久化(XDG state 目录之下)。 | @@ -1640,15 +1640,15 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报 | `BILI_FAKE_COMPLETION_RETRIES` | `fakeCompletion.retries` | 0 (opt-in) | | `BILI_FOLD_RECONCILE` | `compress.reconcile` | "repair" | | `BILI_FORK_ADOPTION` | `forkAdoption` | false | +| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | unset (no injection) | +| `BILI_GUARDRAIL_MAX_OUTPUT_BYTES` | `guardrails.maxOutputBytes` | 50000 | +| `BILI_GUARDRAIL_REPETITION` | `guardrails.repetition` | true | | `BILI_IMAGE_BILLING` | `imageBilling` | auto (resolves to pixels) | | `BILI_IMAGE_TOKEN_CAP` | `imageTokenCap` | unset (uncapped) | | `BILI_KEEP_ALIVE_TIMEOUT_MS` | `network.keepAliveTimeoutMs` | 5000 | | `BILI_LOG_MASK_HOSTS` | `maskHosts` | true | | `BILI_MAX_SESSIONS` | `sessions.max` | 256 | | `BILI_MAX_SHRINK_PER_COMPRESS` | `network.maxShrinkPerCompress` | unset | -| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | unset(不注入) | -| `BILI_GUARDRAIL_MAX_OUTPUT_BYTES` | `guardrails.maxOutputBytes` | 50000(0 禁用截断) | -| `BILI_GUARDRAIL_REPETITION` | `guardrails.repetition` | true | | `BILI_MCP_PROXY` | `native.attachUrl` | unset (discover per lane) | | `BILI_MITM` | `mitm.enabled` | true | | `BILI_MITM_DOMAINS` | `mitm.domains` | [] | diff --git a/website/docs/index.html b/website/docs/index.html index de87dfdf14..7d8270a156 100644 --- a/website/docs/index.html +++ b/website/docs/index.html @@ -279,6 +279,7 @@

Other top-level fields

  • mitm.handshakeTimeoutMs — TLS handshake timeout (default 10000).
  • Process blocks
  • network — transport timeouts & replays: upstreamTimeoutMs 720000 · requestWatchdogMs 2× · replayRetryMax 3 · replayRetryBaseMs 1500 · keepAliveTimeoutMs 5000 · clientErrorBackstopMs 30000 · exposureLogIntervalMs 3600000 · streamKeepAliveMs 15000 · preflightHoldMs 30000 · preflightDeadEndCooldownMs 300000 · proxyKeepAliveMaxMs 55000.
  • +
  • guardrails — pi/omp plugin tool-output guardrails: bashTimeout unset · maxOutputBytes 50000 · repetition true.
  • persist — session persistence to disk: enabled true · zstd false · debounceMs 500 · tailTokens 16384 · epermAlertThreshold 5 · epermAlertRepeatMs 0.
  • storage — unified storage sidecar: unified legacy — file tier selects the lane-wide storage mode; env BILI_STORAGE_UNIFIED wins when set.
  • sessions — max 256 (LRU) · gc { enabled false, maxAgeDays 7, maxTokens 1000000, intervalMs 3600000 } — GC is opt-in; user data is never pruned silently.
  • diff --git a/website/main.js b/website/main.js index b1dbba4dcb..820b913b22 100644 --- a/website/main.js +++ b/website/main.js @@ -123,6 +123,7 @@ "ttl.ttl": "ccrRetrievalTtlMs — lifetime of CCR retrieval pointers (default 600000; 0 disables retrieval).", "ttl.tmp": "decompressTmpCap — size cap for temporary decompressed blocks (default 50).", "tt.network": "network — transport timeouts & replays: upstreamTimeoutMs 720000 · requestWatchdogMs 2× · replayRetryMax 3 · replayRetryBaseMs 1500 · keepAliveTimeoutMs 5000 · clientErrorBackstopMs 30000 · exposureLogIntervalMs 3600000 · streamKeepAliveMs 15000 · preflightHoldMs 30000 · preflightDeadEndCooldownMs 300000 · proxyKeepAliveMaxMs 55000.", + "tt.guardrails": "guardrails — pi/omp plugin tool-output guardrails: bashTimeout unset · maxOutputBytes 50000 · repetition true.", "tt.persist": "persist — session persistence to disk: enabled true · zstd false · debounceMs 500 · tailTokens 16384 · epermAlertThreshold 5 · epermAlertRepeatMs 0.", "tt.storage": "storage — unified storage sidecar: unified legacy — file tier selects the lane-wide storage mode; env BILI_STORAGE_UNIFIED wins when set.", "tt.sessions": "sessions — max 256 (LRU) · gc { enabled false, maxAgeDays 7, maxTokens 1000000, intervalMs 3600000 } — GC is opt-in; user data is never pruned silently.", @@ -361,6 +362,7 @@ "ttl.ttl": "ccrRetrievalTtlMs —— CCR 回取指针有效期(默认 600000;0 禁用回取)。", "ttl.tmp": "decompressTmpCap —— 临时展开块的大小上限(默认 50)。", "tt.network": "network —— 传输超时与重放:upstreamTimeoutMs 720000 · requestWatchdogMs 2× · replayRetryMax 3 · replayRetryBaseMs 1500 · keepAliveTimeoutMs 5000 · clientErrorBackstopMs 30000 · exposureLogIntervalMs 3600000 · streamKeepAliveMs 15000 · preflightHoldMs 30000 · preflightDeadEndCooldownMs 300000 · proxyKeepAliveMaxMs 55000。", + "tt.guardrails": "guardrails —— pi/omp 插件工具输出守卫:bashTimeout 不注入 · maxOutputBytes 50000 · repetition true。", "tt.persist": "persist —— 会话落盘持久化:enabled true · zstd false · debounceMs 500 · tailTokens 16384 · epermAlertThreshold 5 · epermAlertRepeatMs 0。", "tt.storage": "storage —— 统一存储边车:unified legacy —— 文件层选定全 lane 存储模式;设置了 BILI_STORAGE_UNIFIED 时环境变量优先。", "tt.sessions": "sessions —— max 256 (LRU) · gc { enabled false, maxAgeDays 7, maxTokens 1000000, intervalMs 3600000 } —— GC 为可选:用户数据不会被悄悄清理。", From a465abc83842e0d950d5fcdf380a3f714fa46395 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Fri, 16 Oct 2026 16:48:35 +0800 Subject: [PATCH 3/4] =?UTF-8?q?fix:=20guardrail=20bash-timeout=20default?= =?UTF-8?q?=20back=20to=2060s=20(#3066=20owner=20intent=20=E2=80=94=20unsu?= =?UTF-8?q?pervised=20bash=20hung=20pi=20sessions=20for=20a=20day)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- CONFIGURATION.md | 4 ++-- CONFIGURATION.zh-CN.md | 4 ++-- src/agent/pi.ts | 3 ++- src/agent/tool-guardrails.ts | 9 ++++---- src/config.ts | 6 ++--- src/knobs.ts | 14 +++++++----- tests/knobs-config-precedence.test.ts | 6 ++--- tests/tool-guardrails-pi.test.ts | 32 +++++++++++++++++++++++++-- website/config-reference/process.yaml | 10 ++++----- 9 files changed, 60 insertions(+), 28 deletions(-) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 73dafccd14..f398f1d02f 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -157,7 +157,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed | `network.decodedBodyBytes` | number | 10737418240 | BILI_DECODED_BODY_BYTES | Max DECODED bytes after content-encoding expansion (gzip/deflate/br/zstd), checked incrementally during decode (decode-stage 413). Default is 2x the receive budget, mirroring the legacy decode=2x-wire relationship; guards against decompression bombs. | | `network.outboundBodyBytes` | number | 5368709120 | BILI_OUTBOUND_BODY_BYTES | Max rebuilt request bytes forwarded upstream (forward-stage 413), counted as UTF-8 bytes of the final body string. Checked before the fetch so an over-budget rebuild never reaches the upstream watchdog allocation. | | `guardrails` | object | {} (all defaults) | — | Tool-output guardrails for the pi/omp plugin bundles (#3066). | -| `guardrails.bashTimeout` | number | unset (no injection) | BILI_GUARDRAIL_BASH_TIMEOUT | Seconds injected as the bash tool's timeout when the model omits it (#3331). OFF by default: pi's bash schema declares timeout an optional per-call override with no host default — silently injecting 60s (the pre-#3331 behavior) killed legitimate long runs like builds and installs. Positive N opts back into injecting N seconds. | +| `guardrails.bashTimeout` | number | 60 | BILI_GUARDRAIL_BASH_TIMEOUT | Seconds injected as the bash tool's timeout when the model omits it (#3066 owner intent, re-affirmed #3366: an unsupervised bash call could hang a pi session for a whole day — the host schema provides no default). Set N to tune, 0 to disable injection (pi-native no-default). | | `guardrails.maxOutputBytes` | number | 50000 | BILI_GUARDRAIL_MAX_OUTPUT_BYTES | Combined text-output byte cap per tool result in the pi/omp plugin (0 disables the cap). Over-cap output is truncated head-first with a notice pointing at the host-saved full output. | | `guardrails.repetition` | boolean | true | BILI_GUARDRAIL_REPETITION | Identical-call loop-breaker for the pi/omp plugin (warn at 3, abort at 5 consecutive byte-identical calls). false / env 0 disables it. | | `persist` | object | {} (all defaults) | — | Session persistence to disk under the XDG state dir. | @@ -1641,7 +1641,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes | `BILI_FAKE_COMPLETION_RETRIES` | `fakeCompletion.retries` | 0 (opt-in) | | `BILI_FOLD_RECONCILE` | `compress.reconcile` | "repair" | | `BILI_FORK_ADOPTION` | `forkAdoption` | false | -| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | unset (no injection) | +| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | 60 | | `BILI_GUARDRAIL_MAX_OUTPUT_BYTES` | `guardrails.maxOutputBytes` | 50000 | | `BILI_GUARDRAIL_REPETITION` | `guardrails.repetition` | true | | `BILI_IMAGE_BILLING` | `imageBilling` | auto (resolves to pixels) | diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index bc8975454a..316a208b36 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -157,7 +157,7 @@ | `network.decodedBodyBytes` | number | 10737418240 | BILI_DECODED_BODY_BYTES | content-encoding 解压(gzip/deflate/br/zstd)后的解码字节上限,解码过程中增量检查(decode 阶段 413)。默认为接收预算的 2 倍,沿用旧的 decode=2×wire 关系;用于防解压炸弹。 | | `network.outboundBodyBytes` | number | 5368709120 | BILI_OUTBOUND_BODY_BYTES | 转发到上游的重建请求字节上限(forward 阶段 413),按最终 body 字符串的 UTF-8 字节计。在 fetch 之前检查,超预算的重建不会触发上游看门狗分配。 | | `guardrails` | object | {} (all defaults) | — | pi/omp 插件包的工具输出守卫(#3066)。 | -| `guardrails.bashTimeout` | number | unset (no injection) | BILI_GUARDRAIL_BASH_TIMEOUT | 模型未写 timeout 时注入到 bash 工具的秒数(#3331)。默认不注入:pi 的 bash schema 把 timeout 声明为可选的逐调用覆盖、无宿主默认值——#3331 之前静默注入 60s 会杀掉构建/安装这类合法长任务。设为正整数 N 即恢复注入 N 秒。 | +| `guardrails.bashTimeout` | number | 60 | BILI_GUARDRAIL_BASH_TIMEOUT | 模型未写 timeout 时注入到 bash 工具的秒数(#3066 owner 有意为之,#3366 重申:无人看管的 bash 会把 pi 会话挂死一整天——宿主 schema 本身无默认值)。设 N 调整秒数,设 0 关闭注入(恢复 pi 原生行为)。 | | `guardrails.maxOutputBytes` | number | 50000 | BILI_GUARDRAIL_MAX_OUTPUT_BYTES | pi/omp 插件中每个工具结果的文本输出合计字节上限(0 禁用)。超限输出从头截断并附指向宿主已存完整输出的提示。 | | `guardrails.repetition` | boolean | true | BILI_GUARDRAIL_REPETITION | pi/omp 插件的同一调用循环破除器(连续 3 次警告、5 次中止,按字节全同判定)。false 或 env 0 关闭。 | | `persist` | object | {} (all defaults) | — | 会话落盘持久化(XDG state 目录之下)。 | @@ -1640,7 +1640,7 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报 | `BILI_FAKE_COMPLETION_RETRIES` | `fakeCompletion.retries` | 0 (opt-in) | | `BILI_FOLD_RECONCILE` | `compress.reconcile` | "repair" | | `BILI_FORK_ADOPTION` | `forkAdoption` | false | -| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | unset (no injection) | +| `BILI_GUARDRAIL_BASH_TIMEOUT` | `guardrails.bashTimeout` | 60 | | `BILI_GUARDRAIL_MAX_OUTPUT_BYTES` | `guardrails.maxOutputBytes` | 50000 | | `BILI_GUARDRAIL_REPETITION` | `guardrails.repetition` | true | | `BILI_IMAGE_BILLING` | `imageBilling` | auto (resolves to pixels) | diff --git a/src/agent/pi.ts b/src/agent/pi.ts index c0bdd215ac..990af2427f 100644 --- a/src/agent/pi.ts +++ b/src/agent/pi.ts @@ -744,7 +744,8 @@ export function createBiliPlugin(agentOverride?: string, opts?: { retryIntervalM const state: RegisterState = { retryIntervalMs: opts?.retryIntervalMs ?? RETRY_INTERVAL_MS }; // #3066: tool-output guardrails (output cap / bash timeout / repetition loop-break); host-independent, wired for pi + omp. // #3331: resolve through knobs (env > config file > default) — bash-timeout - // injection is opt-in, cap and repetition stay on by default. + // default 60s (#3066 owner intent, anti-hang), 0 disables; cap and + // repetition stay on by default. wireToolGuardrails(pi, { bashTimeout: guardrailBashTimeout(), maxBytes: guardrailMaxOutputBytes(), diff --git a/src/agent/tool-guardrails.ts b/src/agent/tool-guardrails.ts index 27f75fa15d..e969c00e3e 100644 --- a/src/agent/tool-guardrails.ts +++ b/src/agent/tool-guardrails.ts @@ -1,10 +1,11 @@ // Tool-output guardrails migrated from billion-context-pi (#3066); wired into // createBiliPlugin for pi and omp via knobs (env > config file > default). // Defaults since #3331: output cap 50KB ON, repetition loop-breaker ON, -// bash-timeout injection OFF (pi's bash tool schema declares `timeout` an -// optional per-call override with no host-side default — silently injecting -// 60s killed legitimate long runs like builds/installs; opt back in with -// BILI_GUARDRAIL_BASH_TIMEOUT / guardrails.bashTimeout). The temp-file dump on +// bash-timeout injection 60s ON (#3066 owner intent — an unsupervised bash +// call could hang a pi session for a whole day; BILI_GUARDRAIL_BASH_TIMEOUT=0 +// restores pi-native no-default behavior, N tunes the seconds). The default +// lives in knobs.ts, NOT here: a caller resolving through knobs must be able +// to disable end-to-end by passing undefined. The temp-file dump on // bash timeout/oversize is done by the PI HOST (path surfaced via result // details.fullOutputPath) — we only reference it in the cap notice and never // write the file ourselves. diff --git a/src/config.ts b/src/config.ts index f0426c5649..4b3980e165 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1828,9 +1828,9 @@ type FileConfig = { /** Auto-mode classifier local-forge switch (#2740) — env BILI_AUTO_MODE_FORGE. */ autoModeForge?: { enabled?: boolean }; /** pi/omp plugin tool-output guardrails (#3066). `bashTimeout` injects N - * seconds as the bash `timeout` when the model omits it — OFF by default - * (#3331: pi's bash schema declares timeout optional with no host default; - * silently injecting 60s killed legitimate long runs like builds). + * seconds as the bash `timeout` when the model omits it — default 60 + * (#3066 owner intent, re-affirmed #3366: unsupervised bash could hang a + * pi session for a whole day); 0 disables injection (pi-native). * `maxOutputBytes` caps combined text tool output (default 50000, 0 = no * cap). `repetition: false` disables the identical-call loop-breaker. * Env BILI_GUARDRAIL_BASH_TIMEOUT / BILI_GUARDRAIL_MAX_OUTPUT_BYTES / diff --git a/src/knobs.ts b/src/knobs.ts index a2aa127fc4..171e884ca2 100644 --- a/src/knobs.ts +++ b/src/knobs.ts @@ -228,14 +228,16 @@ export function autoModeForgeEnabled(): boolean { // process, so the env tier is what the launcher forwards; the FILE tier reads // the same state dir's config the proxy reads. --- -/** BILI_GUARDRAIL_BASH_TIMEOUT > guardrails.bashTimeout > undefined (no - * injection). Positive N = inject N seconds as the bash `timeout` when the - * model omits it. Default OFF: pi's bash tool schema documents `timeout` as - * an optional per-call override with no host default — injecting one is a - * behavior change pi users don't expect (#3331); opt back in explicitly. */ +/** BILI_GUARDRAIL_BASH_TIMEOUT > guardrails.bashTimeout > 60 (#3066 owner + * intent, re-affirmed in #3366: an unsupervised bash call could hang a pi + * session for a whole day — the host schema provides no default, so the + * proxy injects one). Positive N = inject N seconds as the bash `timeout` + * when the model omits it; 0 (or negative) disables injection for hosts + * that want pi-native behavior. */ export function guardrailBashTimeout(): number | undefined { const n = tNumLoose("BILI_GUARDRAIL_BASH_TIMEOUT", loadConfigFile().guardrails?.bashTimeout); - return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined; + if (!Number.isFinite(n)) return 60; + return n > 0 ? Math.floor(n) : undefined; // 0 or negative = no injection } /** BILI_GUARDRAIL_MAX_OUTPUT_BYTES > guardrails.maxOutputBytes > 50000 (50KB). 0 disables the cap. */ diff --git a/tests/knobs-config-precedence.test.ts b/tests/knobs-config-precedence.test.ts index 51a2798c11..0c2446b86f 100644 --- a/tests/knobs-config-precedence.test.ts +++ b/tests/knobs-config-precedence.test.ts @@ -412,9 +412,9 @@ test("#2984 allowPrivateHttpProviders: positive env judgment, file tier, env win clearConfig(); }); -test("#3331 guardrail knobs: bash-timeout default OFF, file tier, env wins; cap/repetition defaults on", () => { +test("#3331 guardrail knobs: bash-timeout default 60 (#3066 anti-hang), file tier, env wins; 0 disables; cap/repetition defaults on", () => { clearConfig(); - assert.equal(knobs.guardrailBashTimeout(), undefined, "default: no injection (pi-native)"); + assert.equal(knobs.guardrailBashTimeout(), 60, "default 60s — #3066 owner intent, unsupervised bash hung pi sessions"); assert.equal(knobs.guardrailMaxOutputBytes(), 50_000, "default cap 50KB"); assert.equal(knobs.guardrailRepetition(), true, "loop-breaker default on"); @@ -427,7 +427,7 @@ test("#3331 guardrail knobs: bash-timeout default OFF, file tier, env wins; cap/ assert.equal(knobs.guardrailBashTimeout(), 120, "env wins"); }); withEnv({ BILI_GUARDRAIL_BASH_TIMEOUT: "0" }, () => { - assert.equal(knobs.guardrailBashTimeout(), undefined, "0 = off, even with the file tier on"); + assert.equal(knobs.guardrailBashTimeout(), undefined, "0 = off (pi-native), even with the file tier on"); }); withEnv({ BILI_GUARDRAIL_MAX_OUTPUT_BYTES: "0" }, () => { assert.equal(knobs.guardrailMaxOutputBytes(), undefined, "0 disables the cap"); diff --git a/tests/tool-guardrails-pi.test.ts b/tests/tool-guardrails-pi.test.ts index f7d6c09cf1..61cf4b6495 100644 --- a/tests/tool-guardrails-pi.test.ts +++ b/tests/tool-guardrails-pi.test.ts @@ -13,6 +13,24 @@ import { type GuardrailOptions, } from "../src/agent/tool-guardrails.ts"; import type { ExtensionAPI } from "../src/agent/pi.ts"; +import { guardrailBashTimeout } from "../src/knobs.ts"; + +function withEnv(env: Record, fn: () => void): void { + const saved: Record = {}; + for (const [k, v] of Object.entries(env)) { + saved[k] = process.env[k]; + if (v === undefined) delete process.env[k]; + else process.env[k] = v; + } + try { + fn(); + } finally { + for (const [k, v] of Object.entries(saved)) { + if (v === undefined) delete process.env[k]; + else process.env[k] = v; + } + } +} type TextPart = { type: "text"; text: string }; type NonTextPart = { type: string } & Record; @@ -174,11 +192,21 @@ test("wireToolGuardrails applies the documented 50KB default when maxBytes is un assert.ok(Buffer.byteLength(t, "utf8") < 60 * 1024, "payload must be truncated near the 50KB default"); }); -test("wireToolGuardrails injects NO bash timeout by default (#3331 — pi-native semantics)", () => { +test("wireToolGuardrails is pass-through: no opts means NO injection (the 60s default lives in guardrailBashTimeout so 0 can disable end-to-end)", () => { const w = wireRepetition(); const call = { toolName: "bash", toolCallId: "b1", input: { command: "npm install" } as { command: string; timeout?: number } }; w.call(call); - assert.equal(call.input.timeout, undefined, "no default timeout may be injected when the knob is unset"); + assert.equal(call.input.timeout, undefined, "wireToolGuardrails itself must not re-default — knobs own the default"); +}); +test("pi lane end-to-end: guardrailBashTimeout() default injects 60 (#3066 anti-hang), 0 disables", () => { + assert.equal(guardrailBashTimeout(), 60, "#3066 owner default — unsupervised bash hung pi sessions for a day"); + withEnv({ BILI_GUARDRAIL_BASH_TIMEOUT: "0" }, () => { + assert.equal(guardrailBashTimeout(), undefined, "0 = pi-native no injection"); + }); + const w = wireRepetition({ bashTimeout: guardrailBashTimeout() }); + const call = { toolName: "bash", toolCallId: "b1", input: { command: "npm install" } as { command: string; timeout?: number } }; + w.call(call); + assert.equal(call.input.timeout, 60); }); test("wireToolGuardrails injects the configured bashTimeout when the model omitted timeout", () => { diff --git a/website/config-reference/process.yaml b/website/config-reference/process.yaml index ed861e46b9..8159ef2030 100644 --- a/website/config-reference/process.yaml +++ b/website/config-reference/process.yaml @@ -139,15 +139,15 @@ entries: site_group: proc desc_en: "Tool-output guardrails for the pi/omp plugin bundles (#3066)." desc_zh: "pi/omp 插件包的工具输出守卫(#3066)。" - site_en: "guardrails — pi/omp plugin tool-output guardrails: bashTimeout unset · maxOutputBytes 50000 · repetition true." - site_zh: "guardrails —— pi/omp 插件工具输出守卫:bashTimeout 不注入 · maxOutputBytes 50000 · repetition true。" + site_en: "guardrails — pi/omp plugin tool-output guardrails: bashTimeout 60 · maxOutputBytes 50000 · repetition true." + site_zh: "guardrails —— pi/omp 插件工具输出守卫:bashTimeout 60 · maxOutputBytes 50000 · repetition true。" - key: guardrails.bashTimeout type: number - default: "unset (no injection)" + default: "60" env: BILI_GUARDRAIL_BASH_TIMEOUT group: process - desc_en: "Seconds injected as the bash tool's timeout when the model omits it (#3331). OFF by default: pi's bash schema declares timeout an optional per-call override with no host default — silently injecting 60s (the pre-#3331 behavior) killed legitimate long runs like builds and installs. Positive N opts back into injecting N seconds." - desc_zh: "模型未写 timeout 时注入到 bash 工具的秒数(#3331)。默认不注入:pi 的 bash schema 把 timeout 声明为可选的逐调用覆盖、无宿主默认值——#3331 之前静默注入 60s 会杀掉构建/安装这类合法长任务。设为正整数 N 即恢复注入 N 秒。" + desc_en: "Seconds injected as the bash tool's timeout when the model omits it (#3066 owner intent, re-affirmed #3366: an unsupervised bash call could hang a pi session for a whole day — the host schema provides no default). Set N to tune, 0 to disable injection (pi-native no-default)." + desc_zh: "模型未写 timeout 时注入到 bash 工具的秒数(#3066 owner 有意为之,#3366 重申:无人看管的 bash 会把 pi 会话挂死一整天——宿主 schema 本身无默认值)。设 N 调整秒数,设 0 关闭注入(恢复 pi 原生行为)。" - key: guardrails.maxOutputBytes type: number default: "50000" From c5a249fd606394f665fe0cdc5cdc5a70a36b1680 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Fri, 16 Oct 2026 17:13:15 +0800 Subject: [PATCH 4/4] docs: regenerate config docs artifacts for the 60s guardrail default (fix docs-sync) --- website/docs/index.html | 2 +- website/main.js | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/index.html b/website/docs/index.html index 7d8270a156..ce0f9b00ba 100644 --- a/website/docs/index.html +++ b/website/docs/index.html @@ -279,7 +279,7 @@

    Other top-level fields

  • mitm.handshakeTimeoutMs — TLS handshake timeout (default 10000).
  • Process blocks
  • network — transport timeouts & replays: upstreamTimeoutMs 720000 · requestWatchdogMs 2× · replayRetryMax 3 · replayRetryBaseMs 1500 · keepAliveTimeoutMs 5000 · clientErrorBackstopMs 30000 · exposureLogIntervalMs 3600000 · streamKeepAliveMs 15000 · preflightHoldMs 30000 · preflightDeadEndCooldownMs 300000 · proxyKeepAliveMaxMs 55000.
  • -
  • guardrails — pi/omp plugin tool-output guardrails: bashTimeout unset · maxOutputBytes 50000 · repetition true.
  • +
  • guardrails — pi/omp plugin tool-output guardrails: bashTimeout 60 · maxOutputBytes 50000 · repetition true.
  • persist — session persistence to disk: enabled true · zstd false · debounceMs 500 · tailTokens 16384 · epermAlertThreshold 5 · epermAlertRepeatMs 0.
  • storage — unified storage sidecar: unified legacy — file tier selects the lane-wide storage mode; env BILI_STORAGE_UNIFIED wins when set.
  • sessions — max 256 (LRU) · gc { enabled false, maxAgeDays 7, maxTokens 1000000, intervalMs 3600000 } — GC is opt-in; user data is never pruned silently.
  • diff --git a/website/main.js b/website/main.js index 820b913b22..c69caa5fa6 100644 --- a/website/main.js +++ b/website/main.js @@ -123,7 +123,7 @@ "ttl.ttl": "ccrRetrievalTtlMs — lifetime of CCR retrieval pointers (default 600000; 0 disables retrieval).", "ttl.tmp": "decompressTmpCap — size cap for temporary decompressed blocks (default 50).", "tt.network": "network — transport timeouts & replays: upstreamTimeoutMs 720000 · requestWatchdogMs 2× · replayRetryMax 3 · replayRetryBaseMs 1500 · keepAliveTimeoutMs 5000 · clientErrorBackstopMs 30000 · exposureLogIntervalMs 3600000 · streamKeepAliveMs 15000 · preflightHoldMs 30000 · preflightDeadEndCooldownMs 300000 · proxyKeepAliveMaxMs 55000.", - "tt.guardrails": "guardrails — pi/omp plugin tool-output guardrails: bashTimeout unset · maxOutputBytes 50000 · repetition true.", + "tt.guardrails": "guardrails — pi/omp plugin tool-output guardrails: bashTimeout 60 · maxOutputBytes 50000 · repetition true.", "tt.persist": "persist — session persistence to disk: enabled true · zstd false · debounceMs 500 · tailTokens 16384 · epermAlertThreshold 5 · epermAlertRepeatMs 0.", "tt.storage": "storage — unified storage sidecar: unified legacy — file tier selects the lane-wide storage mode; env BILI_STORAGE_UNIFIED wins when set.", "tt.sessions": "sessions — max 256 (LRU) · gc { enabled false, maxAgeDays 7, maxTokens 1000000, intervalMs 3600000 } — GC is opt-in; user data is never pruned silently.", @@ -362,7 +362,7 @@ "ttl.ttl": "ccrRetrievalTtlMs —— CCR 回取指针有效期(默认 600000;0 禁用回取)。", "ttl.tmp": "decompressTmpCap —— 临时展开块的大小上限(默认 50)。", "tt.network": "network —— 传输超时与重放:upstreamTimeoutMs 720000 · requestWatchdogMs 2× · replayRetryMax 3 · replayRetryBaseMs 1500 · keepAliveTimeoutMs 5000 · clientErrorBackstopMs 30000 · exposureLogIntervalMs 3600000 · streamKeepAliveMs 15000 · preflightHoldMs 30000 · preflightDeadEndCooldownMs 300000 · proxyKeepAliveMaxMs 55000。", - "tt.guardrails": "guardrails —— pi/omp 插件工具输出守卫:bashTimeout 不注入 · maxOutputBytes 50000 · repetition true。", + "tt.guardrails": "guardrails —— pi/omp 插件工具输出守卫:bashTimeout 60 · maxOutputBytes 50000 · repetition true。", "tt.persist": "persist —— 会话落盘持久化:enabled true · zstd false · debounceMs 500 · tailTokens 16384 · epermAlertThreshold 5 · epermAlertRepeatMs 0。", "tt.storage": "storage —— 统一存储边车:unified legacy —— 文件层选定全 lane 存储模式;设置了 BILI_STORAGE_UNIFIED 时环境变量优先。", "tt.sessions": "sessions —— max 256 (LRU) · gc { enabled false, maxAgeDays 7, maxTokens 1000000, intervalMs 3600000 } —— GC 为可选:用户数据不会被悄悄清理。",