HAI-Relay

HAI-Relay is a local-first communication backbone for Codex, Claude, Cursor, Gemini, OpenCode, and Hermes. Each client receives one fixed identity through its MCP launch command and talks to one central Unix-socket daemon.

Current scope:

• passive, durable agent-to-agent messages;
• A2A-shaped threads, tasks, artifact references, acknowledgements, and audit events;
• mission/lease-gated task dispatch through a fail-closed HAI-MCP authority port;
• ACP dispatch through the official Python ACP client SDK (runtime import isolated);
• SQLite persistence, restart recovery, idempotency, 64 KiB payloads, 14-day retention, and a maximum hop count of three;
• read-only/advisory execution by default; state-changing tasks require guarded Claude authority.

HAI-MCP has no callable production authority implementation yet. Tasks fail closed unless an external authority adapter is configured. The relay does not claim live HAI-MCP integration.

Separate gates

Gate	Status in this repository
Core relay package (socket, store, seven MCP tools, policy)	Implemented
Global client MCP registrations	Not included — requires separate owner approval
Live six-agent ACP smoke tests	Not included — worked_live stays false until bounded adapter proofs exist

hai-relay --version reports package metadata only; it is not live ACP proof.

Local development

uv sync
uv run pytest
uv run ruff check .
uv run mypy src

Start the daemon:

uv run hai-relay serve \
  --state-dir /tmp/hai-relay-state \
  --socket /tmp/hai-relay.sock

Start one identity-bound MCP facade:

uv run hai-relay-mcp --agent codex --socket /tmp/hai-relay.sock

Without --authority-command, passive messages work and every task fails closed. An authority adapter must accept one JSON document on stdin and return:

{"allowed": true, "assurance": "advisory", "reason": "active mission and lease"}

state_changing additionally requires target claude and assurance guarded. ACP permission requests are denied by the relay client; guarded filesystem/tool execution belongs to the maintained HAI-MCP host adapter.

Registered agents

Agent	Adapter command	Mode
Codex	codex-acp	advisory
Claude	claude-code-acp	guarded
Cursor	cursor-agent acp	advisory
Gemini	gemini --acp	advisory
OpenCode	opencode acp	advisory
Hermes	hermes acp	advisory

Health reports configured, enabled, and worked_live separately.

MCP tools

1. relay_health
2. relay_list_agents
3. relay_send_message
4. relay_read_inbox
5. relay_get_thread
6. relay_ack_message
7. relay_cancel_task

No tool accepts from_agent; identity is fixed at MCP process launch.