Provider Adapters & Quirks

This reference details the credential sources, endpoint contracts, quota window structures, error handling, and vendor-specific quirks for the providers with dedicated sections below. Muse has no section here; its specification lives in the README provider notes.

1. Anthropic Claude (claude)

• Credential Sources (evaluated in order):
  1. env (CLAUDE_CODE_OAUTH_TOKEN): Takes top precedence because Claude Code resolves environment tokens before opening local stores. It has no expiresAt or refresh token; never invent either and never route it through delegated refresh. claudeEnvOauthToken in src/lib/claude-profile.ts is the single reader. claudeCredentialContextId includes an env marker to prevent serving stored-credential cache snapshots for environment sessions.
  2. oauth-file: Reads the local profile credentials file.
  3. keychain: macOS Keychain item matching Claude Code's validated user account selector. Ambiguous service-only queries are forbidden. Value reads require an existing non-secret access marker (0600) or --allow-keychain-prompt. Keychain failures (including exit 44) must never retire the cache.
• Quota Windows:
  • Windows can include five_hour, seven_day, seven_day_opus, and extra_usage.
  • When the OAuth usage payload includes a limits array, that array is authoritative over top-level fields. It exposes active limits, including model-scoped limits (e.g. Fable) via scope.model.display_name, assigned window ID model:<slug>.
• Soft Expiry: A stored-expired, refreshable Claude token definitively rejected by the endpoint produces authStatus: expired_refreshable (a soft failure retaining cache), never auth_required.
• Native Quota Probe: Bounded opt-in native inference quota probe lives in src/providers/claude-native-quota.ts. Keep it distinct from delegated refresh.
• Delegated Refresh: Permitted via claude doctor only when no Claude Code process is running (src/lib/running-processes.ts).