iop/agent-ops/rules/project/domain/node/rules.md

domain	last_rule_review_commit	last_rule_updated_at
node	01bef3dc93	2026-05-21

node

목적 / 책임

Edge에 연결되어 실제 adapter execution을 수행하는 IOP 노드 에이전트 영역이다. edge에서 들어온 실행·취소·조회성 명령을 runtime 요청으로 변환하고, 라우팅된 어댑터를 실행하며, 실행 이벤트와 현재 단계의 로컬 실행 이력을 관리한다.

포함 경로

• apps/node/cmd/node/ — node CLI 진입점과 서브커맨드
• apps/node/internal/bootstrap/ — fx 의존성 주입과 adapter registry 구성
• apps/node/internal/node/ — transport handler 구현과 실행 오케스트레이션
• apps/node/internal/runtime/ — node 도메인 타입과 핵심 인터페이스
• apps/node/internal/router/ — RunRequest를 ExecutionSpec으로 해석하는 라우팅
• apps/node/internal/transport/ — edge와의 TCP/protobuf 세션 및 메시지 처리
• apps/node/internal/adapters/ — mock/ollama/vllm/cli 실행 어댑터
• apps/node/internal/store/ — SQLite 실행 이력 저장
• apps/node/README.md — node 실행 흐름과 adapter/session 경계 설명

제외 경로

• apps/edge/ — Node를 관리하는 실행 그룹 컨트롤러 영역
• apps/control-plane/ — 여러 Edge 연결 관리와 운영 제어 API 제공 예정 영역
• apps/web/ — Web Portal 앱 영역
• apps/worker/ — 비동기 작업 처리 예정 영역
• packages/ — 여러 앱이 공유하는 공통 패키지
• proto/ — 앱 간 메시지 계약

주요 구성 요소

• runtime.Adapter — adapter target 실행 계약
• runtime.Router — 실행 요청을 구체적인 ExecutionSpec으로 변환하는 계약
• runtime.CommandHandler — adapter별 NodeCommandRequest 처리 optional 계약
• runtime.SessionTerminator — logical session 종료를 지원하는 optional 계약
• node.Node — transport.Handler 구현체이자 실행 파이프라인 조정자
• node.runManager — run ID 기준 runHandle(cancel, done) 등록/해제/취소 관리; node.Node 내부에서만 사용
• node.sessionSink — adapter RuntimeEvent를 proto RunEvent로 변환해 edge session으로 보내는 sink
• transport.Session — edge와 연결된 node 세션 및 메시지 처리
• adapters.Registry — 어댑터 등록/조회 및 LifecycleAdapter start/stop lifecycle 관리 (실패 시 역순 롤백)
• adapters.LifecycleAdapter — start/stop lifecycle이 필요한 어댑터의 optional 인터페이스
• adapters.BuildFromPayload() — edge에서 받은 NodeConfigPayload로 Registry를 초기화하는 factory
• adapters/cli.CLI — one-shot, persistent TUI, codex-exec, opencode-sse profile을 실행하는 CLI adapter
• adapters/cli/status — claude/codex/antigravity CLI 상태 파서 (사용량 한도, reset 시각 등)
• adapters/cli.lineEmitter — stdout 한 줄을 파싱해 RuntimeEvent를 반환하는 내부 인터페이스; emitters.go에서 format별로 등록
• store.Store — 실행 상태와 결과 저장

유지할 패턴

• runtime 패키지에는 도메인 타입과 인터페이스를 두고 구체 구현 의존성을 넣지 않는다.
• transport/proto 타입은 node.Node 경계에서 runtime 타입으로 변환한다.
• 내부 실행 식별자는 adapter + target을 사용한다. 외부 OpenAI-compatible API나 legacy placeholder를 제외하고 model을 내부 실행 대표 용어로 되돌리지 않는다.
• 어댑터 추가 시 runtime.Adapter를 구현하고 adapters.BuildFromPayload() 또는 bootstrap registry에 등록한다.
• 실행 취소는 run ID 기준으로 runManager에 등록하고 실행 종료 시 반드시 deregister로 해제한다.
• CancelAction_CANCEL_RUN은 현재 run 취소, CancelAction_TERMINATE_SESSION은 logical session 종료로 구분한다.
• NodeCommandRequest는 실행 요청과 분리해 USAGE_STATUS, CAPABILITIES, SESSION_LIST, TRANSPORT_STATUS 같은 조회/제어성 명령으로 처리한다.
• adapters.Registry의 start/stop은 bootstrap lifecycle에서만 호출하고 개별 adapter에서 직접 호출하지 않는다.
• cli adapter의 출력 format별 파싱 로직은 lineEmitter 구현체로 분리하고 node.Node에 분기문으로 박지 않는다.
• CLI profile mode별 세부 실행(persistent-lazy, codex-exec, opencode-sse)은 adapters/cli 내부에 두고, runtime.Adapter 계약 밖으로 새 transport를 노출하지 않는다.
• node 내부 변경은 가능한 대상 패키지 테스트를 먼저 추가하거나 갱신한다.
• apps/node/cmd/node/**, apps/node/internal/bootstrap/**, apps/node/internal/transport/**, apps/node/internal/node/**, apps/node/internal/router/**, apps/node/internal/adapters/**, apps/node/internal/store/**의 실행 요청/응답/stream/cancel/status/session 경로를 바꾼 뒤에는 testing domain rule의 작업 후 검증 기준을 따른다.

다른 도메인과의 경계

• edge: edge는 node 연결 등록, adapter/runtime 설정 전달, 라우팅 진입, stream relay를 담당한다. node는 edge가 보낸 실행/취소/명령 요청을 처리하고 이벤트와 명령 응답을 돌려준다.
• platform-common: node는 packages/config, packages/events, packages/observability, proto/gen/iop 등을 사용하지만 공통 타입/설정/event helper 자체의 소유자는 platform-common이다.
• control-plane 후보: control-plane은 Node가 아니라 Edge를 통해 시스템을 제어한다. node는 control-plane 직접 연결/직접 스케줄링을 전제로 하지 않는다.

금지 사항

• node 도메인 내부에서 gRPC, WebSocket 기본 transport, actor/FSM/plugin framework를 새 기본 구조로 도입하지 않는다.
• proto/gen/iop/*.pb.go 생성 파일을 직접 수정하지 않는다.
• 새 어댑터 구현을 node.Node에 직접 분기문으로 박아 넣지 않는다.
• edge-local console, OpenAI-compatible HTTP, A2A 같은 입력 표면 책임을 node로 끌어오지 않는다.
• placeholder 상태인 control-plane/worker 책임을 node에 임시로 흡수하지 않는다.