herdr-plugin-amq 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cabra.lat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# Herdr AMQ Plugin
+
+[![CI](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/ci.yml/badge.svg)](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/ci.yml)
+[![Security](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/security.yml/badge.svg)](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/security.yml)
+[![Tests](https://img.shields.io/badge/tests-95%20passing-brightgreen.svg)](https://github.com/cabra-lat/herdr-plugin-amq)
+[![Coverage](https://img.shields.io/badge/coverage-80%25-brightgreen.svg)](https://github.com/cabra-lat/herdr-plugin-amq)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Proudly Vibe Coded - Plasma Mix](https://vibecoded.fyi/badges/flat/main/proudly-vibe-coded-plasma-mix.svg)](https://vibecoded.fyi/)
+
+> **The asynchronous nervous system for autonomous AI agent swarms in [Herdr](https://herdr.dev/).**  
+> Combines native pure-JS Maildir inter-agent messaging, an autonomous **Doorbell Bridge**, decentralized file-based task coordination, and the **AGmail** webmail dashboard.
+
+---
+
+## The Origin & The Problem
+
+> *"If you follow AI news, you have probably seen endless hype around 'multi-agent swarms' talking to each other... That is cute for a 30-second screen recording. In a real codebase with actual physics, compiler errors, and Git history, it is a complete disaster."*  
+> — Read the full story: [**My AI Agents Send Me Emails: Office Drama in a Godot Repo**](https://cabra.pw/my-ai-agents-send-me-emails.html)
+
+When coordinating swarms of AI coding agents across complex codebases, synchronous chat rooms and blocking `wait` loops fall apart:
+1. **Context Window Bloat**: Group chats flood agent context with irrelevant noise, burning hundreds of thousands of tokens per hour.
+2. **Turn-Based Nature of LLMs**: AI models are turn-based; when an agent says *"Yeah I'll do that"* or finishes its tool execution, **it terminates its turn and goes to sleep**. It cannot run a busy-wait loop.
+3. **Dead Mailboxes Without a Doorbell**: Having asynchronous inboxes (AMQ) solves decoupled storage, but mail sitting in a directory is inert. If an agent is asleep, incoming messages sit unread forever.
+
+### The Missing Piece: The Doorbell Bridge
+
+This plugin bridges **AMQ** (the persistent storage) and **Herdr** (the terminal multiplexer and agent lifecycle supervisor).
+
+The **Bridge Daemon** continuously inspects agent inboxes. When an agent is `idle` or `done` in its Herdr terminal pane and has unread transmissions, the bridge **rings the doorbell** via `herdr agent prompt`. The sleeping agent wakes up, drains its inbox, performs its work, sends an asynchronous reply, and goes back to sleep.
+
+```mermaid
+flowchart TD
+    subgraph Storage ["Persistent Transport Layer"]
+        AMQ[".agent-mail/ (Maildir + RFC 5322)<br/>Decoupled Markdown Transmissions"]
+        BUS[".opencode/bus/ (Decentralized Task Cards)<br/>backlog/ → doing/ → blocked/ → done/"]
+        CAS[".agent-mail/blobs/ (CAS Blobstore)<br/>SHA-256 Render Strips & Proofs"]
+    end
+
+    subgraph Bridge ["The Autonomous Nervous System"]
+        DAEMON["Bridge Daemon (herdr-amq bridge-daemon)<br/>Watches mailboxes & checks Herdr agent states"]
+        DOORBELL{"Agent Status in Herdr?"}
+    end
+
+    subgraph Execution ["Herdr PTY / Terminal Swarm"]
+        H_BUSY["working → Leave alone (no spam)"]
+        H_BLOCKED["blocked → Alert coordinator / human"]
+        H_IDLE["idle / done → RING DOORBELL<br/>(herdr agent prompt)"]
+        AGENT["Awakened Agent<br/>1. herdr-amq drain --me <handle><br/>2. Executes task in isolated worktree<br/>3. herdr-amq send / reply --id ...<br/>4. Goes back to sleep"]
+    end
+
+    subgraph Oversight ["Human-in-the-Loop & Mission Control"]
+        AGMAIL["AGmail Webmail & Kanban Dashboard<br/>http://127.0.0.1:8505 (Strictly Local)"]
+    end
+
+    AMQ -->|New mail arrives| DAEMON
+    DAEMON --> DOORBELL
+    DOORBELL -->|working| H_BUSY
+    DOORBELL -->|blocked| H_BLOCKED
+    DOORBELL -->|idle/done| H_IDLE
+    H_IDLE --> AGENT
+    AGENT -->|Sends mail + CAS attachments| AMQ
+    AGENT -->|Claims / updates tasks| BUS
+    AGENT -->|Pins render artifacts| CAS
+    AMQ -.->|Monitored & inspected by| AGMAIL
+    BUS -.->|Rendered live in Kanban| AGMAIL
+```
+
+---
+
+## Key Features
+
+### 1. The Autonomous Doorbell Bridge
+- **Lifecycle-Aware Wakeups**: Rings doorbells (`herdr agent prompt`) only when agents are `idle` or `done`, preventing command interleaving during active turns.
+- **De-duplication**: Tracks delivered message IDs in persistent state (`bridge-state.json`) so agents are never doorbelled twice for the same mail.
+- **Self-Healing Panes**: Automatically detects and renames desynced terminal titles back to their canonical agent handles (`herdr agent rename`).
+- **Blocked State Alerts**: When an agent with unread mail is blocked on external input, logs actionable alert directives for human intervention.
+
+### 2. Pure-JS Maildir & RFC 5322 Engine (Zero Runtime Dependencies)
+- **100% Self-Contained ESM**: No external Go binary, Python scripts, or npm supply-chain dependencies required.
+- **DJB Atomic Delivery**: Uses classic `tmp/` -> `new/` atomic filesystem renames to prevent partial reads or race conditions between concurrent agents.
+- **RFC 5322 In-Reply-To & References**: Full thread tracking and conversation reconstruction from standard message headers.
+
+### 3. AGmail Dashboard (Mission Control)
+- **Authentic Webmail Interface**: Real folders (Inbox, Sent, Drafts, Starred, Trash) powered by live Maildir storage.
+- **Rich Visual Attachment Cards**: Previews render strips, PNG contact sheets, and test output generated by headless tools (like Godot via VirtualGL) directly in email threads.
+- **Interactive Kanban Board**: Visual task lane tracking (`backlog/`, `doing/`, `blocked/`, `done/`) with real-time SSE updates.
+- **Human-in-the-Loop Interventions**: Compose and inject executive orders directly into the swarm's queue from your browser.
+- **Fuzzy Search & Filtering**: Fast multi-attribute filtering (`from:spotter with-images:true kind:status`).
+
+### 4. Git Worktree Isolation & Task Bus
+- **Multi-Lane Isolation**: Automatically provisions and manages dedicated Git worktrees (`.worktrees/<agent>`) so parallel agents never step on each other's unstaged files.
+- **Decentralized File-Based Task Cards**: Directory-based task bus (`.opencode/bus/`) immune to concurrent merge conflicts.
+
+---
+
+## Requirements
+
+- **Node.js** >= 18
+- **[Herdr](https://herdr.dev/)** >= 0.7.0 *(Terminal workspace manager & agent lifecycle supervisor)*
+- **Zero npm runtime dependencies**
+
+---
+
+## Installation & Linking
+
+Link the plugin into your local Herdr configuration:
+
+```bash
+# Clone or navigate to the repository
+cd herdr-plugin-amq
+
+# Link into Herdr
+herdr plugin link .
+```
+
+Verify that the plugin and its actions are active:
+
+```bash
+herdr plugin list
+herdr plugin action list --plugin cabra.amq
+```
+
+---
+
+## Herdr Actions & Keybindings
+
+Add keybindings to `~/.config/herdr/config.toml` for instant access:
+
+```toml
+[[keys.command]]
+key = "prefix+m"
+type = "plugin_action"
+command = "cabra.amq.bridge-status"
+description = "Check AMQ mailbox status"
+
+[[keys.command]]
+key = "prefix+M"
+type = "plugin_action"
+command = "cabra.amq.doorbell-check"
+description = "Ring AMQ doorbells for idle agents"
+```
+
+### Available Plugin Actions
+
+```bash
+# Check queue status, active daemon, and unread mail per agent
+herdr plugin action invoke cabra.amq.bridge-status
+
+# Start background bridge daemon
+herdr plugin action invoke cabra.amq.bridge-start
+
+# Stop background bridge daemon
+herdr plugin action invoke cabra.amq.bridge-stop
+
+# Trigger an immediate one-shot doorbell check
+herdr plugin action invoke cabra.amq.doorbell-check
+
+# Launch the AGmail webmail dashboard
+herdr plugin action invoke cabra.amq.open-dashboard
+```
+
+### Herdr Terminal Panes
+
+Open modal terminal panes inside Herdr:
+
+```bash
+# Fast terminal inbox peek popup
+herdr plugin pane open --plugin cabra.amq --entrypoint inbox-popup
+
+# Dashboard server in dedicated pane
+herdr plugin pane open --plugin cabra.amq --entrypoint dashboard
+```
+
+---
+
+## CLI Reference (`herdr-amq`)
+
+The plugin ships an executable CLI dispatcher (`bin/herdr-amq.mjs`) used by both agents and operators:
+
+```bash
+# Start AGmail webmail dashboard (default: http://127.0.0.1:8505)
+herdr-amq dashboard
+
+# Start the continuous bridge daemon
+herdr-amq bridge-daemon
+
+# Messaging
+herdr-amq send --to spotter --subject "Check ADS alignment" --body @/tmp/prompt.txt
+herdr-amq reply --id 20260922-120000-001@swarm --body "Approved. Commit with explicit pathspec."
+herdr-amq drain --me coordinator
+
+# Decentralized Kanban Task Bus
+herdr-amq task list
+herdr-amq task claim TSK-402 --me worker-alpha
+herdr-amq task done TSK-402 --proof "Proof of Sabotage: INV-29 passed with non-zero exit on mutation"
+herdr-amq task block TSK-402 --reason "Waiting on asset import lock"
+
+# Print or install the agentic skill
+herdr-amq --skill
+herdr-amq --skill --install .opencode/skills/herdr-amq
+```
+
+---
+
+## Agentic Skill Integration
+
+AI coding agents (Antigravity, Claude Code, OpenCode, Aider) can consume the skill definition directly to learn the protocol without human instruction:
+
+```bash
+# Output full YAML-frontmattered SKILL.md
+herdr-amq --skill
+
+# Auto-install directly into your workspace
+herdr-amq --skill --install .opencode/skills/herdr-amq/SKILL.md
+```
+
+---
+
+## Security & Threat Model (Strictly Local-Only)
+
+> [!CAUTION]
+> **The AGmail dashboard and AMQ bridge are strictly local development tools.**
+> Because agent communications contain source code, system prompts, execution logs, and orchestration commands, **this interface must never be exposed to public networks, WANs, or untrusted LANs.**
+
+By design, `herdr-plugin-amq` implements strict defense-in-depth protections verified by continuous red-team exploit tests:
+
+* **Exclusive Loopback Binding**: The HTTP server strictly binds to `127.0.0.1` IPv4 loopback (dropping non-local external TCP requests at the OS level).
+* **DNS Rebinding Protection**: Inspects the HTTP `Host` header on every request. Any foreign domain (e.g. `attacker.com` pointing to 127.0.0.1) receives immediate `403 Forbidden`.
+* **Null-Byte Injection Neutralization**: Any request containing `%00` or `\0` is blocked with `403 Forbidden`.
+* **Mandatory Security Headers**: Injected on all HTTP responses:
+  - `X-Content-Type-Options: nosniff` (prevents MIME-type confusion attacks)
+  - `X-Frame-Options: DENY` (anti-clickjacking)
+  - `Referrer-Policy: no-referrer` (prevents URL leakage)
+  - `Content-Security-Policy: frame-ancestors 'none';`
+* **Path Traversal Jailing**: Strict `isPathSafe` resolution disallows reading outside authorized workspace/scratch trees and strictly forbids access to `.ssh`, `.env`, `/etc/passwd`, credentials, or `.git/config`.
+
+---
+
+## Testing & Quality Assurance
+
+Our test suite adheres to high-rigor standards with zero external test runners:
+
+```bash
+# Run 95 automated unit, integration, simulation & security tests
+npm test
+
+# Run red-team security penetration audit suite
+npm run test:security
+
+# Run tests with experimental coverage reporting (80%+ lines and functions)
+npm run test:coverage
+
+# Validate JavaScript module syntax across all files
+npm run check
+```
+
+Automated GitHub Actions CI validates compatibility across **Node 18.x, 20.x, and 22.x** on both **Ubuntu** and **macOS**, alongside a dedicated **Security Compliance & Red-Team Audit** workflow.
+
+---
+
+## License
+
+MIT © [Cabra](https://cabra.pw)

package/bin/herdr-amq.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import {
+  handleStatus,
+  handleStart,
+  handleStop,
+  handleDoorbell,
+  handleStartup,
+  handleAgentStatusChanged,
+  handleTaskCommand,
+  handleMailCommand,
+  handleSkillCommand,
+} from "../src/actions.mjs";
+import { startDaemonLoop } from "../src/bridge.mjs";
+import { launchDashboardPane, launchInboxPeekPane } from "../src/panes.mjs";
+
+const cmd = process.argv[2] || "status";
+
+switch (cmd) {
+  case "status":
+    handleStatus();
+    break;
+  case "start":
+    handleStart();
+    break;
+  case "stop":
+    handleStop();
+    break;
+  case "doorbell":
+    handleDoorbell();
+    break;
+  case "startup":
+    handleStartup();
+    break;
+  case "on-agent-status-changed":
+    handleAgentStatusChanged();
+    break;
+  case "bridge-daemon":
+    startDaemonLoop();
+    break;
+  case "dashboard":
+  case "server":
+  case "pane-dashboard":
+    launchDashboardPane();
+    break;
+  case "pane-inbox":
+    launchInboxPeekPane();
+    break;
+  case "task":
+  case "tasks":
+  case "board":
+    handleTaskCommand(process.argv[3], process.argv.slice(4));
+    break;
+  case "mail":
+    handleMailCommand(process.argv[3], process.argv.slice(4));
+    break;
+  case "send":
+    handleMailCommand("send", process.argv.slice(3));
+    break;
+  case "reply":
+    handleMailCommand("reply", process.argv.slice(3));
+    break;
+  case "drain":
+    handleMailCommand("drain", process.argv.slice(3));
+    break;
+  case "--skill":
+  case "-s":
+  case "skill":
+    handleSkillCommand(process.argv.slice(3));
+    break;
+  default:
+    console.error(`Unknown command: ${cmd}`);
+    console.log("Available commands: status, start, stop, doorbell, startup, pane-dashboard, pane-inbox, task, mail, send, reply, drain, --skill");
+    process.exit(1);
+}

package/herdr-plugin.toml

@@ -0,0 +1,57 @@
+id = "cabra.amq"
+name = "Herdr AMQ"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Agent Message Queue (AMQ) bridge daemon, mailbox monitor, and dashboard for Herdr"
+platforms = ["linux", "macos"]
+
+[[startup]]
+command = ["node", "bin/herdr-amq.mjs", "startup"]
+
+[[actions]]
+id = "bridge-status"
+title = "AMQ Bridge Status"
+contexts = ["workspace"]
+command = ["node", "bin/herdr-amq.mjs", "status"]
+
+[[actions]]
+id = "bridge-start"
+title = "Start AMQ Bridge Daemon"
+contexts = ["workspace"]
+command = ["node", "bin/herdr-amq.mjs", "start"]
+
+[[actions]]
+id = "bridge-stop"
+title = "Stop AMQ Bridge Daemon"
+contexts = ["workspace"]
+command = ["node", "bin/herdr-amq.mjs", "stop"]
+
+[[actions]]
+id = "doorbell-check"
+title = "Check AMQ Unread Mail and Ring Doorbells"
+contexts = ["workspace"]
+command = ["node", "bin/herdr-amq.mjs", "doorbell"]
+
+[[actions]]
+id = "open-dashboard"
+title = "Open AGmail Webmail Dashboard"
+contexts = ["workspace"]
+command = ["node", "bin/herdr-amq.mjs", "dashboard"]
+
+[[panes]]
+id = "dashboard"
+title = "AGmail Dashboard"
+placement = "overlay"
+command = ["node", "bin/herdr-amq.mjs", "pane-dashboard"]
+
+[[panes]]
+id = "inbox-popup"
+title = "AMQ Inbox Peek"
+placement = "popup"
+width = "80%"
+height = 24
+command = ["node", "bin/herdr-amq.mjs", "pane-inbox"]
+
+[[events]]
+on = "pane.agent_status_changed"
+command = ["node", "bin/herdr-amq.mjs", "on-agent-status-changed"]

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "herdr-plugin-amq",
+  "version": "0.1.2",
+  "description": "Herdr plugin for AMQ (Agent Message Queue) autonomous bridge, status monitoring, and AGmail dashboard",
+  "type": "module",
+  "main": "src/index.mjs",
+  "bin": {
+    "herdr-amq": "bin/herdr-amq.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "herdr-plugin.toml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:coverage": "mkdir -p coverage && node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=coverage/lcov.info test/*.test.mjs",
+    "check": "node --check bin/herdr-amq.mjs src/*.mjs test/*.test.mjs",
+    "test:security": "node --test test/security.test.mjs",
+    "coverage:summary": "node tools/coverage-summary.mjs",
+    "status": "node bin/herdr-amq.mjs status",
+    "start": "node bin/herdr-amq.mjs start",
+    "stop": "node bin/herdr-amq.mjs stop"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cabra-lat/herdr-plugin-amq.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cabra-lat/herdr-plugin-amq/issues"
+  },
+  "homepage": "https://github.com/cabra-lat/herdr-plugin-amq#readme",
+  "keywords": [
+    "herdr",
+    "herdr-plugin",
+    "amq",
+    "multi-agent",
+    "autonomous-agents",
+    "cas-blobstore",
+    "agmail"
+  ],
+  "author": "cabra.lat",
+  "license": "MIT"
+}

package/skills/herdr-amq/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: herdr-amq
+description: Autonomous coordination, inter-agent messaging, task claiming, and CAS blob attachments via AMQ Maildir and Herdr. Use when communicating between agents, claiming board tasks, sending reports with attachments, or inspecting the live AGmail dashboard.
+metadata:
+  short-description: AMQ Maildir & Herdr Multi-Agent Autonomous Coordination
+  compatibility: herdr, opencode, antigravity, claude-code, codex-cli
+---
+
+# Herdr AMQ Autonomous Coordination (`herdr-amq`)
+
+`herdr-amq` provides native multi-agent messaging, decentralized task tracking, and immutable Content-Addressed Storage (CAS) attachments over standard Maildir queues (`.agent-mail/`) without requiring external binaries.
+
+## Golden Rules for Agents
+
+1. **Drain First**: Whenever awakened by a doorbell notification or starting a turn, drain your inbox before taking action:
+   ```bash
+   herdr-amq mail drain --me <handle> --include-body
+   ```
+2. **Reply to the Sender**: Always reply to the sender on the same thread/ref chain. Never drop thread context:
+   ```bash
+   herdr-amq mail reply --me <handle> --id <msg_id> --body "..."
+   ```
+3. **Atomic Task Claiming**: Claim cards from the directory bus before modifying shared code:
+   ```bash
+   herdr-amq task list
+   herdr-amq task claim <task-id> --me <handle>
+   ```
+   When finished, complete with proof:
+   ```bash
+   herdr-amq task done <task-id> --proof "Tests passed (70/70), commit abc123"
+   ```
+   If blocked, flag with reason:
+   ```bash
+   herdr-amq task block <task-id> --reason "Waiting for schema migration"
+   ```
+4. **CAS Blob Attachments**: Use `--attach <path>` when sending logs, diffs, images, or test outputs. The file is automatically frozen into immutable Content-Addressed Storage (`.agent-mail/blobs/<sha256>`) and exposed via persistent HTTP URLs:
+   ```bash
+   herdr-amq mail send --me <handle> --to coordinator --subject "Test run output" --body "Attached full test logs" --attach /tmp/shooter/test.log
+   ```
+
+## CLI Reference
+
+### Inter-Agent Mail (`herdr-amq mail` or shortcuts `send`, `reply`, `drain`)
+
+| Command | Usage | Description |
+|---|---|---|
+| `drain` | `herdr-amq mail drain --me <handle> [--include-body]` | Atomic Maildir drain (moves `inbox/new` -> `inbox/cur`, marks seen) |
+| `send` | `herdr-amq mail send --to <handle> --subject <subj> --body <text\|@file> [--me <handle>] [--attach <path>]` | Send an RFC 5322 message with optional CAS attachment |
+| `reply` | `herdr-amq mail reply --id <msg_id> --body <text\|@file> [--me <handle>] [--attach <path>]` | Reply preserving `thread`, `in-reply-to`, and `references` |
+
+### Task Board & Bus (`herdr-amq task`)
+
+Operates against decentralized card files in `.opencode/bus/{backlog,doing,blocked,done}/`:
+
+| Command | Usage | Description |
+|---|---|---|
+| `list` | `herdr-amq task list [--json]` | List cards grouped by column |
+| `claim` | `herdr-amq task claim <task-id> --me <handle>` | Atomically moves card to `doing/<task-id>.md` and updates assignee |
+| `done` | `herdr-amq task done <task-id> --proof "<proof>"` | Moves card to `done/` with timestamp, proof, and duration |
+| `block` | `herdr-amq task block <task-id> --reason "<reason>"` | Moves card to `blocked/` with blocker reason |
+
+### Bridge, Dashboard & Status
+
+| Command | Usage | Description |
+|---|---|---|
+| `status` | `herdr-amq status` | Show bridge daemon status, unread counts per handle, and paths |
+| `doorbell` | `herdr-amq doorbell` | Run a single doorbell pass alerting idle/blocked agents |
+| `dashboard` | `herdr-amq dashboard [--port 8505]` | Launch web AGmail UI & REST API |
+| `--skill` | `herdr-amq --skill [--install [dir]]` | Print or install this agentic skill definition |