Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 | 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. |
| `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). |
Expand Down Expand Up @@ -1637,6 +1641,9 @@ 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` | 60 |
| `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 |
Expand Down
7 changes: 7 additions & 0 deletions CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 | 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 目录之下)。 |
| `persist.enabled` | boolean | true | BILI_PERSIST | 会话记录落盘总开关(0/false 关闭)。 |
| `persist.zstd` | boolean | false | BILI_PERSIST_ZSTD | zstd 压缩持久化会话文件(1/true 启用)。 |
Expand Down Expand Up @@ -1636,6 +1640,9 @@ 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` | 60 |
| `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 |
Expand Down
11 changes: 9 additions & 2 deletions src/agent/pi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -743,7 +743,14 @@ 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
// default 60s (#3066 owner intent, anti-hang), 0 disables; 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).
Expand Down
31 changes: 23 additions & 8 deletions src/agent/tool-guardrails.ts
Original file line number Diff line number Diff line change
@@ -1,13 +1,18 @@
// 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 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.

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;

Expand Down Expand Up @@ -44,13 +49,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;
}

Expand Down Expand Up @@ -205,7 +216,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 };
}
Expand All @@ -226,7 +241,7 @@ export function wireToolGuardrails(pi: ExtensionAPI, opts: GuardrailOptions = {}
const trackers = new Map<string, RepetitionTracker>();
const pendingWarns = new Map<string, number>();
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) => {
Expand Down
13 changes: 13 additions & 0 deletions src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 — 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 /
* 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). */
Expand Down
30 changes: 30 additions & 0 deletions src/knobs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,36 @@ 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 > 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);
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. */
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;
Expand Down
26 changes: 26 additions & 0 deletions tests/knobs-config-precedence.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -412,6 +412,32 @@ test("#2984 allowPrivateHttpProviders: positive env judgment, file tier, env win
clearConfig();
});

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(), 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");

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 (pi-native), 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;
Expand Down
54 changes: 52 additions & 2 deletions tests/tool-guardrails-pi.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string | undefined>, fn: () => void): void {
const saved: Record<string, string | undefined> = {};
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<string, unknown>;
Expand All @@ -34,8 +52,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)", () => {
Expand Down Expand Up @@ -173,6 +192,37 @@ 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 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, "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", () => {
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);
Expand Down
Loading
Loading