본문으로 건너뛰기

ACP 내부

ACP 어댑터는 비동기 JSON-RPC stdio 서버에서 Hermes의 동기 AIAgent을 래핑합니다.

주요 구현 파일:

  • acp_adapter/entry.py
  • acp_adapter/server.py
  • acp_adapter/session.py
  • acp_adapter/events.py
  • acp_adapter/permissions.py
  • acp_adapter/tools.py
  • acp_adapter/auth.py
  • acp_registry/agent.json

부팅 흐름​

hermes acp / hermes-acp / python -m acp_adapter
  -> acp_adapter.entry.main()
  -> parse --version / --check / --setup before server startup
  -> load ~/.hermes/.env
  -> configure stderr logging
  -> construct HermesACPAgent
  -> acp.run_agent(agent, use_unstable_protocol=True)

Zed ACP 레지스트리 경로는 hermes-agent PyPI 릴리스를 가리키는 uvx --from 'hermes-agent[acp]==<version>' hermes-acp을 통해 동일한 어댑터를 시작합니다.

Stdout은 ACP JSON-RPC 전송용으로 예약되어 있습니다. 사람이 읽을 수 있는 로그는 stderr로 이동됩니다.

주요 구성품​

HermesACPAgent​

acp_adapter/server.py은 ACP 에이전트 프로토콜을 구현합니다.

책임:

  • 초기화 / 인증
  • 신규/로드/재개/포크/목록/세션 취소 방법
  • 신속한 실행
  • 세션 모델 전환
  • 동기화 AIAgent 콜백을 ACP 비동기 알림에 연결

SessionManager​

acp_adapter/session.py은 실시간 ACP 세션을 추적합니다.

각 세션에는 다음이 저장됩니다.

  • session_id
  • agent
  • cwd
  • model
  • history
  • cancel_event

관리자는 스레드로부터 안전하며 다음을 지원합니다.

  • 창조하다
  • 얻다
  • 제거하다
  • 포크
  • 목록
  • 청소
  • CWD 업데이트

이벤트 브릿지​

acp_adapter/events.py은 AIAgent 콜백을 ACP session_update 이벤트로 변환합니다.

브리지된 콜백:

  • tool_progress_callback
  • thinking_callback(현재 ACP 브리지에서 None로 설정되어 있습니다. 대신 추론은 step_callback을 통해 전달됩니다)
  • step_callback

ACP I/O가 기본 이벤트 루프에 있는 동안 AIAgent은 작업자 스레드에서 실행되므로 브리지는 다음을 사용합니다.

asyncio.run_coroutine_threadsafe(...)

허가 브리지​

acp_adapter/permissions.py은 위험한 터미널 승인 메시지를 ACP 권한 요청에 적용합니다.

매핑:

  • allow_once -> 에르메스 once
  • allow_always -> 에르메스 always
  • 거부 옵션 -> 헤르메스 deny

시간 초과 및 브리지 오류는 기본적으로 거부됩니다.

도구 렌더링 도우미​

acp_adapter/tools.py은 Hermes 도구를 ACP 도구 종류에 매핑하고 편집자용 콘텐츠를 구축합니다.

예:

  • patch / write_file -> 파일 차이점
  • terminal -> 쉘 명령 텍스트
  • read_file / search_files -> 텍스트 미리보기
  • 큰 결과 -> UI 안전을 위해 잘린 텍스트 블록

세션 수명주기​

new_session(cwd)
  -> create SessionState
  -> create AIAgent(platform="acp", enabled_toolsets=["hermes-acp"])
  -> bind task_id/session_id to cwd override

prompt(..., session_id)
  -> extract text from ACP content blocks
  -> reset cancel event
  -> install callbacks + approval bridge
  -> run AIAgent in ThreadPoolExecutor
  -> update session history
  -> emit final agent message chunk

취소​

cancel(session_id):

  • 세션 취소 이벤트를 설정합니다.
  • 가능한 경우 agent.interrupt()을 호출합니다.
  • 프롬프트 응답으로 인해 stop_reason="cancelled"이 반환됩니다.

포크​

fork_session() 메시지 기록을 새로운 라이브 세션에 심층 복사하여 대화 상태를 유지하면서 포크에 자체 세션 ID와 cwd를 제공합니다.

제공자/인증 동작​

ACP는 자체 인증 저장소를 구현하지 않습니다.

대신 Hermes의 런타임 리졸버를 재사용합니다.

  • acp_adapter/auth.py
  • hermes_cli/runtime_provider.py

따라서 ACP는 현재 구성된 Hermes 제공자/자격 증명을 광고하고 사용합니다. 또한 첫 실행 레지스트리 클라이언트가 일반 ACP 세션을 시작하기 전에 Hermes의 대화형 모델/제공자 구성을 열 수 있도록 항상 터미널 설정 인증 방법(hermes-setup, args --setup)을 광고합니다.

작업 디렉토리 바인딩​

ACP 세션에는 편집기 cwd가 있습니다.

세션 관리자는 작업 범위 터미널/파일 재정의를 통해 해당 cwd를 ACP 세션 ID에 바인딩하므로 파일 및 터미널 도구는 편집기 작업 공간을 기준으로 작동합니다.

동일한 이름의 도구 호출이 중복되었습니다.​

이벤트 브리지는 이름당 하나의 ID가 아니라 도구 이름당 도구 ID FIFO를 추적합니다. 이는 다음과 같은 경우에 중요합니다.

  • 동시 동명 통화
  • 한 번에 같은 이름의 통화를 반복

FIFO 대기열이 없으면 완료 이벤트가 잘못된 도구 호출에 연결됩니다.

승인 콜백 복원​

ACP는 프롬프트 실행 중에 터미널 도구에 승인 콜백을 일시적으로 설치한 다음 나중에 이전 콜백을 복원합니다. 이렇게 하면 ACP 세션별 승인 처리기가 전역적으로 영구적으로 설치된 상태로 유지되는 것을 방지할 수 있습니다.

현재 제한사항​

  • ACP 세션은 공유 ~/.hermes/state.db(SessionDB)에 유지되며 프로세스가 다시 시작될 때 투명하게 복원됩니다. session_search에 표시됩니다.
  • 텍스트 추출 요청 시 텍스트가 아닌 프롬프트 블록은 현재 무시됩니다.
  • 편집기별 UX는 ACP 클라이언트 구현에 따라 다릅니다.
  • tests/acp/ — ACP 테스트 스위트
  • toolsets.py — hermes-acp 도구 세트 정의
  • hermes_cli/main.py — hermes acp CLI 하위 명령
  • pyproject.toml — [acp] 선택적 종속성 + hermes-acp 스크립트