Skip to content

[PR] feat: route-scoped renderNone for stateful relays (#6506) - #6507

Open
Huakira wants to merge 1 commit into
ranxianglei:masterfrom
Huakira:2026-11-13_route-render-none
Open

Huakira wants to merge 1 commit into
ranxianglei:masterfrom
Huakira:2026-11-13_route-render-none

Conversation

@Huakira

@Huakira Huakira commented Nov 13, 2026

Copy link
Copy Markdown

Fixes #6506. Follow-up to #2483 / #2485.

What

Adds a route field providers["<upstream url>"].renderNone:

  • true: no ACP render tags in that route's history (and no tags-only prompt section)
  • false: tags forced on, even when diagnostics.renderNone=true
  • unset: follows diagnostics.renderNone
  • ACP_RENDER_NONE still wins over both

How

  • src/knobs.ts: renderNone() reads a request-scoped override from an AsyncLocalStorage (withRouteRenderNone). Every existing reader (prepare-anthropic/openai/responses/google, inject, count_tokens, compress-loop rebuild) picks it up without signature changes.
  • src/server/handle.ts: resolves the route once per request (findRoute(opts.routes, providerDestUrl)?.renderNone) and wraps runPrepareInner with it.
  • src/config.ts: ProviderRoute.renderNone, parsed in parseRouteEntry, listed in NAMED_PROVIDER_ROUTING_FIELDS.
  • src/cache-ledger.ts: the stateful-upstream hint now points at the route field.
  • Docs: seed entry cr.rn in website/config-reference/providers.yaml, regenerated with tools/gen-config-docs.mjs generate.

Tests

New tests/issue2483-route-render-none.test.ts (wire bytes, same harness as issue2483-render-strategy): matching route untagged, route false overrides global true, non-matching route keeps tags, env wins over route.

Pre-flight

  • npm run typecheck: clean
  • node --import tsx --test on the new test + issue2483-render-strategy, issue1881-acp-tags-decoupled, knobs-config-precedence, cache-seam-detector, cache-ledger suites: 129/129 pass
  • gen-config-docs check-coverage and scripts/config-surface-guard.mjs: OK
  • No kernel/** change, no version bump.

@ranxianglei ranxianglei changed the title feat: route-scoped renderNone for stateful relays (#6506) [PR] feat: route-scoped renderNone for stateful relays (#6506) Nov 13, 2026
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: opencode/qwen3.8-27b)

查重: 不重复 — 检索 open+closed 的 renderNone 相关 issue/PR:#6506 是本 PR 的来源 issue(该家族唯一 open 条目);#2485(closed)是本 PR 所基于的前置全局一致性修复;无其他 open PR 触碰 per-route render tags。

Review of PR #6507 — fetched head 89e295b8, base == current master, CI 30/30 green on this exact sha (verified live).

What I verified in code (not just the diff):

  • Traced every renderNone() reader: prepare-anthropic/openai/responses/google, injectSystem (src/server/prepare-anthropic.ts:498), both count_tokens prep (src/server/handle.ts:3030, inside runPrepareInner), and the relay compress-loop rebuild (src/server/relay.ts:2681, via Prepared.renderTags which each lane sets from the knob). All execute inside the withRouteRenderNone ALS scope established around runPrepareInner (src/server/handle.ts:3060) — the "every reader picks it up without signature changes" claim holds.
  • Preflight's processTurn probes (src/preflight.ts:1626/1980/2203/2383) hardcode renderTags: "text-only", but those are measurement-only views (token estimation for the fold walk); wire bytes are rebuilt by prepare under the knob. Pre-existing, untouched by this PR, no wire impact.
  • Watermark fastpath ([Bug][dsh] 20k-message / 81 MiB-inbound session: host aborted 6× in 2 h — the #3050 resident-AST OOM is not bounded by sessions.hardMaxBytes (Windows, 0.1.210) #5403) only swaps inputs into the same prepare pipeline — no independent tag rendering.
  • Precedence in src/knobs.ts:882: env (if defined, incl. empty-string explicit-off) > route > diagnostics.renderNone > false — matches the spec; pre-existing empty-env semantics preserved.
  • findRoute is the same longest-prefix matcher as every other route field (src/config.ts:840).
  • Docs: re-ran tools/gen-config-docs.mjs generate on the PR head — output byte-identical to the diff (no hand-edits); check-coverage and scripts/config-surface-guard.mjs both pass locally.

Findings:

  1. Required before merge — missing "config surface" section in the PR body. This PR adds a new config field, and the Configuration Surface Discipline requires a "config surface" heading covering: what is added, why the existing surface cannot express it, which existing mechanisms were considered, and the compat/migration story. The "What/How" sections describe the field but not under that heading, and don't address considered-alternatives / migration. Suggested text to add:

    Config surface. Adds providers["<upstream url>"].renderNone (boolean, optional). The existing surface cannot express per-route tag control: diagnostics.renderNone and ACP_RENDER_NONE are process-global, so one stateful lane (magpie) forcing tags off disables them for every lane. Considered: a new env var (rejected — env is a scarce surface, 彻底整治环境变了滥用,除非必要都走配置文件 #2030, and per-URL keys don't fit env); reusing passthrough (rejected — passthrough skips the kernel entirely, different semantics). Follows the existing per-route field pattern (same matcher as passthrough/imageBilling, listed in NAMED_PROVIDER_ROUTING_FIELDS so inert named entries warn). Compat/migration: purely additive optional field; unset = byte-identical to today (follows diagnostics.renderNone); no migration.

  2. Optional nit: the diagnostics.renderNone docs row (docs/configuration.md:263) could cross-reference the new route override.

  3. Optional nit: the new test file carries the full original header comment from issue2483-render-strategy.test.ts; a one-line pointer would be cleaner, but it is labeled as provenance, so not a blocker.

Tests: 4 wire-byte tests pin the decision matrix (route on → untagged + no tags-only prompt section; route false vs global true → tags forced on; non-matching route → default; env wins over route). Real server + fake upstream, assertions with teeth (byte-identity, tag prefix). Harness copy matches the repo convention (20+ e2e files are self-contained).

Regression audit (existing behaviors touched by this diff):

  • Default path (no route field): withRouteRenderNone(undefined, fn) runs fn() directly — no ALS run, renderNone() falls through exactly as before. Zero behavior change.
  • ACP_RENDER_NONE precedence: unchanged, still top, including empty-string explicit-off.
  • NAMED_PROVIDER_ROUTING_FIELDS += renderNone: named (non-URL) entries setting it now get the existing inert-field warning instead of silent ignore — intended, consistent with the other 9 fields.
  • cache-ledger hint text: changed (old: "set diagnostics.renderNone=true until per-route render-tags control ships" → new: points at the route field) — intended, disclosed in the diff.
  • No kernel/ change, no version bump, no lockfile churn, no wire/protocol or persistence change.

结构化八问

  1. 是什么问题:diagnostics.renderNone/ACP_RENDER_NONE 是进程级全局开关;有状态中继(magpie 这类 claude-code relay)要求某一条路由关渲染标签、其他路由保留标签——全局开关只能全关,其他车道失去 ref/size 标签。(cache-ledger 提示文案本来就写着 "until per-route render-tags control ships",这是计划中的缺口。)
  2. 什么原因导致的:渲染策略只有全局载体(文件 flag + env),没有按路由作用域的机制;是功能缺口,不是 bug。
  3. 影响范围与严重程度:纯新增功能。存量用户零影响(字段不设 = 跟随 diagnostics.renderNone,字节级不变);受益面:同时跑有状态 relay + 其他正常车道的部署。
  4. 怎么修复的:新增路由字段 providers[<url>].renderNone(三态 true/false/unset),每请求解析一次,用 AsyncLocalStorage 注入请求作用域,所有渲染读取点(prepare 四车道、injectSystem、count_tokens、relay 压缩环重建)不改签名自动生效;优先级 env > route > 文件 > false。
  5. 是否有回归问题:审过的既有行为——默认路径(不设字段)字节级不变;ACP_RENDER_NONE 最高优先级保持(含空串显式关);preflight 测量视图硬编码 "text-only" 为既有行为且不产生线上字节,本 PR 未动;cache-ledger 提示文案变更为有意且已披露;高危模式(语义漂移/fail-fast 变吞错/阈值时序/输出格式漂移)逐项过——无意外变更。
  6. 是否破坏缓存:不。缓存键/重试/增量游标/去重键均未触碰;线上字节只在用户显式按路由开启时才变。
  7. 是否改了设计方向:没有。沿用既有按路由字段模式(与 passthrough/imageBilling 同一 matcher)与 knob 优先级约定(彻底整治环境变了滥用,除非必要都走配置文件 #2030);ALS 是 knobs.ts 内部的新请求作用域机制,不外溢。
  8. 是否引入了新的配置:是——providers["<upstream url>"].renderNone(boolean,可选,unset=跟随 diagnostics.renderNone);纯增量、无迁移;docs en/zh/ja + website 已同步,生成器复跑字节级一致,coverage 与 config-surface-guard 均过。

结论: 代码本身可合;合并前需补 PR 正文的 config surface 一节(第 1 条,或 owner 豁免)。feat: + 配置面变更,按 §7.4 属人工合并范畴。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: opencode/qwen3.8-27b)

PR #6507 review — complete. (Full review with code verification + 8问 posted in the comment above; this is a closing summary.)

Verdict: code is solid and merge-ready from my side. Fetched head 89e295b8 (base == current master, CI 30/30 green on this exact sha — verified live). Traced every renderNone() reader (prepare-anthropic/openai/responses/google, injectSystem, both count_tokens prep, relay compress-loop rebuild) into the withRouteRenderNone ALS scope — the "every reader picks it up without signature changes" claim holds. Default path (no route field) is byte-identical; ACP_RENDER_NONE precedence preserved; docs regenerate byte-identical; coverage + config-surface-guard green.

One required action before merge: the PR body is missing the mandatory "config surface" section (Configuration Surface Discipline) — suggested text is provided in the review comment above. Two optional nits (docs cross-ref, test header comment) are non-blocking.

Merge path: feat: + config-schema change → human merge per §7.4.

8问 (compact; full version in the review comment above):

  1. 是什么问题: 有状态中继(magpie)需要某一条路由关渲染标签、其他路由保留——全局开关做不到。
  2. 什么原因: 渲染策略只有全局载体(文件 flag + env),无按路由作用域机制;功能缺口,非 bug。
  3. 影响范围: 纯新增;存量用户零影响(不设 = 跟随 diagnostics.renderNone,字节不变)。
  4. 怎么修: 新增路由字段 providers[<url>].renderNone(三态 true/false/unset),ALS 注入请求作用域,所有读取点不改签名生效;优先级 env > route > 文件 > false。
  5. 回归: 无意外变更(默认路径字节不变;ACP_RENDER_NONE 保持;cache-ledger 提示文案变更为有意且已披露)。
  6. 缓存: 不破坏(缓存键/重试/游标/去重键均未触碰)。
  7. 设计方向: 未改(沿用既有按路由字段模式与 knob 优先级约定)。
  8. 新配置: 是——providers["<upstream url>"].renderNone(boolean,可选,纯增量无迁移)。

结论: 代码可合;合并前补 config surface 一节(或 owner 豁免);按 §7.4 走人工合并。

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.

Route-scoped renderNone so one stateful lane can drop render tags

2 participants