Agent Orchestration Description Language — a typed IR for agent graphs.
Public name: AODL. Wire identifier: hotl-0.2 (Hermes Orchestration Topology Language, kept for continuity with NousResearch/hermes-agent#88589).
This repository is a specification (schema + fail-closed validator + Hermes dry-run compiler) plus a design-language join table. It is not a scheduler, runtime, payment system, or paper.
Live catalog: kvnloo.github.io/aodl. Other git branches land at /preview/<branch>/.
The formal language is a working note, not a preprint: docs/working-note.md. There is no .tex / PDF and nothing on arXiv.
Harnesses describe nodes (Codex, OMP, Hermes, humans, tools) and then wave at the topology with English: swarm, mesh, supervisor, marketplace. Two systems can share a label and have different computational structure.
An orchestration at logical time
| Symbol | Meaning |
|---|---|
| nodes: agents, models, tools, humans, memories, tasks | |
| typed relations (delegate, verify, depend, observe, …) | |
| runtime state | |
| allocation / routing policy | |
| goals, budgets, human gates (Keel) |
Keep three objects distinct:
| Object | Meaning |
|---|---|
| Intent graph | what the controller wants (intentGraph + policies + constraints + provenance) |
| Compiled plan | what a specific runtime can safely support |
| Observed |
what actually exists now |
A marketplace is an allocation policy
Readable DSL is sugar. First proof of generality: the same primitives express ReAct and bounded recursion. Architecture search is search over programs in this IR. Mesh is declared peer edges, not a kind. Keel is spec/craid.md). The intent/participation contract is a compiler profile (profiles/intent-contract.md), not HOTL 0.3.
| Want | Open |
|---|---|
| Equations + stack | docs/working-note.md |
| C(RAID) R-phase capture | docs/research-craid-20260911.md (not a preprint) |
| Grammar | spec/hotl-0.2.ebnf |
| Structural IR shape | schema/hotl-0.2.schema.json — NOT the validator; see below |
| Long research spec | spec/hotl-0.2.md (ASCII; GitHub will not render O_t there) |
| Intent → plan → observed | spec/architecture.mermaid |
| Live UI (KaTeX + React) | kvnloo.github.io/aodl (branch previews: /preview/) |
| Visual ⇀ IR | spec/translation.md · encodings/ir-map.json |
| Intent / participation (LLM) | profiles/intent-contract.md |
| Searchable policy kernel | profiles/searchable-policy-kernel.md — policy search/distillation contract; no runtime |
| Hermes dry-run | profiles/hermes.md · compiler/hermes.py |
| Mesh registry (catalog only) | docs/mesh-registry.md · mesh/registry.json |
| Proof | python3 tests/validate.py · python3 tests/compile.py · python3 tests/mesh_registry.py |
| Path | Job |
|---|---|
schema/ + spec/ + tests/validate.py
|
HOTL 0.2 IR. Unknown version, implicit fan-in, unbounded spawn, payment grants fail closed. |
encodings/ |
Join table. Visual topology ids compile only through ir-map.json. |
harnesses/catalog.json |
Formal supported harness ids (hermes, omp, o8, grok, codex, claude, pi, fx). |
language/ |
Catalog: |
profiles/ |
Compiler / interpretation profiles (Hermes, intent-contract, searchable policy kernel). Not node kinds or runtimes. |
compiler/hermes.py |
Read-only Kanban dry-run. Predicts task ids; does not execute. |
mesh/registry.json |
Domain-tool catalog by stage. Not HOTL fields, not harness ids, not adapters. |
docs/working-note.md equations + stack (GitHub math)
docs/network.md sibling repos + harness ids
schema/hotl-0.2.schema.json structural IR shape (draft 2020-12); a
SUBSET of the validator, see Validation
schema/hotl-0.1.schema.json archived 0.1
spec/hotl-0.2.md research spec (ASCII)
spec/hotl-0.2.ebnf grammar sketch
spec/craid.md C(RAID) named hybrid (R→A→I→D)
encodings/visual.json design-language catalog (canonical)
encodings/ir-map.json τ: visual topology → HOTL 0.2
spec/translation.md human form of τ (LaTeX)
harnesses/catalog.json supported harness + network ids
language/ Vite catalog: calculus + translation + decoder (port 5178)
profiles/ compiler profiles (not kinds)
compiler/hermes.py Hermes dry-run → immutable `plan`
mesh/registry.json domain tools by stage (not HOTL)
schema/mesh-registry.schema.json fail-closed schema for that catalog
docs/mesh-registry.md Mesh Registry concept + shadcn/lint example
examples/valid/ fixtures that must pass
examples/invalid/ fail-closed cases
examples/compile-stop/ valid IR that must not compile to Kanban
tests/validate.py zero-dependency validator + join-table + catalog check
tests/compile.py dry-run corpus (message/mesh/auction/payment ⊥)
tests/mesh_registry.py mesh catalog (duplicate id / unknown stage fail closed)
python3 tests/validate.py
python3 tests/compile.py
python3 tests/mesh_registry.py
python3 compiler/hermes.py examples/valid/hermes-dry-run.json
python3 tests/validate.py examples/valid/pipeline.json
cd language && bun install && bun run dev
# http://127.0.0.1:5178/
python3 scripts/build-pages.py --current-only # site/ for GitHub Pages
# https://kvnloo.github.io/aodl/ (main)
# https://kvnloo.github.io/aodl/preview/<branch>/Unknown specVersion, implicit fan-in, unbounded spawn, missing ports, dependency cycles, undeclared privileged capability, and payment-execution grants fail closed. A visual swarm silhouette does not compile unless ir-map.json lists the required bounds.
Two validators exist and they are not equivalent. Measured against
examples/:
| validator | documents it rejects |
|---|---|
aodl_contract/validator.py (pure Python, zero dependencies) |
all 18 in examples/invalid/ |
schema/hotl-0.2.schema.json (draft 2020-12) |
3 of 18 0.2 documents — structural faults only |
The other 15 are graph properties (cycles, reachability, fan-in, bounds), policy
(privilege, payment, human gates) or the harness catalog (unknown id,
control-room kind). None is expressible in draft 2020-12 without duplicating
harnesses/catalog.json into the schema, so they stay in Python. The JSON Schema
is a subset, not a second implementation.
One rule it can express was missing until 2026-09-22: harness is only
meaningful on an executor node. A document putting a harness on a task node
passed the published schema and failed the validator — the schema being MORE
permissive, the direction that misleads an external consumer.
examples/invalid/harness-on-task.json covers it now. Nothing
loaded it until tests/validate.py began cross-checking it, one-directionally:
a 0.2 document the validator accepts must not be rejected by the schema, or an
external consumer implementing the published schema would refuse documents this
repo calls valid. The cross-check SKIPs when jsonschema is absent, because this
repo is zero-dependency by design.
Ids are fixed in harnesses/catalog.json. Unknown ids fail closed.
| id | kind | Dash | Firstmate | Upstream |
|---|---|---|---|---|
hermes |
executor | wired | none | NousResearch/hermes-agent |
omp |
executor | wired | primary | can1357/oh-my-pi |
o8 |
control-room | none | none | hurttlocker/o8 |
grok |
executor | wired | primary | xai-org/grok-build |
codex |
executor | wired | primary | openai/codex |
claude |
executor | wired | primary | anthropics/claude-code |
pi |
executor | none | primary | earendil-works/pi |
fx |
executor | none | none | vercel-labs/fx |
kunchenguid/firstmate is a distro, not a ninth harness. Fork: kvnloo/firstmate.
Named hybrid, not a new kind. Continuous Research → Analysis → Integration → Deployment. Feedback is observation. Unlabeled hybrid stays closed. Spec: spec/craid.md. Fixture: examples/valid/craid.json.
Blueprint is the product goal. C(RAID) is the protocol. AODL is the IR. Solarpunk is the digital twin.
| Repo | Job |
|---|---|
| kvnloo/aodl | this IR |
| kvnloo/verified-oss-loop | contribution contract (claims, evidence, never-merge) |
| kvnloo/dash | phone + Tailscale spawn of executor CLIs |
| kvnloo/frontier-kb | research notes |
| kvnloo/hermes-keel | Hermes governance, Level 0 only |
| NousResearch/hermes-agent | Kanban / profiles / A2A |
| kvnloo/blueprint | product goal; autonomous PM is step 1 |
| kvnloo/evolve | legacy C(RAID) / Claude Flow (inspo) |
See docs/network.md.
- Second scheduler or ledger (Hermes Kanban / Keel stay canonical where they exist)
- Inferring swarm / intelligence / consensus from a drawing
- Shipping the private ChatGPT voice thread that motivated the IR
- Mixing this into
kvnloo/dash - Treating Firstmate or o8 as AODL graphs
- A second GitHub repo for the same ids (
kvnloo/rippleis the ephemeral surface, not the IR contract) - An arXiv preprint before a measured claim exists (dry-run is in-tree; it does not execute)
Recovered 2026-08-17 from Hermes Kanban attachments t_7432ab2d (0.1) and t_83991e68 (0.2). examples/ and tests/validate.py were named in the 0.2 README and never attached; this repo is that first implementation milestone.
See spec/provenance.md.
See CONTRIBUTING.md and AGENTS.md. MIT. CI: python3 tests/validate.py, python3 tests/compile.py, python3 tests/mesh_registry.py. Workers never merge main.
from aodl_contract import validate, validate_or_raise, spec_revision, WIRE_SPEC
issues = validate(doc) # [] = okWire spec: hotl-0.2. Semantic revision: spec_revision().
CLI corpus remains python3 tests/validate.py (same implementation).