Skip to content

feat: providers followups — lane credentials + agent-reported provider registry (#2336) - #2344

Merged
ranxianglei merged 6 commits into
masterfrom
2026-10-07_providers-followups
Oct 7, 2026
Merged

ranxianglei merged 6 commits into
masterfrom
2026-10-07_providers-followups

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Implements both followups from #2336 on top of the providers dictionary that landed in #2167.

① Lane credentials — providers[URL].apiKeyEnv / credentialRef

A provider route (URL-prefix entry) may now carry exactly one credential reference; on every forwarded request the proxy overrides the auth headers for that lane:

  • x-api-key / x-goog-api-key present → replaced in kind
  • authorization present → replaced only when it is a Bearer scheme (anything else is signature-owned, e.g. AWS SigV4 — kept + warned)
  • none of the three present → injects authorization: Bearer <key>
  • active re-sign lanes (bili 改写带 body 签名的模型请求,CodeArts(华为 APIG SDK-HMAC-SHA256)全部 401 #1884) are skipped — the re-signer owns Authorization
  • unresolved credential (env unset / secret missing) → keep the client's headers, warn once per route+ref (visible failure, never corruption)

Applied once on the shared headers object in forward() after the resign block, so every egress (initial request, role-retry, refold, compress-loop, continuation) inherits it. bind aliases inherit via fillRouteGaps. Web PUT validates via the existing per-entry parseRouteEntry pass (invalid → 400, #1909-style strict).

③ Agent-reported provider registry (fallback layer)

ACP-native agents report their own configured providers to the proxy once per process (POST /__bili/agent-providers): name, baseUrl, api, resolved key, model list. The pi extension (reportAgentProviders) sanitizes before sending: OAuth providers, auth.json ("stored") credentials, endpoints pointing back at the proxy itself (origin comparison — the env-base form of detectProxyBase matches every URL), unmapped wire apis (bedrock/vertex/mistral/pi-messages), and name/shape violations are skipped.

Core side (src/agent-providers.ts): strict parseAgentProviderReport validation, in-memory per-agent registry, merged UNDER file recipes at both consumption points ({ ...agentProviderRecipes(), ...opts.namedProviders } in server.ts reqConfig + admin.ts plugin manifest) — file wins on name collision (a file recipe shadows that provider's agent contribution entirely, including its models).

Inline keys ride the request rail: ExternalSummaryTarget.apiKey (XOR with credentialRef), accepted only via parseExternalSummarySettings(value, { inlineKeys: true }) — the rail switch used by the ConfiguredSummaryPlan ctor; the file world still rejects plaintext keys. Keys never persist, never leave GET responses, never enter logs.

Web surface: GET /__bili/config adds agentProviders (agent + provider/model names only, no keys, no baseUrl); the summary panel offers agent models in the target dropdown with an (agent) badge.

Bug fixed in passing: the per-field PUT branch never validated chain expansion (an unknown ref saved with 200 — only the whole-file branch did). Both branches now reject unresolvable enabled chains with 400, with the agent layer merged in.

config surface

  • Added: providers[URL].apiKeyEnv / providers[URL].credentialRef (lane credential override; exactly one; [feature] configurable wire-path table (per-provider custom paths) - Claude Desktop's claude.ai private protocol as motivating case #1909-style strict validation). Considered: reusing named-recipe fields on URL entries (rejected — route entries and recipes have different validation grammars; parseRouteEntry now parses credentials only for non-recipe-shaped values); a separate lanes table (rejected — the providers table is the single routing surface by design).
  • Behavior: agent-reported recipes are a runtime-only fallback layer — no new file keys; chain references may now resolve against it. Merge order documented (file wins).
  • Compat: both features are strictly opt-in (absent fields = byte-identical behavior). No persistence format change; kernel untouched.

Testing

  • tests/lane-credentials.test.ts (12): apply rules (bearer ci / non-bearer preserved+warn / x-api-key / x-goog / inject-when-absent), resolution (env / longest-prefix routing / warn-once re-arm / secret via store), parse (double-cred throw / bad names / recipe-shape skip), full-chain against a fake upstream.
  • tests/agent-providers.test.ts (8): report parse+normalize, 16-entry reject table, registry merge/status leak-proofing, inline-key rail (file rejects / inlineKeys accepts / XOR), endpoint + GET/PUT contract through a real server (agent-only ref saves; file-name shadowing 400s; unknown ref 400s), inline key dials verbatim, pi-side reporting (skip rules, POST shape, retry/done semantics).
  • Regression: external-summary-settings / web-api / web-routing / web-i18n / named-provider-bind / provider-protocol / issue2072 / external-summary-runtime / pi-subagent-channel — 113+68 green; typecheck; build; docs coverage (140 env + 51 keys).
  • Also drops the unused export on PiSubagentChildSignal that turns the unused-export gate red on current master (verified on a2d2895 pre-fix).

Fixes #2336

ACP-native agents (pi) POST their configured providers to the proxy
(POST /__bili/agent-providers); recipes merge UNDER file recipes at
request-apply time (file wins on name collision). Inline keys ride the
request rail (target.apiKey XOR credentialRef, file world still rejects
plaintext). Web GET exposes the registry without secrets; per-field
PUT now validates chain expansion too (gap: it never did).
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-07_providers-followups (67cca4b)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2500-pr.2344.1f49d1d

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

Install instructions are refreshed on each push.

awork added 2 commits October 7, 2026 21:53
…2344)

The lane-credential table rows were hand-edited into the generated
CONFIGURATION index; docs-sync regenerates from website/config-reference
seeds and dropped them, failing the gate. Add the two seed entries and
commit the regenerated output (rows now stable; backticks normalized out
of desc cells per generator rule).
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 #2344 核对完成(未重做工作):按 [PR] 流程拉取分支、对照 #2336 已批设计逐项审代码与行为、跑定向测试、查 CI。发现一处 CI 红灯(docs-sync)已直接在分支上修掉(见下)。

七问

1. 是什么问题:非缺陷——#2163 统一 providers 字典蓝图的两项推迟设计落地:① operator 向 lane 主通道注入自有凭据(providers[URL].apiKeyEnv/credentialRef);③ ACP-native agent(pi)握手上报自己的 provider 配置作为具名字典的兜底层。

2. 什么原因导致:不适用(功能项)。设计演进产物:#2163 蓝图 ① 已随 #2167 落地,②③ 因动凭据流被显式推迟到 #2336。

3. 怎么修复的:

  • ① lane 凭据:parseRouteEntry 仅对非配方形条目(baseUrl/api 缺席)解析,XOR + 严格校验(fail-fast,[feature] configurable wire-path table (per-provider custom paths) - Claude Desktop's claude.ai private protocol as motivating case #1909 纪律);注入点在 forward() 转发边界单点(src/server.ts:6143 附近),作用于共享 headers 对象 → 首发/retry/refold/compress-loop 全部 egress 一致携带;re-sign arm(bili 改写带 body 签名的模型请求,CodeArts(华为 APIG SDK-HMAC-SHA256)全部 401 #1884)活跃时跳过;env 未设/secret 缺失 → warn-once + 保留客户端头(不静默降级成必然 401),成功解析后重新武装告警。
  • ③ agent 注册表:POST /__bili/agent-providers(loopback admin gate)+ 内存态 per-agent 表(src/agent-providers.ts,不落盘);pi 扩展上报前自清洗(OAuth/auth.json/自回环/无摘要拨号的 wire 协议全跳过);合并 {...agentProviderRecipes(), ...opts.namedProviders} —— file 恒胜、同名整体 shadow;agent 条目永不喂 findRoute/loadRoutes(红线守住,消费方只有具名配方展开);inline key 只走请求 rail(parseExternalSummarySettings(value, { inlineKeys: true }),单一调用点 configuredSummaryPlan 即 rail 入口),文件世界仍拒明文。
  • 顺手修(PR 正文已披露):两个 PUT 分支都补了链展开校验(此前 per-field PUT 存未知 ref 返回 200);删未用导出 PiSubagentChildSignal(master 上 unused-export gate 红,已核实在 a2d2895 预存在)。

4. 是否有回归问题:审过的既有行为逐项结论——

  • 关闭态(字段不设)= 字节等价现状 ✓(parseRouteEntry 只是多认字段;存量配置零变化)
  • 开启态 = 有意行为变更:旧「客户端 key 计费」→ 新「lane key 计费」(归属转移 operator),docs en+zh + 日志 + web UI 三处披露 ✓
  • prefix-cache:注入只改 egress auth header,body/system/tool schema 字节不动 ✓
  • persist 格式不变 ✓;fail-fast 未变吞错(坏配置拒收、坏 ref warn-once + 禁用链而非回落主模型)✓
  • 大量缓存接缝事件导致缓存命中率大幅度降低 #2131 出站指纹语义漂移(docs 已披露)✓
  • 一处与设计稿的偏差(非阻塞):我 Q2 方案建议 passthrough(billion-context ACP kernel 改写 body 导致 ZCode (zcode.z.ai) 405/3012 #661)lane 跳过注入 + warn-once,实现里没做——passthrough 请求同样经 forward() 会被注入(owner floor 5 的定稿描述也只列了 resign 跳过,视为已按此范围拍板)。我的判断:可接受且更合理——route 显式声明的凭据不应因压缩开关不同而被静默忽略,且 billion-context ACP kernel 改写 body 导致 ZCode (zcode.z.ai) 405/3012 #661 防的是 body 指纹,header 变更不在其面内。另 Q2 第 4 条(OAuth lane inert 的 warn-once)也未实现:在 codex ChatGPT-login 这类 lane 上配 apiKeyEnv 会用静态 key 顶掉 OAuth token → 上游 401,属可预期的 operator 误配,行为可见,记一笔不拦。

5. 是否破坏缓存:不涉及(prefix-cache/persist/重试游标均不受影响,见 4)。

6. 是否改了设计方向:无转向——完全落在统一字典方向内(单一名词表、gap-fill 合并序、凭据引用模式);③ 额外强化边界:agent 影响力封顶具名字典。

7. 是否引入了新的配置:apiKeyEnv/credentialRef 加入 URL 键路由条目(+ bind 别名经 fillRouteGaps 免费继承);零新增 BILI_* env;agent-providers 是协议端点不是配置文件字段。CONFIGURATION.md/zh-CN + website i18n 均已同步。

验证证据

  • 定向本地测试(全绿):tests/lane-credentials.test.ts 12/12、tests/agent-providers.test.ts 8/8、tests/external-summary-settings.test.ts+external-summary-runtime.test.ts 54/54(覆盖 inlineKeys 改动路径)、tests/route-passthrough.test.ts 7/7(billion-context ACP kernel 改写 body 导致 ZCode (zcode.z.ai) 405/3012 #661 既有行为未被注入块破坏)。
  • 安全面抽查:handlePluginManifest 只序列化工具/能力/端点,不回显 namedProviders(manifest 无 key 泄漏);agentRegistryStatus() 只出名字+模型;parseAgentProviderReport 尺寸/URL/字符集上限齐全。
  • CI(旧头 3503f10):26/27 绿,唯一红 = docs-sync——根因是 lane-credential 表格行手改进了生成物 CONFIGURATION 索引,而该索引由 website/config-reference/*.yaml seeds 生成(CI 重生成后行消失 → git diff --exit-code 失败;master 同 job 为绿,确认是本 PR 引入)。已直接修:补两条 seed(cr.lanekey/cr.lanecred)+ 提交重生成产物(backtick 按生成器规则从 desc 格归一化),commit 67cca4bb4 已推到 PR 分支;本地复跑生成器幂等通过。windows test shard 检查时仍在跑。

收工判定

代码方向、边界、披露均符合 #2336 已批设计,定向验证全绿,diff 干净(17 文件每一行都服务于本 PR 目的)。待 67cca4bb4 的 CI 全绿即可合并(合并留给人——凭据流工作本就在 human-review 档)。我会在 CI 出结果后跟进确认。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 跟进:CI 已出结果——head 67cca4bb4(含 docs-sync 修复)全部绿 ✅

  • 主 CI run(含 typecheck、ubuntu/windows 全量 test shards、docs-sync、docs-coverage、unused-exports、kernel-guard、version-guard、lane-guard)completed / success
  • 其余 13 条 lane(e2e-native opencode/pi/dsh、e2e-fake-codex、E2E real codex、e2e-codex-persona、e2e-pi-codex-ws、e2e-local-registry、ci-image、dsh-plugin-lane、CI Windows codex overlay、PR Build Artifact、Theorem Lane)全部 success
  • 说明:轮询中途 check-runs 端点曾瞬时报过 windows test shard failure,经 jobs API 复核该 job 实为 completed / success(API 状态更新间隙的旧快照),无实际失败。
  • docs-sync 修复生效:补 seed 后重生成产物与仓库一致,幂等验证通过。

收工判定维持不变:可合并(凭据流工作按档留给人工合并;我不会代合)。

@ranxianglei
ranxianglei merged commit 589bf4f into master Oct 7, 2026
27 checks passed
@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.113-master.589bf4f (rolling master tag).

npm install -g billion-context@0.0.113-master.589bf4f  # 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.

providers 统一字典后续:lane 凭据注入 + agent 注册表兜底(#2163 推迟项)

1 participant