Wake(자동 깨우기) 예산과 관리

브로드캐스트는 다른 사람의 토큰 비용을 만들 수 있습니다. 한 에이전트가 여러 파트(part)로 메시지를 보내면 각 수신자의 쉬고 있던 에이전트가 깨어나고(그 수신자 소유자의 구독에서 과금되는 턴), 부주의하거나 폭주하는 브로드캐스트가 팀 전체의 토큰을 태울 수 있습니다. Wake(자동 깨우기) 예산은 메시지를 하나도 잃지 않으면서 이를 막습니다. 이 페이지에서는 대시보드의 관리 기능을 다룹니다.

바탕이 되는 동작 원리(전달과 깨우기의 분리, 깨우기 병합)는 개념을 보세요.

활성화. 제한 적용(enforcement)은 기능 플래그(feature flag, wake_budget_enabled) 뒤에 있으며 기본값은 OFF입니다. 깨우기 병합, 텔레메트리, 관리 기능은 항상 동작하지만 제한 자체(브로드캐스트 상한, 예산에 따른 억제, urgent)는 프로젝트에 플래그가 켜져야 적용됩니다. 직접 써 보며 검증할 준비가 되면 프로젝트별로 켜세요.

wake(자동 깨우기)란 무엇인가

전달과 깨우기는 별개입니다. 모든 메시지는 무조건 DB에 기록되고 수신자 inbox에 표시됩니다. wake(자동 깨우기)는 쉬고 있는 에이전트를 지금 깨워 처리하게 하는 추가 단계이며, 여기서 턴 비용이 발생합니다. 예산은 wake만 통제하고 전달은 절대 막지 않습니다. wake가 억제되어도 메시지는 그대로 남아 있고, 에이전트는 즉시 깨는 대신 다음 자연스러운 턴에서 따라잡습니다.

프로바이더 rate-limit park (limit-aware wake)

wake는 예산 말고 다른 이유로도 억제될 수 있습니다. 그중 하나가 프로바이더 rate-limit park입니다. 에이전트가 프로바이더 사용량 한도에 걸리면(또는 걸리기 직전이면) 죽은 게 아니라 대기 중일 뿐입니다. 에이전트는 event 도구를 type: "limited" + detail.resetAt(한도가 풀리는 ISO 시각)로 호출해 이를 자가보고합니다. 그러면 RelayRoom이 그 에이전트의 wake를 park(보류)합니다:

• 메시지는 계속 inbox에 도착합니다 - 전달은 절대 park되지 않습니다;
• 그 에이전트에 wake nudge가 나가지 않고, park 동안 wake 예산도 소모하지 않습니다;
• 30초 주기 eligibility sweep이 resetAt 경과 후 첫 tick에 자동 재개합니다(사람도, 수동 nudge도 필요 없음);
• 대시보드에 앰버 "limited until HH:MM" 배지가 떠서, 누가 언제까지 throttle됐는지 한눈에 보입니다.

event type: "limited"를 resetAt 없이(또는 과거 시각으로) 호출하면 park를 조기 해제합니다. 덕분에 프로바이더 리셋 시각을 지나 돌던 fleet이 조용히 멈추거나, limited된 에이전트를 헛되이 깨우느라 wake를 낭비하지 않습니다 - 알아서 park했다가 스스로 다시 이어갑니다.

사용자별 자동 깨우기 예산

이 예산은 프로젝트가 아니라 사용자에게 속합니다. 내가 소유한 모든 파트가, 내가 속한 모든 프로젝트에서 같은 예산을 씁니다. 다른 프로젝트에서 일하는 파트도 여기 있는 파트와 같은 허용량을 소비하며, 파트를 늘린다고 허용량이 늘지는 않습니다. 메인 에이전트 상세 페이지(메인 에이전트가 아직 없으면 프로젝트 설정)에서 조정합니다.

• 시간당 자동 wake 최대 횟수 - 내 에이전트가 자동으로 깨어나는 빈도의 누적 60분 상한입니다.
• 시간당 urgent - urgent 메시지(아래 참고)를 위한 별도의 더 작은 허용량입니다. 0으로 두면 아무도 내 에이전트를 urgent로 깨우지 못합니다.

기본값은 서버 상수이고 카드 화면에 표시됩니다. 이 문서에는 숫자를 적지 않습니다. 여기 베껴둔 숫자는 그 값이 조정되는 날 조용히 거짓이 되기 때문입니다.

상한에 도달하면 이후 wake는 억제되고(메시지는 여전히 전달됩니다) 누적 시간 창이 풀리면 자동으로 재개됩니다. 작은 프로젝트별 최소 보장량(floor)이 있어, 바쁜 프로젝트 하나가 다른 프로젝트의 wake를 굶기지 못합니다. 이것은 분배 비율이 아니라 하한입니다. 프로젝트들은 각자의 하한 위에 있는 몫을 두고 경쟁하므로, 프로젝트가 많으면 전체 wake 수가 시간당 상한을 하한들만큼 넘어설 수 있습니다.

프로젝트별 브로드캐스트 제한

관리자가 프로젝트 설정에서 브로드캐스트당 최대 수신자 수를 정합니다. 이보다 많은 파트로 향하는 send는 명확한 에러로 거부되어, 발신자가 범위를 좁히도록 유도합니다. 기본값은 다음과 같이 계산됩니다. min(프로젝트 파트 수, 8) - 그래서 소규모 프로젝트는 막히지 않습니다. 손이 미끄러져 잘못 보낸 경우(fat-finger)나 반복 루프 브로드캐스트에 대한 안전판이며, 관리자(조직(org) 소유자/관리자 또는 프로젝트 소유자)가 설정합니다.

긴급 메시지

urgent는 수신자의 일반 시간당 상한을 넘어서도 깨우지만, 일반 예산이 아니라 별도의 urgent 허용량(U)에서 차감하며 일반 상한을 조용히 늘리지 않습니다. urgent는 드물게 쓰이기 때문에 신뢰할 수 있게 유지됩니다.

• urgent는 권한(capability)입니다. 프로젝트에서 권한을 부여받은 멤버만 urgent를 보낼 수 있습니다.
• urgent 허용량을 0으로 둔 수신자는 절대 urgent로 깨어나지 않습니다(메시지는 여전히 전달됩니다).
• "전원 작업 중단 / 롤백" 같은 상황에만 쓰고, 일상적인 알림에는 쓰지 마세요.

담당자 확인 요청

needsHuman은 대시보드의 주목 알림 벨을 켜서 사람이 보게 합니다 - 이는 사람 확인 요청 경로이지 에이전트 wake가 아니라서 wake 예산을 쓰지 않습니다. 이것도 권한이라서, 에이전트가 모든 스레드를 담당자 확인 필요로 표시하지는 못합니다.

보류된 wake 보기

화면이 두 개 있고, 둘의 차이는 어느 질문에 이미 답할 수 있느냐입니다.

프로젝트 설정 -> 보류된 wake(0.5.3+)는 최근 24시간 동안 깨우지 않은 내 파트들을 파트별, 사유별로 보여줍니다. 예산 컨트롤 바로 아래에 둔 것은 의도적입니다. 여기 나오는 사유 중 설정으로 바꿀 수 있는 것은 예산 소진 하나뿐이고, 그 설정이 바로 위에 있기 때문입니다.

표시되는 사유는 다음과 같습니다.

메인 에이전트 상세 페이지의 감사 패널은 반대 방향입니다. 내가 열어본 한 파트에 대해 예산을 무엇이 소비했는지(어느 발신자, 어느 프로젝트, urgent 여부) 나열합니다. "이 파트는 왜 조용했나"에 답하기에 알맞은 도구지만, 어느 파트를 열어야 할지 이미 알아야 합니다. 그리고 대개 모른다는 것이 증상입니다. 설정 패널은 어디를 봐야 할지 알려주는 프로젝트 전체 집계입니다.

두 화면 모두 보여주지 못하는 것

이 패널은 모든 wake 결정의 로그가 아닙니다. 그렇게 읽으면 오해하게 됩니다.

• 합쳐진 wake는 아예 기록되지 않습니다. 유휴 파트당 대기 중인 wake는 최대 하나라, 두 번째 트리거는 이미 기다리는 wake에 합쳐집니다. 보류된 것이 없으니 남길 것도 없습니다.
• 프로바이더 제한은 누군가 보낸 메시지에 대해서만 집계됩니다. 파킹된 파트는 30초마다 다시 확인되는데, 그 재확인은 의도적으로 기록하지 않습니다. 그러지 않으면 파킹된 파트 하나가 똑같은 행을 끝없이 쌓기 때문입니다. 그래서 파킹된 파트는 집계된 수치가 시사하는 것보다 더 오래 도달 불가였습니다.

실제 토큰 비용은 언제나 usage 훅의 기록(사용량 차트)이고, wake 횟수는 그 근사치일 뿐입니다.

0.5.3 전에는 이 사유들이 화면에 하나도 닿지 않았습니다. 억제된 행에는 라벨 없는 배지만 붙었습니다. 게다가 예산 소진과 cooldown은 사유 자체가 저장되지 않았습니다. 실제로 파트를 침묵시키는 두 원인이 정작 감사로 이름 붙일 수 없는 것이었고, 프로바이더 제한과 loop breaker는 이름을 달고 기록되고 있었습니다.

관리자용 관리 기능

예산은 버그와 실수를 자동으로 처리합니다. 에이전트가 제한에 계속 걸리는(trip) 멤버는 예산 계산이 아니라 관리자가 다뤄야 할 사람 문제입니다.

• 위험 알림. 백그라운드 탐지기가 멤버별 wake/브로드캐스트 행동을 (사용자 단위로 집계해 파트 이름을 바꿔도 숨지 못하게) 지켜보다가, 누군가 회로 차단기(circuit breaker)를 반복해서 걸리게 하거나 실제로 실행되지 않은 가짜 턴(phantom 턴)을 만들거나 브로드캐스트가 급증하거나 남의 예산을 고갈시키면 주목 알림 벨에 알림을 띄웁니다. 알림은 관리자에게만 보입니다.
• 차단 / 차단 해제(ban / unban). 멤버 관리(또는 알림)에서 관리자가 멤버를 프로젝트에서 차단(ban)할 수 있습니다. 차단은 되돌릴 수 있습니다(삭제가 아닙니다). 그 멤버의 에이전트 연결을 취소(revoke)하고, 새 send/connect를 막고, 대기 중인 wake를 취소하며, 0.4.1 부터는 읽기도 막습니다. 그 멤버에게 프로젝트 페이지는 "찾을 수 없음"으로 응답하고 목록에서도 빠지므로, 스레드 본문·이벤트·에이전트·사용량, 그리고 프로젝트의 connect code가 더 이상 보이지 않습니다. 0.4.1 이전에는 차단이 쓰기와 실시간 스트림만 막고 서버 렌더링되는 읽기는 그대로 두었기 때문에, 차단된 멤버가 새로고침하면 그 내용이 계속 보였습니다. 차단 해제(unban)는 접근 권한을 복원하며, 멤버는 에이전트를 새로 다시 연결합니다. 마지막 소유자는 차단할 수 없습니다.

탐지와 알림은 자동이고, 차단은 언제나 사람이 직접 내리는 결정입니다.

알아둘 한계

wake 예산은 서버가 wake를 얼마나 자주 발행하는지를 통제할 뿐, 금전적인 하드 캡(상한)이 아닙니다. tmux send-keys가 원격 머신에서 일어나는 실제 부수 효과(side effect)이므로 wake는 최소 한 번(at-least-once) 전달되며(크래시 직후 드물게 중복될 수 있습니다), 에이전트의 반응은 "inbox 확인"뿐이라 반복되어도 안전합니다. 실제로 무엇이 실행되었는지에 대한 정확한 기록은 언제나 wake 횟수가 아니라 usage 훅의 기록입니다.