Skip to content
13 changes: 13 additions & 0 deletions docs/clients.md
Original file line number Diff line number Diff line change
Expand Up @@ -699,6 +699,19 @@ fallback — read only while the section is absent, ignored once it exists.
Full field table and the `PI_ACP_DELEGATE_*` env overrides:
configuration.md → [`pi`](configuration.md#pi).

**Nudge visibility (what the proxy injected, without model-context cost).**
With the global debug switch on (`ACP_DEBUG=1`, or `"debug": true` in the
config file), every nudge the proxy injects mid-compression is shown in the
terminal — once per user turn, as a transient notification after the model
has answered — with the VERBATIM wire text: exactly the ephemeral trailing
user message the model reads that turn, byte for byte. The notification is
terminal-only: it is never written to the session file and adds nothing to
model context (the nudge reaching the model is the pre-existing mechanism's
job; this view just lets a human see it happen). Pi inline mode only — in
spawn/attach the proxy is a separate process and the view is unavailable.
Covers the Anthropic and OpenAI wire lanes (the two pi reaches over HTTP); on
hosts without `ui.notify` the feature degrades to absent.

**How routing works.** The pi extension bootstraps (or attaches to) its own
proxy and patches `globalThis.fetch` in-process: every model-API HTTP request
is rewritten to `<proxy>/bili/<upstream-url>`, and the extension stamps the
Expand Down
2 changes: 2 additions & 0 deletions docs/clients.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,8 @@ Pi 有完整原生模式(`bili plugin install pi`,README 快速上手方案 1);

**子代理配置(#2230)。** 内置 `acp_delegate` 面(三个 delegate 工具、角色、fleet 检查器——由 `bili pi` 经内嵌扩展接线)配置在 bili 自己的配置文件:`~/.config/billion-context/billion-context.json` 的 `pi.subagents` 段(布尔简写 `"pi": {"subagents": false}` 可整体关闭)。`~/.pi/acp.json` 的四键(`delegate` / `delegatePrompt` / `displayUsage` / `debug`)是已废弃的回退源——仅当段缺失时读取,段存在后完全忽略。完整字段表与 `PI_ACP_DELEGATE_*` 环境变量见 configuration.zh-CN.md 的 [`pi`](configuration.zh-CN.md#pi) 段。

**nudge 可见性(模型零上下文成本,看代理注入了什么)。** 打开全局 debug 开关(`ACP_DEBUG=1` 或配置文件 `"debug": true`)后,代理每次在压缩中注入 nudge,都会在终端以**一次性临时通知**显示——每个用户 turn 一次,且在该轮模型回答之后——显示的是**逐字 wire 原文**,即模型当轮实际读到的那条临时尾随 user 消息,一字不差。通知只进终端:从不写入 session 文件,也不给模型上下文增加任何东西(nudge 进模型是既有机制的职责,这个视图只是让人看到它发生)。仅 pi inline 模式有效——spawn/attach 下代理是独立进程,看不到;覆盖 Anthropic 与 OpenAI 两条 wire 车道(pi 走 HTTP 仅有的两条);宿主没有 `ui.notify` 时此功能静默缺席。

**路由机制。** pi 扩展自行拉起(或附着)代理并进程内 patch `globalThis.fetch`:所有模型 API 的 HTTP 请求被改写到 `<proxy>/bili/<upstream-url>`,扩展经 pi 的 `before_provider_headers` 事件盖 `x-bili-plugin*` 头。所有 HTTP 系 provider(Anthropic、OpenAI chat/completions/responses、Gemini、Mistral、OpenRouter、Azure、自定义中转……)走这条路,得到具名 plugin-mode 会话。

**搭配 pi-claude-bridge:压缩状态不跨 reopen/resume(#3429)。** pi-claude-bridge 每次 pi 会话启动都会拉起一个**全新的 Claude Code 子进程**,该子进程在每个模型请求上盖自己的 `x-claude-code-session-id`——pi 的稳定会话 id 根本不上这条 HTTP。bili 按它看到的 id verbatim 键控会话(此处即 `x-claude-code-session-id`),所以 reopen/resume/fork 之后桥的新 CC id 映射到空会话:已折叠历史与压缩账本不延续,launcher/native `compress` 对 pi id 返回 404(未知 plugin 会话)——同一根机制,不是两个 bug。这是桥侧的身份缺口,不是 bili 缺陷:内容从不丢失或损坏,只是压缩的*状态*重置。根治属于 pi-claude-bridge(让 CC session id 从 pi 会话 id 稳定派生);在那之前,把 pi+claude-bridge 当纯代理模式看待上下文管理。
Expand Down
1 change: 1 addition & 0 deletions reference/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,7 @@ billion-context/
│ ├── notice-store.ts # Notice dismissal receipts in unified kv_store, legacy file fallback (#5548)
│ ├── notices.ts # Built-in notice registry: activity predicates + i18n key table (#5548)
│ ├── nudge-decide.ts # Model-decided nudge timing over the already-cached prefix (#2228)
│ ├── nudge-debug.ts # Nudge-injection bus: mirrors the exact wire nudge text to the pi lane's debug terminal notify (transient, never in LLM context, never persisted)
│ ├── order-persist.ts # Persists session-order skeletons across restarts (#3397)
│ ├── pack-install.ts # bili pack install|remove|list: npm-distributable prompt packs (#5319)
│ ├── pck-notice.ts # One-time notice for the prompt_cache.routing default flip (#5079)
Expand Down
46 changes: 45 additions & 1 deletion src/agent/pi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { wrapCacheReport, wrapRuleReport } from "../acp-panel.js";
import { onNudgeInjected, type NudgeDebugEvent } from "../nudge-debug.js";
import { awaitNativeProxyOrigin } from "./native-bootstrap.js";
import { disposeSubagentSelfReg, selfRegisterForSession, type SubagentSelfRegState } from "./pi-subagent-registry.js";
import { isModelApiUrl, nativeInterceptInstalled } from "./native-intercept.js";
Expand All @@ -25,7 +26,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, guardrailBashTimeout, guardrailMaxOutputBytes, guardrailRepetition } from "../knobs.js";
import { allowPrivateHttpProviders, debugEnabled, guardrailBashTimeout, guardrailMaxOutputBytes, guardrailRepetition } from "../knobs.js";
import { hostProfileFor } from "../host-profiles.js";

export type Ctx = {
Expand Down Expand Up @@ -891,6 +892,20 @@ export function createPiDirectSendGuard(): (url: string, input: string | URL | R
};
}

// Nudge-debug wiring guard: the bus subscription is process-global (the
// emitters live in this same bundle in inline mode), so wire it at most once
// even if a host ever re-invokes the factory.
// Nudge debug surface (transient terminal view only) — module-level because
// the bus subscription is process-singleton:
// nudgeDebugWired: the onNudgeInjected listener registered exactly once.
// nudgeFullPending: the latest injected nudge, consumed (and cleared) by the
// after_provider_response hook once the model has answered.
// nudgeNotifiedTurns: (sessionId → turnKey) dedup — emergency nudges
// re-inject on every LLM call of a turn; notify at most once per turn.
let nudgeDebugWired = false;
const nudgeNotifiedTurns = new Map<string, string>();
let nudgeFullPending: NudgeDebugEvent | null = null;

export function createBiliPlugin(agentOverride?: string, opts?: { retryIntervalMs?: number }): (pi: ExtensionAPI) => void {
return function biliPlugin(pi: ExtensionAPI): void {
const agent = agentName(agentOverride);
Expand Down Expand Up @@ -1102,6 +1117,35 @@ export function createBiliPlugin(agentOverride?: string, opts?: { retryIntervalM
return box;
});
}
// Nudge debug view (transient only, gated on the debug switch —
// ACP_DEBUG / config `debug`): when the proxy injects a nudge (the
// ephemeral trailing user message the model reads), the VERBATIM wire
// text is shown once per user turn as a terminal notification after
// the model has answered. Nothing is persisted and nothing is added
// to model context. Engine-side emitter: same bundle/process in the
// default INLINE pi mode (spawn/attach proxies are separate processes
// — no bus listener, feature inert there; docs/clients.md).
if (agent === "pi") {
if (!nudgeDebugWired) {
nudgeDebugWired = true;
onNudgeInjected((event) => {
nudgeFullPending = event;
});
}
pi.on("after_provider_response", ((_event: unknown, ctx: Ctx) => {
const pending = nudgeFullPending;
nudgeFullPending = null;
if (pending === null || !debugEnabled()) return;
if (nudgeNotifiedTurns.get(pending.sessionId) === pending.turnKey) return;
nudgeNotifiedTurns.set(pending.sessionId, pending.turnKey);
try {
const example = pending.topRange !== null ? `\n\nExample: compress({ content: [{ startId: "${pending.topRange.startRef}", endId: "${pending.topRange.endRef}", summary: "..." }] })` : "";
ctx.ui?.notify?.(`[ACP nudge → context]${pending.emergency ? " [EMERGENCY]" : ""}\n${pending.text}${example}`);
} catch {
// host UI unavailable — best-effort display
}
}) as unknown as (...args: unknown[]) => void);
}
const piCommands = piCommandsEnabled();
if (typeof pi.registerCommand === "function") {
if (piCommands.has("acp")) {
Expand Down
10 changes: 10 additions & 0 deletions src/knobs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -775,6 +775,16 @@ export function dump4xxEnabled(): boolean {
return fileDiag().dump4xx === true;
}

/** ACP_DEBUG > debug > false — the existing global verbose-debug switch,
* resolved EXACTLY like Options.debug (src/config.ts): same expression, so
* the two surfaces can never disagree on any input. Reused by the
* pi-lane nudge debug surface (src/nudge-debug.ts / src/agent/pi.ts) so the
* feature rides the familiar debug switch instead of adding a knob of its
* own. */
export function debugEnabled(): boolean {
return (process.env.ACP_DEBUG ?? (loadConfigFile().debug ? "1" : "0")) === "1";
}

/** BILI_DUMP_4XX_MAX_BYTES > diagnostics.dump4xxMaxBytes > 2 MiB (floor 1 KiB). */
export function dump4xxMaxBytes(): number {
const envRaw = process.env.BILI_DUMP_4XX_MAX_BYTES;
Expand Down
143 changes: 143 additions & 0 deletions src/nudge-debug.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
// Nudge-injection debug surface: a tiny in-process pub/sub carrying the nudge
// a prepare stage just injected as the ephemeral trailing user message (final
// wrapped wire text, post renderNudgeText + withFirstSightDrain/
// withSummaryBudgetNote/withMarkerIntegrityNote — the exact string on the
// wire, not the pre-wrapper template).
//
// Display contract: the nudge ITSELF goes to the model — that is the
// pre-existing nudge mechanism's job (the model must read it to call
// compress); this module adds nothing to model context. The pi lane mirrors
// the injection to the TERMINAL ONLY, gated on the debug switch
// (debugEnabled() — ACP_DEBUG > config `debug` > false): once the model has
// answered a request that carried a nudge, the verbatim wire text is shown
// as a transient terminal notification (pi.ui.notify), at most once per user
// turn (per-turn dedup, turnKey: emergency nudges re-inject on every LLM
// call of a turn). Nothing is written to the session file.
//
// Why a bus and not a log line: the nudge text IS the thing under debugging —
// "what did the model actually read this round" — and grepping a log file
// after the fact hides the placement (which turn, which arm).
//
// Process scope: the bus is a module-level singleton. It reaches the pi
// extension because BOTH live inside the same dist bundle + process in the pi
// lane's default INLINE mode (dist/agent/pi-native.js bundles pi.ts AND
// inline-engine.ts AND the prepare modules — tsup splitting:false). In
// spawn/attach mode the proxy is a separate process holding its own bundle
// copy: no listener ever fires there and the feature is inert (documented in
// docs/clients.md en+zh, Pi section).

type NudgeDebugKind = "advisory" | "directive" | "fallback";

export type NudgeDebugEvent = {
/** bili session id the nudge armed under (not the host session id). */
sessionId: string;
/** Wire family that carried the nudge ("anthropic" | "openai"). */
protocol: string;
/** Which injection arm fired: legacy/over-limit advisory, model-decided
* directive (#2228), or decide-ladder fallback advisory. */
kind: NudgeDebugKind;
/** Nudge tier (1 = gentle, 2+ = distillation pressure); null when the
* nudge is not tier-based (legacy over-limit/emergency). */
tier: number | null;
/** Why the nudge armed (turn.nudge.reason). */
reason: string;
/** Context usage at decision time, whole percent. */
pct: number;
/** Emergency arm (breakdown.emergencyOverride) — record line marks it. */
emergency: boolean;
/** Largest compressible range by tokens (the record line's suggestion),
* or null when the nudge carried no ranges. */
topRange: { startRef: string; endRef: string } | null;
/** Identity of the user message this nudge belongs to (the LAST user
* message of the pre-nudge conversation). One record line per
* (session, turnKey) — emergency re-injections within a turn collapse. */
turnKey: string;
/** The FINAL wrapped wire text, verbatim (debug display only — shown
* transiently in the terminal, never persisted). */
text: string;
ts: number;
};

/** Minimal structural view of the kernel NudgeDecision the emit sites have
* in scope — keeps this module free of a kernel import. */
type NudgeDecisionView = {
tier: number | null;
reason: string;
contextUsage: number;
breakdown?: { emergencyOverride?: number } | null;
compressibleRanges?: Array<{ startRef: string; endRef: string; tokens: number }> | null;
};

/** Fields shared by every emit site of a turn — computed once at the top of
* the injection block (see prepare-anthropic.ts / prepare-openai.ts). */
type NudgeDebugMeta = Pick<NudgeDebugEvent, "tier" | "reason" | "pct" | "emergency" | "topRange" | "turnKey">;

export function nudgeDebugMeta(nudge: NudgeDecisionView, preNudgeMessages: Array<{ role?: string; content?: unknown }>): NudgeDebugMeta {
const top = [...(nudge.compressibleRanges ?? [])].sort((a, b) => b.tokens - a.tokens)[0] ?? null;
return {
tier: nudge.tier,
reason: nudge.reason,
pct: Math.round(nudge.contextUsage * 100),
emergency: nudge.breakdown?.emergencyOverride === 1,
topRange: top !== null ? { startRef: top.startRef, endRef: top.endRef } : null,
turnKey: nudgeTurnKey(preNudgeMessages),
};
}

/** Cheap identity key for the LAST user message with TEXT content (before
* the nudge append): length + djb2 of the first 512 chars. On the anthropic
* wire, tool results come back as role:"user" with tool_result blocks (no
* text) — they are skipped, so the key stays stable across a turn's tool
* loop and the per-turn record dedup collapses re-injections. A collision
* only ever costs one record line. */
export function nudgeTurnKey(messages: Array<{ role?: string; content?: unknown }>): string {
for (let i = messages.length - 1; i >= 0; i--) {
const m = messages[i];
if (m === undefined || m.role !== "user") continue;
const c = m.content;
const text =
typeof c === "string"
? c
: Array.isArray(c)
? c.map((p) => (typeof p === "string" ? p : (p as { text?: string } | null)?.text ?? "")).join("")
: "";
if (text.length === 0) continue;
return `${text.length}:${djb2(text.slice(0, 512))}`;
}
return "0:0";
}

function djb2(s: string): number {
let h = 5381;
for (let i = 0; i < s.length; i++) {
h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
}
return h;
}

type NudgeDebugListener = (event: NudgeDebugEvent) => void;

const listeners = new Set<NudgeDebugListener>();

/** Subscribe; returns an unsubscribe function. */
export function onNudgeInjected(listener: NudgeDebugListener): () => void {
listeners.add(listener);
return () => listeners.delete(listener);
}

/** Fire-and-forget emit. A throwing listener must never break the request
* pipeline — injection already happened on the wire when this fires. */
export function emitNudgeInjected(event: NudgeDebugEvent): void {
for (const listener of [...listeners]) {
try {
listener(event);
} catch {
// debug surface only — swallow
}
}
}

/** Test seam: drop all listeners between cases. */
export function _resetNudgeDebugForTest(): void {
listeners.clear();
}
Loading
Loading