pi-ultra-messenger

Continuous Pi worker pool for the Agent Flywheel workflow

A fork of pi-messenger-swarm by Tom (@monotykamary), customized into a continuous Pi worker pool. Configure Pi-visible worker pools, start the supervisor, and it continuously replenishes lightweight Pi agents that execute the existing Agent Flywheel workflow — without manually farming terminal panes.

Quick Start

# Install
pi install npm:pi-ultra-messenger

# Non-interactive setup with two pools
pi-ultra-messenger setup \
  --worker 'anthropic/claude-sonnet-5=6' \
  --worker 'umans/umans-coder=4' \
  --max-concurrent 10 \
  --start

# Or interactive
pi-ultra-messenger setup

# Start the supervisor
pi-ultra-messenger supervisor start

# Check status
pi-ultra-messenger supervisor status

# Open the /swarm overlay in Pi
/swarm

Commands

# Setup
pi-ultra-messenger setup [--worker 'model=count'] [--max-concurrent n] [--start] [--dry-run]

# Pool management
pi-ultra-messenger pool list
pi-ultra-messenger pool add --model <provider/model> --workers <n>
pi-ultra-messenger pool remove <id>
pi-ultra-messenger pool scale <id> --workers <n>
pi-ultra-messenger pool enable <id>
pi-ultra-messenger pool disable <id>

# Supervisor
pi-ultra-messenger supervisor start
pi-ultra-messenger supervisor status
pi-ultra-messenger supervisor pause
pi-ultra-messenger supervisor resume
pi-ultra-messenger supervisor stop

# Spawn (manual)
pi-ultra-messenger spawn --role Researcher "Analyze X" [--model provider/model]
pi-ultra-messenger spawn list
pi-ultra-messenger spawn history
pi-ultra-messenger spawn stop <id>

# Worker telemetry (called by spawned workers)
pi-ultra-messenger worker status --phase <phase> [--bead <id>] [--spawn-id <id>] [--agent-name <name>] "message"

# Status
pi-ultra-messenger status
pi-ultra-messenger list
pi-ultra-messenger swarm

# Server
pi-ultra-messenger --status | --start | --stop | --restart | --logs

Architecture

Project checkout on main
  AGENTS.md · .beads/ · source · .pi/pi-messenger.json
        ↓
Detached harness server
  Supervisor timer (poll, refill, stagger)
  Spawn map (PIDs, progress, history)
  JSONL events + spawn-runtimes.json + orphan recovery
        ↓ spawn Pi JSON workers
Fungible Pi workers
  Pi loads AGENTS.md
  Worker uses br / bv / MCP Agent Mail / Git / project tools
  Worker completes one bead and exits

What This Fork Keeps

• Detached harness process
• Pi JSON-mode spawning
• Role-file loading
• Pi skill discovery
• Live JSON event parsing
• Per-project spawned-agent JSONL history
• PID persistence
• Harness restart recovery
• Orphan-process reconciliation
• Concurrency limiting
• Memorable worker names
• Pi extension and terminal overlay framework

What This Fork Removes

• Pi Messenger channels and direct messages
• Pi Messenger feed polling
• Pi Messenger file reservations
• Custom task.* issue database
• Internal task board
• Task claims and completion through Pi Messenger

Workers coordinate through MCP Agent Mail and follow the target project's AGENTS.md directly.

Optional Roles

• Coordinator (agents/coordinator.md): one-shot tender that inspects worker state and sends coordination messages via Agent Mail. Disabled by default. Never gates refill.
• Goal Refiner (agents/goal-refiner.md): suggestion-only role by default (manual). Optionally an automatic context-rich Bead quality gate (goalRefiner.mode: "automatic"): thin ready Beads are withheld from workers and sent once to the configured refiner model, which rewrites the description into self-contained executable memory before the next supervisor tick. Already-approved Beads keep flowing to workers without waiting. Never gates all refill.

/swarm Control Plane (Phase C1)

The /swarm overlay is evolving from a read-only dashboard into a control plane. Phase C1 adds:

• Supervisor control bar on Overview: S Start Swarm, p pause, P resume, s stop (with y/N confirmation).
• Heartbeat in the title bar (flips per supervisor tick; requires the harness reachable).
• Gauges: worker headroom and per-pool fill bars (12-cell block glyphs).
• View-only mode (v): disables all mutating keys without crashing.
• All mutations go through the new POST /control HTTP endpoint — the single authority shared with the CLI — and are written to a control-audit.jsonl trail with source: ui|cli.

State refreshes from disk on the next render; a true per-tick live heartbeat needs a TUI redraw timer (planned for a later phase).

Configuration

{
  "maxConcurrentSpawns": 10,
  "supervisor": {
    "enabled": true,
    "paused": false,
    "pollIntervalMs": 15000,
    "maxStartsPerTick": 2,
    "workerPools": [
      { "id": "default", "workers": 3, "model": { "mode": "inherit" }, "enabled": true }
    ],
    "coordinator": { "enabled": false, "model": { "mode": "inherit" }, "mode": "manual" },
    "goalRefiner": {
      "enabled": false,
      "model": { "mode": "inherit" },
      "mode": "manual",
      "minimumQualityScore": 75
    }
  }
}

Config locations: .pi/pi-messenger.json (project), ~/.pi/agent/pi-messenger.json (global).

Releasing

Releases are automated.

• Test runs typecheck + tests on every push/PR to main.
• Sync master fast-forwards the legacy master branch to main on every push to main (no manual git push origin main:master).
• Release builds, tests, and publishes to npm when a v* tag is pushed — using the NPM_TOKEN repo secret, a npm Granular access token scoped to this package (granular tokens bypass 2FA, so CI needs no OTP). Provenance is signed via GitHub OIDC. It can also be run manually from the Actions tab with a tag.

One-command release (from a clean main):

npm run release:push    # standard-version bumps+commits+tags, then pushes

CI does the rest. The only setup is the NPM_TOKEN secret — an npm Granular token (Read and write, scoped to pi-ultra-messenger). Avoid classic "Publish" tokens: they require an OTP when 2FA is on.

Future Improvements

• Bead plan-to-memory conversion: an automated pipeline that converts a full implementation plan into a dependency-linked set of context-rich Beads (outcome, acceptance criteria, failure modes, verification plan). The automatic quality gate validates and enriches individual ready Beads, but does not yet decompose a plan into them.

License

MIT