From 55987c8e591ca9687eb6a31bfdbb2dd4aa8c3245 Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 29 Jun 2026 15:21:33 +0900 Subject: [PATCH] feat: node provider milestone and SDD docs add --- .../PHASE.md | 4 + .../node-provider-first-config-surface.md | 77 ++++++++++++ .../node-provider-first-config-surface/SDD.md | 115 ++++++++++++++++++ 3 files changed, 196 insertions(+) create mode 100644 agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md create mode 100644 agent-roadmap/sdd/operational-observability-provider-management/node-provider-first-config-surface/SDD.md diff --git a/agent-roadmap/phase/operational-observability-provider-management/PHASE.md b/agent-roadmap/phase/operational-observability-provider-management/PHASE.md index 32aa87a..9e645c6 100644 --- a/agent-roadmap/phase/operational-observability-provider-management/PHASE.md +++ b/agent-roadmap/phase/operational-observability-provider-management/PHASE.md @@ -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차 운영 경계를 스케치한다. diff --git a/agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md b/agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md new file mode 100644 index 0000000..c6fe604 --- /dev/null +++ b/agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md @@ -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 기반 +- 확인 필요: 없음 diff --git a/agent-roadmap/sdd/operational-observability-provider-management/node-provider-first-config-surface/SDD.md b/agent-roadmap/sdd/operational-observability-provider-management/node-provider-first-config-surface/SDD.md new file mode 100644 index 0000000..e94b883 --- /dev/null +++ b/agent-roadmap/sdd/operational-observability-provider-management/node-provider-first-config-surface/SDD.md @@ -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 기준을 참조한다.