fix(chat): enforce effort ceilings without model pins

[lidge-jun]

Summary

Native Chat Completions now enforces qualifying main/subagent effort ceilings even when no model pin resolves. Pin selection precedes cap admission; provider wire mapping runs only for a pin or cap rewrite. Compaction/V1 exemptions, lower/unranked caller values and retry snapshot behavior are preserved.

Carries #4124 at 38c9b70 as an independent dev PR. Regression coverage and eight translated configuration pages are included.

Co-authored-by: luvs01 27862058+luvs01@users.noreply.github.com

Verification

• Independent Erdos source/plan audit: PASS across all 11 changed files; implementation carries the audited patch unchanged.
• git diff --check HEAD^ HEAD: passed.
• Local test suites of every size, build, typecheck and install: NOT RUN under explicit maintainer instruction. GitHub-hosted CI is tracked after publication at the final head.
• Coordinator integration is explicitly authorized by the maintainer; original PR disposition remains tracked separately.

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.

Summary by CodeRabbit

• Documentation

  • Clarified native Chat Completions effort-cap behavior across supported languages and architectural references.
  • Documented provider value mapping when pins or caps change effort, while unchanged caller values retain their original format.
  • Updated Ultra reasoning-level guidance, including version-specific and compaction exceptions.

• Bug Fixes

  • Effort caps now apply to eligible native requests without a configured model pin.
  • Compaction signals bypass operator pinning while still receiving applicable caps.
  • Preserved original effort values during retry and failover scenarios.

Maintainer integration decision

The owner-authorized coordinator will integrate exact head 300ee08 into dev with trailing final-tip CI. Independent Erdos implementation review and Laplace final preservation review passed; coordinator inspected the final runtime/test delta, all documentation changes, effort-policy consumers, and fresh resolved review state. No auth/credential boundary changes were introduced. The five document conflicts preserve both sides and the original coauthor trailer remains intact.

Automatic exact-head run 34694883965 ended CANCELLED: product jobs did not execute, and the aggregate ci job failed. This is not passing runtime evidence. Local suites/build/typecheck/install are NOT RUN by explicit user instruction. Manual redispatch remains on hold pending the separate actor-cancellation clarification; no workflow or protection changes are authorized. Technical acceptance stays open until final hosted evidence is obtained.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-12T04:51:25.272127Z	cc1421d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: cbb5f96e-bf48-4ac2-bf0a-93314ae8a21c

📥 Commits

Reviewing files that changed from the base of the PR and between f302982 and 300ee08.

📒 Files selected for processing (7)

• structure/adapters/registry.md
• structure/clients/claude-desktop.md
• structure/data-planes/inbound-compat.md
• structure/ops/docs-and-release.md
• structure/providers/xai-grok.md
• structure/runtime.md
• structure/transports/inventory.md

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

---

📝 Walkthrough

Walkthrough

Native Chat effort handling now applies eligible caps without model pins, conditionally normalizes rewritten values for provider transmission, preserves unchanged caller notation, and expands integration coverage for compaction and retry behavior.

Changes

Native Chat effort handling

Layer / File(s)	Summary
Effort normalization and cap application src/server/chat-native.ts	Compaction turns bypass pin resolution. Eligible caps apply to compaction and non-compaction turns. Provider wire normalization runs when a pin resolves or a cap changes the value.
Integration validation tests/codex-integration/model-pinned-effort.test.ts	Tests cover capped efforts, pin behavior, V1 and compaction exemptions, absent or unsupported efforts, and destination-specific retry recomputation.
Reference documentation docs-site/src/content/docs/*/reference/configuration/agents.md, structure/**/*.md	Configuration, catalog, and structural references document cap application without pins, conditional wire mapping, exemptions, and preservation of unchanged caller notation.

Priority: ➖ Normal

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

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant NativeChat
  participant EffortNormalizer
  participant Provider
  NativeChat->>EffortNormalizer: provide effort and compaction_trigger
  EffortNormalizer->>EffortNormalizer: apply eligible cap
  EffortNormalizer->>Provider: send mapped effort when rewritten
  EffortNormalizer-->>NativeChat: preserve original notation when unchanged

Loading

Merge Risk: ⚪ Minimal · up to 300ee

The change is ready to merge after the normal hosted CI checks complete.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (7 skipped: 7 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 main change: enforcing chat effort ceilings when no model pin resolves.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (7 skipped: 7 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/260912-60plus-models-effort-caps

---

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.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cc1421d089

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 70 / 80

지금 dev HEAD는 81f0c78d7이고, 방금 캐시 affinity #4340이 들어간 상태다. 패키지는 2.52.0이다. 이 PR은 그 캐시 레인과 별개인 네이티브 Chat Completions effort 상한 수정이다. 지금 dev의 src/server/chat-native.ts normalizePinnedChatEffort는 운영자 모델 pin이 잡힐 때만 applyChatEffortCap과 mapReasoningEffort로 들어간다. pin이 없으면 호출자가 보낸 reasoning_effort: "ultra"가 그대로 올라간다. 그래서 subagentEffortCap: "low"를 켜 둬도, pin 없는 네이티브 Chat 자식 턴(또는 v2 main)이 ultra로 새는 구멍이 있다. Responses 쪽은 이미 pin 없이도 상한이 먹는데, 네이티브 Chat만 pin 분기에 묶여 있었다. 원본은 열려 있는 #4124이고, 이 PR은 그 패치를 38c9b7085에서 가져와 독립 dev PR로 다시 올린 캐리다.

고치는 흐름은 짧다. 먼저 compaction이면 pin을 건너뛴다. pin이 있으면 값을 넣고 wire 정규화 후보로 표시한다. 그다음 pin 성공 여부와 무관하게 effortCapAppliesTo(surface, headers, config, compaction)로 상한 자격을 본다. 상한이 값을 바꾸면 그때도 wire 정규화 후보가 된다. 마지막으로 pin이 있거나 상한이 값을 바꾼 경우에만 mapReasoningEffort로 제공자 전송 표기를 맞추고, 둘 다 아니면 호출자 표기를 그대로 둔다. compaction과 multiAgentMode v1 면제는 기존 effort-policy 계약을 그대로 쓴다. 문서 8개 로케일 agents.md와 structure/catalog.md Ultra reasoning-level 절, 그리고 structure 쪽 여러 소유 문서에 같은 계약 문단을 맞춰 두었다. 회귀는 tests/codex-integration/model-pinned-effort.test.ts에서 pin 없는 spawn 자식 상한, v2 main/v1 강제, wire 매핑·낮은 값 보존, 사다리 불일치 strip, compaction 면제, 재시도 스냅샷 복원을 덮는다. 예전 테스트가 spawn 자식을 ultra로 기대한 줄은 사실상 버그를 고정해 둔 것이었고, 이번엔 low로 바뀐다.

라인 / src/server/chat-native.ts (normalizePinnedChatEffort 재배치) - pin 분기와 cap 분리를 맞춘 방향은 옳다. 다만 본문대로 로컬 suite/build/typecheck는 돌리지 않았고, 게시 직후 CI는 label만 통과·resolve-pr는 아직 pending이다. 머지 전에 GitHub CI 그린만 확인하면 된다.

라인 / structure/*.md 다수 파일 동일 문단 - adapters·images·xai-grok·transports 등 여러 소유 문서 끝에 같은 Native Chat effort 계약 문단이 붙었다. catalog 계약 동기화 관례로는 이해되지만, 실제 코드 소유와 무관한 파일까지 동일 문장이 퍼져 diff 소음이 크다. catalog.md + agents 로케일만으로도 계약은 충분해 보이니, 이후 캐리에서는 structure blast 범위를 줄여도 된다.

경로 / #4124 - 같은 제목·같은 구멍의 원본 PR이 아직 OPEN이다. 이 PR이 머지되면 #4124는 landed-via로 닫아야 한다. 둘을 같이 살리지 말 것.

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

• CI 그린 후 바로 dev에 넣을지, 아니면 캐시 레인(fix(claude): opt in to harness prompt-cache stabilization (carry #4052) #4347/test(chat): verify native outbound conversation identity (#3433) #4365) 뒤에 둘지. 이 변경은 캐시 affinity와 겹치지 않는 독립 버그픽스라 순서는 자유다.
• structure 문서 blast를 이번 머지에 그대로 둘지, 후속으로 catalog/agents만 남기도록 줄일지.
• fix(chat): enforce effort caps without model pins #4124 원본 브랜치(agent/native-chat-effort-caps-20260909)를 이 머지 직후 닫을지(권장).

너의 추천
CI(resolve-pr 포함) 그린 확인 후 머지. 머지되면 #4124에 Landed via #4349 at <commit> 남기고 landed-via-maintainer 붙여 닫기. 캐시 레인 PR들과 충돌 없으니 대기열 앞에 둬도 된다. 로컬 미실행은 CI로 대체한다는 본문 전제를 그대로 수용.

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