Skip to content

feat: pi.subagents config home in billion-context.json (#2230) - #2233

Merged
ranxianglei merged 5 commits into
masterfrom
2026-10-06_pi-subagents-config-home
Oct 6, 2026
Merged

ranxianglei merged 5 commits into
masterfrom
2026-10-06_pi-subagents-config-home

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Fixes #2230.

What

The built-in pi-lane acp_delegate surface (bili pi embedded wiring) now reads its config from bili's own config file — the pi.subagents section of ~/.config/billion-context/billion-context.json — instead of pi's ~/.pi/acp.json. Companion package PR: billion-context-pi-subagents#5 (the standalone package reads the same section through its own loader; the file format is the contract, no shared code — this bili PR has no dependency on the package release).

  • New section type PiSubagentsFileConfig in src/config.ts + pi added to KNOWN_TOP_LEVEL_KEYS.
  • Wiring (src/agent/pi-subagents.ts): loadConfigFile().pi?.subagents is primary; the package's acp.json loader stays as a deprecated fallback (one-time console warning when legacy keys are actually used). Boolean shorthand "pi": {"subagents": false} disables the surface.
  • Renames: delegatePrompt → prompt; debug is scoped to the sub-agent subsystem (no collision with the top-level proxy debug).
  • When the section exists it OWNS the config — acp.json keys are ignored (not merged).

Config surface (owner-approved in #2230)

  • Added: pi top-level block → pi.subagents (enabled/forceEnable/displayUsage/maxDepth/syncTimeoutMinutes/idleTimeoutMinutes/asyncTimeoutMinutes/maxConcurrent/thinkingLevel/agents/notifyIfRead/fleetShortcut/prompt/debug + boolean shorthand).
  • Deprecated: the four acp.json keys, read only while the section is absent; removal after a few releases. Zero-user window: the embedded surface is unreleased (feat: inline billion-context-pi-subagents into the pi lane (#2186) #2221 merged post-0.1.184).
  • Why the existing surface can't express it: acp.json is community-perceived as billion-context-pi's file; one product family had two config homes with dead keys confusing users (owner decision in Built-in pi sub-agents config: move acp.json delegate keys to billion-context.json (pi.subagents) #2230).
  • Env vars: six pre-existing PI_ACP_DELEGATE_* spawn-channel overrides now documented (CONFIGURATION.md/zh env tables + the pi section table) — "document or don't ship".
  • Docs: CONFIGURATION.md/zh pi section + quick-ref rows + env-mapping rows; CLIENTS.md/zh Pi section pointer; reference/env-vars.md per-process-channel row.

Tests

  • tests/pi-subagents-wiring.test.ts: 8 → 14 — pi.subagents enabled:false drops tools/prompt/shortcut, boolean shorthand, section-owns-config (acp.json ignored when both exist), prompt rename replaces the appendix, debug/maxConcurrent passthrough, deprecated-fallback warning asserted (console.error spy). Header now isolates BILI_CONFIG_FILE too.
  • Full suite runs in CI (remote).

The built-in pi-lane acp_delegate surface reads its config from bili's own
config file (pi.subagents section) instead of pi's acp.json. The four
acp.json keys (delegate/delegatePrompt/displayUsage/debug) become a
deprecated fallback: still read while the section is absent (one-time
warning), ignored once it exists. prompt replaces delegatePrompt; debug is
scoped to the sub-agent subsystem. The standalone package reads the same
section through its own loader (billion-context-pi-subagents#5) — the file
format is the contract, no shared code.

Co-Authored-By: Claude <noreply@anthropic.com>
@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-06_pi-subagents-config-home (cb6e9ce)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2311-pr.2233.ca0a82f

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-pr2233.tgz
npm install -g package

Install instructions are refreshed on each push.

The docs-sync drift guard (#2107) caught hand-edited generated blocks —
the quick-ref and env-map rows now come from the seed in
website/config-reference/server.yaml like every other key; the narrative
pi section (field table + env overrides) stays hand-written outside the
generated blocks.
@ranxianglei

Copy link
Copy Markdown
Owner Author

Note: the four red test jobs here are INHERITED from master — HEAD bd33b11 is red on the same single test (tests/pi-subagent-registry.test.ts:275), a #2209+#2186 semantic merge conflict unrelated to this PR. Filed #2234 with the diagnosis; test-only fix in #2235. Once #2235 merges I will rebase this PR and rerun CI. Everything else (docs-sync, docs-coverage, lanes, kernel/lane/version guards, build) is green.

ework-agent added 2 commits October 6, 2026 14:17
…honest smoke test

Review fix for #2233 (issue #2230). The old 'scoped debug flag reaches
setDebugEnabled' test asserted only tools.length==3, so a broken
debug/maxConcurrent mapping would still pass. debug/maxConcurrent have no
hermetically observable wiring-level effect (package debug state is
module-private; no debug.event fires during session_start), so export
piSubagentsAdapter as a test seam and pin the full mapping directly:
boolean shorthands, prompt->delegatePrompt rename, displayUsage canonical
placement inside delegate.
Review fixes for #2233 (issue #2230), each a one-line correction:
- CONFIGURATION.md / .zh-CN.md: the acp.json fallback warning is a single
  console.error on the host process stderr once per process; it does not go
  to the bili log or ~/.pi/acp.log (verified: package dist has no such
  logging path). Doc now says what actually happens.
- CLIENTS.md:479 typo 'dele gate tools' -> 'delegate tools'.
- server.yaml seed: pi.subagents type '{ subagents?: object | boolean }'
  violated the nested-key convention (type = value at that path); fixed to
  'object | boolean' and regenerated via tools/gen-config-docs.mjs
  (only the two generated table cells change; i18n check passes).
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 已拉取分支核对代码 + 本地定向验证 + 逐门 CI 状态,结论如下(结构化七问):

1. 是什么问题:把内置 pi-lane 的 acp_delegate 子代理配置从 pi 的 ~/.pi/acp.json 搬到 bili 自己的 billion-context.json → pi.subagents 段(配置归属搬家)。

2. 什么原因导致的:不是 bug,是产品决策(#2230 owner 拍板)——一个产品家族有两个配置家(acp.json 被社区当成 billion-context-pi 的文件),且 acp.json 里有死键让用户困惑。方向成立。

3. 怎么修复的:新增 PiSubagentsFileConfig schema + pi 入 KNOWN_TOP_LEVEL_KEYS;wiring 里 loadConfigFile().pi?.subagents 为主源,映射到包的 SubagentsAdapterConfig(prompt→delegatePrompt、debug 限定子代理子系统、其余 spread 回嵌到规范 delegate.*);acp.json loader 降级为「段缺失时读 + 一次性 console.error」的废弃回退;段存在即独占(不合并 acp.json);文档走 #2107 单源种子(server.yaml 加 pi.subagents 条目并重新生成 CONFIGURATION/index)。

4. 是否有回归问题:审过的既有行为——(a) 段缺失时 acp.json 回退路径保持原样(wiring 测试 #9/#12 覆盖);(b) 段存在时独占、忽略 acp.json(#12);(c) 映射对照包真实类型 SubagentsAdapterConfig/DelegateConfig 逐字段核对正确,displayUsage 落到规范位 delegate.displayUsage(非 legacy 顶层别名),文件路径与 acp.json 两路产出同形 ⇒ 下游 consume 不变;(d) 只动 pi-lane 内嵌扩展接线(src/agent/pi-subagents.ts),不碰 src/server.ts 请求管线/loop,无 wire/消息形状变更;(e) 新加的 console.error 与 src/agent/* 既有约定一致(非 server-side logger 违规)。高危模式逐项过:无语义漂移、无 fail-fast→吞错、无阈值/时序/输出格式变化。唯一红项 = 4 个 test job,已实证为 master(bd33b11) 继承的单一失败:我在 master 上单跑 tests/pi-subagent-registry.test.ts,仅第 9 个用例 #2185: factory wiring — session_start self-registers 挂(AssertionError expected: true actual: false,即 :275),与本 PR 改动正交且本 PR 未触碰该文件。→ 非本 PR 回归,与你 #2234/#2235 的诊断一致。

5. 是否破坏缓存:不涉及。改动在插件接线层,不在压缩/wire/cache 路径;prefix cache、增量游标、去重键均不受影响。

6. 是否改了设计方向:无架构转向。是 owner 已批准的配置归属决策落地——bili 拥有自己的配置面、acp.json 变废弃回退、配套包以「文件格式为契约」独立读同一段(无共享代码、本 PR 无跨仓依赖,devDep 仍钉 0.1.1)。

7. 是否引入了新的配置:有——新增顶层块 pi → pi.subagents(enabled/forceEnable/displayUsage/maxDepth/syncTimeoutMinutes/idleTimeoutMinutes/asyncTimeoutMinutes/maxConcurrent/thinkingLevel/agents/notifyIfRead/fleetShortcut/prompt/debug + 布尔简写 subagents:false),#2230 owner 已批准。另把 6 个既有 PI_ACP_DELEGATE_* spawn-channel env 补进文档(CONFIGURATION en/zh env 表 + pi 段表 + reference/env-vars.md per-process-channel 行)=「document or don't ship」。迁移方式:把 acp.json 四键搬进 pi.subagents(delegatePrompt→prompt、displayUsage 提到段级),段缺失前旧文件仍可读(带一次性警告),数版本后移除。

验证证据:docs-sync / docs-coverage 两门在旧 head(6d458a3) 曾红(手改生成表 + 缺种子),你 commit 7556bf2 补种子+重新生成后——我本地跑 check-coverage=coverage ok: 139 env names + 50 top-level keys、generate 无 diff、CI 新 head 两门转绿 ✅;自研 wiring 测试本地 14/14 pass;除 4 个继承 test job 外所有 gate(lanes/kernel/version guards/build/e2e)绿 ✅。

判定:实现正确、范围干净(feat + docs-seed 两个 commit)、映射经包类型核对无误、自研测试有牙且通过、文档双门已绿。唯一红 CI 为 master 继承失败(#2234/#2235),非本 PR 之过。待 #2235 合并后 rebase 本 PR 即可合并;本 PR 本身无需再改,不建议因继承红项而拦。(合并按规由人工执行。)

@ranxianglei
ranxianglei merged commit 2f6fe8b 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.69-master.2f6fe8b (rolling master tag).

npm install -g billion-context@0.0.69-master.2f6fe8b  # 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.

Built-in pi sub-agents config: move acp.json delegate keys to billion-context.json (pi.subagents)

1 participant