iop/apps/edge/README.md

# edge — Edge Execution Group Controller

여러 Node를 하나의 로컬 실행 그룹으로 묶고, IOP 내부 TCP/protobuf 프로토콜을 통해 adapter execution 요청과 이벤트 스트림을 중계한다.

Edge는 현재 단계에서 OpenAI-compatible HTTP API gateway가 아니라 Node registry, node configuration, runtime routing, stream relay를 검증하는 백엔드 실행 그룹 컨트롤러다. 외부 HTTP 호환 계층은 node/transport 경계가 안정화된 뒤 별도 표면으로 추가한다.

**현재 상태: 초기 구현**
node 등록/레지스트리/transport와 edge 콘솔 기반 수동 통신 테스트가 구현되어 있다.

## 내부 경계

edge-local ops console은 최종 API가 아니라 diagnostic surface다. ops console의 `/` 명령은 직접 transport를 다루지 않고 `apps/edge/internal/service`를 호출한다. 이후 HTTP/API handler가 추가되면 같은 service를 호출하고, ops console은 필요하면 수동 테스트 도구로만 남긴다.

ops console은 edge-local diagnostic surface이고, HTTP/API는 central/remote management surface다.

현재 edge 내부 흐름은 다음처럼 나뉜다.

- `internal/transport`: node TCP/protobuf 연결, register handshake, protobuf message 수신
- `internal/node`: node registry와 사전 등록 node store
- `internal/service`: `SubmitRun`, `TerminateSession`, `UsageStatus`, `ListNodes`, `ResolveNode`
- `internal/events`: `RunEvent`, `EdgeNodeEvent` in-process publish/subscribe fanout
- `cmd/edge`: serve/console CLI 진입점과 console 출력 포맷

실행 요청과 이벤트는 같은 TCP 연결을 공유하지만, 메시지 타입과 내부 파이프라인은 분리한다. `RunRequest`, `CancelRequest`, `NodeCommandRequest`는 edge가 node에 보내는 command/request 계열이고, `RunEvent`, `EdgeNodeEvent`는 node와 edge 내부에서 발생한 event 계열이다.

## 원격 CLI adapter E2E Smoke & 수동 테스트

`make test-e2e` 명령은 `scripts/e2e-smoke.sh`를 실행하여 아래의 테스트 흐름을 임시 설정과 `mock` 프로필로 자동 검증한다.
실제 외부 프로필(예: `gemini`)을 테스트하려면 `IOP_E2E_PROFILE=gemini make test-e2e`와 같이 환경 변수를 지정한다.

수동으로 실행하려면 아래 과정을 따른다.

`bin/edge.sh`는 edge 서버를 열고 입력 프롬프트를 제공한다.
`bin/node.sh`는 원격 edge 주소로 접속해 등록한 뒤, edge에서 보낸 `RunRequest`를 `adapter + target` 실행으로 처리한다.
테스트 파라미터는 `configs/edge.yaml`, `configs/node.yaml`에 하드코딩한다.

**전제 조건**: `configs/edge.yaml`의 `console.target`이 가리키는 CLI profile command가 node 호스트에서 실행 가능해야 한다. 기본 예시는 `opencode`이며, `claude`, `gemini`, `codex`, `cline-dgx` 등으로 바꿀 수 있다.

같은 `cli` 어댑터 안에 `claude`, `gemini`, `codex`, `opencode`, `cline` profile을 포함할 수 있다. 예를 들어 `gemini --approval-mode yolo -p <prompt>`, `codex exec --dangerously-bypass-approvals-and-sandbox`, `cline -y --json --config /config/.cline/profiles/ollama-dgx <prompt>`처럼 headless 조합으로 설정한다. `opencode`는 `mode: "opencode-sse"` profile로 `opencode serve`의 HTTP/SSE 인터페이스를 사용하며, args의 `--model`, `--dangerously-skip-permissions`, `--title` 등은 그대로 유지하면 된다.

실행 순서:

1. edge 호스트에서 `configs/edge.yaml`의 `server.listen`, `nodes[].token`을 확인한다. 예시 설정은 `console.adapter=cli`, `console.target=opencode`, `console.session_id=default`를 사용한다.
2. node 호스트에서 `configs/node.yaml`의 `transport.edge_addr`를 edge 호스트 주소로, `transport.token`을 edge token과 같게 맞춘다.
3. edge 호스트의 `9090/tcp` 포트를 node 호스트에서 접근 가능하게 연다.
4. edge 호스트에서 `./bin/edge.sh`
5. node 호스트에서 `./bin/node.sh` — edge 포트가 열릴 때까지 최대 30초 기다린 뒤, edge에서 받은 입력을 선택된 `adapter + target`으로 실행한다.
6. edge 콘솔에서 `/nodes`로 node 등록을 확인한다.
7. (선택 사항) node가 여러 대일 경우 `/node <id|alias>`로 대상을 선택한다. 1대일 경우 자동 선택된다.
8. edge 콘솔의 `edge>` 프롬프트에 메시지를 입력한다.
9. `[node-{alias}-event]` 라인으로 실행 상태를, `[node-{alias}-message]` 라인으로 adapter output을 확인한다.
10. edge 콘솔에서 `/exit` 또는 `quit`로 종료한다.

예상 출력:

```text
edge> hello
[edge] sent run_id=manual-... node=local-node adapter=cli target=opencode session=default background=false
[node-local-node-event] start run_id=manual-...
[node-local-node-event] complete run_id=manual-... detail="opencode sse execution complete"
[node-local-node-message] <adapter output>
```

## Console 명령

| 명령 | 설명 |
|---|---|
| `/nodes` | 연결된 node 목록 확인. 선택된 node는 `*`로 표시됨. |
| `/node <id\|alias>` | 요청을 보낼 명시적 node 선택 |
| `/session <id>` | 현재 console이 사용할 logical session 변경 |
| `/background on\|off` | background 실행 모드 토글 (on: 응답 기다리지 않음) |
| `/terminate-session` | 현재 `adapter/target/session_id`의 worker process 종료 |
| `/status` | 현재 선택된 target/profile의 사용량(Usage Status) 조회 |
| `/capabilities` | 현재 선택된 adapter의 지원 target 등 capability 조회 |
| `/sessions` | 현재 선택된 adapter의 logical session 목록 조회 |
| `/transport` | 현재 선택된 node의 transport/runtime 상태 조회 |
| `/exit` | 콘솔 종료 |

`/capabilities`, `/sessions`, `/transport`는 `NodeCommandResponse.result` 맵을 그대로 키 정렬 순서로 출력한다. adapter가 명령을 지원하지 않거나 응답을 비워둔 경우 명시적인 unsupported / empty-payload 메시지가 출력된다.

## 멀티포인트 라우팅 (Multi-Point Routing)

edge는 여러 대의 node가 동시에 연결된 환경을 지원한다.

- **명시적 선택**: `/node <alias>` 또는 `/node <node_id>` 명령으로 특정 node를 고정할 수 있다.
- **Single-node Fallback**: 연결된 node가 정확히 1개일 때는 선택 없이도 해당 node가 자동 지정된다.
- **Ambiguous Error**: node가 2개 이상일 때 node 선택 없이 메시지를 보내면 에러가 발생하며 선택을 요구한다.
- **Node-aware Events**: 모든 이벤트와 메시지 출력에 `[node-{alias}-...]` 접두어가 붙어 출처를 식별할 수 있다.
- **Lifecycle Events**: node 등록/연결 해제는 실행 스트림과 분리된 `EdgeNodeEvent`로 인식하며, 콘솔에서는 `connected`/`disconnected` 이벤트와 reason을 출력한다.

## Transport 1개 · Logical Session 여러 개

edge-node transport 연결은 **node id당 1개** TCP 연결만 유지한다. 그 연결 위에서 edge는 `session_id`를 지정해 node의 cli adapter가 관리하는 개별 worker process에 접근한다. 같은 `codex` profile이라도 `session_id`가 다르면 독립적인 장수 process다.

- **cancel run**: 현재 run 중단, session process 유지
- **terminate session**: session process 명시 종료 (`/terminate-session` 또는 `CancelAction_TERMINATE_SESSION`)

프롬프트 없이 TCP/protobuf edge 서버만 실행하려면 기존처럼 `go run ./apps/edge/cmd/edge serve -c configs/edge.yaml`를 사용한다.

`bin/node.sh`의 edge 대기 시간은 `IOP_NODE_WAIT_TIMEOUT`, 확인 간격은 `IOP_NODE_WAIT_INTERVAL`, 접속 주소는 `IOP_EDGE_ADDR` 환경 변수로 임시 override할 수 있다.