Feature proposal: inspect and redeem Grok reset coupons via management API + CLI

[lidge-jun]

Area

Provider adapters

What are you trying to accomplish?

Let operators inspect and redeem Grok billing reset coupons (Codex-style usage-reset credits) directly through OpenCodex, using the xAI OAuth tokens already stored — no browser session.

What prevents this today?

OpenCodex only provides quota reset credit inspection and consumption for Codex/ChatGPT accounts (`/api/codex-auth/reset-credits`, `ocx account reset-credits`). Grok reset coupons are served by `prod_mc_billing.ConsumerUiSvc` over binary gRPC-Web and have no management API or CLI surface, so the only way to see or spend one is the grok.com web UI with devtools open.

What should OpenCodex do?

1. Expose `GET /api/grok/reset-coupons?accountId=` to inspect remaining reset tokens and validity windows.
2. Expose `POST /api/grok/reset-coupons/consume` to redeem one with durable UUIDv4 operation-id idempotency (journal before fetch; identical ids replay; foreign ids 409; exhausted ledger 503).
3. Provide `ocx account grok-reset-coupons [--consume --yes --token-id ] [--operation-id ]` mirroring the `reset-credits` safety flags.

Example usage or interface

```bash
ocx account grok-reset-coupons
ocx account grok-reset-coupons --consume --yes --operation-id 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
```

Alternatives or workarounds

Manually inspecting and redeeming coupons in a web browser using devtools network payloads.

Additional context

Contract verified live against `grok.com` (`GetRemainingResets` / `RedeemReset`): binary gRPC-Web framing (`application/grpc-web+proto`, 5-byte envelope), `Authorization: Bearer ` + `X-XAI-Token-Auth: xai-grok-cli`, no cookies. Response tokens carry `tokenId` plus validity start/end timestamps.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.

[lidge-jun]

Landed on dev via #4306 (squash). Management API routes + ocx account grok-reset-coupons with journaled idempotent redemption are now on the integration branch.

[lidge-jun]

리뷰 · 우선순위 64 / 80

이 이슈는 지금 dev(HEAD 43d2a352a, #4289 generic OAuth pool.kernel 소비가 tip)에는 없는 Grok 빌링 리셋 쿠폰을, 이미 저장된 xAI OAuth 토큰만으로 OpenCodex 관리 API·CLI에서 보고·쓰게 하자는 제안이다. Codex/ChatGPT 쪽은 이미 /api/codex-auth/reset-credits 와 ocx account reset-credits 가 있고, 저널 멱등성도 src/codex/reset-credit-operation-ledger.ts 와 #3219(자동 소진)·#3970·#3965 줄기로 단단하다. 반면 Grok 쿠폰은 grok.com 의 prod_mc_billing.ConsumerUiSvc 가 GetRemainingResets / RedeemReset 을 binary gRPC-Web(application/grpc-web+proto, 5바이트 프레임)으로만 열고, Bearer + X-XAI-Token-Auth: xai-grok-cli 헤더를 쓴다. 쿠키 세션이 필요 없다는 점까지 이슈 본문에 살아 검증으로 적혀 있어서, “브라우저+devtools 아니면 못 쓴다”는 구멍이 제품 면에서도 분명하다.

제안 표면은 Codex 패턴을 거의 그대로 옮긴다. (1) GET /api/grok/reset-coupons?accountId= 로 남은 토큰·유효기간 조회, (2) POST /api/grok/reset-coupons/consume 으로 소진하되 UUIDv4 operation-id를 upstream 호출 전에 저널에 남기고, 같은 id는 replay·다른 id(계정 충돌)는 409·용량 초과는 503, (3) ocx account grok-reset-coupons 가 --consume --yes --token-id / --operation-id 안전 플래그를 reset-credits 와 맞춘다. 구현 PR은 이미 #4306 이 열려 있고 Closes #4305 를 달고 있다. 그 PR은 src/grok/grpc-web.ts / reset-coupons.ts / reset-coupon-ledger.ts, src/server/management/grok-coupon-routes.ts, CLI·문서(EN+7 locale)·structure/providers/xai-grok.md 계약까지 한 묶음이다. 지금 checkout의 src/grok/ 에는 catalog/effort/inject/inspect/models/status/sync 만 있고 reset-coupon 모듈은 아직 없다. route-registry에도 Codex reset-credits 항목만 있다. 그래서 이 이슈는 “이미 끝난 일”이 아니라 tip 대비 아직 빠진 provider/account 기능 제안이고, types.ts/config.ts 쪼개기 캠페인과도 겹치지 않아 close-don't-rebase 대상이 아니다.

경로 제안 /api/grok/reset-coupons - Codex는 /api/codex-auth/reset-credits 네임스페이스를 쓴다. Grok을 /api/grok/... 로 새로 파는 것은 읽기 쉽지만, 나중에 다른 프로바이더 리셋 크레딧이 늘면 네임스페이스가 갈라진다. 이번은 Grok 전용으로 가도 되지만, “account-pool 공통 계약 vs 벤더별 경로”를 한 줄로라도 남겨 두면 후속 설계가 덜 흔들린다.
경로 ocx account grok-reset-coupons - 서브커맨드 이름이 reset-credits(Codex)와 다르다. 의도적(쿠폰 vs 크레딧 용어)이면 문서에 대응표를 박고, 아니면 grok-reset-credits 같은 대칭 이름도 검토할 만하다. 플래그 모양 positionals를 account id로 안 삼는 규칙은 Codex CLI와 반드시 같아야 한다.
경로 멱등성 계약 - “foreign ids 409 / exhausted ledger 503 / identical ids replay” 는 좋다. 다만 이슈만 보면 tokenId 불일치(같은 operationId, 다른 쿠폰)와 실패 settle replay의 HTTP 상태가 빠져 있다. #4306 리뷰에서 이미 저널 account만 비교·실패도 200 가능 이슈가 나왔으니, 이슈 acceptance에 “저널에 박힌 tokenId가 요청보다 우선, 불일치는 409”와 “terminal failure는 성공과 상태 코드로 구분”을 명시하는 편이 낫다.
경로 자동 소진 - Codex는 #3219 줄기로 opt-in auto-redeem이 있다. 이 이슈 범위는 수동 inspect/consume만이다. 범위를 일부러 좁힌 건 맞지만, “자동 소진은 후속 이슈”라고 한 줄 적어 두지 않으면 리뷰어가 이번 PR에 auto-redeem까지 기대할 수 있다.
경로 동시성 - 이슈는 저널 매체(JSON vs SQLite)를 못 박지 않았다. Codex는 SQLite BEGIN IMMEDIATE 직렬화다. 구현이 JSON 단일 파일이면 동시 POST consume 덮어쓰기 위험이 acceptance에 안 보인다. “단일 프로세스·파일 잠금 또는 SQLite” 중 무엇을 최소 기준으로 둘지 밝혀야 한다.
경로 라이브 계약 - GetRemainingResets / RedeemReset 과 헤더 조합이 본문에 구체적이라 재현에 도움이 된다. 다만 엔드포인트 호스트·패키지 전체 이름이 이슈 본문에만 있고, 머지 후 SoT는 structure/providers/xai-grok.md 쪽이 된다. 이슈를 닫을 때 그 문서에 계약이 실제로 들어갔는지 한 번 확인하면 된다.

메인테이너의 판단이 필요한 지점

• 이 이슈를 feat(grok): reset-coupon inspection + gated redemption (gRPC-Web, journaled idempotency) #4306 과 한 묶음으로 머지·클로즈할지, CI/저널 수정이 끝날 때까지 이슈만 열어 둘지.
• Grok 리셋 API 경로를 /api/grok/... 로 고정할지, 장기적으로 account-pool 공통 표면으로 묶을지.
• 이번 범위에 Grok auto-redeem을 넣을지, Codex 패리티는 후속 이슈로 미룰지.
• 저널을 Codex와 같은 SQLite로 맞출지, JSON+문서화된 단일 작가 전제로 갈지.

너의 추천
#4306 이 이미 이 이슈를 구현하고 Closes #4305 를 달고 있으니, 별도 구현 PR을 더 열지 말고 #4306 쪽 리뷰 지적(저널 tokenId 우선·동시성·실패 replay 상태 코드)을 반영한 뒤 같이 머지하고 이 이슈를 닫는다. types/config 쪼개기와 무관하니 이 이슈를 close-don't-rebase로 버릴 이유는 없다. 자동 소진·공통 네임스페이스는 후속 이슈로 분리해 라벨만 남겨 두면 된다.

이 댓글은 grok-bot이 작성했습니다