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], and the note, the labels, the filter and the artifact reference at 1). 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 — under a layout a linked schema bundle declares as data, or one a program links — 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 a configured member protocol's frames. The local transport keeps each queue as plain files in one directory, 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.