Repository navigation
[PR] docs: document session-name endpoint semantics + zcode lane gap (#5702) - #5708
ranxianglei wants to merge 4 commits into
Conversation
… gap (#5702) PLUGIN.md documented every other /__bili/plugin/* endpoint but not POST /__bili/plugin/session-name. Add a trailing topic section covering: - purpose + body shape ({conversationId, name}, latest-wins, empty name clears back to the derived title, whitespace-normalized, 200-char cap) and which lanes actually report it today (only pi + dsh-native; omp/opencode do not, and zcode cannot because its title lives in the Electron layer); - why an idle POST returns 404 (the endpoint resolves against RESIDENT sessions only) and the two distinct 404 messages already in the code, with the practical rule to report during a model-request window; - the direct-write caveat: sessions.host_title can be written by hand for a COOLED session but is clobbered by the resident process's end-of-request writeback while the session is active. Docs only, no behavior change. Addresses the documentation request in #5702; the native zcode title-reporting direction still awaits an owner decision (needs a ZCode-side title seam).
📦 Built Package ArtifactBranch: Latest build — install this exact versionnpm install -g billion-context@0.0.8925-pr.5708.1d9bff8This exact version is immutable and reproducible. The rolling Recent builds (commit → version)
Download artifact
tar xzf billion-context-pr5708.tgz
npm install -g packageInstall instructions are refreshed on each push. |
(ai: vllm-qwen/qwen3.8-27b) 查重: 不重复 —— 已核全部 open [PR] 行,无其他 PR 覆盖 session-name 端点文档或 #5702 suggestion 1。 审核方式:拉了分支 逐条事实核验(全部通过):
CI 状态(镜像缓存 05:07Z 快照):static-gates / gate / kernel-guard / lock-sync / unused-exports / test-import-graph / mysql-contract 全绿;test 矩阵 12 shard 中 1 红 10 在跑。红的 顺带观察(不拦本 PR):issue 正文说「PLUGIN.md documented every other 结构化八问:
判定:内容可合入(claims 全数对码核验通过,diff 干净);待 CI 收口——re-run 那个与本 diff 无关的 Windows 失败 shard 后即为全绿。 |
(ai: vllm-qwen/qwen3.8-27b) 收口更新:CI 已全绿 —— 镜像缓存 05:44Z 快照(同一 head 完整审核见上方我发的 review 评论(逐条对码核验 + 结构化八问)。最终判定不变:内容可合入 —— 纯文档改动、claims 全部对码通过、diff 干净、CI 全绿。合并动作留给你(owner-only):#5708 |
(ai: vllm-qwen/qwen3.8-27b) CI auto-fix lane,attempt 1/3。结论:本 docs PR 自身干净可合,红的两块 shard 是继承性 master 级确定性失败,已按政策上报 #4599,不在本分支内修。逐项八问:
判定:本 PR 无需改动即可合;其红的 shard 是继承性 master 级确定性失败,等 master/ci-fixes 收敛转绿后本 PR 即绿。无需 owner 决策——方向已由今日 #5700/#5703 与哨兵共识(master 级修,不在各 PR 分支各修一遍)。注意:因该失败确定性地挂在 master 上,本 auto-fix lane 的第 2/3 次尝试重跑不会变绿,须待 master 侧修复落地。 |
…er-request servicing (#5702)
ranxianglei
left a comment
There was a problem hiding this comment.
(ai: vllm-qwen/qwen3.8-27b)
结论:APPROVE(GitHub 禁止对本人所开 PR 提交正式 approve,故以 comment review 形式发布同等结论)— docs-only single-file change (PLUGIN.md +8 lines), base is current master (fresh), every factual claim re-verified against source at head. No behavior/config/wire/persistence/kernel change. CI green per mirror cache (30 checks: 0 failed, 0 pending; test matrix path-skipped for docs-only).
Independent verification (file:line at head):
- Shape/semantics:
src/plugin.ts:867-905—{conversationId, name}, whitespace-normalized, 200-char cap (HOST_TITLE_MAX), latest-wins, empty name clears → panel falls back to derived first-message title (src/web/sessions-data.ts:951). - Error surface: both 404 messages quoted verbatim and correctly (
src/plugin.ts:893-894); the three 400 cases match the handler. - Lanes: only pi (
src/agent/pi.ts:315) and dsh-native (src/agent/dsh-native.ts:458) fetch the endpoint; grep across src shows zero references from omp/opencode/zcode. (Issue #5702's caller list naming omp/opencode-native was inaccurate against current source — the doc records the correct two.) - zcode gap: lane = SessionStart hook + per-session MCP entry (
src/zcode/bootstrap-hook.ts,src/zcode/mcp-entry.ts), neither on the model-request path; Electron-layer title unreadable by the plugin. - Direct-write caveat: active-session clobber is real — end-of-request writeback persists
sess.hostTitle ?? null(src/storage/store.ts:2008) over direct store writes; cooled sessions are served straight from the store.
Two small findings, fixed on the spot (non-blocking):
- Residency wording was factually wrong: "exists while the proxy is servicing that conversation's requests" — residency is a bounded LRU pool (session-count + byte-budget caps,
evictOldest,src/session.ts:1275,2009); active sessions stay resident between requests, idle ones cool under pool pressure. Reworded the EN + ZH paragraphs. 已顺手修:residency 措辞改对(有界 LRU 常驻池,非按请求存活)+ commit 561cb3e(已推本分支) - Body overclaimed "documented every other
/__bili/plugin/*endpoint":runtime-info(src/server/admin.ts:843) andattribution(src/server/admin.ts:854) are also absent from PLUGIN.md. Corrected the first sentence; scope stays session-name per #5702 suggestion 1. 已顺手修:PR 描述首句过度声明已更正(另两处缺文档留后续 pass,不扩本 PR 范围)
八问:1 是什么问题:PLUGIN.md 缺 session-name 端点文档(#5702 suggestion 1)。2 什么原因:端点随 #2322(pi)/#2604(dsh-native) 落地时未同步写入。3 影响与严重度:纯文档缺口,零行为变更,p3。4 怎么修:按既有「尾部主题段+中文要点」体例追加 EN×3+ZH×1。5 回归:无——单文件 docs-only,不触任何代码路径;高危模式逐项过(无语义/阈值/时序/输出格式变化)。6 缓存:不涉及。7 设计方向:不涉及(zcode 原生标题上报仍留 #5702 等 owner 决策)。8 新配置:无。
Awaiting merge.
(ai: vllm-qwen/qwen3.8-27b) CI auto-fix lane,attempt 1/3。这次哨兵已把 master 级修复收敛到
判定:已把哨兵 ci-fixes 修复 merge 进本 PR 分支并推送( |
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) CI auto-fix lane,attempt 1/3(head 5851ee0)。上轮 merge ci-fixes 后,CI 从 10 shard 红降到只剩 1 个——且那是个 flaky job。本轮已触发重跑。逐项八问:
判定:本 PR 代码干净可合。唯一红 job 是 master 级既有 flaky-test 竞态(非本 PR 引入),已触发重跑待确认转绿;若重跑仍红则为持续性 flake,需 owner/sentinel 在 master/ci-fixes 做确定性修复(已在 #4599 记录,评论 id 6653309251)。本轮无需 owner 决策。 |
ranxianglei
left a comment
There was a problem hiding this comment.
(ai: vllm-qwen/qwen3.8-27b)
Round 2 verdict: APPROVE(GitHub 禁止对本人所开 PR 提交正式 approve,继续以 comment review 形式发布)— head moved 561cb3e → 5851ee0 with two CI-coordination commits; delta re-reviewed end-to-end.
Delta since round 1 (round-1 docs content unchanged; base still current master):
0470bec62test(ci): realign five dsh regression pins to the #5656 sidecar residual (#4599)5851ee00eci: merge origin/ci-fixes — inherit sentinel realignment (#4599)
Verification of the delta:
- All six changed files are test-only (+86/−49); no code/config/wire/kernel change — this PR's docs-only scope is intact.
- Mechanism premise confirmed in source: the generic dsh single-shot sidecar gate exists (
dshSingleShotSidecar→resolveSideLane, verbatim side lane, kernel no-touch —src/server/handle.ts:1067,2240). Turn 1 of a tool-less single-shot shape riding that lane explains every re-pin: no refs assigned there, uncounted instats.requests, unstamped by the fastpath scan. - Sentinel convergence per #4599 policy:
0470bec62is an ancestor of origin/ci-fixes and all six test files are byte-identical to ci-fixes — inherited verbatim, no local variant. - Teeth check (would they catch regressions?): the four catalog/baseline/snapshot tests (issue2419/2446/2447/2481) still assert the BLOCKED ref on the protected message — now pinned to the first FULL-PIPELINE turn (turn 2), which is sound: nothing can fold before turn 2 (nothing compressible, no action surface), so protection must land exactly when folding becomes possible; a missing stamp still fails the test. issue2817 keeps its fork-teeth assertions untouched (only the request counters move 9→8 / 12→11). issue5403 ADDS a positive assertion (B-phase turn 0 must stay unstamped on the side lane) — a strengthening, not a weakening.
- CI green at 5851ee0 via mirror cache: 30 checks, 0 failed, 0 pending; all 11 test shards actually ran and passed (the path filter released the matrix once test files were touched) — empirical confirmation the re-pins hold.
No new findings; nothing to fix on the spot. Verdict stands: APPROVE, awaiting owner merge.
复审 PR #5708(head 5851ee0):结论仍 APPROVE——新增两 commit 均为 #4599 ci-fixes 哨兵继承(test-only,与 ci-fixes 逐字节一致、无本地变体;#5656 sidecar residual 机制在 src/server/handle.ts:2240 核实;teeth 完好且 issue5403 加了一条反向断言)。CI 全绿:30 checks 0 红 0 待,11 个 test shard 实跑通过。第二轮 comment review 已发(id 5782358048),待 owner 合并。 |
Resolve the PLUGIN.md conflict caused by master moving the protocol doc to docs/plugin-protocol.md (#5920): root PLUGIN.md takes master's redirect stub; the session-name/residency/direct-write notes added in this PR (#5708) are relocated byte-exact into docs/plugin-protocol.md. Net PR diff vs master is +8 lines in docs/plugin-protocol.md only.
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) 冲突已解决并推送。 master 把协议文档整篇从根目录 八问:
判定:冲突已闭环(mergeable=true)。当前 |
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) 冲突已解决并推送。 master 把协议文档整篇从根目录 八问:
判定:冲突已闭环(mergeable=true)。当前 |
[bot] 🏷 收尾确认:本轮阻塞(合并冲突)已闭环。
详情见上方八问回复。 |
[ework] auto-fix stalled: test (ubuntu-latest, 22, 1), test (windows-latest, 22, 3), test (windows-latest, 22, 1), test (ubuntu-latest, 24, 3), test (ubuntu-latest, 24, 1), test (ubuntu-latest, 22, 2), test (ubuntu-latest, 24, 2), test (windows-latest, 22, 4), test (ubuntu-latest, 22, 3), test (windows-latest, 22, 2) — stopping for human review |
ranxianglei
left a comment
There was a problem hiding this comment.
(ai: vllm-qwen/qwen3.8-27b)
Round 3 verdict: APPROVE(GitHub 禁止对本人所开 PR 提交正式 approve,继续以 comment review 形式发布)— head moved 5851ee0 → fbd5bb2 via a merge of current master; full delta re-verified at the new base.
What changed since round 2: the branch merged origin/master (fbd5bb2 Merge origin/master into zcode-session-name-docs). Master relocated PLUGIN.md → docs/plugin-protocol.md during its docs reorg, so the PR's 8-line session-name section now lands in docs/plugin-protocol.md. Net PR diff vs current master = one file, +8 lines, pure docs. No code/config/wire/kernel change; the round-1 residency-wording fix (561cb3e) survived the rebase intact.
Re-verification at head fbd5bb2 (master moved ~495 files, so every claim was re-checked against the new tree, not old line numbers):
- Handler
src/plugin.ts:983-1019: 400 paths (invalid JSON body/conversationId is required/name must be a string (empty clears)), 404 with both exact strings(id registered but session not resident)vs(no model request has arrived with this conversation id yet),.replace(/\s+/g," ").trim(),HOST_TITLE_MAX=200slice, latest-wins/clear,markDirty— matches the doc verbatim. - Residency pool
src/session.ts:1178-1179,1361-1376:MAX_SESSIONScount cap +MAX_RESIDENT_BYTESbyte budget +evictOldest()— the "bounded LRU resident pool" wording holds. - Panel/writeback:
web/sessions-data.ts:971hostTitle || title; cooled-store readstore.ts:2784hostTitle ?? title; active end-of-request writebackstore.ts:2188— the direct-write clobber mechanism is confirmed. - Reporting lanes: only
pi.ts:315+dsh-native.ts:460POST the endpoint; zero hostTitle/session-name refs in omp/opencode/zcode sources — "only pi + dsh-native report today" is accurate; the zcode-gap paragraph (SessionStart hook + MCP entry, neither on the model-request path, title in the Electron layer) is consistent with the lane shape.
CI green via mirror cache @fbd5bb2: 30 checks, 0 failed, 0 pending. Nothing to fix on the spot. Verdict stands: APPROVE, awaiting owner merge.
[bot] 复审 PR #5708(head fbd5bb2,已合并最新 master):净变更收敛为单文件 +8 行 docs(session-name 端点文档,master 文档重组后 PLUGIN.md→docs/plugin-protocol.md),无代码/配置/kernel 改动。全部事实声明已在新树逐条复核——handler src/plugin.ts:983-1019(400/404 文案、200 字截断、latest-wins/clear)、residency 池 src/session.ts:1178-1179,1361-1376、面板回写 web/sessions-data.ts:971 + store.ts:2188、仅 pi.ts:315 + dsh-native.ts:460 上报(omp/opencode/zcode 零引用)——均与文档一致。CI 全绿 30/30。结论仍 APPROVE(comment review id 5841793009,正式 approve 因本人所开 PR 被 GitHub 拦截),待 owner 合并。 |
PLUGIN.mdhad no section forPOST /__bili/plugin/session-name(runtime-infoandattributionare also still undocumented there — left to a later pass). This adds a trailing topic section for it, covering the three things users keep re-deriving by hand:{conversationId, name}, latest-wins, an emptynameclears back to the derived first-message title, whitespace-normalized + 200-char cap. Only pi and dsh-native report it today; omp/opencode do not, and zcode cannot — its lane is only a SessionStart hook + MCP entry (neither on the model-request path) and ZCode keeps the conversation title in its Electron layer where the plugin can't read it.404, with the two distinct messages already insrc/plugin.ts(id registered but session not residentvsno model request has arrived … yet). Practical rule: report during a model-request window.sessions.host_titleworks for a cooled session but is clobbered by the resident process's end-of-request writeback while the session is active.Scope
Docs only — no behavior change, no config surface, no test gate. Addresses the documentation request in #5702 (its suggestion 1). The native zcode title-reporting direction (suggestion 3) is intentionally out of scope here: it needs a ZCode-side title seam plus non-resident/out-of-band endpoint writes, which is an owner decision tracked in the issue thread.
Part of #5702.