EVEX Agent Messaging Gateway

Provider-neutral MCP transport for Parent Main, Child Main, and Role Child conversation operations. Agents call this MCP; they do not call OpenHands' Conversation API directly.

Tools

• create_child: validate the complete structured Mission and the clean deterministic Git checkout, bind Child identity plus callback capability, then create one deterministic Conversation. The provider runs one tool-free admission turn, restores and revalidates the exact branch/head after ACP bootstrap, and only then admits tools and delivers the Mission. No Conversation API call occurs when checkout authority is missing or mismatched. Source roles receive only Messaging; only explicit QA/repair Missions may request capabilities: ["runtime_environment"].

• send_to_parent: deliver a structured RESULT/NEEDS_INPUT to the capability's owning Main.

• request_user_decision: deliver an A/B/C-style question to the owning Main.

• cancel_mission / resume_mission: stop or resume the exact Child task.

• publish_navigation_links: publish informational Issue/Main/Child/PR links to the owning Main.

Capabilities are compact opaque evx1_ HMAC-SHA256 references. They bind the owning Main, Child, task key, role, allowed action, and expiry. The server holds the OpenHands credential; it never appears in tool input, tool output, or child environment variables. There is no persistent state: callers provide a stable message key and the Main deduplicates semantic replays.

Each created Child receives an asynchronous native Stop hook. The hook calls the private /completion-hook endpoint with its scoped reference; the gateway waits for terminal native state and sends one stable RECOVERY_WAKE containing the bounded terminal assistant response to the owning Main. This is the provider-neutral fallback when a model finishes without calling send_to_parent. Repeated hooks reuse the same semantic message key and do not require a database, poller, read tool, or receipt store.

The trusted Event Gateway/host mints the short-lived Main capability with main_capability_token(...) and injects it into the Main Mission. The MCP does not expose a capability minting tool to agents.

The Parent creates or fetches only the persistent bare mirror at /home/openhands/workspace/mirrors/<owner>--<repository>.git. create_child derives /home/openhands/workspace/delivery/child-<child UUID>, creates the exact branch worktree when absent, and validates repository, origin, branch, head, and cleanliness before touching the Conversation API. It never clones/fetches remotely, deletes, resets, or repurposes an existing worktree.

Related MCP server: agent-broker

Run

The server uses MCP stdio framing (Content-Length headers):

export EVEX_MESSAGING_SECRET='long-random-secret'
export OPENHANDS_URL='http://openhands:8000'
export OPENHANDS_API_KEY='server-only-key'
export OPENHANDS_PUBLIC_URL='http://openhands.example/canvas'
PYTHONPATH=src python3 -m evex_agent_messaging

Only the adapter reads the OpenHands variables. A fake provider can be injected in tests or by a host embedding the service, so skills and Missions remain runtime-neutral.

Validation

python3 -m unittest discover -s tests -p 'test_*.py' -q