[RFC] Add a compatibility contract, proxy budgets, and OS-backed credentials

[thatlev]

Area

Multiple areas

What are you trying to accomplish?

Make OpenCodex a dependable multi-provider layer for Codex and ChatGPT-compatible workflows, with three properties users can verify:

1. Native OpenAI requests retain native Responses semantics with negligible proxy overhead.
2. Routed providers expose an explicit compatibility contract instead of silently guessing at unsupported fields or events.
3. Long-lived credentials use the operating system secret store wherever the platform supports one.

The outcome is not a new model or a replacement for the official Codex execution engine. It is a safer, measurable routing layer around it: faster diagnosis, fewer compatibility surprises, and lower credential risk.

What prevents this today?

OpenCodex already has strong provider coverage, loopback-first defaults, remote-auth guards, redirect/private-network protections, bounded state, redaction, and extensive tests. The missing piece is a single, user-visible contract tying compatibility, performance, and credential handling together.

Today:

• Users cannot easily tell whether each Responses field/event is passed through, translated, degraded, or unsupported for a selected provider.
• There is no repeatable direct-vs-proxy benchmark gate for latency, token amplification, streaming correctness, and tool-call behavior.
• Some authentication/account-pool paths persist refresh credentials in owner-only JSON even though the native profile vault already demonstrates OS-backed storage.
• Core routing and Responses behavior is concentrated in several multi-thousand-line modules, increasing regression risk and making provider isolation difficult.
• Reports such as [Bug]: routed first-turn tool catalog is 3–5x native Sol input tokens #1587, Cursor proxy being too slow compared to regular codex subscription #2300, opencode-go/muse-spark-1.2: frequent 'upstream stream ended mid tool call without a terminal signal — possible truncation' in streaming tool calls (Codex App via ocx, Pi direct OK) #2156, and Account pool: continuing a thread after pool selection moves to a new account fails with 400 encrypted content could not be verified (account-bound reasoning ciphertext) #2247 show the practical cost: tool-catalog token amplification, slower routed requests, streaming/tool truncation, and account-switch failures around encrypted content.

A clean-room rewrite would discard a large amount of working compatibility code. The safer path is to harden OpenCodex incrementally behind conformance tests and measurable budgets.

What should OpenCodex do?

I propose an umbrella roadmap delivered as small, independently reviewable PRs:

Phase 1: compatibility contract and differential lab

• Publish a versioned capability manifest for every adapter.
• Classify each supported Responses input, output event, and tool as passthrough, translated, degraded, or unsupported.
• Replay the same request directly and through OpenCodex, comparing semantic output, streaming order, tool calls, usage accounting, and error shape.
• Generate a machine-readable compatibility matrix from fixtures so documentation cannot drift from behavior.

Phase 2: measurable performance budgets

• Benchmark native passthrough, routed text, parallel tool calls, large tool catalogs, long conversations, and streaming.
• Report local routing overhead, time to first event, end-to-end latency, token delta, peak memory, and bundle size.
• Initial targets: under 100 ms local native-path overhead; under 5% p50 end-to-end overhead; at least 15% less avoidable input-token amplification on tool-heavy routes, with a 30% stretch goal; and no dropped or reordered required tool-call deltas.
• Make regressions fail dedicated CI only after maintainers agree stable baselines.

Phase 3: credential boundary

• Move OAuth refresh tokens and account-pool credentials to Keychain, Credential Manager, or Secret Service.
• Keep encrypted-file fallback explicit and opt-in where no OS vault exists.
• Store only opaque credential references in configuration files.
• Preserve a documented, lossless migration and rollback path.
• Prevent provider adapters from reading or mutating credentials/configuration outside a narrow broker interface.

Phase 4: isolate the provider core

• Extract a small, versioned protocol core and adapter interface from the large routing/Responses modules.
• Load non-native adapters lazily, with schema validation and explicit resource limits.
• Preserve the official Codex execution engine and native OpenAI Responses path; do not rebuild orchestration already provided upstream.
• Introduce stable/LTS and preview/nightly compatibility channels.

Each phase should land only with focused regression tests, documentation, and a migration note. No flag-day rewrite is required.

Example usage or interface

One possible interface (names are illustrative):

# Explain a routed request before sending it.
ocx compatibility explain --provider anthropic --model claude-opus-4-1 --features previous_response_id,parallel_tool_calls,tool_search

# Compare direct OpenAI behavior with the OpenCodex path.
ocx benchmark responses --provider openai --scenario tool-heavy --runs 20 --output benchmark.json

# Audit storage without printing secret values.
ocx auth audit

Example compatibility output:

previous_response_id  passthrough
parallel_tool_calls   translated (conformance: pass)
tool_search           degraded: provider-side discovery unavailable
max_tool_calls        unsupported: request rejected before dispatch
credential_storage    os-vault

Example acceptance output:

native passthrough p50 overhead: 42 ms  PASS (<100 ms)
end-to-end p50 delta:             2.8%   PASS (<5%)
stream/tool event conformance:    48/48  PASS
input-token delta, tool-heavy:   -21.4%  PASS (>=15% reduction)

The first implementation PR could be limited to the capability-manifest schema plus conformance fixtures for the native OpenAI adapter. That gives later performance, security, and adapter refactors a trusted baseline.

Alternatives or workarounds

• Keep the current implicit contract and fix provider regressions case by case. Lowest immediate cost, but it does not reduce diagnosis time or architectural risk.
• Rewrite OpenCodex from scratch. This would simplify some modules but discard mature compatibility and create a long period with lower confidence.
• Use only the official Codex/OpenAI path. This is the best default when multi-provider routing is unnecessary, but it does not serve OpenCodex's core use case.
• Implement credentials, benchmarks, and adapter cleanup as unrelated PRs. They can be separate PRs, but an agreed umbrella contract prevents the pieces from optimizing against different goals.

Additional context

This proposal follows a local architecture and verification pass over the repository. Type checking, privacy checks, dependency audit, GUI lint, and GUI production build passed. Focused GUI tests passed after installing GUI dependencies. The broader suite ran thousands of cases but is not claimed here as a completed full-suite run.

The review found a strong existing security baseline, so this is a hardening proposal, not a claim that OpenCodex is currently insecure.

Expected benefit:

• Peace of mind and correctness: the largest gain, from explicit compatibility and conformance evidence.
• Security: meaningful, especially for stolen-disk, backup, or accidental-file-exposure scenarios.
• Maintainability: major, from smaller boundaries and isolated adapters.
• Performance: modest on the native path, potentially substantial for tool-heavy routed requests.
• Model quality: unchanged; this improves delivery of model capability, not the model itself.

Related reports: #1587, #2300, #2156, #2247. I am happy to split the work into maintainer-approved phases and start with the compatibility manifest/conformance slice.

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]

리뷰 · 우선순위 44 / 80

설명: 이 이슈는 새 모델이 아니다. OpenCodex를 믿을 수 있는 라우팅 층으로 굳히려는 큰 지도다. 세 가지를 사용자에게 보여 주자고 한다. 하나는 네이티브 OpenAI 요청이 거의 그대로 지나가게. 하나는 라우팅된 프로바이더가 어떤 필드를 통과하고, 바꾸고, 깎고, 거절하는지 표로 보여 주게. 하나는 오래 사는 비밀을 운영체제 금고에 넣게. 지금 CURRENT dev HEAD는 ced9a85c5 이다. 이 브랜치 끝은 지난 시간 그대로다. 착지한 것은 문서뿐이다. #2348 WP4 감사(0 P0/P1, P2 두 개, 전체 스위트 14264 통과), #2349 GO 판정. 코드 마지막은 여전히 #2346 Opus Fast 카탈로그다. 메인테이너가 preview/main 에 v2.31.0 태그를 올렸지만 그건 origin/dev 가 아니다. 이 RFC는 dev 위의 이야기다. 1단계는 지금 코드에 없다. 어댑터마다 통과/번역/깎임/미지원을 한 장에 모은 매니페스트가 없다. ocx compatibility explain 같은 명령도 없다. 2단계는 이미 열린 구멍과 겹친다. #1587 은 라우팅 첫 턴 도구 목록이 네이티브보다 토큰이 몇 배다. #2300 은 Cursor 프록시가 느리다. #2156 은 스트림이 도구 호출 중간에 끊긴다. 본문이 인용한 #2247 암호화 이어가기 실패는 이미 닫혀 있다. 그 네 장을 이 RFC 하나로 합치지 않는다. 3단계는 반만 맞다. 네이티브 메인 프로필은 이미 OS 금고를 쓴다. src/codex/native-profile-store.ts 가 @napi-rs/keyring 으로 서비스 opencodex.native-main-profile.v1 키를 넣고, 금고가 없으면 평문 폴백을 금지한다. 그런데 OAuth 리프레시 토큰은 여전히 ~/.opencodex/auth.json 이다. 서드파티 API 키 풀은 src/providers/api-keys.ts 주석대로 config.json 의 apiKeyPool 에 산다. 그게 이미 열린 #1221 이다. 4단계는 위험하다. src/types.ts 는 이미 AUTO-SPLIT 배럴이고 몸은 src/types/* 에 있다. 라우팅과 Responses 큰 모듈을 지금 쪼개 다시 짜면 Cursor 라운드와 GO 직후 레인을 멈춘다. 깨끗한 재작성은 본문도 거절한다. 그 거절을 지킨다. Cursor #2334 CursorCredentialRouter 는 여전히 src/providers/cursor-pool.ts 모듈+테스트만 있고 어댑터에 연결되지 않았다. #2332 H2 풀은 discovery 전용, 종료 훅은 #2338. Run 은 자기 세션. #2320 overflow 매핑은 dev 에 있고 #2342 size prior 가 provably-small 만 429 로 좁힌다. 카탈로그 팁은 Ox Alpha x-preview-f-free + deepseek-v4-flash-vision-exp. package.json 은 아직 2.27.0. #2188 사이드카+routed vision 은 이미 dev. 지도는 필요하지만 지금 핫픽스가 아니라서 44.

src/codex/native-profile-store.ts @napi-rs/keyring - 네이티브 메인 프로필만 OS 금고다. 평문 폴백을 막는다. OAuth/API 키 길이 아니다
src/oauth/store.ts ~/.opencodex/auth.json - 리프레시 토큰이 소유자 전용 JSON에 남는다. 3단계의 실제 구멍
src/providers/api-keys.ts apiKeyPool - 서드파티 키가 config.json 에 산다. 이미 열린 #1221 과 같은 장
issue #1587 / #2300 / #2156 OPEN, #2247 CLOSED - 성능·스트림 구멍은 각자 연다. 이 RFC로 합쳐 닫지 말 것
src/types.ts AUTO-SPLIT 배럴 - 4단계 재작성의 핑계가 되지 않는다. 이미 몸이 src/types/* 로 나뉘어 있다

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

• 우산 RFC로 열어 두고 1단계 매니페스트만 받을지, 이슈를 방향만 적고 닫을지
• OS 금고 이전을 Store third-party provider API keys in the OS keychain (currently plaintext in config.json) #1221 한 장으로 둘지, 이 RFC 3단계로 이름을 바꿀지
• 벤치 게이트를 CI 필수에 넣을지, 메인테이너가 기준을 고른 뒤에만 넣을지

너의 추천
이 이슈는 우산으로 연다. 지금 Cursor round-3 / 미연결 라우터(#2334)를 막거나 묶지 않는다. 첫 PR은 능력 매니페스트 스키마와 네이티브 OpenAI 어댑터 픽스처만 넣는다. 명령 ocx compatibility explain 은 그 다음이다. #1221 키체인, #1587 토큰 증폭, #2300 Cursor 지연, #2156 스트림 끊김은 각자 연다. 이 장으로 합쳐 닫지 말 것. #2247 은 이미 닫혀 있으니 근거로 다시 열지 말 것. 라우팅/Responses 재작성(4단계)은 하지 않는다. types.ts/config.ts 스플릿이 매니페스트 파일을 이미 옮긴 뒤에야 충돌이 보이면 리베이스하지 말고 닫고 다시 연다. 지금은 그 정도 아님. 라벨은 그대로 둔다. 프리뷰 배포가 아니다.

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

[Ingwannu]

Implemented the maintainer-approved Phase 1 slice in #2439.

The PR adds a strict passive manifest schema plus one exact fixture-backed subject (openai / forward auth / openai-responses / gpt-5.6-sol). It deliberately does not add the CLI/GUI surface, broaden claims to other providers, change request routing, or close this umbrella RFC.

Local focused tests, typecheck, privacy scan, and docs build pass. I requested @lidge-jun's review and will leave the PR unmerged until another maintainer approves it and exact-head required CI is green.