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 릴레이 (⚠️ DEPRECATED — WS Hub 사용) (523줄)
│
├── ── Extension 측 (TypeScript) ──
├── extension/src/
│   ├── extension.ts         # 메인: SDK init, activate, 오케스트레이션 (650줄)
│   ├── step-probe.ts        # 폴링 + 응답 처리 + 승인 전략 (1,479줄)
│   │                        #   setupMonitor(), processResponseFile(),
│   │                        #   writePendingApproval(), tryApprovalStrategies()
│   ├── http-bridge.ts       # HTTP 서버 (Renderer↔Extension Host 통신) (280줄)
│   │                        #   startHttpBridge(), getDeterministicPort()
│   ├── html-patcher.ts      # AG HTML 패치 + product.json 체크섬 (280줄)
│   │                        #   setupApprovalObserver(), updateProductChecksums()
│   ├── command-handler.ts   # Discord→AG 명령어 처리 (175줄)
│   │                        #   watchCommandsDir(), handleWSCommand()
│   ├── 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, observer, command handler 시작
WS bridge	WSBridgeClient 통한 Hub 연결 (우선)
Status bar	SDK 상태 + 연결 상태 표시

3.4a HTTP Bridge (http-bridge.ts)

HttpBridgeContext 인터페이스로 extension.ts의 공유 상태 참조:

기능	설명
POST /pending	Renderer가 발견한 승인 버튼 보고
GET /response/:rid	Renderer가 Discord 응답 폴링
GET /trigger-click	Extension→Renderer 클릭 트리거
GET/POST /deep-inspect*	DOM 심층 검사
getDeterministicPort	프로젝트명 기반 결정적 포트

3.4b HTML Patcher (html-patcher.ts)

기능	설명
setupApprovalObserver	AG Workbench HTML 파일에 observer 스크립트 인라인 삽입
updateProductChecksums	product.json SHA256 체크섬 업데이트 (vscode-file:// 프로토콜용)
CSP 패치	script-src에 'unsafe-inline' 추가
.orig 백업	최초 패치 전 원본 백업, 손상 시 자동 복구

3.4c Command Handler (command-handler.ts)

CommandHandlerContext 인터페이스로 extension.ts 상태 참조:

기능	설명
watchCommandsDir	commands/ 디렉토리 fs.watch + 3s 폴링
handleWSCommand	WS Hub 경유 명령어 처리
!stop, !auto	AG 에이전트 제어 명령어
텍스트 전달	Discord → AG sendPromptToAgentPanel

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, setClickTrigger, recentDiscordSentTexts, writeChatSnapshot, writeChatSnapshotWithFiles, workspaceUri, diffReviewMetadata, sessionStalled, lastPendingStepIndex, stallProbed, sawRunningAfterPending

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", 8초 지연)
  → Discord (Accept all / Reject all 버튼)
  → 응답 → handleDiffReviewResponse()
     → openReviewChanges → 파일별 포커스 → agentAcceptAllInFile VS Code 커맨드

Important

diff_review는 VS Code 커맨드만 유효합니다. RPC 방식(AcknowledgeCascadeCodeEdit 등)은 모두 실패 확정. 상세 경위는 known-issues-archive.md의 "Diff Review 관련" 섹션을 참조하세요.

---

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	✅	❌	⚠️ DEPRECATED — 레거시 Collector (WS Hub 사용 권장)

---

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 등록 코드	(서버에서 발급)