# Provider guide
Provider construction, request serialization, HTTP transport, catalogs and stream assembly.
## Where to look
| Change | Owner |
| --- | --- |
| Selection validation and construction | `factory.rs` |
| Request/conversation types | `request.rs`; shared `Provider` trait: `openai.rs` |
| Codex/compatible endpoints | `openai/codex.rs`, `openai/compatible.rs` |
| Bodies/headers/catalogs | `openai/{bodies,headers,catalog}.rs` |
| Anthropic Messages | `anthropic.rs`, `anthropic/stream.rs` |
| Claude subscription CLI/relay/admission/inert MCP/replay | `claude_subscription.rs`, `claude_admission.rs`, `claude_inert.rs`, `claude_projection.rs` |
| Attempts/semantic timeout vs byte-idle transport | `openai_stream.rs` / `transport.rs` |
| SSE and Chat/Responses assembly | `sse.rs`, `stream.rs`, `stream/` |
| Duplicate-skill overlay / turn routing / live quota | `skill_projection.rs` / `codex_session.rs` / `codex_usage.rs` |
## Local contracts
- Preparation selects provider; factory validates/builds it. Keep provider-family auth headers separate and Chat Completions/Responses body builders distinct.
- Claude subscription launches installed `claude -p` with one placeholder prompt; relay supplies complete ordered host history. No SDK or native session replay. Keep CLI/inert MCP in Rust's process group; require native assistant/result/message_stop, accepted exit and complete upstream validation before tool release. Relay admits one official Messages request and fails closed on history replacement; headers stay memory-only. Retry flags do not replace admission enforcement. No mirrored sessions, API-key fallback or automatic billing/model changes. Exact model capacity policy lives in `providers.rs`; metadata cannot raise it. See `docs/features/claude-subscription.md`.
- `prompts/claude-cli.md` appends subscription-only tool instructions; include it in request token estimates. Complete rejected tool calls become failed host tool results without dispatch. Preserve native call names for Claude replay, and strip Claude-only replay metadata from other providers' wire items.
- Codex web search uses `openai/codex/web_search.rs` and existing transport/auth refresh. Bound raw SSE, require `response.completed`, retain citations and distinguish synthesis from page content. No experimental endpoint or Exa fallback.
- Codex replay replaces null role content with space, removes role `tool_calls` and reasoning/function-call `id`/`status` while retaining calls/outputs and identity.
- Preparation gates primary reasoning updates. Durable `ProviderConversationItem::ReasoningSelection` projects eligible ordered `configuration_update` items with original effort; body builders omit unprojected selections.
- Duplicate-skill replacement is request-owned overlay with validated earlier witnesses and serializer call-ID filtering. Retain raw storage, rebuild after conversation changes; no disk reads or cross-request availability state.
- Fast tier/routing diagnostics alone are not semantic progress. Preserve partial arguments, call IDs, response order and terminal events; bound event/argument buffers. Retry policy belongs above parsers.
- Distinguish byte-idle from semantic-progress failure; honor workload-specific configured timeouts. Redact catalog/wire diagnostics; terminal streaming boundaries belong to output owners.
- Codex routing is turn-scoped: conversation session ID stays stable, children distinct, server turn state private/bounded and unchanged across retries. Reset on turn/account changes; never persist state or salts. Prefix diagnostics are local-only.
- Quota uses stored Codex OAuth, bounded direct HTTP and one refresh on 401; never substitute cached quota after failure.
Request-body profiling: `openai/profiling.rs`; shared parser workload: `../profiling/profile_harness/cpu.rs`. Neither establishes live auth/stream behavior.