Files
EJClaw/docs/architecture.md
Codex f127ac7a2b refactor: remove the main room concept
No room has room_settings.is_main = 1, so every main-only path was dead,
and admin work is done from the host shell. Each room's agent may now
only act on its own room:

- IPC: messages/inbound injection only to the source room; schedule,
  update, pause, resume and cancel only for the source room's tasks;
  drop the assign_room and refresh_groups IPC tasks and the deps they
  needed (assignRoom/syncGroups/getAvailableGroups/writeGroupsSnapshot)
- DB/host evidence is always scoped to the source group folder
- runner MCP server: drop the assign_room tool, the target_group_jid
  parameters and the isMain flag; list_tasks shows only the room's tasks
- drop EJCLAW_IS_MAIN, RunnerInput.isMain and AgentInput.isMain; the
  global CLAUDE.md memory is now included for every room
- drop the available_groups.json snapshot (available-groups.ts), the
  inferred restart announcement that only went to the main room, and
  the unused Channel.syncGroups hook
- setup register: drop --is-main; deregister-room: drop the main-room
  refusal and --force, and fix its unknown[] binding type error
- remove the groups/main/ template

The room_settings.is_main column and migrations are untouched; new rows
get the column default (0) and nothing reads it anymore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 19:37:29 +09:00

6.3 KiB

아키텍처

서비스 구성

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가 입력으로만 읽음)

실행 흐름

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를 수행

주요 파일

파일 역할
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