fleet-bus
Open source under the MIT licence. View the source
A NATS coordination bus for long-running AI agents, plus a deterministic orchestrator that decides who works on what.
The problem
Agents that coordinate by chatting in a channel miss mentions, answer twice, lose handoffs, and leave no record of who owned a task. fleet-bus moves coordination off the chat surface and into code.
How it works
Chat (Discord) is only the human display. NATS is the control plane: dispatch, relay, wake and sequencing ride typed envelopes on a fixed subject tree. An external k-board, reached over REST with compare-and-set updates, is the record of task state (only its client ships here). The orchestrator is a state machine with no LLM in the control path, and every transition is a unit-tested case.
Features
- fleet-nats: shared NATS library with connection, typed envelope, subject builders, pub/sub/request-reply and redaction
- fleet-orchestrator: task state machine with dispatch, relay, wake and retry behaviors and a k-board CAS client
- fleet-core base client with typed config and a prod/staging URL tripwire
- fleet-subscriber turns an inbound envelope into an agent turn on a Hermes-style gateway
- Example NATS cluster configs, provisioning and deploy scripts, envelope/ordering/retry/QoS contracts in docs
How it was built
The repository began on 2026-04-27 as a small agent-to-agent server for monitoring. On 2026-07-07 it was repurposed as fleet-bus, because agents coordinating by chatting missed mentions, double-answered and lost hand-offs.
Coordination moved onto NATS with a typed envelope, and chat became display only. Nothing reads chat to decide control flow.
The orchestrator is a pure state machine with no model, clock or I/O, and every transition has a unit test. It writes the task board first and then emits the signal, so ownership never lags the message.
Docstrings once promised at-least-once delivery the transport did not honour. Contract C5, ratified on 2026-07-10, states the real promise, and text markers parsed out of agent replies were replaced by typed fields.
AI agents wrote the code in parallel lanes under a written master plan, with a review swarm and a Codex cross-review before merge. Rico ran the goal runs and kept people watching and steering in the chat channel.