hive-swarm 1.9.1 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hive-swarm",
3
- "version": "1.9.1",
3
+ "version": "2.1.0",
4
4
  "license": "MIT",
5
5
  "description": "Cross-harness Hive Swarm plugin: coordinate dependent tasks and wake agents with @mentions.",
6
6
  "skills": "./skills/",
package/README.md CHANGED
@@ -1,263 +1,24 @@
1
- <div align="center">
2
- <img src="./assets/hive-swarm-banner.svg" alt="Hive Swarm — multi-agent coordination for AI agents" width="100%" />
1
+ # Hive Swarm
3
2
 
4
- <p><strong>One goal. A team of agents. A shared board for every handoff.</strong></p>
3
+ Version **2.1.0**. Coordinate dependent agent tasks with a shared board, outcome threads, live activity, owned journals, and message-flow graphs.
5
4
 
6
- <p>
7
- <a href="https://github.com/snowmiku601-cpu/hive-swarm/actions/workflows/ci.yml"><img src="https://github.com/snowmiku601-cpu/hive-swarm/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
8
- <a href="https://www.npmjs.com/package/hive-swarm"><img src="https://img.shields.io/badge/npm-hive--swarm%401.9.1-f6bc55?style=flat-square" alt="npm hive-swarm 1.9.1" /></a>
9
- <a href="https://www.npmjs.com/package/dsh-hive-swarm"><img src="https://img.shields.io/badge/DSH%20(next)-dsh--hive--swarm%401.9.1-9a7138?style=flat-square" alt="npm dsh-hive-swarm 1.9.1 next" /></a>
10
- <img src="https://img.shields.io/badge/runtime-Node.js%2022.19%20%7C%2024.2%2B-75baef?style=flat-square" alt="Node.js 22.19 or 24.2 and newer" />
11
- <img src="https://img.shields.io/badge/core_runtime_dependencies-0-55cbb2?style=flat-square" alt="Zero core runtime dependencies" />
12
- <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-b3ce64?style=flat-square" alt="MIT license" /></a>
13
- </p>
5
+ The core and Codex runtime use Node.js ESM, built-in SQLite, and **zero third-party runtime dependencies**. Required Node range: `^22.19.0 || >=24.2.0`.
14
6
 
15
- <p>
16
- <a href="#quick-start">🚀 Quick Start</a> ·
17
- <a href="#see-it-in-action">🖼️ See It in Action</a> ·
18
- <a href="#how-the-hive-moves-work">🧭 How It Works</a> ·
19
- <a href="#key-features">💡 Features</a> ·
20
- <a href="#usage">💬 Usage</a> ·
21
- <a href="#development-and-tests">✅ Tests</a> ·
22
- <a href="./CHANGELOG.md">📋 Changelog</a>
23
- </p>
24
- </div>
7
+ Hive Swarm **2.1.0** pairs `hive-swarm@2.1.0` (core + Codex) with `dsh-hive-swarm@2.1.0` (experimental native DeepSeek Harness `0.2.2-rc.5` bundle). Both tarballs are verified against their source artifacts before publication.
25
8
 
26
- ---
27
-
28
- Hive Swarm is a lightweight **multi-agent coordination engine and UI** for AI coding assistants. Split a goal across focused workers, let builders and verifiers hand work directly to each other on a shared board, track outcomes and live steps, and trace every result back to its handoff.
29
-
30
- The coordination core (`engine.mjs`, `core.mjs`, `run-store.mjs`) is harness-agnostic:
31
-
32
- - **Codex Desktop & Codex CLI (`hive-swarm@1.9.1`, npm `latest`)** — full MCP server, per-member Codex `app-server` sessions, inline MCP App, and standalone four-tab board UI.
33
- - **DeepSeek Harness Desktop `0.2.2-rc.5` (`dsh-hive-swarm@1.9.1`, npm `next`, experimental)** — native DSH sessions, permission-scoped tools, bee-marked **Swarm** Start card, right-dock tab, and full React panel.
34
-
35
- The core runtime uses **Node.js ESM**, built-in `node:sqlite`, and **zero third-party runtime dependencies**. Pinned `devDependencies` are only used to build and test the DSH client bundle (React is supplied by DSH at runtime).
36
-
37
- ## Quick Start
38
-
39
- Requires **Node.js `^22.19.0 || >=24.2.0`** and either **Codex Desktop / Codex CLI** or **DeepSeek Harness Desktop `0.2.2-rc.5`**.
40
-
41
- | Host | Published package | Status | Worker & UI model |
42
- | --- | --- | --- | --- |
43
- | **Codex Desktop / CLI** | `hive-swarm@1.9.1` (`latest`) | Production adapter; lifecycle qualified on CLI `0.169.1` | Per-member Codex sessions, inline MCP App & standalone 4-tab board |
44
- | **DeepSeek Harness `0.2.2-rc.5`** | `dsh-hive-swarm@1.9.1` (`next`) | Experimental; hardened via live multi-worker DSH stress testing | Native DSH sessions, Start card, right tab & full React panel |
45
-
46
- ### 1. Codex Desktop / CLI (via npm — recommended)
47
-
48
- `npm install` has **no install hooks** and never modifies your Codex profile automatically. Use the explicit `hive-swarm` CLI commands:
9
+ ## Codex lifecycle
49
10
 
50
11
  ```sh
51
- # Read-only environment check (does not launch Codex or call models)
52
12
  npx hive-swarm@latest doctor --host codex
53
-
54
- # Install persistent verified plugin copy and register with Codex
55
13
  npx hive-swarm@latest install --host codex
56
- ```
57
-
58
- Lifecycle commands:
59
-
60
- ```sh
61
- # Stage an update safely while Codex may be running
62
14
  npx hive-swarm@latest update --host codex
63
-
64
- # Apply staged update after active turns finish and Codex is closed
15
+ # Finish active work and close Codex before applying a staged update:
65
16
  npx hive-swarm@latest update --host codex --after-close
66
-
67
- # Remove plugin registration (retains SQLite boards, journals, and verified releases)
68
17
  npx hive-swarm@latest uninstall --host codex
69
18
  ```
70
19
 
71
- > **Note on Codex CLI versions:** Local version switching and rollback are verified against Codex CLI `0.169.1`. On newer Codex CLI versions, `update --host codex --after-close` keeps the verified candidate staged by default unless you pass `--allow-unqualified-cli`. Installation copies verified files into `<CODEX_HOME>/hive-swarm/versions/<version>/marketplace` (never pointing Codex at a transient `npx` cache) and refuses to overwrite existing unmanaged installations without migration guidance.
72
-
73
- After installing or updating, open a **new Codex Desktop chat** so the fresh MCP session loads the installed version.
74
-
75
- ### 2. DeepSeek Harness Desktop `0.2.2-rc.5` (Experimental)
76
-
77
- DSH manages plugins through its own profile manager. Close DSH Desktop, then run:
78
-
79
- ```sh
80
- dsh plugin --profile desktop add dsh-hive-swarm@1.9.1
81
- ```
82
-
83
- - `npx hive-swarm@latest install --host dsh` prints this command and never edits a DSH profile directly.
84
- - Native DSH state lives under `<profileContext.dir>/.hive-swarm` (completely separate from Codex).
85
- - Read-only and workspace-write workers enforce permissions through DSH's native Agent presets. On Windows, DSH reports shell confinement as **partial**; see the [1.8.0 qualification report](docs/releases/1.8.0-qualification.md) for verified probes and platform limits.
86
-
87
- ### 3. Install from source (Codex)
88
-
89
- <details>
90
- <summary><strong>Windows (PowerShell)</strong></summary>
91
-
92
- ```powershell
93
- git clone https://github.com/snowmiku601-cpu/hive-swarm.git
94
- cd hive-swarm
95
- powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
96
- ```
97
-
98
- Options:
99
- - `-RunTests` — run the mocked test suite before installing
100
- - `-NodePath "C:\path\to\node.exe"` — pin a compatible Node 22.19 or 24.2+ binary (the wrapper also checks Codex Desktop's bundled Node runtime)
101
- - `-CodexPath "C:\path\to\codex.exe"` — select a specific Codex CLI binary
102
-
103
- </details>
104
-
105
- <details>
106
- <summary><strong>macOS / Linux</strong></summary>
107
-
108
- ```bash
109
- git clone https://github.com/snowmiku601-cpu/hive-swarm.git
110
- cd hive-swarm
111
- chmod +x ./install.sh
112
- ./install.sh
113
- ```
114
-
115
- Pass `--test` to run the test suite first (`./install.sh --test`).
116
-
117
- </details>
118
-
119
- ## See it in action
120
-
121
- See what is running, which outcome threads are blocked or done, and where each result came from. The captures below use representative local demo data exported as lossless 2× PNGs. Click **Light PNG / Dark PNG** to view originals at full resolution.
122
-
123
- <p align="center">
124
- <picture>
125
- <source media="(prefers-color-scheme: dark)" srcset="./assets/overview-dark.png" />
126
- <img src="./assets/overview-light.png" alt="Hive Swarm Overview with a concise goal, ranked alerts, worker progress, and post links" width="100%" />
127
- </picture>
128
- </p>
129
-
130
- <p align="center"><a href="./assets/overview-light.png">Light PNG</a> · <a href="./assets/overview-dark.png">Dark PNG</a></p>
131
-
132
- ### Four views of the same swarm
133
-
134
- <table>
135
- <tr>
136
- <td align="center" width="50%"><a href="./assets/overview-light.png"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/overview-dark.png" /><img src="./assets/overview-light.png" alt="Overview with goal progress and ranked alerts" width="100%" /></picture></a><br/><sub><strong>Overview</strong> · goal, outcome threads, progress, ranked alerts, and next actions<br/><a href="./assets/overview-light.png">Light PNG</a> · <a href="./assets/overview-dark.png">Dark PNG</a></sub></td>
137
- <td align="center" width="50%"><a href="./assets/board-light.png"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/board-dark.png" /><img src="./assets/board-light.png" alt="Board with channel filters, messages and stall diagnostics" width="100%" /></picture></a><br/><sub><strong>Board</strong> · searchable Markdown feed, channels, mentions, and `#seq` jumps<br/><a href="./assets/board-light.png">Light PNG</a> · <a href="./assets/board-dark.png">Dark PNG</a></sub></td>
138
- </tr>
139
- <tr>
140
- <td align="center" width="50%"><a href="./assets/members-light.png"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/members-dark.png" /><img src="./assets/members-light.png" alt="Members with a crowned coordinator, worker status and journal controls" width="100%" /></picture></a><br/><sub><strong>Members</strong> · live steps, Journals, model switching, recovery, and worktrees<br/><a href="./assets/members-light.png">Light PNG</a> · <a href="./assets/members-dark.png">Dark PNG</a></sub></td>
141
- <td align="center" width="50%"><a href="./assets/graph-light.png"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/graph-dark.png" /><img src="./assets/graph-light.png" alt="Graph replay with elapsed time and directed mention counts" width="100%" /></picture></a><br/><sub><strong>Graph</strong> · replay message flow, timing, and spot silent handoffs<br/><a href="./assets/graph-light.png">Light PNG</a> · <a href="./assets/graph-dark.png">Dark PNG</a></sub></td>
142
- </tr>
143
- </table>
144
-
145
- <details>
146
- <summary><strong>Look inside a worker journal</strong></summary>
147
-
148
- Follow saved turns and live activity without opening or interrupting the worker's chat.
149
-
150
- <p align="center">
151
- <picture>
152
- <source media="(prefers-color-scheme: dark)" srcset="./assets/journal-dark.png" />
153
- <img src="./assets/journal-light.png" alt="Journal modal with two saved worker turns, step labels and verified reports" width="100%" />
154
- </picture>
155
- </p>
156
- <p align="center"><a href="./assets/journal-light.png">Light PNG</a> · <a href="./assets/journal-dark.png">Dark PNG</a></p>
157
- </details>
158
-
159
- ## How the hive moves work
160
-
161
- <p align="center"><img src="./assets/hive-swarm-flow.svg" alt="Goal to coordinator to workers to verified board handoff flow" width="100%" /></p>
162
-
163
- - **Direct peer-to-peer handoffs:** workers can wake each other directly via `@member`, `@group`, `@#channel`, or `@all` — a `@builder` can hand straight to `@reviewer`, and `@reviewer` can request fixes from `@builder` without bouncing every turn through `@coordinator`.
164
- - **Wakeup doorbell discipline:** `@name` wakes a teammate (and writes plain names in prose when only referencing them), preventing accidental wasted turns.
165
- - **Explicit dependencies & zero-token waits:** workers with `waitFor` stay queued until every upstream member reports `[done]`, and coordinators block on `wait_for_board` without burning model tokens.
166
-
167
- ## Key features
168
-
169
- | What you need | What Hive Swarm provides |
170
- | --- | --- |
171
- | Coordinate parallel & dependent work | Up to 12 active workers, `waitFor` dependencies, sharding (`n`/`tasks`), groups, channels, and per-member sessions |
172
- | Direct peer collaboration | `@member`, `@group`, `@#channel`, and `@all` routing with normalized target matching |
173
- | Track outcomes, not just logs | Progress bars, milestones, coordinator summaries, and optional outcome `threads` (`Blocked` → `Active` → `Queued` → `Done`) |
174
- | Understand a stalled or uncertain run | Zero-token `[stall]` root-cause diagnostics, ranked alerts with `#seq` links, and explicit `Retry fresh turn` / `Dismiss` recovery for unconfirmed runs |
175
- | Flexible model routing | Per-member `model` and `effort`, runtime model switching with warm forks, and optional `fallbackModel` quota failover |
176
- | Safe isolation & cleanup | Read-only default workers, optional detached Git `worktree` per writable worker, and uncommitted-safe worktree removal |
177
-
178
- <details>
179
- <summary><strong>Runtime and implementation details</strong></summary>
180
-
181
- - **Cross-harness core (`engine.mjs`, `core.mjs`, `run-store.mjs`):** SQLite WAL scheduler, `@mention` / `@group` / `@all` / `@#channel` routing, dependency tracking (`waitFor`), outcome `threads` (`set_team_plan`), opt-in quota failover (`fallbackModel` / `fallbackEffort`), durable run admission/settlement evidence, explicit recovery (`resolve_recovery`), shared-checkout write locking, and bounded turn budgets.
182
- - **Codex adapter (`codex.mjs`, `server.mjs`):** runs each member in its own Codex `app-server` chat with thread persistence, activity-resetting idle turn timeouts (`HIVE_SWARM_TURN_TIMEOUT_MS`), warm forks for provider/model changes, automatic archival, and live SSE activity.
183
- - **Native DSH adapter (`packages/dsh-hive-swarm/`):** Cordis plugin for DSH `0.2.2-rc.5` with host-minted Gateway peers, per-session preset sandbox verification, worker-scoped tool visibility, Start launcher card, right-dock tab, full React panel, safe Markdown rendering, `#seq` jump links, progress bars, outcome threads, Graph playback, and owned Journals.
184
- - **Root-cause stall diagnostics:** one `[stall]` system post per stalled episode identifies unaddressed results by `#seq`, unanswered mentions, quota/failure/recovery stops, dependency roots, and circular waits without starting a diagnostic model turn.
185
- - **Windows portability:** handles `.cmd` Node shims directly without `cmd.exe`, strips inherited MSIX/session markers via `childEnvironment()`, sets `features.prefer_mxc=false` on Windows, keeps portable `.mcp.json` `cwd: "."`, and preserves legacy `CodexTeamBoard` / port `17943` compatibility.
186
-
187
- </details>
188
-
189
- ## Usage
190
-
191
- ### In Codex Desktop / CLI
192
-
193
- 1. Start a team from a local project chat with `/swarm` or `$hive-swarm:swarm`:
194
-
195
- ```text
196
- $hive-swarm:swarm Review this repository, fix edge-case bugs, and run verification tests.
197
- ```
198
-
199
- 2. Specify a model when needed (`Use <model> ...`), or let the launcher pick from `list_models` (or inherit the runtime default).
200
- 3. In a **Goal**, use `coordinator: false` so your main Goal chat stays the sole coordinator polling with zero-token `wait_for_board`. In a single-turn chat, set `coordinator: true` when you want `@coordinator` to synthesize worker rounds in the background.
201
- 4. Click **🐝 Open Swarm UI** to follow live steps, inspect Journals, switch models, resolve unconfirmed runs, clean worktrees, or steer workers directly with `@mentions`.
202
-
203
- ### In DeepSeek Harness Desktop
204
-
205
- 1. Run `/hive-swarm` in an authorized workspace chat to start or inspect a native team.
206
- 2. Open the bee-marked **Swarm** card in Start (or click **Open Swarm** on a verified tool result) to inspect **Overview**, **Board**, **Members**, **Graph**, and owned **Journals** — opening the UI never starts a model turn.
207
-
208
- <details>
209
- <summary><strong>Advanced workflow example (peer-to-peer handoffs, worktrees, outcome threads &amp; quota failover)</strong></summary>
210
-
211
- ```text
212
- $hive-swarm:swarm Split this feature into two isolated worktree builders (@api and @ui) and one read-only @reviewer who waits for both.
213
- - Have @api and @ui hand off directly to @reviewer (and @reviewer request fixes directly from @api/@ui), notifying @coordinator only when verified or blocked.
214
- - Group Overview into two outcome threads: "API contract" and "UI integration".
215
- - Use a fallback model if the primary model hits quota limits.
216
- ```
217
-
218
- </details>
219
-
220
- ## Repository layout
221
-
222
- - `.agents/plugins/marketplace.json`, `.codex-plugin/plugin.json`, `.mcp.json` — Codex plugin metadata & portable MCP config
223
- - `engine.mjs`, `core.mjs`, `run-store.mjs`, `worktrees.mjs` — harness-agnostic scheduler, host application layer, durable run store, and Git worktree manager
224
- - `codex.mjs`, `server.mjs`, `cli.mjs`, `installer.mjs` — Codex `app-server` adapter, MCP/HTTP/SSE server, and npm lifecycle CLI
225
- - `board.html`, `board.css`, `board.js`, `hive-bees.js`, `hive-graph.js` — standalone & inline MCP App UI
226
- - `skills/swarm/` — Codex `/swarm` skill and agent metadata
227
- - `packages/dsh-hive-swarm/` — native DeepSeek Harness plugin (`host.mjs`, `native.mjs`, `runner.mjs`, `routes.mjs`, `client/`, `skills/hive-swarm/`)
228
- - `scripts/` — verified core/DSH packagers (`pack-core.mjs`, `pack-dsh.mjs`) and DSH client builder (`build-dsh-client.mjs`)
229
- - `docs/releases/` — release qualification evidence and artifact manifests
230
- - `install.ps1`, `install.sh` — cross-platform source installers
231
- - `assets/` — banner, coordination diagram, icons, and lossless light/dark UI captures
232
- - `*.test.mjs`, `packages/dsh-hive-swarm/*.test.mjs` — full `node:test` test suite
233
-
234
- ## Development and tests
235
-
236
- ```sh
237
- # Run the complete core, Codex, CLI, packaging, and native DSH test suite
238
- npm test
239
-
240
- # Rebuild the native DSH React client bundle
241
- npm run build:dsh
242
-
243
- # Pack and cryptographically verify both npm tarballs locally
244
- npm run pack:core
245
- npm run pack:dsh
246
- ```
247
-
248
- The test suite uses mocked runners and makes **no paid API calls**. Opening views, reading Journals, running `doctor`, and computing `[stall]` diagnostics never start a model turn.
249
-
250
- ## Troubleshooting notes
251
-
252
- - **Codex CLI update qualification gate:** `hive-swarm update --host codex --after-close` defaults to verifying Codex CLI `0.169.1`. Pass `--allow-unqualified-cli` to apply a staged update on a newer Codex CLI build.
253
- - **Long-running worker turns:** Codex worker turns use an activity-resetting idle timeout (default 20 minutes of inactivity, 60-minute hard cap, configurable via `HIVE_SWARM_TURN_TIMEOUT_MS`).
254
- - **Windows sandbox process errors:** the installer and runtime strip inherited MSIX/session markers and set `features.prefer_mxc=false` on Windows so workers can run shell commands cleanly.
255
- - **Vitest `spawn EPERM` in Windows worker sandboxes:** pass `--configLoader native --pool threads` to avoid child-process pool restrictions.
256
- - **Opening a live worker chat:** Codex Desktop may hold one writer lock per active thread. Use **View journal** in the Hive UI to inspect progress without interrupting the turn.
257
- - **State locations & ports:**
258
- - **Codex:** SQLite WAL under `%LOCALAPPDATA%\CodexTeamBoard` (Windows) or `~/CodexTeamBoard` (macOS/Linux); override with `HIVE_SWARM_DATA` / `TEAM_BOARD_DATA`. Default loopback port: `17943` (`HIVE_SWARM_PORT` / `TEAM_BOARD_PORT`).
259
- - **DSH:** isolated under `<profileContext.dir>/.hive-swarm`.
20
+ `npm install` only installs package files; it does not register a plugin. The explicit CLI creates an immutable persistent marketplace copy and delegates host changes to supported Codex CLI commands. Local switching/rollback is qualified for CLI `0.169.1`; other versions retain the stage unless `--allow-unqualified-cli` is explicitly passed. Active owned turns block replacement. Uninstall preserves databases, journals, and verified release copies. Doctor does not execute Codex by default or call models.
260
21
 
261
- ## License
22
+ DSH uses the separate `dsh-hive-swarm` bundle and its own profile manager. Install the matching experimental `0.2.2-rc.5` bundle with `dsh plugin --profile desktop add dsh-hive-swarm@2.1.0` (or `@next`). Release `2.1.0` brings an Antigravity-style Overview (task summary accordion, `goalLine`, `taskLabel`, outcome `threads` progress bars, and `Screenshots` timeline), Dual-Mode **Graph** (**`Hive`** honeycomb + **`Mentions`** capsule ring + zero-dependency **Export GIF**), hidden native DSH subagents (`executionMode: 'subagent'`), and attached Codex `0.171+` child threads (`executionMode: 'attached'`). Its Windows shell retains the Host's partial confinement limits. `--host dsh` prints guidance without editing a DSH profile.
262
23
 
263
- Licensed under the [MIT License](./LICENSE). Copyright © 2026 snowmiku601-cpu.
24
+ [Full documentation and high-resolution screenshots](https://github.com/snowmiku601-cpu/hive-swarm#see-it-in-action) · [Source and issue tracker](https://github.com/snowmiku601-cpu/hive-swarm) · MIT license