# AG Native 릴레이 아키텍처 분석

> **이 문서는 AG Native ↔ Discord 릴레이의 데이터 흐름 SSOT입니다.**
> 구현/디버깅 전 반드시 확인합니다.

---

## 1. 데이터 경로 요약

AG Native에서 Discord로 메시지를 전달하는 경로는 크게 2개:

| # | 경로 | 소스 | 실시간? | 상태 |
|---|------|------|---------|------|
| 1 | **Observer DOM** | workbench.html 인라인 스크립트 → DOM 관찰 → HTTP POST → http-bridge | ✅ 실시간 | AI 응답: ✅ 작동 (v0.5.72+), 사용자 메시지: ✅ 작동 (v0.5.74+) |
| 2 | **Step Probe (trajectory API)** | LS RPC `GetCascadeTrajectorySteps` → step 분석 | ❌ cascade 완료 후에만 | AI 응답: ❌ 실시간 불가, 사용자 메시지: ❌ 실시간 불가 |

### 1.1 핵심 API 제약 (2026-04-18 확인)

> [!CAUTION]
> **`GetCascadeTrajectorySteps`는 진행 중인 cascade의 step을 실시간으로 반환하지 않습니다.**
> step count는 cascade가 **완전히 종료**(IDLE 전환)된 후에만 업데이트됩니다.
> 따라서 Step Probe의 RT-CAPTURE, HB-CAPTURE 모두 **현재 진행 중인 대화에서는 작동하지 않습니다.**

**검증 데이터**:
- POLL에서 `status=CASCADE_RUN_STATUS_IDLE`, `steps=928`, `delta=0` 고정
- HEARTBEAT probe: `offset=927 got=1 real=928 known=928` → 변함 없음
- 실제로 수십 개의 tool call이 실행되었지만 step count 불변
- Cascade 종료 후 다음 poll에서 step count가 점프 (예: 733 → 865 → 928)

### 1.2 AG Native SDK EventMonitor

SDK에 이벤트 시스템이 있으나 **모두 polling 기반**:
- `EventMonitor.onStepCountChanged` — getDiagnostics 기반 polling
- `EventMonitor.onActiveSessionChanged` — state.vscdb 기반 polling
- **실시간 push (WebSocket/SSE)는 없음**
- 현재 상태: ERR_CONNECTION_REFUSED 문제로 비활성화됨

---

## 2. Observer DOM 경로 상세

### 2.1 Observer 스크립트 삽입 체인

```
extension.ts activate()
  → html-patcher.ts setupApprovalObserver()
    → observer-script.ts generateApprovalObserverScript(port)
      → workbench-jetski-agent.html에 인라인 <script> 삽입
        → AG 재시작 시 렌더러가 로드
```

### 2.2 Observer 주요 함수

| 함수 | 역할 |
|------|------|
| `scanChatBodies()` | 3초마다 실행, conversation view에서 메시지 블록 탐색 |
| `extractCleanStepText(el)` | DOM 클론 → style/script/button 제거 → textContent 추출 |
| `extractContextFromNearby(btn)` | 승인 버튼 주변 DOM에서 명령어 텍스트 추출 |
| `pollResponseGroup(rid, btnRefs)` | response 파일 polling → 버튼 자동 클릭 |

### 2.3 AI 응답 감지 셀렉터

```javascript
var responseBlocks = cv.querySelectorAll(
  '.leading-relaxed.select-text, '           // ← AI 응답 마크다운 블록 (주력)
  + '.text-ide-message-block-user-color, '   // ← 사용자 메시지 (미매칭)
  + '.text-ide-message-block-bot-color, '    // ← NUX tooltip 전용 (오매칭)
  + '.bg-ide-message-block-user-background, '// ← 사용자 메시지 (미매칭)
  + '[data-message-role="user"], '           // ← 사용자 메시지 (미매칭)
  + '[data-role="user"]'                     // ← 사용자 메시지 (미매칭)
);
```

> [!NOTE]
> **v0.5.74에서 사용자 메시지 셀렉터가 추가되었습니다.**
> AG Native 소스(`jetskiAgent/main.js`)의 `Esn` 컴포넌트 분석으로
> 사용자 메시지 CSS 클래스(`msn = "bg-gray-500/10 border border-gray-500/20 p-2 rounded-lg w-full text-sm select-text"`)를 식별.
> 셀렉터: `.select-text.rounded-lg`, 역할 판별: `rounded-lg` 있고 `leading-relaxed` 없으면 → user

### 2.4 AI 응답 추출 흐름

```
scanChatBodies() 3초 간격
  → cv = document.querySelector('#conversation')
  → responseBlocks = cv.querySelectorAll('.leading-relaxed.select-text, ...')
  → lastBlock = responseBlocks[last] (가장 최근 블록)
  → 이미 scrape 됐으면 skip
  → blockText = extractCleanStepText(lastBlock)
  → 안정화 대기 (3초 동안 텍스트 변경 없으면)
  → POST /chat { text, source, block_index, role }
  → http-bridge → writeChatSnapshot() → WS → Discord
```

### 2.5 Observer 업데이트 제약

> [!CAUTION]
> **Observer 코드는 workbench.html에 인라인 삽입됩니다.**
> extension reload만으로는 Observer 코드가 업데이트되지 않습니다.
> **AG 재시작 + V8 CachedData 삭제**가 필요합니다.
> (단, product.json 체크섬이 맞으면 CachedData 삭제 없이 AG 재시작만으로 충분할 수 있음)

---

## 3. 승인 버튼 (Auto-Approve) 경로

### 3.1 "Always run" 자동 승인 흐름

```
Observer DOM scan
  → "Always run" 버튼 텍스트 감지
  → POST /pending { command: "Always run", description: "...", buttons: [...] }
  → http-bridge _handlePending()
    → alwaysRunDetected = true
    → enrichment 시도:
      1. rawDesc에서 > 프롬프트 마커 찾기 → ✅ 성공 (buttons=2일 때 desc에 프롬프트 포함)
      2. rawDesc 최장 라인 사용 → buttons=1일 때 desc="Always run"이라 실패
      3. v20 fallback: bridge/pending/ 최신 파일에서 command 읽기 → Step Probe pending 있을 때만
    → response 파일 작성 → Observer pollResponseGroup → 버튼 클릭
    → WS sendPending { status: 'auto_approved', command: displayCmd }
    → Discord embed 표시
```

### 3.2 명령어 enrichment 현황 (2026-04-18 검증)

| 조건 | 결과 | 빈도 |
|------|------|------|
| Observer가 buttons=2 (`["Always run","Cancel"]`)이고 desc에 `>` 포함 | ✅ 명령어 표시 | ~50% |
| Observer가 buttons=1 (`["Always run"]`)이고 desc="Always run" | ❌ "Always run" 표시 | ~50% |

**로그 증거** (04:25:59):
```
AUTO-APPROVE raw: cmd="Always run" desc="…\extension > npm.cmd run compile..." buttons=["Always run","Cancel"]
→ cmd="npm.cmd run compile 2>&1; npm.cmd version patch..."  ✅ 성공

AUTO-APPROVE raw: cmd="Always run" desc="Always run" buttons=["Always run"]
→ cmd="Always run"  ❌ 실패
```

> buttons=2인 경우("Always run" + "Cancel")는 Observer가 code 블록을 찾아 description에 포함.
> buttons=1인 경우는 code 블록이 DOM에서 아직 렌더링되지 않았거나 접근 불가.

---

## 4. 사용자 메시지 릴레이 상태

### 4.1 현재 상태: ✅ 작동 (v0.5.74+)

| 경로 | 상태 | 비고 |
|------|------|------|
| Observer DOM | ✅ | `.select-text.rounded-lg` 셀렉터로 캡처 (v0.5.74) |
| Step Probe (trajectory API) | ❌ | cascade 진행 중 step 조회 불가 |
| Step Probe (observer [USER-MSG]) | ❌ | `lastUserInputStepIndex`가 갱신되지 않음 |

### 4.2 해결 방안

1. **DOM 덤프에서 사용자 메시지 클래스 식별** → Observer 셀렉터 추가
2. **Cascade 완료 후** Step Probe HB-CAPTURE에서 `USER_INPUT` step 캡처 (지연 릴레이)

---

## 5. 파일/포트 매핑

| 항목 | 값 |
|------|-----|
| Observer 삽입 대상 | `workbench-jetski-agent.html` |
| HTTP Bridge 포트 | `getDeterministicPort('gravity_control')` = **18080** |
| Extension 로그 | `~/.gemini/antigravity/bridge/extension.log` |
| Pending 파일 | `~/.gemini/antigravity/bridge/pending/*.json` |
| Response 파일 | `~/.gemini/antigravity/bridge/response/*.json` |
| Chat Snapshot 파일 | `~/.gemini/antigravity/bridge/chat_snapshots/*.json` |
| Discord 채널 | `#ag-gravity_control` (ID: 1483082084540223663) |
| Discord Bot 토큰 | `.env` → `DISCORD_TOKEN` |

---

## 6. 디버깅 도구

| 도구 | 경로 | 용도 |
|------|------|------|
| Discord 메시지 읽기 | `extension/scratch/discord_read.js` | API로 채널 최근 메시지 조회 |
| Discord 채널 목록 | `extension/scratch/discord_channels.js` | 서버 채널 목록 조회 |
| Extension 로그 확인 | `Select-String -Path $logFile -Pattern "패턴"` | 실시간 로그 분석 |
| DOM 구조 덤프 | Observer 자동 (CV-CHILDREN 로그) | AG Native DOM 클래스 식별 |

---

## 7. 버전 히스토리 (v0.5.67~)

| 버전 | 변경 | 결과 |
|------|------|------|
| v0.5.67 | Observer DOM relay 비활성화, Step Probe RT-CAPTURE로 전환 | ❌ API가 진행중 step 미반환 |
| v0.5.68 | auto-approve enrichment 디버그 로그 추가, 조건 >10 → >3 완화 | Observer가 desc="Always run" 보냄 확인 |
| v0.5.69 | pending 파일 fallback으로 auto-approve 명령어 enrichment | 일부 개선 (Step Probe pending 있을 때만) |
| v0.5.70 | heartbeat 로깅 강화 | API step count 동결 확인 |
| v0.5.71 | heartbeat 3 poll마다 실행, HB-CAPTURE 추가 | API가 진행중 step 미반환 재확인 |
| v0.5.72 | Observer DOM relay 재활성화 | AG 재시작 필요 (Observer HTML 캐시) |

---

## 8. 남은 작업 (TODO)

- [x] AG 재시작하여 Observer 반영 확인 — ✅ v0.5.72 작동 확인
- [x] Observer의 AI 응답 릴레이가 작동하는지 Discord에서 확인 — ✅ 작동
- [ ] v0.5.73 설치 (MSG-BLOCKS 로그 추가) → AG 재시작 → 사용자 메시지 DOM 클래스 식별
- [ ] 사용자 메시지 셀렉터 추가 후 테스트
- [ ] "Always run" enrichment 개선 — buttons=1일 때 code 블록 추출 개선
- [ ] AI 응답이 마지막 블록만 캡처되는 문제 개선 (전문 캡처)