@hueyexe/opencode-ensemble 0.17.0 → 0.20.0

package/README.md

@@ -6,24 +6,24 @@
 
 [![npm version](https://img.shields.io/npm/v/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
 [![npm downloads](https://img.shields.io/npm/dm/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
-[![tests](https://img.shields.io/badge/tests-666%20passing-brightgreen.svg)]()
+[![CI](https://github.com/hueyexe/opencode-ensemble/actions/workflows/ci.yml/badge.svg)](https://github.com/hueyexe/opencode-ensemble/actions/workflows/ci.yml)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)]()
-[![OpenCode SDK](https://img.shields.io/badge/deps-OpenCode%20SDK%20only-blue.svg)]()
+[![deps](https://img.shields.io/badge/deps-runtime%3A%20OpenCode%20SDKs-blue.svg)]()
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 Run parallel AI agents in OpenCode. Each agent gets its own session, context window, and task. They coordinate through messaging and a shared task board.
 
-Plugin built on the public OpenCode SDK. No internal dependencies.
+Built on the public OpenCode SDKs — no OpenCode internals. Runtime dependencies are the three OpenCode SDK packages (`@opencode-ai/sdk`, `@opencode-ai/plugin`, `@opencode/plugin`). The bundled TUI companion additionally uses SolidJS and OpenTUI, provided by the OpenCode host and declared as peer dependencies.
 
 ## Quick Start
 
-```json
-{
-  "plugin": ["@hueyexe/opencode-ensemble@0.16.0"]
-}
+Install the plugin and you're done:
+
+```sh
+opencode plugin add @hueyexe/opencode-ensemble@0.18.0
 ```
 
-Add to your `opencode.json`, restart OpenCode, and ask it to do something that benefits from parallel work. The agent handles the rest. See [Install](#install) for full setup including worktree permissions.
+Then restart OpenCode and ask it to do something that benefits from parallel work. The agent handles the rest. See [Install](#install) for worktree permissions and other options.
 
 ## What actually happens
 
@@ -40,10 +40,10 @@ The lead agent:
 2. Adds independent tasks first and records the generated task IDs.
 3. Adds dependent QA and review tasks with `depends_on` using real returned IDs.
 4. Spawns a small team with explicit roles:
-   - scout: explore agent, worktree disabled, model openai/gpt-5.3-codex-spark
-   - api-dev: build agent, own worktree, model anthropic/claude-opus-4-7, plan_approval: true
-   - qa: build agent, own worktree, model anthropic/claude-sonnet-4-6
-   - reviewer: explore agent, worktree disabled, model openai/gpt-5.3-codex-spark
+   - scout: explore agent, worktree disabled, model openai/gpt-5-mini (example)
+   - api-dev: build agent, own worktree, model anthropic/claude-opus-4-7 (example), plan_approval: true
+   - qa: build agent, own worktree, model anthropic/claude-opus-4-7 (example)
+   - reviewer: explore agent, worktree disabled, model openai/gpt-5-mini (example)
 ```
 
 The lead uses the task board to make sequencing visible. Record the returned task IDs before creating dependent tasks:
@@ -79,7 +79,7 @@ team_spawn({
   name: "scout",
   agent: "explore",
   worktree: false,
-  model: "openai/gpt-5.3-codex-spark",
+  model: "openai/gpt-5-mini",
   claim_task: "task_abc123",
   prompt: "Trace the checkout webhook flow. Report the files, data model, existing tests, and the smallest safe implementation plan. Do not edit files.",
 })
@@ -177,21 +177,31 @@ The plugin uses SQLite via the host's runtime adapter:
 
 ### 1. Add the plugin
 
-Add to your OpenCode config with a pinned version. Project-level or global.
+The simplest install is the CLI (npm registry or Git package specifiers both work):
+
+```sh
+opencode plugin add @hueyexe/opencode-ensemble@0.18.0
+```
+
+This installs globally and writes the config entry for you. To update later: `opencode plugin update @hueyexe/opencode-ensemble`.
+
+**Manual config** — add to your OpenCode config with a pinned version. Project-level or global.
 
 **Project-level** (`opencode.json` in your project root):
 
-```json
+```jsonc
 {
-  "plugin": ["@hueyexe/opencode-ensemble@0.16.0"]
+  // OpenCode v2:
+  "plugins": ["@hueyexe/opencode-ensemble@0.18.0"]
 }
 ```
 
-**Global** (`~/.config/opencode/opencode.json`):
+**Global** (`~/.config/opencode/opencode.json`): same entry.
 
-```json
+```jsonc
 {
-  "plugin": ["@hueyexe/opencode-ensemble@0.16.0"]
+  // OpenCode v1:
+  "plugin": ["@hueyexe/opencode-ensemble@0.18.0"]
 }
 ```
 
@@ -211,7 +221,19 @@ Then restart OpenCode.
 
 Teammates work in git worktrees outside your project directory. Without this permission, OpenCode will prompt you to approve every file operation in a teammate's worktree.
 
-Add to your OpenCode config (`~/.config/opencode/opencode.json`):
+Add to your OpenCode config (`~/.config/opencode/opencode.json`).
+
+OpenCode v2 (`permissions` array):
+
+```jsonc
+{
+  "permissions": [
+    { "action": "external_directory", "resource": "~/.local/share/opencode/worktree/**", "effect": "allow" }
+  ]
+}
+```
+
+OpenCode v1 (`permission` map):
 
 ```json
 {
@@ -227,15 +249,15 @@ This is required. Without it, you'll see "Permission required — Access externa
 
 ### Local development
 
-To test a local build, point your plugin config at the built output:
+Configure the worktree as a local plugin (v2 loads the source entry; v1 uses the `server()` export from the same file):
 
-```json
+```jsonc
 {
-  "plugin": ["/path/to/opencode-ensemble/dist/index.js"]
+  "plugins": [{ "package": "/path/to/opencode-ensemble" }]
 }
 ```
 
-Build with `bun run build`, then restart OpenCode to pick up changes.
+No build step needed for local testing — but run `bun run typecheck && bun test && bun run build` before committing. Restart OpenCode (or wait for hot-reload) to pick up changes.
 
 ## Tools
 
@@ -251,7 +273,7 @@ Build with `bun run build`, then restart OpenCode to pick up changes.
 | `team_merge` | Merge a shutdown teammate's branch into working directory (unstaged). Blocks if you have local changes to overlapping files. |
 | `team_cleanup` | Remove the current team when done. Safety-net merges forgotten branches. With `purge`, previews archived-team deletion and returns exact approval labels plus a confirmation token. |
 | `team_status` | See all members, their status, and a task summary. |
-| `team_view` | Switch the TUI to a teammate's session. |
+| `team_view` | Resolve a teammate's session; pass `navigate: true` to switch the TUI to it (opt-in — only when the user explicitly asks). |
 
 Archived-team purge is intentionally two-step. First call `team_cleanup` with `purge` to get a preview, exact approval and denial option labels, and `confirm_token`; no data is deleted. Stale archived worktree/workspace references and stale Ensemble-owned branches are counted in the preview and cleaned during confirmed purge. Arbitrary non-Ensemble branches still block purge for safety. The lead must then use the question tool with those exact options. Only after the user selects the exact approval option should it call `team_cleanup` again with the same `purge`, `confirm_purge: true`, and the preview token.
 
@@ -274,17 +296,15 @@ Archived-team purge is intentionally two-step. First call `team_cleanup` with `p
 
 ## What you see in the TUI
 
-The plugin works within OpenCode's existing TUI. For deeper visibility, open the [dashboard](#dashboard) at `http://localhost:4747`.
+The plugin works within OpenCode's existing UI on every client (terminal, desktop, web): tools, approvals, messages, and the [dashboard](#dashboard) at `http://localhost:4747` all live server-side.
 
 What you get:
 
-- **Toast notifications** when teammates spawn, finish, error, shut down, or get rate-limited
-- **Working progress toasts** showing who's still active after every status change (e.g. "Working: alice, bob (2/3)")
-- **Rich tool titles** in the sidebar (e.g. "Spawned alice (build)", "Message -> bob", "Task board (3 tasks)")
-- **Session switching** via `team_view` to see any teammate's full chat log
-- **Status checks** via `team_status` for a snapshot of the whole team
-
-Teammate messages arrive in the lead's session as `[Team message from alice]: ...` blocks. They look like user messages because that's how `promptAsync` delivery works. Content is clearly labeled with the sender's name.
+- **Team state in context** — the lead's system prompt carries member statuses and task counts, so it stays aware across turns including after compaction.
+- **Teammate messages** arriving in the lead's session as labeled blocks with the sender's name.
+- **Rich tool titles** in the sidebar (e.g. "Spawned alice (build)", "Message -> bob", "Task board (3 tasks)").
+- **Status checks** via `team_status` for a snapshot of the whole team.
+- **Terminal extras** (terminal only): a sidebar widget with live member status and task counts via the bundled `./tui` companion, loaded automatically with the plugin. `team_view` reports the teammate session by default; ask for it and `navigate: true` switches the TUI there (ctrl+p to return).
 
 ## Architecture
 
@@ -436,7 +456,9 @@ STALL_THRESHOLD_MS=0
 
 ## Known limitations
 
-- **Teammate messages may switch the lead's agent mode.** When a teammate sends a message back to the lead via `promptAsync`, OpenCode starts a new prompt loop that can switch the lead from plan/explore mode into build mode. This is a server-level behavior that the plugin cannot override. The lead's mode will restore when you send your next message.
+- **Teammate messages may switch the lead's agent mode (v1).** When a teammate sends a message back to the lead, OpenCode can start the next prompt loop in build mode even if the lead was in plan/explore mode. Tracked upstream; the lead's mode restores when you send your next message. On v2, pass an explicit `model` on `team_spawn` so teammates never inherit the server default.
+- **Session switching is opt-in (v2).** `team_view` reports the teammate's session ID by default; it switches the user's client only when asked for with `navigate: true` — agents never hijack the client unprompted. The live sidebar (terminal only) shows member status on every client's dashboard at `http://localhost:4747`.
+- **Per-session shell env is unavailable (v2).** The v2 shell hook carries no session ID, so `ENSEMBLE_*` variables are not injected into teammate shells. Team identity travels in prompts and tool calls instead.
 
 ## How this differs from Claude Code agent teams
 
@@ -455,7 +477,7 @@ Same coordination model (shared tasks, peer messaging, lead coordination) with s
 ```bash
 bun install
 bun run typecheck
-bun test             # 623 tests
+bun test             # 835 tests
 bun run build
 ```