Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ jobs:
# Kernel boundary (#2092): the kernel's own unit suite against its TS
# source — both test layers must be green on every PR (AGENTS.md rule 5).
- run: npm --prefix kernel test
# Pi-subagents boundary (#2384): same two-layer rule for the in-repo
# pi-lane component — its own unit suite against its TS source.
- run: npm --prefix pi-subagents test
# ACP_TEST_CLAUDE_NATIVE keeps the claude-native live e2e subtests
# running here: the runner is dedicated, so their process/port
# observations are reliable (#1248 gates them off for loaded local
Expand Down Expand Up @@ -120,6 +123,40 @@ jobs:
fi
echo "✓ kernel version discipline OK"

# #2384: version discipline for the vendored pi-lane component — a commit IS
# the pin, so accumulated changes can later ship as an independent
# billion-context-pi-subagents release. Deliberately lighter than kernel-guard:
# no PR-body declaration / human gate (fast-moving extension surface, not
# load-bearing core compression).
pi-subagents-guard:
runs-on: ubuntu-latest
if: github.event_name == 'pull_request'
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Verify pi-subagents version discipline (#2384)
run: |
set -euo pipefail
SRC_CHANGED=0
if git diff --name-only origin/master...HEAD -- pi-subagents/src pi-subagents/tsup.config.ts pi-subagents/tsconfig.json | grep -q .; then
SRC_CHANGED=1
fi
BUMPED=0
if git diff origin/master...HEAD -- pi-subagents/package.json | grep -Eq '^[+-][[:space:]]*"version"[[:space:]]*:'; then
BUMPED=1
fi
if [[ "$SRC_CHANGED" == 1 && "$BUMPED" != 1 ]]; then
echo "::error::pi-subagents/ source changed without bumping the version in pi-subagents/package.json."
echo "Bump the component version so accumulated changes can ship as an independent billion-context-pi-subagents release later."
exit 1
fi
if [[ "$BUMPED" == 1 && "$SRC_CHANGED" != 1 ]]; then
echo "::error::pi-subagents/package.json version bumped without any pi-subagents/ source change."
exit 1
fi
echo "✓ pi-subagents version discipline OK"

# #2107 drift guard A: the config docs are generated from
# website/config-reference/*.yaml (single source). Regenerate and fail when
# the committed artifacts differ — a schema edit without re-running the
Expand Down
21 changes: 15 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,11 @@ The full file-by-file map lives in [reference/architecture.md](reference/archite

### Key Design Decisions

1. **The in-repo kernel is bundled inline** — `kernel/` (the acp-kernel source, consumed as a `file:` devDependency, #2092) is NOT listed in tsup `external`, so `dist/index.js` is self-contained. Exception: `zod` (exact `4.1.8`, matching the opencode host's own zod so V1 plugin-tool shapes interoperate) is a real dependency and stays external — only `dist/agent/opencode-native.js` imports it (lazily, at plugin-tool registration); `dist/index.js` and every other entry remain zod-free. When zod cannot be resolved at runtime the V1 plugin degrades to plain proxy mode instead of failing.
1. **The in-repo kernel is bundled inline** — `kernel/` (the acp-kernel source, consumed as a `file:` devDependency, #2092) is NOT listed in tsup `external`, so `dist/index.js` is self-contained. Exception: `zod` (exact `4.1.8`, matching the opencode host's own zod so V1 plugin-tool shapes interoperate) is a real dependency and stays external — only `dist/agent/opencode-native.js` imports it (lazily, at plugin-tool registration); `dist/index.js` and every other entry remain zod-free. When zod cannot be resolved at runtime the V1 plugin degrades to plain proxy mode instead of failing. Same for `pi-subagents/` (the billion-context-pi-subagents source, #2384): consumed via a `file:` devDependency and inlined into the pi-lane entries; its own build inlines the `typebox` peer, so those bundles stay self-contained too.
2. **Tags use XML format** — messages carry ACP tags like `<acp tokens="2" type="text">m00001</acp>` (an opening element with `tokens=`/`type=` attributes wrapping a ref id, closed by its end element). In **source files** these angle brackets MUST be written as hex escapes (`\x3c`, `\x3e`) to avoid tooling that strips well-formed tags.
3. **Auto-update**: checks npm registry every 3 min by default (`CHECK_INTERVAL_MS = 3*60*1000`, overridable via `update.checkIntervalMs` / `BILI_UPDATE_CHECK_INTERVAL_MS`, #2030); first check per process ignores throttle.
4. **Tee logger**: all proxy logs go through `src/logger.ts` (file + stderr). Do NOT use `console.error` in server-side modules — use `loggerLog()`.
5. **The kernel lives in-repo; determinism comes from git, not a registry pin (#2092).** The acp-kernel source is vendored under `kernel/` and consumed via `"acp-kernel": "file:./kernel"` (devDependency; inlined into `dist` at build time). A commit IS the pin — there is no registry range left to drift. The kernel keeps its OWN version in `kernel/package.json`: any kernel source change MUST bump it (CI-enforced — see Kernel Boundary below), so accumulated changes can later ship as an independent npm release of `acp-kernel`. `package-lock.json` records the file link and stays committed.
5. **The kernel lives in-repo; determinism comes from git, not a registry pin (#2092).** The acp-kernel source is vendored under `kernel/` and consumed via `"acp-kernel": "file:./kernel"` (devDependency; inlined into `dist` at build time). A commit IS the pin — there is no registry range left to drift. The kernel keeps its OWN version in `kernel/package.json`: any kernel source change MUST bump it (CI-enforced — see Kernel Boundary below), so accumulated changes can later ship as an independent npm release of `acp-kernel`. `package-lock.json` records the file link and stays committed. Same pattern for `pi-subagents/` (#2384): vendored under `pi-subagents/`, consumed via `"billion-context-pi-subagents": "file:./pi-subagents"`, own version in `pi-subagents/package.json` (CI-enforced — see Pi-Subagents Boundary below).
6. **Single-writer plugin copies (#991)** — every bili presence has exactly ONE writer; mixing writers is what the guard forbids. The canonical statement is the Install-Lane & Update-Ownership Contract below.
7. **Two compression modes with different summary carriers** (CRITICAL — reason in BOTH, see §6):
- **pluginMode** (the `x-bili-plugin` header / registered agent, e.g. `bili pi`): the ACP-native agent OWNS compression — it executes `compress` locally, the call+result live in its own re-sent history, and the wire summary carrier is the **tool call** (the proxy suppresses tool + nudge injection; the agent's view never renders the kernel's `acp_summary`).
Expand Down Expand Up @@ -83,14 +83,23 @@ The compression kernel lives IN THIS REPO under `kernel/` (migrated verbatim fro
5. **Two test layers, both must pass.** The kernel's own unit suite (`npm --prefix kernel test` — runs against TS source) plus the bili suite/e2e as the integration layer. A kernel change is done only when BOTH are green on the rebased head.
6. **Structural invariants stay human-gated** (carried over from the kernel's own spec): zero runtime deps (no new dependency without owner sign-off), platform-agnostic core (no host API / file I/O / network), message-id immutability, wire-artifact format, lossless round-trip, protected-tool hard exclusion, canonical pipeline node ordering.

## Pi-Subagents Boundary (in-repo pi-lane component, #2384)

The pi sub-agent surface (`acp_delegate` tools) lives IN THIS REPO under `pi-subagents/` (migrated verbatim from ranxianglei/billion-context-pi-subagents @ master `d19481e` on 2026-10-08, INCLUDING the merged-but-unreleased settle-gate notification fix for #2301; initial in-repo version `0.1.2`; the old repo stays frozen until the move has settled — see `pi-subagents/PROVENANCE.md`). It keeps its own identity — npm name `billion-context-pi-subagents`, own `version`, own unit suite (`pi-subagents/tests/`), own build chain (tsup → `pi-subagents/dist` + d.ts) — and the host consumes it through `"billion-context-pi-subagents": "file:./pi-subagents"` exactly like `kernel/`. Enforced rules:

1. **Version discipline (CI-enforced).** Any change under `pi-subagents/src/**` (or `pi-subagents/tsup.config.ts` / `pi-subagents/tsconfig.json`) MUST bump `version` in `pi-subagents/package.json`; a bump without such a change also fails (CI job `pi-subagents-guard`). Normal changes ride along with billion-context releases; when enough accumulates, a dedicated release can publish `billion-context-pi-subagents` standalone.
2. **Two test layers, both must pass.** The component's own unit suite (`npm --prefix pi-subagents test` — runs against TS source) plus the bili suite/e2e as the integration layer. A component change is done only when BOTH are green on the rebased head.
3. **Lighter gating than `kernel/` (deliberate).** No PR-body declaration and no human-only review tier: this is a fast-moving pi-lane extension surface, not load-bearing core compression — the point of #2384 is ending the cross-repo npm round-trip. If that assessment changes, tighten HERE first (add the gate, don't improvise it).
4. **Zero-runtime-dep contract preserved.** The component's only runtime host import (`@earendil-works/pi-coding-agent`, namespace-imported by its config-dir module for `CONFIG_DIR_NAME`) stays external and is aliased to `src/agent/pi-host-stub.ts` in the bili bundle (#2186); its `typebox` peer is inlined by the component's OWN tsup build, so no new runtime dependency ever reaches `dist/`.

## 3. Development Standards

### Build Commands

```bash
npm run build # builds kernel/ first, then tsup bundle (kernel inlined)
npm run typecheck # tsc --noEmit --project tsconfig.json (src + tests; pre-hooks build kernel/)
npm test # node --import tsx --test tests/*.test.ts (bili suite; kernel suite: npm --prefix kernel test)
npm run build # builds kernel/ + pi-subagents/ first, then tsup bundle (both inlined)
npm run typecheck # tsc --noEmit --project tsconfig.json (src + tests; pre-hooks build kernel/ + pi-subagents/)
npm test # node --import tsx --test tests/*.test.ts (bili suite; kernel suite: npm --prefix kernel test; pi-subagents suite: npm --prefix pi-subagents test)
```

### Local Testing & Install
Expand Down Expand Up @@ -179,7 +188,7 @@ Releases are fully automated via CI (`.github/workflows/release.yml`): the Agent

## 6. Contributing

Before changes: (1) `npm run typecheck` clean, (2) `npm test` green, (3) understand the module dependency graph, (4) **consider BOTH compression modes** — any change touching the wire (message rebuild, system/developer handling, tool injection, `acp_summary` stripping, preflight, nudge) must be reasoned in BOTH plugin mode and proxy mode; correct-in-one-mode can break the other (#377 only manifested in proxy mode). See TECHNICAL-NOTES.md "Two compression modes" and the `pluginMode` comment in `src/server.ts`. (5) **Kernel changes follow the Kernel Boundary** — declaration marker, owner approval, version discipline, two-layer tests; the kernel is relatively stable by design, touch it only when necessary.
Before changes: (1) `npm run typecheck` clean, (2) `npm test` green, (3) understand the module dependency graph, (4) **consider BOTH compression modes** — any change touching the wire (message rebuild, system/developer handling, tool injection, `acp_summary` stripping, preflight, nudge) must be reasoned in BOTH plugin mode and proxy mode; correct-in-one-mode can break the other (#377 only manifested in proxy mode). See TECHNICAL-NOTES.md "Two compression modes" and the `pluginMode` comment in `src/server.ts`. (5) **Kernel changes follow the Kernel Boundary** — declaration marker, owner approval, version discipline, two-layer tests; the kernel is relatively stable by design, touch it only when necessary. (6) **`pi-subagents/` changes follow the Pi-Subagents Boundary** — version discipline + two-layer tests, lighter gating than `kernel/` (see that section).

Commit convention: `feat:` / `fix:` / `refactor:` / `test:` / `docs:` / `release:`.

Expand Down
4 changes: 2 additions & 2 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -693,7 +693,7 @@ Top-level keys that control how the proxy listens and behaves globally.
- **Type:** `{ subagents?: PiSubagentsFileConfig | boolean }`
- **Default:** `{}` (acp_delegate surface enabled with package defaults)
- **Status:** ACTIVE (#2230 config-home)
- **Description:** Settings for the built-in **pi-lane sub-agents** (`acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel`, registered when `bili pi` wires the embedded extension). The `pi.subagents` section is the config home for this surface; the standalone `billion-context-pi-subagents` package reads the same section through its own loader (the file format is the contract, not shared code). Previously these knobs lived in pi's `~/.pi/acp.json` under `delegate` / `delegatePrompt` / `displayUsage` / `debug` — those four keys are a **deprecated fallback**: still read while the section is absent (one-time deprecation warning on the host process stderr), **ignored once the section exists**, slated for removal in a future release. Renames: `delegatePrompt` → `prompt`; `debug` is scoped to the sub-agent subsystem and does **not** collide with the top-level proxy `debug`.
- **Description:** Settings for the built-in **pi-lane sub-agents** (`acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel`, registered when `bili pi` wires the embedded extension). The `pi.subagents` section is the config home for this surface; the in-repo `pi-subagents/` component (npm name `billion-context-pi-subagents`) reads the same section through its own loader (the file format is the contract, not shared code). Previously these knobs lived in pi's `~/.pi/acp.json` under `delegate` / `delegatePrompt` / `displayUsage` / `debug` — those four keys are a **deprecated fallback**: still read while the section is absent (one-time deprecation warning on the host process stderr), **ignored once the section exists**, slated for removal in a future release. Renames: `delegatePrompt` → `prompt`; `debug` is scoped to the sub-agent subsystem and does **not** collide with the top-level proxy `debug`.

```jsonc
"pi": {
Expand Down Expand Up @@ -729,7 +729,7 @@ Top-level keys that control how the proxy listens and behaves globally.
| `PI_ACP_DELEGATE_ASYNC_TIMEOUT_MINUTES` | `pi.subagents.asyncTimeoutMinutes` | `0` disables. |
| `PI_ACP_DELEGATE_MAX_CONCURRENT` | `pi.subagents.maxConcurrent` | Integer ≥ 1; invalid falls through to the file value, then unlimited. |

Changes take effect on a **new session** (tools register at session start). Full delegate surface docs (roles, execution model, fleet inspector): [billion-context-pi-subagents README](https://github.com/ranxianglei/billion-context-pi-subagents#readme).
Changes take effect on a **new session** (tools register at session start). Full delegate surface docs (roles, execution model, fleet inspector): [billion-context-pi-subagents README](pi-subagents/README.md).

### Process-level blocks (#2030)

Expand Down
4 changes: 2 additions & 2 deletions CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -693,7 +693,7 @@
- **类型:** `{ subagents?: PiSubagentsFileConfig | boolean }`
- **默认值:** `{}`(acp_delegate 面按包默认值启用)
- **状态:** ACTIVE(#2230 配置搬家)
- **说明:** 内置 **pi lane 子代理**(`acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel`,`bili pi` 装入内嵌扩展时注册)的配置。`pi.subagents` 段是该功能的配置家;独立包 `billion-context-pi-subagents` 用自己的 loader 读同一段(契约是文件格式,不是共享代码)。此前这些旋钮在 pi 的 `~/.pi/acp.json`(`delegate` / `delegatePrompt` / `displayUsage` / `debug` 四键)——这四键是**已废弃的回退源**:段缺失时仍读取(宿主进程 stderr 打印一次性弃用警告),**段存在后完全忽略**,未来版本移除。改名:`delegatePrompt` → `prompt`;`debug` 限定子代理子系统,**不**与顶层代理 `debug` 冲突。
- **说明:** 内置 **pi lane 子代理**(`acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel`,`bili pi` 装入内嵌扩展时注册)的配置。`pi.subagents` 段是该功能的配置家;仓内组件 `pi-subagents/`(npm 名 `billion-context-pi-subagents`)用自己的 loader 读同一段(契约是文件格式,不是共享代码)。此前这些旋钮在 pi 的 `~/.pi/acp.json`(`delegate` / `delegatePrompt` / `displayUsage` / `debug` 四键)——这四键是**已废弃的回退源**:段缺失时仍读取(宿主进程 stderr 打印一次性弃用警告),**段存在后完全忽略**,未来版本移除。改名:`delegatePrompt` → `prompt`;`debug` 限定子代理子系统,**不**与顶层代理 `debug` 冲突。

```jsonc
"pi": {
Expand Down Expand Up @@ -729,7 +729,7 @@
| `PI_ACP_DELEGATE_ASYNC_TIMEOUT_MINUTES` | `pi.subagents.asyncTimeoutMinutes` | `0` 关闭。 |
| `PI_ACP_DELEGATE_MAX_CONCURRENT` | `pi.subagents.maxConcurrent` | ≥1 整数;非法值回落到文件值,再回落到无限。 |

修改在**新会话**生效(工具在会话启动时注册)。完整 delegate 面文档(角色、执行模型、fleet 检查器)见 [billion-context-pi-subagents README](https://github.com/ranxianglei/billion-context-pi-subagents#readme)。
修改在**新会话**生效(工具在会话启动时注册)。完整 delegate 面文档(角色、执行模型、fleet 检查器)见 [billion-context-pi-subagents README](pi-subagents/README.md)。

### 进程级配置块(#2030)

Expand Down
44 changes: 28 additions & 16 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading