Skip to content

feat(config): named provider lanes — bind aliasing + dead-field guard (one-shot #1469) - #1473

Merged
ranxianglei merged 8 commits into
masterfrom
2026-09-27_named-provider-bind
Sep 30, 2026
Merged

ranxianglei merged 8 commits into
masterfrom
2026-09-27_named-provider-bind

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #1469. Supersedes #1466 (closed unmerged). Also lands the substance of #1437 — which is not actually merged (still open/unmerged on GitHub; master contains none of it — verified by grep + GitHub API), so per the one-shot decision this PR carries both pieces in one linear history.

What changed

1. #1437 substance (cherry-picked from its branch, zero conflicts)

  • providers["<name>"] = { "compactionOptIn": true }: non-URL keys are routing-inert; the launcher exports the union to BILI_NON_HTTP_PROVIDERS (public env contract, unchanged); the pi/omp plugin's evidence-based ownsCompaction (fix: cancel pi/omp auto-compaction only on evidence the proxy carries the conversation (#1382) #1383) stops vetoing that provider's non-http baseUrl. Default behavior byte-for-byte unchanged when unset.
  • Three commits: original feature → review fix (stale veto comment + Phase-A routing guard test) → owner-decided shape (folded into the providers table).

2. bind — named entries become real lanes (new)

  • bind = an http(s) base URL; the named entry becomes a pure alias of that URL lane. Resolved purely at config-load time in loadRoutes (src/config.ts): the entry's routing fields (compress, models, proxy, passthrough, compressProtocol, compat, imageBilling) deep-merge onto the bound URL route and apply exactly as if written under that URL key. No named-provider awareness anywhere in the request path; names never appear on the wire. When [investigation] Taking over pi-claude-bridge traffic: route the bridge child's upstream calls through bili so compression ownership becomes natural #1468 lands, removal is a deletion, not a refactor (aliasing lives only in config resolution).
  • Precedence (per field): explicit URL-key entry beats any alias field; between sources the external ACP_PROVIDERS file beats inline config at every level (aliases fold in source order, first-set wins). Objects merge per key; arrays/scalars are taken wholesale from the winner — no element-wise merging.
  • A name key WITHOUT bind stays routing-inert (agent-side identity only).

3. Dead-field guard (the known wart, fixed in the same PR)

A name key without bind that carries routing fields → startup warning naming the key and the inert fields ("add bind, or move these under the URL entry"), once per signature — loud, not silent. Invalid bind values (non-string, non-http(s) URL) warn and leave the entry inert; bind on a URL key warns and is ignored.

4. Web config API made raw-faithful (source-level fix for a clobber)

handleConfigPut rebuilt every provider entry through parseRouteEntry, which silently drops unknown fields — any web-UI save would have erased compactionOptIn (already-shipped shape) and would have erased bind. GET/PUT now pass raw entry values through; validation is unchanged (legacy-shape reject + proxy scheme check still run).

config surface

New/documented fields (owner-gated surface):

  • providers[<name>].bind (string, http(s) base URL) — new, this PR. Why the existing surface cannot express it: URL keys are matched by longest prefix, so a name key can never carry routing fields today; the launcher-name-map approach (feat: named provider entries bind onto their URL lanes #1466) put aliasing in launcher env plumbing instead of config, splitting one mapping across two layers. Considered and rejected: implicit name→URL inference (ambiguous, silent), per-lane aliases array on URL entries (inverse direction — the name must also carry compactionOptIn, i.e. the identity lives on the name key).
  • providers[<name>].compactionOptIn (boolean) — lands here because feat: opt-in for non-http(s) baseUrl providers to ride bili (#1392) #1437 never merged; shape is exactly the owner-decided one from that thread.
  • Compat/migration: nothing to migrate. Name keys without bind behave exactly as before (inert + opt-in consumed); the dead-field warning is advisory, not an error. BILI_NON_HTTP_PROVIDERS env-var contract unchanged.

Behavior changes (disclosed)

  1. Web UI config view: GET now returns the raw inline providers block. External ACP_PROVIDERS file entries no longer appear in the view (they were never persistable through the UI's PUT anyway — the old view displayed them while PUT ignored them, which was misleading).
  2. Web UI config save: PUT now writes raw entry values back verbatim instead of re-serializing parsed routes — saves no longer strip trailing slashes / drop unrecognized fields. Runtime is unaffected: loadRoutes normalizes keys at load time, so stored-key normalization stays intact.
  3. New startup warnings (once per signature, [acp-config]): inert routing fields on a name key without bind; invalid bind value; bind present on a URL key.

Tests

tests/named-provider-bind.test.ts (11 tests): bind aliasing applies compress/models/proxy onto the bound lane; URL-key per-field precedence incl. presence-semantics (passthrough: false) and compat.roles per-key merge; arrays taken wholesale from the URL lane; name-without-bind inertness + warning text; invalid binds (non-URL string / ftp:// / number) warn and stay inert; bind on a URL key warns + ignored; external file outranks inline at every level; compactionOptIn consumed alongside bind via the resolveNonHttpProviders union; warning dedup across reloads; web round-trip preserves bind/compactionOptIn on disk and the runtime alias still resolves; PUT still rejects legacy string entries / socks5 proxies / array providers with 400.

Pre-flight (rebased head b7167ac0, base = current master a57ab8dd)

  • npm run typecheck ✅
  • npm test ✅ 2897 tests, 2885 pass, 0 fail, 12 skipped (baseline 2886/2874 + 11 new)
  • npm run build ✅ (dist-import-annotations OK)

Docs: CONFIGURATION.md en/zh — new "Named provider entries (bind)" section (alias semantics, precedence, all three warnings), cross-links from the Providers intro and compactionOptIn.

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-27_named-provider-bind (96a1045)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1742-pr.1473.a1e60d6

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-pr1473.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] 🏷 开始 review PR #1473(named provider lanes — bind aliasing + dead-field guard,one-shot #1469)。已拉取分支 2026-09-27_named-provider-bind(head b7167ac0),确认其 base 即当前 master tip(cae30bb3),4 个线性 commit,无 rebase 陈旧问题。正在按规范逐项审:原 issue 方向 → 回归清点 → 代码 → 测试有效性 → diff 整洁度。结论稍后贴出。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review progress — rebase done, two small fixes pushed, final verdict after CI/local gates.

① Direction (原 issue): matches the one-shot decision exactly. bind = required http(s) URL making a named entry a pure load-time alias of that URL lane; name key without bind stays routing-inert (agent-side identity only, compactionOptIn consumed) and its dead routing fields (compress/models/proxy/passthrough/compressProtocol/compat/imageBilling) get a once-per-signature [acp-config] warning naming key + fields + "add bind". Precedence verified by reading loadRoutes: external ACP_PROVIDERS file outranks inline at every level, URL key beats alias field-wise, aliases fold source-order first-set-wins, objects merge per-key, arrays/scalars wholesale — no element merging. Both compression modes unaffected (no wire change); no load-bearing infra touched (update.ts / persist / kernel pin / session identity all untouched).

② Regression audit: walked all four loadRoutes consumers (server start :929, hot-reload :5608, launcher budget-alignment :3233, loadOptions :903) — name keys were already registered under their own normalized key on master, so exposure surface does NOT expand (valid binds fold into URL lanes; it shrinks). Web overrides panel now lists named entries as rows instead of silently clobbering them on save (the root cause being fixed); setting a proxy there on a bind-less name creates a dead field → warning fires, which is acceptable self-documenting behavior. The three disclosed behavior changes (raw view, raw write-back, advisory warnings) verified accurate against the code.

③ Code: logic/invariants/error handling clean; parseRouteEntry semantics confirm bind-only/optin-only entries pass web-PUT validation; runTestPi omitting the new buildPiEnv param is consistent (--no-extensions, consumer never loads). Two trivial nits found and fixed directly on the PR branch as labeled commits:

  • chore(config): drop orphaned #1392 JSDoc left above maskHosts — 5-line leftover comment block at src/config.ts:1095-1099 documenting a field that no longer exists (removed plugin/nonHttpProviders residue)
  • docs(zh): fix 情性→惰性 typo in pi/omp opt-in paragraph (CONFIGURATION.zh-CN.md:909)

④ Tests: all have teeth — 11 new named-provider-bind cases cover bind aliasing (incl. findRoute + context-limit resolution), field-wise precedence, array non-merge, inert-name warnings, invalid binds, external-file precedence, opt-in consumption, warning dedupe, web round-trip verbatim, PUT 400/200 paths; plugin-agent adds the #1392 opt-in matrix incl. the Phase-A guard proving opt-in never widens destinationRoutedThroughProxy; launcher pins env export + strict-true filtering. Regression coverage for the clobber bug exists via the round-trip test.

⑤ Base freshness — action taken: the branch was based on a57ab8dd, 4 commits behind current master (cae30bb3), overlapping src/launcher.ts / tests/launcher.test.ts / both CONFIGURATION files. Master-side hunks are disjoint regions (#1429 Electron node-runtime at resolveNodeRuntime/ensureProxyRunning, one ACP_UPDATE_TAG doc line, #1429 tests) — no semantic conflict, but per review discipline I rebased onto current master (clean, zero conflicts) and pushed: new head 1cbc7ef3. Old-head CI was fully green (test matrix ubuntu/windows × node 22/24, e2e codex/opencode/dsh/pi lanes, hermetic registry, build-artifact, version-guard); CI is re-running on the new head, and I'm running typecheck + full suite + build locally on 1cbc7ef3 right now.

Verdict follows once both go green. Merge stays yours.

中文摘要:审查通过方向与回归审计,已在 PR 分支上顺手修了两处小瑕疵(config.ts 残留的孤立注释、中文文档错别字),并把分支 rebase 到最新 master(干净无冲突)后推送了新 head 1cbc7ef3,等 CI 与本地全量验证绿了再给最终结论。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Final review verdict: mergeable — head 1cbc7ef3, CI fully green, local gates green. Details below.

① 原 issue(方向关)— pass

The implementation matches the #1469 one-shot decision point-for-point: bind (required http(s) URL) makes a named entry a pure load-time alias of that URL lane; a name key without bind stays routing-inert (agent-side identity only — compactionOptIn consumed by pi/omp) and its dead routing fields get a once-per-signature advisory warning. Precedence verified against the code, not just the doc: external ACP_PROVIDERS file outranks inline at every level; URL key beats alias field-wise; multiple aliases fold source-order first-set-wins; objects merge per-key; arrays/scalars take wholesale (no element merging). The folded-in #1392 substance keeps its reviewed guarantees: default veto byte-identical, opt-in only widens the compaction-ownership candidate set (carriage evidence still decides), and the Phase-A guard test proves opt-in never widens destinationRoutedThroughProxy.

② 回归审查(既有行为清点)— all clean

Walked every existing consumer of the changed paths:

  • loadRoutes consumers (×4) — server start (src/server.ts:929), hot-reload (src/server.ts:5608), launcher budget-alignment (src/launcher.ts:3233), loadOptions (src/config.ts:903): name keys were already registered under their own normalized key on master, so this PR shrinks map exposure (valid binds fold into URL lanes), never expands it. Hot-reload refills the same object reference; log line shape unchanged.
  • findRoute longest-prefix: a name key can never prefix-match an http(s) request URL (covered by test).
  • Web overrides panel: named entries now appear as rows instead of being silently clobbered on save — that clobber was the root cause being fixed. Setting a proxy there on a bind-less name creates a dead field → warning fires; acceptable self-documenting behavior.
  • runTestPi omitting the new buildPiEnv param: consistent (--no-extensions, the env consumer never loads).
  • Both compression modes: no wire change anywhere — plugin mode and proxy mode carriers untouched.
  • Load-bearing infra untouched: update.ts, release workflow, persist format/version, kernel pin, session identity/ref logic, MITM/CA — zero diff.
  • Docs en/zh: synced section-for-section (one typo found, fixed in passing).

③ 代码审查 — pass

Logic/invariants/error handling clean. Spot-checks that mattered: parseRouteEntry returns a truthy route for any non-array object ⇒ bind-only/optin-only entries correctly pass web-PUT validation; rejectLegacyRoute export-reuse in handleConfigPut preserves master's 400 paths (legacy string, socks5 proxy) while adding array rejection; strict === true opt-in filter with exact provider-id match (case-sensitive, fail-closed empty set); warning dedupe keyed by signature survives config reloads (tested: 3 reloads → 1 warning). One pathological edge noted, not blocking: two keys differing only by trailing slash — master's web-save did last-wins normalized overwrite, new code preserves both with runtime first-set-wins (= direct-file-edit semantics on master). Arguably a fix; mention-only.

④ 测试有效性 — real teeth

No tautologies: 11 new named-provider-bind cases assert exact shapes (deepEqual on merged routes, exact warning text fragments, 400/200 PUT paths, verbatim disk round-trip); the matrix covers every precedence branch including presence-semantics (passthrough:false) and per-key object merge (compat.roles); plugin-agent adds the full #1392 opt-in matrix (A not-opted-in veto holds / B opted-in-but-unrouted no-cancel — the #1382 invariant / C cancel / D exact-match / E Phase-A routing guard); launcher pins env-export-once + strict-true filtering. The clobber regression is pinned by the round-trip test.

⑤ diff 整洁度 — clean (after rebase)

10 files, +625/−35; one linear commit chain; every line serves the PR purpose. Action taken during review: branch was based on a57ab8dd (4 commits behind current master cae30bb3, overlapping src/launcher.ts/tests/launcher.test.ts/both CONFIGURATION docs — master-side hunks disjoint regions, no semantic conflict). Rebased onto current master (zero conflicts) and pushed; added two labeled small-fix commits: orphaned 5-line #1392 JSDoc dropped from src/config.ts:1095-1099 (residue of the removed plugin/nonHttpProviders field, sat above maskHosts documenting nothing) and the zh 情性→惰性 typo. PR state now: mergeable: True, mergeable_state: clean.

Behavior-change ledger (old → new, all pre-disclosed in PR body — verified accurate)

  1. Web view returns the raw inline providers block instead of normalized runtime routes → external ACP_PROVIDERS file entries no longer displayed (they were shown but ignored on save — the old display was misleading). Runtime resolution unchanged.
  2. Web save writes raw values under raw keys instead of normalized parsed routes → trailing slashes/unrecognized fields survive write-back; runtime normalizes at load time, so effective behavior unchanged.
  3. Three new [acp-config] startup warnings (advisory, once per signature): routing fields on a bind-less name key, invalid bind target, bind on a URL-like key. No behavior change.
  4. (Folded [investigation] Non-http baseUrl providers (pi-claude-bridge etc.): an opt-in path to ride bili — beyond the #1383 stopgap veto #1392) pi/omp non-http(s) providers gain explicit opt-in (compactionOptIn: true / BILI_NON_HTTP_PROVIDERS) — default behavior byte-identical to master.

Verification evidence (head 1cbc7ef3)

  • CI: 13/13 success — test matrix ubuntu/windows × node 22/24, e2e (real codex/opencode/dsh/pi lanes vs deterministic fake upstreams), hermetic registry e2e, codex MCP overlay, build-artifact, version-guard.
  • Local on 1cbc7ef3: npm ci ✅ · typecheck ✅ · npm test 2909 tests / 2897 pass / 0 fail / 12 skipped (skip count matches baseline) · build ✅.

Verdict: direction correct, root cause fixed at the decision point (config-load normalization + web write-back), no regressions found, tests pin the behavior, diff clean on current master. Ready to merge — the merge itself stays yours.

中文摘要:PR #1473 审查通过——实现与 #1469 一次性方案逐点吻合,回归审计(loadRoutes 全部消费者、热重载、web 面板、两种压缩模式)均无破坏,测试断言有牙且覆盖所有优先级分支;审查中发现分支落后 master 4 个提交已代为 rebase(无冲突),并顺手修了两处小瑕疵(config.ts 孤立注释、中文错别字),新 head 1cbc7ef3 上 CI 13/13 全绿、本地 2897 通过 0 失败,可以合并。

ework-agent and others added 6 commits September 29, 2026 08:19
Narrow the #1383 stopgap veto so an explicitly opted-in non-http(s) baseUrl
provider (e.g. pi-claude-bridge's literal "claude-bridge") can claim compaction
ownership when its traffic actually flows through bili.

Opt-in (either mechanism): config file plugin.nonHttpProviders
({"<providerId>": true}) or env BILI_NON_HTTP_PROVIDERS (comma-separated).
The launcher resolves both and mirrors them to the client env.

Safety property preserved (#1382): opt-in only widens the candidate set. An
opted-in non-http provider still passes the SAME carriage-evidence gate
(carriedSids local stamp / /__bili/plugin/status probe), so unrouted traffic
never cancels and native compaction keeps working.

No behavior change unless opted in: with no opt-in configured, non-http(s)
providers are never cancelled - byte-for-byte the prior stopgap behavior.
…rd test (#1392)

- Update the #1382 comment block: non-http baseUrl vetoes BY DEFAULT now
  (BILI_NON_HTTP_PROVIDERS opt-in below widens only the candidate set).
- Add case (E): opted-in non-http baseUrl stays outside
  destinationRoutedThroughProxy — opt-in must never widen wire-side routing
  (no /bili/ rewrites, no stamped cache keys, no MITM candidacy). Guards
  Phase B against accidentally wiring the flag into stamp eligibility.
…s table (#1392, owner decision)

plugin.nonHttpProviders section is gone — the opt-in now lives where users
already look: the providers table, keyed by the provider id, with a
compactionOptIn boolean field on the entry:

  "providers": { "claude-bridge": { "compactionOptIn": true } }

A non-URL key is inert for routing (longest-prefix matching never hits it);
parseRouteEntry ignores the field. Env mirror BILI_NON_HTTP_PROVIDERS is
unchanged (union with the file, deduped). Docs: field reference entries in
CONFIGURATION.md (+zh) and the launcher prose updated.
…#1469)

A non-URL providers key with 'bind' becomes a pure alias of the bound URL lane: its routing fields (compress/models/proxy/passthrough/compressProtocol/compat/imageBilling) deep-merge onto the URL route at config-load time only (explicit URL key wins per field; external ACP_PROVIDERS beats inline at every level). Name keys without bind stay routing-inert and now get a startup warning when they carry routing fields. Web config API now round-trips raw entry values so saves can no longer clobber bind/compactionOptIn.
@ranxianglei
ranxianglei force-pushed the 2026-09-27_named-provider-bind branch from 1cbc7ef to b0c5658 Compare September 29, 2026 00:20
@ranxianglei

Copy link
Copy Markdown
Owner Author

Rebased onto current master (head b0c5658). Conflicts were doc-section neighbors (master's MITM-vs-/bili/ scheme section vs this PR's named-bind section — union: both sections kept, each with its own self-contained example) and one import line in src/agent/pi.ts (union). Gates: typecheck ✓, targeted suites 252/252 + named-provider-bind suite ✓, build ✓.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Rebase verified; the one red job was a flake in a NEW MASTER test (not PR code) — rerun green, run now 13/13.

① Your conflict resolutions check out. On b0c5658:

  • Docs union: en CONFIGURATION.md:200 keeps master's ### MITM vs /bili/ key schemes (own jsonc example) immediately followed by :222 ### Named provider entries (bind) (own jsonc example); zh mirror has both sections in the same order. No section lost or merged into a shared example.
  • src/agent/pi.ts import union is correct: all master ./shared.js symbols retained + nonHttpProvidersFromEnv appended — nothing dropped.
  • My two small fix commits survived on top (chore(config) orphaned-JSDoc drop, docs(zh) 情性→惰性 typo). Diffstat vs current master unchanged (10 files, +625/−35).

② CI: 12/13 then 1 failure — test (windows-latest, 24), diagnosed as a timing flake outside this PR:

③ Drift note (informational): your rebase base 68d1b921 (v0.1.169) is 10 commits behind tip 846548be (#1625 landed after you rebased). Only overlapping file is src/agent/shared.ts — master appends fitNoticeDescription (#1602), this PR appends nonHttpProvidersFromEnv; pure append-append, zero semantic interaction, local merge is clean. GitHub will show "behind"; an optional re-rebase onto 846548be buys linearity, otherwise squash-merge handles it fine.

④ Flake follow-up: the 400 ms/250 ms fixed walls in that property-net helper will keep biting any PR's windows-24 job under load (it's now in master via #1625). Suggested root fix: make the walls adaptive (baseline-measured latency scaling) or event-driven waits instead of fixed timers. I have not filed a separate issue since this thread is a PR-mirror — say the word and I'll file it with the 来源 marker pointing here.

Verdict: no PR-caused regressions; both compression modes unaffected; no load-bearing infra touched. Mergeable once CI is green to your satisfaction (it now is) — merge stays yours.

中文摘要:你 rebase 后的唯一红点是 master 新测试(#1613 abort/rewind property net,不在本 PR 代码里,CI 按 merge-ref 检出才跑到的)在 Windows 慢机器上撞了测试内部写死的 400ms 超时墙——已重跑该任务通过,整条 run 13/13 全绿,与本 PR 无关;冲突解决(文档两节并存、pi.ts import 并集)均已核实无误,可以合并。

@ranxianglei
ranxianglei merged commit 7c6b41f into master Sep 30, 2026
13 checks passed
@github-actions github-actions Bot mentioned this pull request Sep 30, 2026
@ranxianglei
ranxianglei deleted the 2026-09-27_named-provider-bind branch October 15, 2026 05:32
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.

One-shot: named providers as real lanes — bind + compactionOptIn + agent-side switch, landing in a single PR (replaces #1466 staging)

1 participant