# Milestone: agent 메시지 프로토콜

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/message-based-build-agent/PHASE.md`

## 목표

`oto agent` 또는 `oto daemon` 모드에서 Edge와 proto-socket 기반 양방향 메시지 통신을 하기 위한 기본 메시지 범위와 계약을 정의한다.

## 상태

[계획]

## 구현 잠금

- 상태: 잠금
- 결정 필요: 아래 체크리스트
  - [ ] OTO agent 등록 경계와 iop Edge 쪽 specialized domain agent protocol 경계가 확정되었는가?
  - [ ] proto 파일, 생성 코드, 메시지 버전을 OTO에서 확정해도 되는 단계인가?
  - [ ] 기존 YAML 실행 경로를 유지하면서 원격 메시지 호출 경계를 어디까지 둘지 결정되었는가?

## 범위

- agent register, capabilities, run request, step event, log stream, artifact event, cancel, status, self-update 메시지의 최소 필드를 정의한다.
- 메시지 버전, 호환성, 에러 표현 방식을 정리한다.
- OTO가 Edge의 build/deploy 전용 domain agent라는 경계를 명시한다.

## 필수 기능

### Epic: [message-contract] Edge-agent 메시지 계약

Edge와 OTO agent가 같은 의미로 해석할 기본 메시지 범위와 호환성 기준을 묶는다.

- [ ] [message-list] 기본 메시지 목록과 방향성이 정의되어 있다.
- [ ] [message-fields] 각 메시지의 최소 필드와 실패 응답 형식이 정의되어 있다.
- [ ] [version-capability] 프로토콜 버전과 capability 협상 기준이 정의되어 있다.
- [ ] [domain-boundary] generic node 하위 실행물이 아니라는 제품 경계가 문서화되어 있다.

## 완료 기준

- [ ] Edge와 agent 구현자가 같은 메시지 계약을 기준으로 병렬 작업을 시작할 수 있다.
- [ ] YAML 파이프라인과 커맨드 모델이 메시지 위에서 어떻게 호출되는지 설명된다.
- [ ] 메시지 추가가 기존 CLI 실행 경로를 깨지 않는다는 경계가 명확하다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 계획 상태이며 필수 Task와 완료 기준이 아직 충족되지 않았다.
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- 웹 UI 또는 Edge 관리 화면을 구현하지 않는다.
- 기존 YAML 파이프라인 형식을 대체하지 않는다.
- 모든 운영 보안 정책을 완성하지 않는다.

## 작업 컨텍스트

- 관련 경로: `lib/oto/**`, `test/**`
- CLI 자동화 표면 정리 단계의 구조화 실행 결과와 step event 기준을 먼저 확인한다.
- 표준선(선택): 메시지 형태는 기존 proto-socket 연결 방식과 구조화 실행 결과/step event 계약을 우선 활용하고, YAML 파이프라인 실행 경로를 대체하지 않는 방향으로 잡는다.
- 선행 Milestone: OTO-iop proto-socket 통신 기반
- 선행 Milestone: `oto-agent` 등록 흐름
- 관련 iop Milestone: agent bootstrap OTO enrollment
- 책임 경계: iop는 Edge가 이해해야 하는 specialized domain agent registry/protocol 경계를 정리한다.
- 책임 경계: OTO는 build/deploy domain agent가 노출할 capabilities, YAML run request 연결, step/log/artifact event 의미를 정리한다.
- 프로토콜 파일이나 생성 코드가 추가되면 관련 도메인 rule 또는 새 도메인 rule 필요 여부를 검토한다.
- 확인 필요: 구현 착수 전 proto 파일, 생성 코드, 메시지 버전의 소유 경계를 확정한다.