# EXAONE Agent — Windows 앱

K-EXAONE 2.5와 대화하고 파일·명령·웹 검색·예약 작업을 처리하는 Windows 데스크톱 앱입니다.

## 실행

## 3.5.0 — Chrome 입력·API 호출 간격

- **Chrome 입력 방식**: Chrome DevTools 연결에서 클릭과 일반 텍스트 입력을 브라우저의 CDP 입력으로 전달합니다. 마우스 누름·뗌·클릭과 입력 이벤트의 `isTrusted`를 실제 Chrome에서 확인합니다. 선택 상자와 스크롤, 이전 내장 브라우저 경로는 DOM 방식이며 결과에 입력 방식을 구분합니다.
- **입력 대상 확인**: 기존 사이트 읽기 허용과 조작 승인을 유지합니다. 화면의 요소 ID·token에 묶인 대상을 승인 후 다시 검사하고, 가림 창·대상 변경·입력 초점 변경을 확인합니다. 비밀번호·인증번호·결제 정보·파일 선택은 계속 직접 처리합니다.
- **결과가 불명확한 조작 중단**: 클릭·입력을 전달한 뒤 취소되거나 응답이 끊기면 자동으로 반복하거나 다른 입력 방식으로 재실행하지 않습니다. 현재 페이지와 실행 기록을 확인한 뒤 이어갑니다.
- **잔여 호출이 있는 429 구분**: 서버가 초·분·일 잔여 호출을 모두 0보다 크게 보내면 호출 횟수를 다 썼다고 표시하지 않습니다. 이때 대기 시간 안내도 없으면 자동 재시도를 중단하고, 명시된 대기 시간이 있으면 기존 대기 정책을 따릅니다.
- **API 요청 간격**: 같은 앱 프로세스의 대화·요약·자동 재시도·실제 평가 요청은 공통 대기열을 거쳐 최소 1초 간격으로 전송을 시작합니다. 응답을 기다리는 시간과 별도로 적용하며, 서버가 재시도에 더 긴 대기 시간을 안내하면 그 시간을 지킵니다. 취소된 대기 요청은 보내지 않습니다. 다른 프로그램이나 별도 앱 프로세스가 같은 API 키를 사용하는 경우까지 합산하는 기능은 아닙니다.

개발 검증은 `npm test`, `npm run test:browser`로 실행합니다. 브라우저 검사는 로컬 테스트 페이지와 별도 Chrome 프로필을 사용하며 실제 EXAONE API를 호출하지 않습니다. 닫힌 shadow DOM·canvas·다른 출처 iframe·좌표 변환이 있는 iframe·일부 사용자 지정 편집기는 직접 조작해야 합니다. 페이지 자체 스크립트의 임의 동작까지 격리하는 기능은 아니며, 사이트 접근 제한을 해제하지 않습니다.

사이트 스크립트가 입력 이벤트 전파를 막으면서 초점을 옮기는 경우까지 모두 사전 차단하지는 못합니다. 요청한 입력란의 값이나 초점이 예상과 다르면 결과를 불명확 상태로 기록합니다. 링크 클릭 직후 페이지가 이동해 이전 화면의 확인 응답을 받지 못한 경우도 새 화면에서 결과를 확인해야 합니다.

## 3.4.0 — 브라우저 읽기·조작·연결 안정성

REA 6.8.0으로 Claude Code 2.1.322의 공개 도구 정의와 EXAONE 3.3.0 배포본의 브라우저 관련 파일 5개를 추가 분석했습니다. Claude의 웹 읽기 도구에 있는 offset 계약을 참고해 긴 페이지 이어 읽기를 독립 구현했습니다. 실제 Claude 브라우저의 클릭·권한 검사 구현은 공개 타입에 포함되지 않아 동작이 동일하다고 판단하지 않습니다. 분석 근거는 `artifacts/rea-browser-review-3.4.json`입니다.

- **긴 페이지 이어 읽기**: 본문 30,000자·요소 160개 이후도 같은 캡처의 token과 다음 위치로 읽습니다. 한 캡처는 본문 200,000자·요소 2,000개·탐색 노드 20,000개로 제한하며 잘림을 표시합니다. 이어 읽기는 이전 캡처의 내용이며 최신 상태는 새 snapshot으로 확인합니다.
- **열린 shadow DOM 지원**: 웹 컴포넌트 안의 본문·버튼·일반 입력란을 읽고 조작합니다. 입력값과 편집 영역 본문은 캡처에서 제외합니다. 닫힌 shadow DOM·canvas·다른 출처 iframe은 계속 직접 처리가 필요합니다.
- **조작 대상 재확인**: 다른 요소가 가린 대상, 숨김·inert·aria-disabled 요소, 승인 후 속성이나 폼 대상이 변경된 요소를 실행하지 않습니다. 입력 중 focus 이벤트로 대상이 변경되면 값을 쓰지 않고 결과 불명확 상태를 기록합니다. 브라우저 조작은 DOM 이벤트 기반이며 실제 마우스의 trusted 이벤트가 필요한 모든 사이트를 지원하는 것은 아닙니다.
- **중복 실행 방지**: 조작을 전달한 뒤 응답을 잃으면 실제 변경 여부 확인 전 추가 변경을 막습니다. 전달 전 미실행은 별도로 구분하며, 다른 탭·프레임을 읽었다고 원래 조작의 재확인을 마친 것으로 처리하지 않습니다.
- **연결·탭 선택 취소**: 수동 연결 중 다른 대화·예약 작업이 끼어들지 않도록 합니다. AI의 탭 선택 창에서 취소·닫기·Escape로 대기를 끝낼 수 있으며 Chrome과 기존 탭은 유지합니다. 새로고침·재열기 때 현재 선택과 대기 상태를 표시합니다.
- **늦게 도착하는 연결 정리**: 취소 후 만들어진 앱 요청 탭은 정리하고 이동 명령을 보내지 않습니다. 오래된 연결·팝업·CDP 응답을 새 작업에 적용하지 않으며, 화면을 읽는 중 팝업이 생겨도 본문과 프레임 정보가 서로 다른 탭에서 섞이지 않도록 합니다.

검증은 로컬 페이지와 별도 Chrome 프로필에서 수행합니다. 개인 Chrome의 로그인 데이터나 실제 EXAONE 계정을 시험에 사용하지 않습니다. 사이트의 접근 제한을 해제하거나 쿠팡 로그인을 보장하는 변경은 아닙니다.

## 3.3.0 — Claude Code 분석을 참고한 검토·파일 읽기와 안정성 개선

공식 npm 배포의 Claude Code 2.1.322를 별도 분석 폴더에서 REA 6.8.0으로 정적 분석했습니다. 공개 도구 타입 정의에서 파일 범위 읽기와 계획 모드의 입출력 계약을 확인하고 EXAONE에 독립적으로 구현했습니다. 공개 타입은 Claude 내부의 실제 권한 검사 방법이나 모델 동작을 입증하지 않습니다. 분석 근거와 범위는 `artifacts/rea-claude-code-2.1.322-review.json`에 기록합니다.

- **AI 읽기 전용 검토**: 사용자가 검토 모드를 선택하면 AI는 파일 읽기·검색·URL 확인·계획·결과 확인만 수행합니다. 파일 작성, 명령 실행, MCP, 브라우저 조작 도구를 숨기며, 모델이 해당 도구를 요청해도 실행 단계에서 다시 차단합니다. 작업을 시작할 때 모드를 고정하고 실행 중 변경을 막습니다. 앱의 수동 터미널처럼 사용자가 직접 조작하는 기능은 별개입니다.
- **큰 파일 범위 읽기**: `read_file`에 `start_line`과 `max_lines`를 추가해 100KB보다 큰 UTF-8 파일도 필요한 줄만 읽습니다. 반환값에 읽은 줄 범위, 이어 읽을 위치, 잘림 이유를 포함합니다. 한 번에 기본 200줄·64,000바이트, 파일 시작부터 8MiB까지만 스캔합니다. 매우 긴 한 줄이나 스캔 한도 때문에 이어 읽을 위치를 확정하지 못하면 그 한계를 표시합니다.

REA 6.8.0으로 3.2.0 배포본의 통신·프로세스·설정 관련 파일 7개를 정적으로 분석한 뒤 모의 서버, 실제 PowerShell, 디스크 오류 주입으로 문제를 재현했습니다. 분석은 선택한 파일 범위이며 전체 앱의 안전성을 보증하지 않습니다. 원본 분석 요약은 `artifacts/rea-exaone-3.2-io-summary.json`입니다.

- **응답 완료 검증**: 스트림의 `[DONE]` 이후 데이터는 무시합니다. 응답 완료 뒤 추가 도구 조각, 차단·알 수 없는 종료 상태, 중복 도구 ID, 완성되지 않은 인수 JSON은 실행하지 않습니다. 일반 JSON 응답도 8MB로 제한하고 초과 시 읽기를 정리합니다.
- **토큰 중복 집계 방지**: 같은 스트림에 누적 사용량이 여러 번 들어오면 마지막 유효한 사용량을 한 번만 기록합니다. 도중에 연결이 끊겨도 이미 받은 사용량은 남깁니다. 실제 계정 잔액을 조회하는 기능은 아닙니다.
- **터미널 종료·재실행**: 이전 셸의 늦은 출력·오류를 새 명령에 전달하지 않습니다. 화면 이벤트 처리 오류가 명령 완료를 막지 않으며, 종료 요청을 중복 보내지 않고 종료 대기에도 제한을 둡니다. 취소 직후 명령을 새로 전송하는 경로도 차단합니다.
- **MCP 취소·결과 검증**: 연결과 도구 목록 조회 중 취소를 전달합니다. 과도하거나 잘못된 도구 이름·결과를 거절하며, 도구 요청을 보낸 뒤 유효한 결과를 확인하지 못하면 외부 상태를 확인하기 전 추가 변경을 막습니다.
- **설정 원자 저장·복구**: 설정 변경을 순서대로 합쳐 복구 사본과 원본에 기록한 뒤 메모리에 반영합니다. 손상된 설정은 보존하고 유효한 사본으로 복구합니다. 복구 원본도 별도로 남기며, 오래된 권한이 조용히 되살아나지 않도록 자동 승인 규칙·MCP·예약 작업을 비활성화하고 검토를 요청합니다.
- **복구 확인의 저장 보장**: 결과 불명확 작업이나 백업 복구를 확인하는 동안 새 작업이 끼어들지 못하게 합니다. 확인 기록 저장이 실패하면 메모리의 차단 상태도 되돌립니다.
- **429 원인 표시·재시도 개선**: 서버가 보내는 초·분·일 단위 남은 호출 수와 대기 시간을 읽어 안내합니다. 일일 잔여 호출이 0이면 자동 재시도하지 않습니다. `Retry-After`/`retry-after-ms`를 지키며, 60초보다 긴 대기는 안내 후 종료합니다. 헤더가 없으면 한도 종류를 추측하지 않고 제한된 횟수만 재시도합니다. 이 기능은 서버의 한도를 늘리거나 토큰 잔액을 조회하지 않습니다.

API 형식 검사는 [K-EXAONE 공식 응답 문서](https://docs.exaone.ai/ko/docs/k-exaone-2.5), 429 처리는 [공식 호출 제한 문서](https://docs.exaone.ai/ko/docs/rate-limits)를 참고했습니다. 회귀 검증은 모의 API 응답을 사용하며 실제 계정의 잔여량이나 제한 해제 여부를 검증하지 않습니다.

## 3.2.0 — REA 분석 후 안정성 개선

REA 6.8.0으로 기존 3.1.0 배포 파일의 핵심 JavaScript 8개와 Electron 실행 옵션을 정적으로 분석했습니다. IPC·비동기 흐름을 소스와 대조하고 별도 실패 주입 테스트로 문제를 확인했습니다. REA의 정적 관찰만으로 실행 오류를 확정하거나 앱 전체를 검증했다고 판단하지 않았습니다. 분석 범위와 원본 버전의 관찰은 `artifacts/rea-exaone-3.1-summary.json`, `artifacts/rea-exaone-3.1-fuses.json`에 남아 있습니다.

- **내부 기록의 재귀 백업 방지**: 작업 폴더가 앱 데이터 폴더 또는 상위 폴더일 때 내부 복구 사본·임시 저장 파일을 사용자 파일 변경으로 수집하지 않습니다. 실제 저장 위치를 기준으로 제외합니다.
- **변경 후 저장 실패 처리**: 파일·명령 실행 뒤 기록 저장이 실패하면 결과를 불명확 상태로 표시하고, 결과 확인 전 추가 변경을 막습니다. 메모리에 남은 실제 결과와 복원 근거를 유지합니다. 디스크 기록 자체가 실패한 상황에서 모든 마지막 정보를 디스크에 보존할 수 있다는 의미는 아닙니다.
- **대화·첨부·파일 복원 충돌 방지**: 폴더 선택, 첨부 읽기, 파일 복원 중 다른 작업이 같은 상태를 바꾸지 못하도록 합니다. 취소·실패 후에는 실행 상태를 해제합니다.
- **업데이트 확인 일관성**: 여러 확인 요청이 엇갈려 다른 버전의 다운로드 대상으로 바뀌지 않도록 확인 작업을 직렬화합니다.
- **대기 요청 보존**: 사용자 요청이 대화 기록에 저장된 것을 확인한 뒤 대기열에서 제거합니다. 저장 중 실패하거나 재시작해도 요청을 조용히 잃거나 같은 요청을 자동 중복 실행하지 않도록 처리합니다.
- **중복 앱 실행 방지**: 같은 데이터 폴더를 사용하는 앱은 한 개만 실행하고 두 번째 실행은 기존 창으로 연결합니다. 별도 데이터 폴더의 앱은 독립적으로 실행할 수 있습니다. 버전 전환은 백업 완료 후 실행 권한을 넘기고, 전환 실패 시 다시 확보합니다. 이전 3.1 이하 버전에는 이 제한이 없으므로 업그레이드할 때 기존 앱을 종료한 뒤 새 EXE를 실행하세요.
- **배포 파일 보호**: `ELECTRON_RUN_AS_NODE`, `NODE_OPTIONS`, Node Inspector 실행 인수를 비활성화하고 ASAR 전용 로딩·내장 무결성 검사를 활성화합니다. 외부 Chrome DevTools 연결 기능과 쿠키 암호화 설정은 이 변경의 대상이 아닙니다. 무결성 검사는 EXE 코드 서명을 대신하지 않습니다.

배포판은 Node Inspector가 비활성화되어 Playwright의 `_electron.launch`로 검사할 수 없습니다. 기존 데스크톱 회귀 검사는 개발 Electron으로 실행하고, 최종 배포 파일은 `hardened-package-smoke.mjs`로 별도 검사합니다. 테스트 프로필과 로컬 모의 데이터만 사용하며 실제 API 사용량은 발생하지 않습니다.

저장소 단위 회귀 테스트는 75개입니다. 추가 IPC·대기열 검사는 `node ipc-ownership-smoke.mjs`, 동시 실행 검사는 `node single-instance-smoke.mjs`로 실행합니다. `EXAONE_TEST_EXE`에 패키징된 앱의 경로, `EXAONE_TEST_TAMPER=1`을 설정하고 `node hardened-package-smoke.mjs`를 실행하면 임시 사본의 ASAR 변조·대체 앱 폴더 로딩 거부도 확인합니다. 현재 빌드는 이전과 같이 서명되지 않았습니다.

## 3.1.0 개선

- **기록 저장·복구**: 임시 파일에 기록하고 디스크 반영 후 교체하며, 같은 체크포인트의 `.bak` 파일을 유지합니다. 손상된 원본은 별도로 보존하고 백업으로 복구합니다. 복구된 기록은 **실행·복구·MCP·업데이트**에서 실제 작업 상태를 확인한 메모를 입력한 뒤 실행할 수 있습니다. 저장 요청이 몰리면 최신 상태로 합쳐 대기 쓰기를 최대 2개로 제한합니다.
- **상태 진단**: 실행 시간, 메모리, 저장 크기, 대기 저장 수를 표시합니다. 이벤트·검증 상세는 최근 300개, 사용량 상세는 최근 500개를 유지하고 누적 토큰 수는 별도로 보존합니다. 원본 대화와 파일 백업은 삭제하지 않습니다. 따라서 장기간 쌓인 원본 기록의 저장 크기에는 별도 상한이 없습니다.
- **브라우저 연결**: DevTools 연결 대기 취소, 늦게 도착한 연결 정리, 반복 탭 선택 시 리스너 정리, 승인 대기 중 페이지 변경 감지를 보완했습니다. 연결·탭·iframe이 사라지면 현재 작업을 중단하고 새 상태를 확인하도록 합니다.
- **절전 대응**: Windows 절전 진입 알림을 받으면 진행 작업을 취소합니다. 재개 후에는 실제 변경 결과를 확인하고 이어가세요. 절전에서 자동으로 작업을 다시 실행하지 않습니다.
- **REA·MCP**: MCP 2025-11-25 협상과 서버 ping, 도구 목록 페이지 처리, 연결·호출 시간 제한 설정을 지원합니다. 모델에는 축약 도구 목록을 전달하고 필요한 도구의 스키마를 따로 조회합니다. REA 실행 인수는 `--mcp`이며, 실제 REA 6.8.0의 229개 도구 조회와 분석 대상이 없는 `binary_session` 호출을 확인했습니다.
- **응답·다운로드 한도**: 과도한 SSE 응답과 잘못된 도구 인덱스를 차단합니다. 업데이트 EXE는 스트리밍 저장·SHA256 검증 후 확정하며, 취소·연결 실패 시 임시 파일을 정리합니다. 새 버전 실행 전 대화·설정 사본을 사용자 데이터 폴더의 `version-backups`에 보관합니다. 이 사본을 자동 복원하거나 구버전 형식으로 변환하지는 않습니다.
- **평가 확대**: 최신 근거 선택, 자료 부재, 한글 경로, 도구 선택, 오류 복구, 문서 속 지시 구분의 6개 사례를 제공합니다. API 오류는 오답과 구분해 미평가로 기록하고, 평가 완료 수와 범위를 함께 표시합니다.
- **실행 충돌 방지**: 평가·버전 전환의 승인 대기 중에도 다른 작업이 시작되지 않도록 실행 상태를 확보하고, 취소·오류 시 해제합니다.

MCP 설정의 `startupTimeoutMs`는 기본 60초·최대 120초, `requestTimeoutMs`는 기본 30초·최대 300초입니다. 도구 목록은 최대 20페이지·500개이며 응답 크기와 단일 스키마 크기에도 제한이 있습니다. 기존 도구 허용 목록과 호출별 승인 정책을 유지합니다.

2026-11-12 검증: 단위 테스트 66개, 데스크톱 회귀 테스트, 손상 기록 복구, 실제 Chrome 연결·취소·탭·iframe 회귀 검사를 통과했습니다. 합성 부하 검사는 저장 요청 500회가 최종 상태까지 반영되고 대기 쓰기가 최대 2개임을 확인했습니다. 수 시간 실사용이나 실제 PC 절전 시험의 결과는 아닙니다. 실제 EXAONE 평가는 6개 중 1개 완료·통과, 5개는 API 사용량 또는 요청 제한으로 미평가였습니다. 이 결과로 전체 작업 성공률을 판단할 수 없습니다.

공개 사이트 검사에서는 example.com과 wikipedia.org의 본문을 확인했습니다. 쿠팡 파트너스는 HTTP 200과 페이지 제목은 확인했지만 10초 후에도 본문이 비어 있어 내용·로그인 성공을 확인하지 못했습니다.

현재 배포 EXE는 서명되지 않았습니다. 유효한 코드 서명 인증서를 빌드 환경에 제공한 경우 `npm run build:exe:signed`를 사용하세요. 이 명령은 서명이 불가능하면 실패하도록 설정되어 있습니다. 공개 업데이트 주소와 게시 파이프라인의 실제 배포는 별도 설정이 필요합니다.

추가 개발 검증: `node recovery-smoke.mjs`, `node storage-soak-smoke.mjs`, `node browser-resilience-smoke.mjs`, `node mcp-rea-smoke.mjs`, `node maintenance-smoke.mjs`. 마지막 검사는 승인 대기 중 예약·동시 실행 차단, 취소·오류·창 종료, 버전 전환 전 백업을 확인합니다. 실제 모델 평가와 공개 사이트 검사는 네트워크 및 API 상태의 영향을 받습니다.

## 3.0.0 개선

왼쪽 **실행·복구·MCP·업데이트**에서 실행 예산, 중단 작업, 외부 도구, 평가와 버전을 관리합니다. 대화 입력창 위 **작업 타임라인**에서 진행 단계를 확인할 수 있습니다.

| 항목 | 적용 내용 |
| --- | --- |
| 브라우저 상태 | 연결·선택 탭 상태 조회, 브라우저 작업 전 연결 확인 |
| 사용자 작업 후 재개 | Chrome 허용·작업 탭 선택 후 같은 요청 자동 재개, 취소·연결 끊김 처리 |
| 반복 실패 | 동일 작업 2회 실패 후 세 번째 실행 차단, 같은 관찰에서 성공한 변경 중복 차단 |
| 완료 검증 | 파일 검증·명령 종료·화면 재확인 근거와 미검증 변경을 기록하고 보고 |
| 중단 복구 | 완료·미실행·결과 불명확 구분, 실제 결과를 확인한 기록을 입력한 뒤 변경 작업 재개 |
| 작업 예산 | 기본 24단계·30분, 최대 120단계·180분, API 보고 토큰 한도 설정 |
| 타임라인 | 도구 시작·종료·승인·검증·예산 이벤트, 호출 ID·단계 기록 |
| 맥락 압축 | 목표·제약·결정·완료·미해결·실패·파일·검증·불확실성 구조화, 이전 요약 호환 |
| 프로젝트 검색 | 다중 검색어 관련도 정렬, 주변 5줄과 줄 번호, 최대 40개·24,000자 |
| 브라우저 안정성 | DOM 로딩 대기, 팝업 추적, 같은 출처 iframe 선택·읽기·조작, 오래된 요소 차단 |
| 외부 변경 보호 | 중단·시간 초과 등 결과 불명확한 변경은 추가 변경 차단, 읽기로 상태 확인 가능 |
| MCP | 로컬 stdio JSON-RPC 서버 등록, 도구 검색, 이름 허용 목록, 호출별 승인 |
| 성능 평가 | 합성 읽기 전용 사례 3개 모의/실제 EXAONE 평가, 성공률·지연·토큰 기록 |
| 배포·복구 | 버전 표시, HTTPS manifest 확인, SHA256 확인 후 EXE 다운로드, 보관된 버전 실행 |

토큰 한도는 응답 후 보고되는 사용량을 기준으로 다음 요청/실행을 중단하므로 과금의 절대 상한은 아닙니다. 다른 출처의 iframe은 직접 조작을 안내하며 지원하지 않습니다. 결과 확인 및 중복 방지는 외부 서비스와 원자적이지 않으므로 정확히 한 번 실행을 보장하지 않습니다.

MCP 설정은 JSON 배열입니다. `id`, 실행 파일 절대 경로인 `command`(.exe), 문자열 배열 `args`, `enabled`, 허용 도구 이름 배열 `allowedTools`를 지정하세요. 실행 파일에는 Node 서버인 경우 node.exe 경로를, 인수에는 서버 스크립트와 해당 서버의 stdio 실행 인수를 넣습니다. 서버 등록은 설치를 수행하지 않습니다. 허용 목록이 비어 있으면 목록 조회만 가능하며 모델의 도구 호출은 차단됩니다. 서버는 사용자 권한으로 실행되므로 신뢰하는 프로그램만 등록하세요. HTTP MCP·서버의 sampling/elicitation 요청은 이번 버전에서 지원하지 않습니다.

업데이트 manifest 예시: `{"version":"3.0.1","url":"https://example.org/EXAONE-Agent-3.0.1.exe","sha256":"64자리 SHA256","notes":"변경 사항"}`. 자동 게시 서버는 포함하지 않으며 사용자가 설정한 HTTPS 주소에서 확인합니다. 리디렉션은 허용하지 않습니다. 현재 portable EXE 경로를 확인할 수 있을 때 새 버전 다운로드 시 현재 EXE도 보관합니다. 대화·설정의 구버전 형식 변환은 수행하지 않습니다.

개발 검증: `npm test`, `npm run test:desktop`, `node devtools-smoke.mjs`, `node browser-stability-smoke.mjs`, `node advanced-smoke.mjs`.

2026-11-12 실제 EXAONE 합성 평가: 3/3 통과, 7회 API 요청, 총 2,582토큰. 실제 Chrome·계정 작업 성공률의 측정은 아닙니다.

v2.6.0: 도구 실행 전후마다 대화 체크포인트를 저장합니다. 여러 도구 중 일부 실행 후 앱이 중단되어도 저장된 결과를 유지하며, 아직 실행하지 않은 도구와 실행 결과가 확정되지 않은 도구를 구분합니다. 결과 불명확 작업은 상태 확인 후 이어가도록 에이전트에 지시합니다. 이 기능은 중복 실행 위험을 줄이지만 외부 서비스와의 원자적 저장이나 정확히 한 번 실행을 보장하지 않습니다. 실행 기록에 도구 호출 ID와 응답 단계 번호도 저장합니다.

v2.5.3: 채팅에서 **크롬 연결해줘**, **로그인된 크롬에서 작업해줘**라고 요청하면 AI가 `browser_connect_chrome` 도구로 Chrome 설정 열기와 공유 연결 요청을 시작할 수 있습니다. 원격 디버깅 활성화 및 Chrome 연결 허용은 사용자가 직접 진행합니다. 연결되면 앱의 탭 선택 창이 열립니다. AI 응답이 끝난 뒤 작업할 탭을 선택하고 대화에서 알려주세요. 예약 작업에서는 연결 도구를 사용할 수 없습니다.

v2.5.2: **Chrome 디버깅 열기 · 연결 요청** 버튼이 자동화 Chrome 열기 버튼을 대신합니다. 일반 Chrome의 원격 디버깅 설정을 열고, 설정 활성화를 최대 60초 기다린 뒤 DevTools 연결을 요청합니다. 원격 디버깅 켜기와 Chrome의 공유 허용은 사용자가 직접 진행합니다. 연결 후 앱에서 작업할 탭을 선택하세요. 이미 설정을 마쳤다면 **Chrome DevTools 연결** 창에서 바로 연결할 수도 있습니다.

v2.5.0: **Chrome DevTools 연결**로 실행 중인 개인 Chrome의 로그인된 탭을 읽고 조작할 수 있습니다. 기존 Playwright의 CDP 연결을 사용하며 별도 MCP 서버 설치는 필요하지 않습니다.

1. Chrome 144 이상에서 `chrome://inspect/#remote-debugging`을 열어 원격 디버깅을 켭니다.
2. 엑사원 왼쪽 **Chrome DevTools 연결 → 연결 요청**을 누르고 Chrome의 연결 요청을 허용합니다.
3. 앱에 표시된 목록에서 작업할 탭을 선택하고 연결 창을 닫습니다. `현재 열린 페이지를 확인해줘`처럼 요청하세요.

연결 권한은 Chrome 프로필에 적용되지만 앱의 에이전트는 선택한 탭과 그 작업 팝업만 대상으로 합니다. 탭 목록은 선택 화면에만 표시하며 AI에 자동 전송하지 않습니다. 첫 본문 읽기와 클릭·입력은 기존 승인 절차를 따릅니다. 읽은 본문은 EXAONE API에 전송됩니다. 새 URL을 열라는 요청은 기존 탭을 덮어쓰지 않고 새 작업 탭을 만듭니다. 연결 해제와 앱 종료는 Chrome·탭·로그인 상태를 유지하며, 앱에서 개인 Chrome의 로그인 정보를 삭제하지 않습니다.

Chrome 연결을 거절하거나 설정이 꺼져 있으면 앱에서 안내 오류를 표시합니다. 다른 브라우저의 로그인 정보를 가져오지 않으며 쿠팡의 접근 제한 해제를 보장하지 않습니다. Chrome에서 직접 접속되는 탭을 선택해 사용하세요.

v2.5.1: 쿠팡 파트너스 전용 직접 열기 버튼을 제거했습니다. 로그인된 페이지 작업은 **Chrome DevTools 연결**에서 탭을 선택해 진행하세요.

v2.4.1: **실제 Google Chrome 연결**로 내장 브라우저 호환성을 개선했습니다. Windows에 Chrome이 설치되어 있어야 합니다. 에이전트는 개인 Chrome 프로필에 연결하지 않고 `%APPDATA%\exaone-agent\agent-chrome`에 별도 프로필을 만듭니다. 기존 Chrome 및 v2.4.0 내장 브라우저 로그인은 복사하지 않으므로 전용 Chrome에서 한 번 다시 로그인하세요. 앱 종료 시 전용 Chrome도 닫으며 로그인 상태는 유지합니다. 로그인 정보 삭제는 전용 Chrome 및 이전 내장 브라우저 프로필에만 적용합니다. 쿠팡 URL은 HTTPS로 열며 Access Denied를 감지하면 실제 본문을 확인하지 못했다고 안내합니다. Chrome의 사용자 에이전트·인증서 검증을 변조하지 않습니다. 사이트의 자동화 제한이나 IP 차단은 별개이므로 모든 사이트 접속을 보장하지 않습니다.

v2.4.0: **URL 직접 확인과 로그인 가능한 에이전트 브라우저**를 추가했습니다.

- 채팅에서 `https://... 내용을 확인해줘`라고 요청하면 공개 페이지의 HTML·텍스트·JSON 본문을 읽습니다. 직접 확인은 `파일·환경·예약 관리 → 검색·첨부 → URL 직접 확인`에서도 가능합니다. 최대 2MB, 본문 30,000자, 30초이며 최대 5회 이동을 처리합니다. 로그인·동적 페이지는 브라우저 기능을 사용하세요. 직접 확인 버튼의 결과는 대화에 자동 추가되지 않습니다.
- `이 사이트를 브라우저로 열어 로그인 후 내용을 확인해줘`라고 요청하세요. 별도 **EXAONE 브라우저** 창에서 사용자가 직접 로그인하고 앱의 **완료 · 계속 진행**을 누르면 에이전트가 이어서 작업합니다. 첫 사이트 본문 읽기는 허용을 요청합니다. 읽은 내용은 EXAONE에 전송되고 대화 기록에 저장됩니다.
- 에이전트는 본문, 버튼·링크·입력란 목록을 읽고 클릭·텍스트 입력·선택·스크롤할 수 있습니다. 클릭·입력·선택은 대상과 내용을 보여 주고 승인 후 실행합니다. 변경된 페이지의 오래된 요소는 다시 확인해야 합니다. 조작 후 새 페이지 읽기로 결과를 검증합니다.
- 입력값은 페이지 스냅샷에서 제외하며 비밀번호·인증번호·결제 정보·파일 선택은 에이전트 조작을 차단합니다. 이런 작업은 사용자가 직접 처리하세요. 쿠키와 사이트 저장소를 모델에게 제공하지 않습니다. 로그인은 앱 전용 프로필(`%APPDATA%\exaone-agent\Partitions\exaone-browser`)에 유지되고 일반 Chrome과 분리됩니다. `파일·환경·예약 관리 → 실행 환경 → 브라우저 로그인 정보 삭제`로 초기화할 수 있습니다.
- 브라우저는 최대 5개 창(로그인 팝업 포함)을 지원합니다. iframe·닫힌 shadow DOM·canvas 화면의 읽기/조작, 파일 다운로드, 사이트의 장치 권한 요청은 지원하지 않습니다. 일부 사이트는 내장 브라우저 로그인을 차단할 수 있습니다. 예약 작업에서는 브라우저 도구를 사용할 수 없습니다. 복잡한 작업은 기존 12단계 도구 실행 한도에 맞춰 나누어 요청하세요.

v2.3.0: API 요청의 응답 대기 제한은 **30분**입니다. 일반 대화 응답을 기다리는 동안 입력창에서 후속 요청을 **대기열에 추가**할 수 있습니다(최대 10개, 텍스트 요청). 현재 작업이 끝난 뒤 같은 대화에서 순서대로 처리하므로 앞선 결과도 다음 요청에 반영됩니다. 동시 API 실행이나 진행 중인 추론에 즉시 끼워 넣는 기능은 아닙니다. 대기 요청은 개별 취소할 수 있습니다. 중지·오류 후에는 ‘대기 요청 재개’를 눌러 이어가며, 앱을 다시 열었을 때도 대기 요청은 자동 실행하지 않습니다. 예약 작업과 터미널 실행 중에는 후속 대화 전송을 기다려야 합니다. 대기열이 남아 있으면 예약 작업은 대기합니다.

Windows 시작 메뉴에서 **EXAONE Agent**를 검색하거나 설치된 `EXAONE Agent.exe`를 더블클릭하세요. 배포된 앱은 Node.js나 터미널이 필요하지 않습니다.

1. **API 키 설정**에서 EXAONE 키를 저장합니다. 이 PC에 이미 설정된 키는 자동으로 불러옵니다.
2. **작업 폴더 선택**으로 사용할 폴더를 지정합니다. 폴더를 바꾸면 새 대화를 만들고 기존 대화는 기록에 보관합니다.
3. 메시지를 입력하고 **보내기**를 누릅니다. Enter는 전송, Shift+Enter는 줄바꿈입니다.
4. 파일을 쓸 때 변경 비교를 확인하고 승인하거나 거절합니다. 승인하면 변경 전 백업을 남깁니다.

키는 Electron safeStorage의 Windows 암호화 기능으로 사용자 프로필에 저장되며 화면이나 배포 파일에 포함되지 않습니다. 대화·도구 결과·첨부에서 추출한 텍스트·백업·예약·터미널 기록은 앱 사용자 데이터 폴더의 `workspace.json`에 로컬 저장됩니다. 대화 기록 화면에서 개별 대화를 삭제할 수 있습니다. 파일 백업은 대화 삭제 후에도 유지됩니다.

## 자동 프롬프트 압축 (Windows 2.2.2)

기본적으로 대화 전송량이 **50,000자**를 넘으면 지난 요청과 결과를 자동 요약합니다. 최근 두 사용자 대화 묶음을 우선 유지하고, 이 부분만으로 기준을 넘으면 최신 묶음은 원문으로 유지하면서 더 오래된 내용을 요약합니다. 최신 요청 하나가 큰 경우 그 요청 자체를 자르지 않습니다. 메시지와 도구 호출/응답 쌍을 분리하지 않습니다.

왼쪽 **대화·작업 기록 → 지난 대화 자동 요약·압축**에서 켜기/끄기와 **2만·3만·5만·6만 자** 기준을 설정할 수 있습니다. 생성된 요약은 같은 화면에서 펼쳐 볼 수 있고, 채팅 아래에 원본/전송 문자 수와 감소율이 표시됩니다. 원본 대화는 로컬에 그대로 남습니다. 표시되는 감소율은 토큰 수나 비용 절감률이 아닙니다.

요약 요청에도 API 사용량이 발생하며 일부 세부 내용은 생략될 수 있습니다. 한 번 만든 요약은 새 메시지를 보낼 때도 재사용합니다. **기존 요약 + 요약 이후 대화 + 시스템 지침을 합친 실제 전송 메시지**가 다시 기준을 넘을 때만 추가 요약합니다. 원본 기록의 크기가 큰 것만으로는 재요약하지 않습니다. 최신 요청 외에 새로 압축할 과거 구간이 없으면 반복 요약하지 않습니다. 새 요약이 기존 전송 내용보다 짧지 않으면 기존 전송 내용을 유지합니다. 요약과 압축 설정은 앱을 다시 열어도 유지됩니다.

## 작업 관리와 터미널 (Windows 2.0.0)

### 2.1.0 개선

1. 답변을 SSE 스트리밍으로 즉시 표시합니다. 추론 내용 자체는 노출하지 않고 추론 중 상태만 표시합니다. 중간 연결 종료 시 미완성 도구 요청을 실행하지 않습니다.
2. 전송할 대화가 60,000자를 넘으면 오래된 대화를 요약하고 최근 사용자 대화 두 묶음은 보존합니다. 원본은 로컬 기록에 유지되며 작업 기록 화면에서 전송용 요약을 확인할 수 있습니다. 요약에도 API 토큰이 사용됩니다.
3. 응답 대기·추론·답변 수신·명령 실행 단계와 경과 시간을 표시합니다. ‘1/12단계’ 진행률처럼 보이는 문구를 제거했습니다. API 요청 대기 제한은 30분입니다.
4. 인증, 접근 권한, 요청 빈도, 사용량/잔액, 네트워크, 응답 시간 초과를 구분해 안내합니다.
5. API가 반환한 실제 입력·출력·합계 토큰을 요청별로 기록하고 대화 누적 사용량을 표시합니다. 계정 잔여 할당량/잔액을 뜻하지 않습니다. 사용량을 받지 못한 요청은 집계할 수 없습니다.
6. 저장 후 파일 해시를 확인하고, 에이전트의 `verify_result`로 파일 존재·내용 조건을 검사합니다. 변경 작업의 최종 답변 전에 검증 요청을 추가하고 결과 기록을 남깁니다. 종료 코드만으로 전체 요구사항이 충족됐다고 판정하지 않습니다.
7. 터미널은 같은 작업 폴더에서 PowerShell 세션을 유지합니다. `cd`, 변수, 환경변수, 활성화한 가상환경이 다음 명령에 이어집니다. 초기화·중지·시간 초과·exit·앱 종료 후에는 새 세션입니다. 대화형 입력은 지원하지 않습니다.
8. 에이전트/터미널 명령의 실행 전후 파일 생성·수정·삭제를 비교하고 복원할 수 있습니다. 작업 폴더 내부, 최대 3,000항목/깊이 12/파일당 1MB/합계 20MB가 대상이며 숨김·의존성·빌드 폴더는 제외합니다. 폴더 밖, 외부 서비스, 늦게 변경하는 백그라운드 프로세스는 복원 범위가 아닙니다. 비정상 종료 시 저장된 실행 전 스냅샷을 다음 시작에 비교합니다.
9. 예약 작업을 별도 세션/실행 화면에서 처리합니다. 현재 대화와 입력 초안은 유지하며 완료 후 결과를 선택해 열 수 있습니다. 파일 충돌 방지를 위해 일반 작업과 예약 작업은 동시에 실행하지 않습니다.

아래는 기본 기능 설명이며, 터미널 세션과 명령 변경 추적은 위 2.1.0 동작을 따릅니다.

- **대화·작업 기록**: 앱 종료 후 대화·작업 폴더 복원, 이전 대화 열기·삭제, 실행 기록 조회. 실패한 작업의 완료된 도구 단계도 보관합니다.
- **파일 복원**: 저장 승인 시 줄 단위 비교, 변경 전 백업, 변경 전·후 보기 및 되돌리기. 외부 수정이 있으면 복원을 중단합니다. 파일 저장 도구는 100KB 이하, 명령 변경 추적은 위 범위에서 지원합니다.
- **계획·진행**: 에이전트가 계획 도구를 호출하면 단계별 상태와 완료 비율을 표시합니다. 모델 응답·도구 실행·API 재시도 상태도 표시합니다.
- **오류 분석·재시도**: API 429/502/503/504 응답은 최대 2회 재시도합니다. 실패·중단 후 ‘오류 분석 후 이어가기’로 기존 도구 결과와 오류를 참고해 남은 작업을 요청합니다. 이미 실행된 명령은 자동 롤백되지 않습니다.
- **실행 환경**: Python·Node.js·npm 경로/버전과 `.venv`/`venv`/`env` 확인. 가상환경 생성 요청 버튼은 채팅에 요청문을 준비하며 사용자가 전송한 뒤 승인 절차로 실행합니다.
- **첨부·검색**: PDF·DOCX·UTF-8 텍스트 첨부(파일당 10MB, 최대 5개, 추출 텍스트 합계 120,000자), 프로젝트 파일명·내용 검색. PDF는 최대 100쪽/80,000자이며 스캔 OCR은 지원하지 않습니다. 첨부는 다음 메시지와 함께 API에 전송됩니다.
- **웹 검색**: DuckDuckGo 결과·요약·출처 링크. 별도 검색 키 없이 동작하며 검색 서비스의 자동 요청 제한 시 오류를 표시합니다. 웹 문서 전문을 읽는 브라우저 기능은 아닙니다.
- **예약·알림**: 5분 이상 간격 또는 매일 지정 시각, 일시 중지·재개·삭제, 완료/실패 Windows 알림. 앱이 켜져 있어야 하며 다른 작업이나 미전송 첨부가 있으면 대기합니다. 종료 중 놓친 예약은 다음 실행 시 한 번만 처리합니다. 예약 작업도 기존 승인 규칙을 따릅니다.
- **PowerShell 터미널**: 직접 입력한 명령을 추가 승인 없이 실행, 실시간 출력·종료 코드·중지·최근 100개 기록. 여러 줄을 한 번에 실행할 수 있습니다. 최대 5분, 출력 64,000자. 터미널 출력은 AI에 자동 전송하지 않습니다.

## 기능과 범위

- 한국어 대화, 추론 강도 선택, 폴더 조회, 최대 100KB UTF-8 파일 읽기·쓰기
- 작업 폴더 외부 및 `.env`, `.git`, `.ssh`, 키 파일 접근 제한
- 파일 작성 전 전체 내용 확인; 새 파일의 상위 폴더는 미리 만들어야 합니다
- 승인 후 PowerShell 명령 실행: 프로그램/스크립트 실행, 테스트, 설치 등의 작업 가능
- 실행 출력 및 종료 코드 표시, 기본 60초·최대 300초 제한, 중지 버튼
- 대화형 터미널 입력은 지원하지 않습니다
- 오류가 발생해도 이미 승인한 파일 변경은 유지됩니다

대화와 읽은 파일은 EXAONE API에 전송됩니다. 경로 제한은 OS 샌드박스가 아니므로 신뢰할 수 있는 전용 작업 폴더를 사용하세요.

## 명령 실행 (Windows 1.1.0)

예: “Node.js 버전을 확인해줘”, “현재 폴더의 테스트를 실행해줘”, “이 파이썬 파일을 실행해줘”. 에이전트가 명령을 제안하면 **명령 실행 승인** 창에서 목적·시작 폴더·전체 명령·제한 시간을 확인하고 승인하거나 거절합니다. 실행 기록은 채팅에 표시됩니다.

Windows PowerShell 5.1을 사용자 권한으로 실행합니다. 프로필과 대화형 입력은 비활성화하며 API 키 등 앱 환경변수를 자동 전달하지 않습니다. 파일 도구의 경로 제한과 달리 **승인한 명령은 시작 폴더 밖의 파일과 네트워크에도 접근할 수 있습니다.** 실행 출력도 EXAONE API로 전송됩니다. 출력은 64,000자까지 보관합니다.

중지 버튼은 응답 생성·승인 대기·실행 중인 명령을 취소합니다. 시간 초과/중지 시 해당 프로세스 트리 종료를 요청하지만 이미 발생한 파일 변경, 설치, 외부 요청은 되돌리지 않습니다. 분리 실행한 프로그램이나 관리자 권한 프로세스까지 항상 종료됨을 보장하지는 않습니다.

## 유사 명령 자동 승인 (Windows 1.2.0)

명령 승인 창에서 **이 유형의 명령은 다음부터 자동 승인**을 선택한 뒤 실행하면 규칙이 저장됩니다. 기본값은 꺼짐입니다. 거절하면 규칙은 저장되지 않습니다. 규칙은 승인한 작업 폴더와 제한 시간 범위에만 적용되며 앱 재시작 후에도 유지됩니다. 왼쪽 **자동 승인 관리**에서 범위를 확인하고 개별 규칙을 삭제할 수 있습니다. 적용된 자동 승인은 대화에 표시됩니다.

- `Get-Date`: 날짜 조회 및 `-Format` 표시 형식 변경을 같은 유형으로 처리
- `git status`: 상태 조회 및 명시된 요약·브랜치·추적 표시 옵션만 같은 유형으로 처리
- `node` / `python` / `python3` 버전 조회: 해당 프로그램의 버전 옵션을 같은 유형으로 처리
- 그 외 단일 명령: 인수를 포함한 동일 명령에만 적용 (인용문 밖 공백 차이는 허용)
- 파이프, 명령 연결, 변수, 치환, 리디렉션 등 복잡한 구문: 자동 승인 대상에서 제외

스크립트나 프로그램 파일 자체의 변경 여부는 검사하지 않으므로 승인한 작업 폴더와 파일을 신뢰할 때 사용하세요. 이 기능은 Windows 앱에 적용되며 CLI와 Android 앱의 승인 정책은 바꾸지 않습니다.

## 개발

Node.js 22.13 이상이 필요합니다. OneDrive에서 설치 도구가 파일을 생성하지 못하면 일반 로컬 폴더에 소스를 복사해 빌드하세요.

```powershell
npm install
npx install-electron
npm start
npm test
npm run test:desktop
npm run build
npm run build:exe
```

빌드 결과는 `dist/EXAONE Agent-win32-x64/EXAONE Agent.exe`입니다. 이동할 때는 실행 파일 하나가 아니라 폴더 전체를 옮겨야 합니다. 배포물에 `.env`가 제외됩니다.

`npm run build:exe`는 파일 하나로 옮길 수 있는 `release/EXAONE-Agent-Portable.exe`를 만듭니다. 설치 없이 실행되며 처음 실행할 때 임시 폴더에 실행 구성요소를 풀기 때문에 잠시 기다릴 수 있습니다. API 키는 포함되지 않습니다. 다른 PC에서는 앱의 API 키 설정에서 입력하세요.

기존 CLI도 `npm run cli`로 사용할 수 있습니다. CLI의 키는 `.env` 또는 `EXAONE_API_KEY` 환경변수에서 읽습니다.

데스크톱 자동 테스트는 실제 창과 IPC를 사용하며 API 응답만 모의 처리합니다. 키 설정, 폴더 선택, 파일 저장 거절·승인, 대화 초기화를 검증합니다. 실제 EXAONE API 연결도 패키징된 앱에서 별도로 확인했습니다.

1.1.0에서는 명령 실행 승인·거절, 실제 PowerShell 실행, 출력 표시, 중지도 데스크톱 테스트로 검증했습니다. 단위 테스트 6개가 통과했으며 실제 EXAONE의 `run_command` 호출로 `Get-Date` 실행까지 확인했습니다.

공식 문서: [K-EXAONE 2.5 API](https://docs.exaone.ai/ko/docs/k-exaone-2.5), [에이전트 안내](https://docs.exaone.ai/ko/docs/agent-start).
