# AX Agent 실행 개선 계획

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

## 1. 목적
- AX Agent의 실행 신뢰성, 권한 처리 일관성, 세션 복원 품질을 높입니다.
- 외부 제품명 비교 대신 실제 참조 모듈 경로와 AX 적용 위치만 기준으로 관리합니다.
- UI 보정만으로 가리는 수정은 지양하고 `상태 -> 실행 -> 렌더` 순서로 정리합니다.

## 2. 현재 판단
- 실행 엔진과 루프 품질은 안정 구간에 들어왔지만, 장기 세션 복원과 이벤트 정규화는 계속 다듬을 여지가 있습니다.
- 설정이 런타임 경로를 바꾸는 지점은 사용자 설정과 개발자용 실험 설정을 더 분리할 필요가 있습니다.
- transcript, status line, queue 표시는 충분히 가벼워졌지만 상태 계산 소스는 더 단일화해야 합니다.

## 3. 참조 흐름

| 참조 모듈 | AX 적용 위치 | 완료 조건 | 품질 판정 기준 |
|---|---|---|---|
| `src/bootstrap/state.ts` | `src/AxCopilot/Views/ChatWindow.xaml.cs`, `src/AxCopilot/Services/Agent/AxAgentExecutionEngine.cs`, `src/AxCopilot/Services/ChatStorageService.cs` | 현재 턴, queue, retry, 실행 이벤트, 저장 스냅샷이 하나의 런타임 상태 모델로 정리 | reopen/retry/queue 후 중복 assistant 카드나 빈 카드가 생기지 않음 |
| `src/bridge/initReplBridge.ts` | `src/AxCopilot/Services/Agent/AxAgentExecutionEngine.cs`, `src/AxCopilot/Services/LlmService.cs` | send/regenerate/retry/queued follow-up/slash가 하나의 실행 준비 경로를 통과 | 같은 입력과 설정에서 진입점이 달라도 실행 경로가 흔들리지 않음 |
| `src/bridge/sessionRunner.ts` | `src/AxCopilot/Services/Agent/AgentLoopService.cs`, `src/AxCopilot/Services/Agent/AgentLoopTransitions.cs`, `src/AxCopilot/Services/Agent/AgentLoopTransitions.Execution.cs` | tool start/result/error/progress가 루프 계층에서 한 번만 정규화 | Cowork/Code 장기 실행 중 상태 문구가 과도하게 흔들리지 않음 |
| `src/bridge/bridgeMessaging.ts` | `src/AxCopilot/Views/ChatWindow.xaml.cs`, `src/AxCopilot/Services/Agent/AgentLoopService.cs` | 실행 이벤트와 표시 전용 이벤트를 렌더 이전에 분리 | replay 후 visible banner 중복이 발생하지 않음 |
| `src/screens/REPL.tsx`, `src/components/Messages.tsx`, `src/components/StatusLine.tsx` | `src/AxCopilot/Views/ChatWindow.xaml`, `src/AxCopilot/Views/ChatWindow.xaml.cs` | timeline, composer, status strip이 공통 런타임 상태를 사용 | 리사이즈, queue 연속 실행, retry 후에도 UI가 패치식으로 흔들리지 않음 |

## 4. 실행 단계

### A. 런타임 상태 단일화
- 적용 위치: `ChatWindow.xaml.cs`, `AxAgentExecutionEngine.cs`, `ChatStorageService.cs`
- 완료 조건:
  - `Chat`, `Cowork`, `Code`가 같은 런타임 상태 모델을 갱신
  - queue, retry, compact 이후 상태가 재오픈 후에도 동일하게 복원
- 품질 기준:
  - 같은 대화를 다시 열었을 때 보이는 timeline과 저장 상태가 일치
  - queue badge와 최근 실행 이력이 어긋나지 않음

### B. 실행 준비 경로 일원화
- 적용 위치: `AxAgentExecutionEngine.cs`, `LlmService.cs`
- 완료 조건:
  - prompt stack assembly, execution mode choice, final commit이 엔진 기준으로 통합
  - send/regenerate/retry/slash가 동일 API를 사용
- 품질 기준:
  - 같은 탭과 같은 설정에서 실행 경로가 예측 가능
  - UI에서 별도 prompt stack을 만들지 않음

### C. 루프 이벤트 정규화
- 적용 위치: `AgentLoopService.cs`, `AgentLoopTransitions.cs`, `AgentLoopTransitions.Execution.cs`
- 완료 조건:
  - 권한 요청, 실패, 재시도, 완료 이벤트가 안정적인 스키마를 사용
  - bounded activity/event record 기준이 문서화
- 품질 기준:
  - 장기 도구 실행 중 상태 flash가 줄고 debug payload 노출이 최소화

### D. timeline 유도 모델 고정
- 적용 위치: `ChatWindow.xaml`, `ChatWindow.xaml.cs`
- 완료 조건:
  - assistant/user message, 실행 로그, compact boundary, queue summary가 하나의 derived timeline에서 생성
  - 직접 bubble injection 경로 제거
- 품질 기준:
  - blank assistant card 0건
  - token-only completion 0건
  - re-render 뒤 duplicate banner 0건

### E. composer와 status strip 정리
- 적용 위치: `ChatWindow.xaml`, `ChatWindow.xaml.cs`
- 완료 조건:
  - composer height는 명시적 줄바꿈 중심으로만 증가
  - status strip, queue summary, runtime activity가 debounce된 업데이트를 사용
- 품질 기준:
  - resize 이후 입력창이 과하게 커지지 않음
  - metadata가 메시지 본문보다 앞서 보이지 않음

### F. 복구/재개/검증 마감
- 적용 위치: `ChatWindow.xaml.cs`, `AxAgentExecutionEngine.cs`, `ChatStorageService.cs`
- 완료 조건:
  - reopen after interruption, retry-last, regenerate, manual compact, manual stop, manual resume 시나리오를 모두 통과
  - 최신 assistant state와 저장 conversation이 일치
- 품질 기준:
  - 복원 후 마지막 상태가 실제 종료 시점과 같음
  - 세션 재개 후 추가 오류 전파가 없음

## 5. 검증 기준
- `dotnet build` 경고 0 / 오류 0
- 고위험 변경마다 최소 1개 이상 회귀 테스트 추가
- `internal` / `external` 운영 모드 정책 위반 0건
- reopen, retry, regenerate, queue follow-up, permission, compact 시나리오 수동 점검 유지

## 6. 최신 메모
- 2026-04-05 15:34 (KST): 실행 개선 계획을 실제 참조 모듈 흐름 기준으로 재정리했습니다.
- 2026-04-05 16:55 (KST): 엔진, 채팅 UI, 상태 UX, 설정 연동의 구조적 갭을 분리해 정리했습니다.
- 2026-04-06 09:36 (KST): 상태 strip 표현을 전용 카탈로그로 분리하고 permission/tool-result 설명을 정형화했습니다.
- 2026-04-06 10:07 (KST): topic preset과 사용자 상호작용 렌더 책임을 presentation 파일로 계속 분리했습니다.
- 2026-04-06 11:52 (KST): permission, tool-result, skill gallery 설명층을 더 구체적인 운영 정보 중심으로 보강했습니다.