From 6719b712b73fd3ba61d0b6f78b05ab0636656413 Mon Sep 17 00:00:00 2001 From: rune-oai <157205701+rune-oai@users.noreply.github.com> Date: Sun, 15 Nov 2026 19:32:57 -0800 Subject: [PATCH 1/3] Pool every provider's limits, weigh accounts by plan, add a reset calendar One home hub should treat every subscription it holds the same way, and an account on a bigger plan should count for more. This brings Grok, Gemini (Antigravity), Kimi, Muse, Devin and Mistral up to what Claude and Codex already had, and makes pooled figures and routing plan-aware. - Quota history records every provider, and each one gets the same pool card on the Overview page. Pool figures read in percent of the heaviest plan (Max 5x 100% + Pro 20% = "of 120%"). - A Resets view shows every account window on a calendar with the next resets and the allowance still unspent on each. Account details open in the table row instead of separate cards. - soonest-reset-first spreads ties by plan weight, guards 5-hour headroom, and no longer sends work to a spent account while one with allowance is only on hold. - Burn rate copes with whole-percent readings and bursty use; projections are capped by what the 5-hour window allows. - Mistral API-key upstreams report their monthly API and Vibe Code budgets. - A Windows migration script moves a CLIProxyAPI hub over in place, and `doctor -check-config` validates a config before the switch. - Guides for every provider, T3 Code environments over Tailscale, and box setup. New logo. T3 Code is unchanged; `/v0/management` stays pinned by its contract test. Co-Authored-By: Claude Fable 5.2 --- AGENTS.md | 2 +- CHANGELOG.md | 64 ++ README.md | 32 +- assets/brand/banner-dark.svg | 20 +- assets/brand/banner-light.svg | 20 +- assets/brand/fox.svg | 20 +- assets/brand/icon.svg | 41 +- config.example.yaml | 28 +- deploy/windows/migrate-windows.Tests.ps1 | 258 ++++++ deploy/windows/register-task.ps1 | 85 +- docs/README.md | 8 +- docs/agents.md | 23 +- docs/box-setup.md | 179 ++++ docs/configuration.md | 6 +- docs/environments.md | 331 +++++++ docs/management-api-v8.md | 35 +- docs/migrating.md | 308 ++++++- docs/providers.md | 268 ++++++ docs/quota-history.md | 142 ++- docs/routing.md | 134 ++- docs/setup.md | 22 +- docs/t3code.md | 60 +- docs/troubleshooting.md | 52 ++ .../api/handlers/management/quota_history.go | 97 ++- .../management/quota_history_mistral_test.go | 144 ++++ .../handlers/management/quota_history_test.go | 6 + .../quota_history_transport_test.go | 133 +++ .../management/routing_plan_weights.go | 34 + .../management/routing_plan_weights_test.go | 108 +++ internal/api/server_management_v8.go | 1 + internal/api/server_management_v8_test.go | 1 + internal/config/config_load.go | 3 + internal/config/config_types.go | 12 + internal/config/parse.go | 3 + internal/config/plan_weights.go | 77 ++ internal/config/plan_weights_test.go | 69 ++ internal/config/quota_history.go | 4 +- internal/config/quota_history_test.go | 7 +- internal/doctor/config_check.go | 247 ++++++ internal/doctor/config_check_test.go | 185 ++++ internal/doctor/doctor.go | 19 + internal/quotahistory/mistral_test.go | 291 +++++++ internal/quotahistory/parse.go | 17 +- internal/quotahistory/parse_providers.go | 321 +++++++ internal/quotahistory/parse_providers_test.go | 102 +++ internal/quotahistory/providers.go | 335 ++++++++ internal/quotahistory/providers_test.go | 277 ++++++ internal/quotahistory/recorder.go | 304 +++++-- internal/quotahistory/recorder_test.go | 2 +- internal/quotahistory/scoped_publish_test.go | 134 ++- internal/quotahistory/settings.go | 13 +- .../quotahistory/testdata/antigravity.json | 14 + internal/quotahistory/testdata/devin.json | 9 + internal/quotahistory/testdata/kimi.json | 9 + internal/quotahistory/testdata/meta.json | 8 + internal/quotahistory/testdata/plugin.json | 7 + internal/quotahistory/testdata/xai.json | 10 + scripts/migrate-windows.ps1 | 750 ++++++++++++++++ sdk/api/handlers/handlers.go | 3 + sdk/api/handlers/handlers_context.go | 41 + sdk/api/handlers/handlers_stream.go | 1 + .../openai/openai_responses_websocket.go | 360 ++++---- .../openai_responses_websocket_forward.go | 46 +- .../openai_responses_websocket_loss_test.go | 344 ++++++++ .../openai/openai_responses_websocket_test.go | 315 +++++++ sdk/cliproxy/auth/conductor_cooldown.go | 6 + sdk/cliproxy/auth/conductor_execution.go | 6 +- sdk/cliproxy/auth/conductor_home.go | 2 +- sdk/cliproxy/auth/conductor_selection.go | 37 +- sdk/cliproxy/auth/home_retry_loop_test.go | 36 + sdk/cliproxy/auth/plan_headroom.go | 186 ++++ sdk/cliproxy/auth/plan_weight.go | 288 +++++++ sdk/cliproxy/auth/plan_weight_test.go | 167 ++++ .../auth/quota_windows_council_test.go | 177 ++++ .../auth/quota_windows_observation.go | 246 ++++++ .../auth/quota_windows_observation_test.go | 131 +++ sdk/cliproxy/auth/selector.go | 12 + sdk/cliproxy/auth/selector_affinity_scoped.go | 50 ++ .../auth/selector_affinity_scoped_test.go | 77 ++ sdk/cliproxy/auth/selector_reset.go | 198 ++++- .../auth/selector_reset_cooling_test.go | 153 ++++ sdk/cliproxy/auth/selector_reset_plan_test.go | 251 ++++++ sdk/cliproxy/auth/selector_reset_scoped.go | 2 + sdk/cliproxy/builder.go | 3 + sdk/cliproxy/executor/types.go | 2 + sdk/cliproxy/service_config.go | 4 + web/DESIGN.md | 4 +- web/index.html | 2 +- web/src/assets/brand/fox.svg | 20 +- web/src/assets/brand/icon.svg | 41 +- web/src/assets/brandLogo.ts | 2 +- web/src/assets/icons/mistral.svg | 1 + web/src/features/authFiles/constants.ts | 30 +- .../sections/SectionQuotaHistory.tsx | 2 +- .../features/connect/ConnectPage.module.scss | 30 + web/src/features/connect/ConnectPage.tsx | 69 +- web/src/features/connect/snippets.ts | 63 ++ web/src/features/quota/QuotaPage.module.scss | 86 +- web/src/features/quota/QuotaPage.tsx | 809 ++++++++++++------ .../features/quota/__fixtures__/devFixture.ts | 79 +- .../__fixtures__/multiProviderHistory.ts | 188 ++++ .../features/quota/__fixtures__/ownerPool.ts | 245 ++++++ .../quota/__fixtures__/resetCredits.ts | 3 + web/src/features/quota/accountRows.ts | 93 +- .../components/AccountDetail.module.scss | 307 +++++++ .../quota/components/AccountDetail.tsx | 327 +++++++ .../quota/components/OtherAccountsTable.tsx | 109 +++ .../components/PoolAccountsTable.module.scss | 119 +++ .../quota/components/PoolAccountsTable.tsx | 279 ++++-- .../features/quota/components/PoolChart.tsx | 36 +- .../quota/components/QuotaCard.module.scss | 40 +- .../components/QuotaPoolCard.module.scss | 73 +- .../quota/components/QuotaPoolCard.tsx | 492 ++++++++--- .../quota/components/QuotaPoolToolbar.tsx | 39 +- .../components/QuotaTimeline.module.scss | 404 --------- .../quota/components/QuotaTimeline.tsx | 484 ----------- .../quota/components/ResetsView.module.scss | 517 +++++++++++ .../features/quota/components/ResetsView.tsx | 658 ++++++++++++++ web/src/features/quota/components/SpanNav.tsx | 50 ++ web/src/features/quota/constants.ts | 21 +- .../features/quota/hooks/usePlanWeights.ts | 164 ++++ .../features/quota/hooks/useSettledQuota.ts | 39 + web/src/features/quota/liveWindows.ts | 256 ++++++ web/src/features/quota/poolFormat.ts | 61 +- web/src/features/quota/poolModel.ts | 788 ++++++++++++++--- web/src/features/quota/poolPrefs.ts | 73 +- web/src/features/quota/poolWindowLabels.ts | 166 ++++ .../preview/QuotaTierPreview.module.scss | 9 +- .../quota/preview/QuotaTierPreview.tsx | 127 ++- web/src/features/quota/resetCalendarModel.ts | 439 ++++++++++ web/src/features/quota/uiState.ts | 38 +- web/src/i18n/locales/en.json | 157 +++- web/src/services/api/index.ts | 1 + web/src/services/api/planWeights.ts | 132 +++ web/src/services/api/quotaHistory.ts | 64 +- web/src/utils/quota/constants.ts | 4 + web/tests/antigravityQuotaTimeline.test.ts | 36 - web/tests/connectSnippets.test.ts | 65 ++ web/tests/fixtures/ownerHistory.json | 1 + web/tests/planWeights.test.ts | 92 ++ web/tests/quotaAccountDetail.test.ts | 242 ++++++ web/tests/quotaBurnBacktest.test.ts | 75 ++ web/tests/quotaBurnProjection.test.ts | 285 ++++++ web/tests/quotaLivePools.test.ts | 317 +++++++ web/tests/quotaPoolModel.test.ts | 551 +++++++++++- web/tests/quotaResetCalendar.test.ts | 242 ++++++ web/tests/quotaResetInstants.test.ts | 4 +- web/tests/quotaResetsDst.test.ts | 91 ++ web/tests/quotaResetsRendering.test.ts | 135 +++ web/tests/quotaSettledQuota.test.ts | 31 + web/tests/quotaTimelineDst.test.ts | 114 --- web/tests/quotaTimelineRendering.test.ts | 164 ---- web/tests/quotaUiState.test.ts | 21 + 153 files changed, 17269 insertions(+), 2472 deletions(-) create mode 100644 deploy/windows/migrate-windows.Tests.ps1 create mode 100644 docs/box-setup.md create mode 100644 docs/environments.md create mode 100644 docs/providers.md create mode 100644 internal/api/handlers/management/quota_history_mistral_test.go create mode 100644 internal/api/handlers/management/quota_history_transport_test.go create mode 100644 internal/api/handlers/management/routing_plan_weights.go create mode 100644 internal/api/handlers/management/routing_plan_weights_test.go create mode 100644 internal/config/plan_weights.go create mode 100644 internal/config/plan_weights_test.go create mode 100644 internal/doctor/config_check.go create mode 100644 internal/doctor/config_check_test.go create mode 100644 internal/quotahistory/mistral_test.go create mode 100644 internal/quotahistory/parse_providers.go create mode 100644 internal/quotahistory/parse_providers_test.go create mode 100644 internal/quotahistory/providers.go create mode 100644 internal/quotahistory/providers_test.go create mode 100644 internal/quotahistory/testdata/antigravity.json create mode 100644 internal/quotahistory/testdata/devin.json create mode 100644 internal/quotahistory/testdata/kimi.json create mode 100644 internal/quotahistory/testdata/meta.json create mode 100644 internal/quotahistory/testdata/plugin.json create mode 100644 internal/quotahistory/testdata/xai.json create mode 100644 scripts/migrate-windows.ps1 create mode 100644 sdk/cliproxy/auth/plan_headroom.go create mode 100644 sdk/cliproxy/auth/plan_weight.go create mode 100644 sdk/cliproxy/auth/plan_weight_test.go create mode 100644 sdk/cliproxy/auth/quota_windows_council_test.go create mode 100644 sdk/cliproxy/auth/quota_windows_observation.go create mode 100644 sdk/cliproxy/auth/quota_windows_observation_test.go create mode 100644 sdk/cliproxy/auth/selector_affinity_scoped.go create mode 100644 sdk/cliproxy/auth/selector_affinity_scoped_test.go create mode 100644 sdk/cliproxy/auth/selector_reset_cooling_test.go create mode 100644 sdk/cliproxy/auth/selector_reset_plan_test.go create mode 100644 web/src/assets/icons/mistral.svg create mode 100644 web/src/features/quota/__fixtures__/multiProviderHistory.ts create mode 100644 web/src/features/quota/__fixtures__/ownerPool.ts create mode 100644 web/src/features/quota/components/AccountDetail.module.scss create mode 100644 web/src/features/quota/components/AccountDetail.tsx create mode 100644 web/src/features/quota/components/OtherAccountsTable.tsx delete mode 100644 web/src/features/quota/components/QuotaTimeline.module.scss delete mode 100644 web/src/features/quota/components/QuotaTimeline.tsx create mode 100644 web/src/features/quota/components/ResetsView.module.scss create mode 100644 web/src/features/quota/components/ResetsView.tsx create mode 100644 web/src/features/quota/components/SpanNav.tsx create mode 100644 web/src/features/quota/hooks/usePlanWeights.ts create mode 100644 web/src/features/quota/hooks/useSettledQuota.ts create mode 100644 web/src/features/quota/liveWindows.ts create mode 100644 web/src/features/quota/poolWindowLabels.ts create mode 100644 web/src/features/quota/resetCalendarModel.ts create mode 100644 web/src/services/api/planWeights.ts create mode 100644 web/tests/fixtures/ownerHistory.json create mode 100644 web/tests/planWeights.test.ts create mode 100644 web/tests/quotaAccountDetail.test.ts create mode 100644 web/tests/quotaBurnBacktest.test.ts create mode 100644 web/tests/quotaBurnProjection.test.ts create mode 100644 web/tests/quotaLivePools.test.ts create mode 100644 web/tests/quotaResetCalendar.test.ts create mode 100644 web/tests/quotaResetsDst.test.ts create mode 100644 web/tests/quotaResetsRendering.test.ts create mode 100644 web/tests/quotaSettledQuota.test.ts delete mode 100644 web/tests/quotaTimelineDst.test.ts delete mode 100644 web/tests/quotaTimelineRendering.test.ts diff --git a/AGENTS.md b/AGENTS.md index 4bbe2982a32..3fc04a6ceec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,7 +68,7 @@ go build -o test-output ./cmd/server && rm test-output # Verify compile (REQUIRE - Wrap defer errors: `defer func() { if err := f.Close(); err != nil { log.Errorf(...) } }()` - Use logrus structured logging; avoid leaking secrets/tokens in logs - Avoid panics in HTTP handlers; prefer logged errors and meaningful HTTP status codes -- Timeouts are allowed only during credential acquisition; after an upstream connection is established, do not set timeouts for any subsequent network behavior. Intentional exceptions that must remain allowed are the Codex websocket liveness deadlines in `internal/runtime/executor/codex_websockets_executor.go`, the wsrelay session deadlines in `internal/wsrelay/session.go`, the management APICall timeout in `internal/api/handlers/management/api_tools.go`, and the `cmd/fetch_antigravity_models` utility timeouts +- Timeouts are allowed only during credential acquisition; after an upstream connection is established, do not set timeouts for any subsequent network behavior. Intentional exceptions that must remain allowed are the Codex websocket liveness deadlines in `internal/runtime/executor/codex_websockets_executor.go`, the wsrelay session deadlines in `internal/wsrelay/session.go`, the management APICall timeout in `internal/api/handlers/management/api_tools.go`, the quota-history per-account sample timeout in `internal/quotahistory/recorder.go` (a background usage read, not client traffic), and the `cmd/fetch_antigravity_models` utility timeouts - Avoid wall-clock `time.Sleep` in TTL, expiration, ordering, or cache-eviction unit tests due to platform timer granularity (e.g. Windows default timer resolution of ~15.6ms) and CI jitter under load; prefer controllable clocks (`nowFunc` / mock clock), explicit timestamp manipulation, or deterministic synchronization primitives. - Note: `internal/home/` integrates with the separate CLIProxyAPIHome control plane. If you change features that involve it, check whether the CLIProxyAPIHome repository needs a matching update. - Endpoints under the `/v0/management` base URL are a supported compatibility contract: T3 Code reads the hub through `GET /v0/management/auth-files`, `POST /v0/management/api-call` and `POST /v0/management/reset-quota`, pinned by `test/t3code_contract_test.go`. Do not remove them or change their request or response shapes. Add new management features under `/v8/management`. diff --git a/CHANGELOG.md b/CHANGELOG.md index 554d30a5a5f..2521f28af87 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,70 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +### Added + +- Mistral monthly API and Vibe Code budget history for API-key upstreams on `api.mistral.ai`, + with cached subscription plans and optional `budget` and `currency` window fields. These + usage-only windows use account weight 1. +- Plan-aware routing and pooling. Each account's plan is resolved (Claude Pro, Max 5x, Max 20x; + Codex Plus, Pro, and so on) and given a capacity weight, overridable under + `routing.plan-weights` and readable at `GET /v8/management/routing/plan-weights`. + `soonest-reset-first` spreads new conversations by plan weight where accounts are otherwise + equal, and `routing.plan-headroom-reserve` keeps new conversations off accounts whose 5-hour + window is nearly used while another account has room. +- Quota history and `soonest-reset-first` ranking for xAI, Antigravity, Kimi, Meta, Devin and + quota plugins, next to Claude and Codex. With `quota-history.enabled: true`, an upgraded hub now + polls the usage endpoints of all of these providers by default; `quota-history.providers` + limits which ones. +- Web panel: the same pool card for every provider that reports renewing limits (from recorded + history, or from the latest live read when the recorder does not sample that provider), with + pooled figures in percent of the heaviest plan in the pool ("38% of 120%" for Max 5x + Pro), + plan weights saved on the hub, a group picker for providers with many windows such as + Antigravity, and Connect snippets for OpenAI-compatible tools, OpenCode, Gemini clients and + Muse Code. +- Web panel Overview: a **Pools** / **Resets** switch. Resets is a calendar of every account + window across providers (current, upcoming and elapsed windows with what was left unspent at + each reset, banked Codex reset expiries with **Use reset**, monthly windows on the calendar + month), with a **Next resets** list of the soonest resets and their unspent allowance, a window + filter, and the Pools view's span controls. It replaces the old "Quota windows" timeline. +- Web panel: Mistral, read by the hub with an API key and present only in the quota history, gets + a tab, a pool and calendar lanes; windows with a budget read in money beside percent. +- `scripts/migrate-windows.ps1`, which replaces a running CLIProxyAPI Scheduled Task with + t3code-proxy: verified backup, detached switch, authenticated checks, automatic rollback, and a + named-backup rollback. `t3code-proxy doctor -check-config` validates a config without starting + a server. +- Guides for every provider, for T3 Code environments over Tailscale (including Windows with + WSL 2), and an agent-readable box-setup checklist. + +### Changed + +- Web panel Overview: account cards are gone. Each row of an accounts table opens that account's + full read in place (windows and resets, plan details, Claude extra usage, Codex banked resets + and credit overage, xAI usage breakdown and pay-as-you-go, Antigravity groups, errors, and the + per-account actions); accounts without a renewing window list in the same table form. The plan + shares caption under the pool headline is removed (the weight editor stays behind the card's + sliders button), and account emails are shown by default with a **Hide emails** toggle. + +- A conversation bound by session affinity moves to another account before sending when the hub + already knows a window governing that model is spent on the bound account. +- `soonest-reset-first` skips an account when any window governing the model is spent, and + response headers newer than a recorded reading overrule it. +- Behavior change for hubs already on `soonest-reset-first`: the 5-hour headroom guard is on by + default (`routing.plan-headroom-reserve: 10`; `0` turns it off), and tied accounts are spread + by plan weight instead of evenly. +- New logo: a fox head in profile, white and silver on the black tile. + +### Fixed + +- `soonest-reset-first` no longer sends new work to an account it knows is spent while the + account with allowance left is only on a short hold. Seen on a live hub: one "overloaded" + answer put the usable Codex account on a five-minute hold and the next conversations were + refused by the spent account with "usage limit reached", valid for two days. The hub now + answers with a cooldown error and the short wait. +- Taken from upstream CLIProxyAPI (after v8.0.74): a request on a persistent Responses + WebSocket that is refused for quota or auth before any output now fails over to another + account instead of surfacing the refusal. + ## [0.1.0] First release as t3code-proxy. The code base starts from CLIProxyAPI v8.0.72; see diff --git a/README.md b/README.md index bb84c70df5d..f60c6850058 100644 --- a/README.md +++ b/README.md @@ -11,17 +11,23 @@ License: MIT

-t3code-proxy is a hub for your own Claude and Codex subscriptions. You run it on one machine at -home that stays on. It holds every account login, keeps the tokens fresh, and exposes one -OpenAI- and Claude-compatible API on port 8317. Your other machines reach it over Tailscale, and -Claude Code, Codex and the T3 Code app use it through their normal config files. Nothing on the -client side is patched. The setup follows the one Theo Browne describes in his +t3code-proxy is a hub for your own AI subscriptions and API-key providers. You run it on one +machine at home that stays on. It holds account logins, keeps OAuth tokens fresh, and exposes +OpenAI-, Claude-, Gemini- and Codex-compatible APIs on port 8317. It serves Claude, Codex, +Antigravity, Kimi, xAI, Devin and Meta accounts, Google API keys and OpenAI-compatible upstreams. +Your other machines reach it over Tailscale. Claude Code, Codex and T3 Code use their normal +client configuration. The panel pools supported limits with plan-aware weights. See +[providers](docs/providers.md) for current coverage. The setup follows Theo Browne's [token maxing video](https://www.youtube.com/watch?v=D8PikZ1KhUo) and -[gist](https://gist.github.com/t3dotgg/59a521d2ee8d70aaf90e280c175072af); his own hub is private, -and this project is an open-source implementation of it. +[gist](https://gist.github.com/t3dotgg/59a521d2ee8d70aaf90e280c175072af). His own hub is private. +This project is an open-source implementation of it. This project is not affiliated with or endorsed by T3, Anthropic or OpenAI. +**Using subscriptions this way may violate provider terms and can get accounts suspended or +banned. Never serve other people's traffic with your subscriptions. Use Claude subscriptions +only through Claude Code.** Read the [risks and rules](#risks-and-rules) before signing in. + ## How it works ```mermaid @@ -43,11 +49,12 @@ flowchart LR hub --- auth hub --> anthropic["Anthropic"] hub --> openai["OpenAI"] + hub --> others["Google, Kimi, xAI, Devin, Meta
and compatible upstreams"] ``` The hub listens on loopback only. `tailscale serve` publishes it to your tailnet over HTTPS, so -only devices on your tailnet can reach it. Every request to Anthropic and OpenAI leaves from the -hub's home connection. +only devices on your tailnet can reach it. Provider requests leave from the hub's home connection. +T3 Code can run agents on any connected home or cloud [environment](docs/environments.md). ## Features @@ -60,7 +67,9 @@ hub's home connection. - **Codex over WebSockets.** Codex clients that set `supports_websockets = true` use the WebSocket transport through the hub. - **Quota history.** The hub records each Claude and Codex account's quota windows over time. - See [quota history](docs/quota-history.md). + The panel's pooled charts support editable plan weights, so accounts on different plans can + contribute different capacity. See [quota history](docs/quota-history.md) and the + [provider capability table](docs/providers.md#capability-table). - **Web panel.** A management panel is compiled into the binary and served at `/management.html`: pooled limits and banked Codex reset credits, accounts, sign-in, routing, activity, providers, logs and settings, plus a Connect page with ready-to-paste client config @@ -115,6 +124,9 @@ second config directory that leaves your normal client setup untouched. ## Documentation - [Setup guide](docs/setup.md): pick a hub, install, sign in, connect clients. +- [Providers](docs/providers.md) covers every login, API-key upstream and current quota capability. +- [Environments](docs/environments.md) covers T3 Code on other machines, including Windows and WSL 2. +- [Set up a box](docs/box-setup.md) gives an ordered agent checklist for a new execution machine. - [Guide for coding agents](docs/agents.md): for an agent doing the setup on someone's behalf. - [T3 Code](docs/t3code.md): providers, usage provider and limits. - [Routing](docs/routing.md): strategies, soonest-reset-first, session affinity, retries. diff --git a/assets/brand/banner-dark.svg b/assets/brand/banner-dark.svg index 03ed89ab50b..3ef69eb2678 100644 --- a/assets/brand/banner-dark.svg +++ b/assets/brand/banner-dark.svg @@ -1,13 +1,15 @@ - + + t3code-proxy - - - - - - - + + + + + + + + t3code-proxy - One home hub for every Claude and Codex account you own. + One home hub for every AI subscription you own. diff --git a/assets/brand/banner-light.svg b/assets/brand/banner-light.svg index 80b1d8d4b04..87866144c12 100644 --- a/assets/brand/banner-light.svg +++ b/assets/brand/banner-light.svg @@ -1,13 +1,15 @@ - + + t3code-proxy - - - - - - - + + + + + + + + t3code-proxy - One home hub for every Claude and Codex account you own. + One home hub for every AI subscription you own. diff --git a/assets/brand/fox.svg b/assets/brand/fox.svg index 75f40c07514..a24a541c3bf 100644 --- a/assets/brand/fox.svg +++ b/assets/brand/fox.svg @@ -1,10 +1,10 @@ - - t3code-proxy fox - - - - - - - - + + t3code-proxy + + + + + + + + diff --git a/assets/brand/icon.svg b/assets/brand/icon.svg index 40e9e756203..a24a541c3bf 100644 --- a/assets/brand/icon.svg +++ b/assets/brand/icon.svg @@ -1,31 +1,10 @@ - - t3code-proxy - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + t3code-proxy + + + + + + + + diff --git a/config.example.yaml b/config.example.yaml index 2066b1303a4..0f1643c601a 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -183,7 +183,10 @@ routing: # expire unused is spent first. Accounts without a fresh reading are probed first (at most once # an hour), an account whose model-specific weekly cap is spent is skipped for that model while # another is available, providers that report no quota rotate round-robin, and ties rotate. - # Priority tiers still apply; weights are not used. See docs/routing.md. + # Priority tiers still apply; per-credential weights are not used. Ties, probes and pools without + # quota reports are spread in proportion to plan weight instead (see plan-weights below), and an + # account whose 5-hour window is nearly spent gets no new conversation while another has headroom. + # See docs/routing.md. # weighted-round-robin uses each credential's integer weight (default 1, maximum 1,000,000). # Non-positive weights exclude the credential while this strategy is active. # Sticky requests (including inherited and LCP bindings) also consume weighted credits @@ -236,6 +239,24 @@ routing: # Ignored when routing.session-affinity is false. session-affinity-rebind-on: "any" + # Plan capacity weights relative to each provider's base paid plan (1.0), used by + # soonest-reset-first. Built-in: claude pro/team 1, max 5, max_5x 5, max_20x 20 (any max_x + # tier weighs N); codex plus/team/business/enterprise/edu 1, prolite 5, pro 20, promax 50; + # xai supergrok 1, supergrok_heavy 10. The Codex ratios are approximate and change over time. + # Entries here replace the built-in value for that plan; names are case-insensitive and + # "Max 20x" equals "max_20x". + # Each weight must be > 0 and <= 1000. + # plan-weights: + # codex: + # pro: 10 + # claude: + # max_20x: 18 + # Plan-weighted 5-hour headroom reserve, in base-plan percent. Headroom is plan weight x percent + # of the 5-hour window left; an account below the reserve gets no NEW conversation while another + # eligible account has more (bound conversations stay). 10 means Pro is tight below 10% left, + # Max 20x below 0.5%. 0 disables the guard. Range 0-1000. Default: 10 + plan-headroom-reserve: 10 + # When true, unprefixed model requests only use credentials without a prefix (except when prefix == model name). force-model-prefix: false @@ -1333,13 +1354,16 @@ observability: addr: "127.0.0.1:8316" # Quota history recorder. When enabled, the hub polls the usage endpoint of -# every enabled Claude and Codex OAuth credential and stores one sample per poll, so the +# every supported enabled account and stores one sample per poll, so the # management panel can chart remaining quota over time. Disabled by default; when disabled # nothing is polled or written. Changes are applied on config hot-reload. # Endpoints: GET /v8/management/quota-history?since=&until= # POST /v8/management/quota-history/refresh (also mirrored under /v0/management). quota-history: enabled: false + # Provider IDs to poll. Empty enables all supported providers and quota plugins. + # Built-in IDs: claude, codex, xai, antigravity, kimi, kimi-ai, meta, devin, mistral. + providers: [] # Poll interval per account (Go duration or "d"). Default 10m, minimum 5m. interval: 10m # Samples older than this are pruned hourly. Default 35d, minimum 1d. diff --git a/deploy/windows/migrate-windows.Tests.ps1 b/deploy/windows/migrate-windows.Tests.ps1 new file mode 100644 index 00000000000..a37c65cb360 --- /dev/null +++ b/deploy/windows/migrate-windows.Tests.ps1 @@ -0,0 +1,258 @@ +BeforeAll { + . (Join-Path $PSScriptRoot '../../scripts/migrate-windows.ps1') +} + +Describe 'Migration path and task discovery' { + It 'reads a quoted config path and preserves the working directory' { + $directory = Join-Path $TestDrive 'old hub' + [xml]$taskXml = @" + +cli-proxy-api.exe-config "config with spaces.yaml" +$directory +"@ + $install = Get-TaskInstall $taskXml '' '' '' + $install.WorkingDirectory | Should -Be $directory + $install.Config | Should -Be (Join-Path $directory 'config with spaces.yaml') + $install.OldExe | Should -Be (Join-Path $directory 'cli-proxy-api.exe') + } + + It 'requires an override for additional legacy arguments' { + [xml]$taskXml = @" +old.exe +-config config.yaml -login$TestDrive +"@ + { Get-TaskInstall $taskXml '' '' '' } | Should -Throw '*Supply -Config*' + (Get-TaskInstall $taskXml '' 'reviewed.yaml' '').Config | Should -Be (Join-Path $TestDrive 'reviewed.yaml') + } + + It 'rejects multiple actions' { + [xml]$taskXml = '' + { Get-TaskInstall $taskXml '' '' '' } | Should -Throw '*one direct executable*' + } + + It 'quotes native arguments including a trailing backslash' { + ConvertTo-NativeArgument 'C:\old hub\' | Should -Be '"C:\old hub\\"' + ConvertTo-NativeArgument '\' | Should -Be '"\\"' + { ConvertTo-NativeArgument 'a"b' } | Should -Throw + } +} + +Describe 'Verified backups' { + It 'copies hidden state and empty directories and detects a different file' { + $source = Join-Path $TestDrive 'auth' + $destination = Join-Path $TestDrive 'backup' + New-Item -ItemType Directory -Path (Join-Path $source '.codex-refresh'), (Join-Path $source 'empty') -Force | Out-Null + Set-Content -LiteralPath (Join-Path $source '.codex-refresh/journal') -Value 'rotation-state' + Set-Content -LiteralPath (Join-Path $source 'account.json') -Value '{"type":"codex","refresh_token":"do-not-print"}' + $manifest = @(Copy-VerifiedTree $source $destination) + $manifest.Count | Should -Be 4 + (Get-Content -LiteralPath (Join-Path $destination '.codex-refresh/journal') -Raw).Trim() | Should -Be 'rotation-state' + Test-Path -LiteralPath (Join-Path $destination 'empty') | Should -BeTrue + Get-MigrationAccountCount $destination | Should -Be 1 + Set-Content -LiteralPath (Join-Path $destination 'account.json') -Value 'different' + (@(Get-TreeManifest $destination) | ConvertTo-Json -Compress) | Should -Not -Be ($manifest | ConvertTo-Json -Compress) + } + + It 'tolerates a file the running hub holds open in a live copy, but never an account file' { + $source = Join-Path $TestDrive 'live-auth' + New-Item -ItemType Directory -Path (Join-Path $source 'logs') -Force | Out-Null + Set-Content -LiteralPath (Join-Path $source 'account.json') -Value '{"type":"codex"}' + Set-Content -LiteralPath (Join-Path $source 'kv.db') -Value 'store' + Set-Content -LiteralPath (Join-Path $source 'logs/error.log') -Value 'log' + $held = [IO.File]::Open((Join-Path $source 'kv.db'), [IO.FileMode]::Open, [IO.FileAccess]::ReadWrite, [IO.FileShare]::None) + try { + { Copy-VerifiedTree $source (Join-Path $TestDrive 'strict-copy') } | Should -Throw '*cannot be read*' + $manifest = @(Copy-VerifiedTree $source (Join-Path $TestDrive 'live-copy') -Live) + ($manifest | Where-Object Path -eq 'kv.db').Hash | Should -Be 'unreadable' + Test-Path -LiteralPath (Join-Path $TestDrive 'live-copy/kv.db') | Should -BeFalse + Test-Path -LiteralPath (Join-Path $TestDrive 'live-copy/account.json') | Should -BeTrue + Test-Path -LiteralPath (Join-Path $TestDrive 'live-copy/logs/error.log') | Should -BeTrue + } finally { $held.Dispose() } + $heldAccount = [IO.File]::Open((Join-Path $source 'account.json'), [IO.FileMode]::Open, [IO.FileAccess]::ReadWrite, [IO.FileShare]::None) + try { + { Copy-VerifiedTree $source (Join-Path $TestDrive 'live-copy-2') -Live } | Should -Throw '*account file could not be backed up*' + } finally { $heldAccount.Dispose() } + } + + It 'ignores listeners on other addresses for a loopback hub' { + function Get-NetTCPConnection { param($State, $ErrorAction) } + Mock Get-NetTCPConnection { + return @( + [pscustomobject]@{ LocalAddress = '127.0.0.1'; LocalPort = 8317; OwningProcess = 10 }, + [pscustomobject]@{ LocalAddress = '100.64.0.1'; LocalPort = 8317; OwningProcess = 20 }, + [pscustomobject]@{ LocalAddress = 'fd7a::1'; LocalPort = 8317; OwningProcess = 20 }, + [pscustomobject]@{ LocalAddress = '127.0.0.1'; LocalPort = 9000; OwningProcess = 30 } + ) + } + $script:bindHost = '127.0.0.1' + @(Get-HubListener 8317).Count | Should -Be 1 + $script:bindHost = '' + @(Get-HubListener 8317).Count | Should -Be 3 + } + + It 'counts root account JSON without counting journals or unrelated JSON' { + $source = Join-Path $TestDrive 'count' + New-Item -ItemType Directory -Path (Join-Path $source '.codex-refresh') -Force | Out-Null + Set-Content -LiteralPath (Join-Path $source 'one.json') -Value '{"type":"claude"}' + Set-Content -LiteralPath (Join-Path $source 'cache.json') -Value '{}' + Set-Content -LiteralPath (Join-Path $source '.codex-refresh/state.json') -Value '{"type":"codex"}' + Get-MigrationAccountCount $source | Should -Be 1 + } + + It 'redacts malformed auth content' { + $source = Join-Path $TestDrive 'invalid' + New-Item -ItemType Directory -Path $source | Out-Null + Set-Content -LiteralPath (Join-Path $source 'bad.json') -Value 'secret-content-malformed-json' + { Get-MigrationAccountCount $source } | Should -Throw 'Migration: An auth JSON file is invalid or unreadable.' + } +} + +Describe 'Rollback process barriers' { + BeforeAll { + # Cmdlet stubs make the same checks runnable on macOS without Windows access. + function Get-ScheduledTask { param($TaskName, $TaskPath, $ErrorAction) return $true } + function Disable-ScheduledTask { param($TaskName, $TaskPath) } + function Stop-ScheduledTask { param($TaskName, $TaskPath) } + function Enable-ScheduledTask { param($TaskName, $TaskPath) } + function Start-ScheduledTask { param($TaskName, $TaskPath) } + function Register-ScheduledTask { param($TaskName, $TaskPath, $Xml, $Force) } + } + BeforeEach { + $script:events = New-Object 'Collections.Generic.List[string]' + $script:taskCredential = $null + $script:BackupPath = $TestDrive + Set-Content -LiteralPath (Join-Path $TestDrive 'old-task.xml') -Value '' + $state = [pscustomobject]@{ NewTaskName = 'new'; OldTaskName = 'old'; TaskPath = '\'; NewExe = 'new.exe'; OldExe = 'old.exe'; Port = 8317; AccountCount = 2; AuthDir = 'auth'; TaskXmlHash = 'checksum'; BackupPath = $TestDrive } + Mock Get-FileHash { return [pscustomobject]@{ Hash = 'checksum' } } + Mock Get-Content { return '' } + Mock Register-ScheduledTask { $script:events.Add('register-' + $TaskName) } + Mock Disable-ScheduledTask { $script:events.Add('disable-' + $TaskName) } + Mock Stop-ScheduledTask { $script:events.Add('stop-' + $TaskName) } + Mock Enable-ScheduledTask { $script:events.Add('enable-' + $TaskName) } + Mock Start-ScheduledTask { $script:events.Add('start-' + $TaskName) } + Mock Wait-MigrationStopped { $script:events.Add('barrier-' + $Executable) } + Mock Get-MigrationAccountCount { return 2 } + Mock Wait-MigrationHealthy { $script:events.Add('verify-old') } + } + It 'starts the old task only after both executable barriers, without re-registering it' { + Mock Get-ExeProcess { return @() } + Invoke-MigrationRollback $state + ($script:events -join ',') | Should -Be 'disable-new,stop-new,barrier-new.exe,barrier-old.exe,enable-old,start-old,verify-old' + } + It 'keeps the old task stopped and re-enables the new one if the new process cannot be proved gone' { + Mock Get-ExeProcess { return @() } + Mock Wait-MigrationStopped { throw 'Migration: still running' } + { Invoke-MigrationRollback $state } | Should -Throw '*still running*' + Should -Invoke Start-ScheduledTask -Times 0 + ($script:events -join ',') | Should -Be 'disable-new,stop-new,enable-new' + } + It 'still enables and starts the old task when the port stays held after both hubs exited' { + Mock Get-ExeProcess { return @() } + Mock Wait-MigrationStopped { if ($Port -gt 0) { throw 'Migration: port held' } } + { Invoke-MigrationRollback $state } | Should -Throw '*port held*' + Should -Invoke Enable-ScheduledTask -Times 1 + Should -Invoke Start-ScheduledTask -Times 1 + } + It 're-enables the old task without starting it when the old hub never exited' { + Mock Get-ExeProcess { if ($Executable -eq 'old.exe') { return @(1) } return @() } + Invoke-MigrationRollback $state + ($script:events -join ',') | Should -Be 'disable-new,stop-new,barrier-new.exe,enable-old,verify-old' + } + It 'starts the old task after a lingering old process has gone, never beside it' { + Mock Get-ExeProcess { if ($Executable -eq 'old.exe') { return @(1) } return @() } + $script:healthChecks = 0 + Mock Wait-MigrationHealthy { $script:healthChecks++; $script:events.Add('verify-old'); if ($script:healthChecks -eq 1) { throw 'Migration: not serving' } } + Invoke-MigrationRollback $state + ($script:events -join ',') | Should -Be 'disable-new,stop-new,barrier-new.exe,enable-old,verify-old,barrier-old.exe,start-old,verify-old' + } + It 'registers the old task again only when it is missing' { + Mock Get-ExeProcess { return @() } + Mock Get-ScheduledTask { if ($TaskName -eq 'old' -and -not $script:events.Contains('register-old')) { return $null } return $true } + Invoke-MigrationRollback $state + ($script:events -join ',') | Should -Be 'disable-new,stop-new,barrier-new.exe,barrier-old.exe,register-old,enable-old,start-old,verify-old' + } + It 'still starts the old task when restoring the config fails' { + Mock Get-ExeProcess { return @() } + $bad = [pscustomobject]@{ NewTaskName = 'new'; OldTaskName = 'old'; TaskPath = '\'; NewExe = 'new.exe'; OldExe = 'old.exe'; Port = 8317; AuthDir = 'auth'; ConfigHash = 'different'; BackupPath = $TestDrive } + { Invoke-MigrationRollback $bad -RestoreConfig } | Should -Throw '*Saved config checksum failed*' + Should -Invoke Start-ScheduledTask -Times 1 + Should -Invoke Enable-ScheduledTask -Times 1 + } +} + +Describe 'Migration task registration' { + BeforeAll { + function Get-ScheduledTask { param($TaskName, $TaskPath, $ErrorAction) } + function Register-ScheduledTask { param($TaskName, $TaskPath, $Xml) } + function Start-ScheduledTask { param($TaskName, $TaskPath) } + } + It 'clones the principal, logon type, working directory and restart policy while registering disabled' { + $template = Join-Path $TestDrive 'task.xml' + @' + +exampleS4UHighestAvailable +true +truePT72HPT2M12 +old.exe-config old.yamlC:\hub + +'@ | Set-Content -LiteralPath $template + Mock Get-ScheduledTask { return $null } + Mock Register-ScheduledTask { + [xml]$registered = $Xml + $registered.Task.Principals.Principal.LogonType | Should -Be 'S4U' + $registered.Task.Principals.Principal.RunLevel | Should -Be 'HighestAvailable' + $registered.Task.Actions.Context | Should -Be 'hub-user' + $registered.Task.Actions.Exec.Command | Should -Be 'C:\staged\t3code-proxy.exe' + $registered.Task.Actions.Exec.WorkingDirectory | Should -Be 'C:\hub' + $registered.Task.Settings.Enabled | Should -Be 'false' + $registered.Task.Settings.ExecutionTimeLimit | Should -Be 'PT0S' + $registered.Task.Settings.RestartOnFailure.Interval | Should -Be 'PT2M' + $registered.Task.Settings.RestartOnFailure.Count | Should -Be '12' + } + Mock Start-ScheduledTask { throw 'Task must remain stopped' } + & (Join-Path $PSScriptRoot 'register-task.ps1') -Exe 'C:\staged\t3code-proxy.exe' -Config 'C:\hub\config.yaml' ` + -WorkingDirectory 'C:\hub' -TemplateXml $template -NoStart + Should -Invoke Register-ScheduledTask -Times 1 + Should -Invoke Start-ScheduledTask -Times 0 + } +} + +Describe 'Result file encoding and empty manifests' { + It 'writes JSON arrays and UTF-8 paths that round-trip on Windows PowerShell' { + $path = Join-Path $TestDrive 'empty.json' + Write-MigrationJson $path @() + [IO.File]::ReadAllText($path).Trim() | Should -Be '[]' + $unicodePath = [string][char]0x00E9 + '-hub' + Write-MigrationJson $path @{ BackupPath = $unicodePath } + ([IO.File]::ReadAllText($path) | ConvertFrom-Json).BackupPath | Should -Be $unicodePath + } +} + +Describe 'Credential snapshot for post-start probes' { + It 'uses the saved config after the live server has hashed its management key' { + $script:install = [pscustomobject]@{ Config = (Join-Path $TestDrive 'live.yaml'); WorkingDirectory = $TestDrive } + $script:probeConfigPath = Join-Path $TestDrive 'saved.yaml' + $script:baseUrl = 'http://127.0.0.1:8317' + $stdout = New-Object 'Threading.Tasks.TaskCompletionSource[string]' + $stdout.SetResult('{"ok":true}') + $stderr = New-Object 'Threading.Tasks.TaskCompletionSource[string]' + $stderr.SetResult('') + $readerOut = [pscustomobject]@{ Task = $stdout.Task } + $readerOut | Add-Member ScriptMethod ReadToEndAsync { return $this.Task } + $readerErr = [pscustomobject]@{ Task = $stderr.Task } + $readerErr | Add-Member ScriptMethod ReadToEndAsync { return $this.Task } + $script:fakeProcess = [pscustomobject]@{ StartInfo = $null; StandardOutput = $readerOut; StandardError = $readerErr; ExitCode = 0 } + $script:fakeProcess | Add-Member ScriptMethod Start { return $true } + $script:fakeProcess | Add-Member ScriptMethod WaitForExit { return $true } + $script:fakeProcess | Add-Member ScriptMethod Dispose { } + # One unfiltered mock: Pester 6 rejects calls that match no filtered mock. + Mock New-Object { + if ($TypeName -eq 'Diagnostics.Process') { return $script:fakeProcess } + if ($null -eq $ArgumentList) { return [Activator]::CreateInstance([type]$TypeName) } + return [Activator]::CreateInstance([type]$TypeName, [object[]]$ArgumentList) + } + (Invoke-MigrationDoctor -Probe).ok | Should -BeTrue + $script:fakeProcess.StartInfo.Arguments | Should -Match ([regex]::Escape($script:probeConfigPath)) + $script:fakeProcess.StartInfo.Arguments | Should -Not -Match 'live.yaml' + } +} diff --git a/deploy/windows/register-task.ps1 b/deploy/windows/register-task.ps1 index 2c207e7754f..8e752095a0f 100644 --- a/deploy/windows/register-task.ps1 +++ b/deploy/windows/register-task.ps1 @@ -26,25 +26,84 @@ param( [string]$Exe, [string]$Config, [string]$TaskName = "t3code-proxy", + [string]$TaskPath = "\", + [string]$WorkingDirectory, + [string]$TemplateXml, + [PSCredential]$Credential, [switch]$Unregister, [switch]$NoStart ) +Set-StrictMode -Version Latest $ErrorActionPreference = "Stop" if ($Unregister) { - if (Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue) { - Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue - Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false - Write-Host "Removed scheduled task $TaskName." + if (Get-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -ErrorAction SilentlyContinue) { + Stop-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -ErrorAction SilentlyContinue + Unregister-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -Confirm:$false + Write-Information "Removed scheduled task $TaskName." -InformationAction Continue } else { - Write-Host "Scheduled task $TaskName is not registered." + Write-Information "Scheduled task $TaskName is not registered." -InformationAction Continue } return } if (-not $Exe -or -not $Config) { throw "-Exe and -Config are required." } $workDir = Split-Path -Parent $Exe +if ($WorkingDirectory) { $workDir = $WorkingDirectory } + +# Migration clones the original principal, triggers and settings. Registration +# stays disabled until the caller has proved the old process has exited. +if ($TemplateXml) { + if (Get-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -ErrorAction SilentlyContinue) { + throw "Migration: Refusing to replace an existing destination task." + } + [xml]$xml = [IO.File]::ReadAllText($TemplateXml) + $ns = New-Object Xml.XmlNamespaceManager($xml.NameTable) + $namespace = $xml.DocumentElement.NamespaceURI + $ns.AddNamespace("t", $namespace) + # The exported URI names the old task; Task Scheduler sets it for the new one. + $uri = $xml.SelectSingleNode("/t:Task/t:RegistrationInfo/t:URI", $ns) + if ($null -ne $uri) { $null = $uri.ParentNode.RemoveChild($uri) } + $actions = $xml.SelectSingleNode("/t:Task/t:Actions", $ns) + while ($actions.HasChildNodes) { $null = $actions.RemoveChild($actions.FirstChild) } + $execNode = $xml.CreateElement("Exec", $namespace) + foreach ($pair in @(@("Command", $Exe), @("Arguments", ('-config "' + $Config + '"')), @("WorkingDirectory", $workDir))) { + $node = $xml.CreateElement($pair[0], $namespace) + $node.InnerText = $pair[1] + $null = $execNode.AppendChild($node) + } + $null = $actions.AppendChild($execNode) + $settingsNode = $xml.SelectSingleNode("/t:Task/t:Settings", $ns) + foreach ($pair in @(@("Enabled", "false"), @("ExecutionTimeLimit", "PT0S"), @("MultipleInstancesPolicy", "IgnoreNew"))) { + $node = $settingsNode.SelectSingleNode("t:" + $pair[0], $ns) + if ($null -eq $node) { + $node = $xml.CreateElement($pair[0], $namespace) + $null = $settingsNode.AppendChild($node) + } + $node.InnerText = $pair[1] + } + if ($null -eq $settingsNode.SelectSingleNode("t:RestartOnFailure", $ns)) { + $restart = $xml.CreateElement("RestartOnFailure", $namespace) + foreach ($pair in @(@("Interval", "PT1M"), @("Count", "999"))) { + $node = $xml.CreateElement($pair[0], $namespace) + $node.InnerText = $pair[1] + $null = $restart.AppendChild($node) + } + $null = $settingsNode.AppendChild($restart) + } + $registration = @{ TaskName = $TaskName; TaskPath = $TaskPath; Xml = $xml.OuterXml } + if ($null -ne $Credential) { + $registration.User = $Credential.UserName + $registration.Password = $Credential.GetNetworkCredential().Password + } + Register-ScheduledTask @registration | Out-Null + if (-not $NoStart) { + Enable-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath | Out-Null + Start-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath + } + return +} $user = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name $elevated = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole( [Security.Principal.WindowsBuiltInRole]::Administrator) @@ -60,19 +119,19 @@ if ($elevated) { $triggers += New-ScheduledTaskTrigger -AtStartup } $arguments = "-config `"$Config`"" $description = "t3code-proxy hub (https://github.com/rune-oai/t3code-proxy)" -if (Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue) { - Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue - Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false +if (Get-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -ErrorAction SilentlyContinue) { + Stop-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -ErrorAction SilentlyContinue + Unregister-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -Confirm:$false } $registered = $false try { $action = New-ScheduledTaskAction -Execute $Exe -Argument $arguments -WorkingDirectory $workDir $principal = New-ScheduledTaskPrincipal -UserId $user -LogonType S4U -RunLevel Limited - Register-ScheduledTask -TaskName $TaskName -Description $description -Action $action ` + Register-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -Description $description -Action $action ` -Trigger $triggers -Settings $settings -Principal $principal | Out-Null $registered = $true - Write-Host "Registered scheduled task $TaskName (runs without a logged-on session)." + Write-Information "Registered scheduled task $TaskName (runs without a logged-on session)." -InformationAction Continue } catch { Write-Verbose "S4U registration failed: $($_.Exception.Message)" } @@ -82,11 +141,11 @@ if (-not $registered) { $action = New-ScheduledTaskAction -Execute "conhost.exe" ` -Argument "--headless `"$Exe`" $arguments" -WorkingDirectory $workDir $principal = New-ScheduledTaskPrincipal -UserId $user -LogonType Interactive -RunLevel Limited - Register-ScheduledTask -TaskName $TaskName -Description $description -Action $action ` + Register-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -Description $description -Action $action ` -Trigger $logonOnly -Settings $settings -Principal $principal | Out-Null - Write-Host "Registered scheduled task $TaskName (starts at logon; run elevated to also start at boot)." + Write-Information "Registered scheduled task $TaskName (starts at logon; run elevated to also start at boot)." -InformationAction Continue } if (-not $NoStart) { - Start-ScheduledTask -TaskName $TaskName + Start-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath } diff --git a/docs/README.md b/docs/README.md index 2c1e23d1d7d..afe4e0248ad 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,11 +1,17 @@ # Documentation -These pages cover running a t3code-proxy hub, connecting clients to it, and working on the code. +These pages cover a hub for your subscription and API-key providers, plan-aware pooled limits, +and T3 Code environments that reach the hub over Tailscale. ## Run a hub - [Setup guide](setup.md): pick the hub machine, install, sign accounts in, publish it over Tailscale and point Claude Code and Codex at it. +- [Providers](providers.md) covers all subscription logins, API-key providers, Google AI Studio/Vertex + and OpenAI-compatible upstreams, with current quota and routing coverage. +- [Environments](environments.md) covers remote T3 Code machines, their services and pairing, + and Windows plus WSL 2 as two environments. +- [Set up a box](box-setup.md) gives an ordered checklist for an agent with SSH access to a new box. - [Guide for coding agents](agents.md): for an agent doing the setup on someone's behalf. - [T3 Code](t3code.md): use the hub from T3 Code and see pooled limits there. - [Routing](routing.md): how the hub picks an account for each request. diff --git a/docs/agents.md b/docs/agents.md index 14ded17eaea..64b8d88c5b7 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -2,15 +2,21 @@ This page is for a coding agent that sets up a t3code-proxy hub for a person. When you finish, the person has a hub on an always-on home machine with their accounts signed in, published to -their tailnet, and the clients they chose pointed at it. Every step below links to the -[setup guide](setup.md), which has the exact commands. +their tailnet, and the clients they chose pointed at it. The hub supports subscription and +API-key providers with plan-aware pooling for supported quota windows. Follow +[providers](providers.md) for every login and current quota coverage, and the +[setup guide](setup.md) for installation. + +For a new machine that runs agents, follow [set up a box](box-setup.md). For T3 Code services, +remote pairing and Windows plus WSL 2, follow [environments](environments.md). ## Tell the user what you are doing Start with a short explanation in your own words. Cover these points: -- One machine at home holds every Claude and Codex login and keeps the tokens fresh. Every other - machine sends its Claude Code, Codex and T3 Code traffic to that machine over Tailscale. +- One machine at home holds the chosen subscription logins and upstream API keys and keeps OAuth + tokens fresh. Every other machine sends its configured provider traffic there over Tailscale. + Agents can run on home or cloud T3 Code environments using that hub. - This avoids signing in on every device and keeps the traffic coming from one home connection. - The setup follows the one Theo Browne describes in his [token maxing video](https://www.youtube.com/watch?v=D8PikZ1KhUo) and @@ -29,7 +35,8 @@ Get answers to these before you change anything: is fine. 2. What operating system does the hub run? 3. Is Tailscale installed on the hub and on every client, signed in to the same tailnet? -4. Which Claude and Codex accounts should be signed in? +4. Which provider accounts and API-key upstreams should be configured? Use the + [provider table](providers.md#capability-table) to establish login and client support. 5. Which machines should use the hub? 6. Should you edit their normal Claude Code and Codex config, or use a second config directory and leave the normal setup alone? @@ -78,7 +85,11 @@ Follow the [setup guide](setup.md) in order: 6. Edit the client config files. Back each file up first. Check for an existing `ANTHROPIC_BASE_URL` in `~/.claude/settings.json` and an existing `model_provider` in `~/.codex/config.toml`, and tell the user before you replace them. -7. If they use T3 Code, follow [T3 Code](t3code.md). +7. If they use T3 Code, follow [T3 Code](t3code.md) and configure each execution machine using + [environments](environments.md). Windows and WSL 2 need separate provider settings. +8. Confirm panel quota coverage and set plan weights for pooled charts where supported. See + [providers](providers.md#capability-table), [quota history](quota-history.md) and + [routing](routing.md). ## Rules for you diff --git a/docs/box-setup.md b/docs/box-setup.md new file mode 100644 index 00000000000..cb58a0edb4e --- /dev/null +++ b/docs/box-setup.md @@ -0,0 +1,179 @@ +# Set up a box + +Use this checklist when you have SSH access to a new machine that should run agents. The result +is a T3 Code environment with Claude Code and Codex sending inference to your existing home +hub. A home desktop or cloud box can be an environment. Subscription logins belong on the +always-on residential hub. + +Read [setup](setup.md) if this machine will also be the hub. [Providers](providers.md) covers all +supported subscriptions and upstreams. [Environments](environments.md) covers platform services, +pairing and Windows plus WSL 2. + +## 1. Confirm the job and stop conditions + +- Establish the machine, OS, SSH user, hub URL and which projects should run here. Confirm which + accounts and clients the user authorized you to configure. +- Disclose that subscription proxying may violate provider terms and can lead to suspension or + a ban. Stop if the user does not accept that risk. +- Keep Theo's hard rules. Never serve other people's traffic with the subscriptions. Use Claude + subscription models only through Claude Code. +- If this is the hub, inspect its public network and sleep state with + `t3code-proxy doctor -config ` once installed. Before installing, use the checks + in [agents](agents.md#check-the-environment). Stop before subscription authorization if the + egress belongs to a datacenter, a cloud host or a VPN. A cloud environment can use the hub's + access key. +- Stop unattended handoff while the hub or environment can sleep. Apply the OS sleep settings + from [setup](setup.md#4-run-it-always-on), then verify again. +- Resolve existing services, occupied ports or an existing configuration with another endpoint + before replacing them. If you need a credential only the user holds, use your tool's secret + input facility or have the user enter it in a private local prompt. + +## 2. Inspect and install base tools + +Run as the user who will own the repositories and T3 Code state. On Linux or macOS, inspect the +OS and available tools. + +```sh +uname -a +git --version +curl --version +ssh -V +node --version +npm --version +``` + +Install missing Git, curl, CA certificates and SSH tools using the OS package manager. Install +a current Node.js LTS with npm if you use the npm provider installs below. Add the project's +compiler, runtime and package manager. On Windows, use Windows builds of the base tools. Check +the non-interactive SSH user's `PATH` as well as an interactive shell. Keep checkouts and home +directories owned by that user. + +## 3. Join Tailscale and check the hub + +Install Tailscale using its [platform instructions](https://tailscale.com/download). Authorize +the machine into the user's tailnet. Check that the hub is online and the tailnet access rules +allow port 8317. + +```sh +tailscale status +curl -s https://..ts.net:8317/v1/models \ + -H "Authorization: Bearer " +``` + +The response should contain a model list. In automation, inject the access key privately and +redact the command record. Resolve DNS, certificate and 401 errors before installing an agent +service. A failed hub connection makes every later provider test inconclusive. + +## 4. Install Claude Code and Codex + +Use an existing supported installation when present. For a fresh user-owned npm setup, these +commands install the provider packages. The script approvals are for their own install hooks. + +```sh +npm install -g --allow-scripts=@anthropic-ai/claude-code @anthropic-ai/claude-code +npm install -g --allow-scripts=@openai/codex @openai/codex +claude --version +codex --version +``` + +If that npm prefix requires root, use a user-owned Node/npm installation or the provider's +installer linked from T3 Code's +[provider setup](https://github.com/pingdotgg/t3code/blob/main/docs/user/install.md#providers). +Use the provider versions recommended by the installed T3 Code release. Confirm `claude` and +`codex` resolve for the eventual background-service user. + +## 5. Back up and merge client config + +Before writing, make a backup of every existing file you will edit in a unique directory. On Linux +or macOS, this copies only files that exist and gives the backups private permissions. + +```sh +umask 077 +backup_dir=$(mktemp -d "$HOME/.hub-config-backup.XXXXXX") +for config_file in "$HOME/.claude/settings.json" "$HOME/.codex/config.toml"; do + if [ -f "$config_file" ]; then + cp -p "$config_file" "$backup_dir/" + chmod 600 "$backup_dir/$(basename "$config_file")" + fi +done +``` + +On Windows, make equivalent protected copies under the same user's profile before editing. +Keep those copies outside the project repository. + +Merge the complete client settings from [providers](providers.md#point-clients-at-the-hub). +Preserve existing JSON fields and TOML tables. Check for conflicting `ANTHROPIC_BASE_URL`, +`ANTHROPIC_AUTH_TOKEN`, `model_provider`, provider tables and project-local overrides. Use +`https://..ts.net:8317` for Claude Code and append `/v1` for Codex. + +### Optional second config directories + +Create `~/.claude-hub/settings.json` and `~/.codex-hub/config.toml` with the hub settings if the +user wants separate client instances. Start them explicitly for verification. + +```sh +CLAUDE_CONFIG_DIR=~/.claude-hub claude +CODEX_HOME=~/.codex-hub codex +``` + +In T3 Code, assign these directories to the corresponding provider instances. A shell variable +used for one CLI invocation only applies to that invocation. The environment server must launch +its providers with the same directories. See [T3 Code](t3code.md). + +## 6. Install and expose the T3 Code environment + +Use the official CLI installer on Linux or macOS. + +```sh +curl -fsSL https://t3.codes/install.sh | sh +t3 --version +t3 serve --help +``` + +For Windows, use the PowerShell installer in [environments](environments.md#before-you-start). +Choose the access method already authorized for this machine. For a Tailscale-only background +server, set the listener in `~/.t3/service.env` as described in +[environments](environments.md#connect-and-run-in-the-background), then run as the normal user. + +```sh +t3 service install +t3 pair --tailscale --tailscale-serve-port 443 +t3 service status +tailscale serve status +``` + +For T3 Connect account access, use `t3 connect --headless` and let the user approve the URL and +code. It sets up the background service too. Keep the Tailscale path from the environment to the +hub working in either case. + +On Linux, verify linger with `loginctl show-user "$(id -un)" -p Linger`. On macOS and Windows, +keep the service's user logged in. For WSL, choose the launcher in +[Windows and WSL 2](environments.md#windows-and-wsl-2-as-two-environments) and test it with every +terminal closed. + +## 7. Verify through the normal entry points + +1. From this box, request `/v1/models` with the access key again. Check only enough response data + to establish connectivity. +2. Start Claude Code in a trusted checkout and send a small prompt using a hub model. Do the + same with Codex. Confirm both requests appear in the hub's activity view. +3. Pair the desktop, web or mobile client with this environment. Create a thread in the remote + checkout. Confirm its terminal OS, user and path belong to this box. +4. Under **Settings → Providers**, select the remote environment and its configured Claude + instance. Select **Use existing CLI** for Codex. Send a small prompt through each. +5. If requested, add the hub usage provider with the management secret and review its pooled + limits. The provider [capability table](providers.md#capability-table) gives current coverage. +6. Disconnect SSH and close the laptop's client, then reconnect from another device. Check that + the service and thread are still available. Reboot the box and check its startup behavior. + +## 8. Hand back a record without secrets + +Report the box's role, service status, CLI versions, config and backup paths, environment URL, +verification results and any pending human sign-in. Record whether the normal or second config +directories are in use and which provider instance uses each. + +Never print, log, paste or commit account JSON, access keys, management secrets, pairing links +or authorization codes. Use placeholders in notes. Protect client configs and backups with +owner-only access or the corresponding Windows ACL. Subscription OAuth files and their refresh +journal stay on the hub. See [Codex refresh recovery](codex-refresh-recovery.md) for backups of +that journal. diff --git a/docs/configuration.md b/docs/configuration.md index a4e059b735a..e4fa6391925 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -87,12 +87,16 @@ routing: strategy: "soonest-reset-first" session-affinity: true session-affinity-ttl: "1h" + plan-headroom-reserve: 10 # default; 0 disables the 5-hour headroom guard + plan-weights: # optional overrides of the built-in plan weights + codex: + pro: 12 retry: request-retry: 3 max-retry-interval: 30 ``` -See [routing](routing.md) for the strategies, affinity and retries. +See [routing](routing.md) for the strategies, plan weights, affinity and retries. ## Quota history diff --git a/docs/environments.md b/docs/environments.md new file mode 100644 index 00000000000..a06fec99666 --- /dev/null +++ b/docs/environments.md @@ -0,0 +1,331 @@ +# T3 Code environments + +An environment is the machine where T3 Code runs providers, terminals and your checkout. Put an +environment on a home desktop or a cloud box and work from your laptop, web browser or phone. +The remote machine's Claude Code and Codex settings send inference to your home hub. The hub +holds your subscription logins and talks to the providers. + +Using subscriptions through a hub may violate provider terms, and accounts can be suspended or +banned. Never serve other people's traffic with your subscriptions. Use Claude subscriptions +only through Claude Code. Keep subscription authorization on the residential hub. A cloud box +can run your agents with the hub's access key. + +## Before you start + +- Have a working [hub](setup.md), its Tailscale HTTPS URL and a client access key. +- Install Tailscale on the environment and your connecting devices, joined to your tailnet. + Tailnet access rules must allow the hub and environment ports. +- Install Git, the tools your project needs, Claude Code and Codex on the environment machine. + Run everything as the same user that owns the checkouts and client configuration. +- Install a current T3 CLI on the environment. The commands below were checked against installed + `t3 v0.1.9`. Read `t3 --help` and subcommand help on machines with another release. +- Keep the environment awake and connected. Linux needs systemd user services for background + service installation. Tailscale HTTPS needs MagicDNS, HTTPS certificates and permission for + your user to manage Serve. + +Install the T3 CLI on Linux or macOS with its official installer. + +```sh +curl -fsSL https://t3.codes/install.sh | sh +t3 --version +t3 serve --help +``` + +On Windows, use PowerShell. + +```powershell +irm https://t3.codes/install.ps1 | iex +t3 --version +``` + +T3 Code's [installation guide](https://github.com/pingdotgg/t3code/blob/main/docs/user/install.md) +lists provider installation requirements. [Box setup](box-setup.md) gives the full order. + +## Point the environment's providers at the hub + +Merge the Claude Code and Codex settings from [providers](providers.md#point-clients-at-the-hub) +into this machine's config files. Back up each file first. Windows uses the signed-in user's +`%USERPROFILE%\.claude` and `%USERPROFILE%\.codex`. Linux and macOS use `~/.claude` and +`~/.codex`. + +In T3 Code, select this environment under **Settings → Providers**. Claude uses its Claude Code +settings. For Codex, choose **Use existing CLI** so it reads `config.toml`. If you use second +config directories, select those directories on the provider instances as described in +[T3 Code](t3code.md). Restart provider sessions after changing their settings. + +Check the hub from the environment machine, then send one prompt from each configured client. + +```sh +curl -s https://..ts.net:8317/v1/models \ + -H "Authorization: Bearer " +claude --version +codex --version +``` + +## Serve the environment over Tailscale + +For a foreground server, run this on the environment machine. + +```sh +t3 serve --host 127.0.0.1 --port 3773 --tailscale-serve --tailscale-serve-port 443 +``` + +`serve` runs the HTTP/WebSocket backend, keeps it in the terminal and prints pairing details. +`--host` and `--port` set its listener. The Tailscale flags publish that listener at +`https://..ts.net` through Serve. Leave this process running while you test. +Port 443 for T3 Code and port 8317 for the hub can share a machine. + +For an existing server, create a fresh pairing link with HTTPS on the same port. + +```sh +t3 pair --tailscale --tailscale-serve-port 443 +``` + +The Serve mapping persists across server restarts. `tailscale serve status` shows its target. +Use a different HTTPS port if 443 already belongs to another service. + +## Connect and run in the background + +`t3 connect` configures T3 Connect account access and the background service. It is equivalent to +`t3 up --connect`. On an SSH host, use the headless flow and approve the printed URL and code +from another device. + +```sh +t3 connect --headless +t3 status +t3 service status +``` + +T3 Connect provides an account-based route to the environment. Tailscale also remains the path +from this machine's provider clients to the hub. You can add a Tailscale HTTPS route for direct +client access with `t3 pair --tailscale`. + +For a Tailscale-only environment, stop your foreground test server and install the built-in +background service as your normal user. + +```sh +t3 service install +t3 pair --tailscale --tailscale-serve-port 443 +t3 service status +``` + +The service reads `service.env` in its T3 home, normally `~/.t3/service.env`, or +`%USERPROFILE%\.t3\service.env` on Windows. For the listener used above, merge these entries +into that file. Values are literal and require absolute paths +when you add path settings. + +```dotenv +T3CODE_HOST=127.0.0.1 +T3CODE_PORT=3773 +``` + +After a change, restart the service. Keep the Serve target's port aligned with `T3CODE_PORT`. + +```sh +t3 service restart +t3 service status +``` + +### Linux + +The installer creates `t3code.service` as a systemd user unit and enables linger. Check it and +enable linger if setup reports that it needs administrator access. + +```sh +systemctl --user status t3code.service +loginctl show-user "$(id -un)" -p Linger +sudo loginctl enable-linger "$(id -un)" +``` + +Linger starts the user manager at boot and keeps it after logout. Verify access again after an +SSH logout and a reboot. Apply the [hub sleep settings](setup.md#4-run-it-always-on) to any box +that must stay available. + +### Windows + +`t3 service install` registers a Scheduled Task named `t3code--`. It starts at +that user's logon, runs without a window and restarts after failure. Keep that user signed in, +lock the screen and disable sleep on AC power. Installing through SSH while the user is signed +out can leave the task waiting for the next interactive logon. Use `t3 service status` for its +actual task name and log path. + +### macOS + +The service is a launchd agent in +`~/Library/LaunchAgents/com.t3tools.t3code.service.plist`. It starts at login and stops at logout. +Keep the user logged in and the Mac awake. Installing through SSH before a GUI login can leave +the final start pending until that login. `t3 service status` reports the log location. + +These service behaviors and the `service.env` format are documented in T3 Code's +[background-service guide](https://github.com/pingdotgg/t3code/blob/main/docs/user/background-service.md). + +## Add it from desktop, web or mobile + +On the environment, run `t3 pair --tailscale` to get a fresh QR code and pairing URL. In the +receiving app, open **Settings → Environments → Add environment** and paste the URL, or scan the +QR code on mobile. A desktop can also open the printed `t3code://pair` link. Use a new pairing +link for each device and keep it private. The hosted web client at `https://app.t3.codes` needs +an HTTPS endpoint. + +If you chose T3 Connect, sign into the same account on your desktop, web or mobile client and +select the environment. T3 Code's +[remote-access guide](https://github.com/pingdotgg/t3code/blob/main/docs/user/remote-access.md) +covers both routes. + +Add a project whose path is on that box and select it when starting a thread. A terminal in the +thread should show that machine's hostname, OS and checkout. A laptop can disconnect while the +server keeps the work running. + +### Let an agent use another environment + +Client pairing lets you operate a remote environment yourself. To let agents on one environment +start work on another, enable **Linked environments** in **Settings → Labs** on both and use +**Settings → Environments → Linked environments → Link**. Choose the target and access mode. +The terminal equivalent runs on the originating environment. + +```sh +t3 environment link https://..ts.net \ + --pairing-code "" --access read-only +t3 environment list +``` + +Supply the target's fresh code privately. Use the app's pairing field to keep it out of shell +history. Choose the access level required for the task. You can revoke the target's session in its +sharing/access settings. See T3 Code's linked-environment section in the remote-access guide. + +## Windows and WSL 2 as two environments + +Windows and a WSL distribution have separate users, files, provider installs and T3 home +directories. Install and configure Claude Code, Codex and `t3` in each. Keep Linux checkouts in +the Linux filesystem for Linux tools. Give the environments clear names in the client, such as +`Windows` and `Ubuntu`. Confirm which environment owns each project before you start work. + +T3 Code's Windows desktop can also manage a distro from **Settings → Sharing & access**. The +steps here set up an independently reachable Linux server. Pick one owner for the distro's T3 +home to avoid two servers trying to open the same state. + +### Enable systemd in the distro + +In PowerShell, check WSL and the distro version. Systemd support requires WSL 0.67.6 or later. + +```powershell +wsl --version +wsl --list --verbose +``` + +Merge this into `/etc/wsl.conf` inside the selected WSL 2 distro. + +```ini +[boot] +systemd=true +``` + +Save work in every distro, then apply it from PowerShell. + +```powershell +wsl --shutdown +``` + +Reopen the distro and check `systemctl status`. Microsoft explicitly states that systemd +services do not keep a WSL instance alive. Linger covers the Linux user manager's lifetime. +WSL still needs a running instance and Windows still needs to stay awake. See Microsoft's +[systemd guide](https://learn.microsoft.com/en-us/windows/wsl/systemd) and +[WSL configuration reference](https://learn.microsoft.com/en-us/windows/wsl/wsl-config). + +### Choose the Tailscale path and distinct ports + +Tailscale recommends running it on the Windows host only. WSL then uses the host's networking +to reach tailnet services. Running Tailscale inside WSL gives Linux its own node identity, but +Tailscale documents failures when WSL's encrypted traffic is carried over the Windows host's +Tailscale connection. Check that limitation before choosing a second node. See +[Tailscale on WSL 2](https://tailscale.com/docs/install/windows/wsl2). + +With host-only Tailscale, use this port layout. + +| Process | Local listener | Windows Tailscale HTTPS port | +| --- | --- | --- | +| Windows T3 Code | `127.0.0.1:3773` | `443` | +| WSL T3 Code | `127.0.0.1:3774` in WSL | `8443` | +| Hub, if on this PC | `127.0.0.1:8317` on Windows | `8317` | + +Run the Linux T3 server inside WSL. + +```sh +t3 serve --host 127.0.0.1 --port 3774 +``` + +WSL's default NAT networking forwards Linux localhost services to Windows localhost. Test +`http://127.0.0.1:3774` in a Windows browser before publishing it. In Windows PowerShell, set the +second Serve mapping. + +```powershell +tailscale serve --bg --https=8443 http://127.0.0.1:3774 +tailscale serve status +``` + +Pair the WSL environment using a link created in its sharing/access settings with the reachable +address `https://..ts.net:8443`. Windows uses +`https://..ts.net`. Distinct ports avoid the host's localhost forwarding and Serve +mappings selecting the wrong server. If you use a Tailscale daemon inside WSL instead, configure +Serve on that Linux node and pair its own hostname. + +### Keep WSL running without a terminal + +Create a Windows Scheduled Task under the Windows user that owns the distro. Trigger it at +logon, enable restart on failure and remove the execution-time limit. Select **Run whether user +is logged on or not** for a background task, and supply any password through Task Scheduler's +own prompt. Use `wsl.exe` as the program and this argument line, replacing the distro, user and path. + +```text +--distribution Ubuntu --user --exec /home//.local/bin/t3 serve --host 127.0.0.1 --port 3774 +``` + +This task keeps a foreground Linux server attached to `wsl.exe` while Windows Task Scheduler +owns its lifetime. Use it as the distro's T3 launcher. If you previously installed a T3 systemd +service there, remove that service with `t3 service uninstall` before enabling this task. Other +Linux services can still use systemd. Test the task after closing every terminal and after a +Windows reboot and logon. `wsl --list --verbose` should show the distro running. + +The WSL command options are described in Microsoft's +[command reference](https://learn.microsoft.com/en-us/windows/wsl/basic-commands). + +### Reach a hub on the Windows host from WSL + +First try the normal hub URL, `https://..ts.net:8317`, from WSL. Use that URL in +both Linux provider configs once it works. This preserves the certificate name and access-key +check used by every other environment. + +With default NAT, Linux `127.0.0.1` addresses Linux itself. Windows' address as seen from Linux +is the default route's gateway, which you can inspect with `ip route show`. A Windows service +bound only to Windows loopback cannot be reached through that gateway address. Keep the hub on +loopback and use its Tailscale Serve endpoint. + +On Windows 11 22H2 or later, mirrored networking lets Linux connect to Windows services on +`127.0.0.1`. Enable it in `%USERPROFILE%\.wslconfig` if you need that path, then restart WSL. + +```ini +[wsl2] +networkingMode=mirrored +``` + +In that mode, a same-PC hub can also be reached at `http://127.0.0.1:8317` inside WSL. The client +still sends the access key. Windows/Hyper-V firewall rules and VPN software can affect these +paths. Microsoft's [networking guide](https://learn.microsoft.com/en-us/windows/wsl/networking) +explains NAT, localhost forwarding and mirrored mode. + +### Failure modes + +- A healthy Linux systemd unit disappears after closing terminals. Check whether the WSL distro + stopped, then start the Windows launcher task. Linger alone cannot keep WSL alive. +- WSL's URL opens the Windows environment. Check both local ports and Serve targets, then make + a fresh pairing link for the Linux environment. +- Linux has the wrong provider settings. Check the Linux user's home and CLI paths. Windows + provider settings do not configure Linux clients. +- WSL can reach the internet but cannot reach the hub. Check MagicDNS, the hub's Serve port, + Windows firewall and the dual-Tailscale limitation above. +- A server reports its data directory is busy. Stop the duplicate foreground, systemd or + desktop-managed server before starting the chosen launcher. +- Everything vanishes after sleep, sign-out or `wsl --shutdown`. Wake Windows, sign into the + task's user and start the task again. Shutdown terminates all running WSL distributions. + +See [troubleshooting](troubleshooting.md) for hub and environment checks. diff --git a/docs/management-api-v8.md b/docs/management-api-v8.md index d4ee2ec1550..ca5628f0671 100644 --- a/docs/management-api-v8.md +++ b/docs/management-api-v8.md @@ -135,6 +135,7 @@ retain the corresponding business operation's fields. | `/server/latest-version` | GET | Get latest release information. | | `/requests/api-call` | POST | Make an authenticated upstream call. | | `/routing/cooldown/reset` | POST | Clear credential cooldown. | +| `/routing/plan-weights` | GET | Read plan capacity weights. See [plan weights](#plan-weights). | | `/routing/model-definitions/` | GET | Get model definitions. | | `/observability/logs` | GET, DELETE | Read or clear application logs. | | `/observability/logs/errors` | GET | List error-log files. | @@ -143,7 +144,7 @@ retain the corresponding business operation's fields. | `/observability/usage/api-keys` | GET | Get API-key usage. | | `/observability/usage/queue` | GET | Get queued usage events. | | `/quota-history` | GET | Read recorded quota samples (`since`/`until` in Unix ms). See [quota history](quota-history.md). | -| `/quota-history/refresh` | POST | Poll every Claude and Codex account now. | +| `/quota-history/refresh` | POST | Poll every enabled, selected account with quota-history support. | | `/credentials` | GET, POST, DELETE | List, upload, or delete credential files. | | `/credentials/models` | GET | Get credential models. | | `/credentials/download` | GET | Download a credential file. | @@ -164,6 +165,38 @@ retain the corresponding business operation's fields. | `/plugins/store//install` | POST | Install or update a plugin. | | `/plugins//quota` | GET, POST, DELETE | Read, fetch, or reset plugin quota. | +## Plan weights + +`GET /v8/management/routing/plan-weights` returns the plan capacity weights +that routing uses (see [routing](routing.md#plan-capacity)). Each table is keyed +by provider and then plan, with normalized lower-case names: + +```json +{ + "defaults": { + "claude": {"max": 5, "max_20x": 20, "max_5x": 5, "pro": 1, "team": 1}, + "codex": {"business": 1, "edu": 1, "enterprise": 1, "plus": 1, "pro": 20, "prolite": 5, "promax": 50, "team": 1}, + "xai": {"supergrok": 1, "supergrok_heavy": 10} + }, + "configured": {"codex": {"pro": 10}}, + "effective": { + "claude": {"max": 5, "max_20x": 20, "max_5x": 5, "pro": 1, "team": 1}, + "codex": {"business": 1, "edu": 1, "enterprise": 1, "plus": 1, "pro": 10, "prolite": 5, "promax": 50, "team": 1}, + "xai": {"supergrok": 1, "supergrok_heavy": 10} + } +} +``` + +`defaults` is the built-in table, `configured` is `routing.plan-weights` +(`{}` when unset), and `effective` is the defaults with the configured values +applied. Plans whose weight comes from a `max_x` tier name are resolved on +demand and are not listed. There is no separate write endpoint: change the +overrides through the configuration paths, for example +`PUT /v8/management/config/routing/plan-weights` with +`{"codex": {"pro": 10}}`, or `PUT /v8/management/config/routing/plan-headroom-reserve` +with `5`. Invalid values (not a number greater than 0 and at most 1000 for a +weight, or outside 0 to 1000 for the reserve) are rejected with 422. + ## OAuth The login URL is shared by all providers. Set the required `provider` query diff --git a/docs/migrating.md b/docs/migrating.md index 695623c6e72..68416cbcc59 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -2,7 +2,7 @@ This page moves an existing CLIProxyAPI hub, or an earlier `v8.x-t3code` build of this hub, to t3code-proxy. When you finish, the new binary runs as the new service with your existing config -and account logins, and the old service is gone. +and account logins. On Windows, the old task remains disabled for recovery. t3code-proxy started from [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) and reads the same config and account files, so nothing needs converting. @@ -29,7 +29,284 @@ the same config and account files, so nothing needs converting. - **Clients.** The API, port and paths are the same. Client configs keep working once the new hub listens on the same port. -## Steps +## Windows one-command migration + +Use `scripts/migrate-windows.ps1` from this checkout with its sibling +`deploy/windows/register-task.ps1`. Stage a release `t3code-proxy.exe` at a separate, +permanent path first, using a verified release archive or `install.ps1 -NoService`. +Keep that binary, this checkout and the old install available through recovery. +The normal installer registers and starts a hub by default. Use `-NoService` when +staging it for this procedure. + +Run Windows PowerShell 5.1 as the same Windows account that owns the old task. +Use elevation if task permissions or process inspection require it. The migration +must be able to export, disable, stop, register and start tasks and inspect full +process paths and TCP listener owners. + +### Confirm the machine before switching + +- The old hub is a single running executable launched by one Scheduled Task. By + default the task is `CLIProxyAPI Hub` in `\`. Its action supplies `-config` and a + working directory. Use `-OldTaskName`, `-TaskPath`, `-OldExe`, `-Config` and + `-WorkingDirectory` to override discovery. When supplying `-Config`, review any + additional old arguments yourself. The replacement action uses only `-config`. +- The config uses local file storage and HTTP loopback on the existing port. Home, + cloud and Postgres/git/object-store deployments need their own migration procedure. + The check considers both the process environment and the working directory's `.env`. + Task Scheduler must see the same required environment. Put persistent settings + in the existing `.env` or machine/user environment before launching. +- The configured auth directory and local model catalogs exist. Auth accounts are + root-level JSON files with a `type` field. Their count must match the old + `/v0/management/auth-files` response. Virtual API-key credentials are excluded. + Custom account layouts or plugin-generated accounts can fail this comparison. +- Both hub tasks are the only launchers of their binaries. Pause client traffic + and other tools that modify config or auth files for the switch. The script + rechecks activity before stopping, but incoming requests can race a snapshot. + The inference session launching the migration will disconnect during the switch. +- Review each reported Catalog Refresh task and confirm its helper only maintains + catalogs. The migration leaves these tasks and user scripts registered. Catalogs + under the old install continue to be used, so retain that folder. No automatic + deletion is performed. +- A local backup volume has twice the auth directory size plus 64 MiB available. + Auth directories and their contents must be ordinary files/directories. Junctions + and symbolic links are rejected so backups cannot omit external credential state. +- The old task uses S4U, InteractiveToken or Password logon. InteractiveToken still + needs the user's interactive Windows session to remain logged on. S4U and Password + can run after logout. SSH disconnect survival is handled by Task Scheduler. + +The config path, working directory, bind port, access keys, management key and auth +path carry over. Keep the existing Tailscale Serve mapping and client URLs. The +script validates the config using the new binary's production loader on a private, +disposable temporary copy. It never starts a second hub for preflight. Unknown +patched-build keys are reported and kept in the original file. The server loader +continues to apply its normal startup behavior, including hashing a plaintext +management key and removing conflicting legacy fields. + +### Supply a hashed management key securely + +The migration reads an access key from the config inside the doctor subprocess. +A plaintext management key can also be read from the config or `MANAGEMENT_PASSWORD`. +After backup, probes use the immutable config snapshot so startup hashing of the +live config cannot discard the plaintext needed for verification. +A bcrypt management hash cannot authenticate an API request. If the file holds a +hash, create a user-private file containing the original plaintext management key +and pass `-ManagementKeyFile`. For example, read it interactively without echoing it +and restrict the containing directory first. + +```powershell +$private = Join-Path $env:USERPROFILE 't3-migration-private' +New-Item -ItemType Directory -Path $private -Force | Out-Null +$sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value +icacls $private /inheritance:r /grant:r "*${sid}:(OI)(CI)F" '*S-1-5-18:(OI)(CI)F' | Out-Null +$secret = Read-Host 'Existing management key' -AsSecureString +$credential = New-Object PSCredential('management', $secret) +[IO.File]::WriteAllText((Join-Path $private 'management.key'), $credential.GetNetworkCredential().Password) +Remove-Variable secret,credential +``` + +Password-logon tasks also require a DPAPI-encrypted credential file created as the +same user on the hub. Add `-TaskCredentialFile "$private\task.credential.xml"` to +each command below. The principal and logon type carry over to the new task. + +```powershell +Get-Credential | Export-Clixml -LiteralPath (Join-Path $private 'task.credential.xml') +``` + +Keep these files available for verification and rollback. Remove them when the +recovery window closes. Their contents are never passed in task arguments or +written to the migration log/result. The backup contains credentials and uses an +ACL restricted to the migrating user and SYSTEM. + +### Dry-run and launch detached + +Use a permanent checkout path on the hub. The following paths are examples to +replace with your staged binary, private key file and a fresh backup directory. +Omit `-ManagementKeyFile` when plaintext is available from the config/environment. + +```powershell +Set-Location C:\src\t3code-proxy +$migration = @{ NewExe = 'C:\tools\t3code-proxy\t3code-proxy.exe'; BackupPath = 'C:\hub-backups\migration-20261115'; ManagementKeyFile = "$private\management.key" } +.\scripts\migrate-windows.ps1 @migration -WhatIf +.\scripts\migrate-windows.ps1 @migration -Detached -AllowUnknownInFlight +``` + +`-WhatIf` performs read-only discovery, config checking and authenticated probes, +prints the plan, and leaves the install and task definitions untouched. It creates +no backup or persistent log. Config checking creates and removes a private +operating-system temporary copy because the production loader can write config. + +The old hub may expose the read-only +`/v8/management/observability/requests/in-flight` endpoint. A positive count blocks +the switch. If the endpoint is absent or its result is unusable, the script reports +that gap and requires `-AllowUnknownInFlight` for a real run. Supply this switch +only after pausing clients and accepting that live traffic cannot be measured. + +`-Detached` completes preflight before registering an on-demand, one-shot +`t3code-migration-` task. The worker repeats preflight and owns the switch +and automatic recovery. It inherits the old task's user and logon type, and runs +elevated when you launch it from an elevated shell: registering and stopping +tasks usually needs that, so launch from an elevated PowerShell. It +has no recurring trigger, restart policy or execution-time limit, and survives the +launching SSH session disconnecting. Do not log out an InteractiveToken principal. +The launcher prints its task name and the backup/result directory before returning. +Keep the checkout at the same path until completion. The worker removes its +one-shot launch task when it finishes; `result.json` is the record of the outcome. + +During the operation the worker takes an exclusive migration lock in the old +working directory. In order, it: + +1. Verifies copies of config, `.env` when present, every auth file/subdirectory + including `.codex-refresh`, and the exported old task XML (`auth/`). The hub is + still running at this point, so a file it holds open or is still writing, such + as its `kv.db` store or a log, is listed in the manifest as `unreadable` or + `changed` and left for step 4. Account files must copy here or the run stops. +2. Registers the replacement task, disabled, using the old task's principal, + triggers and restart settings, while the old hub is still serving. A missing + restart policy gains one-minute retries and the task has no execution-time + limit. If this account is not allowed to register the task, the migration + stops here with the old hub untouched. +3. Disables the old task, stops it and waits for its process to exit and the port + to become free. For a hub bound to loopback, only listeners on loopback or on + all interfaces count: Tailscale Serve keeps listening on the tailnet address + for the same port and is ignored. +4. Takes a second, strict auth snapshot that includes the final token rotations + and every file (`auth-final/`). The first snapshot is kept. +5. Enables and starts the replacement task. + +Verification requires `/healthz`, authenticated `/v1/models`, and authenticated +`/v0/management/auth-files` with the backed-up file-account count, and every +account the hub lists must be a file in the auth directory the config resolves to. +That last check runs against the old hub before the switch as well, so a hub +reading `~/.cli-proxy-api` is not replaced by one reading a different +`~/.t3code-proxy` that happens to hold the same number of accounts. The new binary +uses the original config in the original working directory. The old task stays +present and disabled. Failed switching or verification invokes rollback and exits +with a failure result even when recovery succeeds. + +Automatic rollback stops the new hub, restores the saved config and `.env`, then +enables and starts the old task; the old task is registered again only if it has +gone missing. Once the new hub's process is confirmed gone, the old task is +enabled and started even if a later rollback step fails, including when the port +is still held: if the old task has a restart-on-failure setting, Task Scheduler +then retries until the port is free (preflight warns when it has none). If the new +process cannot be confirmed gone, neither hub is started, the result says so, and +recovery is manual. If the old hub never exited in the first place, its files are +left alone and its task is re-enabled; if it is still shutting down, the task is +started once that process has gone. + +### Read the outcome + +```powershell +Get-Content -LiteralPath 'C:\hub-backups\migration-20261115\result.json' -Encoding UTF8 -Raw | ConvertFrom-Json | Format-List +Get-Content -Path 'C:\hub-backups\migration-20261115\transcript-*.log' -Tail 100 +``` + +`result.json` records `Phase`, `Success`, `StartedAt`, `FinishedAt`, `Reason`, +`BackupPath` and `RolledBack`. An unset `FinishedAt` means completion has not been +recorded. A launcher failure is recorded after its result directory is prepared. +Read-only preflight failures before launch appear in the calling console. +Transcripts contain phase changes and redacted failure descriptions. Raw config, +HTTP bodies, access keys, management secrets and auth content are excluded from +both artifacts. SHA-256 manifests and `migration.json` accompany the backups. + +Re-running a completed migration with the same `-BackupPath` checks the running new +hub and returns without switching again. Other runs refuse an existing destination +task or backup directory. After a failed attempt, inspect its result and recover +from that named backup before starting another migration. An automatic rollback +leaves the replacement task registered and disabled, so the next run needs a fresh +`-BackupPath` and either a different `-NewTaskName` or the disabled task removed +first (`Unregister-ScheduledTask -TaskName t3code-proxy`). + +### Roll back a named backup + +Rollback disables and stops the new task and checks both executable/port barriers +before restoring the saved config and `.env`. It saves the later +config/environment in the backup folder, enables the old task, starts it and +verifies authenticated models and the current file-account count; `result.json` +carries a warning when that count differs from the one recorded before the switch. +`-Rollback` +reads the old task to find the install, so the old task must still be registered; +if you deleted it, use the manual recovery below, which registers it from the +saved XML. Keep the old +binary and task available, and retain the staged new binary for read-only checks. + +```powershell +.\scripts\migrate-windows.ps1 -Rollback -BackupPath 'C:\hub-backups\migration-20261115' -ManagementKeyFile "$private\management.key" -WhatIf +.\scripts\migrate-windows.ps1 -Rollback -BackupPath 'C:\hub-backups\migration-20261115' -ManagementKeyFile "$private\management.key" -Detached +``` + +Include custom `-OldTaskName`/`-TaskPath` and `-TaskCredentialFile` when applicable. +Automatic and explicit rollback retain the latest live auth directory. OAuth +refresh tokens rotate, so replaying the backup's older tokens can invalidate +logins. The auth snapshot is available for disaster recovery and forensic checks. +Restoring it requires assessing token rotation and may require signing in again. + +For manual recovery, open PowerShell as the task owner and use the saved paths +and names. Disable both launchers before stopping either. Confirm that both full +executable paths have disappeared and that the saved port has no listener before +starting either hub. If a process remains, resolve its shutdown first. + +```powershell +$backup = 'C:\hub-backups\migration-20261115' +$state = Get-Content -LiteralPath (Join-Path $backup 'migration.json') -Encoding UTF8 -Raw | ConvertFrom-Json +Disable-ScheduledTask -TaskName $state.NewTaskName -TaskPath $state.TaskPath +Disable-ScheduledTask -TaskName $state.OldTaskName -TaskPath $state.TaskPath +Stop-ScheduledTask -TaskName $state.NewTaskName -TaskPath $state.TaskPath +Stop-ScheduledTask -TaskName $state.OldTaskName -TaskPath $state.TaskPath +Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -in @($state.OldExe, $state.NewExe) } | Select-Object ProcessId,ExecutablePath +# For a hub bound to 127.0.0.1, only loopback and all-interface listeners matter. +# Tailscale Serve keeps listening on the tailnet address for the same port. +Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -eq $state.Port -and $_.LocalAddress -in @('127.0.0.1', '0.0.0.0', '::', '::1') } +``` + +Once both checks are empty, verify the saved config and task XML, preserve the +current config/environment, then restore the saved files. Restore `.env` only +when the backup has one. If it was added after migration, move it aside before +starting the old hub so it cannot override the saved config. + +```powershell +foreach ($pair in @(@('config.yaml', $state.ConfigHash), @('old-task.xml', $state.TaskXmlHash))) { + if ((Get-FileHash -LiteralPath (Join-Path $backup $pair[0]) -Algorithm SHA256).Hash -ne $pair[1]) { + throw 'Backup checksum failed' + } +} +if ($state.EnvironmentHash -and (Get-FileHash -LiteralPath (Join-Path $backup 'environment.env') -Algorithm SHA256).Hash -ne $state.EnvironmentHash) { + throw 'Environment backup checksum failed' +} +$before = Join-Path $backup ('manual-before-' + [DateTime]::UtcNow.ToString('yyyyMMddTHHmmssfffZ')) +New-Item -ItemType Directory -Path $before | Out-Null +Copy-Item -LiteralPath $state.Config -Destination (Join-Path $before 'config.yaml') +Copy-Item -LiteralPath (Join-Path $backup 'config.yaml') -Destination $state.Config -Force +$environmentPath = Join-Path $state.WorkingDirectory '.env' +if (Test-Path -LiteralPath $environmentPath) { + Move-Item -LiteralPath $environmentPath -Destination (Join-Path $before 'environment.env') +} +if ($state.EnvironmentHash) { + Copy-Item -LiteralPath (Join-Path $backup 'environment.env') -Destination $environmentPath +} +$registration = @{ TaskName = $state.OldTaskName; TaskPath = $state.TaskPath; Xml = [IO.File]::ReadAllText((Join-Path $backup 'old-task.xml')); Force = $true } +# For Password logon, populate User and Password from the same-user PSCredential. +Register-ScheduledTask @registration | Out-Null +Enable-ScheduledTask -TaskName $state.OldTaskName -TaskPath $state.TaskPath +Start-ScheduledTask -TaskName $state.OldTaskName -TaskPath $state.TaskPath +Push-Location $state.WorkingDirectory +try { + & $state.NewExe doctor -check-config -config $state.Config -probe-url ("http://127.0.0.1:" + $state.Port) -management-key-file "$private\management.key" +} finally { Pop-Location } +``` + +Password-logon task registration requires the original account credentials. Use +`Import-Clixml` on the private credential file and pass its username/password to +`Register-ScheduledTask` in memory. Keep the auth directory live throughout this +recovery. Confirm `probe.models` and the expected `probe.accounts` in the redacted +doctor output, then verify clients through Tailscale. + +A machine crash, power loss or forced termination of the migration worker can +leave both tasks disabled. Use the recorded phase and manual stop barriers to +recover. Keep the backup and the old folder until you finish validating clients +through the existing Tailscale URL. + +## Manual migration on Linux and macOS ### 1. Stop the old service @@ -45,7 +322,7 @@ macOS with Homebrew: brew services stop cliproxyapi ``` -Windows: stop and disable the Scheduled Task or service that runs `cli-proxy-api.exe`. +For Windows, use the detached migration procedure above. Keep the old binary until the new hub works, so you can go back. @@ -61,16 +338,24 @@ cp ~/.local/share/t3code-proxy/config.yaml curl -fsSL https://raw.githubusercontent.com/rune-oai/t3code-proxy/main/scripts/install.sh | sh ``` -On Windows, copy the old config to `%LOCALAPPDATA%\t3code-proxy\config.yaml` before you run -`install.ps1`. +The Windows migration keeps the original config path and working directory. ### 3. Review the config -Optional changes that match the new defaults: +An old config keeps its old behavior. Two settings turn on what this project adds, and plan-aware +routing needs both: + +- `routing.strategy: "soonest-reset-first"` for [soonest-reset-first routing](routing.md). Plan + weights and the 5-hour headroom guard only act inside this strategy. If your old config + already used this strategy, two things change on upgrade: tied accounts are spread by plan + weight, and an account with little 5-hour headroom left stops taking new conversations while + another has room. Set `routing.plan-headroom-reserve: 0` to turn the guard off. +- `quota-history.enabled: true` for the [quota history](quota-history.md) recorder. Claude plans + are learned from it, so without it every Claude account weighs 1. The recorder polls every + supported provider you have accounts for; list the ones you want under + `quota-history.providers` to limit that. -- `routing.strategy: "soonest-reset-first"` for [soonest-reset-first routing](routing.md). -- `quota-history.enabled: true` for the [quota history](quota-history.md) recorder. -- `server.host: "127.0.0.1"` if the old hub listened on every interface. +Also consider `server.host: "127.0.0.1"` if the old hub listened on every interface. Earlier `v8.x-t3code` builds set `management.panel-github-repository` so the hub downloaded the panel from this repository's releases. Releases no longer publish a separate `management.html`. @@ -86,9 +371,8 @@ launchctl kickstart -k "gui/$(id -u)/com.t3code-proxy.hub" # macOS t3code-proxy doctor -config ~/.local/share/t3code-proxy/config.yaml ``` -On Windows, run `Start-ScheduledTask -TaskName t3code-proxy`. The `accounts` line of `doctor` -shows which auth directory the hub uses and how many accounts of each provider it found. Open the -panel and confirm every account is listed. +The `accounts` line of `doctor` shows which auth directory the hub uses and how many accounts +of each provider it found. Open the panel and confirm every account is listed. `tailscale serve` forwards to the port, not to a program, so it needs no change. diff --git a/docs/providers.md b/docs/providers.md new file mode 100644 index 00000000000..a99ea24918c --- /dev/null +++ b/docs/providers.md @@ -0,0 +1,268 @@ +# Providers + +The hub serves subscription accounts, provider API keys and OpenAI-compatible upstreams through +one endpoint. Keep subscription logins on your always-on home hub. Clients send the hub's access +key. The hub keeps upstream credentials and refreshes OAuth tokens. + +Using subscriptions this way may violate provider terms, and accounts can be suspended or banned. +Two hard rules apply throughout this page. + +1. Never serve other people's traffic with your subscriptions. +2. Use Claude subscription models only through Claude Code. + +Follow [setup](setup.md) for installation and keys. [Environments](environments.md) covers machines +that run agents, and [box setup](box-setup.md) gives an ordered checklist. + +## Capability table + +The table describes this checkout. **Text APIs** means the hub's translated Chat Completions, +Responses, Claude Messages and Gemini generateContent surfaces. Select a model returned by +`/v1/models`. Tools, reasoning, images and other modalities depend on that model and its executor. +Claude subscription requests must still come from Claude Code. + +**Ranked routing** means soonest-reset-first ranking from observed quota resets. All providers +can use ordinary account selection, priority, retries and affinity. See [routing](routing.md). +**Pooled limits** refers to the web panel's recorded pool charts. The per-account quota views have +broader coverage. T3 Code has its own [usage-provider coverage](t3code.md#what-appears-under-limits). + +| Provider | Login or credential | Served API surface | Quota shown in panel | Pooled limits | Ranked routing | +| --- | --- | --- | --- | --- | --- | +| Claude subscription | `-claude-login` | Text APIs, use Claude Code | Yes, account windows | Yes, plan-weighted | Yes, weekly and model-scoped caps | +| Codex / ChatGPT subscription | `-codex-login`, `-codex-device-login` | Text APIs, Responses WebSocket, Codex routes | Yes, account windows and reset credits | Yes, plan-weighted | Yes, weekly | +| Antigravity / Google account | `-antigravity-login` | Text APIs | Yes, model quota | Yes, per model group | Yes, when the recorder has a reading | +| Kimi.com | `-kimi-login` | Text APIs | Yes, account quota and plan | Yes | Yes, when the recorder has a reading | +| Kimi.ai | `-kimi-ai-login` | Text APIs | Yes, account quota and plan | Yes | Yes, when the recorder has a reading | +| xAI / Grok | `-xai-login` | Text APIs, Responses WebSocket, xAI media routes | Yes, account quota | Yes, weekly and monthly | Yes, when billing windows are reported | +| Devin / Cognition | `-devin-login` | Text APIs, translated Interactions | Yes, daily/weekly status | Yes, daily and weekly | Yes | +| Meta / Muse | `-meta-login` | Text APIs, Muse Code helper routes | Yes, account usage | Yes | Yes, when the recorder has a reading | +| Gemini API key | `api-keys.gemini` | Text APIs | No subscription quota view | No | No | +| Native Gemini Interactions key | `api-keys.interactions` | `/v1beta/interactions` | No | No | No | +| Vertex | `-vertex-import` or `api-keys.vertex` | Text APIs, optional native Interactions | No | No | No | +| AI Studio browser relay | Connected AI Studio relay session | Text APIs over the browser relay | No | No | No | +| Claude, Codex, xAI, Meta API keys | Respective `api-keys` groups | Text APIs and executor-specific routes | No subscription quota guarantee | No | Only where supported reset signals exist | +| Mistral | API key under `api-keys.openai-compatibility`, host `api.mistral.ai` | Text APIs | Monthly API and Vibe budgets through the recorder | Recorded monthly windows | No | +| OpenAI-compatible upstream | `api-keys.openai-compatibility` | Text APIs, configured image models | No | No | No | +| Plugin provider | Plugin-defined login or credentials | Plugin-defined executor or compatibility API | When the plugin supplies quota | When the plugin supplies renewing windows | When the plugin supplies renewing windows | + +Pooled limits and ranked routing for providers other than Claude and Codex come from the +[quota history](quota-history.md) recorder, which polls each provider's usage endpoint. With the +recorder off, those providers rotate by plan weight without ranking. + +Accounts on different plans do not count equally. The hub resolves each account's plan and gives +it a capacity weight (Claude Pro 1, Max 5x 5, Max 20x 20; Codex Plus 1, the $100 Pro tier 5, the $200 Pro tier 20), used by both +the pool charts and routing. Override the weights under `routing.plan-weights`. They are separate +from the integer credential `weight` used by weighted-round-robin. See [routing](routing.md). + +## Subscription logins + +Run these commands on the hub with the service's config. Repeat once per account. The human +finishes authorization in a browser. On Windows, use the config path from [setup](setup.md). + +```sh +CONFIG=~/.local/share/t3code-proxy/config.yaml +t3code-proxy -config "$CONFIG" -claude-login +t3code-proxy -config "$CONFIG" -codex-login +t3code-proxy -config "$CONFIG" -codex-device-login +t3code-proxy -config "$CONFIG" -antigravity-login +t3code-proxy -config "$CONFIG" -kimi-login +t3code-proxy -config "$CONFIG" -kimi-ai-login +t3code-proxy -config "$CONFIG" -xai-login +t3code-proxy -config "$CONFIG" -devin-login +t3code-proxy -config "$CONFIG" -meta-login +``` + +| Account | What you authorize | Clients through the hub | +| --- | --- | --- | +| Claude | Anthropic Claude subscription OAuth | Claude Code, including Claude Code run by T3 Code | +| Codex | ChatGPT account's Codex access | Codex CLI, including T3 Code's **Use existing CLI** instance, and compatible Responses clients | +| Antigravity | Google OAuth and Antigravity model access | Claude Code or Codex using an exposed model, or a compatible text API client | +| Kimi.com / Kimi.ai | Moonshot's device authorization on the selected domain | Claude Code, Codex or a compatible text API client using a Kimi model | +| xAI | Grok device authorization | Claude Code, Codex or a compatible text API client using a Grok model | +| Devin | Cognition authorization code or session token | Claude Code, Codex or a compatible text API client using a Devin catalog model | +| Meta | Muse device authorization | Claude Code, Codex or a compatible text API client using a Muse model | + +The client setup below applies to each row. The provider name selects the upstream account pool +through the chosen model. Logging into a provider on the hub does not configure that provider's +native application on another machine. + +### Headless logins and callbacks + +For Claude, Codex browser login and Antigravity, open an SSH tunnel from your laptop before +starting the login on the hub. Choose the matching row. + +| Login | Callback | Tunnel from laptop | +| --- | --- | --- | +| Claude | `http://localhost:54545/callback` | `ssh -L 54545:localhost:54545 @..ts.net` | +| Codex browser | `http://localhost:1455/auth/callback` | `ssh -L 1455:localhost:1455 @..ts.net` | +| Antigravity | `http://localhost:51121/oauth-callback` | `ssh -L 51121:localhost:51121 @..ts.net` | + +In that SSH session, use the corresponding command with `-no-browser` and open its printed URL +on your laptop. + +```sh +t3code-proxy -config ~/.local/share/t3code-proxy/config.yaml -claude-login -no-browser +t3code-proxy -config ~/.local/share/t3code-proxy/config.yaml -codex-login -no-browser +t3code-proxy -config ~/.local/share/t3code-proxy/config.yaml -antigravity-login -no-browser +``` + +Use the default ports above for Claude and Codex. Their authorization URLs use fixed callback +URIs in this checkout. Antigravity builds its callback URI from the listener port and supports +`-oauth-callback-port `. Forward that same port if you change it. A busy callback port +usually means another login is running. + +Codex device login, Kimi, Kimi.ai, xAI and Meta print a verification URL and device code. Add +`-no-browser` on SSH and authorize on your laptop. They need no callback tunnel. + +```sh +t3code-proxy -config "$CONFIG" -codex-device-login -no-browser +t3code-proxy -config "$CONFIG" -kimi-login -no-browser +t3code-proxy -config "$CONFIG" -kimi-ai-login -no-browser +t3code-proxy -config "$CONFIG" -xai-login -no-browser +t3code-proxy -config "$CONFIG" -meta-login -no-browser +``` + +Devin's `-no-browser` flow prompts for an authorization code or session token in the hub terminal. +Enter it there privately. + +```sh +t3code-proxy -config "$CONFIG" -devin-login -no-browser +``` + +Its browser flow uses an ephemeral callback port by default. For a tunneled browser flow, +forward a fixed port from your laptop. + +```sh +ssh -L 54546:localhost:54546 @..ts.net +``` + +In that SSH session, run the browser flow with the matching listener port and open the printed +URL on your laptop. + +```sh +t3code-proxy -config ~/.local/share/t3code-proxy/config.yaml -devin-login -oauth-callback-port 54546 +``` + +## Point clients at the hub + +Back up existing settings and merge these entries with the rest of each file. The URL belongs to +the hub. The access key is from `access.api-keys`. Keep the management secret for the panel and +the T3 Code usage provider. + +For Claude Code, put this in `~/.claude/settings.json`, or `%USERPROFILE%\.claude\settings.json` +on Windows. + +```json +{ + "env": { + "ANTHROPIC_BASE_URL": "https://..ts.net:8317", + "ANTHROPIC_AUTH_TOKEN": "" + } +} +``` + +For Codex, use `~/.codex/config.toml`, or `%USERPROFILE%\.codex\config.toml` on Windows. + +```toml +model_provider = "t3code-proxy" + +[model_providers.t3code-proxy] +name = "t3code-proxy" +base_url = "https://..ts.net:8317/v1" +wire_api = "responses" +requires_openai_auth = false +supports_websockets = true +experimental_bearer_token = "" +``` + +Choose an available model from the hub's catalog. These flags are supported by both installed +clients. + +```sh +claude --model +codex --model +``` + +A general OpenAI-compatible client takes base URL +`https://..ts.net:8317/v1` and the access key as its API key. A Messages client +takes the root hub URL and calls `/v1/messages`. A Gemini-compatible client calls +`/v1beta/models/:generateContent` or `:streamGenerateContent` and can send the access key +in `X-Goog-Api-Key`. Native Interactions calls use `/v1beta/interactions`. + +T3 Code uses these settings on the machine running the environment. See [T3 Code](t3code.md). + +## API-key providers and custom upstreams + +The v8 config has two key areas. `access.api-keys` authenticates your clients. The top-level +`api-keys` mapping holds upstream provider groups. Its supported groups are `gemini`, +`interactions`, `vertex`, `claude`, `codex`, `xai`, `meta` and `openai-compatibility`. + +For example, merge this into your hub config to add Gemini and an OpenAI-compatible upstream. +Replace the example model with one your upstream actually serves. + +```yaml +api-keys: + gemini: + - name: google-api + keys: + - api-key: "" + openai-compatibility: + - name: custom + base-url: "https:///v1" + keys: + - api-key: "" + models: + - name: "" + alias: "" +``` + +Use `api-keys.claude` for Anthropic Messages endpoints, `api-keys.codex` for Codex-compatible +Responses endpoints, and `api-keys.xai` or `api-keys.meta` for their native executors. Use +`openai-compatibility` for OpenAI, OpenRouter, local servers or another Chat Completions upstream. +Its models can declare image support. Each group supports multiple keys, model aliases and +per-key routing settings. Follow the commented examples for endpoint paths and optional fields. +See [configuration](configuration.md) and [config.example.yaml](../config.example.yaml). + +### Mistral + +Configure Mistral under `api-keys.openai-compatibility` with base URL +`https://api.mistral.ai/v1`, the account's API key and its models. The quota-history recorder +recognizes the `api.mistral.ai` host regardless of the configured upstream name. Select +`mistral` in `quota-history.providers`, or leave the list empty to poll all supported providers. +The configured name labels the account. Monthly API and Vibe Code budgets and the subscription +plan come from Mistral's billing endpoints using the same API key. Each budget resets on the +first day of the month, UTC. These are usage-only windows, and each account has weight 1. +See [quota history](quota-history.md) for the recorded fields. + +### Google AI Studio and Vertex + +Gemini API keys issued through Google AI Studio go in `api-keys.gemini`. Keys for direct native +Interactions execution go in `api-keys.interactions`. + +The separate `aistudio` provider is a browser WebSocket relay. A connected channel whose ID begins +with `aistudio-` at `/v1/ws` creates a runtime account and forwards requests through that browser +session. It requires a compatible connected relay client. This checkout has no AI Studio login +flag or bundled browser-client installer. See the +[relay registration](../sdk/cliproxy/service_auth.go) and +[executor](../internal/runtime/executor/aistudio_executor.go). + +Vertex accepts API keys under `api-keys.vertex` or a Google Cloud service-account JSON import. + +```sh +t3code-proxy -config "$CONFIG" -vertex-import /secure/path/service-account.json +``` + +The import stores the key in the auth directory, requires a `project_id`, and defaults the +location to `global`. `-vertex-import-prefix ` gives its models a namespace. There is no +browser callback for the import. Native Vertex Interactions is opt-in through +`interactions: true` on the key group or imported credential. Treat the original JSON and stored +account file as secrets. See the [import implementation](../internal/cmd/vertex_import.go). + +## Check coverage in source + +The CLI flags live in [cmd/server](../cmd/server/main.go), the login flows in +[sdk/auth](../sdk/auth), and executor registration in +[service_executors.go](../sdk/cliproxy/service_executors.go). The +[HTTP routes](../internal/api/server_routes.go), +[quota adapters](../web/src/features/quota/providers/index.ts), +[pool model](../web/src/features/quota/poolModel.ts) and +[reset selector](../sdk/cliproxy/auth/selector_reset.go) define the capability table above. diff --git a/docs/quota-history.md b/docs/quota-history.md index 8980d162a1e..50fd81bb20a 100644 --- a/docs/quota-history.md +++ b/docs/quota-history.md @@ -1,9 +1,49 @@ # Quota history -The quota-history recorder polls each Claude and Codex account's usage on a schedule and stores +The quota-history recorder polls supported accounts' usage on a schedule and stores the readings on the hub. With it enabled, the web panel's Overview page charts remaining quota over time and projects when the pool runs out, and soonest-reset-first routing sees spent -model-scoped caps before it sends a request. +renewing caps before it sends a request. + +## On the Overview page + +The Overview has two views, switched next to the provider tabs; both follow the provider tab and +share the same 14-day span. + +**Pools.** Every provider whose accounts report a quota window that renews gets the same pool +card: a chart of the pooled remaining quota with its projection, the time the pool and the first +account run dry, the next reset, the burn rate, and a row per account. A provider the recorder +samples is charted from its history; any other provider (the recorder is off, or it has not +sampled the provider yet) is charted from each account's latest live read, which the Refresh +button or the card's **Read quota now** takes. Selecting an account's name opens its full read +beneath the row: every window with its reset time, the plan details, Claude extra usage, Codex +banked resets and credit overage, xAI usage breakdown and pay-as-you-go state, Antigravity groups +and their models, the last read's error, and the account's actions (read again, Claude reset +grants, Codex reset quota). A provider whose accounts report no renewing window at all, such as +an API key or an account whose read failed, is listed in the same kind of table below the pools. +Account emails are shown; **Hide emails** blurs them and the choice is remembered in the browser. + +**Resets.** A calendar of every account window: one lane per window, grouped by provider and +ordered the way soonest-reset-first routes (soonest reset of an account's longest window first). +Each bar runs from when a window opened to when it resets; the current one is solid with its +remaining share, upcoming ones are dashed, and elapsed ones are muted and show how much was left +unspent when they reset. 5-hour windows start on first use, so only the current one is drawn. +Monthly windows (the xAI billing month, Mistral budgets) turn over on the calendar month. Banked +Codex resets are marked at their expiry, with **Use reset** beside the account. Above the +calendar, **Next resets** lists the soonest daily-or-longer resets with the allowance still +unspent on each: whatever is left when a window resets is lost. A window filter (5-hour, Weekly, +Monthly) narrows both. + +Providers the hub reads with an API key rather than a credential file, such as a Mistral EDU key +with monthly budgets, exist only in the history; they get a tab, a pool and calendar lanes all the +same, and a window with a budget reads in money beside percent ("$0.39 of $15 spent"). + +Pooled figures are in percent of the heaviest plan in the pool. That plan's account counts as +100% and a lighter plan by its [plan weight](routing.md#plan-capacity): a Max 5x and a Pro +account pool to 120% (Max 5x = 100%, Pro = 20%), so 38% left on the Max 5x and none on the Pro +reads as "38% of 120%". A pool whose accounts all weigh the same reads as N × 100%. The chart +axis, reset steps, burn rate and the accounts' Capacity column use the same unit. Plan weights +are edited from the sliders button on each pool card. ## Turn it on @@ -13,6 +53,7 @@ quota-history: interval: 10m retention: 35d path: "" + providers: [] ``` | Key | Meaning | Default | @@ -20,6 +61,7 @@ quota-history: | `enabled` | Run the recorder. When `false`, nothing is polled or written. | `false` | | `interval` | Time between polls of each account. Go duration or `d`. Minimum `5m`. | `10m` | | `retention` | Samples older than this are deleted, checked hourly. Minimum `1d`. | `35d` | +| `providers` | Provider IDs to poll, for example `[claude, codex, kimi, mistral]`. An omitted or empty list enables every supported provider, including registered quota plugins. | `[]` | | `path` | Database file. Relative paths resolve against the config file's directory. | `quota-history.db` next to the config file | The installer's config enables it. Changes apply on config reload without a restart. The database @@ -27,24 +69,78 @@ must not be inside the auth directory; the recorder refuses such a path. ## What it reads -For each enabled Claude and Codex OAuth account, the recorder calls the provider's usage endpoint -with that account's token: +Enabling quota history means the hub polls each selected provider's usage endpoint on the +configured interval. Disabled accounts are included in the account list and skipped during polling. +One account's reading is given at most 45 seconds; an account that does not answer in time is +recorded as an error for that round and the next account is read. A reading never refreshes an +OAuth token itself: an xAI or Antigravity account whose token is due for refresh is recorded as +`token refresh due` for that round and read again after the hub's own refresh has renewed it. -- Claude: `https://api.anthropic.com/api/oauth/usage` -- Codex: `https://chatgpt.com/backend-api/wham/usage` +When a provider leaves `providers`, or the recorder is turned off, the readings it took for those +accounts are dropped from routing straight away. +Each request uses the account's credentials and configured proxy through the existing management +transport. Registered quota plugins use the host's per-account quota capability and HTTP client. -Each sample stores the used percentage, reset time and length of every window the provider -reports. Window IDs: - -| Window | Providers | -| --- | --- | -| `five_hour` | Claude, Codex | -| `seven_day` | Claude, Codex | -| `seven_day_opus` | Claude | -| `seven_day_fable` | Claude | +| Provider | Usage endpoint | Window keys | +| --- | --- | --- | +| Claude | `GET https://api.anthropic.com/api/oauth/usage` | `five_hour`, `seven_day`, `seven_day_opus`, `seven_day_fable` | +| Codex | `GET https://chatgpt.com/backend-api/wham/usage` | `five_hour`, `seven_day` | +| xAI/Grok (`xai`) | `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits` and `GET https://cli-chat-proxy.grok.com/v1/billing` | `weekly`, `monthly` | +| Antigravity (`antigravity`) | `POST /v1internal:retrieveUserQuotaSummary` on the three hosts below, with `{"project":""}` | `group__`, such as `group_gemini_models_gemini_weekly` | +| Kimi (`kimi`, `kimi-ai`) | `GET https://api.kimi.com/coding/v1/usages` or `https://api.kimi.ai/coding/v1/usages`, following the credential's domain | `summary`, `monthly`, `limit_` or `limit_h` | +| Meta/Muse (`meta`) | `POST https://api.meta.ai/muse-code/key` with `{}` and the account's DCA token | `window`, `weekly` | +| Devin (`devin`) | `POST https://server.codeium.com/exa.seat_management_pb.SeatManagementService/GetUserStatus` with the panel's Connect JSON metadata | `daily`, `weekly` | +| Mistral (`mistral`) | `GET https://api.mistral.ai/v1/billing/budget` with the upstream API key | `api_monthly`, `vibe_monthly` | +| Registered quota plugins | The existing plugin host `FetchQuota` capability selects the upstream endpoint | `group__` | + +Antigravity tries `daily-cloudcode-pa.googleapis.com`, +`daily-cloudcode-pa.sandbox.googleapis.com`, then `cloudcode-pa.googleapis.com`. It preserves +partial pools across responses and stops when Gemini quota is available, following the panel. +The account must have a project ID. Claude also reads its OAuth profile at most every six hours +for the cached plan label. + +Mistral API-key upstreams are recognized by the `api.mistral.ai` base URL host. The configured +upstream name labels the history account. `GET /v1/billing/subscription` supplies `plan_name`, +cached for six hours. The `api_monthly` window is labeled "API usage" and `vibe_monthly` is +labeled "Vibe Code". Each records `usage_percentage` as `used_percent`, `reset_at` as `resets_at`, +and the current UTC calendar month's length as `period_hours` (672, 696, 720 or 744 hours). +Resets occur on the first day of each month, UTC. Percentages above 100 are preserved so spending +can be calculated accurately. Missing budget objects are skipped, and a response with neither +budget records an empty-payload error. A missing reset is stored as `null`. + +Each sample stores used percentage, reset time and period in hours. Existing Claude/Codex +window keys and the history response shape are preserved. Group and bucket names are normalized +to lowercase with underscore separators. A missing bucket ID uses its window name, then its +array index. Kimi limit keys use the name/title/scope when available, then the explicit period, +then the array index. Duplicate keys gain an index suffix. These index fallbacks follow the +provider's response order. Unknown usage percentages produce no window, and an unknown period +is stored as `0` with an absent reset stored as `null`. + +Soonest-reset-first routing uses the longest renewing window governing the requested model. +Model-scoped windows take precedence over account-wide windows of equal length. Accounts whose +governing window is spent are skipped while another eligible account exists. If all accounts +are spent, the earliest reset wins. Claude's existing scoped weekly observations remain supported. +Antigravity bucket IDs identify Gemini, Claude and GPT pools, including model-specific prefixes. +Unidentified Antigravity pools remain in history and contribute no routing rank. Plugin groups +with recognized model pools use those scopes. Other plugin groups apply account-wide because +the current plugin quota contract supplies no model-scope field. Renewing plugin windows need +a known period (`5h`, `weekly`, `daily`, or a duration such as `24h` or `7d`). + +A usable reading requires a known used percentage, positive period and future reset. Providers +without such a reading retain their existing routing behavior. xAI paid-account health checks +supply no quota window, so the recorder uses billing data and leaves accounts without it +unranked. Billing periods need both start and end times to establish their duration. Kimi's +weekly summary and monthly summary use the same 7-day and 30-day periods as the panel. +Providers without a built-in usage call or registered quota capability, including standalone +Gemini CLI and declarative plugin probes, are skipped. Passive response-header parsing remains +limited to the existing supported headers. A failed poll is stored as a sample with an `error` message, so gaps in the chart have a reason. +Mistral's API and Vibe Code allowances cover separate request types. The recorder keeps both as +usage-only windows with account weight 1. Routing continues to use ordinary account selection +and upstream failure handling for these accounts. + ## API Both endpoints need the management secret (`Authorization: Bearer `). They are @@ -82,6 +178,22 @@ before `until`. The response: } ``` +Windows can also include `label`, `budget` and `currency`. `budget` is the monetary allowance +from `initial_budget`, such as `15`, and `currency` is its currency code, such as `"USD"`. +Empty values are omitted. Spending is `budget * used_percent / 100`. A Mistral API window +can therefore be returned as follows. + +```json +{ + "used_percent": 2.59892596, + "resets_at": 1796083200000, + "period_hours": 720, + "label": "API usage", + "budget": 15, + "currency": "USD" +} +``` + When the recorder is off the response is `200` with `"enabled": false` and empty arrays. A bad `since` or `until` returns `400`. diff --git a/docs/routing.md b/docs/routing.md index 00f11f8907d..859d7a6c4f4 100644 --- a/docs/routing.md +++ b/docs/routing.md @@ -37,18 +37,43 @@ allowance that expires first, so less of it goes unused. For each new conversation the hub: -1. Takes the accounts in the highest available priority tier. Weights are ignored. +1. Takes the accounts in the highest available priority tier. The per-account `weight` is + ignored; [plan weights](#plan-capacity) are used instead. 2. Reads each account's most recent weekly reset time. Claude accounts report it in the `Anthropic-Ratelimit-Unified-7d-Reset` response header; Codex accounts report a 7-day window in their rate-limit headers. A reading stays valid until its reset time passes. -3. Sends the request to the account whose weekly window resets first. Ties rotate round-robin. +3. Sends the request to the account whose weekly window resets first. Ties are spread in + proportion to plan weight. Two cases change that order: - **Accounts without a reading.** An account the hub has not observed yet, or whose last reading is older than one hour and no longer has a future reset, is tried first. This collects a fresh - reading after a restart or a reset. Providers that never report a weekly window, such as xAI and - Antigravity, are not ranked; a pool of only those accounts rotates round-robin. + reading after a restart or a reset. When several accounts need a reading, they are spread by + plan weight too. Providers whose limits the hub only learns from the + [quota history](quota-history.md) recorder, such as xAI, Antigravity, Kimi and Meta, are ranked + once every available account of that provider has a reading. Until then, or with the recorder + off, that provider's accounts rotate by plan weight when the pool holds only that provider, so + one account whose reading failed is not starved by the others. In a pool shared with a provider + that is ranked, the ranked provider's accounts come first and the unread provider's accounts + serve as fallback until every one of them has a reading. This lasts as long as the reading keeps failing: fix or disable that + account to get ranking back. The Overview page shows which account has no reading. +- **Spent windows.** An account is skipped, while another eligible account exists, when any window + that governs the requested model is spent, not only the longest one: a spent 5-hour or weekly + window makes the account unusable whatever its monthly window says. The longest window still + gives the reset used for ranking. If Claude's or Codex's response headers are newer than the + recorder's reading and show the window with allowance left, as after an early reset, the headers + win. Resetting an account's quota state from the panel also clears its recorded readings. +- **Spent accounts while another is on hold.** When every account that could take a request is + known to be spent, and an account with allowance left is only held back for a while (a quota + cooldown, or the short hold after an upstream error such as "overloaded"), the hub answers + with its own cooldown error and a `Retry-After` for when that account is back. It does not send + the request to a spent account, whose refusal would tell the client to wait for that account's + reset, often days away. When every account really is spent the request still goes to the one + that resets first, so the client gets the provider's own answer. +- **Nearly spent 5-hour window.** An account whose 5-hour window has almost no headroom left is + skipped for new conversations while another account has more. See + [5-hour headroom](#5-hour-headroom). - **Model-scoped weekly caps.** Claude has weekly caps that apply to one model family, such as the Fable and Opus weekly windows, next to the overall weekly window. When the requested model belongs to such a family, the hub skips accounts whose cap for that family is spent, as long as @@ -64,8 +89,99 @@ recorder on, the hub can see a spent cap before it sends a request to that accou For Codex, accounts that support the WebSocket transport are preferred when the request arrives over a WebSocket. -The web panel's Overview page marks the account that receives the next new conversation as -**Next**. The Routing page sets the strategy, session affinity, priority tiers and weights, and +### Plan capacity + +Accounts in one pool are not equal. A Claude Max 20x account has about twenty times the +allowance of a Pro account, so it should take about twenty times as many conversations. The hub +gives each account a plan weight: its capacity relative to the provider's base paid plan, which +weighs `1`. + +The plan comes from what the hub already knows about the account, newest first: + +- the plan read by the [quota history](quota-history.md) recorder (Claude's OAuth profile, the + `plan_type` in Codex's usage reply), +- the `X-Codex-Plan-Type` response header, +- the fields stored with the credential: Codex `plan_type` from the ID token, or a Claude + `subscription_type` / `rate_limit_tier`. + +Built-in weights: + +| Provider | Plan | Weight | +| --- | --- | --- | +| Claude | `pro`, `team` | 1 | +| Claude | `max_5x`, or `max` with an unknown tier | 5 | +| Claude | `max_20x` | 20 | +| Claude | any `max_x` tier, such as `default_claude_max_40x` | N | +| Codex | `plus`, `team`, `business`, `enterprise`, `edu` | 1 | +| Codex | `prolite` (the $100 Pro tier) | 5 (approximate) | +| Codex | `pro` (the $200 Pro tier) | 20 (approximate) | +| Codex | `promax` (the $500 tier) | 50 (approximate) | +| Codex | `free`, `go` and other names not listed | 1 (not known; set your own) | +| xAI | `supergrok` | 1 | +| xAI | `supergrok_heavy` | 10 | +| any | unknown plan or provider | 1 | + +The Codex ratios are approximate. OpenAI describes its tiers as multiples of Plus usage (5x for +the $100 tier, 20x for the $200 tier) and changes them over time; `promax` is set to 2.5 times +`pro`. SuperGrok Heavy carries ten times the monthly credit of SuperGrok. A plan +name that is not in the table weighs 1, including tiers these defaults do not know yet. The +panel's Overview page shows each account's plan name and its capacity in the pool (the heaviest +plan in the pool is 100%; hover the figure for the weight), so check it after adding an account +and add a weight for any plan that reads as large as your base plan but should not. Write plan names lower case +with underscores (`max_20x`, not `Max 20x`). Both spellings are read, but the panel can only +change or clear an override written in that form. Override any weight with +`routing.plan-weights`: + +```yaml +routing: + plan-weights: + codex: + pro: 10 + claude: + max_20x: 18 +``` + +Provider and plan names are case-insensitive, and spaces and hyphens count as underscores +(`Max 20x` is `max_20x`). A weight must be greater than 0 and at most 1000. Listed entries replace +the built-in value; other plans keep theirs. Changes apply on config reload. +`GET /v8/management/routing/plan-weights` returns the built-in, configured and effective tables. + +Where soonest-reset-first has several equal choices (tied resets, accounts that need a reading, +providers that report no quota), it spreads new conversations with smooth weighted round-robin: +with a Pro and a Max 20x account tied, 1 of every 21 new conversations goes to the Pro account, +and the picks are interleaved rather than batched. With equal weights this is plain round-robin. +The proportion holds while the same accounts stay tied; when the set changes (a cooldown, a spent +window), the rotation starts over from the heaviest account. +Ranking still comes first: an account whose weekly window resets sooner takes every new +conversation regardless of weight. + +### 5-hour headroom + +Claude and Codex accounts also have a 5-hour window. A conversation started on an account whose +5-hour window is nearly spent runs into that limit within a few turns. The hub therefore does +not start a new conversation on such an account while another eligible account has headroom. + +Headroom is plan weight times the percent of the 5-hour window left. 10% left on a Pro account is +10; 10% left on a Max 20x account is 200. An account is tight when its headroom is below +`routing.plan-headroom-reserve`: + +```yaml +routing: + plan-headroom-reserve: 10 # default; 0 disables the guard +``` + +With the default of 10, a Pro account is tight below 10% left, a Max 5x account below 2%, and a +Max 20x account below 0.5%. The value must be between 0 and 1000. + +The guard uses only readings the hub already has: Claude's +`Anthropic-Ratelimit-Unified-5h-*` and Codex's 300-minute window in its rate-limit response +headers, and the 5-hour readings the quota history recorder takes. It makes no extra upstream +call. A reading whose window has since reset no longer counts. If every account is tight, the +guard does nothing and the normal order applies. Conversations already bound by session affinity +are not moved by it. + +The web panel's Overview page marks the account expected to receive the next new conversation as +**Next**. It is an estimate that follows the same order and the default headroom reserve. The Routing page sets the strategy, session affinity, priority tiers and weights, and shows the current reset order. ## Session affinity @@ -84,6 +200,12 @@ The strategy decides only where a new conversation starts. Once a conversation i keeps it on that account until the binding expires (`session-affinity-ttl` after its last use) or the account fails. On failure it moves the conversation and binds it to the new account. +When the hub already knows that a window governing the requested model is spent on the bound +account, and another eligible account exists, it rebinds the conversation before sending instead +of first collecting a 429. That covers Claude's model-scoped weekly caps (such as the Fable weekly +window) and any spent window the recorder has read for the account, on every provider. With +`session-affinity-rebind-on: never` the binding is kept. + The hub identifies a conversation from the session headers that Claude Code and Codex send, and falls back to other request fields when those are missing. Subagents inherit their parent's account by default (`session-affinity-subagents: true`). `session-affinity-rebind-on` controls diff --git a/docs/setup.md b/docs/setup.md index 721ce3debf5..fcf1bd76ffa 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,10 +1,18 @@ # Setup guide -At the end of this guide you have one always-on machine at home running t3code-proxy with your -Claude and Codex accounts signed in, reachable from your other machines over Tailscale, and -Claude Code and Codex on those machines sending their requests through it. +At the end of this guide you have one always-on machine at home running t3code-proxy, reachable +from your other machines over Tailscale, with your chosen provider accounts and keys. Claude +Code and Codex on those machines send requests through it. The examples start with Claude and +Codex. [Providers](providers.md) covers every supported subscription login, API-key provider, +AI Studio/Vertex and OpenAI-compatible upstream. + +The panel offers plan-aware pooled limits for supported providers. Check the +[capability table](providers.md#capability-table) for current coverage and [routing](routing.md) +for account selection. If a coding agent is doing the setup for you, point it at the [guide for agents](agents.md). +Use [environments](environments.md) to run T3 Code on other machines and [box setup](box-setup.md) +for the ordered SSH checklist. ## Before you start: risks and rules @@ -233,6 +241,10 @@ docker compose exec t3code-proxy t3code-proxy -config /data/config.yaml -claude- Repeat each login once per account. Each OAuth login ends in a browser where you sign in to that account. +For Antigravity, Kimi.com, Kimi.ai, xAI, Devin and Meta, follow +[subscription logins](providers.md#subscription-logins). That page gives each callback or device +flow and the matching client settings. API keys and Vertex imports are covered there too. + ### Headless hub: tunnel the callback The Claude login redirects your browser to `http://localhost:54545/callback` on the machine @@ -314,7 +326,9 @@ CODEX_HOME=~/.codex-hub codex Here `~/.claude-hub/settings.json` and `~/.codex-hub/config.toml` hold the hub settings. -For T3 Code, see [T3 Code](t3code.md). +For T3 Code, see [T3 Code](t3code.md). Configure these files on the machine running the +[environment](environments.md), including when it is a remote home or cloud box. On Windows +and WSL 2, configure the two users' homes separately. ## 8. Verify diff --git a/docs/t3code.md b/docs/t3code.md index a1100525220..fcd0f40664f 100644 --- a/docs/t3code.md +++ b/docs/t3code.md @@ -1,8 +1,13 @@ # T3 Code -After this page, T3 Code sends its Claude and Codex requests through your hub, and **Usage → -Limits** shows the pooled limits of every account on the hub. You need a working hub from the -[setup guide](setup.md). +After this page, T3 Code sends its configured providers' requests through your hub, and +**Usage → Limits** shows pooled limits for the accounts its usage reader supports. You need a +working hub from the [setup guide](setup.md). [Providers](providers.md) lists every subscription +and API-key upstream, its login flow and its client API surface. + +Subscription proxying may violate provider terms and can lead to suspension or a ban. Never +serve other people's traffic with your subscriptions. Use Claude subscriptions only through +Claude Code, including the Claude Code instance T3 Code runs. T3 Code needs no plugin and no change on the hub. Requests go through the clients' own config files, and limits come from the hub's management API. @@ -13,6 +18,10 @@ T3 Code runs a provider on the machine of the environment that owns the thread, machine's Claude Code and Codex configuration. Configure the hub on that machine. Phones and other devices that only view the thread do not matter here. +[Environments](environments.md) covers the verified `t3 serve`, `t3 connect`, service and pairing +commands, including Windows and WSL 2 on one PC. [Box setup](box-setup.md) gives an ordered SSH +checklist. Once you select a remote environment, its terminals and agents run on that box. + ## Claude Pick one of these on the environment's machine: @@ -30,6 +39,45 @@ Point the machine's Codex at the hub in `~/.codex/config.toml` as in the setup g choose **Use existing CLI** for Codex. That option reads `config.toml`. **Continue with ChatGPT** signs in directly and does not go through the hub. +## Antigravity (Gemini) + +T3 Code's Antigravity provider runs the Antigravity CLI (`agy`). With its **Gemini API key** sign-in +the CLI sends Gemini API requests, and it reads the endpoint from `GOOGLE_GEMINI_BASE_URL`. That +lets the stock provider use the hub's Antigravity account. It needs an `agy` release that knows +this variable; 1.5.9 does. + +1. Open **Settings → Providers → Antigravity**. +2. Set the sign-in method to **Gemini API key** and enter a hub access key, not a Google key. +3. Add the environment variable `GOOGLE_GEMINI_BASE_URL` with the hub's root URL, such as + `https://..ts.net:8317`. + +The model list comes from the CLI, not from the hub, so it also shows Gemini models your +Antigravity account does not serve. Those fail with `unknown provider for model`. Hide them in +the model picker and keep the ones `GET /v1beta/models` on the hub returns. The Google account +sign-in method does not go through the hub. + +## Mistral (OpenCode and Vibe) + +Mistral has two monthly budgets on one account: API usage and Vibe Code. Which one a request +draws on is decided by Mistral from the client that sent it. + +- **OpenCode** pointed at the hub uses the hub's Mistral upstream (an `api-keys.openai-compatibility` + entry for `https://api.mistral.ai/v1`) and draws on the API budget. +- **Mistral Vibe**, added in T3 Code as an ACP agent and signed in with Mistral, talks to Mistral + directly and draws on the Vibe Code budget. It does not pass through the hub. + +The hub reads both budgets with its Mistral key and shows them on the Overview page as money +spent of the monthly amount, with the reset date, whichever client did the spending. See +[quota history](quota-history.md). + +## Other upstream providers + +The hub also serves Antigravity, Kimi, xAI, Devin, Meta, Google API keys, Vertex and +OpenAI-compatible upstreams. Use the client configuration and model selection in +[providers](providers.md#point-clients-at-the-hub). For example, a Codex instance pointed at the +hub can select an exposed model from another upstream. Check the model's supported tools and +modalities before relying on it for a coding task. + ## Add the hub as a usage provider A Claude connection that uses `ANTHROPIC_AUTH_TOKEN` does not report subscription limits by @@ -53,6 +101,12 @@ on an environment and also on the hub counts once. T3 Code reads the hub's Codex, Claude, xAI (shown as Grok) and Antigravity accounts. Accounts for other providers on the hub are not shown. +The hub web panel has its own quota views and plan-aware pool charts. Its Claude and Codex +charts let you weight accounts by plan. Configure those weights to match your subscriptions. +The [capability table](providers.md#capability-table) gives the panel's coverage, and +[quota history](quota-history.md) describes the recorder. T3 Code reads provider usage through +the management endpoints below. The panel's chart weights are stored in that browser. + ## Reset credits Codex accounts can hold banked reset credits. T3 Code shows the count in each account's details. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d86eaa27f87..0565ae53114 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -7,6 +7,10 @@ finds most setup problems and prints a fix for each: t3code-proxy doctor -config ~/.local/share/t3code-proxy/config.yaml ``` +The hub serves subscription and API-key providers with different quota capabilities. Check +[providers](providers.md) for the login and client API you are using. [Environments](environments.md) +covers T3 Code service and pairing setup. [Box setup](box-setup.md) gives the checks in order. + ## Codex returns 401 `token_invalidated` The account's OAuth grant is dead. Refreshing cannot bring it back, and restarting the hub does @@ -103,3 +107,51 @@ the access key, not the management secret. Conversations are moving between accounts. See [check that affinity works](routing.md#check-that-affinity-works). + +## A provider works but has no pooled chart or reset rank + +Per-account quota, recorded pool charts and soonest-reset-first ranking have different provider +coverage. Compare the [capability table](providers.md#capability-table), then check +[quota history](quota-history.md) and [routing](routing.md). For plan-aware pool charts, set the +plan weights to match your subscriptions. A missing plan weight counts as one account. + +T3 Code's Limits view has its own [provider coverage](t3code.md#what-appears-under-limits). +Seeing an account in the hub's Accounts page establishes that the hub loaded its credentials. +Check a real client request and the relevant quota view as separate verification steps. + +## T3 Code works locally but the remote environment is offline + +On the machine that runs the environment, inspect its service and Serve target. + +```sh +t3 service status +t3 status +tailscale serve status +``` + +Confirm the local port matches the Tailscale Serve target, and that the machine is awake. A +foreground `t3 serve` exits with its terminal. Linux services need linger. The macOS launchd +agent and Windows task need their user logged in. Follow [environments](environments.md) for +the platform-specific checks and a fresh pairing link. The hosted web client needs HTTPS. + +If using T3 Connect, `t3 connect status` tests that route. `t3 status --json` only reads settings. + +## T3 Code calls the provider directly on another machine + +Edit the Claude Code and Codex settings on the machine that owns the thread's environment. +Check its service user and provider config directory, then start a fresh provider session. +Choose **Use existing CLI** for Codex. Follow [T3 Code](t3code.md) and +[the client settings](providers.md#point-clients-at-the-hub). + +## Windows and WSL show the wrong environment or stop after closing terminals + +Use separate provider installations, user homes and T3 listener ports. Check Windows' Serve +target for the Linux port before pairing. Microsoft documents that systemd services alone do +not keep WSL running. Check the Windows task that launches the Linux foreground server and +verify `wsl --list --verbose` after closing the terminals. + +For a hub on the same Windows PC, default WSL NAT has separate loopback. Use the hub's Tailscale +HTTPS URL or the documented mirrored-network path. Tailscale also documents failures when both +Windows and WSL carry nested Tailscale traffic. Follow the full +[Windows and WSL 2 section](environments.md#windows-and-wsl-2-as-two-environments) before changing +network settings. diff --git a/internal/api/handlers/management/quota_history.go b/internal/api/handlers/management/quota_history.go index 59139cc0c8c..849d22d59bd 100644 --- a/internal/api/handlers/management/quota_history.go +++ b/internal/api/handlers/management/quota_history.go @@ -5,6 +5,7 @@ package management // and to the same token/transport path APICall uses. import ( + "bytes" "context" "errors" "io" @@ -14,10 +15,12 @@ import ( "sync" "time" + "github.com/MoeForge/moego/ojson" "github.com/gin-gonic/gin" "github.com/rune-oai/t3code-proxy/internal/config" "github.com/rune-oai/t3code-proxy/internal/quotahistory" coreauth "github.com/rune-oai/t3code-proxy/sdk/cliproxy/auth" + "github.com/rune-oai/t3code-proxy/sdk/pluginapi" log "github.com/sirupsen/logrus" ) @@ -34,9 +37,12 @@ type quotaHistoryState struct { func (h *Handler) quotaHistoryRecorder() *quotahistory.Recorder { h.quotaHistory.once.Do(func() { h.quotaHistory.rec = quotahistory.NewRecorder(quotahistory.Deps{ - ListAuths: h.quotaHistoryAuths, - Do: h.quotaHistoryDo, - Label: authEmail, + ListAuths: h.quotaHistoryAuths, + Do: h.quotaHistoryDo, + DoRequest: h.quotaHistoryRequest, + PluginProviders: h.quotaHistoryPluginProviders, + FetchPlugin: h.quotaHistoryPlugin, + Label: authEmail, }) }) return h.quotaHistory.rec @@ -82,14 +88,49 @@ func (h *Handler) quotaHistoryAuths() []*coreauth.Auth { // quotaHistoryDo sends one request with the credential's token, using the same // token resolution and proxy selection as APICall. func (h *Handler) quotaHistoryDo(ctx context.Context, auth *coreauth.Auth, method, url string, header map[string]string) (int, []byte, error) { - token, errToken := h.resolveTokenForAuth(ctx, auth, "") - if token == "" { + return h.quotaHistoryRequest(ctx, auth, method, url, header, nil) +} + +func (h *Handler) quotaHistoryRequest(ctx context.Context, auth *coreauth.Auth, method, url string, header map[string]string, data []byte) (int, []byte, error) { + if auth == nil { + return 0, nil, errors.New("auth token not found") + } + needsToken := !strings.EqualFold(auth.Provider, "meta") || bytes.Contains(data, []byte("$TOKEN$")) + for _, value := range header { + needsToken = needsToken || strings.Contains(value, "$TOKEN$") + } + // The hub's refresh loop renews OAuth tokens. A usage read never starts a + // second refresh of the same token, which could invalidate a single-use + // refresh token; it reports the account as due and reads it next round. + if needsToken && quotaHistoryTokenRefreshDue(auth) { + return 0, nil, errors.New("token refresh due") + } + var token string + var errToken error + if needsToken { + // Credential acquisition has its own deadline. The usage request remains + // cancellable by recorder shutdown without a network timeout. + acquireCtx, cancel := context.WithTimeout(ctx, 20*time.Second) + token, errToken = h.resolveTokenForAuth(acquireCtx, auth, "") + cancel() + } + if needsToken && token == "" { if errToken != nil { return 0, nil, errors.New("auth token refresh failed") } return 0, nil, errors.New("auth token not found") } - req, errReq := http.NewRequestWithContext(ctx, method, url, nil) + if needsToken && len(data) > 0 { + // Replace JSON string values through a document so tokens are escaped. + doc := ojson.NewDoc(data) + if strings.EqualFold(auth.Provider, "devin") { + if errSet := doc.Set("metadata.apiKey", token); errSet != nil { + return 0, nil, errors.New("failed to build request") + } + } + data = doc.Bytes() + } + req, errReq := http.NewRequestWithContext(ctx, method, url, bytes.NewReader(data)) if errReq != nil { return 0, nil, errors.New("failed to build request") } @@ -116,6 +157,50 @@ func (h *Handler) quotaHistoryDo(ctx context.Context, auth *coreauth.Auth, metho return resp.StatusCode, body, nil } +func quotaHistoryTokenRefreshDue(auth *coreauth.Auth) bool { + switch strings.ToLower(strings.TrimSpace(auth.Provider)) { + case "xai": + return xaiRefreshToken(auth) != "" && (xaiTokenValue(auth) == "" || xaiOAuthTokenNeedsRefresh(auth)) + case "antigravity": + return len(auth.Metadata) > 0 && (strings.TrimSpace(tokenValueFromMetadata(auth.Metadata)) == "" || antigravityTokenNeedsRefresh(auth.Metadata)) + } + return false +} + +func (h *Handler) quotaHistoryPluginProviders(ctx context.Context) map[string]string { + h.mu.Lock() + host := h.pluginHost + h.mu.Unlock() + if host == nil { + return nil + } + return host.QuotaProviderPluginIDs(ctx) +} + +func (h *Handler) quotaHistoryPlugin(ctx context.Context, auth *coreauth.Auth) ([]byte, error) { + h.mu.Lock() + host := h.pluginHost + h.mu.Unlock() + if host == nil { + return nil, errors.New("no quota plugin") + } + response, handled, errFetch := host.FetchQuota(ctx, pluginapi.QuotaFetchRequest{ + AuthIndex: auth.Index, AuthID: auth.ID, Provider: auth.Provider, + Metadata: auth.Metadata, Attributes: auth.Attributes, + }) + if errFetch != nil || !handled { + return nil, errors.New("plugin quota request failed") + } + doc := ojson.NewDocString(`{}`) + if errSet := doc.Set("groups", response.Groups); errSet != nil { + return nil, errors.New("invalid plugin quota groups") + } + if errSet := doc.Set("subscription", response.Subscription); errSet != nil { + return nil, errors.New("invalid plugin quota subscription") + } + return doc.Bytes(), nil +} + // GetQuotaHistory returns recorded quota samples. // // GET /v0/management/quota-history?since=&until= diff --git a/internal/api/handlers/management/quota_history_mistral_test.go b/internal/api/handlers/management/quota_history_mistral_test.go new file mode 100644 index 00000000000..2339f077a7a --- /dev/null +++ b/internal/api/handlers/management/quota_history_mistral_test.go @@ -0,0 +1,144 @@ +package management + +import ( + "context" + "net" + "net/http" + "net/http/httptest" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/MoeForge/moego/ojson" + "github.com/gin-gonic/gin" + "github.com/rune-oai/t3code-proxy/internal/config" + "github.com/rune-oai/t3code-proxy/internal/watcher/synthesizer" + coreauth "github.com/rune-oai/t3code-proxy/sdk/cliproxy/auth" +) + +func TestQuotaHistoryMistralAPIKeyEndpoint(t *testing.T) { + budget := `{"vibe_budget":{"usage_percentage":0.0,"initial_budget":150.0,"currency":"USD","reset_at":"2026-12-01T00:00:00Z","payg_enabled":false},"api_budget":{"usage_percentage":2.59892596,"initial_budget":15.0,"currency":"USD","reset_at":"2026-12-01T00:00:00Z","payg_enabled":false},"usage_percentage":2.59892596,"initial_budget":15.0,"currency":"USD","reset_at":"2026-12-01T00:00:00Z"}` + upstream := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + if req.Method != "GET" || req.Host != "api.mistral.ai" || req.Header.Get("Authorization") != "Bearer fixture-mistral-key" { + t.Error("billing request must use the upstream's own Bearer key and host") + w.WriteHeader(http.StatusBadRequest) + return + } + w.Header().Set("Content-Type", "application/json") + switch req.URL.Path { + case "/v1/billing/budget": + _, _ = w.Write([]byte(budget)) + case "/v1/billing/subscription": + _, _ = w.Write([]byte(`{"plan_name":"EDU","payg_enabled":false,"vibe_payg_enabled":false,"enterprise":false}`)) + default: + t.Errorf("unexpected billing path %q", req.URL.Path) + w.WriteHeader(http.StatusNotFound) + } + })) + t.Cleanup(upstream.Close) + // Route the real billing URLs to the TLS fixture while exercising the + // management transport's credential substitution and HTTP request path. + transport := upstream.Client().Transport.(*http.Transport).Clone() + transport.TLSClientConfig.ServerName = "127.0.0.1" + transport.DialContext = func(ctx context.Context, network, _ string) (net.Conn, error) { + return (&net.Dialer{}).DialContext(ctx, network, upstream.Listener.Addr().String()) + } + previous := http.DefaultTransport + http.DefaultTransport = transport + t.Cleanup(func() { + http.DefaultTransport = previous + transport.CloseIdleConnections() + }) + dir := t.TempDir() + cfg := &config.Config{ + AuthDir: filepath.Join(dir, "auths"), + QuotaHistory: config.QuotaHistoryConfig{Enabled: true, Providers: []string{"mistral"}}, + OpenAICompatibility: []config.OpenAICompatibility{ + {Name: "Campus account", BaseURL: "https://api.mistral.ai/v1", APIKeyEntries: []config.OpenAICompatibilityAPIKey{{APIKey: "fixture-mistral-key"}}}, + {Name: "mistral", BaseURL: "https://other.example/v1", APIKeyEntries: []config.OpenAICompatibilityAPIKey{{APIKey: "fixture-other-key"}}}, + }, + } + auths, err := synthesizer.NewConfigSynthesizer().Synthesize(&synthesizer.SynthesisContext{Config: cfg, Now: time.Now(), IDGenerator: synthesizer.NewStableIDGenerator()}) + if err != nil { + t.Fatal(err) + } + manager := coreauth.NewManager(nil, nil, nil) + for _, auth := range auths { + if _, errRegister := manager.Register(context.Background(), auth); errRegister != nil { + t.Fatal(errRegister) + } + } + h := NewHandler(cfg, filepath.Join(dir, "config.yaml"), manager) + h.ApplyQuotaHistoryConfig(cfg) + t.Cleanup(h.CloseQuotaHistory) + gin.SetMode(gin.TestMode) + router := gin.New() + router.GET("/v8/management/quota-history", h.GetQuotaHistory) + router.POST("/v8/management/quota-history/refresh", h.RefreshQuotaHistory) + router.GET("/v0/management/auth-files", h.ListAuthFiles) + request := func(method, path string) ojson.Result { + t.Helper() + response := httptest.NewRecorder() + router.ServeHTTP(response, httptest.NewRequest(method, path, nil)) + if response.Code != http.StatusOK || !ojson.ValidBytes(response.Body.Bytes()) { + t.Fatalf("%s %s = %d %s", method, path, response.Code, response.Body.String()) + } + if strings.Contains(response.Body.String(), "fixture-") { + t.Fatal("history response leaked an API key") + } + return ojson.Parse(response.Body.String()) + } + if files := request("GET", "/v0/management/auth-files").Get("files"); !files.IsArray() || len(files.Array()) != 0 { + t.Fatal("API-key upstreams must stay out of auth-files") + } + if refresh := request("POST", "/v8/management/quota-history/refresh"); refresh.Get("samples").Int() != 1 || !refresh.Get("done").Bool() { + t.Fatalf("refresh = %s", refresh.Raw) + } + history := request("GET", "/v8/management/quota-history") + if len(history.Get("accounts").Array()) != 1 || len(history.Get("samples").Array()) != 1 { + t.Fatalf("history = %s", history.Raw) + } + account, sample := history.Get("accounts.0"), history.Get("samples.0") + if account.Get("provider").String() != "mistral" || account.Get("label").String() != "Campus account" || account.Get("plan").String() != "EDU" || account.Get("weight").Float() != 1 || account.Get("auth_index").String() == "" || account.Get("auth_index").String() != sample.Get("auth_index").String() { + t.Fatalf("account = %s", account.Raw) + } + now := time.UnixMilli(sample.Get("t").Int()).UTC() + start := time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, time.UTC) + hours := start.AddDate(0, 1, 0).Sub(start).Hours() + for _, tc := range []struct { + id, label string + budget, used float64 + }{ + {"api_monthly", "API usage", 15, 2.59892596}, + {"vibe_monthly", "Vibe Code", 150, 0}, + } { + window := sample.Get("windows." + tc.id) + if window.Get("budget").Float() != tc.budget || window.Get("currency").String() != "USD" || window.Get("used_percent").Float() != tc.used || window.Get("label").String() != tc.label || window.Get("period_hours").Float() != hours || window.Get("resets_at").Int() != 1796083200000 { + t.Errorf("window = %s", window.Raw) + } + } + t.Logf("history account %s", account.Raw) + t.Logf("history sample %s", sample.Raw) + if files := request("GET", "/v0/management/auth-files").Get("files"); len(files.Array()) != 0 { + t.Fatal("polling exposed API-key upstreams in auth-files") + } +} + +func TestQuotaHistoryAPIKeyUsesAccountProxy(t *testing.T) { + proxy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + if req.URL.String() != "http://api.mistral.ai/v1/billing/budget" || req.Header.Get("Authorization") != "Bearer fixture-proxy-key" { + t.Error("proxy did not receive the authenticated billing request") + w.WriteHeader(http.StatusBadRequest) + return + } + _, _ = w.Write([]byte(`{}`)) + })) + t.Cleanup(proxy.Close) + h := NewHandler(&config.Config{SDKConfig: config.SDKConfig{ProxyURL: "http://127.0.0.1:1"}}, "", nil) + auth := &coreauth.Auth{ID: t.Name(), Provider: "openai-compatible-campus", ProxyURL: proxy.URL, Attributes: map[string]string{"api_key": "fixture-proxy-key"}} + status, _, err := h.quotaHistoryRequest(context.Background(), auth, "GET", "http://api.mistral.ai/v1/billing/budget", map[string]string{"Authorization": "Bearer $TOKEN$"}, nil) + if err != nil || status != http.StatusOK { + t.Fatalf("request through account proxy = %d, %v", status, err) + } +} diff --git a/internal/api/handlers/management/quota_history_test.go b/internal/api/handlers/management/quota_history_test.go index 9507ca84cdd..611539411ee 100644 --- a/internal/api/handlers/management/quota_history_test.go +++ b/internal/api/handlers/management/quota_history_test.go @@ -122,6 +122,12 @@ func TestQuotaHistoryEndpoints(t *testing.T) { } sample := samples[0].(map[string]any) window := sample["windows"].(map[string]any)["five_hour"].(map[string]any) + if _, exists := window["budget"]; exists { + t.Fatalf("legacy window gained a budget: %v", window) + } + if _, exists := window["currency"]; exists { + t.Fatalf("legacy window gained a currency: %v", window) + } if sample["auth_index"] != "idx-1" || sample["error"] != "" || window["used_percent"] != 12.5 || window["resets_at"] != 1731610000000.0 || window["period_hours"] != 5.0 { t.Fatalf("sample = %v", sample) } diff --git a/internal/api/handlers/management/quota_history_transport_test.go b/internal/api/handlers/management/quota_history_transport_test.go new file mode 100644 index 00000000000..c95937487ec --- /dev/null +++ b/internal/api/handlers/management/quota_history_transport_test.go @@ -0,0 +1,133 @@ +package management + +import ( + "bufio" + "context" + "fmt" + "io" + "net" + "net/http" + "strings" + "testing" + "time" + + "github.com/MoeForge/moego/ojson" + "github.com/rune-oai/t3code-proxy/internal/config" + "github.com/rune-oai/t3code-proxy/internal/pluginhost" + coreauth "github.com/rune-oai/t3code-proxy/sdk/cliproxy/auth" + "github.com/rune-oai/t3code-proxy/sdk/pluginapi" +) + +func TestQuotaHistoryPostTransport(t *testing.T) { + // net.Pipe exercises the HTTP transport without opening a network socket. + type captured struct { + authorization, body string + err error + } + received := make(chan captured, 1) + transport := &http.Transport{DialContext: func(context.Context, string, string) (net.Conn, error) { + client, server := net.Pipe() + go func() { + defer func() { + if err := server.Close(); err != nil { + t.Errorf("close pipe: %v", err) + } + }() + req, err := http.ReadRequest(bufio.NewReader(server)) + if err != nil { + received <- captured{err: err} + return + } + body, errRead := io.ReadAll(req.Body) + if errClose := req.Body.Close(); errClose != nil { + t.Errorf("close request: %v", errClose) + } + received <- captured{authorization: req.Header.Get("Authorization"), body: string(body), err: errRead} + if _, errWrite := fmt.Fprint(server, "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\n{}"); errWrite != nil { + t.Errorf("write response: %v", errWrite) + } + }() + return client, nil + }} + previous := http.DefaultTransport + http.DefaultTransport = transport + t.Cleanup(func() { http.DefaultTransport = previous; transport.CloseIdleConnections() }) + handler := NewHandler(&config.Config{}, "", nil) + for _, tc := range []struct{ provider, token, authorization, body string }{ + {"devin", "fixture-\"-\\-token", "", `{"metadata":{"apiKey":"$TOKEN$"}}`}, + {"meta", "", "Bearer dca:fixture", `{}`}, + } { + t.Run(tc.provider, func(t *testing.T) { + auth := &coreauth.Auth{ID: tc.provider, Provider: tc.provider, Metadata: map[string]any{"session_token": tc.token}} + headers := map[string]string{"Content-Type": "application/json"} + if tc.authorization != "" { + headers["Authorization"] = tc.authorization + } + status, _, err := handler.quotaHistoryRequest(context.Background(), auth, http.MethodPost, "http://quota.invalid/usage", headers, []byte(tc.body)) + if err != nil || status != 200 { + t.Fatalf("request = %d %v", status, err) + } + got := <-received + if got.err != nil { + t.Fatal(got.err) + } + if got.authorization != tc.authorization { + t.Fatalf("authorization = %q", got.authorization) + } + if tc.provider == "devin" && ojson.Get(got.body, "metadata.apiKey").String() != tc.token { + t.Fatalf("invalid JSON token substitution %q", got.body) + } + if strings.Contains(got.body, "$TOKEN$") { + t.Fatal("unresolved token placeholder") + } + }) + } +} + +func TestQuotaHistoryPluginUsesHostCapability(t *testing.T) { + host := pluginhost.New() + host.RegisterPluginForTest("fixture-plugin", pluginapi.Plugin{Capabilities: pluginapi.Capabilities{QuotaProvider: &mockQuotaProvider{ + identifier: "fixture-provider", + fetchFn: func(_ context.Context, req pluginapi.QuotaFetchRequest) (pluginapi.QuotaFetchResponse, error) { + if req.AuthID != "fixture-auth" || req.AuthIndex != "fixture-index" || req.Metadata["token"] != "fixture-token" || req.HTTPClient == nil { + t.Fatalf("missing account context or host HTTP client") + } + return pluginapi.QuotaFetchResponse{Subscription: &pluginapi.QuotaSubscription{Plan: "fixture-plan"}, Groups: []pluginapi.QuotaGroup{{DisplayName: "Account", Buckets: []pluginapi.QuotaBucket{{Window: "weekly", RemainingFraction: 0.25, ResetTime: "2026-11-20T00:00:00Z"}}}}}, nil + }, + }}}) + handler := NewHandler(&config.Config{}, "", nil) + handler.SetPluginHost(host) + if got := handler.quotaHistoryPluginProviders(context.Background())["fixture-provider"]; got != "fixture-plugin" { + t.Fatalf("quota plugin = %q", got) + } + body, err := handler.quotaHistoryPlugin(context.Background(), &coreauth.Auth{ID: "fixture-auth", Index: "fixture-index", Provider: "fixture-provider", Metadata: map[string]any{"token": "fixture-token"}}) + if err != nil { + t.Fatal(err) + } + root := ojson.ParseBytes(body) + if root.Get("subscription.plan").String() != "fixture-plan" || root.Get("groups.0.buckets.0.remainingFraction").Float() != 0.25 { + t.Fatalf("quota = %s", body) + } +} + +// A usage read never starts its own OAuth refresh: an account whose token is +// due is reported and left to the hub's refresh loop. +func TestQuotaHistoryRequestLeavesTokenRefreshToTheHub(t *testing.T) { + expired := time.Now().Add(-time.Hour).UTC().Format(time.RFC3339) + fresh := time.Now().Add(6 * time.Hour).UTC().Format(time.RFC3339) + due := &coreauth.Auth{ID: "agy-due", Provider: "antigravity", Metadata: map[string]any{"access_token": "old", "refresh_token": "r", "expired": expired}} + if !quotaHistoryTokenRefreshDue(due) { + t.Fatal("an expired Antigravity token must be reported as due") + } + ok := &coreauth.Auth{ID: "agy-ok", Provider: "antigravity", Metadata: map[string]any{"access_token": "new", "refresh_token": "r", "expired": fresh}} + if quotaHistoryTokenRefreshDue(ok) { + t.Fatal("a fresh Antigravity token must not be reported as due") + } + if quotaHistoryTokenRefreshDue(&coreauth.Auth{ID: "claude", Provider: "claude", Metadata: map[string]any{"access_token": "x"}}) { + t.Fatal("providers that do not refresh on this path are never due") + } + handler := &Handler{} + if _, _, err := handler.quotaHistoryRequest(context.Background(), due, "GET", "http://127.0.0.1:1/unreachable", map[string]string{"Authorization": "Bearer $TOKEN$"}, nil); err == nil || err.Error() != "token refresh due" { + t.Fatalf("err = %v, want token refresh due without any request", err) + } +} diff --git a/internal/api/handlers/management/routing_plan_weights.go b/internal/api/handlers/management/routing_plan_weights.go new file mode 100644 index 00000000000..bdc99d899a6 --- /dev/null +++ b/internal/api/handlers/management/routing_plan_weights.go @@ -0,0 +1,34 @@ +package management + +import ( + "net/http" + + "github.com/gin-gonic/gin" + coreauth "github.com/rune-oai/t3code-proxy/sdk/cliproxy/auth" +) + +// GetRoutingPlanWeights returns the plan capacity weights used by routing. +// +// GET /v8/management/routing/plan-weights +// +// The response is {"defaults": {...}, "configured": {...}, "effective": {...}}, +// each keyed by provider and then plan. "configured" is routing.plan-weights +// with normalized keys; "effective" is the defaults with it applied. Writes go +// through /v8/management/config/routing/plan-weights. +func (h *Handler) GetRoutingPlanWeights(c *gin.Context) { + h.mu.Lock() + var configured map[string]map[string]float64 + if h.cfg != nil { + configured = coreauth.NormalizePlanWeights(h.cfg.Routing.PlanWeights) + } + h.mu.Unlock() + if configured == nil { + configured = map[string]map[string]float64{} + } + c.Header("Cache-Control", "no-store") + c.JSON(http.StatusOK, gin.H{ + "defaults": coreauth.DefaultPlanWeights(), + "configured": configured, + "effective": coreauth.EffectivePlanWeights(configured), + }) +} diff --git a/internal/api/handlers/management/routing_plan_weights_test.go b/internal/api/handlers/management/routing_plan_weights_test.go new file mode 100644 index 00000000000..a0a832eb103 --- /dev/null +++ b/internal/api/handlers/management/routing_plan_weights_test.go @@ -0,0 +1,108 @@ +package management + +import ( + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "reflect" + "strings" + "testing" + + "github.com/MoeForge/moego/ojson" + "github.com/gin-gonic/gin" + "github.com/rune-oai/t3code-proxy/internal/config" + coreauth "github.com/rune-oai/t3code-proxy/sdk/cliproxy/auth" +) + +func TestRoutingPlanWeightsEndpoint(t *testing.T) { + gin.SetMode(gin.TestMode) + path := filepath.Join(t.TempDir(), "config.yaml") + if errWrite := os.WriteFile(path, []byte("routing:\n strategy: soonest-reset-first\n"), 0o600); errWrite != nil { + t.Fatalf("write: %v", errWrite) + } + cfg, errLoad := config.LoadConfig(path) + if errLoad != nil { + t.Fatalf("load: %v", errLoad) + } + h := &Handler{cfg: cfg, configFilePath: path} + router := gin.New() + router.GET("/v8/management/routing/plan-weights", h.GetRoutingPlanWeights) + router.PUT("/v8/management/config/*path", h.ConfigV8) + router.PATCH("/v8/management/config/*path", h.ConfigV8) + + request := func(method, url, body string, wantStatus int) []byte { + t.Helper() + recorder := httptest.NewRecorder() + router.ServeHTTP(recorder, httptest.NewRequest(method, url, strings.NewReader(body))) + if recorder.Code != wantStatus { + t.Fatalf("%s %s: status=%d body=%s", method, url, recorder.Code, recorder.Body.String()) + } + return recorder.Body.Bytes() + } + type tables struct { + Defaults map[string]map[string]float64 `json:"defaults"` + Configured map[string]map[string]float64 `json:"configured"` + Effective map[string]map[string]float64 `json:"effective"` + } + get := func() tables { + t.Helper() + raw := request(http.MethodGet, "/v8/management/routing/plan-weights", "", http.StatusOK) + root := ojson.ParseBytes(raw) + if !root.IsObject() || len(root.Map()) != 3 { + t.Fatalf("response %s: want exactly defaults, configured, effective", raw) + } + table := func(name string) map[string]map[string]float64 { + out := make(map[string]map[string]float64) + for provider, plans := range root.Get(name).Map() { + out[provider] = make(map[string]float64) + for plan, weight := range plans.Map() { + out[provider][plan] = weight.Float() + } + } + return out + } + if !root.Get("defaults").IsObject() || !root.Get("configured").IsObject() || !root.Get("effective").IsObject() { + t.Fatalf("response %s: missing a weight table", raw) + } + out := tables{Defaults: table("defaults"), Configured: table("configured"), Effective: table("effective")} + return out + } + + initial := get() + if !reflect.DeepEqual(initial.Defaults, coreauth.DefaultPlanWeights()) || initial.Defaults["claude"]["max_20x"] != 20 { + t.Fatalf("defaults = %v", initial.Defaults) + } + if initial.Configured == nil || len(initial.Configured) != 0 { + t.Fatalf("configured = %v, want {}", initial.Configured) + } + if !reflect.DeepEqual(initial.Effective, initial.Defaults) { + t.Fatalf("effective = %v, want defaults", initial.Effective) + } + + // Writes go through the generic config endpoint. + request(http.MethodPut, "/v8/management/config/routing/plan-weights", `{"codex":{"Pro":10},"kimi":{"premium":3}}`, http.StatusOK) + updated := get() + if updated.Configured["codex"]["pro"] != 10 || updated.Configured["kimi"]["premium"] != 3 { + t.Fatalf("configured = %v", updated.Configured) + } + if updated.Effective["codex"]["pro"] != 10 || updated.Effective["codex"]["plus"] != 1 || updated.Effective["kimi"]["premium"] != 3 { + t.Fatalf("effective = %v", updated.Effective) + } + if updated.Defaults["codex"]["pro"] != 20 { + t.Fatalf("defaults changed: %v", updated.Defaults) + } + request(http.MethodPut, "/v8/management/config/routing/plan-headroom-reserve", `5`, http.StatusOK) + if got := h.cfg.Routing.EffectivePlanHeadroomReserve(); got != 5 { + t.Fatalf("reserve = %v, want 5", got) + } + + // Invalid values are rejected and leave the file unchanged. + before, _ := os.ReadFile(path) + request(http.MethodPut, "/v8/management/config/routing/plan-weights", `{"codex":{"pro":0}}`, http.StatusUnprocessableEntity) + request(http.MethodPut, "/v8/management/config/routing/plan-headroom-reserve", `-1`, http.StatusUnprocessableEntity) + after, _ := os.ReadFile(path) + if string(before) != string(after) { + t.Fatal("rejected write changed the config file") + } +} diff --git a/internal/api/server_management_v8.go b/internal/api/server_management_v8.go index f04d1700812..bbd46abe7fc 100644 --- a/internal/api/server_management_v8.go +++ b/internal/api/server_management_v8.go @@ -30,6 +30,7 @@ func (s *Server) registerManagementV8Routes() { v8.GET("/server/latest-version", s.mgmt.GetLatestVersion) v8.POST("/requests/api-call", s.mgmt.APICall) v8.POST("/routing/cooldown/reset", s.mgmt.ResetQuota) + v8.GET("/routing/plan-weights", s.mgmt.GetRoutingPlanWeights) v8.GET("/routing/model-definitions/:channel", s.mgmt.GetStaticModelDefinitions) v8.POST("/routing/model-definitions/refresh", s.mgmt.RefreshModelDefinitions) v8.POST("/models/refresh", s.mgmt.RefreshModelDefinitions) diff --git a/internal/api/server_management_v8_test.go b/internal/api/server_management_v8_test.go index 79e5dae1721..b92e4b8b7c1 100644 --- a/internal/api/server_management_v8_test.go +++ b/internal/api/server_management_v8_test.go @@ -94,6 +94,7 @@ func TestManagementV8IndependentContract(t *testing.T) { "GET /v8/management/credentials", "POST /v8/management/credentials", "POST /v8/management/credentials/verify", "GET /v8/management/oauth/auth-url", "POST /v8/management/oauth/auth-url", "POST /v8/management/oauth/import", "POST /v8/management/oauth/callback", "POST /v8/management/routing/cooldown/reset", + "GET /v8/management/routing/plan-weights", "POST /v8/management/routing/model-definitions/refresh", "POST /v8/management/models/refresh", "GET /v8/management/plugins/:id/quota", "POST /v8/management/plugins/:id/quota", "DELETE /v8/management/plugins/:id/quota", diff --git a/internal/config/config_load.go b/internal/config/config_load.go index f3e9be37a44..7a6889006b5 100644 --- a/internal/config/config_load.go +++ b/internal/config/config_load.go @@ -238,6 +238,9 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) { if errValidate := cfg.ValidateCredentialWeights(); errValidate != nil { return nil, errValidate } + if errValidate := cfg.ValidatePlanRouting(); errValidate != nil { + return nil, errValidate + } // Hash remote management key if plaintext is detected (nested) // We consider a value to be already hashed if it looks like a bcrypt hash ($2a$, $2b$, or $2y$ prefix). diff --git a/internal/config/config_types.go b/internal/config/config_types.go index 849f36b569d..71e842e2ab7 100644 --- a/internal/config/config_types.go +++ b/internal/config/config_types.go @@ -602,6 +602,18 @@ type RoutingConfig struct { // keep the binding and return the error (or retry the same credential) instead. // Ignored when SessionAffinity is false. SessionAffinityRebindOn string `yaml:"session-affinity-rebind-on,omitempty" json:"session-affinity-rebind-on,omitempty"` + + // PlanWeights overrides the built-in plan capacity weights, keyed by provider and then + // by plan (for example claude: {max_20x: 20}). A weight is capacity relative to the + // provider's base paid plan (1.0). Entries replace the matching built-in value; plans + // not listed keep their built-in weight. See docs/routing.md. + PlanWeights map[string]map[string]float64 `yaml:"plan-weights,omitempty" json:"plan-weights,omitempty"` + + // PlanHeadroomReserve is the plan-weighted short-window (5-hour) headroom, in base-plan + // percent, below which soonest-reset-first does not start a new conversation on an + // account while another eligible account has more. Headroom is weight x remaining + // percent. Omitted means DefaultPlanHeadroomReserve; 0 disables the guard. + PlanHeadroomReserve *float64 `yaml:"plan-headroom-reserve,omitempty" json:"plan-headroom-reserve,omitempty"` } // OAuthModelAlias defines a model ID alias for a specific channel. diff --git a/internal/config/parse.go b/internal/config/parse.go index 9e0feba0c74..c20f2dd17a9 100644 --- a/internal/config/parse.go +++ b/internal/config/parse.go @@ -54,6 +54,9 @@ func ParseConfigBytes(data []byte) (*Config, error) { if errValidate := cfg.ValidateCredentialWeights(); errValidate != nil { return nil, errValidate } + if errValidate := cfg.ValidatePlanRouting(); errValidate != nil { + return nil, errValidate + } if errValidate := cfg.Codex.LiveMediaRelay.Validate(); errValidate != nil { return nil, errValidate } diff --git a/internal/config/plan_weights.go b/internal/config/plan_weights.go new file mode 100644 index 00000000000..1b06269dc13 --- /dev/null +++ b/internal/config/plan_weights.go @@ -0,0 +1,77 @@ +package config + +import ( + "fmt" + "math" + "strings" +) + +const ( + // DefaultPlanHeadroomReserve is the routing.plan-headroom-reserve used when the key is + // omitted: a Pro account (weight 1) counts as tight below 10% of its 5-hour window left, + // a Max 20x account (weight 20) below 0.5%. + DefaultPlanHeadroomReserve = 10.0 + // MaxPlanWeight bounds routing.plan-weights values. + MaxPlanWeight = 1000.0 + // MaxPlanHeadroomReserve bounds routing.plan-headroom-reserve. + MaxPlanHeadroomReserve = 1000.0 +) + +// NormalizePlanKey returns the canonical form of a provider or plan name used by +// routing.plan-weights: lower case, trimmed, with spaces and hyphens folded to +// underscores ("Max 20x" and "max-20x" both become "max_20x"). +func NormalizePlanKey(name string) string { + name = strings.ToLower(strings.TrimSpace(name)) + name = strings.NewReplacer(" ", "_", "-", "_").Replace(name) + for strings.Contains(name, "__") { + name = strings.ReplaceAll(name, "__", "_") + } + return strings.Trim(name, "_") +} + +// EffectivePlanHeadroomReserve returns routing.plan-headroom-reserve, or the default +// when it is omitted. +func (r RoutingConfig) EffectivePlanHeadroomReserve() float64 { + if r.PlanHeadroomReserve == nil { + return DefaultPlanHeadroomReserve + } + return *r.PlanHeadroomReserve +} + +// ValidatePlanRouting validates routing.plan-weights and routing.plan-headroom-reserve. +func (cfg *Config) ValidatePlanRouting() error { + if cfg == nil { + return nil + } + seenProviders := make(map[string]string, len(cfg.Routing.PlanWeights)) + for provider, plans := range cfg.Routing.PlanWeights { + normalizedProvider := NormalizePlanKey(provider) + if normalizedProvider == "" { + return fmt.Errorf("routing.plan-weights: provider name must not be empty") + } + if previous, dup := seenProviders[normalizedProvider]; dup { + return fmt.Errorf("routing.plan-weights: providers %q and %q are the same provider", previous, provider) + } + seenProviders[normalizedProvider] = provider + seenPlans := make(map[string]string, len(plans)) + for plan, weight := range plans { + normalizedPlan := NormalizePlanKey(plan) + if normalizedPlan == "" { + return fmt.Errorf("routing.plan-weights.%s: plan name must not be empty", provider) + } + if previous, dup := seenPlans[normalizedPlan]; dup { + return fmt.Errorf("routing.plan-weights.%s: plans %q and %q are the same plan", provider, previous, plan) + } + seenPlans[normalizedPlan] = plan + if math.IsNaN(weight) || math.IsInf(weight, 0) || weight <= 0 || weight > MaxPlanWeight { + return fmt.Errorf("routing.plan-weights.%s.%s: weight must be greater than 0 and at most %g", provider, plan, MaxPlanWeight) + } + } + } + if reserve := cfg.Routing.PlanHeadroomReserve; reserve != nil { + if math.IsNaN(*reserve) || math.IsInf(*reserve, 0) || *reserve < 0 || *reserve > MaxPlanHeadroomReserve { + return fmt.Errorf("routing.plan-headroom-reserve: must be between 0 and %g", MaxPlanHeadroomReserve) + } + } + return nil +} diff --git a/internal/config/plan_weights_test.go b/internal/config/plan_weights_test.go new file mode 100644 index 00000000000..be1402aeec8 --- /dev/null +++ b/internal/config/plan_weights_test.go @@ -0,0 +1,69 @@ +package config + +import ( + "math" + "strings" + "testing" +) + +func TestValidatePlanRouting(t *testing.T) { + tests := []struct { + name string + routing RoutingConfig + wantErr string + }{ + {name: "empty"}, + {name: "valid", routing: RoutingConfig{ + PlanWeights: map[string]map[string]float64{"claude": {"max_20x": 20, "pro": 1}, "codex": {"pro": 0.5}}, + PlanHeadroomReserve: new(0.0), + }}, + {name: "zero weight", routing: RoutingConfig{PlanWeights: map[string]map[string]float64{"codex": {"pro": 0}}}, wantErr: "weight must be greater than 0"}, + {name: "negative weight", routing: RoutingConfig{PlanWeights: map[string]map[string]float64{"codex": {"pro": -1}}}, wantErr: "weight must be greater than 0"}, + {name: "too large", routing: RoutingConfig{PlanWeights: map[string]map[string]float64{"codex": {"pro": MaxPlanWeight + 1}}}, wantErr: "at most"}, + {name: "infinite", routing: RoutingConfig{PlanWeights: map[string]map[string]float64{"codex": {"pro": math.Inf(1)}}}, wantErr: "weight must be"}, + {name: "nan", routing: RoutingConfig{PlanWeights: map[string]map[string]float64{"codex": {"pro": math.NaN()}}}, wantErr: "weight must be"}, + {name: "empty plan", routing: RoutingConfig{PlanWeights: map[string]map[string]float64{"codex": {" ": 2}}}, wantErr: "plan name must not be empty"}, + {name: "empty provider", routing: RoutingConfig{PlanWeights: map[string]map[string]float64{"": {"pro": 2}}}, wantErr: "provider name must not be empty"}, + {name: "duplicate plan", routing: RoutingConfig{PlanWeights: map[string]map[string]float64{"claude": {"Max 20x": 20, "max-20x": 15}}}, wantErr: "same plan"}, + {name: "negative reserve", routing: RoutingConfig{PlanHeadroomReserve: new(-1.0)}, wantErr: "plan-headroom-reserve"}, + {name: "reserve too large", routing: RoutingConfig{PlanHeadroomReserve: new(MaxPlanHeadroomReserve + 1)}, wantErr: "plan-headroom-reserve"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := (&Config{Routing: tt.routing}).ValidatePlanRouting() + if tt.wantErr == "" { + if err != nil { + t.Fatalf("ValidatePlanRouting() = %v", err) + } + return + } + if err == nil || !strings.Contains(err.Error(), tt.wantErr) { + t.Fatalf("ValidatePlanRouting() = %v, want error containing %q", err, tt.wantErr) + } + }) + } +} + +func TestParsePlanRouting(t *testing.T) { + cfg, err := ParseConfigBytes([]byte("routing:\n strategy: soonest-reset-first\n plan-weights:\n codex:\n pro: 8\n plan-headroom-reserve: 5\n")) + if err != nil { + t.Fatalf("ParseConfigBytes() = %v", err) + } + if cfg.Routing.PlanWeights["codex"]["pro"] != 8 || cfg.Routing.EffectivePlanHeadroomReserve() != 5 { + t.Fatalf("routing = %+v", cfg.Routing) + } + if cfg, err = ParseConfigBytes([]byte("routing:\n strategy: soonest-reset-first\n")); err != nil || cfg.Routing.EffectivePlanHeadroomReserve() != DefaultPlanHeadroomReserve { + t.Fatalf("default reserve: %v, %v", cfg, err) + } + if _, err = ParseConfigBytes([]byte("routing:\n plan-weights:\n codex:\n pro: 0\n")); err == nil { + t.Fatal("ParseConfigBytes accepted a zero plan weight") + } +} + +func TestNormalizePlanKey(t *testing.T) { + for raw, want := range map[string]string{" Max 20x ": "max_20x", "max-5x": "max_5x", "PRO": "pro", "a -b": "a_b", "_": ""} { + if got := NormalizePlanKey(raw); got != want { + t.Fatalf("NormalizePlanKey(%q) = %q, want %q", raw, got, want) + } + } +} diff --git a/internal/config/quota_history.go b/internal/config/quota_history.go index 4a6b479db52..90b4c31a66b 100644 --- a/internal/config/quota_history.go +++ b/internal/config/quota_history.go @@ -1,10 +1,12 @@ package config // QuotaHistoryConfig configures the background recorder that samples the quota -// of Claude and Codex OAuth credentials (t3code fork addition). +// of subscription credentials (t3code fork addition). type QuotaHistoryConfig struct { // Enabled turns the recorder on. Default false: nothing is polled or stored. Enabled bool `yaml:"enabled" json:"enabled"` + // Providers restricts polling to these provider IDs. Empty enables every supported provider. + Providers []string `yaml:"providers,omitempty" json:"providers,omitempty"` // Interval is the poll interval, e.g. "10m". Values below 5m are clamped. Interval string `yaml:"interval,omitempty" json:"interval,omitempty"` // Retention bounds how long samples are kept, e.g. "35d" or "840h". diff --git a/internal/config/quota_history_test.go b/internal/config/quota_history_test.go index d5b1a939688..a1ae45b51f4 100644 --- a/internal/config/quota_history_test.go +++ b/internal/config/quota_history_test.go @@ -3,12 +3,13 @@ package config import ( "os" "path/filepath" + "reflect" "strings" "testing" ) func TestQuotaHistorySectionLoads(t *testing.T) { - data := []byte("config-version: 8\nquota-history:\n enabled: true\n interval: 15m\n retention: 30d\n path: qh.db\n") + data := []byte("config-version: 8\nquota-history:\n enabled: true\n interval: 15m\n retention: 30d\n path: qh.db\n providers: [claude, kimi]\n") if errValidate := ValidateV8Config(data); errValidate != nil { t.Fatalf("quota-history must be a valid v8 section: %v", errValidate) } @@ -20,8 +21,8 @@ func TestQuotaHistorySectionLoads(t *testing.T) { if errLoad != nil { t.Fatal(errLoad) } - want := QuotaHistoryConfig{Enabled: true, Interval: "15m", Retention: "30d", Path: "qh.db"} - if cfg.QuotaHistory != want { + want := QuotaHistoryConfig{Enabled: true, Interval: "15m", Retention: "30d", Path: "qh.db", Providers: []string{"claude", "kimi"}} + if !reflect.DeepEqual(cfg.QuotaHistory, want) { t.Fatalf("QuotaHistory = %+v, want %+v", cfg.QuotaHistory, want) } after, errRead := os.ReadFile(path) diff --git a/internal/doctor/config_check.go b/internal/doctor/config_check.go new file mode 100644 index 00000000000..db332e84223 --- /dev/null +++ b/internal/doctor/config_check.go @@ -0,0 +1,247 @@ +package doctor + +import ( + "context" + "fmt" + "io" + "net/http" + "net/url" + "os" + "path/filepath" + "regexp" + "strconv" + "strings" + + "github.com/MoeForge/moego/ojson" + "github.com/joho/godotenv" + "github.com/rune-oai/t3code-proxy/internal/config" + "github.com/rune-oai/t3code-proxy/internal/util" + log "github.com/sirupsen/logrus" + "gopkg.in/yaml.v3" +) + +// Config checking uses the production loader on a disposable copy because that +// loader hashes management secrets and cleans conflicting fields on disk. +// No credential store, server, watcher, or catalog updater is constructed. +func checkConfigCommand(ctx context.Context, path, probeURL, keyFile string, out io.Writer) bool { + doc := ojson.NewDocString(`{"ok":false,"issues":[],"unknown_keys":[],"probe":null}`) + fail := func(reason string) bool { + _ = doc.Set("reason", reason) + _, _ = fmt.Fprintln(out, doc.String()) + return false + } + if path == "" { + path = "config.yaml" + } + data, errRead := os.ReadFile(path) + if errRead != nil { + return fail("cannot read config file") + } + // Suppress production sanitizer logs, which can include user-controlled values. + previousOutput := log.StandardLogger().Out + log.SetOutput(io.Discard) + defer log.SetOutput(previousOutput) + env, errEnv := godotenv.Read(".env") + if errEnv != nil && !os.IsNotExist(errEnv) { + return fail("cannot parse working-directory .env") + } + lookup := func(key string) string { + if value, exists := os.LookupEnv(key); exists { + return value + } + return env[key] + } + for _, key := range []string{"HOME_JWT", "home_jwt", "PGSTORE_DSN", "pgstore_dsn", "GITSTORE_GIT_URL", "gitstore_git_url", "OBJECTSTORE_ENDPOINT", "objectstore_endpoint"} { + if strings.TrimSpace(lookup(key)) != "" { + return fail("config check requires local file storage without Home or cloud deployment") + } + } + if lookup("DEPLOY") == "cloud" { + return fail("config check requires local file storage without Home or cloud deployment") + } + var raw config.Config + if errParse := yaml.Unmarshal(data, &raw); errParse != nil { + _ = doc.Set("issues", configDiagnostics(errParse)) + return fail("incompatible config or invalid YAML (values redacted)") + } + tmp, errTemp := os.MkdirTemp("", "t3code-config-check-") + if errTemp != nil { + return fail("cannot create private temporary config copy") + } + defer func() { + if errRemove := os.RemoveAll(tmp); errRemove != nil { + log.Warn("could not remove temporary config check directory") + } + }() + copyPath := filepath.Join(tmp, "config.yaml") + if errWrite := os.WriteFile(copyPath, data, 0600); errWrite != nil { + return fail("cannot write private temporary config copy") + } + cfg, errLoad := config.LoadConfig(copyPath) + if errRemove := os.RemoveAll(tmp); errRemove != nil { + return fail("cannot remove private temporary config copy") + } + if errLoad != nil { + _ = doc.Set("issues", configDiagnostics(errLoad)) + return fail("server config loader rejected config (values redacted)") + } + unknown := []string{} + config.SetV8MigrationWarnFunc(func(section, _ string) { unknown = append(unknown, section) }) + normalized, _, errNormalize := config.NormalizeConfigLayout(data, true) + config.SetV8MigrationWarnFunc(nil) + _ = doc.Set("unknown_keys", unknown) + if errNormalize != nil { + return fail("cannot inspect config layout (values redacted)") + } + // Strict validation also examines fields inside provider/key sequences. + if errStrict := config.ValidateV8Config(normalized); errStrict != nil { + _ = doc.Set("issues", configDiagnostics(errStrict)) + } + authDir, errAuth := util.ResolveAuthDir(cfg.AuthDir) + if errAuth != nil { + return fail("cannot resolve auth directory") + } + authDir, errAuth = filepath.Abs(authDir) + if errAuth != nil { + return fail("cannot resolve auth directory") + } + _ = doc.Set("settings.port", cfg.Port) + _ = doc.Set("settings.host", cfg.Host) + _ = doc.Set("settings.tls", cfg.TLS.Enable) + _ = doc.Set("settings.auth_dir", authDir) + _ = doc.Set("settings.access_key_count", len(cfg.APIKeys)) + _ = doc.Set("settings.config_sha256", config.ComputeSourceHash(data)) + paths := []string{authDir} + for _, source := range []string{cfg.Models.Catalog, cfg.Models.CodexCatalog, cfg.Models.DevinCatalog, cfg.TLS.Cert, cfg.TLS.Key} { + if source == "" { + continue + } + parsed, errURL := url.Parse(source) + if errURL == nil && (parsed.Scheme == "http" || parsed.Scheme == "https") { + continue + } + paths = append(paths, source) + } + if cfg.Plugins.Enabled { + paths = append(paths, cfg.Plugins.Dir) + } + _ = doc.Set("settings.required_paths", paths) + if probeURL != "" { + parsed, errURL := url.Parse(probeURL) + if errURL != nil || parsed.Scheme != "http" || (parsed.Hostname() != "127.0.0.1" && parsed.Hostname() != "localhost" && parsed.Hostname() != "::1") || parsed.User != nil { + return fail("probe URL must be loopback HTTP") + } + secret := raw.RemoteManagement.SecretKey + if keyFile != "" { + key, errKey := os.ReadFile(keyFile) + if errKey != nil { + return fail("cannot read management key file") + } + secret = strings.TrimSpace(string(key)) + } else if value := lookup("MANAGEMENT_PASSWORD"); value != "" { + secret = value + } + if secret == "" || strings.HasPrefix(secret, "$2") { + return fail("management plaintext unavailable; supply -management-key-file") + } + if len(cfg.APIKeys) == 0 { + return fail("config has no access API key") + } + probe := probeHub(ctx, strings.TrimRight(probeURL, "/"), cfg.APIKeys[0], secret, authDir, http.DefaultClient) + _ = doc.Set("probe", probe) + if !probe.Models || probe.Accounts < 0 { + return fail("authenticated hub probe failed") + } + } + _ = doc.Set("ok", true) + _, _ = fmt.Fprintln(out, doc.String()) + return true +} + +var configDiagnosticPattern = regexp.MustCompile(`(?m)line [0-9]+|field [a-zA-Z][a-zA-Z0-9_-]* not found|(?:server|models|routing|oauth|access|management|credentials|api-keys)[.a-zA-Z0-9_-]* must be [a-zA-Z ()-]+|unsupported config-version`) + +func configDiagnostics(err error) []string { + diagnostics := configDiagnosticPattern.FindAllString(err.Error(), -1) + if len(diagnostics) == 0 { + return []string{"unknown or incompatible setting; values redacted"} + } + return diagnostics +} + +type hubProbe struct { + Health bool `json:"health"` + Models bool `json:"models"` + Accounts int `json:"accounts"` + // AccountsOutsideAuthDir counts file accounts the hub serves that are not + // files in the auth directory this config resolves to. A hub reading another + // directory can hold the same number of accounts with different logins. + AccountsOutsideAuthDir int `json:"accounts_outside_auth_dir"` + InFlight int64 `json:"in_flight"` +} + +// accountInAuthDir reports whether a file account listed by the hub is a file +// directly inside authDir, by its reported path when present, else by name. +func accountInAuthDir(authDir, path, name string) bool { + if path != "" { + return strings.EqualFold(filepath.Clean(filepath.Dir(path)), filepath.Clean(authDir)) + } + if name == "" || name != filepath.Base(name) { + return false + } + info, errStat := os.Stat(filepath.Join(authDir, name)) + return errStat == nil && info.Mode().IsRegular() +} + +func probeHub(ctx context.Context, base, accessKey, managementKey, authDir string, client *http.Client) hubProbe { + result := hubProbe{Accounts: -1, InFlight: -1} + // Never follow redirects carrying credentials, or inherit an HTTP proxy for localhost. + localClient := *client + localClient.CheckRedirect = func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse } + if client.Transport == nil { + transport := http.DefaultTransport.(*http.Transport).Clone() + transport.Proxy = nil + localClient.Transport = transport + defer transport.CloseIdleConnections() + } + get := func(path, key string) ([]byte, bool) { + req, errRequest := http.NewRequestWithContext(ctx, http.MethodGet, base+path, nil) + if errRequest != nil { + return nil, false + } + if key != "" { + req.Header.Set("Authorization", "Bearer "+key) + } + resp, errResponse := localClient.Do(req) + if errResponse != nil { + return nil, false + } + body, errBody := io.ReadAll(io.LimitReader(resp.Body, 16<<20)) + errClose := resp.Body.Close() + return body, errBody == nil && errClose == nil && resp.StatusCode == http.StatusOK + } + health, healthOK := get("/healthz", "") + result.Health = healthOK && ojson.GetBytes(health, "status").String() == "ok" + body, ok := get("/v1/models", accessKey) + result.Models = ok && ojson.ValidBytes(body) && ojson.GetBytes(body, "data").IsArray() + body, ok = get("/v0/management/auth-files", managementKey) + if ok && ojson.ValidBytes(body) && ojson.GetBytes(body, "files").IsArray() { + result.Accounts = 0 + for _, entry := range ojson.GetBytes(body, "files").Array() { + // Configured API-key providers create virtual auths without a disk file. + if entry.Get("runtime_only").Bool() || entry.Get("source").String() == "memory" { + continue + } + result.Accounts++ + if !accountInAuthDir(authDir, entry.Get("path").String(), entry.Get("name").String()) { + result.AccountsOutsideAuthDir++ + } + } + } + body, ok = get("/v8/management/observability/requests/in-flight", managementKey) + if ok && ojson.ValidBytes(body) && ojson.GetBytes(body, "in_flight").Type == ojson.Number { + if count, errCount := strconv.ParseInt(ojson.GetBytes(body, "in_flight").Raw, 10, 64); errCount == nil && count >= 0 { + result.InFlight = count + } + } + return result +} diff --git a/internal/doctor/config_check_test.go b/internal/doctor/config_check_test.go new file mode 100644 index 00000000000..b668bb9c090 --- /dev/null +++ b/internal/doctor/config_check_test.go @@ -0,0 +1,185 @@ +package doctor + +import ( + "bytes" + "context" + "fmt" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/MoeForge/moego/ojson" +) + +func TestConfigCheckLeavesSourceAndAuthUntouched(t *testing.T) { + dir := t.TempDir() + auth := filepath.Join(dir, "auth") // Deliberately absent. Validation must not create it. + path := filepath.Join(dir, "config.yaml") + source := fmt.Sprintf(`config-version: 8 +server: {host: 127.0.0.1, port: 8317} +management: {secret-key: never-print-management} +access: {api-keys: [never-print-access]} +oauth: {auth-dir: %q} +patched-build-setting: never-print-patched +openai-compatibility: + - name: compatible + base-url: https://example.invalid + api-key-entries: [{api-key: never-print-upstream}] +`, filepath.ToSlash(auth)) + if err := os.WriteFile(path, []byte(source), 0600); err != nil { + t.Fatal(err) + } + var out bytes.Buffer + if status := Main(context.Background(), []string{"-check-config", "-config", path}, &out, &out); status != 0 { + t.Fatalf("status %d, output %s", status, out.String()) + } + if !ojson.Get(out.String(), "ok").Bool() || ojson.Get(out.String(), "settings.port").Int() != 8317 { + t.Fatal(out.String()) + } + if !strings.Contains(out.String(), "patched-build-setting") { + t.Fatal("unknown key was not reported") + } + for _, secret := range []string{"never-print-management", "never-print-access", "never-print-patched", "never-print-upstream"} { + if strings.Contains(out.String(), secret) { + t.Fatal("secret appeared in output") + } + } + saved, err := os.ReadFile(path) + if err != nil || string(saved) != source { + t.Fatal("source config changed") + } + if _, errStat := os.Stat(auth); !os.IsNotExist(errStat) { + t.Fatal("auth directory was opened for writing") + } +} + +func TestConfigCheckRedactsIncompatibleValues(t *testing.T) { + for _, source := range []string{ + "server: {port: never-print-this-value}\n", + "config-version: 99\n", + "server: {port: 8317, port: 9999}\n", + "management: {secret-key: [never-print-this-value]}\n", + } { + t.Run(source[:6], func(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.yaml") + if err := os.WriteFile(path, []byte(source), 0600); err != nil { + t.Fatal(err) + } + var out bytes.Buffer + if Main(context.Background(), []string{"-check-config", "-config", path}, &out, &out) != 1 { + t.Fatal("invalid config accepted") + } + if strings.Contains(out.String(), "never-print-this-value") { + t.Fatal("value leaked") + } + if !ojson.Valid(out.String()) { + t.Fatal(out.String()) + } + }) + } +} + +func TestProbeUsesKeysAndCountsOnlyFileAccounts(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch r.URL.Path { + case "/healthz": + _, _ = w.Write([]byte(`{"status":"ok"}`)) + case "/v1/models": + if r.Header.Get("Authorization") != "Bearer access-secret" { + t.Error("access credential missing") + } + _, _ = w.Write([]byte(`{"data":[]}`)) + case "/v0/management/auth-files": + if r.Header.Get("Authorization") != "Bearer management-secret" { + t.Error("management credential missing") + } + _, _ = w.Write([]byte(`{"files":[{"name":"one.json","source":"file"},{"name":"two.json"},{"runtime_only":true},{"source":"memory"}]}`)) + default: + http.NotFound(w, r) + } + })) + defer server.Close() + // one.json is in the auth directory; two.json belongs to some other directory. + authDir := t.TempDir() + if errWrite := os.WriteFile(filepath.Join(authDir, "one.json"), []byte(`{"type":"codex"}`), 0o600); errWrite != nil { + t.Fatal(errWrite) + } + result := probeHub(context.Background(), server.URL, "access-secret", "management-secret", authDir, server.Client()) + if !result.Health || !result.Models || result.Accounts != 2 || result.AccountsOutsideAuthDir != 1 || result.InFlight != -1 { + t.Fatalf("unexpected result %+v", result) + } + if !accountInAuthDir(authDir, filepath.Join(authDir, "x.json"), "") || accountInAuthDir(authDir, filepath.Join(t.TempDir(), "one.json"), "one.json") { + t.Fatal("a reported path must decide whether the account is in the auth directory") + } +} + +func TestProbeDoesNotFollowCredentialRedirect(t *testing.T) { + reached := false + target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { reached = true })) + defer target.Close() + source := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { http.Redirect(w, r, target.URL, http.StatusFound) })) + defer source.Close() + result := probeHub(context.Background(), source.URL, "access", "management", t.TempDir(), source.Client()) + if reached || result.Models || result.Accounts != -1 { + t.Fatal("credential redirect followed") + } +} + +func TestConfigCheckProbeReadsPlaintextAndHashedManagementKeys(t *testing.T) { + t.Setenv("MANAGEMENT_PASSWORD", "") + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path == "/healthz" { + _, _ = w.Write([]byte(`{"status":"ok"}`)) + return + } + expectedKey := "management-secret" + if r.URL.Path == "/v1/models" { + expectedKey = "access-secret" + } + if r.Header.Get("Authorization") != "Bearer "+expectedKey { + t.Error("wrong key used") + } + switch r.URL.Path { + case "/v1/models": + _, _ = w.Write([]byte(`{"data":[]}`)) + case "/v0/management/auth-files": + _, _ = w.Write([]byte(`{"files":[]}`)) + case "/v8/management/observability/requests/in-flight": + _, _ = w.Write([]byte(`{"in_flight":0}`)) + default: + http.NotFound(w, r) + } + })) + defer server.Close() + for _, hashed := range []bool{false, true} { + dir := t.TempDir() + path := filepath.Join(dir, "config.yaml") + key := "management-secret" + args := []string{"-check-config", "-config", path, "-probe-url", server.URL} + if hashed { + key = "$2a$already-hashed-secret" + keyPath := filepath.Join(dir, "management.key") + if errWrite := os.WriteFile(keyPath, []byte("management-secret"), 0600); errWrite != nil { + t.Fatal(errWrite) + } + args = append(args, "-management-key-file", keyPath) + } + source := "server: {port: 8317}\naccess: {api-keys: [access-secret]}\nmanagement: {secret-key: '" + key + "'}\n" + if errWrite := os.WriteFile(path, []byte(source), 0600); errWrite != nil { + t.Fatal(errWrite) + } + var out bytes.Buffer + if code := Main(context.Background(), args, &out, &out); code != 0 { + t.Fatal(out.String()) + } + if ojson.Get(out.String(), "probe.in_flight").Int() != 0 || !ojson.Get(out.String(), "probe.models").Bool() { + t.Fatal(out.String()) + } + if strings.Contains(out.String(), "management-secret") || strings.Contains(out.String(), "access-secret") { + t.Fatal("probe leaked a secret") + } + } +} diff --git a/internal/doctor/doctor.go b/internal/doctor/doctor.go index 39facfbb0b4..c64509f1270 100644 --- a/internal/doctor/doctor.go +++ b/internal/doctor/doctor.go @@ -16,6 +16,10 @@ // -port port to check (default: server.port from the config, then 8317) // -json print a JSON report instead of aligned text // -offline skip the public network (ipinfo.io) lookup +// -check-config use the production config loader without starting services +// or modifying source files, and print a redacted JSON report +// -probe-url with -check-config, probe an existing loopback HTTP hub +// -management-key-file plaintext key file when config holds a hash // // Exit codes from Main: 0 when no check failed (warnings allowed), 1 when at // least one check failed, 2 on a usage error. @@ -98,6 +102,11 @@ func Main(ctx context.Context, args []string, stdout, stderr io.Writer) int { fs := flag.NewFlagSet("doctor", flag.ContinueOnError) fs.SetOutput(stderr) var opts Options + var configOnly bool + var probeURL, managementKeyFile string + fs.BoolVar(&configOnly, "check-config", false, "validate with the server loader on a temporary copy, without starting services (JSON output)") + fs.StringVar(&probeURL, "probe-url", "", "with -check-config, probe an existing loopback hub using config keys") + fs.StringVar(&managementKeyFile, "management-key-file", "", "plaintext management key file for -probe-url when config holds a hash") fs.StringVar(&opts.ConfigPath, "config", "", "config file to inspect") fs.StringVar(&opts.AuthDir, "auth-dir", "", "auth directory override") fs.IntVar(&opts.Port, "port", 0, "port to check (default from config, then 8317)") @@ -110,6 +119,16 @@ func Main(ctx context.Context, args []string, stdout, stderr io.Writer) int { _, _ = fmt.Fprintf(stderr, "doctor: unexpected argument %q\n", fs.Arg(0)) return 2 } + if configOnly { + if checkConfigCommand(ctx, opts.ConfigPath, probeURL, managementKeyFile, stdout) { + return 0 + } + return 1 + } + if probeURL != "" || managementKeyFile != "" { + _, _ = fmt.Fprintln(stderr, "doctor: probe flags require -check-config") + return 2 + } if Run(ctx, stdout, opts) { return 0 } diff --git a/internal/quotahistory/mistral_test.go b/internal/quotahistory/mistral_test.go new file mode 100644 index 00000000000..494ca487868 --- /dev/null +++ b/internal/quotahistory/mistral_test.go @@ -0,0 +1,291 @@ +package quotahistory + +import ( + "context" + "errors" + "path/filepath" + "reflect" + "strings" + "sync/atomic" + "testing" + "time" + + "github.com/MoeForge/moego/ojson" + "github.com/rune-oai/t3code-proxy/internal/config" + "github.com/rune-oai/t3code-proxy/internal/watcher/synthesizer" + coreauth "github.com/rune-oai/t3code-proxy/sdk/cliproxy/auth" + "github.com/rune-oai/t3code-proxy/sdk/cliproxy/executor" +) + +const mistralBudgetFixture = `{"vibe_budget":{"usage_percentage":0.0,"initial_budget":150.0,"currency":"USD","reset_at":"2026-12-01T00:00:00Z","payg_enabled":false},"api_budget":{"usage_percentage":2.59892596,"initial_budget":15.0,"currency":"USD","reset_at":"2026-12-01T00:00:00Z","payg_enabled":false},"usage_percentage":2.59892596,"initial_budget":15.0,"currency":"USD","reset_at":"2026-12-01T00:00:00Z"}` +const mistralSubscriptionFixture = `{"plan_name":"EDU","payg_enabled":false,"vibe_payg_enabled":false,"enterprise":false}` + +func TestParseMistralUsage(t *testing.T) { + now := time.Date(2026, 11, 15, 0, 0, 0, 0, time.UTC) + reset := time.Date(2026, 12, 1, 0, 0, 0, 0, time.UTC).UnixMilli() + windows, err := parseMistralUsage([]byte(mistralBudgetFixture), now) + want := map[string]Window{ + "api_monthly": {UsedPercent: 2.59892596, ResetsAt: &reset, PeriodHours: 720, Label: "API usage", Budget: 15, Currency: "USD"}, + "vibe_monthly": {UsedPercent: 0, ResetsAt: &reset, PeriodHours: 720, Label: "Vibe Code", Budget: 150, Currency: "USD"}, + } + if err != nil || !reflect.DeepEqual(windows, want) { + t.Fatalf("usage = %+v, %v, want %+v", windows, err, want) + } + if plan := parseMistralPlan([]byte(mistralSubscriptionFixture)); plan != "EDU" { + t.Fatalf("plan = %q", plan) + } + for _, body := range []string{`{}`, `null`, `[]`, `not json`, `{"api_budget":`, `{"usage_percentage":5}`, `{"api_budget":{"usage_percentage":"NaN"}}`, `{"api_budget":{"usage_percentage":-1}}`} { + if _, errParse := parseMistralUsage([]byte(body), now); !errors.Is(errParse, errEmptyPayload) { + t.Errorf("invalid payload %s: %v", body, errParse) + } + } + for _, body := range []string{`{}`, `null`, `{"plan_name":42}`, `{"plan_name":"EDU"`} { + if plan := parseMistralPlan([]byte(body)); plan != "" { + t.Errorf("invalid plan payload %s: %q", body, plan) + } + } + for _, key := range []string{"api_budget", "vibe_budget"} { + t.Run(key, func(t *testing.T) { + doc := ojson.NewDocString(mistralBudgetFixture) + other, id := "vibe_budget", "api_monthly" + if key == "vibe_budget" { + other, id = "api_budget", "vibe_monthly" + } + _ = doc.Delete(other) + _ = doc.Delete(key + ".reset_at") + _ = doc.Set(key+".usage_percentage", 125.5) + windows, errParse := parseMistralUsage(doc.Bytes(), now) + if errParse != nil || len(windows) != 1 || windows[id].UsedPercent != 125.5 || windows[id].ResetsAt != nil { + t.Fatalf("single budget without reset = %+v, %v", windows, errParse) + } + }) + } +} + +func TestMistralCalendarMonthHours(t *testing.T) { + for _, tc := range []struct { + now time.Time + hours float64 + }{ + {time.Date(2026, 1, 31, 23, 0, 0, 0, time.UTC), 744}, + {time.Date(2026, 2, 15, 0, 0, 0, 0, time.UTC), 672}, + {time.Date(2028, 2, 15, 0, 0, 0, 0, time.UTC), 696}, + {time.Date(2026, 12, 15, 0, 0, 0, 0, time.UTC), 744}, + // The local date is February while the UTC date is still January. + {time.Date(2026, 2, 1, 1, 0, 0, 0, time.FixedZone("UTC+2", 2*3600)), 744}, + } { + windows, err := parseMistralUsage([]byte(`{"api_budget":{"usage_percentage":1}}`), tc.now) + if err != nil || windows["api_monthly"].PeriodHours != tc.hours { + t.Errorf("%s: windows = %+v, %v, want %g hours", tc.now, windows, err, tc.hours) + } + } +} + +func TestMistralBillingErrorIsBounded(t *testing.T) { + r := NewRecorder(Deps{Do: func(context.Context, *coreauth.Auth, string, string, map[string]string) (int, []byte, error) { + return 401, []byte(`{"error":"fixture-secret-key"}`), nil + }}) + if _, _, err := r.fetchMistral(context.Background(), &coreauth.Auth{}); err == nil || err.Error() != "HTTP 401" { + t.Fatalf("billing error = %v", err) + } +} + +func TestRecorderMistralAPIKeyAccounts(t *testing.T) { + now := time.Date(2026, 11, 15, 0, 0, 0, 0, time.UTC) + cfg := &config.Config{OpenAICompatibility: []config.OpenAICompatibility{ + {Name: "Campus account", BaseURL: "https://api.mistral.ai/v1", APIKeyEntries: []config.OpenAICompatibilityAPIKey{{APIKey: "fixture-mistral-key"}}}, + {Name: "mistral", BaseURL: "https://other.example/v1", APIKeyEntries: []config.OpenAICompatibilityAPIKey{{APIKey: "fixture-other-key"}}}, + }} + manager := coreauth.NewManager(nil, nil, nil) + manager.SetConfig(&config.Config{Routing: config.RoutingConfig{PlanWeights: map[string]map[string]float64{"mistral": {"edu": 8}}}}) + t.Cleanup(func() { manager.SetConfig(nil) }) + synthesize := func() []*coreauth.Auth { + t.Helper() + auths, err := synthesizer.NewConfigSynthesizer().Synthesize(&synthesizer.SynthesisContext{Config: cfg, Now: now, IDGenerator: synthesizer.NewStableIDGenerator()}) + if err != nil || len(auths) != 2 { + t.Fatalf("synthesis = %d accounts, %v", len(auths), err) + } + return auths + } + auths := synthesize() + index := auths[0].EnsureIndex() + if index == "" || index != synthesize()[0].EnsureIndex() || strings.Contains(index, "fixture") { + t.Fatalf("API-key index is not stable and opaque: %q", index) + } + calls := map[string]int{} + planStatus := 200 + r := NewRecorder(Deps{ + ListAuths: func() []*coreauth.Auth { return auths }, + Label: func(*coreauth.Auth) string { return "fixture-mistral-key" }, + DoRequest: func(_ context.Context, auth *coreauth.Auth, method, url string, header map[string]string, data []byte) (int, []byte, error) { + if auth.ID != auths[0].ID || method != "GET" || header["Authorization"] != "Bearer $TOKEN$" || auth.Attributes["api_key"] != "fixture-mistral-key" || len(data) != 0 { + t.Error("wrong account or Bearer request") + return 400, nil, nil + } + calls[url]++ + switch url { + case MistralBudgetURL: + return 200, []byte(mistralBudgetFixture), nil + case MistralSubscriptionURL: + return planStatus, []byte(mistralSubscriptionFixture), nil + } + t.Errorf("unexpected billing URL %q", url) + return 404, nil, nil + }, + }) + var clock atomic.Int64 + clock.Store(now.UnixNano()) + r.now = func() time.Time { return time.Unix(0, clock.Load()) } + r.startupDelay = time.Hour + s := enabledSettings(t) + if err := r.Apply(s); err != nil { + t.Fatal(err) + } + t.Cleanup(r.Close) + for _, providers := range []string{"", "mistral"} { + r.providers.Store(providers) + now = now.Add(time.Minute) + clock.Store(now.UnixNano()) + if n := r.poll(context.Background(), r.store, 0, nil); n != 1 { + t.Fatalf("allowlist %q: %d samples", providers, n) + } + } + if calls[MistralBudgetURL] != 2 || calls[MistralSubscriptionURL] != 1 { + t.Fatalf("billing calls = %v", calls) + } + history, err := r.History(0, 0) + if err != nil || len(history.Accounts) != 1 || len(history.Samples) != 2 { + t.Fatalf("history = %+v, %v", history, err) + } + account := history.Accounts[0] + if account.AuthIndex != index || account.Provider != "mistral" || account.Label != "Campus account" || account.Plan != "EDU" || account.Weight != 1 { + t.Fatalf("account = %+v", account) + } + // Reopening seeds the display plan without publishing a routing plan. + r.Close() + if err := r.Apply(s); err != nil { + t.Fatal(err) + } + if accounts := r.accounts(); len(accounts) != 1 || accounts[0].Plan != "EDU" || coreauth.PlanOf(auths[0]) != "" { + t.Fatalf("reopened accounts = %+v", accounts) + } + now = now.Add(profileTTL) + clock.Store(now.UnixNano()) + planStatus = 503 + if rec := r.sample(context.Background(), auths[0]); rec.Error != "" || rec.Plan != "EDU" || calls[MistralSubscriptionURL] != 2 { + t.Fatalf("failed plan refresh = %+v, calls %v", rec, calls) + } + r.providers.Store("codex") + if n := r.poll(context.Background(), r.store, 0, nil); n != 0 || len(r.accounts()) != 0 { + t.Fatal("an allowlist excluding Mistral must skip its accounts") + } + r.providers.Store("mistral") + auths[0].Disabled = true + if n := r.poll(context.Background(), r.store, 0, nil); n != 0 || !r.accounts()[0].Disabled { + t.Fatal("a disabled Mistral account must remain listed without polling") + } +} + +func TestMistralHostDetection(t *testing.T) { + for _, tc := range []struct { + base string + want bool + }{ + {"https://api.mistral.ai/v1", true}, + {"https://API.MISTRAL.AI:443/v1/", true}, + {"https://api.mistral.ai.example/v1", false}, + {"https://api.mistral.ai@other.example/v1", false}, + {"https://other.example/api.mistral.ai", false}, + {":invalid", false}, + } { + auth := &coreauth.Auth{ID: "host-test", Provider: "mistral", Attributes: map[string]string{"api_key": "fixture", "base_url": tc.base}} + r := NewRecorder(Deps{ListAuths: func() []*coreauth.Auth { return []*coreauth.Auth{auth} }}) + if got := len(r.trackable(nil)) == 1; got != tc.want { + t.Errorf("%s: trackable = %t", tc.base, got) + } + delete(auth.Attributes, "api_key") + if len(r.trackable(nil)) != 0 { + t.Errorf("%s: tracked without an API key", tc.base) + } + } +} + +func TestMistralSpentBudgetsDoNotGovernRouting(t *testing.T) { + spent := &coreauth.Auth{ID: t.Name() + "-spent", Provider: "openai-compatible-campus", Attributes: map[string]string{"compat_name": "Campus", "api_key": "fixture-spent", "base_url": "https://api.mistral.ai/v1"}} + fresh := spent.Clone() + fresh.ID = t.Name() + "-fresh" + fresh.Attributes["api_key"] = "fixture-fresh" + auths := []*coreauth.Auth{spent, fresh} + r := NewRecorder(Deps{ListAuths: func() []*coreauth.Auth { return auths }, Do: func(_ context.Context, auth *coreauth.Auth, _, url string, _ map[string]string) (int, []byte, error) { + if url == MistralSubscriptionURL { + return 200, []byte(mistralSubscriptionFixture), nil + } + used := 0 + if auth.ID == spent.ID { + used = 125 + } + doc := ojson.NewDocString(mistralBudgetFixture) + _ = doc.Set("api_budget.usage_percentage", used) + _ = doc.Set("vibe_budget.usage_percentage", 100) + return 200, doc.Bytes(), nil + }}) + for _, auth := range r.trackable(nil) { + rec := r.sample(context.Background(), auth) + if rec.Error != "" || len(rec.Windows) != 2 { + t.Fatalf("sample = %+v", rec) + } + if observed, windows := coreauth.ObservedQuotaWindows(auth.ID); !observed.IsZero() || len(windows) != 0 || coreauth.PlanOf(auth) != "" { + t.Fatalf("usage-only account published routing observations: %v %+v", observed, windows) + } + } + selector := &coreauth.SoonestResetFirstSelector{} + seen := map[string]bool{} + for range 4 { + picked, err := selector.Pick(context.Background(), spent.Provider, "mistral-vibe-cli-latest", executor.Options{}, auths) + if err != nil || picked == nil { + t.Fatalf("pick = %v, %v", picked, err) + } + seen[picked.ID] = true + } + if !seen[spent.ID] || !seen[fresh.ID] { + t.Fatalf("spent budget excluded an account from rotation: %v", seen) + } +} + +func TestStoreMistralBudgetsRoundTrip(t *testing.T) { + path := filepath.Join(t.TempDir(), "qh.db") + store, err := OpenStore(path) + if err != nil { + t.Fatal(err) + } + windows, err := parseMistralUsage([]byte(mistralBudgetFixture), time.Date(2026, 11, 15, 0, 0, 0, 0, time.UTC)) + if err != nil { + t.Fatal(err) + } + rec := record{Sample: Sample{T: 5, AuthIndex: "mistral-index", Windows: windows}, Plan: "EDU"} + if errPut := store.put(rec); errPut != nil { + t.Fatal(errPut) + } + if errClose := store.Close(); errClose != nil { + t.Fatal(errClose) + } + reopened, err := OpenStore(path) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { + if errClose := reopened.Close(); errClose != nil { + t.Error(errClose) + } + }) + if records := collect(t, reopened, 0, 10); len(records) != 1 || !reflect.DeepEqual(records[0], rec) { + t.Fatalf("budget round trip = %+v", records) + } + doc := ojson.NewDocString(`{}`) + if errSet := doc.Set("window", Window{UsedPercent: 20, PeriodHours: 5}); errSet != nil { + t.Fatal(errSet) + } + if got := doc.Get("window").Raw; got != `{"used_percent":20,"resets_at":null,"period_hours":5}` { + t.Fatalf("legacy window JSON changed: %s", got) + } +} diff --git a/internal/quotahistory/parse.go b/internal/quotahistory/parse.go index c4c8c96a0b5..0c2c5e19eaa 100644 --- a/internal/quotahistory/parse.go +++ b/internal/quotahistory/parse.go @@ -2,6 +2,7 @@ package quotahistory import ( "errors" + "math" "strconv" "strings" "time" @@ -27,6 +28,13 @@ type Window struct { UsedPercent float64 `json:"used_percent"` ResetsAt *int64 `json:"resets_at"` PeriodHours float64 `json:"period_hours"` + // Label is the provider's own name for the window, when it has one. + Label string `json:"label,omitempty"` + Budget float64 `json:"budget,omitempty"` + Currency string `json:"currency,omitempty"` + modelScope []string + // estimated marks a used percent the payload did not state. + estimated bool } var errEmptyPayload = errors.New("empty or invalid usage payload") @@ -202,8 +210,10 @@ func ParseCodexUsage(body []byte, now time.Time) (map[string]Window, string, err if !limitReached { continue } + // The payload says a limit was hit but not which window. used = 100 } + estimated := !ok reset := resetMs(firstExisting(raw.Get("reset_at"), raw.Get("resetAt"))) if reset == nil { if after, okAfter := number(firstExisting(raw.Get("reset_after_seconds"), raw.Get("resetAfterSeconds"))); okAfter && after > 0 { @@ -211,7 +221,7 @@ func ParseCodexUsage(body []byte, now time.Time) (map[string]Window, string, err reset = &ms } } - windows[id] = Window{UsedPercent: used, ResetsAt: reset, PeriodHours: seconds / 3600} + windows[id] = Window{UsedPercent: used, ResetsAt: reset, PeriodHours: seconds / 3600, estimated: estimated} } return windows, plan, nil } @@ -220,10 +230,11 @@ func ParseCodexUsage(body []byte, now time.Time) (map[string]Window, string, err func number(r ojson.Result) (float64, bool) { switch r.Type { case ojson.Number: - return r.Float(), true + v := r.Float() + return v, !math.IsNaN(v) && !math.IsInf(v, 0) case ojson.String: v, errParse := strconv.ParseFloat(strings.TrimSpace(r.String()), 64) - if errParse != nil { + if errParse != nil || math.IsNaN(v) || math.IsInf(v, 0) { return 0, false } return v, true diff --git a/internal/quotahistory/parse_providers.go b/internal/quotahistory/parse_providers.go new file mode 100644 index 00000000000..8058de1a559 --- /dev/null +++ b/internal/quotahistory/parse_providers.go @@ -0,0 +1,321 @@ +package quotahistory + +import ( + "fmt" + "math" + "strings" + "time" + + "github.com/MoeForge/moego/ojson" +) + +func usageRoot(body []byte) (ojson.Result, error) { + if !ojson.ValidBytes(body) { + return ojson.Result{}, errEmptyPayload + } + root := ojson.ParseBytes(body) + if !root.IsObject() { + return root, errEmptyPayload + } + return root, nil +} + +func clampedPercent(value float64) float64 { return math.Max(0, math.Min(100, value)) } + +func parseMistralUsage(body []byte, now time.Time) (map[string]Window, error) { + root, err := usageRoot(body) + if err != nil { + return nil, err + } + now = now.UTC() + start := time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, time.UTC) + period := start.AddDate(0, 1, 0).Sub(start).Hours() + windows := make(map[string]Window) + for _, budget := range []struct{ key, id, label string }{ + {"api_budget", "api_monthly", "API usage"}, + {"vibe_budget", "vibe_monthly", "Vibe Code"}, + } { + raw := root.Get(budget.key) + used, ok := number(raw.Get("usage_percentage")) + if !raw.IsObject() || !ok || used < 0 { + continue + } + window := Window{UsedPercent: used, ResetsAt: resetMs(raw.Get("reset_at")), PeriodHours: period, Label: budget.label} + if amount, hasAmount := number(raw.Get("initial_budget")); hasAmount && amount >= 0 { + window.Budget = amount + } + window.Currency = firstString(raw.Get("currency")) + windows[budget.id] = window + } + if len(windows) == 0 { + return nil, errEmptyPayload + } + return windows, nil +} + +func parseMistralPlan(body []byte) string { + root, err := usageRoot(body) + if err != nil { + return "" + } + return firstString(root.Get("plan_name")) +} + +func parseMetaUsage(body []byte) (map[string]Window, error) { + root, err := usageRoot(body) + if err != nil { + return nil, err + } + windows := make(map[string]Window) + for _, key := range []string{"window", "weekly"} { + raw := root.Get("subs_usage." + key) + used, ok := number(raw.Get("used_percent")) + if !ok { + continue + } + period := 168.0 + if key == "window" { + minutes, _ := number(raw.Get("window_duration_mins")) + period = math.Max(0, minutes/60) + } + windows[key] = Window{UsedPercent: clampedPercent(used), ResetsAt: resetMs(raw.Get("resets_at")), PeriodHours: period} + } + return windows, nil +} + +func parseDevinUsage(body []byte) (map[string]Window, error) { + root, err := usageRoot(body) + if err != nil { + return nil, err + } + status := root.Get("userStatus.planStatus") + windows := make(map[string]Window) + for _, key := range []string{"daily", "weekly"} { + remaining, ok := number(status.Get(key + "QuotaRemainingPercent")) + if !ok || remaining < 0 || remaining > 100 { + continue + } + period := 24.0 + if key == "weekly" { + period = 168 + } + windows[key] = Window{UsedPercent: 100 - remaining, ResetsAt: resetMs(status.Get(key + "QuotaResetAtUnix")), PeriodHours: period} + } + if len(windows) == 0 { + return nil, errEmptyPayload + } + return windows, nil +} + +func parseXAIUsage(body []byte) (map[string]Window, error) { + root, err := usageRoot(body) + if err != nil { + return nil, err + } + config := root.Get("config") + if !config.IsObject() { + return nil, errEmptyPayload + } + windows := make(map[string]Window) + current := firstExisting(config.Get("currentPeriod"), config.Get("current_period")) + if used, ok := number(firstExisting(config.Get("creditUsagePercent"), config.Get("credit_usage_percent"))); ok { + key := "weekly" + if strings.Contains(strings.ToLower(current.Get("type").String()), "monthly") { + key = "monthly" + } + start := firstExisting(current.Get("start"), config.Get("billingPeriodStart"), config.Get("billing_period_start")) + end := firstExisting(current.Get("end"), config.Get("billingPeriodEnd"), config.Get("billing_period_end")) + windows[key] = datedWindow(used, start, end) + } + limit := firstExisting(config.Get("monthlyLimit"), config.Get("monthly_limit")) + if limit.IsObject() { + limit = limit.Get("val") + } + spent := config.Get("used") + if spent.IsObject() { + spent = spent.Get("val") + } + cap, hasCap := number(limit) + used, hasUsed := number(spent) + if hasCap && cap > 0 && hasUsed && used >= 0 { + windows["monthly"] = datedWindow(used/cap*100, firstExisting(config.Get("billingPeriodStart"), config.Get("billing_period_start")), firstExisting(config.Get("billingPeriodEnd"), config.Get("billing_period_end"))) + } + return windows, nil +} + +// Billing periods must have both boundaries to establish a renewing duration. +func datedWindow(used float64, start, end ojson.Result) Window { + reset, begin := resetMs(end), resetMs(start) + period := 0.0 + if reset != nil && begin != nil && *reset > *begin { + period = float64(*reset-*begin) / float64(time.Hour/time.Millisecond) + } + return Window{UsedPercent: clampedPercent(used), ResetsAt: reset, PeriodHours: period} +} + +func parseKimiUsage(body []byte, now time.Time) (map[string]Window, error) { + root, err := usageRoot(body) + if err != nil { + return nil, err + } + windows := make(map[string]Window) + for index, item := range root.Get("limits").Array() { + detail := item.Get("detail") + if !detail.IsObject() { + detail = item + } + label := firstString(detail.Get("name"), detail.Get("title"), item.Get("name"), item.Get("title"), item.Get("scope"), detail.Get("scope")) + duration, _ := number(firstExisting(item.Get("window.duration"), item.Get("duration"), detail.Get("duration"))) + unit := firstString(item.Get("window.timeUnit"), item.Get("timeUnit"), detail.Get("timeUnit")) + period := kimiPeriod(label, duration, unit) + key := stableKey(label) + if key == "" && period > 0 { + key = fmt.Sprintf("%gh", period) + } + key = "limit_" + indexedKey(key, index) + // Repeated labels retain separate windows instead of overwriting a cap. + if _, exists := windows[key]; exists { + key = fmt.Sprintf("%s_%d", key, index) + } + if window, ok := kimiWindow(detail, period, now); ok { + window.Label = strings.TrimSpace(label) + windows[key] = window + } + } + if window, ok := kimiWindow(root.Get("usage"), 168, now); ok { + windows["summary"] = window + } + monthly := root.Get("usages.limit_month_total") + if ratio, ok := number(monthly.Get("used_ratio")); ok && ratio >= 0 { + windows["monthly"] = Window{UsedPercent: clampedPercent(ratio * 100), ResetsAt: resetMs(monthly.Get("reset_time")), PeriodHours: 720} + } + return windows, nil +} + +func kimiPeriod(label string, duration float64, unit string) float64 { + if duration > 0 { + switch strings.TrimSuffix(strings.TrimPrefix(strings.ToUpper(strings.TrimSpace(unit)), "TIME_UNIT_"), "S") { + case "SECOND": + return duration / 3600 + case "HOUR": + return duration + case "DAY": + return duration * 24 + case "WEEK": + return duration * 168 + default: + return duration / 60 + } + } + label = strings.ToLower(label) + switch { + case strings.Contains(label, "daily"), strings.Contains(label, "day"): + return 24 + case strings.Contains(label, "weekly"), strings.Contains(label, "week"): + return 168 + case strings.Contains(label, "monthly"), strings.Contains(label, "month"): + return 720 + case strings.Contains(label, "5h"), strings.Contains(label, "hour"): + return 5 + default: + return 0 + } +} + +func kimiWindow(raw ojson.Result, period float64, now time.Time) (Window, bool) { + cap, hasCap := number(raw.Get("limit")) + used, hasUsed := number(raw.Get("used")) + if !hasUsed { + if remaining, ok := number(raw.Get("remaining")); ok && hasCap { + used, hasUsed = cap-remaining, true + } + } + if !hasCap || cap <= 0 || !hasUsed { + return Window{}, false + } + reset := resetMs(firstExisting(raw.Get("reset_at"), raw.Get("resetAt"), raw.Get("reset_time"), raw.Get("resetTime"))) + if reset == nil { + for _, field := range []string{"reset_in", "resetIn", "ttl"} { + if seconds, ok := number(raw.Get(field)); ok && seconds > 0 { + ms := now.Add(time.Duration(seconds * float64(time.Second))).UnixMilli() + reset = &ms + break + } + } + } + return Window{UsedPercent: clampedPercent(used / cap * 100), ResetsAt: reset, PeriodHours: period}, true +} + +func parseQuotaGroups(body []byte, modelScoped bool) (map[string]Window, error) { + root, err := usageRoot(body) + if err != nil { + return nil, err + } + windows := make(map[string]Window) + for groupIndex, group := range root.Get("groups").Array() { + name := firstString(group.Get("displayName"), group.Get("display_name")) + groupID := indexedKey(name, groupIndex) + for bucketIndex, bucket := range group.Get("buckets").Array() { + remaining, ok := number(firstExisting(bucket.Get("remainingFraction"), bucket.Get("remaining_fraction"))) + if !ok { + continue + } + // The panel also accepts percentages in remainingFraction. + if remaining > 1 && remaining <= 100 { + remaining /= 100 + } + remaining = math.Max(0, math.Min(1, remaining)) + window := firstString(bucket.Get("window")) + period := 0.0 + switch strings.ToLower(strings.TrimSpace(window)) { + case "5h", "five-hour", "five_hour": + period = 5 + case "weekly", "week": + period = 168 + case "daily", "day": + period = 24 + default: + if duration, ok := parseDuration(window); ok { + period = duration.Hours() + } + } + bucketID := firstString(bucket.Get("bucketId"), bucket.Get("bucket_id")) + key := "group_" + groupID + "_" + indexedKey(bucketID, bucketIndex) + if bucketID == "" && window != "" { + key = "group_" + groupID + "_" + stableKey(window) + } + if _, exists := windows[key]; exists { + key = fmt.Sprintf("%s_%d", key, bucketIndex) + } + scope := quotaGroupScope(bucketID, name) + if modelScoped && len(scope) == 0 { + // Unidentified model pools remain visible in history but cannot govern routing. + scope = []string{""} + } + label := strings.TrimSpace(strings.TrimSpace(name) + " " + strings.ToLower(strings.TrimSpace(window))) + windows[key] = Window{UsedPercent: clampedPercent((1 - remaining) * 100), ResetsAt: resetMs(firstExisting(bucket.Get("resetTime"), bucket.Get("reset_time"))), PeriodHours: period, Label: label, modelScope: scope} + } + } + return windows, nil +} + +func quotaGroupScope(bucketID, groupName string) []string { + // Bucket IDs identify the pool. Strip the renewing-window suffix before + // matching a family pool or a model-specific pool against model IDs. + id := strings.ToLower(strings.TrimSpace(bucketID)) + for _, suffix := range []string{"-weekly", "-week", "-five-hour", "-five_hour", "-5h"} { + id = strings.TrimSuffix(id, suffix) + } + for _, family := range []string{"gemini", "claude", "gpt"} { + if id == family { + return []string{family + "-*"} + } + if strings.HasPrefix(id, family+"-") { + return []string{id, id + "-*"} + } + if bucketID == "" && strings.HasPrefix(strings.ToLower(strings.TrimSpace(groupName)), family) { + return []string{family + "-*"} + } + } + return nil +} diff --git a/internal/quotahistory/parse_providers_test.go b/internal/quotahistory/parse_providers_test.go new file mode 100644 index 00000000000..0a9c5af5eb4 --- /dev/null +++ b/internal/quotahistory/parse_providers_test.go @@ -0,0 +1,102 @@ +package quotahistory + +import ( + "math" + "os" + "path/filepath" + "reflect" + "testing" + "time" +) + +func quotaFixture(t *testing.T, provider string) []byte { + t.Helper() + body, err := os.ReadFile(filepath.Join("testdata", provider+".json")) + if err != nil { + t.Fatal(err) + } + return body +} + +func TestProviderUsageFixtures(t *testing.T) { + now := time.Date(2026, 11, 15, 0, 0, 0, 0, time.UTC) + reset := time.Date(2026, 11, 20, 0, 0, 0, 0, time.UTC).UnixMilli() + type expected struct { + used, hours float64 + reset int64 + scope []string + } + cases := []struct { + provider string + parse func([]byte) (map[string]Window, error) + want map[string]expected + }{ + {"xai", parseXAIUsage, map[string]expected{ + "weekly": {used: 25, hours: 168, reset: reset}, + "monthly": {used: 45, hours: 720, reset: now.AddDate(0, 0, 16).UnixMilli()}, + }}, + {"meta", parseMetaUsage, map[string]expected{ + "window": {used: 2, hours: 5, reset: 1794726000000}, + "weekly": {used: 65, hours: 168, reset: reset}, + }}, + {"devin", parseDevinUsage, map[string]expected{ + "daily": {used: 46, hours: 24, reset: now.AddDate(0, 0, 1).UnixMilli()}, + "weekly": {used: 23, hours: 168, reset: reset}, + }}, + {"kimi", func(body []byte) (map[string]Window, error) { return parseKimiUsage(body, now) }, map[string]expected{ + "limit_session": {used: 60, hours: 5, reset: now.Add(time.Hour).UnixMilli()}, + "limit_daily": {used: 20, hours: 24, reset: now.AddDate(0, 0, 1).UnixMilli()}, + "limit_168h": {used: 10, hours: 168, reset: reset}, + "summary": {used: 50, hours: 168, reset: reset}, + "monthly": {used: 75, hours: 720, reset: now.AddDate(0, 0, 16).UnixMilli()}, + }}, + {"antigravity", func(body []byte) (map[string]Window, error) { return parseQuotaGroups(body, true) }, map[string]expected{ + "group_gemini_models_gemini_weekly": {used: 75, hours: 168, reset: reset + 123, scope: []string{"gemini-*"}}, + "group_gemini_models_gemini_5h": {used: 30, hours: 5, reset: now.Add(4 * time.Hour).UnixMilli(), scope: []string{"gemini-*"}}, + "group_claude_models_claude_weekly": {used: 100, hours: 168, reset: now.AddDate(0, 0, 4).UnixMilli(), scope: []string{"claude-*"}}, + "group_unknown_pool_opaque": {used: 0, hours: 0, scope: []string{""}}, + }}, + {"plugin", func(body []byte) (map[string]Window, error) { return parseQuotaGroups(body, false) }, map[string]expected{ + "group_account_weekly": {used: 75, hours: 168, reset: reset}, + "group_account_5h": {used: 50, hours: 5, reset: now.Add(4 * time.Hour).UnixMilli()}, + }}, + } + for _, tc := range cases { + t.Run(tc.provider, func(t *testing.T) { + windows, err := tc.parse(quotaFixture(t, tc.provider)) + if err != nil { + t.Fatal(err) + } + if len(windows) != len(tc.want) { + t.Fatalf("windows = %+v, want %d windows", windows, len(tc.want)) + } + for key, want := range tc.want { + got, ok := windows[key] + if !ok || math.Abs(got.UsedPercent-want.used) > 1e-9 || got.PeriodHours != want.hours || !reflect.DeepEqual(got.modelScope, want.scope) { + t.Errorf("window %s = %+v, want %+v", key, got, want) + } + if want.reset == 0 { + if got.ResetsAt != nil { + t.Errorf("window %s reset = %d, want unknown", key, *got.ResetsAt) + } + } else if got.ResetsAt == nil || *got.ResetsAt != want.reset { + t.Errorf("window %s reset = %v, want %d", key, got.ResetsAt, want.reset) + } + } + for _, invalid := range []string{"null", "[]", "not json", `{"groups": [`} { + if _, err := tc.parse([]byte(invalid)); err == nil { + t.Errorf("accepted invalid payload %s", invalid) + } + } + }) + } +} + +func TestProviderUnknownUsageIsNotZero(t *testing.T) { + for _, parse := range []func([]byte) (map[string]Window, error){parseMetaUsage, parseXAIUsage, parseDevinUsage, func(body []byte) (map[string]Window, error) { return parseKimiUsage(body, time.Unix(0, 0)) }} { + windows, _ := parse([]byte(`{"config":{"currentPeriod":{"type":"weekly"}},"subs_usage":{"window":{"used_percent":"NaN"},"weekly":{"used_percent":null}},"usage":{"limit":100},"userStatus":{"planStatus":{"weeklyQuotaRemainingPercent":null}}}`)) + if len(windows) != 0 { + t.Fatalf("unknown usage produced windows %+v", windows) + } + } +} diff --git a/internal/quotahistory/providers.go b/internal/quotahistory/providers.go new file mode 100644 index 00000000000..a44dc6ab91f --- /dev/null +++ b/internal/quotahistory/providers.go @@ -0,0 +1,335 @@ +package quotahistory + +import ( + "context" + "errors" + "fmt" + "strings" + + "github.com/MoeForge/moego/ojson" + kimiauth "github.com/rune-oai/t3code-proxy/internal/auth/kimi" + "github.com/rune-oai/t3code-proxy/internal/misc" + coreauth "github.com/rune-oai/t3code-proxy/sdk/cliproxy/auth" +) + +const ( + XAIWeeklyURL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits" + XAIMonthlyURL = "https://cli-chat-proxy.grok.com/v1/billing" + // XAISettingsURL and XAIUserURL name the subscription behind a Grok login. + XAISettingsURL = "https://cli-chat-proxy.grok.com/v1/settings" + XAIUserURL = "https://cli-chat-proxy.grok.com/v1/user?include=subscription" + // AntigravityCodeAssistURL reports the subscription tier of a Google account. + AntigravityCodeAssistURL = "https://daily-cloudcode-pa.googleapis.com/v1internal:loadCodeAssist" + MetaUsageURL = "https://api.meta.ai/muse-code/key" + DevinUsageURL = "https://server.codeium.com/exa.seat_management_pb.SeatManagementService/GetUserStatus" + MistralBudgetURL = "https://api.mistral.ai/v1/billing/budget" + MistralSubscriptionURL = "https://api.mistral.ai/v1/billing/subscription" +) + +var antigravityQuotaURLs = []string{ + "https://daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary", + "https://daily-cloudcode-pa.sandbox.googleapis.com/v1internal:retrieveUserQuotaSummary", + "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary", +} + +type providerPoller func(*Recorder, context.Context, *coreauth.Auth) (map[string]Window, string, error) + +var providerPollers = map[string]providerPoller{ + "claude": func(r *Recorder, ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + windows, err := r.fetchClaude(ctx, auth) + plan := "" + if err == nil { + plan = r.claudePlan(ctx, auth) + } + return windows, plan, err + }, + "codex": func(r *Recorder, ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + windows, plan, err := r.fetchCodex(ctx, auth) + if plan == "" { + plan = metadataString(auth, "plan_type") + } + return windows, plan, err + }, + "xai": func(r *Recorder, ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + windows, plan, err := r.fetchXAI(ctx, auth) + if err == nil && plan == "" { + plan = r.cachedPlan(auth, func() string { return r.xaiPlan(ctx, auth) }) + } + return windows, plan, err + }, + "antigravity": func(r *Recorder, ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + windows, plan, err := r.fetchAntigravity(ctx, auth) + if err == nil && plan == "" { + plan = r.cachedPlan(auth, func() string { return r.antigravityPlan(ctx, auth) }) + } + return windows, plan, err + }, + "kimi": (*Recorder).fetchKimi, + "kimi-ai": (*Recorder).fetchKimi, + "meta": (*Recorder).fetchMeta, + "devin": (*Recorder).fetchDevin, + "mistral": (*Recorder).fetchMistral, +} + +func (r *Recorder) fetchMistral(ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + body, err := r.get(ctx, auth, MistralBudgetURL, bearerHeaders()) + if err != nil { + return nil, "", err + } + windows, errParse := parseMistralUsage(body, r.now()) + if errParse != nil { + return nil, "", errParse + } + plan := r.cachedPlan(auth, func() string { + body, errGet := r.get(ctx, auth, MistralSubscriptionURL, bearerHeaders()) + if errGet != nil { + return "" + } + return parseMistralPlan(body) + }) + return windows, plan, nil +} + +func bearerHeaders() map[string]string { + return map[string]string{"Authorization": "Bearer $TOKEN$", "Content-Type": "application/json", "Accept": "application/json"} +} + +func xaiHeaders(auth *coreauth.Auth) map[string]string { + headers := bearerHeaders() + headers["x-xai-token-auth"] = "xai-grok-cli" + headers["x-grok-client-version"] = "1.0.70" + headers["User-Agent"] = "grok-pager/1.0.70 grok-shell/1.0.70 (macos; aarch64)" + for _, key := range []string{"sub", "subject", "user_id", "userId", "oauth.sub", "oauth.subject", "user.sub", "user.id"} { + if userID := accountValue(auth, key); userID != "" { + headers["x-userid"] = userID + break + } + } + return headers +} + +// xaiPlan names the Grok subscription by its display name ("SuperGrok"), which +// is what plan weights are keyed by. The internal tier ("GrokPro") is used only +// when the settings answer carries no display name; a failed settings request +// yields no plan, so a known plan is kept and the request is retried. +func (r *Recorder) xaiPlan(ctx context.Context, auth *coreauth.Auth) string { + headers := xaiHeaders(auth) + settings, errSettings := r.get(ctx, auth, XAISettingsURL, headers) + if errSettings != nil { + return "" + } + root := ojson.ParseBytes(settings) + if plan := firstString(root.Get("subscription_tier_display"), root.Get("subscriptionTierDisplay")); plan != "" { + return plan + } + body, err := r.get(ctx, auth, XAIUserURL, headers) + if err != nil { + return "" + } + user := ojson.ParseBytes(body) + return firstString(user.Get("subscriptionTier"), user.Get("subscription_tier")) +} + +var antigravityTierPlans = map[string]string{ + "free-tier": "free", + "g1-pro-tier": "pro", + "g1-ultra-tier": "ultra", + "g1-ultra-lite-tier": "ultra-lite", +} + +// antigravityPlan names the Google subscription tier. The paid tier wins over +// the current tier, as in the panel's account view. +func (r *Recorder) antigravityPlan(ctx context.Context, auth *coreauth.Auth) string { + headers := bearerHeaders() + headers["User-Agent"] = misc.AntigravityUserAgent() + body, err := r.request(ctx, auth, "POST", AntigravityCodeAssistURL, headers, []byte(`{"metadata":{"ideType":"ANTIGRAVITY"}}`)) + if err != nil { + return "" + } + return parseAntigravityPlan(body) +} + +func parseAntigravityPlan(body []byte) string { + root := ojson.ParseBytes(body) + for _, tier := range []ojson.Result{ + firstExisting(root.Get("paidTier"), root.Get("paid_tier")), + firstExisting(root.Get("currentTier"), root.Get("current_tier")), + } { + id := firstString(tier.Get("id")) + if id == "" { + continue + } + if plan := antigravityTierPlans[id]; plan != "" { + return plan + } + if name := firstString(tier.Get("name")); name != "" { + return name + } + return id + } + return "" +} + +func (r *Recorder) fetchXAI(ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + headers := xaiHeaders(auth) + windows := make(map[string]Window) + var lastErr error + for _, url := range []string{XAIWeeklyURL, XAIMonthlyURL} { + body, err := r.get(ctx, auth, url, headers) + if err != nil { + lastErr = err + continue + } + parsed, errParse := parseXAIUsage(body) + if errParse != nil { + lastErr = errParse + continue + } + for key, window := range parsed { + windows[key] = window + } + } + if len(windows) == 0 && lastErr != nil { + return nil, "", lastErr + } + return windows, "", nil +} + +func (r *Recorder) fetchKimi(ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + host := "api.kimi.com" + if kimiauth.IsKimiAIDomain(kimiauth.ResolveKimiDomainFromAuth(auth)) { + host = "api.kimi.ai" + } + body, err := r.get(ctx, auth, "https://"+host+"/coding/v1/usages", bearerHeaders()) + if err != nil { + return nil, "", err + } + windows, errParse := parseKimiUsage(body, r.now()) + return windows, "", errParse +} + +func (r *Recorder) fetchMeta(ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + // Muse quota requires the persisted DCA credential, independently of the LLM key. + token := accountValue(auth, "dca_token") + if !strings.HasPrefix(token, "dca:") || strings.ContainsAny(token, " \t\r\n") { + return nil, "", errors.New("missing Meta DCA credential") + } + headers := bearerHeaders() + headers["Authorization"] = "Bearer " + token + headers["x-api-version"] = "1.0.0" + body, err := r.request(ctx, auth, "POST", MetaUsageURL, headers, []byte("{}")) + if err != nil { + return nil, "", err + } + windows, errParse := parseMetaUsage(body) + root := ojson.ParseBytes(body) + return windows, firstString(root.Get("subs_tier_name"), root.Get("subs_usage.tier")), errParse +} + +func (r *Recorder) fetchDevin(ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + doc := ojson.NewDocString(`{"metadata":{"ideName":"chisel","ideVersion":"3000.10.21","apiKey":"$TOKEN$","locale":"en","os":"darwin","extensionVersion":"3000.10.21","clientName":"chisel"}}`) + body, err := r.request(ctx, auth, "POST", DevinUsageURL, map[string]string{"Content-Type": "application/json", "Connect-Protocol-Version": "1"}, doc.Bytes()) + if err != nil { + return nil, "", err + } + windows, errParse := parseDevinUsage(body) + return windows, firstString(ojson.ParseBytes(body).Get("userStatus.planStatus.planInfo.planName")), errParse +} + +func (r *Recorder) fetchAntigravity(ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + project := "" + for _, key := range []string{"project_id", "projectId", "gemini_virtual_project", "installed.project_id", "installed.projectId", "web.project_id", "web.projectId"} { + if project = accountValue(auth, key); project != "" { + break + } + } + if project == "" { + return nil, "", errors.New("missing Antigravity project ID") + } + doc := ojson.NewDocString(`{}`) + if errSet := doc.Set("project", project); errSet != nil { + return nil, "", errors.New("invalid Antigravity project ID") + } + headers := bearerHeaders() + headers["User-Agent"] = misc.AntigravityUserAgent() + windows := make(map[string]Window) + var lastErr error + for _, url := range antigravityQuotaURLs { + body, err := r.request(ctx, auth, "POST", url, headers, doc.Bytes()) + if err != nil { + lastErr = err + continue + } + parsed, errParse := parseQuotaGroups(body, true) + if errParse != nil { + lastErr = errParse + continue + } + hasGemini := false + for key, window := range parsed { + if _, exists := windows[key]; !exists { + windows[key] = window + } + for _, scope := range window.modelScope { + if strings.HasPrefix(scope, "gemini") { + hasGemini = true + } + } + } + if hasGemini { + break + } + } + if len(windows) == 0 { + if lastErr == nil { + lastErr = errEmptyPayload + } + return nil, "", lastErr + } + return windows, "", nil +} + +func (r *Recorder) fetchPlugin(ctx context.Context, auth *coreauth.Auth) (map[string]Window, string, error) { + if r.deps.FetchPlugin == nil { + return nil, "", errors.New("no quota provider") + } + body, err := r.deps.FetchPlugin(ctx, auth) + if err != nil { + return nil, "", errors.New("plugin quota request failed") + } + windows, errParse := parseQuotaGroups(body, false) + return windows, firstString(ojson.ParseBytes(body).Get("subscription.plan")), errParse +} + +// accountValue reads normalized metadata first, then routing attributes and storage. +func accountValue(auth *coreauth.Auth, key string) string { + if value := metadataString(auth, key); value != "" { + return value + } + if value := strings.TrimSpace(auth.Attributes[key]); value != "" { + return value + } + for _, source := range []any{auth.Metadata, auth.Storage} { + doc := ojson.NewDocString(`{}`) + if err := doc.Set("account", source); err == nil { + if value := firstString(doc.Get("account." + key)); value != "" { + return value + } + } + } + return "" +} + +func stableKey(value string) string { + fields := strings.FieldsFunc(strings.ToLower(strings.TrimSpace(value)), func(r rune) bool { + return (r < 'a' || r > 'z') && (r < '0' || r > '9') + }) + return strings.Join(fields, "_") +} + +func indexedKey(value string, index int) string { + if key := stableKey(value); key != "" { + return key + } + return fmt.Sprintf("%d", index) +} diff --git a/internal/quotahistory/providers_test.go b/internal/quotahistory/providers_test.go new file mode 100644 index 00000000000..6b887b6de43 --- /dev/null +++ b/internal/quotahistory/providers_test.go @@ -0,0 +1,277 @@ +package quotahistory + +import ( + "context" + "errors" + "reflect" + "strings" + "testing" + "time" + + "github.com/MoeForge/moego/ojson" + "github.com/rune-oai/t3code-proxy/internal/config" + coreauth "github.com/rune-oai/t3code-proxy/sdk/cliproxy/auth" +) + +func TestRecorderProviderRequestsAndPublication(t *testing.T) { + now := time.Date(2026, 11, 15, 0, 0, 0, 0, time.UTC) + for _, provider := range []string{"xai", "antigravity", "kimi", "kimi-ai", "meta", "devin", "fixture-plugin"} { + t.Run(provider, func(t *testing.T) { + auth := &coreauth.Auth{ID: t.Name(), Index: t.Name(), Provider: provider, Metadata: map[string]any{"project_id": "fixture-project", "dca_token": "dca:fixture", "sub": "fixture-user"}} + if provider == "kimi-ai" { + auth.Metadata["domain"] = "kimi.ai" + } + t.Cleanup(func() { coreauth.ForgetQuotaWindows(auth.ID) }) + fixture := provider + if fixture == "kimi-ai" { + fixture = "kimi" + } + if fixture == "fixture-plugin" { + fixture = "plugin" + } + body := quotaFixture(t, fixture) + var urls []string + deps := Deps{DoRequest: func(ctx context.Context, got *coreauth.Auth, method, url string, headers map[string]string, data []byte) (int, []byte, error) { + if got != auth { + t.Fatal("wrong account") + } + // Each account's sample is bounded so a silent provider cannot stall the recorder. + if deadline, bounded := ctx.Deadline(); !bounded || time.Until(deadline) > sampleTimeout { + t.Fatal("usage sample is not bounded by sampleTimeout") + } + urls = append(urls, url) + switch provider { + case "xai": + if method != "GET" || headers["x-userid"] != "fixture-user" || headers["x-xai-token-auth"] != "xai-grok-cli" { + t.Fatalf("xai request %s %v", method, headers) + } + case "antigravity": + if url == AntigravityCodeAssistURL { + break + } + if method != "POST" || ojson.GetBytes(data, "project").String() != "fixture-project" { + t.Fatalf("antigravity request %s %s", method, data) + } + case "meta": + if method != "POST" || headers["Authorization"] != "Bearer dca:fixture" || string(data) != "{}" { + t.Fatalf("meta request %s %s", method, data) + } + case "devin": + if method != "POST" || ojson.GetBytes(data, "metadata.apiKey").String() != "$TOKEN$" || headers["Connect-Protocol-Version"] != "1" { + t.Fatalf("devin request %s %s", method, data) + } + default: + if method != "GET" || headers["Authorization"] != "Bearer $TOKEN$" { + t.Fatalf("kimi request %s %v", method, headers) + } + } + return 200, body, nil + }, FetchPlugin: func(_ context.Context, got *coreauth.Auth) ([]byte, error) { + if got != auth { + t.Fatal("wrong plugin account") + } + return body, nil + }} + r := NewRecorder(deps) + r.now = func() time.Time { return now } + rec := r.sample(context.Background(), auth) + if rec.Error != "" || len(rec.Windows) == 0 { + t.Fatalf("sample = %+v", rec) + } + expectedURLs := map[string][]string{ + "xai": {XAIWeeklyURL, XAIMonthlyURL, XAISettingsURL, XAIUserURL}, "antigravity": {antigravityQuotaURLs[0], AntigravityCodeAssistURL}, "kimi": {"https://api.kimi.com/coding/v1/usages"}, "kimi-ai": {"https://api.kimi.ai/coding/v1/usages"}, "meta": {MetaUsageURL}, "devin": {DevinUsageURL}, + } + if !reflect.DeepEqual(urls, expectedURLs[provider]) { + t.Fatalf("urls = %v, want %v", urls, expectedURLs[provider]) + } + observed, windows := coreauth.ObservedQuotaWindows(auth.ID) + if !observed.Equal(now) || len(windows) == 0 { + t.Fatalf("observation = %v %+v", observed, windows) + } + }) + } +} + +func TestRecorderProvidersAllowlistReloadAndDisabled(t *testing.T) { + auths := []*coreauth.Auth{ + {ID: "quota-kimi", Index: "quota-kimi", Provider: "kimi"}, + {ID: "quota-meta", Index: "quota-meta", Provider: "meta", Disabled: true}, + {ID: "quota-xai", Index: "quota-xai", Provider: "xai", Status: coreauth.StatusDisabled}, + {ID: "quota-plugin", Index: "quota-plugin", Provider: "fixture-plugin"}, + {ID: "quota-unknown", Index: "quota-unknown", Provider: "unknown"}, + } + r := NewRecorder(Deps{ListAuths: func() []*coreauth.Auth { return auths }, PluginProviders: func(context.Context) map[string]string { return map[string]string{"fixture-plugin": "fixture"} }}) + r.startupDelay = time.Hour + t.Cleanup(r.Close) + s := enabledSettings(t) + if err := r.Apply(s); err != nil { + t.Fatal(err) + } + // Plugins are only asked during a poll; before one, history lists built-in providers. + if got := len(r.accounts()); got != 3 { + t.Fatalf("accounts before the first poll = %d, want 3", got) + } + if targets := r.targets(context.Background()); len(targets) != 2 { + t.Fatalf("targets = %v", targets) + } + if got := len(r.accounts()); got != 4 { + t.Fatalf("accounts = %d, want 4", got) + } + cfg := &config.Config{QuotaHistory: config.QuotaHistoryConfig{Providers: []string{" KIMI ", "meta"}}} + resolved, err := SettingsFromConfig(cfg, "config.yaml") + if err != nil { + t.Fatal(err) + } + if resolved.Providers != "kimi,meta" { + t.Fatalf("providers = %q", resolved.Providers) + } + s.Providers = resolved.Providers + if err := r.Apply(s); err != nil { + t.Fatal(err) + } + if got := len(r.accounts()); got != 2 { + t.Fatalf("restricted accounts = %d, want 2", got) + } + if targets := r.targets(context.Background()); len(targets) != 1 || targets[0].Provider != "kimi" { + t.Fatalf("restricted targets = %v", targets) + } +} + +func TestAntigravityFallbackKeepsPartialPools(t *testing.T) { + auth := &coreauth.Auth{ID: t.Name(), Provider: "antigravity", Metadata: map[string]any{"project_id": "fixture"}} + calls := 0 + r := NewRecorder(Deps{DoRequest: func(_ context.Context, _ *coreauth.Auth, _, url string, _ map[string]string, _ []byte) (int, []byte, error) { + if url != antigravityQuotaURLs[calls] { + t.Fatalf("unexpected URL %s", url) + } + calls++ + switch calls { + case 1: + return 200, []byte(`{"groups":[{"displayName":"Claude Models","buckets":[{"bucketId":"claude-weekly","window":"weekly","remainingFraction":0.5}]}]}`), nil + case 2: + return 503, nil, nil + default: + return 200, quotaFixture(t, "antigravity"), nil + } + }}) + windows, _, err := r.fetchAntigravity(context.Background(), auth) + if err != nil || calls != 3 || len(windows) != 4 || windows["group_claude_models_claude_weekly"].UsedPercent != 50 { + t.Fatalf("fallback = %+v %v, calls %d", windows, err, calls) + } +} + +func TestQuotaErrorsExcludeResponseSecrets(t *testing.T) { + r := NewRecorder(Deps{DoRequest: func(context.Context, *coreauth.Auth, string, string, map[string]string, []byte) (int, []byte, error) { + return 401, []byte(`{"error":{"message":"secret-token"},"api_key":"secret-key"}`), nil + }}) + auth := &coreauth.Auth{ID: t.Name(), Provider: "meta", Metadata: map[string]any{"dca_token": "dca:fixture"}} + rec := r.sample(context.Background(), auth) + if rec.Error != "HTTP 401" { + t.Fatalf("unsafe error %q", rec.Error) + } + r.deps.FetchPlugin = func(context.Context, *coreauth.Auth) ([]byte, error) { return nil, errors.New("secret-token") } + auth.Provider = "fixture-plugin" + rec = r.sample(context.Background(), auth) + if strings.Contains(rec.Error, "secret") { + t.Fatalf("unsafe plugin error %q", rec.Error) + } +} + +func TestRecorderNamesGrokAndAntigravityPlans(t *testing.T) { + now := time.Unix(1_800_000_000, 0) + planCalls := map[string]int{} + planBodies := map[string]string{ + XAISettingsURL: `{"subscription_tier_display":"SuperGrok"}`, + AntigravityCodeAssistURL: `{"currentTier":{"id":"free-tier","name":"Free"},"paidTier":{"id":"g1-pro-tier","name":"Google AI Pro"}}`, + } + r := NewRecorder(Deps{DoRequest: func(_ context.Context, auth *coreauth.Auth, _, url string, _ map[string]string, _ []byte) (int, []byte, error) { + if body, ok := planBodies[url]; ok { + planCalls[url]++ + return 200, []byte(body), nil + } + return 200, quotaFixture(t, auth.Provider), nil + }}) + r.now = func() time.Time { return now } + xai := &coreauth.Auth{ID: t.Name() + "-xai", Index: t.Name() + "-xai", Provider: "xai", Metadata: map[string]any{"access_token": "fixture"}} + antigravity := &coreauth.Auth{ID: t.Name() + "-ag", Index: t.Name() + "-ag", Provider: "antigravity", Metadata: map[string]any{"project_id": "fixture-project"}} + for auth, want := range map[*coreauth.Auth]string{xai: "SuperGrok", antigravity: "pro"} { + if rec := r.sample(context.Background(), auth); rec.Error != "" || rec.Plan != want { + t.Fatalf("%s sample plan = %q (error %q), want %q", auth.Provider, rec.Plan, rec.Error, want) + } + if got := coreauth.PlanOf(auth); got != config.NormalizePlanKey(want) { + t.Fatalf("%s routing plan = %q, want %q", auth.Provider, got, config.NormalizePlanKey(want)) + } + } + + // The plan endpoints are asked once per profileTTL, not on every poll. + now = now.Add(profileTTL - time.Minute) + for _, auth := range []*coreauth.Auth{xai, antigravity} { + if rec := r.sample(context.Background(), auth); rec.Plan == "" { + t.Fatalf("%s lost its cached plan", auth.Provider) + } + } + if planCalls[XAISettingsURL] != 1 || planCalls[AntigravityCodeAssistURL] != 1 { + t.Fatalf("plan requests = %v, want one each", planCalls) + } + + // A failing plan endpoint keeps the known plan. + now = now.Add(2 * time.Minute) + planBodies[XAISettingsURL] = `{}` + if rec := r.sample(context.Background(), xai); rec.Plan != "SuperGrok" { + t.Fatalf("plan after an empty refresh = %q, want SuperGrok", rec.Plan) + } +} + +func TestRecorderRetriesAnUnknownPlanOnTheNextPoll(t *testing.T) { + now := time.Unix(1_800_000_000, 0) + settingsStatus, settingsCalls, userCalls := 503, 0, 0 + r := NewRecorder(Deps{DoRequest: func(_ context.Context, auth *coreauth.Auth, _, url string, _ map[string]string, _ []byte) (int, []byte, error) { + switch url { + case XAISettingsURL: + settingsCalls++ + return settingsStatus, []byte(`{"subscription_tier_display":"SuperGrok Heavy"}`), nil + case XAIUserURL: + userCalls++ + return 200, []byte(`{"subscriptionTier":"GrokPro"}`), nil + } + return 200, quotaFixture(t, auth.Provider), nil + }}) + r.now = func() time.Time { return now } + xai := &coreauth.Auth{ID: t.Name(), Index: t.Name(), Provider: "xai", Metadata: map[string]any{"access_token": "fixture"}} + + // A failed settings request leaves the plan unknown instead of storing the internal + // tier, which no plan weight is keyed by. + if rec := r.sample(context.Background(), xai); rec.Error != "" || rec.Plan != "" { + t.Fatalf("sample with settings down = plan %q, error %q; want no plan", rec.Plan, rec.Error) + } + if userCalls != 0 { + t.Fatalf("user endpoint asked %d times after a failed settings request, want 0", userCalls) + } + + // The next poll asks again instead of waiting out profileTTL. + now = now.Add(15 * time.Minute) + settingsStatus = 200 + if rec := r.sample(context.Background(), xai); rec.Plan != "SuperGrok Heavy" { + t.Fatalf("plan on the next poll = %q, want SuperGrok Heavy", rec.Plan) + } + if settingsCalls != 2 { + t.Fatalf("settings asked %d times, want 2", settingsCalls) + } + if got := coreauth.PlanWeightOf(xai); got != 10 { + t.Fatalf("routing weight = %v, want 10", got) + } +} + +func TestParseAntigravityPlan(t *testing.T) { + for body, want := range map[string]string{ + `{"currentTier":{"id":"free-tier"}}`: "free", + `{"paid_tier":{"id":"g1-ultra-tier"},"current_tier":{"id":"free-tier"}}`: "ultra", + `{"currentTier":{"id":"new-tier","name":"Google AI Next"}}`: "Google AI Next", + `{"currentTier":{"id":"new-tier"}}`: "new-tier", + `{}`: "", + } { + if got := parseAntigravityPlan([]byte(body)); got != want { + t.Fatalf("parseAntigravityPlan(%s) = %q, want %q", body, got, want) + } + } +} diff --git a/internal/quotahistory/recorder.go b/internal/quotahistory/recorder.go index 6b302ea9e3b..9f8a9b80aba 100644 --- a/internal/quotahistory/recorder.go +++ b/internal/quotahistory/recorder.go @@ -4,13 +4,13 @@ import ( "context" "errors" "fmt" + "net/url" "sort" "strings" "sync" "sync/atomic" "time" - "github.com/MoeForge/moego/ojson" coreauth "github.com/rune-oai/t3code-proxy/sdk/cliproxy/auth" log "github.com/sirupsen/logrus" ) @@ -41,15 +41,15 @@ func codexHeaders() map[string]string { } const ( - requestTimeout = 20 * time.Second - defaultScheduledGap = 3 * time.Second - defaultManualGap = 500 * time.Millisecond - defaultStartupDelay = 30 * time.Second - minPollSpacing = time.Minute - pruneEvery = time.Hour - profileTTL = 6 * time.Hour - planSeedRecords = 5000 - maxErrorMessageBytes = 200 + // sampleTimeout bounds one account's usage reads (see AGENTS.md exceptions). + sampleTimeout = 45 * time.Second + defaultScheduledGap = 3 * time.Second + defaultManualGap = 500 * time.Millisecond + defaultStartupDelay = 30 * time.Second + minPollSpacing = time.Minute + pruneEvery = time.Hour + profileTTL = 6 * time.Hour + planSeedRecords = 5000 // MaxSamplesPerAccount caps how many samples one account contributes to a // History response; denser ranges are downsampled evenly. @@ -72,6 +72,13 @@ type Deps struct { ListAuths func() []*coreauth.Auth // Do sends an authenticated request. Do Doer + // DoRequest supports provider requests with JSON bodies. Do remains a GET fallback. + DoRequest func(context.Context, *coreauth.Auth, string, string, map[string]string, []byte) (int, []byte, error) + // PluginProviders lists providers served by registered quota plugins. + // The context ends when the recorder stops. + PluginProviders func(context.Context) map[string]string + // FetchPlugin uses the host's per-account quota capability and transport. + FetchPlugin func(context.Context, *coreauth.Auth) ([]byte, error) // Label returns the display label of a credential (optional). Label func(*coreauth.Auth) string } @@ -82,7 +89,9 @@ type Account struct { Provider string `json:"provider"` Label string `json:"label"` Plan string `json:"plan"` - Disabled bool `json:"disabled"` + // Weight is the plan capacity routing uses for this account (1 = base plan). + Weight float64 `json:"weight"` + Disabled bool `json:"disabled"` } // History is the GET /quota-history response. @@ -119,7 +128,10 @@ type Recorder struct { manualMu sync.Mutex manual *manualPoll - pollMu sync.Mutex + pollMu sync.Mutex + providers atomic.Value // normalized comma-separated provider allowlist + // pluginIDs is the last plugin discovery; nil until the first poll. + pluginIDs atomic.Pointer[map[string]string] plansMu sync.Mutex plans map[string]string @@ -154,11 +166,16 @@ func (r *Recorder) Apply(s Settings) error { } r.stopLocked() r.settings = s + r.providers.Store(s.Providers) + r.forgetUntracked(s.Enabled) + r.pluginIDs.Store(nil) if !s.Enabled { return nil } store, errOpen := OpenStore(s.Path) if errOpen != nil { + // Nothing will poll, so no reading may keep steering routing. + r.forgetUntracked(false) return errOpen } r.plansMu.Lock() @@ -170,6 +187,12 @@ func (r *Recorder) Apply(s Settings) error { r.plansMu.Unlock() r.store = store r.ctx, r.cancel = context.WithCancel(context.Background()) + // Routing learns stored plans now instead of after the first poll. + for _, auth := range r.trackable(nil) { + if plan := r.plan(auth.Index); plan != "" && providerOf(auth) != "mistral" { + coreauth.ObserveAuthPlan(auth.ID, plan) + } + } r.wg.Add(1) go r.run(r.ctx, store, s) log.Infof("quota-history: recording every %s to %s (retention %s)", s.Interval, s.Path, s.Retention) @@ -306,7 +329,7 @@ func (r *Recorder) poll(ctx context.Context, store *Store, gap time.Duration, co r.pollMu.Lock() defer r.pollMu.Unlock() stored := 0 - for i, auth := range r.targets() { + for i, auth := range r.targets(ctx) { if i > 0 && gap > 0 { t := time.NewTimer(gap) select { @@ -319,6 +342,12 @@ func (r *Recorder) poll(ctx context.Context, store *Store, gap time.Duration, co if ctx.Err() != nil { return stored } + // The target list was taken when the round started. Read the account + // again so one disabled or removed meanwhile is not polled, and a token + // refresh does not write back a stale copy. + if auth = r.current(auth.ID); auth == nil || isDisabled(auth) { + continue + } rec := r.sample(ctx, auth) if ctx.Err() != nil { // Shutting down or reconfiguring: do not record a cancellation as an error. @@ -337,40 +366,72 @@ func (r *Recorder) poll(ctx context.Context, store *Store, gap time.Duration, co } func (r *Recorder) sample(ctx context.Context, auth *coreauth.Auth) record { - reqCtx, cancel := context.WithTimeout(ctx, requestTimeout) + // One provider that accepts the connection and never answers must not stop + // recording for every other account. + ctx, cancel := context.WithTimeout(ctx, sampleTimeout) defer cancel() rec := record{Sample: Sample{T: r.now().UnixMilli(), AuthIndex: auth.Index, Windows: map[string]Window{}}} - var windows map[string]Window - var errFetch error - switch providerOf(auth) { - case "claude": - windows, errFetch = r.fetchClaude(reqCtx, auth) - if errFetch == nil { - rec.Plan = r.claudePlan(reqCtx, auth) - } - case "codex": - var plan string - windows, plan, errFetch = r.fetchCodex(reqCtx, auth) - if plan == "" { - plan = metadataString(auth, "plan_type") - } - if plan != "" { - r.setPlan(auth.Index, plan) - } - rec.Plan = plan + poll := providerPollers[providerOf(auth)] + if poll == nil { + poll = (*Recorder).fetchPlugin } + windows, plan, errFetch := poll(r, ctx, auth) if errFetch != nil { rec.Error = errFetch.Error() log.Debugf("quota-history: %s auth %s: %s", providerOf(auth), auth.Index, rec.Error) return rec } rec.Windows = windows + rec.Plan = plan + if plan != "" { + r.setPlan(auth.Index, plan) + } + // Mistral's API and Vibe budgets fund separate request types. History keeps + // both allowances, while account-wide routing cannot identify which applies. + if providerOf(auth) == "mistral" { + return rec + } + r.publishRouting(auth, plan, windows, time.UnixMilli(rec.T)) + observations := make([]coreauth.QuotaWindow, 0, len(windows)) + for key, window := range windows { + // A usage figure the parser had to assume is charted but does not steer routing. + if window.ResetsAt == nil || window.PeriodHours <= 0 || window.estimated { + continue + } + scope := window.modelScope + if family, scoped := strings.CutPrefix(key, WindowSevenDay+"_"); providerOf(auth) == "claude" && scoped { + scope = []string{"*-" + family + "-*", "*-" + family} + } + observations = append(observations, coreauth.QuotaWindow{Key: key, UsedPercent: window.UsedPercent, + ResetAt: time.UnixMilli(*window.ResetsAt), Period: time.Duration(window.PeriodHours * float64(time.Hour)), ModelScope: scope}) + } + coreauth.ObserveQuotaWindows(auth.ID, time.UnixMilli(rec.T), observations) if providerOf(auth) == "claude" { coreauth.ObserveScopedWeeklyWindows(auth.ID, time.UnixMilli(rec.T), scopedWeeklyWindows(windows)) } return rec } +// publishRouting hands routing the plan and 5-hour reading of one account, so +// plan weights and the headroom guard use what the recorder already fetched. +func (r *Recorder) publishRouting(auth *coreauth.Auth, plan string, windows map[string]Window, observedAt time.Time) { + if plan == "" { + plan = r.plan(auth.Index) + } + if plan != "" { + coreauth.ObserveAuthPlan(auth.ID, plan) + } + window, ok := windows[WindowFiveHour] + if !ok || window.estimated { + return + } + var resetAt time.Time + if window.ResetsAt != nil && *window.ResetsAt > 0 { + resetAt = time.UnixMilli(*window.ResetsAt) + } + coreauth.ObserveShortWindowUsage(auth.ID, observedAt, window.UsedPercent, resetAt) +} + // scopedWeeklyWindows extracts the model-scoped weekly caps ("seven_day_") // keyed by family token, for the soonest-reset-first selector. func scopedWeeklyWindows(windows map[string]Window) map[string]coreauth.ScopedWeeklyWindow { @@ -398,6 +459,20 @@ func (r *Recorder) fetchClaude(ctx context.Context, auth *coreauth.Auth) (map[st // claudePlan returns the cached plan and refreshes it from the profile endpoint // at most once per profileTTL. func (r *Recorder) claudePlan(ctx context.Context, auth *coreauth.Auth) string { + return r.cachedPlan(auth, func() string { + body, errDo := r.get(ctx, auth, ClaudeProfileURL, claudeHeaders()) + if errDo != nil { + return "" + } + return ParseClaudePlan(body) + }) +} + +// cachedPlan returns the plan last learned for an account and asks fetch for a +// fresh one at most once per profileTTL. A failed or empty fetch keeps the +// stored plan, so an outage of the plan endpoint does not erase a known plan. +// While no plan is known at all, the fetch is retried on the next poll. +func (r *Recorder) cachedPlan(auth *coreauth.Auth, fetch func() string) string { r.plansMu.Lock() plan := r.plans[auth.Index] last := r.profileAttempts[auth.Index] @@ -409,13 +484,14 @@ func (r *Recorder) claudePlan(ctx context.Context, auth *coreauth.Auth) string { if !due { return plan } - body, errDo := r.get(ctx, auth, ClaudeProfileURL, claudeHeaders()) - if errDo != nil { - return plan + if fetched := strings.TrimSpace(fetch()); fetched != "" { + r.setPlan(auth.Index, fetched) + return fetched } - if parsed := ParseClaudePlan(body); parsed != "" { - r.setPlan(auth.Index, parsed) - return parsed + if plan == "" { + r.plansMu.Lock() + delete(r.profileAttempts, auth.Index) + r.plansMu.Unlock() } return plan } @@ -435,31 +511,31 @@ func (r *Recorder) fetchCodex(ctx context.Context, auth *coreauth.Auth) (map[str } func (r *Recorder) get(ctx context.Context, auth *coreauth.Auth, url string, header map[string]string) ([]byte, error) { - if r.deps.Do == nil { + return r.request(ctx, auth, "GET", url, header, nil) +} + +func (r *Recorder) request(ctx context.Context, auth *coreauth.Auth, method, url string, header map[string]string, data []byte) ([]byte, error) { + var status int + var body []byte + var errDo error + if r.deps.DoRequest != nil { + status, body, errDo = r.deps.DoRequest(ctx, auth, method, url, header, data) + } else if r.deps.Do != nil && len(data) == 0 { + status, body, errDo = r.deps.Do(ctx, auth, method, url, header) + } else { return nil, errors.New("no request transport") } - status, body, errDo := r.deps.Do(ctx, auth, "GET", url, header) if errDo != nil { return nil, errDo } if status < 200 || status >= 300 { - return nil, statusError(status, body) + // Usage responses can echo credentials or personal data. Keep errors bounded + // to the status code for both storage and logs. + return nil, fmt.Errorf("HTTP %d", status) } return body, nil } -func statusError(status int, body []byte) error { - root := ojson.ParseBytes(body) - msg := firstString(root.Get("error.message"), root.Get("error"), root.Get("message"), root.Get("detail")) - if len(msg) > maxErrorMessageBytes { - msg = msg[:maxErrorMessageBytes] - } - if msg == "" { - return fmt.Errorf("HTTP %d", status) - } - return fmt.Errorf("HTTP %d: %s", status, msg) -} - func (r *Recorder) setPlan(authIndex, plan string) { r.plansMu.Lock() r.plans[authIndex] = plan @@ -551,29 +627,35 @@ func downsample(samples []Sample, max int) []Sample { return out } -// accounts lists every Claude/Codex OAuth credential, including disabled ones. +// accounts lists supported subscription credentials, including disabled ones. func (r *Recorder) accounts() []Account { out := []Account{} - for _, auth := range r.trackable() { + for _, auth := range r.trackable(r.pluginProviders(context.Background(), false)) { plan := r.plan(auth.Index) - if plan == "" && providerOf(auth) == "codex" { - plan = metadataString(auth, "plan_type") + if plan == "" { + plan = coreauth.PlanOf(auth) + } + weight := 1.0 + if providerOf(auth) != "mistral" { + weight = coreauth.PlanWeight(providerOf(auth), plan) } out = append(out, Account{ AuthIndex: auth.Index, Provider: providerOf(auth), Label: r.label(auth), Plan: plan, + Weight: weight, Disabled: isDisabled(auth), }) } return out } -// targets lists the credentials polled this round. -func (r *Recorder) targets() []*coreauth.Auth { +// targets lists the credentials polled this round and refreshes the list of +// quota-plugin providers. +func (r *Recorder) targets(ctx context.Context) []*coreauth.Auth { var out []*coreauth.Auth - for _, auth := range r.trackable() { + for _, auth := range r.trackable(r.pluginProviders(ctx, true)) { if !isDisabled(auth) { out = append(out, auth) } @@ -581,19 +663,95 @@ func (r *Recorder) targets() []*coreauth.Auth { return out } -func (r *Recorder) trackable() []*coreauth.Auth { +// pluginProviders returns the providers served by quota plugins. Only polls +// ask the plugins, with the recorder's context, so a slow plugin cannot +// outlive a shutdown or hold up a history request; history requests reuse the +// last list, which is empty until the first poll. Plugins are not asked at all +// when the provider allowlist names only built-in providers. +func (r *Recorder) pluginProviders(ctx context.Context, refresh bool) map[string]string { + if r.deps.PluginProviders == nil { + return nil + } + if !refresh { + if cached := r.pluginIDs.Load(); cached != nil { + return *cached + } + return nil + } + providers, _ := r.providers.Load().(string) + wanted := providers == "" + for _, name := range strings.Split(providers, ",") { + wanted = wanted || (name != "" && providerPollers[name] == nil) + } + found := map[string]string{} + if wanted { + for provider, id := range r.deps.PluginProviders(ctx) { + found[provider] = id + } + } + r.pluginIDs.Store(&found) + return found +} + +// forgetUntracked drops the routing readings of accounts the recorder no +// longer polls, because the recorder was turned off or the provider left the +// allowlist. Otherwise a last "spent" reading would keep steering routing until +// its window resets. +func (r *Recorder) forgetUntracked(enabled bool) { + if r.deps.ListAuths == nil { + return + } + tracked := make(map[string]bool) + if enabled { + // The last plugin list keeps plugin-provider accounts tracked across a + // settings change; trackable applies the new allowlist to them. + for _, auth := range r.trackable(r.pluginProviders(context.Background(), false)) { + tracked[auth.ID] = true + } + } + for _, auth := range r.deps.ListAuths() { + if auth == nil || tracked[auth.ID] { + continue + } + coreauth.ForgetQuotaWindows(auth.ID) + coreauth.ForgetScopedWeeklyWindows(auth.ID) + coreauth.ForgetShortWindowUsage(auth.ID) + // The plan falls back to response headers and the credential's own fields. + coreauth.ObserveAuthPlan(auth.ID, "") + } +} + +// current returns the live copy of an account, or nil when it is gone. +func (r *Recorder) current(id string) *coreauth.Auth { + if r.deps.ListAuths == nil { + return nil + } + for _, auth := range r.deps.ListAuths() { + if auth != nil && auth.ID == id { + return auth + } + } + return nil +} + +func (r *Recorder) trackable(plugins map[string]string) []*coreauth.Auth { if r.deps.ListAuths == nil { return nil } var out []*coreauth.Auth + providers, _ := r.providers.Load().(string) for _, auth := range r.deps.ListAuths() { if auth == nil { continue } - if p := providerOf(auth); p != "claude" && p != "codex" { + p := providerOf(auth) + if providerPollers[p] == nil && plugins[p] == "" { continue } - if auth.AuthKind() == coreauth.AuthKindAPIKey { + if providers != "" && !strings.Contains(","+providers+",", ","+p+",") { + continue + } + if auth.AuthKind() == coreauth.AuthKindAPIKey && (p == "claude" || p == "codex" || p == "xai") { continue } if auth.EnsureIndex() == "" { @@ -611,6 +769,12 @@ func (r *Recorder) trackable() []*coreauth.Auth { } func (r *Recorder) label(auth *coreauth.Auth) string { + if providerOf(auth) == "mistral" { + if name := strings.TrimSpace(auth.Attributes["compat_name"]); name != "" { + return name + } + return "Mistral" + } if r.deps.Label != nil { if label := strings.TrimSpace(r.deps.Label(auth)); label != "" { return label @@ -629,7 +793,19 @@ func (r *Recorder) label(auth *coreauth.Auth) string { } func providerOf(auth *coreauth.Auth) string { - return strings.ToLower(strings.TrimSpace(auth.Provider)) + if auth.AuthKind() == coreauth.AuthKindAPIKey { + base, err := url.Parse(strings.TrimSpace(auth.Attributes["base_url"])) + if err == nil && strings.EqualFold(base.Hostname(), "api.mistral.ai") { + return "mistral" + } + } + provider := strings.ToLower(strings.TrimSpace(auth.Provider)) + // The billing poller requires Mistral's own host and an API key, even when + // another upstream happens to use the same provider name. + if provider == "mistral" { + return "" + } + return provider } func isDisabled(auth *coreauth.Auth) bool { diff --git a/internal/quotahistory/recorder_test.go b/internal/quotahistory/recorder_test.go index f0d50567964..80af7520604 100644 --- a/internal/quotahistory/recorder_test.go +++ b/internal/quotahistory/recorder_test.go @@ -170,7 +170,7 @@ func TestRecorderRefreshAndHistory(t *testing.T) { samples[s["auth_index"].(string)] = s } broken := samples["claude-broken"] - if broken["error"] != "HTTP 401: token expired" || fmt.Sprint(broken["windows"]) != "map[]" { + if broken["error"] != "HTTP 401" || fmt.Sprint(broken["windows"]) != "map[]" { t.Fatalf("error sample = %v", broken) } windows := samples["claude-ok"]["windows"].(map[string]any) diff --git a/internal/quotahistory/scoped_publish_test.go b/internal/quotahistory/scoped_publish_test.go index 8bfbd088245..c3f7463b750 100644 --- a/internal/quotahistory/scoped_publish_test.go +++ b/internal/quotahistory/scoped_publish_test.go @@ -31,7 +31,9 @@ func TestRecorderPublishesSpentFableCapToSelector(t *testing.T) { spent := &coreauth.Auth{ID: "qh-scoped-spent", Index: "qh-scoped-spent", Provider: "claude", Metadata: map[string]any{"access_token": "a"}} open := &coreauth.Auth{ID: "qh-scoped-open", Index: "qh-scoped-open", Provider: "claude", Metadata: map[string]any{"access_token": "b"}} t.Cleanup(func() { + coreauth.ForgetQuotaWindows(spent.ID) coreauth.ForgetScopedWeeklyWindows(spent.ID) + coreauth.ForgetQuotaWindows(open.ID) coreauth.ForgetScopedWeeklyWindows(open.ID) }) r := NewRecorder(Deps{Do: func(_ context.Context, auth *coreauth.Auth, _, url string, _ map[string]string) (int, []byte, error) { @@ -39,11 +41,13 @@ func TestRecorderPublishesSpentFableCapToSelector(t *testing.T) { return 404, nil, nil } used := 20 + overallReset := now.Add(5 * 24 * time.Hour) if auth.ID == spent.ID { used = 100 + overallReset = now.Add(24 * time.Hour) } return 200, []byte(fmt.Sprintf(`{"seven_day":{"utilization":10,"resets_at":%q},"limits":[{"kind":"weekly_scoped","scope":{"model":{"display_name":"Fable"}},"percent":%d,"resets_at":%q,"is_active":true}]}`, - now.Add(5*24*time.Hour).UTC().Format(time.RFC3339), used, fableReset)), nil + overallReset.UTC().Format(time.RFC3339), used, fableReset)), nil }}) r.now = func() time.Time { return now } for _, auth := range []*coreauth.Auth{spent, open} { @@ -62,3 +66,131 @@ func TestRecorderPublishesSpentFableCapToSelector(t *testing.T) { } } } + +// The recorder hands routing each account's plan and 5-hour reading, and the +// account list reports the resulting plan weight. +func TestRecorderPublishesPlanAndShortWindowToRouting(t *testing.T) { + now := time.Unix(1_800_000_000, 0) + codex := &coreauth.Auth{ID: "qh-plan-codex", Index: "qh-plan-codex", Provider: "codex", Metadata: map[string]any{"access_token": "a"}} + claude := &coreauth.Auth{ID: "qh-plan-claude", Index: "qh-plan-claude", Provider: "claude", Metadata: map[string]any{"access_token": "b"}} + t.Cleanup(func() { + for _, auth := range []*coreauth.Auth{codex, claude} { + coreauth.ObserveAuthPlan(auth.ID, "") + coreauth.ForgetShortWindowUsage(auth.ID) + coreauth.ForgetQuotaWindows(auth.ID) + coreauth.ForgetScopedWeeklyWindows(auth.ID) + } + }) + request := func(_ context.Context, _ *coreauth.Auth, _, url string, _ map[string]string, _ []byte) (int, []byte, error) { + switch url { + case CodexUsageURL: + return 200, []byte(`{"plan_type":"pro","rate_limit":{"primary_window":{"used_percent":40,"limit_window_seconds":18000,"reset_after_seconds":3600}}}`), nil + case ClaudeUsageURL: + return 200, []byte(`{"five_hour":{"utilization":10,"resets_at":"2027-01-15T10:00:00Z"}}`), nil + case ClaudeProfileURL: + return 200, []byte(`{"organization":{"rate_limit_tier":"default_claude_max_20x"}}`), nil + } + return 404, nil, nil + } + r := NewRecorder(Deps{DoRequest: request, ListAuths: func() []*coreauth.Auth { return []*coreauth.Auth{codex, claude} }}) + r.now = func() time.Time { return now } + for _, auth := range []*coreauth.Auth{codex, claude} { + if rec := r.sample(context.Background(), auth); rec.Error != "" { + t.Fatalf("sample %s: %s", auth.ID, rec.Error) + } + } + if got := coreauth.PlanOf(codex); got != "pro" { + t.Fatalf("codex plan = %q, want pro", got) + } + if got := coreauth.PlanOf(claude); got != "max_20x" { + t.Fatalf("claude plan = %q, want max_20x", got) + } + weights := map[string]float64{} + for _, account := range r.accounts() { + weights[account.AuthIndex] = account.Weight + } + if weights[codex.Index] != coreauth.PlanWeight("codex", "pro") || weights[claude.Index] != 20 { + t.Fatalf("account weights = %v", weights) + } +} + +// An account disabled after the round's target list was taken is not polled, +// and a Codex "limit reached" reading without percentages is charted but does +// not tell routing that both windows are spent. +func TestPollRereadsAccountsAndKeepsEstimatesOutOfRouting(t *testing.T) { + now := time.Unix(1_800_000_000, 0) + first := &coreauth.Auth{ID: "qh-live-first", Index: "qh-live-first", Provider: "codex", Metadata: map[string]any{"access_token": "a"}} + second := &coreauth.Auth{ID: "qh-live-second", Index: "qh-live-second", Provider: "codex", Metadata: map[string]any{"access_token": "b"}} + t.Cleanup(func() { + for _, auth := range []*coreauth.Auth{first, second} { + coreauth.ObserveAuthPlan(auth.ID, "") + coreauth.ForgetShortWindowUsage(auth.ID) + coreauth.ForgetQuotaWindows(auth.ID) + } + }) + var polled []string + request := func(_ context.Context, auth *coreauth.Auth, _, _ string, _ map[string]string, _ []byte) (int, []byte, error) { + polled = append(polled, auth.ID) + // Reading the first account is when the second one gets disabled. + second.Disabled = true + return 200, []byte(`{"plan_type":"plus","rate_limit":{"limit_reached":true,"primary_window":{"limit_window_seconds":18000,"reset_after_seconds":600},"secondary_window":{"limit_window_seconds":604800,"reset_after_seconds":86400}}}`), nil + } + r := NewRecorder(Deps{DoRequest: request, ListAuths: func() []*coreauth.Auth { return []*coreauth.Auth{first, second} }}) + r.now = func() time.Time { return now } + r.manualGap = 0 + t.Cleanup(r.Close) + if err := r.Apply(enabledSettings(t)); err != nil { + t.Fatal(err) + } + if stored := r.poll(context.Background(), r.store, 0, nil); stored != 1 || len(polled) != 1 || polled[0] != first.ID { + t.Fatalf("stored %d, polled %v; want only the first account", stored, polled) + } + history, err := r.History(0, 0) + if err != nil || len(history.Samples) != 1 || history.Samples[0].Windows[WindowSevenDay].UsedPercent != 100 { + t.Fatalf("history = %+v, %v; want the assumed 100%% charted", history.Samples, err) + } + if _, windows := coreauth.ObservedQuotaWindows(first.ID); len(windows) != 0 { + t.Fatalf("routing received assumed windows: %+v", windows) + } +} + +// Readings of accounts the recorder stops polling are dropped from routing, +// both when a provider leaves the allowlist and when the recorder is turned off. +func TestApplyForgetsReadingsOfUntrackedAccounts(t *testing.T) { + now := time.Unix(1_800_000_000, 0) + xai := &coreauth.Auth{ID: "qh-forget-xai", Index: "qh-forget-xai", Provider: "xai", Metadata: map[string]any{"access_token": "a"}} + codex := &coreauth.Auth{ID: "qh-forget-codex", Index: "qh-forget-codex", Provider: "codex", Metadata: map[string]any{"access_token": "b"}} + spent := []coreauth.QuotaWindow{{Key: "weekly", UsedPercent: 100, ResetAt: now.Add(48 * time.Hour), Period: 168 * time.Hour}} + observe := func() { + coreauth.ObserveQuotaWindows(xai.ID, now, spent) + coreauth.ObserveQuotaWindows(codex.ID, now, spent) + } + count := func(id string) int { + _, windows := coreauth.ObservedQuotaWindows(id) + return len(windows) + } + t.Cleanup(func() { + coreauth.ForgetQuotaWindows(xai.ID) + coreauth.ForgetQuotaWindows(codex.ID) + }) + r := NewRecorder(Deps{ListAuths: func() []*coreauth.Auth { return []*coreauth.Auth{xai, codex} }}) + r.startupDelay = time.Hour + t.Cleanup(r.Close) + s := enabledSettings(t) + + observe() + s.Providers = "codex" + if err := r.Apply(s); err != nil { + t.Fatal(err) + } + if count(xai.ID) != 0 || count(codex.ID) != 1 { + t.Fatalf("after narrowing the allowlist: xai %d, codex %d; want 0 and 1", count(xai.ID), count(codex.ID)) + } + s.Enabled = false + if err := r.Apply(s); err != nil { + t.Fatal(err) + } + if count(codex.ID) != 0 { + t.Fatalf("after turning the recorder off: codex %d; want 0", count(codex.ID)) + } +} diff --git a/internal/quotahistory/settings.go b/internal/quotahistory/settings.go index 402c5474756..d1a4194f294 100644 --- a/internal/quotahistory/settings.go +++ b/internal/quotahistory/settings.go @@ -1,4 +1,4 @@ -// Package quotahistory records the remaining quota of Claude and Codex OAuth +// Package quotahistory records the remaining quota of subscription // credentials over time so the management panel can chart and project it. // // When quota-history.enabled is false nothing is polled, opened or written. @@ -7,6 +7,7 @@ package quotahistory import ( "fmt" "path/filepath" + "sort" "strconv" "strings" "time" @@ -35,6 +36,8 @@ type Settings struct { Interval time.Duration Retention time.Duration Path string + // Providers is the normalized comma-separated allowlist. Empty enables all. + Providers string } // SettingsFromConfig resolves the quota-history section of cfg. Invalid or @@ -48,6 +51,14 @@ func SettingsFromConfig(cfg *config.Config, configFilePath string) (Settings, er } qh := cfg.QuotaHistory s.Enabled = qh.Enabled + providers := make([]string, 0, len(qh.Providers)) + for _, provider := range qh.Providers { + if provider = strings.ToLower(strings.TrimSpace(provider)); provider != "" { + providers = append(providers, provider) + } + } + sort.Strings(providers) + s.Providers = strings.Join(providers, ",") if d, ok := parseDuration(qh.Interval); ok { s.Interval = d } else if strings.TrimSpace(qh.Interval) != "" { diff --git a/internal/quotahistory/testdata/antigravity.json b/internal/quotahistory/testdata/antigravity.json new file mode 100644 index 00000000000..c360976ef67 --- /dev/null +++ b/internal/quotahistory/testdata/antigravity.json @@ -0,0 +1,14 @@ +{ + "groups": [ + {"displayName": "Gemini Models", "buckets": [ + {"bucketId": "gemini-weekly", "window": "weekly", "remainingFraction": "0.25", "resetTime": "2026-11-20T00:00:00.123456789Z"}, + {"bucket_id": "gemini-5h", "window": "five_hour", "remaining_fraction": 70, "reset_time": "2026-11-15T04:00:00Z"} + ]}, + {"display_name": "Claude Models", "buckets": [ + {"bucketId": "claude-weekly", "window": "week", "remainingFraction": 0, "resetTime": "2026-11-19T00:00:00Z"} + ]}, + {"displayName": "Unknown Pool", "buckets": [ + {"bucketId": "opaque", "window": "unknown", "remainingFraction": 1} + ]} + ] +} diff --git a/internal/quotahistory/testdata/devin.json b/internal/quotahistory/testdata/devin.json new file mode 100644 index 00000000000..92c5c02ef8d --- /dev/null +++ b/internal/quotahistory/testdata/devin.json @@ -0,0 +1,9 @@ +{ + "userStatus": {"planStatus": { + "planInfo": {"planName": "Fixture Pro"}, + "dailyQuotaRemainingPercent": "54", + "weeklyQuotaRemainingPercent": 77, + "dailyQuotaResetAtUnix": "1794787200", + "weeklyQuotaResetAtUnix": 1795132800 + }} +} diff --git a/internal/quotahistory/testdata/kimi.json b/internal/quotahistory/testdata/kimi.json new file mode 100644 index 00000000000..d3220fe45c0 --- /dev/null +++ b/internal/quotahistory/testdata/kimi.json @@ -0,0 +1,9 @@ +{ + "limits": [ + {"name": "Session", "window": {"duration": "300", "timeUnit": "TIME_UNIT_MINUTE"}, "detail": {"limit": "100", "remaining": 40, "reset_in": "3600"}}, + {"scope": "daily", "detail": {"limit": 100, "used": 20, "resetAt": "2026-11-16T00:00:00Z"}}, + {"window": {"duration": 1, "timeUnit": "TIME_UNIT_WEEK"}, "detail": {"limit": 100, "used": 10, "reset_time": 1795132800000}} + ], + "usage": {"limit": 1000, "used": "500", "reset_time": "2026-11-20T00:00:00Z"}, + "usages": {"limit_month_total": {"used_ratio": "0.75", "reset_time": "2026-12-01T00:00:00Z"}} +} diff --git a/internal/quotahistory/testdata/meta.json b/internal/quotahistory/testdata/meta.json new file mode 100644 index 00000000000..2a0da2204d4 --- /dev/null +++ b/internal/quotahistory/testdata/meta.json @@ -0,0 +1,8 @@ +{ + "api_key": "fixture-secret-do-not-retain", + "subs_tier_name": "Muse Code Everyday Usage", + "subs_usage": { + "window": {"used_percent": "2", "window_duration_mins": "300", "resets_at": 1794726000}, + "weekly": {"used_percent": 65, "resets_at": 1795132800} + } +} diff --git a/internal/quotahistory/testdata/plugin.json b/internal/quotahistory/testdata/plugin.json new file mode 100644 index 00000000000..d8a042b4733 --- /dev/null +++ b/internal/quotahistory/testdata/plugin.json @@ -0,0 +1,7 @@ +{ + "subscription": {"plan": "Fixture Plan"}, + "groups": [{"displayName": "Account", "buckets": [ + {"window": "weekly", "remainingFraction": 0.25, "resetTime": "2026-11-20T00:00:00Z"}, + {"window": "5h", "remainingFraction": 0.5, "resetTime": "2026-11-15T04:00:00Z"} + ]}] +} diff --git a/internal/quotahistory/testdata/xai.json b/internal/quotahistory/testdata/xai.json new file mode 100644 index 00000000000..30dc1b1455f --- /dev/null +++ b/internal/quotahistory/testdata/xai.json @@ -0,0 +1,10 @@ +{ + "config": { + "creditUsagePercent": "25", + "currentPeriod": {"type": "weekly", "start": "2026-11-13T00:00:00Z", "end": "2026-11-20T00:00:00Z"}, + "monthlyLimit": {"val": 10000}, + "used": {"val": 4500}, + "billingPeriodStart": "2026-11-01T00:00:00Z", + "billingPeriodEnd": "2026-12-01T00:00:00Z" + } +} diff --git a/scripts/migrate-windows.ps1 b/scripts/migrate-windows.ps1 new file mode 100644 index 00000000000..abbbcdd94f6 --- /dev/null +++ b/scripts/migrate-windows.ps1 @@ -0,0 +1,750 @@ +<# +.SYNOPSIS +Safely replace a CLIProxyAPI Scheduled Task, or roll back a named migration. +.DESCRIPTION +Run -WhatIf first. Use -Detached to hand the operation to Task Scheduler before +stopping the hub. See docs/migrating.md for credentials, backups and recovery. +#> +[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'The script entry point calls ShouldProcess before any helper mutates state.')] +[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingPlainTextForPassword', 'TaskCredentialFile', Justification = 'This string is the path to a DPAPI encrypted PSCredential file.')] +[CmdletBinding(SupportsShouldProcess = $true)] +param( + [string]$NewExe, + [string]$OldTaskName = 'CLIProxyAPI Hub', + [string]$TaskPath = '\', + [string]$NewTaskName = 't3code-proxy', + [string]$OldExe, + [string]$Config, + [string]$WorkingDirectory, + [string]$BackupRoot, + [string]$BackupPath, + [string]$ManagementKeyFile, + [string]$TaskCredentialFile, + [switch]$AllowUnknownInFlight, + [switch]$Detached, + [switch]$Rollback, + [switch]$Worker, + [string]$LaunchTaskName, + [ValidateRange(10, 900)][int]$WaitSeconds = 90 +) +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +function Get-FullMigrationPath([string]$Path, [string]$Base) { + $expanded = [Environment]::ExpandEnvironmentVariables($Path.Trim('"')) + if (-not [IO.Path]::IsPathRooted($expanded)) { $expanded = Join-Path $Base $expanded } + return [IO.Path]::GetFullPath($expanded) +} + +function Get-TaskInstall([xml]$Xml, [string]$ExeOverride, [string]$ConfigOverride, [string]$DirectoryOverride) { + $ns = New-Object Xml.XmlNamespaceManager($Xml.NameTable) + $ns.AddNamespace('t', $Xml.DocumentElement.NamespaceURI) + $actions = @($Xml.SelectNodes('/t:Task/t:Actions/*', $ns)) + if ($actions.Count -ne 1 -or $actions[0].LocalName -ne 'Exec') { + throw 'Migration: The old task must have one direct executable action.' + } + $action = $actions[0] + $dirNode = $action.SelectSingleNode('t:WorkingDirectory', $ns) + $directory = '' + if ($null -ne $dirNode) { $directory = $dirNode.InnerText } + if ($DirectoryOverride) { $directory = $DirectoryOverride } + if (-not $directory) { throw 'Migration: Supply -WorkingDirectory for a task without one.' } + $directory = Get-FullMigrationPath $directory (Get-Location).Path + $executable = $action.SelectSingleNode('t:Command', $ns).InnerText + if ($ExeOverride) { $executable = $ExeOverride } + $executable = Get-FullMigrationPath $executable $directory + $configPath = $ConfigOverride + if (-not $configPath) { + $argumentsNode = $action.SelectSingleNode('t:Arguments', $ns) + if ($null -eq $argumentsNode) { throw 'Migration: Supply -Config for a task without config arguments.' } + $match = [regex]::Match($argumentsNode.InnerText, '^\s*--?config(?:=|\s+)(?:"([^"]+)"|(\S+))\s*$') + if (-not $match.Success) { throw 'Migration: Supply -Config after reviewing the old task arguments. Only -config is inferred.' } + $configPath = $match.Groups[1].Value + if (-not $configPath) { $configPath = $match.Groups[2].Value } + } + return [pscustomobject]@{ + OldExe = $executable + Config = (Get-FullMigrationPath $configPath $directory) + WorkingDirectory = $directory + } +} + +function Get-MigrationAccountCount([string]$Directory) { + $count = 0 + foreach ($file in @(Get-ChildItem -LiteralPath $Directory -File -Force -Filter '*.json')) { + try { $record = [IO.File]::ReadAllText($file.FullName) | ConvertFrom-Json } + catch { throw 'Migration: An auth JSON file is invalid or unreadable.' } + if ($null -ne $record -and $null -ne $record.PSObject.Properties['type'] -and $record.type) { $count++ } + } + return $count +} + +function Get-TreeManifest([string]$Directory, [string]$Base = '', [switch]$Live) { + # -Live is for a tree a running hub still owns: a file it holds open (its + # key-value store) is listed as unreadable instead of failing the walk. + if (-not $Base) { $Base = [IO.Path]::GetFullPath($Directory).TrimEnd('\', '/') } + if (((Get-Item -LiteralPath $Directory -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { + throw 'Migration: Backup trees must not contain junctions or symbolic links.' + } + foreach ($entry in @(Get-ChildItem -LiteralPath $Directory -Force)) { + if (($entry.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { + throw 'Migration: Backup trees must not contain junctions or symbolic links.' + } + $relative = $entry.FullName.Substring($Base.Length + 1) + if ($entry.PSIsContainer) { + [pscustomobject]@{ Path = $relative; Hash = 'directory' } + Get-TreeManifest -Directory $entry.FullName -Base $Base -Live:$Live + } else { + $hash = 'unreadable' + try { $hash = (Get-FileHash -LiteralPath $entry.FullName -Algorithm SHA256).Hash } + catch { if (-not $Live) { throw 'Migration: A file in the backup tree cannot be read.' } } + [pscustomobject]@{ Path = $relative; Hash = $hash } + } + } +} + +function Copy-VerifiedTree([string]$Source, [string]$Destination, [switch]$Live) { + # Strict (default): the hub is stopped, so every file must copy and the tree + # must not change. -Live: the hub is running, so a file it holds open or is + # still writing (logs, its key-value store) is recorded as such and captured + # by the strict copy taken after the stop. Account files must copy either way. + $before = @(Get-TreeManifest $Source -Live:$Live | Sort-Object Path) + if (Test-Path -LiteralPath $Destination) { Remove-Item -LiteralPath $Destination -Recurse -Force } + New-Item -ItemType Directory -Path $Destination | Out-Null + foreach ($item in $before) { + $target = Join-Path $Destination $item.Path + if ($item.Hash -eq 'directory') { + New-Item -ItemType Directory -Path $target -Force | Out-Null + continue + } + if ($item.Hash -eq 'unreadable') { continue } + $parent = Split-Path -Parent $target + if (-not (Test-Path -LiteralPath $parent)) { New-Item -ItemType Directory -Path $parent -Force | Out-Null } + $copied = $true + try { Copy-Item -LiteralPath (Join-Path $Source $item.Path) -Destination $target -Force } + catch { $copied = $false } + if ($copied -and (Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash -eq $item.Hash) { continue } + if (-not $Live) { throw 'Migration: Auth files changed during backup or copy verification failed. Re-run after activity settles.' } + $item.Hash = 'changed' + } + if ($Live) { + foreach ($item in $before) { + if ($item.Hash -in @('unreadable', 'changed') -and $item.Path -notmatch '[\\/]' -and $item.Path -like '*.json') { + throw 'Migration: An account file could not be backed up while the hub is running. Re-run after activity settles.' + } + } + return $before + } + $after = @(Get-TreeManifest $Source | Sort-Object Path) + $copy = @(Get-TreeManifest $Destination | Sort-Object Path) + if (($before | ConvertTo-Json -Depth 4 -Compress) -cne ($after | ConvertTo-Json -Depth 4 -Compress) -or + ($after | ConvertTo-Json -Depth 4 -Compress) -cne ($copy | ConvertTo-Json -Depth 4 -Compress)) { + throw 'Migration: Auth files changed during backup or copy verification failed. Re-run after activity settles.' + } + return $copy +} + +function Protect-MigrationDirectory([string]$Directory) { + $identity = [Security.Principal.WindowsIdentity]::GetCurrent().User + $acl = New-Object Security.AccessControl.DirectorySecurity + $acl.SetOwner($identity) + $acl.SetAccessRuleProtection($true, $false) + foreach ($sid in @($identity, (New-Object Security.Principal.SecurityIdentifier('S-1-5-18')))) { + $rule = New-Object Security.AccessControl.FileSystemAccessRule($sid, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow') + $acl.AddAccessRule($rule) + } + Set-Acl -LiteralPath $Directory -AclObject $acl +} + +function Write-MigrationJson([string]$Path, $Value) { + $temporary = $Path + '.tmp' + [IO.File]::WriteAllText($temporary, (ConvertTo-Json -InputObject $Value -Depth 12), (New-Object Text.UTF8Encoding($false))) + Move-Item -LiteralPath $temporary -Destination $Path -Force +} + +function ConvertTo-NativeArgument([string]$Value) { + if ($Value -match '["\r\n]') { throw 'Migration: Quoted or multiline arguments are unsupported.' } + # CommandLineToArgvW doubles trailing backslashes inside quoted arguments. + return '"' + [regex]::Replace($Value, '(\\+)$', '$1$1') + '"' +} + +function Invoke-MigrationDoctor([switch]$Probe, [string]$ConfigPath = '') { + if (-not $ConfigPath) { + $ConfigPath = $script:install.Config + if ($script:probeConfigPath) { $ConfigPath = $script:probeConfigPath } + } + $arguments = @('doctor', '-check-config', '-config', $ConfigPath) + if ($Probe) { + $arguments += @('-probe-url', $script:baseUrl) + if ($ManagementKeyFile) { $arguments += @('-management-key-file', $ManagementKeyFile) } + } + # Capture native output in memory. Bound a hung diagnostic without touching + # either hub process. No temporary stdout file can contain config secrets. + $start = New-Object Diagnostics.ProcessStartInfo + $start.FileName = $NewExe + $start.Arguments = ($arguments | ForEach-Object { ConvertTo-NativeArgument $_ }) -join ' ' + $start.WorkingDirectory = $script:install.WorkingDirectory + $start.UseShellExecute = $false + $start.CreateNoWindow = $true + $start.RedirectStandardOutput = $true + $start.RedirectStandardError = $true + $start.StandardOutputEncoding = New-Object Text.UTF8Encoding($false) + $process = New-Object Diagnostics.Process + $process.StartInfo = $start + try { + $null = $process.Start() + $stdout = $process.StandardOutput.ReadToEndAsync() + $stderr = $process.StandardError.ReadToEndAsync() + if (-not $process.WaitForExit(15000)) { + $process.Kill() + $process.WaitForExit() + throw 'Migration: Read-only doctor probe exceeded 15 seconds.' + } + $output = $stdout.GetAwaiter().GetResult() + $null = $stderr.GetAwaiter().GetResult() + $exitCode = $process.ExitCode + } finally { $process.Dispose() } + try { $report = $output | ConvertFrom-Json } + catch { throw 'Migration: New binary did not return a config-check JSON report.' } + if ($exitCode -ne 0 -or -not $report.ok) { + # The doctor's reason is a fixed, redacted string. Do not print its raw output. + throw 'Migration: Config check or authenticated probe failed. Run doctor -check-config directly for its redacted reason.' + } + return $report +} + +function Get-ExeProcess([string]$Executable) { + # Failure to inspect processes fails closed. Match the full executable path. + return @(Get-CimInstance Win32_Process | Where-Object { + $_.ExecutablePath -and [string]::Equals($_.ExecutablePath, $Executable, [StringComparison]::OrdinalIgnoreCase) + }) +} + +function Get-HubListener([int]$Port) { + # Listeners that a hub bound to the configured address would collide with. + # A loopback hub shares its port with listeners on other addresses, such as + # Tailscale Serve on the tailnet address, and those never go away. + $all = @(Get-NetTCPConnection -State Listen -ErrorAction Stop | Where-Object { $_.LocalPort -eq $Port }) + $bind = '' + if (Test-Path -LiteralPath variable:script:bindHost) { $bind = [string]$script:bindHost } + if ($bind -in @('127.0.0.1', 'localhost')) { + return @($all | Where-Object { $_.LocalAddress -in @('127.0.0.1', '0.0.0.0', '::', '::1') }) + } + return $all +} + +function Wait-MigrationStopped([string]$Executable, [int]$Port = 0) { + # Port 0 waits for the process only; the other hub may still own the port. + $until = [DateTime]::UtcNow.AddSeconds($WaitSeconds) + do { + $processes = @(Get-ExeProcess $Executable) + $listeners = @() + if ($Port -gt 0) { $listeners = @(Get-HubListener $Port) } + if ($processes.Count -eq 0 -and $listeners.Count -eq 0) { return } + Start-Sleep -Milliseconds 500 + } while ([DateTime]::UtcNow -lt $until) + throw 'Migration: Process exit and free-port barrier failed. The other hub will remain stopped.' +} + +function Wait-MigrationHealthy([int]$ExpectedAccounts, [switch]$RequireHealth) { + $until = [DateTime]::UtcNow.AddSeconds($WaitSeconds) + $lastStatus = 'Authenticated endpoints did not respond.' + do { + try { + $report = Invoke-MigrationDoctor -Probe + $lastStatus = "Health $($report.probe.health), models $($report.probe.models), file accounts $($report.probe.accounts), expected $ExpectedAccounts, outside the auth directory $($report.probe.accounts_outside_auth_dir)." + if ($report.probe.models -and $report.probe.accounts -eq $ExpectedAccounts -and $report.probe.accounts_outside_auth_dir -eq 0 -and + (-not $RequireHealth -or $report.probe.health)) { return } + } catch { Write-Verbose 'Authenticated readiness checks are still pending.' } + Start-Sleep -Seconds 2 + } while ([DateTime]::UtcNow -lt $until) + throw ('Migration: Hub verification failed. ' + $lastStatus) +} + +function Assert-MigrationPrincipal([xml]$Xml) { + $ns = New-Object Xml.XmlNamespaceManager($Xml.NameTable) + $ns.AddNamespace('t', $Xml.DocumentElement.NamespaceURI) + $userNode = $Xml.SelectSingleNode('/t:Task/t:Principals/t:Principal/t:UserId', $ns) + if ($null -eq $userNode) { throw 'Migration: Group principals are unsupported. Run as the hub task user.' } + $userId = $userNode.InnerText + if ($userId -match '^S-1-') { $sid = New-Object Security.Principal.SecurityIdentifier($userId) } + else { $sid = (New-Object Security.Principal.NTAccount($userId)).Translate([Security.Principal.SecurityIdentifier]) } + if ($sid -ne [Security.Principal.WindowsIdentity]::GetCurrent().User) { + throw 'Migration: Run this migration as the same Windows user as the old task.' + } + $logon = $Xml.SelectSingleNode('/t:Task/t:Principals/t:Principal/t:LogonType', $ns) + if ($null -eq $logon -or $logon.InnerText -notin @('S4U', 'InteractiveToken', 'Password')) { + throw 'Migration: Unsupported task logon type.' + } + if ($null -ne $script:taskCredential) { + if ($logon.InnerText -ne 'Password' -or $script:taskCredential -isnot [PSCredential]) { throw 'Migration: A task credential is valid only for Password-logon tasks.' } + $credentialSid = (New-Object Security.Principal.NTAccount($script:taskCredential.UserName)).Translate([Security.Principal.SecurityIdentifier]) + if ($credentialSid -ne $sid) { throw 'Migration: Task credential must belong to the old task user.' } + } + if ($logon.InnerText -eq 'Password' -and $null -eq $script:taskCredential) { + throw 'Migration: Password-logon tasks require -TaskCredentialFile (same-user DPAPI Export-Clixml).' + } +} + +function Set-MigrationPhase([string]$Name) { + $script:phase = $Name + Write-Information "Phase $Name" -InformationAction Continue + if ($null -ne $script:result) { + $script:result.Phase = $Name + Write-MigrationJson (Join-Path $BackupPath 'result.json') $script:result + } +} + +function New-MigrationResult { + return [ordered]@{ Phase = $script:phase; Success = $false; StartedAt = [DateTime]::UtcNow.ToString('o'); FinishedAt = $null; Reason = ''; BackupPath = $BackupPath; RolledBack = $false } +} + +function Start-DetachedMigration { + $launchName = 't3code-migration-' + [guid]::NewGuid().ToString('N') + $arguments = @('-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', (ConvertTo-NativeArgument $PSCommandPath)) + $forward = @{ + NewExe = $NewExe; OldTaskName = $OldTaskName; TaskPath = $TaskPath; NewTaskName = $NewTaskName + OldExe = $script:install.OldExe; Config = $script:install.Config; WorkingDirectory = $script:install.WorkingDirectory + BackupRoot = $BackupRoot; BackupPath = $BackupPath; ManagementKeyFile = $ManagementKeyFile; TaskCredentialFile = $TaskCredentialFile + WaitSeconds = [string]$WaitSeconds + } + foreach ($key in $forward.Keys) { + if ($forward[$key]) { + if ([string]$forward[$key] -match '["\r\n]') { throw 'Migration: Quoted or multiline task arguments are unsupported.' } + $arguments += @('-' + $key, (ConvertTo-NativeArgument ([string]$forward[$key]))) + } + } + if ($AllowUnknownInFlight) { $arguments += '-AllowUnknownInFlight' } + if ($Rollback) { $arguments += '-Rollback' } + $arguments += @('-Worker', '-LaunchTaskName', (ConvertTo-NativeArgument $launchName)) + $action = New-ScheduledTaskAction -Execute (Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe') ` + -Argument ($arguments -join ' ') -WorkingDirectory $script:install.WorkingDirectory + $settings = New-ScheduledTaskSettingsSet -ExecutionTimeLimit ([TimeSpan]::Zero) -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -MultipleInstances IgnoreNew + $task = Get-ScheduledTask -TaskName $OldTaskName -TaskPath $TaskPath + $principal = $task.Principal + $elevated = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole( + [Security.Principal.WindowsBuiltInRole]::Administrator) + if ($elevated) { + # The worker registers and stops tasks, which a limited token is often not + # allowed to do. Launched from an elevated shell, it runs elevated too. + $principal = New-ScheduledTaskPrincipal -UserId $task.Principal.UserId -LogonType $task.Principal.LogonType -RunLevel Highest + } + $definition = New-ScheduledTask -Action $action -Settings $settings -Principal $principal + if ($null -ne $script:taskCredential) { + Register-ScheduledTask -TaskName $launchName -InputObject $definition -User $script:taskCredential.UserName ` + -Password $script:taskCredential.GetNetworkCredential().Password | Out-Null + } else { Register-ScheduledTask -TaskName $launchName -InputObject $definition | Out-Null } + Start-ScheduledTask -TaskName $launchName + Write-Information "Detached migration task $launchName started." -InformationAction Continue + Write-Information "Result directory $BackupPath" -InformationAction Continue +} + +function Invoke-MigrationRollback($State, [switch]$RestoreConfig) { + # Stop the new hub first and wait for its process only. + if (Get-ScheduledTask -TaskName $State.NewTaskName -TaskPath $State.TaskPath -ErrorAction SilentlyContinue) { + Disable-ScheduledTask -TaskName $State.NewTaskName -TaskPath $State.TaskPath | Out-Null + Stop-ScheduledTask -TaskName $State.NewTaskName -TaskPath $State.TaskPath + } + try { Wait-MigrationStopped $State.NewExe } + catch { + # The new hub would not stop, so it is still the one serving. Put its task + # back in charge before giving up, or a reboot would start no hub at all. + if (Get-ScheduledTask -TaskName $State.NewTaskName -TaskPath $State.TaskPath -ErrorAction SilentlyContinue) { + Enable-ScheduledTask -TaskName $State.NewTaskName -TaskPath $State.TaskPath | Out-Null + } + throw + } + $oldTask = Get-ScheduledTask -TaskName $State.OldTaskName -TaskPath $State.TaskPath -ErrorAction SilentlyContinue + if (@(Get-ExeProcess $State.OldExe).Count -ne 0) { + # The old hub never exited. Leave its files alone and put its task back in + # charge, so a reboot or crash still starts a hub. + if ($null -eq $oldTask) { throw 'Migration: The old hub is running but its task is missing. Use manual recovery in docs/migrating.md.' } + Enable-ScheduledTask -TaskName $State.OldTaskName -TaskPath $State.TaskPath | Out-Null + $serving = $true + try { Wait-MigrationHealthy (Get-MigrationAccountCount $State.AuthDir) } catch { $serving = $false } + if ($serving) { return } + # It is running but not serving: it is still shutting down. Start its task + # only after that process is gone, so two copies never run together. + Wait-MigrationStopped $State.OldExe + Start-ScheduledTask -TaskName $State.OldTaskName -TaskPath $State.TaskPath + Wait-MigrationHealthy (Get-MigrationAccountCount $State.AuthDir) + return + } + try { + # Inside the try: if the port stays held, the old task is still enabled and + # started below, and its restart policy brings the hub up once the port frees. + Wait-MigrationStopped $State.OldExe $State.Port + if ($RestoreConfig) { + $savedConfig = Join-Path $State.BackupPath 'config.yaml' + if ((Get-FileHash -LiteralPath $savedConfig -Algorithm SHA256).Hash -ne $State.ConfigHash) { + throw 'Migration: Saved config checksum failed.' + } + # Preserve the later config before restoring. Live auth is always retained. + if (Test-Path -LiteralPath $State.Config) { + Copy-Item -LiteralPath $State.Config -Destination (Join-Path $State.BackupPath ('config-before-rollback-' + [guid]::NewGuid().ToString('N') + '.yaml')) + } + Copy-Item -LiteralPath $savedConfig -Destination $State.Config -Force + $environmentPath = Join-Path $State.WorkingDirectory '.env' + $savedEnvironment = Join-Path $State.BackupPath 'environment.env' + if ($State.EnvironmentHash -and (Get-FileHash -LiteralPath $savedEnvironment -Algorithm SHA256).Hash -ne $State.EnvironmentHash) { + throw 'Migration: Saved environment checksum failed.' + } + if (Test-Path -LiteralPath $environmentPath) { + Move-Item -LiteralPath $environmentPath -Destination (Join-Path $State.BackupPath ('environment-before-rollback-' + [guid]::NewGuid().ToString('N') + '.env')) + } + if ($State.EnvironmentHash) { Copy-Item -LiteralPath $savedEnvironment -Destination $environmentPath } + } + if ($null -eq $oldTask) { + # The migration only ever disables the old task. Register it again only + # when something else removed it. + $taskXmlPath = Join-Path $State.BackupPath 'old-task.xml' + if ((Get-FileHash -LiteralPath $taskXmlPath -Algorithm SHA256).Hash -ne $State.TaskXmlHash) { + throw 'Migration: Saved task XML checksum failed.' + } + $registration = @{ TaskName = $State.OldTaskName; TaskPath = $State.TaskPath; Xml = [IO.File]::ReadAllText($taskXmlPath); Force = $true } + if ($null -ne $script:taskCredential) { + $registration.User = $script:taskCredential.UserName + $registration.Password = $script:taskCredential.GetNetworkCredential().Password + } + Register-ScheduledTask @registration | Out-Null + } + } finally { + # Whatever failed above, the old task must end up enabled and started: with + # the new hub stopped it is the only thing that can serve. + if (Get-ScheduledTask -TaskName $State.OldTaskName -TaskPath $State.TaskPath -ErrorAction SilentlyContinue) { + Enable-ScheduledTask -TaskName $State.OldTaskName -TaskPath $State.TaskPath | Out-Null + Start-ScheduledTask -TaskName $State.OldTaskName -TaskPath $State.TaskPath + } + } + Wait-MigrationHealthy (Get-MigrationAccountCount $State.AuthDir) +} + +function Get-MigrationAccountNote($State) { + # A rollback is verified against the accounts that exist now. Say so when + # that differs from what the migration recorded before the switch. + $live = Get-MigrationAccountCount $State.AuthDir + if ($live -eq $State.AccountCount) { return '' } + return " Warning: the auth directory now holds $live account files; $($State.AccountCount) were recorded before the switch. Compare it with auth-final in the backup." +} + +# Dot sourcing exposes only pure/support functions to Pester. +if ($MyInvocation.InvocationName -eq '.') { return } + +# -WhatIf is this script's dry-run switch. Windows PowerShell 5.1 hands the +# preference down to script cmdlets such as Get-FileHash, which then return +# nothing, so the read-only preflight runs with it off and the switch is +# honored at the single point where changes would begin. +$dryRun = [bool]$WhatIfPreference +$WhatIfPreference = $false +$phase = 'preflight' +$stopped = $false +$accountNote = '' +$registeredNew = $false +$transcribing = $false +$lock = $null +$result = $null +$exitCode = 1 +$script:taskCredential = $null +$script:probeConfigPath = '' +try { + if ($Worker) { + if (-not $BackupPath -or -not (Test-Path -LiteralPath (Join-Path $BackupPath 'result.json'))) { + throw 'Migration: Detached worker requires its prepared result directory.' + } + Start-Transcript -LiteralPath (Join-Path $BackupPath ('transcript-' + [DateTime]::UtcNow.ToString('yyyyMMddTHHmmssfffZ') + '.log')) | Out-Null + $transcribing = $true + $result = New-MigrationResult + Write-MigrationJson (Join-Path $BackupPath 'result.json') $result + } + if ($env:OS -ne 'Windows_NT') { throw 'Migration: Run this script on Windows.' } + Write-Verbose "Readiness wait budget $WaitSeconds seconds." + if ($TaskCredentialFile) { $script:taskCredential = Import-Clixml -LiteralPath $TaskCredentialFile } + $oldTask = Get-ScheduledTask -TaskName $OldTaskName -TaskPath $TaskPath + [xml]$oldXml = Export-ScheduledTask -TaskName $OldTaskName -TaskPath $TaskPath + Assert-MigrationPrincipal $oldXml + $script:install = Get-TaskInstall -Xml $oldXml -ExeOverride $OldExe -ConfigOverride $Config -DirectoryOverride $WorkingDirectory + $oldArguments = [string]$oldTask.Actions[0].Arguments + if ($Config -and $oldArguments -notmatch '^\s*--?config(?:=|\s+)(?:"[^"]+"|\S+)\s*$') { + Write-Warning 'The old task runs with arguments other than -config. The replacement task will run with -config only; add anything else it needs to the config file.' + } + if ($Rollback) { + if (-not $BackupPath) { throw 'Migration: -Rollback requires a named -BackupPath.' } + $BackupPath = [IO.Path]::GetFullPath($BackupPath) + $state = [IO.File]::ReadAllText((Join-Path $BackupPath 'migration.json')) | ConvertFrom-Json + if ($state.OldTaskName -ne $OldTaskName -or $state.TaskPath -ne $TaskPath) { throw 'Migration: Backup belongs to another task.' } + foreach ($pair in @(@('config.yaml', $state.ConfigHash), @('old-task.xml', $state.TaskXmlHash))) { + if ((Get-FileHash -LiteralPath (Join-Path $BackupPath $pair[0]) -Algorithm SHA256).Hash -ne $pair[1]) { throw 'Migration: Backup config or task XML checksum failed.' } + } + if ($state.EnvironmentHash -and (Get-FileHash -LiteralPath (Join-Path $BackupPath 'environment.env') -Algorithm SHA256).Hash -ne $state.EnvironmentHash) { throw 'Migration: Backup environment checksum failed.' } + $state.BackupPath = $BackupPath + $script:probeConfigPath = Join-Path $BackupPath 'config.yaml' + $NewExe = $state.NewExe + $NewTaskName = $state.NewTaskName + $script:install = [pscustomobject]@{ OldExe = $state.OldExe; Config = $state.Config; WorkingDirectory = $state.WorkingDirectory } + } + if (-not $NewExe) { throw 'Migration: Supply an already staged -NewExe.' } + $NewExe = Get-FullMigrationPath $NewExe (Get-Location).Path + if ($NewExe -eq $script:install.OldExe) { throw 'Migration: Stage the new binary at a different path from the old binary.' } + if ($NewTaskName -eq $OldTaskName) { throw 'Migration: Old and new task names must differ.' } + $requiredInstallPaths = @($NewExe, $script:install.OldExe, $script:install.WorkingDirectory) + if (-not $Rollback) { $requiredInstallPaths += $script:install.Config } + foreach ($path in $requiredInstallPaths) { + if (-not (Test-Path -LiteralPath $path)) { throw 'Migration: A binary, config or working-directory path is missing.' } + } + if ($ManagementKeyFile) { $ManagementKeyFile = Get-FullMigrationPath $ManagementKeyFile (Get-Location).Path } + if ($TaskCredentialFile) { $TaskCredentialFile = Get-FullMigrationPath $TaskCredentialFile (Get-Location).Path } + $registerScript = Join-Path (Split-Path -Parent $PSScriptRoot) 'deploy\windows\register-task.ps1' + if (-not (Test-Path -LiteralPath $registerScript)) { throw 'Migration: Keep deploy/windows/register-task.ps1 alongside scripts/.' } + Push-Location $script:install.WorkingDirectory + try { + if ($Rollback) { $check = Invoke-MigrationDoctor -ConfigPath (Join-Path $BackupPath 'config.yaml') } + else { $check = Invoke-MigrationDoctor } + } finally { Pop-Location } + if ($check.settings.tls -or $check.settings.port -lt 1 -or $check.settings.port -gt 65535) { + throw 'Migration: This procedure requires a local HTTP hub on a valid port.' + } + if ($check.settings.host -notin @('127.0.0.1', 'localhost', '', '0.0.0.0', '::', '[::]')) { throw 'Migration: The configured bind address does not include loopback.' } + if ($Rollback -and ($check.settings.auth_dir -ne $state.AuthDir -or $check.settings.port -ne $state.Port)) { throw 'Migration: Auth directory or port changed since backup. Review manual recovery before restoring config.' } + $script:baseUrl = 'http://127.0.0.1:' + $check.settings.port + $script:bindHost = [string]$check.settings.host + foreach ($path in $check.settings.required_paths) { + $resolved = Get-FullMigrationPath $path $script:install.WorkingDirectory + if (-not (Test-Path -LiteralPath $resolved)) { throw 'Migration: A configured auth, catalog, TLS or plugin path is missing.' } + } + if ($oldXml.OuterXml -notmatch '') { + Write-Warning 'The old task has no restart-on-failure setting, so after a rollback it starts once and is not retried if the port is briefly held.' + } + foreach ($key in $check.unknown_keys) { Write-Warning "Ignored configuration key $key" } + foreach ($issue in $check.issues) { Write-Warning "Configuration diagnostic $issue" } + $environmentFile = Join-Path $script:install.WorkingDirectory '.env' + $environmentHash = '' + if (Test-Path -LiteralPath $environmentFile) { $environmentHash = (Get-FileHash -LiteralPath $environmentFile -Algorithm SHA256).Hash } + $authDir = $check.settings.auth_dir + $null = @(Get-TreeManifest $authDir -Live) + $accountCount = Get-MigrationAccountCount $authDir + $helper = @(Get-ScheduledTask -ErrorAction Stop | Where-Object { $_.TaskName -like '*Catalog*Refresh*' }) + foreach ($helperTask in $helper) { Write-Information "Catalog helper task $($helperTask.TaskPath)$($helperTask.TaskName) remains registered." -InformationAction Continue } + Write-Information "Catalog helper tasks found $($helper.Count)." -InformationAction Continue + if (-not $BackupRoot) { $BackupRoot = Join-Path (Split-Path -Parent $script:install.WorkingDirectory) 't3code-migration-backups' } + $BackupRoot = Get-FullMigrationPath $BackupRoot (Get-Location).Path + if (-not $BackupPath) { $BackupPath = Join-Path $BackupRoot ([DateTime]::UtcNow.ToString('yyyyMMddTHHmmssfffZ') + '-' + [guid]::NewGuid().ToString('N').Substring(0, 8)) } + $BackupPath = [IO.Path]::GetFullPath($BackupPath) + $authPrefix = [IO.Path]::GetFullPath($authDir).TrimEnd('\') + '\' + if (($BackupPath + '\').StartsWith($authPrefix, [StringComparison]::OrdinalIgnoreCase) -or $authPrefix.StartsWith($BackupPath.TrimEnd('\') + '\', [StringComparison]::OrdinalIgnoreCase)) { throw 'Migration: Backups must be outside the auth directory.' } + $drive = New-Object IO.DriveInfo([IO.Path]::GetPathRoot($BackupPath)) + $authSize = (Get-ChildItem -LiteralPath $authDir -File -Force -Recurse | Measure-Object Length -Sum).Sum + if ($null -eq $authSize) { $authSize = 0 } + # A rollback copies no auth tree, so a full backup volume must not refuse it. + if (-not $Rollback -and $drive.AvailableFreeSpace -lt (2 * $authSize + 64MB)) { throw 'Migration: Backup volume needs twice the auth size plus 64 MiB free.' } + if (-not $Rollback) { + $existingNew = Get-ScheduledTask -TaskName $NewTaskName -TaskPath $TaskPath -ErrorAction SilentlyContinue + if ($null -ne $existingNew) { + $previousStatePath = Join-Path $BackupPath 'migration.json' + $previousResultPath = Join-Path $BackupPath 'result.json' + if (-not $Worker -and (Test-Path -LiteralPath $previousStatePath) -and (Test-Path -LiteralPath $previousResultPath)) { + $previousState = [IO.File]::ReadAllText($previousStatePath) | ConvertFrom-Json + $previousResult = [IO.File]::ReadAllText($previousResultPath) | ConvertFrom-Json + if ($previousResult.Success -and -not $previousResult.RolledBack -and $previousState.NewExe -eq $NewExe -and + $previousState.Config -eq $script:install.Config -and $previousState.OldTaskName -eq $OldTaskName -and + $previousState.NewTaskName -eq $NewTaskName -and $previousState.TaskPath -eq $TaskPath -and -not $oldTask.Settings.Enabled) { + $savedConfig = Join-Path $BackupPath 'config.yaml' + if ((Get-FileHash -LiteralPath $savedConfig -Algorithm SHA256).Hash -ne $previousState.ConfigHash) { throw 'Migration: Named migration config backup checksum failed.' } + $script:probeConfigPath = $savedConfig + Wait-MigrationHealthy (Get-MigrationAccountCount $authDir) -RequireHealth + Write-Information 'This named migration already succeeded and the new hub still passes authenticated checks.' -InformationAction Continue + return + } + } + throw 'Migration: New task already exists. Use its named backup for rollback or choose another new task name.' + } + if (@(Get-ExeProcess $NewExe).Count -ne 0) { throw 'Migration: The staged binary is already running.' } + $oldProcesses = @(Get-ExeProcess $script:install.OldExe) + if ($oldProcesses.Count -ne 1 -or $oldTask.State -ne 'Running') { throw 'Migration: Expected exactly one running old hub owned by its running task.' } + $listeners = @(Get-HubListener $check.settings.port) + if ($listeners.Count -eq 0 -or @($listeners | Where-Object { $_.OwningProcess -ne $oldProcesses[0].ProcessId }).Count -ne 0) { + throw 'Migration: The old executable must own every listener on the configured port.' + } + Push-Location $script:install.WorkingDirectory + try { $probe = Invoke-MigrationDoctor -Probe } finally { Pop-Location } + if ($probe.probe.accounts -ne $accountCount) { throw 'Migration: Old management account count differs from auth files. Resolve this before switching.' } + if ($probe.probe.accounts_outside_auth_dir -ne 0) { throw 'Migration: The old hub serves accounts that are not files in the auth directory the new hub would use. Set oauth.auth-dir explicitly before switching.' } + Write-Information "Preflight found $accountCount file-backed accounts on port $($check.settings.port)." -InformationAction Continue + if ($probe.probe.in_flight -lt 0) { + Write-Warning 'In-flight requests are unavailable on this hub. Pause clients and use -AllowUnknownInFlight to accept this gap.' + if (-not $AllowUnknownInFlight -and -not $dryRun) { throw 'Migration: In-flight status unavailable; -AllowUnknownInFlight is required.' } + } elseif ($probe.probe.in_flight -gt 0) { + Write-Warning "In-flight request count $($probe.probe.in_flight)." + if (-not $dryRun) { throw 'Migration: Requests are in flight. Pause clients and re-run when idle.' } + } + } + Write-Information 'Plan includes verified backup, disabling/stopping old, process exit and free-port checks, registering/starting new, authenticated verification and automatic rollback on failure.' -InformationAction Continue + Write-Information "Backup and result directory $BackupPath" -InformationAction Continue + if ($dryRun) { + Write-Information ('Dry run complete. Preflight passed and nothing was changed. A real run would ' + $(if ($Rollback) { 'roll back the named migration.' } else { 'migrate the hub.' })) -InformationAction Continue + return + } + if (-not $PSCmdlet.ShouldProcess($OldTaskName, $(if ($Rollback) { 'Roll back named migration' } else { 'Migrate hub' }))) { return } + if ($Detached) { + if (-not $Rollback) { + if (Test-Path -LiteralPath $BackupPath) { throw 'Migration: Backup directory already exists.' } + New-Item -ItemType Directory -Path $BackupPath | Out-Null + } + Protect-MigrationDirectory $BackupPath + $result = New-MigrationResult + Set-MigrationPhase 'detached-launch' + Start-DetachedMigration + # The worker owns subsequent result updates, including preflight failures. + $result = $null + return + } + $lockPath = Join-Path $script:install.WorkingDirectory '.t3code-migration.lock' + $lock = [IO.File]::Open($lockPath, [IO.FileMode]::OpenOrCreate, [IO.FileAccess]::ReadWrite, [IO.FileShare]::None) + if (-not $Rollback -and -not $Worker) { + if (Test-Path -LiteralPath $BackupPath) { throw 'Migration: Backup directory already exists. Choose a new path.' } + New-Item -ItemType Directory -Path $BackupPath | Out-Null + } + Protect-MigrationDirectory $BackupPath + if (-not $transcribing) { + Start-Transcript -LiteralPath (Join-Path $BackupPath ('transcript-' + [DateTime]::UtcNow.ToString('yyyyMMddTHHmmssfffZ') + '.log')) | Out-Null + $transcribing = $true + $result = New-MigrationResult + Write-MigrationJson (Join-Path $BackupPath 'result.json') $result + } + Push-Location $script:install.WorkingDirectory + try { + if ($Rollback) { + Set-MigrationPhase 'rollback' + Invoke-MigrationRollback $state -RestoreConfig + $result.RolledBack = $true + $accountNote = Get-MigrationAccountNote $state + } else { + Set-MigrationPhase 'backup' + Copy-Item -LiteralPath $script:install.Config -Destination (Join-Path $BackupPath 'config.yaml') + # Use the immutable config snapshot for authenticated probes. Startup can + # replace the live plaintext management key with its bcrypt hash. + $script:probeConfigPath = Join-Path $BackupPath 'config.yaml' + $configHash = (Get-FileHash -LiteralPath (Join-Path $BackupPath 'config.yaml') -Algorithm SHA256).Hash + if ($configHash -ne $check.settings.config_sha256) { throw 'Migration: Config changed after preflight.' } + [IO.File]::WriteAllText((Join-Path $BackupPath 'old-task.xml'), $oldXml.OuterXml, [Text.Encoding]::Unicode) + $exportCheck = [xml]([IO.File]::ReadAllText((Join-Path $BackupPath 'old-task.xml'))) + if ($exportCheck.OuterXml -cne $oldXml.OuterXml) { throw 'Migration: Task XML backup verification failed.' } + $environmentFile = Join-Path $script:install.WorkingDirectory '.env' + if ($environmentHash) { + Copy-Item -LiteralPath $environmentFile -Destination (Join-Path $BackupPath 'environment.env') + if ((Get-FileHash -LiteralPath (Join-Path $BackupPath 'environment.env') -Algorithm SHA256).Hash -ne $environmentHash) { throw 'Migration: Environment file changed during backup.' } + } + # The hub is still running here, so this first copy tolerates the files it + # holds open; the strict copy after the stop captures everything. + $manifest = @(Copy-VerifiedTree $authDir (Join-Path $BackupPath 'auth') -Live) + Write-MigrationJson (Join-Path $BackupPath 'auth-manifest.json') $manifest + $deferred = @($manifest | Where-Object { $_.Hash -in @('unreadable', 'changed') }).Count + if ($deferred -gt 0) { Write-Information "$deferred file(s) in use by the running hub will be captured after it stops." -InformationAction Continue } + $state = [ordered]@{ + OldTaskName = $OldTaskName; NewTaskName = $NewTaskName; TaskPath = $TaskPath + OldExe = $script:install.OldExe; NewExe = $NewExe; Config = $script:install.Config + WorkingDirectory = $script:install.WorkingDirectory; AuthDir = $authDir; Port = $check.settings.port + ConfigHash = $configHash; AccountCount = $accountCount; EnvironmentHash = $environmentHash; BackupPath = $BackupPath + TaskXmlHash = (Get-FileHash -LiteralPath (Join-Path $BackupPath 'old-task.xml') -Algorithm SHA256).Hash + } + Write-MigrationJson (Join-Path $BackupPath 'migration.json') $state + $lastProbe = Invoke-MigrationDoctor -Probe + if ((Get-FileHash -LiteralPath $script:install.Config -Algorithm SHA256).Hash -ne $check.settings.config_sha256) { throw 'Migration: Config changed during backup.' } + if ($lastProbe.probe.in_flight -gt 0 -or ($lastProbe.probe.in_flight -lt 0 -and -not $AllowUnknownInFlight)) { + throw 'Migration: Requests appeared or in-flight status became unavailable during backup.' + } + $currentEnvironmentHash = '' + if (Test-Path -LiteralPath $environmentFile) { $currentEnvironmentHash = (Get-FileHash -LiteralPath $environmentFile -Algorithm SHA256).Hash } + if ($currentEnvironmentHash -ne $environmentHash) { throw 'Migration: Working-directory environment changed after preflight.' } + [xml]$currentTaskXml = Export-ScheduledTask -TaskName $OldTaskName -TaskPath $TaskPath + if ($currentTaskXml.OuterXml -cne $oldXml.OuterXml) { throw 'Migration: Old task definition changed during backup.' } + Set-MigrationPhase 'register-new' + # Register the replacement, still disabled, while the old hub is serving. + # A registration this account is not allowed to make fails here, before + # anything has been stopped. + & $registerScript -Exe $NewExe -Config $script:install.Config -WorkingDirectory $script:install.WorkingDirectory ` + -TaskName $NewTaskName -TaskPath $TaskPath -TemplateXml (Join-Path $BackupPath 'old-task.xml') -Credential $script:taskCredential -NoStart + $registeredNew = $true + if ((Get-ScheduledTask -TaskName $NewTaskName -TaskPath $TaskPath).Settings.Enabled) { throw 'Migration: The replacement task must be registered disabled.' } + Set-MigrationPhase 'switch-stop-old' + # Disable before stopping so task triggers and restart policy cannot relaunch it. + Disable-ScheduledTask -TaskName $OldTaskName -TaskPath $TaskPath | Out-Null + $stopped = $true + Stop-ScheduledTask -TaskName $OldTaskName -TaskPath $TaskPath + Wait-MigrationStopped $script:install.OldExe $state.Port + if ((Get-FileHash -LiteralPath $script:install.Config -Algorithm SHA256).Hash -ne $state.ConfigHash) { throw 'Migration: Config changed while stopping the old hub.' } + # Capture the last token rotations after the process-exit barrier, next to + # the first verified copy instead of over it. + $manifest = @(Copy-VerifiedTree $authDir (Join-Path $BackupPath 'auth-final')) + Write-MigrationJson (Join-Path $BackupPath 'auth-final-manifest.json') $manifest + if ((Get-MigrationAccountCount (Join-Path $BackupPath 'auth-final')) -ne $state.AccountCount) { throw 'Migration: Account set changed during the switch.' } + Set-MigrationPhase 'switch-start-new' + Enable-ScheduledTask -TaskName $NewTaskName -TaskPath $TaskPath | Out-Null + Start-ScheduledTask -TaskName $NewTaskName -TaskPath $TaskPath + Set-MigrationPhase 'verify' + Wait-MigrationHealthy $state.AccountCount -RequireHealth + if (@(Get-ExeProcess $script:install.OldExe).Count -ne 0) { throw 'Migration: Old executable reappeared during verification.' } + } + $result.Success = $true + $result.Reason = 'Completed and authenticated checks passed.' + $accountNote + $result.FinishedAt = [DateTime]::UtcNow.ToString('o') + Write-MigrationJson (Join-Path $BackupPath 'result.json') $result + $exitCode = 0 + } finally { Pop-Location } +} catch { + $reason = "Phase $phase failed ($($_.Exception.GetType().Name))." + if ($_.Exception.Message.StartsWith('Migration:')) { $reason = $_.Exception.Message } + Write-Information $reason -InformationAction Continue + if ($null -ne $result) { + $result.Success = $false + $result.Reason = $reason + if ($stopped -and -not $Rollback) { + try { + Push-Location $script:install.WorkingDirectory + try { Invoke-MigrationRollback $state -RestoreConfig } finally { Pop-Location } + $result.RolledBack = $true + $result.Reason += ' Old hub restarted and authenticated checks passed.' + (Get-MigrationAccountNote $state) + } catch { + $rollbackReason = 'Rollback task operation or verification failed.' + if ($_.Exception.Message.StartsWith('Migration:')) { $rollbackReason = $_.Exception.Message } + $result.Reason += ' Automatic rollback failed. ' + $rollbackReason + ' Use manual recovery in docs/migrating.md.' + # Last resort: with the new hub not running, leave the old task enabled + # so the next boot or crash restart brings a hub back. + try { + if (@(Get-ExeProcess $NewExe).Count -eq 0 -and (Get-ScheduledTask -TaskName $OldTaskName -TaskPath $TaskPath -ErrorAction SilentlyContinue)) { + Enable-ScheduledTask -TaskName $OldTaskName -TaskPath $TaskPath | Out-Null + $result.Reason += ' The old task was left enabled.' + } elseif (@(Get-ExeProcess $NewExe).Count -ne 0 -and (Get-ScheduledTask -TaskName $NewTaskName -TaskPath $TaskPath -ErrorAction SilentlyContinue)) { + # The new hub would not stop and is still the one serving. Leave its + # task enabled so a reboot does not come up with no hub at all. + Enable-ScheduledTask -TaskName $NewTaskName -TaskPath $TaskPath | Out-Null + $result.Reason += ' The new hub is still running and its task was left enabled.' + } + } catch { $result.Reason += ' The old task could not be re-enabled.' } + } + } elseif ($registeredNew -and -not $Rollback) { + # Nothing was stopped. Remove the disabled replacement so a re-run starts clean. + try { + Unregister-ScheduledTask -TaskName $NewTaskName -TaskPath $TaskPath -Confirm:$false + $result.Reason += ' The old hub was not touched.' + } catch { $result.Reason += ' The disabled replacement task could not be removed; remove it before re-running.' } + } + } +} finally { + if ($null -ne $result) { + $result.Phase = $phase + $result.FinishedAt = [DateTime]::UtcNow.ToString('o') + try { Write-MigrationJson (Join-Path $BackupPath 'result.json') $result } + catch { Write-Warning 'Could not persist the final result. Check disk space and the task/log state.' } + Write-Information "Success $($result.Success). Rolled back $($result.RolledBack). Result $(Join-Path $BackupPath 'result.json')" -InformationAction Continue + } + try { + if ($transcribing) { Stop-Transcript | Out-Null } + } finally { + if ($null -ne $lock) { $lock.Dispose() } + # The one-shot launch task has done its job; its definition holds file paths. + if ($Worker -and $LaunchTaskName -like 't3code-migration-*') { + Unregister-ScheduledTask -TaskName $LaunchTaskName -Confirm:$false -ErrorAction SilentlyContinue + } + } +} +exit $exitCode diff --git a/sdk/api/handlers/handlers.go b/sdk/api/handlers/handlers.go index b66467507b7..a294b2cc288 100644 --- a/sdk/api/handlers/handlers.go +++ b/sdk/api/handlers/handlers.go @@ -312,6 +312,9 @@ func requestExecutionMetadata(ctx context.Context) map[string]any { if pinnedAuthID := pinnedAuthIDFromContext(ctx); pinnedAuthID != "" { meta[coreexecutor.PinnedAuthMetadataKey] = pinnedAuthID } + if excludedAuthIDs := excludedAuthIDsFromContext(ctx); len(excludedAuthIDs) > 0 { + meta[coreexecutor.ExcludedAuthIDsMetadataKey] = excludedAuthIDs + } if selectedCallback := selectedAuthIDCallbackFromContext(ctx); selectedCallback != nil { meta[coreexecutor.SelectedAuthCallbackMetadataKey] = selectedCallback } diff --git a/sdk/api/handlers/handlers_context.go b/sdk/api/handlers/handlers_context.go index a986a040456..19c413454b1 100644 --- a/sdk/api/handlers/handlers_context.go +++ b/sdk/api/handlers/handlers_context.go @@ -12,6 +12,8 @@ import ( type pinnedAuthContextKey struct{} +type excludedAuthIDsContextKey struct{} + type selectedAuthCallbackContextKey struct{} type finalizedResponseFormatCallbackContextKey struct{} @@ -81,6 +83,33 @@ func WithPinnedAuthID(ctx context.Context, authID string) context.Context { return context.WithValue(ctx, pinnedAuthContextKey{}, authID) } +// WithExcludedAuthIDs returns a child context that excludes specific auth IDs from selection. +func WithExcludedAuthIDs(ctx context.Context, authIDs []string) context.Context { + if len(authIDs) == 0 { + return ctx + } + filtered := make([]string, 0, len(authIDs)) + seen := make(map[string]struct{}, len(authIDs)) + for _, authID := range authIDs { + trimmed := strings.TrimSpace(authID) + if trimmed == "" { + continue + } + if _, exists := seen[trimmed]; exists { + continue + } + seen[trimmed] = struct{}{} + filtered = append(filtered, trimmed) + } + if len(filtered) == 0 { + return ctx + } + if ctx == nil { + ctx = context.Background() + } + return context.WithValue(ctx, excludedAuthIDsContextKey{}, filtered) +} + // WithSelectedAuthIDCallback returns a child context that receives the selected auth ID. func WithSelectedAuthIDCallback(ctx context.Context, callback func(string)) context.Context { if callback == nil { @@ -217,6 +246,18 @@ func pinnedAuthIDFromContext(ctx context.Context) string { } } +func excludedAuthIDsFromContext(ctx context.Context) []string { + if ctx == nil { + return nil + } + raw := ctx.Value(excludedAuthIDsContextKey{}) + ids, ok := raw.([]string) + if !ok || len(ids) == 0 { + return nil + } + return append([]string(nil), ids...) +} + func selectedAuthIDCallbackFromContext(ctx context.Context) func(string) { if ctx == nil { return nil diff --git a/sdk/api/handlers/handlers_stream.go b/sdk/api/handlers/handlers_stream.go index e328adc5560..26fae15c757 100644 --- a/sdk/api/handlers/handlers_stream.go +++ b/sdk/api/handlers/handlers_stream.go @@ -47,6 +47,7 @@ func (h *BaseAPIHandler) HasAlternativeExecutionTarget(ctx context.Context, hand providers = adjustExecutionProvidersForEntryProtocol(handlerType, providers) reqMeta := requestExecutionMetadata(ctx) delete(reqMeta, coreexecutor.PinnedAuthMetadataKey) + delete(reqMeta, coreexecutor.ExcludedAuthIDsMetadataKey) delete(reqMeta, coreexecutor.ExecutionSessionMetadataKey) delete(reqMeta, coreexecutor.SelectedAuthCallbackMetadataKey) delete(reqMeta, coreexecutor.FinalizedResponseFormatCallbackMetadataKey) diff --git a/sdk/api/handlers/openai/openai_responses_websocket.go b/sdk/api/handlers/openai/openai_responses_websocket.go index 29a14ac8876..b59580ef239 100644 --- a/sdk/api/handlers/openai/openai_responses_websocket.go +++ b/sdk/api/handlers/openai/openai_responses_websocket.go @@ -932,62 +932,6 @@ func (h *OpenAIResponsesAPIHandler) ResponsesWebsocket(c *gin.Context) { } modelName := strings.Clone(ojson.GetBytesNoCopy(requestJSON, "model").String()) - lastAttemptedAuthID := pinnedAuthID - attemptedUpstreamMode := responsesWebsocketUpstreamModeUnknown - selectedAuthObserved := false - nativeRequest := util.IsCodexResponsesLiteRequest(payload, c.Request.Header) - var preserveNativeOutput atomic.Bool - codexDuplexStream.Store(false) - pinnedAuthAttempted := false - turnStartEpoch := inputEpoch.Load() - cliCtx, cliCancel := h.GetContextWithCancel(h, c, executionParent) - cliCtx = cliproxyexecutor.WithDownstreamWebsocket(cliCtx) - cliCtx = cliproxyexecutor.WithLocalWebsocketTurnTracker(cliCtx) - cliCtx = cliproxyexecutor.WithWebsocketInputEpoch(cliCtx, &inputEpoch, msgEpoch) - if duplexInput != nil { - cliCtx = cliproxyexecutor.WithWebsocketInput(cliCtx, duplexInput) - cliCtx = cliproxyexecutor.WithWebsocketAuthCheck(cliCtx, func(authID string) bool { - current, ok := sessionAuthByID(authID) - return ok && current != nil && !current.Disabled && current.Status != coreauth.StatusDisabled - }) - boundPrincipal := usage.APIKeyFromContext(cliCtx) - cliCtx = cliproxyexecutor.WithWebsocketTurnAuthorizer(cliCtx, func(turnPayload []byte) ([]byte, error) { - principal, errAuth := h.authenticateResponsesWebsocketTurn(c, upgradeRequest, turnPayload, modelName, false) - if errAuth == nil && principal != "" && principal != boundPrincipal { - errAuth = &interfaces.ErrorMessage{ - StatusCode: http.StatusUnauthorized, - Error: errors.New("client credential changed during the websocket stream; reconnect"), - } - } - if errAuth == nil { - return nil, nil - } - return buildResponsesWebsocketErrorPayload(errAuth) - }) - } - if nativeWebsocketPassthrough && requestRequiresCurrentUpstreamWebsocket { - cliCtx = cliproxyexecutor.WithRequiredUpstreamWebsocket(cliCtx) - } - cliCtx = handlers.WithExecutionSessionID(cliCtx, passthroughSessionID) - cliCtx = handlers.WithSelectedAuthIDCallback(cliCtx, func(authID string) { - preserveNativeOutput.Store(false) - codexDuplexStream.Store(false) - cliproxyexecutor.ResetLocalWebsocketTurn(cliCtx) - authID = strings.TrimSpace(authID) - if authID == "" || h == nil || h.AuthManager == nil { - return - } - lastAttemptedAuthID = authID - selectedAuthObserved = true - pinnedAuthAttempted = pinnedAuthAttempted || (pinnedAuthID != "" && authID == pinnedAuthID) - selectedAuth, ok := sessionAuthByID(authID) - if !ok || selectedAuth == nil { - return - } - attemptedUpstreamMode = upstreamModeForAuth(selectedAuth) - codexDuplexStream.Store(duplexInput != nil && attemptedUpstreamMode == responsesWebsocketUpstreamModeWS && strings.EqualFold(strings.TrimSpace(selectedAuth.Provider), "codex")) - preserveNativeOutput.Store(nativeRequest && strings.EqualFold(strings.TrimSpace(selectedAuth.Provider), "codex")) - }) executionAuthID := "" if !routeOverridesModelResolution { executionAuthID = pinnedAuthID @@ -995,112 +939,230 @@ func (h *OpenAIResponsesAPIHandler) ResponsesWebsocket(c *gin.Context) { if executionAuthID == "" { executionAuthID = observedCompactionReplayAuthID } - if executionAuthID != "" && !isPluginExecutorRoute { - cliCtx = handlers.WithPinnedAuthID(cliCtx, executionAuthID) - } - dataChan, _, errChan := h.ExecuteStreamWithAuthManager(cliCtx, h.HandlerType(), modelName, requestJSON, "") - if !selectedAuthObserved { - // Plugin/alternate routes bypass auth selection. Keep canonical HTTP-mode - // state instead of inheriting the previous pinned websocket mode. - attemptedUpstreamMode = responsesWebsocketUpstreamModeHTTP - } - // A connection-scoped continuation cannot rotate credentials in place. Suppress - // credential errors and make the client replay the full turn on a new socket - // when another eligible target can serve the replayed turn. - var lossWriteErr error - var replayedPinnedAuthFailure bool - replayPinnedAuthFailure := func(errMsg *interfaces.ErrorMessage) bool { - if cliproxyexecutor.IsUpstreamWebsocketTurnError(errMsg.Error) { - // The upstream websocket was lost: tell the client, keep its socket open, and - // fence the input it sent before the loss. A refused continuation is not a loss. - var turnErr *cliproxyexecutor.UpstreamWebsocketTurnError - if errors.As(errMsg.Error, &turnErr) { - if (turnErr.FullContextRequired || turnErr.NotSent || !codexDuplexStream.Load()) && - turnErr.EventID == "" && !turnErr.Idle && len(turnErr.Abandoned) == 0 { - turnErr.EventID = strings.Clone(strings.TrimSpace(ojson.GetBytesNoCopy(payload, "event_id").String())) + + var excludedAuthIDs []string + retriedPinnedFailover := false + var lastAttemptedAuthID string + var attemptedUpstreamMode string + var selectedAuthObserved bool + var preserveNativeOutput atomic.Bool + var pinnedAuthAttempted bool + var cliCtx context.Context + var completedOutput []byte + var completedResponseID string + var completedPendingToolCallIDs []string + var forwardErrMsg *interfaces.ErrorMessage + + for { + lastAttemptedAuthID = pinnedAuthID + attemptedUpstreamMode = responsesWebsocketUpstreamModeUnknown + selectedAuthObserved = false + nativeRequest := util.IsCodexResponsesLiteRequest(payload, c.Request.Header) + preserveNativeOutput.Store(false) + codexDuplexStream.Store(false) + pinnedAuthAttempted = false + turnStartEpoch := inputEpoch.Load() + var cliCancel handlers.APIHandlerCancelFunc + cliCtx, cliCancel = h.GetContextWithCancel(h, c, executionParent) + cliCtx = cliproxyexecutor.WithDownstreamWebsocket(cliCtx) + cliCtx = cliproxyexecutor.WithLocalWebsocketTurnTracker(cliCtx) + cliCtx = cliproxyexecutor.WithWebsocketInputEpoch(cliCtx, &inputEpoch, msgEpoch) + if duplexInput != nil { + cliCtx = cliproxyexecutor.WithWebsocketInput(cliCtx, duplexInput) + cliCtx = cliproxyexecutor.WithWebsocketAuthCheck(cliCtx, func(authID string) bool { + current, ok := sessionAuthByID(authID) + return ok && current != nil && !current.Disabled && current.Status != coreauth.StatusDisabled + }) + boundPrincipal := usage.APIKeyFromContext(cliCtx) + cliCtx = cliproxyexecutor.WithWebsocketTurnAuthorizer(cliCtx, func(turnPayload []byte) ([]byte, error) { + principal, errAuth := h.authenticateResponsesWebsocketTurn(c, upgradeRequest, turnPayload, modelName, false) + if errAuth == nil && principal != "" && principal != boundPrincipal { + errAuth = &interfaces.ErrorMessage{ + StatusCode: http.StatusUnauthorized, + Error: errors.New("client credential changed during the websocket stream; reconnect"), + } } - if !turnErr.FullContextRequired && !turnErr.NotSent && inputEpoch.Load() == turnStartEpoch { - inputEpoch.Add(1) + if errAuth == nil { + return nil, nil } + return buildResponsesWebsocketErrorPayload(errAuth) + }) + } + if nativeWebsocketPassthrough && requestRequiresCurrentUpstreamWebsocket { + cliCtx = cliproxyexecutor.WithRequiredUpstreamWebsocket(cliCtx) + } + cliCtx = handlers.WithExecutionSessionID(cliCtx, passthroughSessionID) + cliCtx = handlers.WithSelectedAuthIDCallback(cliCtx, func(authID string) { + preserveNativeOutput.Store(false) + codexDuplexStream.Store(false) + cliproxyexecutor.ResetLocalWebsocketTurn(cliCtx) + authID = strings.TrimSpace(authID) + if authID == "" || h == nil || h.AuthManager == nil { + return } - lossWriteErr = writeResponsesWebsocketUpstreamLoss(writer, wsTimelineLog, errMsg) - return true + lastAttemptedAuthID = authID + selectedAuthObserved = true + pinnedAuthAttempted = pinnedAuthAttempted || (pinnedAuthID != "" && authID == pinnedAuthID) + selectedAuth, ok := sessionAuthByID(authID) + if !ok || selectedAuth == nil { + return + } + attemptedUpstreamMode = upstreamModeForAuth(selectedAuth) + codexDuplexStream.Store(duplexInput != nil && attemptedUpstreamMode == responsesWebsocketUpstreamModeWS && strings.EqualFold(strings.TrimSpace(selectedAuth.Provider), "codex")) + preserveNativeOutput.Store(nativeRequest && strings.EqualFold(strings.TrimSpace(selectedAuth.Provider), "codex")) + }) + if executionAuthID != "" && !isPluginExecutorRoute { + cliCtx = handlers.WithPinnedAuthID(cliCtx, executionAuthID) } - if !nativeWebsocketPassthrough || !requestRequiresCurrentUpstreamWebsocket || !pinnedAuthAttempted || - !shouldReplayResponsesWebsocketPinnedAuthFailure(errMsg) { - return false + if len(excludedAuthIDs) > 0 { + cliCtx = handlers.WithExcludedAuthIDs(cliCtx, excludedAuthIDs) } - if (responsesWebsocketErrorStatus(errMsg) == http.StatusTooManyRequests || isResponsesWebsocketQuotaOrCooldownError(errMsg.Error)) && - !h.responsesWebsocketHasAlternativeReplayTarget(cliCtx, modelName, requestJSON, lastAttemptedAuthID) { - return false + dataChan, _, errChan := h.ExecuteStreamWithAuthManager(cliCtx, h.HandlerType(), modelName, requestJSON, "") + if !selectedAuthObserved { + // Plugin/alternate routes bypass auth selection. Keep canonical HTTP-mode + // state instead of inheriting the previous pinned websocket mode. + attemptedUpstreamMode = responsesWebsocketUpstreamModeHTTP + } + // A connection-scoped continuation cannot rotate credentials in place. Suppress + // credential errors and make the client replay the full turn on a new socket + // when another eligible target can serve the replayed turn. For a self-contained + // full response.create that fails before committing any downstream output, unpin + // and fail over in place on the existing downstream socket. + var lossWriteErr error + var replayedPinnedAuthFailure bool + var failoverInPlace bool + var downstreamCommitted atomic.Bool + replayPinnedAuthFailure := func(errMsg *interfaces.ErrorMessage) bool { + if cliproxyexecutor.IsUpstreamWebsocketTurnError(errMsg.Error) { + // The upstream websocket was lost: tell the client, keep its socket open, and + // fence the input it sent before the loss. A refused continuation is not a loss. + var turnErr *cliproxyexecutor.UpstreamWebsocketTurnError + if errors.As(errMsg.Error, &turnErr) { + if (turnErr.FullContextRequired || turnErr.NotSent || !codexDuplexStream.Load()) && + turnErr.EventID == "" && !turnErr.Idle && len(turnErr.Abandoned) == 0 { + turnErr.EventID = strings.Clone(strings.TrimSpace(ojson.GetBytesNoCopy(payload, "event_id").String())) + } + if !turnErr.FullContextRequired && !turnErr.NotSent && inputEpoch.Load() == turnStartEpoch { + inputEpoch.Add(1) + } + } + lossWriteErr = writeResponsesWebsocketUpstreamLoss(writer, wsTimelineLog, errMsg) + return true + } + if !nativeWebsocketPassthrough || !pinnedAuthAttempted { + return false + } + if !shouldReplayResponsesWebsocketPinnedAuthFailure(errMsg) && + !isResponsesWebsocketQuotaOrCooldownError(errMsg.Error) { + return false + } + if !requestRequiresCurrentUpstreamWebsocket { + if retriedPinnedFailover || downstreamCommitted.Load() { + return false + } + if !h.responsesWebsocketHasAlternativeReplayTarget(cliCtx, modelName, requestJSON, lastAttemptedAuthID) { + return false + } + failoverInPlace = true + return true + } + if (responsesWebsocketErrorStatus(errMsg) == http.StatusTooManyRequests || isResponsesWebsocketQuotaOrCooldownError(errMsg.Error)) && + !h.responsesWebsocketHasAlternativeReplayTarget(cliCtx, modelName, requestJSON, lastAttemptedAuthID) { + return false + } + replayedPinnedAuthFailure = true + return true } - replayedPinnedAuthFailure = true - return true - } - completedOutput, completedResponseID, completedPendingToolCallIDs, forwardErrMsg, errForward := h.forwardResponsesWebsocket( - c, - writer, - cliCancel, - dataChan, - errChan, - wsTimelineLog, - passthroughSessionID, - responsesWebsocketForwardOptions{ - preserveCompletionOutput: preserveNativeOutput.Load, - duplexStream: func() bool { - return codexDuplexStream.Load() && !cliproxyexecutor.LocalWebsocketTurnExecuted(cliCtx) - }, - toolCacheTurn: toolCacheTurn, - suppressError: replayPinnedAuthFailure, - localInterrupt: localInterrupt, - websocketOwned: func() bool { - return attemptedUpstreamMode == responsesWebsocketUpstreamModeWS && !cliproxyexecutor.LocalWebsocketTurnExecuted(cliCtx) + var errForward error + completedOutput, completedResponseID, completedPendingToolCallIDs, forwardErrMsg, errForward = h.forwardResponsesWebsocket( + c, + writer, + cliCancel, + dataChan, + errChan, + wsTimelineLog, + passthroughSessionID, + responsesWebsocketForwardOptions{ + preserveCompletionOutput: preserveNativeOutput.Load, + duplexStream: func() bool { + return codexDuplexStream.Load() && !cliproxyexecutor.LocalWebsocketTurnExecuted(cliCtx) + }, + toolCacheTurn: toolCacheTurn, + suppressError: replayPinnedAuthFailure, + onDownstreamCommit: func() { downstreamCommitted.Store(true) }, + localInterrupt: localInterrupt, + websocketOwned: func() bool { + return attemptedUpstreamMode == responsesWebsocketUpstreamModeWS && !cliproxyexecutor.LocalWebsocketTurnExecuted(cliCtx) + }, }, - }, - ) - if errForward != nil { - wsTerminateErr = errForward - switch { - case errors.Is(errForward, websocket.ErrCloseSent): - case isWebsocketConnectionClosedError(errForward): - // The client hung up while a downstream write was in flight. This is a - // normal shutdown race, not a proxy failure. - log.Debugf("responses websocket: client closed during forward id=%s error=%v", passthroughSessionID, errForward) - default: - log.Warnf("responses websocket: forward failed id=%s error=%v", passthroughSessionID, errForward) - } - return - } - if forwardErrMsg != nil && cliproxyexecutor.IsUpstreamWebsocketTurnError(forwardErrMsg.Error) { - if lossWriteErr != nil { - wsTerminateErr = lossWriteErr + ) + cliCancel(nil) + if errForward != nil { + wsTerminateErr = errForward + switch { + case errors.Is(errForward, websocket.ErrCloseSent): + case isWebsocketConnectionClosedError(errForward): + // The client hung up while a downstream write was in flight. This is a + // normal shutdown race, not a proxy failure. + log.Debugf("responses websocket: client closed during forward id=%s error=%v", passthroughSessionID, errForward) + default: + log.Warnf("responses websocket: forward failed id=%s error=%v", passthroughSessionID, errForward) + } return } - // Keep the credential: the next full create reconnects on it, never on another one. - if (attemptedUpstreamMode == responsesWebsocketUpstreamModeWS || upstreamMode == responsesWebsocketUpstreamModeWS) && lastAttemptedAuthID != "" { - upstreamMode = responsesWebsocketUpstreamModeWS - upstreamWebsocketAuthID = lastAttemptedAuthID - rememberPinnedAuth(lastAttemptedAuthID, modelName) - passthroughModelName = modelName - } - continue - } - if forwardErrMsg != nil { - if pinnedAuthAttempted && shouldReleaseResponsesWebsocketPinnedAuth(forwardErrMsg) { - forgetPinnedAuth() + if forwardErrMsg != nil && cliproxyexecutor.IsUpstreamWebsocketTurnError(forwardErrMsg.Error) { + if lossWriteErr != nil { + wsTerminateErr = lossWriteErr + return + } + // Keep the credential: the next full create reconnects on it, never on another one. + if (attemptedUpstreamMode == responsesWebsocketUpstreamModeWS || upstreamMode == responsesWebsocketUpstreamModeWS) && lastAttemptedAuthID != "" { + upstreamMode = responsesWebsocketUpstreamModeWS + upstreamWebsocketAuthID = lastAttemptedAuthID + rememberPinnedAuth(lastAttemptedAuthID, modelName) + passthroughModelName = modelName + } + break } - if replayedPinnedAuthFailure { - replayErr := responsesWebsocketHTTPReplayRequiredError() - wsTerminateErr = replayErr - matched, errClose := writer.closeForUpstreamError(replayErr) - if !matched { - _ = conn.Close() - } else if errClose != nil && !errors.Is(errClose, websocket.ErrCloseSent) { - log.Debugf("responses websocket: credential replay close failed id=%s error=%v", passthroughSessionID, errClose) + if forwardErrMsg != nil { + if failoverInPlace { + retriedPinnedFailover = true + if lastAttemptedAuthID != "" { + excludedAuthIDs = append(excludedAuthIDs, lastAttemptedAuthID) + } + forgetPinnedAuth() + upstreamWebsocketAuthID = "" + upstreamMode = responsesWebsocketUpstreamModeUnknown + observedCompactionReplayAuthID = "" + executionAuthID = "" + nativeWebsocketPassthrough = false + failoverDoc := ojson.NewDoc(requestJSON) + _ = failoverDoc.Delete("type") + requestJSON = failoverDoc.Bytes() + requestJSON, toolCacheTurn = prepareResponsesWebsocketFallbackTurn(downstreamSessionKey, requestJSON) + nextLastRequest = requestJSON + continue } - return + if pinnedAuthAttempted && shouldReleaseResponsesWebsocketPinnedAuth(forwardErrMsg) { + forgetPinnedAuth() + } + if replayedPinnedAuthFailure { + replayErr := responsesWebsocketHTTPReplayRequiredError() + wsTerminateErr = replayErr + matched, errClose := writer.closeForUpstreamError(replayErr) + if !matched { + _ = conn.Close() + } else if errClose != nil && !errors.Is(errClose, websocket.ErrCloseSent) { + log.Debugf("responses websocket: credential replay close failed id=%s error=%v", passthroughSessionID, errClose) + } + return + } + break } + break + } + if forwardErrMsg != nil { continue } diff --git a/sdk/api/handlers/openai/openai_responses_websocket_forward.go b/sdk/api/handlers/openai/openai_responses_websocket_forward.go index c81aae3c4d1..278997c3e33 100644 --- a/sdk/api/handlers/openai/openai_responses_websocket_forward.go +++ b/sdk/api/handlers/openai/openai_responses_websocket_forward.go @@ -28,6 +28,7 @@ type responsesWebsocketForwardOptions struct { duplexStream func() bool toolCacheTurn *responsesWebsocketToolCacheTurn suppressError func(*interfaces.ErrorMessage) bool + onDownstreamCommit func() localInterrupt *responsesLocalInterrupt // websocketOwned reports whether this turn runs on an upstream // websocket. While true, no interrupt may claim the local HTTP path. @@ -65,6 +66,11 @@ func (h *OpenAIResponsesAPIHandler) forwardResponsesWebsocket( downstreamSessionKey = websocketDownstreamSessionKey(c.Request) } + markDownstreamCommitted := func() { + if opts.onDownstreamCommit != nil { + opts.onDownstreamCommit() + } + } if opts.localInterrupt != nil { websocketOwned := opts.websocketOwned != nil && opts.websocketOwned() opts.localInterrupt.begin(websocketOwned) @@ -81,6 +87,7 @@ func (h *OpenAIResponsesAPIHandler) forwardResponsesWebsocket( // already gone need no answer. if c.Request.Context().Err() == nil { if claimed := opts.localInterrupt.takeClaimed(); claimed != nil { + markDownstreamCommitted() _, _ = writeResponsesWebsocketError(writer, wsTimelineLog, &interfaces.ErrorMessage{ StatusCode: http.StatusBadRequest, Error: errors.New("no active response to interrupt"), @@ -138,6 +145,7 @@ func (h *OpenAIResponsesAPIHandler) forwardResponsesWebsocket( } continue } + markDownstreamCommitted() return completeResponsesWebsocketLocalInterrupt(writer, wsTimelineLog, cancel, interruptPayload, outputItemsByIndex, outputItemsFallback, pendingToolCallIDs) case <-c.Request.Context().Done(): cause := context.Cause(c.Request.Context()) @@ -200,10 +208,12 @@ func (h *OpenAIResponsesAPIHandler) forwardResponsesWebsocket( if opts.localInterrupt != nil { if interruptPayload := opts.localInterrupt.takeClaimed(); interruptPayload != nil { if !turnEnded { + markDownstreamCommitted() return completeResponsesWebsocketLocalInterrupt(writer, wsTimelineLog, cancel, interruptPayload, outputItemsByIndex, outputItemsFallback, pendingToolCallIDs) } // The response is over: reject instead of fabricating an // incomplete event, then keep forwarding this chunk. + markDownstreamCommitted() if _, errWrite := writeResponsesWebsocketError(writer, wsTimelineLog, &interfaces.ErrorMessage{ StatusCode: http.StatusBadRequest, Error: errors.New("no active response to interrupt"), @@ -223,6 +233,7 @@ func (h *OpenAIResponsesAPIHandler) forwardResponsesWebsocket( } if eventType == "response.created" { responseStarted = true + markDownstreamCommitted() completed = false turnEnded = false if opts.localInterrupt != nil { @@ -246,20 +257,26 @@ func (h *OpenAIResponsesAPIHandler) forwardResponsesWebsocket( // In Codex duplex mode the executor owns connection termination: // payload errors after response.created are recoverable events; // StreamChunk.Err still arrives through errs and closes the socket. - preserveErrorEvent := responseStarted && opts.duplexStream != nil && opts.duplexStream() - if eventType == wsEventTypeError && preserveErrorEvent { - turnEnded = true - if errMsg := responsesWebsocketErrorMessageFromPayload(payloads[i]); errMsg != nil && h != nil { - h.LoggingAPIResponseError(context.WithValue(context.Background(), "gin", c), errMsg) - } - } else if eventType == wsEventTypeError && !preserveErrorEvent { - payloadErrMsg = responsesWebsocketErrorMessageFromPayload(payloads[i]) - if h != nil { - h.LoggingAPIResponseError(context.WithValue(context.Background(), "gin", c), payloadErrMsg) - } - if opts.suppressError != nil && opts.suppressError(payloadErrMsg) { - cancel(payloadErrMsg.Error) - return completedOutput, completedResponseID, sortedStringSet(pendingToolCallIDs), payloadErrMsg, nil + // Known credential quota/cooldown errors are not recoverable on the + // same socket and must still consult the replay guard. + if eventType == wsEventTypeError { + errMsg := responsesWebsocketErrorMessageFromPayload(payloads[i]) + preserveErrorEvent := responseStarted && opts.duplexStream != nil && opts.duplexStream() && + (errMsg == nil || !isResponsesWebsocketQuotaOrCooldownError(errMsg.Error)) + if preserveErrorEvent { + turnEnded = true + if errMsg != nil && h != nil { + h.LoggingAPIResponseError(context.WithValue(context.Background(), "gin", c), errMsg) + } + } else { + payloadErrMsg = errMsg + if h != nil { + h.LoggingAPIResponseError(context.WithValue(context.Background(), "gin", c), payloadErrMsg) + } + if opts.suppressError != nil && opts.suppressError(payloadErrMsg) { + cancel(payloadErrMsg.Error) + return completedOutput, completedResponseID, sortedStringSet(pendingToolCallIDs), payloadErrMsg, nil + } } } else if isResponsesWebsocketCompletionEvent(eventType) || eventType == "response.incomplete" { // response.incomplete ends the turn too. Codex uses it, with @@ -312,6 +329,7 @@ func (h *OpenAIResponsesAPIHandler) forwardResponsesWebsocket( // reactivated it. opts.localInterrupt.deactivate() } + markDownstreamCommitted() if errWrite := writeResponsesWebsocketPayload(writer, wsTimelineLog, payloads[i], time.Now()); errWrite != nil { log.Warnf( "responses websocket: downstream_out write failed id=%s event=%s error=%v", diff --git a/sdk/api/handlers/openai/openai_responses_websocket_loss_test.go b/sdk/api/handlers/openai/openai_responses_websocket_loss_test.go index bcd1064c2ad..8ab13cb4ea4 100644 --- a/sdk/api/handlers/openai/openai_responses_websocket_loss_test.go +++ b/sdk/api/handlers/openai/openai_responses_websocket_loss_test.go @@ -1579,3 +1579,347 @@ func TestBuildResponsesWebsocketErrorPayloadSuppressesStaleRetryAfterWhenTrusted t.Fatalf("headers.X-Request-Id = %q, want req-1 (%s)", got, payload) } } + +func TestResponsesWebsocketSameSessionLaterCreate429FailoverToAlternativeCredential(t *testing.T) { + gin.SetMode(gin.TestMode) + + const quota429Frame = `{"type":"error","status":429,"error":{"type":"usage_limit_reached","message":"The usage limit has been reached","plan_type":"team","resets_in_seconds":3600}}` + + for _, buffering := range []bool{false, true} { + t.Run(fmt.Sprintf("buffering=%t", buffering), func(t *testing.T) { + var authACreates, authBCreates atomic.Int32 + var authA429Next atomic.Bool + + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + authHeader := strings.TrimSpace(r.Header.Get("Authorization")) + if authHeader != "Bearer key-a" && authHeader != "Bearer key-b" { + t.Errorf("unexpected Authorization header: %q", authHeader) + http.Error(w, "unauthorized", http.StatusUnauthorized) + return + } + c, errUpgrade := (&websocket.Upgrader{}).Upgrade(w, r, nil) + if errUpgrade != nil { + t.Error(errUpgrade) + return + } + defer func() { _ = c.Close() }() + _ = c.SetReadDeadline(time.Now().Add(10 * time.Second)) + + for { + _, payload, errRead := c.ReadMessage() + if errRead != nil { + return + } + if ojson.GetBytesNoCopy(payload, "type").String() != "response.create" { + continue + } + if authHeader == "Bearer key-a" { + turn := authACreates.Add(1) + if authA429Next.Load() { + if buffering { + _ = c.WriteMessage(websocket.TextMessage, []byte(`{"type":"response.created","response":{"id":"resp-a-buffered","status":"in_progress","output":[]}}`)) + _ = c.WriteMessage(websocket.TextMessage, []byte(`{"type":"response.in_progress","response":{"id":"resp-a-buffered","status":"in_progress","output":[]}}`)) + } + _ = c.WriteMessage(websocket.TextMessage, []byte(quota429Frame)) + continue + } + respID := fmt.Sprintf("resp-a-%d", turn) + _ = c.WriteMessage(websocket.TextMessage, []byte(fmt.Sprintf(`{"type":"response.created","response":{"id":%q,"status":"in_progress","output":[]}}`, respID))) + _ = c.WriteMessage(websocket.TextMessage, []byte(fmt.Sprintf(`{"type":"response.completed","response":{"id":%q,"status":"completed","output":[{"id":"msg-a-%d","type":"message","role":"assistant","content":[{"type":"output_text","text":"from-a"}]}]}}`, respID, turn))) + continue + } + turn := authBCreates.Add(1) + respID := fmt.Sprintf("resp-b-%d", turn) + _ = c.WriteMessage(websocket.TextMessage, []byte(fmt.Sprintf(`{"type":"response.created","response":{"id":%q,"status":"in_progress","output":[]}}`, respID))) + _ = c.WriteMessage(websocket.TextMessage, []byte(fmt.Sprintf(`{"type":"response.completed","response":{"id":%q,"status":"completed","output":[{"id":"msg-b-%d","type":"message","role":"assistant","content":[{"type":"output_text","text":"from-b"}]}]}}`, respID, turn))) + } + })) + t.Cleanup(upstream.Close) + + cfg := &config.Config{ + DisableCooling: false, + RequestRetry: 3, + MaxRetryCredentials: 0, + Codex: config.CodexConfig{ + StreamBootstrapBuffering: buffering, + }, + } + manager := coreauth.NewManager(nil, &coreauth.FillFirstSelector{}, nil) + manager.SetConfig(cfg) + manager.SetRetryConfig(cfg.RequestRetry, 0, cfg.MaxRetryCredentials) + manager.RegisterExecutor(runtimeexecutor.NewCodexAutoExecutor(cfg)) + + modelName := "codex-same-session-create-429-" + strings.ReplaceAll(t.Name(), "/", "-") + authAID := "auth-a-" + modelName + authBID := "auth-b-" + modelName + for _, spec := range []struct { + id string + key string + priority string + }{ + {id: authAID, key: "key-a", priority: "4"}, + {id: authBID, key: "key-b", priority: "3"}, + } { + if _, errRegister := manager.Register(context.Background(), &coreauth.Auth{ + ID: spec.id, + Provider: "codex", + Status: coreauth.StatusActive, + Attributes: map[string]string{ + "api_key": spec.key, + "base_url": upstream.URL, + "websockets": "true", + "priority": spec.priority, + }, + }); errRegister != nil { + t.Fatal(errRegister) + } + registry.GetGlobalRegistry().RegisterClient(spec.id, "codex", []*registry.ModelInfo{{ID: modelName}}) + id := spec.id + t.Cleanup(func() { registry.GetGlobalRegistry().UnregisterClient(id) }) + } + + base := handlers.NewBaseAPIHandlers(&cfg.SDKConfig, manager) + h := NewOpenAIResponsesAPIHandler(base) + router := gin.New() + router.GET("/v1/responses", h.ResponsesWebsocket) + downstream := httptest.NewServer(router) + t.Cleanup(downstream.Close) + wsURL := "ws" + strings.TrimPrefix(downstream.URL, "http") + "/v1/responses" + + conn, resp, errDial := websocket.DefaultDialer.Dial(wsURL, nil) + if resp != nil && resp.Body != nil { + defer func() { _ = resp.Body.Close() }() + } + if errDial != nil { + t.Fatalf("dial downstream websocket: %v", errDial) + } + defer func() { _ = conn.Close() }() + + // Turn 1: full response.create succeeds on auth-a and pins auth-a for the connection. + req1 := fmt.Sprintf(`{"type":"response.create","model":%q,"input":[{"type":"message","id":"msg-1","role":"user","content":"turn-1"}]}`, modelName) + if errWrite := conn.WriteMessage(websocket.TextMessage, []byte(req1)); errWrite != nil { + t.Fatalf("write turn 1: %v", errWrite) + } + for { + _ = conn.SetReadDeadline(time.Now().Add(5 * time.Second)) + _, frame, errRead := conn.ReadMessage() + if errRead != nil { + t.Fatalf("turn 1 read failed: %v", errRead) + } + if ojson.GetBytesNoCopy(frame, "type").String() == "response.completed" { + if got := ojson.GetBytesNoCopy(frame, "response.id").String(); got != "resp-a-1" { + t.Fatalf("turn 1 response.id = %q, want resp-a-1", got) + } + break + } + } + + // Turn 2: on the same downstream websocket, auth-a is now quota-exhausted and returns + // a pre-content 429 usage_limit_reached. Another full response.create must fail over + // to auth-b without closing the downstream websocket or leaking frames from auth-a. + authA429Next.Store(true) + req2 := fmt.Sprintf(`{"type":"response.create","model":%q,"input":[{"type":"message","id":"msg-2","role":"user","content":"turn-2"}]}`, modelName) + if errWrite := conn.WriteMessage(websocket.TextMessage, []byte(req2)); errWrite != nil { + t.Fatalf("write turn 2: %v", errWrite) + } + var turn2Completed []byte + for { + _ = conn.SetReadDeadline(time.Now().Add(5 * time.Second)) + _, frame, errRead := conn.ReadMessage() + if errRead != nil { + t.Fatalf("turn 2 failed instead of failing over to auth-b: %v (authACreates=%d authBCreates=%d)", errRead, authACreates.Load(), authBCreates.Load()) + } + if gotID := ojson.GetBytesNoCopy(frame, "response.id").String(); gotID == "resp-a-buffered" { + t.Fatalf("buffered frame from failed credential A leaked to downstream: %s", frame) + } + if ojson.GetBytesNoCopy(frame, "type").String() == "error" { + t.Fatalf("received error frame instead of failing over to auth-b: %s", frame) + } + if ojson.GetBytesNoCopy(frame, "type").String() == "response.completed" { + turn2Completed = frame + break + } + } + if got := ojson.GetBytesNoCopy(turn2Completed, "response.id").String(); got != "resp-b-1" { + t.Fatalf("turn 2 response.id = %q, want resp-b-1", got) + } + if authACreates.Load() != 2 || authBCreates.Load() != 1 { + t.Fatalf("after turn 2: authACreates=%d authBCreates=%d, want 2 and 1", authACreates.Load(), authBCreates.Load()) + } + + authA, okA := manager.GetByID(authAID) + if !okA || authA == nil || !authA.Quota.Exceeded { + t.Fatalf("expected auth-a quota exceeded cooldown to be recorded, got %+v (ok=%t)", authA, okA) + } + + // Turn 3: continuation on the same downstream websocket must stay pinned to auth-b. + req3 := fmt.Sprintf(`{"type":"response.create","model":%q,"previous_response_id":"resp-b-1","input":[{"type":"message","id":"msg-3","role":"user","content":"turn-3"}]}`, modelName) + if errWrite := conn.WriteMessage(websocket.TextMessage, []byte(req3)); errWrite != nil { + t.Fatalf("write turn 3: %v", errWrite) + } + for { + _ = conn.SetReadDeadline(time.Now().Add(5 * time.Second)) + _, frame, errRead := conn.ReadMessage() + if errRead != nil { + t.Fatalf("turn 3 read failed: %v", errRead) + } + if ojson.GetBytesNoCopy(frame, "type").String() == "response.completed" { + if got := ojson.GetBytesNoCopy(frame, "response.id").String(); got != "resp-b-2" { + t.Fatalf("turn 3 response.id = %q, want resp-b-2", got) + } + break + } + } + if authACreates.Load() != 2 || authBCreates.Load() != 2 { + t.Fatalf("after turn 3: authACreates=%d authBCreates=%d, want 2 and 2", authACreates.Load(), authBCreates.Load()) + } + }) + } +} + +func TestResponsesWebsocketSameSessionLaterCreate429DoesNotReplayAfterDownstreamCommit(t *testing.T) { + gin.SetMode(gin.TestMode) + + const quota429Frame = `{"type":"error","status":429,"error":{"type":"usage_limit_reached","message":"The usage limit has been reached","plan_type":"team","resets_in_seconds":3600}}` + + var authACreates, authBCreates atomic.Int32 + var authA429Next atomic.Bool + downstreamGotCreated := make(chan struct{}) + + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + authHeader := strings.TrimSpace(r.Header.Get("Authorization")) + c, errUpgrade := (&websocket.Upgrader{}).Upgrade(w, r, nil) + if errUpgrade != nil { + t.Error(errUpgrade) + return + } + defer func() { _ = c.Close() }() + _ = c.SetReadDeadline(time.Now().Add(10 * time.Second)) + + for { + _, payload, errRead := c.ReadMessage() + if errRead != nil { + return + } + if ojson.GetBytesNoCopy(payload, "type").String() != "response.create" { + continue + } + if authHeader == "Bearer key-b" { + authBCreates.Add(1) + _ = c.WriteMessage(websocket.TextMessage, []byte(`{"type":"response.completed","response":{"id":"resp-b-1","status":"completed","output":[]}}`)) + continue + } + turn := authACreates.Add(1) + if authA429Next.Load() { + // Emit response.created before the 429 error while buffering is disabled so + // downstream observes a committed response frame before the error arrives. + _ = c.WriteMessage(websocket.TextMessage, []byte(`{"type":"response.created","response":{"id":"resp-a-committed","status":"in_progress","output":[]}}`)) + select { + case <-downstreamGotCreated: + case <-time.After(5 * time.Second): + t.Error("timed out waiting for downstream to receive response.created") + return + } + _ = c.WriteMessage(websocket.TextMessage, []byte(quota429Frame)) + continue + } + respID := fmt.Sprintf("resp-a-%d", turn) + _ = c.WriteMessage(websocket.TextMessage, []byte(fmt.Sprintf(`{"type":"response.created","response":{"id":%q,"status":"in_progress","output":[]}}`, respID))) + _ = c.WriteMessage(websocket.TextMessage, []byte(fmt.Sprintf(`{"type":"response.completed","response":{"id":%q,"status":"completed","output":[]}}`, respID))) + } + })) + t.Cleanup(upstream.Close) + + cfg := &config.Config{ + DisableCooling: false, + RequestRetry: 3, + MaxRetryCredentials: 0, + Codex: config.CodexConfig{ + StreamBootstrapBuffering: false, + }, + } + manager := coreauth.NewManager(nil, &coreauth.FillFirstSelector{}, nil) + manager.SetConfig(cfg) + manager.SetRetryConfig(cfg.RequestRetry, 0, cfg.MaxRetryCredentials) + manager.RegisterExecutor(runtimeexecutor.NewCodexAutoExecutor(cfg)) + + modelName := "codex-committed-no-replay-429" + authAID := "auth-a-" + modelName + authBID := "auth-b-" + modelName + for _, spec := range []struct { + id string + key string + priority string + }{ + {id: authAID, key: "key-a", priority: "4"}, + {id: authBID, key: "key-b", priority: "3"}, + } { + if _, errRegister := manager.Register(context.Background(), &coreauth.Auth{ + ID: spec.id, + Provider: "codex", + Status: coreauth.StatusActive, + Attributes: map[string]string{ + "api_key": spec.key, + "base_url": upstream.URL, + "websockets": "true", + "priority": spec.priority, + }, + }); errRegister != nil { + t.Fatal(errRegister) + } + registry.GetGlobalRegistry().RegisterClient(spec.id, "codex", []*registry.ModelInfo{{ID: modelName}}) + id := spec.id + t.Cleanup(func() { registry.GetGlobalRegistry().UnregisterClient(id) }) + } + + base := handlers.NewBaseAPIHandlers(&cfg.SDKConfig, manager) + h := NewOpenAIResponsesAPIHandler(base) + router := gin.New() + router.GET("/v1/responses", h.ResponsesWebsocket) + downstream := httptest.NewServer(router) + t.Cleanup(downstream.Close) + wsURL := "ws" + strings.TrimPrefix(downstream.URL, "http") + "/v1/responses" + + conn, resp, errDial := websocket.DefaultDialer.Dial(wsURL, nil) + if resp != nil && resp.Body != nil { + defer func() { _ = resp.Body.Close() }() + } + if errDial != nil { + t.Fatalf("dial downstream websocket: %v", errDial) + } + defer func() { _ = conn.Close() }() + + req1 := fmt.Sprintf(`{"type":"response.create","model":%q,"input":[{"type":"message","id":"msg-1","role":"user","content":"turn-1"}]}`, modelName) + if errWrite := conn.WriteMessage(websocket.TextMessage, []byte(req1)); errWrite != nil { + t.Fatalf("write turn 1: %v", errWrite) + } + for { + _ = conn.SetReadDeadline(time.Now().Add(5 * time.Second)) + _, frame, errRead := conn.ReadMessage() + if errRead != nil { + t.Fatalf("turn 1 failed: %v", errRead) + } + if ojson.GetBytesNoCopy(frame, "type").String() == "response.completed" { + break + } + } + + authA429Next.Store(true) + req2 := fmt.Sprintf(`{"type":"response.create","model":%q,"input":[{"type":"message","id":"msg-2","role":"user","content":"turn-2"}]}`, modelName) + if errWrite := conn.WriteMessage(websocket.TextMessage, []byte(req2)); errWrite != nil { + t.Fatalf("write turn 2: %v", errWrite) + } + _ = conn.SetReadDeadline(time.Now().Add(5 * time.Second)) + _, frame1, errRead1 := conn.ReadMessage() + if errRead1 != nil || ojson.GetBytesNoCopy(frame1, "type").String() != "response.created" { + t.Fatalf("turn 2 first frame = %s, err=%v; want committed response.created", frame1, errRead1) + } + close(downstreamGotCreated) + _, frame2, errRead2 := conn.ReadMessage() + if errRead2 != nil || ojson.GetBytesNoCopy(frame2, "type").String() != "error" || int(ojson.GetBytesNoCopy(frame2, "status").Int()) != http.StatusTooManyRequests { + t.Fatalf("turn 2 second frame = %s, err=%v; want terminal 429 error frame without replay", frame2, errRead2) + } + if authBCreates.Load() != 0 { + t.Fatalf("authBCreates = %d, want 0 (must not silently replay after downstream commit)", authBCreates.Load()) + } +} diff --git a/sdk/api/handlers/openai/openai_responses_websocket_test.go b/sdk/api/handlers/openai/openai_responses_websocket_test.go index 9a2b6b51fe9..7420636bcbe 100644 --- a/sdk/api/handlers/openai/openai_responses_websocket_test.go +++ b/sdk/api/handlers/openai/openai_responses_websocket_test.go @@ -8229,3 +8229,318 @@ func TestForwardResponsesWebsocketPrefersBufferedErrorOverClosedData(t *testing. } } } + +func TestForwardResponsesWebsocketDuplexErrorClassificationAfterResponseCreated(t *testing.T) { + gin.SetMode(gin.TestMode) + + const createdFrame = `{"type":"response.created","response":{"id":"r-quota"}}` + + t.Run("quota_and_cooldown_consult_replay_guard_when_suppressed", func(t *testing.T) { + for _, tc := range []struct { + name string + errorFrame string + }{ + { + name: "usage_limit_reached", + errorFrame: `{"type":"error","status":429,"error":{"type":"usage_limit_reached","message":"exhausted"}}`, + }, + { + name: "model_cooldown", + errorFrame: `{"type":"error","status":429,"error":{"code":"model_cooldown","message":"cooling down"}}`, + }, + } { + t.Run(tc.name, func(t *testing.T) { + var suppressCalls atomic.Int32 + var cancelCalls atomic.Int32 + serverErrCh := make(chan error, 1) + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + conn, err := responsesWebsocketUpgrader.Upgrade(w, r, nil) + if err != nil { + serverErrCh <- err + return + } + defer func() { _ = conn.Close() }() + + ctx, _ := gin.CreateTestContext(httptest.NewRecorder()) + ctx.Request = r + + data := make(chan []byte, 2) + errCh := make(chan *interfaces.ErrorMessage) + data <- []byte(createdFrame) + data <- []byte(tc.errorFrame) + close(data) + close(errCh) + + _, _, _, errMsg, errForward := (*OpenAIResponsesAPIHandler)(nil).forwardResponsesWebsocket( + ctx, + newResponsesWebsocketWriter(conn), + func(...interface{}) { cancelCalls.Add(1) }, + data, + errCh, + newInMemoryWebsocketTimelineLog(), + "session-duplex-quota", + responsesWebsocketForwardOptions{ + duplexStream: func() bool { return true }, + suppressError: func(msg *interfaces.ErrorMessage) bool { + suppressCalls.Add(1) + return msg != nil && isResponsesWebsocketQuotaOrCooldownError(msg.Error) + }, + }, + ) + if errForward != nil { + serverErrCh <- fmt.Errorf("expected nil errForward when suppressed, got %v", errForward) + return + } + if errMsg == nil { + serverErrCh <- errors.New("expected non-nil errMsg when suppressed") + return + } + serverErrCh <- nil + })) + defer server.Close() + + wsURL := "ws" + strings.TrimPrefix(server.URL, "http") + conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil) + if err != nil { + t.Fatalf("dial websocket: %v", err) + } + defer func() { _ = conn.Close() }() + _ = conn.SetReadDeadline(time.Now().Add(5 * time.Second)) + + _, frame1, errRead1 := conn.ReadMessage() + if errRead1 != nil { + t.Fatalf("read response.created: %v", errRead1) + } + if got := ojson.GetBytesNoCopy(frame1, "type").String(); got != "response.created" { + t.Fatalf("frame1 type = %q, want response.created: %s", got, frame1) + } + + if _, frame2, errRead2 := conn.ReadMessage(); errRead2 == nil { + t.Fatalf("expected suppressed quota frame not to be forwarded, got: %s", frame2) + } + + if errServer := <-serverErrCh; errServer != nil { + t.Fatalf("server error: %v", errServer) + } + if got := suppressCalls.Load(); got != 1 { + t.Fatalf("suppressError calls = %d, want 1", got) + } + if got := cancelCalls.Load(); got != 1 { + t.Fatalf("cancel calls = %d, want 1", got) + } + }) + } + }) + + t.Run("quota_and_cooldown_emit_terminal_error_when_not_suppressed", func(t *testing.T) { + for _, tc := range []struct { + name string + errorFrame string + wantField string + wantValue string + }{ + { + name: "usage_limit_reached", + errorFrame: `{"type":"error","status":429,"error":{"type":"usage_limit_reached","message":"exhausted"}}`, + wantField: "error.type", + wantValue: "usage_limit_reached", + }, + { + name: "model_cooldown", + errorFrame: `{"type":"error","status":429,"error":{"code":"model_cooldown","message":"cooling down"}}`, + wantField: "error.code", + wantValue: "model_cooldown", + }, + } { + t.Run(tc.name, func(t *testing.T) { + var suppressCalls atomic.Int32 + var cancelCalls atomic.Int32 + serverErrCh := make(chan error, 1) + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + conn, err := responsesWebsocketUpgrader.Upgrade(w, r, nil) + if err != nil { + serverErrCh <- err + return + } + defer func() { _ = conn.Close() }() + + ctx, _ := gin.CreateTestContext(httptest.NewRecorder()) + ctx.Request = r + + data := make(chan []byte, 2) + errCh := make(chan *interfaces.ErrorMessage) + data <- []byte(createdFrame) + data <- []byte(tc.errorFrame) + close(data) + close(errCh) + + _, _, _, errMsg, errForward := (*OpenAIResponsesAPIHandler)(nil).forwardResponsesWebsocket( + ctx, + newResponsesWebsocketWriter(conn), + func(...interface{}) { cancelCalls.Add(1) }, + data, + errCh, + newInMemoryWebsocketTimelineLog(), + "session-duplex-terminal", + responsesWebsocketForwardOptions{ + duplexStream: func() bool { return true }, + suppressError: func(*interfaces.ErrorMessage) bool { + suppressCalls.Add(1) + return false + }, + }, + ) + if !errors.Is(errForward, websocket.ErrCloseSent) { + serverErrCh <- fmt.Errorf("errForward = %v, want websocket.ErrCloseSent", errForward) + return + } + if errMsg == nil || errMsg.StatusCode != http.StatusTooManyRequests { + serverErrCh <- fmt.Errorf("errMsg = %+v, want status 429", errMsg) + return + } + serverErrCh <- nil + })) + defer server.Close() + + wsURL := "ws" + strings.TrimPrefix(server.URL, "http") + conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil) + if err != nil { + t.Fatalf("dial websocket: %v", err) + } + defer func() { _ = conn.Close() }() + _ = conn.SetReadDeadline(time.Now().Add(5 * time.Second)) + + _, frame1, errRead1 := conn.ReadMessage() + if errRead1 != nil { + t.Fatalf("read response.created: %v", errRead1) + } + if got := ojson.GetBytesNoCopy(frame1, "type").String(); got != "response.created" { + t.Fatalf("frame1 type = %q, want response.created: %s", got, frame1) + } + + _, frame2, errRead2 := conn.ReadMessage() + if errRead2 != nil { + t.Fatalf("read terminal error frame: %v", errRead2) + } + if got := ojson.GetBytesNoCopy(frame2, tc.wantField).String(); got != tc.wantValue { + t.Fatalf("frame2 %s = %q, want %q: %s", tc.wantField, got, tc.wantValue, frame2) + } + + if _, extraFrame, errRead3 := conn.ReadMessage(); errRead3 == nil { + t.Fatalf("expected socket close after terminal quota frame, got: %s", extraFrame) + } + + if errServer := <-serverErrCh; errServer != nil { + t.Fatalf("server error: %v", errServer) + } + if got := suppressCalls.Load(); got != 1 { + t.Fatalf("suppressError calls = %d, want 1", got) + } + if got := cancelCalls.Load(); got != 1 { + t.Fatalf("cancel calls = %d, want 1", got) + } + }) + } + }) + + t.Run("request_and_client_rate_limit_errors_stay_on_duplex_path", func(t *testing.T) { + for _, tc := range []struct { + name string + errorFrame string + }{ + { + name: "rate_limit_exceeded", + errorFrame: `{"type":"error","status":429,"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"rate limit exceeded"}}`, + }, + { + name: "invalid_request_error", + errorFrame: `{"type":"error","status":400,"error":{"type":"invalid_request_error","message":"bad request"}}`, + }, + } { + t.Run(tc.name, func(t *testing.T) { + var suppressCalls atomic.Int32 + serverErrCh := make(chan error, 1) + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + conn, err := responsesWebsocketUpgrader.Upgrade(w, r, nil) + if err != nil { + serverErrCh <- err + return + } + defer func() { _ = conn.Close() }() + + ctx, _ := gin.CreateTestContext(httptest.NewRecorder()) + ctx.Request = r + + data := make(chan []byte, 4) + errCh := make(chan *interfaces.ErrorMessage) + data <- []byte(createdFrame) + data <- []byte(tc.errorFrame) + data <- []byte(`{"type":"response.created","response":{"id":"r-recovered"}}`) + data <- []byte(`{"type":"response.completed","response":{"id":"r-recovered","output":[]}}`) + close(data) + close(errCh) + + _, completedID, _, errMsg, errForward := (*OpenAIResponsesAPIHandler)(nil).forwardResponsesWebsocket( + ctx, + newResponsesWebsocketWriter(conn), + func(...interface{}) {}, + data, + errCh, + newInMemoryWebsocketTimelineLog(), + "session-duplex-preserved", + responsesWebsocketForwardOptions{ + duplexStream: func() bool { return true }, + suppressError: func(*interfaces.ErrorMessage) bool { + suppressCalls.Add(1) + return true + }, + }, + ) + if !errors.Is(errForward, websocket.ErrCloseSent) { + serverErrCh <- fmt.Errorf("errForward = %v, want websocket.ErrCloseSent", errForward) + return + } + if errMsg != nil { + serverErrCh <- fmt.Errorf("errMsg = %v, want nil", errMsg) + return + } + if completedID != "r-recovered" { + serverErrCh <- fmt.Errorf("completedID = %q, want r-recovered", completedID) + return + } + serverErrCh <- nil + })) + defer server.Close() + + wsURL := "ws" + strings.TrimPrefix(server.URL, "http") + conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil) + if err != nil { + t.Fatalf("dial websocket: %v", err) + } + defer func() { _ = conn.Close() }() + _ = conn.SetReadDeadline(time.Now().Add(5 * time.Second)) + + wantTypes := []string{"response.created", "error", "response.created", "response.completed"} + for idx, wantType := range wantTypes { + _, frame, errRead := conn.ReadMessage() + if errRead != nil { + t.Fatalf("read frame %d (%s): %v", idx, wantType, errRead) + } + if got := ojson.GetBytesNoCopy(frame, "type").String(); got != wantType { + t.Fatalf("frame %d type = %q, want %q: %s", idx, got, wantType, frame) + } + } + + if errServer := <-serverErrCh; errServer != nil { + t.Fatalf("server error: %v", errServer) + } + if got := suppressCalls.Load(); got != 0 { + t.Fatalf("suppressError calls = %d, want 0", got) + } + }) + } + }) +} diff --git a/sdk/cliproxy/auth/conductor_cooldown.go b/sdk/cliproxy/auth/conductor_cooldown.go index b09c8c809a8..9643b0dfac4 100644 --- a/sdk/cliproxy/auth/conductor_cooldown.go +++ b/sdk/cliproxy/auth/conductor_cooldown.go @@ -175,6 +175,7 @@ func (m *Manager) setConfigSnapshotLocked(cfg *internalconfig.Config) bool { m.homeSessionAliases.clear() } m.runtimeConfig.Store(cfg) + applyPlanRoutingConfig(cfg) clearedCooldowns := m.clearDisabledCooldownStates(cfg) if clearedCooldowns && oldCooldownStore != nil { m.mu.Lock() @@ -1080,6 +1081,11 @@ func (m *Manager) ResetQuota(ctx context.Context, authID string) (*Auth, []strin m.mu.Unlock() return nil, nil, nil } + // A manual reset also drops recorded "spent" readings, so routing does not + // keep avoiding the account until the next poll. + ForgetQuotaWindows(authID) + ForgetScopedWeeklyWindows(authID) + ForgetShortWindowUsage(authID) var cooldownRecordsBefore []CooldownStateRecord trackCooldownState := m.cooldownStore != nil diff --git a/sdk/cliproxy/auth/conductor_execution.go b/sdk/cliproxy/auth/conductor_execution.go index 379b9e2eb96..b2bfd3a3033 100644 --- a/sdk/cliproxy/auth/conductor_execution.go +++ b/sdk/cliproxy/auth/conductor_execution.go @@ -1110,12 +1110,16 @@ func (m *Manager) executeStreamMixedOnce(ctx context.Context, providers []string homeMode := m.HomeEnabled() homeAuthCount := 1 tried := make(map[string]struct{}) + homeExcludedAuthIDs := make(map[string]struct{}) + for _, authID := range homeExcludedAuthIDsFromMetadata(opts.Metadata) { + tried[authID] = struct{}{} + homeExcludedAuthIDs[authID] = struct{}{} + } if !homeMode { for authID := range m.requestRetryRoundExclusions(retryRound, defaultRequestRetry) { tried[authID] = struct{}{} } } - homeExcludedAuthIDs := make(map[string]struct{}) homeSameAuthRetries := make(map[string]int) lastHomeAuthID := "" homeSameAuthRetryPending := false diff --git a/sdk/cliproxy/auth/conductor_home.go b/sdk/cliproxy/auth/conductor_home.go index 23ee990acf2..214bb9a14d4 100644 --- a/sdk/cliproxy/auth/conductor_home.go +++ b/sdk/cliproxy/auth/conductor_home.go @@ -25,7 +25,7 @@ const ( homeRetryRoundMetadataKey = "request_retry_round" // ExcludedAuthIDsMetadataKey stores credential IDs already attempted in the // current request retry round. - ExcludedAuthIDsMetadataKey = "excluded_auth_ids" + ExcludedAuthIDsMetadataKey = cliproxyexecutor.ExcludedAuthIDsMetadataKey // CloseAllExecutionSessionsID asks an executor to release all active execution sessions. // Executors that do not support this marker may ignore it. CloseAllExecutionSessionsID = "__all_execution_sessions__" diff --git a/sdk/cliproxy/auth/conductor_selection.go b/sdk/cliproxy/auth/conductor_selection.go index 8849b36514f..1fca3160023 100644 --- a/sdk/cliproxy/auth/conductor_selection.go +++ b/sdk/cliproxy/auth/conductor_selection.go @@ -1019,6 +1019,25 @@ func (m *Manager) transientlyUnavailableSessionAffinityAuthIDs(ctx context.Conte return authIDs } +// coolingCandidates lists the accounts in pool (every account that could serve +// the request, including ones this request already tried) that are kept out of +// this pick only for a while (a quota cooldown or the hold after a transient upstream error +// such as "overloaded"), with the time each one is back. Callers hold m.mu. +func (m *Manager) coolingCandidates(ctx context.Context, pool []*Auth, routeModel string, now time.Time, clientHeaders ...http.Header) []coolingCandidate { + var cooling []coolingCandidate + for _, candidate := range pool { + if candidate == nil { + continue + } + checkModel := m.selectionModelForAuth(candidate, routeModel) + blocked, reason, next := isAuthBlockedForModelForRequest(ctx, candidate, checkModel, now, clientHeaders...) + if blocked && reason != blockReasonDisabled && next.After(now) { + cooling = append(cooling, coolingCandidate{auth: candidate, until: next}) + } + } + return cooling +} + func restoreModelCooldownErrorModel(err error, requestedModel string) error { if err == nil || requestedModel == "" { return err @@ -2329,7 +2348,7 @@ func (m *Manager) pickNextLegacy(ctx context.Context, provider, model string, op _, weighted = affinitySelector.fallback.(*WeightedRoundRobinSelector) } trackPinnedAccounting := pinnedAuthID != "" && weighted - var accountingCandidates, affinityCandidates []*Auth + var accountingCandidates, affinityCandidates, heldPool []*Auth if trackTransientAffinity { affinityCandidates = make([]*Auth, 0, len(m.auths)) } @@ -2357,6 +2376,10 @@ func (m *Manager) pickNextLegacy(ctx context.Context, provider, model string, op if trackTransientAffinity { affinityCandidates = append(affinityCandidates, candidate) } + // Accounts this request already tried stay out of the pick, but one that is + // now on hold with allowance left is still a reason not to fall back to a + // spent account. + heldPool = append(heldPool, candidate) if used { continue } @@ -2391,6 +2414,7 @@ func (m *Manager) pickNextLegacy(ctx context.Context, provider, model string, op accountingAuths = fullAvailable } transientAuthIDs := m.transientlyUnavailableSessionAffinityAuthIDs(ctx, selector, affinityCandidates, model, now, opts.Headers) + cooling := m.coolingCandidates(ctx, heldPool, model, now, opts.Headers) m.mu.RUnlock() selected, handled, excluded, errPick := m.pickViaPluginScheduler(ctx, pluginScheduler, provider, []string{provider}, model, opts, tried, available) @@ -2426,10 +2450,12 @@ func (m *Manager) pickNextLegacy(ctx context.Context, provider, model string, op accountingAuths = nil } transientAuthIDs = m.transientlyUnavailableSessionAffinityAuthIDs(ctx, selector, affinityCandidates, model, now, opts.Headers) + cooling = m.coolingCandidates(ctx, heldPool, model, now, opts.Headers) m.mu.RUnlock() } selectorCtx := selectorContextForAvailableAuths(ctx, selector, model) selectorCtx = withSessionAffinityTransientAuthIDs(selectorCtx, transientAuthIDs) + selectorCtx = withCoolingCandidates(selectorCtx, cooling) if accountingAuths != nil { selectorCtx = context.WithValue(selectorCtx, weightedAccountingPoolKey{}, accountingAuths) } @@ -2817,7 +2843,7 @@ func (m *Manager) pickNextMixedLegacy(ctx context.Context, providers []string, m _, weighted = affinitySelector.fallback.(*WeightedRoundRobinSelector) } trackPinnedAccounting := pinnedAuthID != "" && weighted - var accountingCandidates, affinityCandidates []*Auth + var accountingCandidates, affinityCandidates, heldPool []*Auth if trackTransientAffinity { affinityCandidates = make([]*Auth, 0, len(m.auths)) } @@ -2855,6 +2881,10 @@ func (m *Manager) pickNextMixedLegacy(ctx context.Context, providers []string, m if trackTransientAffinity { affinityCandidates = append(affinityCandidates, candidate) } + // Accounts this request already tried stay out of the pick, but one that is + // now on hold with allowance left is still a reason not to fall back to a + // spent account. + heldPool = append(heldPool, candidate) if used { continue } @@ -2889,6 +2919,7 @@ func (m *Manager) pickNextMixedLegacy(ctx context.Context, providers []string, m accountingAuths = fullAvailable } transientAuthIDs := m.transientlyUnavailableSessionAffinityAuthIDs(ctx, selector, affinityCandidates, model, now, opts.Headers) + cooling := m.coolingCandidates(ctx, heldPool, model, now, opts.Headers) m.mu.RUnlock() selected, handled, excluded, errPick := m.pickViaPluginScheduler(ctx, pluginScheduler, "mixed", providers, model, opts, tried, available) @@ -2924,10 +2955,12 @@ func (m *Manager) pickNextMixedLegacy(ctx context.Context, providers []string, m accountingAuths = nil } transientAuthIDs = m.transientlyUnavailableSessionAffinityAuthIDs(ctx, selector, affinityCandidates, model, now, opts.Headers) + cooling = m.coolingCandidates(ctx, heldPool, model, now, opts.Headers) m.mu.RUnlock() } selectorCtx := selectorContextForAvailableAuths(ctx, selector, model) selectorCtx = withSessionAffinityTransientAuthIDs(selectorCtx, transientAuthIDs) + selectorCtx = withCoolingCandidates(selectorCtx, cooling) if accountingAuths != nil { selectorCtx = context.WithValue(selectorCtx, weightedAccountingPoolKey{}, accountingAuths) } diff --git a/sdk/cliproxy/auth/home_retry_loop_test.go b/sdk/cliproxy/auth/home_retry_loop_test.go index e0ca0052f8e..24040cad2c5 100644 --- a/sdk/cliproxy/auth/home_retry_loop_test.go +++ b/sdk/cliproxy/auth/home_retry_loop_test.go @@ -98,3 +98,39 @@ func TestManagerExecuteHomeStopsWhenDispatchRepeatsTriedAuth(t *testing.T) { t.Fatalf("home dispatch calls = %d, want 2", got) } } + +func TestManagerExecuteStreamHomeRejectsMetadataExcludedAuthWhenRepeated(t *testing.T) { + dispatcher := &repeatedHomeAuthDispatcher{} + oldCurrentHomeDispatcher := currentHomeDispatcher + currentHomeDispatcher = func() homeAuthDispatcher { + return dispatcher + } + t.Cleanup(func() { + currentHomeDispatcher = oldCurrentHomeDispatcher + }) + + executor := &unauthorizedHomeExecutor{} + manager := NewManager(nil, nil, nil) + manager.SetConfig(&internalconfig.Config{Home: internalconfig.HomeConfig{Enabled: true}}) + manager.SetHomeExecutionRegistry(executionregistry.New()) + manager.RegisterExecutor(executor) + + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + + opts := cliproxyexecutor.Options{ + Metadata: map[string]any{ + ExcludedAuthIDsMetadataKey: []string{"home-auth-1"}, + }, + } + _, err := manager.ExecuteStream(ctx, []string{"home-loop-test"}, cliproxyexecutor.Request{Model: "gemini-3.5-flash-low"}, opts) + if err == nil { + t.Fatal("ExecuteStream error = nil, want repeated auth rejection") + } + if got := executor.calls.Load(); got != 0 { + t.Fatalf("executor calls = %d, want 0 when dispatch returns metadata-excluded auth", got) + } + if got := dispatcher.calls.Load(); got != 1 { + t.Fatalf("home dispatch calls = %d, want 1", got) + } +} diff --git a/sdk/cliproxy/auth/plan_headroom.go b/sdk/cliproxy/auth/plan_headroom.go new file mode 100644 index 00000000000..d0e4cc89431 --- /dev/null +++ b/sdk/cliproxy/auth/plan_headroom.go @@ -0,0 +1,186 @@ +package auth + +import ( + "math" + "strconv" + "strings" + "sync" + "time" +) + +// Plan-weighted short-window headroom. +// +// Claude and Codex accounts carry a 5-hour window next to the weekly one. A new +// conversation started on an account whose 5-hour window is nearly spent hits +// that limit within a few turns. Absolute headroom is the account's plan weight +// times its remaining percent, so 10% left on a Pro account is 10 while 10% left +// on a Max 20x account is 200: a small plan is considered tight far earlier. +// Only readings the hub already has are used: passive response headers and the +// usage-endpoint readings published through ObserveShortWindowUsage. + +// shortWindowLength is the length of the Claude and Codex short window. +const shortWindowLength = 5 * time.Hour + +// shortWindowReading is one observation of an account's 5-hour window. +type shortWindowReading struct { + usedPercent float64 + resetAt time.Time + observedAt time.Time +} + +var shortWindowReadings = struct { + sync.RWMutex + byAuth map[string]shortWindowReading +}{byAuth: make(map[string]shortWindowReading)} + +// ObserveShortWindowUsage records a usage-endpoint reading of an account's +// 5-hour window: usedPercent is 0-100 and resetAt may be zero when unknown. An +// older reading never replaces a newer one. +func ObserveShortWindowUsage(authID string, observedAt time.Time, usedPercent float64, resetAt time.Time) { + authID = strings.TrimSpace(authID) + if authID == "" || observedAt.IsZero() || math.IsNaN(usedPercent) || math.IsInf(usedPercent, 0) { + return + } + shortWindowReadings.Lock() + defer shortWindowReadings.Unlock() + if previous, ok := shortWindowReadings.byAuth[authID]; ok && previous.observedAt.After(observedAt) { + return + } + shortWindowReadings.byAuth[authID] = shortWindowReading{usedPercent: usedPercent, resetAt: resetAt, observedAt: observedAt} +} + +// ForgetShortWindowUsage drops the recorded usage reading of an account. +func ForgetShortWindowUsage(authID string) { + shortWindowReadings.Lock() + delete(shortWindowReadings.byAuth, strings.TrimSpace(authID)) + shortWindowReadings.Unlock() +} + +// shortWindowFor returns the newest still-current reading of the account's +// 5-hour window. A reading whose reset has passed, or that is older than one +// window when its reset is unknown, is not current: the window has refilled. +func shortWindowFor(auth *Auth, now time.Time) (shortWindowReading, bool) { + if auth == nil { + return shortWindowReading{}, false + } + var best shortWindowReading + found := false + consider := func(reading shortWindowReading, ok bool) { + if !ok || reading.observedAt.IsZero() || reading.observedAt.After(now) { + return + } + if reading.resetAt.IsZero() { + if now.Sub(reading.observedAt) > shortWindowLength { + return + } + } else if !reading.resetAt.After(now) { + return + } + if !found || reading.observedAt.After(best.observedAt) { + best, found = reading, true + } + } + consider(shortWindowFromSignals(auth.Provider, auth.Quota)) + for _, state := range auth.ModelStates { + if state != nil { + consider(shortWindowFromSignals(auth.Provider, state.Quota)) + } + } + shortWindowReadings.RLock() + reading, ok := shortWindowReadings.byAuth[auth.ID] + shortWindowReadings.RUnlock() + consider(reading, ok) + return best, found +} + +// shortWindowFromSignals reads the 5-hour window from passive response headers. +func shortWindowFromSignals(provider string, quota QuotaState) (shortWindowReading, bool) { + if quota.ObservedAt.IsZero() || len(quota.Signals) == 0 { + return shortWindowReading{}, false + } + signal := func(name string) string { return strings.TrimSpace(quota.Signals[name]) } + switch strings.ToLower(strings.TrimSpace(provider)) { + case "claude": + const prefix = "Anthropic-Ratelimit-Unified-5h-" + reading := shortWindowReading{observedAt: quota.ObservedAt, usedPercent: -1} + // Utilization is a fraction (0-1) in the unified headers. + if utilization, errParse := strconv.ParseFloat(signal(prefix+"Utilization"), 64); errParse == nil && !math.IsNaN(utilization) && !math.IsInf(utilization, 0) { + reading.usedPercent = utilization * 100 + } + if strings.EqualFold(signal(prefix+"Status"), "rejected") { + reading.usedPercent = 100 + } + if reading.usedPercent < 0 { + return shortWindowReading{}, false + } + reading.resetAt = parseResetInstant(signal(prefix + "Reset")) + return reading, true + case "codex": + for _, window := range []string{"Primary", "Secondary"} { + prefix := "X-Codex-" + window + "-" + minutes, errMinutes := strconv.ParseFloat(signal(prefix+"Window-Minutes"), 64) + if errMinutes != nil || minutes != shortWindowLength.Minutes() { + continue + } + used, errUsed := strconv.ParseFloat(signal(prefix+"Used-Percent"), 64) + if errUsed != nil || math.IsNaN(used) || math.IsInf(used, 0) { + continue + } + reading := shortWindowReading{observedAt: quota.ObservedAt, usedPercent: used} + if reading.resetAt = parseResetInstant(signal(prefix + "Reset-At")); !reading.resetAt.IsZero() { + return reading, true + } + if after, errAfter := strconv.ParseFloat(signal(prefix+"Reset-After-Seconds"), 64); errAfter == nil && after > 0 && after <= shortWindowLength.Seconds() { + reading.resetAt = quota.ObservedAt.Add(time.Duration(after * float64(time.Second))) + } + return reading, true + } + } + return shortWindowReading{}, false +} + +// parseResetInstant parses an RFC 3339 or unix-seconds reset time. Unlike +// futureResetTime it keeps resets that have passed, so a stale reading is +// recognized as refilled instead of being treated as having no reset. +func parseResetInstant(raw string) time.Time { + if reset, errParse := time.Parse(time.RFC3339, raw); errParse == nil { + return reset + } + if seconds, errParse := strconv.ParseInt(raw, 10, 64); errParse == nil && seconds > 0 { + return time.Unix(seconds, 0) + } + return time.Time{} +} + +// shortWindowHeadroom returns the account's plan-weighted 5-hour headroom +// (plan weight x remaining percent) and whether a current reading exists. +func shortWindowHeadroom(auth *Auth, now time.Time) (float64, bool) { + reading, ok := shortWindowFor(auth, now) + if !ok { + return 0, false + } + remaining := math.Max(0, math.Min(100, 100-reading.usedPercent)) + return PlanWeightOf(auth) * remaining, true +} + +// withShortWindowHeadroom drops accounts whose plan-weighted 5-hour headroom is +// below reserve, as long as at least one account keeps enough headroom (or has +// no current reading). It returns auths unchanged when reserve is not positive +// or every account is tight. It is applied to new conversations only: the +// session-affinity wrapper does not consult the inner selector for a bound +// conversation whose account is still available. +func withShortWindowHeadroom(auths []*Auth, reserve float64, now time.Time) []*Auth { + if reserve <= 0 || len(auths) < 2 { + return auths + } + roomy := make([]*Auth, 0, len(auths)) + for _, auth := range auths { + if headroom, ok := shortWindowHeadroom(auth, now); !ok || headroom >= reserve { + roomy = append(roomy, auth) + } + } + if len(roomy) == 0 { + return auths + } + return roomy +} diff --git a/sdk/cliproxy/auth/plan_weight.go b/sdk/cliproxy/auth/plan_weight.go new file mode 100644 index 00000000000..456b03d9d5b --- /dev/null +++ b/sdk/cliproxy/auth/plan_weight.go @@ -0,0 +1,288 @@ +package auth + +import ( + "math" + "regexp" + "strconv" + "strings" + "sync" + "sync/atomic" + + internalconfig "github.com/rune-oai/t3code-proxy/internal/config" +) + +// Plan capacity. +// +// Accounts in one provider pool are not equal: a Claude Max 20x account has +// roughly twenty times the allowance of a Pro account. PlanWeight expresses an +// account's capacity relative to its provider's base paid plan (1.0) so routing +// can spread new conversations and judge headroom in proportion to capacity. + +// defaultPlanWeights is the single table of built-in plan weights, keyed by +// provider and normalized plan name (see internalconfig.NormalizePlanKey). +// routing.plan-weights overrides any entry. +// +// Claude: Pro is the base plan; Max 5x and Max 20x are named after their +// multiple of Pro usage. "max" is a Max account whose tier is unknown and is +// counted as the smaller Max plan. Team seats are counted as Pro. +// +// Codex: the ratios are APPROXIMATE. OpenAI describes its tiers as multiples of +// Plus usage and changes them over time. Plus is the base plan; the $100 Pro +// tier (reported as "prolite") is 5x Plus and the $200 Pro tier ("pro") 20x. +// The $500 tier ("promax") is set to 2.5x Pro. Team/Business, Enterprise and Edu +// seats are counted as Plus. Override with routing.plan-weights.codex when the +// real ratio is known. +// +// xAI: SuperGrok is the base plan. SuperGrok Heavy carries ten times the +// monthly credit of SuperGrok. +var defaultPlanWeights = map[string]map[string]float64{ + "claude": { + "pro": 1, + "team": 1, + "max": 5, + "max_5x": 5, + "max_20x": 20, + }, + "codex": { + "plus": 1, + "team": 1, + "business": 1, + "enterprise": 1, + "edu": 1, + "prolite": 5, + "pro": 20, + "promax": 50, + }, + "xai": { + "supergrok": 1, + "supergrok_heavy": 10, + }, +} + +// planMultiplierPattern matches a plan or tier name that carries its own +// multiple of the base plan, such as "max_20x" or "default_claude_max_20x". +var planMultiplierPattern = regexp.MustCompile(`(?:^|_)(max_)?([0-9]+(?:\.[0-9]+)?)x$`) + +// planRoutingSettings is the hot-reloaded routing.plan-weights and +// routing.plan-headroom-reserve state. +type planRoutingSettings struct { + weights map[string]map[string]float64 + reserve float64 +} + +var planRouting atomic.Pointer[planRoutingSettings] + +// applyPlanRoutingConfig publishes the plan routing settings of cfg. It runs on +// every manager config update, so the settings follow config hot reloads. +func applyPlanRoutingConfig(cfg *internalconfig.Config) { + settings := &planRoutingSettings{reserve: internalconfig.DefaultPlanHeadroomReserve} + if cfg != nil { + settings.weights = NormalizePlanWeights(cfg.Routing.PlanWeights) + settings.reserve = cfg.Routing.EffectivePlanHeadroomReserve() + } + planRouting.Store(settings) +} + +func currentPlanRouting() *planRoutingSettings { + if settings := planRouting.Load(); settings != nil { + return settings + } + return &planRoutingSettings{reserve: internalconfig.DefaultPlanHeadroomReserve} +} + +// planHeadroomReserve returns the active routing.plan-headroom-reserve. +func planHeadroomReserve() float64 { + return currentPlanRouting().reserve +} + +// NormalizePlanWeights returns a copy of a routing.plan-weights table with +// normalized provider and plan keys. Invalid weights are dropped; config +// validation rejects them before they reach the runtime. +func NormalizePlanWeights(weights map[string]map[string]float64) map[string]map[string]float64 { + out := make(map[string]map[string]float64, len(weights)) + for provider, plans := range weights { + provider = internalconfig.NormalizePlanKey(provider) + if provider == "" { + continue + } + for plan, weight := range plans { + plan = internalconfig.NormalizePlanKey(plan) + if plan == "" || !validPlanWeight(weight) { + continue + } + if out[provider] == nil { + out[provider] = make(map[string]float64) + } + out[provider][plan] = weight + } + } + return out +} + +func validPlanWeight(weight float64) bool { + return !math.IsNaN(weight) && !math.IsInf(weight, 0) && weight > 0 && weight <= internalconfig.MaxPlanWeight +} + +// DefaultPlanWeights returns a copy of the built-in plan weight table. +func DefaultPlanWeights() map[string]map[string]float64 { + return NormalizePlanWeights(defaultPlanWeights) +} + +// EffectivePlanWeights returns the built-in table with configured overrides +// applied on top. Plans whose weight is derived from an "x" suffix are not +// listed; PlanWeight resolves them on demand. +func EffectivePlanWeights(configured map[string]map[string]float64) map[string]map[string]float64 { + out := DefaultPlanWeights() + for provider, plans := range NormalizePlanWeights(configured) { + if out[provider] == nil { + out[provider] = make(map[string]float64, len(plans)) + } + for plan, weight := range plans { + out[provider][plan] = weight + } + } + return out +} + +// PlanWeight returns the capacity of plan relative to provider's base paid plan +// (1.0), using routing.plan-weights overrides first, then the built-in table, +// then an "x" multiplier in the plan name for providers with a built-in +// table. An unknown plan or provider weighs 1. +func PlanWeight(provider, plan string) float64 { + provider = internalconfig.NormalizePlanKey(provider) + plan = normalizePlan(plan) + if provider == "" || plan == "" { + return 1 + } + if weight, ok := currentPlanRouting().weights[provider][plan]; ok { + return weight + } + builtIn, known := defaultPlanWeights[provider] + if !known { + return 1 + } + if weight, ok := builtIn[plan]; ok { + return weight + } + if multiplier := planMultiplier(plan); multiplier > 0 { + return multiplier + } + return 1 +} + +// PlanWeightOf returns PlanWeight for the account's provider and plan. +func PlanWeightOf(auth *Auth) float64 { + if auth == nil { + return 1 + } + return PlanWeight(auth.Provider, PlanOf(auth)) +} + +func planMultiplier(plan string) float64 { + match := planMultiplierPattern.FindStringSubmatch(plan) + if match == nil { + return 0 + } + multiplier, errParse := strconv.ParseFloat(match[2], 64) + if errParse != nil || !validPlanWeight(multiplier) { + return 0 + } + return multiplier +} + +// normalizePlan returns the canonical plan name for a plan, subscription type +// or rate-limit tier value. Tier names that carry a Max multiplier collapse to +// "max_x" ("default_claude_max_20x" becomes "max_20x"). +func normalizePlan(raw string) string { + plan := internalconfig.NormalizePlanKey(raw) + if match := planMultiplierPattern.FindStringSubmatch(plan); match != nil && match[1] != "" { + return "max_" + match[2] + "x" + } + return plan +} + +// observedPlans holds plans learned at runtime (for example from the Claude +// OAuth profile the quota-history recorder fetches), keyed by auth ID. +var observedPlans sync.Map + +// ObserveAuthPlan records the plan of an account learned from an upstream +// reading. An empty plan clears the recorded value. It takes precedence over +// plan fields stored with the credential, which can be stale. +func ObserveAuthPlan(authID, plan string) { + authID = strings.TrimSpace(authID) + if authID == "" { + return + } + if plan = normalizePlan(plan); plan == "" { + observedPlans.Delete(authID) + return + } + observedPlans.Store(authID, plan) +} + +// planFieldKeys are the credential attribute and metadata keys that carry a +// plan, in order of preference. A rate-limit tier counts only when it names a +// Max multiplier, because tiers such as "default_claude_ai" say nothing about +// the plan. +var planFieldKeys = []struct { + key string + tier bool +}{ + {key: "plan_type"}, + {key: "plan"}, + {key: "rate_limit_tier", tier: true}, + {key: "rateLimitTier", tier: true}, + {key: "subscription_type"}, + {key: "subscriptionType"}, +} + +// PlanOf returns the account's normalized lower-case plan, such as "pro", +// "max_5x", "max_20x" (Claude) or "plus", "pro", "team" (Codex), or "" when +// unknown. Sources, newest first: a plan observed at runtime (ObserveAuthPlan), +// the X-Codex-Plan-Type response header, then the credential's attributes and +// metadata (Codex plan_type from the ID token, Claude subscription type or +// rate-limit tier). +func PlanOf(auth *Auth) string { + if auth == nil { + return "" + } + if value, ok := observedPlans.Load(auth.ID); ok { + if plan, _ := value.(string); plan != "" { + return plan + } + } + if plan := codexPlanSignal(auth); plan != "" { + return plan + } + for _, field := range planFieldKeys { + raw := strings.TrimSpace(auth.Attributes[field.key]) + if raw == "" { + raw, _ = auth.Metadata[field.key].(string) + } + plan := normalizePlan(raw) + if plan == "" || (field.tier && !strings.HasPrefix(plan, "max_")) { + continue + } + return plan + } + return "" +} + +// codexPlanSignal returns the plan from the newest passive X-Codex-Plan-Type +// response header recorded for a Codex account. +func codexPlanSignal(auth *Auth) string { + if !strings.EqualFold(strings.TrimSpace(auth.Provider), "codex") { + return "" + } + const header = "X-Codex-Plan-Type" + best := auth.Quota + for _, state := range auth.ModelStates { + if state == nil || state.Quota.Signals[header] == "" { + continue + } + if best.Signals[header] == "" || state.Quota.ObservedAt.After(best.ObservedAt) { + best = state.Quota + } + } + return normalizePlan(best.Signals[header]) +} diff --git a/sdk/cliproxy/auth/plan_weight_test.go b/sdk/cliproxy/auth/plan_weight_test.go new file mode 100644 index 00000000000..4125e344914 --- /dev/null +++ b/sdk/cliproxy/auth/plan_weight_test.go @@ -0,0 +1,167 @@ +package auth + +import ( + "testing" + "time" + + internalconfig "github.com/rune-oai/t3code-proxy/internal/config" +) + +// setPlanRouting applies plan routing settings for one test and restores the +// defaults afterwards. +func setPlanRouting(t *testing.T, weights map[string]map[string]float64, reserve *float64) { + t.Helper() + applyPlanRoutingConfig(&internalconfig.Config{Routing: internalconfig.RoutingConfig{PlanWeights: weights, PlanHeadroomReserve: reserve}}) + t.Cleanup(func() { applyPlanRoutingConfig(nil) }) +} + +func TestPlanOf(t *testing.T) { + now := time.Unix(1_800_000_000, 0) + tests := []struct { + name string + auth *Auth + want string + }{ + {name: "nil", auth: nil, want: ""}, + {name: "unknown", auth: &Auth{ID: "p-unknown", Provider: "claude"}, want: ""}, + {name: "codex id token plan", auth: &Auth{ID: "p-codex", Provider: "codex", Attributes: map[string]string{"plan_type": " Plus "}}, want: "plus"}, + { + name: "codex response header beats stored plan", + auth: &Auth{ + ID: "p-codex-header", Provider: "codex", + Attributes: map[string]string{"plan_type": "plus"}, + Quota: QuotaState{ObservedAt: now, Signals: map[string]string{"X-Codex-Plan-Type": "pro"}}, + }, + want: "pro", + }, + { + name: "codex header on a model state", + auth: &Auth{ + ID: "p-codex-model-header", Provider: "codex", + Quota: QuotaState{ObservedAt: now, Signals: map[string]string{"X-Codex-Primary-Used-Percent": "3"}}, + ModelStates: map[string]*ModelState{"gpt-5": {Quota: QuotaState{ObservedAt: now.Add(-time.Minute), Signals: map[string]string{"X-Codex-Plan-Type": "team"}}}}, + }, + want: "team", + }, + {name: "claude rate-limit tier", auth: &Auth{ID: "p-tier", Provider: "claude", Metadata: map[string]any{"rateLimitTier": "default_claude_max_20x", "subscriptionType": "max"}}, want: "max_20x"}, + {name: "claude tier without multiplier falls through", auth: &Auth{ID: "p-tier-ai", Provider: "claude", Metadata: map[string]any{"rate_limit_tier": "default_claude_ai", "subscription_type": "pro"}}, want: "pro"}, + {name: "claude subscription type", auth: &Auth{ID: "p-sub", Provider: "claude", Metadata: map[string]any{"subscriptionType": "Max"}}, want: "max"}, + {name: "plan spelled with spaces", auth: &Auth{ID: "p-spaces", Provider: "claude", Attributes: map[string]string{"plan": "Max 5x"}}, want: "max_5x"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := PlanOf(tt.auth); got != tt.want { + t.Fatalf("PlanOf() = %q, want %q", got, tt.want) + } + }) + } + + t.Run("observed plan wins", func(t *testing.T) { + auth := &Auth{ID: "p-observed", Provider: "claude", Metadata: map[string]any{"subscriptionType": "pro"}} + t.Cleanup(func() { ObserveAuthPlan(auth.ID, "") }) + ObserveAuthPlan(auth.ID, "max_20x") + if got := PlanOf(auth); got != "max_20x" { + t.Fatalf("PlanOf() = %q, want max_20x", got) + } + ObserveAuthPlan(auth.ID, "") + if got := PlanOf(auth); got != "pro" { + t.Fatalf("PlanOf() after clear = %q, want pro", got) + } + }) +} + +func TestPlanWeightDefaults(t *testing.T) { + setPlanRouting(t, nil, nil) + tests := []struct { + provider, plan string + want float64 + }{ + {"claude", "pro", 1}, + {"claude", "max_5x", 5}, + {"Claude", "Max 20x", 20}, + {"claude", "default_claude_max_20x", 20}, + {"claude", "max", 5}, + {"claude", "max_40x", 40}, // derived from the tier name, no code change needed + {"claude", "enterprise", 1}, + {"claude", "", 1}, + {"codex", "plus", 1}, + {"codex", "prolite", 5}, + {"codex", "pro", 20}, + {"codex", "promax", 50}, + {"codex", "team", 1}, + {"xai", "SuperGrok", 1}, + {"xai", "SuperGrok Heavy", 10}, + {"grok", "max_20x", 1}, // unknown provider + {"", "pro", 1}, + } + for _, tt := range tests { + if got := PlanWeight(tt.provider, tt.plan); got != tt.want { + t.Fatalf("PlanWeight(%q, %q) = %v, want %v", tt.provider, tt.plan, got, tt.want) + } + } + auth := &Auth{ID: "w-auth", Provider: "codex", Attributes: map[string]string{"plan_type": "pro"}} + if got := PlanWeightOf(auth); got != 20 { + t.Fatalf("PlanWeightOf() = %v, want 20", got) + } + if got := PlanWeightOf(nil); got != 1 { + t.Fatalf("PlanWeightOf(nil) = %v, want 1", got) + } +} + +func TestPlanWeightOverrides(t *testing.T) { + setPlanRouting(t, map[string]map[string]float64{ + "Codex": {"Pro": 10, "free": 0.25}, + "claude": {"max-20x": 15}, + "kimi": {"premium": 3}, + }, nil) + for _, tt := range []struct { + provider, plan string + want float64 + }{ + {"codex", "pro", 10}, + {"codex", "free", 0.25}, + {"codex", "plus", 1}, + {"claude", "max_20x", 15}, + {"claude", "default_claude_max_20x", 15}, + {"claude", "max_5x", 5}, + {"kimi", "premium", 3}, + } { + if got := PlanWeight(tt.provider, tt.plan); got != tt.want { + t.Fatalf("PlanWeight(%q, %q) = %v, want %v", tt.provider, tt.plan, got, tt.want) + } + } + + effective := EffectivePlanWeights(map[string]map[string]float64{"Codex": {"Pro": 10}, "kimi": {"premium": 3}}) + if effective["codex"]["pro"] != 10 || effective["codex"]["plus"] != 1 || effective["claude"]["max_20x"] != 20 || effective["kimi"]["premium"] != 3 { + t.Fatalf("EffectivePlanWeights() = %v", effective) + } + if defaults := DefaultPlanWeights(); defaults["codex"]["pro"] != 20 { + t.Fatalf("DefaultPlanWeights() changed by an override: %v", defaults) + } + + // A config update without overrides restores the built-in values. + applyPlanRoutingConfig(&internalconfig.Config{}) + if got := PlanWeight("codex", "pro"); got != 20 { + t.Fatalf("PlanWeight after reload = %v, want 20", got) + } +} + +func TestPlanRoutingFollowsManagerConfig(t *testing.T) { + t.Cleanup(func() { applyPlanRoutingConfig(nil) }) + reserve := 0.0 + manager := NewManager(nil, nil, nil) + manager.SetConfig(&internalconfig.Config{Routing: internalconfig.RoutingConfig{ + PlanWeights: map[string]map[string]float64{"codex": {"pro": 8}}, + PlanHeadroomReserve: &reserve, + }}) + if got := PlanWeight("codex", "pro"); got != 8 { + t.Fatalf("PlanWeight after SetConfig = %v, want 8", got) + } + if got := planHeadroomReserve(); got != 0 { + t.Fatalf("planHeadroomReserve after SetConfig = %v, want 0", got) + } + manager.SetConfig(&internalconfig.Config{}) + if got := planHeadroomReserve(); got != internalconfig.DefaultPlanHeadroomReserve { + t.Fatalf("planHeadroomReserve default = %v, want %v", got, internalconfig.DefaultPlanHeadroomReserve) + } +} diff --git a/sdk/cliproxy/auth/quota_windows_council_test.go b/sdk/cliproxy/auth/quota_windows_council_test.go new file mode 100644 index 00000000000..cbe3a706a30 --- /dev/null +++ b/sdk/cliproxy/auth/quota_windows_council_test.go @@ -0,0 +1,177 @@ +package auth + +import ( + "fmt" + "testing" + "time" +) + +func forgetReadings(t *testing.T, ids ...string) { + t.Helper() + t.Cleanup(func() { + for _, id := range ids { + ForgetQuotaWindows(id) + ForgetScopedWeeklyWindows(id) + ForgetShortWindowUsage(id) + } + }) +} + +// A spent shorter window makes the account unusable even when the longest +// window that governs the model still has allowance. +func TestSpentShorterWindowExcludesAccount(t *testing.T) { + setPlanRouting(t, nil, nil) + now := time.Unix(1_800_000_000, 0) + forgetReadings(t, "xai-spent", "xai-open") + week, month := 7*24*time.Hour, 30*24*time.Hour + ObserveQuotaWindows("xai-spent", now.Add(-time.Minute), []QuotaWindow{ + {Key: "weekly", UsedPercent: 100, ResetAt: now.Add(3 * 24 * time.Hour), Period: week}, + {Key: "monthly", UsedPercent: 20, ResetAt: now.Add(5 * 24 * time.Hour), Period: month}, + }) + ObserveQuotaWindows("xai-open", now.Add(-time.Minute), []QuotaWindow{ + {Key: "weekly", UsedPercent: 10, ResetAt: now.Add(4 * 24 * time.Hour), Period: week}, + {Key: "monthly", UsedPercent: 20, ResetAt: now.Add(20 * 24 * time.Hour), Period: month}, + }) + spent := &Auth{ID: "xai-spent", Provider: "xai"} + open := &Auth{ID: "xai-open", Provider: "xai"} + state, ok := governingQuotaWindowFor(spent, "grok-4", now) + if !ok || !state.exhausted || !state.reset.Equal(now.Add(3*24*time.Hour)) { + t.Fatalf("spent state = %+v, %v; want exhausted until the weekly reset", state, ok) + } + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + // The spent account's monthly reset is sooner, so it would otherwise win. + if got := countPicks(t, selector, "xai", "grok-4", []*Auth{spent, open}, 10); got["xai-open"] != 10 { + t.Fatalf("picks = %v, want all on xai-open", got) + } +} + +// Newer response headers that show allowance overrule an older spent poll, as +// after an early reset; ranking then uses the header's weekly reset. +func TestNewerPassiveHeadersOverruleSpentPoll(t *testing.T) { + setPlanRouting(t, nil, nil) + now := time.Unix(1_800_000_000, 0) + forgetReadings(t, "codex-reset", "codex-other") + week := 7 * 24 * time.Hour + ObserveQuotaWindows("codex-reset", now.Add(-2*24*time.Hour), []QuotaWindow{ + {Key: "seven_day", UsedPercent: 100, ResetAt: now.Add(24 * time.Hour), Period: week}, + }) + fresh := resetAuth("codex-reset", "codex", now.Add(6*24*time.Hour)) + fresh.Quota.ObservedAt = now.Add(-time.Minute) + fresh.Quota.Signals["X-Codex-Secondary-Used-Percent"] = "3" + if state, ok := governingQuotaWindowFor(fresh, "gpt-6", now); !ok || state.exhausted { + t.Fatalf("state = %+v, %v; want usable after newer headers", state, ok) + } + if reset := observedWeeklyReset(fresh, "gpt-6", now); !reset.Equal(now.Add(6 * 24 * time.Hour)) { + t.Fatalf("reset = %v, want the header's weekly reset", reset) + } + // Headers older than the poll change nothing. + stale := resetAuth("codex-reset", "codex", now.Add(6*24*time.Hour)) + stale.Quota.ObservedAt = now.Add(-3 * 24 * time.Hour) + stale.Quota.Signals["X-Codex-Secondary-Used-Percent"] = "3" + if state, ok := governingQuotaWindowFor(stale, "gpt-6", now); !ok || !state.exhausted { + t.Fatalf("state = %+v, %v; want still exhausted with older headers", state, ok) + } + // A manual quota reset forgets the spent poll. + ForgetQuotaWindows("codex-reset") + if _, ok := governingQuotaWindowFor(stale, "gpt-6", now); ok { + t.Fatal("reading survived ForgetQuotaWindows") + } +} + +// A scoped cap that only response headers report stays in force when a newer +// poll does not read that family. +func TestHeaderScopedCapSurvivesPollWithoutThatFamily(t *testing.T) { + now := time.Unix(1_800_000_000, 0) + forgetReadings(t, "claude-sonnet-cap") + auth := resetAuth("claude-sonnet-cap", "claude", now.Add(4*24*time.Hour)) + auth.Quota.ObservedAt = now.Add(-10 * time.Minute) + auth.Quota.Signals["Anthropic-Ratelimit-Unified-7d_sonnet-Reset"] = fmt.Sprint(now.Add(2 * 24 * time.Hour).Unix()) + auth.Quota.Signals["Anthropic-Ratelimit-Unified-7d_sonnet-Status"] = "rejected" + ObserveQuotaWindows(auth.ID, now.Add(-time.Minute), []QuotaWindow{ + {Key: "seven_day", UsedPercent: 30, ResetAt: now.Add(4 * 24 * time.Hour), Period: 7 * 24 * time.Hour}, + }) + if state, ok := governingQuotaWindowFor(auth, "claude-sonnet-5", now); !ok || !state.exhausted { + t.Fatalf("sonnet state = %+v, %v; want exhausted from headers", state, ok) + } + if state, ok := governingQuotaWindowFor(auth, "claude-opus-5-5", now); !ok || state.exhausted { + t.Fatalf("opus state = %+v, %v; want usable", state, ok) + } +} + +// A usage-only account whose poll failed is not starved by a sibling that has +// a reading; accounts of other providers do not change that. +func TestUsageOnlyAccountWithoutReadingIsNotStarved(t *testing.T) { + setPlanRouting(t, nil, nil) + now := time.Unix(1_800_000_000, 0) + forgetReadings(t, "agy-read", "agy-unread") + ObserveQuotaWindows("agy-read", now.Add(-time.Minute), []QuotaWindow{ + {Key: "group_pro_weekly", UsedPercent: 99, ResetAt: now.Add(24 * time.Hour), Period: 7 * 24 * time.Hour}, + }) + read := &Auth{ID: "agy-read", Provider: "antigravity"} + unread := &Auth{ID: "agy-unread", Provider: "antigravity"} + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + if got := countPicks(t, selector, "antigravity", "gemini-pro", []*Auth{read, unread}, 20); got["agy-read"] != 10 || got["agy-unread"] != 10 { + t.Fatalf("picks = %v, want an even rotation", got) + } + // Once both have readings the pool is ranked again. + ObserveQuotaWindows("agy-unread", now.Add(-time.Minute), []QuotaWindow{ + {Key: "group_pro_weekly", UsedPercent: 5, ResetAt: now.Add(3 * 24 * time.Hour), Period: 7 * 24 * time.Hour}, + }) + if got := countPicks(t, selector, "antigravity", "gemini-pro", []*Auth{read, unread}, 10); got["agy-read"] != 10 { + t.Fatalf("picks = %v, want the sooner reset", got) + } +} + +// A poll that carries no usable reset does not stop the account from being +// probed: only passive readings count for the probe interval. +func TestEmptyPollDoesNotSuppressProbe(t *testing.T) { + setPlanRouting(t, nil, nil) + now := time.Unix(1_800_000_000, 0) + forgetReadings(t, "claude-fresh", "claude-ranked") + ranked := resetAuth("claude-ranked", "claude", now.Add(2*24*time.Hour)) + ranked.Quota.ObservedAt = now.Add(-time.Minute) + fresh := &Auth{ID: "claude-fresh", Provider: "claude"} + ObserveQuotaWindows(fresh.ID, now.Add(-time.Minute), nil) + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + if got := countPicks(t, selector, "claude", "claude-sonnet-5", []*Auth{ranked, fresh}, 5); got["claude-fresh"] != 5 { + t.Fatalf("picks = %v, want the unread account probed", got) + } +} + +// Devin sends no reset in response headers, so an account without a reading +// rotates with its siblings instead of winning every pick as a probe. +func TestDevinAccountWithoutReadingRotates(t *testing.T) { + setPlanRouting(t, nil, nil) + now := time.Unix(1_800_000_000, 0) + forgetReadings(t, "devin-read", "devin-unread") + ObserveQuotaWindows("devin-read", now.Add(-time.Minute), []QuotaWindow{ + {Key: "weekly", UsedPercent: 10, ResetAt: now.Add(3 * 24 * time.Hour), Period: 7 * 24 * time.Hour}, + }) + read := &Auth{ID: "devin-read", Provider: "devin"} + unread := &Auth{ID: "devin-unread", Provider: "devin"} + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + if got := countPicks(t, selector, "devin", "devin-1", []*Auth{read, unread}, 10); got["devin-read"] != 5 || got["devin-unread"] != 5 { + t.Fatalf("picks = %v, want an even rotation", got) + } +} + +// An unread account of one usage-only provider does not take ranking away from +// the other providers in a mixed pool. +func TestUnreadUsageOnlyAccountLeavesOtherProvidersRanked(t *testing.T) { + setPlanRouting(t, nil, nil) + now := time.Unix(1_800_000_000, 0) + forgetReadings(t, "agy-mixed-read", "agy-mixed-unread") + sooner := resetAuth("claude-sooner", "claude", now.Add(24*time.Hour)) + sooner.Quota.ObservedAt = now.Add(-time.Minute) + later := resetAuth("claude-later", "claude", now.Add(4*24*time.Hour)) + later.Quota.ObservedAt = now.Add(-time.Minute) + ObserveQuotaWindows("agy-mixed-read", now.Add(-time.Minute), []QuotaWindow{ + {Key: "group_pro_weekly", UsedPercent: 5, ResetAt: now.Add(2 * time.Hour), Period: 7 * 24 * time.Hour}, + }) + read := &Auth{ID: "agy-mixed-read", Provider: "antigravity"} + unread := &Auth{ID: "agy-mixed-unread", Provider: "antigravity"} + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + if got := countPicks(t, selector, "mixed", "shared-model", []*Auth{later, read, unread, sooner}, 20); got["claude-sooner"] != 20 { + t.Fatalf("picks = %v, want all on the soonest-reset Claude account", got) + } +} diff --git a/sdk/cliproxy/auth/quota_windows_observation.go b/sdk/cliproxy/auth/quota_windows_observation.go new file mode 100644 index 00000000000..b712813f325 --- /dev/null +++ b/sdk/cliproxy/auth/quota_windows_observation.go @@ -0,0 +1,246 @@ +package auth + +import ( + "math" + "path" + "strconv" + "strings" + "sync" + "time" +) + +// QuotaWindow is a renewing allowance read from a provider's usage endpoint. +type QuotaWindow struct { + Key string + UsedPercent float64 + ResetAt time.Time + Period time.Duration + // ModelScope contains model IDs or path.Match patterns. Empty means all models. + ModelScope []string +} + +type quotaWindowReading struct { + observedAt time.Time + windows []QuotaWindow +} + +var quotaWindowReadings = struct { + sync.RWMutex + byAuth map[string]quotaWindowReading +}{byAuth: make(map[string]quotaWindowReading)} + +// ObserveQuotaWindows replaces an account's usage reading, including an empty +// reading. Older observations cannot replace newer ones. Inputs are copied. +func ObserveQuotaWindows(authID string, observedAt time.Time, windows []QuotaWindow) { + authID = strings.TrimSpace(authID) + if authID == "" || observedAt.IsZero() { + return + } + normalized := make([]QuotaWindow, 0, len(windows)) + for _, window := range windows { + if window.Key == "" || window.Period <= 0 || window.ResetAt.IsZero() || math.IsNaN(window.UsedPercent) || math.IsInf(window.UsedPercent, 0) || window.UsedPercent < 0 { + continue + } + window.ModelScope = append([]string(nil), window.ModelScope...) + normalized = append(normalized, window) + } + quotaWindowReadings.Lock() + defer quotaWindowReadings.Unlock() + if previous := quotaWindowReadings.byAuth[authID]; previous.observedAt.After(observedAt) { + return + } + quotaWindowReadings.byAuth[authID] = quotaWindowReading{observedAt: observedAt, windows: normalized} +} + +// ObservedQuotaWindows returns an independent copy of the latest account reading. +func ObservedQuotaWindows(authID string) (time.Time, []QuotaWindow) { + quotaWindowReadings.RLock() + reading := quotaWindowReadings.byAuth[strings.TrimSpace(authID)] + quotaWindowReadings.RUnlock() + windows := append([]QuotaWindow(nil), reading.windows...) + for i := range windows { + windows[i].ModelScope = append([]string(nil), windows[i].ModelScope...) + } + return reading.observedAt, windows +} + +// ForgetQuotaWindows removes an account's usage-endpoint observations. +func ForgetQuotaWindows(authID string) { + quotaWindowReadings.Lock() + delete(quotaWindowReadings.byAuth, strings.TrimSpace(authID)) + quotaWindowReadings.Unlock() +} + +func quotaWindowMatches(window QuotaWindow, model string) bool { + if len(window.ModelScope) == 0 { + return true + } + model = strings.ToLower(strings.TrimSpace(model)) + for _, scope := range window.ModelScope { + if match, _ := path.Match(strings.ToLower(scope), model); match { + return true + } + } + return false +} + +// passiveUsage is one allowance window read from passive response headers. +type passiveUsage struct { + period time.Duration + scoped bool + usedPercent float64 +} + +// passiveWindowUsage returns the windows that the newest passive observation of +// the account reports for model, when that observation is newer than after. +// Only Claude and Codex send such headers. +func passiveWindowUsage(auth *Auth, model string, after time.Time) []passiveUsage { + quota := latestQuota(auth, model) + if !quota.ObservedAt.After(after) || len(quota.Signals) == 0 { + return nil + } + signals := make(map[string]string, len(quota.Signals)) + for key, value := range quota.Signals { + signals[strings.ToLower(key)] = strings.TrimSpace(value) + } + number := func(key string) (float64, bool) { + value, errParse := strconv.ParseFloat(signals[key], 64) + return value, errParse == nil && !math.IsNaN(value) && !math.IsInf(value, 0) + } + var out []passiveUsage + switch strings.ToLower(strings.TrimSpace(auth.Provider)) { + case "claude": + const prefix = "anthropic-ratelimit-unified-" + tokens := modelScopeTokens(model) + for key := range signals { + name, isUtilization := strings.CutSuffix(key, "-utilization") + name, hasPrefix := strings.CutPrefix(name, prefix) + if !isUtilization || !hasPrefix { + continue + } + usage := passiveUsage{period: 7 * 24 * time.Hour} + switch family, scoped := strings.CutPrefix(name, "7d_"); { + case name == "5h": + usage.period = shortWindowLength + case name == "7d": + case scoped: + if _, match := tokens[family]; !match { + continue + } + usage.scoped = true + default: + continue + } + // Utilization is a fraction (0-1) in the unified headers. + fraction, ok := number(key) + if !ok { + continue + } + usage.usedPercent = fraction * 100 + if strings.EqualFold(signals[prefix+name+"-status"], "rejected") { + usage.usedPercent = 100 + } + out = append(out, usage) + } + case "codex": + for _, window := range []string{"primary", "secondary"} { + minutes, okMinutes := number("x-codex-" + window + "-window-minutes") + used, okUsed := number("x-codex-" + window + "-used-percent") + if okMinutes && okUsed && minutes > 0 { + out = append(out, passiveUsage{period: time.Duration(minutes * float64(time.Minute)), usedPercent: used}) + } + } + } + return out +} + +// passiveShowsHeadroom reports whether a newer passive observation shows the +// same window with allowance left, which happens when a window resets early. +func passiveShowsHeadroom(passive []passiveUsage, window QuotaWindow) bool { + for _, usage := range passive { + difference := usage.period - window.Period + if difference < 0 { + difference = -difference + } + if usage.scoped == (len(window.ModelScope) > 0) && difference <= window.Period/10 && usage.usedPercent < 100 { + return true + } + } + return false +} + +// observedGoverningWindow reads the account's polled windows for model. The +// longest window that governs the model gives the reset used for ranking. The +// account is exhausted when any governing window is spent, unless a newer +// passive observation shows that window with allowance left; its reset is then +// the time the last spent window renews. +func observedGoverningWindow(auth *Auth, model string, now time.Time) (scopedWeeklyState, bool) { + observedAt, windows := ObservedQuotaWindows(auth.ID) + if observedAt.IsZero() || observedAt.After(now) { + return scopedWeeklyState{}, false + } + passive := passiveWindowUsage(auth, model, observedAt) + var best QuotaWindow + var usableAt time.Time + for _, window := range windows { + if !quotaWindowMatches(window, model) || !window.ResetAt.After(now) || window.ResetAt.Sub(now) > window.Period+24*time.Hour || now.Sub(observedAt) > window.Period+24*time.Hour { + continue + } + if window.UsedPercent >= 100 && !passiveShowsHeadroom(passive, window) && window.ResetAt.After(usableAt) { + usableAt = window.ResetAt + } + if best.Period > window.Period { + continue + } + if best.Period == window.Period { + // Prefer a model-scoped cap over an account-wide cap of equal length. + if len(best.ModelScope) > 0 && len(window.ModelScope) == 0 { + continue + } + if (len(best.ModelScope) > 0) == (len(window.ModelScope) > 0) && !window.ResetAt.Before(best.ResetAt) { + continue + } + } + best = window + } + if best.Period == 0 { + return scopedWeeklyState{}, false + } + state := scopedWeeklyState{reset: best.ResetAt, observedAt: observedAt, scoped: len(best.ModelScope) > 0} + if !usableAt.IsZero() { + state.exhausted, state.reset = true, usableAt + } + return state, true +} + +// governingQuotaWindowFor combines the polled windows with Claude's +// model-scoped weekly cap, which is also read from response headers. The scoped +// cap decides ranking; a poll replaces a header reading of it only when the +// poll is newer and itself read a scoped cap for the model. Another spent +// window from the poll still marks the account exhausted. +func governingQuotaWindowFor(auth *Auth, model string, now time.Time) (scopedWeeklyState, bool) { + state, ok := observedGoverningWindow(auth, model, now) + scoped, hasScoped := scopedWeeklyWindowFor(auth, model, now) + if !hasScoped { + return state, ok + } + scoped.scoped = true + if !ok { + return scoped, true + } + if state.scoped && state.observedAt.After(scoped.observedAt) { + return state, true + } + if state.exhausted && !scoped.exhausted { + scoped.exhausted, scoped.reset = true, state.reset + } + return scoped, true +} + +// quotaObservationCanProbe reports whether serving a request yields a reset +// the selector can rank by. Only Claude and Codex send one in response +// headers; every other provider is ranked from the quota-history recorder. +func quotaObservationCanProbe(auth *Auth) bool { + provider := strings.ToLower(strings.TrimSpace(auth.Provider)) + return provider == "claude" || provider == "codex" +} diff --git a/sdk/cliproxy/auth/quota_windows_observation_test.go b/sdk/cliproxy/auth/quota_windows_observation_test.go new file mode 100644 index 00000000000..cee738d681d --- /dev/null +++ b/sdk/cliproxy/auth/quota_windows_observation_test.go @@ -0,0 +1,131 @@ +package auth + +import ( + "context" + "math" + "testing" + "time" + + cliproxyexecutor "github.com/rune-oai/t3code-proxy/sdk/cliproxy/executor" +) + +func TestQuotaWindowsSnapshot(t *testing.T) { + id := t.Name() + t.Cleanup(func() { ForgetQuotaWindows(id) }) + now := time.Date(2026, 11, 15, 0, 0, 0, 0, time.UTC) + windows := []QuotaWindow{{Key: "weekly", UsedPercent: 42, ResetAt: now.Add(time.Hour), Period: 168 * time.Hour, ModelScope: []string{"gemini-*"}}} + ObserveQuotaWindows(id, now, windows) + windows[0].ModelScope[0] = "claude-*" + windows[0].UsedPercent = 100 + ObserveQuotaWindows(id, now.Add(-time.Second), nil) + observed, got := ObservedQuotaWindows(id) + if !observed.Equal(now) || len(got) != 1 || got[0].UsedPercent != 42 || got[0].ModelScope[0] != "gemini-*" { + t.Fatalf("snapshot = %v %+v", observed, got) + } + got[0].ModelScope[0] = "gpt-*" + _, got = ObservedQuotaWindows(id) + if got[0].ModelScope[0] != "gemini-*" { + t.Fatal("reader mutated stored scope") + } + ObserveQuotaWindows(id, now.Add(time.Second), []QuotaWindow{{Key: "invalid", Period: time.Hour, ResetAt: now, UsedPercent: math.NaN()}}) + observed, got = ObservedQuotaWindows(id) + if !observed.Equal(now.Add(time.Second)) || len(got) != 0 { + t.Fatal("invalid windows were retained") + } + ForgetQuotaWindows(id) + observed, got = ObservedQuotaWindows(id) + if !observed.IsZero() || len(got) != 0 { + t.Fatal("forgotten windows were retained") + } +} + +func TestSoonestResetFirstUsageWindows(t *testing.T) { + now := time.Date(2026, 11, 15, 0, 0, 0, 0, time.UTC) + for _, provider := range []string{"xai", "kimi", "meta", "devin", "antigravity", "fixture-plugin"} { + t.Run(provider, func(t *testing.T) { + a := &Auth{ID: t.Name() + "-a", Provider: provider} + b := &Auth{ID: t.Name() + "-b", Provider: provider} + t.Cleanup(func() { ForgetQuotaWindows(a.ID); ForgetQuotaWindows(b.ID) }) + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + publish := func(auth *Auth, used float64, reset time.Duration) { + ObserveQuotaWindows(auth.ID, now, []QuotaWindow{ + {Key: "weekly", UsedPercent: used, ResetAt: now.Add(reset), Period: 168 * time.Hour}, + {Key: "daily", UsedPercent: 10, ResetAt: now.Add(2 * time.Hour), Period: 24 * time.Hour}, + }) + } + pick := func(model string, want *Auth) { + t.Helper() + got, err := selector.Pick(context.Background(), provider, model, cliproxyexecutor.Options{}, []*Auth{a, b}) + if err != nil || got != want { + t.Fatalf("Pick(%s) = %v %v, want %s", model, got, err, want.ID) + } + } + publish(a, 20, 72*time.Hour) + publish(b, 20, 48*time.Hour) + pick("gemini-3-pro", b) // Longest window determines rank, despite equal daily resets. + publish(b, 100, 48*time.Hour) + pick("gemini-3-pro", a) + publish(a, 100, 72*time.Hour) + pick("gemini-3-pro", b) // Every account is spent, so keep earliest reset. + ObserveQuotaWindows(a.ID, now, []QuotaWindow{ + {Key: "monthly", UsedPercent: 10, ResetAt: now.Add(10 * 24 * time.Hour), Period: 30 * 24 * time.Hour}, + {Key: "weekly", UsedPercent: 20, ResetAt: now.Add(24 * time.Hour), Period: 168 * time.Hour}, + }) + publish(b, 20, 48*time.Hour) + pick("gemini-3-pro", b) // Monthly observations are usable beyond eight days. + ObserveQuotaWindows(a.ID, now, []QuotaWindow{ + {Key: "gemini", UsedPercent: 100, ResetAt: now.Add(time.Hour), Period: 168 * time.Hour, ModelScope: []string{"gemini-*"}}, + {Key: "claude", UsedPercent: 10, ResetAt: now.Add(time.Hour), Period: 168 * time.Hour, ModelScope: []string{"claude-*"}}, + }) + pick("gemini-3-pro", b) + pick("claude-opus-4", a) + }) + } +} + +func TestObservedQuotaWindowExpiryAndScope(t *testing.T) { + now := time.Date(2026, 11, 15, 0, 0, 0, 0, time.UTC) + auth := &Auth{ID: t.Name(), Provider: "antigravity"} + t.Cleanup(func() { ForgetQuotaWindows(auth.ID) }) + cases := []struct { + name string + observed, reset time.Time + period time.Duration + scopes []string + want bool + }{ + {"expired", now.Add(-time.Hour), now, time.Hour, nil, false}, + {"future observation", now.Add(time.Second), now.Add(time.Hour), time.Hour, nil, false}, + {"stale", now.Add(-48 * time.Hour), now.Add(time.Hour), time.Hour, nil, false}, + {"implausible reset", now, now.Add(48 * time.Hour), time.Hour, nil, false}, + {"different model", now, now.Add(time.Hour), 168 * time.Hour, []string{"claude-*"}, false}, + {"unknown scope", now, now.Add(time.Hour), 168 * time.Hour, []string{""}, false}, + {"matching scope", now, now.Add(time.Hour), 168 * time.Hour, []string{"gemini-*"}, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + ForgetQuotaWindows(auth.ID) + ObserveQuotaWindows(auth.ID, tc.observed, []QuotaWindow{{Key: "cap", UsedPercent: 100, ResetAt: tc.reset, Period: tc.period, ModelScope: tc.scopes}}) + if _, ok := observedGoverningWindow(auth, "gemini-3-pro", now); ok != tc.want { + t.Fatalf("usable = %v, want %v", ok, tc.want) + } + }) + } +} + +func TestUsageOnlyProvidersWithoutReadingsKeepRoundRobin(t *testing.T) { + now := time.Date(2026, 11, 15, 0, 0, 0, 0, time.UTC) + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + a, b := &Auth{ID: t.Name() + "-a", Provider: "xai"}, &Auth{ID: t.Name() + "-b", Provider: "xai"} + counts := map[string]int{} + for range 4 { + got, err := selector.Pick(context.Background(), "xai", "grok-4", cliproxyexecutor.Options{}, []*Auth{a, b}) + if err != nil { + t.Fatal(err) + } + counts[got.ID]++ + } + if counts[a.ID] != 2 || counts[b.ID] != 2 { + t.Fatalf("counts = %v", counts) + } +} diff --git a/sdk/cliproxy/auth/selector.go b/sdk/cliproxy/auth/selector.go index 938748c041a..0aa4d71c2fd 100644 --- a/sdk/cliproxy/auth/selector.go +++ b/sdk/cliproxy/auth/selector.go @@ -1532,6 +1532,10 @@ func (s *SessionAffinitySelector) shouldPreserveBindingWhenUnavailable(ctx conte if s == nil || (!s.rebindOnQuotaOnly && !s.rebindOnNever) || authID == "" { return false } + // A spent scoped weekly cap is a quota condition, not a transient one. + if !s.rebindOnNever && boundAuthScopedWeeklyCapSpent(candidates, model, authID, now) { + return false + } if ctx != nil { if validated, _ := ctx.Value(prevalidatedAuthCandidatesKey{}).(bool); validated { transientAuthIDs := sessionAffinityTransientAuthIDsFromContext(ctx) @@ -1694,6 +1698,10 @@ func (s *SessionAffinitySelector) Pick(ctx context.Context, provider, model stri if err != nil && !s.rebindOnNever { return nil, err } + if !s.rebindOnNever { + // A bound account whose scoped weekly cap is known spent rebinds before sending. + available = withoutSpentScopedWeeklyCaps(available, model, now) + } fallbackAuths := highestPriorityAuths(available) modelKey := canonicalModelKey(model) @@ -1875,6 +1883,10 @@ func (s *SessionAffinitySelector) pickLCP(ctx context.Context, provider, model s if errAvailable != nil && !s.rebindOnNever { return nil, true, errAvailable } + if !s.rebindOnNever { + // A bound account whose scoped weekly cap is known spent rebinds before sending. + available = withoutSpentScopedWeeklyCaps(available, model, now) + } var preservedAuthID string if match, ok := s.matcher.MatchFingerprintsWithContext(namespace, fingerprints, tailFingerprints, envDigest, minPrefixLength); ok { diff --git a/sdk/cliproxy/auth/selector_affinity_scoped.go b/sdk/cliproxy/auth/selector_affinity_scoped.go new file mode 100644 index 00000000000..2446dfeed9a --- /dev/null +++ b/sdk/cliproxy/auth/selector_affinity_scoped.go @@ -0,0 +1,50 @@ +package auth + +import "time" + +// A conversation bound by session affinity keeps its account while that +// account is available. A spent model-scoped weekly cap (see +// selector_reset_scoped.go) does not make the account unavailable in the +// scheduler, so without this check the bound conversation would be sent once, +// get a 429, and only then rebind. When the hub already knows the cap is spent +// and another eligible account exists, the session-affinity wrapper treats the +// spent account as unavailable for that model and rebinds before sending. + +// scopedWeeklyCapSpent reports whether the newest observation of the allowance +// governing model on auth shows it spent. It uses the same lookup as the +// soonest-reset-first selector, so it covers Claude's model-scoped weekly caps +// and the recorded windows of every other provider. +func scopedWeeklyCapSpent(auth *Auth, model string, now time.Time) bool { + state, ok := governingQuotaWindowFor(auth, model, now) + return ok && state.exhausted +} + +// withoutSpentScopedWeeklyCaps drops accounts whose model-scoped weekly cap is +// known spent, as long as at least one account remains. When every account is +// spent the list is returned unchanged so the inner selector can still choose. +func withoutSpentScopedWeeklyCaps(auths []*Auth, model string, now time.Time) []*Auth { + if len(auths) < 2 { + return auths + } + usable := make([]*Auth, 0, len(auths)) + for _, auth := range auths { + if !scopedWeeklyCapSpent(auth, model, now) { + usable = append(usable, auth) + } + } + if len(usable) == 0 || len(usable) == len(auths) { + return auths + } + return usable +} + +// boundAuthScopedWeeklyCapSpent reports whether the bound account authID, found +// in candidates, has a spent model-scoped weekly cap for model. +func boundAuthScopedWeeklyCapSpent(candidates []*Auth, model, authID string, now time.Time) bool { + for _, candidate := range candidates { + if candidate != nil && candidate.ID == authID { + return scopedWeeklyCapSpent(candidate, model, now) + } + } + return false +} diff --git a/sdk/cliproxy/auth/selector_affinity_scoped_test.go b/sdk/cliproxy/auth/selector_affinity_scoped_test.go new file mode 100644 index 00000000000..1f1671f86f4 --- /dev/null +++ b/sdk/cliproxy/auth/selector_affinity_scoped_test.go @@ -0,0 +1,77 @@ +package auth + +import ( + "context" + "testing" + "time" + + cliproxyexecutor "github.com/rune-oai/t3code-proxy/sdk/cliproxy/executor" +) + +// A conversation bound to an account whose model-scoped weekly cap the hub +// already knows is spent rebinds before the request is sent, instead of being +// sent once, getting a 429, and only then rebinding. +func TestSessionAffinityRebindsBeforeSendingOnKnownSpentScopedCap(t *testing.T) { + for _, rebindOn := range []string{SessionAffinityRebindOnAny, SessionAffinityRebindOnQuota, SessionAffinityRebindOnNever} { + t.Run(rebindOn, func(t *testing.T) { + now := time.Now() + day := 24 * time.Hour + a := resetAuth("affinity-scoped-a-"+rebindOn, "claude", now.Add(day)) + b := resetAuth("affinity-scoped-b-"+rebindOn, "claude", now.Add(4*day)) + auths := []*Auth{a, b} + t.Cleanup(func() { ForgetScopedWeeklyWindows(a.ID) }) + selector := NewSessionAffinitySelectorWithConfig(SessionAffinityConfig{ + Fallback: &SoonestResetFirstSelector{}, + TTL: time.Hour, + RebindOn: rebindOn, + }) + t.Cleanup(selector.Stop) + session := cliproxyexecutor.Options{Headers: map[string][]string{"X-Session-Id": {"affinity-scoped-" + rebindOn}}} + pick := func(model, want, step string) { + t.Helper() + got, err := selector.Pick(context.Background(), "claude", model, session, auths) + if err != nil || got == nil || got.ID != want { + t.Fatalf("%s: Pick() = %v, %v; want %s", step, got, err, want) + } + } + + pick(fableModel, a.ID, "conversation binds to the soonest reset") + // The quota-history recorder learns that a's Fable weekly cap is spent. + // No request result (and no 429) is reported to the selector. + ObserveScopedWeeklyWindows(a.ID, now, map[string]ScopedWeeklyWindow{"fable": {UsedPercent: 100, ResetAt: now.Add(3 * day)}}) + if rebindOn == SessionAffinityRebindOnNever { + pick(fableModel, a.ID, "never mode keeps the binding") + return + } + pick(fableModel, b.ID, "bound conversation rebinds before sending") + // The new binding sticks, also once the reading is gone. + ForgetScopedWeeklyWindows(a.ID) + pick(fableModel, b.ID, "rebound conversation stays on its new account") + }) + } +} + +// The spent cap only governs its model family and only matters when another +// eligible account exists. +func TestSessionAffinityScopedCapRebindScope(t *testing.T) { + now := time.Now() + day := 24 * time.Hour + a := resetAuth("affinity-scope-a", "claude", now.Add(day)) + b := resetAuth("affinity-scope-b", "claude", now.Add(4*day)) + t.Cleanup(func() { ForgetScopedWeeklyWindows(a.ID) }) + selector := NewSessionAffinitySelectorWithConfig(SessionAffinityConfig{Fallback: &SoonestResetFirstSelector{}, TTL: time.Hour}) + t.Cleanup(selector.Stop) + session := cliproxyexecutor.Options{Headers: map[string][]string{"X-Session-Id": {"affinity-scope"}}} + pick := func(model string, auths []*Auth, want, step string) { + t.Helper() + got, err := selector.Pick(context.Background(), "claude", model, session, auths) + if err != nil || got == nil || got.ID != want { + t.Fatalf("%s: Pick() = %v, %v; want %s", step, got, err, want) + } + } + pick("claude-sonnet-5", []*Auth{a, b}, a.ID, "sonnet conversation binds") + pick(fableModel, []*Auth{a}, a.ID, "fable conversation binds") + ObserveScopedWeeklyWindows(a.ID, now, map[string]ScopedWeeklyWindow{"fable": {UsedPercent: 100, ResetAt: now.Add(3 * day)}}) + pick("claude-sonnet-5", []*Auth{a, b}, a.ID, "a fable cap does not move a sonnet conversation") + pick(fableModel, []*Auth{a}, a.ID, "the only account is kept") +} diff --git a/sdk/cliproxy/auth/selector_reset.go b/sdk/cliproxy/auth/selector_reset.go index db51b4ad2e7..0b3963d01f7 100644 --- a/sdk/cliproxy/auth/selector_reset.go +++ b/sdk/cliproxy/auth/selector_reset.go @@ -3,8 +3,10 @@ package auth import ( "context" "net/http" + "sort" "strconv" "strings" + "sync" "time" cliproxyexecutor "github.com/rune-oai/t3code-proxy/sdk/cliproxy/executor" @@ -16,14 +18,25 @@ import ( // that reset passes. Accounts without a usable reset whose last observation is // absent or older than probeInterval are probed first, so every account gets // observed after restarts and resets. Accounts that never report a weekly -// window, such as Grok or Antigravity, therefore keep round-robin behavior. +// window keep round-robin behavior until the recorder publishes a reading. // // When the requested model is governed by a model-scoped weekly cap (see // selector_reset_scoped.go), accounts whose latest observation shows that cap // spent are skipped while another eligible account exists, and the scoped // cap's reset replaces the overall weekly reset for ranking. +// +// Plan capacity (see plan_weight.go) shapes two decisions. Accounts whose +// plan-weighted 5-hour headroom is below routing.plan-headroom-reserve are +// skipped for new conversations while another eligible account has headroom +// (see plan_headroom.go). Where several accounts remain equal (tied resets, +// probes, or pools that report no quota), new conversations are spread in +// proportion to plan weight with smooth weighted round-robin, so a Max 20x +// account takes twenty conversations for every one on a Pro account. With equal +// weights this is plain round-robin in ID order. type SoonestResetFirstSelector struct { - fallback RoundRobinSelector + mu sync.Mutex + // credits holds the smooth weighted round-robin state per provider and model. + credits map[string]map[string]float64 // now overrides the clock in tests. now func() time.Time } @@ -38,12 +51,12 @@ func (s *SoonestResetFirstSelector) Pick(ctx context.Context, provider, model st return nil, err } available = preferCodexWebsocketAuths(ctx, provider, available) - // Skip accounts whose scoped cap for this model is spent. When every account + // Skip accounts whose governing allowance for this model is spent. When every account // is spent, keep them all so ranking picks the one whose cap resets first. scoped := make(map[*Auth]scopedWeeklyState) usable := make([]*Auth, 0, len(available)) for _, auth := range available { - state, ok := scopedWeeklyWindowFor(auth, model, now) + state, ok := governingQuotaWindowFor(auth, model, now) if ok { scoped[auth] = state } @@ -53,40 +66,161 @@ func (s *SoonestResetFirstSelector) Pick(ctx context.Context, provider, model st } if len(usable) > 0 { available = usable + } else if wait, ok := waitForCoolingSibling(ctx, scoped, model, now); ok { + // Every account that can take the request is known to be spent, and one with + // allowance left is only cooling down. Sending the request to a spent account + // would hand the client that account's "limit reached until its reset" instead + // of the short wait that is actually ahead. + if provider == "mixed" { + provider = "" + } + return nil, newModelCooldownError(model, provider, wait) } - var earliest time.Time - var candidates, probes []*Auth + available = withShortWindowHeadroom(available, planHeadroomReserve(), now) + type rankedAuth struct { + auth *Auth + reset time.Time + } + var ranked []rankedAuth + var probes []*Auth + // Providers with a usage-only account that has no reading. + unread := make(map[string]bool) for _, auth := range available { reset := observedWeeklyReset(auth, model, now) - if state, ok := scoped[auth]; ok { + if state, ok := scoped[auth]; ok && (state.scoped || state.exhausted) { reset = state.reset } - if reset.IsZero() { - // Only providers that report quota can produce an observation; others (Grok, - // Antigravity) would otherwise stay probes forever and win every mixed pool. - if !ProviderSupportsQuotaObservation(auth.Provider) { - continue - } - if observed := lastObservation(auth, model); observed.IsZero() || now.Sub(observed) > probeInterval { - probes = append(probes, auth) - } + if !reset.IsZero() { + ranked = append(ranked, rankedAuth{auth: auth, reset: reset}) + continue + } + // A usage-only account gets readings only from the recorder. + if !quotaObservationCanProbe(auth) { + unread[strings.ToLower(auth.Provider)] = true + continue + } + if observed := lastObservation(auth, model); observed.IsZero() || now.Sub(observed) > probeInterval { + probes = append(probes, auth) + } + } + // While one account of a usage-only provider has no reading, ranking its + // siblings would starve it, so that provider is left out of ranking. Other + // providers in the same pool are still ranked. + var earliest time.Time + var candidates []*Auth + for _, entry := range ranked { + if unread[strings.ToLower(entry.auth.Provider)] { continue } - if earliest.IsZero() || reset.Before(earliest) { - earliest = reset - candidates = []*Auth{auth} - } else if reset.Equal(earliest) { - candidates = append(candidates, auth) + if earliest.IsZero() || entry.reset.Before(earliest) { + earliest = entry.reset + candidates = []*Auth{entry.auth} + } else if entry.reset.Equal(earliest) { + candidates = append(candidates, entry.auth) } } switch { case len(probes) > 0: - return s.fallback.Pick(ctx, provider, model, opts, probes) + return s.pickWeighted(provider, model, probes), nil case len(candidates) > 0: - return s.fallback.Pick(ctx, provider, model, opts, candidates) + return s.pickWeighted(provider, model, candidates), nil default: - return s.fallback.Pick(ctx, provider, model, opts, available) + return s.pickWeighted(provider, model, available), nil + } +} + +// coolingCandidate is an account kept out of a pick only until a known time: a +// quota cooldown, or the hold after a transient upstream error. +type coolingCandidate struct { + auth *Auth + until time.Time +} + +type coolingCandidatesKey struct{} + +// withCoolingCandidates tells the selector which candidates are cooling down. +// The manager hands selectors only the available accounts, so without this a +// selector cannot tell "every account is spent" from "the account with +// allowance left is unavailable for a moment". +func withCoolingCandidates(ctx context.Context, cooling []coolingCandidate) context.Context { + if len(cooling) == 0 { + return ctx + } + if ctx == nil { + ctx = context.Background() + } + return context.WithValue(ctx, coolingCandidatesKey{}, cooling) +} + +// waitForCoolingSibling reports how long to wait when a cooling account still +// has allowance: until the first such account is back, or until the first +// spent account resets if that comes sooner. spent holds the governing state +// of the available accounts, all of which are exhausted. +func waitForCoolingSibling(ctx context.Context, spent map[*Auth]scopedWeeklyState, model string, now time.Time) (time.Duration, bool) { + if ctx == nil { + return 0, false + } + cooling, _ := ctx.Value(coolingCandidatesKey{}).([]coolingCandidate) + var back time.Time + for _, candidate := range cooling { + if candidate.auth == nil || !candidate.until.After(now) { + continue + } + if state, ok := governingQuotaWindowFor(candidate.auth, model, now); ok && state.exhausted { + continue + } + if back.IsZero() || candidate.until.Before(back) { + back = candidate.until + } + } + if back.IsZero() { + return 0, false + } + for _, state := range spent { + if state.exhausted && state.reset.After(now) && state.reset.Before(back) { + back = state.reset + } } + return back.Sub(now), true +} + +// maxWeightedKeys bounds the number of provider/model credit tables kept. +const maxWeightedKeys = 4096 + +// pickWeighted picks one of auths with smooth weighted round-robin by plan +// weight: every candidate earns its weight, the richest is picked (ties go to +// the lowest ID) and pays the candidates' total. The result is deterministic +// and spreads picks in proportion to weight. Credits of accounts outside the +// current candidate set are dropped, so a set change starts them fresh. +func (s *SoonestResetFirstSelector) pickWeighted(provider, model string, auths []*Auth) *Auth { + if len(auths) == 1 { + return auths[0] + } + ordered := make([]*Auth, len(auths)) + copy(ordered, auths) + sort.Slice(ordered, func(i, j int) bool { return ordered[i].ID < ordered[j].ID }) + key := provider + ":" + canonicalModelLookupKey(model) + + s.mu.Lock() + defer s.mu.Unlock() + if s.credits == nil || (s.credits[key] == nil && len(s.credits) >= maxWeightedKeys) { + s.credits = make(map[string]map[string]float64) + } + previous := s.credits[key] + credits := make(map[string]float64, len(ordered)) + var total float64 + var picked *Auth + for _, auth := range ordered { + weight := PlanWeightOf(auth) + total += weight + credits[auth.ID] = previous[auth.ID] + weight + if picked == nil || credits[auth.ID] > credits[picked.ID] { + picked = auth + } + } + credits[picked.ID] -= total + s.credits[key] = credits + return picked } // probeInterval bounds how often an account without a usable weekly reset is @@ -101,11 +235,27 @@ func latestQuota(auth *Auth, model string) QuotaState { return quota } +// lastObservation is the time of the newest passive reading. Usage polls do +// not count: a poll that carries no usable reset arrives every interval and +// would otherwise keep an account from ever being probed. func lastObservation(auth *Auth, model string) time.Time { return latestQuota(auth, model).ObservedAt } +// observedWeeklyReset returns the reset used to rank the account: the polled +// governing window, or the weekly reset from response headers when those are +// newer (a window can reset early) or no poll exists. func observedWeeklyReset(auth *Auth, model string, now time.Time) time.Time { + passive := passiveWeeklyReset(auth, model, now) + state, ok := observedGoverningWindow(auth, model, now) + if !ok || (!passive.IsZero() && latestQuota(auth, model).ObservedAt.After(state.observedAt)) { + return passive + } + return state.reset +} + +// passiveWeeklyReset reads the weekly reset from passive response headers. +func passiveWeeklyReset(auth *Auth, model string, now time.Time) time.Time { quota := latestQuota(auth, model) // futureResetTime rejects resets that have passed or exceed one week. if quota.ObservedAt.IsZero() || quota.ObservedAt.After(now) || now.Sub(quota.ObservedAt) > 8*24*time.Hour { diff --git a/sdk/cliproxy/auth/selector_reset_cooling_test.go b/sdk/cliproxy/auth/selector_reset_cooling_test.go new file mode 100644 index 00000000000..d2eedf18ac8 --- /dev/null +++ b/sdk/cliproxy/auth/selector_reset_cooling_test.go @@ -0,0 +1,153 @@ +package auth + +import ( + "context" + "errors" + "net/http" + "testing" + "time" + + cliproxyexecutor "github.com/rune-oai/t3code-proxy/sdk/cliproxy/executor" +) + +// The case seen on a live hub: the account with allowance answered "overloaded" +// and went on a five-minute cooldown, which left only an account whose weekly +// limit was spent. New work must wait for the first, not be sent to the second, +// whose refusal tells the client to come back in two days. +func TestSpentAccountIsNotPickedWhileSiblingCoolsDown(t *testing.T) { + setPlanRouting(t, nil, nil) + now := time.Unix(1_800_000_000, 0) + forgetReadings(t, "codex-spent", "codex-open") + week := 7 * 24 * time.Hour + spentReset := now.Add(2 * 24 * time.Hour) + ObserveQuotaWindows("codex-spent", now.Add(-time.Minute), []QuotaWindow{ + {Key: "seven_day", UsedPercent: 100, ResetAt: spentReset, Period: week}, + }) + ObserveQuotaWindows("codex-open", now.Add(-time.Minute), []QuotaWindow{ + {Key: "seven_day", UsedPercent: 22, ResetAt: now.Add(5 * 24 * time.Hour), Period: week}, + }) + spent := &Auth{ID: "codex-spent", Provider: "codex"} + open := &Auth{ID: "codex-open", Provider: "codex"} + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + pick := func(ctx context.Context, auths ...*Auth) (*Auth, error) { + return selector.Pick(ctx, "codex", "gpt-6.1-sol", cliproxyexecutor.Options{}, auths) + } + + cooling := withCoolingCandidates(context.Background(), []coolingCandidate{{auth: open, until: now.Add(5 * time.Minute)}}) + got, err := pick(cooling, spent) + var cooldown *modelCooldownError + if got != nil || !errors.As(err, &cooldown) { + t.Fatalf("pick = %v, %v; want a cooldown error", got, err) + } + if cooldown.resetIn != 5*time.Minute { + t.Fatalf("wait = %v, want the sibling's 5m cooldown", cooldown.resetIn) + } + + // Mixed-provider picks name no provider in the error. + if _, err = selector.Pick(cooling, "mixed", "gpt-6.1-sol", cliproxyexecutor.Options{}, []*Auth{spent}); !errors.As(err, &cooldown) || cooldown.provider != "" { + t.Fatalf("mixed pick error = %v, want a cooldown error without a provider", err) + } + + // Without a cooling sibling every account really is spent: the provider answers. + if got, err = pick(context.Background(), spent); err != nil || got != spent { + t.Fatalf("pick with nothing cooling = %v, %v; want the spent account", got, err) + } + + // A cooling sibling that is itself spent is no reason to wait. + ObserveQuotaWindows("codex-open", now.Add(-time.Minute), []QuotaWindow{ + {Key: "seven_day", UsedPercent: 100, ResetAt: now.Add(5 * 24 * time.Hour), Period: week}, + }) + if got, err = pick(cooling, spent); err != nil || got != spent { + t.Fatalf("pick with a spent sibling cooling = %v, %v; want the spent account", got, err) + } + ObserveQuotaWindows("codex-open", now.Add(-time.Minute), []QuotaWindow{ + {Key: "seven_day", UsedPercent: 22, ResetAt: now.Add(5 * 24 * time.Hour), Period: week}, + }) + + // A cooldown that has already ended is ignored. + ended := withCoolingCandidates(context.Background(), []coolingCandidate{{auth: open, until: now.Add(-time.Second)}}) + if got, err = pick(ended, spent); err != nil || got != spent { + t.Fatalf("pick with an ended cooldown = %v, %v; want the spent account", got, err) + } + + // The wait is never longer than the spent account's own reset. + long := withCoolingCandidates(context.Background(), []coolingCandidate{{auth: open, until: now.Add(3 * 24 * time.Hour)}}) + if _, err = pick(long, spent); !errors.As(err, &cooldown) || cooldown.resetIn != spentReset.Sub(now) { + t.Fatalf("wait = %v (%v), want the spent account's reset in %v", cooldown.resetIn, err, spentReset.Sub(now)) + } + + // An account with allowance that is available is still simply picked. + if got, err = pick(cooling, spent, open); err != nil || got != open { + t.Fatalf("pick with the open account available = %v, %v; want it", got, err) + } +} + +// End to end through the manager: it is the manager that knows which candidates +// are cooling down, and the selector that knows which are spent. +func TestManagerWaitsForCoolingAccountInsteadOfSpentOne(t *testing.T) { + setPlanRouting(t, nil, nil) + ctx := context.Background() + const model = "cooling-sibling-model" + manager := NewManager(nil, &SoonestResetFirstSelector{}, nil) + manager.RegisterExecutor(schedulerProviderTestExecutor{provider: "codex"}) + registerSchedulerModels(t, "codex", model, "cooling-spent", "cooling-open") + forgetReadings(t, "cooling-spent", "cooling-open") + + spent := &Auth{ID: "cooling-spent", Provider: "codex"} + open := &Auth{ID: "cooling-open", Provider: "codex"} + for _, auth := range []*Auth{spent, open} { + if _, err := manager.Register(ctx, auth); err != nil { + t.Fatalf("register %s: %v", auth.ID, err) + } + } + now := time.Now() + week := 7 * 24 * time.Hour + ObserveQuotaWindows(spent.ID, now.Add(-time.Minute), []QuotaWindow{ + {Key: "seven_day", UsedPercent: 100, ResetAt: now.Add(2 * 24 * time.Hour), Period: week}, + }) + ObserveQuotaWindows(open.ID, now.Add(-time.Minute), []QuotaWindow{ + {Key: "seven_day", UsedPercent: 22, ResetAt: now.Add(5 * 24 * time.Hour), Period: week}, + }) + + // With both available, the account with allowance takes the work. + got, _, err := manager.pickNext(ctx, "codex", model, cliproxyexecutor.Options{}, nil) + if err != nil || got == nil || got.ID != open.ID { + t.Fatalf("pickNext() = %v, %v; want %s", got, err, open.ID) + } + + // The provider answers "overloaded" on that account, which puts it on a cooldown. + manager.MarkResult(ctx, Result{ + AuthID: open.ID, + Provider: "codex", + Model: model, + Success: false, + Error: &Error{HTTPStatus: http.StatusBadGateway, Message: "server_is_overloaded"}, + }) + current, ok := manager.GetByID(open.ID) + if !ok { + t.Fatal("open account vanished") + } + if blocked, _, next := isAuthBlockedForModel(current, model, time.Now()); !blocked || !next.After(time.Now()) { + t.Fatalf("the failed account is not on hold (blocked=%v until %v)", blocked, next) + } + + got, _, err = manager.pickNext(ctx, "codex", model, cliproxyexecutor.Options{}, nil) + var cooldown *modelCooldownError + if got != nil || !errors.As(err, &cooldown) { + t.Fatalf("pickNext() while the open account cools down = %v, %v; want a cooldown error, not the spent account", got, err) + } + if cooldown.resetIn <= 0 || cooldown.resetIn > 24*time.Hour { + t.Fatalf("wait = %v, want the open account's short cooldown", cooldown.resetIn) + } + + // The same holds inside one request: after the open account failed, the retry + // that excludes it must not fall back to the spent account either. + got, _, err = manager.pickNext(ctx, "codex", model, cliproxyexecutor.Options{}, map[string]struct{}{open.ID: {}}) + if got != nil || !errors.As(err, &cooldown) { + t.Fatalf("pickNext() retry after the open account failed = %v, %v; want a cooldown error", got, err) + } + gotMixed, _, _, errMixed := manager.pickNextMixed(ctx, []string{"codex"}, model, cliproxyexecutor.Options{}, map[string]struct{}{open.ID: {}}) + if gotMixed != nil || !errors.As(errMixed, &cooldown) { + t.Fatalf("pickNextMixed() retry after the open account failed = %v, %v; want a cooldown error", gotMixed, errMixed) + } +} diff --git a/sdk/cliproxy/auth/selector_reset_plan_test.go b/sdk/cliproxy/auth/selector_reset_plan_test.go new file mode 100644 index 00000000000..e273bd48d72 --- /dev/null +++ b/sdk/cliproxy/auth/selector_reset_plan_test.go @@ -0,0 +1,251 @@ +package auth + +import ( + "context" + "fmt" + "testing" + "time" + + cliproxyexecutor "github.com/rune-oai/t3code-proxy/sdk/cliproxy/executor" +) + +// planAuth is resetAuth with a plan and an optional 5-hour reading taken +// from passive headers (usedPercent < 0 means none). +func planAuth(id, provider, plan string, observedAt, weekly time.Time, usedPercent float64, fiveHourReset time.Time) *Auth { + auth := resetAuth(id, provider, weekly) + auth.Quota.ObservedAt = observedAt + auth.Attributes = map[string]string{"plan_type": plan} + if usedPercent < 0 { + return auth + } + switch provider { + case "claude": + auth.Quota.Signals["Anthropic-Ratelimit-Unified-5h-Utilization"] = fmt.Sprint(usedPercent / 100) + auth.Quota.Signals["Anthropic-Ratelimit-Unified-5h-Reset"] = fmt.Sprint(fiveHourReset.Unix()) + case "codex": + auth.Quota.Signals["X-Codex-Primary-Window-Minutes"] = "300" + auth.Quota.Signals["X-Codex-Primary-Used-Percent"] = fmt.Sprint(usedPercent) + auth.Quota.Signals["X-Codex-Primary-Reset-At"] = fmt.Sprint(fiveHourReset.Unix()) + } + return auth +} + +func countPicks(t *testing.T, selector *SoonestResetFirstSelector, provider, model string, auths []*Auth, n int) map[string]int { + t.Helper() + counts := make(map[string]int) + for range n { + got, err := selector.Pick(context.Background(), provider, model, cliproxyexecutor.Options{}, auths) + if err != nil || got == nil { + t.Fatalf("Pick() = %v, %v", got, err) + } + counts[got.ID]++ + } + return counts +} + +func TestSoonestResetFirstSpreadsTiesByPlanWeight(t *testing.T) { + setPlanRouting(t, nil, nil) + now := time.Unix(1_800_000_000, 0) + observed := now.Add(-time.Minute) + weekly := now.Add(2 * 24 * time.Hour) + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + + // Tied weekly resets: 1 + 5 + 20 = 26 picks land exactly in proportion. + pro := planAuth("pro", "claude", "pro", observed, weekly, -1, time.Time{}) + max5 := planAuth("max5", "claude", "max_5x", observed, weekly, -1, time.Time{}) + max20 := planAuth("max20", "claude", "default_claude_max_20x", observed, weekly, -1, time.Time{}) + auths := []*Auth{max20, pro, max5} + if got := countPicks(t, selector, "claude", "claude-sonnet-5", auths, 2*26); got["pro"] != 2 || got["max5"] != 10 || got["max20"] != 40 { + t.Fatalf("tied picks = %v, want pro:2 max5:10 max20:40", got) + } + + // The spread is smooth and deterministic: weights 1 and 2 give b, a, b. + a := planAuth("a", "codex", "plus", observed, weekly, -1, time.Time{}) + a.Attributes["plan_type"] = "plus" + b := planAuth("b", "codex", "plus", observed, weekly, -1, time.Time{}) + setPlanRouting(t, map[string]map[string]float64{"codex": {"double": 2}}, nil) + b.Attributes["plan_type"] = "double" + fresh := &SoonestResetFirstSelector{now: func() time.Time { return now }} + var sequence string + for range 6 { + got, err := fresh.Pick(context.Background(), "codex", "gpt-5", cliproxyexecutor.Options{}, []*Auth{a, b}) + if err != nil { + t.Fatal(err) + } + sequence += got.ID + } + if sequence != "babbab" { + t.Fatalf("sequence = %s, want babbab", sequence) + } + + // Ranking still wins over weight: a sooner weekly reset takes every pick. + soon := planAuth("soon", "claude", "pro", observed, now.Add(time.Hour), -1, time.Time{}) + if got := countPicks(t, selector, "claude", "claude-sonnet-5", []*Auth{max20, soon}, 5); got["soon"] != 5 { + t.Fatalf("ranked picks = %v, want soon:5", got) + } + + // Probes and pools without quota reports are spread by weight too. + probeSmall := &Auth{ID: "probe-small", Provider: "codex", Attributes: map[string]string{"plan_type": "plus"}} + probeBig := &Auth{ID: "probe-big", Provider: "codex", Attributes: map[string]string{"plan_type": "prolite"}} + if got := countPicks(t, selector, "codex", "gpt-5", []*Auth{probeSmall, probeBig}, 6); got["probe-small"] != 1 || got["probe-big"] != 5 { + t.Fatalf("probe picks = %v, want probe-small:1 probe-big:5", got) + } + grokA := &Auth{ID: "grok-a", Provider: "grok"} + grokB := &Auth{ID: "grok-b", Provider: "grok"} + if got := countPicks(t, selector, "grok", "grok-4", []*Auth{grokA, grokB}, 4); got["grok-a"] != 2 || got["grok-b"] != 2 { + t.Fatalf("unranked picks = %v, want round-robin", got) + } +} + +func TestSoonestResetFirstPlanHeadroomGuard(t *testing.T) { + now := time.Unix(1_800_000_000, 0) + observed := now.Add(-time.Minute) + weekly := now.Add(2 * 24 * time.Hour) + fiveHour := now.Add(2 * time.Hour) + const model = "claude-sonnet-5" + tests := []struct { + name string + provider string + reserve *float64 + auths func() []*Auth + want map[string]int // exact counts over 4 picks + }{ + { + name: "tight pro skipped for a roomy pro", provider: "claude", + auths: func() []*Auth { + return []*Auth{ + planAuth("a", "claude", "pro", observed, weekly, 95, fiveHour), + planAuth("b", "claude", "pro", observed, weekly, 50, fiveHour), + } + }, + want: map[string]int{"b": 4}, + }, + { + name: "tight account skipped even with the soonest weekly reset", provider: "claude", + auths: func() []*Auth { + return []*Auth{ + planAuth("a", "claude", "pro", observed, now.Add(time.Hour), 95, fiveHour), + planAuth("b", "claude", "pro", observed, weekly, 50, fiveHour), + } + }, + want: map[string]int{"b": 4}, + }, + { + name: "same percent left is tight on pro but not on max 20x", provider: "claude", + auths: func() []*Auth { + return []*Auth{ + // Pro with 5% left has headroom 5; Max 20x with 3% left has 60. + planAuth("a", "claude", "pro", observed, now.Add(time.Hour), 95, fiveHour), + planAuth("b", "claude", "max_20x", observed, weekly, 97, fiveHour), + } + }, + want: map[string]int{"b": 4}, + }, + { + name: "every account tight keeps ranking", provider: "claude", + auths: func() []*Auth { + return []*Auth{ + planAuth("a", "claude", "pro", observed, now.Add(time.Hour), 95, fiveHour), + planAuth("b", "claude", "pro", observed, weekly, 99, fiveHour), + } + }, + want: map[string]int{"a": 4}, + }, + { + name: "zero reserve disables the guard", provider: "claude", reserve: new(0.0), + auths: func() []*Auth { + return []*Auth{ + planAuth("a", "claude", "pro", observed, weekly, 95, fiveHour), + planAuth("b", "claude", "pro", observed, weekly, 50, fiveHour), + } + }, + want: map[string]int{"a": 2, "b": 2}, + }, + { + name: "reading whose window already reset is ignored", provider: "claude", + auths: func() []*Auth { + return []*Auth{ + planAuth("a", "claude", "pro", observed.Add(-3*time.Hour), weekly, 95, now.Add(-time.Minute)), + planAuth("b", "claude", "pro", observed, weekly, 50, fiveHour), + } + }, + want: map[string]int{"a": 2, "b": 2}, + }, + { + name: "codex primary 5-hour window", provider: "codex", + auths: func() []*Auth { + return []*Auth{ + planAuth("a", "codex", "plus", observed, weekly, 95, fiveHour), + planAuth("b", "codex", "plus", observed, weekly, 10, fiveHour), + } + }, + want: map[string]int{"b": 4}, + }, + { + name: "codex pro tolerates a low percent", provider: "codex", + auths: func() []*Auth { + return []*Auth{ + // Pro (weight 6) with 5% left has headroom 30. + planAuth("a", "codex", "pro", observed, now.Add(time.Hour), 95, fiveHour), + planAuth("b", "codex", "plus", observed, weekly, 10, fiveHour), + } + }, + want: map[string]int{"a": 4}, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + setPlanRouting(t, nil, tt.reserve) + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + got := countPicks(t, selector, tt.provider, model, tt.auths(), 4) + if fmt.Sprint(got) != fmt.Sprint(tt.want) { + t.Fatalf("picks = %v, want %v", got, tt.want) + } + }) + } +} + +func TestShortWindowUsageReadingFeedsHeadroomGuard(t *testing.T) { + setPlanRouting(t, nil, nil) + now := time.Unix(1_800_000_000, 0) + weekly := now.Add(2 * 24 * time.Hour) + // Header readings say both accounts are roomy; a newer usage-endpoint reading + // says a is nearly spent. + a := planAuth("headroom-usage-a", "claude", "pro", now.Add(-time.Hour), weekly, 20, now.Add(time.Hour)) + b := planAuth("headroom-usage-b", "claude", "pro", now.Add(-time.Hour), weekly, 20, now.Add(time.Hour)) + t.Cleanup(func() { ForgetShortWindowUsage(a.ID) }) + ObserveShortWindowUsage(a.ID, now.Add(-time.Minute), 97, now.Add(time.Hour)) + // An older reading never replaces a newer one. + ObserveShortWindowUsage(a.ID, now.Add(-2*time.Hour), 0, now.Add(time.Hour)) + selector := &SoonestResetFirstSelector{now: func() time.Time { return now }} + if got := countPicks(t, selector, "claude", "claude-sonnet-5", []*Auth{a, b}, 3); got[b.ID] != 3 { + t.Fatalf("picks = %v, want only %s", got, b.ID) + } +} + +// The headroom guard only shapes new conversations: a bound conversation stays +// on its account when that account becomes tight. +func TestPlanHeadroomGuardKeepsBoundConversations(t *testing.T) { + setPlanRouting(t, nil, nil) + const model = "claude-sonnet-5" + now := time.Now() + weekly := now.Add(2 * 24 * time.Hour) + a := planAuth("a", "claude", "pro", now.Add(-time.Minute), now.Add(24*time.Hour), 10, now.Add(time.Hour)) + b := planAuth("b", "claude", "pro", now.Add(-time.Minute), weekly, 10, now.Add(time.Hour)) + auths := []*Auth{a, b} + selector := NewSessionAffinitySelectorWithConfig(SessionAffinityConfig{Fallback: &SoonestResetFirstSelector{}, TTL: time.Hour}) + t.Cleanup(selector.Stop) + session := cliproxyexecutor.Options{Headers: map[string][]string{"X-Session-Id": {"plan-headroom-bound"}}} + other := cliproxyexecutor.Options{Headers: map[string][]string{"X-Session-Id": {"plan-headroom-new"}}} + pick := func(opts cliproxyexecutor.Options, want, step string) { + t.Helper() + got, err := selector.Pick(context.Background(), "claude", model, opts, auths) + if err != nil || got == nil || got.ID != want { + t.Fatalf("%s: Pick() = %v, %v; want %s", step, got, err, want) + } + } + pick(session, "a", "new conversation binds to the soonest reset") + a.Quota.Signals["Anthropic-Ratelimit-Unified-5h-Utilization"] = "0.96" + pick(other, "b", "a new conversation avoids the tight account") + pick(session, "a", "the bound conversation is not moved") +} diff --git a/sdk/cliproxy/auth/selector_reset_scoped.go b/sdk/cliproxy/auth/selector_reset_scoped.go index ff49878bc28..8cac6267bee 100644 --- a/sdk/cliproxy/auth/selector_reset_scoped.go +++ b/sdk/cliproxy/auth/selector_reset_scoped.go @@ -74,6 +74,8 @@ type scopedWeeklyState struct { exhausted bool reset time.Time observedAt time.Time + // scoped marks a cap that governs only some models. + scoped bool } // modelScopeTokens splits a model ID into lower-case alphanumeric tokens. diff --git a/sdk/cliproxy/builder.go b/sdk/cliproxy/builder.go index e25feb954cb..8db6d1d8eab 100644 --- a/sdk/cliproxy/builder.go +++ b/sdk/cliproxy/builder.go @@ -230,6 +230,9 @@ func (b *Builder) Build() (*Service, error) { if errValidate := b.cfg.ValidateCredentialWeights(); errValidate != nil { return nil, fmt.Errorf("cliproxy: validate credential weights: %w", errValidate) } + if errValidate := b.cfg.ValidatePlanRouting(); errValidate != nil { + return nil, fmt.Errorf("cliproxy: validate plan routing: %w", errValidate) + } b.cfg.NormalizePluginsConfig() if errResolvePluginsDir := b.cfg.ResolvePluginsDir(); errResolvePluginsDir != nil && b.cfg.Plugins.Enabled { return nil, fmt.Errorf("cliproxy: %w", errResolvePluginsDir) diff --git a/sdk/cliproxy/executor/types.go b/sdk/cliproxy/executor/types.go index d34a17a16aa..f12ec7eab33 100644 --- a/sdk/cliproxy/executor/types.go +++ b/sdk/cliproxy/executor/types.go @@ -34,6 +34,8 @@ const GenerateMetadataKey = "generate" const ( // PinnedAuthMetadataKey locks execution to a specific auth ID. PinnedAuthMetadataKey = "pinned_auth_id" + // ExcludedAuthIDsMetadataKey excludes specific auth IDs from selection for the current attempt. + ExcludedAuthIDsMetadataKey = "excluded_auth_ids" // SelectionIDMetadataKey stores the per-selection ID generated for a plugin scheduler pick. SelectionIDMetadataKey = "selection_id" // SelectedAuthMetadataKey stores the auth ID selected by the scheduler. diff --git a/sdk/cliproxy/service_config.go b/sdk/cliproxy/service_config.go index 433bf3ff394..6dd2bda9821 100644 --- a/sdk/cliproxy/service_config.go +++ b/sdk/cliproxy/service_config.go @@ -168,6 +168,10 @@ func (s *Service) commitConfigUpdate(newCfg *config.Config) configCommit { log.WithError(errValidate).Warn("rejected config update with invalid credential weights") return configCommit{} } + if errValidate := newCfg.ValidatePlanRouting(); errValidate != nil { + log.WithError(errValidate).Warn("rejected config update with invalid plan routing") + return configCommit{} + } if errValidate := newCfg.Models.Validate(); errValidate != nil { log.WithError(errValidate).Warn("rejected invalid model catalog sources") diff --git a/web/DESIGN.md b/web/DESIGN.md index 748749ce777..8cc32dae1b3 100644 --- a/web/DESIGN.md +++ b/web/DESIGN.md @@ -100,7 +100,7 @@ lift. `prefers-reduced-motion` turns animation off globally (`global.scss`). | Toast | `showNotification('Saved', 'success')` from `useNotificationStore` | | `Table` (+ `TableHeader/Body/Row/Head/Cell`) | `......
` | | `Skeleton` | `` | -| `EmptyState` | `Add account} />` | +| `EmptyState` | `Add account} />` | | `Spinner` (`LoadingSpinner`) | `` | | `PageHeader` | see below | | `Toolbar` | `}>` | @@ -128,7 +128,7 @@ no top bar on desktop and no floating toolbar: page actions belong in `PageHeade <> 12} actions={} tabs={} diff --git a/web/index.html b/web/index.html index 24d2abec4e4..996cf7006de 100644 --- a/web/index.html +++ b/web/index.html @@ -7,7 +7,7 @@ - + t3code-proxy