iop/agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md

Milestone: IOP Agent CLI Runtime

위치

• Roadmap: ROADMAP.md
• Phase: PHASE.md

목표

모델이 감시하던 Agent Task 실행 루프를 프로덕션 Go runtime과 독립 실행 가능한 iop-agent CLI로 이전한다. 현재 Python dispatcher와 Node CLI runtime에서 검증된 provider 실행, 선택, quota, 오류, 복구, review와 관측 동작을 축소하지 않고 흡수하며, Node도 같은 공통 CLI Provider·AgentTaskManager 구현을 소비하게 한다.

상태

[스케치]

승격 조건

• 보류된 공통 Agent Task Runtime과 Desktop Agent와 기존 SDD의 runtime 요구사항을 CLI 범위로 이관하고 Python·Node 참조 동작의 parity inventory를 고정한다.
• 공통 runtime lifecycle, YAML config, checkpoint, provider process와 binary 측 local proto-socket 경계를 SDD에 고정하고 필요한 agent-contract 작성 범위를 확정했다.
• 기능 Task와 Acceptance Scenario·Evidence Map을 연결했다.
• Flutter Desktop Control UI와 Unity 3D Desktop Character를 각각 후속 Milestone으로 분리하고 현재 범위에서 client UI 구현을 제외했다.

구현 잠금

• 상태: 잠금
• SDD: 필요
• SDD 문서: SDD.md
• SDD 사유: 공통 runtime/Node host 경계, lifecycle, retry·identity·checkpoint, config/proto event 계약과 실제 로그인 환경 smoke를 함께 변경한다.
• 잠금 해제 조건: 아래 체크리스트
  • SDD 잠금이 해제되어 있다.
  • SDD 사용자 리뷰가 없거나 승인·해결되었다.
  • Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
  • Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
  • 나머지 승격 조건을 충족해 [계획]으로 전환되어 있다.
• 결정 필요: 없음

범위

• packages/go의 공통 CLI Provider·AgentTaskManager와 이를 실행하는 독립 iop-agent binary/CLI
• Node 내부 CLI provider를 공통 모듈 소비 방식으로 전환하고 Node·iop-agent에 provider나 manager 구현을 중복하지 않는 경계
• 선언된 provider와 provider/model/profile 공식 이름, one-shot/persistent 실행, stream/session/resume, quota/status, cancel, retry/failover와 오류 표면화
• app-owned YAML의 provider/global 설정, 명시 등록 project와 project override, ordered selection rule, file watcher와 다음 agent 호출부터의 revision 적용
• 자동 실행은 기본 on이고 사용자가 언제든 중단할 수 있다. 등록 project별 남은 agent-task를 우선 실행한 뒤 priority-queue.md의 최상위 ready Milestone을 순차 실행하며, 서로 다른 project와 clone/worktree/branch workspace instance는 병렬 실행한다.
• project-owned Milestone/Plan/Code Review/USER_REVIEW/completion artifact를 해석하는 workflow adapter, provider-neutral review submission matcher와 Pi same-context evidence repair
• workspace lease, durable route/checkpoint, process/session locator, failure budget, restart reconciliation과 task-local blocker
• project-local agent-log와 runtime-owned WORK_LOG.md의 task별 pinned loop, attempt, locator 및 exactly-once archive reconciliation
• 향후 Flutter·Unity client가 같은 binary를 제어할 수 있도록 iop-agent가 제공할 local proto-socket의 server-side 상태·event·control 경계. 실제 protocol 원문은 계획 승격 시 agent-contract로 고정한다.

기능

Epic: [runtime-core] 공통 Provider와 AgentTaskManager

Node와 독립 CLI가 같은 실행 구현을 소비하는 runtime capability를 묶는다.

• [common-runtime] CLI Provider, emitter/stream/session, quota/status, failure codec과 AgentTaskManager가 공통 Go package의 단일 구현으로 제공된다.
• [provider-catalog] YAML에 선언된 지원 provider/model/profile을 discovery하고 이미 인증된 실행 환경에서 run, resume, cancel과 status를 수행한다.
• [task-manager] AgentTaskManager가 모델 감시 없이 project 작업 상태를 읽고 dependency-ready task, review, 후속 작업과 Milestone을 끝까지 진행한다.
• [node-consumer] Node가 공통 runtime을 소비하는 얇은 bridge로 전환되고 기존 Node 실행 계약과 provider 동작을 보존한다.

Epic: [policy-state] 선택 정책과 내구 상태

여러 project와 provider를 무인 실행하면서 선택·복구 결과를 재현할 수 있는 상태를 묶는다.

• [config-registry] app-owned YAML defaults와 project override, ordered rule array 전체 교체, file watcher와 immutable execution revision 경계가 제공된다.
• [target-policy] 공통 evaluator가 host/project 정책을 주입받아 조건과 배열 순서에 따라 provider/model 하나를 반환하고 durable route plan에 판단 근거와 후보 이력을 보존한다.
• [quota-failure] provider별 quota/status와 알려진 오류를 typed result로 정규화하고 선언 정책 안에서만 retry/failover하며 unknown 오류는 해당 work unit에 표면화한다.
• [workflow-evidence] 모든 provider/model/execution class에 같은 artifact matcher와 review gate를 적용하고 Pi의 selfcheck 후 미작성 review artifact는 같은 native context에서 보완한다.
• [state-recovery] workspace 단일 manager lease, checkpoint, process/session locator, failure budget과 completion reconciliation이 restart·cancel·부분 실패에서도 중복 실행 없이 복구된다.

Epic: [cli-delivery] Headless CLI와 운영 검증

UI 없이도 설치·설정·실행·관측 가능한 제품 표면을 묶는다.

• [cli-surface] iop-agent가 binary와 기본 YAML 배포물, YAML 검증, provider/project 조회, preview, serve/auto-run, stop/resume와 상태 확인을 일관된 CLI command로 제공한다.
• [local-control] 후속 client가 사용할 local proto-socket의 binary 측 lifecycle, 상태, event와 control endpoint가 UI 구현과 분리된 경계로 제공된다.
• [project-logs] 현재 최소 관측 수준을 축소하지 않는 project-local event/log와 task별 loop·attempt·locator가 연결된 WORK_LOG timeline을 제공한다.
• [parity-cutover] Python·Node 동작을 absorb | replace | not-applicable로 분류하고 미분류 동작, Python runtime 의존성과 Node provider 중복 없이 Go runtime으로 전환한다.
• [logged-smoke] 실제 로그인된 macOS CLI 환경에서 discovery, 실행, stream, quota/status, cancel, 재호출, restart와 다중 project 동작을 검증한다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 최초 CLI 범위 스케치이며 승격 조건과 구현 gate가 아직 남아 있다.
• 검토 항목: 없음
• agent-ui 상태 반영: 해당 없음
• 리뷰 코멘트: 없음

범위 제외

• Flutter 설정·운영 UI, tray, macOS .app shell과 UI가 binary lifecycle을 관리하는 기능
• Unity 3D Character, transparent window, animation, click-through와 Flutter package 통합
• Flutter·Unity client 구현과 화면 정의. 현재 범위는 binary 측 local protocol 경계까지만 포함한다.
• provider 로그인, credential/token 저장, 계정 전환과 billing 구매 자동화
• 사용자 승인 prompt와 interactive approval gate. 현재 기본은 provider별 approval bypass다.
• agent-ops를 사용하지 않는 일반 요청의 direct/Plan/Milestone 분류와 합성 tool call 주입. 이는 에이전트 작업 루프 오케스트레이션 MVP의 범위다.
• Edge, Control Plane, remote terminal tunnel, 외부 알림/dashboard, oto scheduler/CI-CD와 Windows/Linux desktop packaging
• Python 코드를 production에서 import·실행·번역 호출하거나 진행 중 Python process 상태를 승계하는 방식

작업 컨텍스트

• 관련 경로: packages/go, apps/node, proto/iop, agent-task, agent-roadmap
• 표준선(선택): iop-agent는 headless runtime과 CLI entry이며 설정·project registry·최소 checkpoint의 관리 주체다. workspace는 작업 파일의 source of truth이지 runtime 설정 소유자가 아니다.
• 표준선(선택): Node와 iop-agent는 공통 provider/manager package를 소비하고 host-specific command, wire와 lifecycle adapter만 가진다.
• 표준선(선택): Python은 정책·오류·관측 behavior fixture로만 사용하고 Go 타입과 테스트로 재구현한다. Python에 없는 선택 엔진은 완료된 selector와 group routing Milestone 요구사항을 기준으로 작성한다.
• 표준선(선택): CLI는 모든 선언 provider를 대상으로 전체 동등성을 제공하며 지원 provider, 선택 엔진, quota, review와 복구 기능을 축소한 선행판을 두지 않는다.
• 표준선(선택): local proto-socket은 binary가 소유하는 client-neutral 경계다. Flutter와 Unity는 후속 Milestone에서 서로 통신하지 않고 각자 이 경계를 소비한다.
• 표준선(선택): 자동 실행과 provider approval bypass는 기본 on이며 사용자는 언제든 project를 중단할 수 있다. provider authentication과 credential은 각 CLI가 소유하고 iop-agent는 이미 인증된 실행만 사용한다.
• 표준선(선택): 세부 command 이름, package/file 배치, proto field, retry backoff 수치와 log serialization은 계획·SDD·contract 단계에서 기존 구조와 표준안으로 정하며 사용자 결정 항목으로 올리지 않는다.
• 이전 설계 참조: 공통 Agent Task Runtime과 Desktop Agent와 기존 SDD. 결합된 Desktop delivery는 구현하지 않고 CLI parity 요구사항만 계획 승격 시 이관한다.
• 큐 배치: Stream Evidence Gate Core 뒤, Flutter Desktop Control UI 앞
• 선행 작업: Stream Evidence Gate Core, Agent Task 동적 실행 Target Selector
• 참조·연결 작업: Pi CLI Provider Integration, CLI Agent Group Grade Routing
• 후속 작업: Flutter Desktop Control UI, Unity 3D Desktop Character, 에이전트 작업 루프 오케스트레이션 MVP, Provider 사용량 알림과 운영 표면
• 확인 필요: 없음