Skip to main content
Glama
README.md
# pt-swarm: Multi-Agent Parallel Collaboration System

This package is a complete port of the **Antigravity Swarm** architecture, packaged and adapted for the **Polytoken** harness.

> **Unaffiliated project.** This is an independent, unofficial port. It is not affiliated with, endorsed by, sponsored by, or supported by Polytoken, Google Antigravity, or their maintainers. Product names are used only to describe interoperability and provenance.

> **Third-party assets.** Files adapted from Antigravity — `sidecar_ui/`, `skills/`, `plugin.json`, and `assets/logo.svg` — are included for interoperability and may be subject to separate upstream terms. The MIT license in this repository covers the code authored for this port, not those upstream assets. See [NOTICE](./NOTICE) for the file-by-file breakdown.

It enables multiple autonomous AI agents to work in parallel on separated tasks, synchronized via an append-only shared message board with @mentions, channels, zero-token sleep parking, and stall monitoring.

---

## Package Contents

```
pt-swarm/
├── README.md                      # Architecture guide & integration instructions
├── AGENTS.md                      # AI agent guidance, invariants, and TDD commands
├── docs/                          # Provenance, specs, and review history
│   ├── PORTING_MANIFEST.md        # Detailed provenance (rebuilt vs adapted breakdown)
│   ├── SPEC_NATIVE_SUBAGENTS.md   # Native-subagent design spec
│   ├── REVIEW_FINDINGS.md         # Code review findings ledger
│   ├── REVIEW_REMEDIATION.md      # Findings disposition ledger
│   └── POLYTOKEN_SIGKILL_BUG_REPORT.md  # polytoken 0.9.8 macOS plugin-runtime crash report
├── .gitignore
├── LICENSE                        # MIT
├── NOTICE                         # Third-party provenance and terms
├── MANIFEST.in                    # Source distribution contents
├── package.json                   # npm manifest (dashboard binary)
├── pyproject.toml                 # Python package & CLI entrypoints
├── plugin.json                    # Antigravity upstream plugin descriptor (legacy/attribution only — the live Polytoken manifest is plugin/polytoken.plugin.json)
├── assets/
│   └── logo.svg
├── pt_swarm/               # The single installed package
│   ├── __init__.py
│   ├── board_manager.py           # File-locked board, @mention parser, wait loop
│   ├── swarm_tools.py             # Tool dispatch and validation
│   ├── tool_defs.py               # TOOLS built from tool_schemas/ + argument gate
│   ├── worker_runner.py           # Cross-process worker supervisor
│   ├── workspace_manager.py       # Git worktree / clone isolation
│   ├── stall_monitor.py           # Deadlock and unaddressed-post detection
│   ├── cli.py                     # Terminal board & roster viewer
│   ├── model_selection.py         # Model request resolution
│   ├── model_hook.py              # Session model hook
│   ├── plugin_bridge.py           # CLI bridge used by the Polytoken plugin tools
│   └── tool_schemas/              # JSON Schemas for function calling
├── plugin/                        # Polytoken plugin package (tools, hooks, resources)
│   ├── polytoken.plugin.json      # Plugin manifest (capabilities, tools, config schema)
│   ├── src/index.ts               # Tool + hook handlers (Extism JS PDK)
│   ├── vendor/plugin-framework/   # Vendored framework shim (unpublished npm package)
│   └── resources/                 # Copies of subagents/ and skills/ shipped as plugin resources
├── skills/                        # Skill runbooks (source of record)
│   ├── native_swarm/SKILL.md
│   ├── swarm_monitor/SKILL.md
│   └── swarm_narrator/SKILL.md
├── subagents/                     # Polytoken subagent manifests
├── .polytoken/                    # Project-local Polytoken config (auto-discovered)
│   ├── subagents/*.md
│   └── skills/*/SKILL.md
├── schemas/                       # On-disk format specs (documentation)
│   ├── board_jsonl.md
│   ├── members_json.md
│   └── view_json.md
├── sidecar_ui/                    # Real-time Web dashboard (Node.js + HTML)
│   ├── main.mjs, channels.mjs, app.js, hive.js, index.html
│   └── sidecar_sdk/index.mjs      # Standalone shim for the host sidecar SDK
├── tests/                         # Python unittest & Node.js test suites
    ├── test_adapter.py
    ├── test_board.py
    ├── test_cli_and_schemas.py
    ├── test_model_selection.py
    ├── test_plugin_bridge.py
    ├── test_plugin_definitions.py
    ├── test_polytoken_only.py
    ├── test_tool_defs.py
    ├── test_worker_review.py
    ├── test_workspace_preservation.py
    ├── test_plugin_shim.mjs
    ├── test_sidecar_frontend_review.mjs
    └── test_sidecar_ui.mjs
```

Everything the runtime needs is inside `pt_swarm/`, so an installed copy is self-contained. `plugin/resources/` holds byte-identical copies of the top-level `subagents/` and `skills/` trees (the sources of record) so the plugin package ships them; a test fails if the copies drift. `.polytoken/` holds the project-local copies Polytoken auto-discovers from this repo root; they carry the same content and are covered by the same parity tests.

---

## Porting Provenance (Rebuilt vs. Adapted)

See [**PORTING_MANIFEST.md**](./docs/PORTING_MANIFEST.md) for full technical rationale and architecture mapping.

* **Adapted Verbatim from Antigravity**:
  * Skill runbooks: `skills/native_swarm/SKILL.md`, `skills/swarm_monitor/SKILL.md`, `skills/swarm_narrator/SKILL.md`
  * Live UI dashboard: `sidecar_ui/*`
  * Metadata and icons: `plugin.json`, `assets/logo.svg`
* **Rebuilt / Reverse-Engineered for Polytoken**:
  * **Tool Schemas** (`pt_swarm/tool_schemas/*.json`): formalized from internal RPC definitions.
  * **Board & Tool Engine** (`pt_swarm/board_manager.py`, `swarm_tools.py`, `tool_defs.py`): replaces Antigravity's compiled Go backend.
  * **Role Prompts** (`subagents/*.md`): standalone role prompts, shipped as plugin resources.
  * **Runtime Glue** (`pt_swarm/worker_runner.py`, `workspace_manager.py`, `stall_monitor.py`, `plugin_bridge.py`).

---

## How It Works in Polytoken

### 1. The Coordinator Loop
1. The user talks to the **Coordinator**.
2. For a multi-faceted task, the Coordinator splits the work into independent chunks.
3. The Coordinator calls `swarm(action="add", name="<worker>", brief="...")`.
4. The brief is posted to the board as `@<worker> <brief>`. With no process spawner configured, `swarm` returns a `swarm-worker` delegation and the coordinator starts it as a native subagent; configured external spawners continue to launch workers themselves.

### 2. The Worker Loop
1. Workers run in separate sessions with their own tools. Native workers are started by the coordinator; external workers can be spawned by `worker_runner.py` when configured.
2. When finished or handing off, the worker posts to the board with `@<next_peer>`.
3. The worker calls `swarm_wait(since=LAST_SEEN)` to sleep with zero token consumption until pinged.

### 3. The Monitor (`swarm-monitor`)
On a timer, it detects unaddressed posts and unanswered `@mentions`, then tags the responsible agent (e.g. `@coordinator [stall] #14 unaddressed`).

### 4. Real-time UI (`sidecar_ui`)
The dashboard visualizes the live board feed, the member roster and states, the @mention graph, and narrator overview cards from `view.json`.

### Board identity (important)
All agents in a workspace share one swarm entry point, so every tool call accepts a `caller` roster name. There is no persistent server process — each plugin tool call carries its `caller` explicitly and the bridge defaults to `POLYTOKEN_AGENT_NAME` or `coordinator`. The worker prompt and the spawn prompt both instruct workers to pass `caller="<name>"`; without it, a worker's posts and read cursors are attributed to the coordinator.

---

## Model selection

A member's `model` is a **request**, not a literal selector. `swarm(action="add", model=...)`
records it on the roster, and `WorkerProcessManager` resolves it once per spawn into a value
`polytoken exec --model` accepts:

| Request | Runs on |
|---|---|
| unset, `default`, `auto` | the member's role tier: `@mg:polytoken:default_model_full` for workers and verifiers, `@mg:polytoken:default_model_mini` for the monitor and narrator |
| `full`, `mini`, `nano` | that reserved Polytoken tier group |
| `session` | the model this Polytoken session is running, as recorded by the hook below; the role tier when nothing is recorded |
| anything else | passed through unchanged: a model name, a `name(level)` reasoning variant, or a `@mg:<group>` group reference |

The roster keeps both halves: `model`/`desired_model` is the request and `applied_model`
is the selector the process launches with. `polytoken exec` rejects the `default` sentinel
("model 'default' is not configured"), so a member with no resolved model starts without
`--model` at all. `swarm(action="models")` lists the models this install can run and
repeats these rules under `selection`.

The plugin records the model the session is running: its `session_start` and
`pre_user_prompt` hooks (exports `polytoken_hook_session_start` /
`polytoken_hook_pre_user_prompt`) run `python3 -m pt_swarm.model_hook`, which writes
`POLYTOKEN_MODEL_NAME` into `<swarm_dir>/session_model.json`.

> **Note (polytoken 0.9.8):** whether the plugin hook's shell environment carries
> `POLYTOKEN_MODEL_NAME` could not be verified live — the plugin runtime crashes the
> polytoken daemon on macOS (see `docs/POLYTOKEN_SIGKILL_BUG_REPORT.md`). If the variable is
> absent, the hook is a harmless no-op and `session` falls back to the role tier.

The plugin wires these hooks for you. To record the session model without the plugin —
for example when driving the engine from your own harness — add the same two hooks
manually: `hooks.json` is environment-local (gitignored), so add the block to
`.polytoken/hooks.json` in the project or to `~/.config/polytoken/hooks.json` for a
global install:

```json
[
  {
    "name": "swarm-session-model",
    "event": "session_start",
    "handler": { "bash": "python3 -m pt_swarm.model_hook; echo '{\"outcome\":\"allow\"}'" }
  },
  {
    "name": "swarm-session-model-switch",
    "event": "pre_user_prompt",
    "handler": { "bash": "python3 -m pt_swarm.model_hook; echo '{\"outcome\":\"accept\"}'" }
  }
]
```

Without the hook everything still works — `session` just falls back to the role tier.

---

## Quickstart Integration Example (Python)

The board engine is plain Python, so a harness that is not Polytoken can drive the same
tools directly:

```python
from pt_swarm.board_manager import BoardManager
from pt_swarm.swarm_tools import SwarmToolHandlers

# 1. Point the board at a swarm directory (one per workspace).
bm = BoardManager("./.swarm/default")

# 2. Build the handler stack; the caller name is the roster identity.
tools = SwarmToolHandlers(bm, caller_agent_name="coordinator")

# 3. Dispatch tool calls from your agent loop.
tools.handle_swarm(action="add", name="parser", brief="Parse the config format")
tools.handle_post_message(text="@parser start with the lexer")
tools.handle_read_board(since=0)
```

---

## Installation & Setup (Polytoken plugin path)

The Polytoken integration ships as a single installable plugin package, `plugin/`, which
provides the four swarm tools as plugin tools (`plugin__pt-swarm__swarm`, `…__post_message`,
`…__read_board`, `…__swarm_wait`), records the session model via plugin hooks, and ships the
subagent manifests and skills as plugin resources. No server block and no manual
copying are needed.

### Plugin architecture

```
model ──▶ plugin tool (WASM, plugin/src/index.ts)
             │  serializes input JSON, base64-encodes it on the bridge command line
             ▼
         host shell capability (polytoken_plugin_shell_exec)
             │  python3 -m pt_swarm.plugin_bridge <tool> --args-base64 <b64>
             ▼
         pt_swarm.plugin_bridge ──▶ SwarmToolHandlers ──▶ BoardManager
             │  one JSON line on stdout
             ▼
         plugin tool parses and returns ok/err envelope to the model
```

All board logic (file locking, cursors, wake modes, worker supervision) stays in the
tested Python engine; the WASM layer is a thin bridge. The bridge also accepts raw JSON
arguments on stdin (used by tests and manual invocation). Because plugin `shell` runs in
the daemon's environment, no environment-clearing or `pass_env` plumbing is needed.

### 1. Build toolchain (one-time)

```bash
polytoken plugin-dev doctor        # lists missing tools
npm install -g esbuild@0.25.11     # JS PDK bundler
brew install binaryen              # wasm-opt / wasm-merge
# extism-js: pinned download from https://github.com/extism/js-pdk/releases (v1.7.0)
polytoken plugin-dev doctor        # must exit 0 (version warnings are fine)
```

### 2. Build, pack, verify, install

```bash
cd plugin
polytoken plugin-dev build --project .
polytoken plugin-dev pack --project . --out dist/pt-swarm.pt-plugin
polytoken plugin-dev verify dist/pt-swarm.pt-plugin
polytoken plugin-dev install dist/pt-swarm.pt-plugin
```

The package is unsigned (built locally), so `plugin_trust.allow_unsigned_local = true` in
`~/.config/polytoken/config.toml` is required, and the plugin's capabilities (`shell`,
`emit_message`) are approved interactively on first load. `polytoken plugin list` shows
the installed package and its resource counts; `/reload` picks up a rebuilt package.

### 3. Per-project setup

The plugin resolves the swarm directory as:
`plugins.pt-swarm.swarm_dir` in the plugin config (optional) → `POLYTOKEN_SWARM_DIR` →
`<project>/.swarm/default`. A session creates the directory lazily on first use, so no
config file is required. Set `plugins.pt-swarm.python` if the bridge must run under a
specific interpreter (default `python3`).

`pt_swarm` must be importable by that interpreter — `pip install --user .` (see
*Global Installation* below) or `pip install -e .` from a checkout.

### 4. Subagents & skills

The plugin ships `subagents/` and `skills/` as plugin resources (referenced via
`plugin+pt-swarm://<path>`). Whether Polytoken auto-loads plugin resources as session
subagents/skills is not yet verified live (blocked by the polytoken 0.9.8 plugin-runtime
crash, see `docs/POLYTOKEN_SIGKILL_BUG_REPORT.md`), so this repository also keeps the
project-local `.polytoken/subagents/` and `.polytoken/skills/` copies, which Polytoken
auto-discovers from the repo root and which carry `plugin__pt-swarm__*` tool references.
A parity test keeps both copies byte-identical to the top-level sources.

### 5. Uninstall

```bash
polytoken plugin-dev remove pt-swarm        # or delete the .pt-plugin from the project's plugins dir, then /reload
pip uninstall pt-swarm                       # if the Python engine was installed for the bridge
```

---

## Global Installation (Available in Any Project)

The plugin path above is per-project. To make the swarm available in every Polytoken
project, install the Python engine and the plugin package globally.

1. **In this repository**: the plugin resolves `.polytoken/subagents/` and
   `.polytoken/skills/` from the repo root, so a checkout works with no extra config —
   install the engine and build the plugin (see *Installation & Setup (Polytoken plugin path)*).
2. **In another project**: install the package (`pip install /path/to/pt-swarm`), copy this
   repository's `.polytoken/` into that project's root, and install the packed plugin package.

### 1. Install the Python engine & CLI entrypoints
   ```bash
   pip install --user .
   # Homebrew and most distro Pythons are PEP 668 "externally managed" and
   # reject a bare `pip install .`:
   #   pip install --user --break-system-packages .
   # `--user` keeps the install in ~/.local and leaves the interpreter's own
   # site-packages untouched.
   ```
   This registers `pt-swarm-cli` (`pt_swarm.cli:main`) and `pt-swarm-plugin-bridge` (`pt_swarm.plugin_bridge:main`) on your `PATH`, and installs the tool schemas inside the package. The plugin bridge is what the plugin's tool layer shells out to.

### 2. Install the plugin package globally

   Build and pack it once (see *Installation & Setup (Polytoken plugin path)*), then install
   the resulting `.pt-plugin` into the user plugin directory so every project picks it up:

   ```bash
   polytoken plugin-dev install dist/pt-swarm.pt-plugin
   polytoken plugin list          # shows pt-swarm and its resource counts
   ```

   The plugin resolves the swarm directory per project: `plugins.pt-swarm.swarm_dir` in the
   plugin config (optional) → `POLYTOKEN_SWARM_DIR` → `<project>/.swarm/default`. Because the
   last fallback is relative to the project, `./.swarm/default` isolates each workspace's
   board to that project and a session creates the directory lazily on first use.

   To enable the swarm in selected projects only, install the package into that project's
   plugins directory instead of the user-wide one.

### 3. Environment variables

   Plugin `shell` runs in the daemon's environment, so no environment-forwarding plumbing is
   needed: variables exported in your shell are visible to the bridge. Workers inherit that
   environment too, so `polytoken` on `PATH` is enough for `polytoken exec` spawns to load the
   same config the session uses.

   A spawn that fails anyway reports the exit code, the log tail, and a hint naming the
   environment variables your config references — an empty model list with `spawned: false`
   and `mode: unconfigured` usually means `polytoken` was not found on `PATH`.

### 4. Subagents & skills

   The plugin ships `subagents/` and `skills/` as plugin resources, so no copying is needed.
   This repository additionally keeps project-local `.polytoken/subagents/` and
   `.polytoken/skills/` copies, which Polytoken auto-discovers from the repo root; a parity
   test keeps them byte-identical to the top-level sources.

   The manifests' `polytoken.tools` lists reference the plugin tool names
   (`plugin__pt-swarm__*`), which resolve when the plugin is installed.

### 5. Install the Web UI globally (optional):
   ```bash
   npm pack
   npm install -g --prefix ~/.local ./pt-swarm-1.0.0.tgz
   rm -f pt-swarm-1.0.0.tgz
   # run it with:
   POLYTOKEN_SWARM_DIR=./.swarm/default pt-swarm-ui
   ```
   The dashboard binds `127.0.0.1:5388` by default; override with `HOST` and `PORT`.

   Two packaging details matter: installing from the folder (`npm install -g .`) creates a *symlink* back to this checkout, so the global command breaks if the checkout moves — install the packed tarball for a self-contained copy. And when npm's default prefix is not writable (common with Homebrew or distro Node), pass `--prefix ~/.local`; its `bin/` directory must be on `PATH`.

### 6. Worker process spawning:
   `WorkerProcessManager` launches workers with `polytoken exec "<prompt>"`, which needs `polytoken` on `PATH`. To override the default command (which includes `exec --model {model}`), set `POLYTOKEN_WORKER_CMD` in the environment the session runs in, for example:
   ```yaml
   env:
     POLYTOKEN_WORKER_CMD: "polytoken exec {prompt}"
   ```
   Supported placeholders: `{prompt}`, `{name}`, `{model}`, `{workspace}`, `{swarm_dir}`.
   `{model}` is the member's resolved selector (see *Model selection*). When a template puts
   `{model}` after a `--model`/`-m` flag and nothing resolved, both tokens are dropped, so
   `polytoken exec --model {model} {prompt}` degrades to `polytoken exec <prompt>` instead of
   failing on an invalid model name.
   A worker that exits during startup is reported as a failed spawn (`spawned: false` with its exit code and log tail) rather than a running agent.

### 7. Uninstall:
   ```bash
   # remove the installed plugin package, then /reload
   rm -f ~/.config/polytoken/plugins/pt-swarm.pt-plugin   # or the project's plugins dir
   pip uninstall pt-swarm
   npm uninstall -g --prefix ~/.local pt-swarm
   ```

---

## Running the CLI, UI & Tests

```bash
# Watch the board in a terminal
python3 -m pt_swarm.cli --swarm-dir ./.swarm/default --watch

# Launch the live web dashboard (http://127.0.0.1:5388/)
POLYTOKEN_SWARM_DIR=./.swarm/default node sidecar_ui/main.mjs

# Run all tests (Python unittest discovery and Node.js test runner).
# The Python packaging regression builds an sdist; install its build requirement first:
python3 -m pip install 'setuptools>=77.0'
python3 -m unittest discover -s tests -v
node --test tests/test_sidecar_ui.mjs tests/test_sidecar_frontend_review.mjs tests/test_plugin_shim.mjs
```

Notes:
- Use `python3`; many systems do not provide a `python` alias.
- The dashboard accepts `POLYTOKEN_SWARM_DIR` (direct board directory), `SWARM_CONVERSATION_ID`, `HOST`, and `PORT`. Without `POLYTOKEN_SWARM_DIR` it falls back to `./.swarm/default`.
- `.polytoken/hooks.json` and `.polytoken/context.py`, if present in a checkout, are environment-local session hooks; they are git-ignored and are not part of the distributable package.

TDQS

B3/5.0

Scored across 4 tools

Disambiguation3/5

post_message, read_board, and swarm_wait have reasonably distinct purposes, but the catch-all 'swarm' tool with seven bundled actions (status, models, add, model, kill, title, channel) overlaps with read_board's 'retrieve member states' capability. An agent must guess whether to use swarm(status) or read_board for member info, and whether add/kill belong to swarm or a separate membership tool.

Naming Consistency3/5

All names are snake_case, but conventions are mixed: post_message and read_board are verb_noun, swarm_wait is noun_verb, and 'swarm' is a bare noun with no verb at all. The grouping is still readable, but there is no predictable pattern for predicting a new tool's name.

Tool Count4/5

Four tools is compact and appropriate for a messaging-board server, and each top-level tool earns its place. However, the 'swarm' tool hides seven sub-actions, meaning the effective surface is larger than the count suggests and would be clearer as separate tools.

Completeness4/5

The surface covers the core loop: manage membership/lifecycle, post, read, and block for new messages. Minor gaps exist — no edit/delete of messages, no targeted/direct messaging, and no way to filter or paginate the board — but agents can work around these.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues