@hueyexe/opencode-ensemble 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Agent teams for OpenCode — parallel agents with peer-to-peer communication, shared tasks, and coordinated execution",
   "module": "src/index.ts",
   "main": "dist/index.js",
@@ -38,7 +38,7 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.2.27",
-    "@opencode-ai/sdk": "^1.2.27"
+    "@opencode-ai/plugin": "^1.3.0",
+    "@opencode-ai/sdk": "^1.3.0"
   }
 }

package/src/client.ts

@@ -0,0 +1,54 @@
+import type { PluginClient } from "./types"
+
+/** Extract error message from a HeyAPI error response. */
+function extractError(err: unknown): string {
+  if (err && typeof err === "object" && "message" in err) return String((err as { message: string }).message)
+  return String(err)
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyFn = (...args: any[]) => Promise<any>
+
+/** Wrap a single async SDK method to throw on { error } responses. */
+function throwing(fn: AnyFn): AnyFn {
+  return async (...args: unknown[]) => {
+    const result = await fn(...args)
+    if (result && typeof result === "object" && "error" in result && result.error !== undefined) {
+      throw new Error(extractError(result.error))
+    }
+    return result
+  }
+}
+
+/** Shape of the raw v2 SDK client — just the methods we wrap. */
+interface RawClient {
+  session: { create: AnyFn; promptAsync: AnyFn; abort: AnyFn; status: AnyFn }
+  tui: { showToast: AnyFn; selectSession: AnyFn }
+  worktree: { create: AnyFn; remove: AnyFn; list: AnyFn; reset: AnyFn }
+}
+
+/**
+ * Wraps a raw v2 SDK client so that methods throw on error responses
+ * instead of returning { error }. This makes existing try/catch blocks work.
+ */
+export function wrapThrowingClient(raw: unknown): PluginClient {
+  const r = raw as RawClient
+  return {
+    session: {
+      create: throwing(r.session.create.bind(r.session)),
+      promptAsync: throwing(r.session.promptAsync.bind(r.session)),
+      abort: throwing(r.session.abort.bind(r.session)),
+      status: throwing(r.session.status.bind(r.session)),
+    },
+    tui: {
+      showToast: throwing(r.tui.showToast.bind(r.tui)),
+      selectSession: throwing(r.tui.selectSession.bind(r.tui)),
+    },
+    worktree: {
+      create: throwing(r.worktree.create.bind(r.worktree)),
+      remove: throwing(r.worktree.remove.bind(r.worktree)),
+      list: throwing(r.worktree.list.bind(r.worktree)),
+      reset: throwing(r.worktree.reset.bind(r.worktree)),
+    },
+  } as PluginClient
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 import type { Plugin } from "@opencode-ai/plugin"
 import { tool } from "@opencode-ai/plugin"
+import { OpencodeClient as OpencodeClientV2 } from "@opencode-ai/sdk/v2"
 import path from "path"
 import { mkdirSync } from "node:fs"
 import { createDb, getDbPath } from "./db"
+import { wrapThrowingClient } from "./client"
 import { recoverStaleMembers, recoverUndeliveredMessages, recoverOrphanedWorktrees } from "./recovery"
 import { MemberRegistry, DescendantTracker } from "./state"
 import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation } from "./hooks"
@@ -47,8 +49,12 @@ const plugin: Plugin = async (input) => {
   const registry = new MemberRegistry()
   const tracker = new DescendantTracker()
 
-  // Build shared tool dependencies
-  const client = input.client as unknown as PluginClient
+  // Reuse the v1 client's working HTTP transport with v2's method signatures.
+  // The v1 client (input.client) has the correct connection (Unix socket/auth),
+  // while v2 gives us flat params + permission on create + agent/tools on promptAsync.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const rawClient = new OpencodeClientV2({ client: (input.client as any)._client })
+  const client = wrapThrowingClient(rawClient)
   const deps: ToolDeps = { db, registry, tracker, client, directory: input.directory }
 
   // Run recovery on init — mark stale busy members as error + abort orphaned sessions
@@ -125,7 +131,7 @@ const plugin: Plugin = async (input) => {
             const entry = registry.getBySession(sessionID)
             if (entry) {
               try {
-                await client.session.abort({ path: { id: sessionID } })
+                await client.session.abort({ sessionID })
               } catch { /* best effort */ }
             }
           }

package/src/recovery.ts

@@ -29,7 +29,7 @@ export async function recoverStaleMembers(db: Database, client?: PluginClient):
   if (client) {
     for (const member of stale) {
       try {
-        await client.session.abort({ path: { id: member.session_id } })
+        await client.session.abort({ sessionID: member.session_id })
       } catch { /* best effort */ }
     }
   }
@@ -111,8 +111,8 @@ export async function recoverUndeliveredMessages(
 
       try {
         await client.session.promptAsync({
-          path: { id: recipientSessionId },
-          body: { parts: [{ type: "text", text: `[Recovered team message from ${msg.from_name}]: ${msg.content}` }] },
+          sessionID: recipientSessionId,
+          parts: [{ type: "text", text: `[Recovered team message from ${msg.from_name}]: ${msg.content}` }],
         })
         markDelivered(db, msg.id)
         redelivered++

package/src/schema.ts

@@ -76,6 +76,8 @@ export const MIGRATIONS: string[] = [
   // Migration 4: Add plan_approval column to team_member for plan-before-build workflow
   `ALTER TABLE team_member ADD COLUMN plan_approval TEXT NOT NULL DEFAULT 'none'
      CHECK(plan_approval IN ('none', 'pending', 'approved', 'rejected'));`,
+  // Migration 5: Track lead's agent mode so message delivery preserves it
+  `ALTER TABLE team ADD COLUMN lead_agent TEXT;`,
 ]
 
 /**

package/src/tools/team-broadcast.ts

@@ -44,8 +44,8 @@ export async function executeTeamBroadcast(
   for (const recipient of recipients) {
     try {
       await deps.client.session.promptAsync({
-        path: { id: recipient.sessionId },
-        body: { parts: [{ type: "text", text: `[Team broadcast from ${senderName}]: ${args.text}` }] },
+        sessionID: recipient.sessionId,
+        parts: [{ type: "text", text: `[Team broadcast from ${senderName}]: ${args.text}` }],
       })
       delivered++
     } catch {

package/src/tools/team-cleanup.ts

@@ -29,7 +29,7 @@ export async function executeTeamCleanup(
   if (args.force) {
     for (const member of active) {
       try {
-        await deps.client.session.abort({ path: { id: member.session_id } })
+        await deps.client.session.abort({ sessionID: member.session_id })
       } catch { /* best effort */ }
     }
   }

package/src/tools/team-message.ts

@@ -68,8 +68,8 @@ export async function executeTeamMessage(
   }
 
   await deps.client.session.promptAsync({
-    path: { id: recipientSessionId },
-    body: { parts: [{ type: "text", text: deliveryText }] },
+    sessionID: recipientSessionId,
+    parts: [{ type: "text", text: deliveryText }],
   })
 
   markDelivered(deps.db, msgId)

package/src/tools/team-shutdown.ts

@@ -52,13 +52,11 @@ export async function executeTeamShutdown(
   // Busy + not force → graceful: send shutdown message, set shutdown_requested
   try {
     await deps.client.session.promptAsync({
-      path: { id: member.session_id },
-      body: {
-        parts: [{
-          type: "text",
-          text: `[Shutdown requested]: The lead has requested you shut down. Finish your current task, send your final findings to the lead via team_message, then stop.`,
-        }],
-      },
+      sessionID: member.session_id,
+      parts: [{
+        type: "text",
+        text: `[Shutdown requested]: The lead has requested you shut down. Finish your current task, send your final findings to the lead via team_message, then stop.`,
+      }],
     })
   } catch {
     // promptAsync failed — best effort
@@ -83,7 +81,7 @@ async function abortAndShutdown(
   sessionId: string,
 ): Promise<void> {
   try {
-    await deps.client.session.abort({ path: { id: sessionId } })
+    await deps.client.session.abort({ sessionID: sessionId })
   } catch {
     // Abort failed — session may already be gone
   }

package/src/tools/team-spawn.ts

@@ -1,4 +1,4 @@
-import type { ToolDeps } from "../types"
+import type { ToolDeps, PermissionRule } from "../types"
 import { generateId, validateMemberName } from "../util"
 import { findTeamBySession } from "../types"
 import path from "path"
@@ -36,7 +36,7 @@ export async function executeTeamSpawn(
   if (useWorktree) {
     const worktreeName = `ensemble-${teamInfo.teamName}-${args.name}`
     try {
-      const result = await deps.client.worktree.create({ name: worktreeName })
+      const result = await deps.client.worktree.create({ worktreeCreateInput: { name: worktreeName } })
       if (result.data) {
         worktreeDir = result.data.directory
         worktreeBranch = result.data.branch
@@ -54,17 +54,28 @@ export async function executeTeamSpawn(
     }
   }
 
-  // Create child session — use worktree directory if available
-  const createOpts: Record<string, unknown> = {
-    body: { parentID: sessionId, title: `${args.name} (@${args.agent} teammate)` },
-  }
-  if (worktreeDir) {
-    createOpts.directory = worktreeDir
-  }
+  // Permission rules on session.create are the hard gate (server-enforced).
+  // For read-only agents, deny write tools and explicitly allow team tools
+  // so the agent's built-in restrictive permissions don't block them.
+  const isReadOnly = args.agent === "plan" || args.agent === "explore"
+  const TEAM_TOOLS = ["team_message", "team_broadcast", "team_tasks_list", "team_tasks_add", "team_tasks_complete", "team_claim"] as const
+  const permission: PermissionRule[] | undefined = isReadOnly
+    ? [
+        { permission: "edit", pattern: "*", action: "deny" },
+        { permission: "bash", pattern: "*", action: "deny" },
+        ...TEAM_TOOLS.map(t => ({ permission: t, pattern: "*", action: "allow" as const })),
+      ]
+    : undefined
 
+  // Create child session — use worktree directory if available
   let childSessionId: string | undefined
   try {
-    const createResult = await deps.client.session.create(createOpts as Parameters<typeof deps.client.session.create>[0])
+    const createResult = await deps.client.session.create({
+      parentID: sessionId,
+      title: `${args.name} (@${args.agent} teammate)`,
+      ...(permission ? { permission } : {}),
+      ...(worktreeDir ? { directory: worktreeDir } : {}),
+    })
     childSessionId = createResult.data?.id
   } catch (err) {
     // Rollback worktree if session creation failed
@@ -160,14 +171,15 @@ export async function executeTeamSpawn(
   // Fire-and-forget: send prompt to teammate session
   try {
     await deps.client.session.promptAsync({
-      path: { id: childSessionId },
-      body: { parts: [{ type: "text", text: contextStr }] },
+      sessionID: childSessionId,
+      parts: [{ type: "text", text: contextStr }],
+      agent: args.agent,
     })
   } catch (err) {
     // Rollback: clean up DB, registry, session, and worktree
     deps.db.run("DELETE FROM team_member WHERE team_id = ? AND name = ?", [teamInfo.teamId, args.name])
     deps.registry.unregister(childSessionId)
-    try { await deps.client.session.abort({ path: { id: childSessionId } }) } catch { /* best effort */ }
+    try { await deps.client.session.abort({ sessionID: childSessionId }) } catch { /* best effort */ }
     if (worktreeDir) {
       try { await deps.client.worktree.remove({ worktreeRemoveInput: { directory: worktreeDir } }) } catch { /* best effort */ }
     }

package/src/types.ts

@@ -15,19 +15,36 @@ export interface ToolDeps {
   directory: string
 }
 
+/** A single permission rule for session-level enforcement. */
+export interface PermissionRule {
+  permission: string
+  pattern: string
+  action: "allow" | "deny" | "ask"
+}
+
 /**
- * Minimal interface for the OpenCode client methods we actually use.
- * This is a subset of OpencodeClient, typed for our needs.
+ * Minimal interface for the OpenCode v2 SDK client methods we actually use.
+ * Uses flat params matching the v2 SDK (imported from @opencode-ai/sdk/v2).
  * Makes mocking trivial in tests.
  */
 export interface PluginClient {
   session: {
-    create(options: { body?: { parentID?: string; title?: string } }): Promise<{ data?: { id: string } }>
+    create(options: {
+      parentID?: string
+      title?: string
+      permission?: PermissionRule[]
+      workspaceID?: string
+      directory?: string
+    }): Promise<{ data?: { id: string } }>
     promptAsync(options: {
-      path: { id: string }
-      body: { parts: Array<{ type: "text"; text: string }>; model?: { providerID: string; modelID: string } }
+      sessionID: string
+      parts: Array<{ type: "text"; text: string }>
+      model?: { providerID: string; modelID: string }
+      agent?: string
+      tools?: Record<string, boolean>
+      system?: string
     }): Promise<unknown>
-    abort(options: { path: { id: string } }): Promise<unknown>
+    abort(options: { sessionID: string }): Promise<unknown>
     status(): Promise<{ data?: Record<string, { type: string }> }>
   }
   tui: {
@@ -40,7 +57,7 @@ export interface PluginClient {
     selectSession(options: { sessionID?: string }): Promise<unknown>
   }
   worktree: {
-    create(options: { name?: string; startCommand?: string }): Promise<{ data?: { name: string; branch: string; directory: string } }>
+    create(options: { worktreeCreateInput?: { name?: string; startCommand?: string } }): Promise<{ data?: { name: string; branch: string; directory: string } }>
     remove(options: { worktreeRemoveInput?: { directory: string } }): Promise<unknown>
     list(): Promise<{ data?: Array<{ name: string; branch: string; directory: string }> }>
     reset(options: { worktreeResetInput?: { directory: string } }): Promise<unknown>

package/src/watchdog.ts

@@ -55,7 +55,7 @@ export class Watchdog {
 
       // Abort session (best effort)
       try {
-        await this.client.session.abort({ path: { id: member.session_id } })
+        await this.client.session.abort({ sessionID: member.session_id })
       } catch { /* best effort */ }
 
       // Notify