# Milestone: 사용량, 토큰, 로그 운영 추적 MVP

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`

## 목표

사용자 관리, token 관리, API/CLI/local inference 사용량 집계, 로그 관리를 1차 MVP 운영 축으로 스케치한다.
이미 존재하는 runtime usage, CLI usage status, audit/observability 패키지와 Control Plane/Client 운영 표면을 기준으로 삼되, 구체 schema와 저장소 구현은 후속 구체화 전까지 확정하지 않는다.
사용자 요청 하나가 어떤 device/provider/node/model로 처리되었는지, 언제 시작/종료되었는지, input/think/output token을 얼마나 사용했는지 추적 가능한 운영 기록을 MVP 핵심 후보로 둔다.

## 상태

[스케치]

## 승격 조건

- [ ] 1차 MVP에서 관리할 사용자/token 범위와 운영 주체를 결정한다.
- [ ] API, CLI, local inference 사용량을 요청, run, session, user, provider/device/model 중 어떤 단위로 집계할지 결정한다.
- [ ] 요청별 input token, cached input token, think/reasoning token, output token, total token을 어떤 provider-reported/estimated 기준으로 기록할지 결정한다.
- [ ] 요청별 사용 device/provider/node, model alias/served model, queue/dispatch/start/first-token/end timestamp, duration, status/error를 어느 이벤트와 저장소에 남길지 결정한다.
- [ ] 로그 관리의 최소 범위, 보관/조회/export 책임 경계, prompt/response preview redaction 정책을 결정한다.
- [ ] Control Plane, Edge-local CLI, Client 중 어떤 표면을 MVP에 포함할지 결정한다.

## 구현 잠금

- 상태: 잠금
- SDD: 불필요
- SDD 사유: 현재 Milestone은 운영 범위와 산출물 스케치이며, proto/schema/storage/API 구현 전 별도 구체화에서 SDD 필요 여부를 재판정한다.
- 결정 필요: 아래 체크리스트
  - [ ] 사용자와 token을 개인/Edge/조직 중 어떤 단위로 시작할지 결정한다.
  - [ ] 사용량 집계의 MVP 단위를 요청, token, runtime duration, CLI limit status, provider/device throughput 중 어디까지로 둘지 결정한다.
  - [ ] think/reasoning token을 provider-reported 값만 신뢰할지, 표시된 reasoning text 기반 추정치를 함께 둘지 결정한다.
  - [ ] 요청별 device/provider 사용 기록을 사용자 로그, audit log, 성능 ledger 중 어디에 canonical하게 둘지 결정한다.
  - [ ] 로그 조회와 export의 MVP 표면을 Control Plane/Client/CLI 중 어디에 둘지 결정한다.

## 범위

- 사용자 관리와 token 관리의 1차 운영 경계
- API, CLI, local inference 사용량 집계의 MVP 산출물 정의
- 요청별 run ledger: user/session/workspace/source/request_id/run_id, 사용 device/provider/node/model, queue/dispatch/start/first-token/end timestamp, status/error
- token ledger: input, cached input, think/reasoning, output, total token과 provider-reported/estimated/unavailable source 표시
- Edge/Node/Control Plane 로그 관리의 최소 조회 경계
- 기존 `Usage`, CLI usage status, audit/observability 패키지와 연결 가능한 표준선 정리

## 기능

### Epic: [ops-usage] Usage and Log Operations

운영자가 사용량과 로그를 한 곳에서 이해하기 위한 최소 capability를 묶는다.

- [ ] [identity-scope] 사용자와 token 관리의 MVP 책임 경계가 정리되어 있다.
- [ ] [usage-rollup] API, CLI, local inference 사용량 집계 후보와 제외 범위가 요청/run/session/user/provider/device/model 단위로 정리되어 있다.
- [ ] [request-ledger] 사용자 요청별 사용 device/provider/node/model, run_id/request_id, queue/dispatch/start/first-token/end timestamp, duration, status/error를 남기는 MVP ledger 후보가 정리되어 있다.
- [ ] [token-breakdown] input, cached input, think/reasoning, output, total token과 usage source(provider-reported/estimated/mixed/unavailable) 기준이 정리되어 있다.
- [ ] [usage-collection] OpenAI-compatible streaming usage, provider별 native usage, CLI usage status, 추정 token count를 어떤 우선순위로 수집할지 정리되어 있다.
- [ ] [log-surface] Edge/Node/Control Plane 로그 조회와 export의 최소 표면 후보가 redaction/preview 정책과 함께 정리되어 있다.
- [ ] [ops-review] 사용자가 MVP 운영 범위와 후속 구체화 우선순위를 검토했다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 스케치 Milestone이며 기능 Task가 아직 충족되지 않았다.
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- 결제, chargeback, 조직 IAM, 장기 retention 정책의 상세 구현
- 모든 로그 schema와 audit schema 확정
- provider routing 또는 inference adapter 구현
- hidden reasoning token을 provider가 보고하지 않는 경우의 완전 정확한 복원

## 작업 컨텍스트

- 관련 경로: `apps/control-plane`, `apps/client`, `apps/edge`, `apps/node`, `packages/go/audit`, `packages/go/observability`, `proto/iop/runtime.proto`, `apps/edge/internal/openai`, `apps/node/internal/adapters/openai_compat`
- 표준선(선택): Edge는 로컬 runtime 상태의 원본을 유지하고, Control Plane은 연결 view와 운영 기록을 보기 쉽게 제공한다.
- 표준선(선택): provider가 usage를 보고하면 provider-reported 값을 우선하고, 보고하지 않는 필드는 estimated/unavailable source를 명시한다.
- 선행 작업: Control Plane과 Client 운영, OpenAI-compatible usage 응답, CLI usage checker
- 후속 작업: 요청 실행 로그와 Usage Ledger 기반, 운영 리포트, audit retention, 품질 기반 routing/fallback 고도화
- 확인 필요: 사용자/token 단위, 사용량 집계 단위, think token 신뢰 기준, 로그 관리 표면
