fix(opencode): support OpenCode 2.x via native tools and commands - #1213

All committers have signed the CLA.

🔍 OpenCodeReview found 4 issue(s) in this PR.

• ✅ Successfully posted inline: 4 comment(s)

Update: addressed the review findings.

Fixed — missing output cap in ocr_health.ts (bug/medium + part of duplication comment). The health tool's runOcr did not enforce maxOutputBytes. Added the same appendChunk guard (10 MiB default) and RunOptions.maxOutputBytes as ocr_review.ts, so all three copies now enforce the limit.

Not applied — clearTimeout(forceKillTimer) in finish() (bug/medium). I tried the suggestion and the repo's own test ocr_review force-kills a child that ignores cancellation fails with it (Process did not exit within 5000ms, reverted, suite green 22/22 again). Reason: on the abort/timeout/output-limit paths the order is terminateChild() (arms the SIGKILL in 3s) then finish() — clearing the timer in finish() disarms the force-kill that was just armed, so a SIGTERM-ignoring child is never reaped. The existing code is correct: close clears the timer once the process exits, and killProcessGroup is guarded by closed, so a fired timer after normal completion is a harmless no-op, not a leak.

Duplication (maintainability/medium x2) — kept self-contained deliberately. Each file under tools/ has its exports registered as individual tools by OpenCode (<filename>_<export>), so a shared helper module would itself be picked up as a (broken) tool definition. Self-contained files are the documented pattern (see https://opencode.ai/docs/custom-tools/); the three copies are byte-identical in the shared sections by construction.

Also fixed the commit author email so the commits link to @SHJordan for the CLA check.

Revision pushed: replaced the separate tools/+commands/ approach with the documented dual V1+V2 entrypoint in the single plugin file (export default { ...Plugin.define({ id, setup }), server }, per https://opencode.ai/v2/docs/build/plugins#support-v1). V2 tools/commands are registered from setup() reusing the exact V1 OCR logic (including the 10 MiB output cap from the earlier review finding), so that finding now holds by construction and the self-containment concern is moot. Verified: npm run check 23/23 green, dual file loads cleanly on opencode2 beta-19425 (no failed to load plugin), and the V2 tool/command path was exercised end-to-end against a scratch repo. Correction to my earlier comment: plugin-registered tools ARE possible on V2 via ctx.tool.transform; one known V2 limitation is documented in the README (no abort signal, timeouts only).

Approach looks right — I checked the V2 docs' "Support V1" section, and V2 reading id/setup() while ignoring server() means no double registration on 2.x. Pulled the branch: typecheck clean, 23/23 pass. Before merge:

Blocking

1. package-lock.json wasn't regenerated, so npm ci fails: Missing: @opencode/[email protected] from lock file. Please commit the lockfile — and note in the description that this dep pulls in ~296 packages.

2. The V2 schema drops V1's .int().positive() — it's just { type: "number" }. Reproducible with a stub context:

overallTimeoutMinutes=0  -> OpenCodeReview timed out after 0 seconds.
overallTimeoutMinutes=-1 -> OpenCodeReview timed out after -60 seconds.

concurrency: -4 and timeoutMinutes: 2.5 reach the CLI unchecked too. { "type": "integer", "minimum": 1 } fixes it.

3. Please add the AI/LLM disclosure AGENTS.md requires, including tools and models.

Not keen to defer

4. 1.x isn't verified live, and it's the version that works today. The object form only landed in OpenCode 1.18.29 (repo pins 1.18.5) and V1 loads function exports — so on >=1.18.29 it's unclear whether both default.server and the named export register the tools twice. That's what the assertion you relaxed was guarding. Please test on 1.x and record the result.

5. ~145 lines of V2 logic sit behind one shape assertion. The stub harness you already wrote would cover point 2 — mine was ~20 lines, so it should be cheap to move into test/.

Smaller notes (dropped period in the V2 command template, redundant as string casts, duplicated README sentence, stale "15-minute" line) I'll post separately.

Smaller notes, none blocking.

• V2 command template lost a sentence break. V1 renders context: $ARGUMENTS. If no target...; the split into TEMPLATE + SUFFIX drops the period, and an empty prompt yields a double space:

  ...business context: review my staged changes If no target is specified, ...
  ...business context:  If no target is specified, ...
  

  Start OCR_REVIEW_COMMAND_SUFFIX with ". If no target".

• as string casts are unnecessary. session.location.directory is already string & Brand<"AbsolutePath"> and session.subpath is already RelativePath | undefined. I removed both casts and typecheck still passes. Keeping them would swallow the error if directory ever becomes optional upstream.

• resolveSessionCwd has no fallback. V1 had context.worktree || context.directory || worktree; V2 is a single point of failure on ctx.session.get(). Plugin.Context exposes location.directory, so a fallback is cheap.

• V2 command registration lost V1's ??= guard. V1 preserved a user's own ocr-review command and has a test for it; editor.add is unconditional. Worth confirming what V2 does on a name collision.

• README: duplicated sentence. "Commit the plugin file if the integration should be shared with the project." appears twice in "Install for one project", the second time glued to the preceding paragraph. Also "copy the same plugin file ... instead" reads as if 2.x needs a different path, but the curl block above already does exactly that — only the deps differ. Same for the globally-install sections: two identical mkdir + curl blocks with the same raw URL will drift.

• README: the 15-minute timeout is stale. Both versions pass 30 minutes explicitly; runOcr's internal 15-minute default never applies to ocr_review. It's in the bullet list you already touched.

• README: as above points at the wrong path. The project-scoped step says to add the dep to .opencode/package.json "as above", but above is cd ~/.config/opencode && npm install. The V1 docs' approach is a package.json with a dependencies block, which OpenCode installs at startup — showing that snippet would fix both.

• Version pinning is inconsistent. package.json pins 0.0.0-beta-19425; the README says @opencode/plugin@beta. The tag moves, so users and CI will drift apart.

• Test name no longer matches. "module exposes only one OpenCode plugin entry point" now asserts two exports.

@Qiyuanqiii @lizhengfeng101 revision pushed addressing everything — walkthrough:

Qiyuanqiii (blocking): V1 hard dependency on the V2 package — fixed structurally, not just docs. The V2 API is now import type only and the default export is a plain object literal (Plugin.define is identity, verified in the published package). Built output imports only node:* + @opencode-ai/plugin, so 1.x needs just the one dep; README reflects exactly that.

Numeric schemas (both): fixed + tested. V2 numerics are now { type: integer, minimum: 1 }; new tests assert the shape for all five fields (the 0/-1 cases from the report can no longer validate).

Attachments in V2 commands: kept text-only deliberately, matching the V1 $ARGUMENTS templates; spreading attachments would break exactOptionalPropertyTypes and risk stale mention offsets after the rewrite. Noted in code.

15-min README line: fixed to the effective 30-minute tool default.

Lockfile: committed (package-lock.json, ~300 packages) with the dir .gitignore updated; clean-room npm ci + check green. Tradeoff noted for maintainers.

AGENTS.md disclosure: added to the PR body (tools used included).

1.x verified live (1.18.30 sandbox): plugin loads clean, exactly one init across sessions, both commands registered once — so no double registration from default.server + named export. @Qiyuanqiii please re-review when you get a chance.

Harness in test/: done (+6 V2 tests, 29/29 green), covering registration, schema shape, command-collision skip, session-cwd resolution + fallback, and template rendering.

Small notes, all applied: sentence break + no double space on empty prompt (tested), as string casts removed, resolveSessionCwd falls back to ctx.location.directory, V2 commands skip existing names via ctx.command.list() (restores the ??= semantics), README deduped to a single download block, misleading "instead" wording gone.

@SHJordan Nice fix. One thing worth confirming: @opencode/plugin is only pulled in via import type, which Bun strips at load time — so it shouldn't be needed at runtime on 2.x. Did you verify the plugin loads on 2.x without it installed? If it's type-only, the README's "2.x needs both packages" step is unnecessary and we can drop it (keeping @opencode-ai/plugin, which reviewArgs does need at module load).