EVEX Agent Messaging Gateway

Parent Main, Child Main, Role Child의 Conversation 작업을 위한 프로바이더 중립적 MCP 전송입니다. 에이전트는 이 MCP를 호출하며, OpenHands의 Conversation API를 직접 호출하지 않습니다.

도구

• create_child: 완전한 구조화된 Mission과 깨끗한 결정론적 Git checkout을 검증하고, Child ID와 콜백 capability를 바인딩한 다음, 하나의 결정론적 Conversation을 생성합니다. 프로바이더는 도구를 사용하지 않는 입장 턴을 실행하고, ACP 부트스트랩 후 정확한 branch/head를 복원하고 재검증한 다음에야 도구를 허용하고 Mission을 전달합니다. checkout 권한이 없거나 일치하지 않으면 Conversation API 호출이 발생하지 않습니다. 소스 역할은 Messaging만 받습니다. 명시적인 QA/수리 Mission만 capabilities: ["runtime_environment"]를 요청할 수 있습니다.

• send_to_parent: 구조화된 RESULT/NEEDS_INPUT을 해당 capability를 소유한 Main에 전달합니다.

• request_user_decision: A/B/C 형식의 질문을 소유 Main에 전달합니다.

• cancel_mission / resume_mission: 정확한 Child 작업을 중지하거나 재개합니다.

• publish_navigation_links: 정보성 Issue/Main/Child/PR 링크를 소유 Main에 게시합니다.

Capabilities는 간결하고 불투명한 evx1_ HMAC-SHA256 참조입니다. 이 참조는 소유 Main, Child, 작업 키, 역할, 허용된 작업 및 만료를 바인딩합니다. 서버는 OpenHands 자격 증명을 보유하며, 이는 도구 입력, 도구 출력 또는 child 환경 변수에 절대 나타나지 않습니다. 영구 상태는 없습니다. 호출자는 안정적인 메시지 키를 제공하고, Main은 의미적 재전송을 중복 제거합니다.

생성된 각 Child는 비동기 네이티브 Stop 훅을 받습니다. 훅은 자신의 범위가 지정된 참조와 함께 비공개 /completion-hook 엔드포인트를 호출합니다. 게이트웨이는 최종 네이티브 상태를 기다린 후, 제한된 최종 어시스턴트 응답을 포함하는 안정적인 RECOVERY_WAKE 하나를 소유 Main에 전송합니다. 이는 모델이 send_to_parent를 호출하지 않고 종료될 때 사용하는 프로바이더 중립적 폴백입니다. 반복되는 훅은 동일한 의미의 메시지 키를 재사용하며, 데이터베이스, 폴러, 읽기 도구 또는 수신 확인 저장소가 필요하지 않습니다.

신뢰할 수 있는 Event Gateway/호스트는 main_capability_token(...)을 사용하여 수명이 짧은 Main capability를 발행하고 이를 Main Mission에 주입합니다. MCP는 에이전트에게 capability 발행 도구를 노출하지 않습니다.

Parent는 /home/openhands/workspace/mirrors/<owner>--<repository>.git에 있는 영구 bare mirror만 생성하거나 가져옵니다. create_child는 /home/openhands/workspace/delivery/child-<child UUID>를 도출하고, 없으면 정확한 branch worktree를 생성한 다음, Conversation API를 건드리기 전에 저장소, origin, branch, head 및 클린 상태를 검증합니다. 원격으로 클론/페치하지 않으며, 기존 worktree를 삭제, 리셋하거나 다른 용도로 재사용하지 않습니다.

Related MCP server: agent-broker

실행

서버는 MCP stdio 프레이밍(Content-Length 헤더)을 사용합니다:

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

OpenHands 변수를 읽는 것은 어댑터뿐입니다. 테스트에서 또는 서비스를 내장하는 호스트에 의해 가짜 프로바이더를 주입할 수 있으므로, 스킬과 Mission은 런타임 중립성을 유지합니다.

검증

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