From d0cddf6f6c43e4bf3460c6f0aa831096dc6cf77c Mon Sep 17 00:00:00 2001 From: toki Date: Wed, 17 Jun 2026 13:54:12 +0900 Subject: [PATCH] add update-plane-self-update-foundation phase and update ROADMAP --- agent-roadmap/ROADMAP.md | 4 + .../PHASE.md | 38 +++++++++ .../edge-node-rollout-recovery-policy.md | 79 ++++++++++++++++++ .../host-local-manager-self-update.md | 79 ++++++++++++++++++ .../update-plane-stable-protocol.md | 80 +++++++++++++++++++ 5 files changed, 280 insertions(+) create mode 100644 agent-roadmap/phase/update-plane-self-update-foundation/PHASE.md create mode 100644 agent-roadmap/phase/update-plane-self-update-foundation/milestones/edge-node-rollout-recovery-policy.md create mode 100644 agent-roadmap/phase/update-plane-self-update-foundation/milestones/host-local-manager-self-update.md create mode 100644 agent-roadmap/phase/update-plane-self-update-foundation/milestones/update-plane-stable-protocol.md diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index de2ed77..a154dfd 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -55,6 +55,10 @@ provider/device/model별 qualification report와 모델 lifecycle 관리는 prov - 경로: `agent-roadmap/phase/automation-runtime-bridge/PHASE.md` - 요약: CLI Agent 실행과 운영 자동화의 MVP 표면을 정리하고, 사용량 limit 알림/자동 이어받기를 우선 스케치하되 원격 터널링과 oto scheduler/CI-CD는 2차로 잠근다. +- [계획] Update Plane과 자체 업데이트 기반 + - 경로: `agent-roadmap/phase/update-plane-self-update-foundation/PHASE.md` + - 요약: frontend와 Control Plane만 재배포해도 Edge/Node가 안정 업데이트 프로토콜, 로컬 상태 캐시, host-local manager를 통해 스스로 버전 수렴하는 기반을 정리한다. + - [계획] 지식과 도구 최적화 확장 - 경로: `agent-roadmap/phase/knowledge-tool-optimization-extension/PHASE.md` - 요약: 로컬 모델 성능 향상 축으로 단계 호출, tool/schema 강제, 검증/retry/fallback의 MVP 실행 모드를 먼저 스케치하고, RAG 장기 기억, advisor, context hook은 2차로 분리한다. diff --git a/agent-roadmap/phase/update-plane-self-update-foundation/PHASE.md b/agent-roadmap/phase/update-plane-self-update-foundation/PHASE.md new file mode 100644 index 0000000..e2695d2 --- /dev/null +++ b/agent-roadmap/phase/update-plane-self-update-foundation/PHASE.md @@ -0,0 +1,38 @@ +# Phase: Update Plane과 자체 업데이트 기반 + +## 상태 + +[계획] + +## 목표 + +frontend와 Control Plane만 재배포해도 Edge와 Node가 desired release state에 자동으로 수렴하는 업데이트 기반을 정리한다. +Control Plane은 release manifest, desired version, rollout/audit view를 제공하고, Edge와 Node는 자기 상태와 연결 peer 상태를 로컬 캐시에 보관하며 업데이트 필요 여부와 적용 흐름을 스스로 판단한다. +실제 프로세스 교체는 Edge/Node 앱 프로세스가 직접 수행하지 않고, host-local manager 또는 updater helper가 담당하는 방향을 기준으로 한다. + +## Milestone 흐름 + +완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획, 스케치 또는 보류 Milestone은 이 Phase 하위 `milestones/` 경로를 가리킨다. +완료, 검토중, 진행중, 계획, 스케치 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다. +스케치 Milestone은 아직 구현 가능한 계획이 아니므로 사용자 검토와 구체화 후 `[계획]`으로 승격한다. + +- [스케치] Update Plane 안정 프로토콜 + - 경로: `agent-roadmap/phase/update-plane-self-update-foundation/milestones/update-plane-stable-protocol.md` + - 요약: 전체 운영 프로토콜이 바뀌어도 업데이트를 지속할 수 있는 hello/status, manifest, command, event, recovery 최소 계약을 스케치한다. + +- [스케치] Host-local Manager 기반 자체 업데이트 + - 경로: `agent-roadmap/phase/update-plane-self-update-foundation/milestones/host-local-manager-self-update.md` + - 요약: Edge/Node 앱 프로세스 바깥의 manager/updater가 release staging, 검증, 프로세스 종료/재시작, rollback을 담당하는 cross-OS 실행 모델을 스케치한다. + +- [스케치] Edge/Node 롤아웃과 복구 정책 + - 경로: `agent-roadmap/phase/update-plane-self-update-foundation/milestones/edge-node-rollout-recovery-policy.md` + - 요약: Edge가 Node rolling update와 자기 업데이트를 조율하고, 실패/재연결/rollback 상태를 Control Plane에 보고하는 운영 정책을 스케치한다. + +## Phase 경계 + +- Control Plane은 Edge/Node의 installed state와 runtime registry의 canonical store가 되지 않고, desired state와 release/audit view를 제공한다. +- Edge는 자신의 상태와 Node 관찰 상태를 캐시하고, Node 업데이트 오케스트레이션의 실행 주체가 된다. +- Node는 자신의 버전, platform, update protocol version, 연결된 Edge의 버전 정보를 캐시하고, 필요한 경우 manager/updater를 통해 자체 업데이트한다. +- host-local manager/updater는 Edge 또는 Node로 등록되지 않으며, adapter 실행, routing, Node registry, Control Plane 운영 프로토콜을 담당하지 않는다. +- 업데이트 파이프라인 프로토콜은 장기 안정 레이어로 유지하되, 일반 운영/실행 프로토콜은 Control Plane 재배포와 Edge/Node 업데이트 수렴을 통해 최신 기준으로 따라가게 한다. +- container/orchestrator 기반 배포를 기본 전제로 삼지 않고, field host의 systemd, launchd, Windows Service 환경에서도 동작 가능한 구조를 우선한다. diff --git a/agent-roadmap/phase/update-plane-self-update-foundation/milestones/edge-node-rollout-recovery-policy.md b/agent-roadmap/phase/update-plane-self-update-foundation/milestones/edge-node-rollout-recovery-policy.md new file mode 100644 index 0000000..de96579 --- /dev/null +++ b/agent-roadmap/phase/update-plane-self-update-foundation/milestones/edge-node-rollout-recovery-policy.md @@ -0,0 +1,79 @@ +# Milestone: Edge/Node 롤아웃과 복구 정책 + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/update-plane-self-update-foundation/PHASE.md` + +## 목표 + +Control Plane이 desired version/channel을 제공하면 Edge가 자신의 Node 그룹과 자기 자신을 어떤 순서로 업데이트하고, 실패 시 어떤 기준으로 재시도/rollback/manual intervention을 보고할지 정리한다. +Node 연결 단절, Edge 재시작, protocol mismatch, artifact 검증 실패 같은 상황에서도 최소 상태 캐시와 update event만으로 운영자가 현재 상태를 판단할 수 있게 한다. + +## 상태 + +[스케치] + +## 승격 조건 + +- [ ] Edge가 Node rolling update를 시작하기 전 drain/admission 정책을 확정한다. +- [ ] Node update와 Edge self-update의 순서와 compatibility 기준을 정한다. +- [ ] 업데이트 중 연결 단절과 재연결 성공 판정 기준을 정한다. +- [ ] rollback과 manual intervention 상태를 Control Plane에 보고하는 기준을 정한다. +- [ ] 후속 구현 Milestone과 SDD 필요 범위를 나눈다. + +## 구현 잠금 + +- 상태: 잠금 +- SDD: 필요 +- SDD 문서: `agent-roadmap/sdd/update-plane-self-update-foundation/edge-node-rollout-recovery-policy/SDD.md` +- SDD 사유: Edge/Node update lifecycle, drain/restart/rollback 정책, 상태 캐시와 Control Plane 보고 계약이 필요하다. +- 잠금 해제 조건: + - [ ] SDD 잠금이 해제되어 있다 + - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다 +- 결정 필요: + - [ ] 자동 롤아웃의 기본 허용 범위와 수동 승인 gate가 필요한 환경 기준을 정한다. + +## 범위 + +- Edge가 Node별 desired version과 observed version을 비교해 update 필요 여부를 판단하는 정책 +- Node rolling update 순서, concurrency, drain, in-flight run 처리 후보 +- Edge self-update 시점과 Control Plane 재연결 후 성공 판정 기준 +- update event/audit를 Control Plane과 frontend에서 보여줄 최소 상태 +- 실패 시 retry, rollback, manual intervention, bootstrap fallback의 상태 분류 + +## 기능 + +### Epic: [rollout] 롤아웃과 복구 기준 + +Edge가 Node와 자기 자신의 업데이트를 조율하고 Control Plane에 관찰 가능한 상태를 보고하는 정책을 정리한다. + +- [ ] [node-rollout] Node rolling update 순서, 동시성, drain/admission 기준 후보가 정리되어 있다. +- [ ] [edge-self] Edge self-update 시점과 Control Plane 재연결 성공 판정 후보가 정리되어 있다. +- [ ] [cache] Edge/Node local cache로 복구할 수 있는 상태와 버릴 수 있는 상태가 정리되어 있다. +- [ ] [failure] artifact 검증 실패, protocol mismatch, 재시작 실패, 재연결 실패의 recovery 상태가 정리되어 있다. +- [ ] [ops-view] Control Plane/frontend가 보여줄 update summary, event, audit view 후보가 정리되어 있다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 스케치 상태이므로 완료 근거 없음 +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- 세부 UI 화면 구현 +- 실제 update runner 구현과 OS별 installer 완성 +- provider/model serving rollback, runtime output validation rollback 정책 + +## 작업 컨텍스트 + +- 관련 경로: `apps/control-plane/**`, `apps/edge/internal/controlplane/**`, `apps/edge/internal/service/**`, `apps/node/internal/transport/**` +- 표준선(선택): Control Plane은 desired state와 audit view를 제공하고, Edge는 Node 그룹 업데이트의 실행 주체가 되며, Node는 자기 update 적용을 manager/updater에 위임한다. +- 선행 작업: Update Plane 안정 프로토콜, Host-local Manager 기반 자체 업데이트 +- 후속 작업: 실제 update command/proto/config 구현 Milestone +- 확인 필요: 자동 업데이트 기본값, 롤아웃 동시성, failure threshold, rollback retention diff --git a/agent-roadmap/phase/update-plane-self-update-foundation/milestones/host-local-manager-self-update.md b/agent-roadmap/phase/update-plane-self-update-foundation/milestones/host-local-manager-self-update.md new file mode 100644 index 0000000..8820d90 --- /dev/null +++ b/agent-roadmap/phase/update-plane-self-update-foundation/milestones/host-local-manager-self-update.md @@ -0,0 +1,79 @@ +# Milestone: Host-local Manager 기반 자체 업데이트 + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/update-plane-self-update-foundation/PHASE.md` + +## 목표 + +Edge/Node 앱 프로세스가 자기 바이너리를 직접 교체하지 않고, 앱 바깥의 host-local manager 또는 updater helper가 프로세스 종료, release pointer 전환, 재시작, rollback을 담당하는 실행 모델을 정리한다. +Linux, macOS, Windows에서 공통으로 유지할 release directory와 current pointer 전략을 스케치하고, systemd/launchd/Windows Service와의 책임 경계를 잡는다. + +## 상태 + +[스케치] + +## 승격 조건 + +- [ ] 항상 떠 있는 manager 방식과 one-shot updater helper 방식의 MVP/장기 기준을 결정한다. +- [ ] Linux, macOS, Windows별 프로세스 종료와 binary 전환 제약을 정리한다. +- [ ] release directory, current pointer, staged artifact, rollback metadata의 파일 구조를 확정한다. +- [ ] manager가 담당하지 않을 IOP Node/Edge runtime 책임을 명확히 한다. +- [ ] 후속 구현 Milestone과 SDD 필요 범위를 나눈다. + +## 구현 잠금 + +- 상태: 잠금 +- SDD: 필요 +- SDD 문서: `agent-roadmap/sdd/update-plane-self-update-foundation/host-local-manager-self-update/SDD.md` +- SDD 사유: cross-OS 프로세스 lifecycle, 파일 전환, rollback 상태 머신, service manager 연동에 영향을 준다. +- 잠금 해제 조건: + - [ ] SDD 잠금이 해제되어 있다 + - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다 +- 결정 필요: + - [ ] 초기 MVP를 one-shot updater helper로 시작할지, 항상 실행되는 manager로 시작할지 결정한다. + +## 범위 + +- `iop-manager` 또는 `iop-updater` helper의 책임과 비책임 경계 +- `releases//`, `current` pointer, `state/update.json`, rollback metadata 구조 후보 +- Linux systemd, macOS launchd, Windows Service에서 manager/updater가 앱 프로세스를 내리고 다시 올리는 방식 +- Edge/Node 앱이 update 필요를 판단하고 manager/updater에 전환 요청을 넘기는 로컬 API 또는 command boundary +- artifact 검증, staging, activation, rollback, post-start version 확인 흐름 + +## 기능 + +### Epic: [manager] Host-local 업데이트 실행자 + +Edge/Node 앱과 별개로 프로세스 바꿔치기 구간만 담당하는 작은 host-local 실행자를 정의한다. + +- [ ] [responsibility] manager/updater가 담당할 process lifecycle, artifact 검증, release pointer 전환, rollback 책임이 정리되어 있다. +- [ ] [non-node] manager/updater가 Edge에 Node로 등록되지 않고 adapter 실행/routing/registry에 참여하지 않는 경계가 정리되어 있다. +- [ ] [layout] release directory와 current pointer, staged artifact, update state 파일 구조 후보가 정리되어 있다. +- [ ] [os-strategy] Linux, macOS, Windows별 교체/재시작 전략과 제약이 정리되어 있다. +- [ ] [local-boundary] Edge/Node 앱이 manager/updater에 업데이트 적용을 요청하는 로컬 경계 후보가 정리되어 있다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 스케치 상태이므로 완료 근거 없음 +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- Edge/Node adapter execution, model serving, CLI runtime 기능 구현 +- manager를 Control Plane 또는 Edge에 별도 agent로 등록하는 구조 +- OS별 installer/package manager의 완성형 구현 + +## 작업 컨텍스트 + +- 관련 경로: `packages/go/hostsetup/**`, `apps/edge/internal/edgecmd/bootstrap.go`, `apps/edge/internal/edgecmd/setup.go`, `apps/node/cmd/node/main.go` +- 표준선(선택): 실행 중 바이너리를 덮어쓰지 않고 새 release를 옆에 풀어 검증한 뒤 current pointer를 전환한다. +- 선행 작업: Update Plane 안정 프로토콜 +- 후속 작업: Edge/Node 롤아웃과 복구 정책 +- 확인 필요: 초기 배포 UX에서 manager를 bootstrap에 포함할 시점, Windows current pointer 표현 방식 diff --git a/agent-roadmap/phase/update-plane-self-update-foundation/milestones/update-plane-stable-protocol.md b/agent-roadmap/phase/update-plane-self-update-foundation/milestones/update-plane-stable-protocol.md new file mode 100644 index 0000000..f14b144 --- /dev/null +++ b/agent-roadmap/phase/update-plane-self-update-foundation/milestones/update-plane-stable-protocol.md @@ -0,0 +1,80 @@ +# Milestone: Update Plane 안정 프로토콜 + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/update-plane-self-update-foundation/PHASE.md` + +## 목표 + +Edge/Node의 일반 운영 프로토콜이 바뀌어도 업데이트 파이프라인만은 지속적으로 동작하도록 최소 안정 계약을 정의한다. +hello/status, release manifest, update command, update event, recovery 판단에 필요한 필드만 장기 호환 레이어로 고정하고, 나머지 실행/운영 프로토콜은 최신 Control Plane 기준으로 수렴시키는 방향을 잡는다. + +## 상태 + +[스케치] + +## 승격 조건 + +- [ ] Edge와 Node가 보고해야 할 최소 self/peer 상태 필드를 확정한다. +- [ ] release manifest의 필수 필드와 서명/해시 검증 기준을 확정한다. +- [ ] update command와 update status/event의 상태 전이를 구현 가능한 수준으로 정리한다. +- [ ] 너무 오래된 updater protocol을 만났을 때의 manual/bootstrap fallback 기준을 정리한다. +- [ ] 후속 구현 Milestone과 SDD 필요 범위를 나눈다. + +## 구현 잠금 + +- 상태: 잠금 +- SDD: 필요 +- SDD 문서: `agent-roadmap/sdd/update-plane-self-update-foundation/update-plane-stable-protocol/SDD.md` +- SDD 사유: 업데이트 프로토콜, manifest schema, 상태 전이, recovery 규칙이 proto/config/schema와 lifecycle 계약에 직접 닿는다. +- 잠금 해제 조건: + - [ ] SDD 잠금이 해제되어 있다 + - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다 +- 결정 필요: + - [ ] 기본 release channel과 자동 적용/승인 적용의 제품 정책을 정한다. + +## 범위 + +- Edge hello/status에 포함할 version, update_protocol_version, platform, capability, peer version 관찰 정보 +- Node registration/status에 포함할 version, platform, update_protocol_version, connected peer version 정보 +- release manifest의 component, version, protocol, platform, artifact URL, sha256/signature, compatibility 필드 +- update command의 update id, target selector, desired version/channel, drain/restart policy +- update status/event의 accepted, downloading, verified, staged, draining, restarting, reconnected, completed, failed, rolled_back 상태 +- recovery와 fallback에 필요한 최소 오류 코드와 manual intervention 기준 + +## 기능 + +### Epic: [protocol] 안정 업데이트 계약 + +업데이트를 가능하게 하는 최소 프로토콜을 일반 운영 프로토콜과 분리해 장기 호환 레이어로 정리한다. + +- [ ] [status-fields] Edge/Node self 상태와 연결 peer 상태 캐시 필드 후보가 정리되어 있다. +- [ ] [manifest-schema] release manifest와 artifact 검증 필수 필드 후보가 정리되어 있다. +- [ ] [update-command] update command와 target selector, drain/restart policy 후보가 정리되어 있다. +- [ ] [update-events] update status/event 상태 전이와 실패 코드 후보가 정리되어 있다. +- [ ] [fallback] updater protocol 불일치와 artifact 검증 실패 시 fallback 기준이 정리되어 있다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 스케치 상태이므로 완료 근거 없음 +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- 일반 RunRequest, provider status, CLI command, OpenAI-compatible/A2A 실행 프로토콜의 전체 호환성 보장 +- 실제 proto/schema 구현과 generated code 갱신 +- release artifact 저장소, 서명 인프라, UI 구현 + +## 작업 컨텍스트 + +- 관련 경로: `proto/iop/control.proto`, `proto/iop/runtime.proto`, `apps/control-plane/**`, `apps/edge/**`, `apps/node/**`, `packages/go/version/**` +- 표준선(선택): 업데이트 파이프라인 프로토콜만 안정 ABI로 보고, 나머지 운영 프로토콜은 최신 Control Plane과 Edge/Node 업데이트 수렴을 통해 따라간다. +- 선행 작업: 없음 +- 후속 작업: Host-local Manager 기반 자체 업데이트, Edge/Node 롤아웃과 복구 정책 +- 확인 필요: release channel 기본 정책, signature 방식, 최소 지원 updater protocol 범위