# Milestone: Specialized Agent proto-socket 연결 기반

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/automation-runtime-bridge/PHASE.md`

## 목표

generic `iop-node`와 OTO 같은 specialized domain agent가 기존 Edge-Node proto-socket 흐름을 node-compatible peer로 재사용할 때의 iop Edge 쪽 계약을 정리한다.
OTO 쪽 Dart `proto_socket` 연결과 iop Edge 등록 smoke가 이미 시작된 상태를 기준으로, iop에서는 새 transport보다 agent kind, registry/config 경계, run/event/command 재사용 기준, reconnect 정책을 확정한다.

## 상태

[폐기]

## 구현 잠금

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

## 범위

- 기존 Edge-Node proto-socket outbound TCP session, heartbeat, parser map, request-response 흐름을 specialized agent의 기본 연결 방식으로 재사용하는 기준을 정리한다.
- OTO agent를 `apps/node` adapter나 하위 프로세스로 흡수하지 않고, Edge에 직접 붙는 node-compatible specialized peer로 다룬다.
- `RegisterRequest(token)`은 우선 유지하고, token이 가리키는 Edge-side 등록 record에서 `generic-node`와 `oto-agent` 같은 agent kind를 구분하는 방향을 후보로 둔다.
- `RegisterResponse`의 config 전달 패턴은 재사용하되, 기존 `NodeConfigPayload`를 그대로 줄지, OTO 전용 config를 후속 메시지로 분리할지 판단 기준을 정리한다.
- `RunRequest/RunEvent`, `CancelRequest`, `NodeCommandRequest/Response`의 envelope 재사용 범위와 OTO 전용 build/deploy payload, artifact/log/progress 의미의 분리 기준을 잡는다.
- OTO Dart `proto_socket` consumer와 iop Go Edge transport 사이의 smoke 범위를 registration에서 run/command까지 확장할지 판단한다.

## 기능

### Epic: [node-compatible-flow] Node-Compatible Flow Mapping

- [x] [node-flow-map] 기존 Edge-Node 등록, config, run/event, command, heartbeat 흐름이 specialized agent 관점에서 매핑되어 있고 Agent Bootstrap과 OTO 등록이 통신 기반을 추측하지 않고 후속 계약을 작성할 수 있다.
- [x] [oto-interop] OTO Dart `proto_socket` consumer가 iop Edge의 기존 `RegisterRequest/RegisterResponse` 등록 smoke 경로를 통과하는 근거가 확인되어 있고 OTO의 proto-socket 통신 기반 Milestone과 같은 책임 경계를 참조한다. 검증: OTO Dart client의 iop Edge registration smoke 근거와 후속 run/command smoke 요구 범위가 문서에 남아 있다.
- [x] [runtime-path-boundary] generic Node, specialized domain agent, remote terminal bridge 경로가 제품/transport 수준에서 구분된다.
- [x] [bootstrap-precondition] Agent Bootstrap과 OTO 등록이 의존할 transport/handshake 선행 조건이 명확하다.

### Epic: [agent-kind-registry] Agent Kind와 Registry Entry

- [x] [agent-kind] Edge registry에서 generic Node와 specialized domain agent를 구분하는 기준 후보와 proto field 추가가 필요한 시점/조건이 정리되어 있다.
- [x] [registry-entry] connected entry가 agent kind, capability, lifecycle을 가질 수 있는지, 기존 `NodeEntry`/registry를 확장할지 별도 registry로 분리할지 기준이 정리되어 있다.
- [x] [reconnect-policy] duplicate connection, reconnect, 기존 연결 대체/거부 정책이 specialized agent 관점에서 정리되어 있다.

### Epic: [config-message-boundary] Config와 Message Boundary

- [x] [config-boundary] `RegisterResponse`의 `NodeConfigPayload`를 OTO에 어떻게 적용할지, 최소 config와 OTO 전용 config 분리 기준이 정리되어 있다.
- [x] [message-boundary] 기존 Node 메시지 재사용과 specialized agent 전용 메시지 분리 기준이 문서화되어 있고 proto schema나 registry schema 구현 전 결정 후보와 확인 필요 항목이 정리되어 있다.

## 완료 리뷰

- 상태: 폐기
- 요청일: 2026-05-25
- 완료 근거: 모든 기능 Task와 Task 안에 명시된 검증이 충족되어 완료 후보로 정리했다. 기존 Edge-Node proto-socket 재사용, Edge-side agent kind 판별, config/message boundary, reconnect 정책, bootstrap 선행 조건이 계약 결정에 반영되어 있다. OTO 직접 연결 Phase와 remote terminal bridge Phase 경계를 참조해 generic Node, specialized agent, agentless terminal bridge 경로를 분리했다.
- 리뷰 필요:
  - [x] 사용자가 OTO 독립형 실행 방식 전환을 결정했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: OTO가 Edge 직접 proto-socket specialized peer가 아니라 독립형 실행 방식으로 바뀔 예정이므로 이 연결 기반 마일스톤은 폐기한다.

## 범위 제외

- proto schema와 생성 코드를 변경하지 않는다.
- Edge registry/API/DB schema를 구현하지 않는다.
- OTO agent를 `apps/node` adapter나 하위 프로세스로 흡수하지 않는다.
- bootstrap command 발급, credential 발급, 장기 credential 재발급을 구현하지 않는다.
- registration 이후 build/deploy artifact, log stream, self-update 전체 메시지 세트를 확정하지 않는다.

## 계약 결정

### Runtime Path Boundary

- generic Node는 기존 `iop-node`가 Edge-Node proto-socket transport로 연결되고, Node runtime/adapter execution을 소유하는 경로다.
- specialized domain agent는 OTO처럼 Edge에 직접 outbound 연결하는 node-compatible peer이며, 초기 handshake와 heartbeat는 재사용하되 build/deploy domain payload는 필요 시 전용 typed payload로 분리한다.
- remote terminal bridge는 agent 설치가 어렵거나 일회성 유지보수 대상에 쓰는 별도 운영 경로이며, Edge가 session broker가 되고 Node terminal transport가 대상 shell/SSH/WinRM/serial 실행을 맡는다.
- 세 경로는 OpenAI-compatible/A2A 입력 표면에 terminal 제어를 억지로 싣지 않고, 제품 UX와 transport 책임을 분리한다.

### OTO Responsibility Boundary

- OTO의 직접 연결 기준은 `../oto/agent-roadmap/phase/edge-direct-oto-agent/PHASE.md`와 완료된 `../oto/agent-roadmap/archive/phase/edge-direct-oto-agent/milestones/oto-iop-proto-socket-foundation.md`를 참조한다.
- iop는 Edge-side registration, token/agent kind 판별, config 전달, reconnect policy, envelope 재사용 기준을 소유한다.
- OTO는 Dart `proto_socket` client, Linux agent 설치 산출물, OTO build/deploy domain config와 event 의미를 소유한다.
- registration 이후 run/command는 이번 마일스톤에서 envelope compatibility 확인 기준까지만 요구하고, OTO build/deploy payload 상세는 후속 OTO agent message protocol로 넘긴다.

### Agent Kind / Registry Entry

- `RegisterRequest`에는 당장 kind field를 추가하지 않는다.
- Edge-side registration record가 `agent_kind`를 소유하며 초기 후보는 `generic-node`, `oto-agent`다.
- connected entry는 `agent_kind`, capability summary, lifecycle state를 담을 수 있는 agent entry로 확장하는 방향을 1차 후보로 둔다.
- 별도 registry는 generic Node와 specialized agent의 routing/index/display 규칙이 분리되어야 할 때 선택한다.

### Config / Message Boundary

- `RegisterResponse`는 accepted/node_id/alias/config 패턴을 유지한다.
- generic Node에는 `NodeConfigPayload`를 그대로 보낸다.
- `oto-agent`에는 최소 runtime identity/config만 공통 handshake에서 전달하고, build/deploy 전용 설정은 후속 OTO config message나 typed payload가 필요해질 때 분리한다.
- `RunRequest/RunEvent`, `CancelRequest`, `NodeCommandRequest/Response`는 envelope와 request-response 패턴만 재사용한다.
- artifact/log/progress/build-result 의미는 Node adapter stream으로 확정하지 않고 OTO 전용 payload 후보로 둔다.

### Reconnect / Duplicate Policy

- 같은 agent identity의 중복 연결 기본값은 reject다.
- 명시적인 reconnect token/session generation이 생기기 전에는 기존 연결 자동 대체를 하지 않는다.
- 후속 구현에서 replace를 허용할 경우 old connection close reason과 audit event가 먼저 정의되어야 한다.

### Bootstrap Preconditions

- 후속 bootstrap/enrollment는 Edge outbound proto-socket listener, token 기반 registration, accepted/node_id/alias response, heartbeat를 선행 조건으로 가정할 수 있다.
- agent kind는 bootstrap token/registration record에 묶인다.
- bootstrap command UX, credential 보안 기준, 초기 capability/run 준비 범위는 `Agent Bootstrap과 OTO 등록` 마일스톤의 잠금 결정으로 남긴다.
- 이번 마일스톤의 run/command smoke 요구는 registration 이후 envelope compatibility 확인 기준까지만 둔다.

## 작업 컨텍스트

- 관련 경로: `proto/iop/runtime.proto`, `apps/edge/internal/transport/server.go`, `apps/node/internal/transport/client.go`, `apps/node/internal/transport/session.go`, `apps/edge/internal/node/registry.go`, `../oto/agent-roadmap/phase/edge-direct-oto-agent/PHASE.md`, `../oto/agent-roadmap/phase/edge-direct-oto-agent/milestones/oto-agent-registration.md`, `../oto/agent-roadmap/phase/message-based-build-agent/milestones/agent-message-protocol.md`, `../oto/test/oto_iop_connection_smoke_test.dart`, `../proto-socket/`
- 표준선(선택): 기존 Edge-Node proto-socket transport와 `RegisterRequest/RegisterResponse`를 우선 재사용하고, agent kind는 Edge-side registration record에서 판별한다.
- 선행 작업: Edge-Node 실행 스켈레톤, CLI Automation Runtime 안정화
- 후속 작업: Agent Bootstrap과 OTO 등록
- 확인 필요: oto-agent를 위한 후속 typed payload 형식, build/deploy 전용 설정 형식.
- 폐기 결정: OTO는 독립형 실행 방식으로 전환될 예정이므로 Edge 직접 specialized peer/proto-socket 연결 기반 정리는 현재 로드맵에서 제외한다.
