Skip to content

feat: report client project directory to proxy sessions (x-bili-plugin-cwd) - #1516

Open
ranxianglei wants to merge 3 commits into
masterfrom
2026-09-27_client-cwd-transport
Open

ranxianglei wants to merge 3 commits into
masterfrom
2026-09-27_client-cwd-transport

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Part of #1406 — the bili-side transport for project-level rules. The key-value / digest redesign itself stays blocked on acp-kernel#446 (latest kernel 0.0.97 still ships the old rule API); this PR lands the one piece that does not depend on it: making the client's project directory available to the proxy.

Why

#1406 item 2 needs <cwd>/rules.md resolution server-side. The proxy's own process.cwd() is wrong whenever a launcher attaches to an already-running proxy started elsewhere, and pure /bili/ clients send nothing today. Without this channel there is no safe way to seed project rules in proxy mode.

What changed

  • New runtime header x-bili-plugin-cwd (src/plugin.ts): stamped by every cooperative host (pi, opencode V1/V2, dsh-native) with its process.cwd(). Same plugin gate as the other x-bili-plugin-* runtime headers; validated at every entry (string, trimmed, ≤4096 chars, no CR/LF) so session metadata can never carry control characters or unbounded strings.
  • Register payload gains optional cwd for launcher lanes that cannot stamp headers (opencode/pi via postIdentityRegister, mcp shell, bili plugin register).
  • session.metadata.clientCwd binding in src/server.ts: per-request header value wins (latest-wins, tracks mid-session /cd, persisted via markDirty); register-payload seeds only-if-absent at both binding sites (identity + pending). Pure /bili/ clients degrade gracefully — no field sent, metadata stays unset, global-only rules apply later.
  • Manifest advertises headers.cwd so third-party plugins learn the name; goldens regenerated via scripts/update-wire-contract-goldens.ts (additive line only).
  • PLUGIN.md: header documented + stale manifest example fixed (it predated maxOutput/model).

Behavior changes (flagged)

  1. Register POST bodies from opencode/pi/mcp/cli lanes now include cwd — additive field, older proxies ignore unknown fields.
  2. Manifest headers object gains a cwd key — additive.
  3. Session metadata may persist a new clientCwd key — additive, inert until the rules follow-up consumes it.
  4. No config surface change (no config field / env var / CLI flag) — protocol-internal transport only; CONFIGURATION en/zh untouched deliberately.

Golden changes

tests/golden/wire-contract/manifest-{default,optin}.json: one added line each (cwd header name), regenerated by the standard script — justification: advertising the new optional header to third-party plugins.

Pre-flight

  • typecheck ✓ · full suite 2968 pass / 0 fail / 12 skipped-by-design ✓ · build ✓ · E2E_CHECK=1 zero-token preflight ✓ (full e2e runs in CI — pipeline hot files touched)
  • New regression suite tests/issue1406-client-cwd.test.ts (7 tests): validation rejections, plugin-gate, register threading (both paths + legacy shape unchanged), headless pending seed, identity seed, header-wins-over-stale-register + /cd latest-wins, oversized-header rejection.

Remaining #1406 items (executeRule key/value upsert, digest injection, proxy-mode rules.md seed) land in a single follow-up PR once acp-kernel#446 is released.

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-27_client-cwd-transport (5cf38ef)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1740-pr.1516.1ef6912

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-pr1516.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] 🏷 Acknowledged. Starting review of PR 2026-09-27_client-cwd-transport (a4d09f3) per the PR review discipline: direction vs #1406, regression audit of touched paths, code review, test validity, diff cleanliness. Full conclusion to follow.

已接单,正在按规范审查该 PR(方向核对、回归审查、代码与测试有效性、diff 整洁度),结论稍后给出。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Review — verified, mergeable ✅

Reviewed the full diff on 2026-09-27_client-cwd-transport (single commit a4d09f30, 15 files, +366/−23), re-ran the checks locally, and checked CI. No blocking issues found.

① Direction vs #1406. Correct scope: this lands exactly the transport that #1406 item 2 (proxy-mode <cwd>/rules.md) was blocked on — the proxy's own process.cwd() is wrong whenever a launcher attaches to an already-running proxy started elsewhere. Fixes the missing channel (root cause), not a symptom; kernel-dependent items (executeRule migration, digest, seed) are correctly deferred to acp-kernel#446. No duplicate work exists in open issues/PRs.

② Regression audit — pre-existing behaviors of touched paths:

  • queuePluginRegister / handlePluginRegister / consumePluginRegisterFor / takePendingPluginRegister: optional trailing param only; LRU eviction untouched; legacy register shape preserved (test-pinned deepEqual({agent:"pi"})). Kept.
  • Manifest endpoint: additive headers.cwd key; goldens regenerated via the standard script (+1 line each). Intended, disclosed.
  • src/server.ts request path: new block is inert for plain clients (pluginReportedCwd → undefined immediately); sticky pluginAgent, derived-parent linking, anonymous-affinity and identity paths untouched. Header update runs before register binding, so first-request-with-both resolves header-wins and the seed no-ops — the intended precedence. Kept.
  • Agent lanes (pi/opencode V1/V2/dsh-native stamp; omp covered via shared createBiliPlugin("omp")): one extra header per request, existing headers unchanged. Register bodies (shared/cli/mcp): additive JSON field old proxies ignore. Intended, disclosed.
  • High-risk patterns: no error-handling drift (malformed cwd → dropped, register still succeeds), no threshold/default/timing/format drift, no config-surface change (verified none — CONFIGURATION.md deliberately untouched). Both compression modes reasoned through: no message-rebuild/injection/nudge/acp_summary changes in either mode.
  • Security: validated at every entry (string/trim/≤4096/no CR-LF) so metadata can never carry control chars or unbounded strings; same x-bili-plugin trust gate as the other runtime-info headers; value currently inert (zero consumers — grep confirms only the 4 binding sites), path-traversal concerns correctly deferred to the rules.projectFile gate in the follow-up. Persistence is an additive key in metadata: Record<string, unknown> — established pattern, no format/version bump needed.

③–④ Code & test validity. Clean. The 7-test suite has teeth: boundary values (exactly 4096 passes / 4097 rejected), the sneaky-gate case (cwd without x-bili-plugin rejected), legacy-shape pinning, and three e2e tests through a real server on random ports covering pending seed, identity seed, header-wins-over-stale-seed + mid-session /cd latest-wins, and oversized rejection. Two minor coverage notes (not blockers): no persistence round-trip assertion for clientCwd (store disabled in the suite; low risk given generic metadata serialization), and the reverse order (register after a header already set the value) isn't e2e-tested — the === undefined guard is trivially correct by inspection.

⑤ Diff cleanliness. Every line serves the PR purpose; the stale PLUGIN.md manifest example fix (pre-dated maxOutput/model) is small, labeled in the description, and correct. No whitespace churn, no lockfile/generated noise.

Behavior changes (confirmed additive-only): register POST bodies gain optional cwd; manifest gains headers.cwd; session metadata may persist clientCwd. Older proxies ignore unknown fields/keys; pure /bili/ clients degrade gracefully. No config surface change.

Verification evidence: CI on head a4d09f30 — 13/13 checks success (full suites ubuntu/windows × node 22/24, e2e, hermetic registry e2e, real-client lanes dsh/opencode/codex/pi, build-artifact, version-guard). Local re-run: typecheck clean; targeted suite (issue1406-client-cwd + wire-contract + opencode-native-v1 + opencode-v2) 74 pass / 0 fail; tsup build OK.

One process note: open refactors #1449 and #1446 both restructure src/server.ts — if either lands first this branch will want a rebase before merge (no semantic conflict with these additive hunks).

I can't merge PRs — system rules forbid it. Please merge yourself: #1516


中文摘要:审核了 #1406 的项目级 rules 传输前置件(client cwd 上报,header + register 双通道、会话级 latest-wins 绑定),方向正确、无回归、测试有效且 CI 全绿(13/13),仅两处非阻塞的测试覆盖小建议,可以合并。

This branch has not been deployed

No deployments
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.

1 participant