Agent Federation Platform

Bring your own host agent, we provide the federation.

中文版 README 见 README.zh-CN.md

⚠️ AI-GENERATED CODE NOTICE: All code in this repository was generated by DeepSeek AI models and has NOT undergone human review. Use at your own risk. Review critical paths (security, permissions, file operations) before deployment.

⚠️ CORE-PATCH NOTICE (read before installing): One optional component — hermes-side/hermes-external-event-steer.patch — modifies Hermes core source (cli.py + hermes_cli/config_defaults.py) to add an "auto-pop External Notification" enhancement. This patch is OPTIONAL and OFF by default:

• Without the patch, the core pipeline works 100% (task dispatch → DSH executes → results written back to the board). You just check results with hermes kanban --board dsh show <id> instead of getting an auto-popup.
• The patch is version-sensitive: it targets a specific Hermes release. If git apply fails (version drift), skip it — the pipeline still works; only the auto-popup is missing.
• install.sh will not fail if the patch can't apply — it warns and continues.
• See "What needs the core patch?" below for exactly what the patch does and what doesn't.

📋 License & attribution: MIT. Code adapted from DeepSeek Harness, Hermes Agent, and dsh-harness-mcp-server (all MIT) — see NOTICE-借鉴与合规.md. Related project: Ericwong5021/dsh-kanban (similar name, different type: React UI kanban vs our background executor).

English README below. This repository currently ships a dual-agent pipeline (Hermes orchestrates, DSH executes via a kanban queue) and grows toward an agent federation: any AI coding agent joins through the same queue, cross-reviews each other's work, and deliberates through a tiered debate protocol — with you as the final decision-maker.

Motivation

A single agent working alone is bounded by its own model: biases uncorrected, blind spots unfilled, hard problems reasoned through only from one perspective. The value of multi-agent collaboration is precisely this — heterogeneous agents reviewing each other can correct the self-confirmation bias of a single agent (validated by the MAD paper).

The project's current form is two agents collaborating: Hermes and DSH. Hermes writes tasks into a kanban queue, DSH claims and executes them in its Web GUI, writes results back to the board, and notifies Hermes on completion. The full chain has been validated in practice: a reliable task state machine (claims are locked — the same task cannot be executed twice; tasks recover after crashes), fully unattended operation (trigger-file event driving plus permission presets), persistent sessions you can revisit, automatic completion notifications, cross-task session inheritance, and basic cross-review (one party produces, another independently reviews).

But the pipeline has two unresolved problems:

1. Execution is locked to a single agent type. Adding Codex means writing another watcher — every new agent adds linear cost.
2. There is no negotiation channel. Board comments are asynchronous notes, not structured round-based deliberation — opinions cannot iterate or converge.

There is also a principled ceiling: the false consensus of two-plate mutual grinding.

In precision machining, standard flat surfaces are made by scraping. Two plates ground against each other can never yield a high-precision plane: if one is convex and the other concave, they will mate perfectly — yet neither is flat; the error is not removed, it is mutually adapted. Three plates ground in a closed loop (A against B, B against C, C against A) are required: any convexity on one plate is exposed by the other two, and after cycles all three converge toward a true plane.

Two-agent cross-review is two-plate grinding. Hermes reviews DSH and DSH reviews Hermes — two agents can validate each other's blind spots and reach a conclusion that is "consistent yet wrong": they did not find the correct answer, they adapted to each other's errors. Breaking false consensus requires a closed loop: at least three parties reviewing in a cycle (A reviews B, B reviews C, C reviews A), so any single point of error is caught by a third party that does not share its bias.

This is the deeper reason for a federation. Not one more agent doing work — a closed loop that forces "consensus" through three-way validation, leaving errors nowhere to hide. Heterogeneity (cross-model pairing) lowers the probability of shared blind spots; closure (three-way cycling) removes the freedom of false consensus — both matter, closure is the essence.

Others are pursuing similar directions, validating the path:

• win4r/team-tasks: a debate mode (round → collect → cross-review → synthesize) nearly identical to the deliberation protocol we plan — the protocol is implementable.
• Skytliang/Multi-Agents-Debate (MAD): the paper shows multi-agent debate corrects single-agent bias, rigidity, and blind spots — the motivation holds.
• thunlp/ChatEval: multi-agent debate for LLM evaluation — supporting evidence.
• omnigent-ai/omnigent: a meta-harness mixing Claude Code, Codex, Cursor, Hermes in one session, "ask one agent to review another's work" — arbitrary mixing works.
• Detrol/quorum-cli: a multi-model debate CLI with seven discussion methods — debate interaction is already productized.
• majiayu000/harness: a Rust control plane orchestrating Claude Code/Codex fleets with policy and review — the review layer can be engineered.
• Happenmass/omux: tmux-based orchestration of parallel CLI coding agents — parallel execution can run unattended.

But none of them combine all three things we consider core: a persisted queue with a hard state machine (kanban), deliberately heterogeneous execution (cross-model pairing), and a human-gated final decision. We borrow their proven protocols and build the record surface ourselves. That is why this repository exists.

For the full argument behind this motivation, see the article: Where Should Coding Agent Go Next? — Why We Need a Multi-Agent Discussion Architecture (original in Chinese: Coding Agent 的下一步要怎么走). It develops the motivation in full, critiques its own assumptions, and specifies the conditions under which the architecture actually holds.

Overview

Agent Federation Platform is a generic multi-agent collaboration layer. It federates any AI coding agents through a shared kanban queue, lets them cross-review each other's work, and runs tiered multi-agent debate for high-stakes decisions — always with a human in the loop. It is orchestrator-agnostic: bring your own host agent (the reference deployment uses Hermes), we provide the federation machinery.

Core capabilities:

• Shared queue: kanban task state machine — claims are locked, crash-recoverable, fully audited.
• Cross-review: one party produces, another independently reviews; implementation and review are always separated.
• Tiered debate: direct execution / dual-model cross-review / full debate, gated by task value.
• Human final say: any unified recommendation is only a recommendation — it executes after your confirmation.

When to use this

• You run Hermes Agent and DSH (DeepSeek Harness) on the same machine
• You want DSH's Web GUI sessions to automatically execute tasks dispatched by Hermes (instead of manually opening a conversation in the GUI every time)
• You want a task queue: Hermes writes tasks into a kanban board, a DSH watcher claims and executes them serially
• You want completion notifications: when DSH finishes a task, it pops up automatically in your Hermes session — no polling required

Not for: single-agent setups (one agent has nothing to collaborate with), or cross-machine distributed setups (this pipeline assumes one machine with a shared filesystem).

Architecture

┌─────────────┐    kanban board (SQLite)    ┌──────────────────┐
│   Hermes    │  ────────────────────────→  │   DSH Web GUI    │
│  (CLI/etc)  │  hermes kanban create       │  (dsh web :3080) │
└─────┬───────┘                             └────────┬─────────┘
      │  /dsh-send skill                             │  watcher plugin
      │                                              │  claim → run → write-back
      │  ~/.dsh/kanban-trigger/<id>.trigger          │
      └─────────────────────── event-driven wake ────┘
                                                  │
      ~/.dsh/kanban-done/<id>.done  ←─────────────┘  writeDoneFile()
      │
      ▼
  Hermes idle loop _drain_done_notifications()
      → session auto-pops 【外部通知】task completed

Four key mechanisms:

1. Kanban queue: task state machine (ready → running → done/blocked), persisted in SQLite, crash-recoverable
2. Event-driven wake-up: Hermes writes a trigger file, the watcher's fs.watch responds immediately (+30s fallback polling)
3. Output whitelist: output is only allowed into whitelisted dirs (default $DSH_WORKSPACE, desktop), preventing privilege escalation writes
4. Completion notification: watcher writes a done file → Hermes session notices it automatically, no polling

Repository layout

├── dsh-side/          DSH-side components (maintained by DSH)
│   ├── plugins/dsh-kanban-watcher/   kanban watcher plugin source + README
│   ├── hermes-side/                  Hermes-side skill source (dsh-send SKILL.md) — mirror of hermes-side/dsh-send-skill/
│   ├── docs/                         capability survey & collaboration feasibility
│   └── scripts/                      session decompress/extract/comment tools + restart script
└── hermes-side/      Hermes-side changes (maintained by Hermes)
    ├── hermes-external-event-steer.patch   source diff (104 lines)
    ├── dsh-send-skill/                /dsh-send skill — mirror of dsh-side/hermes-side/dsh-send/
    ├── dsh-web.service                systemd service file (TEMPLATE — edit placeholders before use)
    ├── PR-提交说明.md                  material for filing a Hermes issue
    └── README.md                      usage doc

What needs the core patch?

Capability	Needs the core patch?	How it works without the patch
Dispatch tasks to DSH (/dsh-send)	❌ No	Pure Hermes skill + kanban CLI — always works
DSH executes in Web GUI, writes back to board	❌ No	The watcher plugin does this — always works
Results visible (hermes kanban --board dsh show <id>, /inbox)	❌ No	Board comments — always works
DSH writes done files (~/.dsh/kanban-done/)	❌ No	Watcher plugin feature — always works
Hermes CLI auto-pops 【外部通知】 on completion	✅ Yes	Manually check the board instead

Bottom line: the core patch only adds the last row (auto-popup). Everything else is plugin/skill/config-level and works on any Hermes version. If you skip the patch, you lose the auto-popup but nothing else.

Quick start

📖 New-user zero-to-install guide: INSTALL.md (kanban init, plugin mount, skill deploy, verification, known pitfalls)

🤖 AI Agent users (another Hermes/DSH/Claude Code instance): just run ./install.sh --yes — fully automatic, idempotent, re-runnable. It auto-detects paths, skips completed steps, and exits 2 with fix hints when prerequisites are missing. Pre-flight with ./install.sh --dry-run. Ensure the DSH web profile is initialized first (dsh web --port 3080 once).

Prerequisites: Hermes Agent + DSH (npm global @deepseek-ai/dsh) installed on the same machine, sharing ~/.dsh.

# 0. Clone this repository first (--recurse-submodules pulls the dsh-kanban-watcher plugin submodule)
git clone --recurse-submodules <your-repo-url> && cd <repo-dir>

# 1. DSH side: install the watcher plugin + start web
cd ~/.dsh/profiles/web
pnpm add file:<repo-dir>/dsh-side/plugins/dsh-kanban-watcher
systemctl --user enable --now dsh-web.service   # or manually: dsh web --port 3080
# (dsh-web.service is a template — edit the <DSH_BIN>/<NPM_PREFIX> placeholders first)

# 2. Hermes side: apply the patch + enable the feature
cd ~/.hermes/hermes-agent
git apply <repo-dir>/hermes-side/hermes-external-event-steer.patch
hermes config set features.external_event_steer true
# restart the Hermes CLI session

# 3. Dispatch a task
# in your Hermes session:
/dsh-send analyze this week's trading data and write a report to the DSH workspace

# 4. Completion notification pops up automatically
# 【外部通知】task t_xxxx「analyze this week's trading data」completed. Result: ...

Usage examples

# Dispatch with a model (note: plugin modelMap only maps flash + __fallback__,
# so a model outside the map (e.g. pro) falls back to flash)
/dsh-send --model deepseek-v4-flash write a scraper for HLTV data

# Dispatch with a skill (copy a Hermes skill to the shared area for DSH to reference)
/dsh-send --skill two-step-t1-dip-buy-strategy analyze the current market with this strategy

# Session inheritance (continue a previous conversation's context, new in v0.2.0)
/dsh-send --resume keep-discussing-X analyze the conclusion from before

# Specify a working directory
/dsh-send --workspace dir:$DSH_WORKSPACE/weekly-reports write this week's report

# View the queue
/inbox

Design principles (cross-agent review gate)

• Territory-based division of labor: whoever owns the environment owns the work — DSH-related code is written by DSH, Hermes-related by Hermes; after the implementer produces output, the other agent independently reviews it (security / error handling / scope / dependency compatibility)
• Mutual restart: Hermes restarts DSH and DSH restarts Hermes; a task to restart the other process must never go into the board for the watcher to self-execute (the watcher runs inside the DSH host — killing the host kills the executor)
• Output whitelist: Hermes side is the single source of truth; the DSH watcher's permission preset mirrors the same whitelist
• The user is the final merge approver: review comments are answered one by one (fixed or explained why not), the user decides

Known limitations

• The watcher executes tasks serially (one at a time, later tasks queue)
• 30s fallback polling + fs.watch: near-real-time, not real-time
• SQLite multi-process writes have lock contention (busy_timeout + retry fallback)
• External event injection only works in Hermes CLI sessions, not gateway platforms
• After plugin code updates, restart dsh web for the change to take effect (node does not hot-reload)

(The watcher falls back to 30s polling when fs.watch events are coalesced/lost.)

Why not an off-the-shelf solution

• Community MCP server (dsh-harness-mcp-server) not used: its dependency ^0.0.1-rc.1 does not match DSH profile 0.1.0-rc.6 (singleton-conflict risk), its task queue is in-memory (lost on restart), and sessions are reused per cwd (not per task). This project's kanban board is a persisted queue that fills those gaps.
• Transitional positioning: this pipeline is expected to last until DSH ships a mature ACP/JSON-RPC cross-agent task protocol; then the watcher can be swapped while keeping the board and skill layers.
• Deployment note: Hermes gateway ships its own kanban watcher — do NOT enable the Hermes dispatcher on board dsh (it would race the DSH watcher). The board/assignee isolation design already avoids the conflict.

Path variables

Repository code and docs are sanitized: real machine paths appear as $VAR placeholders. Replace them with your own paths when deploying:

Variable	Meaning	Example
$HOME / $USER	home directory / username	/home/alice / alice
$DSH_WORKSPACE	DSH workspace (default task dir)	/home/alice/DSH
$DSH_HOME	DSH data dir	~/.dsh
$DSH_TRIGGER_DIR	kanban trigger file dir	~/.dsh/kanban-trigger
$DSH_DONE_DIR	done file dir (completion notices)	~/.dsh/kanban-done
$DSH_SESSIONS	DSH session archive dir	~/.dsh/sessions
$DSH_WEB_PROFILE	DSH web profile dir	~/.dsh/profiles/web
$DSH_BIN	dsh executable	/home/alice/.hermes/node/bin/dsh
$HERMES_HOME	Hermes data/source dir	~/.hermes
$HERMES_BIN	hermes CLI executable	~/.local/bin/hermes
$HERMES_BIN_DIR	hermes CLI dir	~/.local/bin
$NPM_PREFIX	npm global prefix	~/.hermes/node
$HERMES_VENV_PYTHON	Hermes venv Python	~/.hermes/hermes-agent/venv/bin/python
$DESKTOP	Windows desktop	/mnt/c/Users/xxx/Desktop
$WIN_USERNAME	Windows username	alice
$HOSTNAME	machine hostname	myhost

Docs

• CHANGELOG.md — release notes (version history + what's new)
• INSTALL.md — full zero-to-install guide + known pitfalls (中文版: INSTALL-安装指南.md)
• dsh-side/docs/DSH-Hermes双Agent协作管道-能力盘点与可行性.md — project origin (DSH capability survey + collaboration feasibility)
• dsh-side/plugins/dsh-kanban-watcher/README.md — watcher plugin detailed docs (config/usage/security)
• hermes-side/README.md — external_event_steer internals & security design (done-file untrusted input, seen baseline)
• hermes-side/PR-提交说明.md — material for filing an issue with Hermes Agent

Vision

Roadmap from the current dual-agent pipeline to full federation:

• P0 — Generic drivers: refactor dsh-kanban-watcher into a driver interface (claim → execute → report) so any agent joins via one driver file (DSH, Codex, Claude Code, custom).
• P1 — Debate state machine on kanban: round → collect positions → cross-review → synthesize, adopted from win4r/team-tasks.
• P2 — Tiered deliberation: direct execution / dual-model cross-review / full debate, gated by task value; model routing + driver registry.
• P3 — Kanban board visualization panel: show task state, model, duration, dependencies and debate rounds in the DSH Web GUI.