onemessagebus

A typed NDJSON message bus for agent communication — and for anything else that speaks in events. One envelope, one filter grammar, payload bounds and redaction, a schema registry with version read-sets, and an emitter and reader over streams, generic over the vocabulary a consumer declares.

Three artifacts:

• onemessagebus — the core library. It knows the shape of an envelope and none of the words: which sources exist, which label keys are reserved and which top-level dimensions an envelope carries are a Vocabulary's to declare. Open reserves nothing; a vocabulary of your own is proven through the same conformance table the agent one is.
• onemessagebus-agent — the agent profile: the sources agentgraph, vcs, pipeline; the phase dimension; the reserved labels run_id, round, node, step, member, persona; and the schema families the stack registers (agent.event-envelope at [2, 1], agent.reply-envelope at [3, 2]). Its types serialize to the bytes oneagentgraph, onevcs and onepipeline write today, which the recorded streams under crates/onemessagebus-agent/tests/recorded/ prove byte for byte.
• onemessagebus, the binary — schema list|check|gen|register over the registry, schemas with schemas clear|fetch over the cache of schema bundles a configuration links by URL, events merge|emit over streams with --profile agent (the default) or --profile open, deliver and inbox carried over the inbox — a typed channel into a running process whose sender learns what the receiver did with each message — and send, next, reply, subscribe and status over durable queues kept on a transport a configuration names, with transports listing the kinds a transport can be, ask raising a question and waiting for the one reply that echoes its correlation, validate judging a record by a queue's validators before anything is sent, and serve answering a onejudge member's frames as its judge side. The local transport keeps the planner channel's files byte-compatible with onepipeline, and a distributed one is a plugin rather than a consumer change.

Install the command line

pip install onemessagebus-cli          # PyPI wheel, no toolchain needed
npm install -g onemessagebus-cli       # npm launcher, no toolchain needed
cargo install --git https://github.com/nickderobertis/onemessagebus onemessagebus-cli --locked

$ echo '{"note":"hello"}' | onemessagebus events emit run.ndjson --kind note-left --stream s-1 --source vcs --label run_id=R
{"v":1,"ts":"2026-09-13T06:16:27.838Z","stream":"s-1","seq":1,"source":"vcs","kind":"note-left","labels":{"run_id":"R"},"payload":{"note":"hello"},"artifacts":[]}
$ onemessagebus events merge run.ndjson other.ndjson --filter '{"include":[{"source":"vcs"}]}' --format text
$ onemessagebus schema check agent.event-envelope@2 --file envelope.json

docs/cli.md is the whole command line; docs/wire.md is the wire; docs/contract.md is the approved contract the consumers restate from.

Use the library

use onemessagebus_agent::{Emitter, EventFilter, Labels, Source};
use serde_json::Map;

let emitter = Emitter::new("run-1", Source::Vcs, Box::new(std::io::stdout()))
    .with_labels(Labels { run_id: Some("R".into()), ..Labels::default() })
    .with_filter(EventFilter::parse(r#"{"exclude":[{"kind":"heartbeat"}]}"#)?);
let envelope = emitter.emit("push", Map::new());
assert_eq!(envelope.seq, 1);

Every wire value is a Rust type with serde and schemars derivations, and the public API is stated in docs/contract.md.

Use the SDKs

pip install onemessagebus              # Python: import onemessagebus
npm install @onemessagebus/sdk         # TypeScript

Both are typed clients over the binary — one method per verb, message types declared as a Pydantic model or with Zod's defineMessage, subscriptions over a resident core — so a message defined in Python is validated by the Rust core and read typed in TypeScript. docs/sdk.md is the whole story.

Develop

just bootstrap   # from a clean clone
just check       # the deterministic gate: format, lint, tests incl. the binary journeys, docs, coverage
just gate        # check plus the diff-scoped LLM-judge tier; the bar before a push

AGENTS.md is the instruction layer; just --list is the command surface.