toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-roadmap/archive/phase/automation-runtime-bridge/milestones/architecture-refactor-foundation.md
toki 672b4cdb5d refactor(bridge): 실행 경계 선행 안정화를 반영한다 
원격 터미널 브리지 POC 전에 Client HTTP lifecycle과 Edge run result surface 계약을 고정해야 하므로 관련 구현, 테스트, 로드맵 상태를 함께 정리한다.
2026-06-07 08:40:36 +09:00

7.7 KiB
Raw Blame History

Milestone: 전역 설계 부채 리팩토링 기반

위치

  • Roadmap: agent-roadmap/ROADMAP.md
  • Phase: agent-roadmap/phase/automation-runtime-bridge/PHASE.md

목표

원격 터미널 브리지와 이후 Control Plane/Client 운영 확장을 얹기 전에 현재 코드베이스의 설계 부채를 정리한다. Edge, Node, Control Plane, Client, proto/config 경계에서 책임이 섞인 부분을 분리하고, 공개 계약과 tracked 예시 설정이 장기 운영 방향을 흐리지 않게 만든다.

상태

[완료]

구현 잠금

  • 상태: 해제
  • 결정 필요: 없음

범위

  • Edge CLI, Edge service, OpenAI-compatible 입력 표면의 책임 분리
  • Node CLI adapter, persistent terminal/SSE 실행기, adapter routing 기본값 정리
  • Control Plane HTTP/API handler와 fleet status 호출 구조 정리
  • Client 상태/DTO/repository/widget 경계 정리
  • proto status/legacy contract와 tracked config/artifact hygiene 정리
  • 원격 터미널 브리지 POC가 기대는 terminal/session/event 경계의 선행 리팩토링

기능

Epic: [edge-boundary] Edge Boundary Refactor

Edge 내부에서 CLI command, service orchestration, external compatibility surface가 서로 커지는 것을 막는다.

  • [edge-cmd-split] apps/edge/cmd/edge/main.go의 config resolution, bootstrap pack, node registration, YAML patch, smoke client 로직을 기존 동작을 유지한 채 내부 패키지 또는 작은 모듈로 분리한다.
  • [edge-service-split] apps/edge/internal/service를 run dispatch, node command, control command, capability/status provider 책임으로 분리하고 health simulation 같은 임시 command 구현을 실제 상태 조회 경계와 분리한다.
  • [openai-surface-split] apps/edge/internal/openai에서 HTTP lifecycle, chat request mapping, run stream/result collection, strict output policy, Ollama passthrough를 분리해 OpenAI-compatible 표면이 IOP native 기능을 흡수하지 않게 한다.
  • [event-bus-contract] Edge event bus의 drop, replay, immutability, future persistence 정책을 코드 경계와 테스트로 명확히 한다. 검증: go test ./apps/edge/internal/events 통과.

Epic: [node-runtime] Node Runtime Boundary

Node CLI automation runtime을 remote terminal bridge가 재사용할 수 있는 단위와 provider-specific 실행 단위로 나눈다.

  • [cli-executor-split] apps/node/internal/adapters/cli의 mode dispatch와 session map 소유를 executor/strategy 경계로 분리한다. 검증: agent-task/archive/2026/06/m-architecture-refactor-foundation/04_cli_executor_split/complete.log
  • [terminal-core] persistent PTY 실행, screen rendering, resize/input/signal/close 기반이 될 terminal session core를 provider-specific Claude/OpenCode 처리와 분리한다. 검증: agent-task/archive/2026/06/m-architecture-refactor-foundation/05+04_terminal_core/complete.log
  • [router-default] Node adapter registry가 mock 기본값으로 오류를 숨기지 않도록 production 실행 경로의 empty adapter 처리 정책을 명시하고 적용한다.
  • [vllm-surface] vLLM adapter skeleton을 명확히 experimental/disabled로 낮추거나 실행 가능한 streaming adapter로 승격한다.

Epic: [cp-client] Control Plane and Client Boundary

Control Plane과 Flutter Client가 multi-edge 운영면으로 커질 때 선형 지연과 상태 결합이 커지지 않게 한다.

  • [cp-api-split] apps/control-plane/cmd/control-plane/main.go의 server lifecycle, HTTP handler, DTO conversion, Edge command/fleet orchestration을 분리한다. 검증: agent-task/archive/2026/06/m-architecture-refactor-foundation/06_cp_api_split/complete.log
  • [fleet-polling] /fleet/status와 fleet command 호출을 bounded concurrency, cache, timeout 정책으로 정리한다. 검증: agent-task/archive/2026/06/m-architecture-refactor-foundation/07+06_fleet_polling/complete.log
  • [client-state-split] Flutter client의 bootstrap, status state, DTO, repository, panel widget 경계를 분리하고 Firebase/Mattermost 같은 외부 통합은 선택적으로 초기화되게 한다. 검증: agent-task/archive/2026/06/m-architecture-refactor-foundation/08_client_state_split/complete.log

Epic: [contract-hygiene] Contract and Repository Hygiene

공개 계약과 tracked 예시 파일이 실제 운영 원칙과 어긋나지 않게 정리한다.

  • [status-config-summary] Control Plane status contract에서 full NodeConfigPayload 노출 여지를 제거하거나 summary-only DTO로 고정한다. 검증: go test -count=1 ./apps/control-plane/... ./packages/go/... ./proto/gen/...
  • [proto-legacy] legacy scheduling/node registration proto placeholder를 deprecated/reserved/remove 중 하나로 정리하고 생성 코드와 call-site를 맞춘다. 검증: agent-task/archive/2026/06/m-architecture-refactor-foundation/09_proto_legacy_contract/complete.log
  • [sample-config] tracked configs/*.yaml에서 로컬 IP, host명, token, 위험한 bypass flag, 개인 경로를 제거하고 안전한 example/default 기준으로 재정리한다. 검증: go test -count=1 ./apps/edge/cmd/edge ./apps/node/cmd/node
  • [git-artifacts] tracked Flutter build artifact를 제거하고 package build 산출물이 다시 추적되지 않도록 ignore 규칙을 보강한다. 검증: git ls-files | rg --sort path 'packages/flutter/iop_console/build|(^|/)build/.*(cache|unit_test_assets|native_assets|\.dill|\.otf|\.frag|NOTICES)'

완료 리뷰

  • 상태: 승인됨
  • 요청일: 2026-06-07
  • 완료 근거: edge-boundary, node-runtime, cp-client, contract-hygiene의 모든 기능 Task가 완료 근거와 함께 [x] 상태다. 마지막 남은 proto-legacy는 agent-task/archive/2026/06/m-architecture-refactor-foundation/09_proto_legacy_contract/complete.log의 Roadmap Completion 근거로 완료 처리했다.
  • 리뷰 필요:
    • 사용자가 완료 결과를 확인했다
    • archive 이동을 승인했다
  • 리뷰 코멘트: 사용자 요청으로 Milestone 종료를 승인하고 archive 이동을 반영했다.

범위 제외

  • 원격 터미널 브리지 open/input/output/resize/signal/close 기능 구현
  • 새로운 terminal transport(SSH/WinRM/serial) 구현
  • OpenAI Responses API, A2A streaming, provider 품질 최적화 같은 신규 제품 기능
  • 정책/audit 상세 schema 확정
  • 완료된 archive 문서 재포맷

작업 컨텍스트

  • 관련 경로: apps/edge, apps/node, apps/control-plane, apps/client, packages/flutter/iop_console, proto/iop, configs, .gitignore
  • 표준선(선택): Control Plane은 Edge를 통해 관찰/제어하고, Edge는 Node 실행 그룹 상태를 소유하며, Node는 adapter execution과 terminal transport 실행자 역할을 유지한다. OpenAI-compatible/A2A 표면은 IOP native terminal 제어를 흡수하지 않는다.
  • 선행 작업: 설계 부채 색인 리뷰
  • 후속 작업: 원격 터미널 브리지 POC
  • 최근 완료 작업: agent-task/archive/2026/06/m-architecture-refactor-foundation/06_cp_api_split/complete.log, agent-task/archive/2026/06/m-architecture-refactor-foundation/07+06_fleet_polling/complete.log, agent-task/archive/2026/06/m-architecture-refactor-foundation/08_client_state_split/complete.log, agent-task/archive/2026/06/m-architecture-refactor-foundation/09_proto_legacy_contract/complete.log
  • active plan: 없음
  • 확인 필요: 없음
  • 잔여 리스크 처리: 완료 후보를 되돌릴 수준의 결함은 아니지만 원격 터미널 브리지 POC 전에 고정해야 할 Client HTTP lifecycle, Edge run surface, Node terminal core, typed adapter config 리스크를 agent-roadmap/phase/automation-runtime-bridge/milestones/bridge-boundary-hardening.md 후속 Milestone으로 승격했다.