tui: Host.resolve treats Bun ResolveMessage as fatal for missing plugin subpaths #48122

Activity

1. github-actions

   assigned

   kitlangton

   on Sep 9, 2026
2. DDwsgood commented on Sep 9, 2026

   

   DDwsgood

   on Sep 9, 2026

   Author

   More actions

   Related reports found while checking for duplicates (different mechanisms, listed for triage):

   • tui: local plugins silently fail to load on Windows since beta-18721 upgrade (cli.json migration regression) #46408 — TUI local plugins silently fail to load on Windows since the beta-18721 cli.json migration (silent absence with zero diagnostics, whereas this issue fails loudly in the plugin error panel).
   • [BUG] 「V2 (next-17444)」local .ts plugins fail to load on Windows #42763 — local .ts plugins fail to load on Windows (older report, possibly overlapping with tui: local plugins silently fail to load on Windows since beta-18721 upgrade (cli.json migration regression) #46408).

   Note: the instanceof Error gate analyzed here predates both of those reports (introduced by ed3259a9b7), so this is likely an independent cause.
3. opencode-agent

   added

   2.0

   on Sep 9, 2026
4. alvaropas17 commented on Sep 30, 2026

   

   alvaropas17

   on Sep 30, 2026

   More actions

   Same root cause, worse surface: a server-side plugin reload dies and registers zero agents

   I hit the exact Host.resolve gate described above, but on the server plugin-reload path instead of the TUI plugin panel. There the consequence is not "one target shown as failed" — the whole plugin generation dies, including builtins, so no agents are registered at all and the session fails with Agent not found <id>. Since it is the same predicate and the same suggested fix, I'm adding the evidence here rather than opening a duplicate.

   • Version/commit: 2.0.18, branch v2, HEAD 5bcf6b7 (built and run from source). Also reproduced on an installed binary dated 2026-09-27, and on a compiled binary.
   • Runtime: Bun, Windows.

   Summary

   Starting a new server from source with a config that includes any directory plugin lacking a server/index entrypoint ends with 0 agents and the agent call failing with Agent not found <id>. The server logs the fatal plugin-generation failure:

   level=ERROR message="failed to reload plugins"
     cause="Cause([Die(ResolveMessage: Cannot find module '<dir>\server' from '<dir>')])"
   

   Reproduced with <config>/plugins/quote-probe (contains only tui.ts) and with <dir>/opencode2-telegram (no server entrypoint).

   Impact

   The failure is total, not partial: because the rethrown ResolveMessage aborts the whole plugin generation, builtins are dropped too, so every agent disappears. The user-facing error (Agent not found <id>) gives no hint that a single optional subpath probe is the cause. This is the same symptom family reported in #48121 (Session.AgentNotFoundError after a failed reload), but here it is deterministic and has a concrete trigger.

   Steps to reproduce

   1. Configure a directory plugin that has no server/index entrypoint, e.g. a plugin dir containing only tui.ts:

      // <config>/opencode.json
      { "plugin": ["<config>/plugins/quote-probe"] }

   2. Start a fresh server from source (e.g. bun run … serve, private --standalone).

   3. Watch the server log: failed to reload plugins, cause="Cause([Die(ResolveMessage: Cannot find module '<dir>\server' from '<dir>')])".

   4. Run any agent: it fails with Agent not found <id>.

   Minimal, framework-free check of the underlying predicate (Bun):

   // Bun 1.x
   try {
     Bun.resolveSync("<plugin>/server", "<plugin>")
   } catch (e) {
     console.log(e.constructor.name, e instanceof Error, e.code)
   }
   // → ResolveMessage false ERR_MODULE_NOT_FOUND

   That is exactly the object the gate rejects.

   Root cause

   packages/plugin/src/host.ts → Host.resolve() tolerates a failed probe only when error instanceof Error and error.code is in { ENOENT, ENOTDIR, MODULE_NOT_FOUND, ERR_MODULE_NOT_FOUND, ERR_PACKAGE_PATH_NOT_EXPORTED, ERR_UNSUPPORTED_DIR_IMPORT }; anything else is rethrown.

   In the Bun runtime, resolveModule (packages/util/src/runtime/import.bun.ts) uses Bun.resolveSync, which throws a ResolveMessage with instanceof Error === false and code === "ERR_MODULE_NOT_FOUND". Because it does not pass the instanceof Error check, it is rethrown instead of skipped. Effect.sync then captures the throw as Die, killing the whole plugin generation (builtins included), which is why zero agents end up registered.

   Empirical verification of the mechanism (not inference): Bun.resolveSync("<dir>/server", "<dir>") on a missing path throws ResolveMessage with instanceof Error === false; wrapping the same failure in a real Error carrying the same code makes Host.resolve tolerate it and return the present entrypoints.

   Minimal fix

   Same as suggested in the issue above; either narrow change works:

   • (a) In Host.resolve, accept the missing-path condition based on a string error.code even when instanceof Error is false (read (error as { code?: unknown }).code, require it to be a string, apply the existing whitelist).
   • (b) In resolveModule (packages/util/src/runtime/import.bun.ts), rethrow a real Error preserving code.

   Note: a compiled binary hits the same path (it uses the same Bun condition / Bun.resolveSync), and the 2026-09-27 installed binary also returns 0 agents — so this is not source/dev-only.

   Workaround (temporary, not a fix)

   Until the predicate is fixed, avoid giving the probe a missing entrypoint: ensure each configured directory plugin has a server or index file (a stub server/index.ts is enough). Then Host.resolve never throws the fatal ResolveMessage.

   How this was surfaced (context)

   Found while validating an opt-in experiment, experimental.direct_exec — letting the shell tool accept executable + argv instead of a command string, so it can spawn a process directly (no PowerShell hop on Windows). A fresh server built with that experiment active had a directory plugin without a server entrypoint in config, which triggered the reload death above and masked the experiment for a while.

   Experiment files (all reverted on 2026-09-30, no PR): packages/schema/src/config/experimental.ts, packages/core/src/config/normalize.ts, packages/core/src/shell.ts, packages/core/src/shell/parse.ts, packages/core/src/tool/plugin/shell.ts, packages/plugin/src/effect/shell.ts, packages/plugin/src/promise/shell.ts; tests/bench created and removed: packages/core/test/direct-exec-parity.test.ts, packages/core/test/fixture/direct-exec.ts, packages/core/test/perf-direct-exec.harness.test.ts.

   A/B validation (private --standalone server from source, agent build, one run per path):

   Path	Input	Child of bun.exe	Output	Total	Shell phase
   Normal (flag off)	command="rg needle sample.txt ."	bun.exe → powershell.exe → rg.exe	needle here	8.961 ms	225 ms
   Direct (flag on)	command=null, executable=<abs rg.exe>, argv=["needle","sample.txt"]	rg.exe (direct, no PowerShell)	needle here	9.326 ms	62 ms

   Result: PASS (exact input, no PowerShell in the tree, correct output). The saving is confined to the shell phase (225 → 62 ms, ~72 %); it does not show up in total turn time (n=1). Reported only as provenance for the plugin failure above — the direct_exec experiment itself is reverted and out of scope here.
5. eana

   added a commit that references this issue on Oct 26, 2026

   feat(module): add ponytail opencode plugin

   ...

   f851d4b
6. opencodejr commented on Oct 28, 2026

   

   opencodejrBot

   on Oct 28, 2026

   Contributor

   More actions

   Thanks for the detailed report and the probe output. I could only reproduce this on the Bun version you used, not on the one the repo targets:

   • On Bun 1.3.14, Bun.resolveSync throws a ResolveMessage that is not instanceof Error. Host.resolve on a local plugin with index.ts but no server.ts then throws Cannot find module '<dir>/server', exactly as you describe. This is still true on the latest dev (d1bd20fa).
   • On Bun 1.4.4, which the repo pins in package.json (packageManager: [email protected]), ResolveMessage is an Error. The same call returns { server: "file://.../index.ts", tui: undefined, rpc: undefined } without throwing.
   • The released CLI (@opencode/[email protected]) has Bun 1.4.4 built in, so it isn't affected either.

   So this only shows up when the source TUI runs on a Bun older than the pinned version. Upgrading Bun (bun upgrade) should fix it for your dev setup. If you still see plugins marked as failed with Bun 1.4.4, or with a released opencode binary, please reply with the version and the plugin setup. Your suggested check (any thrown value with a whitelisted string code) would still be a reasonable hardening for maintainers to consider.

   Related plugin-loading reports, which look like different causes: #58647, #49608, #50434, #46095.
7. opencodejr

   closed this as not plannedon Oct 31, 2026
8. opencodejr commented on Oct 31, 2026

   

   opencodejrBot

   on Oct 31, 2026

   Contributor

   More actions

   Closing this as not planned since we haven't heard back. In our testing, Host.resolve only failed when the source TUI ran on Bun 1.3.14. That version throws a ResolveMessage that isn't an Error. On Bun 1.4.4, which the repo pins, and in the released @opencode/cli binary (it has Bun 1.4.4 built in), missing /server and /rpc subpaths are skipped as intended. Upgrading Bun should fix your dev setup.

   If plugins still show as failed with Bun 1.4.4 or a released opencode binary, please comment with the version and plugin setup and we can reopen this. Thanks again for the detailed report.