# Milestone: Seulgivibe OpenAI-compatible Provider 연동

## 위치

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

## 목표

Seulgivibe의 Claude/OpenAI 프록시 경로를 IOP의 OpenAI-compatible provider family로 관리한다.
Claude 모델 3종과 OpenAI/Codex 모델 축을 정적 catalog로 노출하고, 사용자별 raw token은 IOP 호출 시점에 provider tunnel header로만 전달한다.
Codex `wire_api=responses` 경로가 provider tunnel을 통해 동작하도록 `/v1/responses` raw passthrough parity를 확보한다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- SDD: 필요
- SDD 문서: [SDD.md](../../../sdd/routing-policy-model-orchestration/seulgivibe-openai-compatible-provider/SDD.md)
- SDD 사유: OpenAI-compatible API/config schema, provider auth header, 외부 provider passthrough 계약이 바뀌는 Milestone이다.
- 잠금 해제 조건:
  - [x] SDD 잠금이 해제되어 있다
  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다
  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  - [x] Evidence Map이 완료 시 `Roadmap Completion`과 최종 검증 evidence로 검증 가능하게 연결되어 있다
- 결정 필요: 없음

## 범위

- Seulgivibe Claude/OpenAI proxy endpoint를 별도 provider id/type 축으로 관리하는 config/catalog 계약
- `seulgivibe_claude`, `seulgivibe_openai` provider type alias와 OpenAI-compatible adapter 재사용
- Claude 모델 `claude-sonnet-4-5`, `claude-opus-4-8`, `claude-fable-5` 정적 model catalog
- OpenAI/Codex 모델 `gpt-5.1`, `gpt-5.5` 정적 model catalog
- 사용자별 raw token을 inbound request header에서 읽어 provider tunnel `Authorization` header로 전달하는 경계
- Chat Completions provider tunnel과 Responses provider tunnel의 Seulgivibe passthrough 지원
- Seulgivibe provider가 model group에 참여할 때 `seulgivibe_claude`, `seulgivibe_openai`를 OpenAI-compatible passthrough(+sideband) 계열 provider로 유지하는 기준
- Seulgivibe provider 자체가 별도 execution path selector를 추가하지 않는 기준. model group 전역 selector 제거/거부는 [Model Group Mixed Provider Dispatch](model-group-mixed-provider-dispatch.md)가 소유한다.

## 기능

### Epic: [seulgivibe-provider] Seulgivibe Provider Surface

Seulgivibe를 IOP 내부에서는 provider-first OpenAI-compatible resource로 다루고, 외부 호출자는 OpenAI-compatible model id와 request-time provider token만 사용하게 하는 기능을 묶는다.

- [x] [config-auth-catalog] Seulgivibe Claude/OpenAI provider aliases, `openai.provider_auth` schema, 정적 model catalog/계약 예시가 추가되어 있다. 검증: `GOCACHE=/config/workspace/iop/.cache/go-build go test ./packages/go/config -count=1`, `GOCACHE=/config/workspace/iop/.cache/go-build go test ./apps/edge/internal/node -count=1`, tracked docs/config secret scan이 통과했다.
- [x] [provider-token-tunnel] Edge OpenAI Chat Completions provider tunnel이 configured request header의 raw user token을 provider `Authorization` header로 전달하고 missing-required를 dispatch 전에 차단한다. 검증: `GOCACHE=/config/workspace/iop/.cache/go-build go test ./apps/edge/internal/openai -count=1`이 auth forwarding/missing tests를 포함해 통과했다.
- [x] [responses-passthrough] OpenAI-compatible provider route에서 `/v1/responses` raw passthrough가 동작하고 Codex-style unknown fields, streaming, provider auth, model rewrite를 보존/검증한다. 검증: `GOCACHE=/config/workspace/iop/.cache/go-build go test ./apps/edge/internal/openai -count=1`이 Responses passthrough tests를 포함해 통과했다.

## 현 작업 현황

- [x] 현재 checkout에는 `config-auth-catalog`, `provider-token-tunnel`, `responses-passthrough` 구현과 관련 regression test가 반영되어 있다.
- [x] 로컬 검증: `GOCACHE=/config/workspace/iop/.cache/go-build go test ./packages/go/config -count=1`, `GOCACHE=/config/workspace/iop/.cache/go-build go test ./apps/edge/internal/node -count=1`, `GOCACHE=/config/workspace/iop/.cache/go-build go test ./apps/edge/internal/openai -count=1`이 통과했다.
- [x] tracked docs/config secret scan은 실제 provider token/key 후보 없이 통과했다. `task-123` 같은 문서 예시가 `sk-123` 부분 문자열로 잡히는 오탐은 길이 기준 재검사에서 제외됐다.
- [x] `agent-task/m-seulgivibe-openai-compatible-provider/**/complete.log`는 현재 worktree에 없고, 본 종료는 2026-07-11 현재 checkout 코드 감사와 사용자 종료 요청을 기준으로 처리했다.
- [x] model group 전역 execution path selector 제거/거부는 [Model Group Mixed Provider Dispatch](model-group-mixed-provider-dispatch.md)의 `no-client-response-mode` 후속 범위로 분리했다.

## 완료 리뷰

- 상태: 통과
- 요청일: 2026-07-11
- 완료 근거:
  - 현재 checkout에서 세 기능 Task의 코드 경로와 regression test가 확인됐다.
  - 코드 감사 중 Seulgivibe provider type label 정규화 누락을 보완했고 회귀 테스트를 추가했다.
  - `go test ./packages/go/config -count=1`, `go test ./packages/go/... -count=1`, `go test ./apps/edge/internal/node -count=1`, `go test ./apps/edge/internal/openai -count=1`, `go test ./apps/edge/... -count=1`, `go test ./apps/node/internal/adapters/openai_compat -count=1`을 workspace Go cache로 실행해 모두 통과했다.
  - tracked docs/config 범위의 secret scan에서 실제 provider token/key 후보가 없음을 확인했다.
  - Spec sync: [provider-pool-config-refresh.md](../../../../../agent-spec/runtime/provider-pool-config-refresh.md), [openai-compatible-surface.md](../../../../../agent-spec/input/openai-compatible-surface.md)에 Seulgivibe/provider auth 현 구현을 반영했다.
  - Workspace 잠금: 관련 lock 없음.
- 검토 항목:
  - [x] 세 기능 Task가 현재 checkout 기준으로 구현되어 있다.
  - [x] 최종 검증 출력이 SDD Evidence Map과 일치한다.
  - [x] 실제 token 값이 tracked 문서/config/test output에 남지 않았다.
  - [x] 사용자 완료 결과 확인을 받는다.
  - [x] archive 이동을 승인받는다.
- agent-ui 상태 반영: 해당 없음
- 리뷰 코멘트: 현재 worktree에는 `agent-task/m-seulgivibe-openai-compatible-provider` task artifact가 없으므로, 완료 판정은 현재 checkout 코드 감사, spec sync, 검증 결과를 기준으로 처리했다.

## 범위 제외

- host-local `~/.claude/anthropic_key.sh`, `~/.codex/config.toml`, Pi coding 설정 변경
- 실제 JWT/API key/token 값을 tracked config, docs, task artifact에 저장
- Seulgivibe `/v1/models` endpoint를 catalog source of truth로 사용하는 방식
- provider response payload의 model echo rewrite 또는 sideband injection을 Responses 기본 passthrough에 강제하는 작업
- billing/chargeback, 조직 IAM, 장기 retention 정책

## 작업 컨텍스트

- 관련 경로: `packages/go/config`, `apps/edge/internal/openai`, `apps/edge/internal/service`, `apps/edge/internal/node`, `apps/node/internal/adapters/openai_compat`, `apps/node/internal/runtime`, `proto/iop/runtime.proto`, [openai-compatible-api.md](../../../../../agent-contract/outer/openai-compatible-api.md)
- 표준선(선택): Seulgivibe는 새 wire adapter가 아니라 OpenAI-compatible provider family로 관리하고, provider별 특수 처리는 generation passthrough 밖의 auth/catalog/config 경계에만 둔다.
- 표준선(선택): Seulgivibe Claude/OpenAI provider aliases는 OpenAI-compatible 호출 방식을 지원하므로 [Model Group Mixed Provider Dispatch](model-group-mixed-provider-dispatch.md)의 passthrough(+sideband) 계열 provider에 포함된다. mixed provider dispatch의 일반 selection/path 분기는 해당 Milestone이 소유하고, 본 Milestone은 Seulgivibe auth/catalog/Responses raw passthrough를 소유한다.
- 표준선(선택): 사용자별 provider token은 request-time raw value로만 받고, Edge가 provider tunnel request header로 변환한다. Node나 host-local helper script가 사용자 token source of truth가 되지 않는다.
- 표준선(선택): provider `/models` endpoint가 실패해도 IOP `/v1/models`는 top-level `models[]` catalog를 source of truth로 노출한다.
- 우선순위 순서: [OpenAI-compatible 출력 검증 필터](../../../../phase/knowledge-tool-optimization-extension/milestones/openai-compatible-output-validation-filters.md) 완료 후 본 Milestone을 진행한다.
- 선행 작업: [OpenAI-compatible Raw Tunnel과 Sideband Passthrough](openai-compatible-raw-tunnel-sideband-passthrough.md), [Model Alias Provider Pool과 Provider Catalog](../../operational-observability-provider-management/milestones/provider-catalog-device-status.md)
- 후속 작업: [Model Group Mixed Provider Dispatch](model-group-mixed-provider-dispatch.md)의 model group mixed dispatch와 execution path selector 제거, 자동 route scorer 구현, provider auth per-provider granularity, Seulgivibe live smoke profile 정리
- 확인 필요: 없음
