@yolk-sdk/pool 0.0.0-stage → 0.1.0-canary.116

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 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
- # Temporary Holding Version
1
+ # @yolk-sdk/pool
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.
@@ -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 };
@@ -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"}
@@ -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"}