Skip to content

feat: ACP-aware OpenCode V2 Responses WebSocket proxy + generic WS bridge shell (#1844/#1467) - #1968

Merged
ranxianglei merged 10 commits into
masterfrom
2026-10-02_opencode-responses-ws-generic
Oct 3, 2026
Merged

ranxianglei merged 10 commits into
masterfrom
2026-10-02_opencode-responses-ws-generic

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 3, 2026 •

Copy link
Copy Markdown
Owner

Closes #1844 (OpenCode V2 WebSocket bypass), closes #1866 (sparse terminal output loses tool calls after fold — fix 46ee9929 rides in this stack). Supersedes nothing, duplicates nothing: this branch is PR #1859 (head 1e282e91) + one refactor commit (85cf11db) — a pure fast-forward that feeds the generalization back into the #1859 review. Opened so the combined diff gets CI and inline review; merging this also merges all of #1859, or the author can git merge --ff-only the branch into the PR branch instead.

Base feature (unchanged, from #1859)

ACP-aware OpenCode V2 Responses WebSocket proxy (#1844): OpenCode V2 connects to bili over WebSocket, bili connects to the Responses upstream over WebSocket, frames enter the existing ACP request pipeline through in-process HTTP-shaped envelopes. Full design notes in docs/opencode-responses-websocket.md and the #1859 description.

Refactor commit: generic WebSocket bridge shell (#1467 phase-2 shell)

One-step generalization discussed in #1467 — extract the transport-agnostic half, keep the Responses half as the first codec:

  • src/ws-bridge.ts (new): protocol-independent shell — admission (loopback source, x-bili-plugin lane marker, x-bili-plugin-conversation header, existing tunnel-destination guard), upgrade handshake, per-connection labeled logging ([codec] [conn=N] [session=…]), exactly-once shutdown teardown (server.close patched, close event kept as backstop). Driven by a readonly WsBridgeCodec[] table; unclaimed upgrades return false so the existing 426 path is untouched.
  • src/responses-ws.ts: everything below installResponsesWebSocket moves into ResponsesWsSession implements WsBridgeSession, exported as responsesCodec (name responses-ws, marker opencode, claims /bili/responses/<upstream>). Frame validation, previous_response_id client-history contract, upstream continuation checkpoints, SSE sink — behavior unchanged.
  • src/server.ts: single wiring site — installWebSocketBridge(server, dispatch, log, [responsesCodec]).
  • tests/ws-bridge.test.ts (new, 3 cases): synthetic second codec (fake protocol on /bili/fake/<upstream>/echo) pins the codec-table abstraction — second codec claims its own path+marker; foreign marker / missing conversation / unknown path fall through as false; server.close shuts every session down exactly once and terminates peers.
  • docs: architecture section on the shell/codec split; a second wire protocol becomes a codec file plus one table entry; unknown protocols stay on [PR] feat: opt-in transparent WebSocket passthrough (#1467) #1472 transparent passthrough (folding requires knowing where history lives in the wire format, so arbitrary-WS compression is out of scope by construction).

Follow-ups landed on this branch after the rebase onto master

Second real codec: codex Responses over WebSocket (346d1db7)

Codex CLI 0.147.0 ships feature-flagged responses_websockets[_v2] (off by default, gradual rollout; supports_websockets per-provider config). When enabled with a prefix-mode base_url it dials GET <base>/responses over WS — in bili terms /bili/<upstream>/responses. Captured on the wire (rig in ~/tmp/dsh/codex-ws-capture):

  • conversation header session-id (plus thread-id, x-codex-window-id, x-client-request-id, x-codex-turn-metadata, openai-beta: responses_websockets=2026-02-06, originator: codex_exec);
  • one text frame per Responses event; response.create carries the full Responses body with stream:true, store:false, prompt_cache_key = session uuid;
  • full history replay every turn — previous_response_id is never sent, so folding simply shrinks the next replay;
  • one prewarm probe per connection (input: [], generate:false, request_kind=prewarm in turn metadata) that expects only a terminal event back.

codexResponsesCodec claims that dial on the generic bridge:

  • prefix-lane admission: no x-bili-plugin marker on the wire — trust rests on loopback source + session-id header + tunnel-destination guard, the same level as prefix-mode HTTP. pluginMarker is therefore optional on WsBridgeCodec, and conversationHeader lets a codec point at its client's own session header.
  • probe bypass (src/responses-ws.ts): empty-input + generate:false frames relay verbatim around the ACP pipeline — the bug: Responses degenerate retry overlooks custom tool calls and drops completed-attempt usage #1862 empty-input normalization would turn the probe into a phantom turn (shifting every later fold anchor), and tool/philosophy injection is pure byte inflation on a no-generation request.
  • allowStreamFlag per-codec transport policy: codex frames always carry stream:true (accepted); opencode keeps the strict absent-flag policy.
  • tests/codex-responses-ws.test.ts (5 cases): probe+turn pipeline ride (verbatim probe, usage/stat accounting, tool injection, no side-request), full-replay semantics with stable refs, fold across a covered range (next replay drops the covered payload, keeps the summary), admission denials (missing session-id, non-responses path → 426), non-stream protocol error frame.

Docs updated (docs/opencode-responses-websocket.md): the codex codec is documented as the second real codec on the shell.

Idle-socket observability (#1926 option (c))

The retention the issue documents (idle client peers pinning one live upstream
connection + both checkpoints, no reclamation until client close) is now
visible instead of silent: GET /__bili/stats gains wsBridge (per live
connection: codec, connection id, idleMs, retainedBytes across both
checkpoints, inFlight), and a 60s scan logs one warn per idle episode once
idle age crosses 30min (BILI_WS_IDLE_WARN_SECONDS overrides, 0 disables),
reset by client activity. Pure observability — nothing is closed; idle-close
(a)/(b) stays pending verified retry-full host recovery per the issue's own
sequence.

Verification

  • tests/codex-responses-ws.test.ts 5/5
  • tests/ws-bridge.test.ts 3/3
  • tests/responses-websocket.test.ts 36/36
  • tests/fix-responses-guard.test.ts 1/1, tests/responses-empty-messages.test.ts 6/6, tests/responses-proxy-id-replay.test.ts 6/6
  • tests/protected-tools.test.ts 7/7 (kernel pin follows master)
  • typecheck clean
  • CI: all four matrix legs green on b8d381d9 (rebased onto master 39250e7d)

Refs #1844, #1467, #1859, #1472, #1699, #1897.

@ranxianglei
ranxianglei force-pushed the 2026-10-02_opencode-responses-ws-generic branch from f7386a7 to c9e166c Compare October 3, 2026 07:29
@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-02_opencode-responses-ws-generic (163cfc5)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2003-pr.1968.71bc2bc

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

Install instructions are refreshed on each push.

@ranxianglei
ranxianglei force-pushed the 2026-10-02_opencode-responses-ws-generic branch from 6ec579b to beb24a2 Compare October 3, 2026 07:46
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 完成,已推两个标注 fixup commit 到分支;等最后两条 CI leg 转绿后给结构化结论。

做了什么

  1. 重基到最新 master(03d27f9)——解决 package.json / package-lock.json / src/server.ts 冲突(union 保留:master 的 stripLeakedBiliTools import + PR 的 ws 导入)。
  2. 发现并修复一个真实缺陷(7b653947):WS lane 上的 title-persona 请求(标题生成等侧请求污染主会话状态:prepareAnthropic 缺 isTitleGen 守卫、快照无条件覆盖、survivedCount 每请求空转 #388 side passthrough 转发 Buffer body)撞上 transport 只收 string 的契约 → 502 Unsupported request in Responses WebSocket transport,会话第一轮即死。修复前本地复现成功;transport 入口统一归一化 string|Buffer|ArrayBuffer 视图为文本,附回归测试。这是 c9e166c 那条 veto 挡掉的 OMP extension injects tools and compression philosophy in helper prompts #1897 路径之外、同类「side 路径把 Buffer 送进 WS transport」机制的另一实例。
  3. 恢复 rebase 决议时丢失的 master 内容(e7bf61a8):version 0.1.180(分支被降回 0.1.179,合并会把 master 降级)、test:e2e:image script(Bill images and text separately — the image estimate's ±15× error bar poisons every window decision (dual-channel accounting) #1843/feat: dual-channel image/text accounting — pixel prior by default, learned per-route cost (#1843) #1857 的 hermetic image e2e——它缺失正是前两个 head 上 ci-image workflow 全红的原因)、acp-kernel 0.0.100 pin(分支自身 beb24a28 已修,我这边确认保持)。lockfile 从 master 重新同步,diff 仅剩 ws/@types/ws 两个 devDep 条目。
  4. 代码审查:shell/codec 拆分合理——admission(loopback + conversation header + marker + path claim)、tunnel guard 前置 403、exactly-once teardown(patched close + close-event backstop)、未认领 upgrade 落回既有 426 路径,全部核实;双历史层(client 面展开全量喂 ACP 管线 / upstream 面向真实 API 重新 delta,分歧时安全回落整发)成立;WC-013 wire-contract ledger 新增符合 [CI/testing] wire-contract anti-regression system: validation-parity fake upstreams + golden schema snapshots + constraint ledger + staged 4-protocol x 3-mode client smoke matrix #1304 只增不缩;无新配置面(lane 身份沿用既有 x-bili-plugin 头,无新 BILI_* env)。

CI(e7bf61a):10 条中 8 条绿,含此前失败的 ci-image ✅(随 script 恢复而绿)、e2e-native-opencode ✅、Windows codex overlay ✅、real codex E2E ✅;剩主 CI(四腿)与 e2e-local-registry 在跑,绿了发七问结论。

@ranxianglei
ranxianglei force-pushed the 2026-10-02_opencode-responses-ws-generic branch from 21e9b67 to b8d381d Compare October 3, 2026 08:16
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — branch rebased onto current master, two review fixes pushed, all CI green on head 21e9b67c. Verdict: 可合.

What I did on the branch

While reviewing I found three merge blockers and fixed them as labeled commits (plus one of my fixes was superseded by a better author-side fix — see below):

  1. 7b653947 fix(OpenCode V2.0.20 OpenAI default WebSocket bypasses bili native HTTP interception; only title request creates empty ACP session #1844): accept pipeline Buffer bodies in the Responses WebSocket transport — real latent bug: a title-persona request over the WS lane (x-bili-plugin-agent: title) hits the 标题生成等侧请求污染主会话状态:prepareAnthropic 缺 isTitleGen 守卫、快照无条件覆盖、survivedCount 每请求空转 #388 side-request passthrough, which forwards the body verbatim as a Buffer; the transport had a string-only contract → Unsupported request in Responses WebSocket transport → 502 on turn 1, killing the session before any turn completes. Reachable for any OpenCode V2 host whose title agent shares the provider endpoint (it does). Fix normalizes string | Buffer | ArrayBuffer | ArrayBufferView → utf-8 text at the transport entry (bodyToText), i.e. at the root boundary where the pipeline's BodyInit meets the WS codec — not a symptom strip — plus a regression test that asserts the side-request log line fires AND the turn completes. (Sibling instance OMP extension injects tools and compression philosophy in helper prompts #1897 — all-bili-tools demotion — was already vetoed by the author's c4669d33 via the new x-bili-ws-lane envelope marker; verified the mechanism.)
  2. e7bf61a8 fix(OpenCode V2.0.20 OpenAI default WebSocket bypasses bili native HTTP interception; only title request creates empty ACP session #1844): restore master's version, kernel pin and image-e2e script lost in rebase — the rebase resolution took the PR-side package.json wholesale, silently downgrading version 0.1.180→0.1.179 (would downgrade master on merge; content branches must never touch version) and dropping the test:e2e:image script (Bill images and text separately — the image estimate's ±15× error bar poisons every window decision (dual-channel accounting) #1843/feat: dual-channel image/text accounting — pixel prior by default, learned per-route cost (#1843) #1857 hermetic image e2e that always runs in CI — its workflow was red on every head until this restore). Restored both, kept acp-kernel: 0.0.100 + the PR's ws/@types/ws devDeps, re-synced the lockfile (delta vs master = only the two ws entries).
  3. Test flake (windows-latest/24, repeated websocket_connection_limit_reached… asserting 0 !== 1 on log-line count): root cause is the logger tee being an unflushed createWriteStream, so a loaded runner reads the file before the last lines land. The author's concurrent 21e9b67c (readLogUntil bounded polling routed through all six log-read sites) supersedes my single-site variant — I dropped mine in favor of the broader mechanism-level fix.

Code review verdicts (the actual feature)

结构化七问

  1. 是什么问题:PR review——OpenCode V2.0.20 OpenAI default WebSocket bypasses bili native HTTP interception; only title request creates empty ACP session #1844/feat: support wss:// (WebSocket) traffic — opt-in transparent passthrough now, protocol-aware compression later #1467 的 Responses WebSocket 代理 + 通用 bridge shell。合并被三件事挡着:stale base 冲突;rebase 解决时把 master 的 version/kernel pin/image-e2e script 静默丢了;一个真实潜在 bug(title-persona 请求走 WS lane 第一轮就 502)+ 一个 windows 测试 flake。
  2. 什么原因导致的:① rebase 时 package.json 整块取了 PR 侧(版本回退、脚本丢失);② 传输层只认 string body,而 标题生成等侧请求污染主会话状态:prepareAnthropic 缺 isTitleGen 守卫、快照无条件覆盖、survivedCount 每请求空转 #388/OMP extension injects tools and compression philosophy in helper prompts #1897 两条 side-passthrough 路径会原样转发 Buffer body——契约在边界处没对齐(同一机制的两个实例,分别由作者 c4669d3 和我的 7b65394 关闭);③ logger tee 是无 flush 屏障的异步写流,慢机器上读文件竞态。
  3. 怎么修复的:冲突按 union 解(保留双方语义)+ 独立 restore commit 恢复 master 状态;body 归一化放在传输入口这一根因边界,不做中途过滤;日志断言改为有界轮询已落盘内容(作者 21e9b67)。
  4. 是否有回归问题:无。HTTP 路径字节级不变;未认领 upgrade 仍走原 426;ws 是 devDeps(tsup inline bundle,dist 依旧零依赖);lockfile delta 仅 ws 两项;version 保持 0.1.180、acp-kernel 保持 0.0.100;ci-image 由红转绿。新增的只是诊断日志行(forward WS → …、view=ws-expanded),纯增量。
  5. 是否破坏缓存:不涉及。纯新增 lane;prefix cache、session persistence、preflight 均未触碰;x-bili-ws-lane 是 bili 内部 envelope 标记,不出现在用户可见面。
  6. 是否改了设计方向:无转向,纯增量——shell/codec 拆分正是 feat: support wss:// (WebSocket) traffic — opt-in transparent passthrough now, protocol-aware compression later #1467 phase-2 定的方向;未知协议仍按 [PR] feat: opt-in transparent WebSocket passthrough (#1467) #1472 透明透传(folding 需要知道历史在 wire 格式里的位置,任意 WS 压缩 by construction 超范围,docs 已写明)。
  7. 是否引入了新的配置:无。没有新 BILI_* env、config 字段或 CLI flag;lane 身份完全复用既有 x-bili-plugin* header 约定。

收工判定

可合。 Head 21e9b67c 上 CI 全绿(main 4-leg test matrix 含 windows-24、ci-image、PR Build Artifact、e2e-native-dsh 均 success)。两点提醒:① 本 PR 正文声称对 #1859 是 pure fast-forward——rebase 后该关系不再成立,合并本 PR 即并入 #1859 全部内容,届时可直接关闭 #1859;② 分支上现共 10 个提交(feat/fix/test/refactor 各就其位),diff 干净可整段审阅。

darkness-A and others added 10 commits October 3, 2026 19:45
…ses becomes the first codec

- src/ws-bridge.ts: protocol-independent shell (admission, upgrade, labeled
  logging, exactly-once shutdown teardown) driven by a codec table
- src/responses-ws.ts: Responses-specific handling becomes responsesCodec
  (WsBridgeCodec/WsBridgeSession contract)
- src/server.ts: single wiring site installWebSocketBridge(server, dispatch,
  log, [responsesCodec]); unclaimed upgrades keep the existing 426
- tests/ws-bridge.test.ts: drives the shell with a synthetic second codec to
  pin the codec-table abstraction
- docs: architecture section covering the shell/codec split; new protocols
  are a codec file plus one table entry; unknown protocols stay on #1472
… lane envelopes

Master's #1897 demotion (omp hosts registering bili's tools as extension
tools) catches first-turn WS frames whose tools array is exactly bili's ACP
set: the frame is demoted to the side passthrough, which cannot speak the
lane's upstream transport (502 'Unsupported request in Responses WebSocket
transport'), and the whole session dies on its first turn.

The bridge now stamps x-bili-ws-lane=<codec name> onto the upgrade request
before the session is created, so every in-process envelope rebuilt from the
source inherits it. The demotion is vetoed for marked envelopes: the WS lane
is that conversation's mainline, the omp leak mechanism cannot produce these
envelopes, and side requests on this lane are identified by the #1699 persona
header instead.

Rebased onto master (dfca5a9) — 108 commits of drift resolved (import
union in src/server.ts, package.json/lock kept from master).
…transport

Review finding on c9e166c: a #1699 persona request (x-bili-plugin-agent:
title) riding the WS lane is a #388 side request, whose passthrough forwards
the inbound body as a Buffer — but the transport only accepted strings, so
every such request 502'd with 'Unsupported request in Responses WebSocket
transport' (reproduced locally before the fix). The c9e166c veto covers the
transport boundary by normalizing string|Buffer|ArrayBuffer views to text.
… lost in rebase

The rebase onto dfca5a9 resolved package.json from the PR side for three
lines that must come from master: version 0.1.180 (content commits never
touch version; merging 0.1.179 would downgrade master), acp-kernel 0.0.100
(exact pin follows master), and the test:e2e:image script (#1843/#1857).
Lockfile re-synced from master plus the ws dev-deps.
…unners

Windows CI legs failed 1-2 random WS fault tests per run on log-read races:
the assertions snapshot bili.log right after a turn, but the server-side
writer has not flushed lines that are logically already emitted (e.g.
'checkpoint reset reason=response.failed' read 78ms into the turn). Add a
bounded readLogUntil helper and route the six synchronous log-read sites
through it; negative patterns are vetted against the same settled snapshot
(after any log-line filtering the test applies).
…c bridge

Codex CLI (0.147.0, feature-flagged responses_websockets[_v2]) dials
GET <base>/responses over WS in prefix mode: /bili/<upstream>/responses,
conversation header session-id, one text frame per Responses event, full
history replay every turn (previous_response_id is never sent), and a
prewarm probe (input:[], generate:false) per connection.

- ws-bridge: pluginMarker is now optional (prefix-lane codecs admit on
  loopback + conversation header + tunnel-guarded upstream, same trust
  level as prefix-mode HTTP); conversationHeader selects the client's
  session header; the claiming codec rides in WsBridgeContext for
  per-protocol transport policy (allowStreamFlag).
- responses-ws: probe frames bypass the ACP pipeline and relay verbatim
  (empty input would be normalized into a phantom turn by #1862 rules and
  tool/philosophy injection is pure byte inflation on a no-generation
  request); stream:true accepted when the codec opts in (codex always
  sends it; opencode keeps the strict absent-flag policy).
- tests/codex-responses-ws.test.ts: probe+turn pipeline ride, full-replay
  semantics, fold across a covered range, admission denials, non-stream
  protocol error.
@ranxianglei
ranxianglei force-pushed the 2026-10-02_opencode-responses-ws-generic branch from 346d1db to 163cfc5 Compare October 3, 2026 11:46
@ranxianglei
ranxianglei merged commit 700e6dd into master Oct 3, 2026
21 checks passed
ranxianglei pushed a commit to yingzhongshuoqi/billion-context that referenced this pull request Oct 4, 2026
… flush (ranxianglei#2040)

The title-persona test was the last reader in this file still using a raw
synchronous fs.readFileSync right after turn completion. On loaded runners
the tee-logger write lags the wire completion, so the snapshot misses a
line that was logically already emitted — observed as a red
windows-latest/Node 22 cell in PR ranxianglei#2034's CI (run 37179443315), green on
re-run, green on the other three matrix cells.

Use the established readLogUntil() polling helper (added by 97ff781 for
exactly this race class, ranxianglei#1968). Both original assertions are unchanged
and now vet the settled snapshot.
ranxianglei pushed a commit that referenced this pull request Oct 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants