multi-agent-mux/SKILL_FEATURES.md

Multi-Agent Mux: Skill Features and Architecture

이 문서는 multi-agent-mux 워크스페이스 내에 구현된 6개의 개별 스킬 및 공통 라이브러리의 핵심 기능, 상태 머신, CLI 사양, 그리고 상호 연동 방식을 종합 정리한 명세입니다. 스킬 최적화 및 팩토링 작업의 기준서로 사용됩니다.

---

1. 아키텍처 개요 (Architecture Overview)

multi-agent-mux는 다중 자율 에이전트(Claude, Agy, Cline, Hermes 등)를 격리된 Tmux 세션 환경에서 관리하고 상호 통신할 수 있게 돕는 시스템입니다.

• 중앙 상태 레지스트리: .mam/agent-sessions.yaml 및 동기화된 .mam/agent-sessions.db (SQLite3)
• 격리 소켓: 독립된 tmux 서버 소켓 지정 구동 가능 (예: multi-agent-mux 서버)
• 이벤트 버스: MQTT 프로토콜 기반의 실시간 작업 상태 비동기 관찰 (multi-agent-mux-delegate-job)

---

2. 공통 라이브러리: lib.sh (Common Library)

모든 스킬 스크립트가 로드하여 사용하는 핵심 공유 헬퍼 라이브러리입니다.

• 상태 파일 원자적 덤프 (atomic_dump_yaml):
  • NFS(네트워크 파일 시스템) 감지 시 SQLite PRAGMA journal_mode=DELETE 폴백, 로컬 환경에서는 PRAGMA journal_mode=WAL 설정.
  • 독점 잠금(BEGIN IMMEDIATE)을 활성화해 멀티프로세스 환경에서 Read-Modify-Write 데이터 유실(lost update race condition) 방지.
  • 트랜잭션 커밋 완료 후 .bak 백업 파일 생성 및 임시파일 생성 후 os.replace 원자적 대체 기법 적용.
• 에이전트 세션 실재성 판단 (*_exists 함수군):
  • claude: 프로젝트 디렉터리 하위 <uuid>.jsonl 존재성
  • agy: .gemini/antigravity-cli/conversations/<uuid>.db 존재성
  • hermes: ~/.hermes/state.db의 sessions 테이블 내 존재성 (SQLite 쿼리 검증)
  • cline: .cline/data/sessions/<uuid>/<uuid>.json 존재성
• 세션 ID 해석 엔진 (find_workspace_uuid 분기 구조):
  • Tier 1 (YAML 직접 조회): YAML 내 기록된 에이전트별 전용 필드(claude_session_id_own 등) 조회.
  • Tier 2 (디스크 잔해 스캔): 워크스페이스 디렉터리(cwd / workspace_root)와 매칭되는 디스크 상의 세션 로그 중 가장 최근 수정일(mtime) 기준 정렬 후 최신 UUID 반환.
  • Tier 3 (아이덴티티 캐시): 레지스트리 상단 agent_identities 캐시 데이터 연동.

---

3. 스킬별 상세 핵심 기능 (Skill Specifications)

3.1. multi-agent-mux-create (생성 스킬)

• 용도: 신규 에이전트 동작용 격리된 Tmux 컨테이너 생성 및 레지스트리 신규 등록.
• 핵심 기능:
  • 사전 기능 검증 (Preflight Check):
    • claude: claude auth status를 통한 로그인 상태("loggedIn": true) 검증
    • agy: agy models를 통한 API 연동 정상 상태 검증
    • hermes: hermes status를 통한 연동 상태 검증
    • cline: cline history --json 동작 및 설정 상태 사전 검증
  • Tmux 세션 생성 및 초기화: 에이전트별 최적화된 화면 크기(-x 140 -y 40) 및 작업 디렉터리(-c)를 적용해 세션 백그라운드 생성.
  • 초기 상태 YAML 등록: status: running, pane 세부정보(인덱스, PID, CWD, CMD_FULL), 시작 명령 및 mcp_attachments 기록.

3.2. multi-agent-mux-resume (재개 스킬)

• 용도: 중지되었거나 유실된 에이전트의 이전 컨텍스트 그대로 Tmux 세션 및 TUI 연결 복원.
• 핵심 기능:
  • 세션 ID 해석 위임: lib.sh::find_workspace_uuid을 구동하여 대상 워크스페이스의 UUID 확인.
  • 세션 복원 기동:
    • claude: claude --dangerously-skip-permissions -r <UUID>
    • agy: agy --dangerously-skip-permissions --conversation <UUID>
    • hermes: hermes --resume <UUID>
    • cline: cline -i --id <UUID>
  • TUI 바이패스 자동화 (Claude): 기동 직후 백그라운드에서 Enter ➔ Down ➔ Enter 키스트로크를 주입하여 권한 우회 및 복구 확인 대화상자 자동 수락.
  • 동기화: update_yaml_resumed.sh를 구동해 상태를 running으로 전이하고 기동 시점에 맞춘 하위 자식 PID 갱신 및 기존 종료 메타데이터 제거.

3.3. multi-agent-mux-stop (종료 스킬)

• 용도: 세션을 안전하게 정리하고, 상태 및 UUID를 안전하게 저장 및 동기화.
• 핵심 기능:
  • 종료 전 TUI 스냅숏 저장: tmux capture-pane을 수행해 최종 화면 상태를 last_visible_status_at_termination 필드에 보존.
  • 다단계 Graceful 종료 프로토콜:
    1. TUI 안전 종료 키스트로크 주입 (/exit 또는 Exit) 후 3초 대기.
    2. 생존 시 tmux kill-session 전송 및 5초 대기.
    3. 최후 수단으로 감지된 자식 PID에 kill -9 전송.
  • 디스크 소거 (--purge-conversation):
    • resumable을 false로 설정하고 상태를 terminated로 기록.
    • 에이전트별 데이터 경로에 접근해 해당 세션 파일 파쇄.
      • claude: <proj-key>/<uuid>.jsonl 삭제
      • agy: conversations/<uuid>.db 및 brain/<uuid> 폴더 삭제
      • hermes: sessions/session_<uuid>.json 삭제 및 state.db 내 이력 삭제 (내부 독자 커넥션 hconn 사용으로 상위 YAML DB 충돌 차단)
      • cline: ~/.cline/data/sessions/<uuid> 폴더 소거

3.4. multi-agent-mux-delegate-job (위임 스킬)

• 용도: 타 에이전트에게 비동기적으로 작업을 위임하고, MQTT 이벤트로 실행 상태 관찰.
• 핵심 기능:
  • 작업 지시 유형 (Delegation Types):
    • direct (기본값): 단일 타겟 세션 기동 후 작업 전달 및 대기.
    • loop (협업 루프): 구현자(Worker)의 작업 완료 후 검토자(Reviewer)가 코드 검수를 수행하여 "PASS" 의견이 나올 때까지 작업 수정을 자동 반복 지시.
    • discuss (토론/합의): 두 에이전트 간 공동 토론을 추진하여 최종 기획 및 계획 합의 도출.
  • MQTT 이벤트 규격: publish_event.py와 job_subscriber.py를 매핑하여 started ➔ permission_required ➔ progress ➔ completed/error 상태 전이 추적 및 자동 이중 타임아웃 검사 (전체 실행 예산 3600초 + 120초 유휴 타임아웃).
  • 감사 로그 기록: .mam/delegate_job_logs/<job_id>/에 meta.json, status.json 및 원시 NDJSON 형식의 events.ndjson을 영속 기록.

3.5. multi-agent-mux-status (현황 스킬)

• 용도: 레지스트리를 읽어와 실행 중인 모든 에이전트의 구동 세션 현황을 즉시 표기.
• 핵심 기능:
  • 읽기 전용 안정성: DB 수정이나 상태 전이 유발 없이 순수 조회만 수행.
  • 실시간 tmux 프로세스 상태 정보와 YAML 간의 이름 매핑 정합성을 검증하여 콘솔에 요약 출력.

3.6. multi-agent-mux-monitor (화해 스킬)

• 용도: 운영체제 Tmux 런타임과 YAML 레지스트리 데이터 불일치를 백그라운드 루프로 감지해 자동 화해(Reconciliation) 처리.
• 핵심 기능:
  • Drift 감지 및 복구 매뉴얼:
    • Drift A (Crash/죽은 세션): YAML 상 running이나 실제 tmux 프로세스가 죽은 경우 감지 ➔ 상태를 terminated로 격하 조정.
    • Drift B (새 세션 감지): YAML에 없으나 tmux 상에 임의로 떠 있는 *-creator-* 세션을 레지스트리에 자동 등록 및 자식 PID 정보 갱신.
    • Drift C (실시간 UUID 갱신): 새로 시작된 에이전트가 첫 명령을 받아 세션 ID를 생성했을 때, 디스크 상의 세션 로그 중 가장 수정시간이 일치하는 최신 UUID를 찾아 *_conversation_id_own 필드에 주입.
    • Drift D (캐시 정합성 점검): 레지스트리 및 캐시 상의 세션 UUID가 실제 디스크에 존재하는지 검사하여 소거된 세션을 리포트.

---

4. 에이전트 상태 머신 (Agent State Machine)

시스템 전반에 걸쳐 에이전트 세션은 아래 흐름을 따라 전이됩니다.

stateDiagram-v2
    [*] --> running : multi-agent-mux-create / Drift B
    running --> stopped : multi-agent-mux-stop (default)
    running --> terminated : multi-agent-mux-stop (--purge-conversation) / Drift A
    stopped --> running : multi-agent-mux-resume
    terminated --> [*]

5. 최적화 및 팩토링 작업 시 주의 사항

1. 원자적 쓰기 무력화 금지: lib.sh에 설정된 atomic_dump_yaml은 다중 에이전트 병렬 기동 시 데이터 꼬임을 막는 중추 역할을 합니다. DB 잠금 및 트랜잭션 흐름을 훼손하지 않아야 합니다.
2. Cline 및 Claude의 TUI 입력 바인딩 유지: 세션 재개나 중지 시, 각 에이전트가 내부적으로 사용하는 프롬프트 제어 명령어(예: /exit, --id <session>)의 세세한 차이를 유지해야 예외 없이 동작합니다.
3. 데이터베이스 변수 충돌 주의: 서브셸 또는 인라인 Python 스크립트 실행 시 전역 SQLite 커넥션(conn)의 이름 공간을 절대 오염시키지 마십시오. (예: stop_session.sh 버그 재발 방지).