Upstream: @opencode/plugin@2.2.1 compatibility report #96

TL;DR: @opencode/plugin 2.2.1 changes nothing that breaks these plugins. All five V2 plugins need only the dev pin bump. The V1-only prompt-inheritance plugin doesn't depend on this package. No published version breaks on OpenCode 2.2.1, and no peer range needs tightening. Two problems turned up that 2.2.1 did not cause: the vendored prompt sync has been broken since July, and the smoke scripts fail under the repo's pinned Bun 1.3.12.

Base: main @ cb6d3dde2. Bump: @opencode/plugin 2.2.0 → 2.2.1 (release, compare). OpenTUI stays at 0.7.0 in the upstream catalog.

Per-plugin verdict

Are published versions broken for users on 2.2.1? No. I diffed the 2.2.0 and 2.2.1 npm tarballs, and the shipped runtime JS is identical. The promise/adapter.js code that builds ctx.session.instructions / wait is unchanged, and host.js (the resolver) is unchanged. Only .d.ts files and package.json differ.

Gate results (scratch clone, dev pins bumped to 2.2.1 in 5 packages, bun install → lockfile moves @opencode/{plugin,ai,client,protocol,schema,util} to 2.2.1)

Upstream changes that matter

Type-level only. None of these change runtime behavior for these plugins.

• SessionDomain now picks wait and instructions from ExperimentalSessionApi instead of SessionApi (#59072, "group experimental SDK methods under client.experimental"). Property names and the adapter are unchanged, so ctx.session.instructions.entry.{list,put,remove} in opencode-output-styles/src/server.ts still typechecks and runs. Upstream now classes it as experimental.
• GenerateApi → ExperimentalGenerateApi for ctx.generate. The old alias is marked @deprecated … Removed in the next minor. No plugin here uses generate.
• New hook session.hook("experimental.idle", …) with background info (#59437, /goal). This is additive.
• GUI plugin SDK: new composer-pill menu popover and extra IconNames. Additive; nothing here uses the GUI SDK.
• Plugin loading / config: ManagedPolicy was removed from the plugin supervisor, the module loader and the config policy plugin (#59609, #59595). Plugin deny decisions now come only from config entries. The config schema adds timezone, experimental.image_generate (#60096) and experimental.schedules (#59457). Package resolution (host.js) did not change, and there were no keymap or command-registry changes. New built-in TUI commands are /goal and /schedule; no plugin here registers either name (AGENTS.md command-collision rule).
• The "Breaking changes" in the release notes only affect direct imports of @opencode/ai provider entry points, which the repo doesn't use.

Watch items (not blocking):

1. session.instructions is now experimental upstream. The output-styles style switching depends on it, so check the 2.3 notes for a rename or move.
2. The deprecated GenerateApi alias goes away in the next minor. Only relevant if ctx.generate gets adopted.

Pre-existing problems found (not caused by 2.2.1)

1. Vendored prompt sync is broken (opencode-agent-prompt-inheritance)

bun run sync:prompts fails with Failed to fetch …: 404. The default ref dev no longer has packages/opencode/ at all: 44b6938b2 "removed packages/opencode" (2026-07-21). The scheduled Sync OpenCode Prompts workflow has failed on every recent run I listed (Oct 25–28).

Did the upstream prompts change? Yes, compared with the V1 line (v1.19.5):

• default.txt differs: upstream dropped two verbosity examples ("2 + 2", "golf balls in a jetta") in 548648a3d (#26821).
• copilot-gpt-5.txt was deleted upstream as unused in b01498d3f (#59669, shipped in v1.19.5). Upstream system.ts has no copilot branch any more. It also added gpt-6 → gpt-astra.txt, muse → meta.txt, and kimi provider-ID matching, none of which provider-prompt.ts mirrors.
• anthropic, beast, codex, gemini, gpt, kimi, trinity: identical.

Suggested fix (not applied):

// scripts/sync-upstream-prompts.ts
const ref = process.env.OPENCODE_UPSTREAM_REF ?? "v1"; // V1 sources live on the v1 line; `dev` is V2-only
export const ALLOWED_FILES = [
  "anthropic.txt", "beast.txt", "codex.txt", "default.txt", "gemini.txt",
  "gpt.txt", "gpt-astra.txt", "kimi.txt", "meta.txt", "trinity.txt",
] as const; // copilot-gpt-5.txt removed upstream (#59669)

Then either keep the bundled copilot-gpt-5.txt as a frozen fixture (drop it from ALLOWED_FILES only) or align providerPromptForModel with upstream V1 system.ts. That second option is a behavior change for Copilot model IDs, so it's a maintainer call. Upstream V1 sources live on the v1 branch.

2. smoke scripts fail on Bun 1.3.12

output-styles and ram-monitor smoke fail with Cannot find module '@capybearista/opencode-output-styles/rpc' (and the …/server equivalent), and do so with both 2.2.0 and 2.2.1 pins. Root cause: @opencode/plugin/host resolve() only swallows probe errors when error instanceof Error. Under Bun 1.3.12 a failed Bun.resolveSync throws a ResolveMessage that is not instanceof Error (verified: instanceof Error: false, code: ERR_MODULE_NOT_FOUND), so the probe for a missing rpc/server subpath gets rethrown. Under Bun 1.4.4 (upstream's packageManager) both smokes pass. Users aren't affected, because OpenCode runs on its own bundled Bun. CI doesn't run smoke, so this hasn't shown up there.

Suggested fix (not applied): bump the root packageManager and the workflows' bun-version to Bun ≥ 1.4.4 together, or run smoke with that Bun version:

// package.json
"packageManager": "bun@1.4.4"

Peer ranges

No tightening needed. Nothing new in 2.2.1 is used, so >=2.0.x / >=2.1.0 / >=2.2.0 stay correct. Per AGENTS.md, keep the peer strings different from the new 2.2.1 dev pin so Dependabot doesn't rewrite them.

Method: npm tarball diff of @opencode/plugin and @opencode/client 2.2.0 vs 2.2.1, upstream tree diffs of packages/{plugin,sdk} and packages/core/src/{plugin,config}, and gates run in a throwaway clone that has since been deleted. Nothing was pushed.

Written by Devin