Skip to content

fix(pi-native): self-heal ACP tools dropped by a mid-session registry rebuild (#2708) - #2713

Merged
ranxianglei merged 3 commits into
masterfrom
2026-10-11_pi-native-registry-drop-selfheal
Oct 11, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-10-11_pi-native-registry-drop-selfheal

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2708

Problem

In the pi-native (plugin) lane the six ACP tools are registered into pi's tool registry once per session id. pi rebuilds its executable tool list from that registry on every request (_refreshToolRegistry walks the live extension instances' tool maps into _toolRegistry; setActiveToolsByName filters active names through _toolRegistry.has(name) and silently drops any name it no longer holds). When that rebuild runs while our extension instance's map is empty (an extension-runtime replacement / reload mid-session), the ACP tools leave both the registry and the active set while the session transcript keeps declaring their names — so the model keeps calling tools pi rejects by name (Tool compress not found). Because registerTools() was gated once-per-sid (if (sid === state.sid) return plus the toolsFor guard), nothing ever re-registered them: unrecoverable until restart, and silent on both sides of the wire (no log line anywhere).

Fix

Remember the tools we registered (state.registeredTools) and, on every provider request for an already-registered sid, probe the host's real registry via getAllTools() and re-assert any of our tools that vanished. registerTool is idempotent (dedup by name) and post-bind triggers a registry refresh, so the session self-heals on the next request cheaply. The same re-assert runs at the end of a successful registration to cover a same-id session_start whose register loop is skipped. A console.warn names the dropped tools so the failure stops being silent.

Hosts without a registry query (older pi / omp) keep the exact once-per-sid behavior — the probe degrades to a no-op, and a throwing query never triggers a blind re-register.

Behavior change (disclosed)

  • Old: after the first successful registration for a session id, the plugin never touched pi's registry again for that sid.
  • New: each provider request for an already-registered sid calls pi.getAllTools() once (cheap, synchronous) and re-registers only if one of our previously-registered tools is missing. When nothing was dropped there is no extra work beyond one name-set lookup and no log line.
  • New log line (host stderr / bili.log): bili-plugin(<agent>): N bili tool(s) dropped from the host registry (<names>) — re-registering (#2708) — emitted once per drop event, not per request.
  • Reason: the drop was permanent and invisible; self-healing on the next request restores the session without a restart.

No config-surface change. No wire/message-shape change (re-registered definitions are byte-identical manifestToTool output; no payload/tool-call arguments touched). No kernel/ or pi-subagents/ change. No new dependencies.

Tests

Four regression cases in tests/plugin-agent.test.ts:

  1. drop → next request re-registers + logs the names + ownership header still stamped;
  2. fast path does not re-register (and emits no warning) when nothing dropped;
  3. a host without getAllTools stays inert (no crash, no blind re-register);
  4. a same-id session_start after a drop re-asserts during registration.

Verified on the rebased head (current master): tsc --noEmit clean; plugin-agent.test.ts 69/69; neighboring pi-lane suites (fork-adopt, native-caller-stamping, session-name, subagent-registry) green. Full build + suite run in CI.

… rebuild (#2708)

pi rebuilds its executable tool list per request from its tool registry
(_refreshToolRegistry walks the live extension instances' tool maps into
_toolRegistry; setActiveToolsByName filters active names through
_toolRegistry.has(name) and silently drops any name it no longer holds). When
that rebuild runs while our extension instance's map is empty (a runtime
replacement / reload mid-session), the ACP tools leave both the registry and
the active set while the transcript keeps declaring their names — so the model
keeps calling tools pi rejects by name ("Tool compress not found") forever.

registerTools() was gated once-per-sid (`if (sid === state.sid) return` plus
the toolsFor guard), so nothing ever re-registered them: unrecoverable until a
restart, and silent on both sides (no log).

Fix: remember the tools we registered (state.registeredTools) and, on every
provider request for an already-registered sid, probe the host's real registry
via getAllTools() and re-assert any we dropped. registerTool is idempotent
(dedup by name) and post-bind triggers a registry refresh, so the session
self-heals on the next request cheaply. The same re-assert runs at the end of a
successful registration to cover a same-id session_start whose register loop is
skipped. Hosts without a registry query (older pi / omp) keep the once-per-sid
behavior — the probe degrades to a no-op, and a throwing query never triggers a
blind re-register. A console.warn names the dropped tools so the failure stops
being silent.

Tests: four regression cases in plugin-agent.test.ts (drop → self-heal + log;
fast path does not re-register; no-query host stays inert; same-id session_start
re-asserts during registration).
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-11_pi-native-registry-drop-selfheal (3cf8755)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2943-pr.2713.4a4165a

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

Option B — Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 On it — reviewing #2713: pulling the branch, reading the full diff vs master, auditing the four regression tests for teeth, and checking CI. Structured eight-question conclusion to follow shortly.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 完成(已 rebase 到当前 master 逐行审过;并对照 @earendil-works/pi-coding-agent@1.1.0 实际 dist 验证了全部宿主机侧假设)。按八问:

1. 是什么问题
pi-native(plugin)通道里,pi 每次请求都会从存活 extension 实例的 tool map 重建可执行工具表;若重建时我们的实例 map 恰好为空(runtime 替换/重载),六个 ACP 工具就同时离开 registry 和 active set,而会话转录仍在声明这些名字——模型继续调用、pi 按名字拒绝(Tool compress not found),且 once-per-sid 注册闸门保证永不重注册:直到重启都不可恢复,两侧零日志。

2. 什么原因导致的
两个机制叠加:(a) pi 侧 _refreshToolRegistry() 每请求把 _toolRegistry 重建为全新 Map(走 getAllRegisteredTools()),active 名单再经 registry 成员过滤("unknown and hidden tool names are ignored")——map 为空的重建会把我们的工具从两处静默抹掉;(b) bili 侧 registerTools 对已注册 sid 直接早退,没有任何再断言路径。已在 pi 1.1.0 dist 逐点核实:loader.js 的 registerTool 是 name-keyed Map 的 set(幂等成立)+ post-bind 触发 refreshTools → _refreshToolRegistry();agent-session.js 中 getAllTools() 读的是同一次刷新后重建的 _toolDefinitions(探针读到的就是真实当前状态)。PR 里"幂等"的说法与 src/agent/pi.ts 旧注释("host may not dedupe by name")表面矛盾——实证以 dist 为准,矛盾解除。

3. 影响范围与严重程度
仅 pi-native 插件通道(pi);omp 等无 getAllTools 的宿主完全不受影响。触发条件苛刻(需要重建撞上我们 map 为空的窗口),但一旦发生=该会话压缩工具永久失效(降级而非致命:代理普通对话仍可用,重启恢复)。此前完全静默,#2708 现场 44 次失败/35 分钟无任何日志。

4. 怎么修复的
在决策点自愈而不是在传输层打补丁:记住注册过的集合(state.registeredTools),每个已注册 sid 的 provider 请求用宿主真实状态探针(getAllTools())检测消失项,只对被丢的工具重注册(条件式,非盲注);注册成功后同样再断言一次,覆盖同 id session_start 跳过注册循环的窗口;console.warn 点名被丢工具,消除静默。无探针能力的宿主保持原 once-per-sid 行为,查询抛错一律 no-op。额外验证了关键一环:重注册的工具会经由 pi 的 activated-on-registration 分支自动重新激活(defaultActive !== false + 默认 exposure "direct"),即恢复的不只是 registry 成员资格,还有模型可见的声明态——这正是修复打到根因的证据。

5. 是否有回归问题
逐项审过触碰路径的既有行为:① fast path 由纯早退变为一次同步 getAllTools()+Set 查找——无 drop 时零额外副作用(PR 已披露 old→new,属实);② 注册循环仅新增记录字段,无额外 manifest 拉取;③ identity-register 重试的 catch 分支不清 registeredTools,分析安全(下次成功循环必然刷新);④ manifest 中途变更的边缘:重断言恢复的是旧定义——与既有行为一致(toolsFor 闸下本来就在服务旧定义)且与转录声明的名字自洽,非回归;⑤ 并发双探针最坏=重复重注册(幂等)+重复告警一行,纯外观;⑥ 无 wire/message-shape 变化(重注册的定义是同一 manifestToTool 字节级输出,execute 闭包先读 LIVE base,#2416 保证 base 漂移自纠);⑦ kernel/、pi-subagents/、config surface、version 均未触碰。结论:未发现回归。透明说明:我本地首跑 tests/plugin-agent.test.ts 出现过 1 例瞬时失败(紧随 npm ci+build 高负载之后),其后含 PR head 在内连续 4 次 69/69;本 PR 测试 diff 为纯新增(0 行改动既有测试),该 flake 属套件既有的 deadline-polling 风格(load 下超时),非本 PR 引入,不拦。

6. 是否破坏缓存
不涉及——正常请求路径零重注册、零 prompt 重建,前缀缓存不受影响;仅在真实 drop 事件上 pi 侧重建一次 system prompt(恢复声明工具所必需,且该会话当时本就处于损坏态)。

7. 是否改了设计方向
不涉及——仍在本插件通道的注册机制内加反应式自愈,与 #2708 建议方向一致,无架构/边界/数据流转向。

8. 是否引入了新的配置
无新配置。唯一新输出:drop 事件日志行(已披露):bili-plugin(<agent>): N bili tool(s) dropped from the host registry (<names>) — re-registering (#2708)。

测试有效性:四个回归 case 是真测试——断言的是可观测副作用(重注册调用计数、warn 文本、ownership header 落章),分别钉死 fast-path 自愈、fast path 无 drop 不重注、无探针宿主 inert、session_start 再断言四条路径,任一条机制被移除对应 case 必红。

CI 状态与判定:除 lock-sync=failure+test=skipped 外全绿。我已定位:这是 master 自身的既有缺陷,与本 PR 无关(本 PR 不碰 package.json/lock)——master tip c0c9593 同样 lock-sync 红、test skipped;因果链:#2695(3956f57)合法 bump kernel 至 0.0.115 未动 lock → #2711 加入 lock-sync 门禁时却基于不含该 bump 的陈旧树同步出 0.0.114 → 门禁首次跑在 master 上即红,此后所有 PR 全灭(test legs 被 needs 跳过=全仓当前没有主测试门禁在跑)。已立 #2716(带来源标记)并开解锁 PR #2717(单行 lock 同步 0.0.114→0.0.115,本地复现 diff 与 CI 日志 blob 完全一致)。代码本身可合;建议先合 #2717 恢复门禁,本 PR 随后 CI 转绿即可合并。

@ranxianglei
ranxianglei merged commit aac8bc3 into master Oct 11, 2026
27 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.249-master.aac8bc3 (rolling master tag).

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

pi-native: tools register once per session id, so a pi tool-registry rebuild silently removes compress/decompress/... for the rest of the session

1 participant