Files
EJClaw/README.md
Codex aed7371cfa feat: pause room work on the Claude usage limit and resume after reset
Before, a Claude run that hit the account usage limit closed the open
paired task as claude_usage_limit, posted the reset time and consumed the
user's messages, so the work was lost and had to be re-requested.

Now the room is paused instead:
- The failed turn is released without touching the paired task (no
  failure count, no status change, no follow-up) and the queue keeps the
  human messages unconsumed, so the same turn can run again.
- The room is recorded in router_state `claude_usage_pause` with the reset
  time (error text, else cached usage API reset, else a 10 min retry). A
  banner time that just passed is read as "now", not tomorrow.
- While the limit lasts, paused rooms run nothing and any other room's
  Claude turn pauses that room without spawning a run (the limit is
  account-wide). A stop request still goes through and drops the room
  from the resume list.
- The scheduler tick clears the pause 1 min after the reset, posts a
  resume notice and re-queues the rooms; the pending turn or the kept
  messages then run again. The state survives restarts.

Safety refusals keep closing the task as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 13:14:56 +09:00

203 lines
11 KiB
Markdown

# EJClaw
![Version](https://img.shields.io/badge/version-0.2.3-blue)
![Claude Agent SDK](https://img.shields.io/badge/Claude_Agent_SDK-0.3.286-blueviolet)
![Codex SDK](https://img.shields.io/badge/Codex_SDK-0.159.3-green)
![Bun](https://img.shields.io/badge/Bun-1.3+-f9f1e1?logo=bun&logoColor=black)
![Discord](https://img.shields.io/badge/Discord-Tribunal-5865F2?logo=discord&logoColor=white)
EJClaw는 Discord 위에서 동작하는 Tribunal 멀티에이전트 개발 보조 시스템입니다.
사용자 요청은 owner가 받고, reviewer가 자동 리뷰를 수행하며, 필요할 때 arbiter가 교착을 정리합니다.
원본은 [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw)에서 출발했지만, 현재는 EJClaw의 Discord/paired-runtime 구조에 맞게 독립적으로 유지되고 있습니다.
이 Gitea 저장소는 GitHub `main`을 베이스로 삼고, 운영 환경에서 검증된 로컬 변경(아래 "운영 적용 사항")을 현재 코드 구조에 맞게 재구현해 얹은 배포본입니다.
## 개요
- 단일 `ejclaw` 서비스가 owner / reviewer / arbiter 세 역할과 세 Discord 봇을 함께 관리합니다.
- 사용자 진입점은 owner 하나이며, reviewer와 arbiter는 내부 역할로 동작합니다.
- room-level 설정은 `room_settings`를 기준으로 하며, 방 등록은 `bun run setup -- --step register`(내부적으로 `assignRoom`)로 합니다.
- 모든 방은 동등합니다. 별도의 main(관리) 방은 없고, 각 방의 에이전트는 자기 방의 메시지·예약 작업·DB 증거만 다룰 수 있습니다. 여러 방에 걸친 관리 작업은 호스트 셸에서 합니다.
- reviewer는 owner의 현재 worktree를 direct mount로 읽고, role-scoped read-only 보호를 적용받습니다.
- paired runtime은 SQLite(WAL), stable owner worktree, turn/lease 추적, host verification으로 구성됩니다.
## 핵심 기능
- Tribunal 3-에이전트 루프: owner / reviewer / arbiter
- 역할별 agent type / model / effort 설정
- role-fixed Discord 봇 3개 체계
- reviewer host runtime + read-only guard
- 승인 후 변경 감지와 재리뷰
- Claude 사용 한도 도달 시 방 작업을 일시정지하고, 사용량이 초기화되면 자동으로 이어서 진행
- `room_settings` 기반 명시적 room assignment
- 자연어 중단: 작업 중인 방에 "그만", "멈춰", "중단해", "취소", "stop" 같은 짧은 메시지만 보내면 실행 중인 에이전트를 끝내고 열린 paired task를 닫음
- Bun + SQLite 기반 빠른 런타임
## 운영 적용 사항
GitHub `main` 베이스 위에 운영 중 검증된 변경을 현재 코드 구조에 맞춰 재구현해 반영했습니다.
- Discord 출력 마크다운 보존: 일반 문장의 `**bold**`, `~~strike~~`, 백틱 등 emphasis 마커를 렌더링 대신 원문 그대로 표시(백슬래시 이스케이프). 코드블록과 구조화 출력(EJClaw JSON, 링크→인라인 코드)은 의도대로 보존하고, 이스케이프는 Discord 전송 직전 한 번만 적용됩니다.
- 2000자 분할 시 코드블록 보존: 코드 펜스(triple backtick)를 인식해 청크 경계에서 코드블록이 깨지지 않도록 분할(서러게이트 페어 안전 처리 포함).
- 사용량 윈도우 정렬 프라이머: Codex/Claude 초기화 시점을 맞추기 위한 정렬 신호를 조건 없이 발사.
- 리뷰어 무응답 방지: 리뷰어가 verdict 없이 연속 실패할 때 재시도 상한(기본 2회)으로 핑퐁 루프를 끊고 arbiter/사용자로 에스컬레이션.
- 대시보드: 등록된 방 별칭을 Discord 채널명과 분리해 보존.
- 상태 대시보드 갱신 정책: 기본 갱신을 벽시계 분 경계(:00초)에 정렬하고, 새 채팅 메시지·에이전트 활성 변화 시 즉시(1.5s 디바운스) 갱신. 상태 메시지 편집이 실패하면 15초 간격 2회 재시도 후에만 새 메시지로 재게시하며(봇 재시작 직후에는 즉시 재표시), 편집 실패로 인한 반복 재생성(알림 스팸)을 제거.
- Claude 세션 토큰 write-back: 각 Claude 턴 종료 시 세션이 rotate한 OAuth 토큰을 표준 자격증명(data/claude)으로 수렴시켜, 본체 리프레시 루프와 세션 CLI가 같은 토큰 패밀리를 각자 갱신하다 발생하던 `invalid_grant`(리프레시 토큰 패밀리 폐기 → 재로그인 강제)를 방지. 세션 자격증명 스캔 경로도 실제 구조(`services/<id>/.claude`, `tasks/<id>` 하위)에 맞게 정정해 fan-out/stale 정리가 실제 세션 파일을 덮도록 함. Codex는 기존 write-back(`syncCodexSessionAuthBack`)을 사용.
- 채널 등록 해제 도구(`scripts/deregister-room.ts`): 채널 등록 해제 시 paired 데이터·세션(reviewer·arbiter 포함)·워크스페이스·디스크 폴더(git worktree 포함)를 전부 정리하고 채팅 채널과 메시지만 보존. `--dry-run` 미리보기, 다른 방과 공유하는 폴더 보호, 실행 전 DB 자동 백업 포함.
## Tribunal 시스템
| 역할 | 현재 기본값 | 설명 |
| --- | --- | --- |
| Owner | room별 `owner_agent_type` (기본 Codex) | 사용자 요청 처리, 코드 작성, 최종 응답 |
| Reviewer | 전역 `REVIEWER_AGENT_TYPE` (기본 Claude Code), room별 `reviewer_agent_type`로 override 가능 | owner 결과 비판적 리뷰, 회귀 검증 |
| Arbiter | 전역 `ARBITER_AGENT_TYPE` (옵션), room별 `arbiter_agent_type`로 override 가능 | owner/reviewer 교착 시 판정 |
```text
사용자 메시지
→ Owner 응답
→ Reviewer 자동 실행
→ verdict:
DONE → Owner finalize → 완료
DONE_WITH_CONCERNS → Owner 수정 → 재리뷰 루프
BLOCKED/NEEDS_CONTEXT
├─ Arbiter enabled → Arbiter 판정
└─ Arbiter disabled → 사용자로 에스컬레이션
→ 왕복이 누적되면 arbiter 자동 요청 가능
```
### 작업 중단
방에서 에이전트가 실행 중이거나, 대기 중인 메시지·열린 paired task가 있을 때 사람이 중단 의도만 담긴 짧은 메시지를 보내면 그 방의 작업을 멈춥니다.
- 인식하는 표현: `그만`, `그만해(줘)`, `그만하자`, `멈춰(줘)`, `중단(해)`, `중지`, `하지 마`, `취소(해)`, `스톱`, `stop`, `cancel` 등. 앞뒤 봇 멘션과 끝의 `. ! ~ ㅠ ㅜ`는 무시하고, "작업 중단해줘", "제발 그만"처럼 짧은 수식어는 허용합니다.
- "그거 하지 말고 이거 해줘", "중단하지 말고 계속해", "로그인 취소 기능 만들어줘"처럼 다른 지시가 섞인 메시지는 중단으로 보지 않습니다. 애매하면 일반 메시지로 처리합니다.
- 중단 시: 실행 중인 owner/reviewer/arbiter 프로세스를 종료하고, 열린 paired task를 `completion_reason = 'user_stopped'`로 닫고(남은 turn 취소, 실행 lease 해제), 중단 메시지까지의 메시지를 처리된 것으로 넘긴 뒤 "진행 중이던 작업을 중단했습니다."라고 한 번 답합니다.
- 멈출 것이 없으면 그 메시지는 평소처럼 에이전트에게 전달됩니다.
## 방 설정 모델
현재 room 설정의 기준은 다음과 같습니다.
- `room_settings`: room-level SSOT
- `room_role_overrides`: owner / reviewer / arbiter 역할별 override
- `paired_projects`: canonical project root
- `paired_workspaces`: 실제 owner / reviewer 실행 workspace
- `registered_groups`: 제거됨. 구버전 DB를 옮길 때 `setup/legacy-room-registrations.ts`가 입력으로만 읽음
운영적으로는:
- `single` → owner만 실행
- `tribunal` → owner + reviewer + optional arbiter
중요한 점:
- reviewer는 더 이상 snapshot copy를 기본 실행 경로로 쓰지 않습니다.
- reviewer는 owner의 현재 workspace를 direct mount로 읽습니다.
- stale reviewer workspace 레코드가 남아 있어도 실행 직전 owner 현재 경로로 재동기화됩니다.
## 아키텍처
```text
Discord ──► SQLite (WAL) ──► GroupQueue ──┬──► Owner (host process)
│ │
│ ▼
├──► Reviewer (host process, read-only)
│ │
│ verdict routing
│ ├─ DONE → finalize
│ ├─ feedback → owner loop
│ └─ BLOCKED → arbiter / user
│
├──► Arbiter (on-demand, fresh session)
│
IPC follow-up / host tools
│
┌────────── Router ──────────┐
▼ ▼
paired_turn_outputs Discord display
```
## 시작하기
### 요구사항
- Linux(Ubuntu 22.04+, systemd)
- [Bun](https://bun.sh/) 1.3+
- Claude Code CLI
- Codex CLI
- Discord 봇 토큰 3개(owner / reviewer / arbiter)
현재 runner 번들 기준 버전:
- Claude Agent SDK: `@anthropic-ai/claude-agent-sdk@0.3.286` (번들 Claude Code CLI 2.1.286 — Claude Opus 5.5는 CLI 2.1.280 이상 필요)
- Codex SDK/CLI: `@openai/codex@0.159.3`
### 설치
```bash
git clone https://git.tkrmagid.kr/claude-bot/EJClaw.git
cd EJClaw
bun install
bun run build:all
```
### 환경 설정
- `.env.example`를 기준으로 `.env`를 작성합니다.
- 전체 키 설명은 [docs/configuration.md](docs/configuration.md)를 봅니다.
- 최소한 아래는 먼저 채워야 합니다.
```bash
DISCORD_OWNER_BOT_TOKEN=
DISCORD_REVIEWER_BOT_TOKEN=
DISCORD_ARBITER_BOT_TOKEN=
CLAUDE_CODE_OAUTH_TOKEN=
OWNER_AGENT_TYPE=codex
REVIEWER_AGENT_TYPE=claude-code
```
### 실행
```bash
bun run dev
```
### 배포
```bash
bun run deploy
```
이 스크립트는 다음을 순서대로 수행합니다.
1. 최신 커밋 fast-forward pull
2. 전체 build
3. `migrate-room-registrations` 실행
4. `systemctl --user restart ejclaw`
주의: 운영 유닛은 `bun src/index.ts`로 src를 직접 실행하므로 루트 `dist/` 빌드는 서비스에 영향이 없습니다(runner의 `dist/`는 경로로 실행되므로 `bun run build:runners`가 필요). 또 에이전트 턴 안에서 `systemctl --user restart`를 직접 실행하면 에이전트 자신이 함께 종료되므로, 턴 안에서는 `systemd-run --user --collect … systemctl --user restart ejclaw.service`처럼 분리 실행해야 합니다.
## 개발
```bash
bun run build
bun run build:runners
bun run test
bun run typecheck
bun run check
```
## 문서
- [docs/architecture.md](docs/architecture.md) — 데이터 모델, 실행 흐름, 주요 파일
- [docs/configuration.md](docs/configuration.md) — `.env` 키와 디버깅 경로
- [docs/legacy-compat-removal-spec.md](docs/legacy-compat-removal-spec.md) — 레거시 제거 설계 문서(주요 결정은 반영 완료, 이력 참고용)
- [CHANGELOG.md](CHANGELOG.md) — 릴리즈 이력
## 라이선스
MIT