fix(codex): recognize boolean native context opt-in

[luvs01]

Summary

Native history/notes relay already exists. This PR fixes a specific activation mismatch rather than adding a second relay or weakening its security boundaries.

• contextExperimentalEnabled currently recognizes only features.context_management.experimental_mode = true. Current Codex FeatureToml<ContextManagementConfigToml> also accepts features.context_management = true, which OpenCodex silently treats as disabled. Both managed URL injection and the runtime recording/dispatch gate use this predicate.
• Accept the explicit boolean form alongside the existing table form. Absent/false settings, non-boolean truthy values, malformed TOML, and profile-only opt-in remain off. Do not infer activation from a model's metadata.
• Extend the existing registered test file with boolean/table cases, URL isolation, and runtime activation/revocation without restart. No new test registration or dependencies.
• Add English/Korean guidance separating native eligibility, local admission, and actual backend availability, including an explicitly opt-in CLI trial profile and a checkpoint-first verification sequence.

Support assessment and limits

The current native relay has the needed ten history/notes endpoints and credential/ownership handling. Default built-in loopback injection does not carry an OpenCodex data-plane key, so model requests may succeed while context requests fail with context_principal_required (403). Merely using the authenticated remote provider-table form is also insufficient for current Codex automatic activation: that form uses env_key and a non-native display name.

The documented trial keeps the native ChatGPT OAuth bearer and uses env_http_headers for a separate x-opencodex-api-key. A distinct, opt-in provider/profile is used because current Codex generally does not override the built-in openai entry from model_providers.openai. Its exact OpenAI name and backend URL match the inspected native predicate. The sample is source-checked, not a live-account end-to-end certification. It uses HTTP/SSE for the initial ownership trial; no desktop profile-selection or WebSocket/steering parity claim is made.

This PR does not automatically enable the feature, alter existing provider identities, change authentication/account selection, remove principal checks, retry notes writes, grant backend eligibility, or advertise the capability on Devin/Gemini/other routed models. #5085's routed-row exclusion remains intact. The guide warns that a root opt-in also affects ordinary native profiles, and requires disabling it before returning to a default profile without the admission header.

Primary source contract

Inspected official Codex source at 78245b47af2a7aafcabe025828ceecca69db4df1:

• FeatureToml boolean/table forms
• Native context activation and account eligibility
• Provider name/backend predicates and built-in merge behavior
• History/notes request headers and authentication

Verification actually performed

Base: upstream dev at f117c20d1244bf20d8cf5bd35de5bb7c71003799. The two edited source/test blobs were rechecked against that base and match the previously inspected originals.

The editing environment has Node and TypeScript but no Bun and cannot clone/install dependencies over the network. Therefore the following are isolated compatibility checks, not bun test or repository-wide CI:

• Execute the actual transpiled production module and the updated test file with Node's test/assert adapters, Python tomllib replacing Bun.TOML.parse, and a throwing getCodexHome stub to prevent reading a real user home: 22 pass, 0 fail.
• Repeat exactly those tests against the unchanged production file: 18 pass, 4 fail. Failures cover the boolean forms and the runtime activation regression.
• Isolated strict TypeScript check of the edited source/test pair with minimal Bun/import declarations: pass. This is not bun run typecheck against the whole repository.
• All six English/Korean TOML example blocks parse, the locale examples agree, and the trial profile's auth fields match the inspected source-level predicates.

Required before review-ready

• Run native Bun regressions: bun test tests/codex-integration/context-compat.test.ts tests/server/context-history.test.ts tests/server/context-history-ownership.test.ts tests/server/data-plane-admission-identity.test.ts.
• Run the repository changed-test lane, typecheck, structure/privacy checks, and documentation build; full suite before review-ready as required by repository guidance.
• Review documentation/structure placement and the native-profile compatibility assumptions.
• For an end-to-end support claim, verify a real disposable Codex session through model success -> note write/read -> history query -> new_context -> state recovery. No user machine, real credentials, or existing working sessions were modified here.

Review readiness checklist

This PR stays in draft until every box below is ticked.

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

Summary by CodeRabbit

• New Features

  • Added support for enabling native Codex context management through either supported configuration format.
  • Native context activation now validates compatible models, providers, authentication, and required API access.
  • Improved handling of activation, reuse, revocation, and reactivation during context sessions.

• Documentation

  • Added English and Korean guides covering setup, eligibility, configuration, troubleshooting, error messages, and cleanup.
  • Added the native context compatibility guide to the documentation navigation.

• Bug Fixes

  • Invalid, unsupported, or malformed configuration values remain safely disabled.

[coderabbitai]

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: bea3cb05-bb8b-4893-bb7e-4a6e754c4b1b

📥 Commits

Reviewing files that changed from the base of the PR and between efb55e7 and a876afb.

📒 Files selected for processing (5)

• docs-site/astro.config.mjs
• docs-site/src/content/docs/guides/codex-native-context.md
• docs-site/src/content/docs/ko/guides/codex-native-context.md
• src/codex/context-compat.ts
• tests/codex-integration/context-compat.test.ts

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

---

📝 Walkthrough

Walkthrough

The change broadens native context opt-in handling, adds integration coverage for activation state changes, and adds English and Korean documentation with a sidebar entry.

Changes

Native Context Compatibility

Layer / File(s)	Summary
Context opt-in and runtime validation src/codex/context-compat.ts, tests/codex-integration/context-compat.test.ts	contextExperimentalEnabled accepts context_management = true and the table form with experimental_mode = true. Tests cover rejected values, malformed TOML, URL preservation, cache reuse, revocation, reactivation, and cleanup.
Context compatibility guide docs-site/src/content/docs/guides/codex-native-context.md, docs-site/src/content/docs/ko/guides/codex-native-context.md, docs-site/astro.config.mjs	The English and Korean guides document eligibility, authentication, configuration, verification, error codes, and cleanup. The Starlight sidebar links to the guide and provides its Korean label.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Bug fix

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the primary code change: recognizing the boolean native context opt-in. It is directly related to the PR objectives and changes.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 3 files. (2 skipped: 2 …
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.

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

[luvs01]

Published-head check for f6988c25767f14f80416d91d402fe3b2363dc37f:

• The comparison against f117c20d1244bf20d8cf5bd35de5bb7c71003799 is exactly one commit and four files (one production file, the existing registered test file, and two locale guide pages); no authentication, ownership, catalog, or workflow files changed.
• Hosted Cross-platform CI run 35437512882 and React Doctor run 35437512817 currently report action_required. These are approval-gated, not passing or failing product-test results.
• The 22 passing checks documented above remain isolated Node/Python compatibility checks, not a substitute for native Bun execution, the documentation build, or real-account state recovery.

Keep this PR in draft. Please do not interpret it as automatic native-context support for the default loopback integration.

[github-actions]

✅ READY

• all PR quality gates passed; the review readiness checklist is complete.

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.

✅ 4/4 boxes ticked.

This pull request is already Ready for Review.
The review-ready label marks this PR as ready; review automation runs independently.
Maintainers: @lidge-jun @Ingwannu

[lidge-jun]

리뷰 · 우선순위 64 / 80

Codex는 이 기능을 두 가지 글로 켤 수 있습니다. context_management = true도 되고, experimental_mode = true가 들어 있는 표도 됩니다. OpenCodex는 지금까지 표만 봤습니다. 불리언으로 켜 두면 주소를 안 바꾸고, history·notes 중계도 닫아 둡니다. 이 PR은 그 불리언도 켜짐으로 봅니다.

켜는 조건은 좁습니다. 값이 정확히 true일 때만 켭니다. 없거나 false이거나, 글자 "true", 숫자 1, 깨진 설정은 모두 꺼 둡니다. 프로필 안에만 적어도 안 켭니다. 누가 요청했는지 보는 키 검사와, 어느 계정 것인지 보는 검사는 그대로입니다.

같이 온 영문·한국어 글은 시험용 프로필입니다. 제공자 표시 이름은 OpenAI여야 하고, 주소는 /backend-api/codex로 끝나야 합니다. env_key를 넣으면 Codex가 이 기능을 거절합니다. 그래서 로컬 키는 x-opencodex-api-key 헤더로만 넣습니다. 이 조건은 Codex 소스 78245b47과 같습니다. 실제 계정으로 메모 쓰기부터 복원까지 해본 것은 아닙니다. 작성자도 그렇게 적었습니다.

베이스는 dev입니다. 지금 tip은 46195ac09b8b, 패키지 2.60.0입니다. 이 브랜치는 그 tip보다 커밋 세 개 뒤입니다. 그 세 커밋은 이 PR이 고친 파일을 안 바꿉니다. types.ts와 config.ts 나누기와는 상관없습니다. 아직 Draft입니다. 위생 검사는 통과했습니다. Cross-platform CI와 React Doctor는 승인 대기라, 테스트가 통과한 것이 아닙니다.

docs-site/astro.config.mjs - 가이드 목록에 guides/codex-native-context가 없습니다. 페이지 파일은 있지만 왼쪽 메뉴에는 안 나옵니다. 영문과 한국어만 있고 다른 언어는 없습니다.

src/codex/context-compat.ts contextExperimentalEnabled - 설정에 이미 context_management = true가 있으면, 다음 ocx sync 때 OpenCodex가 넣어 둔 로컬 주소가 /v1에서 /backend-api/codex로 바뀝니다. 사용자가 직접 적은 주소는 그대로입니다. 주소가 바뀌면 Codex가 history·notes를 보내기 시작합니다. 기본 loopback은 데이터 키를 안 실어서, 그 요청은 403 context_principal_required로 떨어집니다. 지금까지는 이 불리언을 무시해서 그 요청이 나가지 않았습니다.

테스트 - 작성자가 말한 22개 통과는 Node로 흉내 낸 것입니다. 저장소의 bun test는 아닙니다. 호스트 CI도 아직 그 테스트를 안 돌렸습니다. 두 형식을 한 파일에 같이 쓰면 Bun이 파싱 에러를 내고, 그때 꺼짐이 되는 것은 따로 확인했습니다.

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

공식 문법으로 이미 켜 둔 사람의 주소를 이번부터 바꿀지입니다. 고치려던 그 구멍이면 맞습니다. 키 없는 기본 대화가 403을 보기 시작하는 것도 같이 옵니다. 시험 프로필은 새 ID라 기존 opencodex 제공자를 덮지 않습니다. 계정으로 확인하기 전에는 그 예제를 기본 사용법처럼 두지 않는 편이 안전합니다.

env_http_headers는 지금 주입 코드가 더 이상 안 만드는 옛 형식입니다. Codex가 env_key를 거절해서 문서에서만 다시 씁니다. 주입은 그대로 두고 문서에만 둘지 정해 주세요.

너의 추천

Draft로 두세요. 머지하지 마세요. 가이드를 사이드바에 넣고, bun test tests/codex-integration/context-compat.test.ts와 작성자가 적은 history·ownership 테스트를 호스트에서 통과시킨 뒤에 다시 보면 됩니다. 불리언을 알아보는 함수 수정은 맞습니다.

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

[lidge-jun]

추가 리뷰 · 우선순위 62 / 80

지난 리뷰 다음에 고친 코드는 없습니다. src/codex/context-compat.ts, 테스트, 영문 안내, 한국어 안내 네 파일은 지난 커밋 f6988c25와 글자가 같습니다. 커밋 번호만 1974ddef로 바뀌었습니다. 같은 글을 더 새 바닥에 다시 붙인 것입니다. 바닥이 f117c20에서 f6b59da로 옮겼습니다. f6b59da는 doctor가 깨진 agents 경로를 참게 한 #5106입니다.

지금 dev 맨 끝은 40670044입니다. 이 브랜치 바닥보다 커밋 15개가 앞에 있습니다. 그 15개는 이 PR이 만지는 파일을 안 바꿉니다. 패키지 버전은 그대로 2.60.0입니다. types.ts와 config.ts 나누기와는 상관이 없습니다.

아직 Draft입니다. 위생 검사, 라벨, 대상 브랜치 검사는 통과했습니다. Cross-platform CI와 React Doctor는 승인 대기이고 걸린 시간이 0초입니다. 테스트가 돈 것이 아닙니다.

지난번에 말한 문제는 그대로입니다.

docs-site/astro.config.mjs 안내 목록 - guides/codex-native-context가 없습니다. 글 파일은 있지만 왼쪽 메뉴에는 안 나옵니다.

contextExperimentalEnabled - context_management = true도 켠 것으로 보는 수정은 맞습니다. 이미 이렇게 적어 둔 사람은 다음 ocx sync 때 로컬 주소가 /v1에서 /backend-api/codex로 바뀝니다. 기본 loopback은 데이터 키를 안 실어서, history와 notes 요청은 403 context_principal_required가 됩니다.

테스트 - 저장소의 bun test는 이번 커밋에서도 안 돌았습니다. 호스트 CI도 그 테스트를 안 돌렸습니다.

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

지난번과 같습니다. 공식 문법으로 이미 켜 둔 사람의 주소를 이번부터 바꿀지입니다. 그리고 env_http_headers를 문서에만 둘지입니다. 이번 푸시는 둘 다 정하지 않았습니다.

너의 추천

머지하지 마세요. 글이 안 바뀌었으니 추천도 같습니다. 안내를 왼쪽 메뉴에 넣고, bun test tests/codex-integration/context-compat.test.ts와 history·ownership 테스트를 호스트에서 통과시킨 다음, dev 맨 끝에 다시 올려 주세요.

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

[luvs01]

Pre-merge items addressed at a876afb:

• Added guides/codex-native-context to the Guides sidebar in docs-site/astro.config.mjs, next to the other Codex guides (EN label + KO translation; only EN/KO pages exist).
• Host Bun 1.4.2 on Windows: bun test --isolate tests/codex-integration/context-compat.test.ts tests/server/context-history.test.ts tests/server/context-history-ownership.test.ts tests/server/data-plane-admission-identity.test.ts — 78 pass, 0 fail. The repo's runner defaults to --isolate; without it, context-history.test.ts's mock.module("../../src/server/auth-cors") leaks into the admission-identity file. bun x tsc --noEmit clean.
• Rebased onto current dev tip 838af40f1b2fe32596b207ff85afcda40636f4d9.

The two open decision points are unchanged: docs-only env_http_headers, and whether existing context_management = true users get the base-URL switch. Still draft.

[lidge-jun]

추가 리뷰 · 우선순위 63 / 80

지난 리뷰 다음에 코드 내용은 안 바뀌었습니다. 안내를 왼쪽 메뉴에 넣었고, 같은 글을 더 새 바닥에 다시 붙였습니다. Draft도 풀렸습니다.

src/codex/context-compat.ts, 테스트, 영문 안내, 한국어 안내는 지난 커밋 1974ddef와 글자가 같습니다. 새 커밋 a876afb는 docs-site/astro.config.mjs 한 줄입니다. guides/codex-native-context가 Codex 안내들 옆에 들어갑니다. 영어 제목과 한국어 번역만 있습니다. 페이지도 영문과 한국어만 있습니다. 지난번에 말한 메뉴 구멍은 닫혔습니다.

바닥은 838af40입니다. 지금 dev 맨 끝은 920d8d7b2d66입니다. 그 사이 커밋이 11개입니다. 그 11개는 이 PR이 만지는 파일을 안 바꿉니다. 패키지는 그대로 2.60.0입니다. types.ts와 config.ts 나누기와는 상관이 없습니다.

작성자 댓글은 아직 Draft라고 적었습니다. 지금은 Draft가 아닙니다. review-ready 라벨이 있습니다. 위생 검사, 라벨, 대상 브랜치 검사는 통과했습니다. Cross-platform CI 35455115934와 React Doctor는 승인 대기이고 걸린 시간이 0초입니다. 테스트가 돈 것이 아닙니다. 작성자는 Windows Bun 1.4.2에서 해당 테스트 78개 통과와 tsc 통과를 적었습니다. 그 기록은 이 저장소에 없습니다.

contextExperimentalEnabled - 지난번과 같습니다. context_management = true도 켠 것으로 봅니다. 이미 이렇게 적어 둔 사람은 다음 ocx sync 때 로컬 주소가 /v1에서 /backend-api/codex로 바뀝니다. 기본 loopback은 데이터 키를 안 실어서, history와 notes 요청은 403 context_principal_required가 됩니다.

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

지난번과 같습니다. 공식 문법으로 이미 켜 둔 사람의 주소를 이번부터 바꿀지입니다. 그리고 env_http_headers를 문서에만 둘지입니다. 작성자도 둘 다 아직 안 정했다고 적었습니다.

너의 추천

머지하지 마세요. 메뉴는 들어갔습니다. 호스트 CI가 그 테스트를 돌리기 전에는 작성자의 78개 통과를 확인한 것으로 보지 마세요. 주소 바꾸기와 문서에만 있는 헤더도 먼저 정해 주세요.

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