# Vercel agent-browser 심층 분석 보고서

> 분석일: 2026-03-17
> 대상: https://github.com/vercel-labs/agent-browser (v0.20.14)
> 분석자: 아누(Anu)

---

## 1. 프로젝트 개요

**agent-browser**는 AI 에이전트를 위한 headless 브라우저 자동화 CLI. Vercel Labs에서 개발. Apache-2.0 라이선스.

**핵심 철학**: AI 에이전트가 웹 브라우저를 도구로 사용할 수 있도록, CLI 명령어 기반의 인터페이스를 제공. Playwright/Puppeteer와 달리 **프로그래밍 언어 SDK 없이 순수 CLI 명령어**만으로 브라우저를 제어.

**기술 스택**:
- **CLI**: Rust (네이티브 바이너리)
- **데몬**: Rust (tokio 비동기 런타임)
- **브라우저 통신**: CDP(Chrome DevTools Protocol) 직접 구현
- **브라우저 엔진**: Chrome for Testing / Lightpanda 지원
- **배포**: npm, Homebrew, Cargo, Docker

---

## 2. 아키텍처 분석

### 2.1 3-레이어 아키텍처

```
[AI 에이전트 / CLI 사용자]
        |
        v
[Rust CLI (cli/src/main.rs)]  ── 명령어 파싱, 유효성 검증, 출력 포맷팅
        |
        v  (Unix Socket / TCP)
[Rust 데몬 (cli/src/native/daemon.rs)]  ── 상태 관리, 세션 관리
        |
        v  (WebSocket + CDP)
[Chrome / Lightpanda 브라우저]  ── 실제 웹 페이지 조작
```

### 2.2 CLI-데몬 분리 패턴 (핵심 아키텍처)

**CLI 프로세스** (매 명령마다 실행/종료):
- `main.rs`: 인자 파싱, 플래그 처리
- `commands.rs`: 명령어를 JSON 메시지로 직렬화
- `connection.rs`: 데몬에 소켓 연결, 재시도 로직
- `output.rs`: 응답을 사람/JSON 형식으로 출력

**데몬 프로세스** (백그라운드 상주):
- `daemon.rs`: Unix Socket 서버, 세션 라이프사이클
- `actions.rs`: 195KB+ 핵심 모듈, 모든 브라우저 명령 실행
- `browser.rs`: Chrome/Lightpanda 론칭, CDP 연결 관리
- `state.rs`: 쿠키/스토리지 저장/복원, AES-256-GCM 암호화

### 2.3 모듈 구조 (cli/src/native/)

| 모듈 | 역할 | 크기 |
|------|------|------|
| `actions.rs` | 전체 명령어 실행 엔진 | 195KB (최대) |
| `browser.rs` | 브라우저 프로세스 관리 | 53KB |
| `snapshot.rs` | 접근성 트리 → 텍스트 변환 | 32KB |
| `element.rs` | Ref 시스템, 요소 해석 | 대형 |
| `interaction.rs` | 클릭/입력/스크롤 등 조작 | 31KB |
| `network.rs` | 도메인 필터, 네트워크 제어 | 중형 |
| `policy.rs` | 행동 정책 (allow/deny/confirm) | 중형 |
| `state.rs` | 상태 저장/복원/암호화 | 대형 |
| `cdp/` | CDP 프로토콜 클라이언트 | 디렉토리 |
| `diff.rs` | 스냅샷/스크린샷 비교 | 중형 |
| `auth.rs` | 인증 프로필 관리 (Vault) | 중형 |
| `recording.rs` | 세션 녹화 | 소형 |
| `stream.rs` | WebSocket 스트리밍 | 중형 |
| `tracing.rs` | Chrome DevTools 프로파일링 | 소형 |
| `cookies.rs` | 쿠키 CRUD | 소형 |
| `storage.rs` | localStorage/sessionStorage | 소형 |
| `webdriver/` | Appium/Safari 통합 | 디렉토리 |

---

## 3. 핵심 설계 패턴 분석

### 패턴 1: Daemon-Client 분리 (IPC 기반)

```
CLI → Unix Socket/TCP → 데몬 → CDP WebSocket → 브라우저
```

- CLI는 stateless: 매 명령마다 소켓 연결→명령 전송→응답 수신→종료
- 데몬은 stateful: 브라우저 상태, 세션, Ref 맵 등 유지
- **장점**: AI 에이전트가 Bash 도구로 직접 호출 가능. SDK/라이브러리 불필요.

### 패턴 2: Ref 시스템 (접근성 기반 요소 참조)

```bash
agent-browser snapshot -i   # @e1, @e2, @e3 ... 생성
agent-browser click @e2     # Ref로 요소 클릭
```

- `snapshot.rs`에서 접근성 트리(AX Tree)를 파싱하여 인터랙티브 요소에 `@eN` 레퍼런스 부여
- `element.rs`의 `RefMap`이 Ref → backend_node_id 매핑을 유지
- Ref가 stale 되면 role/name으로 AX Tree를 재검색하여 자동 복구 (Fallback)
- **CSS 셀렉터 대비 장점**: AI가 DOM 구조를 모르더라도 스냅샷 텍스트만으로 상호작용 가능

### 패턴 3: 계층적 재시도 전략 (Transient Error Detection)

`connection.rs`의 `is_transient_error()`:
```rust
fn is_transient_error(error: &str) -> bool {
    error.contains("os error 35")   // EAGAIN macOS
    || error.contains("os error 11") // EAGAIN Linux
    || error.contains("WouldBlock")
    || error.contains("EOF")
    || error.contains("Connection reset")
    || error.contains("Broken pipe")
    // ... OS별 에러 코드 12가지 대응
}
```
- 최대 5회 재시도, 200ms * attempt 지수 백오프
- Non-transient 에러는 즉시 실패 (불필요한 대기 방지)
- **모든 OS(macOS/Linux/Windows) 에러 코드를 명시적으로 분류**

### 패턴 4: Action Policy 시스템 (보안 게이트)

```json
{ "default": "deny", "allow": ["navigate", "snapshot", "click"], "deny": ["delete"], "confirm": ["submit"] }
```

- 3단계 정책: Allow → Confirm → Deny
- Deny가 최고 우선순위 (Confirm보다 높음)
- `AGENT_BROWSER_ACTION_POLICY` 환경변수로 JSON 파일 경로 지정
- `AGENT_BROWSER_CONFIRM_ACTIONS`로 확인이 필요한 액션 카테고리 지정
- 런타임 정책 리로드(`reload()`) 지원

### 패턴 5: Content Boundary 보안 (AI Injection 방어)

```
--- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
[접근성 트리 내용]
--- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
```

- CSPRNG(getrandom)로 생성한 16바이트 nonce로 경계 마커 생성
- **목적**: 악의적 웹 페이지가 AI 에이전트의 출력을 조작하는 것(Prompt Injection) 방지
- 페이지 콘텐츠와 도구 출력을 명확히 구분

### 패턴 6: 도메인 필터 이중 레이어

Layer 1 (서버 사이드): `Fetch.enable` CDP 인터셉트로 모든 네트워크 요청 검사
Layer 2 (클라이언트 사이드): `Page.addScriptToEvaluateOnNewDocument`로 WebSocket/EventSource/sendBeacon 차단

- 와일드카드 지원: `*.example.com`이 `example.com`도 매치
- Sub-resource 요청까지 차단 (CDN 도메인을 allowlist에 추가해야 함)

### 패턴 7: 상태 관리 (암호화 지원)

- `state.rs`: 쿠키 + localStorage + sessionStorage를 JSON으로 직렬화
- AES-256-GCM 암호화: `AGENT_BROWSER_ENCRYPTION_KEY`로 활성화
- 키 파생: SHA-256(key_string) → 256비트 키
- Nonce: getrandom으로 12바이트 생성, ciphertext 앞에 prepend
- 세션 자동 저장/복원: `--session-name`으로 활성화

### 패턴 8: 데몬 Auto-Launch + Idle Timeout

- 브라우저 없는 상태에서 `navigate` 호출하면 자동으로 브라우저 론칭
- `AGENT_BROWSER_IDLE_TIMEOUT_MS`로 비활동 시 자동 종료
- 매 명령 수신 시 idle 타이머 리셋 (mpsc 채널)
- CI/임시 환경에서 리소스 누수 방지

### 패턴 9: 크로스 플랫폼 빌드 + 배포 전략

- 빌드: Docker로 Linux/Windows 크로스 컴파일, macOS는 네이티브(arm64 + x64 동시)
- 배포: npm postinstall에서 플랫폼별 바이너리 자동 다운로드
- Chrome 설치: "Chrome for Testing" 채널에서 Stable 버전 자동 다운로드
- **Zero-dependency**: Playwright/Node.js 없이 순수 Rust 바이너리 + Chrome만으로 동작

### 패턴 10: 환경 변수 기반 설정 (12-Factor)

모든 설정이 환경변수로 오버라이드 가능:
```
AGENT_BROWSER_HEADED, AGENT_BROWSER_DEBUG, AGENT_BROWSER_PROXY,
AGENT_BROWSER_ALLOWED_DOMAINS, AGENT_BROWSER_IDLE_TIMEOUT_MS,
AGENT_BROWSER_ENCRYPTION_KEY, AGENT_BROWSER_CONTENT_BOUNDARIES, ...
```

우선순위: `~/.agent-browser/config.json` < `./agent-browser.json` < 환경변수 < CLI 플래그

### 패턴 11: 스냅샷 기반 AI 상호작용 루프

```
navigate → snapshot → 분석 → interact → re-snapshot → ...
```

- 접근성 트리를 텍스트로 변환하여 AI에 전달 (스크린샷보다 토큰 효율적)
- 인터랙티브/컨텐츠/구조적 역할(role)을 구분하여 필터링
- `-i` (interactive only), `-C` (cursor-interactive 포함), `-s` (selector scope) 등 세밀한 필터
- compact 모드: 불필요한 structural 노드 생략

### 패턴 12: 비주얼 디버깅 + Diff

- `--annotate`: 스크린샷에 번호 라벨 오버레이 → Vision 모델용
- `diff snapshot`: Myers 알고리즘(similar 크레이트)으로 접근성 트리 비교 (git diff 형식)
- `diff screenshot`: 픽셀 단위 비교, 색상 거리(Euclidean) 기반, 차이 영역 빨간색 표시
- `diff url`: 두 URL의 페이지를 동시에 비교

### 패턴 13: Auth Vault (인증 자격 증명 관리)

- 프로필 기반 인증: 이름→URL+유저+패스 매핑
- 암호화 저장: AES-256-GCM (AGENT_BROWSER_ENCRYPTION_KEY)
- `--password-stdin`으로 셸 히스토리 노출 방지
- 자동 로그인: `auth login <name>` → URL 이동 → 필드 자동 입력 → 제출

### 패턴 14: Claude Plugin 통합 (.claude-plugin)

```json
{
  "name": "agent-browser",
  "plugins": [{
    "skills": ["./skills/agent-browser"],
    "category": "development"
  }]
}
```

- `SKILL.md`: AI 에이전트용 사용 가이드 (트리거 패턴, 워크플로우, 팁)
- `allowed-tools`: 실행 가능한 Bash 패턴 지정
- **Claude Code와의 네이티브 통합**: skill로 등록하면 Claude가 자동으로 브라우저 도구 사용

### 패턴 15: 환경 변수 기반 EnvGuard (테스트 격리)

```rust
pub struct EnvGuard<'a> {
    _lock: MutexGuard<'a, ()>,  // 글로벌 뮤텍스
    vars: Vec<(String, Option<String>)>,  // 원래 값 백업
}
```

- 테스트에서 환경변수 변경 시 RAII 패턴으로 자동 복원
- 글로벌 뮤텍스로 병렬 테스트 간 충돌 방지
- `debug_assert!`로 등록되지 않은 변수 접근 차단

### 패턴 16: NO_COLOR 표준 준수

```rust
pub fn is_enabled() -> bool {
    static COLORS_ENABLED: OnceLock<bool> = OnceLock::new();
    *COLORS_ENABLED.get_or_init(|| env::var("NO_COLOR").is_err())
}
```

- https://no-color.org/ 표준 준수
- `OnceLock`으로 한 번만 체크 (성능)
- 모든 색상 함수가 `is_enabled()` 게이트를 거침

### 패턴 17: 벤치마크 프레임워크 (Vercel Sandbox)

- Vercel Sandbox에서 실제 브라우저를 띄워 벤치마크
- Node.js 데몬 vs Rust 네이티브 데몬 A/B 비교
- 측정 항목: 명령 레이턴시(avg/stddev/p50/min/max), 콜드 스타트, 데몬 RSS/Peak RSS, CPU 시간
- 워밍업 라운드 분리, 통계적 유의성 검증

### 패턴 18: 세션 이름 기반 격리

```bash
agent-browser --session site1 open site-a.com
agent-browser --session site2 open site-b.com
```

- 세션별 독립 소켓 파일: `{session}.sock`
- 세션별 독립 PID 파일: `{session}.pid`
- Windows에서는 세션 이름으로 포트 해싱 (djb2 알고리즘, 49152~65534 범위)

### 패턴 19: 접근성 트리 기반 Semantic Locator

```bash
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "user@test.com"
agent-browser find role button click --name "Submit"
```

- CSS 셀렉터 없이 텍스트/레이블/역할/placeholder로 요소 탐색
- AI 에이전트에게 직관적인 인터페이스

### 패턴 20: 출력 Truncation + Boundary

```rust
fn truncate_if_needed(content: &str, max: Option<usize>) -> String {
    // byte가 아닌 char 기준 truncation (유니코드 안전)
    // 남은 글자 수 안내: "[truncated: showing N of M chars]"
}
```

- `AGENT_BROWSER_MAX_OUTPUT`으로 출력 제한
- AI 에이전트의 컨텍스트 오버플로우 방지
- 유니코드 경계(char_boundary) 안전 truncation

---

## 4. 에러 핸들링 전략

### 4.1 계층별 에러 처리

| 계층 | 에러 유형 | 처리 방식 |
|------|----------|----------|
| CLI 파싱 | `ParseError` enum (5가지) | 친화적 메시지 + 사용법 제시 |
| 소켓 연결 | Transient/Non-transient 분류 | Transient만 재시도 (5회, 지수 백오프) |
| 데몬 시작 | 소켓 경로 길이/권한 사전 검증 | Pre-flight check로 조기 실패 |
| 브라우저 론칭 | 옵션 조합 검증 | 상호 배타 옵션 거부 (extensions + cdp 등) |
| CDP 통신 | 타임아웃 (30초 읽기, 5초 쓰기) | 타임아웃 설정 가능 |
| Ref 해석 | stale backend_node_id | AX 트리 재검색 fallback |

### 4.2 데몬 시작 Pre-flight Checks

```rust
// 1. 소켓 경로 길이 검증 (Unix 104바이트 제한)
if path_len > 103 { return Err(...) }

// 2. 소켓 디렉토리 쓰기 권한 검증
let test_file = socket_dir.join(".write_test");
fs::write(&test_file, b"")?;  // 실패 시 에러

// 3. 기존 stale 소켓/PID 파일 정리
cleanup_stale_files(session);
```

### 4.3 ParseError의 정교한 분류

```rust
pub enum ParseError {
    UnknownCommand { command: String },
    UnknownSubcommand { subcommand: String, valid_options: &'static [&'static str] },
    MissingArguments { context: String, usage: &'static str },
    InvalidValue { message: String, usage: &'static str },
    InvalidSessionName { name: String },
}
```

---

## 5. 테스트 전략 분석

### 5.1 테스트 계층

| 계층 | 테스트 수 | 위치 | 특성 |
|------|----------|------|------|
| 단위 테스트 | ~320개 | 각 모듈 `#[cfg(test)]` | Chrome 불필요, 빠름 |
| e2e 테스트 | 18개 | `e2e_tests.rs` | 실제 Chrome 인스턴스, `#[ignore]` |
| 패리티 테스트 | `parity_tests.rs` | CLI ↔ 데몬 일관성 검증 |
| 벤치마크 | `benchmarks/` | Vercel Sandbox, 성능 비교 |

### 5.2 e2e 테스트 커버리지

```
launch/close, navigation, snapshots, screenshots,
form interaction, cookies, storage, tabs,
element queries, viewport/emulation, domain filtering,
diff, state management, error handling, Phase 8 commands
```

- `--test-threads=1` 강제 (Chrome 인스턴스 경쟁 방지)
- `DaemonState::new()`로 독립 상태 생성 (데몬 없이 직접 테스트)

### 5.3 테스트 유틸리티

- `EnvGuard`: 환경변수 격리 (RAII + Mutex)
- `assert_success()`, `get_data()`: 응답 검증 헬퍼
- Lightpanda 테스트: `LIGHTPANDA_BIN` 환경변수로 조건부 실행

---

## 6. 우리 시스템 적용 가능한 학습 패턴 (전체 리스트)

### A. dev-system (개발 인프라) 적용

#### A-1. Daemon-Client IPC 패턴 → dispatch.py 고도화
- **현재**: dispatch.py가 매번 새 프로세스 생성
- **적용**: Unix Socket 기반 상주 데몬으로 dispatch 큐 관리
- **이점**: 팀 상태 실시간 추적, 중복 위임 방지

#### A-2. Transient Error Detection → 팀 통신 안정화
- **현재**: cokacdir Telegram 메시지 실패 시 단순 재시도 or 실패
- **적용**: 에러를 transient(네트워크)/non-transient(인증)으로 분류, transient만 지수 백오프 재시도
- **코드 참고**: `connection.rs`의 `is_transient_error()` + `send_command()` 재시도 로직

#### A-3. Action Policy 시스템 → 팀 권한 관리
- **현재**: 팀별 행동 제한이 프롬프트 기반
- **적용**: JSON 기반 Action Policy (`allow/deny/confirm` 3단계)
- **예시**: 3팀(Ra)은 `{allow: ["edit", "test"], deny: ["deploy", "delete"]}`

#### A-4. Content Boundary / Nonce → AI Injection 방어
- **현재**: 에이전트 출력과 웹 콘텐츠 구분 없음
- **적용**: 팀장→팀원 위임 시 nonce 경계 마커로 지시 내용과 코드 실행 결과를 분리
- **보안 강화**: 악의적 코드 출력이 지시를 오버라이드하는 것 방지

#### A-5. EnvGuard 패턴 → 테스트 환경 격리
- **적용**: 환경변수 의존 테스트에서 RAII 패턴으로 자동 복원
- **구현**: Python 버전 context manager로 동일 패턴 적용 가능

#### A-6. Pre-flight Validation → 위임 사전 검증
- **현재**: dispatch.py가 실행 후 실패를 감지
- **적용**: 위임 전 사전 검증 (파일 경로 유효성, 팀 가용성, 리소스 충돌)
- **코드 참고**: `ensure_daemon()`의 소켓 경로/권한 사전 체크

#### A-7. Idle Timeout 자동 종료 → 팀 세션 리소스 관리
- **현재**: 팀 세션이 완료 후에도 프로세스가 남을 수 있음
- **적용**: idle timeout으로 비활동 팀 세션 자동 정리

#### A-8. 벤치마크 프레임워크 → 팀 성능 비교 고도화
- **현재**: `memory/reports/team-comparison-v1.md` 수동 비교
- **적용**: 구조화된 벤치마크 (워밍업/반복/통계/메모리/CPU 측정)
- **코드 참고**: `benchmarks/bench.ts`의 Stats 계산 (avg/stddev/p50/min/max)

#### A-9. .done 프로토콜 강화 (State Management 패턴)
- **현재**: `.done` 파일 생성/rename만
- **적용**: agent-browser의 state.rs처럼 구조화된 상태 파일 (JSON + 암호화 옵션)
- **이점**: 작업 결과 메타데이터 (소요시간, 변경 파일, 테스트 결과) 포함

#### A-10. Changeset 기반 버전 관리 → dev-system 버전 관리
- **현재**: dev_workspace에 버전 개념 없음
- **적용**: @changesets/cli로 변경사항 추적, 자동 CHANGELOG 생성

### B. InsuRo / ThreadAuto 프로젝트 적용

#### B-1. CLI-Daemon 아키텍처 → InsuRo 백그라운드 처리
- **적용**: 보장분석/약관비교 등 heavy 작업을 데몬으로 분리
- **이점**: 웹 UI 응답성 유지, 작업 상태 실시간 조회

#### B-2. Ref 시스템 → InsuRo 크롤링 안정화
- **현재**: CSS 셀렉터 기반 크롤링은 사이트 변경에 취약
- **적용**: 접근성 트리 기반 요소 식별 (role + name)
- **이점**: 보험사 사이트 마크업 변경에 강건

#### B-3. Snapshot Diff → 보험 약관 변경 감지
- **적용**: 정기적으로 약관 페이지 스냅샷 → diff로 변경사항 감지
- **코드 참고**: `diff.rs`의 Myers 알고리즘 기반 텍스트 diff

#### B-4. Screenshot Diff → 보험료 비교 결과 시각적 검증
- **적용**: 보험료 비교 결과 페이지의 시각적 회귀 테스트
- **코드 참고**: `diff.rs`의 픽셀 비교 (Euclidean 색상 거리)

#### B-5. Auth Vault → 보험사 로그인 관리
- **적용**: 보험사별 로그인 정보를 암호화 저장, `auth login <보험사>` 식으로 자동 로그인
- **보안**: AES-256-GCM 암호화, 환경변수 키 관리

#### B-6. Domain Filter → InsuRo 안전한 크롤링
- **적용**: 허용된 보험사 도메인만 접근 가능하도록 제한
- **이중 레이어**: 네트워크 인터셉트 + JS 패칭으로 우회 방지

#### B-7. Session Persistence → ThreadAuto SNS 세션 유지
- **적용**: Threads/Instagram 로그인 세션을 저장/복원
- **이점**: 매번 로그인 불필요, 계정 잠금 위험 감소

#### B-8. Content Boundary → ThreadAuto 콘텐츠 추출 안전
- **적용**: 크롤링한 콘텐츠와 시스템 프롬프트를 명확히 분리
- **이점**: 악의적 게시물이 에이전트 동작을 조작하는 것 방지

#### B-9. Semantic Locator → InsuRo 폼 자동화
- **적용**: `find label "보험료" fill "50000"` 식으로 셀렉터 없이 폼 입력
- **이점**: 보험사 사이트마다 다른 HTML 구조에 적응

### C. browser.py (현재 브라우저 자동화) 직접 개선

#### C-1. agent-browser 직접 도입 검토
- **현재**: `scripts/browser.py` (424줄, Python + Playwright)
- **대안**: `agent-browser` CLI 직접 사용 또는 참고하여 개선
- **장점**: Rust 성능, 네이티브 CDP, AI 에이전트 친화적 출력
- **단점**: 원격 CDP(Tailscale) 연결은 이미 browser.py가 지원

#### C-2. Ref 시스템 추가 → browser.py 개선
- **현재**: CSS 셀렉터 기반
- **적용**: `snapshot` 시 접근성 트리 파싱 → Ref 부여 → Ref 기반 조작
- **코드 참고**: `snapshot.rs`의 AX 트리 파싱 + `element.rs`의 RefMap

#### C-3. Transient Error 재시도 → browser.py 안정화
- **현재**: 원격 CDP 연결(100.116.204.95:9222) 불안정할 수 있음
- **적용**: 에러 분류 + 지수 백오프 재시도
- **코드 참고**: `connection.rs`의 에러 분류 + 재시도 로직

#### C-4. 스냅샷 기반 워크플로우 → AI 에이전트 통합
- **현재**: browser.py는 스크린샷 위주
- **적용**: 접근성 트리 텍스트 출력 추가 → AI가 분석 → 조작 명령 생성
- **토큰 절약**: 이미지보다 텍스트가 훨씬 적은 토큰 사용

#### C-5. 도메인 필터 + Action Policy → 안전한 자동화
- **적용**: browser.py에 도메인 화이트리스트 + 금지 액션 목록 추가
- **이점**: 팀 위임 시 브라우저 작업 범위를 제한

#### C-6. 상태 저장/복원 → 세션 지속성
- **현재**: 세션 정보가 /tmp에 임시 저장
- **적용**: 쿠키 + localStorage를 JSON으로 구조화 저장, 선택적 암호화
- **코드 참고**: `state.rs`의 `save_state()`/`load_state()`

#### C-7. Content Boundary → 원격 브라우저 보안
- **적용**: 원격 브라우저(제이회장님 노트북)에서 가져온 콘텐츠에 nonce 경계 추가
- **이점**: 악의적 페이지 콘텐츠가 에이전트 프롬프트를 조작하는 것 방지

#### C-8. Screenshot Annotation → 비전 모델 활용
- **적용**: 스크린샷에 인터랙티브 요소 번호 오버레이
- **이점**: 비전 모델(Gemini 등)이 요소를 참조할 수 있음

#### C-9. Idle Timeout → 원격 브라우저 자원 관리
- **적용**: 원격 Chrome 세션이 비활동 시 자동 정리
- **이점**: 제이회장님 노트북 리소스 절약

---

## 7. 코드 품질 관찰

### 장점
1. **모듈 분리가 명확**: 각 모듈이 단일 책임, 20+ 모듈이 독립적
2. **에러 처리가 정교**: 5가지 ParseError, 12가지 transient error, pre-flight check
3. **테스트 충실**: ~320 단위 + 18 e2e, 환경변수 격리 유틸
4. **보안 고려**: Content Boundary, Domain Filter, Auth Vault, 암호화
5. **크로스 플랫폼**: macOS/Linux/Windows 모두 지원, OS별 분기 처리
6. **문서화**: README 46KB, SKILL.md, AGENTS.md, docs 사이트

### 개선 가능한 점
1. `actions.rs` 195KB — 하나의 파일에 모든 명령어 로직이 집중 (분리 가능)
2. `main.rs` 29KB — CLI 진입점이 너무 많은 플래그 처리를 담당

---

## 8. 기술적 인사이트

### 8.1 왜 Rust인가
- **성능**: Node.js 대비 메모리 1/10, 콜드 스타트 빠름 (벤치마크 제공)
- **바이너리 배포**: 단일 실행 파일, Node.js 런타임 불필요
- **안정성**: 타입 시스템으로 소켓/에러 처리 컴파일 타임 검증

### 8.2 왜 CDP 직접 구현인가
- **경량**: Playwright/Puppeteer 의존 제거 (수백 MB → 수 MB)
- **제어**: CDP 메시지를 직접 구성, 프로토콜 레벨 최적화 가능
- **유연성**: Chrome 외 엔진(Lightpanda) 쉽게 추가

### 8.3 접근성 트리가 핵심인 이유
- AI 에이전트는 DOM/CSS를 이해하지 못함
- 접근성 트리는 **의미론적** (버튼, 링크, 텍스트박스 등)
- 시각적 레이아웃 무관하게 상호작용 가능
- 스크린샷 대비 토큰 1/100 수준

---

## 9. 결론 및 우선순위 제안

### 즉시 적용 (Lv.0~1)
1. `agent-browser` CLI 설치하여 browser.py 대안으로 평가
2. Transient error 분류 패턴을 dispatch.py에 적용
3. Content Boundary 개념을 팀 위임 프롬프트에 도입

### 단기 적용 (Lv.2, 프로젝트 필요 시)
4. Ref 시스템을 browser.py에 접근성 트리 기반으로 추가
5. Auth Vault 패턴으로 보험사 로그인 관리 (InsuRo)
6. Snapshot diff로 약관 변경 감지 (InsuRo)
7. Session persistence로 SNS 세션 유지 (ThreadAuto)

### 중기 적용 (Lv.3, 설계 필요)
8. Daemon-Client IPC로 dispatch.py 고도화
9. Action Policy 시스템으로 팀 권한 관리
10. 벤치마크 프레임워크로 팀 성능 비교 고도화

---

*참고 파일*:
- 현재 browser.py: `/home/jay/workspace/scripts/browser.py` (424줄)
- 조직도: `/home/jay/workspace/memory/organization-structure.json`
- 기존 브라우저 연결: `python3 scripts/browser.py --remote-cdp http://100.116.204.95:9222`