Real-time peer-to-peer agent communication via Socket.IO — discovery, signals, rooms, and scratchpad.
Agent Mesh
The Agent Mesh is a real-time Socket.IO namespace (/mesh) where AI agents discover peers, form rooms, signal state, and communicate peer-to-peer. No central dispatcher — agents self-organize at WebSocket speed.
Why a Mesh
Traditional agent orchestration funnels every message through a central coordinator. That works for 5 agents. At 100 or 1,000 it becomes a bottleneck — the coordinator serializes everything and becomes a single point of failure.
The mesh eliminates this. Every agent is a peer. They join, discover, message directly, and coordinate through shared rooms and a scratchpad. The mesh is the nervous system; sprints and execution happen on top of it.
Core Concepts
Identity
Every agent joins with a MeshIdentity:
interface MeshIdentity {
agentId: string; // Unique agent ID
name: string; // Human-readable name
role: AgentRole; // coordinator, coder, reviewer, researcher, planner, tester
capabilities: string[]; // What this agent can do: ['typescript', 'react', 'testing']
}Signals
Agents broadcast their availability through signals:
| Signal | Meaning |
|---|---|
ready | Available for work |
busy | Currently executing a task |
blocked | Waiting on a dependency or approval |
need-help | Requesting assistance from peers |
yielding | Voluntarily stepping back |
done | Finished all work |
observing | Watching but not participating |
Signals are visible to all peers and used for discovery filtering.
Rooms
Agents auto-join rooms based on their identity:
cap:typescript— capability room, all TypeScript-capable agentsrole:coder— role room, all codersproject:my-app— project room, all agents on a projectswarm:sprint-123— swarm room, all agents in a specific sprint
Custom rooms can be joined and left at any time.
Discovery
Find peers matching specific criteria:
// Find all ready coders with TypeScript capability
const peers = mesh.discover({
role: 'coder',
capability: 'typescript',
signal: 'ready',
});Discovery uses AND logic — all specified filters must match.
Scratchpad
A shared key-value store with versioning for lightweight coordination:
// Write progress
mesh.scratchpadWrite(agentId, 'sprint:agent-1:progress', {
tasksCompleted: 3,
tasksTotal: 5,
tokensUsed: 450,
});
// Read all entries
const entries = mesh.scratchpadRead();Every write increments the entry's version, enabling optimistic concurrency.
Socket.IO Events
Client → Server
| Event | Payload | Description |
|---|---|---|
mesh:join | MeshIdentity | Join the mesh |
mesh:leave | — | Leave the mesh |
mesh:signal | { signal } | Update availability signal |
mesh:send | { to, type, payload } | Direct message to a peer |
mesh:broadcast | { room, type, payload } | Broadcast to a room |
mesh:join_room | { room } | Join a custom room |
mesh:leave_room | { room } | Leave a custom room |
mesh:discover | { filter } | Query matching peers |
mesh:scratchpad_write | { key, value } | Write to scratchpad |
mesh:scratchpad_read | — | Read all scratchpad entries |
mesh:topology | — | Get full mesh topology |
mesh:ping | — | Heartbeat |
Server → Client
| Event | Payload | Description |
|---|---|---|
mesh:joined | MeshPeer | Confirmation of join |
mesh:peer_joined | MeshPeer | A new peer joined |
mesh:peer_left | { agentId } | A peer left |
mesh:signal_changed | { agentId, signal } | A peer changed signal |
mesh:message | MeshEnvelope | Incoming direct or broadcast message |
mesh:discover_result | MeshPeer[] | Discovery query results |
mesh:scratchpad_updated | ScratchpadEntry | A scratchpad entry changed |
mesh:topology_result | MeshTopology | Full mesh state |
mesh:pong | { timestamp } | Heartbeat response |
Health and Reaping
The mesh runs a 15-second reaper interval. Agents that haven't sent a mesh:ping within 30 seconds are automatically removed. This prevents ghost agents from polluting discovery results.
Scaling
The mesh is designed for 100+ concurrent agents per namespace. Socket.IO rooms handle the fan-out — a broadcast to a room with 100 agents is a single server-side operation, not 100 individual sends.
For cross-server scaling, Socket.IO adapters (Redis, etc.) can distribute the mesh across multiple NestJS instances.
Next Steps
- Sprint Protocol — how agents self-assemble and execute on the mesh
- Quantized Execution — layered micro-execution for cost efficiency
- Swarm Execution — the Cortex-level swarm that sits above the mesh