@hueyexe/opencode-ensemble 0.5.1 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "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/system-prompt.ts

@@ -47,6 +47,8 @@ export function buildLeadSystemPrompt(db: Database, teamId: string): string {
     "",
     "Teammates work asynchronously and message you when done.",
     "Do NOT poll team_status or team_tasks_list repeatedly — wait for messages.",
+    "Spawn teammates ONE at a time — do not send multiple team_spawn calls in a single response.",
+    "After each team_spawn, verify the output confirms the spawn succeeded before spawning the next.",
     "After spawning teammates, tell the user what you've set up and wait.",
     "When all teammates finish, summarize results and suggest next steps.",
   ].join("\n")

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,7 +1,6 @@
-import type { ToolDeps } from "../types"
+import type { ToolDeps, PermissionRule } from "../types"
 import { generateId, validateMemberName } from "../util"
 import { findTeamBySession } from "../types"
-import path from "path"
 
 /**
  * Execute the team_spawn tool. Creates a child session and starts a teammate.
@@ -36,7 +35,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 +53,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
@@ -134,17 +144,6 @@ export async function executeTeamSpawn(
     "Your plain text output is NOT visible to the team. You MUST use team_message to communicate.",
   )
 
-  // Load project AGENTS.md if it exists
-  try {
-    const agentsPath = path.join(deps.directory, "AGENTS.md")
-    const file = Bun.file(agentsPath)
-    if (await file.exists()) {
-      const content = await file.text()
-      const truncated = content.length > 2000 ? content.slice(0, 2000) + "\n...(truncated)" : content
-      context.push("", "Project guidelines (from AGENTS.md):", truncated)
-    }
-  } catch { /* file may not exist or be unreadable */ }
-
   context.push(
     "",
     "Your task:",
@@ -160,14 +159,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