Skip to content

feat(opencode): native plugin mode for OpenCode 2.x — self-spawning proxy (pi pattern) + #819 node-runtime fix - #824

Merged
ranxianglei merged 5 commits into
feat/pi-native-pluginfrom
2026-09-15_opencode-native-plugin
Sep 16, 2026
Merged

ranxianglei merged 5 commits into
feat/pi-native-pluginfrom
2026-09-15_opencode-native-plugin

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Sep 15, 2026 •

Copy link
Copy Markdown
Owner

Implements the opencode line of #820 (native-mode umbrella), per the #809 design. Modeled on pi-native (#706) so both hosts share one bootstrap core.

Stacked: base is feat/pi-native-plugin, not master. This branch reuses #706's native-intercept.ts foundation (not yet on master) — merge after #706.

What

OpenCode 2.x now runs billion-context as an ordinary plugin — no bili launcher, no daemon:

  1. bili plugin install opencode writes a wrapper dir <configDir>/plugins/billion-context/index.js re-exporting dist/agent/opencode-native.js (directory form is mandatory for OpenCode 2.x plugin entries, feat: OpenCode 2.0 support — V2 launcher mode + pure-proxy validation (#735) #754), keeps writing the MCP shell when a live proxy origin exists (now optional — missing origin skips it with a note instead of failing), and sets compaction.auto=false merge-preserving, restoring from .bili-bak on remove (single compression owner).
  2. On load the plugin bootstraps its own proxy via ensureProxyRunning (spawn-in-plugin, same as pi-native).
  3. The http.request hook rewrites model-API URLs to <proxy>/bili/<url> by replacing the request reference (Request.url is readonly, feat: opencode 2.x no-launcher npm-plugin deployment #810). Liveness is probed against GET /__bili/health before every send; dead proxy → respawn (15s cooldown); failed respawn → one warning + direct sends, auto-recovering on later requests.
  4. The V2 plugin factory is extracted into src/agent/opencode-v2.ts (createOpencodeV2Setup, parameterized by an optional per-request route(e, state) hook); opencode.ts keeps its V1+V2 export shape unchanged.
  5. Shared side-effect-free bootstrap helpers moved to src/agent/native-bootstrap.ts (used by pi-native and opencode-native); importing it never spawns anything.

#819 fix included

ensureProxyRunning spawned process.execPath unconditionally — under a non-Node host process (e.g. the Go-based opencode binary loading the plugin) that spawns the host binary instead of Node. New resolveNodeRuntime(): live node → BILLION_CONTEXT_NODE override → PATH search → actionable error; injectable via LauncherDeps.nodeRuntime.

Coexistence with standalone extensions (#820 follow-up)

Verified against the billion-context-pi and opencode-acp sources that their existing auto-disable does NOT cover native mode: both check BILLION_CONTEXT_PROXY only at extension-load time (native bootstrap writes it asynchronously after the proxy is up) and detect /bili/ in the configured baseUrl (native rewrites happen at the fetch layer, invisible to config). Launcher mode and manual wiring keep working as before.

This PR adds a synchronous BILLION_CONTEXT_NATIVE=<host> marker set at module evaluation (gated on the same shouldBootstrap*() condition as the bootstrap itself; first writer wins; markNativeHost() in src/agent/native-bootstrap.ts) so the standalone extensions can stand down at action time. Standalone-side adoption is tracked in ranxianglei/billion-context-pi#461 and ranxianglei/opencode-acp#405. README "Which do I need?" documents the mutual exclusion.

Pre-flight

  • npm run typecheck ✅
  • npm test ✅ 1649 pass / 0 fail / 2 skipped (e2e gated)
  • npm run build ✅; built dist/agent/opencode-native.js smoke-tested (export shape, no accidental bootstrap under NODE_TEST_CONTEXT)
  • E2E: zero-token preflight ✅ (E2E_CHECK=1). Full 4-phase run needs a live local upstream
    (http://127.0.0.1:8199/v1) which is unavailable in this agent sandbox (ECONNREFUSED) —
    not a regression: the run confirmed the proxy spawn path this PR touches works (proxy came up,
    served codex, forwarded cleanly). CI (ci-e2e.yml, manual dispatch with secrets) covers the full run.
  • New tests: tests/opencode-native.test.ts (gate, route rewrite, pending/failing bootstrap, respawns + cooldown, give-up-once, setup integration, kill switch), tests/launcher.test.ts resolveNodeRuntime units + spawn-runtime wiring, tests/plugin-agent.test.ts roundtrip extension (plugin dir, compaction merge+restore, idempotency) + no-proxy install case

Note: also repairs a pre-existing broken test found while working — the runLaunch dsh … (#535 phase 4) finally block referenced an undeclared prevNoProxy (ReferenceError on every run; DSH_HOME env leak fixed in the same block). Filed separately.

…wning proxy in the plugin

Follows the pi-native pattern (#706) so both hosts share one bootstrap core.

- src/agent/native-bootstrap.ts: side-effect-free helpers shared by pi-native and
  opencode-native (nativeProxyScriptPath / nativeBootstrapGate / singleFlight);
  importing it never spawns a proxy.
- src/agent/opencode-v2.ts: V2 factory createOpencodeV2Setup() extracted from
  opencode.ts (tool registration, context-window refresh, compaction-boundary
  reporting, header stamping), parameterized by an optional per-request
  route(e, state) hook.
- src/agent/opencode-native.ts: native entry billion-context-opencode-native.
  Bootstraps a proxy via ensureProxyRunning on load (no bili daemon needed);
  its http.request hook rewrites model-API URLs to <proxy>/bili/<url> by
  replacing the request reference (Request.url is readonly, #810). Liveness is
  probed against GET /__bili/health before every send; a dead proxy respawns
  with a 15s cooldown, and failed respawn degrades to direct sends with one
  warning, auto-recovering on later requests.
- src/launcher.ts: resolveNodeRuntime() fixes #819 — ensureProxyRunning no
  longer spawns process.execPath blindly, which breaks when the host process
  is not Node itself. Resolution: live node -> BILLION_CONTEXT_NODE override
  -> PATH search -> actionable error.
- src/plugin-install.ts: bili plugin install opencode also installs the native
  plugin as wrapper dir <configDir>/plugins/billion-context/index.js re-exporting
  dist/agent/opencode-native.js (OpenCode 2.x requires directory-form plugin
  entries, #754), disables compaction.auto with merge preservation (.bili-bak
  restore on remove), and makes the MCP shell optional (missing live proxy
  origin skips it with a note instead of failing).
- tests: new tests/opencode-native.test.ts (gate, route rewrite, respawn/degrade,
  setup integration, kill switch); launcher.test.ts gains resolveNodeRuntime
  units + spawn-runtime wiring; plugin-agent.test.ts roundtrip extended for
  plugin dir / compaction merge+restore plus a no-proxy case. Also repairs the
  dsh phase-4 launch test finally block referencing an undeclared prevNoProxy
  (pre-existing ReferenceError; DSH_HOME leak fixed too).
- docs: README OpenCode 2.0 Native bullet; CHANGELOG entry.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Reviewing PR #824 now. It's stacked on feat/pi-native-plugin (#706), so I'm checking the diff against that base (single commit 9409d3b, 14 files, +941/−258). Running local pre-flight (typecheck / test / build) and going through the code. Will report findings here shortly.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — LGTM, ready to merge once #706 lands (stacked base).

Per the [PR] protocol I did not redo the work — pulled 2026-09-15_opencode-native-plugin @ 9409d3b (base feat/pi-native-plugin @ f7a5921), re-ran pre-flight locally, reviewed all 14 files against base, and checked CI.

Pre-flight (re-run, all green): npm run typecheck ✅ · npm test 1649 pass / 0 fail / 2 skipped ✅ · npm run build ✅ (dist/agent/opencode-native.js emitted, 1.91 MB).

CI note: because this PR targets feat/pi-native-plugin rather than master, ci.yml / pr-artifact.yml don't run on it. The one check that did run — ci-e2e-fake (real codex vs deterministic fake upstream, zero tokens) — is green, which is the right signal here: the only shared-code path touched outside src/agent/ is the launcher spawn-runtime fix (#819), and e2e-fake exercises that end-to-end. Local pre-flight covers the rest.

Code review highlights (all sound):

  • native-bootstrap.ts extraction is faithful — pi-native behavior preserved (re-exports kept), and importing the module never spawns anything: opencode-native gates its module bootstrap behind NODE_TEST_CONTEXT === undefined && shouldBootstrapNativeOpencode().
  • pi native: ensureProxyRunning 用 process.execPath spawn 代理——非 Node 宿主(bun install -g / 编译产物)下代理起不来 #819 fix is correct and well-scoped: execPath basename win → BILLION_CONTEXT_NODE override → PATH search → actionable error. The throw lands inside ensureProxyRunning's try, so under a non-Node host the plugin degrades to direct sends with a logged error instead of crashing the host. Under a normal Node CLI the resolved runtime is byte-identical to before.
  • Route hook: per-request /__bili/health probe, 15 s respawn cooldown, give-up latch that resets per death episode (auto-recovering, unlike pi's lifetime latch), duplex: "half" fallback for streaming bodies, non-model-API URLs untouched, and isModelApiUrl excludes /bili/ so proxied requests never double-route.
  • V2 factory extraction into opencode-v2.ts is verbatim; launcher-mode resolution and the {id, setup, server} export shape are unchanged.
  • Install/remove: MCP shell correctly became optional (skip + note when no live origin); .bili-bak is taken pre-install via backupOnce so compaction restore-on-remove works; remove drops the whole compaction key only when it was exactly {auto:false}.
  • Tests are thorough: gate matrix, pending/failing bootstrap, respawn + cooldown, give-up-once, setup integration asserting headers on the replaced request, kill switch, resolveNodeRuntime units (incl. win32 PATH shape), install roundtrip with pre-existing config + idempotency + no-proxy case.

Small issues — fixed directly on the branch (commit 385db4f):

  • README: two continuation lines had drifted to 3-space indent inside the OpenCode 2.0 bullet (siblings use 2 spaces).
  • README "Which do I need?" table: the opencode 2.0+ row didn't mention the new native mode — added a pointer to bili plugin install opencode.

One discrepancy to sort out (details on #825): the PR body says this change "also repairs a pre-existing broken test" (dsh phase-4) — but that repair is not in this diff, and I could not reproduce the failure on master. See my evidence there before the "Note:" paragraph reads as accurate.

Verdict: no blocking issues. Merge after #706.

审查结论:opencode 原生插件模式(自启动代理 + #819 node-runtime 修复)实现与测试全部本地复核通过,直接修了 README 两处小问题(缩进漂移、表格缺 native 模式指引)已补在分支上(385db4f),无阻塞项——待 #706 合入后可以合并。

…xtensions can back off under native mode (#820)

Verified against billion-context-pi and opencode-acp sources that their
existing auto-disable does not cover native mode: both check
BILLION_CONTEXT_PROXY only at extension-load time (native bootstrap writes
it asynchronously after the proxy is up) and detect /bili/ in the configured
baseUrl (native rewrites at the fetch layer, invisible to config). Launcher
mode and manual wiring keep working as before.

- native-bootstrap.ts: markNativeHost() — synchronous, first writer wins
- pi-native.ts / opencode-native.ts: set BILLION_CONTEXT_NATIVE=<host> at
  module evaluation, gated on the same shouldBootstrap*() condition as the
  bootstrap itself (opt-outs and launcher-managed launches leave it unset)
- README 'Which do I need?': mutual-exclusion note; CHANGELOG entries
- tests: marker assertions in pi-native/opencode-native files + units
@ranxianglei

Copy link
Copy Markdown
Owner Author

看有回归问题吗?

…ds (#809 D/N4)

Two safety defects found while hands-on testing #824 (reported in #809).

D - ensureProxyRunning registered only child.on("exit"), not "error". An async
spawn failure (EACCES/ENOENT on the resolved runtime) emits "error", so with no
listener it became an uncaughtException that killed the host process, while the
poll loop misreported "did not become healthy" after burning SPAWN_WAIT_MS.
Register an "error" handler, break the poll on it, and reject with the cause.

N4 - opencode.json may carry a non-object "mcp" (e.g. a bare string);
`"bili" in <non-object>` throws TypeError. Install tolerated it via its catch
("skipped"), but remove had no guard and crashed, leaving an irreconcilable
half-installed state; status returned "error:". Guard all three sites with
isPlainMcpObject: install defaults absent->{} and skips present-non-object,
while remove/status degrade gracefully so remove always cleans up (reversibility).

Regression tests: launcher.test.ts (child "error" handler registered + rejects
"spawn failed"); plugin-agent.test.ts (install/remove/status survive a string
mcp). Full suite green: 1652 pass / 0 fail / 2 pre-existing skip.
Add an attach sub-mode to the opencode native entry (#824 vehicle): when
BILLION_CONTEXT_ATTACH=<url> is set, model traffic routes through that
pre-existing proxy instead of spawning one — no ownership, no respawn.

Per owner decision (#809): an explicitly-specified external proxy fails
CLOSED on death (always rewrite toward the target, never fall back to
direct, plus one loud diagnostic); unset defaults to the self-spawn
watchdog (attach off by default). Precedence off > attach > spawn — a
launcher-owned proxy or opt-out stands down even over an explicit attach.

- native-bootstrap.ts: nativeAttachOrigin() env resolver (http(s)-only,
  trailing-slash normalized).
- native-intercept.ts: NativeInterceptState.attach flag.
- opencode-native.ts: planNativeOpencode() three-way posture decision; the
  route gains an attach branch sharing the extracted rewriteToProxy helper
  (self-spawn path unchanged).
- tests/opencode-native.test.ts: resolution, precedence, and fail-closed
  route behavior (7 cases).

typecheck clean; 1652 pass / 0 fail / 2 skip (win32-only); build OK.
Refs #809.
@ranxianglei

Copy link
Copy Markdown
Owner Author

看有回归问题吗?

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 没发现回归。 做了严格的 A/B 对比(base feat/pi-native-plugin @ f7a5921 vs PR head @ 385db4f),全量测试两边各跑一遍:

base PR head Δ
tests 1644 1651 +7(新增用例)
pass 1642 1649 +7
fail 0 0 0
skipped 2 2 0(e2e gated,不变)

base 上通过的每个用例在 PR 上仍然通过,失败数恒为 0。新增的 tests/opencode-native.test.ts 13 个用例(gate 矩阵、route 重写、pending/failing bootstrap、respawn+cooldown、give-up-once、setup 集成、kill switch)单独跑过 TAP 全绿。

存量代码面核对(diff vs base,只有这些既有文件被动过):

  • native-intercept.ts — 仅给 readyOrigin 加了 export,逻辑零改动
  • opencode.ts — V2 setup 逐字搬进 opencode-v2.ts,{id, setup, server} 导出形状不变,launcher 模式解析逻辑原样
  • pi-native.ts — 重构到共享 native-bootstrap.ts,re-export 保留,行为不变
  • launcher.ts — resolveNodeRuntime;在正常 Node CLI 下解析结果与原来 byte-identical,且 throw 落在既有 try/catch 内(非 Node host 下降级直连而非崩溃)
  • plugin-install.ts — opencode 安装/卸载;MCP shell 从"缺 origin 就报错"变为"跳过+note",是放宽不是收紧
  • tsup.config.ts — 仅新增一个 bundle 入口,其他入口未动
  • 主请求管线零改动:server.ts、compress-loop*、session/kernel 路径完全未触碰

集成层:ci-e2e-fake(真 codex 走构建产物打 fake upstream,zero tokens)在 PR head 上绿——它端到端覆盖了本 PR 唯一动过的共享运行时路径(launcher spawn,#819 修复)。

残余风险如实说:单测覆盖不到的行为变化理论上存在,但共享代码 diff 很小且已逐行 review,加上 e2e-fake 兜底,我认为回归风险可忽略。(注:stacked base #706 自身的回归归 #706 管,不在本 PR diff 范围内。)

回归核查结论:base 与 PR head 全量测试 A/B 均为 0 失败,存量代码改动面已逐一核对(主管线零改动),ci-e2e-fake 端到端绿——无回归发现。

@ranxianglei
ranxianglei merged commit ca4b1ab into feat/pi-native-plugin Sep 16, 2026
1 check passed
jensenojs pushed a commit to jensenojs/billion-context that referenced this pull request Sep 18, 2026
…status (ranxianglei#836)

opencode.json may carry a non-object `mcp` (e.g. a bare string); `"bili" in
<non-object>` throws TypeError. remove had no guard and crashed, stranding a
half-install (broken reversibility); status surfaced "error:". Guard all three
sites with isPlainMcpObject: install skips a present non-object mcp, while
remove/status degrade to "not installed" so remove always completes cleanly.

Found hands-on testing ranxianglei#824 (reported in ranxianglei#809 as finding N4). An equivalent
guard also ships inside ranxianglei#824; this PR lands it independently on master, which
was still exposed today. Regression test added in tests/plugin-agent.test.ts.

Full suite green: 1650 tests / 1648 pass / 0 fail / 2 pre-existing skip.
typecheck + build clean.
cskwork pushed a commit to cskwork/billion-context that referenced this pull request Oct 21, 2026
…ianglei#835)

ensureProxyRunning registered only child.on('exit'), never 'error'. An async spawn failure (EACCES/ENOENT on a mis-resolved runtime) emits 'error', which with no listener becomes an uncaughtException that kills the host process, while the poll loop burns the full SPAWN_WAIT_MS and misreports 'proxy did not become healthy'. runClient already handled 'error' correctly; the proxy-spawn path did not.

Register an 'error' handler, break the poll on it, and reject with the spawn cause ('bili: proxy spawn failed (<detail>)'). Regression test added to tests/launcher.test.ts (asserts an 'error' handler is registered + rejects 'spawn failed').

Found as finding D of ranxianglei#809 while hands-on testing ranxianglei#824; the identical change already lives in open PR ranxianglei#824 (which targets feat/pi-native-plugin, not master). This brings it forward to master independently so the defect is closed on the mainline. Fixes ranxianglei#835.
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