# node — Node Agent

디바이스당 1개 실행되는 IOP 노드 에이전트.  
실제 AI 모델 추론 어댑터를 관리하고, TCP + Protobuf + mTLS 소켓을 통해 요청을 처리한다.

## 내부 구조 (Hexagonal Architecture)

```
cmd/node/            — CLI 진입점 (cobra)
internal/
  bootstrap/         — fx 의존성 주입 모듈
  node/              — 핵심 노드 서비스 (transport.Handler 구현)
  runtime/           — 도메인 타입: ExecutionSpec, RuntimeEvent, 인터페이스
  router/            — RunRequest → ExecutionSpec 라우팅
  transport/         — TCP 서버, 세션 관리, 프레임 코덱
  adapters/
    mock/            — 에코 테스트 어댑터
    ollama/          — Ollama API 어댑터 (TODO)
    vllm/            — vLLM OpenAI-compatible 어댑터 (TODO)
    cli/             — CLI 프로세스 어댑터 (claude/gemini/codex/opencode)
  store/             — SQLite 실행 이력
```

## 실행

```bash
# 빌드
go build -o bin/node ./apps/node/cmd/node

# 버전 확인
./bin/node version

# 설정 확인
./bin/node config print --config configs/node.yaml

# 서버 실행
./bin/node serve --config configs/node.yaml
```

원격 edge에 붙는 수동 테스트는 `configs/node.yaml`의 `transport.edge_addr`와 `transport.token`을 먼저 맞춘 뒤 repo root에서 실행한다.

```bash
./bin/node.sh
```

node가 시작되면 cli adapter가 `claude` persistent terminal process를 띄운다. PATH에 `claude` 명령이 없으면 node 시작이 실패한다.

edge에서 실행 요청을 받으면 node는 해당 입력을 Claude process의 stdin으로 전달하고, `response_idle_timeout_ms`(기본 1500ms) 동안 새 출력이 없으면 응답 경계로 처리해 complete 이벤트를 보낸다.

```text
[edge-message] hello
[node-event] start run_id=manual-...
[node-event] complete run_id=manual-... detail="cli execution complete"
[node-message] <Claude 응답 텍스트>
```

## 어댑터

| 어댑터 | 설명 | 상태 |
|---|---|---|
| `mock` | 입력 에코, 스트리밍 테스트용 | 구현 완료 |
| `ollama` | 로컬 Ollama 서버 연동 | TODO |
| `vllm` | vLLM OpenAI-compatible API | TODO |
| `cli` | claude/gemini/codex/opencode CLI 실행 | 구현 완료 |

## Transport

- TCP 4-byte length-prefix framing
- JSON-encoded Envelope (TODO: protobuf 교체)
- mTLS (configs/node.yaml에서 활성화)
- 하트비트: 30초 간격