iop/agent-roadmap/phase/automation-runtime-bridge/milestones/agent-workflow-loop-orchestration-mvp.md

# Milestone: 에이전트 작업 루프 오케스트레이션 MVP

## 위치

- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
- Phase: [PHASE.md](../PHASE.md)

## 목표

사용자는 일반적인 바이브코딩처럼 한 번 요청하고, IOP는 코딩·저장소 조회·일반 질의를 direct, Plan, Milestone 단위로 분류해 필요한 작업 파일 생성, 실행 모델 라우팅, 상위 모델 리뷰, 후속 작업 연결을 자동으로 반복하는 방향을 스케치한다.
MVP는 사용자 로컬 workspace를 작업 상태의 원본으로 유지하고, 지원 대상을 좁힌 agent-family protocol과 event-aware passthrough를 이용해 한 사이클이 완료될 때까지 이어지는 구조를 검증한다. 최초 요청 판정은 교체 가능한 독립 라우팅 모듈로 분리하고 초기에는 상위 cloud 모델을 사용하되, 구체적인 판단 계약과 구현 방식은 이 Milestone을 계획으로 승격할 때 재설계한다.

## 상태

[스케치]

## 승격 조건

- [ ] direct, Plan, Milestone 분류부터 완료 알림까지 한 사이클의 상태와 종료 조건을 확정한다.
- [ ] 최초 지원할 agent family와 각 family의 stream, tool call, tool result, continuation capability 경계를 정한다.
- [ ] 로컬 workspace 파일 상태와 IOP가 보유할 최소 in-flight 상태의 책임 경계를 확정한다.
- [ ] terminal event 대체와 합성 tool call을 포함한 event-aware passthrough의 protocol별 동작과 실패 경계를 정한다.
- [ ] Plan/Milestone 작업의 실행 모델 라우팅, 상위 모델 리뷰, 보완 반복의 횟수·비용·중단 기준을 정한다.
- [ ] 최초 요청 라우터와 orchestration, agent-family codec, provider dispatch의 책임 경계를 정하고 라우팅 결과의 최소 의미 계약을 결정한다.
- [ ] direct 요청에서 local 실행 가능 시 저비용 local target을 우선하고, cloud 간 위임에서는 추가 hop의 비용·지연과 절감 효과를 비교하는 기준을 결정한다.
- [ ] MVP 한 사이클과 후속 재개/복구 Milestone의 범위를 분리한다.
- [ ] API/stream/tool/lifecycle 계약 구현으로 승격할 때 SDD와 후속 구현 Milestone 구성을 확정한다.

## 구현 잠금

- 상태: 잠금
- SDD: 불필요
- SDD 문서: 없음
- SDD 사유: 현재 Milestone은 작업 루프의 제품·런타임 방향을 정리하는 스케치이며, API/stream/tool/lifecycle 계약을 구현 가능한 계획으로 승격할 때 SDD를 작성한다.
- 잠금 해제 조건: 아래 체크리스트
  - [ ] 승격 조건의 미정 항목이 사용자 검토로 해소되어 있다.
  - [ ] 구현 가능한 MVP 범위와 후속 Milestone이 분리되어 있다.
- 결정 필요: 아래 체크리스트
  - [ ] MVP에서 우선 지원할 agent family 조합과 protocol capability 기준을 결정한다.
  - [ ] 사용자에게 그대로 노출할 중간 stream과 IOP가 교체할 terminal tail의 경계를 결정한다.
  - [ ] direct 요청에서 local capability가 충족되면 local target을 우선하고, local 실행이 불가능한 경우 상위 cloud 모델의 같은 호출 응답과 저비용 cloud target 위임을 나누는 조건을 결정한다.
  - [ ] 라우팅 모듈이 반환할 분류, lane, grade, capability, confidence/abstain 의미와 invalid/low-confidence fallback 경계를 결정한다.
  - [ ] 자동 리뷰·보완 반복의 최대 횟수, 비용 예산, 사용자 중단 조건을 결정한다.
  - [ ] 완료 알림과 실패·부분 완료 상태를 사용자에게 표현하는 최소 UX를 결정한다.

## 범위

- orchestration, agent-family codec, provider dispatch와 분리된 교체 가능한 진입 라우팅 모듈의 컨셉. 초기 구현은 성능이 좋은 cloud 모델을 사용하되 구체 계약과 내부 설계는 계획 승격 시 재검토한다.
- 최초 요청을 direct, Plan, Milestone으로 분류하고, 동시에 local/cloud lane, G0X grade, 필요한 capability와 위임 여부를 판정하는 방향
- 작은 direct 작업은 Milestone/Plan 생성 없이 실행하되 local 모델이 처리 가능하면 저비용 local target으로 보내고, cloud 간 위임은 추가 hop의 비용·지연보다 절감 이득이 있을 때 선택하는 fast path
- 코딩 작업뿐 아니라 저장소 단순 조회, 일반 지식 응답, web/tool capability가 필요한 요청을 direct 후보로 다루는 방향
- Plan/Milestone 작업은 IOP가 사용자 로컬 경로를 포함한 지시를 주입하고, 모델 stream과 write/edit tool call을 로컬 agent에 전달해 작업 파일을 로컬 workspace에 생성하는 경로
- [Stream Evidence Gate Core](../../knowledge-tool-optimization-extension/milestones/stream-evidence-gate-core.md)의 normalized event/release contract를 소비해 확정된 선행 stream은 지연 없이 전달하고 판정이 필요한 bounded tail만 보류한 뒤, 정상 terminal event를 억제하고 로컬 파일 read tool call로 대체할 수 있는 event-aware passthrough
- tool result가 새 HTTP 요청으로 돌아오더라도 같은 logical workflow/session으로 이어지는 continuation 경계
- `agent-task/m-*`, 순번 task directory, `PLAN-{lane}-GNN.md`, archive 이동을 이용한 filesystem-backed 작업 상태 판독
- IOP가 보유하는 session/call id 매핑과 active provider call 같은 최소 in-flight 상태
- Plan에 기록된 lane/grade에 따른 하이브리드 실행 라우팅과 상위 모델의 독립 리뷰, 보완 작업 재라우팅
- 모든 task가 닫히면 Milestone 완료와 사용자 complete/알림으로 끝나는 단일 작업 사이클
- Claude, Codex, Pi, OpenCode 같은 대중적 agent 후보를 제품명이 아니라 stream/tool/continuation capability family별 codec으로 지원하는 방향

## 기능

### Epic: [entry-route] 요청 분류와 Fast Path

사용자가 orchestration 지식을 몰라도 요청 규모와 실행 경로를 자동으로 선택하는 진입 capability를 묶는다.

- [ ] [router-boundary] 최초 요청 라우터가 orchestration, agent-family codec, provider dispatch와 분리된 교체 가능한 모듈이며 초기 cloud 구현과 후속 local 구현이 같은 의미 계약을 사용할 수 있는 방향이 정리되어 있다.
- [ ] [request-triage] 상위 cloud 라우터가 코딩·저장소 조회·일반 요청을 direct, Plan, Milestone으로 분류하고 lane, grade, 필요한 capability, confidence/abstain을 함께 판정하는 컨셉이 정리되어 있다.
- [ ] [direct-fastpath] direct는 작업 파일을 만들지 않는 실행 방식으로 정의하고, local 실행 가능 시 저비용 local target을 우선하며 cloud 간 위임은 추가 hop의 비용·지연과 절감 효과를 비교하는 방향이 정리되어 있다.
- [ ] [route-fallback] capability·privacy·tool·schema·context 제약과 invalid/low-confidence 판정을 안전하게 처리하고 상위 cloud 라우터로 fallback할 수 있는 방향이 정리되어 있다.
- [ ] [work-decompose] Plan과 Milestone 요청은 로컬 작업 파일을 기준으로 task를 순차 실행할 수 있게 분해되는 구조가 정리되어 있다.

### Epic: [agent-bridge] Agent Bridge와 Stream Hook

로컬 agent가 파일과 tool 실행 주체로 남으면서 IOP가 다음 작업을 연결할 수 있는 통신 경계를 묶는다.

- [ ] [family-codec] 지원 agent를 stream terminal, tool call/result, continuation capability family로 묶고 공통 workflow와 분리하는 경계가 정리되어 있다.
- [ ] [terminal-hook] `workflow_terminal_hook`이 [Stream Evidence Gate Core](../../knowledge-tool-optimization-extension/milestones/stream-evidence-gate-core.md)의 `Filter`/normalized event/`FilterObservation` contract를 소비해 다른 활성 filter와 동일 terminal batch에서 병렬 평가되고 replacement decision과 sanitized reason만 반환하도록 정리되어 있다. 이미 보낸 content는 보존하고 terminal이 commit되기 전에만 protocol-safe replacement를 append하며, all-complete Arbiter, response staging/commit과 dispatch를 재구현하지 않는다.
- [ ] [workspace-state] 로컬 workspace 파일이 durable source of truth가 되고 IOP는 최소 in-flight 상태만 보유하는 책임 경계가 정리되어 있다.

### Epic: [review-loop] 라우팅·리뷰·완료 루프

작은 모델과 로컬 모델의 실행 비용 이점을 유지하면서 상위 모델 리뷰로 품질을 닫는 capability를 묶는다.

- [ ] [task-route] Plan의 lane/grade와 agent capability에 따라 cloud/local 실행 후보로 task를 라우팅하는 구조가 정리되어 있다.
- [ ] [frontier-review] 구현 agent의 자가 검증이 아니라 독립된 상위 모델 리뷰가 통과·보완·중단을 판정하는 구조가 정리되어 있다.
- [ ] [cycle-complete] 한 사이클에서 모든 task와 Milestone 종료를 판정하고 사용자에게 complete와 알림을 보내는 구조가 정리되어 있다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 방향성 스케치이며 승격 조건과 기능 경계가 아직 확정되지 않았다.
- 검토 항목: 없음
- agent-ui 상태 반영: 해당 없음
- 리뷰 코멘트: 없음

## 범위 제외

- 중단 후 자동 재개, filesystem 정합성 복구, local model 기반 continuation point 판정
- 동시에 같은 작업을 실행하는 사용자 요청의 중복 방지, distributed lock, lease, idempotent replay
- 모든 agent와 모든 provider protocol을 MVP에서 한 번에 지원하는 작업
- Milestone/Plan/Review 파일 원문과 전체 stream history를 IOP 중앙 저장소에 영구 캐시하는 구조
- 누적 message, tool 결과, 검색/RAG 자료의 선택·정렬·압축과 target별 context package 최적화
- 장기 기억, RAG, 자동 policy self-mutation, 학습 기반 route threshold 자동 승격
- 라우터 teaching, shadow/canary, offline replay, 증류·튜닝과 특정 local model에 종속된 판단 구현
- weighted scorer 세부식, 분석기 조합, 모델별 threshold와 provider별 실행 정책의 조기 확정
- 세부 API field, event schema, 파일 위치, 패키지 구조의 구현 확정

## 작업 컨텍스트

- 관련 경로: `apps/edge/internal/openai`, `apps/edge/internal/service`, `apps/node/internal/runtime`, `apps/node/internal/adapters/cli`, `agent-task`
- 표준선(선택): workflow 의미와 다음 단계 replacement directive는 orchestration filter가 소유한다. Core는 bounded tail, terminal batch의 all-complete evaluation과 `stream_open` 뒤 기존 content를 되돌리지 않는 pre-terminal replacement 적용을 담당하며 terminal commit 뒤 replacement는 거부한다. 외부 caller는 replacement를 지정하지 않는다.
- 표준선(선택): durable workflow 상태는 사용자 로컬 workspace 파일에 두고, IOP는 재구성 가능한 내용을 별도 workflow DB나 파일 캐시로 복제하지 않는다.
- 표준선(선택): SSE 연결 하나를 양방향 세션으로 가정하지 않는다. tool result는 새 HTTP 요청으로 돌아올 수 있으며 logical workflow/session identity로 연결한다.
- 표준선(선택): direct는 상위 모델 직접 실행을 뜻하지 않는다. local capability가 충족되면 저비용 local 실행을 우선하고, cloud 간 위임만 추가 hop의 비용·지연을 비교한다.
- 표준선(선택): 라우팅 모듈은 계획 승격 시 재설계하며, 현재 스케치에서는 교체 가능 경계와 분류·lane·grade·capability·confidence/abstain 의미만 후보로 둔다.
- 표준선(선택): 생성된 Plan의 lane/grade는 다시 추론하지 않고 실행 라우팅 입력으로 소비하며, route outcome 관측은 별도 Usage Ledger가 소비할 수 있는 접점까지만 둔다.
- 큐 배치: [CLI Agent Group Grade Routing](cli-agent-group-grade-routing.md) 뒤, [CLI Agent 사용량 알림과 자동 이어받기 MVP](cli-agent-usage-notification-continuation.md) 앞
- 선행 작업: [CLI Agent Group Grade Routing](cli-agent-group-grade-routing.md), [Stream Evidence Gate Core](../../knowledge-tool-optimization-extension/milestones/stream-evidence-gate-core.md), [OpenAI-compatible 출력 검증 필터](../../knowledge-tool-optimization-extension/milestones/openai-compatible-output-validation-filters.md)
- 후속 작업: 중단 후 재개와 filesystem 정합성 복구, agent family 확대, 운영 관측과 비용 예산 정책
- 확인 필요: `구현 잠금 > 결정 필요`와 승격 조건