# Architecture

```text
Codex ─┐
Claude ┤
Cursor ┤  identity-bound MCP stdio facades
Gemini ┤                │
OpenCode ┤              ▼
Hermes ─┘        Unix socket (0600)
                      │
               HAI-Relay daemon
             ┌────────┼─────────┐
             ▼        ▼         ▼
          SQLite   HAI-MCP    ACP target
          + audit  authority   process
```

The relay is a transport and evidence boundary, not an authority. Passive
messages are stored without starting the recipient. Task envelopes require a
mission ID and lease ID, and the authority port must allow them before the ACP
dispatcher starts a process.

The internal envelope borrows A2A concepts—agent identity, message, task,
thread/context, artifact references, lifecycle state—without exposing a network
A2A server in v1.

## Trust boundaries

- The MCP facade fixes the caller identity at process launch. No public tool has
  a `from_agent` field.
- The Unix socket is local and owner-only (`0600`). Same-user malicious
  processes remain outside the v1 threat model.
- Authority errors and absence fail closed for tasks.
- `state_changing` requires both target Claude and `guarded` assurance.
- The ACP client denies permission requests. Host-action authorization remains
  the responsibility of HAI-MCP's maintained guarded adapter.
- No chain-of-thought, transcript mirroring, broadcast, or automatic memory/KG
  ingestion is implemented.

## HAI-MCP authority port

HAI-Relay calls an optional subprocess authority adapter with a JSON request
describing mission, lease, caller, target, and operation mode. When no adapter
is configured, or when the adapter is unavailable, tasks are blocked with a
stable error code. The relay does not embed HAI-MCP or claim live integration.

## Health dimensions

Agent registry entries expose three independent signals:

- **configured**: adapter binary exists on PATH
- **enabled**: policy permits use (always true for core six in v1)
- **worked_live**: bounded real invocation succeeded recently (false until live gate)

These must never be collapsed into a single green indicator.

## Out of scope (v1)

- Global MCP/client configuration changes
- Broadcast and group autonomy
- Public A2A HTTP endpoint
- Automatic Knowledge Graph or memory ingestion
- State-changing execution on agents other than guarded Claude