base-schema.ts now holds the full schema at version 22, taken from the
production database (column order, indexes, provenance triggers), so a
fresh database is identical to the live one. Previously a fresh DB
differed: it had an extra idx_messages_chat_timestamp index and a
different column order in paired_tasks and paired_turn_outputs.
The migration runner keeps schema_migrations:
- empty DB: apply the baseline and record version 22 ('baseline')
- existing DB: must already be at version >= 22 (the live DB records
1-22), otherwise startup refuses it without touching it
- later migrations (23+) run once each inside a transaction
Removed the 22 historical migrations, the legacy schema bundle, the
paired-turn provenance rebuild/backfill helpers that migration 10 replayed
on every start (all no-ops on the live DB), legacy session migration
helpers, the unused service handoff metadata helpers, and the tests that
only exercised legacy-schema upgrades. New schema tests check a fresh DB
against a snapshot dumped from production and that reopening a DB at the
baseline changes neither schema nor data.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.7 KiB
6.7 KiB
아키텍처
서비스 구성
EJClaw는 단일 ejclaw 서비스가 세 Discord 봇과 paired runtime을 함께 운영하는 구조입니다.
ejclaw.service: 단일 unified process- Discord 봇:
DISCORD_OWNER_BOT_TOKENDISCORD_REVIEWER_BOT_TOKENDISCORD_ARBITER_BOT_TOKEN
- 저장소:
store/: SQLite DBgroups/: 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가 보는 실행 경로는:
paired_projects.canonical_work_dir같은 canonical root와 별개로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 |