# src/providers KNOWLEDGE BASE
## OVERVIEW
Provider transport/auth boundary for OpenAI Codex, Anthropic, Claude Code CLI bridge, and custom OpenAI-compatible endpoints. Owns request shape, stream parsing, retry/cancel semantics, sanitized errors, and model catalog fetches.
## STRUCTURE
```text
src/providers/
├── mod.rs # provider exports, IDs/default models, shared trait/types
├── request.rs # ProviderRequest, conversation/tool/result items, defaults
├── stream/ # stream parser implementations and reasoning/tool assembly helpers
├── openai_stream.rs # shared OpenAI-family streaming attempts and semantic timeout
├── transport.rs # blocking reqwest transport, timeout/read-idle diagnostics
├── error.rs # provider error categories and redacted diagnostics
├── prompt_dump.rs # provider request preview path
├── openai/ # Codex Responses API and custom compatible endpoints/catalog
├── anthropic.rs # Anthropic Messages API provider and stream parser
└── claude_code/ # Claude Code auth/body/header bridge
```
## WHERE TO LOOK
| Module surface | `mod.rs` | Provider exports, IDs, defaults, shared trait/types. Keep boundary crate-private unless tests prove public need. |
| Request model | `request.rs` | Conversation items, tool mode, reasoning, text verbosity, cache key, default provider/model mapping. |
| Stream events | `stream/`, `openai_stream.rs` | `ProviderEvent`, tool-call assembly, usage, reasoning summaries, buffer limits, semantic progress. |
| HTTP boundary | `transport.rs` | Blocking `reqwest`, timeout threads, bounded/redacted error bodies, transport test doubles. |
| Provider errors | `error.rs` | Retryability, sanitized diagnostics, user-visible failure categories. |
| Prompt dump | `prompt_dump.rs` | Provider request preview path. Redaction still required. |
| OpenAI family | `openai/` | Codex Responses API plus custom compatible chat-completions/responses bodies, headers, catalog. |
| Anthropic | `anthropic.rs` | Messages API, Anthropic SSE parser, tool-use/result shape, model catalog. |
| Claude Code | `claude_code/` | Claude Code auth/header/body modules; Anthropic-like stream parser, separate credential path. |
## CONVENTIONS
- Provider IDs own credential lanes: `openai-codex` uses Codex OAuth/account data, `anthropic` uses Anthropic API keys, `claude-code` uses Claude Code credentials, compatible endpoints use configured endpoint keys.
- OpenAI Codex uses ChatGPT/Codex OAuth/account headers. Custom compatible uses explicit compatible endpoint/key path.
- Anthropic uses `x-api-key` Messages API headers. Claude Code uses Claude Code auth/header/body modules, not Anthropic API-key path.
- Transport stays blocking `reqwest`. No casual async fork, no second stream driver.
- Provider tool schemas live in request/body builders. OpenAI/Codex, Anthropic, Claude Code shapes differ; do not normalize by wish.
- Preserve event order: text deltas, reasoning summary deltas/completion, response items, tool calls, usage, done.
- Preserve tool-call IDs and argument accumulation. Tool result replay depends on exact IDs.
- Retry only before semantic progress. Cancellation checks must survive header wait, stream read, and backoff sleep.
- Usage parsing matters for token reports and cache accounting; keep partial/final usage semantics distinct.
- Transport diagnostics must be redacted before surfacing through errors, prompt dumps, fixtures, or catalog/debug paths.
## ANTI-PATTERNS
- Do not feed Claude Code subscription auth into Anthropic API-key transport.
- Do not reorder stream events, collapse tool-call chunks early, drop `call_id`, or emit `Done` before terminal completion.
- Do not broaden retry buffering, wall timeouts, idle timeouts, semantic timeouts, or buffer caps without focused cancellation/redaction tests.
- Do not push provider-specific body/header quirks into CLI/TUI/agent dispatch; keep shape code here.
- Do not persist prompt dumps or diagnostics with secrets, raw bearer headers, auth codes, account ids, or credential JSON.