Skip to content

[PR] dsh purpose: declare auxiliary requests instead of content-guessing (#6880) - #6883

Merged
ranxianglei merged 3 commits into
masterfrom
design/6880-dsh-purpose-signal
Nov 16, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
design/6880-dsh-purpose-signal

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What & why

The dsh in-process plugin now reads GenerateOptions.purpose off the llm/stream dispatch options and stamps it per fetch as x-bili-plugin-purpose. dsh's contract for that field: set ONLY on auxiliary calls (session-title / compaction / auto-review / timeline-report) — ordinary conversation leaves it unset. So presence of the header is the side/main signal, and bili stops guessing which requests are auxiliary by matching body content (the #2503/#4438/#5656/#5584 template chain, the ≤200-token budget rule).

Background: #6880 (dsh source study — every auxiliary call passes purpose on the same dispatch seam the plugin already listens on).

Changes

Plugin side (src/agent/dsh-native.ts)

  • llm/stream listener captures options.purpose (ASCII-gated, ≤64 chars; absent/junk values simply stay off the wire — same degradation discipline as the sid capture)
  • per-fetch header stamp adds x-bili-plugin-purpose next to x-bili-plugin / x-bili-plugin-conversation

Server side

Rollout safety

  • Old plugin (no purpose header) → byte-identical behavior to today (all heuristics unchanged, persona anchor untouched)
  • New plugin + old server → the header is inert telemetry, server falls back to its heuristics
  • New plugin + new server → declaration-first; text templates only fire if the plugin fails to stamp

Tests

  • new tests/issue6880-purpose-declaration.test.ts: trust gate (purpose without marker is inert), declared title sidecar at 4096 budget with template-drifted text → raw-key passthrough, no-header control, declared compaction under instruction drift → guard still fires (422, zero egress)
  • tests/dsh-llm-stream-attribution.test.ts: plugin-side capture + stamp, junk-value degradation (control chars / >64 / spaces / non-ASCII / non-strings)

Local: typecheck clean, dsh-*/side-*/plugin-* 649/650 (the 1 failure — dsh-tool-registration-lifetime — fails identically on clean HEAD in this environment), server-*/persona-*/compaction-*/title-*/issue* sweep failures verified pre-existing on clean HEAD, unused-exports + test-import-graph gates clean.

…declares it (#6880)

The dsh in-process plugin reads GenerateOptions.purpose off the llm/stream
dispatch options (dsh contract: set ONLY on auxiliary calls —
session-title / compaction / auto-review / timeline-report; ordinary
conversation leaves it unset) and stamps it per fetch as
x-bili-plugin-purpose, next to the existing x-bili-plugin(-conversation)
marker.

Server side:

- plugin.ts: pluginPurposeHeader() — honored only behind the x-bili-plugin
  marker (same trust discipline as the conversation header); an unannounced
  client's purpose header is inert.
- side-request.ts: isSideRequest gains a purpose parameter — a declared
  purpose classifies the request as side by declaration, outranking every
  body heuristic (max_tokens<=200 / system-text templates #2503/#4438/
  #5656/#5584). Those recognizers stay as the fallback for pre-#6880 plugin
  installs. KNOWN_AUXILIARY_PURPOSES documents the set (not a gate).
- handle.ts: both isSideRequest call sites pass the declared purpose (a
  declared side request takes the #388 verbatim passthrough and rides the
  raw persona key — no more |sub:<fp> ghost lanes); the compaction guard
  short-circuits on purpose=compaction so the marker-DECISIVE INSTRUCTION
  text check (#2193) is no longer load-bearing for post-#6880 installs
  while remaining the fallback.

Tests: new tests/issue6880-purpose-declaration.test.ts (trust gate,
declared sidecar at 4096 budget with template-drifted text, no-header
control, unannounced purpose inert, declared compaction survives
instruction drift); dsh-llm-stream-attribution.test.ts covers plugin-side
capture/stamp (including junk-value degradation).
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: design/6880-dsh-purpose-signal (4662b07)

Latest build — install this exact version

npm install -g billion-context@0.0.10311-pr.6883.252ed3c

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
4662b07 billion-context@0.0.10311-pr.6883.252ed3c build
3226c7e billion-context@0.0.10310-pr.6883.f00edcf build
6eb3ac9 billion-context@0.0.10308-pr.6883.e3932a8 build
81937b1 billion-context@0.0.10302-pr.6883.bd6044e build
005ec64 billion-context@0.0.10300-pr.6883.46e898c build

Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title dsh purpose: declare auxiliary requests instead of content-guessing (#6880) [PR] dsh purpose: declare auxiliary requests instead of content-guessing (#6880) Nov 16, 2026
…ard)

The lane-guard job (#2170) requires a side-lane suite edit alongside any
side-request.ts/handle.ts lane change: exhaustively pin isSideRequest's
new purpose argument over agent × purpose × the strongest main-shape body
(main veto outranks declaration; known side agent wins as before; empty/
absent purpose keeps the pre-#6880 table byte-identical), plus the two
blind shapes the template recognizers exist for flipping by declaration
without content matching.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: opencode/qwen3.8-27b)

Duplicate check: not a duplicate — no other open PR touches dsh purpose declaration; this PR is part 1 of #6880's three-part proposal (#6723 is an unrelated batch PR).

Review — PR #6883 (dsh purpose declaration)

① Direction gate (original issue). The PR implements part 1 of #6880's three-part proposal: the in-process dsh plugin declares each auxiliary request's purpose on the llm/stream dispatch seam, and bili classifies by declaration instead of content-guessing. This is the right first slice — self-contained (plugin capture + server trust gate + classification clause), keeps the content heuristics as the fallback for pre-#6880 installs, and deliberately leaves the persona-fork retirement and id-only identity (parts 2–3) as open work. The direction matches the issue: header presence is the side/main signal, and the ≤200-token budget rule stops being load-bearing for post-#6880 installs.

② Regression review (existing-behavior audit). I read the pre-change code on every touched path and judged each existing behavior:

  • Old plugin (no purpose header) → purpose is undefined → every new clause is inert → byte-identical to today. Preserved.
  • New plugin + old server → the header is inert telemetry; the server falls back to its heuristics. Preserved (forward-compatible).
  • Trust model → pluginPurposeHeader() is marker-gated at its definition in src/plugin.ts (returns the value only when x-bili-plugin is present) — stricter than the conversation header, which is consumer-gated. An unannounced client's purpose header is inert; no new attack surface beyond the existing x-bili-plugin-agent: title trust domain. Preserved.
  • main veto → isSideRequest checks agent === "main" → false BEFORE the purpose clause, so a declared purpose can never turn a main turn into a side request. Pinned by the truth-table test. Preserved.
  • Declared side requests ride the raw key → no |sub:<fp> ghost lanes (KDD release v0.1.2 #9: side requests never claim the anchor). Pinned by the new test. Consistent.
  • Compaction guard → declared purpose=compaction short-circuits the guard (422 zero-egress, or the bili-authored client compaction: let the host's own compaction flow run, but bili writes the checkpoint #3733 authored local answer); the marker-DECISIVE INSTRUCTION text check remains the fallback for old installs; the guard runs before the 标题生成等侧请求污染主会话状态:prepareAnthropic 缺 isTitleGen 守卫、快照无条件覆盖、survivedCount 每请求空转 #388 side lane. Preserved (fallback intact).
  • isSideRequest call sites → exactly 2 in src/ (handle.ts:1247, handle.ts:2655); both updated. sideRequestGuard is a size guard only, unaffected. Complete.
  • No kernel change, no config surface, no model-facing text. Clean.
  • Wire-protocol extension (new x-bili-plugin-purpose header) → human review tier per §7.4 (and it is a feat, not auto-mergeable). Flagged.

No unintentional regression found.

③ Code review. The trust gate is correctly placed (marker-gated at definition). The isSideRequest ordering (agent → main-veto → purpose → heuristics) is the right precedence. KNOWN_AUXILIARY_PURPOSES is explicitly documentation, not a gate — correct: a brand-new dsh sidecar purpose needs no bili recognizer. The ASCII/length gate on capture (≤64, /^[\x21-\x7e]+$/) matches the sid-capture degradation discipline.

④ Test validity. The new tests are real, not tautological: they spin up an actual server, send real HTTP requests, and assert on the forwarded body (verbatim), session stats.requests, the sub-session list (no ghost), and 422 + error code + zero egress. The truth-table test is exhaustive over agent × purpose × main-shape. Both gate directions are asserted (#3617): fires when it should (declared title sidecar → passthrough; declared compaction → guard), does not fire when it shouldn't (no marker → inert; no header → legacy; main veto wins; junk value → off the wire).

⑤ Diff cleanliness. 7 files, +371 −10, all on-topic; no unrelated changes, no whitespace churn, no lock-file churn.

⑤b Code cleanliness. Good naming (pluginPurposeHeader, declaredDshCompaction, KNOWN_AUXILIARY_PURPOSES), no dead code, no magic numbers (the 64-char limit and ASCII range are documented), comments explain why, style consistent with the file.

Two log-accuracy findings — fixed directly on the PR branch (labeled commit 6eb3ac95f5, log-only, no behavior change):

  1. sideLane label: a declared-purpose side request (dsh stamps no x-bili-plugin-agent header) was logging as side request (max_tokens<=200) → passthrough — the very diagnosability gap [Design][dsh] Stop guessing dsh's auxiliary requests — the in-process plugin can declare each request's purpose explicitly #6880 closes. The sideLabel chain now leads with declared purpose=<value> (#6880).
  2. Compaction identification log: the authored/refusal logs claimed final user message = COMPACTION_INSTRUCTION as the identification basis even when the call was identified purely by declaration — exactly the text-drift scenario [Design][dsh] Stop guessing dsh's auxiliary requests — the in-process plugin can declare each request's purpose explicitly #6880 targets. Both now log the actual basis via identifiedAs.

CI: in progress at the time of this review (30 checks, 0 failed, 12 pending — test shards running). Local targeted: typecheck clean; the 3 PR test files + lane gates + compaction guard 63/63; the dsh/side/plugin lane sweep 652/652. The 19 failures in the broader server/persona/compaction/title/issue sweep are pre-existing on clean HEAD (verified identical failure set in both directions).


八问(中文)

  1. 是什么问题:dsh 的辅助请求(标题/压缩/自动审查/时间线)此前靠 bili 匹配请求体内容来猜,模板一漂移就漏判([dsh] 原生压缩拦截门的 SHAPE 信号(≤4 条消息)在 dsh-compaction-basic 0.2.0-rc.2 上恒假 → 压缩静默落地 → 1510 条 fold 锚点永久失配,连刷 166 条 no-anchor-match 且面板仍报 netSaved 355.9M #2193 教训:漏判 = 静默丢底稿)。本 PR 让插件在 dispatch 缝上显式声明每个请求的 purpose,bili 按声明分类,内容匹配降级为旧安装的兜底。
  2. 什么原因导致的:根因是「侧/主请求」的判定信号放在了错误的一层——bili 在代理层用请求体内容反推 dsh 的意图,而意图只有 dsh 自己知道。修法是把信号下沉到唯一知道意图的地方(插件的 dispatch options)。
  3. 影响范围与严重程度:仅 dsh 车道。旧插件(无 purpose 头)字节级不变;新插件+旧服务器头是惰性遥测。严重度属「特定条件下有问题」(条件 = dsh 模板漂移):漂移时辅助请求会被误当主请求走内核(侧车道直通丢失、可能认领锚点),压缩调用漏判则守卫失效、dsh 原生压缩可能持久遮蔽原始历史(nudge 死锁无检测:同一 session 交替收到两种结构互斥的请求流(巨型单消息 ↔ 多轮)时不告警 #1729)——非全面不可用,但压缩路径的漏判是数据完整性隐患。
  4. 怎么修复的:声明优先,内容兜底。插件捕获 options.purpose(ASCII/≤64 字符门,脏值不上线)→ 每 fetch 盖 x-bili-plugin-purpose 头;服务端 pluginPurposeHeader() 在 x-bili-plugin 标记门内取值(未声明者头惰性),isSideRequest 在 agent 判定之后、内容启发式之前插入声明条款;压缩守卫对 purpose=compaction 短路(422 零出口 / bili-authored client compaction: let the host's own compaction flow run, but bili writes the checkpoint #3733 本地作答)。
  5. 是否有回归问题:审了 8 条既有行为(旧插件字节级、新插件+旧服务器、信任模型、main 否决、原始键乘坐、压缩守卫兜底、调用点完整性、无内核/配置/模型面文本)——全部保持,无意回归。唯一「变更」是新增头(协议扩展),已按 §7.4 标记人工审核档。
  6. 是否破坏缓存:不涉及。不改缓存键、重试、增量游标、去重键;声明侧请求仍乘原始键(KDD release v0.1.2 #9,侧请求永不认领锚点),不产生 |sub:<fp> 幽灵车道。
  7. 是否改了设计方向:是,但收敛在 [Design][dsh] Stop guessing dsh's auxiliary requests — the in-process plugin can declare each request's purpose explicitly #6880 三件套的第一件(声明优先分类)。第 2/3 件(退役 persona fork、id-only 身份)本 PR 刻意不做,仍是开放工作。新方向:侧/主判定信号从「代理层内容反推」转向「插件层显式声明」,内容匹配降为兜底。
  8. 是否引入了新的配置:不涉及。无新 env/config/CLI;KNOWN_AUXILIARY_PURPOSES 是文档不是门,新 dsh sidecar purpose 无需 bili 侧配置。

合并判定:代码正确、测试有牙、diff 干净、无回归、rollout 安全。两处日志准确性小修已直接补进 PR 分支(commit 6eb3ac95f5)。CI 跑完绿即可合(人工审核档:wire 协议扩展 + feat)。

ranxianglei added a commit that referenced this pull request Nov 16, 2026
… the raw session id (#6880)

The #6883 purpose header was only stamped for auxiliary dispatches, which
left the persona-order ladder (claim races, |sub:<fp> fork rungs) live for
dsh main turns even on upgraded plugins. dsh mints one UUID per session and
never recycles an id (SESSION_ALREADY_EXISTS in its store), so for a
conversation whose plugin declares purposes the raw session id IS the
complete identity — the ladder is dead weight there.

- dsh-native: stamp x-bili-plugin-purpose on every dispatch — the real dsh
  purpose for aux calls, or the new "conversation" sentinel for main
  turns (dsh leaves GenerateOptions.purpose unset for ordinary
  conversation, so no real purpose can collide; junk values degrade to
  the sentinel, never the raw value).
- plugin.ts: export PLUGIN_PURPOSE_CONVERSATION sentinel.
- handle.ts: normalize the sentinel back to "absent" before the side
  classification (it is a main turn, never a sidecar); a request CARRYING
  the header in any value skips all four persona-order call sites and keys
  the verbatim raw id. Pre-#6883 plugins stamp no header and keep the
  ladder byte-for-byte; persisted |sub: lanes of old traffic become orphan
  history (new declared traffic never resolves onto them). The declared
  compaction guard now reads the normalized purpose.
- tests: truth-table pin for the sentinel split (#2170 lane-guard), three
  new handle-level v2 pins (first-sight raw key, system-drift stays raw,
  sentinel is a main turn), attribution stamps updated to the v2 wire.
@ranxianglei
ranxianglei force-pushed the design/6880-dsh-purpose-signal branch from 6eb3ac9 to 3226c7e Compare November 16, 2026 05:30
… the raw session id (#6880)

The #6883 purpose header was only stamped for auxiliary dispatches, which
left the persona-order ladder (claim races, |sub:<fp> fork rungs) live for
dsh main turns even on upgraded plugins. dsh mints one UUID per session and
never recycles an id (SESSION_ALREADY_EXISTS in its store), so for a
conversation whose plugin declares purposes the raw session id IS the
complete identity — the ladder is dead weight there.

- dsh-native: stamp x-bili-plugin-purpose on every dispatch — the real dsh
  purpose for aux calls, or the new "conversation" sentinel for main
  turns (dsh leaves GenerateOptions.purpose unset for ordinary
  conversation, so no real purpose can collide; junk values degrade to
  the sentinel, never the raw value).
- plugin.ts: export PLUGIN_PURPOSE_CONVERSATION sentinel.
- handle.ts: normalize the sentinel back to "absent" before the side
  classification (it is a main turn, never a sidecar); a request CARRYING
  the header in any value skips all four persona-order call sites and keys
  the verbatim raw id. Pre-#6883 plugins stamp no header and keep the
  ladder byte-for-byte; persisted |sub: lanes of old traffic become orphan
  history (new declared traffic never resolves onto them). The declared
  compaction guard now reads the normalized purpose; the compaction
  authored/refusal logs and the sideLane label state the ACTUAL
  identification basis (declared purpose=… instead of claiming the
  content heuristics) — review follow-up on the original PR, folded in.
- tests: truth-table pin for the sentinel split (#2170 lane-guard), three
  new handle-level v2 pins (first-sight raw key, system-drift stays raw,
  sentinel is a main turn), attribution stamps updated to the v2 wire.
@ranxianglei
ranxianglei force-pushed the design/6880-dsh-purpose-signal branch from 3226c7e to 4662b07 Compare November 16, 2026 05:32

@ranxianglei ranxianglei left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent review (fresh clone, re-ran everything myself — complements the ework bot pass, which focused on commits 1–2; the v2 raw-key bypass of commit 4662b074 is the delta I dug into).

Local verification (all on head 4662b074):

  • npm run typecheck clean; tests/issue6880-purpose-declaration.test.ts + dsh-llm-stream-attribution + side-lane-truth-table + side-request-isolation = 71/71
  • prefix sweep dsh-*/side-*/plugin-*/persona-*/compaction-*/title-*/issue*: 3559 pass / 29 fail — the 29 are identical on clean base e0d63bf8 (verified in a second worktree: same 66-file subset, same 29). Environment-specific, not PR-caused
  • check:unused-exports + check:test-import-graph clean; remote CI fully green (e2e-dsh lane skips on PRs are the expected three-layer CI behavior — on-demand/cron only)

v2 bypass audit (commit 4662b07) — the part the earlier pass didn't cover:

  1. All four persona-ladder entry points are gated (!dshDeclaredPersona && dshPersona && !sideRequestLike): google, anthropic-dsh, openai, responses (src/server/handle.ts). Declared dsh traffic therefore never enters personaConversationOrder on any wire.
  2. Fall-through safety verified: declared dsh traffic on the anthropic wire falls to the claudeAnthropicPersonaOrderApplies clause, which is false for dsh (src/host-profiles.ts:81 personaOrderKeyed: false — only claude-responses is true); on the responses wire the stableSystemAnchor clause is false (dsh stamps the x-bili-plugin marker, so pluginAgentHeader !== undefined) and instructionsFingerprintApplies is codex/claude-responses-only → both land on the raw key. Structurally safe under the KDD #9 permitlist discipline.
  3. v2 invariant (one dsh UUID = one conversation) verified against the dsh source study in #6880: subagent children always mint a fresh UUID (packages/subagent/subagent/src/manager.ts:335), forks mint fresh ids, resume reuses the same id. Residual assumption (documented, accepted): a future dsh that ever dispatches a different persona under the same session id without setting purpose would merge into the main session on v2 — the aux set today always sets it (llm/src/types.ts:600-605), so this holds for current dsh.
  4. session-resolve.ts |sub:<fp16(tag)> lanes are a different mechanism (msgid-tag driven, not header driven) — untouched by this PR; declared traffic bypasses them simply because it never reaches the resolver.
  5. Junk-value degradation note: an aux purpose that fails the ASCII/≤64 capture gate degrades to the conversation sentinel at stamp time (src/agent/dsh-native.ts:2621 attr.purpose ?? "conversation") — i.e. it declares MAIN. Unavoidable (unset-main and junk-aux are indistinguishable at the seam) and harmless for current dsh (purposes are fixed ASCII literals), recording it as the accepted trade-off.

One suggestion (owner call, not fixed here): the KDD #9 mechanism text (AGENTS.md line 50 + reference/design-decisions.md) and docs/session-identity-resolution.md describe the persona lane as if it applies to all dsh traffic — commit 3 changed who enters the ladder (declared plugin traffic never does). Per the append-only ledger convention that reads as a new entry (next: #20) or a Tier B addendum, not a rewrite of #9. CI doc lanes are mechanical-sync only, so nothing catches this.

Verdict: approve. No regressions (old plugin byte-identical; new plugin + old server = inert header), tests are toothy (real server, forwarded-body assertions, zero-egress 422, both gate directions), diff is clean and on-topic. Merge once you decide the doc/ledger touch above is in or out of scope for this PR.

@ranxianglei
ranxianglei merged commit d1ff6ea into master Nov 16, 2026
92 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.1215-master.d1ff6ea (rolling master tag).

npm install -g billion-context@0.0.1215-master.d1ff6ea  # 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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant