toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: node provider milestone and SDD docs add

Browse source
This commit is contained in:
toki 2026-06-29 15:21:33 +09:00
parent e30fb2494e
commit 55987c8e59
3 changed files with 196 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
agent-roadmap/phase/operational-observability-provider-management/PHASE.md
View file

@ -24,6 +24,10 @@ provider 확장 Phase에서 검증한 Ollama, vLLM, SGLang, Lemonade 같은 추
- 경로: `agent-roadmap/archive/phase/operational-observability-provider-management/milestones/node-resource-model-unification.md`
- 요약: Node를 Edge 연결 identity로 두고 CLI, OpenAI-compatible provider, 기타 resource를 같은 Node 아래 나열하며 provider/resource capacity만 concurrency를 소유하도록 runtime 계약과 dev-runtime 구성을 정렬했다.
- [계획] Node Provider-First Config Surface
- 경로: `agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md`
- 요약: Node 설정 표면을 `providers[]` resource list 중심으로 재정렬하고, adapter 설정은 내부 실행 IR 또는 legacy compat로 낮춰 운영자가 한 Node의 CLI/provider 자원을 한 곳에서 이해하고 관리하게 만든다.
- [스케치] 사용량, 토큰, 로그 운영 추적 MVP
- 경로: `agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md`
- 요약: 사용자 관리, token 관리, API/CLI/local inference 사용량 집계, 요청별 device/provider/time/token ledger, 로그 관리의 1차 운영 경계를 스케치한다.

77
agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md Normal file
View file

@ -0,0 +1,77 @@
# Milestone: Node Provider-First Config Surface
## 위치
- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`
## 목표
Node 설정 표면을 `providers[]` resource list 중심으로 재정렬한다.
운영자는 한 Node가 제공하는 CLI, Ollama, OpenAI-compatible, vLLM/Lemonade/SGLang 계열 resource를 `providers[]`에 나열하고, `type`과 provider별 필드만으로 실행 방식을 선언한다.
내부 adapter registry와 `adapter + target` 실행 계약은 유지하되, 사용자 config에서 `adapters`와 `providers`를 동시에 맞춰야 하는 중복 source of truth를 제거한다.
## 상태
[계획]
## 구현 잠금
- 상태: 해제
- SDD: 필요
- SDD 문서: `agent-roadmap/sdd/operational-observability-provider-management/node-provider-first-config-surface/SDD.md`
- SDD 사유: Edge config schema, provider/resource source of truth, Edge-to-Node config payload normalization, dispatch/status/config refresh, dev-runtime smoke 기준이 함께 바뀌는 설정 표면 변경이다.
- 잠금 해제 조건: 아래 체크리스트
- [x] SDD 잠금이 해제되어 있다.
- [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
- [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
- [x] Evidence Map이 완료 시 `Roadmap Completion`과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
- 결정 필요: 없음
## 범위
- `nodes[].providers[]`를 Node가 제공하는 가용 resource의 사용자-facing source of truth로 만든다.
- provider `type`별 필드로 실행 방식을 선언한다. 예: `openai_compat`/`ollama`/`cli`와 endpoint, base URL, command, args, headers, timeout, capacity, queue, model alias/served model mapping.
- loader/normalizer가 provider-first config를 내부 adapter registry와 `NodeConfigPayload`로 컴파일한다.
- 기존 `nodes[].adapters`와 기존 top-level model/provider mapping은 legacy/compat 입력 또는 optional display/policy 입력으로 낮추고, 새 문서와 예시는 provider-first를 기본으로 둔다.
- Edge provider-pool dispatch, direct CLI route, status snapshot, config refresh classification이 provider-first source of truth와 일관되게 동작한다.
- dev-runtime Mac node 예시를 `providers[]` 하나에 Codex/OpenCode CLI resource와 MLX vLLM provider resource가 함께 나열되는 형태로 정리한다.
## 기능
### Epic: [provider-first-config] Provider-First Node Config
운영자가 한 Node의 가용 실행 resource를 한 곳에서 읽고 관리하도록 config schema, runtime normalization, 검증 evidence를 정렬한다.
- [ ] [schema-source] provider-first Node config schema가 `providers[]`를 source of truth로 정의하고, `type`별 필드와 model alias/served model mapping을 한 resource 안에 표현한다. 검증: config loader/validation tests가 provider-first happy path와 invalid path를 모두 검증한다.
- [ ] [normalize-compile] provider-first config가 내부 adapter registry와 `NodeConfigPayload`로 컴파일되어 기존 Node runtime의 `adapter + target` 실행 계약을 재사용한다. 검증: mapper/config_set/router tests가 provider id를 adapter instance key로 사용할 수 있음을 확인한다.
- [ ] [legacy-compat] 기존 `nodes[].adapters` 기반 설정은 legacy/compat로 유지하되, provider-first와 충돌하면 명확한 validation error 또는 우선순위 규칙을 제공한다. 검증: legacy config와 mixed config 회귀 tests가 통과한다.
- [ ] [routing-status-refresh] Edge dispatch, status snapshot, config refresh가 provider-first source of truth를 기준으로 provider capacity, queue, health, model alias, served target을 처리한다. 검증: service/openai/status/configrefresh tests가 provider-first route와 zero/disabled provider edge case를 검증한다.
- [ ] [dev-runtime-docs] dev-runtime inventory, local/dev test rules, `configs/edge.yaml`, 운영 guide가 provider-first 예시로 정리되어 `adapters`와 `providers` 중복 작성을 기본 경로로 안내하지 않는다. 검증: `rg` stale-reference check와 config check evidence가 남아 있다.
- [ ] [full-cycle-smoke] dev-runtime provider pool에서 provider-first config로 3 connected nodes, 3 provider candidates, total capacity 10 smoke가 유지된다. 검증: config check, refresh dry-run/apply 또는 restart-required 판정, `/v1/models`, `/v1/responses`, `/v1/chat/completions` capacity smoke evidence가 남아 있다.
## 완료 리뷰
- 상태: 없음
- 요청일: 없음
- 완료 근거: 새 계획 Milestone이며 기능 Task가 아직 충족되지 않았다.
- 검토 항목: 모든 기능 Task의 `Roadmap Completion`, SDD Evidence Map, 최종 dev-runtime smoke evidence
- 리뷰 코멘트: 없음
## 범위 제외
- Node 내부 adapter abstraction 자체를 즉시 제거하는 대수술
- Control Plane을 Edge-local runtime/provider registry의 canonical store로 만드는 변경
- provider/device/model qualification report와 lifecycle 정책 구현
- billing, chargeback, 조직 IAM, 장기 audit retention
- 외부 public API endpoint 추가
## 작업 컨텍스트
- 관련 경로: `packages/go/config`, `configs/edge.yaml`, `apps/edge/internal/edgevalidate`, `apps/edge/internal/node/mapper.go`, `apps/edge/internal/service`, `apps/edge/internal/openai`, `apps/edge/internal/configrefresh`, `apps/node/internal/adapters`, `apps/node/internal/router`, `proto/iop/runtime.proto`, `agent-contract/inner/edge-config-runtime-refresh.md`, `agent-contract/inner/edge-node-runtime-wire.md`, `agent-test/dev`, `agent-test/local`, `docs/edge-local-dev-guide.md`
- 표준선(선택): 사용자-facing config는 provider/resource-first이고, 내부 adapter registry는 provider config를 컴파일한 실행 IR로 유지한다.
- 표준선(선택): `providers[].id`는 기본 internal adapter instance key가 되며, provider `type`이 내부 driver를 선택한다.
- 표준선(선택): CLI는 provider/resource로 표현하되 IOP-level concurrency 제한은 두지 않는다. provider-pool capacity는 provider별 `capacity`가 소유한다.
- 선행 작업: Node Resource Model Unification
- 후속 작업: 사용량, 토큰, 로그 운영 추적 MVP, 요청 실행 로그와 Usage Ledger 기반
- 확인 필요: 없음

115
agent-roadmap/sdd/operational-observability-provider-management/node-provider-first-config-surface/SDD.md Normal file
View file

@ -0,0 +1,115 @@
# SDD: Node Provider-First Config Surface
## 위치
- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md`
- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`
## 상태
[승인됨]
## SDD 잠금
- 상태: 해제
- 사용자 리뷰: 없음
- 잠금 항목:
- 없음
## 문제 / 비목표
- 문제: 현재 Edge config는 실행 driver 정보가 `nodes[].adapters`에, 운영 resource/catalog 정보가 `nodes[].providers[]`에, 외부 model alias mapping이 `models[]`에 나뉘어 있어 한 Node의 가용 resource를 이해하려면 여러 섹션을 왕복해야 한다. 이 SDD는 `nodes[].providers[]`를 사용자-facing source of truth로 고정하고, 내부 adapter registry는 provider config에서 컴파일되는 실행 IR로 낮추는 기준을 정한다.
- 비목표:
- Node 내부 adapter abstraction을 즉시 제거하지 않는다.
- Control Plane을 Edge-local config/provider registry의 canonical store로 만들지 않는다.
- provider/device/model qualification report와 lifecycle policy는 이번 Milestone에서 구현하지 않는다.
- billing, org IAM, 장기 audit retention, 품질 평가 기반 routing은 다루지 않는다.
- 새 public endpoint를 추가하지 않는다.
## Source of Truth
| 영역 | 기준 | 메모 |
|------|------|------|
| Roadmap | `agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md` | 목표, 기능 Task, 구현 잠금, 완료 판단 기준 |
| Contract | `agent-contract/inner/edge-config-runtime-refresh.md`, `agent-contract/inner/edge-node-runtime-wire.md` | config schema, provider/resource source of truth, Edge-to-Node payload 의미 기준 |
| Code | `packages/go/config`, `apps/edge/internal/edgevalidate`, `apps/edge/internal/node/mapper.go`, `apps/edge/internal/service`, `apps/node/internal/adapters`, `apps/node/internal/router`, `proto/iop/runtime.proto` | config load/validation, internal adapter compile, dispatch/status/runtime 실행 기준 |
| External Provider | Ollama, OpenAI-compatible providers, vLLM/MLX, Lemonade/SGLang-compatible endpoints, CLI tools | provider `type`별 실행 필드와 smoke 기준 |
| User Decision | 2026-06-29 대화 결정 | 사용자-facing Node config는 `providers[]` resource list 중심으로 정리하고, `adapters`/`providers` 중복 source of truth를 제거한다 |
## State Machine
| 상태 | 진입 조건 | 다음 상태 | 근거 |
|------|-----------|-----------|------|
| `provider-config-loaded` | `nodes[].providers[]`에 provider/resource가 선언된다 | `provider-config-validated` 또는 `config-error` | Edge config load/validate |
| `provider-config-validated` | provider id, type, model alias/served mapping, capacity/queue, type별 실행 필드가 유효하다 | `internal-adapter-compiled` | config normalization |
| `internal-adapter-compiled` | provider-first config가 `AdapterConfig`/CLI profile/internal registry item으로 변환된다 | `node-config-sent` 또는 `config-error` | Edge node mapper/config refresh |
| `node-config-sent` | Node가 provider-derived payload를 받는다 | `node-runtime-ready` 또는 `node-config-error` | Edge-Node register/refresh |
| `node-runtime-ready` | Node adapter registry가 provider-derived adapters를 등록한다 | `provider-routed` 또는 `direct-cli-routed` 또는 `status-reported` | Node router/adapter registry |
| `provider-routed` | OpenAI-compatible model alias가 provider resource 후보를 선택한다 | `run-complete` 또는 `run-error` | Edge service queue/dispatch |
| `direct-cli-routed` | CLI provider/resource가 직접 실행 route로 선택된다 | `run-complete` 또는 `run-error` | Edge service/Node CLI adapter |
| `status-reported` | Edge/Control Plane status가 Node provider/resource snapshot을 조회한다 | 없음 | Edge status provider |
## Interface Contract
- 계약 원문: `agent-contract/inner/edge-config-runtime-refresh.md`, `agent-contract/inner/edge-node-runtime-wire.md`
- 입력:
- `nodes[].providers[].id`: Node 안에서 고유한 provider/resource identity이며 기본 internal adapter instance key다.
- `nodes[].providers[].type`: 실행 driver 선택자다. MVP 후보는 `openai_compat`, `ollama`, `cli`이며 provider/runtime label은 별도 `provider` 또는 type별 필드로 표현할 수 있다.
- `nodes[].providers[].models[]`: 외부 alias와 provider served target mapping을 provider resource 안에서 표현한다.
- `nodes[].providers[].capacity`, `max_queue`, `queue_timeout_ms`, `request_timeout_ms`: provider/resource의 scheduling과 실행 timeout 기준이다.
- type별 실행 필드: `openai_compat`는 endpoint/headers/provider label, `ollama`는 base_url/context_size, `cli`는 command/args/resume_args/output_format/mode/session 옵션을 가진다.
- legacy `nodes[].adapters`: compat 입력이다. provider-first config와 충돌하면 validation error 또는 명확한 우선순위 규칙을 적용한다.
- 출력:
- internal adapter registry: provider-first config에서 컴파일된 adapter instance와 CLI profile set이다.
- `NodeConfigPayload`: Node가 기존 `adapter + target` runtime으로 실행할 수 있는 provider-derived payload다.
- provider/resource status snapshot: `providers[]` resource identity, type/category, served models, health, capacity, in-flight, queued 상태다.
- 금지:
- 사용자-facing 기본 config에서 같은 provider endpoint/capacity/model 정보를 `adapters`와 `providers`에 중복 작성하도록 요구하지 않는다.
- provider id, adapter instance key, model alias, served model 의미를 섞지 않는다.
- Node runtime을 global concurrency gate로 되돌리지 않는다.
- 기존 config를 silent break하지 않는다. legacy/compat 또는 명확한 migration error를 제공한다.
## Acceptance Scenarios
| ID | Milestone Task | Given | When | Then |
|----|----------------|-------|------|------|
| S01 | `schema-source` | 한 Node에 `openai_compat`, `ollama`, `cli` provider resource가 `providers[]`에 선언된다 | config load/validation을 실행한다 | `providers[]`만으로 type별 필드, model alias/served target, capacity/queue가 검증된다 |
| S02 | `normalize-compile` | provider-first config가 유효하다 | Edge가 Node config payload를 만든다 | provider id가 internal adapter instance key 또는 CLI target으로 컴파일되고 Node가 기존 adapter registry로 실행 가능하다 |
| S03 | `legacy-compat` | 기존 `nodes[].adapters` config 또는 provider-first와 legacy adapter가 섞인 config가 있다 | config check를 실행한다 | legacy config는 회귀 없이 통과하거나, 충돌 config는 명확한 validation error를 낸다 |
| S04 | `routing-status-refresh` | OpenAI-compatible 요청이 provider model alias를 사용한다 | Edge dispatch를 실행한다 | provider-first `models[]` mapping에서 후보를 선택하고 provider type별 internal adapter/served target으로 dispatch한다 |
| S05 | `routing-status-refresh` | provider-first config로 연결된 Node status를 조회한다 | Edge/Control Plane status snapshot을 만든다 | status는 `providers[]` resource catalog를 우선하고 adapter duplicate snapshot을 만들지 않는다 |
| S06 | `dev-runtime-docs` | 운영자가 dev-runtime guide와 config 예시를 읽는다 | Mac CLI + MLX provider node를 확인한다 | `providers[]` 한 곳에 CLI resource와 MLX vLLM provider resource가 나열되고 `adapters` 중복 선언을 기본 경로로 요구하지 않는다 |
| S07 | `full-cycle-smoke` | dev-runtime provider-first config가 배포된다 | config check/refresh 또는 restart, `/v1/models`, `/v1/responses`, `/v1/chat/completions` capacity smoke를 실행한다 | 3 connected nodes, 3 provider candidates, total capacity 10 기준 smoke가 유지된다 |
## Evidence Map
| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
|----------|-------------------|------------------|---------------------------|
| S01 | config schema/validation unit tests and `configs/edge.yaml` provider-first example diff | `agent-task/m-node-provider-first-config-surface/01_schema_source` | `schema-source` Roadmap Completion과 config loader/validation verification output |
| S02 | mapper/config_set/router tests proving provider-derived adapter payload | `agent-task/m-node-provider-first-config-surface/02_normalize_compile` | `normalize-compile` Roadmap Completion과 Edge-to-Node payload tests |
| S03 | legacy/mixed config compatibility tests | `agent-task/m-node-provider-first-config-surface/03_legacy_compat` | `legacy-compat` Roadmap Completion과 backward compatibility verification |
| S04 | Edge service/OpenAI route tests | `agent-task/m-node-provider-first-config-surface/04_routing_status_refresh` | `routing-status-refresh` Roadmap Completion과 provider-first dispatch evidence |
| S05 | status/config refresh tests | `agent-task/m-node-provider-first-config-surface/04_routing_status_refresh` | `routing-status-refresh` Roadmap Completion과 provider-first snapshot/config refresh evidence |
| S06 | docs/inventory/stale-reference check | `agent-task/m-node-provider-first-config-surface/05_dev_runtime_docs` | `dev-runtime-docs` Roadmap Completion과 `rg` stale reference verification |
| S07 | dev-runtime config check, refresh/restart evidence, OpenAI-compatible capacity smoke | `agent-task/m-node-provider-first-config-surface/06_full_cycle_smoke` | `full-cycle-smoke` Roadmap Completion과 `/v1/responses`, `/v1/chat/completions`, capacity accounting evidence |
## Cross-repo Dependencies
- 없음
## Drift Check
- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
- [x] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
- [x] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다.
## 사용자 리뷰 이력
- 2026-06-29: 사용자 대화에서 Node config 표면은 `providers[]` resource list 중심이어야 하며 `adapters`와 `providers` 중복 source of truth는 이해하기 어렵고 관리 비용을 높인다는 방향을 확인했다.
## 작업 컨텍스트
- 표준선: 사용자-facing config는 provider/resource-first로 단순화하고, 내부 adapter registry는 provider config에서 컴파일되는 실행 IR로 유지한다.
- 표준선: 기존 adapter runtime은 안정화된 내부 실행 구조로 유지하되, 새 config 예시와 dev-runtime 운영 경로는 provider-first를 기본으로 한다.
- 후속 SDD: 요청 실행 로그와 Usage Ledger 기반이 provider/resource/node identity를 ledger schema로 확장할 때 이 SDD의 provider id 기준을 참조한다.