diff --git a/docs/clients.md b/docs/clients.md index e0819f6151..6f177f15e2 100644 --- a/docs/clients.md +++ b/docs/clients.md @@ -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 `/bili/`, and the extension stamps the diff --git a/docs/clients.zh-CN.md b/docs/clients.zh-CN.md index 24d9a97b65..d942693270 100644 --- a/docs/clients.zh-CN.md +++ b/docs/clients.zh-CN.md @@ -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 请求被改写到 `/bili/`,扩展经 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 当纯代理模式看待上下文管理。 diff --git a/reference/architecture.md b/reference/architecture.md index 41bc0ffb6a..2800e7a1d1 100644 --- a/reference/architecture.md +++ b/reference/architecture.md @@ -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) diff --git a/src/agent/pi.ts b/src/agent/pi.ts index 83792937a7..b858f3eed8 100644 --- a/src/agent/pi.ts +++ b/src/agent/pi.ts @@ -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"; @@ -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 = { @@ -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(); +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); @@ -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")) { diff --git a/src/knobs.ts b/src/knobs.ts index c9649ceeeb..091ff4247f 100644 --- a/src/knobs.ts +++ b/src/knobs.ts @@ -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; diff --git a/src/nudge-debug.ts b/src/nudge-debug.ts new file mode 100644 index 0000000000..a65a41bc2c --- /dev/null +++ b/src/nudge-debug.ts @@ -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; + +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(); + +/** 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(); +} diff --git a/src/server/prepare-anthropic.ts b/src/server/prepare-anthropic.ts index a7b1908856..1268575ec1 100644 --- a/src/server/prepare-anthropic.ts +++ b/src/server/prepare-anthropic.ts @@ -10,6 +10,7 @@ import { pluginAgentHeader } from "../plugin.js"; import { applyReasoningDrop, dedupeAdjacentOutputConfig, diagNudge, diagTagSummary, deriveTitle, effectiveTokenCount, imageBillingFor, imageReserveFor, imageTokenCapFor, isAutoInjectedNotification, planReasoningDrop, reapOrphansLogged, runNudgeDecision, stripKernelSummaries, warnAnthropicThinkingPairs, type Prepared } from "../server.js"; import { recordNudgeObservation } from "../context-analysis.js"; import { buildDecisionPrompt, buildDirectiveText, consumeFallback, ladderMode, resolveDecisionRange, stripDecisionReasoningFields, type DecideConfig } from "../nudge-decide.js"; +import { emitNudgeInjected, nudgeDebugMeta } from "../nudge-debug.js"; import { excludeDeadRefRanges } from "../acp-status.js"; import { reconcileFoldCoverage, noteSystemPromptFingerprint, resolveFoldReconcileMode } from "../fold-reconcile.js"; import { maybeSnapshotView } from "./snapshot-render.js"; @@ -520,14 +521,20 @@ export async function prepareAnthropic( // anything else injects nothing this round. EMERGENCY arms and // tier>=2 distillation keep the legacy advisory below. const useDecide = decide !== undefined && turn.nudge.tier === 1 && turn.nudge.breakdown.emergencyOverride !== 1; + // Nudge debug record fields (billion-context-pi #326 parity) — + // computed from the PRE-nudge array so the turnKey is the user + // message, stable across the turn's re-injections. + const nudgeMeta = nudgeDebugMeta(turn.nudge, rebuiltMessages); if (useDecide && ladderMode(session.metadata) === "fallback") { consumeFallback(session.metadata); try { const rendered = renderNudgeText(turn.nudge, prompts, surface?.nudgeSections, "anthropic"); const renderedWithPayload = rendered.text; if (rendered.text) { - rebuiltMessages = insertBeforeTrailingSystemRun(rebuiltMessages, [{ role: "user", content: withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(renderedWithPayload, turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers) }]); + const wireText = withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(renderedWithPayload, turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers); + rebuiltMessages = insertBeforeTrailingSystemRun(rebuiltMessages, [{ role: "user", content: wireText }]); nudgeOutcome = "injected"; + emitNudgeInjected({ sessionId, protocol: "anthropic", kind: "fallback", text: wireText, ts: Date.now(), ...nudgeMeta }); } else { nudgeOutcome = "skipped"; } @@ -549,8 +556,10 @@ export async function prepareAnthropic( if (outcome.kind === "yes") { const span = resolveDecisionRange(outcome, ranges); if (span) { - rebuiltMessages = insertBeforeTrailingSystemRun(rebuiltMessages, [{ role: "user", content: withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(buildDirectiveText(span.startRef, span.endRef, outcome.topic), turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers) }]); + const wireText = withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(buildDirectiveText(span.startRef, span.endRef, outcome.topic), turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers); + rebuiltMessages = insertBeforeTrailingSystemRun(rebuiltMessages, [{ role: "user", content: wireText }]); nudgeOutcome = "injected"; + emitNudgeInjected({ sessionId, protocol: "anthropic", kind: "directive", text: wireText, ts: Date.now(), ...nudgeMeta }); } else { nudgeOutcome = "skipped"; log("info", `[${sessionId}] [acp-decide] yes but no live range left to target — skipping injection`); @@ -565,8 +574,10 @@ export async function prepareAnthropic( const rendered = renderNudgeText(turn.nudge, prompts, surface?.nudgeSections, "anthropic"); const renderedWithPayload = rendered.text; if (rendered.text) { - rebuiltMessages = insertBeforeTrailingSystemRun(rebuiltMessages, [{ role: "user", content: withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(renderedWithPayload, turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers) }]); + const wireText = withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(renderedWithPayload, turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers); + rebuiltMessages = insertBeforeTrailingSystemRun(rebuiltMessages, [{ role: "user", content: wireText }]); nudgeOutcome = "injected"; + emitNudgeInjected({ sessionId, protocol: "anthropic", kind: "advisory", text: wireText, ts: Date.now(), ...nudgeMeta }); } else { nudgeOutcome = "skipped"; } diff --git a/src/server/prepare-openai.ts b/src/server/prepare-openai.ts index 84a453fcee..bc6b0ae882 100644 --- a/src/server/prepare-openai.ts +++ b/src/server/prepare-openai.ts @@ -13,6 +13,7 @@ import { applyReasoningDrop, diagNudge, diagTagSummary, deriveTitle, effectiveTo import { recordNudgeObservation } from "../context-analysis.js"; import { yieldToEventLoop } from "../yield-loop.js"; import { buildDecisionPrompt, buildDirectiveText, consumeFallback, ladderMode, resolveDecisionRange, stripDecisionReasoningFields, type DecideConfig } from "../nudge-decide.js"; +import { emitNudgeInjected, nudgeDebugMeta } from "../nudge-debug.js"; import { excludeDeadRefRanges } from "../acp-status.js"; import { reconcileFoldCoverage, noteSystemPromptFingerprint, resolveFoldReconcileMode } from "../fold-reconcile.js"; import { maybeSnapshotView } from "./snapshot-render.js"; @@ -489,14 +490,20 @@ export async function prepareOpenai( // gentle/over-limit T1 arms ask the model first; EMERGENCY and // tier>=2 keep the legacy advisory. const useDecide = decide !== undefined && turn.nudge.tier === 1 && turn.nudge.breakdown.emergencyOverride !== 1; + // Nudge debug record fields (billion-context-pi #326 parity) — + // computed from the PRE-nudge array so the turnKey is the user + // message, stable across the turn's re-injections. + const nudgeMeta = nudgeDebugMeta(turn.nudge, rebuiltMessages); if (useDecide && ladderMode(session.metadata) === "fallback") { consumeFallback(session.metadata); try { const rendered = renderNudgeText(turn.nudge, prompts, surface?.nudgeSections, "openai"); const renderedWithPayload = rendered.text; if (rendered.text) { - rebuiltMessages = [...rebuiltMessages, { role: "user", content: withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(renderedWithPayload, turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers) }]; + const wireText = withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(renderedWithPayload, turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers); + rebuiltMessages = [...rebuiltMessages, { role: "user", content: wireText }]; nudgeOutcome = "injected"; + emitNudgeInjected({ sessionId, protocol: "openai", kind: "fallback", text: wireText, ts: Date.now(), ...nudgeMeta }); } else { nudgeOutcome = "skipped"; } @@ -516,8 +523,10 @@ export async function prepareOpenai( if (outcome.kind === "yes") { const span = resolveDecisionRange(outcome, ranges); if (span) { - rebuiltMessages = [...rebuiltMessages, { role: "user", content: withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(buildDirectiveText(span.startRef, span.endRef, outcome.topic), turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers) }]; + const wireText = withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(buildDirectiveText(span.startRef, span.endRef, outcome.topic), turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers); + rebuiltMessages = [...rebuiltMessages, { role: "user", content: wireText }]; nudgeOutcome = "injected"; + emitNudgeInjected({ sessionId, protocol: "openai", kind: "directive", text: wireText, ts: Date.now(), ...nudgeMeta }); } else { nudgeOutcome = "skipped"; log("info", `[${sessionId}] [acp-decide] yes but no live range left to target — skipping injection`); @@ -534,8 +543,10 @@ export async function prepareOpenai( const rendered = renderNudgeText(turn.nudge, prompts, surface?.nudgeSections, "openai"); const renderedWithPayload = rendered.text; if (rendered.text) { - rebuiltMessages = [...rebuiltMessages, { role: "user", content: withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(renderedWithPayload, turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers) }]; + const wireText = withMarkerIntegrityNote(withSummaryBudgetNote(withFirstSightDrain(renderedWithPayload, turn.nudge.reason, externalSummaryEnabled(config)), externalSummaryEnabled(config)), visibilityMarkers); + rebuiltMessages = [...rebuiltMessages, { role: "user", content: wireText }]; nudgeOutcome = "injected"; + emitNudgeInjected({ sessionId, protocol: "openai", kind: "advisory", text: wireText, ts: Date.now(), ...nudgeMeta }); } else { nudgeOutcome = "skipped"; } diff --git a/tests/nudge-debug.test.ts b/tests/nudge-debug.test.ts new file mode 100644 index 0000000000..2e413d8f66 --- /dev/null +++ b/tests/nudge-debug.test.ts @@ -0,0 +1,338 @@ +// Nudge debug surface: the prepare stage must mirror the EXACT nudge wire +// text it injects into the in-process bus (src/nudge-debug.ts); the pi lane +// shows it as a TRANSIENT terminal notification (debug switch on — +// ACP_DEBUG / config `debug`), once per user turn, never persisted. The nudge +// itself going to the model is the pre-existing mechanism's job; this module +// adds nothing to model context. +// Gold assertion: the bus event text is BYTE-IDENTICAL to the trailing user +// message content the proxy actually sent upstream — the human in pi sees +// exactly what the model read, and nothing more. +import assert from "node:assert/strict"; +import fs from "node:fs"; +import http from "node:http"; +import os from "node:os"; +import path from "node:path"; +import { once } from "node:events"; +import test from "node:test"; + +process.env.NODE_ENV = "test"; + +import { defaultConfig } from "acp-kernel"; +import { startServer } from "../src/server.ts"; +import type { ProxyOptions } from "../src/config.ts"; +import { SessionStore, _setStoreForTest } from "../src/persist.ts"; +import { _setForTest as setRegistryForTest } from "../src/registry.ts"; +import { emitNudgeInjected, onNudgeInjected, _resetNudgeDebugForTest, nudgeDebugMeta, nudgeTurnKey, type NudgeDebugEvent } from "../src/nudge-debug.ts"; +import { debugEnabled } from "../src/knobs.ts"; +import { createBiliPlugin } from "../src/agent/pi.ts"; + +// ---------- bus unit ---------- + +test("nudge-debug bus: emit reaches subscribers; unsubscribe works; a throwing listener is isolated", () => { + _resetNudgeDebugForTest(); + const seen: NudgeDebugEvent[] = []; + const off = onNudgeInjected((e) => seen.push(e)); + let afterThrow = false; + const bad = onNudgeInjected(() => { + throw new Error("boom"); + }); + const later = onNudgeInjected(() => { + afterThrow = true; + }); + const ev: NudgeDebugEvent = { sessionId: "s1", protocol: "anthropic", kind: "advisory", tier: null, reason: "r", pct: 92, emergency: false, topRange: null, turnKey: "42:123456", text: "T", ts: 1 }; + emitNudgeInjected(ev); + assert.deepEqual(seen, [ev]); + assert.ok(afterThrow, "a throwing listener must not break later subscribers"); + off(); + emitNudgeInjected(ev); + assert.equal(seen.length, 1, "unsubscribed listener must not fire"); + bad(); + later(); + _resetNudgeDebugForTest(); +}); + +// ---------- knob (debugEnabled reuses the global debug switch) ---------- + +test("debugEnabled: ACP_DEBUG env wins; file `debug` tier; default off; only the literal 1 enables", () => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "bili-nudge-debug-cfg-")); + const cfg = path.join(root, "config.jsonc"); + const savedEnv = process.env.ACP_DEBUG; + const savedCfg = process.env.BILI_CONFIG_FILE; + try { + process.env.BILI_CONFIG_FILE = cfg; + fs.writeFileSync(cfg, "{}"); + if (savedEnv !== undefined) process.env.ACP_DEBUG = savedEnv; + else delete process.env.ACP_DEBUG; + assert.equal(debugEnabled(), false, "default off"); + fs.writeFileSync(cfg, '{ "debug": true }'); + assert.equal(debugEnabled(), true, "file tier"); + process.env.ACP_DEBUG = "0"; + assert.equal(debugEnabled(), false, "env '0' beats file true"); + process.env.ACP_DEBUG = "true"; + assert.equal(debugEnabled(), false, "only literal '1' enables (matches Options.debug)"); + fs.writeFileSync(cfg, "{}"); + process.env.ACP_DEBUG = "1"; + assert.equal(debugEnabled(), true, "env '1' wins over file false"); + } finally { + if (savedEnv === undefined) delete process.env.ACP_DEBUG; + else process.env.ACP_DEBUG = savedEnv; + if (savedCfg === undefined) delete process.env.BILI_CONFIG_FILE; + else process.env.BILI_CONFIG_FILE = savedCfg; + fs.rmSync(root, { recursive: true, force: true }); + } +}); + +// ---------- turn key (per-turn dedup for the terminal notify) ---------- + +test("nudgeTurnKey: identity of the last TEXT user message; tool-only tails do not move it", () => { + const u = { role: "user", content: "please fix the ledger bug" }; + const a = { role: "assistant", content: "on it" }; + const t1 = nudgeTurnKey([u, a]); + // anthropic wire: tool results come back as role:"user" with tool_result + // blocks (no text) — they must NOT change the key, or the per-turn record + // dedup could not collapse a turn's re-injections. + const toolResult = { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: "ok" }] }; + assert.equal(nudgeTurnKey([u, a, toolResult]), t1, "tool_result tail keeps the key"); + assert.notEqual(nudgeTurnKey([{ role: "user", content: "a different ask" }]), t1, "different user message → different key"); + assert.equal(nudgeTurnKey([a]), "0:0", "no user message at all"); +}); + +test("nudgeDebugMeta: pct rounds, emergency flags, top range by tokens", () => { + const meta = nudgeDebugMeta( + { tier: 2, reason: "over-limit", contextUsage: 0.924, breakdown: { emergencyOverride: 0 }, compressibleRanges: [{ startRef: "m1", endRef: "m2", tokens: 400 }, { startRef: "m3", endRef: "m4", tokens: 900 }] }, + [{ role: "user", content: "go" }], + ); + assert.equal(meta.pct, 92); + assert.equal(meta.emergency, false); + assert.deepEqual(meta.topRange, { startRef: "m3", endRef: "m4" }, "largest range by tokens"); + assert.equal(typeof meta.turnKey, "string"); + const emergency = nudgeDebugMeta({ tier: 1, reason: "x", contextUsage: 0.98, breakdown: { emergencyOverride: 1 }, compressibleRanges: [] }, [{ role: "user", content: "go" }]); + assert.equal(emergency.emergency, true); + assert.equal(emergency.topRange, null, "no ranges → null"); +}); + +// ---------- pi wiring (both directions, #3617 discipline) ---------- + +test("pi wiring: the nudge terminal-notify hook subscribes on the pi host only", () => { + const savedEnv = process.env.ACP_DEBUG; + try { + if (savedEnv !== undefined) process.env.ACP_DEBUG = savedEnv; + else delete process.env.ACP_DEBUG; + const makeStub = () => { + const events: string[] = []; + return { + events, + on: (name: string) => { events.push(name); }, + fire: () => undefined, + fireAsync: async () => undefined, + registerTool: () => {}, + registerCommand: () => {}, + registerProvider: () => {}, + registerMessageRenderer: () => {}, + getSessionName: () => "test", + }; + }; + const on = makeStub(); + createBiliPlugin("pi")(on as never); + const other = makeStub(); + createBiliPlugin("omp")(other as never); + // The #3248 incremental-ack channel subscribes after_provider_response + // for BOTH lanes unconditionally, so assert the DIFFERENCE: the pi + // host carries exactly one extra subscription — the nudge notify hook + // (the debug switch gates the display, not the wiring). + const count = (s: { events: string[] }) => s.events.filter((e) => e === "after_provider_response").length; + assert.ok(count(on) >= 1, "pi host has the after_provider_response hook"); + assert.equal(count(on), count(other) + 1, "pi lane only: exactly one extra after_provider_response subscription vs omp"); + } finally { + if (savedEnv === undefined) delete process.env.ACP_DEBUG; + else process.env.ACP_DEBUG = savedEnv; + } +}); + +// ---------- e2e: emitted text === the wire text actually sent upstream ---------- + +const WINDOW = 15_000; +const MODEL = "claude-test"; +const SYSTEM = "You are a coding agent."; +const ARMED_INPUT_TOKENS = 13_500; + +// 7 messages × ~4400 distinct chars → local estimate ≈51% of WINDOW (below the +// band) so turn 1 stays clean; the upstream-reported usage crosses the +// over-limit band (90%) so turn 2 injects the nudge. +function filler(seed: number, targetChars: number): string { + const para = `Paragraph ${seed}: the ledger module under review passed its integration suite across all four regions without any reported regressions. `; + const unit = Math.max(1, Math.ceil(targetChars / para.length)); + return Array.from({ length: unit }, (_, i) => para.replace(String(seed), `${seed}-${i}`)).join(""); +} + +const ANTHROPIC_MESSAGES = (): Array<{ role: string; content: Array<{ type: string; text: string }> }> => { + const out: Array<{ role: string; content: Array<{ type: string; text: string }> }> = []; + for (let i = 1; i <= 7; i++) { + out.push({ role: i % 2 === 1 ? "user" : "assistant", content: [{ type: "text", text: `Turn ${i}: working session entry. ` + filler(i, 4400) }] }); + } + return out; +}; + +const OPENAI_MESSAGES = (): Array<{ role: string; content: string }> => + ANTHROPIC_MESSAGES().map((m) => ({ role: m.role, content: m.content.map((b) => b.text).join("") })); + +const anthropicSse = (event: string, data: unknown): string => `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`; + +const anthropicReply = (): string => + [ + anthropicSse("message_start", { type: "message_start", message: { id: "msg_r", role: "assistant", usage: { input_tokens: ARMED_INPUT_TOKENS } } }), + anthropicSse("content_block_start", { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } }), + anthropicSse("content_block_delta", { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "ack" } }), + anthropicSse("content_block_stop", { type: "content_block_stop", index: 0 }), + anthropicSse("message_delta", { type: "message_delta", delta: { stop_reason: "end_turn", stop_sequence: null }, usage: { output_tokens: 3 } }), + anthropicSse("message_stop", { type: "message_stop" }), + ].join(""); + +interface Harness { + origin: string; + upstreamUrl: string; + captured: string[]; + close(): Promise; +} + +async function startHarness(wire: "anthropic" | "openai"): Promise { + const captured: string[] = []; + const upstream = http.createServer((req, res) => { + const chunks: Buffer[] = []; + req.on("data", (c: Buffer) => chunks.push(c)); + req.on("end", () => { + captured.push(Buffer.concat(chunks).toString("utf8")); + if (wire === "anthropic") { + res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" }); + res.end(anthropicReply()); + } else { + res.writeHead(200, { "content-type": "application/json" }); + res.end(JSON.stringify({ id: "chat_r", object: "chat.completion", choices: [{ index: 0, message: { role: "assistant", content: "ack" }, finish_reason: "stop" }], usage: { prompt_tokens: ARMED_INPUT_TOKENS, completion_tokens: 3, total_tokens: ARMED_INPUT_TOKENS + 3 } })); + } + }); + }); + upstream.listen(0, "127.0.0.1"); + await once(upstream, "listening"); + const upstreamUrl = `http://127.0.0.1:${(upstream.address() as { port: number }).port}`; + + _setStoreForTest(new SessionStore({ enabled: false })); + setRegistryForTest({}); + const proxy = await startServer({ + port: 0, + host: "127.0.0.1", + upstream: upstreamUrl, + routes: { [upstreamUrl]: { models: { [MODEL]: { context: WINDOW } } } }, + modelContextLimit: WINDOW, + kernelConfig: { ...defaultConfig(WINDOW), nudge: { ...defaultConfig(WINDOW).nudge, minPressureBenefitTokens: 0 } }, + compress: { injectTool: true, injectNudge: true }, + promptCache: { routing: "auto" }, + sessionHeader: "x-acp-session", + log: false, + debug: false, + passthrough: false, + autoUpdate: false, + mitm: { enabled: false, domains: [] }, + } as ProxyOptions); + await once(proxy, "listening"); + const origin = `http://127.0.0.1:${(proxy.address() as { port: number }).port}`; + + return { + origin, + upstreamUrl, + captured, + close: async () => { + proxy.close(); + proxy.closeIdleConnections?.(); + await once(proxy, "close"); + upstream.close(); + upstream.closeIdleConnections?.(); + await once(upstream, "close"); + }, + }; +} + +function textOf(content: string | Array<{ type?: string; text?: string }>): string { + return typeof content === "string" ? content : content.map((b) => b.text ?? "").join(""); +} + +test("nudge-debug e2e (anthropic wire): bus event text is byte-identical to the injected trailing user message", async () => { + const h = await startHarness("anthropic"); + const events: NudgeDebugEvent[] = []; + const off = onNudgeInjected((e) => events.push(e)); + try { + const url = `${h.origin}/bili/${h.upstreamUrl}/v1/messages`; + const post = (session: string) => fetch(url, { + method: "POST", + headers: { "content-type": "application/json", "x-acp-session": session }, + body: JSON.stringify({ model: MODEL, max_tokens: 1024, stream: true, system: SYSTEM, messages: ANTHROPIC_MESSAGES() }), + }); + + const r1 = await post("nudgedbg-anth-a"); + assert.equal(r1.status, 200); + await r1.text(); + assert.equal(events.length, 0, "turn 1 (under the band) injects no nudge"); + + const r2 = await post("nudgedbg-anth-a"); + assert.equal(r2.status, 200); + await r2.text(); + + assert.equal(events.length, 1, "turn 2 (over limit) fires exactly one nudge event"); + const ev = events[0]!; + assert.equal(ev.protocol, "anthropic"); + assert.equal(ev.kind, "advisory", "no decide config in this harness → legacy advisory arm"); + assert.equal(ev.text.length > 0, true, "event carries the verbatim wire text"); + assert.ok(ev.pct >= 0 && ev.pct <= 100, "record metadata: usage percent"); + assert.equal(ev.emergency, false, "the over-limit band here is not the emergency arm"); + assert.ok(typeof ev.turnKey === "string" && ev.turnKey.length > 0, "record metadata: turn key"); + + const body = JSON.parse(h.captured[1]!) as { messages: Array<{ role: string; content: string | Array<{ type?: string; text?: string }> }> }; + const sent = ANTHROPIC_MESSAGES().length; + assert.equal(body.messages.length, sent + 1, "exactly one nudge message appended"); + const last = body.messages[body.messages.length - 1]!; + assert.equal(last.role, "user"); + assert.equal(ev.text, textOf(last.content), "bus event text === the exact bytes sent upstream"); + } finally { + off(); + await h.close(); + } +}); + +test("nudge-debug e2e (openai wire): bus event text is byte-identical to the injected trailing user message", async () => { + const h = await startHarness("openai"); + const events: NudgeDebugEvent[] = []; + const off = onNudgeInjected((e) => events.push(e)); + try { + const url = `${h.origin}/bili/${h.upstreamUrl}/v1/chat/completions`; + const post = (session: string) => fetch(url, { + method: "POST", + headers: { "content-type": "application/json", "x-acp-session": session }, + body: JSON.stringify({ model: MODEL, max_tokens: 1024, messages: OPENAI_MESSAGES() }), + }); + + const r1 = await post("nudgedbg-openai-a"); + assert.equal(r1.status, 200); + await r1.text(); + const r2 = await post("nudgedbg-openai-a"); + assert.equal(r2.status, 200); + await r2.text(); + + assert.equal(events.length, 1, "turn 2 fires exactly one nudge event"); + const ev = events[0]!; + assert.equal(ev.protocol, "openai"); + assert.equal(ev.kind, "advisory"); + + type OMsg = { role: string; content: string | Array<{ type?: string; text?: string }> }; + const t1 = JSON.parse(h.captured[0]!) as { messages: OMsg[] }; + const t2 = JSON.parse(h.captured[1]!) as { messages: OMsg[] }; + // The openai lane injects its own lane message into `messages` on the + // armed turn (see issue3910's non-vacuity guard), so compare against + // the turn-1 count instead of an absolute +1. + assert.equal(t2.messages.length, t1.messages.length + 1, "exactly one nudge message appended vs turn 1"); + const last = t2.messages[t2.messages.length - 1]!; + assert.equal(last.role, "user"); + assert.equal(ev.text, textOf(last.content), "bus event text === the exact bytes sent upstream"); + } finally { + off(); + await h.close(); + } +});