# The Synapse Protocol (v1.0-draft)
**Status:** Draft
**Last Updated:** 2026-02-02
**Version:** 0.3.0
## Abstract
The Synapse Protocol defines a mechanism for asynchronous coordination between autonomous AI agents ("Nodes") working on a shared codebase. It relies on a central "Context Bus" (state store) to manage task assignment, file locking, and consensus.
## 1. Core Concepts
### 1.1 The Context Bus
A centralized, persistent state store (typically a JSON file with atomic locking) that holds:
* **Summary:** A high-level description of current progress.
* **Next Steps:** A structured queue of pending tasks.
* **Active Files:** A list of resources currently locked by an active Node.
* **Messages:** A broadcast channel for inter-node communication.
* **Heartbeats:** Liveness signals to prevent deadlocks.
### 1.2 The Node
An autonomous AI agent session. Each Node generates a unique ID (e.g., `Node-A1B2`) and registers its **Role** and **Model Strength** upon startup.
#### 1.2.1 Roles
* **Bootstrap Manager:** The low-cost node responsible for task distribution and consensus monitoring.
* **Architect/Developer:** High-strength nodes responsible for complex implementation and design.
## 2. The Execution Loop
Nodes MUST adhere to the following lifecycle:
0. **REGISTER (Discovery)**
* Node calls `register_node(agent_id, role, model_name)`.
* If `bootstrap_required` is true, the node MUST attempt to claim the `bootstrap_manager` role if strength is sufficient (or instruct the user to spawn a manager).
1. **SYNCHRONIZE (Read)**
* Node calls `read_state()` to fetch the current context.
* Node checks `messages` for high-priority interruptions.
* Node identifies the next available task from `next_steps`.
2. **CLAIM (Lock)**
* Node calls `update_state()` to:
* Mark a specific task as `[IN PROGRESS by Node-ID]`.
* Add target files to `active_files` (Locking).
* *Collision Avoidance:* If a file is already in `active_files` (and heartbeat is fresh), the Node MUST back off.
3. **ACT (Execute)**
* Node performs file edits, shell commands, etc.
* Node SHOULD call `heartbeat()` periodically (every <60s) during long operations.
4. **VERIFY (Test)**
* Node runs tests to validate changes.
5. **REPORT (Unlock)**
* Node calls `update_state()` to:
* Mark the task as `[COMPLETED]`.
* Clear `active_files` (Unlocking).
* Update `summary` with results.
## 3. Data Structures
### 3.1 Task Object
```json
{
"task": "Refactor server.py",
"status": "pending" | "in_progress" | "completed" | "failed",
"assigned_to": "Node-A1B2" | null,
"id": "1"
}
```
### 3.2 State Object
```json
{
"summary": "...",
"next_steps": [Task, ...],
"active_files": ["server.py"],
"messages": ["..."],
"last_heartbeat": 1700000000.0,
"timestamp": 1700000000.0
}
```
## 4. Resilience
### 4.1 Zombie Detection
The Context Bus Monitor checks `last_heartbeat`. If `time.now() - last_heartbeat > 60s` AND `active_files` is not empty:
1. The active Node is declared a Zombie.
2. `active_files` is cleared (Locks released).
3. An alert is logged to `summary`.
## 5. Security
* **Path Confinement:** All operations are restricted to the Project Root.
* **Command Whitelist:** Only approved shell commands may be executed via the Bus (if applicable).
