Skip to content

Support OpenCode V2 plugin API (dual V1/V2 default export, ported session/event backend) - #14

Draft
mike2194 wants to merge 1 commit into
leecoder:mainfrom
mike2194:fix/opencode-v2-plugin-compatibility
Draft

mike2194 wants to merge 1 commit into
leecoder:mainfrom
mike2194:fix/opencode-v2-plugin-compatibility

Conversation

@mike2194

@mike2194 mike2194 commented Nov 3, 2026 •

Copy link
Copy Markdown

Summary

Fixes #13. opencode-slack-agent fails to load on OpenCode V2 with:

Plugin must export a default definition with an id and an effect or setup function.

V2 requires the default export to have an id plus setup() (or effect()). This
package only exported the V1 { id, server() } shape.

V2 also renamed or restructured every server endpoint this plugin calls (session
creation, session messages, prompt, the permission-reply endpoint, and the SSE event
stream shape), confirmed against a live OpenCode 2.2.5 server's /openapi.json and
the @opencode/plugin/@opencode/client type definitions. A setup() that just
re-ran the existing V1 server() body unchanged would not have worked.

What changed

  • Added a SlackAgentBackend interface with two implementations:
    • createV1Backend(client) — wraps the V1 PluginInput["client"] SDK, same
      endpoints the plugin already called.
    • createV2Backend(ctx) — wraps a V2 setup(ctx) context: ctx.session.create /
      .context / .prompt / .switchAgent / .switchModel, ctx.event.subscribe()'s
      granular session.tool.* / session.reasoning.* / permission.asked lifecycle
      events (replacing V1's single flat message.part.updated event), and
      ctx.permission.reply.
  • Ported handleMessage, syncAssistantMessagesSinceCursor, and handleCommand to
    call backend.* instead of pluginClient.* directly, so the Slack-facing behavior
    (formatting, session store, slash commands, background-task polling) is unchanged
    and shared between both backends.
  • src/v2-adapter.ts holds the pure V2-message-shape → legacy-shape mapping, unit
    tested in isolation (bun test).
  • Default export now follows OpenCode's documented V1/V2 dual-support
    pattern
    :
    { ...Plugin.define({ id, setup }), server }.
  • Added a slack_test_prompt debug tool (alongside the existing slack_status) that
    runs handleMessage without a Slack connection, so this plugin can be verified
    against a real server without a Slack workspace.
  • Removed the unused better-sqlite3 dependency (not referenced anywhere in src/).
    Its native build failed under newer Node versions and was blocking npm install /
    bun install for local development; this was pre-existing and unrelated to the V2
    fix, but unblocking installs was necessary to work on this PR at all.

Known gaps on V2 (documented in README's new "OpenCode V2" section)

  • question tool replies are not forwarded. The V2 plugin context has no
    ctx.session.form.* (confirmed against the SessionDomain type, which only
    Picks a specific method list that excludes form), which is what would be needed
    to answer the agent's question tool from outside. Forwarding the question to
    Slack still works; the bot now tells the user to answer in the OpenCode session
    directly instead of silently dropping the Slack reply.
  • Plan/todo updates lose their dedicated checklist formatting. V2 removed the
    todo.updated event; the todo tool now surfaces through the same generic
    tool-call lifecycle as any other tool, so it renders as a plain 🔧 progress line.
  • !agent/@agent overrides become sticky for the session (ctx.session.switchAgent
    changes the session's default going forward) instead of applying to only the one
    message, because V2 has no per-message agent override on session.prompt.

Testing

  • bun test — unit tests for the V2 message-shape mapping (src/v2-adapter.ts),
    written before the implementation (red, then green).
  • npx tsc --noEmit and npm run build — clean.
  • Live integration test against a real OpenCode 2.2.5 server (opencode serve) in a
    scratch project, with this branch loaded as a local plugin path:
    • GET /api/plugin shows this plugin "status": "active", confirmed side-by-side
      in the same response against the unpatched opencode-slack-agent@latest npm
      package, which shows the exact reported "status": "failed" with the exact
      reported error message.
    • Called the new slack_test_prompt debug tool through a real session/prompt.
      Plugin logs confirm the full path executed against the live V2 server: session
      created via ctx.session.create, prompt sent via ctx.session.prompt, turn
      events subscribed via ctx.event.subscribe, idle detected, and the assistant's
      final message correctly fetched and mapped back via ctx.session.context +
      mapSessionMessageToLegacyShape.

This is a draft because the known gaps above (especially question tool replies)
have not been exercised against a real Slack workspace, only against the OpenCode
server directly. I'd like feedback on the question-tool gap in particular before
merging — happy to adjust the approach if there's a plugin-reachable API for it I
missed.


Summary by cubic

Fixes the plugin failing to load on OpenCode V2 by adding V2 API support alongside the existing V1 path. The default export now includes both a V2 setup() and the original V1 server(), so the package works on both host versions.

  • Adds a shared SlackAgentBackend interface with createV1Backend (wraps the V1 SDK client) and createV2Backend (wraps the V2 setup(ctx) context), and ports message handling, session syncing, and commands to use it. Slack-facing behavior (formatting, session store, slash commands, background-task polling) is unchanged and shared.
  • Maps V2 message shapes to the legacy format in a new src/v2-adapter.ts, unit tested with bun test.
  • Adds a slack_test_prompt debug tool that exercises the full session/prompt/turn-event path without a Slack connection, for verifying against a real server.
  • Removes the unused better-sqlite3 dependency, which was blocking installs under newer Node versions.
  • Adds a test script (bun test) to package.json.

Known gaps on V2

  • Replying from Slack to the agent's question tool is not supported; the V2 plugin API has no reachable way to answer it, so the bot tells the user to answer in the OpenCode session.
  • Plan/todo updates render as a generic tool-progress line instead of a formatted checklist (V2 removed the todo.updated event).
  • !agent/@agent overrides switch the session's agent going forward instead of applying to a single message.

Written for commit c4451aa. Summary will update on new commits.

View guided diff

OpenCode V2 requires a plugin's default export to have an `id` plus a
`setup` (or `effect`) function. This package only exported the V1
`{ id, server }` shape, so it failed to load on V2 with:

  Plugin must export a default definition with an id and an effect or
  setup function.

V2 also renamed or restructured every server endpoint this plugin
uses (session creation/messages/prompt, the permission reply
endpoint, and the SSE event stream), so a V2 `setup()` cannot just
call the existing V1 `server()` body unchanged.

This adds a `createV2Backend`/`createV1Backend` pair implementing a
shared `SlackAgentBackend` interface, and ports `handleMessage`,
`syncAssistantMessagesSinceCursor`, and `handleCommand` to it instead
of calling `pluginClient` directly. The package now default-exports
both a V2 `setup()` and the original V1 `server()`, following
OpenCode's documented dual-support pattern, so it keeps working on V1
hosts.

Known gaps on V2 (see README "OpenCode V2" section):
- Replying to the agent's `question` tool from Slack is not supported;
  the V2 plugin API has no reachable way to answer it.
- Plan/todo updates render as a generic tool-progress line instead of
  a formatted checklist (V2 removed the `todo.updated` event).
- `!agent`/`@agent` overrides switch the session's agent going
  forward instead of applying to one message only.

Also:
- Added a `slack_test_prompt` debug tool that exercises session
  creation, prompting, and turn-event handling without a Slack
  connection, for verifying this plugin against a real server.
- Removed the unused `better-sqlite3` dependency (not referenced
  anywhere in `src/`); its native build fails under newer Node
  versions and was blocking `npm install` for development.

Fixes leecoder#13
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.

Plugin fails to load on OpenCode V2: default export missing setup/effect

1 participant