# Milestone: agent 메시지 프로토콜

## 위치

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

## 목표

`oto agent` 또는 `oto daemon` 모드에서 OTO Server와 runner가 양방향 메시지 통신을 하기 위한 기본 메시지 범위와 계약을 정의한다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- runner register, capabilities, run request, step event, log stream, artifact event, cancel, status, self-update 메시지의 최소 필드를 정의한다.
- 메시지 버전, 호환성, 에러 표현 방식을 정리한다.
- OTO runner가 OTO Server의 build/deploy 전용 실행 표면이며 generic remote shell 하위 실행물이 아니라는 경계를 명시한다.

## 메시지 계약 요약

기본 메시지 목록과 방향성은 `proto/oto/runner.proto`의 `oto.runner.v1` 패키지를 기준으로 한다.

| 방향 | 메시지 | 목적 |
|------|--------|------|
| runner -> server | `RegisterRunnerRequest`, `RegisterRunnerResponse` | enrollment token, runner id, protocol version, capability, command catalog로 runner 등록과 거절 사유를 주고받는다. |
| runner -> server | `HeartbeatRequest`, `HeartbeatResponse` | 등록된 runner의 생존 상태를 갱신하고 unknown runner 또는 terminal state를 거절한다. |
| server -> operator -> runner | `BootstrapCommandRequest`, `BootstrapCommandResponse` | OTO Server가 agent 설치와 등록에 필요한 bootstrap command를 발급한다. |
| runner -> server | `JobClaimRequest`, `JobClaimResponse` | runner가 OTO Server 소유 job/execution을 claim하고 `RunRequest`를 받는다. |
| server -> runner | `RunRequest` | YAML path/content, 변수, 허용 command type 목록으로 OTO pipeline 실행을 지시한다. |
| runner -> server | `ExecutionReportRequest`, `ExecutionReportResponse` | 실행 성공 여부, exit code, message, step event를 보고한다. |
| runner -> server | `LogAppendRequest`, `LogAppendResponse` | 실행 로그 라인을 OTO Server execution log로 append한다. |
| runner -> server | `ArtifactReportRequest`, `ArtifactReportResponse` | 실행 산출물 이름과 경로를 OTO Server execution artifact로 보고한다. |
| server -> runner | `CancelRunRequest`, `CancelRunResponse` | 실행 취소 요청과 실패 사유를 표현한다. |
| server -> runner | `RunnerStatusRequest`, `RunnerStatusResponse` | runner 상태와 현재 execution id 조회를 표현한다. |
| server -> runner | `SelfUpdateRequest`, `SelfUpdateResponse` | runner self-update 버전과 다운로드 위치, 실패 사유를 표현한다. |

제품 경계는 OTO runner를 generic remote shell의 하위 실행물이 아니라 build/deploy 전용 실행 표면으로 두는 것이다. 원격 메시지는 기존 YAML pipeline과 command catalog를 호출하는 계약이며, 로컬 CLI 실행 경로와 YAML 형식을 대체하지 않는다. 따라서 새 메시지는 `RunRequest.command_types`, `StepEventReport`, log/artifact/report 메시지처럼 OTO pipeline 실행 의미를 보존하는 범위에서만 추가한다.

## 기능

### Epic: [message-contract] Server-runner 메시지 계약

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

- [x] [message-list] 기본 메시지 목록과 방향성이 정의되어 있다.
- [x] [message-fields] 각 메시지의 최소 필드와 실패 응답 형식이 정의되어 있다. 검증: OTO Server와 runner 구현자가 같은 메시지 계약을 기준으로 병렬 작업을 시작할 수 있고, YAML 파이프라인과 커맨드 모델이 메시지 위에서 어떻게 호출되는지 설명된다.
- [x] [version-capability] 프로토콜 버전과 capability 협상 기준이 정의되어 있다.
- [x] [domain-boundary] generic node 하위 실행물이 아니라는 제품 경계가 문서화되어 있다. 검증: 메시지 추가가 기존 CLI 실행 경로를 깨지 않는다는 경계가 명확하다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-06
- 완료 근거: 모든 `message-contract` Task가 충족되었다. `message-fields`는 `agent-task/archive/2026/06/m-agent-message-protocol/01_proto_contract/complete.log`, `version-capability`는 `agent-task/archive/2026/06/m-agent-message-protocol/02+01_core_compatibility/complete.log`의 Roadmap Completion으로 충족되었다. `message-list`와 `domain-boundary`는 이 문서의 `메시지 계약 요약`에 직접 정리했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-06 사용자 요청에 따라 현 Milestone을 종료하고 다음 Milestone으로 전환한다.

## 범위 제외

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

## 작업 컨텍스트

- 관련 경로: `apps/runner/lib/oto/**`, `apps/runner/test/**`, `proto/oto/**`, `services/core/**`
- CLI 자동화 표면 정리 단계의 구조화 실행 결과와 step event 기준을 먼저 확인한다.
- 표준선(선택): 메시지 형태는 `proto/oto`의 OTO Server/Runner 계약과 구조화 실행 결과/step event 계약을 우선 활용하고, YAML 파이프라인 실행 경로를 대체하지 않는 방향으로 잡는다.
- 선행 Milestone: 독립 Control Plane 분리 마이그레이션
- 후속 의존: `control-plane-separation-migration`의 `oto-owns-cicd` Task가 OTO Server의 job/execution/log/artifact 소유권을 먼저 확정해야 한다.
- 선행 완료 근거(2026-06-06): `agent-roadmap/archive/phase/independent-control-plane/milestones/control-plane-separation-migration.md`가 `[완료]`로 archive되었고, `agent-task/archive/2026/06/m-control-plane-separation-migration/07+05,06_cicd_smoke_evidence/complete.log`의 Roadmap Completion이 `oto-owns-cicd` 완료를 기록한다.
- 책임 경계: iop는 이 Phase의 wire/protocol 소유자가 아니며, AI provider가 필요한 후속 기능에서만 선택적으로 소비된다.
- 책임 경계: OTO는 build/deploy runner가 노출할 capabilities, YAML run request 연결, step/log/artifact event 의미를 정리한다.
- 프로토콜 파일이나 생성 코드가 추가되면 관련 도메인 rule 또는 새 도메인 rule 필요 여부를 검토한다.
- 완료 동기화(2026-06-06): `message-fields`와 `version-capability`는 각각 proto contract foundation과 Core/Dart compatibility review PASS 완료 로그를 근거로 반영했다.
- 완료 동기화(2026-06-06): `message-list`와 `domain-boundary`는 큰 구현 계획 없이 현재 Milestone 문서의 메시지 계약 요약으로 직접 반영했다.
