feat(ai): OpenCode provider via HTTP + SSE (#379)

* feat(ai): add OpenCode provider via HTTP + SSE

Bundle @opencode-ai/sdk to spawn `opencode serve` and communicate via
HTTP REST + SSE. Richest provider: fork, resume, streaming, tools, and
runtime permission approvals all work natively.

- OpenCodeProvider: lazy server spawn, shared HTTP client, dynamic model
  discovery via GET /provider
- OpenCodeSession: SSE event drain loop, system prompt via API field,
  permission reply (once/reject), abort via HTTP
- mapOpenCodeEvent: SSE → AIMessage mapping (text deltas, tool lifecycle,
  permissions, session status, errors)
- 11 new event mapping tests (78 total, 157 expect calls)

For provenance purposes, this commit was AI assisted.

* docs(ai): add OpenCode to AI features guide and code review docs

For provenance purposes, this commit was AI assisted.

* fix(ai): prevent double server spawn in OpenCode ensureServer()

Use a promise-mutex pattern so concurrent callers (e.g. fetchModels +
createSession) share a single server spawn instead of racing to create two.
Also remove empty finally block from SSE drain loop.

For provenance purposes, this commit was AI assisted.

* fix(ai): await SSE subscribe in OpenCode provider

The SDK's event.subscribe() is async — must be awaited before
destructuring the stream.

For provenance purposes, this commit was AI assisted.

* fix(ui): scrollable model dropdown with search filter

Cap dropdown height at min(320px, 50vh) so it doesn't overflow the
viewport when providers expose many models (e.g. OpenCode with 20+).
Add a search/filter input when there are more than 8 models.

For provenance purposes, this commit was AI assisted.

* fix(ai): close SSE stream, rename to opencode-sdk, move dep to root

- Close SSE stream in finally block to prevent connection leak on
  abort/early return
- Rename provider from opencode to opencode-sdk for consistency with
  claude-agent-sdk, codex-sdk, pi-sdk
- Move @opencode-ai/sdk dependency to root package.json alongside the
  other SDK dependencies

For provenance purposes, this commit was AI assisted.

* feat(ui): add first-run AI setup dialog for provider selection

Show a one-time modal on first review when AI providers are available.
Users pick a default provider and model from a 2-column grid, with a
brief feature intro and auth disclaimer. Persists via cookie, can be
changed later in Settings.

For provenance purposes, this commit was AI assisted.

* fix(ai): clear startPromise on failure so OpenCode provider can retry

If doStart() fails (port conflict, timeout, binary crash), the cached
rejected promise prevented all future ensureServer() calls from
retrying. Now cleared on failure and on dispose().

Also updates stale "future" comment in types.ts.

For provenance purposes, this commit was AI assisted.

Author: backnotprop

apps/marketing/src/content/docs/commands/code-review.md

@@ -84,8 +84,9 @@ Plannotator supports multiple AI providers. Providers are auto-detected based on
 - **Claude** — Requires the `claude` CLI ([Claude Code](https://docs.anthropic.com/en/docs/claude-code))
 - **Codex** — Requires the `codex` CLI ([OpenAI Codex](https://github.com/openai/codex))
 - **Pi** — Requires the `pi` CLI ([Pi](https://github.com/mariozechner/pi-coding-agent))
+- **OpenCode** — Requires the `opencode` CLI ([OpenCode](https://opencode.ai))
 
-All providers can be available simultaneously. Plannotator does not manage API keys — you must be authenticated with each CLI independently (`claude` uses `~/.claude/` credentials, `codex` uses `OPENAI_API_KEY`, `pi` uses its own local configuration).
+All providers can be available simultaneously. Plannotator does not manage API keys — you must be authenticated with each CLI independently (`claude` uses `~/.claude/` credentials, `codex` uses `OPENAI_API_KEY`, `pi` and `opencode` use their own local configuration).
 
 ### Choosing a provider
 

apps/marketing/src/content/docs/guides/ai-features.md

@@ -39,6 +39,12 @@ Requires the `pi` CLI installed and configured. Plannotator spawns `pi --mode rp
 
 No API keys are managed by Plannotator — Pi uses its own local configuration.
 
+### OpenCode (via OpenCode SDK)
+
+Requires the `opencode` CLI installed and authenticated. Plannotator spawns `opencode serve` and communicates via HTTP + SSE. Models are discovered dynamically from your connected providers.
+
+OpenCode supports session forking, resuming, and runtime permission approvals — the richest capability set of all four providers.
+
 ## Configuration
 
 Provider and model selection is available in **Settings > AI**. These persist via cookies across sessions.
@@ -55,6 +61,8 @@ A session is created lazily on your first question. Until then, no resources are
 
 **Pi sessions** inject the review context as a system prompt prefix, similar to Codex. Pi uses its full default toolset (read, bash, edit, write). Pi sessions are always standalone — fork and resume are not available.
 
+**OpenCode sessions** pass the review context via the `system` field on the prompt API. OpenCode supports forking from a parent session and resuming previous sessions. Permission requests work the same as Claude — approval cards appear inline.
+
 **Diff context handling:** Large diffs are truncated at roughly 40k characters to stay within context limits. However, when you select specific lines and ask a question, the selected code is always sent alongside the question regardless of truncation.
 
 ## Permission requests
@@ -63,19 +71,21 @@ When using Claude, the AI may request permission to use tools like Read, Glob, G
 
 Codex sessions run in a sandboxed read-only mode, so permission requests do not apply.
 
+OpenCode supports the same permission approval flow as Claude — tool calls that need approval appear as inline cards. You can approve or deny each request.
+
 Pi does not expose a permission approval gate over RPC, so tool execution is handled entirely by Pi's own runtime.
 
 ## Reasoning effort
 
 Codex supports a reasoning effort setting with four levels: **Low**, **Medium**, **High**, and **Max**. This is available in the config bar at the bottom of the AI sidebar. Higher effort means slower but more thorough responses.
 
-This setting only applies to Codex — Claude and Pi do not expose a reasoning effort control.
+This setting only applies to Codex — Claude, Pi, and OpenCode do not expose a reasoning effort control.
 
 ## Available settings
 
 | Setting | Description | Provider |
 |---------|-------------|----------|
-| Provider | Claude, Codex, or Pi | All |
+| Provider | Claude, Codex, Pi, or OpenCode | All |
 | Model | Model selection per provider | All |
 | Reasoning effort | Low / Medium / High / Max | Codex only |
 | Default tools | Read, Glob, Grep, WebSearch | Claude only |

bun.lock

@@ -34,6 +34,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.81",
     "@openai/codex-sdk": "^0.116.0",
+    "@opencode-ai/sdk": "^1.3.0",
     "@pierre/diffs": "^1.1.0-beta.19",
     "diff": "^8.0.3",
     "dompurify": "^3.3.3",

package.json

@@ -326,11 +326,11 @@ describe("ProviderRegistry", () => {
   test("mixed provider types", () => {
     const reg = new ProviderRegistry();
     reg.register(mockProvider("claude-agent-sdk"), "claude-1");
-    reg.register(mockProvider("opencode"), "oc-1");
+    reg.register(mockProvider("opencode-sdk"), "oc-1");
 
     expect(reg.size).toBe(2);
     expect(reg.getByType("claude-agent-sdk").length).toBe(1);
-    expect(reg.getByType("opencode").length).toBe(1);
+    expect(reg.getByType("opencode-sdk").length).toBe(1);
   });
 
   test("disposeAll clears everything", () => {
@@ -403,7 +403,7 @@ describe("AI endpoints", () => {
   test("capabilities lists multiple providers", async () => {
     const { reg, endpoints } = setup();
     reg.register(mockProvider("claude-agent-sdk"), "claude-1");
-    reg.register(mockProvider("opencode"), "oc-1");
+    reg.register(mockProvider("opencode-sdk"), "oc-1");
 
     const res = await endpoints["/api/ai/capabilities"](
       new Request("http://localhost/api/ai/capabilities")
@@ -466,7 +466,7 @@ describe("AI endpoints", () => {
   test("session creation with specific provider ID", async () => {
     const { reg, endpoints } = setup();
     reg.register(mockProvider("claude-agent-sdk"), "claude-fast");
-    reg.register(mockProvider("opencode"), "oc-default");
+    reg.register(mockProvider("opencode-sdk"), "oc-default");
 
     const createRes = await endpoints["/api/ai/session"](
       new Request("http://localhost/api/ai/session", {
@@ -1054,3 +1054,173 @@ describe("mapPiEvent", () => {
     }]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// OpenCode event mapping
+// ---------------------------------------------------------------------------
+
+import { mapOpenCodeEvent } from "./providers/opencode-sdk.ts";
+
+describe("mapOpenCodeEvent", () => {
+  const SESSION_ID = "oc_session_1";
+
+  test("message.part.delta with text field maps to text_delta", () => {
+    const result = mapOpenCodeEvent("message.part.delta", {
+      sessionID: SESSION_ID,
+      messageID: "msg_1",
+      partID: "part_1",
+      field: "text",
+      delta: "Hello ",
+    }, SESSION_ID);
+    expect(result).toEqual([{ type: "text_delta", delta: "Hello " }]);
+  });
+
+  test("message.part.delta with non-text field returns empty", () => {
+    const result = mapOpenCodeEvent("message.part.delta", {
+      field: "reasoning",
+      delta: "thinking...",
+    }, SESSION_ID);
+    expect(result).toEqual([]);
+  });
+
+  test("message.part.updated with running tool maps to tool_use", () => {
+    const result = mapOpenCodeEvent("message.part.updated", {
+      part: {
+        id: "part_1",
+        type: "tool",
+        tool: "read",
+        callID: "call_1",
+        state: {
+          status: "running",
+          input: { path: "/foo.ts" },
+          time: { start: 1000 },
+        },
+      },
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "tool_use",
+      toolName: "read",
+      toolInput: { path: "/foo.ts" },
+      toolUseId: "call_1",
+    }]);
+  });
+
+  test("message.part.updated with completed tool maps to tool_result", () => {
+    const result = mapOpenCodeEvent("message.part.updated", {
+      part: {
+        id: "part_1",
+        type: "tool",
+        tool: "read",
+        callID: "call_1",
+        state: {
+          status: "completed",
+          output: "file contents here",
+          time: { start: 1000, end: 1100 },
+        },
+      },
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "tool_result",
+      toolUseId: "call_1",
+      result: "file contents here",
+    }]);
+  });
+
+  test("message.part.updated with error tool maps to tool_result with [Error] prefix", () => {
+    const result = mapOpenCodeEvent("message.part.updated", {
+      part: {
+        id: "part_1",
+        type: "tool",
+        tool: "read",
+        callID: "call_1",
+        state: {
+          status: "error",
+          error: "file not found",
+          time: { start: 1000, end: 1100 },
+        },
+      },
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "tool_result",
+      toolUseId: "call_1",
+      result: "[Error] file not found",
+    }]);
+  });
+
+  test("permission.updated maps to permission_request", () => {
+    const result = mapOpenCodeEvent("permission.updated", {
+      id: "perm_1",
+      type: "write_file",
+      title: "Write to /src/foo.ts",
+      callID: "call_2",
+      sessionID: SESSION_ID,
+      metadata: { path: "/src/foo.ts" },
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "permission_request",
+      requestId: "perm_1",
+      toolName: "write_file",
+      toolInput: { path: "/src/foo.ts" },
+      title: "Write to /src/foo.ts",
+      toolUseId: "call_2",
+    }]);
+  });
+
+  test("session.status idle maps to result", () => {
+    const result = mapOpenCodeEvent("session.status", {
+      sessionID: SESSION_ID,
+      status: { type: "idle" },
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "result",
+      sessionId: SESSION_ID,
+      success: true,
+    }]);
+  });
+
+  test("session.status busy returns empty", () => {
+    const result = mapOpenCodeEvent("session.status", {
+      sessionID: SESSION_ID,
+      status: { type: "busy" },
+    }, SESSION_ID);
+    expect(result).toEqual([]);
+  });
+
+  test("message.updated with error maps to error", () => {
+    const result = mapOpenCodeEvent("message.updated", {
+      info: {
+        id: "msg_1",
+        sessionID: SESSION_ID,
+        role: "assistant",
+        error: {
+          name: "ProviderAuthError",
+          data: { message: "Invalid API key", providerID: "anthropic" },
+        },
+      },
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "error",
+      error: "Invalid API key",
+      code: "opencode_message_error",
+    }]);
+  });
+
+  test("session.error maps to error", () => {
+    const result = mapOpenCodeEvent("session.error", {
+      sessionID: SESSION_ID,
+      error: { message: "Something went wrong" },
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "error",
+      error: "Something went wrong",
+      code: "opencode_session_error",
+    }]);
+  });
+
+  test("ignored events return empty", () => {
+    expect(mapOpenCodeEvent("session.created", { sessionID: SESSION_ID }, SESSION_ID)).toEqual([]);
+    expect(mapOpenCodeEvent("session.updated", { sessionID: SESSION_ID }, SESSION_ID)).toEqual([]);
+    expect(mapOpenCodeEvent("server.connected", {}, SESSION_ID)).toEqual([]);
+    expect(mapOpenCodeEvent("file.edited", { file: "foo.ts" }, SESSION_ID)).toEqual([]);
+  });
+});

packages/ai/ai.test.ts

@@ -74,6 +74,7 @@ export type {
   ClaudeAgentSDKConfig,
   CodexSDKConfig,
   PiSDKConfig,
+  OpenCodeConfig,
 } from "./types.ts";
 
 // Provider registry

packages/ai/index.ts

@@ -12,6 +12,8 @@
     "./endpoints": "./endpoints.ts",
     "./providers/claude-agent-sdk": "./providers/claude-agent-sdk.ts",
     "./providers/codex-sdk": "./providers/codex-sdk.ts",
-    "./providers/pi-sdk": "./providers/pi-sdk.ts"
-  }
+    "./providers/pi-sdk": "./providers/pi-sdk.ts",
+    "./providers/opencode-sdk": "./providers/opencode-sdk.ts"
+  },
+  "dependencies": {}
 }