opencode v2.2.0: plugin fails to load — "Plugin must export a default definition with an id and an effect or setup function" #6146

Summary

After upgrading opencode from v2.1.x to v2.2.0, the hindsight-coding-agents plugin fails to load with:

Plugin must export a default definition with an id and an effect or setup function.
(cause: SchemaError(Expected object at ["default"]))

The plugin shows as failed, local in the TUI Plugins panel and the hindsight-coding-agent skill is not registered.

Environment

• opencode: v2.2.0
• @vectorize-io/hindsight-coding-agents: 0.8.2 (installed to ~/.hindsight/coding-agents)
• OS: macOS (darwin, Apple Silicon)
• Node: v22

Root cause

The plugin uses a clever dual-entry trick to support both opencode v1 and v2 from one package directory:

• v1 follows package.json main → dist/index.js (v1 plugin shape: { id, hooks })
• v2 ignores main and loads <dir>/index.js, which re-exports dist/opencode2.js (v2 plugin shape: default export { id, setup })

This relied on v2 resolving a plugin directory to <dir>/index.js.

In opencode v2.2.0, directory resolution changed: v2 now follows package.json exports["."].default (or main if no exports) — the same as v1. So it loads dist/index.js, gets the v1-shaped export, and the schema check rejects it because v1's default export isn't an object with an id + effect/setup.

Reproduction

1. Install the plugin per the docs (any path; mine was ~/.hindsight/coding-agents).
2. Add to ~/.config/opencode/opencode.json:

   { "plugin": ["/Users/you/.hindsight/coding-agents"] }

3. Run opencode v2.1.x → plugin loads (server log shows entrypoint=file:///.../index.js).
4. Upgrade to opencode v2.2.0, restart → server log shows:

   loading plugin id=.../coding-agents entrypoint=file:///.../dist/index.js
   failed to load plugin ... SchemaError(Expected object at ["default"])
   

   Note the entrypoint changed from index.js to dist/index.js — this is the smoking gun.

Local workaround (verified)

Two-line patch to the installed ~/.hindsight/coding-agents/package.json:

-  "main": "dist/index.js",
+  "main": "dist/opencode2.js",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "default": "./dist/opencode2.js"
     },

Then kill the long-running opencode serve --service process (restarting the TUI alone is not enough — the plugin is loaded by the server, which keeps running across TUI restarts):

pkill -f 'opencode serve --service'

After that, server log shows:

loading plugin id=.../coding-agents entrypoint=file:///.../dist/opencode2.js

and the plugin works again.

⚠️ This workaround breaks v1 compatibility (v1 also resolves via main/exports and would now load the v2 entrypoint). Anyone still on opencode v1 should not apply it.

Suggested fixes (upstream)

A few options, in increasing order of robustness:

1. Detect host version at runtime. Make dist/index.js (the file both v1 and v2 now load) a shim that inspects the host (e.g. process.env.OPENCODE_VERSION, or probe which API shape the loader passes to setup/hooks) and dynamically delegates to either the v1 or v2 implementation. This keeps one package working for both hosts.
2. Ship two packages / two install paths. E.g. @vectorize-io/hindsight-coding-agents (v1) and ...-opencode2 (v2), each with a single unambiguous entry. The installer picks based on detected opencode version.
3. Drop v1 support in a new major, point main/exports at dist/opencode2.js, and document the minimum opencode version.

Option 1 is the smallest change for users.

Diagnostics while debugging

Useful commands for anyone else hitting this:

# See which entrypoint opencode actually resolved
grep -i hindsight ~/.local/share/opencode/log/opencode.log | grep -iE 'loading plugin|failed'

# Verify what the default export looks like (v2 expects { id, setup|effect })
node -e "import('$HOME/.hindsight/coding-agents/dist/opencode2.js').then(m => console.log(Object.keys(m.default)))"