Hermes Agent GUI

터미널 화면을 열었다고 명령을 실행할 수 있는 것은 아닙니다

Hermes Agent GUI는 Hermes Agent의 대화와 작업을 화면으로 연결하는 프로젝트입니다. 저는 원본 에이전트의 기능과 GUI의 조작 책임을 나누면서, 대화 화면뿐 아니라 파일과 터미널을 다루는 경로도 구성했습니다. 그중 터미널에는 로그인 여부만으로 설명할 수 없는 조건이 있었습니다.

명령 실행을 설정에서 켰더라도 서버가 어디에 바인딩됐는지에 따라 실제 실행 가능성이 달라집니다. 로컬에서만 접근하는 서버와 0.0.0.0에 열어 둔 서버는 같은 조건이 아닙니다. 화면이 실행 설정 하나만 읽으면 버튼은 활성화됐는데 서버는 요청을 거절하는 상태가 생길 수 있습니다.

5월 27일의 정리에서는 터미널 화면이 서버의 실제 실행 판정을 읽도록 맞췄습니다. 로그인에 성공했는지, 실행 기능을 켰는지, 현재 연결 범위에서 실행을 허용했는지를 나눠 보여주는 작업이었습니다. 설정값과 현재 가능한 동작을 같은 정보로 다루지 않기로 했습니다.

실행 기능을 기본으로 닫아 두었습니다

명령 실행은 기본 비활성으로 두었습니다. 로컬 사용자가 명시적으로 실행 기능을 켜야 터미널·PTY·예약 작업·swarm의 실행 경로를 사용할 수 있습니다. 공통 실행 정책을 두어 각 기능이 같은 조건을 확인하도록 연결했습니다.

이것은 버튼 하나를 숨기는 처리로 끝나지 않습니다. 서버의 각 요청 경로에서 실행 정책을 확인하고, 비활성 상태에는 exec_disabled를 반환합니다. UI가 호출을 보내더라도 서버가 판정하도록 한 구조입니다. 인증은 요청한 사용자를 확인하는 단계이고, 실행 허용은 그 뒤의 별도 판단입니다.

저는 같은 종류의 권한을 여러 화면에서 따로 해석하는 방식은 피했습니다. 터미널에서는 막히는데 예약 작업에서는 허용되면 기능마다 다른 경계를 갖게 됩니다. 실행을 시작하는 경로가 늘어나더라도 공통 정책을 확인하는 구성을 유지하는 것이 이 단계의 선택이었습니다.

원격 바인딩에는 두 번째 선택이 필요했습니다

서버가 loopback 주소에서 동작하는 경우와 다른 네트워크 인터페이스에 열리는 경우를 나눴습니다. 실행을 켰어도 원격 바인딩이면 추가적인 원격 실행 허용이 필요합니다. 이 조건을 만족하지 않으면 exec_remote_bind_disabled와 바인딩 주소를 전달합니다.

로컬 브라우저로 접속했다는 사실만으로 서버가 로컬에만 열려 있다고 판단하지 않았습니다. 실제 서버의 바인딩 주소가 무엇인지 확인하도록 했습니다. Docker나 LAN 구성으로 주소를 바꿨을 때도 이전 설정이 그대로 실행 권한으로 이어지지 않도록 한 선택입니다.

이 구분 덕분에 차단 이유를 설명할 수 있습니다. 실행 설정 자체가 꺼진 것인지, 설정은 켰지만 네트워크 범위가 허용 조건 밖인지가 다릅니다. 사용자가 다시 살필 곳도 달라지므로 하나의 ‘실패’ 문구로 합치지 않았습니다.

화면은 설정값 대신 실제 판정 결과를 읽습니다

터미널 상태 API에는 exec_enabled와 exec_available를 따로 두었습니다. 전자는 설정 여부이고 후자는 공통 정책을 적용한 현재 실행 가능성입니다. 여기에 blocked_reason, 바인딩 주소, 허용된 명령 목록과 설명을 함께 전달합니다.

화면은 exec_available이 참일 때만 실행 조작을 활성화하도록 맞췄습니다. 상태를 가져오는 동안에도 조작을 막고, 조회 자체가 실패하면 그 오류를 표시합니다. 아직 상태를 모르는 순간을 실행 가능으로 간주하지 않도록 한 것입니다.

서버는 실행을 막은 이유를 반환하고, 화면은 그 판정에 따라 버튼을 제어하며 같은 이유를 보여 줍니다. 버튼이 막혀 있을 때 사용자가 읽는 설명과 서버가 요청을 거절하는 이유가 맞도록 연결했습니다.

명령과 작업 경로에도 별도 조건을 뒀습니다

실행이 가능해진 다음에도 명령과 작업 폴더를 확인합니다. 기본 명령 목록을 두고, 작업 경로는 허용된 워크스페이스 안으로 제한했습니다. 터미널의 단발 실행에는 시간 제한과 출력 길이 제한도 넣어 결과가 화면과 서버를 끝없이 차지하지 않도록 했습니다.

다만 명령 목록만으로 모든 명령의 동작을 안전하다고 판단하지는 않습니다. python3나 node처럼 다른 작업을 수행할 수 있는 프로그램도 목록에 있습니다. 이 목록은 실행 기능을 켠 환경에서 허용할 입구이며, 작업 범위와 입력을 별도로 검토해야 합니다.

원본 에이전트와의 연결도 같은 방식으로 나눕니다. 대화 어댑터의 연결 상태와 터미널 실행 정책을 각각 확인하도록 구성했습니다. 에이전트 연결을 바꿀 때도 실행 정책이 그 설정을 따라 무심코 넓어지지 않는지 함께 살필 수 있습니다.

기능의 존재보다 차단 상태를 검사했습니다

터미널 검수 조건에는 기본 비활성 상태에서의 실행 거절, PTY 실행 거절, 실행을 켠 상태의 허용 목록, 잘못된 입력과 resize 값이 포함되어 있습니다. 특히 실행 설정은 켜고 원격 바인딩 허용은 끈 조건에서 상태 API가 exec_available을 거짓으로 반환하도록 확인 조건을 뒀습니다.

정상 연결만 살피면 설정과 실제 가능성이 어긋나는 경우를 놓칠 수 있습니다. 저는 기능이 꺼진 경우, 설정이 일부만 켜진 경우, 상태를 아직 읽지 못한 경우를 화면과 서버 양쪽의 경계로 남겼습니다. 테스트에 담긴 이 조건은 새로운 환경에 연결할 때도 다시 살펴야 할 항목입니다.

Hermes Agent GUI를 만들며 정리한 기준은 조작 화면이 서버의 판단을 대신해서는 안 된다는 것입니다. 명령 실행 같은 기능은 로그인 버튼 뒤에 자동으로 따라오는 부가 기능이 아닙니다. 실제 가능 여부와 차단 이유를 끝까지 연결해야 사용자가 화면에 보이는 버튼의 의미를 이해할 수 있습니다.