iop/agent-roadmap/phase/automation-runtime-bridge/PHASE.md

Phase: Automation Runtime과 Bridge 확장

상태

[진행중]

목표

Runtime과 Automation 실행 흐름을 공통화하고, agent 설치형 대상과 비설치형 대상의 제어 경로를 분리해 확장한다. CLI 실행, specialized agent 등록, bootstrap/enrollment, OpenAI-compatible workspace agent 실행 계약을 서로 충돌하지 않는 운영 경로로 정리했다. NomadCode가 IOP를 실행 백엔드로 사용할 수 있도록 하는 Responses 기반 workspace agent 실행 계약과 정적 lane/G 결과를 시간대·quota·실행 상태와 결합하는 Agent Task 동적 실행 Target Selector를 완료했다. 후속으로 Node와 독립 iop-agent CLI가 함께 사용하는 공통 Go Agent Task runtime으로 현재 Python 감시 루프를 전체 동등성 기준에서 이전하고 provider/grade routing을 같은 공통 경계에 연결한다. 개인 장비의 단일 iop-agent가 여러 project와 Flutter·Unity client subprocess를 소유하며, Flutter Desktop Control UI와 Unity 3D Desktop Character 구현은 CLI 이후의 별도 Milestone으로 둔다. 원격 터미널/CLI 터널링과 oto scheduler/CI-CD 자동화는 2차 스케치로 잠그고, 현재 활성 구현 범위로 끌어오지 않는다.

Milestone 흐름

완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획, 스케치 또는 보류 Milestone은 이 Phase 하위 milestones/ 경로를 가리킨다. 이 흐름은 해당 Phase 안의 상태 정리이며, Phase를 가로지르는 실행 순서는 아니다. Milestone은 완료, 검토중, 진행중, 계획, 스케치 또는 보류 상태 그룹으로 정리한다. Phase를 가로지르는 실제 다음 작업 선택은 전역 마일스톤 실행 순서를 우선한다.

• [완료] CLI Automation Runtime 안정화

  • 경로: cli-automation-runtime-stabilization
  • 요약: one-shot, persistent terminal, opencode SSE, codex exec 계열 CLI 실행 모드와 운영 command 응답을 같은 adapter execution 모델 안에서 안정화했다.

• [완료] Agent Bootstrap과 Domain Agent 등록

  • 경로: agent-bootstrap-domain-agent-enrollment
  • 요약: Edge 직접 연결 specialized domain agent 등록을 위한 MVP enrollment 계약과 후속 구현 Milestone 경계를 확정했다.

• [완료] Domain Agent Registry 구현

  • 경로: domain-agent-registry-implementation
  • 요약: Edge-side generic-node/domain-agent 구분을 config/store, registry/transport, service snapshot에 반영하고 검증을 완료했다.

• [완료] Domain Agent Bootstrap Command 발급

  • 경로: domain-agent-bootstrap-command-issue
  • 요약: iop-edge agent register가 domain agent record와 Linux bootstrap script 인자를 포함한 one-line command를 발급하고 config roundtrip 검증을 완료했다.

• [완료] IOP 전용 Domain Agent 경로 제거

  • 경로: domain-agent-specific-iop-removal
  • 요약: 독립 Control Plane 전환에 맞춰 IOP 활성 코드와 문서에서 전용 agent kind, bootstrap, smoke, 운영 문구를 제거했다.

• [완료] 전역 설계 부채 리팩토링 기반

  • 경로: architecture-refactor-foundation
  • 요약: 원격 터미널 브리지와 이후 운영 확장 전에 Edge, Node, Control Plane, Client, proto/config 경계의 설계 부채를 정리했고, 잔여 리스크는 후속 선행 안정화 마일스톤으로 넘겼다.

• [완료] OpenAI Responses Input Surface

  • 경로: openai-responses-input-surface
  • 요약: Edge OpenAI-compatible 입력 표면에 non-streaming POST /v1/responses, metadata 전달 계약, response subset, iop-edge smoke openai Responses 검증을 추가하고 실제 Edge/Node/fake Ollama smoke evidence를 확보했다.

• [폐기] Specialized Agent proto-socket 연결 기반

  • 경로: specialized-agent-proto-socket-foundation
  • 요약: domain agent가 독립형 실행 방식으로 전환될 예정이므로 Edge 직접 proto-socket specialized peer 기준의 연결 기반 정리는 폐기한다.

• [폐기] Domain Agent Registration Online Smoke

  • 경로: domain-agent-registration-online-smoke
  • 요약: 독립형 실행 방식으로 전환될 예정이므로 Edge 직접 registration online smoke는 폐기한다.

• [폐기] Domain Agent Registration Unlock Handoff

  • 경로: domain-agent-registration-unlock-handoff
  • 요약: 독립형 실행 전환으로 Edge 직접 등록 흐름 잠금 해제 handoff가 필요 없어져 폐기한다.

• [폐기] Domain Agent Message Boundary

  • 경로: domain-agent-message-boundary
  • 요약: 독립형 실행 전환으로 Edge 직접 domain payload boundary 정리가 현재 범위에서 필요 없어져 폐기한다.

• [완료] 워크스페이스 포트/환경 표준화

  • 경로: workspace-port-env-standardization
  • 요약: Control Plane, Edge, Node, Client, OpenAI-compatible, A2A, wire, metrics, DB/cache 포트를 workspace 공통 대역으로 정렬한다.

• [완료] 브리지 선행 경계 안정화

  • 경로: bridge-boundary-hardening
  • 요약: 원격 터미널 브리지 POC 전에 남은 호환성/소유권 리스크를 Client HTTP lifecycle, Edge run surface, Node terminal core, typed adapter config 계약으로 고정한다.

• [완료] Codex App Server 스트리밍 전환

  • 경로: codex-app-server-streaming-migration
  • 요약: Codex CLI target의 기본 codex profile을 app-server 기반으로 전환하고 실제 codex foreground/background smoke와 app-server session lifecycle 검증을 완료했다.

• [완료] OpenAI Workspace Agent Execution Contract

  • 경로: openai-workspace-agent-execution-contract
  • 요약: NomadCode가 IOP CLI를 직접 실행하지 않고 IOP Edge OpenAI-compatible HTTP 호출의 metadata.workspace와 task/source metadata만으로 내부 workspace-bound agent target이 해당 checkout에서 산출물을 만들 수 있게 하는 최우선 contract/serving hardening 작업이다.

• [완료] 에이전트 작업성 중심 저장소 구조 리팩터링

  • 경로: agent-readable-repository-refactor
  • 요약: 거대 소스·테스트와 추적 artifact를 책임 단위로 정리하고, task-local read set과 동작 보존형 가독성 ratchet을 검증해 완료했다.

• [완료] Agent Task 동적 실행 Target Selector

  • 경로: agent-task-runtime-target-selector
  • 요약: 정적 lane/G 결과를 시간대, quota와 이전 실행 상태에 결합해 작업 단위로 고정되는 adapter + target 선택과 failover·selfcheck·task-local blocker·독립 작업 drain 정책을 구현했다. 중복된 최종 audit pair는 임시 Python 구현 폐기 예정에 따른 사용자 결정으로 미실행 종료했다.

• [계획] Pi CLI Provider Integration

  • 경로: pi-cli-provider-integration
  • 요약: Node CLI adapter의 실행 profile 후보에 Pi를 추가하고, Pi JSON stream 출력 파서, config 예시, OpenAI-compatible route smoke를 통해 adapter=cli,target=pi를 안정적으로 사용할 수 있게 한다.

• [계획] CLI Agent Group Grade Routing

  • 경로: cli-agent-group-grade-routing
  • 요약: PLAN-local-G08.md, CODE_REVIEW-cloud-G07.md 같은 예약어/lane/grade 파일명을 기준으로 CLI provider agent를 목적별 agent group에 라우팅하고, 수동/자동 grade range assignment와 OpenAI-compatible metadata.agent_group.task_file 계약을 정리한다.

• [계획] IOP Agent CLI Runtime

  • 경로: iop-agent-cli-runtime
  • 요약: 현재 Python 감시·dispatcher와 Node CLI runtime의 전체 동등성을 공통 Go CLI Provider·AgentTaskManager 및 개인 장비당 단일 iop-agent binary로 이전하고, 다중 project 관측·수동 시작/자동 재개·client subprocess 소유 경계를 고정한다.

• [스케치] Flutter Desktop Control UI

  • 경로: flutter-desktop-control-ui
  • 요약: iop-agent가 소유·실행하고 local proto-socket으로 연결하는 Flutter subprocess에서 공통/로컬 설정, project registry, 실행 상태·오류·로그를 제공하는 전체 설정·운영 UI를 스케치한다.

• [스케치] Unity 3D Desktop Character

  • 경로: unity-3d-desktop-character
  • 요약: iop-agent가 소유·실행하고 local proto-socket으로 연결하는 Unity subprocess에서 작업 상태를 3D 캐릭터로 표현하며, 간단한 메뉴에서 상세 Flutter UI 표시를 요청하는 macOS client를 스케치한다.

• [스케치] 에이전트 작업 루프 오케스트레이션 MVP

  • 경로: agent-workflow-loop-orchestration-mvp
  • 요약: 교체 가능한 최초 요청 라우터가 코딩·저장소 조회·일반 요청을 direct, Plan, Milestone과 lane/G0X로 분류하고, 사용자 agent의 tool call로 작업 파일을 만든 뒤 파일 상태, 하이브리드 실행과 상위 모델 리뷰를 연결하는 작업 루프를 스케치한다.

• [스케치] Provider 사용량 알림과 운영 표면

  • 경로: provider-usage-notification-operations-surface
  • 요약: 공통 runtime의 quota/status/failure event를 소비해 macOS·Desktop·후속 외부 채널에 전달하고 selection/failover를 중복하지 않는 운영 알림 표면을 스케치한다.

• [스케치] 원격 코딩/유지보수 작업 환경

  • 경로: remote-workspace-operations-environment
  • 요약: CLI Agent와 workspace-bound execution을 이용한 원격 코딩/유지보수 환경의 운영 경계를 스케치한다.

• [스케치] oto 자동화 스케줄러와 CI-CD 연동 (2차)

  • 경로: oto-automation-scheduler-second-wave
  • 요약: oto를 이용한 자동화, scheduler, CI-CD 연동은 MVP 이후 2차 후보로 스케치한다.

• [보류] 공통 Agent Task Runtime과 Desktop Agent

  • 경로: shared-agent-task-runtime-desktop-agent
  • 요약: 공통 runtime, Flutter Desktop과 배포를 결합한 기존 계획은 IOP Agent CLI와 후속 Flutter·Unity Milestone으로 분리하기 위해 보류하고 요구사항 참조로 유지한다.

• [보류] 원격 터미널/CLI 터널링 POC (2차)

  • 경로: remote-terminal-bridge-poc
  • 요약: Agent를 설치하기 어려운 host/device 또는 특정 Node의 CLI agent를 Socket 경유로 다른 원격지에 연결하는 터널링 POC는 MVP 이후 2차로 보류한다.

Phase 경계

• OpenAI-compatible API와 A2A API에 terminal 제어 기능을 억지로 싣지 않는다.
• Edge는 실행 요청의 broker 역할을 하고, Node는 대상 transport 실행자 역할을 유지한다.
• iop-agent는 Edge를 포함하거나 요구하지 않는 독립 headless CLI이며, 개인 장비의 소유 OS 사용자 범위에서 하나의 active supervisor process만 실행한다. Node와 동일한 공통 Go CLI Provider·AgentTaskManager를 host adapter로 소비하되 Node process가 두 번째 iop-agent supervisor가 되지는 않는다.
• 단일 iop-agent는 여러 등록 project를 관측하고, Flutter·Unity client를 subprocess로 시작·중단·복구하며, 같은 OS 사용자에게 제한된 local proto-socket에서 이들을 신뢰한다.
• Unity의 상세 UI 요청은 Unity가 Flutter를 직접 실행하지 않고 iop-agent가 Flutter를 표시하거나 시작하는 command로 처리한다.
• 설치 가능한 대상은 bootstrap/enrollment 경로로, 설치가 어렵거나 일회성 유지보수 대상은 remote terminal bridge 경로로 구분한다.
• OpenAI-compatible Responses 표면은 외부 모델 호출 호환을 위한 입력 표면이며, IOP 고유 운영 제어는 native protocol이나 명시 운영 API로 분리한다.
• NomadCode 지원을 위한 metadata.workspace 실행 계약은 provider 확장, Lemonade 추가, remote terminal bridge보다 먼저 닫는다.
• Agent Task runtime은 사용자 workspace의 Milestone/Plan/Review/work-log 파일을 durable source of truth로 사용한다. repo-global 설정은 비밀정보 없는 공통 기본값·정책 템플릿을 버전 관리하고 runtime은 읽기만 하며, user-local store는 장비별 project registry·override·경로와 최소 checkpoint/lease/client process 상태를 소유한다.
• 에이전트 작업 루프 오케스트레이션은 사용자가 agent-ops 스킬을 직접 실행하지 않은 일반 요청을 direct, Plan, Milestone으로 분류하고, Plan/Milestone이면 사용자 agent의 tool call로 작업 파일을 만들고 그 파일 상태를 연결하는 상위 IOP 기능으로 별도 소유한다.
• 공통 Agent Task runtime은 위 오케스트레이션과 Node/iop-agent host가 공통으로 소비하는 provider 실행·선택·관측·복구 기반이며, 최초 요청 분류와 작업 파일 생성의 의미를 대체하지 않는다.
• Python dispatcher/selector는 스킬 기반 1차 테스트를 거쳐 안정화된 동작·정책·오류 evidence의 참조로만 사용하며 production runtime에서 실행하거나 가져오지 않는다. Go parity와 cutover evidence를 확보한 뒤 IOP Agent CLI Runtime Milestone 완료 전환 시 Python 구현을 폐기한다.
• provider 실행, quota/status, stream/session, failure와 AgentTaskManager는 공통 Go package가 단일 구현으로 소유한다. Node와 iop-agent host에 이를 복사하거나 중복 선언하지 않는다. Flutter와 Unity는 후속 client이며 이 실행 로직을 소유하지 않는다.
• 새 Milestone 선택과 최초 시작은 항상 수동이며, 시작 기록이 있는 중단 작업만 기본적으로 자동 재개한다. 자동 재개 여부는 local 설정으로 조정한다.
• 사용자가 등록한 canonical workspace는 해당 폴더 범위의 agent 작업을 사전 승인한 것으로 본다. iop-agent는 dispatch 전에 workspace boundary와 provider의 unattended/approval-bypass capability를 검증하고, 충족하지 않으면 실행하지 않은 채 설정 안내 알림을 낸다.
• task dependency는 명시된 predecessor만 사용하고 숫자 순서에서 암묵 의존성을 추론하지 않는다. 서로 다른 project/workspace instance는 병렬 실행한다.
• 같은 canonical workspace의 dependency-ready 작업은 pinned base snapshot 위에 작업별 copy-on-write writable layer를 부여해 병렬 실행하고 canonical base를 직접 변경하지 않는다. 완료 작업은 immutable change set으로 동결하며 iop-agent가 결정적 순서로 하나씩 검증·통합한다.
• 충돌 없는 통합은 자동 승인하고 merge conflict, 검증 실패 또는 관리되지 않은 base drift는 해당 작업만 blocker로 남긴다. 실제 branch/index/commit 의미가 필요한 도구에는 격리된 worktree 또는 full clone을 fallback으로 사용한다.
• 선택 엔진은 하나의 provider/model을 반환하는 공통 evaluator와 host별 정책 입력을 분리하며, app 기본값 뒤 project override와 ordered rule priority를 적용한다.
• Provider 사용량 알림은 공통 runtime의 quota/status/failure event를 소비하는 운영 표면으로 두고, provider 선택·retry/failover·task continuation을 다시 구현하지 않는다.
• 원격 터미널/CLI 터널링 POC와 oto scheduler/CI-CD 연동은 현재 활성 작업에서 제외하고, provider 상태/capacity queue와 운영 관측 MVP 이후 재개 후보로 둔다.