# Milestone: `oto-agent` 등록 흐름

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/edge-direct-oto-agent/PHASE.md`

## 목표

설치된 `oto-agent`가 `iop-node`를 거치지 않고 Edge에 직접 outbound 연결하는 등록 흐름을 구현 가능한 단위로 정리한다.

## 상태

[진행중]

## 구현 잠금

- 상태: 잠금
- 결정 필요:
  - [ ] iop에서 OTO에 대한 Edge 직접 통신 경로가 확보되었는지 확인한다.

## 범위

- Edge bootstrap script로 설치된 Linux `oto-agent`가 `~/.oto/agent/config.yaml`을 읽고 Edge에 직접 outbound 등록하는 흐름을 정의한다.
- bootstrap script가 전달한 agent 식별 값과 Edge 연결 정보를 사용해 등록을 시작하는 최소 흐름을 정의한다.
- 백그라운드 등록/실행 후 Edge 등록 완료와 최초 heartbeat 도착까지의 상태 전이를 정의한다.
- Edge identity 검증, checksum/signature, 장기 credential 세부 정책은 MVP 이후 보안 강화 항목으로 분리한다.

## 기능

### Epic: [registration-contract] Edge 직접 등록 계약

bootstrap으로 설치된 Linux `oto-agent`가 설정 파일을 읽고 Edge에 직접 등록되는 상태 전이를 묶는다.

- [x] [token-flow] bootstrap agent 식별 값 또는 token의 전달과 최초 등록 사용 흐름이 정의되어 있다.
- [x] [edge-identity] Edge identity 검증을 MVP 최소 연결 기준과 후속 보안 강화 기준으로 분리해 정리되어 있다.
- [x] [binary-integrity] OTO repo release asset 다운로드 기준과 후속 checksum/signature 강화 기준이 분리되어 있다.
- [x] [service-runtime] 백그라운드 실행 상태와 agent 프로세스 재시작 기준이 정의되어 있으며, bootstrap script 실행 후 다운로드된 `oto-agent`가 `~/.oto/agent/config.yaml`을 통해 Edge에 직접 연결하는 상태 전이가 구현 가능한 수준으로 분해되어 있다.
- [ ] [registration-state] Edge 등록 성공/실패, 최초 heartbeat 기반 online 판정, 재시도 기준과 백그라운드 실행 실패/등록 실패/heartbeat 미도착 상태 구분이 정의되어 있다. 검증: Edge 등록 완료와 최초 heartbeat 도착을 online으로 보는 판정 기준, 실패 상태 구분, 재시도 기준이 구현 가능한 수준으로 설명된다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: `registration-state`와 online/실패/heartbeat 기준이 남아 있어 완료 후보가 아니다.
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- generic node agent 기능을 포함하지 않는다.
- 원격 파이프라인 실행 메시지 전체를 구현하지 않는다.
- 운영용 인증서 관리 시스템을 구현하지 않는다.
- MVP에서 checksum/signature, Edge fingerprint, credential rotation 강제 구현을 포함하지 않는다.

## 작업 컨텍스트

- 관련 경로: `lib/oto/**`, `test/oto_agent_*`, `assets/script/shell/oto_agent_bootstrap.sh`
- 선행 Edge bootstrap 계약은 완료 상태로 아카이브되었으며, 일반 작업에서는 활성 Phase의 archive 링크와 아래 표준선을 기준으로 한다.
- 선행 계약의 상세 문서는 과거 기록 확인이나 복원이 명시된 경우에만 읽는다.
- 표준선(선택): Linux MVP는 OTO가 없는 대상 머신에서 bootstrap script로 release asset을 다운로드한 뒤 `~/.oto/agent/config.yaml`을 생성하고 백그라운드로 실행한다.
- 표준선(선택): online 판정은 Edge 등록 완료와 최초 heartbeat 도착을 모두 만족했을 때로 둔다.
- 표준선(선택): bootstrap agent 식별 값 또는 token은 보안 완성보다 등록 대상 식별과 최초 연결 매칭을 위한 최소 계약으로 먼저 둔다.
- 표준선(선택): 바이너리 무결성은 후속 강화 항목으로 두고, MVP에서는 release asset 다운로드 기준과 실패 처리만 먼저 정리한다.
- 구현 근거: `AgentConfig`는 `~/.oto/agent/config.yaml` 형태의 `agent.id`, `agent.alias`, `agent.enrollment_token`, `edge.url`, runtime 경로를 파싱한다.
- 구현 근거: `CommandAgent`는 `oto agent run --config <path>`를 통해 설정 파일을 읽고 `AgentRunner`로 등록을 시작한다.
- 구현 근거: `EdgeRegistrationClient`는 `proto_socket`으로 Edge endpoint에 연결해 enrollment token을 `RegisterRequest`로 전송하고 `RegisterResponse`를 accepted/rejected 결과로 변환한다.
- 구현 근거: registration/config/CLI 검증은 `test/oto_agent_config_test.dart`, `test/oto_agent_registration_test.dart`, `test/oto_agent_cli_test.dart`, `test/oto_iop_connection_smoke_test.dart`에 있다.
- MVP 재시작 기준: bootstrap으로 시작한 background 프로세스의 pid/log를 기준으로 사용자가 상태를 확인하고 `oto agent run --config <path>`를 재실행한다. 자동 재시작과 systemd user service는 후속 강화로 둔다.
- 남은 작업: Edge 등록 완료 이후 최초 heartbeat 도착까지의 online 판정과 재시도 정책은 agent 메시지/heartbeat 흐름과 맞물려 별도 정리가 필요하다.
- 선행 OTO Milestone: OTO-iop proto-socket 통신 기반
- 선행 iop Milestone: agent bootstrap OTO enrollment
- 외부 의존 잠금: iop에서 OTO에 대한 Edge 직접 통신 경로가 확보되면 이 Milestone은 잠금 해제 후보가 된다. 런타임 판별은 프로젝트 상위 `.agent-roadmap-sync/locks.yaml`에서 관리한다.
- 책임 경계: iop는 Edge outbound enrollment를 받아들이는 registry/protocol/credential 기준을 정리한다.
- 책임 경계: OTO는 설치된 `oto-agent`가 해당 기준을 소비해 설정을 만들고 Edge에 직접 outbound 연결하는 상태 전이를 정리한다.
- 네트워크, 설치, packaging 관련 코드나 문서가 추가될 경우 관련 도메인 rule을 먼저 확인한다.
- 구현 계획: `agent-task/m-oto-agent-registration/` 하위 plan-code-review 루프로 진행한다.
- 확인 필요: Edge 등록 완료 이후 최초 heartbeat 도착까지의 online 판정과 재시도 정책을 agent 메시지/heartbeat 흐름과 맞춰 정리한다.