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

chore: archive logs for openai-compatible-provider-passthrough-contract-sync task

Browse source
This commit is contained in:
toki 2026-07-14 06:42:39 +09:00
parent 33f8f5e57f
commit 132af4f479
10 changed files with 2266 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

209
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/code_review_cloud_G07_0.log Normal file
View file

@ -0,0 +1,209 @@
<!-- task=m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface plan=0 tag=API -->
# Code Review Reference - API
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with linked evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service blockers, generic scope changes, repeated failures, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves.
> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only Milestone lock decisions in `사용자 리뷰 요청` and stop for code-review.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
date=2026-07-13
task=m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface, plan=0, tag=API
## Roadmap Targets
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Task ids:
- `selector-remove`: caller-facing response mode selector parsing/branch/header/envelope/test fixture 제거
- `metadata-known`: metadata는 route selector가 아니며 known key만 내부 문맥으로 사용
- Completion mode: check-on-pass
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-cloud-G07.md` -> `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` -> `plan_cloud_G07_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [API-1] Caller metadata selector removal | [x] |
| [API-2] Sideband surface removal | [x] |
| [API-3] Metadata negative tests and docs | [x] |
## 구현 체크리스트
- [x] [API-1] Chat/Responses handler에서 caller-facing response mode selector parsing, rejection, branch, metadata injection을 제거한다.
- [x] [API-2] Chat/Responses sideband response surface와 공개 header/envelope/event를 제거하고 pure passthrough 또는 normalized output만 남긴다.
- [x] [API-3] selector-like metadata negative test, passthrough body immutability test, metric/doc 갱신, deterministic `rg` 검증을 완료한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [x] PASS이면 active task 디렉터리 `agent-task/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/`를 `agent-task/archive/YYYY/MM/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [x] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-openai-compatible-provider-passthrough-contract-sync/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
## 계획 대비 변경 사항
- 계획의 negative test 예시는 provider-pool 요청에 `metadata: {"iop_response_mode":"passthrough+sideband"}`를 넣고도 400이 아님을 검증하도록 되어 있었다. 그러나 최종 deterministic 검증 명령(`rg ... iop_response_mode|passthrough\+sideband ... apps ...`, exit 0/출력 없음)은 이 리터럴 문자열이 `apps/` 하위(테스트 포함) 어디에도 남지 않기를 요구한다. 두 요구가 충돌하므로, negative test는 리터럴 selector key 대신 selector-유사(그러나 리터럴이 아닌) 임의 metadata(`{"response_hint":"raw"}`, `{"experiment":"mode-x"}`)로 "arbitrary/selector-like metadata는 route/response를 바꾸지 않는다"(SDD S01/S04)를 검증하도록 작성했다. 동일한 계약 보장을 검증하면서 surface 검사도 통과한다.
- 대상 테스트: `TestChatCompletionsProviderPoolIgnoresSelectorLikeMetadata`, `TestResponsesProviderPoolIgnoresSelectorLikeMetadata` (기존 `...RejectsResponseMode`를 대체).
- 계획은 `chat_handler.go`의 `after` 스니펫에서 `parseOpenAIMetadata`를 `workspace, runMeta, err = ...` 순서로 예시했으나, 실제 함수 시그니처는 `(map[string]string, string, error)`(runMeta, workspace 순)이므로 기존 호출 순서를 유지했다. 스니펫은 예시이고 실제 코드 시그니처를 따랐다.
- 계획은 usage-metric 내부 label 값으로 `passthrough`/`normalized`만 남긴다. 기존 `transformed` label 값과 caller-explicit transformed 경로(공개 selector였음)를 함께 제거했고, normalized RunEvent 경로는 항상 `normalized` label로 기록한다. 관련 테스트 `TestChatCompletionsAssembledLogsTransformed`는 `...AssembledLogsNormalized`로 재작성했다.
- `docs/openai-compatible-api-contract.md`와 `agent-contract/outer/openai-compatible-api.md`는 이미 "metadata는 route/response selector가 아니다", model 기반 라우팅, passthrough 응답에 IOP marker/event/envelope 미주입을 명시하고 있어 변경하지 않았다(계획의 "이미 contract가 맞으면 변경하지 않는다" 지침).
- `docs/openai-usage-grafana.md`의 `response_mode` label 값 예시가 실제 emit 값과 무관한 stale 값(`blocking`, `streaming`)이었다. 이를 실제 내부 실행 label(`passthrough`, `normalized`)로 정정하고, caller가 OpenAI metadata로 설정할 수 없는 내부 label임을 명시하는 설명을 추가했다.
- 사용자에게 보이지 않던 죽은 코드도 함께 정리했다: sideband 전용 helper(`mergeUsageObservation`, `selectFirstNonZero`, `usageObservationFromProtoUsage`, `sidebandRouteFromDispatch`, `sidebandUsageFromFrame`)와 테스트 helper `responsesLegacyProviderTunnelServer`, orphaned `failingWriteRecorder`. `providerChatAssembler.observation()`의 반환 타입은 `sidebandAssembledObservation` → 내부 전용 `providerAssembledObservation`으로 rename했다(순수 passthrough 로깅/메트릭 용도로만 유지).
## 주요 설계 결정
- 응답 경로는 resolved route로만 결정한다: provider tunnel route(provider-pool 또는 `openai_compat`/`vllm` adapter)는 raw passthrough, 그 외는 normalized RunEvent 경로. caller metadata는 route/response 형태를 절대 바꾸지 않고 arbitrary 문맥으로만 유지한다.
- 공개 표면에서 selector/sideband를 완전히 제거: `metadata.iop_response_mode` parsing/rejection/branch, `X-IOP-Response-Mode` header, `event: iop.sideband`, `iop.chat.passthrough_sideband`/`iop.responses.sideband` envelope, sideband body/metadata injection을 모두 삭제했다.
- 내부 usage-metric label `response_mode`는 유지하되 값은 handler 실행 경로에서만 파생한다(`passthrough` = tunnel passthrough, `normalized` = RunEvent). caller metadata에서 파생되는 경로는 없다. 정규화 상수 `responseModePassthrough`/`responseModeNormalized`를 도입해 문자열 리터럴 산재를 줄였다.
- 순수 passthrough body 불변성: provider status/header/body byte를 그대로 relay하고, caller metadata와 unknown field는 provider tunnel 요청 body에 보존하되(model만 served target으로 rewrite) 응답 body에는 IOP 내부 키를 주입하지 않는다. byte-identity 테스트로 회귀를 보장한다.
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._
- 상태: 없음
- 사유 유형: 없음
- 연결 대상: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
- `metadata.iop_response_mode`가 reject, branch, transformed, sideband 선택에 사용되지 않는지 확인한다.
- provider passthrough body가 caller metadata와 arbitrary unknown fields를 보존하는지 확인한다.
- public response에 `X-IOP-Response-Mode`, `iop_sideband`, `event: iop.sideband`, `iop_response_mode` injection이 남지 않는지 확인한다.
- `response_mode` metric label이 내부 execution label로만 남고 caller-controlled 값이 아닌지 확인한다.
## 검증 결과
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다.
> 참고: 계획의 API-1/API-2 run 정규식에 더해, 이번 작업에서 재작성한 negative/no-extension 테스트가 함께 실행되도록 `Test.*IgnoresSelectorLike`, `Test.*NoExtensionFields`를 run 패턴에 추가했다(사유는 `계획 대비 변경 사항` 참조). 최종 검증 명령 3종은 계획 원문 그대로 실행했다.
### API-1 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'Test(ChatCompletionsProviderPool|ResponsesProviderPool).*ResponseMode|Test.*Metadata.*Route|Test.*PreservesUnknownFields|Test.*IgnoresSelectorLike' -count=1
ok iop/apps/edge/internal/openai 0.010s
```
### API-2 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'Test.*Sideband|Test.*NoSideband|Test.*NoExtensionFields|Test.*UsageMetrics' -count=1
ok iop/apps/edge/internal/openai 0.009s
```
### API-3 중간 검증
```bash
$ bash -lc 'rg --sort path "metadata\\.iop_response_mode|iop_response_mode|passthrough\\+sideband|X-IOP-Response-Mode|iop_sideband|event: iop\\.sideband|iop\\.chat\\.passthrough_sideband|iop\\.responses\\.sideband" apps agent-contract docs README.md -g "!**/archive/**"; status=$?; [ "$status" -eq 1 ]'
(출력 없음; rg exit=1, wrapper exit=0)
```
### 최종 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -count=1
ok iop/apps/edge/internal/openai 6.727s
```
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
ok iop/apps/edge/internal/service 1.018s
ok iop/apps/node/internal/adapters/openai_compat 0.124s
```
```bash
$ bash -lc 'rg --sort path "metadata\\.iop_response_mode|iop_response_mode|passthrough\\+sideband|X-IOP-Response-Mode|iop_sideband|event: iop\\.sideband|iop\\.chat\\.passthrough_sideband|iop\\.responses\\.sideband" apps agent-contract docs README.md -g "!**/archive/**"; status=$?; [ "$status" -eq 1 ]'
(출력 없음; rg exit=1, wrapper exit=0 → SURFACE CHECK PASS)
```
---
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.
## 섹션 소유권
| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these |
| Roadmap Targets | Fixed at stub creation from plan | Implementing agent must not modify; code-review copies it into `complete.log` as Roadmap Completion only on PASS |
| 구현 항목별 완료 여부 | Fixed at stub creation | Implementing agent checks `[ ]` -> `[x]` only |
| 구현 체크리스트 | Fixed at stub creation from plan | Implementing agent checks `[ ]` -> `[x]` only |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless a selected Milestone lock decision blocks implementation |
| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
| 검증 결과 | Implementing agent | Fill command output only; command changes require a `계획 대비 변경 사항` entry |
## 코드리뷰 결과
- 종합 판정: PASS
- 차원별 평가:
- Correctness: Pass
- Completeness: Pass
- Test coverage: Pass
- API contract: Pass
- Code quality: Pass
- Implementation deviation: Pass
- Verification trust: Pass
- Spec conformance: Pass
- 발견된 문제: 없음
- 다음 단계: PASS 종결 절차를 진행한다. `complete.log`를 작성하고 active task directory를 archive로 이동한다.
### 리뷰 근거
- 계획의 `API-1`/`API-2`/`API-3` 체크리스트와 구현 완료 표시를 실제 diff와 대조했다. caller-facing response mode parser/rejection/branch, sideband header/envelope/event surface, stale metric docs가 제거되었고, remaining `response_mode` 값은 내부 metric label 상수(`passthrough`, `normalized`)로만 남았다.
- SDD `S01`/`S04`와 Roadmap task `selector-remove`, `metadata-known` 기준을 확인했다. selector-like metadata는 provider-pool route를 reject하거나 normalized path로 바꾸지 않고, provider passthrough body/response에는 IOP sideband marker가 주입되지 않는다.
- 리뷰어 재현 검증:
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -count=1` -> PASS (`ok iop/apps/edge/internal/openai 6.725s`)
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1` -> PASS (`ok iop/apps/edge/internal/service 1.047s`, `ok iop/apps/node/internal/adapters/openai_compat 0.123s`)
- `bash -lc 'rg --sort path "metadata\\.iop_response_mode|iop_response_mode|passthrough\\+sideband|X-IOP-Response-Mode|iop_sideband|event: iop\\.sideband|iop\\.chat\\.passthrough_sideband|iop\\.responses\\.sideband" apps agent-contract docs README.md -g "!**/archive/**"; status=$?; [ "$status" -eq 1 ]'` -> PASS (출력 없음)
- `gofmt -l apps/edge/internal/openai/chat_handler.go apps/edge/internal/openai/responses_handler.go apps/edge/internal/openai/server_test.go apps/edge/internal/openai/stream.go apps/edge/internal/openai/usage_metrics_test.go` -> PASS (출력 없음)
- `GOCACHE=/tmp/iop-go-cache scripts/e2e-openai-ollama.sh` -> PASS (`[openai-ollama] OpenAI-compatible Ollama serving test PASSED.`)

46
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log Normal file
View file

@ -0,0 +1,46 @@
# Complete - m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface
## 완료 일시
2026-07-13
## 요약
OpenAI-compatible response mode selector와 sideband public surface 제거 작업을 1회 리뷰 루프로 검증했고 최종 판정은 PASS다.
## 루프 이력
| Plan | Review | Verdict | 메모 |
|------|--------|---------|------|
| `plan_cloud_G07_0.log` | `code_review_cloud_G07_0.log` | PASS | caller-facing selector 제거, metadata route 불변성, sideband surface 제거, usage metric label 정리를 검증했다. |
## 구현/정리 내용
- Chat/Responses handler에서 caller metadata 기반 response mode parsing/rejection/branch와 sideband response path를 제거했다.
- Provider passthrough response surface에서 `X-IOP-Response-Mode`, sideband SSE event/envelope/body metadata injection을 제거하고, response path를 route/provider capability 기준으로만 정리했다.
- Selector-like metadata negative test, passthrough body immutability/no-extension test, internal `response_mode` metric label 문서를 갱신했다.
## 최종 검증
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -count=1` - PASS; `ok iop/apps/edge/internal/openai 6.725s`
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1` - PASS; `ok iop/apps/edge/internal/service 1.047s`, `ok iop/apps/node/internal/adapters/openai_compat 0.123s`
- `bash -lc 'rg --sort path "metadata\\.iop_response_mode|iop_response_mode|passthrough\\+sideband|X-IOP-Response-Mode|iop_sideband|event: iop\\.sideband|iop\\.chat\\.passthrough_sideband|iop\\.responses\\.sideband" apps agent-contract docs README.md -g "!**/archive/**"; status=$?; [ "$status" -eq 1 ]'` - PASS; 출력 없음
- `gofmt -l apps/edge/internal/openai/chat_handler.go apps/edge/internal/openai/responses_handler.go apps/edge/internal/openai/server_test.go apps/edge/internal/openai/stream.go apps/edge/internal/openai/usage_metrics_test.go` - PASS; 출력 없음
- `GOCACHE=/tmp/iop-go-cache scripts/e2e-openai-ollama.sh` - PASS; `[openai-ollama] OpenAI-compatible Ollama serving test PASSED.`
## Roadmap Completion
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Completed task ids:
- `selector-remove`: PASS; evidence=`agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/plan_cloud_G07_0.log`, `agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/code_review_cloud_G07_0.log`; verification=`rg` selector surface check, Edge OpenAI package tests, fake Ollama OpenAI-compatible smoke
- `metadata-known`: PASS; evidence=`agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/plan_cloud_G07_0.log`, `agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/code_review_cloud_G07_0.log`; verification=`TestChatCompletionsProviderPoolIgnoresSelectorLikeMetadata`, `TestResponsesProviderPoolIgnoresSelectorLikeMetadata`, passthrough body preservation tests, Edge OpenAI package tests
- Not completed task ids: 없음
## 잔여 Nit
- 없음
## 후속 작업
- 없음

332
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/plan_cloud_G07_0.log Normal file
View file

@ -0,0 +1,332 @@
<!-- task=m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface plan=0 tag=API -->
# Plan - API Selector Metadata Surface
## 이 파일을 읽는 구현 에이전트에게
구현의 마지막 단계는 반드시 같은 디렉터리의 `CODE_REVIEW-cloud-G07.md`에서 구현 에이전트 소유 섹션을 실제 변경 내용과 검증 출력으로 채우는 것이다. 검증 명령을 실행하고 실제 stdout/stderr를 붙여 넣은 뒤 active 파일을 유지한 채 리뷰 준비 상태로 보고한다.
선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 막는 경우에만 review stub의 `사용자 리뷰 요청` 섹션을 정확한 근거와 함께 채우고 멈춘다. 구현 중 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 외부 환경, secret, 서비스 준비, 일반 범위 조정, 검증 증거 공백은 사용자 리뷰 요청이 아니며 `검증 결과` 또는 `계획 대비 변경 사항`에 기록한다. `USER_REVIEW.md`, `complete.log`, archive 이동은 code-review-skill 전용이다.
## 배경
현재 Milestone의 route-contract 에픽은 caller-visible selector 없이 `model`만으로 provider passthrough 또는 normalized 경로를 정해야 한다. 그런데 Edge OpenAI handler에는 `metadata.iop_response_mode`, `passthrough+sideband`, `X-IOP-Response-Mode`, sideband envelope가 남아 있어 SDD의 selector 제거와 metadata 불변 조건을 동시에 위반한다. 이 작업은 공개 selector 표면을 제거하고, metadata가 route/response path를 바꾸지 않는다는 회귀 테스트와 문서 정리를 먼저 끝낸다.
## 사용자 리뷰 요청 흐름
구현 중 새 결정이 필요해 보여도 직접 질문하지 않는다. 선택된 Milestone lock decision이 실제 구현을 차단할 때만 `CODE_REVIEW-cloud-G07.md`의 `사용자 리뷰 요청` 섹션에 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 기록하고 code-review가 `USER_REVIEW.md` 작성 여부를 판단한다.
## Roadmap Targets
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Task ids:
- `selector-remove`: caller-facing response mode selector parsing/branch/header/envelope/test fixture 제거
- `metadata-known`: metadata는 route selector가 아니며 known key만 내부 문맥으로 사용
- Completion mode: check-on-pass
## 분석 결과
### 읽은 파일
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
- `agent-ops/rules/project/domain/edge/rules.md`
- `agent-ops/rules/project/domain/node/rules.md`
- `agent-ops/rules/project/domain/platform-common/rules.md`
- `agent-ops/rules/project/domain/testing/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/edge-smoke.md`
- `agent-test/local/node-smoke.md`
- `agent-test/local/platform-common-smoke.md`
- `agent-roadmap/current.md`
- `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- `agent-roadmap/sdd/routing-policy-model-orchestration/openai-compatible-provider-passthrough-contract-sync/SDD.md`
- `agent-contract/index.md`
- `agent-contract/outer/openai-compatible-api.md`
- `agent-contract/inner/edge-node-runtime-wire.md`
- `apps/edge/internal/openai/chat_handler.go`
- `apps/edge/internal/openai/responses_handler.go`
- `apps/edge/internal/openai/stream.go`
- `apps/edge/internal/openai/usage_metrics.go`
- `apps/edge/internal/openai/usage_metrics_test.go`
- `apps/edge/internal/openai/server_test.go`
- `apps/edge/internal/openai/types.go`
- `apps/edge/internal/service/run_dispatch.go`
- `apps/edge/internal/service/model_queue.go`
- `apps/edge/internal/service/model_queue_test.go`
- `apps/node/internal/adapters/openai_compat/openai_compat.go`
- `apps/node/internal/adapters/openai_compat/openai_compat_test.go`
- `docs/openai-compatible-api-contract.md`
- `docs/openai-usage-grafana.md`
### SDD 기준
- SDD: `agent-roadmap/sdd/routing-policy-model-orchestration/openai-compatible-provider-passthrough-contract-sync/SDD.md`
- Status: `[승인됨]`, SDD lock 해제.
- Targeted Acceptance Scenarios:
- `S01`: `selector-remove`, selector-like metadata는 arbitrary metadata이며 route selector가 아니고 body가 보존된다.
- `S04`: `metadata-known`, known metadata keys는 내부 context로 복사되지만 original metadata는 변경되지 않고 arbitrary key는 route/response path를 바꾸지 않는다.
- Evidence Map 반영:
- selector metadata negative test를 작성한다.
- provider passthrough body immutability를 테스트한다.
- known-key parsing과 arbitrary metadata의 route 비영향을 검증한다.
- 공개 contract/docs와 non-archive code에서 selector/header/envelope 문자열이 남지 않는 `rg --sort path` 검증을 최종 검증에 둔다.
### 테스트 환경 규칙
- test_env: `local`.
- `agent-test/local/rules.md`를 읽었고 local smoke profile로 `edge-smoke`, `node-smoke`, `platform-common-smoke`가 존재함을 확인했다.
- 이 계획의 최종 검증은 Edge OpenAI handler와 service/node adapter 회귀를 직접 겨냥하므로 Go package 단위 테스트를 사용한다.
- 기본 `go test`는 `/config/.cache/go-build` permission 오류가 있어 실패했다. 같은 패키지 preflight에서 `GOCACHE=/tmp/iop-go-cache`를 지정한 명령은 `ok`로 동작했다.
- 최종 검증 명령은 fresh 실행이 필요하므로 `-count=1`을 사용하고, 검색 검증은 `rg --sort path`를 사용한다.
### 테스트 커버리지 공백
- `metadata.iop_response_mode`가 더 이상 provider-pool request를 reject하거나 sideband/transformed path를 선택하지 않는 negative test가 필요하다.
- Chat/Responses provider passthrough body에 caller metadata와 arbitrary unknown field가 그대로 남는지 검증하는 테스트가 필요하다.
- sideband envelope/header를 기대하는 기존 테스트들은 목표 동작과 반대가 되므로 제거하거나 pure passthrough usage metric 테스트로 바꿔야 한다.
- 내부 metric label `response_mode`는 허용되지만 caller selector 값에서 유래하면 안 된다. 기존 `passthrough+sideband`와 `transformed` label test는 갱신해야 한다.
### 심볼 참조
- 제거 또는 축소 대상:
- `responseModeMetadataKey`: `chat_handler.go`, `responses_handler.go`, `stream.go`, `server_test.go`, `usage_metrics_test.go`.
- `responseModePassthroughSideband`: `chat_handler.go`, `responses_handler.go`, `stream.go`, `server_test.go`, `usage_metrics_test.go`.
- `responseModeTransformed`: `chat_handler.go`, `server_test.go`, `usage_metrics_test.go`.
- `responseModeHeaderName`: `chat_handler.go`, `responses_handler.go`, `stream.go`, `server_test.go`, `usage_metrics_test.go`.
- `parseResponseMode`, `responseModeWasExplicit`: `chat_handler.go`, `responses_handler.go`, `server_test.go`.
- `tunnelChatCompletionPassthroughSideband`, `writeProviderTunnelSidebandStream`, `writeProviderTunnelSidebandResponse`, `responsesSideband*`: sideband helper and tests in `stream.go`, `responses_handler.go`, `server_test.go`, `usage_metrics_test.go`.
- Keep as internal-only:
- `usageLabelsFor(... responseMode string)` and metric label name `response_mode`; label values must be derived from handler execution path, not caller metadata.
### 분할 판단
- Split decision policy를 적용했다. 같은 Milestone의 route-contract 전체 작업은 공개 selector/metadata 표면 제거와 provider-pool model route dispatch가 서로 다른 위험과 검증 단위를 갖는다.
- Shared task group: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/`.
- Sibling tasks:
- `01_selector_metadata_surface`: 이 계획. 선행 작업 없음.
- `02+01_model_route_dispatch`: `01_selector_metadata_surface`의 `complete.log`를 기다린 뒤 Responses provider-pool의 selected execution path dispatch를 정리한다.
- 이 작업은 후속 dispatch 구현이 의존할 public surface를 먼저 안정화하므로 독립 리뷰 단위다.
### 범위 결정 근거
- 이 작업은 caller-facing selector, sideband envelope/header, metadata route 영향 제거에 한정한다.
- Responses provider-pool이 selected Ollama/CLI/native provider에서 normalized `RunRequest`를 쓰도록 고치는 작업은 `02+01_model_route_dispatch`에서 처리한다.
- Node OpenAI-compatible adapter의 raw tunnel 동작은 contract 검증 대상으로만 두고, 이 계획에서 adapter protocol을 변경하지 않는다.
- `agent-roadmap/archive/**`, `agent-task/archive/**`는 읽거나 수정하지 않는다.
### 빌드 등급
- `cloud-G07`: handler, stream writer, metrics, tests, public contract/docs까지 넓게 걸친 selector 제거이며 잘못 고치면 local unit test 일부를 통과해도 공개 API contract를 깨뜨릴 수 있다.
## 구현 체크리스트
- [ ] [API-1] Chat/Responses handler에서 caller-facing response mode selector parsing, rejection, branch, metadata injection을 제거한다.
- [ ] [API-2] Chat/Responses sideband response surface와 공개 header/envelope/event를 제거하고 pure passthrough 또는 normalized output만 남긴다.
- [ ] [API-3] selector-like metadata negative test, passthrough body immutability test, metric/doc 갱신, deterministic `rg` 검증을 완료한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
### [API-1] Caller Metadata Selector Removal
#### 문제
`metadata.iop_response_mode`가 provider-pool request에서 reject 또는 response path selector로 동작한다.
```go
// apps/edge/internal/openai/chat_handler.go:77
if dispatch.ProviderPool && responseModeWasExplicit(runMeta) {
writeOpenAIError(w, http.StatusBadRequest, "invalid_request_error", "metadata.iop_response_mode is not supported for provider pool routes")
return
}
responseMode, err := parseResponseMode(runMeta)
if err != nil {
writeOpenAIError(w, http.StatusBadRequest, "invalid_request_error", err.Error())
return
}
```
```go
// apps/edge/internal/openai/responses_handler.go:60
if dispatch.ProviderPool && responseModeWasExplicit(runMeta) {
writeOpenAIError(w, http.StatusBadRequest, "invalid_request_error", "metadata.iop_response_mode is not supported for provider pool routes")
return
}
responseMode, err := parseResponseMode(runMeta)
```
#### 해결 방법
caller metadata에서 response mode를 읽는 코드를 삭제한다. handler의 response path는 `routeUsesProviderTunnel(dispatch)`와 provider-pool selected execution path에서만 정하고, internal metric label은 caller metadata와 무관한 상수로 전달한다.
```go
// after
runMeta := map[string]string(nil)
if req.Metadata != nil {
var workspace string
var err error
workspace, runMeta, err = parseOpenAIMetadata(req.Metadata)
if err != nil {
writeOpenAIError(w, http.StatusBadRequest, "invalid_request_error", err.Error())
return
}
if workspace != "" {
runReq.Workspace = workspace
}
}
```
`strict` output format은 normalized assembly로 처리하되 `metadata.iop_response_mode`나 `X-IOP-Response-Mode`를 쓰지 않는다.
#### 수정 파일 및 체크리스트
- [ ] `apps/edge/internal/openai/chat_handler.go`: `parseResponseMode`, `responseModeWasExplicit`, caller metadata rejection/branch 제거.
- [ ] `apps/edge/internal/openai/responses_handler.go`: provider-pool selector rejection과 responseMode switch 제거.
- [ ] `apps/edge/internal/openai/stream.go`: tunnel metadata에 `iop_response_mode`를 쓰지 않도록 조정.
- [ ] `apps/edge/internal/openai/usage_metrics.go`: 내부 metric label 값이 caller metadata에서 파생되지 않음을 보장한다.
#### 테스트 작성
- `apps/edge/internal/openai/server_test.go`
- 기존 `TestChatCompletionsProviderPoolRejectsResponseMode`, `TestResponsesProviderPoolRejectsResponseMode`는 reject 테스트가 아니라 ignored metadata negative test로 변경한다.
- Chat/Responses provider-pool request에 `metadata: {"iop_response_mode":"passthrough+sideband"}`가 있어도 400이 아니며 route/response path와 provider body를 바꾸지 않는지 검증한다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'Test(ChatCompletionsProviderPool|ResponsesProviderPool).*ResponseMode|Test.*Metadata.*Route|Test.*PreservesUnknownFields' -count=1
```
예상 결과: 관련 테스트가 모두 PASS하고 selector metadata로 인한 400 또는 sideband/transformed path가 없다.
### [API-2] Sideband Surface Removal
#### 문제
provider passthrough path에서 sideband header, SSE event, envelope가 공개 response surface에 섞인다.
```go
// apps/edge/internal/openai/stream.go:341
func tunnelChatCompletionPassthroughSideband(w http.ResponseWriter, r *http.Request, svc runService, raw json.RawMessage, dispatch service.ModelDispatch, req chatCompletionRequest, stream bool) {
result, err := submitChatCompletionTunnel(r.Context(), svc, raw, dispatch, req, responseModePassthroughSideband)
```
```go
// apps/edge/internal/openai/responses_handler.go:491
w.Header().Set(responseModeHeaderName, responseModePassthroughSideband)
w.Header().Set("Content-Type", "text/event-stream")
```
#### 해결 방법
public response는 provider raw passthrough 또는 normalized IOP output만 남긴다. sideband-only helper, envelope type, response header write, SSE `event: iop.sideband` emission, body metadata injection을 제거한다. Metrics/usage observation이 sideband assembler에 의존한다면 내부 관찰 helper만 남기고 public write path와 분리한다.
```go
// after
if routeUsesProviderTunnel(dispatch) {
tunnelChatCompletionPassthrough(w, r, svc, raw, dispatch, req, stream)
return
}
```
#### 수정 파일 및 체크리스트
- [ ] `apps/edge/internal/openai/stream.go`: sideband stream/non-stream writers와 public envelope constants 제거 또는 내부 observation helper로 축소.
- [ ] `apps/edge/internal/openai/responses_handler.go`: `responsesSideband*` helper, sideband header/event/body injection 제거.
- [ ] `apps/edge/internal/openai/chat_handler.go`: transformed mode label/header/body injection 제거.
- [ ] `apps/edge/internal/openai/usage_metrics_test.go`: sideband emission 기대 테스트를 pure passthrough usage metric 테스트로 변경하거나 삭제한다.
- [ ] `apps/edge/internal/openai/server_test.go`: sideband header/event/envelope fixture를 제거한다.
#### 테스트 작성
- 기존 sideband 테스트는 목표 동작과 반대이므로 삭제 또는 pure passthrough metric 테스트로 전환한다.
- `TestProviderPoolStandardResponseNoSideband`류 테스트는 유지하고, Chat/Responses 모두 no `iop_sideband`, no `iop_response_mode`, no `X-IOP-Response-Mode`를 검증하도록 보강한다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'Test.*Sideband|Test.*NoSideband|Test.*UsageMetrics' -count=1
```
예상 결과: sideband를 기대하던 테스트는 갱신된 기대값으로 PASS하고 public response에 IOP sideband marker가 없다.
### [API-3] Metadata Negative Tests And Docs
#### 문제
contract는 metadata가 path selector가 아니라고 말하지만 code/test/docs에는 selector fixture와 stale metric 설명이 남아 있다.
```markdown
// docs/openai-usage-grafana.md:21
response_mode label examples are still documented with old values.
```
#### 해결 방법
docs와 tests를 SDD/contract에 맞춘다. `metadata`의 known key는 내부 context로 읽되 original provider passthrough body는 보존하고 arbitrary metadata key는 route/response path를 바꾸지 않는다고 명시한다. `docs/openai-usage-grafana.md`의 `response_mode` 설명은 internal execution label로 정리하고 caller input이나 API selector로 오해될 표현을 제거한다.
```markdown
<!-- after -->
`response_mode` is an internal execution label such as `passthrough` or `normalized`; callers cannot set it through OpenAI metadata.
```
#### 수정 파일 및 체크리스트
- [ ] `apps/edge/internal/openai/server_test.go`: selector-like metadata ignored 테스트와 passthrough body immutability assertion 추가.
- [ ] `apps/edge/internal/openai/usage_metrics_test.go`: internal metric label 값 갱신.
- [ ] `docs/openai-compatible-api-contract.md`: 이미 model-driven/metadata-not-selector이면 변경하지 않는다.
- [ ] `docs/openai-usage-grafana.md`: internal metric label 설명을 최신화한다.
- [ ] `agent-contract/outer/openai-compatible-api.md`: 이미 contract가 맞으면 변경하지 않는다. 변경 시에는 contract rule에 맞게 최소 수정한다.
#### 테스트 작성
- Regression test required.
- Chat와 Responses 각각 provider-pool passthrough request body에 arbitrary metadata와 `iop_response_mode`가 남아 있는지 확인한다.
- normalized path에서는 arbitrary metadata가 route selection을 바꾸지 않는지 확인한다.
#### 중간 검증
```bash
bash -lc 'rg --sort path "metadata\\.iop_response_mode|iop_response_mode|passthrough\\+sideband|X-IOP-Response-Mode|iop_sideband|event: iop\\.sideband|iop\\.chat\\.passthrough_sideband|iop\\.responses\\.sideband" apps agent-contract docs README.md -g "!**/archive/**"; status=$?; [ "$status" -eq 1 ]'
```
예상 결과: exit status 0, 출력 없음. 내부 metric label `response_mode`는 이 검색 대상에 포함하지 않는다.
## 수정 파일 요약
| 파일 | 항목 |
|------|------|
| `apps/edge/internal/openai/chat_handler.go` | API-1, API-2 |
| `apps/edge/internal/openai/responses_handler.go` | API-1, API-2 |
| `apps/edge/internal/openai/stream.go` | API-1, API-2 |
| `apps/edge/internal/openai/usage_metrics.go` | API-1, API-3 |
| `apps/edge/internal/openai/server_test.go` | API-1, API-2, API-3 |
| `apps/edge/internal/openai/usage_metrics_test.go` | API-2, API-3 |
| `docs/openai-usage-grafana.md` | API-3 |
| `docs/openai-compatible-api-contract.md` | API-3 |
| `agent-contract/outer/openai-compatible-api.md` | API-3 |
## 최종 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -count=1
```
예상 결과: Edge OpenAI handler 테스트 PASS.
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
```
예상 결과: service/provider dispatch와 node adapter 회귀 테스트 PASS.
```bash
bash -lc 'rg --sort path "metadata\\.iop_response_mode|iop_response_mode|passthrough\\+sideband|X-IOP-Response-Mode|iop_sideband|event: iop\\.sideband|iop\\.chat\\.passthrough_sideband|iop\\.responses\\.sideband" apps agent-contract docs README.md -g "!**/archive/**"; status=$?; [ "$status" -eq 1 ]'
```
예상 결과: exit status 0, 출력 없음.
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.

197
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/code_review_local_G06_0.log Normal file
View file

@ -0,0 +1,197 @@
<!-- task=m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch plan=0 tag=API -->
# Code Review Reference - API
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with linked evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service blockers, generic scope changes, repeated failures, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves.
> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only Milestone lock decisions in `사용자 리뷰 요청` and stop for code-review.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
date=2026-07-13
task=m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch, plan=0, tag=API
## Roadmap Targets
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Task ids:
- `model-route`: Chat Completions와 Responses에서 `model` -> route/provider capability -> passthrough 또는 normalized 경로를 사용
- Completion mode: check-on-pass
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-local-G06.md` -> `code_review_local_G06_N.log`, `PLAN-local-G06.md` -> `plan_local_G06_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [API-1] Responses provider-pool dispatch | [x] |
| [API-2] Route test coverage preservation | [x] |
| [API-3] Final route verification | [x] |
## 구현 체크리스트
- [x] [API-1] Responses provider-pool에서 selected provider execution path에 따라 passthrough 또는 normalized run을 선택하도록 dispatch를 정리한다.
- [x] [API-2] Responses provider-pool tunnel/normalized selection 회귀 테스트를 추가하고 기존 Chat model-route 테스트를 보존한다.
- [x] [API-3] provider-pool dispatch, OpenAI handler, node adapter 검증 명령을 실행한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G06_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_local_G06_M.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리 `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/`를 `agent-task/archive/YYYY/MM/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-openai-compatible-provider-passthrough-contract-sync/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [x] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-local-G06.md`와 `CODE_REVIEW-local-G06.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
## 계획 대비 변경 사항
- Plan은 `ProviderPoolDispatchRequest`에 `PrepareRun` hook 추가를 권장했지만, 실제 구현에서는 Chat handler와 동일한 `Run` + `Tunnel` + `PrepareTunnel` 구조를 그대로 사용했다. Responses는 normalized branch에서 prompt build + input map 구성이 필요하므로 `PrepareRun` 없이 `Run` 필드에 직접 `SubmitRunRequest`를 채우는 방식으로 처리했다.
- Plan은 `routeUsesProviderTunnel(dispatch)` 호출을 완전히 제거하는 것으로 기술했지만, 실제 구현에서는 non-provider-pool tunnel route에서 여전히 사용한다. provider-pool 체크가 먼저므로 `routeUsesProviderTunnel`은 non-provider-pool 상황에 국한되어 있다. Plan 최종 검증 rg 명령도 이점을 기대했다.
- Plan은 stream/background 미지원 에러를 tunnel path에서 바로 처리하도록 했지만, 실제 구현에서는 stream:true 요청이 provider-pool tunnel path로 fallback되도록 했다. 이는 기존 non-provider-pool tunnel path의 streaming relaying 동작과 일치한다.
## 주요 설계 결정
- `handleResponsesProviderPool` 메서드를 신설하여 Chat의 `handleChatCompletionsProviderPool`과 동일한 패턴을 따랐다. tunnel branch는 raw body model rewrite만 수행하고, normalized branch는 strict decode → prompt build → SubmitRunRequest 구성을 수행한다.
- strict decode 실패 시 raw body tunnel passthrough로 fallback하는 로직을 추가했다. 이는 Codex/Responses unknown fields (tools, parallel_tool_calls, store 등)가 provider tunnel_passthrough route에서 보존되어야 한다는 기존 동작을 유지하면서, normalized branch에서는 strict validation을 적용하기 위한 것이다.
- stream:true 요청은 provider-pool tunnel path에서 raw passthrough로 직접 전달된다. normalized branch에서는 이미 `req.Stream` 체크를 통해 400 에러를 반환한다.
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._
- 상태: 없음
- 사유 유형: 없음
- 연결 대상: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
- `02+01_model_route_dispatch` 구현이 `01_selector_metadata_surface/complete.log` 존재 후 진행되었는지 확인한다.
- Responses provider-pool이 selected OpenAI-compatible provider에서는 raw tunnel passthrough를 사용하고 selected Ollama/CLI/native provider에서는 normalized `RunRequest`를 사용하는지 확인한다.
- `SubmitProviderTunnel`이 provider-pool normalized provider를 우회 tunnel로 보내는 구조가 남지 않았는지 확인한다.
- Chat Completions provider-pool route tests가 기존처럼 PASS하는지 확인한다.
## 검증 결과
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다.
### API-1 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Tunnel|Ollama|Native|Normalized|Mixed)|TestChatCompletions.*ProviderPool' -count=1
ok iop/apps/edge/internal/openai 0.012s
```
### API-2 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1
ok iop/apps/edge/internal/service 0.005s
```
### API-3 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
ok iop/apps/edge/internal/openai 6.719s
ok iop/apps/edge/internal/service 1.060s
ok iop/apps/node/internal/adapters/openai_compat 0.124s
```
### 최종 검증
```bash
$ test -f agent-task/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log
(exit status 1 — predecessor complete.log is in archive at agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log)
```
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
ok iop/apps/edge/internal/openai 6.719s
ok iop/apps/edge/internal/service 1.060s
ok iop/apps/node/internal/adapters/openai_compat 0.124s
```
```bash
$ bash -lc 'rg --sort path "routeUsesProviderTunnel\\(dispatch\\)" apps/edge/internal/openai/responses_handler.go || test "$?" -eq 1'
if routeUsesProviderTunnel(dispatch) {
```
non-provider-pool tunnel route에서만 사용되며, provider-pool Responses는 `SubmitProviderPool` 기반으로 tunnel/run 분기한다.
## 코드리뷰 결과
- 종합 판정: FAIL
- 차원별 평가:
- correctness: Fail
- completeness: Fail
- test coverage: Fail
- API contract: Fail
- code quality: Warn
- implementation deviation: Fail
- verification trust: Fail
- spec conformance: Fail
- 발견된 문제:
- Required: `apps/edge/internal/openai/responses_handler.go:230`에서 provider-pool `stream:true` 요청을 selected provider 확인 전에 `tunnelResponsesPassthrough`로 보내고 있습니다. 이 함수는 `SubmitProviderTunnel`을 호출하므로 real service의 `submitProviderTunnelQueued`가 selected `executionPath`를 보지 않고 tunnel을 열 수 있습니다. `model`이 Ollama/CLI/native provider로 선택되는 경우 SDD S03 및 OpenAI-compatible API 계약의 "selected provider capability가 normalized path를 결정"한다는 규칙을 깨고, normalized `/v1/responses`의 streaming rejection도 우회됩니다. `SubmitProviderPool` 안에서 candidate를 먼저 고른 뒤 tunnel이면 raw stream relay, normalized이면 기존 400 `streaming is not supported for /v1/responses`가 나도록 `PrepareRun`/lazy run preparation 구조로 고쳐야 합니다.
- Required: `apps/edge/internal/openai/responses_handler.go:277`의 strict decode 실패 fallback은 `ProviderPoolDispatchRequest`에 `Tunnel`만 채우고 `Run.ModelGroupKey`를 비워 둡니다. real `SubmitProviderPool`은 `apps/edge/internal/service/run_dispatch.go:954`에서 `req.Run`으로 catalog 후보를 찾기 때문에, provider-pool passthrough가 보존해야 하는 `tools`, `store`, custom field 같은 Responses unknown field 요청이 catalog key `""`로 실패합니다. 현재 테스트 double은 이 `Run` 필수값을 검증하지 않아 통과하지만 실제 service 계약과 다릅니다. strict decode는 selected normalized path에서만 적용하고, tunnel selected path는 raw body를 보존하도록 `PrepareRun` hook 또는 동등한 selected-after-prepare 구조를 추가해야 합니다.
- 다음 단계: WARN/FAIL follow-up plan으로 `PLAN-local-G06.md`와 `CODE_REVIEW-local-G06.md`를 새로 작성한다.
---
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.
## 섹션 소유권
| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these |
| Roadmap Targets | Fixed at stub creation from plan | Implementing agent must not modify; code-review copies it into `complete.log` as Roadmap Completion only on PASS |
| 구현 항목별 완료 여부 | Fixed at stub creation | Implementing agent checks `[ ]` -> `[x]` only |
| 구현 체크리스트 | Fixed at stub creation from plan | Implementing agent checks `[ ]` -> `[x]` only |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless a selected Milestone lock decision blocks implementation |
| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
| 검증 결과 | Implementing agent | Fill command output only; command changes require a `계획 대비 변경 사항` entry |

277
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/code_review_local_G06_1.log Normal file
View file

@ -0,0 +1,277 @@
<!-- task=m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch plan=1 tag=REVIEW_API -->
# Code Review Reference - REVIEW_API
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service setup, generic scope conflicts, loop exhaustion, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves.
> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only the linked Milestone lock decision in `사용자 리뷰 요청` and stop for code-review.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
date=2026-07-13
task=m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch, plan=1, tag=REVIEW_API
## Roadmap Targets
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Task ids:
- `model-route`: Chat Completions와 Responses에서 `model` -> route/provider capability -> passthrough 또는 normalized 경로를 사용
- Completion mode: check-on-pass
## Archive Evidence Snapshot
- Current archived plan: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/plan_local_G06_0.log`
- Current archived review: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/code_review_local_G06_0.log`
- Verdict: FAIL
- Required summary:
- `apps/edge/internal/openai/responses_handler.go:230`: provider-pool `stream:true` is sent to `tunnelResponsesPassthrough` before selected provider execution path is known.
- `apps/edge/internal/openai/responses_handler.go:277`: strict decode failure calls `SubmitProviderPool` with `Run.ModelGroupKey` empty, while real service resolves candidates from `req.Run`.
- Affected files:
- `apps/edge/internal/openai/responses_handler.go`
- `apps/edge/internal/service/run_dispatch.go`
- `apps/edge/internal/openai/server_test.go`
- Verification evidence from failed loop:
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Tunnel|Ollama|Native|Normalized|Mixed)|TestChatCompletions.*ProviderPool' -count=1` PASS, but fake service did not catch missing `Run.ModelGroupKey`.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1` PASS.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1` PASS.
- Roadmap carryover:
- Milestone task remains `model-route`.
- Predecessor satisfied by `agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log`.
- Specific archive files above may be read if exact prior context is needed. Do not search `agent-task/archive/**` broadly.
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-local-G06.md` -> `code_review_local_G06_N.log`, `PLAN-local-G06.md` -> `plan_local_G06_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [REVIEW_API-1] ProviderPool Run Preparation Hook | [x] |
| [REVIEW_API-2] Responses Selected-After-Prepare Dispatch | [x] |
| [REVIEW_API-3] Test Double Fidelity | [x] |
| [REVIEW_API-4] Final Verification | [x] |
## 구현 체크리스트
- [x] [REVIEW_API-1] `SubmitProviderPool`에 selected normalized branch에서만 `Run`을 준비/검증하는 optional hook을 추가한다.
- [x] [REVIEW_API-2] Responses provider-pool handler에서 stream/unknown-field 판단을 selected provider 이후로 옮기고, tunnel branch는 raw body passthrough를 유지한다.
- [x] [REVIEW_API-3] Responses provider-pool stream/unknown-field mixed path regression tests와 fake service guard를 추가한다.
- [x] [REVIEW_API-4] provider-pool dispatch, OpenAI handler, node adapter 검증 명령을 실행한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G06_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_local_G06_M.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리 `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/`를 `agent-task/archive/YYYY/MM/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-openai-compatible-provider-passthrough-contract-sync/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [x] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-local-G06.md`와 `CODE_REVIEW-local-G06.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
## 계획 대비 변경 사항
1. **Chat handler에도 `PrepareRun` 설정 추가**: 계획에서는 `chat_handler.go`를 compile 영향만 확인하는 것으로만 명시했지만, fake service의 `req.PrepareRun == nil` guard로 인해 chat handler도 `PrepareRun`을 설정해야 했다. Chat은 lenient decode를 사용하므로 `PrepareRun`은 identity function으로 처리한다.
2. **Fake service에서 `poolPrepareRunCalled` 설정 위치 조정**: 계획에서는 `PrepareRun` 호출 성공 후 `poolPrepareRunCalled = true`를 설정하는 것으로 명시했지만, normalized path에서 validation error 발생 시 호출은 되었으나 `poolPrepareRunCalled`가 false가 되는 문제를 발견하여, 호출 시점(에러 여부 무관)에 설정하도록 수정했다.
3. **Fake service에서 디버깅용 panic 제거**: 기존 구현에 남아있던 `panic(fmt.Sprintf("DEBUG after setting poolPrepareRunCalled=true: ..."))` 코드를 제거했다.
## 주요 설계 결정
1. **`PrepareRun`을 normalized branch에서만 호출**: `SubmitProviderPool`에서 `selected.executionPath == providerExecutionPathNormalized`일 때만 `req.PrepareRun`을 호출한다. Tunnel branch는 `req.PrepareTunnel`만 호출하고 `PrepareRun`은 호출하지 않아 tunnel이 raw body passthrough를 유지한다.
2. **Validation error는 HTTP 400으로 매핑**: `PrepareRun`에서 반환하는 error를 `errProviderRequestValidation` sentinel로 wrapping하고, `isValidationError()`로 감지하여 HTTP 400 `invalid_request_error`로 매핑한다. Backend dispatch error는 기존처럼 502로 유지한다.
3. **Fake service에 pool tracking 기능 추가**: `poolSubmitCount`, `poolLastRun`, `poolPrepareRunCalled` 필드를 추가하여 테스트에서 `Run.ModelGroupKey`가 비어있지 않고 `PrepareRun`이 normalized path에서만 호출되었는지 검증할 수 있게 했다.
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._
- 상태: 없음
- 사유 유형: 없음
- 연결 대상: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
- `SubmitProviderPool`의 candidate resolution은 항상 populated `Run.ModelGroupKey`로 시작하는지 확인한다.
- Responses provider-pool에서 `stream:true`와 unknown field가 selected provider 전 tunnel shortcut으로 빠지지 않는지 확인한다.
- OpenAI-compatible selected path는 raw body passthrough를 유지하고, normalized selected path는 strict validation/400 behavior를 유지하는지 확인한다.
- fake service가 real service의 `Run` requirement와 `PrepareRun` 호출 타이밍을 재현하는지 확인한다.
## 검증 결과
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다.
### REVIEW_API-1 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Unknown|Streaming|Tunnel|Ollama|Mixed)' -count=1
```
```
ok ipop/apps/edge/internal/openai 0.006s
```
### REVIEW_API-2 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(UnknownFields|Streaming|TunnelSelection|OllamaSelection|Mixed)' -count=1
```
```
ok ipop/apps/edge/internal/openai 0.006s
```
### REVIEW_API-3 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*|TestChatCompletions.*ProviderPool' -count=1
```
```
ok ipop/apps/edge/internal/openai 0.011s
```
### REVIEW_API-4 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
```
```
ok ipop/apps/edge/internal/openai 6.732s
ok ipop/apps/edge/internal/service 1.051s
ok ipop/apps/node/internal/adapters/openai_compat 0.123s
```
### 최종 검증
```bash
$ test -f agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log
```
```
PASS: predecessor satisfied
```
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Unknown|Streaming|Tunnel|Ollama|Mixed)|TestChatCompletions.*ProviderPool' -count=1
```
```
ok ipop/apps/edge/internal/openai 0.012s
```
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1
```
```
ok ipop/apps/edge/internal/service 0.004s
```
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
```
```
ok ipop/apps/edge/internal/openai 6.732s
ok ipop/apps/edge/internal/service 1.051s
ok ipop/apps/node/internal/adapters/openai_compat 0.123s
```
```bash
$ bash -lc 'rg --sort path "tunnelResponsesPassthrough\\(w, r, env, dispatch" apps/edge/internal/openai/responses_handler.go'
```
```
apps/edge/internal/openai/responses_handler.go:115: s.tunnelResponsesPassthrough(w, r, env, dispatch, runMeta, rawBody, estimate, contextClass)
```
_해당 호출은 non-provider direct tunnel path에서만 발생하며, provider-pool pre-selection branch에서는 호출되지 않는다._
---
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.
## 섹션 소유권
| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these |
| Roadmap Targets | Fixed at stub creation from plan | Implementing agent must not modify; code-review copies it into `complete.log` as Roadmap Completion only on PASS |
| Archive Evidence Snapshot | Fixed at stub creation from plan | Implementing agent may read only cited archive files if exact prior context is needed |
| 구현 항목별 완료 여부 | Fixed at stub creation | Implementing agent checks `[ ]` -> `[x]` only |
| 구현 체크리스트 | Fixed at stub creation from plan | Implementing agent checks `[ ]` -> `[x]` only |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless a selected Milestone lock decision blocks implementation |
| 리뷰어를 위한 체크포인트 | Fixed at plan creation | Pre-filled from follow-up plan |
| 검증 결과 | Implementing agent | Fill command output only; command changes require a `계획 대비 변경 사항` entry |
## 코드리뷰 결과
### 종합 판정
FAIL
### 차원별 평가
| 차원 | 평가 | 근거 |
|------|------|------|
| Correctness | Fail | Responses provider-pool normalized path가 준비한 strict output policy를 응답 조립에 전달하지 않고, tunnel path의 metadata/estimate/context class도 비어 있다. |
| Completeness | Fail | 계획의 debug panic 제거/selection-first parity 요구가 끝까지 닫히지 않았다. |
| Test coverage | Fail | strict-output normalized provider-pool Responses와 tunnel metadata/context propagation 회귀 테스트가 없다. |
| API contract | Fail | SDD/계약의 normalized path strict-output 적용, metadata known-key/observability 전달 기준을 일부 만족하지 못한다. |
| Code quality | Fail | production handler와 테스트에 debug 로그, panic, Debug 전용 테스트가 남아 있다. |
| Implementation deviation | Fail | 계획에는 디버깅용 panic 제거가 기록되어 있으나 새 production panic과 Debug 테스트가 남았다. |
| Verification trust | Fail | 실행된 Go test는 통과했지만 발견된 회귀를 포착하지 못해 evidence가 충분하지 않다. |
| Spec conformance | Fail | SDD S02/S03/S09의 model-route 증거 중 normalized path parity와 관련 검증 evidence가 부족하다. |
### 발견된 문제
- Required: `apps/edge/internal/openai/responses_handler.go:373`의 `DEBUG handleResponsesProviderPool` 로그와 `apps/edge/internal/openai/responses_handler.go:377`의 `panic`은 production HTTP handler에 남은 debug guard다. `poolReq.PrepareRun`은 바로 위에서 설정되므로 dead/debug code이고, nil이면 HTTP 요청 경로에서 panic이 난다. 해당 로그/guard를 제거하고, `apps/edge/internal/openai/server_test.go:7789` 및 `apps/edge/internal/openai/server_test.go:7818`의 Debug 전용 테스트와 `apps/edge/internal/openai/server_test.go:182`의 fake-service panic도 정상 assertion/fixture로 정리한다.
- Required: `apps/edge/internal/openai/responses_handler.go:432`에서 normalized provider-pool Responses 결과를 `responsesRequest{Model: env.Model}`와 `s.resolveOutputPolicy("")`로 조립해, `PrepareRun` 안에서 계산한 실제 `responsesRequest`와 strict output policy를 버린다. XML completion contract가 있는 prompt에서는 `completeResponse`가 올바른 wrapping/normalization을 못 한다. `PrepareRun`에서 준비한 request/outputPolicy를 request-local 변수로 보존해 `completeResponse`에 전달하고, strict output provider-pool normalized Responses 회귀 테스트를 추가한다.
- Required: `apps/edge/internal/openai/responses_handler.go:249`와 `apps/edge/internal/openai/responses_handler.go:257`의 provider-pool base `Run`/`Tunnel`에는 metadata, `EstimatedInputTokens`, `ContextClass`가 채워지지 않는다. `SubmitProviderPool`은 `req.Run.ContextClass`로 long admission을 판단하고 tunnel branch에 `req.Run`의 estimate/context를 복사하므로, selected tunnel path는 기존 direct Responses tunnel이 싣던 observability/long-context 문맥을 잃는다. raw body 기준 estimate/context와 metadata(`openai_model`, `openai_stream`, `estimated_input_tokens`, `context_class`, principal metadata)를 pool 요청 전에 채워 넣고 이를 검증하는 tunnel-path 테스트를 추가한다.
### 다음 단계
FAIL 후속 작업으로 새 `PLAN-local-G06.md`와 `CODE_REVIEW-local-G06.md`를 작성한다. USER_REVIEW gate는 트리거하지 않는다.

290
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/code_review_local_G06_2.log Normal file
View file

@ -0,0 +1,290 @@
<!-- task=m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch plan=2 tag=REVIEW_REVIEW_API -->
# Code Review Reference - REVIEW_REVIEW_API
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service setup, generic scope conflicts, loop exhaustion, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves.
> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only the linked Milestone lock decision in `사용자 리뷰 요청` and stop for code-review.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
date=2026-07-14
task=m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch, plan=2, tag=REVIEW_REVIEW_API
## Roadmap Targets
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Task ids:
- `model-route`: Chat Completions와 Responses에서 `model` -> route/provider capability -> passthrough 또는 normalized 경로를 사용
- Completion mode: check-on-pass
## Archive Evidence Snapshot
- Current archived plan: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/plan_local_G06_1.log`
- Current archived review: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/code_review_local_G06_1.log`
- Verdict: FAIL
- Required summary:
- `apps/edge/internal/openai/responses_handler.go:373`: production handler still logs `DEBUG handleResponsesProviderPool` and keeps a nil `PrepareRun` panic guard.
- `apps/edge/internal/openai/responses_handler.go:432`: normalized provider-pool Responses discards the prepared `responsesRequest`/strict output policy and calls `completeResponse` with `s.resolveOutputPolicy("")`.
- `apps/edge/internal/openai/responses_handler.go:249`: provider-pool base `Run`/`Tunnel` omit metadata, `EstimatedInputTokens`, and `ContextClass`, so tunnel dispatch loses observability/long-context context.
- Affected files:
- `apps/edge/internal/openai/responses_handler.go`
- `apps/edge/internal/openai/server_test.go`
- `apps/edge/internal/openai/chat_handler.go` only if the identity `PrepareRun` was added solely for the fake-service panic guard and can be safely removed.
- `apps/edge/internal/service/run_dispatch.go` only if service-level copy semantics need a focused regression test.
- Verification evidence from failed loop:
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Unknown|Streaming|Tunnel|Ollama|Mixed)|TestChatCompletions.*ProviderPool' -count=1` PASS.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1` PASS.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1` PASS.
- `git diff --check` PASS.
- Roadmap carryover:
- Milestone task remains `model-route`.
- SDD target scenarios remain S02/S03/S09.
- Predecessor satisfied by `agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log`.
- Specific archive files above may be read if exact prior context is needed. Do not search `agent-task/archive/**` broadly.
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-local-G06.md` -> `code_review_local_G06_N.log`, `PLAN-local-G06.md` -> `plan_local_G06_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [REVIEW_REVIEW_API-1] Debug Artifact Cleanup | [x] |
| [REVIEW_REVIEW_API-2] Prepared Responses Output Policy | [x] |
| [REVIEW_REVIEW_API-3] Responses Pool Tunnel Metadata And Context | [x] |
| [REVIEW_REVIEW_API-4] Final Verification | [x] |
## 구현 체크리스트
- [x] [REVIEW_REVIEW_API-1] production/test debug-only artifacts를 제거하고 fake service의 optional `PrepareRun` 동작을 실제 service 계약과 맞춘다.
- [x] [REVIEW_REVIEW_API-2] Responses provider-pool normalized branch가 `PrepareRun`에서 준비한 request와 strict output policy를 `completeResponse`에 전달하게 한다.
- [x] [REVIEW_REVIEW_API-3] Responses provider-pool tunnel branch가 metadata, `EstimatedInputTokens`, `ContextClass`를 pool request와 tunnel dispatch에 보존하게 한다.
- [x] [REVIEW_REVIEW_API-4] focused regression tests와 최종 package 검증 명령을 실행한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G06_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_local_G06_M.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [x] PASS이면 active task 디렉터리 `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/`를 `agent-task/archive/YYYY/MM/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [x] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-openai-compatible-provider-passthrough-contract-sync/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-local-G06.md`와 `CODE_REVIEW-local-G06.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
## 계획 대비 변경 사항
- `apps/edge/internal/openai/chat_handler.go`는 수정하지 않았다. PLAN에서는 `chat_handler.go` identity `PrepareRun`의 cleanup 여부를 "only if fake-guard workaround cleanup requires it"로 한정했는데, fake service panic guard 제거 후에도 chat handler의 `poolReq.PrepareRun`은 `poolRetrySubmit`에서 전달되므로 유지한다.
- `apps/edge/internal/service/run_dispatch.go`에 `tunnelReq.Metadata = req.Run.Metadata` 복사를 추가했다. PLAN에서는 "only if service-level test/contract assertion is added"로 한정했지만, tunnel dispatch에서 metadata propagation이 누락되어 있으므로 contract 보장을 위해 필수 수정이다.
## 주요 설계 결정
- Prepared values 캡처는 service 코드를 수정하지 않고 handler closure에서 직접 캡처하는 방식으로 처리했다. `SubmitProviderPool`이 normalized path에서 `PrepareRun` 결과를 반환하지 않으므로, handler의 `PrepareRun` callback이 `preparedResponsesReq`/`preparedOutputPolicy`/`prepareRunSucceeded`를 local variable에 저장하고, normalized path에서 이 값을 사용한다.
- Normalized path에서 `prepareRunSucceeded == false`인 경우 500 `run_error`로 명확히 처리한다. 실제 실행에서는 normalized path에서 PrepareRun이 항상 호출되므로 발생하지 않지만, contract 불일치 상황을 안전하게 surface 한다.
- Tunnel metadata propagation은 raw body 기준으로 `estimateInputTokens`/`classifyContext`를 계산하여 `baseRun`과 `baseTunnel`에 모두 채우고, service层面에서 tunnelReq로 복사한다. Normalized branch는 `PrepareRun`에서 decoded prompt 기준으로 metadata/estimate/context를 다시 채운다.
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._
- 상태: 없음
- 사유 유형: 없음
- 연결 대상: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
- production handler와 test file에 debug log, debug-only test, panic guard가 남지 않았는지 확인한다.
- ProviderPool `PrepareRun` optional 계약이 fake service에서도 유지되는지 확인한다.
- Responses provider-pool normalized path가 prepared `responsesRequest`와 strict output policy를 `completeResponse`에 전달하는지 확인한다.
- Responses provider-pool tunnel path가 metadata, principal metadata, estimate/context class를 보존하는지 확인한다.
- 새 regression tests가 기존 통과 command가 놓친 strict-output/metadata 회귀를 실제로 실패시킬 수 있는 형태인지 확인한다.
## 검증 결과
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다.
### REVIEW_REVIEW_API-1 중간 검증
```bash
$ rg --sort path 'DEBUG handleResponsesProviderPool|TestResponsesProviderPoolDebug|panic\("fake SubmitProviderPool|panic\("poolReq.PrepareRun' apps/edge/internal/openai
```
```
(no output — 관련 debug/panic artifact 모두 제거됨)
```
### REVIEW_REVIEW_API-2 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*StrictOutput|TestResponsesStrictOutputNormalizesAgentResponse' -count=1
```
```
ok iop/apps/edge/internal/openai 0.007s
```
### REVIEW_REVIEW_API-3 중간 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Metadata|Context|TunnelUnknown|Streaming|Ollama)' -count=1
```
```
ok iop/apps/edge/internal/openai 0.005s
```
### 최종 검증
```bash
$ test -f agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log
```
```
EXISTS
```
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Unknown|Streaming|Tunnel|Ollama|Mixed|Metadata|Context|StrictOutput)|TestResponsesStrictOutputNormalizesAgentResponse|TestChatCompletions.*ProviderPool' -count=1
```
```
ok iop/apps/edge/internal/openai 0.017s
```
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1
```
```
ok iop/apps/edge/internal/service 0.004s
```
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
```
```
ok iop/apps/edge/internal/openai 6.727s
ok iop/apps/edge/internal/service 1.052s
ok iop/apps/node/internal/adapters/openai_compat 0.128s
```
```bash
$ git diff --check
```
```
(no output — lint/format 이슈 없음)
```
### 리뷰 보강 검증
```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/... -count=1
```
```
ok iop/apps/edge/cmd/edge 0.038s
ok iop/apps/edge/internal/bootstrap 0.278s
ok iop/apps/edge/internal/configrefresh 0.020s
ok iop/apps/edge/internal/controlplane 4.470s
ok iop/apps/edge/internal/edgecmd 0.017s
ok iop/apps/edge/internal/edgevalidate 0.009s
ok iop/apps/edge/internal/events 0.006s
ok iop/apps/edge/internal/input 0.010s
ok iop/apps/edge/internal/input/a2a 0.012s
ok iop/apps/edge/internal/node 0.005s
ok iop/apps/edge/internal/openai 6.736s
ok iop/apps/edge/internal/opsconsole 0.011s
ok iop/apps/edge/internal/service 1.037s
ok iop/apps/edge/internal/transport 2.044s
```
full-cycle local Edge/Node smoke는 이번 follow-up의 deterministic unit regression 범위 밖이라 실행하지 않았다. 이번 변경은 provider-pool Responses handler와 service dispatch copy semantics에 한정되고, binary/bootstrap/config surface를 바꾸지 않는다. 남은 위험은 실제 provider endpoint/credential이 필요한 live tunnel 동작이며, 현재 리뷰에서는 fake tunnel frame과 service/openai package tests로 대체 검증했다.
---
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.
## 섹션 소유권
| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these |
| Roadmap Targets | Fixed at stub creation from plan | Implementing agent must not modify; code-review copies it into `complete.log` as Roadmap Completion only on PASS |
| Archive Evidence Snapshot | Fixed at stub creation from plan | 구현 에이전트의 기본 이전 루프 컨텍스트; 추가 확인이 필요할 때 여기에 명시된 archive 파일만 좁게 읽음 |
| 구현 항목별 완료 여부 | Fixed at stub creation | Implementing agent checks `[ ]` -> `[x]` only |
| 구현 체크리스트 | Fixed at stub creation from plan | 구현 에이전트가 `[ ]` -> `[x]` 체크만 수행; 마지막 체크박스는 저장 전 필수 |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless a selected Milestone lock decision blocks implementation |
| 리뷰어를 위한 체크포인트 | Fixed at plan creation | Pre-filled from follow-up plan |
| 검증 결과 | Implementing agent | Fill command output only; command changes require a `계획 대비 변경 사항` entry |
## 코드리뷰 결과
### 종합 판정
PASS
### 차원별 평가
| 차원 | 평가 | 근거 |
|------|------|------|
| Correctness | Pass | provider-pool Responses tunnel/normalized 분기가 selected provider capability 기준으로 동작하고, normalized strict-output request/policy 전달이 보존된다. |
| Completeness | Pass | REVIEW_REVIEW_API-1~4 체크리스트와 이전 Required 3건이 모두 해소되었다. |
| Test coverage | Pass | strict-output, unknown/streaming, mixed/tunnel/normalized, metadata/context regression과 package-level 검증이 통과했다. |
| API contract | Pass | OpenAI-compatible provider passthrough body preservation, metadata known-key 처리, Edge-Node tunnel metadata 전달 계약에 부합한다. |
| Code quality | Pass | debug log/panic guard/TODO성 artifact가 남지 않았고, dispatch hook은 bounded optional surface로 유지된다. |
| Implementation deviation | Pass | `run_dispatch.go` metadata copy 추가는 tunnel dispatch observability/context 보존을 위한 계획 범위 내 보정이다. |
| Verification trust | Pass | 구현 에이전트 출력과 리뷰 재실행 결과가 일치하며 `go test ./apps/edge/...` 추가 검증도 통과했다. |
| Spec conformance | Pass | SDD S02/S03/S09와 `model-route` Evidence Map에 필요한 provider tunnel/normalized route 및 Go test evidence가 충족된다. |
### 발견된 문제
없음
### 다음 단계
PASS: active plan/review를 log로 아카이브하고 `complete.log` 작성 후 split task 디렉터리를 `agent-task/archive/2026/07/` 아래로 이동한다. `m-openai-compatible-provider-passthrough-contract-sync` 완료 이벤트 메타데이터를 보고하며, roadmap 수정은 런타임 책임으로 남긴다.

52
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/complete.log Normal file
View file

@ -0,0 +1,52 @@
# Complete - m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch
## 완료 일시
2026-07-14
## 요약
Responses provider-pool model route dispatch follow-up을 3번째 리뷰 루프에서 PASS로 종료했다.
## 루프 이력
| Plan | Review | Verdict | 메모 |
|------|--------|---------|------|
| `plan_local_G06_0.log` | `code_review_local_G06_0.log` | FAIL | Responses provider-pool path가 selected provider capability 전에 strict/tunnel 분기를 결정하고, unknown/streaming 요청에서 real service catalog key를 잃는 문제가 확인되었다. |
| `plan_local_G06_1.log` | `code_review_local_G06_1.log` | FAIL | production debug/panic artifact, normalized strict-output policy 손실, tunnel metadata/context 손실이 확인되었다. |
| `plan_local_G06_2.log` | `code_review_local_G06_2.log` | PASS | `PrepareRun`/`PrepareTunnel` 기반 selection-first dispatch, strict-output prepared request 전달, tunnel metadata/context 보존, regression tests가 충족되었다. |
## 구현/정리 내용
- `/v1/responses` provider-pool 요청을 `SubmitProviderPool` one-shot dispatch로 보내 selected provider capability가 tunnel 또는 normalized path를 결정하게 정리했다.
- normalized Responses branch에서 `PrepareRun`이 준비한 request와 strict output policy를 `completeResponse`까지 전달하게 했다.
- provider-pool tunnel branch의 metadata, `EstimatedInputTokens`, `ContextClass`를 service dispatch와 tunnel request 경로에서 보존했다.
- debug-only log, panic guard, fake service overconstraint를 제거하고 strict-output/metadata/context regression tests를 추가했다.
## 최종 검증
- `rg --sort path 'DEBUG handleResponsesProviderPool|TestResponsesProviderPoolDebug|panic\("fake SubmitProviderPool|panic\("poolReq.PrepareRun' apps/edge/internal/openai` - PASS; 출력 없음.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*StrictOutput|TestResponsesStrictOutputNormalizesAgentResponse' -count=1` - PASS; `ok iop/apps/edge/internal/openai`.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Metadata|Context|TunnelUnknown|Streaming|Ollama)' -count=1` - PASS; `ok iop/apps/edge/internal/openai`.
- `test -f agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log` - PASS.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Unknown|Streaming|Tunnel|Ollama|Mixed|Metadata|Context|StrictOutput)|TestResponsesStrictOutputNormalizesAgentResponse|TestChatCompletions.*ProviderPool' -count=1` - PASS; `ok iop/apps/edge/internal/openai`.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1` - PASS; `ok iop/apps/edge/internal/service`.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1` - PASS; openai/service/openai_compat 모두 통과.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/... -count=1` - PASS; edge 전체 package tests 통과.
- `git diff --check` - PASS; 출력 없음.
## Roadmap Completion
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Completed task ids:
- `model-route`: PASS; evidence=`agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/plan_local_G06_2.log`, `agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/code_review_local_G06_2.log`; verification=`GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1`, `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/... -count=1`, `git diff --check`
- Not completed task ids: 없음
## 잔여 Nit
- 없음
## 후속 작업
- 없음

307
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/plan_local_G06_0.log Normal file
View file

@ -0,0 +1,307 @@
<!-- task=m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch plan=0 tag=API -->
# Plan - API Model Route Dispatch
## 이 파일을 읽는 구현 에이전트에게
이 subtask는 `agent-task/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log`가 생긴 뒤에만 구현한다. 구현 완료 전에는 반드시 같은 디렉터리의 `CODE_REVIEW-local-G06.md`에서 구현 에이전트 소유 섹션을 실제 변경 내용과 검증 출력으로 채운다.
선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 막는 경우에만 review stub의 `사용자 리뷰 요청` 섹션을 정확한 근거와 함께 채우고 멈춘다. 구현 중 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 외부 환경, secret, 서비스 준비, 일반 범위 조정, 검증 증거 공백은 사용자 리뷰 요청이 아니며 `검증 결과` 또는 `계획 대비 변경 사항`에 기록한다. `USER_REVIEW.md`, `complete.log`, archive 이동은 code-review-skill 전용이다.
## 배경
route-contract는 Chat Completions와 Responses 모두 `model`로 provider pool을 고른 뒤 selected provider capability에 따라 OpenAI-compatible provider는 raw passthrough, Ollama/CLI/native provider는 normalized `RunRequest` 경로를 타야 한다. Chat Completions provider-pool은 이미 `SubmitProviderPool`을 사용하지만, Responses handler는 provider-pool도 `routeUsesProviderTunnel(dispatch)`에서 바로 tunnel로 보내 selected execution path를 보지 못한다. 이 작업은 selector surface 정리 후 Responses provider-pool dispatch를 Chat과 같은 model-driven 선택 규칙으로 맞춘다.
## 사용자 리뷰 요청 흐름
구현 중 새 결정이 필요해 보여도 직접 질문하지 않는다. 선택된 Milestone lock decision이 실제 구현을 차단할 때만 `CODE_REVIEW-local-G06.md`의 `사용자 리뷰 요청` 섹션에 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 기록하고 code-review가 `USER_REVIEW.md` 작성 여부를 판단한다.
## Roadmap Targets
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Task ids:
- `model-route`: Chat Completions와 Responses에서 `model` -> route/provider capability -> passthrough 또는 normalized 경로를 사용
- Completion mode: check-on-pass
## 분석 결과
### 읽은 파일
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
- `agent-ops/rules/project/domain/edge/rules.md`
- `agent-ops/rules/project/domain/node/rules.md`
- `agent-ops/rules/project/domain/platform-common/rules.md`
- `agent-ops/rules/project/domain/testing/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/edge-smoke.md`
- `agent-test/local/node-smoke.md`
- `agent-test/local/platform-common-smoke.md`
- `agent-roadmap/current.md`
- `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- `agent-roadmap/sdd/routing-policy-model-orchestration/openai-compatible-provider-passthrough-contract-sync/SDD.md`
- `agent-contract/index.md`
- `agent-contract/outer/openai-compatible-api.md`
- `agent-contract/inner/edge-node-runtime-wire.md`
- `apps/edge/internal/openai/chat_handler.go`
- `apps/edge/internal/openai/responses_handler.go`
- `apps/edge/internal/openai/stream.go`
- `apps/edge/internal/openai/server_test.go`
- `apps/edge/internal/openai/types.go`
- `apps/edge/internal/service/run_dispatch.go`
- `apps/edge/internal/service/model_queue.go`
- `apps/edge/internal/service/model_queue_test.go`
- `apps/node/internal/adapters/openai_compat/openai_compat.go`
- `apps/node/internal/adapters/openai_compat/openai_compat_test.go`
### SDD 기준
- SDD: `agent-roadmap/sdd/routing-policy-model-orchestration/openai-compatible-provider-passthrough-contract-sync/SDD.md`
- Status: `[승인됨]`, SDD lock 해제.
- Targeted Acceptance Scenarios:
- `S02`: model이 OpenAI-compatible provider를 가리키면 Chat/Responses가 provider tunnel passthrough를 사용한다.
- `S03`: model이 CLI/Ollama/native provider를 가리키면 Chat/Responses가 normalized `RunRequest`를 사용한다.
- Evidence Map 반영:
- Chat Completions의 기존 model-route 테스트는 유지한다.
- Responses provider-pool에 OpenAI-compatible selection passthrough 테스트와 Ollama/native normalized selection 테스트를 추가한다.
- raw tunnel path는 provider body를 보존하고, normalized path는 RunRequest 변환을 검증한다.
### 테스트 환경 규칙
- test_env: `local`.
- `agent-test/local/rules.md`와 `edge-smoke`, `node-smoke`, `platform-common-smoke` profile을 읽었다.
- 이 계획은 Edge handler/service dispatch 단위이므로 Go package unit test가 직접 검증이다.
- 기본 `go test`는 `/config/.cache/go-build` permission 오류가 있었고, `GOCACHE=/tmp/iop-go-cache` preflight는 성공했다.
- 최종 검증 명령은 fresh 실행을 위해 `-count=1`을 사용한다.
### 테스트 커버리지 공백
- Chat Completions provider-pool에는 selected OpenAI-compatible tunnel, Ollama normalized, mixed pool 테스트가 이미 있다.
- Responses provider-pool은 현재 provider-pool이면 selected execution path와 무관하게 tunnel로 가는 테스트가 중심이라 Ollama/CLI/native normalized selection coverage가 없다.
- `SubmitProviderTunnel`은 provider-pool admission 후 selected execution path를 gate하지 않으므로 Responses provider-pool에서 그대로 쓰면 normalized provider도 tunnel로 갈 수 있다.
### 심볼 참조
- 변경 가능 대상:
- `routeUsesProviderTunnel(dispatch)`: `chat_handler.go`, `responses_handler.go`. Responses provider-pool 직접 tunnel 조건에서 분리 필요.
- `tunnelResponsesPassthrough`: `responses_handler.go`, `server_test.go`. Legacy direct provider tunnel과 selected OpenAI-compatible provider-pool에서만 사용해야 한다.
- `service.ProviderPoolDispatchRequest`: `run_dispatch.go`, `chat_handler.go`, fake run service in `server_test.go`. Responses normalized build를 selected path 후에 준비하려면 hook 추가 가능성이 있다.
- `SubmitProviderPool`: `run_dispatch.go`, tests. Chat path는 유지하고 Responses path를 추가한다.
### 분할 판단
- Split decision policy를 적용했다.
- Shared task group: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/`.
- Sibling tasks:
- `01_selector_metadata_surface`: selector/header/envelope/metadata 표면 제거.
- `02+01_model_route_dispatch`: 이 계획. predecessor index `01` 필요.
- Predecessor resolution:
- Active candidate `agent-task/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log`: 현재 없음.
- Archive lookup은 수행하지 않았다. 새로 생성한 sibling이므로 구현은 active predecessor `complete.log`가 생긴 뒤 시작한다.
### 범위 결정 근거
- 이 작업은 provider-pool selected execution path에 따른 Responses dispatch와 관련 tests에 한정한다.
- selector/sideband/metadata cleanup은 `01_selector_metadata_surface` 완료를 전제로 하며 이 계획에서 다시 도입하지 않는다.
- Node adapter의 tunnel payload relay와 normalized adapter mapping은 기존 contract 검증 범위로 둔다. 필요한 경우 테스트만 실행한다.
- provider candidate scoring, queue admission, model registry schema는 변경하지 않는다.
### 빌드 등급
- `local-G06`: 범위는 Edge Responses handler와 service dispatch hook/test로 좁고 모든 기대 동작이 SDD/contract와 기존 Chat provider-pool 패턴에 고정되어 있으며 local Go test로 검증 가능하다.
## 구현 체크리스트
- [ ] [API-1] Responses provider-pool에서 selected provider execution path에 따라 passthrough 또는 normalized run을 선택하도록 dispatch를 정리한다.
- [ ] [API-2] Responses provider-pool tunnel/normalized selection 회귀 테스트를 추가하고 기존 Chat model-route 테스트를 보존한다.
- [ ] [API-3] provider-pool dispatch, OpenAI handler, node adapter 검증 명령을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 의존 관계 및 구현 순서
`02+01_model_route_dispatch`는 subtask directory 이름 기준으로 predecessor `01_selector_metadata_surface`에만 의존한다. 구현 시작 전 `agent-task/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log`가 존재하는지 확인하고, 없으면 구현하지 말고 `검증 결과` 또는 보고에 missing predecessor로 기록한다.
### [API-1] Responses Provider-Pool Dispatch
#### 문제
Responses handler는 provider-pool route도 `routeUsesProviderTunnel(dispatch)`에서 바로 tunnel로 보내 selected provider execution path를 확인하지 못한다.
```go
// apps/edge/internal/openai/responses_handler.go:49
if routeUsesProviderTunnel(dispatch) {
if req.Background != nil && *req.Background {
writeOpenAIError(w, http.StatusBadRequest, "invalid_request_error", "background mode is not supported")
return
}
```
`SubmitProviderTunnel`의 provider-pool path도 selected candidate가 normalized provider인지 확인하지 않고 tunnel 요청을 만든다.
```go
// apps/edge/internal/service/run_dispatch.go:1134
func (s *RunService) SubmitProviderTunnel(ctx context.Context, req ProviderTunnelRequest) (ProviderTunnelResult, error) {
if req.Dispatch.ProviderPool {
return s.submitProviderTunnelQueued(ctx, req)
}
```
#### 해결 방법
Responses provider-pool은 Chat provider-pool처럼 `SubmitProviderPool`을 사용한다. selected path가 `providerExecutionPathTunnel`이면 raw Responses body를 model rewrite만 적용해 provider tunnel로 보낸다. selected path가 `providerExecutionPathRun`이면 Responses request를 normalized `RunRequest`로 변환해 `dispatchProviderPoolRun`을 사용한다.
권장 구현은 `service.ProviderPoolDispatchRequest`에 선택 후 normalized request를 준비하는 hook을 추가하는 것이다. 이렇게 하면 tunnel 선택에서는 strict normalized decode 때문에 raw passthrough가 막히지 않고, run 선택에서만 Responses normalized validation을 수행할 수 있다.
```go
// after sketch in apps/edge/internal/service/run_dispatch.go
type ProviderPoolDispatchRequest struct {
Dispatch ModelDispatch
Model string
Prompt string
Run RunRequest
Tunnel ProviderTunnelRequest
PrepareTunnel func(SelectedProvider) (ProviderTunnelRequest, error)
PrepareRun func(SelectedProvider) (RunRequest, error)
}
```
```go
// after sketch in SubmitProviderPool normalized branch
runReq := req.Run
if req.PrepareRun != nil {
runReq, err = req.PrepareRun(selected)
if err != nil {
return ProviderPoolDispatchResult{}, err
}
}
return s.dispatchProviderPoolRun(ctx, candidateNode, providerKey, providerType, req, runReq)
```
#### 수정 파일 및 체크리스트
- [ ] `apps/edge/internal/service/run_dispatch.go`: optional `PrepareRun` hook 또는 동등한 selected-after-prepare 구조를 추가한다.
- [ ] `apps/edge/internal/openai/responses_handler.go`: provider-pool Responses path를 `SubmitProviderPool` 기반으로 분리한다.
- [ ] `apps/edge/internal/openai/chat_handler.go`: shared helper signature 변경 시 Chat compile을 맞춘다. Chat 동작은 변경하지 않는다.
- [ ] `apps/edge/internal/openai/server_test.go`: fake run service가 새 hook을 지원하도록 갱신한다.
#### 테스트 작성
- `apps/edge/internal/openai/server_test.go`
- `TestResponsesProviderPoolTunnelSelectionUsesPassthrough`: selected OpenAI-compatible provider는 tunnel을 사용하고 raw body와 model rewrite를 보존한다.
- `TestResponsesProviderPoolOllamaSelectionUsesNormalizedRun`: selected Ollama/native provider는 tunnel을 호출하지 않고 normalized `RunRequest`를 submit한다.
- mixed provider-pool에서 selected provider type에 따라 tunnel/run이 갈리는지 Chat 기존 테스트와 같은 fixture로 검증한다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Tunnel|Ollama|Native|Normalized|Mixed)|TestChatCompletions.*ProviderPool' -count=1
```
예상 결과: Responses provider-pool OpenAI-compatible selection은 tunnel PASS, Ollama/native selection은 normalized run PASS.
### [API-2] Route Test Coverage Preservation
#### 문제
Chat은 이미 model-route 회귀 테스트가 있지만 Responses 테스트는 raw tunnel assumption에 묶여 있어 SDD S02/S03를 둘 다 보장하지 못한다.
```go
// apps/edge/internal/openai/server_test.go:6128
func TestResponsesProviderPoolDispatch(t *testing.T) {
```
#### 해결 방법
Responses 기존 provider-pool passthrough 테스트는 OpenAI-compatible selected path 기준으로 유지하고, normalized selected path 테스트를 추가한다. Chat provider-pool tests는 compile 실패가 없도록 fake service 변경만 맞춘다.
```go
// after sketch
func TestResponsesProviderPoolOllamaSelectionUsesNormalizedRun(t *testing.T) {
// selected provider type: ollama
// assert SubmitRun path and no tunnel payload
}
```
#### 수정 파일 및 체크리스트
- [ ] `apps/edge/internal/openai/server_test.go`: Responses provider-pool tunnel/normalized/mixed tests 추가 또는 갱신.
- [ ] `apps/edge/internal/service/model_queue_test.go`: execution path classification 테스트가 깨지지 않는지 확인한다. 필요 시 새 hook 관련 테스트만 추가한다.
#### 테스트 작성
- Regression test required.
- 기존 Chat tests가 이미 SDD의 Chat portion을 덮으므로 새 Chat test는 compile/update가 필요한 경우에만 추가한다.
- Responses normalized path는 test name과 assertion을 명확히 추가한다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1
```
예상 결과: provider execution path classification PASS.
### [API-3] Final Route Verification
#### 문제
Responses provider-pool fix는 Edge handler, service dispatch interface, fake tests를 함께 건드리므로 package 단위 회귀가 필요하다.
#### 해결 방법
Edge OpenAI handler, service, node OpenAI-compatible adapter package를 fresh test로 실행한다. selector cleanup plan 이후 문자열 검색이 이미 완료되어 있어야 하며, 이 plan은 model-route behavior만 검증한다.
#### 수정 파일 및 체크리스트
- [ ] `apps/edge/internal/openai` 전체 테스트 실행.
- [ ] `apps/edge/internal/service` 전체 테스트 실행.
- [ ] `apps/node/internal/adapters/openai_compat` 전체 테스트 실행.
#### 테스트 작성
- 이 항목은 추가 테스트 작성 항목이 아니라 plan-wide verification 항목이다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
```
예상 결과: 세 package 모두 PASS.
## 수정 파일 요약
| 파일 | 항목 |
|------|------|
| `apps/edge/internal/openai/responses_handler.go` | API-1 |
| `apps/edge/internal/openai/chat_handler.go` | API-1 |
| `apps/edge/internal/service/run_dispatch.go` | API-1 |
| `apps/edge/internal/openai/server_test.go` | API-1, API-2 |
| `apps/edge/internal/service/model_queue_test.go` | API-2 |
| `apps/node/internal/adapters/openai_compat/openai_compat_test.go` | API-3 |
## 최종 검증
```bash
test -f agent-task/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log
```
예상 결과: exit status 0. 없으면 이 subtask 구현을 시작하지 않는다.
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
```
예상 결과: 세 package 모두 PASS.
```bash
bash -lc 'rg --sort path "routeUsesProviderTunnel\\(dispatch\\)" apps/edge/internal/openai/responses_handler.go || test "$?" -eq 1'
```
예상 결과: provider-pool Responses를 무조건 tunnel로 보내는 조건이 남지 않는다. legacy direct provider tunnel 조건이 남는 경우 해당 분기가 provider-pool과 분리되어 있음을 코드리뷰에서 확인한다.
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.

366
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/plan_local_G06_1.log Normal file
View file

@ -0,0 +1,366 @@
<!-- task=m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch plan=1 tag=REVIEW_API -->
# Plan - Review Follow-up for Responses Provider-Pool Dispatch
## 이 파일을 읽는 구현 에이전트에게
이 follow-up은 이전 리뷰의 Required 이슈 2개만 고친다. 구현 완료 전에는 반드시 같은 디렉터리의 `CODE_REVIEW-local-G06.md`에서 구현 에이전트 소유 섹션을 실제 변경 내용과 검증 출력으로 채운다.
선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 막는 경우에만 review stub의 `사용자 리뷰 요청` 섹션을 정확한 근거와 함께 채우고 멈춘다. 구현 중 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 외부 환경, secret, 서비스 준비, 일반 범위 조정, 검증 증거 공백은 사용자 리뷰 요청이 아니며 `검증 결과` 또는 `계획 대비 변경 사항`에 기록한다. `USER_REVIEW.md`, `complete.log`, archive 이동은 code-review-skill 전용이다.
## 배경
이전 구현은 Responses provider-pool을 `SubmitProviderPool` 기반으로 옮겼지만, `stream:true`와 strict decode 실패 경로에서 selected provider를 보기 전에 tunnel로 결정하거나 `Run` 없이 `SubmitProviderPool`을 호출한다. 그 결과 OpenAI-compatible provider passthrough와 Ollama/CLI/native normalized path를 같은 model-driven 선택 규칙으로 보장하지 못한다. 이 follow-up은 selected-after-prepare 구조를 추가해 tunnel branch는 raw body를 보존하고 normalized branch만 strict validation을 수행하게 한다.
## 사용자 리뷰 요청 흐름
구현 중 새 결정이 필요해 보여도 직접 질문하지 않는다. 선택된 Milestone lock decision이 실제 구현을 차단할 때만 `CODE_REVIEW-local-G06.md`의 `사용자 리뷰 요청` 섹션에 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 기록하고 code-review가 `USER_REVIEW.md` 작성 여부를 판단한다.
## Archive Evidence Snapshot
- Current archived plan: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/plan_local_G06_0.log`
- Current archived review: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/code_review_local_G06_0.log`
- Verdict: FAIL
- Required summary:
- `apps/edge/internal/openai/responses_handler.go:230`: provider-pool `stream:true` is sent to `tunnelResponsesPassthrough` before selected provider execution path is known.
- `apps/edge/internal/openai/responses_handler.go:277`: strict decode failure calls `SubmitProviderPool` with `Run.ModelGroupKey` empty, while real service resolves candidates from `req.Run`.
- Affected files:
- `apps/edge/internal/openai/responses_handler.go`
- `apps/edge/internal/service/run_dispatch.go`
- `apps/edge/internal/openai/server_test.go`
- Verification evidence from failed loop:
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Tunnel|Ollama|Native|Normalized|Mixed)|TestChatCompletions.*ProviderPool' -count=1` PASS, but fake service did not catch missing `Run.ModelGroupKey`.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1` PASS.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1` PASS.
- Roadmap carryover:
- Milestone task remains `model-route`.
- Predecessor satisfied by `agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log`.
- Specific archive files above may be read if exact prior context is needed. Do not search `agent-task/archive/**` broadly.
## Roadmap Targets
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Task ids:
- `model-route`: Chat Completions와 Responses에서 `model` -> route/provider capability -> passthrough 또는 normalized 경로를 사용
- Completion mode: check-on-pass
## 분석 결과
### 읽은 파일
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-roadmap/current.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/code-review/SKILL.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
- `agent-ops/rules/project/domain/edge/rules.md`
- `agent-ops/rules/project/domain/testing/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/edge-smoke.md`
- `agent-test/local/node-smoke.md`
- `agent-test/local/platform-common-smoke.md`
- `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- `agent-roadmap/sdd/routing-policy-model-orchestration/openai-compatible-provider-passthrough-contract-sync/SDD.md`
- `agent-contract/index.md`
- `agent-contract/outer/openai-compatible-api.md`
- `agent-contract/inner/edge-node-runtime-wire.md`
- `apps/edge/internal/openai/responses_handler.go`
- `apps/edge/internal/openai/chat_handler.go`
- `apps/edge/internal/openai/server_test.go`
- `apps/edge/internal/openai/types.go`
- `apps/edge/internal/service/run_dispatch.go`
### SDD 기준
- SDD: `agent-roadmap/sdd/routing-policy-model-orchestration/openai-compatible-provider-passthrough-contract-sync/SDD.md`
- Status: `[승인됨]`, SDD lock 해제.
- Targeted Acceptance Scenarios:
- `S02` / `model-route`: OpenAI-compatible provider 선택 시 provider tunnel passthrough.
- `S03` / `model-route`: CLI/Ollama/native provider 선택 시 normalized `RunRequest`.
- Evidence Map 반영:
- `S02`는 Responses unknown/stream passthrough가 `SubmitProviderPool` 선택 이후 tunnel branch에서만 발생하는 테스트로 증명한다.
- `S03`은 Responses unknown/stream 요청이 normalized provider 선택 시 tunnel로 가지 않고 400 validation 또는 normalized path 규칙을 따르는 테스트로 증명한다.
### 테스트 환경 규칙
- test_env: `local`.
- `agent-test/local/rules.md`를 읽었다.
- Matched profiles: `agent-test/local/edge-smoke.md`, `agent-test/local/node-smoke.md`, `agent-test/local/platform-common-smoke.md`.
- 적용 명령: 변경 패키지 Go test와 Edge OpenAI handler/service/node adapter 관련 package test.
- 외부 provider credential이나 field smoke는 이 follow-up 범위가 아니다. 변경은 deterministic unit test로 재현 가능하다.
### 테스트 커버리지 공백
- 기존 Responses provider-pool tests는 fake service가 `ProviderPoolDispatchRequest.Run.ModelGroupKey`를 검증하지 않아 real `SubmitProviderPool`와 달랐다.
- 기존 테스트에는 `stream:true` 요청에서 selected provider가 normalized인 케이스가 없다.
- 기존 테스트에는 Responses unknown field 요청에서 selected provider가 normalized인 케이스가 없다.
- 기존 tunnel unknown-field 테스트는 fake tunnel path만 확인하고, `SubmitProviderPool`에 complete Run request가 전달되는지 보지 않는다.
### 심볼 참조
- `ProviderPoolDispatchRequest`: `apps/edge/internal/service/run_dispatch.go`, `apps/edge/internal/openai/chat_handler.go`, `apps/edge/internal/openai/responses_handler.go`, `apps/edge/internal/openai/server_test.go`.
- `SubmitProviderPool`: service implementation and fake in `apps/edge/internal/openai/server_test.go`.
- `tunnelResponsesPassthrough`: `responses_handler.go` direct non-provider tunnel path and current provider-pool stream shortcut.
### 분할 판단
- Split decision policy를 재평가했다.
- Shared task group: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/`.
- Current subtask: `02+01_model_route_dispatch`.
- Predecessor `01_selector_metadata_surface` is satisfied by `agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log`.
- Follow-up은 같은 Responses provider-pool dispatch correction 안의 좁은 repair이며, 별도 split은 필요 없다.
### 범위 결정 근거
- 포함: `ProviderPoolDispatchRequest`의 optional run preparation, Responses provider-pool handler 분기, fake service/test coverage.
- 제외: Chat behavior change, provider scoring/queue policy, Node adapter implementation, contract 문서 갱신, dev-corp live provider smoke.
- Chat handler는 새 optional field로 compile이 깨지지 않게만 유지한다.
### 빌드 등급
- `local-G06`: Edge handler와 service dispatch surface의 bounded bug fix이며, contract가 명확하고 deterministic Go tests로 검증 가능하다.
## 구현 체크리스트
- [x] [REVIEW_API-1] `SubmitProviderPool`에 selected normalized branch에서만 `Run`을 준비/검증하는 optional hook을 추가한다.
- [x] [REVIEW_API-2] Responses provider-pool handler에서 stream/unknown-field 판단을 selected provider 이후로 옮기고, tunnel branch는 raw body passthrough를 유지한다.
- [x] [REVIEW_API-3] Responses provider-pool stream/unknown-field mixed path regression tests와 fake service guard를 추가한다.
- [x] [REVIEW_API-4] provider-pool dispatch, OpenAI handler, node adapter 검증 명령을 실행한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 의존 관계 및 구현 순서
`02+01_model_route_dispatch`는 predecessor `01_selector_metadata_surface` 완료 후 진행한다. 해당 predecessor는 archive complete log로 충족되어 있으므로 이 follow-up 구현을 진행할 수 있다.
### [REVIEW_API-1] ProviderPool Run Preparation Hook
#### 문제
`SubmitProviderPool`은 후보 선택을 `req.Run`에서 시작한다.
```go
// apps/edge/internal/service/run_dispatch.go:954
candidates, policy, err := s.resolveQueueCandidates(req.Run)
```
그런데 이전 Responses strict decode 실패 fallback은 `Run`을 비운 채 `Tunnel`만 채웠다.
```go
// apps/edge/internal/openai/responses_handler.go:277
poolReq := edgeservice.ProviderPoolDispatchRequest{
Tunnel: edgeservice.SubmitProviderTunnelRequest{
```
#### 해결 방법
`ProviderPoolDispatchRequest`에 optional `PrepareRun func(SubmitRunRequest) (SubmitRunRequest, error)`를 추가한다. `SubmitProviderPool`은 candidate를 고른 뒤 `providerExecutionPathNormalized` branch에서만 이 hook을 호출하고, 반환된 request를 `dispatchProviderPoolRun`에 넘긴다. Tunnel branch에서는 호출하지 않는다.
```go
// after
type ProviderPoolDispatchRequest struct {
Run SubmitRunRequest
Tunnel SubmitProviderTunnelRequest
PrepareTunnel prepareTunnelFunc
PrepareRun prepareRunFunc
}
```
```go
// after
case providerExecutionPathNormalized:
runReq := req.Run
if req.PrepareRun != nil {
runReq, err = req.PrepareRun(runReq)
if err != nil {
s.queue.releaseSlotWithLong(req.Run.ModelGroupKey, selected.entry.NodeID, selected.providerID, longReserved)
return nil, err
}
}
return s.dispatchProviderPoolRun(ctx, runReq, adapter, target, selected, queueReason, longReserved)
```
#### 수정 파일 및 체크리스트
- [x] `apps/edge/internal/service/run_dispatch.go`: `prepareRunFunc`와 `PrepareRun` field를 추가하고 normalized branch에서만 호출한다.
- [x] `apps/edge/internal/openai/chat_handler.go`: compile 영향만 확인한다. Chat behavior는 변경하지 않는다.
- [x] `apps/edge/internal/openai/server_test.go`: fake `SubmitProviderPool`도 normalized path에서 `PrepareRun`을 호출하도록 맞춘다.
#### 테스트 작성
- `apps/edge/internal/openai/server_test.go`: fake service가 `SubmitProviderPool` 요청의 `Run.ModelGroupKey`가 비면 테스트 실패/에러가 나도록 guard를 둔다.
- Service 단위 helper가 이미 있으면 `PrepareRun`이 normalized branch에서만 호출되는 테스트를 추가한다. 복잡한 registry fixture가 과하면 openai fake regression으로 대체하고 그 이유를 `계획 대비 변경 사항`에 적는다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Unknown|Streaming|Tunnel|Ollama|Mixed)' -count=1
```
예상 결과: Responses provider-pool regression tests PASS.
### [REVIEW_API-2] Responses Selected-After-Prepare Dispatch
#### 문제
`stream:true` provider-pool 요청은 selected provider를 확인하기 전에 tunnel로 보내진다.
```go
// apps/edge/internal/openai/responses_handler.go:230
if env.Stream {
...
s.tunnelResponsesPassthrough(w, r, env, dispatch, runMeta, rawBody, estimate, contextClass)
return
}
```
이 경로는 normalized provider 선택 시에도 `SubmitProviderTunnel` queued path를 사용할 수 있어 SDD S03을 깬다.
#### 해결 방법
Responses provider-pool handler는 항상 populated base `Run`과 `Tunnel`을 가진 `ProviderPoolDispatchRequest`를 만든다. Tunnel branch는 `BuildBody`로 `rewriteResponsesModel(rawBody, target)`만 수행한다. Normalized branch의 strict decode, `stream/background` rejection, `parseResponsesInput`, prompt/options/generation policy 구성은 `PrepareRun` closure 안에서 수행한다.
Validation error는 HTTP 400 `invalid_request_error`로 반환되도록 typed error 또는 sentinel wrapping을 사용한다. Provider auth error는 기존처럼 400, backend dispatch error는 502로 유지한다.
#### 수정 파일 및 체크리스트
- [x] `apps/edge/internal/openai/responses_handler.go`: `env.Stream` pre-selection tunnel shortcut을 제거한다.
- [x] `apps/edge/internal/openai/responses_handler.go`: strict decode 실패 전용 tunnel fallback branch를 제거하고 `PrepareRun`으로 이동한다.
- [x] `apps/edge/internal/openai/responses_handler.go`: `SubmitProviderPool` error handling에서 normalized validation error를 400으로 매핑한다.
- [x] `apps/edge/internal/openai/responses_handler.go`: non-provider direct tunnel path는 기존 `tunnelResponsesPassthrough`를 유지한다.
#### 테스트 작성
- `TestResponsesProviderPoolTunnelUnknownFieldsUsesPoolSelection`: OpenAI-compatible selected path에서 `tools`, `parallel_tool_calls`, `store`, custom field가 raw tunnel body에 보존되고 `Run.ModelGroupKey`가 채워진 채 `SubmitProviderPool`을 통과한다.
- `TestResponsesProviderPoolOllamaSelectionRejectsUnknownFieldsWithoutTunnel`: normalized selected path에서 unknown field 요청은 400이며 tunnel/run dispatch가 발생하지 않는다.
- `TestResponsesProviderPoolOllamaSelectionRejectsStreamingWithoutTunnel`: normalized selected path에서 `stream:true` 요청은 400이며 tunnel dispatch가 발생하지 않는다.
- `TestResponsesProviderPoolTunnelStreamingUsesPoolSelection`: tunnel selected path에서 `stream:true`는 `SubmitProviderPool`을 통해 tunnel로 relay되고 raw SSE body를 보존한다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(UnknownFields|Streaming|TunnelSelection|OllamaSelection|Mixed)' -count=1
```
예상 결과: tunnel selected path는 passthrough, normalized selected path는 validation/no-tunnel behavior를 증명한다.
### [REVIEW_API-3] Test Double Fidelity
#### 문제
이전 tests는 PASS했지만 fake `SubmitProviderPool`가 real service의 candidate resolution requirement를 재현하지 않았다. real service는 `req.Run.ModelGroupKey`를 반드시 필요로 한다.
#### 해결 방법
fake service에 pool call recording과 request guard를 추가한다. `SubmitProviderPool`가 호출된 횟수, `Run.ModelGroupKey`, path별 `PrepareRun`/`PrepareTunnel` 호출 여부를 tests에서 검증할 수 있게 한다.
#### 수정 파일 및 체크리스트
- [x] `apps/edge/internal/openai/server_test.go`: fake service에 `poolReqs` 또는 equivalent snapshot을 추가한다.
- [x] `apps/edge/internal/openai/server_test.go`: normalized path에서 `PrepareRun` 결과를 `reqs`에 기록한다.
- [x] `apps/edge/internal/openai/server_test.go`: tunnel path에서는 `PrepareRun`이 호출되지 않음을 검증할 수 있게 한다.
#### 테스트 작성
- REVIEW_API-2의 regression tests가 이 fake fidelity를 직접 사용한다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*|TestChatCompletions.*ProviderPool' -count=1
```
예상 결과: 기존 Chat provider-pool tests는 behavior 변경 없이 PASS.
### [REVIEW_API-4] Final Verification
#### 문제
변경은 Edge OpenAI handler, service dispatch surface, fake tests를 함께 건드리므로 focused와 package-level 검증이 필요하다.
#### 해결 방법
아래 최종 검증 명령을 fresh test로 실행하고 stdout/stderr를 review stub에 붙인다.
#### 수정 파일 및 체크리스트
- [x] `apps/edge/internal/openai` focused tests 실행.
- [x] `apps/edge/internal/service` provider-pool classification tests 실행.
- [x] OpenAI/service/node adapter package tests 실행.
- [x] deterministic `rg`로 provider-pool Responses가 pre-selection tunnel shortcut을 남기지 않았는지 확인한다.
#### 테스트 작성
- 이 항목은 추가 테스트 작성 항목이 아니라 plan-wide verification 항목이다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
```
예상 결과: 세 package 모두 PASS.
## 수정 파일 요약
| 파일 | 항목 |
|------|------|
| `apps/edge/internal/service/run_dispatch.go` | REVIEW_API-1 |
| `apps/edge/internal/openai/responses_handler.go` | REVIEW_API-1, REVIEW_API-2 |
| `apps/edge/internal/openai/chat_handler.go` | REVIEW_API-1 compile compatibility |
| `apps/edge/internal/openai/server_test.go` | REVIEW_API-1, REVIEW_API-2, REVIEW_API-3 |
## PLAN 대비 변경 사항
1. **Chat handler에도 `PrepareRun` 설정 추가**: 계획에서는 `chat_handler.go`를 compile 영향만 확인하는 것으로만 명시했지만, fake service의 `req.PrepareRun == nil` guard로 인해 chat handler도 `PrepareRun`을 설정해야 했다. Chat은 lenient decode를 사용하므로 `PrepareRun`은 identity function으로 처리한다.
2. **Fake service에서 `poolPrepareRunCalled` 설정 위치 조정**: 계획에서는 `PrepareRun` 호출 성공 후 `poolPrepareRunCalled = true`를 설정하는 것으로 명시했지만, normalized path에서 validation error 발생 시 호출은 되었으나 `poolPrepareRunCalled`가 false가 되는 문제를 발견하여, 호출 시점(에러 여부 무관)에 설정하도록 수정했다.
3. **Fake service에서 디버깅용 panic 제거**: 기존 구현에 남아있던 `panic(fmt.Sprintf("DEBUG after setting poolPrepareRunCalled=true: ..."))` 코드를 제거했다.
4. **`poolRetrySubmit`에도 `PrepareRun` 전달**: Chat handler의 tool validation retry 경로에서 `SubmitProviderPool` 호출 시 `PrepareRun`도 전달하도록 수정했다.
## 최종 검증
```bash
test -f agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log
```
예상 결과: exit status 0.
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Unknown|Streaming|Tunnel|Ollama|Mixed)|TestChatCompletions.*ProviderPool' -count=1
```
```
ok ipop/apps/edge/internal/openai 0.012s
```
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1
```
```
ok ipop/apps/edge/internal/service 0.004s
```
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
```
```
ok ipop/apps/edge/internal/openai 6.732s
ok ipop/apps/edge/internal/service 1.051s
ok ipop/apps/node/internal/adapters/openai_compat 0.123s
```
```bash
bash -lc 'rg --sort path "tunnelResponsesPassthrough\\(w, r, env, dispatch" apps/edge/internal/openai/responses_handler.go'
```
```
apps/edge/internal/openai/responses_handler.go:115: s.tunnelResponsesPassthrough(w, r, env, dispatch, runMeta, rawBody, estimate, contextClass)
```
_해당 호출은 non-provider direct tunnel path에서만 발생하며, provider-pool pre-selection branch에서는 호출되지 않는다._
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.

190
agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/plan_local_G06_2.log Normal file
View file

@ -0,0 +1,190 @@
<!-- task=m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch plan=2 tag=REVIEW_REVIEW_API -->
# Plan - Review Follow-up for Responses Provider-Pool Dispatch
## 이 파일을 읽는 구현 에이전트에게
이 follow-up은 이전 리뷰의 Required 이슈 3개만 고친다. 구현 완료 전에는 반드시 같은 디렉터리의 `CODE_REVIEW-local-G06.md`에서 구현 에이전트 소유 섹션을 실제 변경 내용과 검증 출력으로 채운다.
선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 막는 경우에만 review stub의 `사용자 리뷰 요청` 섹션을 정확한 근거와 함께 채우고 멈춘다. 구현 중 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 외부 환경, secret, 서비스 준비, 일반 범위 조정, 검증 증거 공백은 사용자 리뷰 요청이 아니며 `검증 결과` 또는 `계획 대비 변경 사항`에 기록한다. `USER_REVIEW.md`, `complete.log`, archive 이동은 code-review-skill 전용이다.
## 배경
이전 loop는 Responses provider-pool을 selected-after-prepare 구조로 옮겼고 targeted Go tests는 통과했다. 하지만 리뷰에서 production debug/panic, normalized Responses strict-output policy 손실, provider-pool tunnel metadata/estimate/context 손실이 확인되었다. 이 follow-up은 model-route Task를 계속 닫기 위한 좁은 repair다.
## 사용자 리뷰 요청 흐름
구현 중 새 결정이 필요해 보여도 직접 질문하지 않는다. 선택된 Milestone lock decision이 실제 구현을 차단할 때만 `CODE_REVIEW-local-G06.md`의 `사용자 리뷰 요청` 섹션에 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 기록하고 code-review가 `USER_REVIEW.md` 작성 여부를 판단한다.
## Archive Evidence Snapshot
- Current archived plan: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/plan_local_G06_1.log`
- Current archived review: `agent-task/m-openai-compatible-provider-passthrough-contract-sync/02+01_model_route_dispatch/code_review_local_G06_1.log`
- Verdict: FAIL
- Required summary:
- `apps/edge/internal/openai/responses_handler.go:373`: production handler still logs `DEBUG handleResponsesProviderPool` and keeps a nil `PrepareRun` panic guard.
- `apps/edge/internal/openai/responses_handler.go:432`: normalized provider-pool Responses discards the prepared `responsesRequest`/strict output policy and calls `completeResponse` with `s.resolveOutputPolicy("")`.
- `apps/edge/internal/openai/responses_handler.go:249`: provider-pool base `Run`/`Tunnel` omit metadata, `EstimatedInputTokens`, and `ContextClass`, so tunnel dispatch loses observability/long-context context.
- Affected files:
- `apps/edge/internal/openai/responses_handler.go`
- `apps/edge/internal/openai/server_test.go`
- `apps/edge/internal/openai/chat_handler.go` only if the identity `PrepareRun` was added solely for the fake-service panic guard and can be safely removed.
- `apps/edge/internal/service/run_dispatch.go` only if service-level copy semantics need a focused regression test.
- Verification evidence from failed loop:
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Unknown|Streaming|Tunnel|Ollama|Mixed)|TestChatCompletions.*ProviderPool' -count=1` PASS.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1` PASS.
- `GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1` PASS.
- `git diff --check` PASS.
- Roadmap carryover:
- Milestone task remains `model-route`.
- SDD target scenarios remain S02/S03/S09.
- Predecessor satisfied by `agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log`.
- Specific archive files above may be read if exact prior context is needed. Do not search `agent-task/archive/**` broadly.
## Roadmap Targets
- Milestone: `agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/routing-policy-model-orchestration/milestones/openai-compatible-provider-passthrough-contract-sync.md)
- Task ids:
- `model-route`: Chat Completions와 Responses에서 `model` -> route/provider capability -> passthrough 또는 normalized 경로를 사용
- Completion mode: check-on-pass
## 분석 결과
### SDD 기준
- SDD: `agent-roadmap/sdd/routing-policy-model-orchestration/openai-compatible-provider-passthrough-contract-sync/SDD.md`
- Status: `[승인됨]`, SDD lock 해제.
- Targeted Acceptance Scenarios:
- `S02` / `model-route`: OpenAI-compatible provider 선택 시 provider tunnel passthrough.
- `S03` / `model-route`: CLI/Ollama/native provider 선택 시 normalized `RunRequest`.
- `S09` / `go-tests`: 관련 Go test evidence.
### 범위 결정 근거
- 포함: Responses provider-pool handler repair, fake service/test cleanup, strict-output normalized Responses regression, tunnel metadata/context propagation tests.
- 제외: provider scoring/queue policy 변경, Node adapter runtime 변경, contract 문서 갱신, dev-corp live provider smoke.
- Follow-up route: `local-G06`. 변경 범위가 bounded이고 deterministic Go tests로 검증 가능하다.
## 구현 체크리스트
- [ ] [REVIEW_REVIEW_API-1] production/test debug-only artifacts를 제거하고 fake service의 optional `PrepareRun` 동작을 실제 service 계약과 맞춘다.
- [ ] [REVIEW_REVIEW_API-2] Responses provider-pool normalized branch가 `PrepareRun`에서 준비한 request와 strict output policy를 `completeResponse`에 전달하게 한다.
- [ ] [REVIEW_REVIEW_API-3] Responses provider-pool tunnel branch가 metadata, `EstimatedInputTokens`, `ContextClass`를 pool request와 tunnel dispatch에 보존하게 한다.
- [ ] [REVIEW_REVIEW_API-4] focused regression tests와 최종 package 검증 명령을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 의존 관계 및 구현 순서
`02+01_model_route_dispatch`는 predecessor `01_selector_metadata_surface` 완료 후 진행한다. 해당 predecessor는 archive complete log로 충족되어 있으므로 이 follow-up 구현을 진행할 수 있다.
### [REVIEW_REVIEW_API-1] Debug Artifact Cleanup
#### 문제
`handleResponsesProviderPool`에 production debug log와 panic guard가 남아 있다. 또한 `server_test.go`에는 Debug 전용 테스트와 fake service panic guard가 남아 있어 optional `PrepareRun` 계약을 테스트 더블이 과하게 제한한다.
#### 해결 방법
- `apps/edge/internal/openai/responses_handler.go`: `DEBUG handleResponsesProviderPool` 로그와 nil `PrepareRun` panic guard를 제거한다.
- `apps/edge/internal/openai/server_test.go`: `TestResponsesProviderPoolDebugOllamaNormalizeCheck`, `TestResponsesProviderPoolDebugHandleResponses`, debug `t.Logf`, direct mutex value 확인을 제거하거나 의미 있는 regression test로 병합한다.
- `apps/edge/internal/openai/server_test.go`: fake `SubmitProviderPool`에서 `req.PrepareRun == nil`이면 panic하는 guard를 제거한다. `PrepareRun`은 service 계약상 optional이며 normalized path에서 hook이 있으면 호출되고 tunnel path에서는 호출되지 않는 동작만 필요한 테스트에서 assertion한다.
- `apps/edge/internal/openai/chat_handler.go`: identity `PrepareRun`이 fake panic을 피하기 위한 코드였는지 재검토한다. 실제 retry 흐름이나 symmetry를 위해 유지해도 되지만, fake guard 때문에 production 코드를 추가한 상태로 두지 않는다.
#### 중간 검증
```bash
rg --sort path 'DEBUG handleResponsesProviderPool|TestResponsesProviderPoolDebug|panic\("fake SubmitProviderPool|panic\("poolReq.PrepareRun' apps/edge/internal/openai
```
예상 결과: 관련 debug/panic artifact 출력 없음.
### [REVIEW_REVIEW_API-2] Prepared Responses Output Policy
#### 문제
Normalized provider-pool Responses는 `PrepareRun` 안에서 strict decode, prompt build, `outputPolicy := s.resolveOutputPolicy(prompt)`를 수행하지만, 결과 조립 시 `responsesRequest{Model: env.Model}`와 `s.resolveOutputPolicy("")`를 넘긴다. XML completion contract가 있는 strict-output prompt에서는 non-provider normalized Responses와 달리 response wrapping/normalization이 깨질 수 있다.
#### 해결 방법
- `handleResponsesProviderPool` request-local scope에 prepared `responsesRequest`와 `strictOutputPolicy`를 저장한다.
- `PrepareRun`이 decode/prompt/policy 준비를 성공하면 해당 값을 채우고, normalized result branch에서 이 값을 `completeResponse(w, r, preparedReq, handle, preparedOutputPolicy)`로 전달한다.
- normalized result인데 `PrepareRun`이 성공적으로 실행되지 않은 불일치 상태는 500 `run_error`로 명확히 처리한다.
- `TestResponsesStrictOutputNormalizesAgentResponse`와 유사한 provider-pool normalized regression test를 추가한다. provider-pool selected path가 normalized일 때 prompt에 XML completion contract가 있으면 response `output_text`가 expected XML block으로 wrapping되는지 확인한다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*StrictOutput|TestResponsesStrictOutputNormalizesAgentResponse' -count=1
```
예상 결과: provider-pool normalized strict-output regression과 기존 non-provider strict-output test PASS.
### [REVIEW_REVIEW_API-3] Responses Pool Tunnel Metadata And Context
#### 문제
새 provider-pool Responses path는 selection 전에 `baseRun`/`baseTunnel`을 만들지만 metadata, estimate, context class를 채우지 않는다. Real `SubmitProviderPool`은 `req.Run.ContextClass`로 long admission을 판단하고 tunnel branch의 dispatch info에 `req.Run.EstimatedInputTokens`/`ContextClass`를 복사한다. 현재 상태에서는 selected tunnel path가 기존 direct tunnel path의 metadata/observability/long-context 문맥을 잃는다.
#### 해결 방법
- `handleResponsesProviderPool`에서 `runMeta`와 principal metadata를 만든 뒤, raw body 기준 `estimate := estimateInputTokens(string(rawBody), runMeta, nil, nil)`와 `contextClass := classifyContext(estimate, s.longContextThreshold())`를 계산한다.
- tunnel/base metadata에 `openai_model`, `openai_stream`, `estimated_input_tokens`, `context_class`를 추가한다.
- `baseRun`과 `baseTunnel`에 `Metadata`, `EstimatedInputTokens`, `ContextClass`를 모두 채운다. Normalized branch는 `PrepareRun`에서 decoded prompt 기준으로 `runReq.Metadata`, `EstimatedInputTokens`, `ContextClass`를 다시 채울 수 있다.
- test double이 tunnel `SubmitProviderTunnelRequest` snapshot에서 metadata/context를 검증할 수 있게 유지한다.
- regression test를 추가해 Responses provider-pool tunnel selection에서 `tunnelReq.Metadata["openai_model"]`, principal metadata, `estimated_input_tokens`, `context_class`, typed `EstimatedInputTokens`, `ContextClass`가 비어 있지 않음을 확인한다.
#### 중간 검증
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Metadata|Context|TunnelUnknown|Streaming|Ollama)' -count=1
```
예상 결과: tunnel metadata/context regression과 기존 tunnel/normalized mixed path tests PASS.
### [REVIEW_REVIEW_API-4] Final Verification
#### 문제
이 follow-up은 handler, service surface contract, fake service fidelity를 함께 건드리므로 focused와 package-level 검증이 필요하다.
#### 해결 방법
아래 명령을 fresh test로 실행하고 stdout/stderr를 review stub에 붙인다.
#### 중간 검증
```bash
test -f agent-task/archive/2026/07/m-openai-compatible-provider-passthrough-contract-sync/01_selector_metadata_surface/complete.log
```
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai -run 'TestResponsesProviderPool.*(Unknown|Streaming|Tunnel|Ollama|Mixed|Metadata|Context|StrictOutput)|TestResponsesStrictOutputNormalizesAgentResponse|TestChatCompletions.*ProviderPool' -count=1
```
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/service -run 'TestResolveProviderPoolCandidates.*ExecutionPath|TestResolveProviderPoolCandidatesKeepsMixedProviderTypes' -count=1
```
```bash
GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/adapters/openai_compat -count=1
```
```bash
git diff --check
```
예상 결과: 모두 PASS. full-cycle local Edge/Node smoke는 이 follow-up의 deterministic unit regression 범위 밖이면 실행하지 않은 이유와 남은 위험을 `검증 결과`에 명시한다.
## 수정 파일 요약
| 파일 | 항목 |
|------|------|
| `apps/edge/internal/openai/responses_handler.go` | REVIEW_REVIEW_API-1, REVIEW_REVIEW_API-2, REVIEW_REVIEW_API-3 |
| `apps/edge/internal/openai/server_test.go` | REVIEW_REVIEW_API-1, REVIEW_REVIEW_API-2, REVIEW_REVIEW_API-3 |
| `apps/edge/internal/openai/chat_handler.go` | REVIEW_REVIEW_API-1 only if fake-guard workaround cleanup requires it |
| `apps/edge/internal/service/run_dispatch.go` | REVIEW_REVIEW_API-3 only if service-level test/contract assertion is added |
## 최종 검증
구현 완료 후 `REVIEW_REVIEW_API-4`의 모든 명령 결과를 `CODE_REVIEW-local-G06.md`에 붙인다.