iop/agent-roadmap/ROADMAP.md

IOP 로드맵

고정 실행 순서

• 전역 Milestone 실행 순서는 전역 마일스톤 실행 순서를 먼저 확인한다.
• Phase는 도메인/책임 영역이며 순차 실행 게이트가 아니다.
• Phase 흐름과 상태는 로드맵 구조를 설명하고, 실제 다음 작업 선택은 priority-queue.md의 prefix별 index와 차단 표기를 따른다.
• priority-queue.md는 순서 전용 문서이며, 상태, 목표, 범위, 잠금, 기능, 완료 근거는 각 Milestone 문서를 원본으로 삼는다.
• priority-queue.md 항목은 [prefix-NN] Milestone 제목 링크, 1~2문장 설명, 필요한 선행 차단/동시 차단 예외만 둔다.
• priority-queue.md는 로드맵 생성 시 함께 만들며, 실행 후보가 없을 때도 문서와 실행 순서 섹션은 유지한다.
• 새 실행 후보 Milestone은 생성과 같은 갱신에서 같은 작업 lane의 prefix와 index를 배정한다. 같은 prefix의 작은 index는 정상 선행이고, 다른 prefix는 차단 표기가 없으면 병렬 실행할 수 있다.
• [보류], [완료], [폐기] Milestone은 큐에서 제거하고, [보류] Milestone을 실행 후보 상태로 재활성화하면 같은 삽입 규칙을 적용한다.
• 신규 삽입과 prefix 안의 index 재계산은 기존 파일 경로 변경이 아니다. 실행 태그를 바꾸면 Milestone H1, Phase/current 표시, queue 제목과 blocker 참조만 함께 바꾸며, 파일명은 유지한다.
• priority-queue.md의 링크가 깨졌으면 활성 Milestone 문서를 기준으로 큐를 재정렬하거나 재생성한다.

전체 목표

IOP(Inference Operations Platform)는 Control Plane - Edge - IOP Node 계층 구조를 기반으로 모델·provider·device의 서빙과 운영을 담당하는 추론 운영 플랫폼을 만든다. 내부 실행 모델은 adapter + target을 기준으로 하며, Edge가 로컬 provider 실행 그룹의 상태와 라우팅을 소유하고 Control Plane은 Edge를 통해 IOP 시스템을 관찰하고 제어한다.

IOP는 특정 agent 제품에 종속된 Shell이 아니라, 외부 agent·client·자동화 도구가 추론 API를 통해 소비할 수 있는 범용 추론 운영 엔진이다. execution preset이 여러 model call과 agent tool round-trip을 하나의 논리 요청으로 조정할 수는 있지만, 실제 workspace·terminal 실행 소유권, 독립 automation process, scheduler와 사람 승인 workflow는 IOP 제품 경계에 포함하지 않는다. 로드맵 전반에서 OpenAI-compatible API와 Anthropic-compatible Messages API는 외부 클라이언트의 모델 기반 호출 표면으로, IOP native protocol은 provider 실행·취소·상태·usage와 provider/device/model lifecycle 같은 IOP 고유 운영 기능의 기준으로 둔다. OpenAI-compatible API는 현재 chat completions baseline을 넘어 Responses API 호환 표면까지 지원해야 한다. Anthropic-compatible Messages API는 Edge가 직접 제공해 Claude Code를 포함한 client가 별도 agent-client gateway 없이 IOP를 호출하게 하며, Chat-only upstream은 IOP의 protocol bridge로 연결한다. IOP의 외부 추론 호출 계약은 OpenAI-compatible API 방식을 기본 표면으로 채택하고, model/provider route, 요청 상관관계, usage, 취소·상태처럼 IOP가 소유하는 의미만 제한된 metadata 또는 IOP native endpoint의 명시 필드로 전달한다. IOP native protocol은 proto-socket을 기본으로 하며, HTTP는 OpenAI-compatible/A2A/health/bootstrap처럼 필요한 경계에서만 사용한다. A2A는 provider-backed 요청을 수용하는 호환 표면으로 유지하며, workflow 의미를 도입하지 않는다. iop-agent 자산의 Chronos 수용 bundle 전달과 IOP의 workspace agent·CLI agent session·terminal·Chronos 연결 surface 제거는 완료됐다. 현재 active delivery는 IOP 실행 프리셋과 Hot Path이며, IOP Node에는 추론 provider 운영 경계만 유지한다. IOP 내부 라우팅 축은 외부 model을 전체 execution preset에 매핑하고 direct/light Hot Path와 논리 request_id coordinator를 구축한 뒤, heavy Plan/Review, cloud-first preset mode 라우팅과 routing evidence 기반 local selector 전환으로 확장한다.

모델 선택, 요청 난이도에 따른 execution mode, 로컬/클라우드 라우팅, 외부 model별 execution preset, token/속도/품질 최적화, 모델 호출 로그와 품질 평가는 IOP 책임으로 둔다. 외부 model 선택이 preset을 고정하고 Edge가 model advisory와 deterministic hard gate를 결합해 allowed mode와 stage binding을 확정하며, Node는 확정된 provider stage를 실행한다. Control Plane은 principal과 IOP token, 사용자별 provider credential slot의 원장을 소유하고 Edge는 principal별 route와 제한된 credential lease를 실행에 사용한다. 또한 원격지와 로컬의 Ollama, vLLM, SGLang, Lemonade 같은 추론 엔진은 단순 endpoint가 아니라 provider/device/model 조합으로 관리하고, provider별 lifecycle capability, device 상태, 모델 qualification, 테스트 결과 리포트를 운영 데이터로 축적하는 방향을 목표로 한다. 초기 하이브리드 라우팅은 cloud frontier model을 semantic judge/teacher로 활용해 route evidence를 축적하고, 충분한 품질·규모 gate를 통과하면 RAG 기반 local routing model을 운영 기본으로 점진 전환하되 cloud fallback과 품질 평가를 유지한다. RAG, context 구성/압축, web search, MCP 정책, tool policy, output validation, retry/fallback은 기본 모델 서빙과 부하 라우팅이 가능해진 뒤 확장한다.

MVP 경계

1차 MVP는 다중 IOP Node/디바이스의 model group queue와 추가 provider 검증, provider 요청 사용량·실행 로그와 운영 관측, 사용자/토큰/credential 추적, provider catalog와 로컬 디바이스 상태 관찰, request-local 단계 호출과 runtime schema 검증의 최소 실행 모드를 기준으로 둔다. standalone workflow, agent automation, terminal과 desktop delivery는 IOP 제품 범위 밖의 별도 제품 축으로 둔다. provider/device/model별 qualification report와 모델 lifecycle 관리는 provider serving 경로와 capacity/concurrency 기준선이 잡힌 뒤 운영 관측과 Provider 관리 Phase의 후반부에서 깊게 구체화한다. (2차)로 분류한 누적 요청 컨텍스트 최적화, 장기 기억/RAG update loop, advisor와 Context Hook, cross-Edge/cloud fallback 고도화는 IOP MVP 이후 스케치로 잠근다. 특정 Node CLI agent, 원격 터널링과 oto 기반 scheduler/CI-CD는 IOP 후속 후보에서 제외한다. 새로 추가되는 MVP/2차 Milestone은 모두 사용자 검토 전까지 구현 잠금: 잠금 상태를 유지하고, 구현 계획이나 세부 API 확정은 별도 구체화 요청에서 다룬다.

Phase 흐름

Phase는 실행 순서가 아니라 도메인/책임 영역의 구조적 지도다. 완료된 Phase도 로드맵에서 제거하지 않고, archive의 Phase 문서로 연결한다. 상태 그룹은 완료, 검토중, 진행중, 계획, 스케치 순서로 정리해 각 도메인 축의 성숙도와 정리 상태를 읽기 쉽게 한다. 실제 다음 작업 선택은 전역 마일스톤 실행 순서의 prefix별 index와 차단 표기를 따른다.

• [완료] Edge-Node 실행 기반

  • 경로: PHASE.md
  • 요약: Edge-Node 소켓 실행 경로, Node adapter execution, CLI session, 최소 외부 입력 표면을 안정화한 단계다.

• [완료] Ollama 서빙 안정화 기반

  • 경로: PHASE.md
  • 요약: Edge OpenAI-compatible API에서 Node의 Ollama adapter를 호출하는 E2E 경로를 실제 Ollama endpoint와 split-host 환경에서 안정화했다. 추가 provider, 표준화, 후속 최적화 계층은 후속 Phase로 넘긴다.

• [완료] Control Plane과 Client 운영

  • 경로: PHASE.md
  • 요약: 여러 Edge를 관찰하고 운영하는 중앙 제어면과 Flutter client 운영면을 구축하는 단계다.

• [완료] 추론 서버 provider 확장

  • 경로: PHASE.md
  • 요약: 1차 MVP의 속도 향상 축으로, 같은 Edge 안의 model group queue와 여러 Node 후보 순차 dispatch를 기준으로 다중 디바이스 효율을 높이고 Lemonade/vLLM/SGLang 같은 provider 검증을 이어가는 단계다.

• [완료] 라우팅 정책과 모델 오케스트레이션

  • 경로: PHASE.md
  • 요약: OpenAI-compatible raw tunnel, provider 연동, mixed provider dispatch와 provider capability 기반 passthrough 계약을 완료했다. 과도하게 결합됐던 과거 Hybrid Routing 스케치는 폐기했지만, IOP Edge의 요청 난이도·실행 형태·local/cloud 판정 책임은 지식과 도구 최적화 확장 Phase에서 현재 경계에 맞게 복원한다.

• [진행중] 운영 관측과 Provider 관리

  • 경로: PHASE.md
  • 요약: 사용자/IOP token/provider credential/사용량/로그 추적과 cloud API protocol profile, native Messages, API/CLI/local inference provider catalog, 로컬 디바이스 provider 상태 관리, provider/device/model qualification report와 모델 lifecycle 관리 방향을 MVP 운영 축과 후속 심화 축으로 스케치한다.

• [진행중] Update Plane과 자체 업데이트 기반

  • 경로: PHASE.md
  • 요약: frontend와 Control Plane만 재배포해도 Edge/Node가 안정 업데이트 프로토콜, 로컬 상태 캐시, host-local manager를 통해 스스로 버전 수렴하는 기반을 정리한다.

• [완료] Automation Runtime과 Bridge 확장

  • 경로: PHASE.md
  • 요약: iop-agent의 source·contract·test·config·state·build·document 자산을 repository-neutral Chronos acceptance bundle로 전달하고 IOP의 관련 surface와 의존성을 제거했다. 완료 evidence로 Chronos Roadmap의 외부 잠금을 해제했으며, 이후 Chronos Server/Node의 작업 루프·agent·terminal 제어는 Chronos가 소유한다. IOP Node에는 추론 provider 운영 경계만 남기고 Chronos 연결점을 두지 않는다.

• [계획] 지식과 도구 최적화 확장

  • 경로: PHASE.md
  • 요약: 외부 model에 연결되는 execution preset과 request_id coordinator를 만들고 direct/light Hot Path, heavy Plan/Review, cloud-first preset mode 라우팅으로 확장한다. 운영 evidence가 충분해지면 routing 전용 RAG local selector로 점진 전환하며, repository 장기 기억 RAG와 Advisor/Context Hook은 별도 책임으로 유지한다.

• [스케치] Personal Edge 패키징과 배포 프로파일

  • 경로: PHASE.md
  • 요약: 로컬용/서버용 코어를 분기하지 않고 같은 Edge runtime을 personal/server/fleet 배포 모드와 capability gate로 운용하며, 개인 로컬 패키지와 서버/팀 배포 패키징 경계를 장기 후속 축으로 스케치한다.

로딩 정책

• 일반 작업에서는 ROADMAP.md를 매번 읽지 않는다.
• Phase를 가로지르는 다음 작업 후보를 고를 때는 전역 마일스톤 실행 순서를 먼저 확인한다.
• 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 current.md를 먼저 읽는다.
• current.md는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
• current.md에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
• current.md의 활성 Phase는 실제 활성 Phase 문서 경로를 가리킨다.
• current.md의 활성 Milestone은 실제 활성 Phase 하위의 Milestone 문서 경로를 가리킨다.
• current.md는 agent-roadmap/archive/** 경로를 활성 항목으로 포함하지 않는다.
• 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Phase와 Milestone 문서를 같은 세션에서 1회 읽는다.
• 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
• 이 문서는 로드맵 생성/갱신, Phase 전환, Phase 추가/수정, 전체 구조 변경 요청이 있을 때만 읽는다.
• 상세 작업은 각 Milestone 문서의 기능으로 관리한다. 검증이 필요한 기능만 같은 Task 안에 검증:으로 통합한다.
• 모든 기능 Task와 Task 안에 명시된 검증이 충족된 Milestone은 먼저 [검토중]으로 두고, 사용자 완료 확인과 archive 승인을 받은 뒤 [완료]로 전환한다.
• 완료된 Phase는 archive Phase 문서 경로로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
• 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 해당 archive Phase 하위 milestones/ 경로로 이동한다.
• archive PHASE.md는 Phase 자체가 완료 또는 폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 milestones/만 있을 수 있다.
• agent-roadmap/archive/**는 일반 작업에서 읽지 않는다. 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 ROADMAP.md 또는 PHASE.md의 archive 링크를 따라가서 읽는다.
• 아카이브된 Phase/Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.
• 선택된 Milestone의 구현 잠금 섹션이 없거나 상태가 잠금이면 코드 구현, agent-task 구현 계획 생성, 세부 API/파일 구조 확정을 시작하지 않는다.
• 현재 요청과 직접 관련 없는 미정 항목도 잠금 상태의 Milestone 안에서는 실구현 진행 예외가 아니다. 먼저 roadmap-only 갱신으로 해당 항목을 범위 제외, 후속 Milestone, 또는 작업 컨텍스트로 옮기고 구현 잠금을 해제한 뒤 별도 구현 계획에서 진행한다.
• Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 구현 잠금 상태를 해제로 둔다.