feat(meta-muse): expose max reasoning effort to routed clients

[shawn-kim-ai]

Summary

• Expose max for both meta-muse Muse Spark 1.3 models. Previously the shared Meta effort ladder stopped at xhigh, so routed clients such as Grok omitted max and requests could be clamped before reaching Meta.
• Give only meta-muse its own identity effort map and muse-build/1.3.0 (opencodex compatibility) User-Agent through the existing registry header seam. Explicit operator headers retain precedence; meta-model and OpenCode Go keep their existing ladders.
• Document the compatibility header and keep the existing unsupported-credential-use and billing disclosures. No authentication grant, credential destination, storage, or refresh behavior changes.

Reviewer entry points: model-seeds.ts and entries-core.ts define the contract; meta-muse-oauth.test.ts verifies the wire effort and header together against a Grok caller header; the Grok injection test verifies picker propagation. The small structure-document updates synchronize the required source ownership map.

Verification

• Passed: 63 focused tests across meta-muse-oauth, muse-key-quota, and grok-effort-inject.
• Passed: 16 additional tests across meta-model-api-provider and opencode-go-muse-context.
• Passed: bun run typecheck, bun run structure:check, bun run privacy:scan, and git diff --check.
• Passed: cd docs-site && bun install --frozen-lockfile && bun run build (465 pages).
• Passed on exact head 979771698: the full test set in four CI-style shards, 27,081 pass / 56 skip / 0 fail across 1,383 files. The equivalent unsharded Bun process wedged in a worker without emitting a test failure; CI-style sharding completed every file in fresh processes.
• GitHub PR hygiene passed. CodeRabbit reviewed the current code and reported no actionable comments; no unresolved review threads remain.
• Security review of this diff: provider scope and operator override precedence were checked; no secrets or new credential destinations were introduced. Maintainer review of the Muse client-identity compatibility choice remains required before merge.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features

  • Added the max reasoning effort option to both Meta Muse models.
  • Enabled the max option in the Grok effort picker for Meta Muse models.
  • Added default Muse compatibility request headers, while allowing explicit provider headers to override them.

• Documentation

  • Documented Meta Muse reasoning levels, request headers, routing behavior, and Grok integration.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 5d47db01-6a0a-4709-814e-229072e129dc

📥 Commits

Reviewing files that changed from the base of the PR and between 9797716 and dbb047b.

📒 Files selected for processing (1)

• structure/providers-and-adapters.md

 _____________________________________________________________
< I'm sorry, Dave. I'm afraid I can't let you write that bug. >
 -------------------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: d350c4e2-ab59-46b2-9210-992ba1fc1f72

📥 Commits

Reviewing files that changed from the base of the PR and between 735f915 and 60da51f.

📒 Files selected for processing (11)

• docs-site/src/content/docs/guides/providers.md
• src/providers/registry/entries-core.ts
• src/providers/registry/model-seeds.ts
• structure/providers-and-adapters.md
• structure/providers/xai-grok.md
• structure/runtime.md
• structure/subagents.md
• structure/transports/inventory.md
• tests/providers/meta-muse-oauth.test.ts
• tests/providers/muse-key-quota.test.ts
• tests/providers/xai/grok-effort-inject.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

Meta Muse Code support

Layer / File(s)	Summary
Muse Code reasoning contract src/providers/registry/model-seeds.ts, src/providers/registry/entries-core.ts	Adds the max reasoning tier for meta-muse and maps all six tiers directly to wire values.
Request headers and wire validation src/providers/registry/entries-core.ts, tests/providers/meta-muse-oauth.test.ts, tests/providers/muse-key-quota.test.ts	Adds the Muse compatibility User-Agent, preserves x-api-version, verifies max reaches the Responses request, and verifies explicit header overrides.
Catalog propagation and documentation tests/providers/xai/grok-effort-inject.test.ts, docs-site/src/content/docs/guides/providers.md, structure/providers-and-adapters.md, structure/providers/xai-grok.md, structure/runtime.md, structure/subagents.md, structure/transports/inventory.md	Verifies that Grok preserves max and documents the separate meta-model and meta-muse contracts.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant meta_muse_registry
  participant createResponsesPassthroughAdapter
  participant Responses_wire_request
  meta_muse_registry->>createResponsesPassthroughAdapter: provide max reasoning and static headers
  createResponsesPassthroughAdapter->>Responses_wire_request: send reasoning.effort=max
  Responses_wire_request-->>createResponsesPassthroughAdapter: use explicit User-Agent override when provided

Loading

Possibly related PRs

• lidge-jun/opencodex#3321: Adds the shared Meta Muse model IDs and base reasoning definitions reused by this PR.

Suggested reviewers: lidge-jun

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 5…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: exposing the max reasoning effort for meta-muse routed clients.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ All CI tests are green on my local testing.
• ⬜ I pushed my PR to the latest dev commit.
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

Automatic draft conversion failed. Please convert this pull request to a draft manually until every box above is ticked.

[lidge-jun]

리뷰 · 우선순위 64 / 80

이 PR은 Meta Muse 로그인으로 쓰는 모델 두 개에 추론 단계 max를 넣습니다. 모델은 muse-spark-1.3과 muse-spark-1.3-contributor입니다. 추론 단계는 모델이 얼마나 오래 생각할지 고르는 값입니다. 전에는 meta-muse가 유료 키용 meta-model과 같은 목록을 써서 xhigh에서 끝났습니다. Grok처럼 이 서버를 거쳐 부르는 프로그램의 선택 창에도 max가 없었고, 요청이 Meta에 가기 전에 더 낮은 단계로 잘릴 수 있었습니다.

이제는 meta-muse만 자기 목록을 갖습니다. 그 목록 끝에 max가 있습니다. meta-model과 OpenCode Go는 그대로 xhigh까지입니다. 요청에는 User-Agent: muse-build/1.3.0 (opencodex compatibility)가 붙습니다. 작성자는 Meta가 이 요청을 Muse 프로그램으로 알아볼 때만 max를 받는다고 적었습니다. 이 diff 안에는 그 말을 뒷받침하는 실제 Meta 응답 기록은 없습니다. 사용자가 provider 설정에 User-Agent를 직접 적으면 그 값이 이깁니다. 그러면 max가 거절될 수 있다고 안내 문서에 나와 있습니다. 거쳐 가는 프로그램이 보낸 User-Agent는 이 기본값으로 바뀝니다. 테스트는 그 두 경우를 나눠 확인합니다.

베이스는 dev입니다. types.ts나 config.ts를 나누는 작업이 아니라서, 그 분리 때문에 닫을 중복 PR은 아닙니다. 같은 주제로 열린 다른 PR도 없습니다.

src/providers/registry/entries-core.ts User-Agent - 값의 앞이 muse-build/1.3.0입니다. 바로 위 주석은 투명한 호환 표시라고 부르지만, Meta가 보는 이름은 자기 CLI 이름입니다. 괄호 안에만 opencodex가 있습니다
같은 헤더 - 버전 1.3.0이 글자로 박혀 있습니다. Meta가 요구 문자열을 바꾸면 max가 다시 막힐 수 있습니다. 지금 그 문자열이 필요한지는 이 diff만으로 확인되지 않습니다
entries-core.ts note - 화면과 설정에 보이는 긴 경고문은 그대로입니다. User-Agent를 Muse CLI처럼 보낸다는 말은 가이드 문서에만 추가됐습니다
tests/providers/xai/grok-effort-inject.test.ts - Grok 테스트는 목록에 max가 이미 들어 있는 가짜 모델을 넣습니다. 레지스트리 목록이 카탈로그로 복사되는 구간은 이 테스트가 아닙니다. 레지스트리 테스트가 따로 있어서 구멍은 작습니다
GitHub 체크 - hygiene, label, CodeRabbit은 통과입니다. 본문에 적은 27,081개 통과는 이 리뷰에서 다시 실행하지 않았습니다

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

• Muse CLI 이름 User-Agent를 보내는 것을 머지 전에 허용할지. 이 provider는 이미 Meta가 허가하지 않은 사용이라고 경고합니다. 이번 변경은 그 위에 클라이언트 이름까지 맞춥니다
• 앱에 보이는 note에도 이 헤더를 한 줄 적을지
• 1.3.0을 코드에 고정해 둘지

너의 추천
사다리 분리는 맞습니다. meta-model은 xhigh에 남고 meta-muse만 max를 갖습니다. 헤더 순서도 코드와 테스트가 같습니다. 사용자가 적은 User-Agent가 이기고, 거쳐 가는 프로그램이 보낸 값은 밀립니다. User-Agent를 Meta CLI로 보이게 하는 선택을 승인하기 전에는 머지하지 않는 편이 맞습니다. 그 한 가지를 승인하면 변경 범위가 작아서 머지 후보가 됩니다. types/config 분리 때문에 닫을 PR은 아닙니다.

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

[lidge-jun]

리뷰 · 우선순위 71 / 80

이 PR은 meta-muse에 생각 단계 max를 넣습니다. 지금까지 meta-muse와 meta-model이 사다리 하나를 같이 썼습니다. 칸은 minimal, low, medium, high, xhigh 다섯 개이고 max는 없습니다. Grok처럼 이 목록을 받아서 피커를 그리는 클라이언트는 Muse를 골라도 max를 보여 주지 못했습니다. 요청이 Meta에 닿기 전에 더 낮은 칸으로 잘릴 수도 있었습니다.

고친 방식은 사다리를 둘로 나눈 것입니다. model-seeds.ts의 예전 배열 META_MUSE_REASONING_EFFORTS는 그대로 둡니다. meta-model과 OpenCode Go는 그 다섯 칸을 계속 씁니다. meta-muse만 새 배열 META_MUSE_CODE_REASONING_EFFORTS를 씁니다. 내용은 예전 다섯 칸 뒤에 max를 붙인 것입니다. 이름 대응표도 max를 max로 그대로 보냅니다. 이 표가 없으면 로컬 쪽이 모르는 칸을 지원 목록 안으로 눌러 넣고, max는 xhigh가 됩니다.

요청 헤더도 바뀝니다. meta-muse 고정 헤더에 User-Agent: muse-build/1.3.0 (opencodex compatibility)가 추가됩니다. 있던 x-api-version: 1.0.0은 남습니다. 운영자가 설정에 같은 이름 헤더를 적으면 그 값이 이깁니다. 들어오는 클라이언트 User-Agent는 이기지 못합니다. 제공자 헤더에 User-Agent가 이미 있으면, 어댑터는 호출자 값을 빈칸 채우기로 넣지 않습니다. 테스트가 Grok 헤더 grok-build/test를 넣어도 나가는 값이 muse-build/1.3.0 (opencodex compatibility)인 이유가 이것입니다.

테스트는 세 곳입니다. 두 모델 사다리에 max가 있는지, 와이어 본문의 effort가 max로 남는지, Grok 피커 표에 max가 전달되는지. 사용자가 적은 User-Agent가 고정 값을 덮는지도 muse-key-quota.test.ts가 봅니다.

베이스는 dev입니다. types.ts와 config.ts는 안 건드립니다. 같은 주제로 열린 다른 PR은 없습니다. 닫고 다시 올릴 대상이 아닙니다. 이 head 979771698에서 hygiene, label, enforce-target, CodeRabbit은 통과했습니다. 전체 테스트 2만 건 통과는 PR 본문의 로컬 샤드 기록이고, 이 리뷰는 그 숫자를 다시 돌리지 않았습니다.

라인 - 이게 무슨 문제다

src/providers/registry/entries-core.ts · staticHeaders User-Agent - 나가는 값은 muse-build/1.3.0입니다. 괄호 안 (opencodex compatibility)는 사람이 읽는 꼬리말입니다. Meta가 제품 이름 muse-build만 보면 자기 Muse Code 클라이언트로 받을 수 있습니다. 바로 위 주석의 "transparent"는 그 사실을 약하게 말합니다. 투명한 꼬리표가 아니라, max가 통과하는 자격 증명 면을 고르려고 클라이언트 이름을 빌리는 헤더입니다.

src/providers/registry/entries-core.ts · 1.3.0 - 버전이 소스에 박혀 있습니다. Meta가 요구 버전을 올리면 max만 실패하는 것이 아닙니다. meta-muse 요청 전부가 로컬 경고 없이 거절될 수 있습니다. 예전 주석은 "서버가 이 헤더를 요구하면 신호 없이 전부 깨진다"고 적었습니다. 그 위험이 이제 이 고정 문자열에 묶입니다.

src/providers/registry/entries-core.ts · 붙여 넣은 키 - 이 User-Agent는 브라우저 디바이스 로그인에만 붙지 않습니다. meta-muse 행의 고정 헤더라서, 같은 행으로 나가는 붙여 넣은 키 요청에도 같이 붙습니다. 그 키가 Muse Code 구독 키가 아니면, 피커의 max와 서버가 실제로 받는 칸이 어긋날 수 있습니다.

tests/providers/meta-muse-oauth.test.ts · max reaches the Responses wire - 본문이 max로 남는 단언은 맞습니다. 시드가 대응표를 복사하고, 표에 max가 없으면 클램프가 xhigh로 바꾸기 때문입니다. 이 테스트는 라우터가 요청 시각에 헤더를 합치는 길은 안 탑니다. 그 합치기는 muse-key-quota.test.ts가 봅니다. 빠진 버그는 아니고, 두 파일이 각자 한쪽만 본다는 점입니다.

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

• muse-build/1.3.0을 기본 User-Agent로 실어 max를 열지. PR 본문도 이 선택을 머지 전에 사람이 보라고 남겨 두었습니다. 기존 안내문은 이미 이 경로를 Meta가 허용하지 않는 사용이라고 적습니다. 이번 변경은 그 위에 "요청을 Muse 클라이언트로 보이게"를 더합니다.
• 버전을 1.3.0에 고정할지. 거절이 났을 때 로그로 이유를 남길지는 후속으로 둬도 됩니다.
• 붙여 넣은 키에도 같은 User-Agent와 max 사다리를 줄지. 디바이스 로그인 키와 붙여 넣은 키를 헤더에서 나누려면 이번 diff보다 범위가 커집니다.

너의 추천

사다리를 나누는 쪽은 맞습니다. meta-model은 다섯 칸으로 두고, Muse Code 자격 증명 행만 max를 광고하면 예전 free 프로브의 unknown variant 거절과 충돌하지 않습니다. 테스트도 그 경계를 고정합니다.

머지 전에 User-Agent만 고르면 됩니다. 제품 이름 muse-build를 기본으로 보내는 것이 괜찮다면 이대로 합쳐도 됩니다. 싫다면 max 사다리만 남기고 User-Agent는 빼세요. 그 경우 Meta가 헤더 없이 max를 거절하면, 피커에는 max가 있고 실제 호출은 실패합니다. types.ts/config.ts 분할과 무관하니 이 PR을 닫지 마세요.

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