iop/agent-spec/runtime/iop-agent-cli-runtime.md

spec_doc_type	spec_id	status	source_evidence
spec	runtime/iop-agent-cli-runtime	구현됨	type path notes contract agent-contract/inner/iop-agent-cli-runtime.md 독립 host lifecycle, config, durable state와 local-control 경계 type path notes contract agent-contract/inner/agent-runtime.md host가 소비하는 공통 provider와 AgentTaskManager 계약 type path notes code apps/agent/internal/command/root.go headless CLI command surface type path notes code apps/agent/internal/bootstrap/module.go daemon, task loop, project log, client process와 local-control 조립 type path notes code apps/agent/internal/taskloop/module.go project lifecycle, milestone selection, preview, reconciliation과 상태 projection type path notes code apps/agent/internal/localcontrol/server.go same-OS-user Unix proto-socket server type path notes test apps/agent/cmd/agent/main_test.go headless S10 transcript와 compiled-binary lifecycle coverage type path notes test apps/agent/internal/taskloop/module_test.go fake provider persisted lifecycle, rollback과 restart coverage type path notes sdd agent-roadmap/archive/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md acceptance scenario와 evidence map type path notes complete-log agent-task/archive/2026/07/m-iop-agent-cli-runtime_1/complete.log cli-surface final PASS와 final verification evidence

스펙: IOP Agent CLI Runtime

목적

개인 장비에서 독립 실행되는 iop-agent headless host의 현재 기능을 정리한다. 이 host는 공통 provider와 AgentTaskManager를 조립해 CLI·daemon·local control 표면으로 제공하며, Node나 Python dispatcher를 대체하는 별도 shared-runtime 구현을 소유하지 않는다.

기능 목록

기능	설명
Headless CLI	validate, provider/project/milestone 조회·선택, preview, serve, start, stop, resume, status와 제한된 task-loop 명령을 text 또는 JSON으로 제공한다.
설정 조합	repo-global의 비밀정보 없는 기본값과 user-local device/project override를 엄격히 검증·합성하고, 실행은 캡처한 불변 revision을 사용한다.
수동 project lifecycle	project의 Milestone을 명시 선택한 뒤에만 시작하며, preview는 durable state나 provider invocation 없이 같은 선택·dependency 판정을 반환한다.
지속 runtime과 관측	daemon은 공통 runtime의 reconciliation을 주기적으로 수행하고 project별 work, dispatch ordinal, overlay/integration, blocker와 project log를 상태로 제공한다.
Local control과 client process	소유 OS 사용자의 local proto-socket을 통해 상태와 project/client control을 제공하고, Flutter·Unity subprocess의 시작·중단·복구와 Unity detail 요청의 Flutter start/focus 중계를 소유한다.
안전한 host 조립	bootstrap은 하나의 durable state store 위에 task runtime, project log, client process manager와 local-control server를 조립하며 시작 실패 시 이미 시작한 component를 역순 정리한다.

범위

• 포함: iop-agent CLI/daemon, repo-global·user-local runtime config 조합, project lifecycle projection, local socket, client process와 host-owned durable state.
• 제외: 공통 provider 실행·selection·retry·AgentTaskManager 알고리즘, Edge-Node protobuf 변환, Flutter·Unity UI 구현, provider 로그인과 credential 저장, active agent-task의 dispatcher/worker/review orchestration.

주요 흐름

flowchart LR
  Operator[운영자 또는 same-user client] --> CLI[iop-agent CLI]
  CLI --> Command[Command service]
  Command --> Snapshot[Validated runtime snapshot]
  Snapshot --> Runtime[taskloop.Runtime]
  Runtime --> Shared[Shared Agent Runtime]
  Shared --> State[Durable state and project logs]
  CLI -->|serve| Bootstrap[Daemon bootstrap]
  Bootstrap --> Runtime
  Bootstrap --> Socket[Local proto-socket]
  Socket --> ClientManager[Flutter/Unity process manager]

serve는 지속 reconciliation과 local control을 실행한다. 나머지 CLI command는 같은 durable state를 제한적으로 조회하거나 명시 lifecycle intent를 기록하며, preview는 side effect를 만들지 않는다.

계약

• IOP Agent CLI Runtime contract는 standalone host lifecycle, config, local control과 client process 경계를 정의한다.
• Agent Runtime contract는 host가 소비하는 공통 provider와 AgentTaskManager 의미를 정의한다.
• SDD는 S10 CLI와 관련 acceptance/evidence 연결을 정의한다.

설정/데이터/이벤트

• repo-global input은 read-only이며 provider/default/selection policy template만 포함한다. user-local input은 device root, project registration, override, client launch policy와 durable state 위치를 포함한다.
• runtime snapshot은 두 입력의 revision과 합성 결과를 보존한다. 현재 실행은 이미 캡처한 revision을 유지하고, 유효한 다음 revision만 이후 invocation에 반영한다.
• local proto-socket은 owner-only state root와 socket permissions, same-OS-user peer credential을 전제로 한다. app token fallback은 없다.
• host는 project/work 상태, local command receipt, client process identity와 project log를 durable record로 보존한다. 공통 runtime의 lifecycle, admission, review와 integration 결정은 공유 계약을 따른다.

검증

• go test -count=1 ./apps/agent/... - CLI, bootstrap, task loop, local control과 client process package가 현재 checkout에서 통과해야 한다.
• go test -count=1 -race ./apps/agent/internal/taskloop ./apps/agent/internal/command ./apps/agent/internal/bootstrap ./packages/go/agenttask ./packages/go/agentstate - shared state와 host lifecycle의 race regression을 확인한다.
• make build-agent 및 make test-iop-agent-logged-smoke-preflight - binary build와 logged-smoke harness preflight를 확인한다.

한계와 주의사항

• 실제 provider 로그인과 logged-in macOS smoke는 credential을 이 spec이나 repo-global config에 기록하지 않고 별도 환경에서 수행한다.
• iop-agent는 active agent-task의 dispatcher, worker, self-check와 official review 경로를 대체하거나 그 경로에서 실행되지 않는다.
• Flutter·Unity는 local control을 소비하는 client이며 provider 선택, task scheduling 또는 daemon ownership을 갖지 않는다.

변경 기록

• 2026-07-31: IOP Agent CLI Runtime Milestone의 종료 검토를 위해 현재 코드·계약·S10 완료 evidence를 기준으로 생성했다.