@hueyexe/opencode-ensemble 0.18.0 → 0.21.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
 
-```jsonc
-{
-  "plugins": ["@hueyexe/opencode-ensemble@0.18.0"]
-}
+Install the plugin and you're done:
+
+```sh
+opencode plugin add @hueyexe/opencode-ensemble@latest
 ```
 
-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
 
@@ -148,21 +148,26 @@ A real-time mission control dashboard runs at `http://localhost:4747` while Open
 - **Agent cards** — status, current task, activity sparklines, timing. Click to open detail drawer
 - **Agent drawer** — full prompt, model, execution status, chat-style message history with markdown rendering
 - **Task board** — progress bar, collapsible status groups, dependency arrows
+- **Dependency graph tab** — task cards with agent ownership, prerequisite arrows,
+  dependency inspection, live updates, and missing/cyclic dependency warnings
 - **Activity feed** — chat-style message bubbles with avatars, expandable with full markdown
 - **Timeline** — horizontal event strip showing spawns, messages, completions, shutdowns
 - **Keyboard shortcuts** — `j/k` navigate agents, `Enter` opens drawer, `Esc` closes, `?` shows help
 - **Live clock** — current time + team session duration
 - **Project outline** — collapsible per-project grouping when teams span multiple working directories
 
+The **Dependency graph** tab lays out every task as a card, with arrows from each prerequisite to its dependent, live agent ownership/status, a detail panel for prerequisites and dependents, and warnings for missing or cyclic dependency IDs. Add dependencies with the `depends_on` field on `team_tasks_add`.
+
 Configure the port in `.opencode/ensemble.json`:
 
 ```json
 {
-  "dashboardPort": 4747
+  "dashboardPort": 4747,
+  "dashboardHost": "127.0.0.1"
 }
 ```
 
-Set to `0` to disable. The dashboard starts automatically when OpenCode loads the plugin.
+Set `dashboardPort` to `0` to disable. The dashboard starts automatically when OpenCode loads the plugin. `dashboardHost` defaults to loopback; changing it can expose dashboard data to other machines on your network.
 
 ## Install
 
@@ -177,14 +182,22 @@ 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. On OpenCode v2 the key is `plugins` (v1 used `plugin` — both work on their respective versions).
+The simplest install is the CLI (npm registry or Git package specifiers both work):
+
+```sh
+opencode plugin add @hueyexe/opencode-ensemble@latest
+```
+
+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 `@latest`, or pin an exact version for reproducibility. Project-level or global.
 
 **Project-level** (`opencode.json` in your project root):
 
 ```jsonc
 {
   // OpenCode v2:
-  "plugins": ["@hueyexe/opencode-ensemble@0.18.0"]
+  "plugins": ["@hueyexe/opencode-ensemble@latest"]
 }
 ```
 
@@ -193,15 +206,13 @@ Add to your OpenCode config with a pinned version. Project-level or global. On O
 ```jsonc
 {
   // OpenCode v1:
-  "plugin": ["@hueyexe/opencode-ensemble@0.18.0"]
+  "plugin": ["@hueyexe/opencode-ensemble@latest"]
 }
 ```
 
-OpenCode auto-installs npm plugins at startup. To update, bump the version number in your config and restart OpenCode.
-
-**Why pin versions?** OpenCode has a [known bug](https://github.com/anomalyco/opencode/issues/6774) where unpinned plugins (e.g., `"@hueyexe/opencode-ensemble"`) get cached on first install and never auto-update, even after restarting. Pinning to a specific version avoids this — when you change the version string, OpenCode sees a new package spec and installs it fresh.
+OpenCode auto-installs npm plugins at startup. To update, change the version spec in your config (or keep `@latest`) and restart OpenCode.
 
-If you're stuck on an old version, clear the cache manually:
+**If updates do not appear:** OpenCode has a [known bug](https://github.com/anomalyco/opencode/issues/6774) where unpinned plugins (e.g., `"@hueyexe/opencode-ensemble"`) get cached on first install and never auto-update, even after restarting. If you hit it, pin an exact version tag (for example, `@0.21.0`) and bump it when you upgrade, or clear the cache manually:
 
 ```bash
 rm -rf ~/.cache/opencode/packages/@hueyexe
@@ -241,7 +252,7 @@ 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 package directory (v2 loads the source entry; v1 uses the `server()` export from the same file):
+Configure the worktree as a local plugin (v2 loads the source entry; v1 uses the `server()` export from the same file):
 
 ```jsonc
 {
@@ -320,7 +331,7 @@ What you get:
 
 ## Model Selection
 
-Control which AI models your agents use. By default, agents use whatever model OpenCode is configured with. You can override this per-agent, per-agent-type, or with automatic rotation.
+Control which AI models your agents use. By default, teammates inherit the lead conversation's current model, read at spawn time (including its variant on v2). You can override this per-agent, per-agent-type, or with automatic rotation.
 
 **All agents use the same model:**
 ```json
@@ -362,7 +373,8 @@ When `promptForModels` is true, the lead uses the question tool to ask which mod
 2. `modelsByAgent` mapping for this agent type
 3. `modelAssignment` strategy (`rotate` or `random` from `modelPool`)
 4. `defaultModel`
-5. OpenCode's default model
+5. The lead conversation's current model at spawn time (including its variant on v2)
+6. OpenCode's default model
 
 The lead can always override by passing `model` directly on `team_spawn`, regardless of config.
 
@@ -385,11 +397,15 @@ Configure via JSON files, environment variables, or both. Project config overrid
   "timeoutMs": 1800000,
   "rateLimitCapacity": 10,
   "dashboardPort": 4747,
+  "dashboardHost": "127.0.0.1",
   "defaultModel": "anthropic/claude-sonnet-4-6",
   "modelPool": ["anthropic/claude-opus-4-7", "anthropic/claude-sonnet-4-6", "openai/gpt-5.4"],
   "modelsByAgent": {},
   "modelAssignment": "default",
-  "promptForModels": false
+  "promptForModels": false,
+  "systemPromptTeamState": "full",
+  "taskDepthLimit": 0,
+  "taskDepthLimitOverflowAction": "lead_resolve"
 }
 ```
 
@@ -406,11 +422,15 @@ All fields are optional. Missing fields use defaults.
 | `timeoutMs` | `1800000` (30 min) | Hard timeout for busy teammates. `0` disables. |
 | `rateLimitCapacity` | `10` | Token bucket capacity for team tool calls. `0` disables. |
 | `dashboardPort` | `4747` | Dashboard server port. `0` disables. |
-| `defaultModel` | `""` | Default model for all agents (e.g. `"anthropic/claude-sonnet-4-6"`). Empty = OpenCode's default. |
+| `dashboardHost` | `127.0.0.1` | Dashboard network interface to bind. Keep the loopback default unless you intend to expose the dashboard on your network. |
+| `defaultModel` | `""` | Default model for all agents (e.g. `"anthropic/claude-sonnet-4-6"`). Empty = inherit the lead conversation's current model, then OpenCode's default. |
 | `modelPool` | `[]` | List of models for rotation/random assignment. |
 | `modelsByAgent` | `{}` | Map agent type to model (e.g. `{"build": "anthropic/claude-opus-4-7"}`). |
 | `modelAssignment` | `"default"` | How to assign models: `"default"`, `"rotate"`, or `"random"`. |
 | `promptForModels` | `false` | Lead asks user about model preferences before spawning. |
+| `systemPromptTeamState` | `"full"` | Live team state in the system prompt: `"full"` (statuses, tasks, message payloads), `"state-only"` (no message payloads; use `team_results`), or `"off"` (stable role/workflow guidance only). Lower settings avoid provider prefix-cache invalidation on every state change. |
+| `taskDepthLimit` | `0` (unlimited) | Maximum active task dependency depth, counting unresolved roots as depth 1. Completed/cancelled prerequisites are treated as resolved and do not accumulate into a lifetime chain. `team_tasks_add` rejects a batch that would exceed it, before writing anything. The issue #42 `depth_limit` alias is accepted. |
+| `taskDepthLimitOverflowAction` | `"lead_resolve"` | `"lead_resolve"` tells the lead to split the work; `"user_resolve"` tells the lead to ask the user first. Both reject the over-limit batch. The issue #42 `depth_limit_overflow_action` alias is accepted. |
 
 ### Environment variables
 
@@ -448,7 +468,8 @@ STALL_THRESHOLD_MS=0
 
 ## Known limitations
 
-- **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.
+- **Lead agent/model preservation is best-effort (v1).** On v1, Ensemble reads the lead's current agent and model and passes them on teammate wake prompts, so a Plan lead normally stays in Plan. If OpenCode cannot report the selection, it may fall back to Build/default; pass an explicit `model` on `team_spawn` when this matters. V2 wakes are synthetic and do not switch the lead's agent/model.
+- **Model variants are v2-only.** A `provider/model#variant` reference is forwarded to v2's `session.switchModel`; v1 hosts do not have a variant field and ignore the suffix.
 - **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.
 
@@ -469,7 +490,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
 ```