19 KiB
19 KiB
SDD: IOP Agent CLI Runtime
위치
- Milestone: IOP Agent CLI Runtime
- Phase: PHASE.md
상태
[승인됨]
SDD 잠금
- 상태: 해제
- 사용자 리뷰: 없음
- 잠금 항목: 없음
문제 / 비목표
- 문제: Agent Task 실행·관측·복구 책임이 현재 Python dispatcher를 모델이 감시하는 흐름과 Node 내부 CLI runtime에 나뉘어 있다. 이 SDD는 검증된 동작을 축소하지 않고 공통 Go runtime과 독립
iop-agentCLI로 이전하면서 Node가 같은 provider·manager 구현을 소비하는 책임, lifecycle, 상태와 evidence 경계를 고정한다. - 비목표:
- Flutter 설정 UI, tray, macOS
.appshell과 Unity 3D Character를 구현하지 않는다. - Python 코드를 production dependency로 사용하거나 진행 중 Python process state를 승계하지 않는다.
- provider 로그인, credential 저장, 사용자 승인 UI와 billing 자동화를 구현하지 않는다.
- agent-ops를 사용하지 않는 일반 요청의 direct/Plan/Milestone 분류나 합성 tool call 주입을 구현하지 않는다.
- local proto-socket의 세부 field를 SDD에 계약 원문으로 복제하지 않는다.
- Flutter 설정 UI, tray, macOS
Source of Truth
| 영역 | 기준 | 메모 |
|---|---|---|
| Roadmap | IOP Agent CLI Runtime | CLI 목표, 기능 Task, 범위와 완료 상태의 원본 |
| 이전 설계 | 공통 Agent Task Runtime과 Desktop Agent, 기존 SDD | CLI parity 요구를 이관할 참조이며 결합된 Desktop delivery는 구현 입력이 아님 |
| Node Wire | Edge-Node Runtime Wire | Node bridge가 보존해야 할 기존 RunRequest/RunEvent, cancel, command와 config 의미 |
| Config Compatibility | Edge Config Runtime Refresh | 기존 Node provider/config 의미의 호환 기준이며 iop-agent app-owned YAML 원문을 대신하지 않음 |
| Project Workflow | 등록 project의 agent-ops Milestone·Plan·Code Review·USER_REVIEW 계약과 workflow adapter | 작업 의미와 artifact contract는 project가 소유하고 runtime은 구조 판정과 실행을 소유함 |
| Project State | 각 workspace의 agent-task, agent-roadmap, WORK_LOG.md, agent-log |
작업 원문, 진행, review와 완료 evidence의 durable source of truth |
| Host State | iop-agent app-owned YAML, project registry, versioned checkpoint와 workspace lease |
provider/global 설정, project override와 최소 복구 상태의 source of truth |
| External Provider | 사용자가 YAML에 선언하고 이미 인증한 CLI provider | runtime은 discovery, status, 실행과 cancel만 수행하며 인증을 소유하지 않음 |
| User Decision | 없음 | 현재 제품·범위 결정은 모두 확정됐고 세부 command, field, backoff와 파일 배치는 표준안으로 정함 |
State Machine
| 상태 | 진입 조건 | 다음 상태 | 근거 |
|---|---|---|---|
starting |
iop-agent serve 또는 Node host가 공통 runtime을 시작했다 |
config-validating 또는 failed |
runtime build와 host identity |
config-validating |
app-owned YAML과 project override revision을 읽었다 | provider-discovering, config-error |
schema validation과 immutable config revision |
provider-discovering |
선언 provider의 binary/version/authenticated readiness/status를 조회한다 | project-watching, provider-error |
provider discovery snapshot |
project-watching |
명시 등록 workspace와 config watcher가 활성화됐다 | workspace-claiming, idle, stopped |
registry와 filesystem event |
workspace-claiming |
auto-run, manual run 또는 resume가 요청됐다 | reconciling, blocked |
canonical workspace identity, lease와 checkpoint revision |
reconciling |
lease 획득 또는 host restart 뒤 filesystem, checkpoint, process/session과 completion ledger를 대조한다 | idle, work-ready, running, blocked, failed |
execution/attempt, locator, active pair, archive와 last-writer state |
idle |
ready work가 없고 watcher가 활성 상태다 | work-ready, config-pending, stopped |
project scan과 watcher event |
work-ready |
남은 agent-task, pinned resume/selfcheck 또는 최상위 ready Milestone이 있다 | previewing, selecting, running, stopped |
dependency와 persisted route state |
previewing |
read-only preview가 요청됐다 | 영속 전이 없이 caller에 반환 | 동일 selector/dependency 판정과 no-side-effect evidence |
selecting |
새 worker stage에 config와 quota snapshot을 적용한다 | running, blocked, selection-error |
하나의 RouteDecision과 durable candidate/rule history |
running |
provider process/session이 pinned config·route로 실행 중이다 | submission-validating, review-validating, retrying, failing-over, cancelling, blocked, failed |
normalized stream, process/session locator와 typed failure |
submission-validating |
worker 또는 selfcheck가 성공 종료했다 | pinned selfcheck의 work-ready, official review의 work-ready, Pi evidence-repairing, retrying, blocked |
completing route, pair/identity와 provider-neutral artifact matcher |
evidence-repairing |
Pi selfcheck 뒤 review artifact의 worker-owned field가 미완성이고 같은 native context가 유효하다 | 같은 context의 running, official review의 work-ready, blocked, cancelling |
durable repair intent, incomplete ordinal, locator와 matcher snapshot |
review-validating |
official review process가 종료했다 | PASS의 reconciling, WARN/FAIL의 work-ready, USER_REVIEW의 blocked, retrying, failed |
exact verdict, filesystem progress, follow-up과 completion artifact |
retrying |
알려진 same-target 복구 가능 오류와 stage budget이 남았다 | bounded backoff 뒤 running, blocked, cancelling |
failure budget과 retry ordinal/deadline |
failing-over |
typed quota/context/model/stream failure와 unused eligible alternate가 있다 | fault-atomic route/context commit 뒤 running, blocked |
persisted route history, runtime quota observation과 continuation handoff |
config-pending |
실행 중 새 유효 config revision이 관측됐다 | 현재 실행 종료 뒤 work-ready 또는 idle |
실행 snapshot은 유지하고 다음 agent 호출부터 새 revision 적용 |
blocked |
invalid state, unknown error, budget 소진 또는 eligible target 부재로 work unit을 진행할 수 없다 | identity-matched resume/retry의 reconciling, 사용자 stop의 stopped |
task-local blocker와 project log |
cancelling |
사용자 또는 host가 project 실행 중단을 요청했다 | stopped, failed |
process group/session cancel evidence |
stopped |
auto-run off 또는 명시 stop이 완료됐다 | config-validating, project-watching |
사용자 재개 또는 config enable event |
failed |
unrecoverable runtime/config/provider 오류가 발생했다 | 독립 project는 계속되고 해당 project는 수정 후 reconciling |
surfaced error와 보존된 route/checkpoint |
Interface Contract
- 계약 원문:
- Node 호환 경계는 Edge-Node Runtime Wire를 유지한다.
iop-agentapp-owned YAML과 local proto-socket의 client-neutral 상태·event·control 계약은 현재agent-contract에 없으므로 구현 계획의 첫 계약 작업에서 생성한다. 계약 생성 전 proto/config 코드를 확정하지 않는다.
- 입력:
RuntimeConfig: config revision, provider catalog, global defaults, selection policy와 log/state root다.ProjectRegistration: stable registry id, canonical workspace instance, enabled/auto-run과 project override다.ProviderProfile: stable provider/model/profile id, command/env reference, execution/session/status capability와 approval bypass mapping이다.SelectionPolicy: default target과 시간, quota/token, agent/stage/lane/grade, capability, known failure 조건을 가진 ordered rule array다.WorkRequest: project/workspace, 이미 선택된 task 또는 Milestone, stage/work-unit와 dependency/persisted route identity다.PreviewRequest: 같은 판정기를 side effect 없이 실행할 project/workspace와 optional work identity다.ProjectWorkflowAdapter: project-owned artifact contract를 normalized active pair, submission completeness, review verdict, USER_REVIEW blocker와 completion state로 반환한다.
- 출력:
RouteDecision: 외부에 노출할 provider/model 하나와 내부에 저장할 ordered candidate, rule/reason, eligibility/rejection와 used history다.RuntimeEvent: execution/attempt, project/work-unit/stage, lifecycle, stream/heartbeat, config/quota reference와 terminal result다.ProviderStatus: official provider/model/profile id, readiness, capability, quota/status와 오류 근거다.PreviewResult: 실행과 같은 selection/dependency/blocker 판단 및 no-side-effect 증명이다.ProjectLogRecord: route, quota, process/session locator, task별 loop/attempt, failure/retry/failover/review/completion을 연결한다.
- 금지:
- Node와
iop-agenthost에 provider 또는 AgentTaskManager 구현을 복사하지 않는다. - Python process, function name, marker와 persisted key를 production 계약으로 가져오지 않는다.
- malformed checkpoint/route/locator를 빈 상태나 현재 정책으로 조용히 초기화·재선택하지 않는다.
- Flutter·Unity가 provider 선택, task scheduling, retry/failover 또는 project state를 다시 소유하지 않는다.
- worker exit code나 완료 문구만으로 review-ready/completed를 확정하지 않는다.
- runtime
WORK_LOG/heartbeat 변화만 review progress로 세지 않는다.
- Node와
Acceptance Scenarios
| ID | Milestone Task | Given | When | Then |
|---|---|---|---|---|
| S01 | common-runtime |
Node와 iop-agent가 같은 provider profile을 선언했다 |
run, stream, resume와 cancel을 각각 수행한다 | 두 host가 같은 common implementation과 lifecycle/failure 의미를 사용하고 중복 구현이 없다 |
| S02 | provider-catalog |
provider가 설치·인증됨, 미설치, 미인증 또는 model 미지원 상태다 | discovery와 status를 실행한다 | 공식 provider/model/profile 이름으로 readiness가 반환되고 실행 불가 상태는 구체적인 오류가 된다 |
| S03 | task-manager |
등록 project에 남은 task와 ready Milestone이 있다 | supervisor 모델 없이 auto-run한다 | 남은 task를 먼저 처리한 뒤 priority queue의 ready Milestone을 순차 실행하고 독립 project는 병렬 진행한다 |
| S04 | node-consumer |
기존 Node run/session/status 요청과 config fixture가 있다 | Node를 common runtime bridge로 전환한다 | 기존 Edge-Node wire 의미와 provider behavior가 보존되고 Node 내부 duplicate provider가 없다 |
| S05 | config-registry |
defaults와 project override, 겹치는 ordered rules 및 실행 중 revision 변경이 있다 | config를 load/watch한다 | override와 array 전체 교체가 결정적으로 적용되고 현재 실행은 기존 revision, 다음 호출은 새 revision을 사용한다 |
| S06 | target-policy |
시간·quota·stage·grade 조건이 겹치고 persisted route가 있거나 손상됐다 | selection 또는 resume한다 | 첫 일치 rule의 provider/model 하나가 반환되고 판단 이력이 저장되며 손상 상태는 silent reselection 없이 오류가 된다 |
| S07 | quota-failure |
provider별 available/exhausted/unknown/not-applicable와 runtime quota error가 있다 | admission, 실행 실패와 failover를 처리한다 | typed evidence와 immutable snapshot이 격리되고 알려진 정책 안에서만 retry/failover하며 unknown은 work-unit blocker가 된다 |
| S08 | workflow-evidence |
worker/selfcheck/review artifact에 완성, placeholder, identity mismatch와 Pi selfcheck 후 미완성이 있다 | submission/review gate를 평가한다 | 모든 provider에 같은 matcher가 적용되고 Pi만 같은 native context repair 후 재검증하며 통과 전 official review는 호출되지 않는다 |
| S09 | state-recovery |
duplicate manager, restart, live child, corrupt checkpoint, partial archive와 failure budget이 있다 | lease 획득과 reconciliation을 수행한다 | invocation owner는 하나이고 valid live work를 중복 실행하지 않으며 불명확 상태는 추정 복구 없이 blocker/error가 된다 |
| S10 | cli-surface |
binary와 YAML만 설치된 로그인 macOS 환경이다 | validate, list, preview, serve, stop/resume와 status command를 사용한다 | UI 없이 설정·실행·제어·관측 가능하고 기본 auto-run과 명시 stop이 일관되게 동작한다 |
| S11 | local-control |
둘 이상의 후속 client가 같은 iop-agent 상태를 소비할 수 있다 |
local control contract를 생성하고 server-side endpoint를 검증한다 | client-neutral protobuf 상태·event·control 의미가 고정되고 UI/runtime 책임이 분리된다 |
| S12 | project-logs |
같은 task의 pair loop 11 retry/follow-up과 다른 task의 병렬 loop, 독립 work-log archive ordinal이 있다 | START/FINISH와 completion archive를 기록·복구한다 | task별 loop/attempt/locator가 안정되고 terminal closure 뒤에만 exactly-once archive와 cleanup이 수행된다 |
| S13 | parity-cutover |
기존 combined SDD, Python/Node behavior와 완료된 selector evidence가 있다 | 각 동작을 absorb/replace/not-applicable로 분류한다 | 미분류 동작과 Python runtime 의존성, 정적 route/cap 문구 및 Node duplicate implementation이 남지 않는다 |
| S14 | logged-smoke |
실제 로그인된 provider와 둘 이상의 등록 project/clone workspace가 있다 | discovery부터 실행, quota, cancel, 재호출, restart와 completion까지 수행한다 | credential을 기록하지 않고 project별 로그와 E2E evidence가 남으며 한 project 오류가 다른 project를 멈추지 않는다 |
Evidence Map
| Scenario | Required Evidence | agent-task 연결 |
완료 Evidence 기대 |
|---|---|---|---|
| S01 | common provider conformance와 duplicate implementation search | agent-task/m-iop-agent-cli-runtime/... |
common-runtime Roadmap Completion과 Node/CLI test output |
| S02 | provider discovery/status table test와 authenticated smoke | agent-task/m-iop-agent-cli-runtime/... |
provider-catalog Roadmap Completion과 readiness/error evidence |
| S03 | deterministic multi-project scheduler integration test | agent-task/m-iop-agent-cli-runtime/... |
task-manager Roadmap Completion과 no-supervisor trace |
| S04 | Node wire/config compatibility suite | agent-task/m-iop-agent-cli-runtime/... |
node-consumer Roadmap Completion과 기존 contract conformance evidence |
| S05 | config merge, invalid config, watcher와 revision integration test | agent-task/m-iop-agent-cli-runtime/... |
config-registry Roadmap Completion과 revision A/B trace |
| S06 | ordered selector, persisted route와 tamper matrix | agent-task/m-iop-agent-cli-runtime/... |
target-policy Roadmap Completion과 selected rule/reason/history evidence |
| S07 | quota parser, runtime observation, isolation과 failover test | agent-task/m-iop-agent-cli-runtime/... |
quota-failure Roadmap Completion과 snapshot/failure transition evidence |
| S08 | provider-neutral matcher와 Pi same-context repair matrix | agent-task/m-iop-agent-cli-runtime/... |
workflow-evidence Roadmap Completion과 review invocation/locator evidence |
| S09 | lease, process identity, checkpoint, restart와 archive fault matrix | agent-task/m-iop-agent-cli-runtime/... |
state-recovery Roadmap Completion과 no-duplicate/exact-state evidence |
| S10 | binary/YAML CLI command integration test | agent-task/m-iop-agent-cli-runtime/... |
cli-surface Roadmap Completion과 headless operation transcript |
| S11 | 신규 local control agent-contract와 proto-socket server contract test | agent-task/m-iop-agent-cli-runtime/... |
local-control Roadmap Completion, contract link와 event/control trace |
| S12 | WORK_LOG loop/attempt/locator, dynamic frontier와 archive reconciliation fixture | agent-task/m-iop-agent-cli-runtime/... |
project-logs Roadmap Completion과 exactly-once archive evidence |
| S13 | disposition-complete parity matrix, stale dependency와 duplicate search | agent-task/m-iop-agent-cli-runtime/... |
parity-cutover Roadmap Completion과 zero-unclassified/zero-match evidence |
| S14 | actual logged-in macOS multi-project field smoke manifest | agent-task/m-iop-agent-cli-runtime/... |
logged-smoke Roadmap Completion과 redacted environment/result manifest |
Cross-repo Dependencies
- 없음. 같은 IOP monorepo 안에서 공통 package, Node bridge,
iop-agentbinary와 protocol source를 관리한다. - 구현 순서 선행 조건은 Agent Task 동적 실행 Target Selector, Pi CLI Provider Integration, CLI Agent Group Grade Routing의 결과다.
Drift Check
- Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- Evidence Map이 code-review/complete.log에서 검증 가능하다.
- agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
- 사용자 리뷰가 필요한 항목은 없으며
USER_REVIEW.md를 만들지 않았다.
사용자 리뷰 이력
- 없음
작업 컨텍스트
- 표준선:
iop-agent는 headless runtime·CLI와 app-owned YAML/project registry/checkpoint의 관리 주체이고 workspace는 project 작업 파일의 source of truth다. - 표준선: 자동 실행과 provider approval bypass는 기본 on이며 사용자는 언제든 project를 stop할 수 있다. provider authentication과 credential은 각 CLI가 소유한다.
- 표준선: Node와
iop-agent는 공통 provider/manager package를 소비하고 host-specific wire, command와 lifecycle adapter만 가진다. - 표준선: Python과 기존 SDD는 behavior fixture다. 계획 승격 시 provider, scheduler, workflow artifact, review/finalization, process/session, quota/error, log/reconciliation 전 영역을
absorb | replace | not-applicable로 분류하며 production dependency로 남기지 않는다. - 표준선: local proto-socket은 binary가 소유하는 client-neutral 경계다. Flutter와 Unity는 서로 통신하지 않고 후속 Milestone에서 각자 이 계약을 소비한다.
- 표준선: command 이름, package/file 배치, proto field, retry backoff 수치와 log serialization은 기존 구조와 표준안으로 정하고 사용자 결정으로 올리지 않는다.
- 후속 SDD: Flutter Desktop 설정·운영 UI와 Unity 3D Character Milestone을 만들 때 각각 필요 여부를 판정한다.