iop/agent-roadmap/ROADMAP.md

IOP 로드맵

고정 실행 순서

• 전역 Milestone 실행 순서는 전역 마일스톤 실행 순서를 먼저 확인한다.
• Phase는 도메인/책임 영역이며 순차 실행 게이트가 아니다.
• Phase 흐름과 상태는 로드맵 구조를 설명하고, 실제 다음 작업 선택은 priority-queue.md의 위아래 순서를 우선한다.
• priority-queue.md는 순서 전용 문서이며, 상태, 목표, 범위, 잠금, 기능, 완료 근거는 각 Milestone 문서를 원본으로 삼는다.
• priority-queue.md 항목은 Milestone 제목 링크와 식별용 한 줄 설명만 둔다.
• priority-queue.md는 로드맵 생성 시 함께 만들며, 실행 후보가 없을 때도 문서와 실행 순서 섹션은 유지한다.
• 새 실행 후보 Milestone은 생성과 같은 갱신에서 사용자 지정 위치, 작업 컨텍스트 > 큐 배치의 명시 anchor, 큐 끝 순서로 priority-queue.md에 삽입한다. 일반 선행 작업과 후속 작업은 큐 위치로 해석하지 않는다.
• [보류], [완료], [폐기] Milestone은 큐에서 제거하고, [보류] Milestone을 실행 후보 상태로 재활성화하면 같은 삽입 규칙을 적용한다.
• 신규 삽입과 연속 순번 재계산은 기존 항목 재정렬로 보지 않는다. 기존 항목끼리의 상대 순서는 사용자가 순서 조정을 요청한 경우, Milestone archive 시 완료 항목 제거가 필요한 경우, 큐에 있는 Milestone이 폐기, 경로 변경, split/merge, 또는 실행 의미가 바뀔 정도로 수정된 경우에만 바꾼다.
• priority-queue.md의 링크가 깨졌으면 활성 Milestone 문서를 기준으로 큐를 재정렬하거나 재생성한다.

전체 목표

IOP(Inference Operations Platform)는 Control Plane - Edge - Node 계층 구조를 기반으로 모델 서빙과 CLI Agent/Automation 실행을 함께 운영하는 실행 오케스트레이션 플랫폼을 만든다. 내부 실행 모델은 adapter + target을 기준으로 하며, Edge가 로컬 실행 그룹의 상태와 라우팅을 소유하고 Control Plane은 Edge를 통해 시스템을 관찰하고 제어한다.

IOP는 NomadCode에 종속된 Agent Shell이 아니라, NomadCode와 외부 agent, 운영 CLI, client, 자동화 도구가 함께 소비할 수 있는 범용 추론/자동화 운영 엔진이다. 로드맵 전반에서 OpenAI-compatible API는 외부 클라이언트의 모델 기반 호출 표면으로, A2A API는 외부 agent의 agent-to-agent 작업 위임 표면으로, IOP native protocol은 운영 제어, logical session, background run, command, lifecycle event, remote terminal session 같은 IOP 고유 기능의 기준으로 둔다. OpenAI-compatible API는 현재 chat completions baseline을 넘어 Responses API 호환 표면까지 지원해야 한다. IOP의 외부 실행 호출 계약은 OpenAI-compatible API 방식을 기본 표면으로 채택하고, IOP 고유의 workspace, session, agent, approval, artifact, notification 의미는 별도 iop wrapper field가 아니라 metadata 또는 IOP native endpoint의 명시 필드로 전달한다. IOP native protocol은 proto-socket을 기본으로 하며, HTTP는 OpenAI-compatible/A2A/health/bootstrap처럼 필요한 경계에서만 사용한다. A2A는 표면으로 유지하되, NomadCode가 A2A를 도입하는 시점은 현재 확정하지 않는다. 현재 제1 active delivery는 NomadCode가 IOP를 실행 백엔드로 사용할 수 있도록 OpenAI-compatible Responses 요청의 metadata.workspace, task/source metadata, 내부 workspace-bound agent 실행 경로를 먼저 안정화하는 것이다.

모델 선택, 로컬/클라우드 라우팅, 모델별 profile, token/속도/품질 최적화, 모델 호출 로그와 품질 평가는 IOP 책임으로 둔다. 또한 원격지와 로컬의 Ollama, vLLM, SGLang, Lemonade 같은 추론 엔진은 단순 endpoint가 아니라 provider/device/model 조합으로 관리하고, provider별 lifecycle capability, device 상태, 모델 qualification, 테스트 결과 리포트를 운영 데이터로 축적하는 방향을 목표로 한다. 특히 로컬 모델을 우선 활용하되, cloud fallback과 품질 평가를 결합해 엔터프라이즈 모델 서비스에 가까운 운영 품질을 목표로 한다. RAG, context 구성/압축, web search, MCP 정책, tool policy, output validation, retry/fallback은 기본 모델 서빙과 부하 라우팅이 가능해진 뒤 확장한다.

MVP 경계

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

Phase 흐름

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

• [완료] 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 계약을 완료했다. 최초 요청 workflow 라우팅과 누적 요청 컨텍스트 최적화는 각각 Automation Runtime과 지식·도구 최적화로 분리했다.

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

  • 경로: PHASE.md
  • 요약: 사용자/토큰/사용량/로그 추적과 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
  • 요약: 정적 lane/G 이후의 시간대·quota 기반 adapter + target 선택과 작업별 failover를 우선 구현하고, 사용량 limit 알림/자동 이어받기를 후속으로 두며 원격 터널링과 oto scheduler/CI-CD는 2차로 잠근다.

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

  • 경로: PHASE.md
  • 요약: 단계 호출, tool/schema 강제, 검증/retry/fallback의 MVP 실행 모드를 먼저 스케치하고, caller-neutral 누적 요청 컨텍스트 최적화, RAG 장기 기억, Advisor와 Context Hook은 서로 책임이 다른 2차 기능으로 분리한다.

• [스케치] 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 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 구현 잠금 상태를 해제로 둔다.