89bf7657a2
Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
---
|
|
created: 2026-09-03
|
|
status: in_progress
|
|
requirements:
|
|
- REQ-PLATFORM-PROVIDER-ERROR-RECOVERY-001
|
|
system_design:
|
|
- ../../specs/platform/system-design/provider-error-recovery.md
|
|
legacy_specs: []
|
|
---
|
|
|
|
# Implementation Plan: Gateway Proxy Usage Adapters
|
|
|
|
## Overview
|
|
|
|
Add a proxy-usage resolver layer ahead of Kandev's direct provider clients.
|
|
Each gateway supplies a small resolver that recognizes an explicitly selected
|
|
profile configuration and constructs a gateway-native usage client. The initial
|
|
supported gateway set is TeamClaude, OpenRouter, and LiteLLM. TeamClaude is the
|
|
first implementation: a Claude ACP profile with `USAGE_PROXY_VENDOR=teamclaude`
|
|
and loopback `ANTHROPIC_BASE_URL` reads only the TeamClaude status control
|
|
plane. Its result is a pool summary using the least-utilized usable account for
|
|
each known quota window; individual identities and credentials are never
|
|
retained.
|
|
|
|
## Scope
|
|
|
|
### In scope
|
|
|
|
- An ordered, independently testable proxy-resolver seam.
|
|
- A first-class profile proxy configuration (`vendor`, `endpoint`,
|
|
`usage_mode`, and optional credential-secret reference), replacing the
|
|
temporary environment-variable selection before additional vendors ship.
|
|
- A bounded, timeout-controlled TeamClaude status client.
|
|
- An OpenRouter authenticated-key usage client.
|
|
- A LiteLLM configured admin/spend usage client.
|
|
- Pool-level 5-hour, 7-day, Sonnet, and Fable utilization windows.
|
|
- Explicit `USAGE_PROXY_VENDOR` selection plus loopback-only endpoint derivation
|
|
from `ANTHROPIC_BASE_URL`.
|
|
|
|
### Out of scope
|
|
|
|
- Guessing a vendor from an endpoint or agent runtime.
|
|
- Forwarding a profile API key to an endpoint without an explicit proxy
|
|
configuration and secret reference.
|
|
- Account switching, usage polling, or dynamic-routing admission changes.
|
|
- Changing direct Anthropic or OpenAI usage clients.
|
|
|
|
## Work orders
|
|
|
|
- [x] [Task 01: Add the proxy usage resolver layer and TeamClaude adapter](task-01-read-teamclaude-pool-utilization.md)
|
|
- [ ] [Task 02: Persist profile proxy configuration](task-02-profile-proxy-configuration.md)
|
|
- [ ] [Task 03: Add OpenRouter key-usage adapter](task-03-openrouter-key-usage.md)
|
|
- [ ] [Task 04: Add LiteLLM configured usage adapter](task-04-litellm-usage.md)
|
|
|
|
## Follow-on provider/error rollout
|
|
|
|
1. Anthropic and TeamClaude: validate upstream 429/500/503/529 plus
|
|
TeamClaude `rate_limit_error` and `proxy_error` fixtures; use the TeamClaude
|
|
pool adapter for proactive availability presentation only.
|
|
2. OpenAI and Codex: complete `rate_limit_exceeded`, `insufficient_quota`,
|
|
invalid API key, model-unavailable, and subscription-limit fixtures.
|
|
3. Gemini and Antigravity: add Google quota/rate-limit, model, authentication,
|
|
and entitlement fixture extractors.
|
|
4. OpenAI-compatible gateways: add a resolver only where the gateway has a
|
|
documented local status API; normalize standard OpenAI JSON and HTTP errors
|
|
for OpenRouter, OpenCode-backed local providers, and LiteLLM-style proxies.
|
|
5. Copilot and Cursor: complete adapter-specific entitlement, authentication,
|
|
and rate-limit fixtures.
|
|
|
|
## Verification results
|
|
|
|
- `cd apps/backend && go test -tags fts5 ./internal/agent/usage` passed.
|
|
- `cd apps/backend && go test -tags fts5 ./internal/backendapp -run
|
|
'TestTeamClaudeStatusURL' -count=1` passed.
|