gravity_control/.agents/references/architecture.md

Architecture

AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.

1. 프로젝트 개요

Gravity Control은 Antigravity AI 코딩 에이전트와 Discord를 실시간으로 연결하는 브릿지 시스템이다.

핵심 목적

• AI 에이전트의 승인 요청(코드 실행, 파일 수정 등)을 Discord로 전달하고 사용자 응답을 반환
• AI 에이전트의 작업 스냅샷(대화 요약, 진행 상황)을 Discord에 실시간 표시
• 코드 리뷰(diff review) accept/reject을 Discord에서 처리
• 사용자의 Discord 명령어(!approve, !reject, !auto 등)를 AG Extension으로 전달
• Auto-approve 모드로 무인 작업 지원

시스템 구성

┌────────────────┐     WebSocket     ┌──────────────┐     Discord API     ┌─────────┐
│  VS Code       │◄──────────────────►│  Hub Server  │◄───────────────────►│ Discord │
│  AG Extension  │   type:auth/chat   │  (hub.py +   │   discord.py bot    │ 서버    │
│  (TypeScript)  │   /pending/resp    │   gateway.py)│                     │         │
└────────────────┘                    └──────────────┘                     └─────────┘
    ↕ AG SDK (RPC)                         ↕
┌────────────────┐                    ┌──────────────┐
│  Antigravity   │                    │  파일 bridge  │ ← 레거시 fallback
│  AI Engine     │                    │  (bridge.py)  │   (WS 미사용 시)
└────────────────┘                    └──────────────┘

---

2. 디렉토리 구조

gravity_control/
├── main.py                  # 진입점: Bot + Hub + Watcher 통합 시작
├── config.py                # 환경변수 + .env 로드 (66줄)
│
├── ── 서버 측 (Python) ──
├── bot.py                   # Discord 봇: 승인 UI, 채널 관리, Hub 핸들러 (1,286줄)
├── hub.py                   # WebSocket Hub: 연결 관리, 메시지 라우팅 (580줄)
├── auth.py                  # JWT 토큰 + registration code 인증 (127줄)
├── gateway.py               # HTTP REST API + /ws endpoint (310줄)
├── bridge.py                # 파일 기반 IPC (레거시 fallback) (479줄)
├── watcher.py               # Brain 디렉토리 변경 감시 (290줄)
├── parser.py                # Markdown → Discord 변환 (245줄)
├── collector.py             # 원격 파일→HTTP 릴레이 (Phase 2 삭제 예정) (517줄)
│
├── ── Extension 측 (TypeScript) ──
├── extension/src/
│   ├── extension.ts         # 메인: SDK init, activate, HTTP bridge (1,290줄)
│   ├── step-probe.ts        # 폴링 + 응답 처리 + 승인 전략 (1,435줄)
│   │                        #   setupMonitor(), processResponseFile(),
│   │                        #   writePendingApproval(), tryApprovalStrategies()
│   ├── observer-script.ts   # DOM Observer 스크립트 생성 (698줄)
│   │                        #   generateApprovalObserverScript()
│   ├── ws-client.ts         # WSBridgeClient: Hub 연결, 재연결, 큐 (505줄)
│   ├── step-utils.ts        # Step 파싱 순수 함수 4개 (114줄)
│   │                        #   extractPlannerText, filterEphemeral,
│   │                        #   extractToolCommand, extractToolDescription
│   └── sdk/                 # Antigravity SDK 로컬 임베드
│       ├── index.js         # SDK 런타임 (4,014줄)
│       └── index.d.ts       # SDK 타입 정의 (2,297줄)
│
├── ── 테스트 ──
├── tests/
│   ├── test_ws_hub.py       # Hub WS 연결 테스트
│   └── test_syntax.py       # Python 구문 검증
│
├── ── 문서 / 설정 ──
├── .env                     # 환경변수 (git 제외)
├── .agents/references/      # AI 에이전트 레퍼런스
├── docs/devlog/             # 작업 로그
└── start_bot.bat            # 윈도우용 봇 시작 스크립트

---

3. 핵심 모듈 상세

3.1 Hub (hub.py) — WebSocket 메시지 허브

역할: Extension ↔ Bot 간 실시간 양방향 통신 중계

기능	설명
연결 관리	프로젝트별 다중 인스턴스, 인스턴스 번호 자동 부여
JWT 인증	registration_code → JWT 발급 → 이후 토큰 재인증
메시지 라우팅	pending, chat, register, auto_resolve, brain_event
응답 역라우팅	request_id → pending_owners → 원본 Extension으로 전달
Rate limiting	per-connection 100msg/10s
Dedup	msg_id 기반 60s TTL 중복 제거
Heartbeat	30s 간격 ping/pong

프로토콜:

1. Client → Server: {type:"auth", registration_code/token, project, pc}
2. Server → Client: {type:"auth_ok", conn_id, instance_number, session_token}
3. 양방향 메시지 교환:
   - Extension→Hub: pending, chat, register, auto_resolve, brain_event
   - Hub→Extension: response, command, instance_update, error

3.2 Auth (auth.py) — 인증 관리

기능	설명
Registration Code	사전 공유 코드로 최초 인증
JWT 발급	HMAC-SHA256, 24시간 유효
토큰 검증	만료/위조 감지, 프로젝트+PC 메타데이터 포함

3.3 Bot (bot.py) — Discord 인터페이스

기능	설명
승인 UI	Approve/Reject 버튼, diff_review Accept/Reject
Auto-approve	!auto 토글, 세션 간 초기화
채널 관리	#ag-{project} 자동 채널 매칭
스냅샷 전달	2000자 초과 시 파일 첨부
명령어	!approve, !reject, !auto, !status, !send
Hub 연동	on_hub_pending, on_hub_chat, on_hub_register 핸들러
IDLE 알림	AI step 종료 시 Discord 알림

3.4 Extension (extension.ts) — VS Code 확장

기능	설명
AG SDK 연동	getCascadeStatus, getAllTrajectories RPC
세션 감지	activeSessionId 자동 추적
프로젝트 자동 감지	git remote URL 기반
HTTP bridge	파일 기반 pending/response 읽기쓰기 (레거시)
WS bridge	WSBridgeClient 통한 Hub 연결 (우선)
Status bar	SDK 상태 + 연결 상태 표시

3.5 Step Probe (step-probe.ts) — 상태 폴링

BridgeContext 인터페이스로 extension.ts와 상태 공유:

기능	설명
setupMonitor	3초 간격 SDK 폴링, 세션/step 변화 감지
processResponseFile	Discord 응답 → AG RPC 실행
writePendingApproval	승인 요청 파일/WS 전송
tryApprovalStrategies	다단계 승인: DOM click → VS Code command → RPC
setupResponseWatcher	response/ 디렉토리 파일 감시

BridgeContext 필드 (14개): bridgePath, projectName, sdk, wsBridge, logToFile, autoApproveEnabled, activeSessionId, sentPendingIds, deterministicPort, recentDiscordSentTexts, writeChatSnapshot, writeChatSnapshotWithFiles, workspaceUri, diffReviewMetadata

3.6 WS Client (ws-client.ts) — Hub 클라이언트

기능	설명
연결 관리	WebSocket + 자동 재연결
Backoff	1s→60s 지수 백오프 + ±30% jitter
메시지 큐	200개 버퍼, 재연결 시 자동 flush
Heartbeat	25s 간격 ping
인증	registration_code 또는 session_token
API	sendPending, sendChat, sendRegister, sendAutoResolve

3.7 Observer Script (observer-script.ts)

AG Webview의 DOM을 관찰하여 승인 버튼을 자동 감지/클릭:

• MutationObserver로 .actions-container 감시
• 버튼 텍스트 매칭으로 Approve/Reject 자동 실행
• postMessage로 Extension과 통신

3.8 Step Utils (step-utils.ts)

순수 함수 4개:

• extractPlannerText(content) — AI 응답 텍스트 추출
• filterEphemeral(text) — 시스템 메시지 필터링
• extractToolCommand(content) — 도구 명령어 추출
• extractToolDescription(content) — 도구 설명 추출

---

4. 데이터 흐름

4.1 승인 요청 플로우

AG Engine → SDK RPC → Extension(step-probe.ts)
  → setupMonitor: WAITING step 감지
  → writePendingApproval: pending 데이터 생성
  → [WS] wsBridge.sendPending() → Hub → Bot → Discord (버튼 UI)
  → [파일] bridge/pending/{id}.json (fallback)

4.2 승인 응답 플로우

Discord (사용자 버튼 클릭) → Bot
  → [Hub connected] Hub.route_response() → WS → Extension
  → [File fallback] bridge/response/{id}.json → setupResponseWatcher
  → processResponseFile → tryApprovalStrategies
     1차: DOM observer script (webview inject)
     2차: VS Code command (cascade.approveCurrentStep)
     3차: Direct RPC (acknowledgeCodeActionStep)

4.3 채팅 스냅샷 플로우

Extension(step-probe.ts) → 새 step 텍스트 감지
  → writeChatSnapshot(text) → truncation + dedup
  → [WS] wsBridge.sendChat() → Hub → Bot → Discord (#ag-{project})
  → [파일] bridge/pending/ snapshot 파일 (fallback)

4.4 Diff Review 플로우

AG Engine → 파일 수정 → Extension(step-probe.ts)
  → edit_step_indices + modified_files 메타데이터 수집
  → writePendingApproval (step_type="diff_review")
  → Discord (Accept all / Reject all 버튼)
  → 응답 → acknowledgeCodeActionStep RPC

---

5. 통신 프로토콜

5.1 WebSocket 메시지 타입

Extension → Hub (upstream):

type	data 필드	설명
auth	registration_code/token, project, pc	최초 인증
pending	request_id, command, description, buttons	승인 요청
chat	content, attached_files, conversation_id	채팅 스냅샷
register	conversation_id, project_name	세션 등록
auto_resolve	request_id	자동 해결 알림
brain_event	(payload)	브레인 이벤트
heartbeat	-	연결 유지

Hub → Extension (downstream):

type	data 필드	설명
auth_ok	conn_id, instance_number, session_token	인증 성공
auth_fail	reason	인증 실패
response	request_id, approved, button_index	승인 응답
command	text, action	Discord 명령어
instance_update	active_count, instances[]	인스턴스 변경
error	error	에러

5.2 BOT_MODE 동작 차이

모드	Watcher	Hub/Gateway	용도
local	✅ (brain 감시)	❌	로컬 개발 (Extension과 같은 PC)
gateway	❌	✅ (port 8585)	서버 배포 (WS Hub + Gateway)
remote	✅	❌	원격 브릿지 (레거시 Collector)

---

6. 보안

항목	구현
WS 인증	Registration Code → JWT (HMAC-SHA256, 24h)
Gateway API	API Key 헤더 (X-API-Key)
Rate limit	per-connection 100msg/10s
메시지 dedup	msg_id 기반 60s TTL
Discord	Bot 토큰 + Guild ID 제한

---

7. Extension 설정 (VS Code)

설정 키	설명	기본값
gravityBridge.bridgePath	Bridge 디렉토리 경로	~/.gemini/antigravity/bridge
gravityBridge.projectName	프로젝트 이름	git remote 자동 감지
gravityBridge.hubUrl	WebSocket Hub URL	(비어있으면 WS 비활성)
gravityBridge.registrationCode	Hub 등록 코드	(서버에서 발급)