refactor: optimize multi-agent-mux-loop spec and clean up workspace docs
- Add OPTIMIZATION.md detailing Invocation-Aware Scoped Guard, race-free lock design, and DoD verification gates approved via multi-agent loop - Update root markdown files (README, BOOTSTRAP, MESSAGING) replacing legacy TMUX references with HERDR - Remove redundant root markdown files and archive promoted reviewer PASS report
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# tmux-agent-orchestration
|
||||
# herdr-agent-orchestration
|
||||
|
||||
An advanced, high-reliability **Multi-Agent Orchestration & Messaging Backplane** framework built on Tmux and MQTT. It is designed to coordinate, isolate, and audit long-running agent tasks (such as code generation, refactoring, and security reviews) across multiple LLM backend clients (e.g., Claude, Hermes).
|
||||
An advanced, high-reliability **Multi-Agent Orchestration & Messaging Backplane** framework built on Herdr and MQTT. It is designed to coordinate, isolate, and audit long-running agent tasks (such as code generation, refactoring, and security reviews) across multiple LLM backend clients (e.g., Claude, Hermes).
|
||||
|
||||
---
|
||||
|
||||
@@ -8,8 +8,8 @@ An advanced, high-reliability **Multi-Agent Orchestration & Messaging Backplane*
|
||||
|
||||
Modern agentic workflows often suffer from session timeout, lack of process isolation, terminal viewport truncation (scrollback limits), and complex concurrency issues.
|
||||
|
||||
**tmux-agent-orchestration** addresses these problems by providing:
|
||||
1. **Tmux-based Process Isolation:** Spawning LLM client sessions inside dedicated, isolated tmux environments to support persistent background runs.
|
||||
**herdr-agent-orchestration** addresses these problems by providing:
|
||||
1. **Herdr-based Process Isolation:** Spawning LLM client sessions inside dedicated, isolated herdr environments to support persistent background runs.
|
||||
2. **Asynchronous Event-Driven Architecture:** Leveraging an MQTT broker as a message backplane to coordinate state transitions (`started`, `progress`, `completed`, `error`) between collaborating agents.
|
||||
3. **Multi-Agent Mux (MAM):** Combining local file-based locks (fcntl) and an ACID-compliant SQLite WAL database (`.mam/agent-sessions.db`) to manage concurrent job claims and track running agent sessions without drift.
|
||||
4. **Automated Review & Quality Loop:** Implementing parallel reviewer loops where worker agents must receive a `PASS` rating from various specialized verification agents (e.g., Claude for high-level logic, Hermes for shell syntax/safety) before merging code.
|
||||
@@ -30,7 +30,7 @@ Alternatively, if you have already cloned the repository locally, run the instal
|
||||
bash deploy/install.sh
|
||||
```
|
||||
|
||||
The idempotent installer automatically validates system dependencies (tmux, python3, and PyYAML), creates the python virtual environment (`.venv`), installs dependencies, copies `.env.example` as `.env`, and initializes the `.agents/` scaffolding.
|
||||
The idempotent installer automatically validates system dependencies (herdr, python3, and PyYAML), creates the python virtual environment (`.venv`), installs dependencies, copies `.env.example` as `.env`, and initializes the `.agents/` scaffolding.
|
||||
|
||||
---
|
||||
|
||||
@@ -38,11 +38,11 @@ The idempotent installer automatically validates system dependencies (tmux, pyth
|
||||
|
||||
All orchestration functionalities are structured under the `.agents/skills/` directory:
|
||||
|
||||
* **`multi-agent-mux-create`**: Spawns isolated tmux sessions running specified agent CLI wrappers. It captures system processes, updates metadata registries, and enforces authentication checks.
|
||||
* **`multi-agent-mux-create`**: Spawns isolated herdr sessions running specified agent CLI wrappers. It captures system processes, updates metadata registries, and enforces authentication checks.
|
||||
* **`multi-agent-mux-stop`**: Gracefully terminates agent CLI sessions (using key macros like `/exit` or `Exit`) and handles disk purge operations (removing conversation JSON files and SQLite logs for deleted workspaces).
|
||||
* **`multi-agent-mux-resume`**: Restores stopped sessions by resolving workspace UUIDs from disk or cache, and invokes the underlying agent using session-resume parameters (e.g., `claude -r <uuid>` or `hermes --resume <uuid>`).
|
||||
* **`multi-agent-mux-status`**: Queries the running states of all active sessions, detecting PID mismatches, command signatures, and drifts between actual tmux instances and the registry database.
|
||||
* **`multi-agent-mux-monitor`**: A long-running Kanban reconcile worker that dynamically monitors tmux sessions and synchronizes states to `.mam/agent-sessions.yaml`.
|
||||
* **`multi-agent-mux-status`**: Queries the running states of all active sessions, detecting PID mismatches, command signatures, and drifts between actual herdr instances and the registry database.
|
||||
* **`multi-agent-mux-monitor`**: A long-running Kanban reconcile worker that dynamically monitors herdr sessions and synchronizes states to `.mam/agent-sessions.yaml`.
|
||||
* **`multi-agent-mux-delegate-job`**: The core asynchronous task distribution module containing:
|
||||
* `registry.py`: Atomically registers and claims jobs using file advisory locks (`fcntl`).
|
||||
* `job_subscriber.py`: Connects to the MQTT backplane, captures live events, and appends them to audit trails.
|
||||
@@ -55,7 +55,7 @@ All orchestration functionalities are structured under the `.agents/skills/` dir
|
||||
|
||||
The system coordinates LLM agents across multiple workspaces through two core layers:
|
||||
|
||||
1. **Layer A — Tmux Orchestration (lib.sh + status/resume/stop/create)**: Runs the agents (one tmux session per agent-workspace combination) and maintains an authoritative registry in `.mam/agent-sessions.yaml` (+ `.mam/agent-sessions.db`).
|
||||
1. **Layer A — Herdr Orchestration (lib.sh + status/resume/stop/create)**: Runs the agents (one herdr session per agent-workspace combination) and maintains an authoritative registry in `.mam/agent-sessions.yaml` (+ `.mam/agent-sessions.db`).
|
||||
2. **Layer B — Async Job Delegation (delegate-job)**: Dispatches a task to an agent and observes progress and completion via an event channel.
|
||||
|
||||
These two layers share one lock-guarded chokepoint for file I/O: `lib.sh::atomic_dump_yaml`. Every write is protected by an exclusive SQLite database transaction lock and schema validation.
|
||||
@@ -92,12 +92,12 @@ These two layers share one lock-guarded chokepoint for file I/O: `lib.sh::atomic
|
||||
+--------+
|
||||
```
|
||||
|
||||
### 🔒 Tmux Server Isolation
|
||||
### 🔒 Herdr Server Isolation
|
||||
|
||||
To prevent workspace tmux processes from interfering with each other or with system tmux servers, the framework enforces isolated tmux environments:
|
||||
* **Per-Workspace Shim:** `_init_tmux_isolation` and `_resolve_real_tmux_path` instantiate a per-workspace shim directory under `/tmp/multi-agent-tmux-shim/<TMUX_SERVER_NAME>/tmux` that intercepts tmux commands and wraps them in `tmux -L <server>`.
|
||||
* **PATH Rewriting:** The `PATH` environment variable is dynamically prepended with the shim path in all child processes. This ensures any `tmux` invocation within the agent's process tree is restricted to its isolated socket server.
|
||||
* **Environment Restoration:** If `TMUX_SERVER_NAME` is set to `default`, the PATH override is removed, reverting to the default global tmux server.
|
||||
To prevent workspace herdr processes from interfering with each other or with system herdr servers, the framework enforces isolated herdr environments:
|
||||
* **Per-Workspace Shim:** `_init_herdr_isolation` and `_resolve_real_herdr_path` instantiate a per-workspace shim directory under `/tmp/multi-agent-herdr-shim/<HERDR_SERVER_NAME>/herdr` that intercepts herdr commands and wraps them in `herdr -L <server>`.
|
||||
* **PATH Rewriting:** The `PATH` environment variable is dynamically prepended with the shim path in all child processes. This ensures any `herdr` invocation within the agent's process tree is restricted to its isolated socket server.
|
||||
* **Environment Restoration:** If `HERDR_SERVER_NAME` is set to `default`, the PATH override is removed, reverting to the default global herdr server.
|
||||
|
||||
### 🛡️ Concurrency Design & Write Serialization
|
||||
|
||||
|
||||
Reference in New Issue
Block a user