From cb1ead78130f8cbb1a63b2fcda2531f3ff033785 Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 21 May 2026 17:41:26 +0900 Subject: [PATCH] update docs and agent-ops roadmap --- README.md | 66 +--------------- agent-ops/roadmap/ROADMAP.md | 79 +++++++++++++++++++ agent-ops/roadmap/current.md | 5 ++ .../M01-edge-node-execution-skeleton.md | 54 +++++++++++++ .../milestones/M02-edge-input-surfaces.md | 50 ++++++++++++ ...03-cli-automation-runtime-stabilization.md | 48 +++++++++++ .../M04-remote-terminal-bridge-poc.md | 49 ++++++++++++ .../M05-agent-bootstrap-oto-enrollment.md | 47 +++++++++++ .../milestones/M06-control-plane-portal.md | 48 +++++++++++ .../milestones/M07-policy-history-audit.md | 48 +++++++++++ .../milestones/M08-multi-edge-operations.md | 48 +++++++++++ agent-ops/rules/project/rules.md | 7 ++ docs/architecture.md | 1 + docs/deploy-dev.md | 32 +------- 14 files changed, 491 insertions(+), 91 deletions(-) create mode 100644 agent-ops/roadmap/ROADMAP.md create mode 100644 agent-ops/roadmap/current.md create mode 100644 agent-ops/roadmap/milestones/M01-edge-node-execution-skeleton.md create mode 100644 agent-ops/roadmap/milestones/M02-edge-input-surfaces.md create mode 100644 agent-ops/roadmap/milestones/M03-cli-automation-runtime-stabilization.md create mode 100644 agent-ops/roadmap/milestones/M04-remote-terminal-bridge-poc.md create mode 100644 agent-ops/roadmap/milestones/M05-agent-bootstrap-oto-enrollment.md create mode 100644 agent-ops/roadmap/milestones/M06-control-plane-portal.md create mode 100644 agent-ops/roadmap/milestones/M07-policy-history-audit.md create mode 100644 agent-ops/roadmap/milestones/M08-multi-edge-operations.md diff --git a/README.md b/README.md index a36a13e..0b13898 100644 --- a/README.md +++ b/README.md @@ -230,70 +230,10 @@ NomadCode ## Roadmap -Edge의 외부 입력 표면은 두 방식을 병행 지원한다. +제품 방향, Phase, Milestone, 우선순위의 canonical source of truth는 `agent-ops/roadmap/ROADMAP.md`다. +일반 작업에서 AI가 읽어야 하는 현재 작업 기준은 `agent-ops/roadmap/current.md`가 가리키는 Active Milestone 문서다. -- **OpenAI-compatible HTTP API**: 외부 모델 클라이언트, Cline류 도구, 단순 chat completion/inference 호환을 위한 입력이다. 이 경계에서는 호환성을 위해 `model`을 받되, Edge 내부에서는 `adapter + target`으로 변환한다. -- **A2A JSON-RPC HTTP API**: NomadCode Core나 외부 agent가 작업을 위임하고 `Task` 상태, artifact, cancel/polling을 공유해야 할 때 사용하는 agent delegation 입력이다. 이 경계도 Edge 내부에서는 `adapter + target`으로 변환한다. - -두 입력 방식은 Edge의 inbound/input surface로 함께 관리하고, 내부 실행은 기존 `RunRequest`/`RunEvent` 흐름으로 수렴시킨다. IOP native protocol은 이 둘을 대체하는 외부 호환 API가 아니라, Control Plane/Portal/운영 CLI가 Edge/Node 운영 제어와 lifecycle event를 다루기 위한 wire protocol로 유지한다. - -Edge는 기존 Edge-Node 실행 흐름과 별도로, specialized domain agent의 bootstrap/enrollment 표면을 제공한다. 목표 UX는 Jenkins node 연결처럼 Edge에서 agent를 먼저 생성하고, Edge가 발급한 bootstrap command를 대상 머신에서 실행해 agent를 설치/등록하는 방식이다. OTO는 이 경로의 대표 build/deploy agent이며, `iop-node`에 종속되지 않고 Edge에 직접 연결한다. - -폐쇄망과 개발망을 고려해 bootstrap HTTP endpoint는 HTTPS를 기본 권장하되 필수 전제로 두지 않는다. HTTP local/insecure 모드를 허용하는 대신 one-time bootstrap token, Edge fingerprint 또는 public key pinning, 바이너리 checksum/signature 검증, 등록 후 장기 credential 재발급을 계약에 포함한다. - -Agent를 설치하기 어려운 대상은 별도 축으로 다룬다. Edge는 `agent-terminal` tunnel 또는 remote terminal bridge 표면을 제공하고, 대상에 도달 가능한 Node가 SSH/WinRM/serial/local shell 같은 terminal transport를 열어 stdin/stdout/stderr, resize, signal, session lifecycle을 Edge로 relay한다. 이 방식은 target device에 IOP agent를 심지 않는 운영 경로이지, 접근 경로 없이 완전 agentless 제어를 보장하는 모델은 아니다. - -### Phase 1. Edge-Node execution skeleton - -- Edge-Node 소켓 연결 -- Node adapter execution -- CLI adapter 검증 -- `adapter + target` 개념 정리 -- OpenAI-compatible serving 표면은 외부 표준 호환 경로로 유지하고, 내부에서는 `model`을 `adapter + target`으로 변환하는 경계를 검증 -- A2A input surface는 기존 OpenAI-compatible input과 같은 Edge input 관리 계층에 추가하고, 1차로 `message/send`, `tasks/get`, `tasks/cancel`을 지원 - -### Phase 2. Runtime and Automation unification - -- 모델 서빙 adapter 확장 -- CLI Agent 실행 안정화 -- Runtime / Automation 실행 흐름 공통화 -- Edge agent registry를 generic node와 specialized domain agent를 함께 다룰 수 있는 모델로 확장 -- Edge가 agent type별 bootstrap command를 발급하는 HTTP bootstrap 표면 설계 -- agent 설치가 어려운 target을 위해 CLI persistent terminal profile 기반 remote shell POC를 추가하고, Edge가 session broker, Node가 terminal transport 실행자 역할을 갖는 경계를 검증 -- Node local execution history와 Edge event aggregation 경계 정리 -- IOP native execution protocol을 기존 protobuf `RunRequest`, `RunEvent`, `NodeCommandRequest`, `EdgeNodeEvent` 계열 계약 위에서 정식화 -- native protocol에는 node 선택, `adapter + target`, logical session, background run, cancel/terminate-session, capabilities/status/session/transport command, remote terminal session event, node lifecycle event처럼 OpenAI-compatible API로 표현하기 어려운 기능을 둠 -- Edge input surface는 OpenAI-compatible 입력을 모델/채팅 호환 경로로, A2A 입력을 agent 작업 위임과 상태 공유 경로로 분리해 유지 - -### Phase 3. Control Plane - -- 자체 서버와 프론트 페이지 제공 -- 여러 Edge 연결 -- Edge 상태 조회 -- Edge 설정 변경 -- Edge 명령 전달 -- 이벤트 수신 -- Portal-Control Plane, Control Plane-Edge 통신은 IOP Wire Protocol(protobuf-socket)을 기준으로 확장하고, 브라우저 직접 TCP가 어려운 경우 server-side bridge를 둠 -- Portal/Control Plane에서 Edge agent 생성과 bootstrap command 발급 상태를 조회/관리 -- Portal/Control Plane에서 remote terminal bridge session 생성, 대상 선택, 권한 확인, audit 조회를 지원하되 Control Plane이 Node에 직접 붙지 않고 Edge를 통해 제어 -- OpenAI-compatible HTTP API는 외부 모델 클라이언트 호환 표면으로 유지하되, 운영/제어/세션 기능의 기본 프로토콜로 확장하지 않음 -- A2A HTTP API는 Core/외부 agent가 Edge 실행 그룹에 작업을 위임하는 표준 입력으로 유지하되, Control Plane의 Edge 운영 제어 프로토콜로 확장하지 않음 - -### Phase 4. Multi-Edge operations - -- 여러 Edge group 관리 -- Edge별 runtime/automation 상태 표시 -- Edge 단위 실행 이력과 상태 집계 -- Edge 단위 작업 실행과 제어 -- OTO 같은 domain agent의 build/deploy 상태, artifact, capability를 Edge 단위 운영 화면과 이벤트 집계에 포함 -- multi-edge 운영 명령과 이벤트 집계는 IOP native protocol을 기준으로 설계하고, OpenAI-compatible 표면은 특정 Edge/adapter로 라우팅되는 inference 호환 경로로 제한 -- A2A 표면은 특정 Edge/adapter로 위임되는 agent task 경로로 제한하고, multi-edge scheduling과 fleet-wide state ownership은 Control Plane/native protocol에서 결정 - -### Phase 5. Policy, History, Audit - -- 권한, 정책, 이력, 감사 기능 확장 -- remote terminal bridge는 target allowlist, credential 관리, command/session audit, timeout, 동시 실행 제한, 입력/출력 기록 정책을 필수 설계 항목으로 둠 -- 상세 설계는 후속 작업에서 결정 +로드맵의 큰 축은 Edge-Node 실행 기반, Edge input surface, CLI Automation runtime, remote terminal bridge, agent bootstrap/OTO enrollment, Control Plane/Portal, policy/history/audit, multi-edge operations로 관리한다. ## Development Notes diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md new file mode 100644 index 0000000..45d739c --- /dev/null +++ b/agent-ops/roadmap/ROADMAP.md @@ -0,0 +1,79 @@ +# IOP Roadmap + +이 문서는 IOP 제품 방향과 Phase/Milestone의 canonical source of truth다. +README와 `docs/**`는 제품 소개, 아키텍처 원칙, 운영 절차를 설명하고, 미래 계획과 우선순위는 이 문서와 각 Milestone 문서에서 관리한다. + +## Overall Goal + +IOP(Inference Operations Platform)는 Control Plane - Edge - Node 계층 구조를 기반으로 모델 서빙과 CLI Agent/Automation 실행을 함께 운영하는 실행 오케스트레이션 플랫폼을 만든다. +내부 실행 모델은 `adapter + target`을 기준으로 하며, Edge가 로컬 실행 그룹의 상태와 라우팅을 소유하고 Control Plane은 Edge를 통해 시스템을 관찰하고 제어한다. + +## Current Position + +- Active Phase: Phase 1. Edge-Node Execution Foundation +- Active Milestone: M01 Edge-Node Execution Skeleton +- Active Milestone File: `agent-ops/roadmap/milestones/M01-edge-node-execution-skeleton.md` + +## Loading Policy + +- 일반 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업에서는 `agent-ops/roadmap/current.md`를 먼저 읽고, 그 안의 Active Milestone 문서를 같은 세션에서 1회 읽는다. +- `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. +- Active Milestone의 Goal 또는 Non-Goals와 작업 요청이 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. + +## Status Semantics + +- `Planned`: 아직 본격 작업 기준으로 삼지 않는 예정 Milestone이다. +- `Active`: 구현, 안정화, 문서 정리, 검증이 진행 중인 Milestone이다. 여러 Milestone이 동시에 `Active`일 수 있다. +- `Done`: Success Criteria가 충족되어 완료된 Milestone이다. +- `Paused`: 일시 중단된 Milestone이다. +- `Dropped`: 현재 제품 방향에서 제외된 Milestone이다. + +`current.md`가 가리키는 Active Milestone은 여러 `Active` Milestone 중 현재 세션의 기본 작업 초점이다. + +## Phase Overview + +### Phase 1. Edge-Node Execution Foundation + +Goal: Edge-Node 소켓 실행 경로, Node adapter execution, CLI session, 최소 외부 입력 표면을 안정화한다. + +| Milestone | Status | File | +|---|---|---| +| M01 Edge-Node Execution Skeleton | Active | `milestones/M01-edge-node-execution-skeleton.md` | +| M02 Edge Input Surfaces | Active | `milestones/M02-edge-input-surfaces.md` | + +### Phase 2. Automation Runtime and Bridge Expansion + +Goal: Runtime과 Automation 실행 흐름을 공통화하고, agent 설치형/비설치형 대상 제어 경로를 분리해 확장한다. + +| Milestone | Status | File | +|---|---|---| +| M03 CLI Automation Runtime Stabilization | Planned | `milestones/M03-cli-automation-runtime-stabilization.md` | +| M04 Remote Terminal Bridge POC | Planned | `milestones/M04-remote-terminal-bridge-poc.md` | +| M05 Agent Bootstrap and OTO Enrollment | Planned | `milestones/M05-agent-bootstrap-oto-enrollment.md` | + +### Phase 3. Control Plane and Portal Operations + +Goal: 여러 Edge를 관찰하고 운영하는 중앙 제어면과 Portal을 구축한다. + +| Milestone | Status | File | +|---|---|---| +| M06 Control Plane and Portal | Planned | `milestones/M06-control-plane-portal.md` | +| M07 Policy History Audit | Planned | `milestones/M07-policy-history-audit.md` | +| M08 Multi-Edge Operations | Planned | `milestones/M08-multi-edge-operations.md` | + +## Cross-Cutting Principles + +- 내부 실행 용어는 `adapter`, `target`, `execution`을 우선한다. `model`은 OpenAI-compatible 경계나 legacy compatibility에서만 사용한다. +- Control Plane은 Node를 직접 연결하거나 직접 스케줄링하지 않는다. Edge가 로컬 Node registry와 런타임 상태의 원본을 가진다. +- Edge-Node, Control Plane-Edge 장기 통신 기준은 TCP/protobuf 기반 IOP Wire Protocol이다. +- gRPC, WebSocket 기본 transport 전환, actor/FSM/plugin framework 도입은 현재 기본 방향이 아니다. +- OpenAI-compatible API는 모델/chat completion 호환 입력 표면이고, A2A API는 외부 agent 작업 위임 입력 표면이다. +- IOP native protocol은 Edge/Node 운영 제어, logical session, background run, command, lifecycle event, remote terminal session 같은 IOP 고유 기능을 다룬다. + +## Roadmap Ownership + +- 제품 방향, Phase, Milestone, 우선순위: `agent-ops/roadmap/ROADMAP.md` +- 현재 작업 기준: `agent-ops/roadmap/current.md`와 Active Milestone 문서 +- 아키텍처 불변 원칙: `docs/architecture.md` +- dev/field 배포 절차: `docs/deploy-dev.md` +- 앱별 현재 구현과 사용법: `apps/*/README.md` diff --git a/agent-ops/roadmap/current.md b/agent-ops/roadmap/current.md new file mode 100644 index 0000000..ea7c0ae --- /dev/null +++ b/agent-ops/roadmap/current.md @@ -0,0 +1,5 @@ +# Current Roadmap Context + +- Active Phase: Phase 1. Edge-Node Execution Foundation +- Active Milestone: M01 Edge-Node Execution Skeleton +- Active Milestone File: agent-ops/roadmap/milestones/M01-edge-node-execution-skeleton.md diff --git a/agent-ops/roadmap/milestones/M01-edge-node-execution-skeleton.md b/agent-ops/roadmap/milestones/M01-edge-node-execution-skeleton.md new file mode 100644 index 0000000..abf01d8 --- /dev/null +++ b/agent-ops/roadmap/milestones/M01-edge-node-execution-skeleton.md @@ -0,0 +1,54 @@ +# M01 Edge-Node Execution Skeleton + +## Goal + +Edge와 Node 사이의 기본 실행 파이프라인을 안정화한다. +Node 등록, 설정 전달, adapter execution, run event streaming, command request/response, field smoke 기준을 한 흐름으로 검증할 수 있게 만든다. + +## Phase + +Phase 1. Edge-Node Execution Foundation + +## Status + +Active + +## Scope + +- Edge-Node TCP/protobuf 연결과 RegisterRequest/RegisterResponse 흐름 +- token 기반 node 등록과 NodeConfigPayload 전달 +- Node adapter registry와 `adapter + target` 실행 라우팅 +- `RunRequest`, `RunEvent`, `CancelRequest`, `NodeCommandRequest`, `NodeCommandResponse` 경로 +- CLI adapter 기반 one-shot/persistent session 실행 검증 +- edge-local ops console과 `bin/edge.sh`, `bin/node.sh` 기반 field smoke + +## Required Features + +- NodeStore와 Registry가 사전 등록 node와 연결 node를 구분해 관리한다. +- Edge가 node 설정을 mapper를 통해 NodeConfigPayload로 전달한다. +- Node가 adapter registry를 구성하고 `runtime.Adapter` 계약으로 실행한다. +- CLI adapter가 logical session과 cancel/terminate-session을 지원한다. +- Edge console이 `/nodes`, `/node`, `/session`, `/background`, `/terminate-session`, `/status`, `/capabilities`, `/sessions`, `/transport`를 통해 기본 진단을 제공한다. +- Field smoke에서 메시지 2회 왕복, start/delta/complete event, command 응답을 확인할 수 있다. + +## Success Criteria + +- `bin/edge.sh`와 `bin/node.sh`를 각각 실행해 node 등록을 확인할 수 있다. +- Edge console에서 두 번의 메시지 실행이 각각 start, non-empty message/delta, complete event를 표시한다. +- `/capabilities`, `/transport`, `/sessions` 명령이 node 응답을 표시한다. +- persistent profile에서 run cancel과 session terminate의 의미가 구분된다. +- 변경 범위에 맞는 Go 테스트 또는 field smoke 기준이 문서와 일치한다. + +## Non-Goals + +- Control Plane이 Node를 직접 연결하거나 직접 스케줄링하는 구조 +- Edge 내부에 Node adapter 실행 로직을 복제하는 구조 +- gRPC 또는 WebSocket을 Edge-Node 기본 transport로 바꾸는 작업 +- 상세 DB schema, audit model, policy engine 확정 + +## Context for Work + +- 관련 앱: `apps/edge`, `apps/node` +- 관련 문서: `apps/edge/README.md`, `apps/node/README.md`, `docs/deploy-dev.md` +- 관련 domain rules: `agent-ops/rules/project/domain/edge/rules.md`, `agent-ops/rules/project/domain/node/rules.md` +- 사용자 실행 파이프라인을 바꾸면 `agent-ops/rules/project/domain/testing/rules.md`의 검증 기준을 따른다. diff --git a/agent-ops/roadmap/milestones/M02-edge-input-surfaces.md b/agent-ops/roadmap/milestones/M02-edge-input-surfaces.md new file mode 100644 index 0000000..6e426e0 --- /dev/null +++ b/agent-ops/roadmap/milestones/M02-edge-input-surfaces.md @@ -0,0 +1,50 @@ +# M02 Edge Input Surfaces + +## Goal + +Edge의 외부 입력 표면을 OpenAI-compatible API와 A2A JSON-RPC API로 분리해 관리하고, 두 입력 모두 내부 `adapter + target` 실행 경로로 수렴시킨다. + +## Phase + +Phase 1. Edge-Node Execution Foundation + +## Status + +Active + +## Scope + +- OpenAI-compatible `/v1/models`, `/v1/chat/completions` 표면 +- A2A `message/send`, `tasks/get`, `tasks/cancel` 최소 표면 +- Edge input manager lifecycle/config 정리 +- 외부 `model` 또는 A2A task 입력을 내부 `adapter + target + session_id`로 변환하는 경계 +- streaming/non-streaming 응답과 background task 상태 저장 기준 정리 +- 현재 구현된 OpenAI-compatible/A2A baseline을 기준으로 설정, lifecycle, task 상태, 문서 경계를 안정화 + +## Required Features + +- OpenAI-compatible API는 모델/chat completion 호환 입력 표면으로 유지한다. +- A2A API는 외부 agent의 작업 위임과 task 상태 공유 표면으로 유지한다. +- 두 입력 표면 모두 Edge service와 edge-node transport를 우회하지 않는다. +- OpenAI-compatible API에 IOP 고유 운영 제어 기능을 억지로 싣지 않는다. +- A2A API를 Control Plane 운영 제어 프로토콜로 확장하지 않는다. + +## Success Criteria + +- 외부 OpenAI-compatible 요청이 Edge 내부에서 명시적인 adapter/target 실행으로 변환된다. +- A2A `message/send`, `tasks/get`, `tasks/cancel`이 task lifecycle과 node cancel 흐름을 일관되게 표현한다. +- 입력 표면별 설정과 lifecycle이 중복 없이 관리된다. +- 앱별 README는 현재 사용법을 설명하고, 미래 우선순위는 roadmap을 참조한다. + +## Non-Goals + +- OpenAI-compatible API를 IOP native 운영 제어 프로토콜로 확장 +- A2A API를 fleet-wide scheduling 또는 Control Plane state ownership 표면으로 확장 +- vendor-specific extension으로 node 선택, terminal session, lifecycle event를 표현 + +## Context for Work + +- 관련 앱: `apps/edge` +- 관련 문서: `apps/edge/README.md` +- 관련 패키지: `apps/edge/internal/openai`, `apps/edge/internal/input/a2a`, `apps/edge/internal/service` +- platform-common 계약 변경 시 `proto/iop`와 `packages/config`를 함께 확인한다. diff --git a/agent-ops/roadmap/milestones/M03-cli-automation-runtime-stabilization.md b/agent-ops/roadmap/milestones/M03-cli-automation-runtime-stabilization.md new file mode 100644 index 0000000..61638bc --- /dev/null +++ b/agent-ops/roadmap/milestones/M03-cli-automation-runtime-stabilization.md @@ -0,0 +1,48 @@ +# M03 CLI Automation Runtime Stabilization + +## Goal + +CLI Agent와 도구 실행을 안정적인 Automation runtime으로 정리한다. +현재 구현된 CLI adapter baseline을 바탕으로 one-shot, persistent terminal, opencode SSE, codex exec 같은 실행 모드를 같은 adapter execution 모델 안에서 안정화한다. + +## Phase + +Phase 2. Automation Runtime and Bridge Expansion + +## Status + +Planned + +## Scope + +- CLI profile 설정과 output format 처리 안정화 +- persistent logical session lifecycle 관리 +- command/status/capability/session list 응답 정리 +- usage/status parser와 terminal screen parser 신뢰성 강화 +- Node local execution history와 Edge event aggregation 경계 정리 +- 이미 동작하는 CLI adapter 기능을 재구현하지 않고 hardening, 경계 정리, 검증 기준 보강에 집중 + +## Required Features + +- CLI adapter는 profile별 실행 모드를 `node.Node` 분기 없이 adapter 내부에서 처리한다. +- output format별 파싱은 `lineEmitter` 또는 모드별 구현으로 분리한다. +- persistent terminal profile은 idle timeout, completion marker, cancel drain 기준을 명확히 가진다. +- `NodeCommandRequest` 경로는 실행 요청과 분리된 조회/제어 명령으로 유지한다. + +## Success Criteria + +- 주요 CLI profile이 동일한 `RunRequest`/`RunEvent` 흐름으로 실행된다. +- session list, usage status, transport status가 운영자가 이해할 수 있는 응답을 제공한다. +- CLI adapter 변경 시 대상 패키지 테스트와 field smoke 기준이 함께 맞는다. + +## Non-Goals + +- 모든 외부 자동화 도구를 `iop-node` 하위 프로세스로 흡수 +- OTO 같은 specialized domain agent를 CLI adapter profile로 대체 +- CLI adapter 내부에 Control Plane 책임 추가 + +## Context for Work + +- 관련 앱: `apps/node` +- 관련 패키지: `apps/node/internal/adapters/cli`, `apps/node/internal/runtime`, `apps/node/internal/node` +- 관련 문서: `apps/node/README.md` diff --git a/agent-ops/roadmap/milestones/M04-remote-terminal-bridge-poc.md b/agent-ops/roadmap/milestones/M04-remote-terminal-bridge-poc.md new file mode 100644 index 0000000..0ae39d0 --- /dev/null +++ b/agent-ops/roadmap/milestones/M04-remote-terminal-bridge-poc.md @@ -0,0 +1,49 @@ +# M04 Remote Terminal Bridge POC + +## Goal + +Agent를 설치하기 어려운 host/device를 위해 remote terminal bridge POC를 만든다. +Edge는 terminal session broker가 되고, 대상에 도달 가능한 Node가 SSH/WinRM/serial/local shell 같은 terminal transport를 실행해 relay한다. + +## Phase + +Phase 2. Automation Runtime and Bridge Expansion + +## Status + +Planned + +## Scope + +- CLI persistent terminal profile 기반 remote shell POC +- terminal session open/input/output/resize/signal/close event 모델 초안 +- Edge가 session broker, Node가 terminal transport 실행자라는 책임 경계 검증 +- 대상 접근 경로와 credential이 있는 경우만 제어할 수 있다는 전제 명시 +- target allowlist, timeout, 동시 실행 제한, session audit 요구사항 초안 + +## Required Features + +- Remote terminal bridge는 완전 agentless 제어가 아니라 target device에 IOP agent를 설치하지 않는 운영 경로로 정의한다. +- Control Plane/Portal/운영 CLI는 Edge에 terminal session을 요청하고, Node에 직접 붙지 않는다. +- Node terminal transport는 adapter/profile 또는 별도 adapter 경계에서 실행된다. +- stdin/stdout/stderr, resize, signal, close lifecycle을 IOP native protocol에서 표현하는 방향을 검증한다. + +## Success Criteria + +- 허용된 target profile을 통해 Edge에서 remote shell session을 열고 입출력을 relay할 수 있다. +- session lifecycle과 adapter execution stream의 경계가 문서화된다. +- 보안 전제(target allowlist, credential, timeout, audit)가 milestone 산출물에 포함된다. +- OpenAI-compatible API나 A2A task payload에 terminal 제어 기능을 억지로 싣지 않는다. + +## Non-Goals + +- 접근 경로가 없는 target device의 제어 보장 +- Control Plane이 Node 또는 target terminal에 직접 연결 +- 모든 terminal transport 구현을 한 번에 지원 +- 정책/audit 상세 schema 확정 + +## Context for Work + +- 관련 앱: `apps/edge`, `apps/node` +- 관련 문서: `docs/architecture.md`, `docs/deploy-dev.md` +- 선행 Milestone: M01, M03 diff --git a/agent-ops/roadmap/milestones/M05-agent-bootstrap-oto-enrollment.md b/agent-ops/roadmap/milestones/M05-agent-bootstrap-oto-enrollment.md new file mode 100644 index 0000000..9334c7b --- /dev/null +++ b/agent-ops/roadmap/milestones/M05-agent-bootstrap-oto-enrollment.md @@ -0,0 +1,47 @@ +# M05 Agent Bootstrap and OTO Enrollment + +## Goal + +Edge가 specialized domain agent를 생성하고 bootstrap command를 발급해 대상 머신에서 agent 설치와 등록을 완료하는 enrollment 흐름을 설계한다. +OTO는 build/deploy domain agent의 대표 후보로 둔다. + +## Phase + +Phase 2. Automation Runtime and Bridge Expansion + +## Status + +Planned + +## Scope + +- Edge agent registry를 generic node와 specialized domain agent를 함께 다룰 수 있는 모델로 확장 +- agent type별 bootstrap command 발급 표면 설계 +- one-time bootstrap token, Edge fingerprint/public key pinning, checksum/signature 검증 계약 +- 등록 후 장기 credential 재발급 흐름 +- OTO agent의 build run, cancel, status, capability, artifact, log event 메시지 경계 + +## Required Features + +- OTO agent는 `iop-node` 하위 프로세스가 아니라 Edge에 직접 outbound 연결하는 specialized domain agent로 둔다. +- Agent를 설치할 수 있는 대상은 bootstrap/enrollment를 우선한다. +- Agent 설치가 어렵거나 일회성 유지보수 대상이면 remote terminal bridge 경로와 구분한다. +- HTTP local/insecure bootstrap 모드는 명시 선택과 추가 검증 조건을 요구한다. + +## Success Criteria + +- Edge가 agent 생성과 bootstrap command 발급 상태를 표현할 수 있다. +- bootstrap command 실행 후 agent config/service 등록과 Edge outbound enrollment 흐름이 문서화된다. +- OTO agent와 generic Node의 책임 경계가 registry와 protocol 수준에서 구분된다. + +## Non-Goals + +- OTO 구현을 `apps/node` adapter로 흡수 +- Control Plane이 Node나 OTO agent를 직접 스케줄링 +- bootstrap 보안 검증을 생략한 insecure 기본값 + +## Context for Work + +- 관련 앱: `apps/edge`, 향후 OTO agent repository +- 관련 문서: `docs/deploy-dev.md`, `docs/architecture.md` +- 선행 Milestone: M01, M02 diff --git a/agent-ops/roadmap/milestones/M06-control-plane-portal.md b/agent-ops/roadmap/milestones/M06-control-plane-portal.md new file mode 100644 index 0000000..7f29baa --- /dev/null +++ b/agent-ops/roadmap/milestones/M06-control-plane-portal.md @@ -0,0 +1,48 @@ +# M06 Control Plane and Portal + +## Goal + +여러 Edge를 연결하고 관찰하며 Edge 설정 변경, 명령 전달, 이벤트 수신을 담당하는 Control Plane과 Web Portal 운영면을 구축한다. + +## Phase + +Phase 3. Control Plane and Portal Operations + +## Status + +Planned + +## Scope + +- Control Plane Go server의 Edge connection 관리 +- Portal-Control Plane, Control Plane-Edge IOP Wire Protocol 확장 +- Web Portal의 Runtime/Automation 운영 화면 기초 +- Edge 상태 조회, 설정 변경, 명령 전달, 이벤트 수신 +- Edge agent 생성과 bootstrap command 발급 상태 조회/관리 +- remote terminal bridge session 생성/조회/권한 확인 표면 + +## Required Features + +- Control Plane은 Node를 직접 연결하거나 직접 스케줄링하지 않는다. +- Portal은 Control Plane을 통해 Edge 운영 상태를 조회한다. +- 브라우저 직접 TCP가 어려운 구간은 Control Plane server-side bridge를 둔다. +- `net/http`는 health/readiness/bootstrap 같은 보조 endpoint 용도로 유지한다. + +## Success Criteria + +- Control Plane이 하나 이상의 Edge 연결 상태를 조회할 수 있다. +- Portal이 Edge/Node/agent 상태를 사용자에게 보여줄 수 있다. +- Edge 명령 전달과 이벤트 수신 흐름이 IOP Wire Protocol 기준으로 문서화된다. +- Control Plane과 Web의 배포/검증 절차가 `docs/deploy-dev.md`와 일치한다. + +## Non-Goals + +- Control Plane을 Kubernetes식 중앙 스케줄러로 만드는 작업 +- Edge 내부 DB를 Control Plane DB로 대체 +- 모든 런타임 상태를 Control Plane 단일 원본으로 만드는 작업 + +## Context for Work + +- 관련 앱: `apps/control-plane`, `apps/web` +- 관련 문서: `apps/control-plane/README.md`, `apps/web/README.md`, `docs/deploy-dev.md` +- 본격 구현 전 control-plane domain rule 생성 또는 갱신이 필요할 수 있다. diff --git a/agent-ops/roadmap/milestones/M07-policy-history-audit.md b/agent-ops/roadmap/milestones/M07-policy-history-audit.md new file mode 100644 index 0000000..de19d5a --- /dev/null +++ b/agent-ops/roadmap/milestones/M07-policy-history-audit.md @@ -0,0 +1,48 @@ +# M07 Policy History Audit + +## Goal + +권한, 정책, 실행 이력, 감사 로그를 제품 운영에 필요한 수준으로 확장한다. +특히 remote terminal bridge와 agent bootstrap은 보안/감사 요구사항을 필수 전제로 둔다. + +## Phase + +Phase 3. Control Plane and Portal Operations + +## Status + +Planned + +## Scope + +- permission model과 policy enforcement 지점 정리 +- Edge/Node 실행 이력과 Control Plane aggregation 경계 +- command/session audit 구조 설계 +- credential 관리와 target allowlist 모델 +- timeout, 동시 실행 제한, 입력/출력 기록 정책 +- metrics/event API와 운영 리포트 후보 + +## Required Features + +- Edge는 로컬 런타임 상태와 실행 이력의 원본을 유지한다. +- Control Plane은 Edge 데이터를 조회/집계하되 Edge 내부 상태 소유권을 대체하지 않는다. +- remote terminal bridge는 target allowlist, credential 관리, command/session audit를 필수로 요구한다. +- policy/audit 상세 schema는 구현 단계에서 명확한 evidence와 함께 확정한다. + +## Success Criteria + +- 실행 요청, command, terminal session, bootstrap/enrollment에 대한 audit event 초안이 있다. +- 권한과 policy가 Edge/Control Plane/Node 경계 중 어디에서 적용되는지 문서화된다. +- 기존 실행 파이프라인을 깨지 않고 history/audit 수집을 붙일 수 있다. + +## Non-Goals + +- 상세 DB schema를 근거 없이 선확정 +- 모든 이벤트를 Control Plane 단일 저장소로 강제 +- 보안 전제가 없는 terminal bridge 또는 insecure bootstrap 기본값 + +## Context for Work + +- 관련 앱: `apps/edge`, `apps/node`, `apps/control-plane` +- 관련 패키지: `packages/auth`, `packages/jobs`, 향후 policy/audit package +- 선행 Milestone: M04, M05, M06 diff --git a/agent-ops/roadmap/milestones/M08-multi-edge-operations.md b/agent-ops/roadmap/milestones/M08-multi-edge-operations.md new file mode 100644 index 0000000..af9768e --- /dev/null +++ b/agent-ops/roadmap/milestones/M08-multi-edge-operations.md @@ -0,0 +1,48 @@ +# M08 Multi-Edge Operations + +## Goal + +여러 Edge group을 관찰하고 운영하는 fleet-level 기능을 구축한다. +Multi-edge scheduling과 fleet-wide state ownership은 Control Plane과 IOP native protocol에서 결정한다. + +## Phase + +Phase 3. Control Plane and Portal Operations + +## Status + +Planned + +## Scope + +- 여러 Edge group 등록/상태 표시 +- Edge별 runtime/automation 상태 집계 +- Edge 단위 실행 이력과 event aggregation +- Edge 단위 작업 실행과 제어 +- OTO 같은 domain agent의 build/deploy 상태, artifact, capability 포함 +- fleet-wide 명령과 운영 리포트 후보 + +## Required Features + +- Multi-edge 운영 명령과 이벤트 집계는 IOP native protocol을 기준으로 설계한다. +- OpenAI-compatible 표면은 특정 Edge/adapter로 라우팅되는 inference 호환 경로로 제한한다. +- A2A 표면은 특정 Edge/adapter로 위임되는 agent task 경로로 제한한다. +- Edge는 자신의 로컬 런타임 상태와 registry 소유권을 유지한다. + +## Success Criteria + +- Control Plane이 여러 Edge 상태를 구분해 조회하고 표시할 수 있다. +- Edge별 실행 이력과 domain agent 상태가 운영 화면에서 구분된다. +- fleet-wide 기능이 Edge의 로컬 상태 소유권을 침범하지 않는다. + +## Non-Goals + +- Control Plane이 매 요청마다 Node를 직접 할당하는 중앙 스케줄러 역할 +- OpenAI-compatible API 또는 A2A API를 multi-edge 운영 제어 기본 프로토콜로 사용 +- Edge federation 상세 설계를 근거 없이 선확정 + +## Context for Work + +- 관련 앱: `apps/control-plane`, `apps/web`, `apps/edge` +- 관련 문서: `docs/architecture.md` +- 선행 Milestone: M06, M07 diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 1c93e3c..f6db9f1 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -25,6 +25,7 @@ - `bin/` — 사용자가 직접 실행하는 edge/node shell entrypoint이다. - `Makefile` — 빌드와 테스트 진입점을 정의한다. - `docs/` — 아키텍처 및 운영 방향 문서이다. +- `agent-ops/roadmap/` — 제품 Goal, Phase, Milestone의 canonical source of truth이다. ## 기술 스택 @@ -57,6 +58,12 @@ - 이미 읽은 domain rule은 같은 세션에서 반복해서 읽지 않는다. - 사용자 실행 파이프라인에 닿는 작업의 검증 단계에서는 `testing` domain rule을 1회 읽는다. +## 마일스톤 컨텍스트 로딩 + +- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 읽고, 그 안의 Active Milestone 문서를 같은 세션에서 1회 읽는다. +- `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. +- 작업 요청이 Active Milestone의 Goal 또는 Non-Goals와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. + ## 도메인 매핑 | 경로 패턴 | 도메인 | rules.md | diff --git a/docs/architecture.md b/docs/architecture.md index b603467..f1ed1ee 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -5,6 +5,7 @@ IOP(Inference Operations Platform)는 모델 서빙과 CLI Agent/Automation 실행을 함께 다루는 실행 오케스트레이션 플랫폼을 지향한다. 단순한 OpenAI-compatible proxy나 모델 라우터가 아니라, Control Plane - Edge - Node 계층으로 로컬 실행 그룹을 관리하는 구조를 목표로 한다. 현재 구현은 Edge-Node 실행 스켈레톤을 검증하는 단계다. Control Plane과 worker는 placeholder이며, 세부 계약은 후속 작업에서 정리한다. +제품 Phase와 Milestone 상세는 `agent-ops/roadmap/ROADMAP.md`에서 관리하고, 이 문서는 상대적으로 덜 변하는 구조 원칙과 책임 경계를 설명한다. ## 계층 구조 diff --git a/docs/deploy-dev.md b/docs/deploy-dev.md index 331282f..c332745 100644 --- a/docs/deploy-dev.md +++ b/docs/deploy-dev.md @@ -117,36 +117,12 @@ repo root에서 수동으로 검증할 때는 기존 helper를 사용할 수 있 IOP_EDGE_ADDR=:9090 ./bin/node.sh ``` -## OTO Agent Bootstrap 방향 +## Agent Bootstrap / Bridge References -OTO는 `iop-node`에 종속시키지 않고 Edge에 직접 붙는 build/deploy domain agent로 둔다. 목표 UX는 Jenkins node 연결처럼 Edge에서 먼저 OTO agent를 생성하고, Edge가 발급한 bootstrap command를 대상 빌드 머신에서 실행하는 방식이다. +OTO 같은 specialized domain agent의 bootstrap/enrollment 상세 계획은 `agent-ops/roadmap/milestones/M05-agent-bootstrap-oto-enrollment.md`에서 관리한다. +Agent 설치가 어렵거나 임시 제어만 필요한 대상의 remote terminal bridge 계획은 `agent-ops/roadmap/milestones/M04-remote-terminal-bridge-poc.md`에서 관리한다. -Agent를 설치할 수 있는 대상은 bootstrap/enrollment를 우선한다. 설치가 어렵거나 임시 제어만 필요한 대상은 Edge가 remote terminal bridge session을 열고, 대상에 도달 가능한 Node가 SSH/WinRM/serial/local shell 같은 terminal transport를 실행해 relay한다. 이 경로는 target allowlist, credential 관리, timeout, session audit를 전제로 한다. - -예상 흐름은 다음과 같다. - -```text -Edge UI/API - -> oto agent 생성 - -> one-time bootstrap token과 install command 발급 - -oto build host - -> bootstrap command 실행 - -> OS/arch에 맞는 oto binary 다운로드 - -> checksum/signature 검증 - -> agent.yaml 생성 - -> systemd/launchd/Windows service 등록 - -> Edge에 outbound 등록 -``` - -폐쇄망과 개발망에서는 도메인 인증서 발급이 어려울 수 있으므로 HTTPS를 필수 전제로 두지 않는다. 대신 HTTP local/insecure 모드는 명시적으로 선택하게 하고, one-time token, Edge fingerprint 또는 public key pinning, 바이너리 checksum/signature 검증, 등록 후 장기 credential 재발급을 함께 요구한다. - -예시 command 형태는 다음처럼 둔다. - -```bash -curl -fsSL http://edge.local:8080/bootstrap/oto.sh \ - | sh -s -- --edge http://edge.local:8080 --token --pool build-linux -``` +이 배포 문서에서는 현재 dev field 기준의 배포 단위와 smoke 절차만 유지한다. ## Field Smoke