Skip to content

feat: inline billion-context-pi-subagents into the pi lane (#2186) - #2221

Merged
ranxianglei merged 5 commits into
masterfrom
2026-10-05_pi-subagents-embed
Oct 6, 2026
Merged

ranxianglei merged 5 commits into
masterfrom
2026-10-05_pi-subagents-embed

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2186

What

bili pi (the native pi extension, dist/agent/pi.js) now ships the acp_delegate sub-agent surface natively: acp_delegate / acp_delegate_wait / acp_delegate_cancel tools, the /acp-fleet inspector command, the fleet shortcut, the delegate status widget, read-tracking, and the system-prompt append. This is the "自带拆分 subagents 内置" ask from #612 (billion-context-pi): users of the bili pi lane get sub-agents without installing anything else.

Implementation follows the package's documented embedder contract: the standalone factory and an embedder are mutually exclusive (isEmbedded()), so bili claims the acp-delegate.embedded marker (check-before-claim) and wires the building blocks itself:

  • src/agent/pi-subagents.ts — wirePiSubagents(pi, agent) gated to agent === "pi" only (omp lane reuses the factory but must NOT get the delegate surface — same reason pi.ts is a dual-host factory). Claims the marker so a concurrently installed standalone billion-context-pi-subagents extension stands down instead of double-registering.
  • tsup.config.ts — noExternal: ["billion-context-pi-subagents"] inlines the package into dist/agent/pi.js; an esbuild alias maps the package's ONLY value import @earendil-works/pi-coding-agent (reads CONFIG_DIR_NAME) to an empty stub (src/agent/pi-host-stub.ts), exercising the package's documented .pi fallback. Result: zero new runtime imports in any dist artifact.
  • src/agent/pi.ts — optional sendUserMessage / registerShortcut on the local ExtensionAPI surface (guarded calls; absent on omp hosts), plus the wiring call at factory tail.
  • Stand-down parity kept: pi-subagents installed at project scope still auto-disables acp_delegate with the notify message; user-scope stays warn-only; user config via the package's own loader (~/.pi/acp.json + <cwd>/.pi/acp.json).

Config surface

No new bili config fields, env vars, or CLI flags. The delegate's knobs stay the package's own acp.json surface (read by the package's loadSubagentsUserConfig), deliberately NOT mirrored into ~/.config/billion-context/billion-context.json — the embedded surface is configure-where-the-package-documents-it, no second shape invented (#1437 discipline).

Dependencies

  • billion-context-pi-subagents devDep pinned exact 0.1.1 (acp-kernel pin discipline — it is bundled at build time). 0.1.1 shipped specifically for this: it exports loadSubagentsUserConfig + isEmbedded (package PR fix: address all code review findings (condense, routing, session-id, dead code) #2 / release PR feat: OpenAI Responses API support (/v1/responses) #4).
  • @earendil-works/pi-coding-agent + @earendil-works/pi-tui 0.83.0 exact: typecheck-only (d.ts resolution), erased by esbuild — no runtime reach.
  • Zero-dependency contract verified: dist/index.js and dist/mcp.js contain 0 references to the package or its imports; only dist/agent/pi.js grows (the only @earendil-works strings left in dist are pre-existing pi-CLI path constants, not imports).

Tests

  • New tests/pi-subagents-wiring.test.ts (8 tests, hermetic, HOME redirected): agent gate (omp never claims), marker claim + stand-down of a second embedder, full registration at session_start (3 tools + command + shortcut), host without buildContextEntries gets command but no tools, before_agent_start prompt append (string + array shapes), tool_result read/bash dispatch incl. isError skip, session_shutdown no-crash, policy gate on the fleet command.
  • Local: typecheck clean, wiring tests 8/8, build verified (pi.js standalone-importable, delegate surface present).
  • Full-suite note: the sandbox cannot complete tests/dsh-native.test.ts (15s apply() timeouts that reproduce identically on clean master — environmental spawn/network timing, unrelated to this change; no dsh file is touched). CI runs the full ubuntu+windows matrix.

Cross-repo

Package side already live: billion-context-pi-subagents@0.1.1 on npm (registry-resolved lockfile, no local paths). billion-context-pi keeps its own richer extension (fleet UI upstream); this lane embeds a pinned snapshot, same model as the acp-kernel inline.

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-05_pi-subagents-embed (78c5d65)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2293-pr.2221.ea9d610

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-pr2221.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] 🏷 收到,正在按 PR Review 规范审 #2221(feat: inline pi-subagents into the pi lane)。

已确认 PR 元数据:head 2026-10-05_pi-subagents-embed(origin/master 之后,behind),1 commit / 8 files / +2466 -35。真实代码改动集中在:src/agent/pi-subagents.ts(新,174)、tests/pi-subagents-wiring.test.ts(新,142)、src/agent/pi.ts(+16)、tsup.config.ts(+12)、src/agent/pi-host-stub.ts(新,9)、package.json(+3)、reference/architecture.md(+2),其余是 lockfile。

我会重点过:①原 issue #2186 方向是否对;②既有行为回归清单(pi.ts 双宿主工厂、omp lane、stand-down parity、零依赖契约);③embedder 契约 claim-before-check 逻辑与 marker 竞态;④测试有效性;⑤diff 整洁度。结论稍后按结构化七问给出。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review of #2221 (feat: inline pi-subagents into the pi lane).

Headline: the CI regression you hit is already fixed by your follow-up c793ed5a9 — I independently reproduced and root-caused it, and my diagnosis matches your fix's comment exactly. I drafted an equivalent local edit, then discarded it when I saw your commit land — I pushed nothing.

Verified hands-on at current head c793ed5a9: typecheck clean · wiring tests 8/8 · tests/issue2072-native-caller-stamping.test.ts 2/2 green · zero-dep contract holds (dist/index.js/dist/mcp.js = 0 refs to the package; the only @earendil-works strings left are pre-existing pi-CLI path constants) · embedder stand-down sound (shared Symbol.for("acp-delegate.embedded"); standalone factory only checks, bili claims synchronously at factory tail before any session_start → mutual exclusion holds regardless of load order).

The #2072 regression (root cause, matches your fix): that test's makeFakePi modeled events as a single-slot Map (events.set(event, handler) = last-wins). pi.ts already registers session_start twice (:581 + :871, the latter calls registerTools→acp_cache); wirePiSubagents (factory tail) adds a third session_start listener, which shadowed the acp_cache-registering handler inside the fake → the 15s poll timed out. Real pi is multi-listener (pi-coding-agent runner.js emit() iterates handlers[]), so production was never affected — only the over-simplified test stub. Your arrays-per-event fix is the correct, faithful correction (not a mask). Verified green locally.

Remaining items (only ① needs action before merge):

① Behavior change — must be stated (Deliverables rule 4; §7.4 default-value = product decision). By default (no ~/.pi/acp.json) the delegate surface is ON for every pi-lane session: src/agent/pi-subagents.ts:140 falls back to "delegate stays enabled", and :142/:166 gate the 3 tools + /acp-fleet + fleet shortcut + ACP_DELEGATE_PROMPT system-prompt append on policy.enabled (default true). So an existing pi user who never installed billion-context-pi-subagents now gets 3 new tools + a system-prompt append in every session with zero opt-in. Body line 5 lists what ships but doesn't frame it as default-on or call out the prompt-append (prompt bytes change once per session start). Please add one line: pi lane: none → delegate surface on-by-default, opt-out via delegate.enabled:false — turning implicit drift into an explicit sign-off.

② Minor (body line 16): "No new env vars… knobs stay the package's own acp.json surface." The inlined package also reads PI_ACP_DELEGATE_{MAX_DEPTH,DEPTH,FORCE_ENABLE,SYNC_TIMEOUT_MINUTES,IDLE_TIMEOUT_MINUTES,ASYNC_TIMEOUT_MINUTES,MAX_CONCURRENT} + PI_ACP_FORK_HOST, now newly reachable from the pi lane and absent from CONFIGURATION.md. Your deliberate non-mirroring stance (#1437) is fine — just note the env channel exists so "acp.json surface" isn't read as exhaustive.

③ Minor (body line 22): "only dist/agent/pi.js grows." dist/agent/omp.js also bundles the package (both ≈1.08 MB); it's dead code there, gated at runtime by agent !== "pi". Description slightly off.

④ Optional test nit (tests/pi-subagents-wiring.test.ts #6/#7/#8): the tool_result dispatch detail, session_shutdown, and fleet policy-gate legs assert presence/no-crash (assert.ok(true)-style) rather than the actual dispatched/disposed/gated behavior. Core lifecycle is well pinned; these three sit below the suite's usual bar.


Structured seven questions:

  1. 是什么问题:把 billion-context-pi-subagents 内联进 pi lane,让 bili pi 自带 acp_delegate 子代理面(工具/命令/system-prompt 追加)。是功能,不是缺陷。
  2. 什么原因导致(CI 红):Host-native agent tool forwarding lacks nativeCaller stamping: stale outbound witness misroutes ACP tool calls across subagent sessions #2072 e2e 的假 pi host 用单槽 Map 建模事件(last-wins),而真实 pi 是每事件多监听器;wirePiSubagents 在工厂尾部新增第 3 个 session_start 监听器,把注册 acp_cache 的 handler 在假 host 里顶掉 → 轮询 15s 超时。生产不受影响(真实 pi 支持多监听器)。已由你的 c793ed5a9(每事件存数组)修复,我本地验证绿。
  3. 怎么修复的:把假 host 的 on() 从「覆盖单槽」改为「追加到数组、emit 时逐个 await」,忠实还原 pi-coding-agent runner.js 的多监听器语义——修正的是不忠实的测试桩,不是掩盖症状。
  4. 是否有回归问题:审过既有行为——(a) Host-native agent tool forwarding lacks nativeCaller stamping: stale outbound witness misroutes ACP tool calls across subagent sessions #2072 路由契约(flagged 走 home / unflagged 409 TOOL_CONVERSATION_CONFLICT / id-less 走 witness)在你的修复后仍被原断言钉住并通过;(b) zero-dep 契约(index.js、mcp.js 零引用)保持;(c) 嵌入式互斥(stand-down)成立;(d) omp lane 不受影响(agent!=="pi" 双重门)。唯一需显式披露的行为变更见①——默认开启会改变每个 pi 会话注入的工具面与 system-prompt 字节(会话起始一次,非逐请求漂移)。
  5. 是否破坏缓存:不破坏。system-prompt 追加按会话稳定(session_start 一次,非逐请求漂移);plugin mode 下 prompt 由 agent 持有、proxy 不注入。无重试/增量游标/去重键影响。
  6. 是否改了设计方向:无架构转向。沿用既有 dual-host 工厂(pi.ts)与 marker 互斥机制,只是把独立包以 file: 依赖内联进 pi 入口;omp 复用工厂但被 agent 门排除,符合既有意图。
  7. 是否引入新配置:bili 自身未新增 config/env/CLI(作者明确不镜像,feat: opt-in for non-http(s) baseUrl providers to ride bili (#1392) #1437 纪律,赞同)。但内联包新可达 PI_ACP_DELEGATE_*/PI_ACP_FORK_HOST 一组 env(第三方约定类),未在 CONFIGURATION.md 记录——建议补一行或明确标注为包自有面(即②)。

判定:阻塞性 CI 回归已由 c793ed5a9 解决并本地验证通过。合并前请补①的一句话行为变更披露(默认开启 + opt-out);②③为描述小勘误、④可选。补齐①即可合并。我无法代合并(human-only),请自行合并:#2221

Wire the acp_delegate sub-agent surface (tools + /acp-fleet command +
fleet shortcut + status widget + read tracking + prompt append) into the
native pi extension via the package's embedder contract: markEmbedded()
claim, manual building-block wiring, tsup noExternal inlining, and an
esbuild alias stub for @earendil-works/pi-coding-agent so the package's
only value import (CONFIG_DIR_NAME) falls back to the documented ".pi".

- agent-gated (pi only; omp lane untouched), single-writer vs a
  standalone billion-context-pi-subagents install
- devDeps pinned exact: billion-context-pi-subagents 0.1.1,
  @earendil-works/{pi-coding-agent,pi-tui} 0.83.0 (typecheck-only)
- dist/index.js + dist/mcp.js import graph unchanged (zero-dep contract)
Real pi awaits an ARRAY of handlers per event per extension
(pi-coding-agent@0.83.0 runner.js emit(): handlers.get(type) then
for..of) — the Map-of-single-handler fake silently replaced the
factory's session_start handler with the embedded subagents wiring's,
so acp_cache never registered and the e2e timed out. The fake now
appends, and the two fire-sites await every registered handler.
@ranxianglei
ranxianglei force-pushed the 2026-10-05_pi-subagents-embed branch from c793ed5 to 3e51990 Compare October 6, 2026 02:58
ework-agent added 3 commits October 6, 2026 11:02
…ent fake (#2186)

Same single-slot shadowing defect the issue2072 fake just got fixed for:
this fake also drops every but the last handler per event, so the wiring's
third session_start registration silently disables registerTools. Composed
in place (rather than array-ified) because this file has ~20 fire-sites.
#2186)

The old fleet-policy test never invoked the captured handler (fake did not
store options); it now drives the handler with delegate.enabled=false and
asserts the notification. Adds the project-scope pi-subagents overlap
stand-down case (tools unregistered + one warning toast).
…ilently (#2186)

A broken acp.json previously fell back to defaults with zero diagnostics;
the standalone package logs this via logThrow but bili's lane has no such
channel — console.error matches the agent-module house style.
@ranxianglei
ranxianglei merged commit 33ce0f8 into master Oct 6, 2026
22 checks passed
@github-actions

github-actions Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.62-master.33ce0f8 (rolling master tag).

npm install -g billion-context@0.0.62-master.33ce0f8  # 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] 内置 billion-context-pi-subagents(acp_delegate)进 Pi lane:官方自有 subagents 支持

1 participant