@yolk-sdk/pool 0.1.0-canary.140 → 0.1.0-canary.142

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/README.md CHANGED
@@ -103,9 +103,23 @@ skipping accounts a fresh reading shows used up unless nothing else is left.
103
103
  ## Store
104
104
 
105
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.
106
+ per account. Implementations must be atomic per key (`movePin` is a compare-and-set).
107
+
108
+ `putCooldown` over an existing cooldown: one that ended before the other began gives way to it;
109
+ two that overlap merge into the later end and its kind (on a tie, the later start's; on a full tie,
110
+ quota), with the later `startedAtMs` of the two (the newest failure), so a reading taken before
111
+ that failure never clears it. A kept quota
112
+ cooldown records the end of an auth failure it absorbed as `authUntilMs`; readings do not clear it
113
+ before then (a reading cannot vouch for the rejected credential). `clearCooldown` removes only the
114
+ observed `PoolQuotaCooldown` (same `startedAtMs` and `authUntilMs`), never a `PoolAuthCooldown`.
115
+ Two requests failing on one account write concurrently, so merge in one atomic statement, not a
116
+ read followed by a write: for example an upsert that sets the greatest start, picks the end and
117
+ kind with a `CASE` on which ends later (then which started later, then quota), and sets
118
+ `authUntilMs` to the greatest auth end of the two (an auth cooldown's end, a quota cooldown's
119
+ `authUntilMs`) when the kept one is quota and that end is after the merged start, else null.
120
+
121
+ Run every case of `poolStoreContract` against a fresh store of your implementation in your tests.
122
+ Store failures never fail a request: the pool routes fill-first without state and logs a warning.
109
123
 
110
124
  ## Host responsibilities
111
125
 
package/dist/model.d.mts CHANGED
@@ -16,8 +16,14 @@ declare const PoolQuotaCooldown_base: Schema.Class<PoolQuotaCooldown, Schema.Tag
16
16
  readonly accountId: Schema.Trimmed;
17
17
  readonly startedAtMs: Schema.Finite;
18
18
  readonly untilMs: Schema.Finite;
19
+ readonly authUntilMs: Schema.optional<Schema.Finite>;
19
20
  }>, {}>;
20
- /** The account's subscription quota is exhausted until `untilMs` (a provider quota reset). */
21
+ /**
22
+ * The account's subscription quota is exhausted until `untilMs` (a provider quota reset).
23
+ * `authUntilMs` is set when the cooldown absorbed an auth failure that ends sooner (see
24
+ * `PoolStoreApi.putCooldown`): until then no reading clears it, since a reading proves nothing
25
+ * about the credential that was rejected.
26
+ */
21
27
  export declare class PoolQuotaCooldown extends PoolQuotaCooldown_base {}
22
28
  declare const PoolAuthCooldown_base: Schema.Class<PoolAuthCooldown, Schema.TaggedStruct<"PoolAuthCooldown", {
23
29
  readonly accountId: Schema.Trimmed;
@@ -27,9 +33,11 @@ declare const PoolAuthCooldown_base: Schema.Class<PoolAuthCooldown, Schema.Tagge
27
33
  /** The provider rejected the account's credentials; it sits out until `untilMs`. */
28
34
  export declare class PoolAuthCooldown extends PoolAuthCooldown_base {}
29
35
  /**
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.
36
+ * Why an account sits out. One cooldown per account: an ended one gives way to the next, and
37
+ * overlapping ones merge into the later end and its kind with the newest failure's `startedAtMs`
38
+ * (and a quota cooldown keeps an absorbed auth failure's end as `authUntilMs`; see
39
+ * `PoolStoreApi.putCooldown`). A reading can clear only a quota cooldown it postdates, once any
40
+ * absorbed auth failure has ended.
33
41
  */
34
42
  export declare const PoolCooldown: Schema.Union<readonly [typeof PoolQuotaCooldown, typeof PoolAuthCooldown]>;
35
43
  export type PoolCooldown = typeof PoolCooldown.Type;
@@ -1 +1 @@
1
- {"version":3,"file":"model.d.mts","names":[],"sources":["../src/model.ts"],"mappings":";;qBAOa,eAAa,OAAA;;;;;;;;;;;qBAMb,gBAAgB;;;;;;;qBAQhB,0BAA0B;;;;;;;qBAU1B,yBAAyB;;;;;;qBAWzB,cAAY,OAAA,uBAAA,0BAAA;YAEb,sBAAsB,aAAa;;;;;;qBAGlC,uBAAuB;;;;;;qBAavB,wBAAwB;;;;;;qBAcxB,gCAAgC"}
1
+ {"version":3,"file":"model.d.mts","names":[],"sources":["../src/model.ts"],"mappings":";;qBAOa,eAAa,OAAA;;;;;;;;;;;qBAMb,gBAAgB;;;;;;;;;;;;;qBAahB,0BAA0B;;;;;;;qBAW1B,yBAAyB;;;;;;;;qBAazB,cAAY,OAAA,uBAAA,0BAAA;YAEb,sBAAsB,aAAa;;;;;;qBAGlC,uBAAuB;;;;;;qBAavB,wBAAwB;;;;;;qBAcxB,gCAAgC"}
package/dist/model.mjs CHANGED
@@ -14,11 +14,17 @@ var PoolPin = class extends Schema.Class("PoolPin")({
14
14
  accountId: PoolAccountId,
15
15
  pinnedAtMs: EpochMs
16
16
  }) {};
17
- /** The account's subscription quota is exhausted until `untilMs` (a provider quota reset). */
17
+ /**
18
+ * The account's subscription quota is exhausted until `untilMs` (a provider quota reset).
19
+ * `authUntilMs` is set when the cooldown absorbed an auth failure that ends sooner (see
20
+ * `PoolStoreApi.putCooldown`): until then no reading clears it, since a reading proves nothing
21
+ * about the credential that was rejected.
22
+ */
18
23
  var PoolQuotaCooldown = class extends Schema.TaggedClass()("PoolQuotaCooldown", {
19
24
  accountId: PoolAccountId,
20
25
  startedAtMs: EpochMs,
21
- untilMs: EpochMs
26
+ untilMs: EpochMs,
27
+ authUntilMs: Schema.optional(EpochMs)
22
28
  }) {};
23
29
  /** The provider rejected the account's credentials; it sits out until `untilMs`. */
24
30
  var PoolAuthCooldown = class extends Schema.TaggedClass()("PoolAuthCooldown", {
@@ -27,9 +33,11 @@ var PoolAuthCooldown = class extends Schema.TaggedClass()("PoolAuthCooldown", {
27
33
  untilMs: EpochMs
28
34
  }) {};
29
35
  /**
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.
36
+ * Why an account sits out. One cooldown per account: an ended one gives way to the next, and
37
+ * overlapping ones merge into the later end and its kind with the newest failure's `startedAtMs`
38
+ * (and a quota cooldown keeps an absorbed auth failure's end as `authUntilMs`; see
39
+ * `PoolStoreApi.putCooldown`). A reading can clear only a quota cooldown it postdates, once any
40
+ * absorbed auth failure has ended.
33
41
  */
34
42
  const PoolCooldown = Schema.Union([PoolQuotaCooldown, PoolAuthCooldown]);
35
43
  /** A pool store operation failed. The pool degrades to stateless fill-first routing on reads. */
@@ -1 +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,CAAC,CAAC;CAC5D,QAAQ;CACR,OAAO;CACP,WAAW;CACX,YAAY;AACd,CAAC,CAAC,CAAC,CAAC;;AAGJ,IAAa,oBAAb,cAAuC,OAAO,YAA+B,CAAC,CAC5E,qBACA;CACE,WAAW;CACX,aAAa;CACb,SAAS;AACX,CACF,CAAC,CAAC,CAAC;;AAGH,IAAa,mBAAb,cAAsC,OAAO,YAA8B,CAAC,CAAC,oBAAoB;CAC/F,WAAW;CACX,aAAa;CACb,SAAS;AACX,CAAC,CAAC,CAAC,CAAC;;;;;;AAOJ,MAAa,eAAe,OAAO,MAAM,CAAC,mBAAmB,gBAAgB,CAAC;;AAK9E,IAAa,iBAAb,cAAoC,OAAO,YAA4B,CAAC,CAAC,kBAAkB;CACzF,WAAW,OAAO,SAAS;EACzB;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD,SAAS,OAAO;AAClB,CAAC,CAAC,CAAC,CAAC;;AAGJ,IAAa,kBAAb,cAAqC,OAAO,YAA6B,CAAC,CAAC,mBAAmB;CAC5F,QAAQ,OAAO,SAAS;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD,SAAS,OAAO;AAClB,CAAC,CAAC,CAAC,CAAC;;AAGJ,IAAa,0BAAb,cAA6C,OAAO,YAAqC,CAAC,CACxF,2BACA;CACE,QAAQ,OAAO;CACf,WAAW,OAAO;AACpB,CACF,CAAC,CAAC,CAAC"}
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/**\n * The account's subscription quota is exhausted until `untilMs` (a provider quota reset).\n * `authUntilMs` is set when the cooldown absorbed an auth failure that ends sooner (see\n * `PoolStoreApi.putCooldown`): until then no reading clears it, since a reading proves nothing\n * about the credential that was rejected.\n */\nexport class PoolQuotaCooldown extends Schema.TaggedClass<PoolQuotaCooldown>()(\n 'PoolQuotaCooldown',\n {\n accountId: PoolAccountId,\n startedAtMs: EpochMs,\n untilMs: EpochMs,\n authUntilMs: Schema.optional(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: an ended one gives way to the next, and\n * overlapping ones merge into the later end and its kind with the newest failure's `startedAtMs`\n * (and a quota cooldown keeps an absorbed auth failure's end as `authUntilMs`; see\n * `PoolStoreApi.putCooldown`). A reading can clear only a quota cooldown it postdates, once any\n * absorbed auth failure has ended.\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,CAAC,CAAC;CAC5D,QAAQ;CACR,OAAO;CACP,WAAW;CACX,YAAY;AACd,CAAC,CAAC,CAAC,CAAC;;;;;;;AAQJ,IAAa,oBAAb,cAAuC,OAAO,YAA+B,CAAC,CAC5E,qBACA;CACE,WAAW;CACX,aAAa;CACb,SAAS;CACT,aAAa,OAAO,SAAS,OAAO;AACtC,CACF,CAAC,CAAC,CAAC;;AAGH,IAAa,mBAAb,cAAsC,OAAO,YAA8B,CAAC,CAAC,oBAAoB;CAC/F,WAAW;CACX,aAAa;CACb,SAAS;AACX,CAAC,CAAC,CAAC,CAAC;;;;;;;;AASJ,MAAa,eAAe,OAAO,MAAM,CAAC,mBAAmB,gBAAgB,CAAC;;AAK9E,IAAa,iBAAb,cAAoC,OAAO,YAA4B,CAAC,CAAC,kBAAkB;CACzF,WAAW,OAAO,SAAS;EACzB;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD,SAAS,OAAO;AAClB,CAAC,CAAC,CAAC,CAAC;;AAGJ,IAAa,kBAAb,cAAqC,OAAO,YAA6B,CAAC,CAAC,mBAAmB;CAC5F,QAAQ,OAAO,SAAS;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD,SAAS,OAAO;AAClB,CAAC,CAAC,CAAC,CAAC;;AAGJ,IAAa,0BAAb,cAA6C,OAAO,YAAqC,CAAC,CACxF,2BACA;CACE,QAAQ,OAAO;CACf,WAAW,OAAO;AACpB,CACF,CAAC,CAAC,CAAC"}
package/dist/pool.mjs CHANGED
@@ -192,7 +192,8 @@ const makePool = (options) => Effect.gen(function* () {
192
192
  });
193
193
  yield* Effect.forEach(stale, (cooldown) => store.clearCooldown({
194
194
  accountId: cooldown.accountId,
195
- startedAtMs: cooldown.startedAtMs
195
+ startedAtMs: cooldown.startedAtMs,
196
+ authUntilMs: Predicate.isTagged(cooldown, "PoolQuotaCooldown") ? cooldown.authUntilMs : void 0
196
197
  }).pipe(Effect.flatMap((cleared) => cleared ? Effect.logInfo(`pool: cleared cooldown (until ${iso(cooldown.untilMs)}): a newer reading shows quota left`).pipe(Effect.annotateLogs({ account: cooldown.accountId })) : Effect.void), Effect.catch(logStoreFailure("clearCooldown"))), { discard: true });
197
198
  const cooldowns = [...snapshot.cooldowns.filter((cooldown) => isCooldownActive(cooldown, nowMs) && !stale.includes(cooldown)), ...input.recorded.filter((cooldown) => isCooldownActive(cooldown, nowMs))];
198
199
  const unavailable = /* @__PURE__ */ new Set([...input.excluded, ...cooldowns.map((cooldown) => cooldown.accountId)]);
package/dist/pool.mjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"pool.mjs","names":[],"sources":["../src/pool.ts"],"sourcesContent":["import { Clock, Effect, Match, Predicate, Ref, Stream } from 'effect'\nimport {\n LLMError,\n type LLMEvent,\n type LLMProvider,\n type LLMProviderError,\n type LLMRequest\n} from '@yolk-sdk/agent/loop'\nimport { ProviderErrorInfo } from '@yolk-sdk/agent/protocol'\nimport type { ProviderSubscriptionUsageSnapshot } from '@yolk-sdk/agent/providers/subscription-usage'\nimport {\n PoolAuthCooldown,\n PoolConfigError,\n type PoolCooldown,\n PoolPin,\n PoolQuotaCooldown,\n type PoolStoreError,\n PoolUnknownAccountError\n} from './model.ts'\nimport {\n isCooldownActive,\n type PoolCandidate,\n type PoolDecision,\n type PoolReading,\n poolReadingFromSnapshot,\n poolRoute,\n rankPool,\n staleQuotaCooldowns\n} from './rank.ts'\nimport { type PoolStoreApi, type PoolStoreSnapshot, PoolStoredReading } from './store.ts'\n\ntype LLMProviderService = typeof LLMProvider.Service\n\n/** One subscription account of a pool: its own provider, built by the host with its credentials. */\nexport type PoolAccount = {\n /** Unique within the store; cooldowns and readings are keyed by it. */\n readonly id: string\n /** Breaks ranking ties and orders fill-first (higher first). Default 0. */\n readonly priority?: number\n readonly provider: LLMProviderService\n}\n\nexport type PoolOptions = {\n /** Pins are keyed by pool id and route. */\n readonly id: string\n /** Accounts of one provider; requests must suit every one of them. */\n readonly accounts: ReadonlyArray<PoolAccount>\n readonly store: PoolStoreApi\n /** How old a reading may be and still rank accounts. Default 30 minutes. */\n readonly maxAgeMs?: number\n /** Quota left untouched on every window, in percent (0 to below 100). Default 0. */\n readonly reservePercent?: number\n}\n\n/** One account as the host UI sees it. */\nexport type PoolAccountState = {\n readonly id: string\n readonly priority: number\n /** The account's cooldown while it is active. */\n readonly cooldown: PoolCooldown | undefined\n readonly reading: ProviderSubscriptionUsageSnapshot | undefined\n}\n\nexport type PoolState = {\n readonly poolId: string\n /** The account serving each route. */\n readonly pins: ReadonlyArray<PoolPin>\n readonly accounts: ReadonlyArray<PoolAccountState>\n}\n\nexport type Pool = {\n readonly id: string\n /** The pooled provider: provide it as the loop's `LLMProvider`, innermost under host wrappers. */\n readonly provider: LLMProviderService\n /** Records an account's usage snapshot; hosts poll usage on their own schedule. */\n readonly recordReading: (\n accountId: string,\n snapshot: ProviderSubscriptionUsageSnapshot\n ) => Effect.Effect<void, PoolUnknownAccountError | PoolStoreError>\n /** Pins, active cooldowns, and readings for host UIs. */\n readonly state: Effect.Effect<PoolState, PoolStoreError>\n}\n\n/** Default `maxAgeMs`: readings older than 30 minutes no longer rank accounts. */\nexport const defaultPoolMaxAgeMs = 30 * 60_000\n\n/**\n * A `rate_limit` whose `Retry-After` reaches this is a quota lockout, not a transient limit\n * (CLIProxyAPI `expiring-first` `QuotaCooldownFloor`).\n */\nexport const poolQuotaRetryAfterFloorMs = 30 * 60_000\n\n/** The longest cooldown the pool records; a later or non-finite hint is not trusted. */\nexport const poolMaxCooldownMs = 366 * 24 * 60 * 60_000\n\n/** How long an account whose credentials were rejected sits out. */\nexport const poolAuthCooldownMs = 30 * 60_000\n\ntype ValidAccount = PoolCandidate & { readonly provider: LLMProviderService }\n\nconst configError = (reason: PoolConfigError['reason'], message: string) =>\n Effect.fail(new PoolConfigError({ reason, message }))\n\n/**\n * The cooldown an account-scoped failure puts its account in, or undefined when the failure is not\n * the account's (the loop's retry handles those): a `rate_limit` with a quota reset or a\n * `Retry-After` of at least `poolQuotaRetryAfterFloorMs` (quota), or `auth`.\n */\nexport const poolFailureCooldown = (\n error: LLMError,\n accountId: string,\n nowMs: number\n): PoolCooldown | undefined => {\n const info = error.provider\n\n if (info === undefined) {\n return undefined\n }\n\n if (info.kind === 'auth') {\n return PoolAuthCooldown.make({\n accountId,\n startedAtMs: nowMs,\n untilMs: nowMs + poolAuthCooldownMs\n })\n }\n\n if (info.kind !== 'rate_limit') {\n return undefined\n }\n\n const trusted = (untilMs: number) =>\n Number.isFinite(untilMs) && untilMs > nowMs && untilMs - nowMs <= poolMaxCooldownMs\n\n if (info.quotaResetsAtMs !== undefined && trusted(info.quotaResetsAtMs)) {\n return PoolQuotaCooldown.make({ accountId, startedAtMs: nowMs, untilMs: info.quotaResetsAtMs })\n }\n\n if (\n info.retryAfterMs !== undefined &&\n info.retryAfterMs >= poolQuotaRetryAfterFloorMs &&\n trusted(nowMs + info.retryAfterMs)\n ) {\n return PoolQuotaCooldown.make({\n accountId,\n startedAtMs: nowMs,\n untilMs: nowMs + info.retryAfterMs\n })\n }\n\n return undefined\n}\n\nconst iso = (ms: number) => {\n const date = new Date(ms)\n\n return Number.isFinite(date.getTime()) ? date.toISOString() : String(ms)\n}\n\nconst minUntil = (cooldowns: ReadonlyArray<PoolCooldown>) =>\n cooldowns.reduce<number | undefined>(\n (earliest, cooldown) =>\n earliest === undefined || cooldown.untilMs < earliest ? cooldown.untilMs : earliest,\n undefined\n )\n\nconst emptySnapshot: PoolStoreSnapshot = { pin: undefined, cooldowns: [], readings: [] }\n\n/**\n * Pools several subscription accounts of one provider behind one `LLMProvider` (ADR 0011).\n *\n * Each request goes to the account whose longest usage window resets soonest and still has quota\n * (expiring-first), or, without fresh readings, stays on the route's pinned account. An\n * account-scoped failure before the first event (an exhausted quota, rejected credentials) cools the\n * account down and the same request moves to the next account; every other failure, and any failure\n * after an event, reaches the caller unchanged. With every account out it fails `rate_limit`\n * (non-retryable) carrying the earliest quota reset, or `auth` when only auth cooldowns remain.\n *\n * Store failures never fail a request: reads fall back to stateless fill-first and writes are\n * logged.\n */\nexport const makePool = (options: PoolOptions): Effect.Effect<Pool, PoolConfigError> =>\n Effect.gen(function* () {\n const poolId = options.id.trim()\n\n if (poolId === '') {\n return yield* configError('invalid_pool_id', 'Pool id must be a non-empty string')\n }\n\n if (options.accounts.length === 0) {\n return yield* configError('no_accounts', `Pool ${poolId} needs at least one account`)\n }\n\n const maxAgeMs = options.maxAgeMs ?? defaultPoolMaxAgeMs\n const reservePercent = options.reservePercent ?? 0\n\n if (!Number.isFinite(maxAgeMs) || maxAgeMs <= 0) {\n return yield* configError('invalid_max_age', 'maxAgeMs must be a positive number')\n }\n\n if (!Number.isFinite(reservePercent) || reservePercent < 0 || reservePercent >= 100) {\n return yield* configError(\n 'invalid_reserve_percent',\n 'reservePercent must be at least 0 and below 100'\n )\n }\n\n const accounts: Array<ValidAccount> = []\n\n for (const account of options.accounts) {\n const id = account.id.trim()\n const priority = account.priority ?? 0\n\n if (id === '' || id !== account.id) {\n return yield* configError(\n 'invalid_account_id',\n 'Account ids must be non-empty without surrounding whitespace'\n )\n }\n\n if (accounts.some(existing => existing.id === id)) {\n return yield* configError('duplicate_account_id', `Duplicate account id: ${id}`)\n }\n\n if (!Number.isFinite(priority)) {\n return yield* configError('invalid_priority', `Account ${id} has a non-finite priority`)\n }\n\n accounts.push({ id, priority, provider: account.provider })\n }\n\n const accountIds = accounts.map(account => account.id)\n const accountsById = new Map(accounts.map(account => [account.id, account]))\n const store = options.store\n\n const loadSnapshot = (route: string) =>\n store\n .load({ poolId, route, accountIds })\n .pipe(\n Effect.catch(error =>\n Effect.logWarning('pool: store load failed; routing without pool state').pipe(\n Effect.annotateLogs({ operation: error.operation }),\n Effect.as(emptySnapshot)\n )\n )\n )\n\n // Host store messages may carry connection details: log the operation only.\n const logStoreFailure = (operation: PoolStoreError['operation']) => () =>\n Effect.logWarning(`pool: store ${operation} failed`)\n\n const readingsOf = (snapshot: PoolStoreSnapshot) => {\n const readings = new Map<string, PoolReading>()\n\n for (const stored of snapshot.readings) {\n const reading = poolReadingFromSnapshot(stored.snapshot)\n\n if (reading !== undefined) {\n readings.set(stored.accountId, reading)\n }\n }\n\n return readings\n }\n\n const moveReason = (input: {\n readonly decision: PoolDecision\n readonly from: string\n readonly cooldowns: ReadonlyArray<PoolCooldown>\n readonly excluded: ReadonlySet<string>\n }) =>\n Match.value(input.decision).pipe(\n Match.tag('Quota', decision =>\n decision.resetsAtMs === undefined\n ? 'quota ranking, window not started'\n : `quota ranking, window resets ${iso(decision.resetsAtMs)}`\n ),\n Match.orElse(() => {\n const cooldown = input.cooldowns.find(current => current.accountId === input.from)\n\n if (cooldown !== undefined) {\n return Match.value(cooldown).pipe(\n Match.tag(\n 'PoolQuotaCooldown',\n current => `quota cooldown until ${iso(current.untilMs)}`\n ),\n Match.tag(\n 'PoolAuthCooldown',\n current => `auth cooldown until ${iso(current.untilMs)}`\n ),\n Match.exhaustive\n )\n }\n\n if (input.excluded.has(input.from)) {\n return 'failed this request'\n }\n\n return accountsById.has(input.from)\n ? 'a fresh reading shows it used up'\n : 'not configured'\n })\n )\n\n const updatePin = (input: {\n readonly route: string\n readonly decision: PoolDecision\n readonly snapshot: PoolStoreSnapshot\n readonly cooldowns: ReadonlyArray<PoolCooldown>\n readonly excluded: ReadonlySet<string>\n readonly nowMs: number\n }) => {\n const current = input.snapshot.pin?.accountId\n const next = input.decision.accountId\n\n if (current === next) {\n return Effect.void\n }\n\n const pin = PoolPin.make({\n poolId,\n route: input.route,\n accountId: next,\n pinnedAtMs: input.nowMs\n })\n\n const log =\n current === undefined\n ? Effect.logDebug('pool: route pinned').pipe(Effect.annotateLogs({ to: next }))\n : Effect.logInfo(\n `pool: pin moved: ${moveReason({\n decision: input.decision,\n from: current,\n cooldowns: input.cooldowns,\n excluded: input.excluded\n })}`\n ).pipe(Effect.annotateLogs({ from: current, to: next }))\n\n return store.movePin({ expected: current, pin }).pipe(\n Effect.flatMap(written => (written ? log : Effect.void)),\n Effect.catch(logStoreFailure('movePin'))\n )\n }\n\n const exhaustedError = (input: {\n /** Cooldowns still active at the final pick. */\n readonly active: ReadonlyArray<PoolCooldown>\n /** Every cooldown that put an account out, including ones this request recorded that ran out. */\n readonly all: ReadonlyArray<PoolCooldown>\n readonly lastError: LLMError | undefined\n }) => {\n const isQuota = (cooldown: PoolCooldown) => Predicate.isTagged(cooldown, 'PoolQuotaCooldown')\n const quotaResetsAtMs = minUntil(input.active.filter(isQuota))\n const until = minUntil(input.active)\n // The vendor id of the last failure; the pool id when no account was tried in this request.\n const provider = input.lastError?.provider?.provider ?? poolId\n\n const message =\n until === undefined\n ? `Every account of pool ${poolId} is unavailable`\n : `Every account of pool ${poolId} is unavailable until ${iso(until)}`\n\n if (!input.all.some(isQuota)) {\n return new LLMError({\n cause: 'provider_error',\n message,\n retryable: false,\n provider: ProviderErrorInfo.make({ provider, kind: 'auth' })\n })\n }\n\n return new LLMError({\n cause: 'rate_limit',\n message,\n retryable: false,\n provider:\n quotaResetsAtMs === undefined\n ? ProviderErrorInfo.make({ provider, kind: 'rate_limit' })\n : ProviderErrorInfo.make({ provider, kind: 'rate_limit', quotaResetsAtMs })\n })\n }\n\n const attempt = (input: {\n readonly request: LLMRequest\n readonly route: string\n readonly account: ValidAccount\n readonly excluded: ReadonlySet<string>\n readonly recorded: ReadonlyArray<PoolCooldown>\n }): Stream.Stream<LLMEvent, LLMProviderError> =>\n Stream.unwrap(\n Ref.make(false).pipe(\n Effect.map(emitted =>\n input.account.provider.stream(input.request).pipe(\n Stream.tap(() => Ref.set(emitted, true)),\n Stream.catchTags({\n LLMError: error =>\n Stream.unwrap(\n Effect.gen(function* () {\n const nowMs = yield* Clock.currentTimeMillis\n const cooldown = poolFailureCooldown(error, input.account.id, nowMs)\n\n if ((yield* Ref.get(emitted)) || cooldown === undefined) {\n return Stream.fail(error)\n }\n\n yield* store\n .putCooldown(cooldown)\n .pipe(Effect.catch(logStoreFailure('putCooldown')))\n yield* Effect.logInfo(\n `pool: failover after ${Predicate.isTagged(cooldown, 'PoolQuotaCooldown') ? 'quota exhaustion' : 'auth failure'}, cooldown until ${iso(cooldown.untilMs)}`\n ).pipe(Effect.annotateLogs({ account: input.account.id }))\n\n return pick({\n request: input.request,\n route: input.route,\n excluded: new Set([...input.excluded, input.account.id]),\n recorded: [...input.recorded, cooldown],\n lastError: error\n })\n })\n )\n })\n )\n )\n )\n )\n\n const pick = (input: {\n readonly request: LLMRequest\n readonly route: string\n readonly excluded: ReadonlySet<string>\n readonly recorded: ReadonlyArray<PoolCooldown>\n readonly lastError: LLMError | undefined\n }): Stream.Stream<LLMEvent, LLMProviderError> =>\n Stream.unwrap(\n Effect.gen(function* () {\n const nowMs = yield* Clock.currentTimeMillis\n const snapshot = yield* loadSnapshot(input.route)\n const readings = readingsOf(snapshot)\n\n const stale = staleQuotaCooldowns({\n cooldowns: snapshot.cooldowns,\n readings,\n nowMs,\n maxAgeMs\n })\n\n yield* Effect.forEach(\n stale,\n cooldown =>\n store\n .clearCooldown({ accountId: cooldown.accountId, startedAtMs: cooldown.startedAtMs })\n .pipe(\n Effect.flatMap(cleared =>\n cleared\n ? Effect.logInfo(\n `pool: cleared cooldown (until ${iso(cooldown.untilMs)}): a newer reading shows quota left`\n ).pipe(Effect.annotateLogs({ account: cooldown.accountId }))\n : Effect.void\n ),\n Effect.catch(logStoreFailure('clearCooldown'))\n ),\n { discard: true }\n )\n\n const cooldowns = [\n ...snapshot.cooldowns.filter(\n cooldown => isCooldownActive(cooldown, nowMs) && !stale.includes(cooldown)\n ),\n ...input.recorded.filter(cooldown => isCooldownActive(cooldown, nowMs))\n ]\n\n const unavailable = new Set([\n ...input.excluded,\n ...cooldowns.map(cooldown => cooldown.accountId)\n ])\n\n const decision = rankPool({\n accounts,\n unavailable,\n readings,\n pin: snapshot.pin?.accountId,\n route: input.route,\n nowMs,\n maxAgeMs,\n reservePercent\n })\n\n const account = decision === undefined ? undefined : accountsById.get(decision.accountId)\n\n if (decision === undefined || account === undefined) {\n yield* Effect.logWarning('pool: every account is unavailable')\n\n return Stream.fail(\n exhaustedError({\n active: cooldowns,\n // Cooldowns recorded by this request decide the kind even if they already ran out.\n all: [\n ...cooldowns,\n ...input.recorded.filter(cooldown => !cooldowns.includes(cooldown))\n ],\n lastError: input.lastError\n })\n )\n }\n\n yield* updatePin({\n route: input.route,\n decision,\n snapshot,\n cooldowns,\n excluded: input.excluded,\n nowMs\n })\n yield* Effect.annotateCurrentSpan({ account: account.id, source: decision._tag })\n\n return attempt({\n request: input.request,\n route: input.route,\n account,\n excluded: input.excluded,\n recorded: input.recorded\n })\n }).pipe(\n Effect.withSpan('pool.pick', { attributes: { pool: poolId, route: input.route } }),\n Effect.annotateLogs({ pool: poolId, route: input.route })\n )\n )\n\n const provider: LLMProviderService = {\n stream: request => {\n const route = poolRoute(request.model)\n\n return route === ''\n ? Stream.fail(\n new LLMError({\n cause: 'validation_error',\n message: `Pool ${poolId} needs a model id`,\n retryable: false\n })\n )\n : pick({ request, route, excluded: new Set(), recorded: [], lastError: undefined })\n }\n }\n\n const recordReading = (accountId: string, snapshot: ProviderSubscriptionUsageSnapshot) =>\n accountsById.has(accountId)\n ? store.putReading(PoolStoredReading.make({ accountId, snapshot }))\n : Effect.fail(new PoolUnknownAccountError({ poolId, accountId }))\n\n const state = Effect.gen(function* () {\n const nowMs = yield* Clock.currentTimeMillis\n const stored = yield* store.state({ poolId, accountIds })\n\n return {\n poolId,\n pins: stored.pins,\n accounts: accounts.map(account => ({\n id: account.id,\n priority: account.priority,\n cooldown: stored.cooldowns.find(\n cooldown => cooldown.accountId === account.id && isCooldownActive(cooldown, nowMs)\n ),\n reading: stored.readings.find(reading => reading.accountId === account.id)?.snapshot\n }))\n }\n })\n\n return { id: poolId, provider, recordReading, state }\n })\n"],"mappings":"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"}
1
+ {"version":3,"file":"pool.mjs","names":[],"sources":["../src/pool.ts"],"sourcesContent":["import { Clock, Effect, Match, Predicate, Ref, Stream } from 'effect'\nimport {\n LLMError,\n type LLMEvent,\n type LLMProvider,\n type LLMProviderError,\n type LLMRequest\n} from '@yolk-sdk/agent/loop'\nimport { ProviderErrorInfo } from '@yolk-sdk/agent/protocol'\nimport type { ProviderSubscriptionUsageSnapshot } from '@yolk-sdk/agent/providers/subscription-usage'\nimport {\n PoolAuthCooldown,\n PoolConfigError,\n type PoolCooldown,\n PoolPin,\n PoolQuotaCooldown,\n type PoolStoreError,\n PoolUnknownAccountError\n} from './model.ts'\nimport {\n isCooldownActive,\n type PoolCandidate,\n type PoolDecision,\n type PoolReading,\n poolReadingFromSnapshot,\n poolRoute,\n rankPool,\n staleQuotaCooldowns\n} from './rank.ts'\nimport { type PoolStoreApi, type PoolStoreSnapshot, PoolStoredReading } from './store.ts'\n\ntype LLMProviderService = typeof LLMProvider.Service\n\n/** One subscription account of a pool: its own provider, built by the host with its credentials. */\nexport type PoolAccount = {\n /** Unique within the store; cooldowns and readings are keyed by it. */\n readonly id: string\n /** Breaks ranking ties and orders fill-first (higher first). Default 0. */\n readonly priority?: number\n readonly provider: LLMProviderService\n}\n\nexport type PoolOptions = {\n /** Pins are keyed by pool id and route. */\n readonly id: string\n /** Accounts of one provider; requests must suit every one of them. */\n readonly accounts: ReadonlyArray<PoolAccount>\n readonly store: PoolStoreApi\n /** How old a reading may be and still rank accounts. Default 30 minutes. */\n readonly maxAgeMs?: number\n /** Quota left untouched on every window, in percent (0 to below 100). Default 0. */\n readonly reservePercent?: number\n}\n\n/** One account as the host UI sees it. */\nexport type PoolAccountState = {\n readonly id: string\n readonly priority: number\n /** The account's cooldown while it is active. */\n readonly cooldown: PoolCooldown | undefined\n readonly reading: ProviderSubscriptionUsageSnapshot | undefined\n}\n\nexport type PoolState = {\n readonly poolId: string\n /** The account serving each route. */\n readonly pins: ReadonlyArray<PoolPin>\n readonly accounts: ReadonlyArray<PoolAccountState>\n}\n\nexport type Pool = {\n readonly id: string\n /** The pooled provider: provide it as the loop's `LLMProvider`, innermost under host wrappers. */\n readonly provider: LLMProviderService\n /** Records an account's usage snapshot; hosts poll usage on their own schedule. */\n readonly recordReading: (\n accountId: string,\n snapshot: ProviderSubscriptionUsageSnapshot\n ) => Effect.Effect<void, PoolUnknownAccountError | PoolStoreError>\n /** Pins, active cooldowns, and readings for host UIs. */\n readonly state: Effect.Effect<PoolState, PoolStoreError>\n}\n\n/** Default `maxAgeMs`: readings older than 30 minutes no longer rank accounts. */\nexport const defaultPoolMaxAgeMs = 30 * 60_000\n\n/**\n * A `rate_limit` whose `Retry-After` reaches this is a quota lockout, not a transient limit\n * (CLIProxyAPI `expiring-first` `QuotaCooldownFloor`).\n */\nexport const poolQuotaRetryAfterFloorMs = 30 * 60_000\n\n/** The longest cooldown the pool records; a later or non-finite hint is not trusted. */\nexport const poolMaxCooldownMs = 366 * 24 * 60 * 60_000\n\n/** How long an account whose credentials were rejected sits out. */\nexport const poolAuthCooldownMs = 30 * 60_000\n\ntype ValidAccount = PoolCandidate & { readonly provider: LLMProviderService }\n\nconst configError = (reason: PoolConfigError['reason'], message: string) =>\n Effect.fail(new PoolConfigError({ reason, message }))\n\n/**\n * The cooldown an account-scoped failure puts its account in, or undefined when the failure is not\n * the account's (the loop's retry handles those): a `rate_limit` with a quota reset or a\n * `Retry-After` of at least `poolQuotaRetryAfterFloorMs` (quota), or `auth`.\n */\nexport const poolFailureCooldown = (\n error: LLMError,\n accountId: string,\n nowMs: number\n): PoolCooldown | undefined => {\n const info = error.provider\n\n if (info === undefined) {\n return undefined\n }\n\n if (info.kind === 'auth') {\n return PoolAuthCooldown.make({\n accountId,\n startedAtMs: nowMs,\n untilMs: nowMs + poolAuthCooldownMs\n })\n }\n\n if (info.kind !== 'rate_limit') {\n return undefined\n }\n\n const trusted = (untilMs: number) =>\n Number.isFinite(untilMs) && untilMs > nowMs && untilMs - nowMs <= poolMaxCooldownMs\n\n if (info.quotaResetsAtMs !== undefined && trusted(info.quotaResetsAtMs)) {\n return PoolQuotaCooldown.make({ accountId, startedAtMs: nowMs, untilMs: info.quotaResetsAtMs })\n }\n\n if (\n info.retryAfterMs !== undefined &&\n info.retryAfterMs >= poolQuotaRetryAfterFloorMs &&\n trusted(nowMs + info.retryAfterMs)\n ) {\n return PoolQuotaCooldown.make({\n accountId,\n startedAtMs: nowMs,\n untilMs: nowMs + info.retryAfterMs\n })\n }\n\n return undefined\n}\n\nconst iso = (ms: number) => {\n const date = new Date(ms)\n\n return Number.isFinite(date.getTime()) ? date.toISOString() : String(ms)\n}\n\nconst minUntil = (cooldowns: ReadonlyArray<PoolCooldown>) =>\n cooldowns.reduce<number | undefined>(\n (earliest, cooldown) =>\n earliest === undefined || cooldown.untilMs < earliest ? cooldown.untilMs : earliest,\n undefined\n )\n\nconst emptySnapshot: PoolStoreSnapshot = { pin: undefined, cooldowns: [], readings: [] }\n\n/**\n * Pools several subscription accounts of one provider behind one `LLMProvider` (ADR 0011).\n *\n * Each request goes to the account whose longest usage window resets soonest and still has quota\n * (expiring-first), or, without fresh readings, stays on the route's pinned account. An\n * account-scoped failure before the first event (an exhausted quota, rejected credentials) cools the\n * account down and the same request moves to the next account; every other failure, and any failure\n * after an event, reaches the caller unchanged. With every account out it fails `rate_limit`\n * (non-retryable) carrying the earliest quota reset, or `auth` when only auth cooldowns remain.\n *\n * Store failures never fail a request: reads fall back to stateless fill-first and writes are\n * logged.\n */\nexport const makePool = (options: PoolOptions): Effect.Effect<Pool, PoolConfigError> =>\n Effect.gen(function* () {\n const poolId = options.id.trim()\n\n if (poolId === '') {\n return yield* configError('invalid_pool_id', 'Pool id must be a non-empty string')\n }\n\n if (options.accounts.length === 0) {\n return yield* configError('no_accounts', `Pool ${poolId} needs at least one account`)\n }\n\n const maxAgeMs = options.maxAgeMs ?? defaultPoolMaxAgeMs\n const reservePercent = options.reservePercent ?? 0\n\n if (!Number.isFinite(maxAgeMs) || maxAgeMs <= 0) {\n return yield* configError('invalid_max_age', 'maxAgeMs must be a positive number')\n }\n\n if (!Number.isFinite(reservePercent) || reservePercent < 0 || reservePercent >= 100) {\n return yield* configError(\n 'invalid_reserve_percent',\n 'reservePercent must be at least 0 and below 100'\n )\n }\n\n const accounts: Array<ValidAccount> = []\n\n for (const account of options.accounts) {\n const id = account.id.trim()\n const priority = account.priority ?? 0\n\n if (id === '' || id !== account.id) {\n return yield* configError(\n 'invalid_account_id',\n 'Account ids must be non-empty without surrounding whitespace'\n )\n }\n\n if (accounts.some(existing => existing.id === id)) {\n return yield* configError('duplicate_account_id', `Duplicate account id: ${id}`)\n }\n\n if (!Number.isFinite(priority)) {\n return yield* configError('invalid_priority', `Account ${id} has a non-finite priority`)\n }\n\n accounts.push({ id, priority, provider: account.provider })\n }\n\n const accountIds = accounts.map(account => account.id)\n const accountsById = new Map(accounts.map(account => [account.id, account]))\n const store = options.store\n\n const loadSnapshot = (route: string) =>\n store\n .load({ poolId, route, accountIds })\n .pipe(\n Effect.catch(error =>\n Effect.logWarning('pool: store load failed; routing without pool state').pipe(\n Effect.annotateLogs({ operation: error.operation }),\n Effect.as(emptySnapshot)\n )\n )\n )\n\n // Host store messages may carry connection details: log the operation only.\n const logStoreFailure = (operation: PoolStoreError['operation']) => () =>\n Effect.logWarning(`pool: store ${operation} failed`)\n\n const readingsOf = (snapshot: PoolStoreSnapshot) => {\n const readings = new Map<string, PoolReading>()\n\n for (const stored of snapshot.readings) {\n const reading = poolReadingFromSnapshot(stored.snapshot)\n\n if (reading !== undefined) {\n readings.set(stored.accountId, reading)\n }\n }\n\n return readings\n }\n\n const moveReason = (input: {\n readonly decision: PoolDecision\n readonly from: string\n readonly cooldowns: ReadonlyArray<PoolCooldown>\n readonly excluded: ReadonlySet<string>\n }) =>\n Match.value(input.decision).pipe(\n Match.tag('Quota', decision =>\n decision.resetsAtMs === undefined\n ? 'quota ranking, window not started'\n : `quota ranking, window resets ${iso(decision.resetsAtMs)}`\n ),\n Match.orElse(() => {\n const cooldown = input.cooldowns.find(current => current.accountId === input.from)\n\n if (cooldown !== undefined) {\n return Match.value(cooldown).pipe(\n Match.tag(\n 'PoolQuotaCooldown',\n current => `quota cooldown until ${iso(current.untilMs)}`\n ),\n Match.tag(\n 'PoolAuthCooldown',\n current => `auth cooldown until ${iso(current.untilMs)}`\n ),\n Match.exhaustive\n )\n }\n\n if (input.excluded.has(input.from)) {\n return 'failed this request'\n }\n\n return accountsById.has(input.from)\n ? 'a fresh reading shows it used up'\n : 'not configured'\n })\n )\n\n const updatePin = (input: {\n readonly route: string\n readonly decision: PoolDecision\n readonly snapshot: PoolStoreSnapshot\n readonly cooldowns: ReadonlyArray<PoolCooldown>\n readonly excluded: ReadonlySet<string>\n readonly nowMs: number\n }) => {\n const current = input.snapshot.pin?.accountId\n const next = input.decision.accountId\n\n if (current === next) {\n return Effect.void\n }\n\n const pin = PoolPin.make({\n poolId,\n route: input.route,\n accountId: next,\n pinnedAtMs: input.nowMs\n })\n\n const log =\n current === undefined\n ? Effect.logDebug('pool: route pinned').pipe(Effect.annotateLogs({ to: next }))\n : Effect.logInfo(\n `pool: pin moved: ${moveReason({\n decision: input.decision,\n from: current,\n cooldowns: input.cooldowns,\n excluded: input.excluded\n })}`\n ).pipe(Effect.annotateLogs({ from: current, to: next }))\n\n return store.movePin({ expected: current, pin }).pipe(\n Effect.flatMap(written => (written ? log : Effect.void)),\n Effect.catch(logStoreFailure('movePin'))\n )\n }\n\n const exhaustedError = (input: {\n /** Cooldowns still active at the final pick. */\n readonly active: ReadonlyArray<PoolCooldown>\n /** Every cooldown that put an account out, including ones this request recorded that ran out. */\n readonly all: ReadonlyArray<PoolCooldown>\n readonly lastError: LLMError | undefined\n }) => {\n const isQuota = (cooldown: PoolCooldown) => Predicate.isTagged(cooldown, 'PoolQuotaCooldown')\n const quotaResetsAtMs = minUntil(input.active.filter(isQuota))\n const until = minUntil(input.active)\n // The vendor id of the last failure; the pool id when no account was tried in this request.\n const provider = input.lastError?.provider?.provider ?? poolId\n\n const message =\n until === undefined\n ? `Every account of pool ${poolId} is unavailable`\n : `Every account of pool ${poolId} is unavailable until ${iso(until)}`\n\n if (!input.all.some(isQuota)) {\n return new LLMError({\n cause: 'provider_error',\n message,\n retryable: false,\n provider: ProviderErrorInfo.make({ provider, kind: 'auth' })\n })\n }\n\n return new LLMError({\n cause: 'rate_limit',\n message,\n retryable: false,\n provider:\n quotaResetsAtMs === undefined\n ? ProviderErrorInfo.make({ provider, kind: 'rate_limit' })\n : ProviderErrorInfo.make({ provider, kind: 'rate_limit', quotaResetsAtMs })\n })\n }\n\n const attempt = (input: {\n readonly request: LLMRequest\n readonly route: string\n readonly account: ValidAccount\n readonly excluded: ReadonlySet<string>\n readonly recorded: ReadonlyArray<PoolCooldown>\n }): Stream.Stream<LLMEvent, LLMProviderError> =>\n Stream.unwrap(\n Ref.make(false).pipe(\n Effect.map(emitted =>\n input.account.provider.stream(input.request).pipe(\n Stream.tap(() => Ref.set(emitted, true)),\n Stream.catchTags({\n LLMError: error =>\n Stream.unwrap(\n Effect.gen(function* () {\n const nowMs = yield* Clock.currentTimeMillis\n const cooldown = poolFailureCooldown(error, input.account.id, nowMs)\n\n if ((yield* Ref.get(emitted)) || cooldown === undefined) {\n return Stream.fail(error)\n }\n\n yield* store\n .putCooldown(cooldown)\n .pipe(Effect.catch(logStoreFailure('putCooldown')))\n yield* Effect.logInfo(\n `pool: failover after ${Predicate.isTagged(cooldown, 'PoolQuotaCooldown') ? 'quota exhaustion' : 'auth failure'}, cooldown until ${iso(cooldown.untilMs)}`\n ).pipe(Effect.annotateLogs({ account: input.account.id }))\n\n return pick({\n request: input.request,\n route: input.route,\n excluded: new Set([...input.excluded, input.account.id]),\n recorded: [...input.recorded, cooldown],\n lastError: error\n })\n })\n )\n })\n )\n )\n )\n )\n\n const pick = (input: {\n readonly request: LLMRequest\n readonly route: string\n readonly excluded: ReadonlySet<string>\n readonly recorded: ReadonlyArray<PoolCooldown>\n readonly lastError: LLMError | undefined\n }): Stream.Stream<LLMEvent, LLMProviderError> =>\n Stream.unwrap(\n Effect.gen(function* () {\n const nowMs = yield* Clock.currentTimeMillis\n const snapshot = yield* loadSnapshot(input.route)\n const readings = readingsOf(snapshot)\n\n const stale = staleQuotaCooldowns({\n cooldowns: snapshot.cooldowns,\n readings,\n nowMs,\n maxAgeMs\n })\n\n yield* Effect.forEach(\n stale,\n cooldown =>\n store\n .clearCooldown({\n accountId: cooldown.accountId,\n startedAtMs: cooldown.startedAtMs,\n authUntilMs: Predicate.isTagged(cooldown, 'PoolQuotaCooldown')\n ? cooldown.authUntilMs\n : undefined\n })\n .pipe(\n Effect.flatMap(cleared =>\n cleared\n ? Effect.logInfo(\n `pool: cleared cooldown (until ${iso(cooldown.untilMs)}): a newer reading shows quota left`\n ).pipe(Effect.annotateLogs({ account: cooldown.accountId }))\n : Effect.void\n ),\n Effect.catch(logStoreFailure('clearCooldown'))\n ),\n { discard: true }\n )\n\n const cooldowns = [\n ...snapshot.cooldowns.filter(\n cooldown => isCooldownActive(cooldown, nowMs) && !stale.includes(cooldown)\n ),\n ...input.recorded.filter(cooldown => isCooldownActive(cooldown, nowMs))\n ]\n\n const unavailable = new Set([\n ...input.excluded,\n ...cooldowns.map(cooldown => cooldown.accountId)\n ])\n\n const decision = rankPool({\n accounts,\n unavailable,\n readings,\n pin: snapshot.pin?.accountId,\n route: input.route,\n nowMs,\n maxAgeMs,\n reservePercent\n })\n\n const account = decision === undefined ? undefined : accountsById.get(decision.accountId)\n\n if (decision === undefined || account === undefined) {\n yield* Effect.logWarning('pool: every account is unavailable')\n\n return Stream.fail(\n exhaustedError({\n active: cooldowns,\n // Cooldowns recorded by this request decide the kind even if they already ran out.\n all: [\n ...cooldowns,\n ...input.recorded.filter(cooldown => !cooldowns.includes(cooldown))\n ],\n lastError: input.lastError\n })\n )\n }\n\n yield* updatePin({\n route: input.route,\n decision,\n snapshot,\n cooldowns,\n excluded: input.excluded,\n nowMs\n })\n yield* Effect.annotateCurrentSpan({ account: account.id, source: decision._tag })\n\n return attempt({\n request: input.request,\n route: input.route,\n account,\n excluded: input.excluded,\n recorded: input.recorded\n })\n }).pipe(\n Effect.withSpan('pool.pick', { attributes: { pool: poolId, route: input.route } }),\n Effect.annotateLogs({ pool: poolId, route: input.route })\n )\n )\n\n const provider: LLMProviderService = {\n stream: request => {\n const route = poolRoute(request.model)\n\n return route === ''\n ? Stream.fail(\n new LLMError({\n cause: 'validation_error',\n message: `Pool ${poolId} needs a model id`,\n retryable: false\n })\n )\n : pick({ request, route, excluded: new Set(), recorded: [], lastError: undefined })\n }\n }\n\n const recordReading = (accountId: string, snapshot: ProviderSubscriptionUsageSnapshot) =>\n accountsById.has(accountId)\n ? store.putReading(PoolStoredReading.make({ accountId, snapshot }))\n : Effect.fail(new PoolUnknownAccountError({ poolId, accountId }))\n\n const state = Effect.gen(function* () {\n const nowMs = yield* Clock.currentTimeMillis\n const stored = yield* store.state({ poolId, accountIds })\n\n return {\n poolId,\n pins: stored.pins,\n accounts: accounts.map(account => ({\n id: account.id,\n priority: account.priority,\n cooldown: stored.cooldowns.find(\n cooldown => cooldown.accountId === account.id && isCooldownActive(cooldown, nowMs)\n ),\n reading: stored.readings.find(reading => reading.accountId === account.id)?.snapshot\n }))\n }\n })\n\n return { id: poolId, provider, recordReading, state }\n })\n"],"mappings":"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"}
package/dist/rank.d.mts CHANGED
@@ -85,7 +85,8 @@ export declare const isCooldownActive: (cooldown: PoolCooldown, nowMs: number) =
85
85
  /**
86
86
  * Active quota cooldowns that a fresh reading taken after they began shows to be over (a limit
87
87
  * reset was spent, or the provider reset early). A reading from before the lockout never clears
88
- * one, and auth cooldowns are never cleared by readings.
88
+ * one, nor one whose absorbed auth failure (`authUntilMs`) is still active, and auth cooldowns are
89
+ * never cleared by readings: a reading proves nothing about a rejected credential.
89
90
  */
90
91
  export declare const staleQuotaCooldowns: (input: {
91
92
  readonly cooldowns: ReadonlyArray<PoolCooldown>;
@@ -1 +1 @@
1
- {"version":3,"file":"rank.d.mts","names":[],"sources":["../src/rank.ts"],"mappings":";;;;YAKY;;WAED;WACA;;WAEA;;WAEA,QAAQ;;;YAMP;WACD;WACA,SAAS,cAAc;;;YAItB;WACD;WACA;;;;;;qBAOE,YAAS;;;;;;qBAOT,0BAAuB,UACxB,sCACT;;YAsCS,eAAe,KAAK;;EAE9B;aAAkB;aAA4B;;;EAE9C;aAAmB;;;EAEnB;aAAsB;;;qBAGX,cAAY,KAAA,WAAA;;WAHU;;;WAJJ;WAA6B;;;WAE5B;;YAOpB;;WAED,UAAU,cAAc;;WAExB,aAAa;WACb,UAAU,oBAAoB;;WAE9B;WACA;WACA;WACA;WACA;;;;;;;;;qBAkHE,WAAQ,OAAW,kBAAgB;;qBA+CnC,mBAAgB,UAAc,cAAY;;;;;;qBAqB1C,sBAAmB;WACrB,WAAW,cAAc;WACzB,UAAU,oBAAoB;WAC9B;WACA;MACP,cAAc"}
1
+ {"version":3,"file":"rank.d.mts","names":[],"sources":["../src/rank.ts"],"mappings":";;;;YAKY;;WAED;WACA;;WAEA;;WAEA,QAAQ;;;YAMP;WACD;WACA,SAAS,cAAc;;;YAItB;WACD;WACA;;;;;;qBAOE,YAAS;;;;;;qBAOT,0BAAuB,UACxB,sCACT;;YAsCS,eAAe,KAAK;;EAE9B;aAAkB;aAA4B;;;EAE9C;aAAmB;;;EAEnB;aAAsB;;;qBAGX,cAAY,KAAA,WAAA;;WAHU;;;WAJJ;WAA6B;;;WAE5B;;YAOpB;;WAED,UAAU,cAAc;;WAExB,aAAa;WACb,UAAU,oBAAoB;;WAE9B;WACA;WACA;WACA;WACA;;;;;;;;;qBAkHE,WAAQ,OAAW,kBAAgB;;qBA+CnC,mBAAgB,UAAc,cAAY;;;;;;;qBAsB1C,sBAAmB;WACrB,WAAW,cAAc;WACzB,UAAU,oBAAoB;WAC9B;WACA;MACP,cAAc"}
package/dist/rank.mjs CHANGED
@@ -126,10 +126,11 @@ const hasQuotaLeft = (reading, nowMs) => {
126
126
  /**
127
127
  * Active quota cooldowns that a fresh reading taken after they began shows to be over (a limit
128
128
  * reset was spent, or the provider reset early). A reading from before the lockout never clears
129
- * one, and auth cooldowns are never cleared by readings.
129
+ * one, nor one whose absorbed auth failure (`authUntilMs`) is still active, and auth cooldowns are
130
+ * never cleared by readings: a reading proves nothing about a rejected credential.
130
131
  */
131
132
  const staleQuotaCooldowns = (input) => input.cooldowns.filter((cooldown) => {
132
- if (!Predicate.isTagged(cooldown, "PoolQuotaCooldown") || !isCooldownActive(cooldown, input.nowMs)) return false;
133
+ if (!Predicate.isTagged(cooldown, "PoolQuotaCooldown") || !isCooldownActive(cooldown, input.nowMs) || cooldown.authUntilMs !== void 0 && cooldown.authUntilMs > input.nowMs) return false;
133
134
  const reading = input.readings.get(cooldown.accountId);
134
135
  return reading !== void 0 && input.nowMs - reading.fetchedAtMs <= input.maxAgeMs && reading.fetchedAtMs > cooldown.startedAtMs && hasQuotaLeft(reading, input.nowMs);
135
136
  });
package/dist/rank.mjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"rank.mjs","names":[],"sources":["../src/rank.ts"],"sourcesContent":["import { Data, Predicate } from 'effect'\nimport type { ProviderSubscriptionUsageSnapshot } from '@yolk-sdk/agent/providers/subscription-usage'\nimport type { PoolCooldown } from './model.ts'\n\n/** One usage window of a reading, as the ranking reads it. */\nexport type PoolWindow = {\n /** Window length; absent when the provider's window has no fixed length (a billing month). */\n readonly durationMinutes?: number\n readonly usedPercent: number\n /** When the window resets; absent when it has not started. */\n readonly resetsAtMs?: number\n /** Lowercase model substrings the window limits; empty for every model. */\n readonly models: ReadonlyArray<string>\n}\n\ntype MutablePoolWindow = { -readonly [Key in keyof PoolWindow]: PoolWindow[Key] }\n\n/** The latest quota reading of one account. */\nexport type PoolReading = {\n readonly fetchedAtMs: number\n readonly windows: ReadonlyArray<PoolWindow>\n}\n\n/** A configured account as the ranking sees it. */\nexport type PoolCandidate = {\n readonly id: string\n readonly priority: number\n}\n\n/**\n * The route a request pins: its model id, trimmed and lowercased. Reasoning effort is a separate\n * request field and never part of the route.\n */\nexport const poolRoute = (model: string) => model.trim().toLowerCase()\n\n/**\n * A usage snapshot as the ranking reads it; an unreadable `fetchedAt` yields no reading. Windows\n * without a length still block a used-up account but never rank it. A window that reports only\n * `resetsAfterSeconds` resets that long after the reading.\n */\nexport const poolReadingFromSnapshot = (\n snapshot: ProviderSubscriptionUsageSnapshot\n): PoolReading | undefined => {\n const fetchedAtMs = Date.parse(snapshot.fetchedAt)\n\n if (!Number.isFinite(fetchedAtMs)) {\n return undefined\n }\n\n const windows = Array.from(snapshot.windows).map((window): PoolWindow => {\n const resetsAtMs =\n window.resetsAt !== undefined\n ? Date.parse(window.resetsAt)\n : window.resetsAfterSeconds !== undefined\n ? fetchedAtMs + window.resetsAfterSeconds * 1000\n : Number.NaN\n\n const models = (window.models ?? []).flatMap(model => {\n const normalized = model.trim().toLowerCase()\n\n return normalized === '' ? [] : [normalized]\n })\n\n const fields: MutablePoolWindow = { usedPercent: window.usedPercent, models }\n\n if (window.windowDurationMinutes !== undefined) {\n fields.durationMinutes = window.windowDurationMinutes\n }\n\n if (Number.isFinite(resetsAtMs)) {\n fields.resetsAtMs = resetsAtMs\n }\n\n return fields\n })\n\n return { fetchedAtMs, windows }\n}\n\n/** Why the ranking chose an account. */\nexport type PoolDecision = Data.TaggedEnum<{\n /** Fresh readings ranked it first; `resetsAtMs` is its longest window's reset, if started. */\n Quota: { readonly accountId: string; readonly resetsAtMs: number | undefined }\n /** No candidate is usable by a fresh reading; the route's pin is still available. */\n Sticky: { readonly accountId: string }\n /** No candidate is usable by a fresh reading and no pin is: highest priority, then lowest id. */\n FillFirst: { readonly accountId: string }\n}>\n\nexport const PoolDecision = Data.taggedEnum<PoolDecision>()\n\nexport type PoolRankInput = {\n /** Configured accounts. */\n readonly accounts: ReadonlyArray<PoolCandidate>\n /** Accounts that cannot serve now: an active cooldown, or already tried by this request. */\n readonly unavailable: ReadonlySet<string>\n readonly readings: ReadonlyMap<string, PoolReading>\n /** The account the route is pinned to, if any. */\n readonly pin: string | undefined\n readonly route: string\n readonly nowMs: number\n readonly maxAgeMs: number\n readonly reservePercent: number\n}\n\nconst appliesTo = (window: PoolWindow, route: string) =>\n window.models.length === 0 || window.models.some(model => route.includes(model))\n\nconst hasStarted = (window: PoolWindow, nowMs: number) =>\n window.resetsAtMs !== undefined && window.resetsAtMs > nowMs\n\ntype AccountRank =\n /** No window of the reading applies to the route: the reading says nothing. */\n | { readonly kind: 'unknown' }\n /** An applicable started window is used up to the reserve. */\n | { readonly kind: 'exhausted' }\n | { readonly kind: 'usable'; readonly resetsAtMs: number | undefined }\n\n/**\n * The reset of the account's longest window with a length that applies to the route (undefined\n * when it has not started, or no applicable window has a length). Unusable when no window applies\n * or an applicable started window is used up to the reserve; a window whose reset has passed counts\n * as fresh, whatever the reading said.\n */\nconst accountRank = (\n reading: PoolReading,\n route: string,\n nowMs: number,\n reservePercent: number\n): AccountRank => {\n let usable = false\n let longest = 0\n let resetsAtMs: number | undefined\n\n for (const window of reading.windows) {\n if (!appliesTo(window, route)) {\n continue\n }\n\n const started = hasStarted(window, nowMs)\n\n if (started && window.usedPercent >= 100 - reservePercent) {\n return { kind: 'exhausted' }\n }\n\n usable = true\n\n if (window.durationMinutes === undefined) {\n continue\n }\n\n if (window.durationMinutes > longest) {\n longest = window.durationMinutes\n resetsAtMs = started ? window.resetsAtMs : undefined\n } else if (\n window.durationMinutes === longest &&\n started &&\n window.resetsAtMs !== undefined &&\n (resetsAtMs === undefined || window.resetsAtMs < resetsAtMs)\n ) {\n resetsAtMs = window.resetsAtMs\n }\n }\n\n return usable ? { kind: 'usable', resetsAtMs } : { kind: 'unknown' }\n}\n\ntype Ranked = { readonly candidate: PoolCandidate; readonly resetsAtMs: number | undefined }\n\n/** Code-unit id order, so ties never depend on locale. */\nconst idBefore = (a: string, b: string) => a < b\n\n/**\n * Started windows by soonest reset, then windows that have not started; ties by higher priority,\n * then lower id.\n */\nconst ranksBefore = (a: Ranked, b: Ranked) => {\n if (a.resetsAtMs !== undefined && b.resetsAtMs !== undefined) {\n if (a.resetsAtMs !== b.resetsAtMs) {\n return a.resetsAtMs < b.resetsAtMs\n }\n } else if (a.resetsAtMs !== undefined || b.resetsAtMs !== undefined) {\n return a.resetsAtMs !== undefined\n }\n\n if (a.candidate.priority !== b.candidate.priority) {\n return a.candidate.priority > b.candidate.priority\n }\n\n return idBefore(a.candidate.id, b.candidate.id)\n}\n\n/** Highest priority, then lowest id. */\nconst fillFirst = (candidates: ReadonlyArray<PoolCandidate>): PoolCandidate | undefined => {\n let best: PoolCandidate | undefined\n\n for (const candidate of candidates) {\n if (\n best === undefined ||\n candidate.priority > best.priority ||\n (candidate.priority === best.priority && idBefore(candidate.id, best.id))\n ) {\n best = candidate\n }\n }\n\n return best\n}\n\n/**\n * Expiring-first: the available account whose longest applicable window resets soonest and still\n * has quota. When no available account is usable by a fresh reading (within `maxAgeMs`), it routes\n * stickily: the pin while it is available, else fill-first, preferring accounts that no fresh\n * reading shows used up; those serve only when nothing else is left, so the provider's own answer\n * decides. Undefined when no account is available.\n */\nexport const rankPool = (input: PoolRankInput): PoolDecision | undefined => {\n const candidates = input.accounts.filter(account => !input.unavailable.has(account.id))\n const exhausted = new Set<string>()\n\n let best: Ranked | undefined\n\n for (const candidate of candidates) {\n const reading = input.readings.get(candidate.id)\n\n if (reading === undefined || input.nowMs - reading.fetchedAtMs > input.maxAgeMs) {\n continue\n }\n\n const rank = accountRank(reading, input.route, input.nowMs, input.reservePercent)\n\n if (rank.kind === 'exhausted') {\n exhausted.add(candidate.id)\n }\n\n if (rank.kind !== 'usable') {\n continue\n }\n\n const next: Ranked = { candidate, resetsAtMs: rank.resetsAtMs }\n\n if (best === undefined || ranksBefore(next, best)) {\n best = next\n }\n }\n\n if (best !== undefined) {\n return PoolDecision.Quota({ accountId: best.candidate.id, resetsAtMs: best.resetsAtMs })\n }\n\n const unexhausted = candidates.filter(candidate => !exhausted.has(candidate.id))\n const fallback = unexhausted.length > 0 ? unexhausted : candidates\n\n if (input.pin !== undefined && fallback.some(candidate => candidate.id === input.pin)) {\n return PoolDecision.Sticky({ accountId: input.pin })\n }\n\n const first = fillFirst(fallback)\n\n return first === undefined ? undefined : PoolDecision.FillFirst({ accountId: first.id })\n}\n\n/** Whether a cooldown still keeps its account out at `nowMs`. */\nexport const isCooldownActive = (cooldown: PoolCooldown, nowMs: number) => cooldown.untilMs > nowMs\n\n/**\n * Every account-wide window of the reading has quota left or has reset; model-scoped windows block\n * only their models through ranking, never the whole account. A reading without account-wide\n * windows proves nothing.\n */\nconst hasQuotaLeft = (reading: PoolReading, nowMs: number) => {\n const accountWide = reading.windows.filter(window => window.models.length === 0)\n\n return (\n accountWide.length > 0 &&\n accountWide.every(window => !hasStarted(window, nowMs) || window.usedPercent < 100)\n )\n}\n\n/**\n * Active quota cooldowns that a fresh reading taken after they began shows to be over (a limit\n * reset was spent, or the provider reset early). A reading from before the lockout never clears\n * one, and auth cooldowns are never cleared by readings.\n */\nexport const staleQuotaCooldowns = (input: {\n readonly cooldowns: ReadonlyArray<PoolCooldown>\n readonly readings: ReadonlyMap<string, PoolReading>\n readonly nowMs: number\n readonly maxAgeMs: number\n}): ReadonlyArray<PoolCooldown> =>\n input.cooldowns.filter(cooldown => {\n if (\n !Predicate.isTagged(cooldown, 'PoolQuotaCooldown') ||\n !isCooldownActive(cooldown, input.nowMs)\n ) {\n return false\n }\n\n const reading = input.readings.get(cooldown.accountId)\n\n return (\n reading !== undefined &&\n input.nowMs - reading.fetchedAtMs <= input.maxAgeMs &&\n reading.fetchedAtMs > cooldown.startedAtMs &&\n hasQuotaLeft(reading, input.nowMs)\n )\n })\n"],"mappings":"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"}
1
+ {"version":3,"file":"rank.mjs","names":[],"sources":["../src/rank.ts"],"sourcesContent":["import { Data, Predicate } from 'effect'\nimport type { ProviderSubscriptionUsageSnapshot } from '@yolk-sdk/agent/providers/subscription-usage'\nimport type { PoolCooldown } from './model.ts'\n\n/** One usage window of a reading, as the ranking reads it. */\nexport type PoolWindow = {\n /** Window length; absent when the provider's window has no fixed length (a billing month). */\n readonly durationMinutes?: number\n readonly usedPercent: number\n /** When the window resets; absent when it has not started. */\n readonly resetsAtMs?: number\n /** Lowercase model substrings the window limits; empty for every model. */\n readonly models: ReadonlyArray<string>\n}\n\ntype MutablePoolWindow = { -readonly [Key in keyof PoolWindow]: PoolWindow[Key] }\n\n/** The latest quota reading of one account. */\nexport type PoolReading = {\n readonly fetchedAtMs: number\n readonly windows: ReadonlyArray<PoolWindow>\n}\n\n/** A configured account as the ranking sees it. */\nexport type PoolCandidate = {\n readonly id: string\n readonly priority: number\n}\n\n/**\n * The route a request pins: its model id, trimmed and lowercased. Reasoning effort is a separate\n * request field and never part of the route.\n */\nexport const poolRoute = (model: string) => model.trim().toLowerCase()\n\n/**\n * A usage snapshot as the ranking reads it; an unreadable `fetchedAt` yields no reading. Windows\n * without a length still block a used-up account but never rank it. A window that reports only\n * `resetsAfterSeconds` resets that long after the reading.\n */\nexport const poolReadingFromSnapshot = (\n snapshot: ProviderSubscriptionUsageSnapshot\n): PoolReading | undefined => {\n const fetchedAtMs = Date.parse(snapshot.fetchedAt)\n\n if (!Number.isFinite(fetchedAtMs)) {\n return undefined\n }\n\n const windows = Array.from(snapshot.windows).map((window): PoolWindow => {\n const resetsAtMs =\n window.resetsAt !== undefined\n ? Date.parse(window.resetsAt)\n : window.resetsAfterSeconds !== undefined\n ? fetchedAtMs + window.resetsAfterSeconds * 1000\n : Number.NaN\n\n const models = (window.models ?? []).flatMap(model => {\n const normalized = model.trim().toLowerCase()\n\n return normalized === '' ? [] : [normalized]\n })\n\n const fields: MutablePoolWindow = { usedPercent: window.usedPercent, models }\n\n if (window.windowDurationMinutes !== undefined) {\n fields.durationMinutes = window.windowDurationMinutes\n }\n\n if (Number.isFinite(resetsAtMs)) {\n fields.resetsAtMs = resetsAtMs\n }\n\n return fields\n })\n\n return { fetchedAtMs, windows }\n}\n\n/** Why the ranking chose an account. */\nexport type PoolDecision = Data.TaggedEnum<{\n /** Fresh readings ranked it first; `resetsAtMs` is its longest window's reset, if started. */\n Quota: { readonly accountId: string; readonly resetsAtMs: number | undefined }\n /** No candidate is usable by a fresh reading; the route's pin is still available. */\n Sticky: { readonly accountId: string }\n /** No candidate is usable by a fresh reading and no pin is: highest priority, then lowest id. */\n FillFirst: { readonly accountId: string }\n}>\n\nexport const PoolDecision = Data.taggedEnum<PoolDecision>()\n\nexport type PoolRankInput = {\n /** Configured accounts. */\n readonly accounts: ReadonlyArray<PoolCandidate>\n /** Accounts that cannot serve now: an active cooldown, or already tried by this request. */\n readonly unavailable: ReadonlySet<string>\n readonly readings: ReadonlyMap<string, PoolReading>\n /** The account the route is pinned to, if any. */\n readonly pin: string | undefined\n readonly route: string\n readonly nowMs: number\n readonly maxAgeMs: number\n readonly reservePercent: number\n}\n\nconst appliesTo = (window: PoolWindow, route: string) =>\n window.models.length === 0 || window.models.some(model => route.includes(model))\n\nconst hasStarted = (window: PoolWindow, nowMs: number) =>\n window.resetsAtMs !== undefined && window.resetsAtMs > nowMs\n\ntype AccountRank =\n /** No window of the reading applies to the route: the reading says nothing. */\n | { readonly kind: 'unknown' }\n /** An applicable started window is used up to the reserve. */\n | { readonly kind: 'exhausted' }\n | { readonly kind: 'usable'; readonly resetsAtMs: number | undefined }\n\n/**\n * The reset of the account's longest window with a length that applies to the route (undefined\n * when it has not started, or no applicable window has a length). Unusable when no window applies\n * or an applicable started window is used up to the reserve; a window whose reset has passed counts\n * as fresh, whatever the reading said.\n */\nconst accountRank = (\n reading: PoolReading,\n route: string,\n nowMs: number,\n reservePercent: number\n): AccountRank => {\n let usable = false\n let longest = 0\n let resetsAtMs: number | undefined\n\n for (const window of reading.windows) {\n if (!appliesTo(window, route)) {\n continue\n }\n\n const started = hasStarted(window, nowMs)\n\n if (started && window.usedPercent >= 100 - reservePercent) {\n return { kind: 'exhausted' }\n }\n\n usable = true\n\n if (window.durationMinutes === undefined) {\n continue\n }\n\n if (window.durationMinutes > longest) {\n longest = window.durationMinutes\n resetsAtMs = started ? window.resetsAtMs : undefined\n } else if (\n window.durationMinutes === longest &&\n started &&\n window.resetsAtMs !== undefined &&\n (resetsAtMs === undefined || window.resetsAtMs < resetsAtMs)\n ) {\n resetsAtMs = window.resetsAtMs\n }\n }\n\n return usable ? { kind: 'usable', resetsAtMs } : { kind: 'unknown' }\n}\n\ntype Ranked = { readonly candidate: PoolCandidate; readonly resetsAtMs: number | undefined }\n\n/** Code-unit id order, so ties never depend on locale. */\nconst idBefore = (a: string, b: string) => a < b\n\n/**\n * Started windows by soonest reset, then windows that have not started; ties by higher priority,\n * then lower id.\n */\nconst ranksBefore = (a: Ranked, b: Ranked) => {\n if (a.resetsAtMs !== undefined && b.resetsAtMs !== undefined) {\n if (a.resetsAtMs !== b.resetsAtMs) {\n return a.resetsAtMs < b.resetsAtMs\n }\n } else if (a.resetsAtMs !== undefined || b.resetsAtMs !== undefined) {\n return a.resetsAtMs !== undefined\n }\n\n if (a.candidate.priority !== b.candidate.priority) {\n return a.candidate.priority > b.candidate.priority\n }\n\n return idBefore(a.candidate.id, b.candidate.id)\n}\n\n/** Highest priority, then lowest id. */\nconst fillFirst = (candidates: ReadonlyArray<PoolCandidate>): PoolCandidate | undefined => {\n let best: PoolCandidate | undefined\n\n for (const candidate of candidates) {\n if (\n best === undefined ||\n candidate.priority > best.priority ||\n (candidate.priority === best.priority && idBefore(candidate.id, best.id))\n ) {\n best = candidate\n }\n }\n\n return best\n}\n\n/**\n * Expiring-first: the available account whose longest applicable window resets soonest and still\n * has quota. When no available account is usable by a fresh reading (within `maxAgeMs`), it routes\n * stickily: the pin while it is available, else fill-first, preferring accounts that no fresh\n * reading shows used up; those serve only when nothing else is left, so the provider's own answer\n * decides. Undefined when no account is available.\n */\nexport const rankPool = (input: PoolRankInput): PoolDecision | undefined => {\n const candidates = input.accounts.filter(account => !input.unavailable.has(account.id))\n const exhausted = new Set<string>()\n\n let best: Ranked | undefined\n\n for (const candidate of candidates) {\n const reading = input.readings.get(candidate.id)\n\n if (reading === undefined || input.nowMs - reading.fetchedAtMs > input.maxAgeMs) {\n continue\n }\n\n const rank = accountRank(reading, input.route, input.nowMs, input.reservePercent)\n\n if (rank.kind === 'exhausted') {\n exhausted.add(candidate.id)\n }\n\n if (rank.kind !== 'usable') {\n continue\n }\n\n const next: Ranked = { candidate, resetsAtMs: rank.resetsAtMs }\n\n if (best === undefined || ranksBefore(next, best)) {\n best = next\n }\n }\n\n if (best !== undefined) {\n return PoolDecision.Quota({ accountId: best.candidate.id, resetsAtMs: best.resetsAtMs })\n }\n\n const unexhausted = candidates.filter(candidate => !exhausted.has(candidate.id))\n const fallback = unexhausted.length > 0 ? unexhausted : candidates\n\n if (input.pin !== undefined && fallback.some(candidate => candidate.id === input.pin)) {\n return PoolDecision.Sticky({ accountId: input.pin })\n }\n\n const first = fillFirst(fallback)\n\n return first === undefined ? undefined : PoolDecision.FillFirst({ accountId: first.id })\n}\n\n/** Whether a cooldown still keeps its account out at `nowMs`. */\nexport const isCooldownActive = (cooldown: PoolCooldown, nowMs: number) => cooldown.untilMs > nowMs\n\n/**\n * Every account-wide window of the reading has quota left or has reset; model-scoped windows block\n * only their models through ranking, never the whole account. A reading without account-wide\n * windows proves nothing.\n */\nconst hasQuotaLeft = (reading: PoolReading, nowMs: number) => {\n const accountWide = reading.windows.filter(window => window.models.length === 0)\n\n return (\n accountWide.length > 0 &&\n accountWide.every(window => !hasStarted(window, nowMs) || window.usedPercent < 100)\n )\n}\n\n/**\n * Active quota cooldowns that a fresh reading taken after they began shows to be over (a limit\n * reset was spent, or the provider reset early). A reading from before the lockout never clears\n * one, nor one whose absorbed auth failure (`authUntilMs`) is still active, and auth cooldowns are\n * never cleared by readings: a reading proves nothing about a rejected credential.\n */\nexport const staleQuotaCooldowns = (input: {\n readonly cooldowns: ReadonlyArray<PoolCooldown>\n readonly readings: ReadonlyMap<string, PoolReading>\n readonly nowMs: number\n readonly maxAgeMs: number\n}): ReadonlyArray<PoolCooldown> =>\n input.cooldowns.filter(cooldown => {\n if (\n !Predicate.isTagged(cooldown, 'PoolQuotaCooldown') ||\n !isCooldownActive(cooldown, input.nowMs) ||\n (cooldown.authUntilMs !== undefined && cooldown.authUntilMs > input.nowMs)\n ) {\n return false\n }\n\n const reading = input.readings.get(cooldown.accountId)\n\n return (\n reading !== undefined &&\n input.nowMs - reading.fetchedAtMs <= input.maxAgeMs &&\n reading.fetchedAtMs > cooldown.startedAtMs &&\n hasQuotaLeft(reading, input.nowMs)\n )\n })\n"],"mappings":"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"}
package/dist/store.d.mts CHANGED
@@ -46,18 +46,38 @@ export type PoolStoreApi = {
46
46
  readonly pin: PoolPin;
47
47
  }) => Effect.Effect<boolean, PoolStoreError>;
48
48
  /**
49
- * Records a cooldown; when the account already has one, the one that ends later stays, and of two
50
- * that end together the one that started later (a newer failure must not be cleared by a reading
51
- * taken before it).
49
+ * Records a cooldown. When the account already has one:
50
+ *
51
+ * - one that ended before the other began is replaced by the other (an expired cooldown never
52
+ * shapes a later one);
53
+ * - two that overlap merge into one: the later end and its kind (of two that end together, the
54
+ * later-started one's kind; of two that also start together, quota), with the later
55
+ * `startedAtMs` of the two, so the kept cooldown carries the newest failure's time and a
56
+ * reading taken before that failure never clears it;
57
+ * - a kept quota cooldown records the latest end of any auth failure it absorbed as
58
+ * `authUntilMs` (omitted when that ended by the kept start), so no reading clears it before
59
+ * then.
60
+ *
61
+ * Concurrent writes for one account are the normal case, so merge atomically: one statement,
62
+ * never a read followed by a write. For example an upsert that sets the start to the greatest
63
+ * start, picks the end and kind with a `CASE` on which ends later (then which started later,
64
+ * then quota), and sets `authUntilMs` to the greatest auth end of the two (an auth cooldown's
65
+ * end, a quota cooldown's `authUntilMs`) when the kept one is quota and that end is after the
66
+ * merged start, else null.
52
67
  */
53
68
  readonly putCooldown: (cooldown: PoolCooldown) => Effect.Effect<void, PoolStoreError>;
54
69
  /**
55
- * Removes the account's cooldown only when it is the one observed (same `startedAtMs`). Returns
56
- * whether it removed one.
70
+ * Removes the account's quota cooldown only when it is the one observed (same `startedAtMs` and
71
+ * `authUntilMs`). Never removes an auth cooldown. Two failures in the same millisecond share a
72
+ * start, so the start alone cannot tell a quota cooldown from what it became after absorbing an
73
+ * auth failure: that merge either made it an auth cooldown or set `authUntilMs`, and both make
74
+ * a clear observed before it fail. Returns whether it removed one.
57
75
  */
58
76
  readonly clearCooldown: (input: {
59
77
  readonly accountId: string;
60
78
  readonly startedAtMs: number;
79
+ /** The observed cooldown's `authUntilMs` (`undefined` when it had none). */
80
+ readonly authUntilMs: number | undefined;
61
81
  }) => Effect.Effect<boolean, PoolStoreError>;
62
82
  /** Records a reading unless the stored one was fetched later. */
63
83
  readonly putReading: (reading: PoolStoredReading) => Effect.Effect<void, PoolStoreError>;
@@ -1 +1 @@
1
- {"version":3,"file":"store.d.mts","names":[],"sources":["../src/store.ts"],"mappings":";;;;;;;;;qBAea,0BAA0B;;YAM3B;WACD,KAAK;WACL,WAAW,cAAc;WACzB,UAAU,cAAc;;;YAIvB;WACD,MAAM,cAAc;WACpB,WAAW,cAAc;WACzB,UAAU,cAAc;;;;;;;;;;;;YAavB;;WAED,OAAO;aACL;aACA;aACA,YAAY;QACjB,OAAO,OAAO,mBAAmB;;;;;WAK9B,UAAU;aACR;aACA,KAAK;QACV,OAAO,gBAAgB;;;;;;WAMpB,cAAc,UAAU,iBAAiB,OAAO,aAAa;;;;;WAK7D,gBAAgB;aACd;aACA;QACL,OAAO,gBAAgB;;WAEpB,aAAa,SAAS,sBAAsB,OAAO,aAAa;;WAEhE,QAAQ;aACN;aACA,YAAY;QACjB,OAAO,OAAO,gBAAgB;;;;;;qBAWzB,2BAA0B;;;;;;qBA2E1B,mCAAmC;;YASpC;WACD;WACA,MACP,OAAO,iBACJ,OAAO,aAAa,6BAA6B;;;qBA+B3C,mBAAmB,cAAc"}
1
+ {"version":3,"file":"store.d.mts","names":[],"sources":["../src/store.ts"],"mappings":";;;;;;;;;qBAea,0BAA0B;;YAM3B;WACD,KAAK;WACL,WAAW,cAAc;WACzB,UAAU,cAAc;;;YAIvB;WACD,MAAM,cAAc;WACpB,WAAW,cAAc;WACzB,UAAU,cAAc;;;;;;;;;;;;YAavB;;WAED,OAAO;aACL;aACA;aACA,YAAY;QACjB,OAAO,OAAO,mBAAmB;;;;;WAK9B,UAAU;aACR;aACA,KAAK;QACV,OAAO,gBAAgB;;;;;;;;;;;;;;;;;;;;;WAqBpB,cAAc,UAAU,iBAAiB,OAAO,aAAa;;;;;;;;WAQ7D,gBAAgB;aACd;aACA;;aAEA;QACL,OAAO,gBAAgB;;WAEpB,aAAa,SAAS,sBAAsB,OAAO,aAAa;;WAEhE,QAAQ;aACN;aACA,YAAY;QACjB,OAAO,OAAO,gBAAgB;;;;;;qBAiEzB,2BAA0B;;;;;;qBA4E1B,mCAAmC;;YASpC;WACD;WACA,MACP,OAAO,iBACJ,OAAO,aAAa,6BAA6B;;;qBAoH3C,mBAAmB,cAAc"}