Skip to content

[PR] fix(pi): declare every pi dispatch as the session's main conversation turn - #7077

Merged
ranxianglei merged 2 commits into
masterfrom
design/6884-pi-purpose-declaration
Nov 18, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
design/6884-pi-purpose-declaration

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What is broken (in one sentence)

A pi main-turn request whose body looks like a side request (e.g. pi -p one-shot, or a small max_tokens with no tools in the body → the max_tokens <= 200 heuristic) gets demoted to the #388 side passthrough lane and skips the whole compression pipeline — the conversation's kernel state is lost for that turn.

The fix

pi has an in-process plugin (discussions/6884: pi and dsh are the only hosts with one), so pi can declare what a dispatch is, instead of the server guessing from the body:

  1. src/agent/pi.ts — the single before_provider_headers stamp site (covers every pi lane, including native spawn and inline; omp never fires this event so it is untouched) now also stamps x-bili-plugin-purpose: conversation, next to the existing x-bili-plugin / x-bili-plugin-conversation headers.
  2. src/server/handle.ts — when a request carries the pi marker and the conversation purpose, the two isSideRequest call sites feed it as explicit main (the existing opencode v2 title-gen requests get injected with compression philosophy (misclassified by isTitleGen) #1699 rung), so the declaration outranks body-shape guessing. isSideRequest itself is unchanged — all side-lane truth-table pins stay green.

Why the sentinel is not normalized to "absent" for pi

The "conversation" sentinel means different things per client, and only dsh's meaning matches "absent":

What is deliberately untouched

  • src/server/side-request.ts (signature and all heuristics unchanged),
  • dsh title/review/single-shot text clauses (dsh-gated; dsh semantics unchanged),
  • demoteGate (OMP extension injects tools and compression philosophy in helper prompts #1897), prepare-openai/prepare-google internal isTitleGen switches,
  • all persona-order call sites (the pi synthesis only changes which agent string reaches isSideRequest).

Test evidence

  • New tests/issue6884-pi-purpose-declaration.test.ts (5 tests): declared pi main turn on a side-shaped body stays on the full pipeline (1 kernel request, no |sub: ghost); the identical undeclared body still takes the legacy side lane (pin, not regression); no plugin marker → no effect; dsh sentinel asymmetry pin (dsh + conversation on a side-shaped body stays off the pipeline, guarding against a future "normalize all sentinels" change); cross-system-drift parity.
  • 3 stamp pins in tests/plugin-agent.test.ts (extension, pi -p one-shot, post-prewarm).
  • Adjacent suites green: [Design][dsh] Stop guessing dsh's auxiliary requests — the in-process plugin can declare each request's purpose explicitly #6880 purpose-declaration pins, side-lane truth table, plugin-agent, dsh llm-stream attribution (107 tests).
  • tsc --noEmit clean.
  • Full local suite: all 50 failures live in 9 files whose failure set is byte-identical on master vs this branch (network-isolated sandbox: advisory feed 30s timeouts cascading, 15s watchdog false-reds) — zero regressions. The two dsh-host files that hang under the suite wrapper hang identically on master (3 pre-existing orphaned suites found wedged at the same spot) — environmental, predates this change.

Refs: discussions/6884, #6880, #6883

… turn (discussions/6884)

pi has no auxiliary LLM calls (no title-gen, no compaction summarizer, no
auto-review; subagents and forks mint fresh session ids), so the pi plugin
now stamps the x-bili-plugin-purpose "conversation" sentinel on every
dispatch, and the server treats that sentinel from a PI-marked request as a
declared main turn riding the #1699 explicit-main intent rung — it outranks
every body heuristic.

The bug this fixes: a pi main turn whose body happens to match a legacy
side shape — a one-shot `pi -p` with a small maxTokens and no tools, for
example — was demoted by the max_tokens<=200 budget heuristic to the #388
side passthrough and never entered the kernel pipeline: no compression
state, no tools, silent substrate loss on a real conversation turn.

The sentinel deliberately means different things per client: dsh DERIVES
it ("GenerateOptions.purpose was unset" — possibly an unrecognized new aux
feature), so for dsh it stays ≡ absent and the body heuristics classify,
byte-for-byte as before #6880 (pinned). pi's sentinel is a FACT, so it
suppresses the heuristics. The per-client asymmetry is pinned in
tests/issue6884-pi-purpose-declaration.test.ts alongside the declared/
undeclared twin cases.

Refs #6880, discussions/6884
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: design/6884-pi-purpose-declaration (cf33226)

Latest build — install this exact version

npm install -g billion-context@0.0.10669-pr.7077.c92b71f

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

Recent builds (commit → version)

commit version build
cf33226 billion-context@0.0.10669-pr.7077.c92b71f build
c197e4c billion-context@0.0.10660-pr.7077.6e4cf06 build

Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title fix(pi): declare every pi dispatch as the session's main conversation turn [PR] fix(pi): declare every pi dispatch as the session's main conversation turn Nov 17, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Duplicate check: not a duplicate. Searched open + closed issues/PRs for "pi purpose declaration side request x-bili-plugin-purpose" and "pi -p one-shot side passthrough demoted compression pipeline" — zero matches. This is the pi leg of the #6880 declaration channel (the dsh leg is already merged); no parallel work exists.

Review status (code review complete):

  • The fix is correct for the targeted shape (no-tools / small-budget pi main turn). The declaredPiMainTurn synthesis in handle.ts feeds the existing opencode v2 title-gen requests get injected with compression philosophy (misclassified by isTitleGen) #1699 "main" rung, which short-circuits isSideRequest before every body heuristic. Both call sites (sideRequestLike and sideIntent) are updated; git grep confirms no third site was left behind.
  • The trust gate is sound: pluginPurposeHeader is marker-gated (returns a purpose only when x-bili-plugin is present), so an unannounced client cannot spoof the declaration.
  • The dsh sentinel asymmetry is correctly preserved: dsh's "conversation" = "purpose unset" → normalized to absent; pi's "conversation" = a fact (pi has no aux LLM calls) → suppresses the heuristics. Pinned by test feat: OpenAI Responses API support (/v1/responses) #4.
  • Tests are real with teeth (5 new handle-level tests + 3 stamp pins); the diff is clean and scoped.

CI is RED on one mechanical gate: lane-guard (#2170 discipline) — "Side-lane logic changed without updating any dedicated side-lane suite." The PR changed the handle.ts lane call-sites but only added a new test file; the gate requires a pin to land in one of the four dedicated side-lane suites (fork-side-request-lane / side-lane-truth-table / side-lane-invariants / side-request-isolation). Every other check is green.

Fixing it now: adding a handle-level pin to tests/side-lane-invariants.test.ts (the behavior-pin suite with the real-server harness) asserting that a declared pi main turn with a side-shaped body rides the main pipeline. Then re-running. I'll follow up with the full 8-question review.

Labels applied on pickup: bug, pi, scope/kernel, p2.

#7077 lane-guard)

lane-guard (#2170) demands a dedicated side-lane suite move whenever the
lane region of handle.ts changes: #7077's declaredPiMainTurn derivation
rides the #1699 explicit-main rung inside isSideRequest, so the truth
table gains the pi leg of the #6880 sentinel pin — pi + conversation
sentinel outranks the budget heuristic (side-shaped body stays main),
while the same sentinel from dsh stays ≡ absent (heuristic still
demotes), a real pi purpose still declares side, and an unstamped pi
dispatch keeps the pre-#6884 heuristic classification.

Closes the lane-guard failure on head c197e4c.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

lane-guard fixed — green on the new head cf3322680b.

What I did this run:

  1. Re-verified the live check state first: lane-guard was still red on head c197e4cb52, with every downstream lane skipped behind it.
  2. Root cause: the PR's src/server/handle.ts diff touches lane-symbol lines (isSideRequest, sideIntent, "side passthrough") — the declaredPiMainTurn derivation that rides the opencode v2 title-gen requests get injected with compression philosophy (misclassified by isTitleGen) #1699 explicit-"main" rung. lane-guard (dsh 回归防护:泳道判定真值表 + 侧请求不变量 + dsh e2e lane + 运行时金丝雀 + lane-guard(5 项) #2170) requires a dedicated side-lane suite to move with any lane-logic edit; the PR landed its coverage in a new standalone file (tests/issue6884-pi-purpose-declaration.test.ts) instead of one of the four pinned suites, so the guard failed even though the behavior IS covered.
  3. Fix: added the pi leg of the [Design][dsh] Stop guessing dsh's auxiliary requests — the in-process plugin can declare each request's purpose explicitly #6880 sentinel pin to tests/side-lane-truth-table.test.ts — the derivation pinned exactly as handle.ts applies it, both directions (gate discipline Test Blind Spot Retrospective: Reinforcing Negative Assertion Discipline, Tightening Fake Upstream Strictness, Thin Inst | 测试盲区复盘:补反向断言纪律、假上游严格化、薄安装冒烟、形态矩阵与生命周期覆盖 #3617):
  4. Verified locally before pushing: truth-table suite 15/15 pass, the PR's own issue6884 suite 5/5 pass, npm run typecheck clean, and the lane-guard script logic simulated green on the new head.
  5. Pushed as the final head (unmarked, per CI-hold discipline — this is the branch's one full CI pass): c197e4cb52..cf3322680b, fast-forward, no force-push.
  6. Verified live afterwards: lane-guard → success; all guard jobs green (kernel-guard, docs-sync, docs-coverage, unused-exports, lock-sync, test-import-graph, architecture-docs, pi-subagents-guard, version-guard); no failures among the 51 check runs (25 success, 13 gated-skip, remainder of the test/e2e lanes still running).

七问:

  1. 是什么问题: lane-guard CI 红——PR 改了 handle.ts 的 side-lane 判定逻辑,但四个专用 side-lane 测试套件一个都没动,guard 按 dsh 回归防护:泳道判定真值表 + 侧请求不变量 + dsh e2e lane + 运行时金丝雀 + lane-guard(5 项) #2170 纪律拦下,PR 无法合并。
  2. 什么原因导致的: PR 的回归覆盖写进了新文件 tests/issue6884-pi-purpose-declaration.test.ts(端到端行为测试),而 lane-guard 机械要求 lane 逻辑变更必须伴随 tests/(fork-side-request-lane|side-lane-truth-table|side-lane-invariants|side-request-isolation).test.ts 之一的变更——覆盖存在,但没落在 guard 认的套件里。
  3. 影响范围与严重程度: 仅 CI 门禁,不影响发布物或运行时行为;触发条件 = 本 PR 的 handle.ts diff,严重度 = 阻塞合并,不影响任何用户。
  4. 怎么修复的: 在 tests/side-lane-truth-table.test.ts 补上 [Design][dsh] Stop guessing dsh's auxiliary requests — the in-process plugin can declare each request's purpose explicitly #6880 sentinel 的 pi 腿真值表钉——按 handle.ts 的推导原样钉住(pi + conversation sentinel 骑 opencode v2 title-gen requests get injected with compression philosophy (misclassified by isTitleGen) #1699 显式 main 档,压过 budget≤200 启发式;dsh 同 sentinel 仍 ≡ 缺失,启发式照常降级;真实 purpose 仍声明 side;未盖章 pi 保持 跨 agent 核查:「session id = 唯一会话身份」这条定律,谁满足谁违反(#6880 背景) #6884 前行为),正反两向都断言。
  5. 是否有回归问题: 无。纯测试新增(33 行),零 src 改动;既有 15 个真值表用例全绿,PR 自带 5 个 e2e 用例全绿,typecheck 干净;高危模式逐项过——无语义漂移、无阈值/时序/输出格式变化。
  6. 是否破坏缓存: 不涉及——无运行时/存储/协议/缓存变更。
  7. 是否改了设计方向: 不涉及——只是把 PR 已有的行为钉进 guard 要求的套件,没有引入新配置。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复。 Searched open+closed issues/PRs for "pi purpose declaration side request x-bili-plugin-purpose" and "pi -p one-shot side passthrough demoted compression pipeline" — zero matches. This is the pi leg of the #6880 purpose-declaration channel (the dsh leg is already merged).

Code review: the fix is correct. Verified:

  • The declaredPiMainTurn gate (src/server/handle.ts:1268) is sound: it requires BOTH the pi marker AND the conversation purpose, and pluginPurposeHeader (src/plugin.ts:236) is marker-gated (returns the purpose only when x-bili-plugin is present), so an unannounced client cannot spoof the purpose.
  • Both isSideRequest call sites (handle.ts:1271 in sideRequestLike, handle.ts:2692 in sideIntent) feed the explicit main rung when declared — that rung short-circuits to non-side BEFORE all body heuristics. isSideRequest itself is unchanged, so every side-lane truth-table pin stays green.
  • The dsh sentinel asymmetry is correctly preserved (dsh + conversation stays off the pipeline; pinned by test feat: OpenAI Responses API support (/v1/responses) #4 in the new file).
  • omp is untouched: omp never fires before_provider_headers, so it carries no x-bili-plugin marker, so declaredPiMainTurn can never be true for omp.
  • Tests are real with teeth: 5 handle-level tests (declared pi main turn on a side-shaped body → full pipeline; identical undeclared body → legacy side lane; no marker → no effect; dsh sentinel asymmetry pin; cross-system-drift parity) + 3 stamp pins in tests/plugin-agent.test.ts.

CI: was red on lane-guard (a mechanical discipline gate — the PR changed handle.ts lane-symbol lines but didn't touch a dedicated side-lane suite). The CI automation has already landed a fix (commit cf3322680b) adding a pure-function pin to tests/side-lane-truth-table.test.ts. I verified the lane-guard gate now passes (simulated the gate logic) and the truth-table suite passes locally (15 tests). I dropped my own redundant commit (a handle-level pin in side-lane-invariants.test.ts) since the PR's own test file already carries that pin. CI is re-running on the new head: 0 failures so far, the full-suite test lanes are still in progress (they passed on the first head, and the only change since is an added test file I verified locally).

Residual gap (not a blocker): the demotedSide path (handle.ts:2459) uses demoteGate, which does NOT reference the pi declaration. So a declared pi main turn whose tools array is ENTIRELY bili's own tools (no host tools, no ACP artifacts) would still be demoted via the #1897 strip path. This is a narrow shape (requires a toolless pi config where bili's tools are the only registered tools); the PR's target shape (no tools in the body) IS fixed. The PR body explicitly says demoteGate (#1897) is deliberately untouched. Flagging for your awareness — if you want the pi declaration to also override the #1897 strip path, that's a small follow-up.

Verdict: mergeable (once the test lanes finish green).


结构化八问

  1. 是什么问题: 一个 pi 主对话轮的请求,如果 body 看起来像 side request(没有 tools 字段,或 max_tokens ≤ 200),会被降级到 side passthrough 车道,跳过整个压缩管道——该轮的 kernel 状态丢失。
  2. 什么原因导致的: 服务端从 body 形状猜测一个请求是不是 side request(没有 tools、max_tokens ≤ 200)。pi 没有任何辅助 LLM 调用,所以每个 pi dispatch 都是主对话轮,但 body 形状启发式不知道这一点——它会把一个恰好长得像 side 的 pi 主对话轮降级。
  3. 影响范围与严重程度: 受影响:pi 客户端(唯一有进程内插件、能声明 purpose 的宿主)。触发条件:一个 body 长得像 side 的 pi 主对话轮(没有 tools,或 max_tokens ≤ 200)。严重程度:该轮跳过压缩管道,kernel 状态不更新——属于「特定条件下有问题」,p2。但范围窄:只影响 body 长得像 side 的 pi 主对话轮;正常的 pi 主对话轮(带宿主 tools)不受影响。
  4. 怎么修复的: pi 现在通过 x-bili-plugin-purpose: conversation 头声明自己的 purpose(在 before_provider_headers handler 里盖戳)。当一个请求同时带 pi marker 和 conversation purpose 时,两个 isSideRequest 调用点把它当作显式 main(opencode v2 title-gen requests get injected with compression philosophy (misclassified by isTitleGen) #1699 档)喂进去,所以声明优先于 body 形状猜测。isSideRequest 函数本身不变。
  5. 是否有回归问题: 审过的既有行为逐项:dsh sentinel 不对称性保留(dsh + "conversation" 仍走 side 车道,新文件测试 feat: OpenAI Responses API support (/v1/responses) #4 钉住);omp 不受影响(omp 从不发 before_provider_headers,不带 x-bili-plugin marker);所有 side-lane truth-table 钉子保持绿(isSideRequest 不变);OMP extension injects tools and compression philosophy in helper prompts #1897 demote 路径(demoteGate)刻意不动(见下方残留缺口);正常的 pi 主对话轮(带宿主 tools)没有回归(本来就不会被降级)。
  6. 是否破坏缓存: 不。改动只影响一个请求走哪条车道(main vs side),不改变 cache key、prefix cache 或任何缓存失效策略。
  7. 是否改了设计方向: 没有。改动是把现有的 [Design][dsh] Stop guessing dsh's auxiliary requests — the in-process plugin can declare each request's purpose explicitly #6880 purpose 声明通道(原本为 dsh)扩展到 pi。不改变架构或车道模型,是现有声明机制的自然延伸。
  8. 是否引入了新的配置: 没有。没有新的 env 变量、config key 或默认值。x-bili-plugin-purpose 头是现有的 wire 头([Design][dsh] Stop guessing dsh's auxiliary requests — the in-process plugin can declare each request's purpose explicitly #6880 为 dsh 引入);这个 PR 只是把 pi 加为一个新的盖戳点。

收工判定: 可合(等 test lanes 跑绿;lane-guard 已由 CI 自动化修好,我本地验证 gate 通过 + 相关套件绿)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

CI is now fully green on the new head (cf3322680b): all 30 checks passed, 0 failures, 0 pending. The lane-guard gate (the only red on the first head) passes with the CI-automation's truth-table pin, and all full-suite test lanes are green.

Final verdict: mergeable, no blockers. The one residual gap (the #1897 demoteGate strip path not referencing the pi declaration — a declared pi main turn with only-bili-tools + no ACP artifacts would still be demoted) is a narrow shape the PR deliberately scoped out; file it as a follow-up if you want the declaration to also override that path.

@ranxianglei
ranxianglei merged commit 6b07dff into master Nov 18, 2026
52 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.1226-master.6b07dff (rolling master tag).

npm install -g billion-context@0.0.1226-master.6b07dff  # this exact build
npm install -g billion-context@master  # always the newest merged build

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

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

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant