Plan: production-grade Anthropic compatibility takeover from #107 (canary-first)

[joeblack2k]

Goal

Take over and harden Anthropic support from PR #107 into reviewable, low-risk slices with high Claude API compatibility (including Claude Code behavior).

Hard rollout rule

• Canary-only until explicit maintainer approval for main/live promotion.
• No production/main compose switch in this track without written approval in PR/issue.

Scope split (recommended PR sequence)

PR-A: anthropic-core-protocol

• POST /claude/v1/messages non-stream and stream contract parity
• Strict Anthropic request/response/error envelope mapping
• SSE event ordering parity (message_start, content_block_*, message_delta, message_stop, error)
• Header handling (x-api-key, anthropic-version, anthropic-beta)
• Contract tests with golden fixtures

PR-B: anthropic-runtime-auth-routing

• OAuth/API token refresh and retry policy (401 and revoked-token 403)
• Provider-aware account selection and isolation from OpenAI refresh path
• Safe defaults for SDK pooling (off by default unless proven safe)
• Runtime diagnostics toggles (env-gated)
• Integration tests for auth recovery and account-path correctness

PR-C: anthropic-ops-observability

• Request logs include provider, actor, model, stop reason, usage breakdown
• Cost/usage normalization rules documented and tested
• docs/anthropic-compat-matrix.md with support levels (full/partial/unsupported)
• docs/anthropic-rollout.md with canary test checklist and rollback

PR-D: anthropic-dashboard-ui (optional but clean)

• Account import UX for Anthropic credentials
• UI provider indicators/badges separated from backend protocol work
• Frontend tests scoped to Anthropic UI changes

Compatibility target matrix

• Must: /claude/v1/messages API compatibility (non-stream + stream)
• Should: /claude/v1/models, /claude/v1/messages/count_tokens
• Nice-to-have: beta feature passthrough where safe

Validation gates (each PR)

• Ruff/ty/pytest green
• Frontend checks green (if touched)
• No regression for existing /v1/* OpenAI-compatible routes
• Canary smoke tests attached in PR body with HTTP codes and sample payload traces

Proposed ownership model for multi-agent work

• One owner per PR slice, plus one reviewer from another slice
• Freeze force-push after first review unless branch cleanup is requested
• Keep PR bodies in format: Summary / Why / Validation / Risks / Rollback

References

• Draft implementation: feat(anthropic): use official Anthropic endpoints/models with API+SDK routes #107
• Related contrast PRs: feat(anthropic): add dedicated Claude-compatible endpoint layer #97, feat(proxy): embeddings + actor overrides + oauth callback paste + response-item compat #102, fix(round-robin): harden runtime locking and per-app balancer state #112

[joeblack2k]

Execution tracks created:

• Track A: Anthropic core protocol parity (/claude/v1/messages) #115 (core protocol)
• Track B: Anthropic runtime/auth/routing hardening #116 (runtime/auth/routing)
• Track C: Anthropic observability + compat docs #117 (observability/docs)
• Track D: Anthropic dashboard UX follow-up #118 (dashboard UX)

Collaboration rule for this thread:

• canary-only rollout until explicit approval for main/live promotion.

[joeblack2k]

Track A status update:

• PR opened: feat(anthropic): Track A core protocol parity for /claude messages #119
• includes core Anthropic protocol slice + tests
• canary-only gate preserved