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와 관측 동작을 축소하지 않고 흡수하며, 개인 장비의 단일 iop-agent가 여러 project와 Flutter·Unity subprocess를 소유하고 Node도 같은 공통 CLI Provider·AgentTaskManager 구현을 소비하게 한다.

상태

[계획]

승격 조건

• 보류된 공통 Agent Task Runtime과 Desktop Agent와 기존 SDD의 runtime 요구사항을 CLI 범위로 이관하고, 스킬 기반 1차 테스트를 거쳐 안정화된 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, task overlay·change-set 통합, retry·identity·checkpoint, config/proto event 계약과 실제 로그인 환경 smoke를 함께 변경한다.
• 잠금 해제 조건: 아래 체크리스트
  • SDD 잠금이 해제되어 있다.
  • D05 provider approval 기본 정책이 승인·해결되었다.
  • D06 병렬 COW Overlay와 직렬 통합이 승인·해결되었다.
  • 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와 오류 표면화
• repo-global 설정의 비밀정보 없는 provider/selection 공통 기본값·정책 템플릿과 user-local 설정의 project registry, 장비 경로, provider 실행 참조, project override, 자동 재개 및 client process 설정을 분리한다. runtime은 repo-global 설정을 쓰지 않고 local override와 checkpoint만 갱신한다.
• 사용자가 project와 Milestone을 선택해 최초 실행을 명시적으로 시작하며 ready Milestone을 자동 시작하지 않는다. 시작 기록이 있는 중단 작업만 기본 자동 재개하되 auto_resume_interrupted local 설정으로 조정한다.
• 등록 workspace 선택은 해당 canonical folder 안의 agent 작업을 사전 승인한 것으로 본다. iop-agent는 dispatch 전에 workspace grant와 provider의 unattended/approval-bypass 실행 capability를 검증하고, 불충족이면 agent를 호출하지 않고 project-local blocker와 사용자 설정 안내 알림을 낸다.
• dependency-ready는 스킬의 명시 predecessor만 따르고 숫자 순서에서 의존성을 추론하지 않는다. 서로 다른 project/workspace instance와 같은 canonical workspace의 independent sibling을 병렬 실행하되, 같은 workspace의 각 task는 pinned base snapshot 위의 독립 copy-on-write writable layer에서 실행하고 canonical base를 직접 쓰지 않는다.
• 완료 task는 immutable change set으로 동결해 결정적 순서로 canonical workspace에 하나씩 통합한다. clean three-way merge는 자동 승인하고 conflict, 검증 실패와 관리되지 않은 base drift는 task-local blocker로 보존한다. 실제 Git branch/index/commit 의미가 필요한 task만 격리 worktree 또는 full clone을 fallback으로 사용한다.
• project-owned Milestone/Plan/Code Review/USER_REVIEW/completion artifact를 해석하는 workflow adapter, provider-neutral review submission matcher와 Pi same-context evidence repair
• 장비·소유 OS 사용자 범위의 iop-agent singleton lease, workspace별 invocation 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
• iop-agent가 Flutter·Unity를 소유 subprocess로 시작·중단·복구하고, 같은 OS 사용자에게 제한된 local proto-socket으로 상태·event·control을 제공하는 경계. Unity의 상세 보기 요청은 iop-agent가 Flutter를 시작하거나 전면 표시하는 command로 중계한다. 실제 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 작업 상태를 읽고, 수동 선택·시작된 Milestone의 dependency-ready task를 격리 mode로 dispatch하며 review·직렬 통합과 후속 작업을 끝까지 진행하고 중단된 시작 기록은 설정에 따라 자동 재개한다.
• [guardrail-admission] 등록 canonical workspace의 사전 승인 범위, path containment, task별 writable-root confinement와 provider별 unattended/approval-bypass capability를 dispatch 전에 검증하고, 불충족이면 실행 없이 typed blocker·설정 안내 event를 제공한다.
• [node-consumer] Node가 공통 runtime을 소비하는 얇은 bridge로 전환되고 기존 Node 실행 계약과 provider 동작을 보존한다.

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

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

• [config-registry] repo-global read-only defaults/policy와 user-local registry/override/state의 schema·소유권·merge precedence, ordered rule array 전체 교체, isolation backend·local root·retention 설정, 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] 장비의 singleton supervisor와 workspace별 manager/base-mutation lease, checkpoint, process/session·overlay locator, integration queue/record, failure budget과 completion reconciliation이 restart·cancel·부분 실패에서도 중복 실행 없이 복구된다.

Epic: [workspace-isolation] 병렬 Overlay와 통합

같은 canonical workspace를 공유하는 작업을 파일 쓰기 단계에서 격리하고 검증된 결과만 base에 반영하는 capability를 묶는다.

• [overlay-workspace] dependency-ready task마다 tracked·untracked·dirty content를 포함한 pinned base fingerprint와 독립 writable layer, 통합 read view 및 task별 temp/cache 경로를 제공한다. unattended/bypass child도 writable root가 해당 layer로 제한되어 canonical base·공용 Git index/ref·다른 task layer를 직접 변경하지 못한다.
• [change-set-integration] 완료 overlay를 base fingerprint·file operation·write-set·검증 evidence를 가진 immutable change set으로 동결하고 dispatch ordinal에 따라 직렬 three-way 통합한다. clean 결과는 자동 승인하며 conflict·검증 실패·관리되지 않은 base drift는 원본 overlay를 보존한 task-local blocker가 되고 partial base mutation 없이 뒤의 독립 change set 통합은 계속된다.

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

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

• [cli-surface] iop-agent가 binary와 repo-global/local 설정 예시, 설정 검증, provider/project/Milestone 조회·선택·preview, serve/start/stop/resume, overlay/integration 상태와 blocker 확인을 일관된 CLI command로 제공한다.
• [project-logs] 현재 최소 관측 수준을 축소하지 않는 project-local event/log와 task별 loop·attempt·process/overlay/change-set/integration locator가 연결된 WORK_LOG timeline을 제공한다.
• [parity-cutover] Python·Node 동작을 absorb | replace | not-applicable로 분류하고 미분류 동작, Python runtime 의존성과 Node provider 중복 없이 Go runtime으로 전환한다. Python 구현은 parity와 cutover evidence를 확보할 때까지 참조 fixture로 보존하고 Milestone 완료 전환 시 폐기한다.
• [logged-smoke] 실제 로그인된 macOS CLI 환경에서 discovery, 실행, stream, quota/status, cancel, 재호출, restart와 다중 project 동작을 검증한다.

Epic: [client-control] Local Client Process와 제어

Flutter·Unity client의 process ownership과 같은 사용자 local control 경계를 묶는다.

• [local-control] 같은 OS 사용자의 후속 client가 사용할 local proto-socket의 binary 측 lifecycle, 상태, event와 control endpoint가 별도 app token 없이 OS-user 경계로 제공된다.
• [client-process-manager] 장비의 단일 iop-agent가 Flutter·Unity subprocess를 중복 없이 시작·중단·재연결하고, Unity의 상세 UI command를 Flutter start/focus로 중계하며 client 종료가 runtime 소유권을 역전시키지 않는다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 승격 조건과 구현 gate는 충족했으며 기능 Task 구현과 검증은 아직 시작 전이다.
• 검토 항목: 없음
• agent-ui 상태 반영: 해당 없음
• 리뷰 코멘트: 없음

범위 제외

• Flutter 설정·운영 UI, tray, macOS .app shell과 UI가 daemon lifecycle을 관리하는 기능
• Unity 3D Character, transparent window, animation, click-through와 Flutter package 통합
• Flutter·Unity client 구현과 화면 정의. 현재 범위는 binary 측 process ownership과 local protocol 경계 및 fixture client 검증까지만 포함한다.
• provider 로그인, credential/token 저장, 계정 전환과 billing 구매 자동화
• 실행 중 개별 action 승인 UI와 prompt. 현재 기본은 등록 workspace 범위의 전자동 approval bypass이며, workspace 밖 권한 확장과 guardrail 우회는 포함하지 않는다.
• 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
• 표준선(선택): 개인 장비의 소유 OS 사용자 범위에서 하나의 active iop-agent만 실행하고 여러 project와 Flutter·Unity subprocess를 관리한다. Flutter·Unity는 client이며 daemon이나 서로의 process를 직접 소유하지 않는다.
• 표준선(선택): repo-global 설정은 비밀정보 없는 공통 provider/default/selection policy template만 버전 관리하고 runtime은 읽기만 한다. user-local 설정·상태는 project registry, 장비 경로, provider command/env reference, project override, 자동 재개, client launch policy, checkpoint/lease를 소유하며 repo-global 뒤에 적용한다. credential은 각 provider CLI가 소유한다.
• 표준선(선택): Node와 iop-agent는 공통 provider/manager package를 소비하고 host-specific command, wire와 lifecycle adapter만 가진다.
• 표준선(선택): 스킬 기반 1차 테스트를 거쳐 안정화된 Python 작업과 이전 Milestone·SDD·실행 결과를 provider, scheduler, workflow artifact, review/finalization, process/session, quota/error, log/reconciliation parity inventory의 입력으로 사용하고 각 동작을 Go 타입과 테스트로 재구현한다.
• 표준선(선택): Python 구현은 Go parity와 cutover evidence가 확보될 때까지 behavior fixture로만 보존하며 production fallback으로 사용하지 않는다. Milestone 완료 전환 시 Python 구현을 폐기하고 남은 runtime 의존성이 없음을 검증한다.
• 표준선(선택): CLI는 모든 선언 provider를 대상으로 전체 동등성을 제공하며 지원 provider, 선택 엔진, quota, review와 복구 기능을 축소한 선행판을 두지 않는다.
• 표준선(선택): 새 Milestone 선택·최초 시작은 항상 수동이고 시작 기록이 있는 중단 작업의 자동 재개만 기본 on이다. 자동 재개 여부는 local 설정이며 사용자는 언제든 project를 중단할 수 있다.
• 표준선(선택): 스킬의 dependency grammar는 명시 predecessor만 권위로 삼고 번호 순서에서 암묵 의존성을 만들지 않는다. 스킬의 canonical-base 직접 병렬 쓰기는 Go runtime에서 replace한다. 같은 workspace의 independent sibling은 pinned base 위의 task별 COW writable layer에서 실행하고 immutable change set만 deterministic serial merge하며, worktree/full clone은 실제 Git 격리가 필요한 경우의 fallback이다.
• 표준선(선택): local proto-socket은 binary가 소유하고 같은 OS 사용자 client를 신뢰하는 경계다. Flutter와 Unity는 각자 이 경계를 소비하며 Unity의 상세 UI 요청은 iop-agent가 Flutter를 시작·표시하는 command로 중계한다.
• 표준선(선택): 완전 자동화를 기본으로 하며 등록 workspace는 그 canonical folder 범위의 agent 작업을 사용자가 사전 승인한 것으로 본다. provider authentication과 credential은 각 CLI가 소유하고, iop-agent는 workspace guardrail과 unattended/approval-bypass capability가 모두 확인된 실행만 허용한다. 미충족 provider/project는 호출하지 않고 설정 안내 알림을 낸다.
• 표준선(선택): 세부 command 이름, package/file 배치, proto field, retry backoff 수치와 log serialization은 계획·SDD·contract 단계에서 기존 구조와 표준안으로 정하며 사용자 결정 항목으로 올리지 않는다.
• 이전 설계 참조: 공통 Agent Task Runtime과 Desktop Agent와 기존 SDD. 결합된 Desktop delivery는 구현하지 않고 CLI parity 요구사항만 현재 Milestone에 이관했다.
• 큐 배치: 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 사용량 알림과 운영 표면
• 확인 필요: 없음