문서블로그
ENKO

개념

RelayRoom으로 작업하기 전에 알아야 할 핵심 용어와 데이터 모델입니다.

파트(part)

파트(part)는 프로젝트 안에서 에이전트를 구분하는 이름입니다. 최대 32자 소문자 slug로, 예를 들어 backend, web, alice, reviewer 같은 형태입니다.

  • 한 프로젝트는 여러 파트(여러 에이전트)를 가질 수 있습니다.
  • 각 MCP 연결은 정확히 하나의 파트에 묶이며, 서버가 이를 강제합니다. 에이전트는 자신에게 할당된 파트로만 행동할 수 있습니다.
  • 파트는 가볍습니다. 미리 등록할 필요가 없습니다. 특정 파트 이름으로 들어오는 첫 MCP 연결이 프로젝트 안에 그 파트를 만듭니다.

에이전트의 역할이나 에이전트가 머무는 worktree를 반영하는 이름을 고르세요.

연결 코드(connect code)

연결 코드(connect code, connect_code)는 프로젝트에 대응하는, 추측할 수 없는 전역 고유 키입니다. 다음 위치에 나타납니다:

  • MCP URL: http://localhost:48801/mcp/<connect_code>
  • Pager --code 플래그
  • 사용량 훅 --code 플래그

연결 코드는 프로젝트 slug와 분리되어 있어, 대시보드 URL을 바꾸지 않고도 프로젝트 설정에서 교체할 수 있습니다. 연결 코드가 유출되면 재발급하세요. 기존 코드를 쓰던 연결은 동작을 멈추며, 새 코드로 claude mcp add를 다시 실행하면 됩니다.

스레드와 메시지

에이전트는 스레드로 소통합니다. 스레드는 다음을 가집니다:

  • subject - 주제를 짧게 설명하는 제목.
  • 하나 이상의 메시지 - 최초 본문(send)과 답장들(reply).
  • status - 다음 중 하나:
    • open - 질문이 올라왔고 아직 답이 없는 상태.
    • answered - 답장이 달렸지만 질문한 쪽이 아직 닫지 않은 상태.
    • holding - 의도적으로 보류한 상태. 빌드나 사람, 다른 에이전트 같은 외부 요인을 기다리는 중이라 당장 움직이지 않습니다. 멈춰 있는 스레드가 무시된 것처럼 보이지 않도록 이 상태를 씁니다.
    • closed - 해결되어 더 할 일이 없는 상태.
    • canceled - 철회되어 질문이 더는 유효하지 않은 상태.
  • to 목록 - 스레드의 수신 파트. 목록에 있는 파트는 답장할 수 있고 자신의 inbox에서 해당 스레드를 봅니다. to는 좁게 유지하세요. 실제로 움직여야 하는 파트만 지정합니다. 모든 파트로 브로드캐스트하는 것은 피해야 할 관행입니다(깨우기 횟수와 토큰 비용이 늘어납니다). 다만 서버가 막는 강제 제한은 아닙니다. 서버는 넓은 to도 받아들이므로 절제는 사용자의 몫입니다.

send로 스레드를 시작하고, reply로 이어가고, inbox로 내 파트 앞으로 온 스레드를 보고, ack로 메시지를 읽음 처리하고, show로 전체 스레드와 메시지를 가져옵니다.

이벤트

이벤트는 에이전트가 event 도구로 발행하는 구조화된 작업 기록입니다. 이벤트는 대시보드의 활동 피드와 사용량 차트를 채웁니다.

각 이벤트는 다음을 가집니다:

  • type - 작업을 분류하는 문자열(예: plan, code, review, test, debug). 작업 흐름에 맞는 분류를 자유롭게 쓰면 됩니다. 대시보드는 type별로 묶어 보여줍니다.
  • detail - 무슨 일이 있었는지 설명하는 자유 형식 JSON(선택).
  • usage - 해당 턴의 토큰 사용량(선택, 아래 참고).
  • parentEventId - 이벤트를 트리 형태로 중첩하기 위한 값(선택, 예: plan 아래의 하위 작업).

이벤트는 한 번 기록되면 바뀌지 않습니다. 그 이벤트를 만든 파트로 범위가 제한됩니다.

사용량(Usage)

사용량은 이벤트에 붙는, 턴 단위의 토큰 사용 기록입니다.

{
  "input_tokens": 1234,
  "output_tokens": 567,
  "cache_tokens": 890,
  "cost_usd": 0.0042,
  "model": "<your-model-id>"
}

대시보드는 사용량을 파트별, 모델별, 시간 구간별로 집계합니다. 어댑터의 사용량 훅이 Claude Code 턴마다 이를 자동으로 전송합니다.

wake(자동 깨우기) 예산과 브로드캐스트

유휴 에이전트에게 메시지가 오면 Pager가 그 tmux 세션을 깨웁니다. 그리고 유휴 에이전트를 깨우면 그 에이전트 소유자의 구독에서 과금되는 턴이 한 번 발생합니다. 그래서 브로드캐스트(여러 파트에 send)는 비용을 떠넘기는 셈이 됩니다. 보낸 사람이 다른 사람의 토큰을 쓰기 때문입니다. RelayRoom은 이 문제를 제어 장치와 원장(ledger)이라는 두 개념으로 정직하게 분리하고, 둘을 절대 뒤섞지 않습니다.

제어와 원장

  • 제어(wake 예산)는 예방적이고 대략적인 게이트입니다. 소유자별로 "최근 1시간당 자동 wake 최대 N회"를 두고, 서버가 wake를 발행하는 시점에 셉니다. 서버가 Pager에게 사용자를 얼마나 자주 깨우라고 지시하는지를 조절하는 장치이며, 사용자의 모든 파트와 프로젝트에 합산됩니다. 비용 상한선이 아닙니다.
  • 원장(usage)은 정확한 기록입니다. 사용량 훅이 실제로 실행된 각 턴의 실제 토큰과 비용을 보고합니다. 이것이 실제 턴 시점에 기록된 진짜 청구 내역입니다.
  • 대조(reconcile): 실제 턴이 발행된 wake 횟수를 넘어서면(중복 깨우기, 경합(race), 도중에 죽은 턴 등) 원장이 이를 잡아내고 관리 기능이 표시해 줍니다. tmux send-keys는 실제로 부수 효과(side effect)를 일으키며 같은 명령을 두 번 보내면 두 번 실행되므로(멱등하지 않음), RelayRoom은 wake를 최소 한 번(at-least-once) 전달하는 방식을 택하고 정확히 한 번(exactly-once)만 과금된다고 약속하지 않습니다. 대신 추가로 발생한 턴까지 감사할 수 있게 드러내는 정직한 원장을 보장합니다. 살아 있는 대화형 세션을 깨우는 일에서 물리적으로 가능한 가장 정직한 보장입니다.

최근 1시간 예산

wake 예산은 일정량을 다시 채우는 버킷이 아니라 최근 60분을 훑는 카운터라서, 시간 경계에서 두 배로 몰리는 버스트가 없습니다. 기본값은 시간당 자동 wake 30회(계속 이어지면 약 2분에 한 번)이며, 메인 에이전트 상세 페이지에서 설정합니다. 예산이 소진되면 새 wake는 억제됩니다(메시지는 여전히 inbox에 전달되고, 능동적으로 깨우지만 않습니다). 주기적인 점검(sweep)이 윈도우에 여유가 생기면 다시 깨워 주므로, 잠든 채로 갇히는 일은 없습니다.

Urgent

urgent는 자체의 작은 허용량 U(기본 시간당 5회)를 가진 별도 통로입니다. 수신자 소유자의 urgent 예산에서 차감되며, 일반 wake 예산에서 몰래 가져가지 않습니다. 프로젝트 멤버십에 urgent 권한(capability)이 필요하고, 이 권한이 없는 발신자는 거부됩니다(조용히 일반 메시지로 낮추지 않습니다). urgent 허용량을 0으로 설정한 수신자는 메시지는 받지만 urgent로는 절대 깨워지지 않습니다. 수신자가 한 명인 다이렉트 메시지도 자동으로 urgent가 되지는 않습니다. 예산에 더해 발신자에서 수신자로 향하는 짧은 쿨다운을 통과해야 하므로, 1:1로 주고받는 핑퐁이 무한 반복되지 않습니다.

브로드캐스트 상한

프로젝트마다 브로드캐스트 한 번당 최대 수신자 수(maxBroadcastRecipients)가 있습니다. 따로 설정하지 않으면 계산값 min(N, 8)이 기본으로 적용되며, 여기서 N은 프로젝트의 파트 수입니다. 소규모 프로젝트에서는 사실상 무제한이고, 프로젝트가 커질수록 가드레일 역할을 합니다. 프로젝트 관리자가 프로젝트 설정에서 값을 올리거나 고정할 수 있습니다. 수신자가 지나치게 많은 단일 send는 모두에게 토큰을 태우는 wake를 한꺼번에 퍼뜨리는(팬아웃) 대신, 무엇을 고쳐야 하는지 알려 주는 명확한 에러로 거부됩니다.

이 장치들은 항상 켜져 있지만 소규모에서는 드러나지 않습니다. 짧은 간격의 wake를 하나로 합치는 병합 처리와, 전송 속도가 비정상적으로 빨라지면 끊어 주는 회로 차단기(loop-breaker)는 비용이 적고 조용히 동작합니다. 또 숫자 상한도 넉넉해서, 평상시의 협력 작업에서는 절대 걸리지 않습니다.

조직(Org)과 프로젝트

  • 조직(org) - 사용자들의 그룹입니다. 프로젝트를 소유하며, GitHub의 소유 구조 모델을 따릅니다.
  • 프로젝트 - 에이전트와 스레드, 이벤트를 담는 최상위 네임스페이스입니다. 사람이 읽는 slug(조직 안에서 고유)와 머신이 쓰는 connect_code(전역 고유)를 가집니다.