@hueyexe/opencode-ensemble 0.1.0 → 0.1.2

package/README.md

@@ -79,26 +79,38 @@ Lead: "All validation and tests are complete. 5 endpoints validated,
 
 ## Install
 
-```bash
-bun add opencode-ensemble
+Add the plugin to your OpenCode config. This can be project-level or global.
+
+**Project-level** — `opencode.json` in your project root:
+
+```json
+{
+  "plugin": ["@hueyexe/opencode-ensemble"]
+}
 ```
 
-Add to your OpenCode config (`.opencode/config.json`):
+**Global** — `~/.config/opencode/opencode.json`:
 
 ```json
 {
-  "plugins": {
-    "ensemble": {
-      "module": "opencode-ensemble"
-    }
-  }
+  "plugin": ["@hueyexe/opencode-ensemble"]
 }
 ```
 
-For local development, create `.opencode/plugins/ensemble.ts`:
+That's it. OpenCode auto-installs npm plugins at startup (cached in `~/.cache/opencode/node_modules/`). No `npm install` or `bun add` needed.
+
+### Local development
+
+For working on the plugin itself, create `.opencode/plugins/ensemble.ts` in your project:
+
+```ts
+export { default } from "@hueyexe/opencode-ensemble"
+```
+
+Or point directly at the source checkout:
 
 ```ts
-export { default } from "opencode-ensemble"
+export { default } from "/path/to/opencode-ensemble/src/index.ts"
 ```
 
 ## Tools

package/dist/index.js

@@ -12335,10 +12335,12 @@ function tool(input) {
 }
 tool.schema = exports_external;
 // src/index.ts
-import path from "path";
+import path2 from "path";
+import { mkdirSync } from "fs";
 
 // src/db.ts
 import { Database } from "bun:sqlite";
+import path from "path";
 
 // src/schema.ts
 var MIGRATIONS = [
@@ -12417,8 +12419,12 @@ function applyMigrations(db) {
 
 // src/db.ts
 var instance;
-function createDb(path) {
-  const db = new Database(path);
+function getDbPath(env = process.env) {
+  const home = env.HOME ?? env.USERPROFILE ?? "~";
+  return path.join(home, ".config", "opencode", "ensemble.db");
+}
+function createDb(path2) {
+  const db = new Database(path2);
   db.exec("PRAGMA journal_mode=WAL");
   db.exec("PRAGMA foreign_keys=ON");
   applyMigrations(db);
@@ -12627,6 +12633,30 @@ async function notifyTeamEvent(client, type, data) {
     });
   } catch {}
 }
+async function notifyWorkingProgress(client, db, teamId) {
+  const members = db.query("SELECT name, status FROM team_member WHERE team_id = ? ORDER BY time_created ASC").all(teamId);
+  if (members.length === 0)
+    return;
+  const busy = members.filter((m) => m.status === "busy");
+  try {
+    if (busy.length === 0) {
+      await client.tui.showToast({
+        title: "Team",
+        message: "All teammates finished",
+        variant: "success",
+        duration: 4000
+      });
+    } else {
+      const names = busy.map((m) => m.name).join(", ");
+      await client.tui.showToast({
+        title: "Team",
+        message: `Working: ${names} (${busy.length}/${members.length})`,
+        variant: "info",
+        duration: 5000
+      });
+    }
+  } catch {}
+}
 
 // src/types.ts
 function findTeamBySession(db, registry2, sessionId) {
@@ -12664,7 +12694,7 @@ async function executeTeamCreate(deps, args, sessionId) {
   const id = generateId("team");
   const now = Date.now();
   deps.db.run("INSERT INTO team (id, name, lead_session_id, status, delegate, time_created, time_updated) VALUES (?, ?, ?, 'active', 0, ?, ?)", [id, args.name, sessionId, now, now]);
-  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates.`;
+  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates. Teammates will message you when done \u2014 do not poll team_status repeatedly.`;
 }
 
 // src/tools/team-spawn.ts
@@ -12703,8 +12733,9 @@ async function executeTeamSpawn(deps, args, sessionId) {
     "- team_claim: claim a pending task from the shared board",
     "",
     "When you finish your task:",
-    "1. Send ONE message to the lead with your findings using team_message.",
-    "2. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.",
+    "1. If you claimed a task, mark it complete using team_tasks_complete.",
+    "2. Send ONE message to the lead with your findings using team_message.",
+    "3. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.",
     "",
     "If you are blocked, send ONE message to the lead describing the specific blocker.",
     "",
@@ -12712,13 +12743,17 @@ async function executeTeamSpawn(deps, args, sessionId) {
     "",
     "Your task:",
     args.prompt
-  ].join(`
+  ];
+  if (args.claim_task) {
+    context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`);
+  }
+  const contextStr = context.join(`
 `);
   await deps.client.session.promptAsync({
     path: { id: childSessionId },
-    body: { parts: [{ type: "text", text: context }] }
+    body: { parts: [{ type: "text", text: contextStr }] }
   });
-  return `Teammate "${args.name}" spawned (session: ${childSessionId}, agent: ${args.agent}). Working on: ${args.prompt.slice(0, 100)}${args.prompt.length > 100 ? "..." : ""}`;
+  return `Teammate "${args.name}" spawned (session: ${childSessionId}, agent: ${args.agent}). Working on: ${args.prompt.slice(0, 100)}${args.prompt.length > 100 ? "..." : ""} Teammates will message you when done. Do not poll team_status to check.`;
 }
 
 // src/tools/team-message.ts
@@ -12814,7 +12849,7 @@ async function executeTeamCleanup(deps, args, sessionId) {
   if (teamInfo.role !== "lead")
     throw new Error("Only the team lead can clean up the team.");
   const members = deps.db.query("SELECT name, session_id, status FROM team_member WHERE team_id = ?").all(teamInfo.teamId);
-  const active = members.filter((m) => m.status !== "shutdown");
+  const active = members.filter((m) => m.status !== "shutdown" && m.status !== "shutdown_requested" && m.status !== "error");
   if (active.length > 0 && !args.force) {
     const names = active.map((m) => m.name).join(", ");
     throw new Error(`Cannot clean up team "${teamInfo.teamName}": ${active.length} member(s) still active: ${names}. Use team_shutdown on each member first, or call team_cleanup with force: true to abort them immediately.`);
@@ -12976,6 +13011,25 @@ async function executeTeamStatus(deps, sessionId) {
     lines.push("");
     lines.push(`Tasks: ${tasks.length} total (${parts.join(", ")})`);
   }
+  if (members.length > 0) {
+    const memberParts = members.map((m) => {
+      const label = m.status === "busy" ? "working" : m.status === "ready" ? "idle" : m.status;
+      return `${m.name} [${label}]`;
+    });
+    let toastMsg = memberParts.join(", ");
+    if (tasks.length > 0) {
+      const completed = tasks.filter((t) => t.status === "completed").length;
+      toastMsg += ` | Tasks: ${completed}/${tasks.length} done`;
+    }
+    try {
+      await deps.client.tui.showToast({
+        title: "Team",
+        message: toastMsg,
+        variant: "info",
+        duration: 4000
+      });
+    } catch {}
+  }
   return lines.join(`
 `);
 }
@@ -13060,7 +13114,8 @@ var DEFAULT_RATE_LIMIT_CAPACITY = 10;
 var DEFAULT_RATE_LIMIT_REFILL = 2;
 var DEFAULT_RATE_LIMIT_INTERVAL_MS = 1000;
 var plugin = async (input) => {
-  const dbPath = path.join(input.directory, ".opencode", "ensemble.db");
+  const dbPath = getDbPath();
+  mkdirSync(path2.dirname(dbPath), { recursive: true });
   const db = createDb(dbPath);
   const registry2 = new MemberRegistry;
   const tracker = new DescendantTracker;
@@ -13094,6 +13149,7 @@ var plugin = async (input) => {
           } else if (transition.to === "error") {
             notifyTeamEvent(client, "error", { memberName: transition.memberName });
           }
+          await notifyWorkingProgress(client, db, transition.teamId);
         }
       }
       if (event.type === "session.created") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",

package/src/db.ts

@@ -1,8 +1,19 @@
 import { Database } from "bun:sqlite"
+import path from "path"
 import { applyMigrations } from "./schema"
 
 let instance: Database | undefined
 
+/**
+ * Resolve the path for the ensemble SQLite database.
+ * Always uses the global ~/.config/opencode/ directory, never the project directory.
+ * Accepts an env override for testability.
+ */
+export function getDbPath(env: Record<string, string | undefined> = process.env): string {
+  const home = env.HOME ?? env.USERPROFILE ?? "~"
+  return path.join(home, ".config", "opencode", "ensemble.db")
+}
+
 /**
  * Create and initialize a SQLite database at the given path.
  * Applies all pending migrations and enables WAL mode.

package/src/index.ts

@@ -1,11 +1,12 @@
 import type { Plugin } from "@opencode-ai/plugin"
 import { tool } from "@opencode-ai/plugin"
 import path from "path"
-import { createDb } from "./db"
+import { mkdirSync } from "node:fs"
+import { createDb, getDbPath } from "./db"
 import { recoverStaleMembers } from "./recovery"
 import { MemberRegistry, DescendantTracker } from "./state"
 import { handleSessionStatusEvent, handleSessionCreatedEvent, checkToolIsolation } from "./hooks"
-import { notifyTeamEvent } from "./notify"
+import { notifyTeamEvent, notifyWorkingProgress } from "./notify"
 import { executeTeamCreate } from "./tools/team-create"
 import { executeTeamSpawn } from "./tools/team-spawn"
 import { executeTeamMessage } from "./tools/team-message"
@@ -32,8 +33,9 @@ const DEFAULT_RATE_LIMIT_INTERVAL_MS = 1000
  * peer-to-peer communication, shared task management, and coordinated execution.
  */
 const plugin: Plugin = async (input) => {
-  // Initialize SQLite database in the project's .opencode directory
-  const dbPath = path.join(input.directory, ".opencode", "ensemble.db")
+  // Initialize SQLite database in the global OpenCode config directory
+  const dbPath = getDbPath()
+  mkdirSync(path.dirname(dbPath), { recursive: true })
   const db = createDb(dbPath)
 
   // Initialize in-memory state
@@ -83,6 +85,9 @@ const plugin: Plugin = async (input) => {
           } else if (transition.to === "error") {
             notifyTeamEvent(client, "error", { memberName: transition.memberName })
           }
+
+          // Show working progress after every transition so the user sees who's still active
+          await notifyWorkingProgress(client, db, transition.teamId)
         }
       }
 

package/src/notify.ts

@@ -1,3 +1,4 @@
+import type { Database } from "bun:sqlite"
 import type { PluginClient } from "./types"
 
 type TeamEventType = "spawn" | "message" | "completed" | "error" | "shutdown"
@@ -52,3 +53,43 @@ export async function notifyTeamEvent(
     // TUI may not be available — silently ignore
   }
 }
+
+/**
+ * Fire a toast showing which teammates are still working.
+ * Called on every session.status transition so the user sees live progress.
+ * Does nothing if the team has no members.
+ */
+export async function notifyWorkingProgress(
+  client: PluginClient,
+  db: Database,
+  teamId: string,
+): Promise<void> {
+  const members = db.query(
+    "SELECT name, status FROM team_member WHERE team_id = ? ORDER BY time_created ASC"
+  ).all(teamId) as Array<{ name: string; status: string }>
+
+  if (members.length === 0) return
+
+  const busy = members.filter(m => m.status === "busy")
+
+  try {
+    if (busy.length === 0) {
+      await client.tui.showToast({
+        title: "Team",
+        message: "All teammates finished",
+        variant: "success",
+        duration: 4000,
+      })
+    } else {
+      const names = busy.map(m => m.name).join(", ")
+      await client.tui.showToast({
+        title: "Team",
+        message: `Working: ${names} (${busy.length}/${members.length})`,
+        variant: "info",
+        duration: 5000,
+      })
+    }
+  } catch {
+    // TUI may not be available — silently ignore
+  }
+}

package/src/tools/team-cleanup.ts

@@ -17,7 +17,7 @@ export async function executeTeamCleanup(
   const members = deps.db.query("SELECT name, session_id, status FROM team_member WHERE team_id = ?")
     .all(teamInfo.teamId) as Array<{ name: string; session_id: string; status: string }>
 
-  const active = members.filter(m => m.status !== "shutdown")
+  const active = members.filter(m => m.status !== "shutdown" && m.status !== "shutdown_requested" && m.status !== "error")
 
   if (active.length > 0 && !args.force) {
     const names = active.map(m => m.name).join(", ")

package/src/tools/team-create.ts

@@ -28,5 +28,5 @@ export async function executeTeamCreate(
     [id, args.name, sessionId, now, now]
   )
 
-  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates.`
+  return `Team "${args.name}" created (ID: ${id}). You are the lead. Use team_spawn to add teammates. Teammates will message you when done — do not poll team_status repeatedly.`
 }

package/src/tools/team-spawn.ts

@@ -54,8 +54,9 @@ export async function executeTeamSpawn(
     "- team_claim: claim a pending task from the shared board",
     "",
     "When you finish your task:",
-    "1. Send ONE message to the lead with your findings using team_message.",
-    "2. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.",
+    "1. If you claimed a task, mark it complete using team_tasks_complete.",
+    "2. Send ONE message to the lead with your findings using team_message.",
+    "3. STOP. Do not send follow-up confirmations, status updates, or 'standing by' messages.",
     "",
     "If you are blocked, send ONE message to the lead describing the specific blocker.",
     "",
@@ -63,15 +64,21 @@ export async function executeTeamSpawn(
     "",
     "Your task:",
     args.prompt,
-  ].join("\n")
+  ]
+
+  if (args.claim_task) {
+    context.push("", `You have been assigned task ${args.claim_task}. Mark it complete when done.`)
+  }
+
+  const contextStr = context.join("\n")
 
   // Fire-and-forget: send prompt to teammate session
   // OQ-1: assuming promptAsync queues when session is busy
   // OQ-10: assuming fresh session accepts promptAsync without session.init()
   await deps.client.session.promptAsync({
     path: { id: childSessionId },
-    body: { parts: [{ type: "text", text: context }] },
+    body: { parts: [{ type: "text", text: contextStr }] },
   })
 
-  return `Teammate "${args.name}" spawned (session: ${childSessionId}, agent: ${args.agent}). Working on: ${args.prompt.slice(0, 100)}${args.prompt.length > 100 ? "..." : ""}`
+  return `Teammate "${args.name}" spawned (session: ${childSessionId}, agent: ${args.agent}). Working on: ${args.prompt.slice(0, 100)}${args.prompt.length > 100 ? "..." : ""} Teammates will message you when done. Do not poll team_status to check.`
 }

package/src/tools/team-status.ts

@@ -45,5 +45,28 @@ export async function executeTeamStatus(
     lines.push(`Tasks: ${tasks.length} total (${parts.join(", ")})`)
   }
 
+  // Fire a toast so the user (not just the model) sees the status summary
+  if (members.length > 0) {
+    const memberParts = members.map(m => {
+      const label = m.status === "busy" ? "working" : m.status === "ready" ? "idle" : m.status
+      return `${m.name} [${label}]`
+    })
+    let toastMsg = memberParts.join(", ")
+    if (tasks.length > 0) {
+      const completed = tasks.filter(t => t.status === "completed").length
+      toastMsg += ` | Tasks: ${completed}/${tasks.length} done`
+    }
+    try {
+      await deps.client.tui.showToast({
+        title: "Team",
+        message: toastMsg,
+        variant: "info",
+        duration: 4000,
+      })
+    } catch {
+      // TUI may not be available — silently ignore
+    }
+  }
+
   return lines.join("\n")
 }