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

The proposal spans compatibility, benchmarking, credential storage, and provider-core architecture rather than naming specific files or tests. Start by reading the existing native OpenAI adapter and its Responses tests; the author identifies the capability-manifest schema and native-adapter conformance fixtures as a possible first PR. Done for that slice means the manifest and fixtures establish a testable compatibility baseline.

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 #1587, #2300, #2156, and #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.