# 아키텍처 ## 서비스 구성 EJClaw는 단일 `ejclaw` 서비스가 세 Discord 봇과 paired runtime을 함께 운영하는 구조입니다. - `ejclaw.service`: 단일 unified process - Discord 봇: - `DISCORD_OWNER_BOT_TOKEN` - `DISCORD_REVIEWER_BOT_TOKEN` - `DISCORD_ARBITER_BOT_TOKEN` - 저장소: - `store/`: SQLite DB - `groups/`: room별 로그 / 메모리 / 설정 - `data/`: 세션, worktree, 런타임 보조 데이터 - SQLite는 WAL + `busy_timeout=5000` 기준으로 동작 ## 핵심 데이터 모델 | 구성 요소 | 역할 | | --- | --- | | `room_settings` | room-level SSOT | | `room_role_overrides` | 역할별 agent type / agentConfig override | | `paired_projects` | canonical project root (`canonical_work_dir`) | | `paired_tasks` | paired runtime의 상태 머신 | | `paired_workspaces` | owner / reviewer의 실제 실행 workspace 경로 | 현재 기준에서 중요한 점: - room 설정의 기준은 `room_settings` - reviewer / arbiter는 room의 공개 진입점이 아니라 내부 역할 - `registered_groups` 테이블은 제거됨(구버전 DB 이전 시 `setup/legacy-room-registrations.ts`가 입력으로만 읽음) ## 실행 흐름 ```text Discord ──► SQLite (WAL) ──► GroupQueue ──┬──► Owner (host process) │ │ │ ▼ ├──► Reviewer (host process, read-only) │ │ │ verdict routing │ ├─ DONE → owner finalize │ ├─ feedback → owner loop │ └─ BLOCKED → arbiter / user │ ├──► Arbiter (on-demand) │ IPC polling / host tools │ ┌────────── Router ──────────┐ ▼ ▼ paired_turn_outputs Discord display ``` ## 방 격리와 작업 중단 - 모든 방은 동등합니다. main(관리) 방 개념은 없으며, 각 방의 에이전트가 IPC로 할 수 있는 일(메시지 전송·inbound 주입, 예약 작업 생성/수정/일시정지/취소, DB·호스트 증거 조회)은 자기 방(같은 group folder)으로만 제한됩니다. 방 등록/변경은 호스트 셸(`setup --step register`, `scripts/deregister-room.ts`)에서 합니다. - 사람이 "그만"·"멈춰"·"stop" 같은 중단 의도만 담긴 짧은 메시지를 보내면 메시지 루프(`src/message-runtime-dispatch.ts` → `src/room-stop.ts`)가 가로채, 커서를 그 메시지까지 넘기고 열린 paired task를 `user_stopped`로 닫은 뒤 `GroupQueue.closeStdin`(사유 `user-stop`) + `killProcess`로 실행 중인 에이전트를 끝냅니다. 판정 규칙은 `src/stop-intent.ts`에 있습니다. ## 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 교착 시 판정 | 역할별 model / effort는 전역 env(`OWNER_*`, `REVIEWER_*`, `ARBITER_*`)로 정하고, room-level `agentConfig`는 provider별(`claudeModel`, `codexModel`) override만 제공합니다. ## Reviewer / Arbiter runtime - reviewer는 owner의 현재 workspace를 direct mount로 읽습니다 - snapshot copy는 현재 기본 실행 경로가 아닙니다 - reviewer workspace 레코드가 오래된 경로를 가리키면 실행 직전에 owner 현재 workspace로 재동기화합니다 - arbiter는 reviewer와 같은 read-only workspace를 쓰되, 세션 디렉토리는 매 호출마다 fresh하게 준비합니다 즉 reviewer가 보는 실행 경로는: 1. `paired_projects.canonical_work_dir` 같은 canonical root와 별개로 2. `paired_workspaces.workspace_dir`에 저장된 실제 owner worktree 입니다. ## 세션 / 프롬프트 구성 - owner는 stable worktree + stable session을 사용 - reviewer / arbiter는 read-only 세션 디렉토리를 매 실행 전에 다시 준비 - `prepareReadonlySessionEnvironment()`가 `CLAUDE.md`, `.codex/AGENTS.md`, 설정 파일을 매번 재생성 - 그래서 reviewer 관련 프롬프트 / workspace 변경은 기존 실행 중 프로세스에는 즉시 적용되지 않지만, **다음 reviewer 턴부터는 자동 반영**됩니다 ## 검증 / 운영 경로 - 검증 명령은 `bun run check` 하나로 묶여 있음 - format - typecheck - test - build - reviewer / arbiter가 직접 로컬 빌드를 못 돌려도, host verification 경로로 `typecheck`, `test`, `build`를 수행할 수 있음 - startup precondition은 전용 오류로 올리고, setup이 생성하는 유닛은 `RestartPreventExitStatus=78`로 crash loop를 막음(현재 운영 호스트의 `ejclaw.service`는 수동 작성 유닛으로 `bun src/index.ts`를 실행하며 이 줄이 없고, 로그는 journald로 감) - deploy는 `migrate-room-registrations`를 선행한 뒤 service restart를 수행 - DB 스키마: 과거 마이그레이션 1~22는 `src/db/base-schema.ts`(기준 버전 22) 하나로 합쳐짐. 새 DB는 이 스키마로 만들고, 기존 DB는 `schema_migrations` 최대 버전이 22 이상이어야 열림(그보다 오래된 DB는 시작 시 거부). 스키마 변경은 `src/db/migrations/index.ts`에 23번부터 마이그레이션을 추가하고 `src/db/schema.snapshot.sql`을 갱신 ## 주요 파일 | 파일 | 역할 | | --- | --- | | `src/index.ts` | 전체 오케스트레이션 진입점 | | `src/message-runtime.ts` | 메시지 루프, paired flow 연결 | | `src/room-stop.ts`, `src/stop-intent.ts` | 자연어 작업 중단 | | `src/message-turn-controller.ts` | progress / final delivery 제어 | | `src/paired-execution-context.ts` | owner / reviewer / arbiter 실행 준비 | | `src/paired-workspace-manager.ts` | owner / reviewer workspace 관리 | | `src/agent-runner.ts` | host process spawn, env/session wiring | | `src/db.ts` | 런타임 DB facade | | `src/db/` | canonical room / paired state / migration 로직 | | `runners/agent-runner/` | Claude Code runner | | `runners/codex-runner/` | Codex runner | | `setup/` | setup / verify / service rendering |