@yolk-sdk/pool 0.0.0-stage → 0.1.0-canary.118
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +123 -2
- package/dist/index.d.mts +4 -0
- package/dist/index.mjs +4 -0
- package/dist/model.d.mts +58 -0
- package/dist/model.d.mts.map +1 -0
- package/dist/model.mjs +68 -0
- package/dist/model.mjs.map +1 -0
- package/dist/pool.d.mts +73 -0
- package/dist/pool.d.mts.map +1 -0
- package/dist/pool.mjs +290 -0
- package/dist/pool.mjs.map +1 -0
- package/dist/rank.d.mts +164 -0
- package/dist/rank.d.mts.map +1 -0
- package/dist/rank.mjs +139 -0
- package/dist/rank.mjs.map +1 -0
- package/dist/store.d.mts +89 -0
- package/dist/store.d.mts.map +1 -0
- package/dist/store.mjs +253 -0
- package/dist/store.mjs.map +1 -0
- package/package.json +59 -3
- package/src/index.ts +32 -0
- package/src/model.ts +81 -0
- package/src/pool.ts +570 -0
- package/src/rank.ts +307 -0
- package/src/store.ts +392 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Yolk SDK contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,124 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @yolk-sdk/pool
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Subscription account pools for Yolk agents
|
|
4
|
+
([ADR 0011](https://github.com/magoz/yolk-sdk/blob/main/docs/adr/0011-subscription-pools.md)).
|
|
5
|
+
Several accounts of one provider (for example two Claude Max subscriptions) serve as one
|
|
6
|
+
`LLMProvider`:
|
|
7
|
+
|
|
8
|
+
- each request goes to the account whose longest usage window (usually the weekly one) resets
|
|
9
|
+
soonest and still has quota, so quota that would reset unused is spent first (expiring-first);
|
|
10
|
+
- without fresh usage readings, a route stays on the account that served it last (sticky
|
|
11
|
+
fill-first);
|
|
12
|
+
- when an account runs out of quota or its credentials are rejected before any output, it cools
|
|
13
|
+
down and the same request moves to the next account.
|
|
14
|
+
|
|
15
|
+
It is the in-process counterpart of a CLIProxyAPI gateway with the
|
|
16
|
+
[`expiring-first`](https://github.com/magoz/cpa-expiring-first) scheduler plugin.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pnpm add @yolk-sdk/pool@canary @yolk-sdk/agent@canary effect@4.0.5
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
|
|
25
|
+
Use the SDK's matching Effect version (`4.0.5`) in host code.
|
|
26
|
+
Published package metadata requires Node.js 22+. The package is runtime-neutral.
|
|
27
|
+
|
|
28
|
+
## Subpaths
|
|
29
|
+
|
|
30
|
+
| Subpath | Purpose |
|
|
31
|
+
| ---------------------- | --------------------------------------------------------------------------------------- |
|
|
32
|
+
| `@yolk-sdk/pool` | `makePool`, the pure ranking (`rankPool`, `staleQuotaCooldowns`), Schemas, and errors |
|
|
33
|
+
| `@yolk-sdk/pool/store` | `PoolStoreApi` port, `makeMemoryPoolStore`, and the `poolStoreContract` semantics cases |
|
|
34
|
+
|
|
35
|
+
## Usage
|
|
36
|
+
|
|
37
|
+
This server-side fragment assumes `claudeWork` and `claudePersonal` are `LLMProvider` services you
|
|
38
|
+
built, one per account with its credentials, and `workToken` is that account's fresh OAuth token:
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
import { Effect, Layer } from 'effect'
|
|
42
|
+
import { LLMProvider } from '@yolk-sdk/agent/loop'
|
|
43
|
+
import { fetchAnthropicClaudeSubscriptionUsage } from '@yolk-sdk/agent/providers/anthropic/usage'
|
|
44
|
+
import { makePool } from '@yolk-sdk/pool'
|
|
45
|
+
import { makeMemoryPoolStore } from '@yolk-sdk/pool/store'
|
|
46
|
+
|
|
47
|
+
const program = Effect.gen(function* () {
|
|
48
|
+
const pool = yield* makePool({
|
|
49
|
+
id: 'claude',
|
|
50
|
+
accounts: [
|
|
51
|
+
// LLMProvider services the host builds, one per account and its credentials.
|
|
52
|
+
{ id: 'claude-work', priority: 1, provider: claudeWork },
|
|
53
|
+
{ id: 'claude-personal', provider: claudePersonal }
|
|
54
|
+
],
|
|
55
|
+
// Serverless hosts implement PoolStoreApi on their database.
|
|
56
|
+
store: makeMemoryPoolStore()
|
|
57
|
+
})
|
|
58
|
+
|
|
59
|
+
// The loop's provider: innermost, under host retry or attachment wrappers.
|
|
60
|
+
const llm = Layer.succeed(LLMProvider, pool.provider)
|
|
61
|
+
|
|
62
|
+
// On the host's own schedule (cron, background job), never per request.
|
|
63
|
+
yield* pool.recordReading('claude-work', yield* fetchAnthropicClaudeSubscriptionUsage(workToken))
|
|
64
|
+
|
|
65
|
+
// For a settings page: pins, active cooldowns, readings.
|
|
66
|
+
const state = yield* pool.state
|
|
67
|
+
})
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Accounts must be interchangeable for the requests the pool serves (same provider, same models).
|
|
71
|
+
Each account's provider is built by the host with that account's credentials; the pool never
|
|
72
|
+
sees tokens.
|
|
73
|
+
|
|
74
|
+
| `makePool` option | Meaning |
|
|
75
|
+
| --------------------- | --------------------------------------------------------------------- |
|
|
76
|
+
| `id` | pool id; pins are keyed by pool id and route |
|
|
77
|
+
| `accounts[].id` | unique within the store; cooldowns and readings are keyed by it |
|
|
78
|
+
| `accounts[].priority` | breaks ranking ties and orders fill-first, higher first (default 0) |
|
|
79
|
+
| `accounts[].provider` | the account's `LLMProvider` service |
|
|
80
|
+
| `store` | a `PoolStoreApi` (`makeMemoryPoolStore` for one process) |
|
|
81
|
+
| `maxAgeMs` | how old a reading may be and still rank accounts (default 30 minutes) |
|
|
82
|
+
| `reservePercent` | quota left untouched on every window, from 0 to below 100 (default 0) |
|
|
83
|
+
|
|
84
|
+
## Failover and retries
|
|
85
|
+
|
|
86
|
+
| Failure before the first event | Pool |
|
|
87
|
+
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
88
|
+
| `rate_limit` with `quotaResetsAtMs` (Claude, Codex quota) | Cooldown until the reset, next account |
|
|
89
|
+
| `rate_limit` with `retryAfterMs` of 30 minutes or more | Cooldown for that long, next account |
|
|
90
|
+
| `auth` | 30-minute cooldown, next account |
|
|
91
|
+
| anything else, or any failure after an event | Unchanged to the caller; the loop retries it only when it is retryable and nothing was emitted |
|
|
92
|
+
| every account out on quota | `rate_limit`, `retryable: false`, earliest quota reset |
|
|
93
|
+
| every account out on rejected credentials only | `auth` (`provider_error`), `retryable: false` |
|
|
94
|
+
|
|
95
|
+
The loop's own retry calls the pool again, which picks again; the pool never retries transient
|
|
96
|
+
errors itself, so attempts never multiply. A hint that is not finite or is more than a year ahead
|
|
97
|
+
is ignored on its own; another trusted hint on the same error (a long `retryAfterMs`) can still
|
|
98
|
+
cool the account down, otherwise the error passes through.
|
|
99
|
+
|
|
100
|
+
When no account is usable by a fresh reading, the pool falls back to the route's pin or fill-first,
|
|
101
|
+
skipping accounts a fresh reading shows used up unless nothing else is left.
|
|
102
|
+
|
|
103
|
+
## Store
|
|
104
|
+
|
|
105
|
+
`PoolStoreApi` holds pins (per pool and route), one cooldown per account, and the latest reading
|
|
106
|
+
per account. Implementations must be atomic per key (`movePin` is a compare-and-set). Run every
|
|
107
|
+
case of `poolStoreContract` against a fresh store of your implementation in your tests. Store
|
|
108
|
+
failures never fail a request: the pool routes fill-first without state and logs a warning.
|
|
109
|
+
|
|
110
|
+
## Host responsibilities
|
|
111
|
+
|
|
112
|
+
- Credentials: one refresher per OAuth grant (refresh tokens rotate). Separate logins of the same
|
|
113
|
+
account are separate grants.
|
|
114
|
+
- Readings: poll each account's usage (`anthropic/usage`, `openai/codex-usage`, `xai/usage`,
|
|
115
|
+
`opencode/usage` under `@yolk-sdk/agent/providers/`) on a schedule and
|
|
116
|
+
call `recordReading`. Readings older than `maxAgeMs` (default 30 minutes) are ignored.
|
|
117
|
+
- Which accounts form a pool, labels, alerts, and UI.
|
|
118
|
+
|
|
119
|
+
## Boundaries
|
|
120
|
+
|
|
121
|
+
- Depends only on `@yolk-sdk/agent/{loop,protocol,providers/subscription-usage}` and Effect; no
|
|
122
|
+
Node builtins. `@yolk-sdk/agent` never imports this package.
|
|
123
|
+
- The pool never sees tokens and never calls usage endpoints; hosts build each account's provider
|
|
124
|
+
and record its readings.
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { PoolAccountId, PoolAuthCooldown, PoolConfigError, PoolCooldown, PoolPin, PoolQuotaCooldown, PoolStoreError, PoolUnknownAccountError } from "./model.mjs";
|
|
2
|
+
import { Pool, PoolAccount, PoolAccountState, PoolOptions, PoolState, defaultPoolMaxAgeMs, makePool, poolAuthCooldownMs, poolFailureCooldown, poolMaxCooldownMs, poolQuotaRetryAfterFloorMs } from "./pool.mjs";
|
|
3
|
+
import { PoolCandidate, PoolDecision, PoolRankInput, PoolReading, PoolWindow, isCooldownActive, poolReadingFromSnapshot, poolRoute, rankPool, staleQuotaCooldowns } from "./rank.mjs";
|
|
4
|
+
export { type Pool, type PoolAccount, PoolAccountId, type PoolAccountState, PoolAuthCooldown, type PoolCandidate, PoolConfigError, PoolCooldown, PoolDecision, type PoolOptions, PoolPin, PoolQuotaCooldown, type PoolRankInput, type PoolReading, type PoolState, PoolStoreError, PoolUnknownAccountError, type PoolWindow, defaultPoolMaxAgeMs, isCooldownActive, makePool, poolAuthCooldownMs, poolFailureCooldown, poolMaxCooldownMs, poolQuotaRetryAfterFloorMs, poolReadingFromSnapshot, poolRoute, rankPool, staleQuotaCooldowns };
|
package/dist/index.mjs
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { PoolAccountId, PoolAuthCooldown, PoolConfigError, PoolCooldown, PoolPin, PoolQuotaCooldown, PoolStoreError, PoolUnknownAccountError } from "./model.mjs";
|
|
2
|
+
import { PoolDecision, isCooldownActive, poolReadingFromSnapshot, poolRoute, rankPool, staleQuotaCooldowns } from "./rank.mjs";
|
|
3
|
+
import { defaultPoolMaxAgeMs, makePool, poolAuthCooldownMs, poolFailureCooldown, poolMaxCooldownMs, poolQuotaRetryAfterFloorMs } from "./pool.mjs";
|
|
4
|
+
export { PoolAccountId, PoolAuthCooldown, PoolConfigError, PoolCooldown, PoolDecision, PoolPin, PoolQuotaCooldown, PoolStoreError, PoolUnknownAccountError, defaultPoolMaxAgeMs, isCooldownActive, makePool, poolAuthCooldownMs, poolFailureCooldown, poolMaxCooldownMs, poolQuotaRetryAfterFloorMs, poolReadingFromSnapshot, poolRoute, rankPool, staleQuotaCooldowns };
|
package/dist/model.d.mts
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import * as Schema from "effect/Schema";
|
|
2
|
+
|
|
3
|
+
//#region src/model.d.ts
|
|
4
|
+
/** A host-chosen account id, unique within the accounts a store serves. */
|
|
5
|
+
declare const PoolAccountId: Schema.Trimmed;
|
|
6
|
+
declare const PoolPin_base: Schema.Class<PoolPin, Schema.Struct<{
|
|
7
|
+
readonly poolId: Schema.Trimmed;
|
|
8
|
+
readonly route: Schema.Trimmed;
|
|
9
|
+
readonly accountId: Schema.Trimmed;
|
|
10
|
+
readonly pinnedAtMs: Schema.Finite;
|
|
11
|
+
}>, {}>;
|
|
12
|
+
/**
|
|
13
|
+
* The account currently serving one route of a pool. A route is a lowercased model id, so every
|
|
14
|
+
* reasoning effort of a model shares one pin.
|
|
15
|
+
*/
|
|
16
|
+
declare class PoolPin extends PoolPin_base {}
|
|
17
|
+
declare const PoolQuotaCooldown_base: Schema.Class<PoolQuotaCooldown, Schema.TaggedStruct<"PoolQuotaCooldown", {
|
|
18
|
+
readonly accountId: Schema.Trimmed;
|
|
19
|
+
readonly startedAtMs: Schema.Finite;
|
|
20
|
+
readonly untilMs: Schema.Finite;
|
|
21
|
+
}>, {}>;
|
|
22
|
+
/** The account's subscription quota is exhausted until `untilMs` (a provider quota reset). */
|
|
23
|
+
declare class PoolQuotaCooldown extends PoolQuotaCooldown_base {}
|
|
24
|
+
declare const PoolAuthCooldown_base: Schema.Class<PoolAuthCooldown, Schema.TaggedStruct<"PoolAuthCooldown", {
|
|
25
|
+
readonly accountId: Schema.Trimmed;
|
|
26
|
+
readonly startedAtMs: Schema.Finite;
|
|
27
|
+
readonly untilMs: Schema.Finite;
|
|
28
|
+
}>, {}>;
|
|
29
|
+
/** The provider rejected the account's credentials; it sits out until `untilMs`. */
|
|
30
|
+
declare class PoolAuthCooldown extends PoolAuthCooldown_base {}
|
|
31
|
+
/**
|
|
32
|
+
* Why an account sits out. One cooldown per account: writing keeps the one that ends later (on a
|
|
33
|
+
* tie, the one that started later; see `PoolStoreApi.putCooldown`), and a reading can clear only a
|
|
34
|
+
* quota cooldown it postdates.
|
|
35
|
+
*/
|
|
36
|
+
declare const PoolCooldown: Schema.Union<readonly [typeof PoolQuotaCooldown, typeof PoolAuthCooldown]>;
|
|
37
|
+
type PoolCooldown = typeof PoolCooldown.Type;
|
|
38
|
+
declare const PoolStoreError_base: Schema.Class<PoolStoreError, Schema.TaggedStruct<"PoolStoreError", {
|
|
39
|
+
readonly operation: Schema.Literals<readonly ["load", "movePin", "putCooldown", "clearCooldown", "putReading", "state"]>;
|
|
40
|
+
readonly message: Schema.String;
|
|
41
|
+
}>, import("effect/Cause").YieldableError>;
|
|
42
|
+
/** A pool store operation failed. The pool degrades to stateless fill-first routing on reads. */
|
|
43
|
+
declare class PoolStoreError extends PoolStoreError_base {}
|
|
44
|
+
declare const PoolConfigError_base: Schema.Class<PoolConfigError, Schema.TaggedStruct<"PoolConfigError", {
|
|
45
|
+
readonly reason: Schema.Literals<readonly ["invalid_pool_id", "no_accounts", "invalid_account_id", "duplicate_account_id", "invalid_priority", "invalid_max_age", "invalid_reserve_percent"]>;
|
|
46
|
+
readonly message: Schema.String;
|
|
47
|
+
}>, import("effect/Cause").YieldableError>;
|
|
48
|
+
/** `makePool` rejected its configuration. */
|
|
49
|
+
declare class PoolConfigError extends PoolConfigError_base {}
|
|
50
|
+
declare const PoolUnknownAccountError_base: Schema.Class<PoolUnknownAccountError, Schema.TaggedStruct<"PoolUnknownAccountError", {
|
|
51
|
+
readonly poolId: Schema.String;
|
|
52
|
+
readonly accountId: Schema.String;
|
|
53
|
+
}>, import("effect/Cause").YieldableError>;
|
|
54
|
+
/** A reading or lookup named an account the pool was not configured with. */
|
|
55
|
+
declare class PoolUnknownAccountError extends PoolUnknownAccountError_base {}
|
|
56
|
+
//#endregion
|
|
57
|
+
export { PoolAccountId, PoolAuthCooldown, PoolConfigError, PoolCooldown, PoolPin, PoolQuotaCooldown, PoolStoreError, PoolUnknownAccountError };
|
|
58
|
+
//# sourceMappingURL=model.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"model.d.mts","names":[],"sources":["../src/model.ts"],"mappings":";;;;cAOa,aAAA,EAAa,MAAA,CAAA,OAAwB;AAAA,cAAA,YAAA;;;;;;;;;;cAMrC,OAAA,SAAgB,YAK3B;AAAA,cAAG,sBAAA;;;;;;cAGQ,iBAAA,SAA0B,sBAOtC;AAAA,cAAG,qBAAA;;;;;;cAGS,gBAAA,SAAyB,qBAIpC;;;;;;cAOW,YAAA,EAAY,MAAA,CAAA,KAAA,kBAAA,iBAAA,SAAA,gBAAA;AAAA,KAEb,YAAA,UAAsB,YAAA,CAAa,IAAI;AAAA,cAAA,mBAAA;;;;;cAGtC,cAAA,SAAuB,mBAUlC;AAAA,cAAG,oBAAA;;;;;cAGQ,eAAA,SAAwB,oBAWnC;AAAA,cAAG,4BAAA;;;;;cAGQ,uBAAA,SAAgC,4BAM5C"}
|
package/dist/model.mjs
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import * as Schema from "effect/Schema";
|
|
2
|
+
//#region src/model.ts
|
|
3
|
+
const NonEmptyTrimmedString = Schema.Trimmed.pipe(Schema.check(Schema.isNonEmpty()));
|
|
4
|
+
const EpochMs = Schema.Finite;
|
|
5
|
+
/** A host-chosen account id, unique within the accounts a store serves. */
|
|
6
|
+
const PoolAccountId = NonEmptyTrimmedString;
|
|
7
|
+
/**
|
|
8
|
+
* The account currently serving one route of a pool. A route is a lowercased model id, so every
|
|
9
|
+
* reasoning effort of a model shares one pin.
|
|
10
|
+
*/
|
|
11
|
+
var PoolPin = class extends Schema.Class("PoolPin")({
|
|
12
|
+
poolId: NonEmptyTrimmedString,
|
|
13
|
+
route: NonEmptyTrimmedString,
|
|
14
|
+
accountId: PoolAccountId,
|
|
15
|
+
pinnedAtMs: EpochMs
|
|
16
|
+
}) {};
|
|
17
|
+
/** The account's subscription quota is exhausted until `untilMs` (a provider quota reset). */
|
|
18
|
+
var PoolQuotaCooldown = class extends Schema.TaggedClass()("PoolQuotaCooldown", {
|
|
19
|
+
accountId: PoolAccountId,
|
|
20
|
+
startedAtMs: EpochMs,
|
|
21
|
+
untilMs: EpochMs
|
|
22
|
+
}) {};
|
|
23
|
+
/** The provider rejected the account's credentials; it sits out until `untilMs`. */
|
|
24
|
+
var PoolAuthCooldown = class extends Schema.TaggedClass()("PoolAuthCooldown", {
|
|
25
|
+
accountId: PoolAccountId,
|
|
26
|
+
startedAtMs: EpochMs,
|
|
27
|
+
untilMs: EpochMs
|
|
28
|
+
}) {};
|
|
29
|
+
/**
|
|
30
|
+
* Why an account sits out. One cooldown per account: writing keeps the one that ends later (on a
|
|
31
|
+
* tie, the one that started later; see `PoolStoreApi.putCooldown`), and a reading can clear only a
|
|
32
|
+
* quota cooldown it postdates.
|
|
33
|
+
*/
|
|
34
|
+
const PoolCooldown = Schema.Union([PoolQuotaCooldown, PoolAuthCooldown]);
|
|
35
|
+
/** A pool store operation failed. The pool degrades to stateless fill-first routing on reads. */
|
|
36
|
+
var PoolStoreError = class extends Schema.TaggedError()("PoolStoreError", {
|
|
37
|
+
operation: Schema.Literals([
|
|
38
|
+
"load",
|
|
39
|
+
"movePin",
|
|
40
|
+
"putCooldown",
|
|
41
|
+
"clearCooldown",
|
|
42
|
+
"putReading",
|
|
43
|
+
"state"
|
|
44
|
+
]),
|
|
45
|
+
message: Schema.String
|
|
46
|
+
}) {};
|
|
47
|
+
/** `makePool` rejected its configuration. */
|
|
48
|
+
var PoolConfigError = class extends Schema.TaggedError()("PoolConfigError", {
|
|
49
|
+
reason: Schema.Literals([
|
|
50
|
+
"invalid_pool_id",
|
|
51
|
+
"no_accounts",
|
|
52
|
+
"invalid_account_id",
|
|
53
|
+
"duplicate_account_id",
|
|
54
|
+
"invalid_priority",
|
|
55
|
+
"invalid_max_age",
|
|
56
|
+
"invalid_reserve_percent"
|
|
57
|
+
]),
|
|
58
|
+
message: Schema.String
|
|
59
|
+
}) {};
|
|
60
|
+
/** A reading or lookup named an account the pool was not configured with. */
|
|
61
|
+
var PoolUnknownAccountError = class extends Schema.TaggedError()("PoolUnknownAccountError", {
|
|
62
|
+
poolId: Schema.String,
|
|
63
|
+
accountId: Schema.String
|
|
64
|
+
}) {};
|
|
65
|
+
//#endregion
|
|
66
|
+
export { PoolAccountId, PoolAuthCooldown, PoolConfigError, PoolCooldown, PoolPin, PoolQuotaCooldown, PoolStoreError, PoolUnknownAccountError };
|
|
67
|
+
|
|
68
|
+
//# sourceMappingURL=model.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"model.mjs","names":[],"sources":["../src/model.ts"],"sourcesContent":["import * as Schema from 'effect/Schema'\n\nconst NonEmptyTrimmedString = Schema.Trimmed.pipe(Schema.check(Schema.isNonEmpty()))\n\nconst EpochMs = Schema.Finite\n\n/** A host-chosen account id, unique within the accounts a store serves. */\nexport const PoolAccountId = NonEmptyTrimmedString\n\n/**\n * The account currently serving one route of a pool. A route is a lowercased model id, so every\n * reasoning effort of a model shares one pin.\n */\nexport class PoolPin extends Schema.Class<PoolPin>('PoolPin')({\n poolId: NonEmptyTrimmedString,\n route: NonEmptyTrimmedString,\n accountId: PoolAccountId,\n pinnedAtMs: EpochMs\n}) {}\n\n/** The account's subscription quota is exhausted until `untilMs` (a provider quota reset). */\nexport class PoolQuotaCooldown extends Schema.TaggedClass<PoolQuotaCooldown>()(\n 'PoolQuotaCooldown',\n {\n accountId: PoolAccountId,\n startedAtMs: EpochMs,\n untilMs: EpochMs\n }\n) {}\n\n/** The provider rejected the account's credentials; it sits out until `untilMs`. */\nexport class PoolAuthCooldown extends Schema.TaggedClass<PoolAuthCooldown>()('PoolAuthCooldown', {\n accountId: PoolAccountId,\n startedAtMs: EpochMs,\n untilMs: EpochMs\n}) {}\n\n/**\n * Why an account sits out. One cooldown per account: writing keeps the one that ends later (on a\n * tie, the one that started later; see `PoolStoreApi.putCooldown`), and a reading can clear only a\n * quota cooldown it postdates.\n */\nexport const PoolCooldown = Schema.Union([PoolQuotaCooldown, PoolAuthCooldown])\n\nexport type PoolCooldown = typeof PoolCooldown.Type\n\n/** A pool store operation failed. The pool degrades to stateless fill-first routing on reads. */\nexport class PoolStoreError extends Schema.TaggedError<PoolStoreError>()('PoolStoreError', {\n operation: Schema.Literals([\n 'load',\n 'movePin',\n 'putCooldown',\n 'clearCooldown',\n 'putReading',\n 'state'\n ]),\n message: Schema.String\n}) {}\n\n/** `makePool` rejected its configuration. */\nexport class PoolConfigError extends Schema.TaggedError<PoolConfigError>()('PoolConfigError', {\n reason: Schema.Literals([\n 'invalid_pool_id',\n 'no_accounts',\n 'invalid_account_id',\n 'duplicate_account_id',\n 'invalid_priority',\n 'invalid_max_age',\n 'invalid_reserve_percent'\n ]),\n message: Schema.String\n}) {}\n\n/** A reading or lookup named an account the pool was not configured with. */\nexport class PoolUnknownAccountError extends Schema.TaggedError<PoolUnknownAccountError>()(\n 'PoolUnknownAccountError',\n {\n poolId: Schema.String,\n accountId: Schema.String\n }\n) {}\n"],"mappings":";;AAEA,MAAM,wBAAwB,OAAO,QAAQ,KAAK,OAAO,MAAM,OAAO,WAAW,CAAC,CAAC;AAEnF,MAAM,UAAU,OAAO;;AAGvB,MAAa,gBAAgB;;;;;AAM7B,IAAa,UAAb,cAA6B,OAAO,MAAe,SAAS,EAAE;CAC5D,QAAQ;CACR,OAAO;CACP,WAAW;CACX,YAAY;AACd,CAAC,EAAE,CAAC;;AAGJ,IAAa,oBAAb,cAAuC,OAAO,YAA+B,EAC3E,qBACA;CACE,WAAW;CACX,aAAa;CACb,SAAS;AACX,CACF,EAAE,CAAC;;AAGH,IAAa,mBAAb,cAAsC,OAAO,YAA8B,EAAE,oBAAoB;CAC/F,WAAW;CACX,aAAa;CACb,SAAS;AACX,CAAC,EAAE,CAAC;;;;;;AAOJ,MAAa,eAAe,OAAO,MAAM,CAAC,mBAAmB,gBAAgB,CAAC;;AAK9E,IAAa,iBAAb,cAAoC,OAAO,YAA4B,EAAE,kBAAkB;CACzF,WAAW,OAAO,SAAS;EACzB;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD,SAAS,OAAO;AAClB,CAAC,EAAE,CAAC;;AAGJ,IAAa,kBAAb,cAAqC,OAAO,YAA6B,EAAE,mBAAmB;CAC5F,QAAQ,OAAO,SAAS;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD,SAAS,OAAO;AAClB,CAAC,EAAE,CAAC;;AAGJ,IAAa,0BAAb,cAA6C,OAAO,YAAqC,EACvF,2BACA;CACE,QAAQ,OAAO;CACf,WAAW,OAAO;AACpB,CACF,EAAE,CAAC"}
|
package/dist/pool.d.mts
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { PoolConfigError, PoolCooldown, PoolPin, PoolStoreError, PoolUnknownAccountError } from "./model.mjs";
|
|
2
|
+
import { PoolStoreApi } from "./store.mjs";
|
|
3
|
+
import { Effect } from "effect";
|
|
4
|
+
import { LLMError, LLMProvider } from "@yolk-sdk/agent/loop";
|
|
5
|
+
import { ProviderSubscriptionUsageSnapshot } from "@yolk-sdk/agent/providers/subscription-usage";
|
|
6
|
+
|
|
7
|
+
//#region src/pool.d.ts
|
|
8
|
+
type LLMProviderService = typeof LLMProvider.Service;
|
|
9
|
+
/** One subscription account of a pool: its own provider, built by the host with its credentials. */
|
|
10
|
+
type PoolAccount = {
|
|
11
|
+
/** Unique within the store; cooldowns and readings are keyed by it. */readonly id: string; /** Breaks ranking ties and orders fill-first (higher first). Default 0. */
|
|
12
|
+
readonly priority?: number;
|
|
13
|
+
readonly provider: LLMProviderService;
|
|
14
|
+
};
|
|
15
|
+
type PoolOptions = {
|
|
16
|
+
/** Pins are keyed by pool id and route. */readonly id: string; /** Accounts of one provider; requests must suit every one of them. */
|
|
17
|
+
readonly accounts: ReadonlyArray<PoolAccount>;
|
|
18
|
+
readonly store: PoolStoreApi; /** How old a reading may be and still rank accounts. Default 30 minutes. */
|
|
19
|
+
readonly maxAgeMs?: number; /** Quota left untouched on every window, in percent (0 to below 100). Default 0. */
|
|
20
|
+
readonly reservePercent?: number;
|
|
21
|
+
};
|
|
22
|
+
/** One account as the host UI sees it. */
|
|
23
|
+
type PoolAccountState = {
|
|
24
|
+
readonly id: string;
|
|
25
|
+
readonly priority: number; /** The account's cooldown while it is active. */
|
|
26
|
+
readonly cooldown: PoolCooldown | undefined;
|
|
27
|
+
readonly reading: ProviderSubscriptionUsageSnapshot | undefined;
|
|
28
|
+
};
|
|
29
|
+
type PoolState = {
|
|
30
|
+
readonly poolId: string; /** The account serving each route. */
|
|
31
|
+
readonly pins: ReadonlyArray<PoolPin>;
|
|
32
|
+
readonly accounts: ReadonlyArray<PoolAccountState>;
|
|
33
|
+
};
|
|
34
|
+
type Pool = {
|
|
35
|
+
readonly id: string; /** The pooled provider: provide it as the loop's `LLMProvider`, innermost under host wrappers. */
|
|
36
|
+
readonly provider: LLMProviderService; /** Records an account's usage snapshot; hosts poll usage on their own schedule. */
|
|
37
|
+
readonly recordReading: (accountId: string, snapshot: ProviderSubscriptionUsageSnapshot) => Effect.Effect<void, PoolUnknownAccountError | PoolStoreError>; /** Pins, active cooldowns, and readings for host UIs. */
|
|
38
|
+
readonly state: Effect.Effect<PoolState, PoolStoreError>;
|
|
39
|
+
};
|
|
40
|
+
/** Default `maxAgeMs`: readings older than 30 minutes no longer rank accounts. */
|
|
41
|
+
declare const defaultPoolMaxAgeMs: number;
|
|
42
|
+
/**
|
|
43
|
+
* A `rate_limit` whose `Retry-After` reaches this is a quota lockout, not a transient limit
|
|
44
|
+
* (CLIProxyAPI `expiring-first` `QuotaCooldownFloor`).
|
|
45
|
+
*/
|
|
46
|
+
declare const poolQuotaRetryAfterFloorMs: number;
|
|
47
|
+
/** The longest cooldown the pool records; a later or non-finite hint is not trusted. */
|
|
48
|
+
declare const poolMaxCooldownMs: number;
|
|
49
|
+
/** How long an account whose credentials were rejected sits out. */
|
|
50
|
+
declare const poolAuthCooldownMs: number;
|
|
51
|
+
/**
|
|
52
|
+
* The cooldown an account-scoped failure puts its account in, or undefined when the failure is not
|
|
53
|
+
* the account's (the loop's retry handles those): a `rate_limit` with a quota reset or a
|
|
54
|
+
* `Retry-After` of at least `poolQuotaRetryAfterFloorMs` (quota), or `auth`.
|
|
55
|
+
*/
|
|
56
|
+
declare const poolFailureCooldown: (error: LLMError, accountId: string, nowMs: number) => PoolCooldown | undefined;
|
|
57
|
+
/**
|
|
58
|
+
* Pools several subscription accounts of one provider behind one `LLMProvider` (ADR 0011).
|
|
59
|
+
*
|
|
60
|
+
* Each request goes to the account whose longest usage window resets soonest and still has quota
|
|
61
|
+
* (expiring-first), or, without fresh readings, stays on the route's pinned account. An
|
|
62
|
+
* account-scoped failure before the first event (an exhausted quota, rejected credentials) cools the
|
|
63
|
+
* account down and the same request moves to the next account; every other failure, and any failure
|
|
64
|
+
* after an event, reaches the caller unchanged. With every account out it fails `rate_limit`
|
|
65
|
+
* (non-retryable) carrying the earliest quota reset, or `auth` when only auth cooldowns remain.
|
|
66
|
+
*
|
|
67
|
+
* Store failures never fail a request: reads fall back to stateless fill-first and writes are
|
|
68
|
+
* logged.
|
|
69
|
+
*/
|
|
70
|
+
declare const makePool: (options: PoolOptions) => Effect.Effect<Pool, PoolConfigError>;
|
|
71
|
+
//#endregion
|
|
72
|
+
export { Pool, PoolAccount, PoolAccountState, PoolOptions, PoolState, defaultPoolMaxAgeMs, makePool, poolAuthCooldownMs, poolFailureCooldown, poolMaxCooldownMs, poolQuotaRetryAfterFloorMs };
|
|
73
|
+
//# sourceMappingURL=pool.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pool.d.mts","names":[],"sources":["../src/pool.ts"],"mappings":";;;;;;;KA+BK,kBAAA,UAA4B,WAAA,CAAY,OAAO;;KAGxC,WAAA;EAHW,gFAKZ,EAAA,UALsB;EAAA,SAOtB,QAAA;EAAA,SACA,QAAA,EAAU,kBAAkB;AAAA;AAAA,KAG3B,WAAA;EAH2B,oDAK5B,EAAA,UANA;EAAA,SAQA,QAAA,EAAU,aAAA,CAAc,WAAA;EAAA,SACxB,KAAA,EAAO,YAAA,EARqB;EAAA,SAU5B,QAAA,WAPC;EAAA,SASD,cAAA;AAAA;;KAIC,gBAAA;EAAA,SACD,EAAA;EAAA,SACA,QAAA,UAVmB;EAAA,SAYnB,QAAA,EAAU,YAAA;EAAA,SACV,OAAA,EAAS,iCAAiC;AAAA;AAAA,KAGzC,SAAA;EAAA,SACD,MAAA,UAjBO;EAAA,SAmBP,IAAA,EAAM,aAAA,CAAc,OAAA;EAAA,SACpB,QAAA,EAAU,aAAA,CAAc,gBAAA;AAAA;AAAA,KAGvB,IAAA;EAAA,SACD,EAAA,UAhBiB;EAAA,SAkBjB,QAAA,EAAU,kBAAA,EAbgC;EAAA,SAe1C,aAAA,GACP,SAAA,UACA,QAAA,EAAU,iCAAA,KACP,MAAA,CAAO,MAAA,OAAa,uBAAA,GAA0B,cAAA,GArB1C;EAAA,SAuBA,KAAA,EAAO,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,cAAA;AAAA;;cAI9B,mBAAA;;AAxBwC;AAGrD;;cA2Ba,0BAAA;;cAGA,iBAAA;;cAGA,kBAAA;;;;;;cAYA,mBAAA,GACX,KAAA,EAAO,QAAA,EACP,SAAA,UACA,KAAA,aACC,YAAY;;;;;AA7CoC;AAGnD;;;;;;;;cA+Ga,QAAA,GAAY,OAAA,EAAS,WAAA,KAAc,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,eAAA"}
|