Models do not share a mind. They collaborate through explicit artifacts and verifiable receipts.
ContextOS-AgentRelay is the cross-model handoff layer of the ContextOS ecosystem. It defines how two or more AI sessions with different tool surfaces pass work between each other — as structured packets with a claim lock, an append-only ledger, and gates that keep an agent from inferring permission it was never granted.
Use it with ContextOS, or point it at any local directory. It is a protocol first; the CLI just enforces it.
Alpha (v0.1): the protocol, schemas, templates, a validator, a ledger linter, and a replayable synthetic run. It does not schedule or execute work for you — it defines and checks the contract your operators run under.
Two models working together fail in a specific way: one of them assumes. It assumes the other saw the conversation, assumes the state it can't read looks a certain way, or assumes an answer that showed up somewhere counts as permission. Each assumption is invisible until it isn't.
The relay removes the assumption. Work moves as a packet that names one owner, one outcome, allowed and forbidden actions, verification, and stop conditions. Every move leaves a receipt. Nothing is inherited.
1. Gates are not tiers. A packet's tier is the work's risk (1 safe, 2 surface first, 3 needs the principal). A packet's gate is why it's parked — and there are exactly two:
- fact-gate — it needs a fact, file, or dependency. Any capable operator can resolve it and continue. Resolving it changes the mechanism, never the scope.
- authority-gate — it needs the principal's authority. Only the principal releases it, never by inference.
These are orthogonal: a Tier-1 read-only packet can hit a fact-gate; a finished Tier-2 packet can sit on an authority-gate. Conflating them is the single biggest source of an agent granting itself permission.
2. Never assign a worker a read it cannot perform. Operators have different tool surfaces. When a packet needs state that lives behind another operator's tools, the operator that can see it exports that state into the packet before handing off. A worker that discovers the gap mid-packet returns a fact-gate — it does not guess.
Python 3.9+ and PyYAML 6.x.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .The bundled examples/relay/ is a complete synthetic run: a clean Tier-1 packet, a fact-gate an operator resolved by exporting state, a Tier-2 result parked on an authority-gate, and a Tier-3 packet dispatched correctly with an explicit approval block.
contextos-relay check examples/relay --principal principal
contextos-relay replay examples/relaycheck validates every packet and result, enforces the lock (one packet, one location), and lints the ledger — including the rule that only the principal may release an authority gate. replay prints the run as a readable timeline in append order.
Try breaking it: change the actor on the unblocked line in examples/relay/ledger.jsonl from principal to executor and re-run check. That's an agent self-releasing an authority gate, and it fails the build.
If you run ContextOS, your assistants already share a private context repo. Add a relay to it:
- Create a relay directory with an inbox per operator, plus
active/,done/,blocked/, andledger.jsonl. - Have your planner write packets from
templates/packet.md; workers claim by moving toactive/and return results fromtemplates/result.md. - Run
contextos-relay check <relay> --principal <you>on a schedule or before you trust a run.
Recurring work gets a lane defined before its first packet — that is where the capability split is declared, so a worker is never assigned a read it cannot perform. Use templates/agent-lane.md.
Read the full contract in docs/protocol.md.
The protocol's self-repair rule requires clear precedent before an operator may fix a jammed packet without a round-trip. If you keep decision records — for example with ContextOS-Decisions — that collection is what supplies the precedent, and its authority levels line up with the relay's gates. This is an adapter, not a dependency: AgentRelay requires no other repository.
| Command | What it enforces |
|---|---|
validate |
Packet/result schema, tier-3 packets carry explicit approval, blocked results declare a gate, required sections, one packet per location |
lint-ledger |
Valid append-only JSONL, events follow packet_created, unknown packets, and authority-gate release by the principal only |
check |
Both, together |
replay |
Prints the ledger as a timeline in append order |
Append order is canonical and ts is metadata — operators stamp from different clocks, so the linter never requires timestamps to increase. The bundled example includes an out-of-order timestamp on purpose.
Your relay stays local — the CLI only reads the path you give it and never uploads anything. The bundled examples/ are synthetic.
See CONTRIBUTING.md for the development workflow, SECURITY.md for reporting, and docs/protocol.md for the full protocol.
MIT — see LICENSE.