Coordination

OpenLegion is a fleet model — blackboard + pub/sub + handoff (no CEO agent). There is no LLM in the middle deciding what runs next. Agents coordinate through four explicit primitives, all running on the mesh host:

• Blackboard — durable shared state in SQLite WAL.
• PubSub — fan-out events.
• Lanes — per-agent FIFO queues.
• Handoffs — durable task records routed through MessageRouter.

Templates assemble agents into ready-made rosters. There are no DAG YAML files and no deterministic orchestrator.

​

Blackboard

A SQLite WAL key-value store with atomic CAS via write_if_version and an audit log that supports undo and archive. Keys are auto-namespaced under projects/{name}/ so fleets in different projects can’t collide. Tools on mesh_tool: Typical namespaces: tasks/* (handoffs), context/* (shared context), signals/* (one-shot signals), history/* (append-only audit log).

​

Pub/Sub

Fan-out topic bus. Both publishing and subscribing are permission-gated by can_publish / can_subscribe. Use pub/sub for fire-and-forget signals (“research is done”, “new lead came in”) rather than work assignment — for work, use handoffs.

​

Lanes

Each agent has a per-agent FIFO lane on the mesh. Messages routed into a lane wake the agent up; results are forwarded with a MessageOrigin carrying kind / channel / user so the reply can flow back to the requester. Lanes support three modes:

• followup (default) — append and wake.
• steer — inject into a busy agent’s loop. Rate-limited to 10 wakeups / 3600s to avoid thrashing.
• collect — batch messages while the agent is busy; deliver the whole batch when it goes idle.

​

Handoffs (coordination_tool)

Structured task assignment between agents. All four functions are part of the coordination_tool: MessageRouter resolves the target — either a literal agent ID or capability:<name> (routes to whichever agent declares that capability). Cross-project routing is blocked when OPENLEGION_PROJECT_SCOPE_MODE=enforce.

​

V1 vs V2 task records

Handoffs run in one of two backends:

• V1 — handoff is stored as a blackboard entry at tasks/{agent}/{handoff_id}. Lightweight, no durable record outside the blackboard.
• V2 — durable task records in a separate table; surface via the openlegion tasks CLI command. Enabled when OPENLEGION_ORCHESTRATION_TASKS_V2=1 — default ON in v0.1.0.

V2 is the recommended mode. Set the env var to 0 only if you specifically need the old blackboard-backed behavior.

​

Fleet Templates

Templates are agent rosters — YAML manifests in src/templates/ that the operator can apply to materialize a fleet. There are 13 templates in the engine today: Templates use a "{default_model}" placeholder which is substituted at apply time.

​

apply_template is per-slot, not atomic

fleet_tool (operator-only) exposes list_templates and apply_template. apply_template accepts agent_overrides per-slot — model, instructions (≤12K), soul (≤4K), heartbeat, interface (≤4K). The role is template-fixed and cannot be overridden. Important: apply_template is per-slot and NOT atomic. If the template has 4 slots and slot 3 fails, agents from slots 1 and 2 stay created. You must clean up partially-applied fleets yourself.

​

MessageOrigin

Every message — chat input from a channel, a handoff, a lane delivery — carries a MessageOrigin Pydantic model with kind / channel / user. Results flow back along the same path: a Telegram message routed to a researcher and then handed off to a writer eventually returns to the original Telegram user, with no extra plumbing required from the agent code.

​

Coordination at a Glance