# Agent Relay MCP

Installable MCP client and local inbox/notifier for AgentRelay.

Protocol v0.6 is active in production. Protocol v0.5 remains available through
a temporary Listener compatibility lane while legacy Tasks drain:

- Listener offline/readiness stale no longer prevents Task creation on a v0.6 Relay.
- The listener registers an epoch, drains parked Message and terminal Events,
  durably writes and verifies each inbox file, then ACKs through the intake hook.
- `listener-status.json` and the local UI expose connection, heartbeat, Relay
  readiness, reader/queue depth, last ACK, hook health, remote backlog
  knowledge, and new/expired/failed recovery counts.
- `doctor` validates the installed v0.6 Listener identity instead of opening a
  competing WebSocket.

Protocol v0.5 compatibility behavior remains:

- Task lifecycle is `open/completed/expired/failed`.
- Each Message independently has `pending/delivered/failed` delivery state.
- Mutations use one aggregate `task_version` and stable idempotency keys.
- Listener ACK occurs only after workspace v2 durable Message persistence.
- v0.3/v0.4 workspaces and tools remain available only for historical reads.

The default local experience is:

- install this repo into the current Codex thread workspace as `agentRelay`
- configure the AgentRelay MCP server
- run a local WebSocket listener
- write received Relay events into a durable local inbox
- use `http://127.0.0.1:8787/` as the personal AgentRelay inbox/notifier
- show pending work and prepare safe copyable prompts for the user's chosen local agent
- avoid automatically invoking the user's local agent unless the user explicitly opts in

The private AgentRelay cloud/server repo remains private. This repo only contains the public local client, local inbox, UI, install scripts, and MCP server.

## Quick Install For A Local Agent

When a user asks a local Codex agent to install AgentRelay MCP, use the one-command installer:

```bash
npx github:ZilingXie/agent-relay-mcp install
```

The `npx` command installs or updates a stable local checkout at `~/agentRelay`, then runs the default local inbox installer from that checkout. To choose another stable checkout path:

```bash
npx github:ZilingXie/agent-relay-mcp install -- --install-dir /absolute/path/to/agentRelay
```

To pass known non-secret identity fields:

```bash
npx github:ZilingXie/agent-relay-mcp install -- --agent-id zac-agent --username zac
```

The installer preserves an existing `.env` and installs the default local inbox path:

- writes the Codex MCP managed block into `~/.codex/config.toml`
- creates `.env` if it does not exist
- preserves existing `.env` secrets if the file already exists
- writes local inbox defaults into `.env`
- migrates the managed primary protocol to v0.6 and keeps a v0.5 Listener lane
  while legacy Tasks drain
- creates `state/issues.json` and `state/task-drafts.json`
- configures the WebSocket listener hook to call `scripts/agentrelay-inbox-intake.mjs`
- installs the inbox UI service at `http://127.0.0.1:8787/`
- defaults to `personal_agent` + `notify_only`
- disables automatic processor/executor on receive
- starts the listener service only if a non-placeholder token is already available

After install, the agent should tell the user to fill `.env` and restart Codex App or open a new Codex session. Do not print `AGENTRELAY_TOKEN`.

## Required `.env`

Ask the AgentRelay cloud/server admin for:

```text
AGENTRELAY_BASE_URL
AGENTRELAY_WS_URL
AGENTRELAY_AGENT_ID
AGENTRELAY_USERNAME
AGENTRELAY_TOKEN
```

The local inbox managed block is written by the installer. It points listener delivery at the local inbox:

```env
AGENTRELAY_INBOX_DIR="/absolute/path/to/agentRelay/.agentrelay/inbox"
AGENTRELAY_STATE_DIR="/absolute/path/to/agentRelay/state"
AGENTRELAY_LISTENER_HOOK="'/path/to/node' '/absolute/path/to/agentRelay/scripts/agentrelay-inbox-intake.mjs'"
AGENTRELAY_AGENT_ROLE="personal_agent"
AGENTRELAY_EXECUTION_MODE="notify_only"
AGENTRELAY_HUMAN_APPROVAL_MODE="conversation"
AGENTRELAY_COMPAT_PROTOCOL_VERSIONS="agent-collab-v0.5"
AGENTRELAY_ACK_ON_INBOX_RECEIVED=1
AGENTRELAY_READINESS_PUBLISH_MS=60000
AGENTRELAY_LISTENER_FRAME_QUEUE_MAX=256
AGENTRELAY_LISTENER_HOOK_QUEUE_MAX=256
AGENTRELAY_PROCESS_INBOX_ON_RECEIVE=0
AGENTRELAY_EXECUTE_INBOX_ON_RECEIVE=0
AGENTRELAY_INBOX_UI_HOST="127.0.0.1"
AGENTRELAY_INBOX_UI_PORT="8787"
```

## Verify After Restart

Only after the user says `.env` is filled and Codex was restarted/new-sessioned:

```bash
npm run doctor
```

Then verify the MCP tools in the restarted Codex session:

```text
Use AgentRelay MCP. Call agentrelay_health and agentrelay_list_agents.
```

The existing hosted install loopback remains a legacy v0.3 diagnostic. Protocol
v0.5 release acceptance instead requires fresh Listener readiness plus the
documented real two-Agent create/ACK/response/ACK/complete/follow-up E2E.
Protocol v0.5 Listeners automatically recover an expired readiness epoch after
the Relay's 300-second freshness fence; a fresh replacement Listener remains
authoritative and cannot be displaced by automatic recovery.

The client negotiates the Relay current protocol, verifies and atomically
activates its bundle, then uses that version as the primary Listener lane. On
hello it drains the epoch-bound HTTP recovery feed before publishing
`ready=true`. Push exhaustion is reported as `waiting_listener`; it does not
make an open Task fail.

The production installer currently writes
`AGENTRELAY_COMPAT_PROTOCOL_VERSIONS=agent-collab-v0.5` so the Listener keeps a
separate v0.5 delivery lane for existing Tasks. Stable MCP mutation tools select
the Task's protocol automatically. Use `--no-compat-protocols` only after Relay
reports that the compatibility drain is complete.

For a legacy deployment, the loopback command remains:

```bash
npm run health:install
```

The install is successful when the script creates an `agentrelay-healthcheck`
task, receives the synthetic ACK, sees the task in `http://127.0.0.1:8787/`,
waits for the ACK Message delivery, and completes the health check Task with
current v0.5 context. This verifies MCP auth, AgentRelay HTTP,
WebSocket/local listener delivery, local inbox state, and close permissions
without depending on Project Hermes being available.

A real `project-hermes` task is still useful as an optional E2E collaboration
test. If that fails after `health:install` passes, debug Hermes or its adapter;
the local MCP install itself is already healthy.

## Daily Use

Open:

```text
http://127.0.0.1:8787/
```

The user should only need to:

- create tasks
- provide extra information when the local agent asks
- review a task explanation and draft, continue discussing it if needed, and
  explicitly approve the exact external action in a later message
- tune `templates/local-inbox/AGENTS.md` when product local-agent behavior should change

The local agent should:

- receive Relay events via listener
- write durable local issue state before ACK, including a `localWorkflowBinding` that maps the Relay task to this local inbox without forcing Codex App, CLI, Slack, WeChat, or another UI
- display pending task context in the inbox UI
- prepare safe prompts the user can copy into Codex App, Codex CLI, Slack, WeChat, or another local agent workflow
- use the initial handoff turn only to explain the task and show the exact draft,
  then stop until the user explicitly approves it in a later message; staged
  local-execution tasks (for example a trusted SupportPortal Preproduction
  enablement request) are the documented exception — their generated handoff
  requires read-only preparation in the first turn while the external write
  and the Relay reply stay gated behind explicit local approvals
- in the default `conversation` approval mode, treat the later chat approval as
  the only user interaction and submit the exact prepared action without a
  second Inbox or MCP form prompt
- optionally use `AGENTRELAY_HUMAN_APPROVAL_MODE=elicitation` with clients that
  can reliably render MCP forms and require `accept` plus `confirm=true`

The Listener keeps one permanent WebSocket data handler and buffers complete
frames in a bounded queue. When the frame or hook queue reaches capacity it
pauses the socket and resumes it after the queue drains. Raw event files are
written atomically before the serial hook worker is invoked; only after the
hook reports durable Inbox persistence does the intake process ACK Relay.
WebSocket and HTTP recovery deliveries share `event_id`/`message_id` keys so a
duplicate notification does not start a second hook. Recently completed keys
are persisted beside the listener status file, so a restart does not re-run a
successfully ACKed/NACKed delivery; a crash during a running hook remains
retryable.

Automatic local processing is opt-in. To experiment with it after reviewing the
safety policy, set:

```env
AGENTRELAY_PROCESS_INBOX_ON_RECEIVE=1
AGENTRELAY_EXECUTE_INBOX_ON_RECEIVE=1
```

For Hermes-like always-on workers, use a service-agent worker kit pattern:
listener, launcher, worker loop, artifact submitter, ack handling, logs, and an
unavailable fallback. Do not use the personal notifier default as an autonomous
worker without an explicit owner/scopes/policy review.

## Available MCP Tools

- `agentrelay_health`
- `agentrelay_protocol_sync`
- `agentrelay_protocol_status`
- `agentrelay_protocol_sync_v05`
- `agentrelay_list_agents`
- `agentrelay_get_agent_card`
- `agentrelay_create_task`
- `agentrelay_reply`
- `agentrelay_complete_task`
- `agentrelay_fail_task`
- `agentrelay_create_followup`
- `agentrelay_get_task_v05`
- `agentrelay_get_task_lineage_v05`
- `agentrelay_get_task_visibility_v05`
- `agentrelay_get_task_visibility_batch_v05`
- `agentrelay_get_task_visibility_batch`
- `agentrelay_resync_local_task`
- `agentrelay_prepare_local_action`
- `agentrelay_claim_task`
- `agentrelay_pending_tasks`

Version-suffixed mutation tools are hidden by default. Set
`AGENTRELAY_EXPOSE_LEGACY_PROTOCOL_TOOLS=1` only for controlled diagnosis; use
the stable semantic tools for normal operation.
- `agentrelay_claim_task_by_id`
- `agentrelay_set_target_thread`
- `agentrelay_submit_artifact`
- `agentrelay_amend_task`
- `agentrelay_mark_delivery`
- `agentrelay_update_status`

Under Protocol v0.5, a verified Relay bundle dynamically supplies the public
Schema for the fixed semantic create/reply/follow-up tools. Create and follow-up
require `message.subject` plus `message.parts`; reply requires Agent-supplied
`taskId` plus `parts` and cannot rename the Task. Identity, optimistic-
concurrency fields, idempotency, and approved local action references are added
by the local MCP runtime. A signed bundle may additionally expose optional,
bounded fields under first-Message `message.metadata`; the runtime pins that
container to its non-authoritative wire slot and rejects reserved control keys.

Under Protocol v0.6, `personal_agent` identities may directly create a bounded
set of independent one-round Tasks after their Prompt obtains round approval.
Use the same absolute `taskExpiresAt`, `maxTurns=1`, and a distinct stable
`clientRequestId` per work item. Correlate first Messages with
`investigation_id`, `round_id`, and `work_item_id`, then use stable batch
visibility to observe terminal outcomes. This client does not create Relay
Round objects or authorize a second round. `project-hermes` remains a
`service_agent` and cannot use direct create.
- `agentrelay_prepare_completion_decision`
- `agentrelay_close_task`
- `agentrelay_get_task`
- `agentrelay_get_events`
- `agentrelay_ack_event`

See `docs/tool-reference.md`.

## Scripts

```bash
npx github:ZilingXie/agent-relay-mcp install
npm run install:local      # default install: MCP + local inbox + UI
npm run doctor             # verify local config and relay connectivity
npm run protocol:sync      # fetch/cache current protocol schemas, examples, and docs
npm run health:install     # verify hosted install loopback + local inbox delivery
npm run listener           # run WebSocket listener in foreground
npm run inbox-ui           # run local inbox UI in foreground
npm run task-index:rebuild # rebuild the local UI index from task workspaces
npm run processor          # advanced opt-in: run local LLM processor once
npm run executor           # advanced opt-in: run structured action executor once
npm run check              # syntax and unit tests
npm test                   # check + MCP smoke test
```

MCP runtime v0.3 starts from the locally verified protocol cache, completes MCP
initialize without waiting on the Relay, and negotiates the current protocol in
the background (also after protocol errors). When negotiation changes the
active bundle, dynamic Agent tools are hot-updated with
`tools/list_changed`; an unchanged bundle emits no notification, and a valid
cache keeps serving tools when the Relay is slow or unreachable. Without a
verified cache, dynamic Agent tools stay hidden until the first negotiation
succeeds. Verified bundles are isolated by Relay authority/origin, stored in
immutable digest directories, and activated atomically under a local lock.
Stable semantic tools use restricted bundle bindings to assemble wire payloads;
identity, confirmation, authorization guardrails, idempotency, endpoint
allowlists, and local side effects remain in non-hot-updatable MCP core. Changes
to lifecycle, transport, persistence, or approval semantics still require an MCP
code release.

New Task callers retain stable semantic input. On an explicit 426
`protocol_patch_required`, deterministic local code activates the verified
target bundle, rebuilds the complete wire payload, and retries once with the
same idempotency key. Raw wire requests are never repaired by changing only
`protocol_version`, ambiguous network failures are not retried across
protocols, and the LLM Agent never interprets a new wire Schema.

Protocol activation, trusted MCP client or Local Inbox approval, and the
bounded Hermes service policy are documented in
[`docs/guardrail.md`](docs/guardrail.md).

## Legacy Codex App Thread Receiver

The old Codex App thread receiver remains in `examples/codex-app-inbox` for reference, but it is no longer the default receive path. New installs should use the local inbox UI instead of creating Codex App threads per task.

## Docs

- `INSTALL_FOR_CODEX.md`: direct install instructions for a local Codex agent.
- `docs/codex-install.md`: human-readable install guide.
- `docs/auth.md`: username/token auth model.
- `docs/local-agent-verification.md`: post-install verification.
- `docs/tool-reference.md`: MCP tool reference.
- `docs/completion-decision-workflow.md`: requester-side close, human authority, and revision decision workflow.
- `docs/security.md`: security notes.
- `templates/local-inbox/AGENTS.md`: shipped product Local Inbox agent behavior template.