feat: carry operator-pinned reasoning effort with current config contracts

[lidge-jun]

Summary

• Carry feat(router): add per-model pinned reasoning effort overrides #3336 by @Liang-Psych with operator-owned provider/model reasoning-effort pins. Provider model pins precede provider-wide pins and global model pins; applicable caps and wire normalization still run afterward.
• Adapt the original work to current configuration validation, public provider DTOs, canonical OpenAI user overlays and failure-safe management writes. none means explicit effort omission/provider default, not guaranteed reasoning disablement. Compaction is exempt.
• Preserve synthetic-row effort and combo destination defaults as the input before pinning. Global keys refer to the final selector/destination; original synthetic selectors and combo aliases are outside that lookup contract.

Verification

• Current head eeb550181ea5167078b11c4f0445bc02d0ae6dac, based on dev@1e188b7874b1bfe6539e85fa91ba2d4ad12ca9eb.
• Independent Astra final reviews at this exact base/head: Darwin CONFIG/SECURITY PASS, blocking_issues: []; Epicurus WIRE4 PASS, blockers: 0. Source review covers validation, canonical/DTO boundaries, deletion/rollback and wire composition. The rebase audit's pricing interaction is fixed in a separate commit with deferred-body replacement/deletion regressions. Source-only verdicts; reviewers ran no product checks.
• Local suite, typecheck, build, install and privacy scan: NOT RUN by instruction. git diff --check passed. Replacement central CI run 34126879673, lane=all, has all 16 required per-chain jobs SUCCESS at this exact head. The full workflow was cancelled after excluded Windows/control jobs were stopped; its aggregate is not claimed green. Run 34126053072 passed gates but failed two pre-existing API fixtures with a missing default provider; that run was cancelled. The API-only fixture now satisfies the existing schema, with all assertions and production validation unchanged. Independent Averroes RCA/source review: PASS; Darwin and Epicurus rebound their PASS verdicts to this test-only follow-up head.
• Per-chain required jobs: Linux 4 shards, macOS 2 shards, gates/storage/api/keyring/npm/docker. Windows 6 shards and macOS control are excluded by the explicit owner policy and handled at final train verification.
• A/B prerequisites were proven with git merge-base --is-ancestor before editing transferred core/config/native-chat files. C's subagent/health blocks remain untouched; only the separately granted effort-caps block/imports changed.
• Original commits carried in order with git cherry-pick -x: 6399c8eb05f9f5b2e16af1f499f3bd73a2983f04, db65ff9b3d5245f1efdea88109ae5be737317aa5, a53597edda1598c5d536a970c6fa724b231fba97. Every carry/adaptation commit preserves Liang-Psych credit. Registry-default additions were removed; these are operator settings only.
• Separate pricing follow-up commit records found by #3336 rebase security audit: re-read provider ownership after asynchronous body parsing, then merge/save on the current row. Authentication, price validation and redaction stay unchanged.

Manual chain (stack: null):

Layer	Branch	Base	Scope
1 (standalone, final lane-E item)	codex/260907-e-pinned-effort	dev	Adapted #3336 pinned effort

The original PR is superseded only after verified landing. No merge, release or publication performed.

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.

Co-authored-by: Liang-Psych 19504206+Liang-Psych@users.noreply.github.com

---

Maintainer integration decision (MAINTAINERS.md, dev-only admin integration; config/wire surface → security review attached in body): @lidge-jun integrates #3892 (carry of #3336 by @Liang-Psych, adapted to current config/wire contracts, plus the pricing-PUT race fix found by its rebase audit) into dev. Exact-head evidence at eeb550181: Cross-platform CI run 34126879673 — Linux test 1/4–4/4, macOS 1/2, 2/2, gates, storage policy, api usage, keyring ×3, npm-global ×3, docker smoke = success; Windows/macos control deferred to the final train head. Prospective merge tree of origin/dev@1e188b787 + head = 402b8e750 = tested tree. Independent CONFIG/SECURITY and WIRE reviews PASS (0 blockers) at this head. Local suites NOT RUN. Maintainer integration, not self-approval.

Summary by CodeRabbit

• New Features

  • Added operator-configurable reasoning-effort pins globally, per provider, and per model.
  • Pins now apply across supported requests, with provider/model precedence and effort-cap enforcement.
  • Added management API support for viewing, setting, updating, and clearing pinned efforts.
  • Added support for omitting explicit effort with the none setting.

• Bug Fixes

  • Model cost updates now safely handle providers being replaced or removed during request processing.

• Documentation

  • Documented pin configuration, precedence, normalization, caps, and maintenance-request behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 4b30d732-153a-44b1-9647-3fdd7ee52142

📥 Commits

Reviewing files that changed from the base of the PR and between 1e188b7 and eeb5501.

📒 Files selected for processing (20)

• docs-site/src/content/docs/reference/configuration/agents.md
• docs-site/src/content/docs/reference/configuration/providers.md
• scripts/test-layout/layout.json
• src/config.ts
• src/config/provider-validation.ts
• src/server/auth-cors.ts
• src/server/chat-native.ts
• src/server/effort-policy.ts
• src/server/management/agent-settings-routes.ts
• src/server/management/model-routes.ts
• src/server/management/provider-routes.ts
• src/server/responses/core.ts
• src/types/config.ts
• src/types/provider.ts
• structure/03_catalog-and-subagents.md
• tests/codex-integration/effort-policy.test.ts
• tests/codex-integration/model-pinned-effort.test.ts
• tests/config/model-pinned-effort-config.test.ts
• tests/fixtures/test-layout-expected.json
• tests/server/model-costs-management-api.test.ts

---

📝 Walkthrough

Walkthrough

This change adds global and provider-specific reasoning-effort pins. It validates and sanitizes pin configuration, applies precedence and caps during Chat and Responses normalization, exposes management API updates with rollback handling, adds race-condition coverage, and documents the configuration.

Changes

Reasoning effort pinning

Layer / File(s)	Summary
Pin configuration and validation src/config.ts, src/config/provider-validation.ts, src/types/config.ts, src/types/provider.ts, src/server/auth-cors.ts, tests/config/*, docs-site/src/content/docs/reference/configuration/providers.md, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json	Adds global and provider pin fields, validation and merge helpers, load-time sanitization, write-boundary checks, provider editor handling, rollback tests, and provider configuration documentation.
Runtime effort resolution and normalization src/server/effort-policy.ts, src/server/chat-native.ts, src/server/responses/core.ts, tests/codex-integration/model-pinned-effort.test.ts, structure/03_catalog-and-subagents.md	Resolves provider-model, provider-wide, and global pins. Applies pins after destination selection and before caps and wire normalization. Handles compaction, synthetic rows, failover, retries, native Chat surfaces, and none.
Management APIs and state-safe persistence src/server/management/provider-routes.ts, src/server/management/agent-settings-routes.ts, src/server/management/model-routes.ts, tests/codex-integration/effort-policy.test.ts, tests/server/model-costs-management-api.test.ts, docs-site/src/content/docs/reference/configuration/agents.md	Adds provider and effort-cap API support for pin updates, validation, partial merges, clears, deletion provenance, rollback, and current-provider rechecks. Tests deferred request-body races and management persistence behavior.

Estimated code review effort: 4 (Complex) | ~60 minutes

Suggested reviewers: invalid-email-address

Sequence Diagram(s)

Runtime normalization

sequenceDiagram
  participant ChatIngress
  participant ResponsesNormalization
  participant EffortPolicy
  participant ProviderSerializer
  ChatIngress->>EffortPolicy: Resolve provider and global pins
  ResponsesNormalization->>EffortPolicy: Normalize the destination effort
  EffortPolicy->>EffortPolicy: Apply caps and provider mapping
  EffortPolicy->>ProviderSerializer: Serialize reasoning_effort

Loading

Management update

sequenceDiagram
  participant ManagementClient
  participant ProviderRoutes
  participant ConfigValidation
  participant ConfigPersistence
  ManagementClient->>ProviderRoutes: Submit pin update
  ProviderRoutes->>ConfigValidation: Validate merged configuration
  ConfigValidation-->>ProviderRoutes: Return validation result
  ProviderRoutes->>ConfigPersistence: Save with rollback state
  ConfigPersistence-->>ManagementClient: Return updated configuration

Loading

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/260907-e-pinned-effort

---

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.

[lidge-jun]

리뷰 · 우선순위 58 / 80

이 PR은 #3336(Liang-Psych)의 operator-owned reasoning effort pin을 현재 dev 설정·DTO·와이어 계약에 맞게 다시 옮긴 캐리입니다. 지금 HEAD(522ce5f8c)의 src/server/effort-policy.ts는 주로 cap/strip(서브에이전트 천장)이고, 요청을 강제로 특정 effort로 고정하는 pin API는 없습니다. 이 변경은 provider 모델 pin → provider-wide pin → global model pin 순으로 적용한 뒤, 기존 cap과 와이어 정규화를 그 위에 탑니다. none은 “effort 필드 생략/프로바이더 기본”이지 추론 완전 끔이 아닙니다. compaction은 면제입니다. synthetic/combo 기본 effort는 pin 입력으로 보존합니다.

건드리는 면이 넓습니다. src/types/config.ts, src/types/provider.ts, src/config.ts, src/config/provider-validation.ts, effort-policy.ts, chat-native.ts, responses/core.ts, management provider/effort-caps 라우트, 문서 두 장, 레이아웃 등록입니다. types/config 분할 캠페인과 같은 파일을 만지지만, 닫고 리베이스 포기할 “무효화된 옛 PR”이 아니라 메인이 직접 적응한 캐리입니다. 원본 #3336은 검증 랜딩 후에만 supersede 하라고 본문에 적혀 있습니다. 로컬 스위트/타입체크는 NOT RUN, Astra/Epicurus 소스 리뷰는 PASS입니다.

src/types/config.ts · src/types/provider.ts (pinned* 필드) - 공개 설정 표면이 늘어납니다. 분할 캠페인 중이라 필드 이름·위치(OcxConfig vs OcxProviderConfig)가 이후 이동할 수 있습니다. 지금 계약(모델 pin이 프로바이더 pin보다 우선, 글로벌은 final selector)을 테스트에 고정해 두는 것이 중요합니다.

src/server/effort-policy.ts (resolvePinnedEffort / applyPinnedEffort) - cap 적용 순서가 “pin 후 cap”인지 코드·테스트가 같은 말을 하는지 확인하세요. 본문은 cap이 wire mapping 전에 온다고 합니다.

src/server/chat-native.ts · responses/core.ts - native chat와 Responses 양쪽에 pin이 들어가는지, compaction 면제가 한쪽에만 빠지지 않는지 봐야 합니다.

원본 #3336 - 아직 OPEN입니다. 이 PR이 랜딩되면 원본에 Landed via #3892 후 landed-via-maintainer로 닫는 절차가 필요합니다.

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

• 중앙 CI·런타임 검증 없이 소스 PASS만으로 랜딩할지
• 레지스트리 기본 pin을 제거한(operator-only) 결정 유지 여부
• #3336을 이 PR 머지 직후 닫을지

너의 추천
필수 CI가 그린이고 pin→cap→wire 순서 테스트가 통과하면 머지하세요. 머지 후 #3336에 landed 코멘트·라벨·클로즈를 바로 하세요. types/config를 만지지만 “close-don't-rebase” 대상이 아니라 적응 캐리로 취급하면 됩니다.

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

[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-07T13:33:33.317487Z	eeb5501	Draft marked ready

ℹ️ 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.