# AX Agent 구조 리뷰

업데이트: 2026-04-15 18:20 (KST)

## 1. 목적
- AX Agent의 현재 구조를 실행 엔진, 루프 정책, 세션 저장, transcript 렌더 관점에서 정리합니다.
- 외부 제품 비교 대신 AX 내부 구조와 참조 모듈 흐름만 문서화합니다.

## 2. 현재 구조

### 실행 계층
- `src/AxCopilot/Services/Agent/AxAgentExecutionEngine.cs`
- `src/AxCopilot/Services/Agent/AgentLoopService.cs`
- `src/AxCopilot/Services/Agent/StreamingToolExecutionCoordinator.cs`

### 루프 정책 계층
- `src/AxCopilot/Services/Agent/AgentLoopTransitions.Execution.cs`
- `src/AxCopilot/Services/Agent/AgentLoopTransitions.Verification.cs`
- `src/AxCopilot/Services/Agent/AgentLoopTransitions.Documents.cs`
- `src/AxCopilot/Services/Agent/AgentLoopCompactionPolicy.cs`
- `src/AxCopilot/Services/Agent/AgentLoopRuntimeThresholds.cs`

### 세션/상태 계층
- `src/AxCopilot/Services/ChatSessionStateService.cs`
- `src/AxCopilot/Services/ChatStorageService.cs`
- `src/AxCopilot/Services/AppStateService.cs`
- `src/AxCopilot/Models/ChatModels.cs`

### transcript/UI 계층
- `src/AxCopilot/Views/ChatWindow.xaml`
- `src/AxCopilot/Views/ChatWindow.xaml.cs`
- `src/AxCopilot/Views/ChatWindow.TranscriptHost.cs`
- `src/AxCopilot/Views/ChatWindow.TranscriptRendering.cs`
- `src/AxCopilot/Views/ChatWindow.TranscriptRenderPlanner.cs`
- `src/AxCopilot/Views/ChatWindow.TranscriptRenderExecution.cs`
- `src/AxCopilot/Views/ChatWindow.TranscriptVirtualization.cs`

## 3. 강점
- Chat / Cowork / Code를 하나의 창과 정책 체계 안에서 운영
- 등록 모델별 실행 프로파일과 verification gate 지원
- 문서 생성 계열 fallback과 품질 리뷰가 루프에 결합되어 있음
- 메모리, slash, permissions, queue가 한 세션 상태에 연결되어 있음

## 4. 구조 리스크
1. `ChatWindow.xaml.cs` 책임이 여전히 크고, UI 이벤트와 런타임 상태 조립이 섞여 있습니다.
2. transcript와 status line이 더 단일한 런타임 상태를 기준으로 계산되면 유지보수가 쉬워질 여지가 있습니다.
3. replay/reopen 경로는 안정화가 많이 진행됐지만, 장기 세션에서는 이벤트 정규화 규칙이 더 중요합니다.
4. 설정이 실행 경로를 바꾸는 지점은 사용자용과 개발용 노출 범위를 더 구분할 필요가 있습니다.

## 5. 개선 우선순위

### A. 런타임 상태 단일화
- 참조 모듈: `src/bootstrap/state.ts`, `src/bridge/initReplBridge.ts`
- AX 적용 위치: `ChatWindow.xaml.cs`, `AxAgentExecutionEngine.cs`, `ChatStorageService.cs`
- 완료 조건:
  - 현재 턴, queue, retry, 실행 이벤트, 저장 스냅샷이 같은 런타임 상태 모델을 사용
  - reopen 뒤 저장 상태와 렌더 결과가 어긋나지 않음

### B. 이벤트 정규화
- 참조 모듈: `src/bridge/sessionRunner.ts`, `src/bridge/bridgeMessaging.ts`
- AX 적용 위치: `AgentLoopService.cs`, `AgentLoopTransitions.cs`, `AppStateService.cs`
- 완료 조건:
  - tool start/result/error/progress, permission, retry, complete 이벤트가 안정적인 스키마를 공유
  - replay 시 visible banner 중복 0건

### C. timeline 유도 모델 고정
- 참조 모듈: `src/screens/REPL.tsx`, `src/components/Messages.tsx`
- AX 적용 위치: `ChatWindow.xaml`, `ChatWindow.xaml.cs`
- 완료 조건:
  - assistant/user message, execution log, compact boundary, queue summary를 하나의 derived timeline에서 생성
  - direct imperative bubble injection 제거

### D. status/composer 정리
- 참조 모듈: `src/components/StatusLine.tsx`
- AX 적용 위치: `ChatWindow.xaml`, `ChatWindow.AgentStatusPresentation.cs`
- 완료 조건:
  - status strip, queue summary, runtime activity가 debounce된 같은 상태 소스를 사용
  - composer는 명시적 줄바꿈 중심으로만 성장

## 6. 검증 기준
- reopen 후 최신 assistant state가 저장 상태와 동일
- retry/regenerate/queue follow-up이 서로 다른 실행 경로로 분기되지 않음
- permission popup, inline ask, plan approval이 transcript 기준으로 닫힘
- `dotnet build` 경고 0 / 오류 0

## 7. 최근 메모
- 2026-04-06 09:36 (KST): 상태 strip 표현과 permission/tool-result 설명 카탈로그를 분리
- 2026-04-06 09:44 (KST): mixed inline interaction rendering을 presentation 파일로 분리
- 2026-04-06 09:58 (KST): Git branch popup과 footer 보조 요약 helper를 분리
- 2026-04-06 10:07 (KST): topic preset 렌더와 선택 흐름을 전용 presentation 파일로 이동
- 2026-04-06 11:52 (KST): permission, tool-result, skill gallery 설명층을 고도화