Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.
routes: each provider's wallets go by what they have left in a group too (#4095)
yetonee5e2aa58e5e9
diff --git a/docs/subsystems/gateway-routing.md b/docs/subsystems/gateway-routing.mdindex 6cb252a50..f89f16f68 100644--- a/docs/subsystems/gateway-routing.md+++ b/docs/subsystems/gateway-routing.md@@ -33,7 +33,7 @@ backfilled; see [Gateway Session Aggregation](gateway-sessions.md).| Model resolution | `serve` resolves the model the agent asked for: Claude tier stand-ins, a routing group (`provider.GroupFor`: its id, the model's id however a vendor spells it, else the one group whose name it is, unless a provider serves a model by that id; the user's own groups only while the `groups` plugin is on, [the plugin runtime](plugin-runtime.md#gateway-extension-points-p3-router-strategy)), auto stand-ins, the agent's own stand-in (`StandIn`: Codex's config.toml `model` when magpie is its provider — in a WSL distro, the distro's own, of the ones running now — for a name it sends that magpie doesn't serve, such as its auto-review's `codex-auto-review`), itself taken through `GroupFor` and auto stand-ins so a config naming a group bare reaches it, then `provider.Resolve`. A Codex memory call or auto-review (`x-openai-subagent: guardian`, or `codex-auto-review`) that still names no served model goes to the model Codex's last turn was answered on (`codexMemoryStandIn`, per agent and gateway key; a memory call first waits beside the turn it was started with, through `codexLeads`, see the side turns below), so a Codex on magpie through another provider table, a profile or another computer isn't answered 404 (Adam on Discord, `TestCodexAutoReviewReachesItsTurnsModel`). A bare model id several providers serve (MOMO on Discord: `glm-5.3` under opencode-go and a6api) is never refused: with found groups on (the default) `GroupFor` takes it to the group magpie found for it (`auto-<slug>`), its members in the Providers order, routed and failed over as any group, a conversation staying with the member that answered it while its cache is worth it (affinity); with them off, `Resolve` takes the first provider in the Providers order that exposes it, with no fallback. magpie writes only `provider/model` ids into agents' configs (`magpieModels`), so a bare id is one the user wrote. `/v1/models` lists bare ids only when the user asks for them ([Model ids without the provider](#model-ids-without-the-provider)). Every reply says who answered in `X-Magpie-Provider` and `X-Magpie-Model` (`noteMember`), and the usage log and the Routing page keep it. A model id with `~` and no slash that resolves as nothing else is the one served id (a provider's model or a group) whose slashes it spells as `~` (`unflat`, `provider.Unflat`; MiniMax Code's spelling, #1387), taken back in `validateModel` before key limits, middleware and usage see it; two ids spelled alike are neither. A Claude model id whose version is dashed (`relay/claude-opus-4-6-us`, with or without `:level` and `[1m]`) that is not served as spelled is the one served id it dashes (`provider.ClaudeUndashed`; the spelling magpie gives Claude Code, which reads a dotted version as Claude Opus 4), taken back in `validateModel` and `unprefixed` the same way. An unknown model gets a 404 naming why: a switched-off provider, a disabled group or an empty group. Otherwise it names up to three ids nearest to what was asked (`provider.Closest`: words of a model's display name count before words of its id, and a provider's id or name only alongside them, so "Zen-Space-Bunny" is told `opencode-zen-free/space-bunny-free`, MOMO on Discord), then the ways a model can be named, then every id (`unknownModel`; chat and embeddings). | [`gateway.go`](../../internal/gateway/gateway.go), [`internal/provider/group.go`](../../internal/provider/group.go), [`internal/provider/flat.go`](../../internal/provider/flat.go), [`internal/provider/claudedash.go`](../../internal/provider/claudedash.go) || A found group's two ids | A group magpie found is listed (`/v1/models`, the catalog, the lists written into agents, the pickers, the CLI and TUI) as `auto/<model>`: the model's id as a vendor spells it, dots kept and with no vendor prefix (`auto/claude-opus-5.5`; `provider.Group.Ref`, `spelledIn`, preferring a spelling models.dev lists), so a client that looks the part after the slash up on models.dev finds it (ZeroClover on X). Its old id `group/auto-<slug>` is served forever. Inside magpie the group keeps that one id: `validateModel` takes `auto/<model>` (with `:level` or `[1m]`) back to it with `provider.CanonicalRef` before key limits, routing, affinity and the usage log see the request, and the request body is rewritten to it, so both ids count as one group. A gateway key naming either id, `group/*` or `auto/*` passes for both (`allows` in `key_models.go`). `SaveGroup` stores a member, rule or classifier picked as `auto/<model>` by the old id. An agent field magpie set to `group/auto-<slug>` moves to `auto/<model>` on the next `SyncCatalog` (`agent.renameFoundGroups`), but only while its value is still what applied.json says magpie wrote; a value the user set or changed stays. A pick of the group by its old id written now (`Agent.Apply`) is written as `auto/<model>`. An agent's hidden, picked and ordered models saved by the old id hold for the new one (`PublicRef` in `visible.go`), and a bare model id still reaches its found group (`bareTarget`). Claude Code is given a dotted Claude version dashed, so it may send `auto/claude-sonnet-4-5`: that is the same group, and `Reseat` still moves an agent off it once the group is gone (`samePick`). `auto` is no provider id: `Save` and `Rename` refuse it for a new provider, and a plugin's `auto` is `auto-plugin` (`PluginID`). A provider of the user's saved as `auto` before keeps its models: while it exists, `auto/<x>` is its model and found groups list as `group/auto-<slug>` (`autoRefsOn`). Hand-made groups stay `group/<id>`. | [`internal/provider/autoref.go`](../../internal/provider/autoref.go), [`key_models.go`](../../internal/gateway/key_models.go), [`internal/agent/autoref.go`](../../internal/agent/autoref.go) || Candidates | `plan` lists one provider's candidates: one per key or account on, then each `Fallback` model, with resting ones last (`restLast`). A fallback the user unchecked in its own provider's model list is skipped, as a group's member is (`provider.ResolveRoute`, #3911; `fallback_unpicked_test.go`), and so is it where fallbacks are read for careful accounts, native compaction, redaction and Codex's own turns. `planGroup` and `planLevel` weigh a group's members together. A nested group plans by its own routing (#576); one left on the default (Smart) in a group that pools (Smart, In turn, Least used, Weekly pace, Free first, Speed first, a plugin's) takes the outer group's, as a provider left on the default does (`provider.Group.Within`, set on `Member.Via`, so the trace's `Subs` and the Routing page read the routing that applies, #3847). In a group In order, By weight or Manual it stays Smart. `TestFreeFirstReachesAGroupInItLeftOnTheDefault`. So does a member whose provider routes other than Smart (`ownRouting`): weighed as one by its first not resting (`firstAwake`), tried whole in its own order; `leastHeld` leaves such a group's order alone too. A provider on Smart, or routed as the group is, is pooled with the group's other keys and accounts. `group_own_routing_test.go`. A member's own fallbacks are not the group's. | [`fallback.go`](../../internal/gateway/fallback.go) |-| Order of keys and accounts | `Routing`: smart (""), `order`, `rotate`, `usage` (least used, with an `usageHalfLife` of 1h), `pace`, `weight`, `free` (free first) or `fast` (speed first). `weighRouted` reads each candidate into a `routes.Seat` and asks the strategy serving its routing (`routes.Find`, the router strategy point of [the plugin runtime](plugin-runtime.md#gateway-extension-points-p3-router-strategy)) for the order: Smart is `routes.Smart`, the core's; the others are `routes.Builtin`, registered by the built-in plugin `rotation`. With it off a routing no strategy serves is tried in its listed order, and `routingOf` treats it as `order` wherever the core asks about a routing (a turn's mark, `goesRound`, `sinks`, a rotate group's sessions, a group's heads). Smart, `usage` and `pace` weigh a subscription by its allowance (`allowances`), and a key by its own usage windows when magpie reads them (`keyAllowance`: a sub2api key given a 5-hour, day or 7-day limit, or a key bought as a plan, such as Kimi Code's or a GLM Coding Plan's); any other key has none. Among accounts a plugin reads as prepaid wallets (a window's `balance`, #3950), Smart, `usage` and `pace` put the one with more left first where they would otherwise tie, only within one provider and unit (`routes.Seat.Left`/`LeftIn`, see [provider plugins](provider-plugins.md#a-wallets-balance)). `free` weighs by what a model costs there and nothing else: only a strategy with `routes.Strategy.ByFree` set (`routes.FreeFirst` is the one) has `weighRouted` fill `routes.Seat.Free`, from `provider.FreeModel` — the vendor's own `catalog.Model.Free` word, else a list price of $0 on every count — so a pool routed any other way never reads a model list for it, and one routed `free` spends the members whose model costs nothing before those that spend the allowance or credits, each tier in its listed order (nothing free is left behind a paid one, and a pool with no free model behaves as `order`). A group routed `free` weighs its members whole, each over its own accounts or keys as its provider routes them. `fast` weighs by speed lately and nothing else: only a strategy with `routes.Strategy.BySpeed` set (`routes.Fastest`) has `weighRouted` fill `routes.Seat.TTFT` and `TPS`, from `speedOf` ([`speed.go`](../../internal/gateway/speed.go)): per `restID` (account or key, and model), a decayed average (half-life 20m) of a streamed answer's ms to its first content and of its output tokens a second as `usage.DecodeOf` counts them, written once as an answer ends (`noteTrySpeed`, beside `servedCandidate`) and read with one map lookup per candidate, never from the usage history; past an hour since its last answer a seat counts as not measured, the records are capped at 4096, and a restart forgets them. `routes.Fastest` ranks the awake by their first token plus 200 tokens at their pace (a seat with no pace at the measured seats' middle pace), keeps seats within a tenth of their band's fastest in listed order, and of a pool's requests with seats both measured and not, gives every fifth to one not measured (round the unmeasured, `probes`, so one is never starved); resting seats go after the awake, used-up ones (`UsedShare`) after those, and rests and failover are as for any routing. The trace's rows carry `lateTtft`/`lateTps` for the Routing page's story ("answered fastest lately — first token in 0.8s"). A non-streamed reply tells nothing (no first token), so a pool that never streams stays in listed order bar the probes. A group routed `weight` (#1910) takes its members, not their keys, by smooth weighted round robin: `planLevel` makes each model member (its keys ordered by its own provider's routing) and each nested group one unit, and `weightedUnits` puts the round's pick (`routes.Round` over `group/<id>`, keyed by the member's spelling, `Group.Weights`, 1 if unset) first and the rest in member order for failover; a unit whose head rests leaves the round, while one whose accounts are only near their limit (Smart's 90% band, not resting) keeps its share, the band ordering only its own accounts (`TestWeightedGroupGivesALowGroupItsShare`; Creat.wu on Discord read the Routing page's "kept for when the others can't" as the member passed over, so the page now tells a member behind another by a group's weights or order as such, `memberSplit` in the routing plugin's `client.js`), and a kept conversation moves the round's charge to the member that kept it (`wrrSeat`, `routes.MoveRound`). A lone key or account is weighed against nobody, but what it has left is still read into the trace (`weighRouted`), so the Routing page shows it as it does for several (#1016); all but used up, it keeps its conversation rather than being said to move (`affine`). A failure rests a candidate (`failure`, `failureOf`). | [`routing.go`](../../internal/gateway/routing.go), [`weighted.go`](../../internal/gateway/weighted.go), [`internal/routes/`](../../internal/routes), [`internal/provider/routing.go`](../../internal/provider/routing.go) |+| Order of keys and accounts | `Routing`: smart (""), `order`, `rotate`, `usage` (least used, with an `usageHalfLife` of 1h), `pace`, `weight`, `free` (free first) or `fast` (speed first). `weighRouted` reads each candidate into a `routes.Seat` and asks the strategy serving its routing (`routes.Find`, the router strategy point of [the plugin runtime](plugin-runtime.md#gateway-extension-points-p3-router-strategy)) for the order: Smart is `routes.Smart`, the core's; the others are `routes.Builtin`, registered by the built-in plugin `rotation`. With it off a routing no strategy serves is tried in its listed order, and `routingOf` treats it as `order` wherever the core asks about a routing (a turn's mark, `goesRound`, `sinks`, a rotate group's sessions, a group's heads). Smart, `usage` and `pace` weigh a subscription by its allowance (`allowances`), and a key by its own usage windows when magpie reads them (`keyAllowance`: a sub2api key given a 5-hour, day or 7-day limit, or a key bought as a plan, such as Kimi Code's or a GLM Coding Plan's); any other key has none. Among accounts a plugin reads as prepaid wallets (a window's `balance`, #3950), Smart, `usage` and `pace` put the one with more left first where they would otherwise tie, only within one provider and unit (`routes.Seat.Left`/`LeftIn`, see [provider plugins](provider-plugins.md#a-wallets-balance)): each kind is ordered in the places its own seats take, so a group weighing several providers' accounts as one pool orders each provider's wallets too (#4095, `TestGroupWalletsGoByWhatTheyHaveLeft`). `free` weighs by what a model costs there and nothing else: only a strategy with `routes.Strategy.ByFree` set (`routes.FreeFirst` is the one) has `weighRouted` fill `routes.Seat.Free`, from `provider.FreeModel` — the vendor's own `catalog.Model.Free` word, else a list price of $0 on every count — so a pool routed any other way never reads a model list for it, and one routed `free` spends the members whose model costs nothing before those that spend the allowance or credits, each tier in its listed order (nothing free is left behind a paid one, and a pool with no free model behaves as `order`). A group routed `free` weighs its members whole, each over its own accounts or keys as its provider routes them. `fast` weighs by speed lately and nothing else: only a strategy with `routes.Strategy.BySpeed` set (`routes.Fastest`) has `weighRouted` fill `routes.Seat.TTFT` and `TPS`, from `speedOf` ([`speed.go`](../../internal/gateway/speed.go)): per `restID` (account or key, and model), a decayed average (half-life 20m) of a streamed answer's ms to its first content and of its output tokens a second as `usage.DecodeOf` counts them, written once as an answer ends (`noteTrySpeed`, beside `servedCandidate`) and read with one map lookup per candidate, never from the usage history; past an hour since its last answer a seat counts as not measured, the records are capped at 4096, and a restart forgets them. `routes.Fastest` ranks the awake by their first token plus 200 tokens at their pace (a seat with no pace at the measured seats' middle pace), keeps seats within a tenth of their band's fastest in listed order, and of a pool's requests with seats both measured and not, gives every fifth to one not measured (round the unmeasured, `probes`, so one is never starved); resting seats go after the awake, used-up ones (`UsedShare`) after those, and rests and failover are as for any routing. The trace's rows carry `lateTtft`/`lateTps` for the Routing page's story ("answered fastest lately — first token in 0.8s"). A non-streamed reply tells nothing (no first token), so a pool that never streams stays in listed order bar the probes. A group routed `weight` (#1910) takes its members, not their keys, by smooth weighted round robin: `planLevel` makes each model member (its keys ordered by its own provider's routing) and each nested group one unit, and `weightedUnits` puts the round's pick (`routes.Round` over `group/<id>`, keyed by the member's spelling, `Group.Weights`, 1 if unset) first and the rest in member order for failover; a unit whose head rests leaves the round, while one whose accounts are only near their limit (Smart's 90% band, not resting) keeps its share, the band ordering only its own accounts (`TestWeightedGroupGivesALowGroupItsShare`; Creat.wu on Discord read the Routing page's "kept for when the others can't" as the member passed over, so the page now tells a member behind another by a group's weights or order as such, `memberSplit` in the routing plugin's `client.js`), and a kept conversation moves the round's charge to the member that kept it (`wrrSeat`, `routes.MoveRound`). A lone key or account is weighed against nobody, but what it has left is still read into the trace (`weighRouted`), so the Routing page shows it as it does for several (#1016); all but used up, it keeps its conversation rather than being said to move (`affine`). A failure rests a candidate (`failure`, `failureOf`). | [`routing.go`](../../internal/gateway/routing.go), [`weighted.go`](../../internal/gateway/weighted.go), [`internal/routes/`](../../internal/routes), [`internal/provider/routing.go`](../../internal/provider/routing.go) || Limits | Each key or account (a candidate's `who()`) has at most `MaxConcurrency` requests out at once (its own `AccountConcurrency` over it); one more waits in its lane's queue, bounded by `QueueLimit` and `QueueWait` and turned away with a 429 past either (`lanes.take`). `MaxRPM` (coeo91 on Discord: OpenRouter's free models take 20 a minute) bounds how many requests it sends the vendor in any rolling 60 seconds (`rpms`), counting each for a second more (`rpmSlack`), since the vendor counts a request when it arrives and the first on a new connection arrives later by its dial: one more waits for room in the minute, in the order they came, after it has its slot and right before it is sent. A wait that would be longer than 2 minutes (or the provider's `QueueWait`, when shorter: `rpmWait`) is turned away at once with a 429 whose `Retry-After` is when the minute has room; nothing rests for it. An agent gone while it waits gives its place back. Every request that reaches the vendor counts: each try of the candidate loop (a retry, the next key, a fallback) waits in `serve`, and the requests a try makes on the way and the gateway's own asks (count_tokens, System One's decisions, embeddings, drawing, Kimi's search) are counted by `rpmTransport` on `s.client` (`metered`, `paidFor`). count_tokens never waits: a candidate with no room is skipped, and the local estimate answers. A full lane or a minute with no room gives way to a ready key or account of the provider or the group (`laneMate`, `ready`); a fallback is never asked for want of either. A plugin's account sends through its own transport, so only its tries are counted, not a plugin's own extra requests. Set in the provider editor (Concurrency, Requests per minute, Queue size, Queue wait) or with `magpie provider account-concurrency`, `queue` and `rpm`; a subscription's are kept with its picks, and every account of it keeps them, those on beside the first as well (`withPicks`, called by `All` and `AlsoOn`; #1899: a second WorkBuddy AI account had none, and queued 62s with the wait set to 1s). | [`concurrency.go`](../../internal/gateway/concurrency.go), [`rpm.go`](../../internal/gateway/rpm.go), [`internal/provider/concurrency.go`](../../internal/provider/concurrency.go) || Sink | With `Sink` on, a key or account that answers 429 while it still has quota goes to the back, behind every one not rate limited since. Held in memory until restart, or until its rest is lifted by hand (Try now, `Unrest` calls `unsink`, `UnrestAll` `unsinkAll` for the key and each of its models), which puts it back in its place (`TestTryNowPutsASunkAccountBack`, `TestUnrestAllUnsinksTheModels`). Another magpie's model rate limited there, whose rest is the model's alone (`remoteModelRest`), sinks alone too (`restID`), and `sunkAt` reads a candidate's model before its key, so the remote's other models keep their place (#2167, ggbdpq; `TestRemoteMagpieRateLimitSinksTheModel`, `TestMagpieAddedByHandRateLimitSinksTheModel`). A group in a group sinks by its own Sink, within its own order (`sinkOwn`, #2255), and the group asked for then sinks the whole by its own; `TestNestedGroupSinksItsOwnOrder`. | [`sink.go`](../../internal/gateway/sink.go) || Image generation | `/v1/images/generations` and `/v1/images/edits` are translated to the selected model's image API. OpenRouter image-only models use its `/images` endpoint and send reference images as `input_references`; OpenRouter models that return images through chat stay on Chat Completions. Volcengine Ark (`isArk`: an `ark.*.volces.com` base, the preset's plans or one added by hand) is asked at `/images/generations` only, as its doc (https://www.volcengine.com/docs/82379/1541523) takes it (`drawArk`): `watermark: false`, since it marks every image otherwise; reference images as JSON `image` (a URL or data URL, an array for several), never a multipart edit; no `n`, so one request per image (`eachDrawing`); no ratio as `size`, so a ratio its doc lists is sent as that ratio's 2K size and any other is a 400 that says to put it in the prompt; no mask, no quality (JL on Discord, `TestArkDrawsWithoutWatermarkOncePerImage`). A routing group named for a drawing or a video (`drawingGroup`: `group/<id>`, or a bare id the group goes by that resolved to one of its members) is tried member by member in the order its routing plans for a chat (`drawingTries` over `planGroup`), each member over its own keys or accounts (`drawOnAccounts`, `startVideo`); the next member is asked while one fails as a chat's would move on (`retryable`: its vendor 5xx, out of quota, the model not served), never for a refusal of the request itself, and the call's `Fallback` names those tried first (#2005, tianxia3111: a group of two relays answered the first one's 502). Pause rules and a gateway key's group hold apply as for a chat. A failed drawing rests no member and no key. An account out of quota for the image model (`failure` reads `failQuota`) rests that model on it alone (`restDrawer`, keyed by `restID`), until the reset its refusal names (`resetsAt`: Antigravity's "Your quota will reset after 3h19m30s.") or `quotaRest`, so the next drawing asks the accounts that still have it first (`restLast`), and the account's text models stay in. Antigravity also tells a model's quota used up as a 200 whose stream is the error; `drawCodeAssist` gives such an error the status its words stand for (`saidStatus`: quota or rate 429, credit 402, else 502), as the images API's 200 with no image does, so a spent account hands the drawing to the next one as its 429 does (01huadalang on Discord: a 502 ended the drawing on the spent account; `TestAntigravityDrawingOutOfQuotaInsideTheReplyGoesOn`, `TestAntigravityDrawingQuotaRestsTheImageModel`). `TestImageGroupMovesOnToTheNextMember`, `TestVideoGroupMovesOnToTheNextMember`. An account's own list of models (#474) never bars a ChatGPT account's GPT Image, a Grok subscription's Grok Imagine or a WorkBuddy plan's image models (`listsCantName`): the list is picked from the editor's chat models, which they are never among, so a list kept for some chat models had every drawing refused as "set not to be served by any account" (heyiwei5 on X). A key's list, picked from models that include its image ones, still bars them. `TestCodexDrawsPastAccountModelLists`. A drawing is given Settings → Images → Image generation timeout (`imageTimeout`, 1 to 60 minutes, 5 when unset; neighbads on X: a slow image endpoint needed more) as its context's deadline (`drawTimeout`, `drawWithin`), and so is downloading an image answered as a link (`imageLongest`, never under `ImageLongest`). A drawing's request goes through a transport with no `ResponseHeaderTimeout` (`drawsApart`), since an images API sends its headers only once it has drawn, and every other request keeps `upstreamHeaderWait` (10 minutes). A video's submit, status and download calls keep 5 minutes each (`videoTimeout`). The `magpie mcp image` process, which may not read these settings (WSL), waits on a call up to `callLongest` (two hours and a minute), so it never cuts one the gateway still waits on. `TestLongImageTimeoutLetsASlowVendorFinish`, `TestImageTimeoutSettingReachesTheVendor`, `TestOnlyDrawingsWaitPastTheHeaderWait`. | [`draw.go`](../../internal/gateway/draw.go), [`draw_volcengine.go`](../../internal/gateway/draw_volcengine.go), [`video.go`](../../internal/gateway/video.go), [`catalog.go`](../../internal/catalog/catalog.go) |diff --git a/docs/subsystems/provider-plugins.md b/docs/subsystems/provider-plugins.mdindex 17bc8c960..86289c82f 100644--- a/docs/subsystems/provider-plugins.md+++ b/docs/subsystems/provider-plugins.md@@ -46,7 +46,7 @@ A window that leaves out `used` but tells its count, `amount` of `limit` with bo## A wallet's balance-A prepaid wallet (SuperMagic's points, [#3950](https://github.com/yetone/magpie/issues/3950)) has a balance and nothing it is a share of. A usage window may send `balance` (a number, in `unit`) and leave out `used`, `limit` and `aside`: `{name: "积分", balance: 6291, unit: "积分"}`. The host passes a finite number on, at least 0, and anything else as `null` (`usageOf` in [`host.js`](../../internal/plugin/host.js)); `plugin.UsageWindow.Balance` and `provider.QuotaWindow.Balance` are `*float64`. [`quotaOfPlugin`](../../internal/provider/plugin_usage.go) keeps the figure and does not make the window `Text` or `Aside`, so the account is known to routing with no `Used` invented. `allowanceOf` copies it into `Limit.Balance`, and an empty wallet (0) counts as used up. `Allowance.Left(model)` is the least balance of the windows that count the model, with its unit. `weighRouted` sets `routes.Seat.Left` to it and `Seat.LeftIn` to the account's provider and unit; Smart, `pace` and `usage` put the seat with more left first where they would otherwise tie (`byLeft` in [`strategies.go`](../../internal/routes/strategies.go)), and only when every seat that has a balance shares one `LeftIn`, so balances in two units or two providers are never weighed against each other. The card, the Routing page (`Weighed.Balance`) and the CLI show the figure ("6,291 积分 left", `provider.BalanceText`) and no meter. A wallet window's `runsOutAt`/`runsOut` (its soonest batch to lapse) and the rows set aside after it (`aside` text: SuperMagic's day's, timed and permanent points) are display only: the card says them, and the Routing page reads them from the same card (`cardOf` in the routing plugin's `client.js`, live requests only), its row saying the lapse after the figure ("6,291 积分 left · 185 积分 expire 23:59", `runsOutText`, #3964) and its tooltip and account list each window (`winsOf`). Routing goes by the balance alone. Tests: `TestPluginWalletBalanceIsAReading`, `TestPluginHostPassesABalanceOn`, `TestWalletsGoByWhatTheyHaveLeft`, `TestWalletWithMoreLeftGoesFirst`, `usage-wallet-balance.test.cjs`, `routing-wallet-balance.test.cjs`, `routing-wallet-lapse.test.cjs`.+A prepaid wallet (SuperMagic's points, [#3950](https://github.com/yetone/magpie/issues/3950)) has a balance and nothing it is a share of. A usage window may send `balance` (a number, in `unit`) and leave out `used`, `limit` and `aside`: `{name: "积分", balance: 6291, unit: "积分"}`. The host passes a finite number on, at least 0, and anything else as `null` (`usageOf` in [`host.js`](../../internal/plugin/host.js)); `plugin.UsageWindow.Balance` and `provider.QuotaWindow.Balance` are `*float64`. [`quotaOfPlugin`](../../internal/provider/plugin_usage.go) keeps the figure and does not make the window `Text` or `Aside`, so the account is known to routing with no `Used` invented. `allowanceOf` copies it into `Limit.Balance`, and an empty wallet (0) counts as used up. `Allowance.Left(model)` is the least balance of the windows that count the model, with its unit. `weighRouted` sets `routes.Seat.Left` to it and `Seat.LeftIn` to the account's provider and unit; Smart, `pace` and `usage` put the seat with more left first where they would otherwise tie (`byLeft` in [`strategies.go`](../../internal/routes/strategies.go)), and only among seats that share one `LeftIn`, so balances in two units or two providers are never weighed against each other: each kind is put in the places its own seats take (the pool's order, or what magpie sent each lately for `pace` and `usage`), and the other kinds keep theirs. Before, a pool with two kinds was weighed by no balance, so a group of SuperMagic's and WorkBuddy's accounts spent SuperMagic's smallest balances first (#4095). The card, the Routing page (`Weighed.Balance`) and the CLI show the figure ("6,291 积分 left", `provider.BalanceText`) and no meter. A wallet window's `runsOutAt`/`runsOut` (its soonest batch to lapse) and the rows set aside after it (`aside` text: SuperMagic's day's, timed and permanent points) are display only: the card says them, and the Routing page reads them from the same card (`cardOf` in the routing plugin's `client.js`, live requests only), its row saying the lapse after the figure ("6,291 积分 left · 185 积分 expire 23:59", `runsOutText`, #3964) and its tooltip and account list each window (`winsOf`). Routing goes by the balance alone. Tests: `TestPluginWalletBalanceIsAReading`, `TestPluginHostPassesABalanceOn`, `TestWalletsGoByWhatTheyHaveLeft`, `TestWalletsOfSeveralProvidersEachGoByWhatTheyHaveLeft`, `TestWalletWithMoreLeftGoesFirst`, `TestGroupWalletsGoByWhatTheyHaveLeft`, `usage-wallet-balance.test.cjs`, `routing-wallet-balance.test.cjs`, `routing-wallet-lapse.test.cjs`.## Cache a vendor doesn't countdiff --git a/internal/gateway/wallet_balance_test.go b/internal/gateway/wallet_balance_test.goindex 8e21349d0..916ce6fb6 100644--- a/internal/gateway/wallet_balance_test.go+++ b/internal/gateway/wallet_balance_test.go@@ -51,3 +51,34 @@ func TestWalletWithMoreLeftGoesFirst(t *testing.T) {}}}++// mycf_711 (#4095): the same SuperMagic accounts that go by their points+// asked directly went in their listed order in a group, which weighs the+// members' accounts as one pool beside WorkBuddy's credits: 282 points,+// then 119, then 6,635. In the group too SuperMagic's go by what they+// have left, and WorkBuddy's account keeps its place.+func TestGroupWalletsGoByWhatTheyHaveLeft(t *testing.T) {+ old := allowances+ defer func() { allowances = old }()+ share := map[string]provider.Allowance{}+ allowances = func(string) map[string]provider.Allowance { return share }+ wallet := func(left float64, unit string) provider.Allowance {+ return provider.Allowance{{Name: unit, Balance: &left, Unit: unit}}+ }+ share["181****632"], share["181****710"], share["189****051"] = wallet(282, "积分"), wallet(119, "积分"), wallet(6635, "积分")+ share["wb"] = wallet(50, "credits")+ acct := func(agent, user string) candidate {+ return candidate{p: provider.Provider{ID: agent, Account: &provider.Account{Agent: agent, User: user}}, model: "m", rest: agent + "#" + user}+ }+ for _, routing := range []string{"", provider.Pace, provider.LeastUsed} {+ g := provider.Provider{ID: provider.GroupPrefix + "deepseek-v4.1-flash1017", Routing: routing}+ got, _ := weigh(g, []candidate{acct("workbuddy", "wb"), acct("magicrew", "181****632"), acct("magicrew", "181****710"), acct("magicrew", "189****051")}, "", provider.Chat)+ var s []string+ for _, c := range got {+ s = append(s, c.p.Account.User)+ }+ if got, want := strings.Join(s, ","), "wb,189****051,181****632,181****710"; got != want {+ t.Errorf("%q: %s, want %s", routing, got, want)+ }+ }+}diff --git a/internal/routes/strategies.go b/internal/routes/strategies.goindex 4535a3f74..bf5c90ce1 100644--- a/internal/routes/strategies.go+++ b/internal/routes/strategies.go@@ -1,6 +1,7 @@package routesimport (+ "cmp""sort""sync""time"@@ -27,42 +28,62 @@ func tier(share float64) int {return 0}-// byLeft is how a pool's wallets go by what they have left (Seat.Left):-// the one with more first, a seat that told none after those that did.-// It orders only a pool whose balances are all in one provider's one unit;-// with two kinds, nothing is weighed by them (nil), since points and-// another vendor's points don't compare.-func byLeft(seats []Seat) func(a, b Seat) int {- in := ""- for _, s := range seats {- switch {- case s.LeftIn == "":- case in == "":- in = s.LeftIn- case in != s.LeftIn:- return nil+// byLeft is how a pool's wallets go by what they have left (Seat.Left),+// as a comparison of two seats by their index: of seats whose balance is+// in one provider's one unit (Seat.LeftIn), the one with more left first;+// a seat that told none after those that did. Points and another+// vendor's points don't compare, so each kind is ordered only within the+// places its own seats take: those places are the told seats' order by+// before (nil: the pool's own order), each kind's seats are put in its+// places by what they have left, and seats of two kinds keep before's+// order between them. Before, a pool with two kinds was weighed by+// nothing (nil), and a group of several providers' accounts spent the+// small balances first (#4095, mycf_711). Nil when no seat told one.+func byLeft(seats []Seat, before func(a, b Seat) bool) func(i, j int) int {+ var told []int+ for i, s := range seats {+ if s.LeftIn != "" {+ told = append(told, i)}}- if in == "" {+ if len(told) == 0 {return nil}- return func(a, b Seat) int {- ha, hb := a.LeftIn != "", b.LeftIn != ""- switch {- case ha != hb:- if ha {- return -1- }- return 1- case a.Left > b.Left:- return -1- case a.Left < b.Left:- return 1+ if before != nil {+ sort.SliceStable(told, func(a, b int) bool { return before(seats[told[a]], seats[told[b]]) })+ }+ place := make([]int, len(seats))+ for i := range place {+ place[i] = len(seats) // told none: after every one that did+ }+ var kinds []string+ places := map[string][]int{}+ for p, i := range told {+ in := seats[i].LeftIn+ if _, ok := places[in]; !ok {+ kinds = append(kinds, in)}- return 0+ places[in] = append(places[in], p)}+ for _, in := range kinds {+ ps := places[in]+ ids := make([]int, len(ps))+ for k, p := range ps {+ ids[k] = told[p]+ }+ sort.SliceStable(ids, func(a, b int) bool { return seats[ids[a]].Left > seats[ids[b]].Left })+ for k, p := range ps {+ place[ids[k]] = p+ }+ }+ return func(i, j int) int { return cmp.Compare(place[i], place[j]) }}+// fewerTokens is what Pace and LeastUsed go by after a wallet's balance:+// what magpie sent a seat lately, the least first. It sets the places+// wallets of two kinds keep between them (byLeft).+func fewerTokens(a, b Seat) bool { return a.Tokens < b.Tokens }+func identity(n int) []int {idx := make([]int, n)for i := range idx {@@ -96,7 +117,7 @@ func identity(n int) []int {// once: else, kept after those known, it would never answer and never be// known (Anthropic's usage endpoint can turn magpie away for hours).var Smart = Strategy{Order: func(_ string, seats []Seat) []int {- left := byLeft(seats)+ left := byLeft(seats, nil)var fine, low, spent []intfor i, s := range seats {switch tier(s.Used) {@@ -135,7 +156,7 @@ var Smart = Strategy{Order: func(_ string, seats []Seat) []int {x, y := a.Lapse.Truncate(time.Hour), b.Lapse.Truncate(time.Hour)if x.Equal(y) {// then a wallet with more left (#3950)- return left != nil && left(a, b) < 0+ return left != nil && left(fine[i], fine[j]) < 0}if x.IsZero() || y.IsZero() {return y.IsZero()@@ -180,7 +201,7 @@ var Rotate = Strategy{Order: func(pool string, seats []Seat) []int {// share, by what they have left first (Seat.Left). Of those all but used up, one that// goes on on its credits goes first (spentBefore).var LeastUsed = Strategy{ByUse: true, Order: func(_ string, seats []Seat) []int {- left := byLeft(seats)+ left := byLeft(seats, fewerTokens)idx := identity(len(seats))sort.SliceStable(idx, func(a, b int) bool {sa, sb := seats[idx[a]], seats[idx[b]]@@ -191,7 +212,7 @@ var LeastUsed = Strategy{ByUse: true, Order: func(_ string, seats []Seat) []intreturn sa.Used < sb.Used}if left != nil {- if c := left(sa, sb); c != 0 {+ if c := left(idx[a], idx[b]); c != 0 {return c < 0}}@@ -245,7 +266,7 @@ var Pace = Strategy{ByUse: true, Order: func(_ string, seats []Seat) []int {band[i] = band[byPace[k-1]]}}- left := byLeft(seats)+ left := byLeft(seats, fewerTokens)idx := identity(len(seats))sort.SliceStable(idx, func(a, b int) bool {sa, sb := seats[idx[a]], seats[idx[b]]@@ -264,7 +285,7 @@ var Pace = Strategy{ByUse: true, Order: func(_ string, seats []Seat) []int {} else if left != nil {// a wallet's pace is a whole week's; the one with more left// first (#3950)- if c := left(sa, sb); c != 0 {+ if c := left(idx[a], idx[b]); c != 0 {return c < 0}}diff --git a/internal/routes/wallet_test.go b/internal/routes/wallet_test.goindex 75374a5f5..c5ec4ccb8 100644--- a/internal/routes/wallet_test.go+++ b/internal/routes/wallet_test.go@@ -52,3 +52,37 @@ func TestWalletLeftWithinItsTier(t *testing.T) {}}}++// mycf_711 (#4095): a group's pool holds several providers' wallets —+// WorkBuddy's credits beside SuperMagic's points — and with two kinds in+// it nothing was weighed by a balance, so the group spent SuperMagic's+// 282 and 119 points before its 6,635. Each kind goes by what it has left+// in the places its own seats take; the other kind's seat, and a seat+// that told none, keep theirs.+func TestWalletsOfSeveralProvidersEachGoByWhatTheyHaveLeft(t *testing.T) {+ const pts, credits = "magicrew\x00积分", "workbuddy\x00credits"+ wallet := func(key string, left float64, in string) Seat {+ return Seat{Key: key, Account: true, Known: true, Pace: 100.0 / 168, Left: left, LeftIn: in}+ }+ for _, st := range []struct {+ name string+ s Strategy+ }{{"smart", Smart}, {"pace", Pace}, {"usage", LeastUsed}} {+ s := []Seat{wallet("wb-small", 40, credits), wallet("632", 282, pts), wallet("710", 119, pts), wallet("wb-big", 900, credits), wallet("051", 6635, pts)}+ if got, want := keys(s, Apply(st.s, "p", s)), []string{"wb-big", "051", "632", "wb-small", "710"}; !slices.Equal(got, want) {+ t.Errorf("%s: %v, want %v", st.name, got, want)+ }+ // the reporter's three behind another provider's wallet+ s = []Seat{wallet("wb", 50, credits), wallet("632", 282, pts), wallet("710", 119, pts), wallet("051", 6635, pts)}+ if got, want := keys(s, Apply(st.s, "p", s)), []string{"wb", "051", "632", "710"}; !slices.Equal(got, want) {+ t.Errorf("%s, reporter's: %v, want %v", st.name, got, want)+ }+ }+ // least used: the kinds keep the order of what magpie sent them lately+ // between them, each kind in its places by what it has left+ s := []Seat{wallet("632", 282, pts), wallet("wb", 50, credits), wallet("051", 6635, pts)}+ s[0].Tokens, s[1].Tokens, s[2].Tokens = 10, 20, 30+ if got, want := keys(s, Apply(LeastUsed, "p", s)), []string{"051", "wb", "632"}; !slices.Equal(got, want) {+ t.Errorf("usage by tokens: %v, want %v", got, want)+ }+}