@omnicross/subscriptions 0.1.2 → 0.1.3

package/dist/index.d.cts

@@ -27,7 +27,15 @@ export { claudeOAuth, codexOAuth, geminiOAuth } from './oauth.cjs';
  * subscriptions layer).
  */
 
-/** The six methods the subscription block consumes from the host credential store. */
+/**
+ * The credential surface the subscription block consumes from the host store.
+ *
+ * The six ORIGINAL methods (active-account getters + refreshers) are REQUIRED;
+ * the three by-id methods (subscription-account-scheduling, design D6) are
+ * OPTIONAL and feature-detected so every existing lightweight test double that
+ * implements only the six keeps compiling and the single-account active path is
+ * untouched.
+ */
 interface SubscriptionCredentialStore {
     /** Full decrypted account-tokens config (all subscription providers). */
     getFullConfig(): Promise<AccountTokensConfig>;
@@ -41,6 +49,124 @@ interface SubscriptionCredentialStore {
     refreshGeminiToken(): Promise<boolean>;
     /** Current valid OpenCodeGo static API key; `null` if none. */
     getValidOpenCodeGoApiKey(): Promise<string | null>;
+    /**
+     * Resolve a SPECIFIC account's access token by id (refreshing a near-expiry
+     * OAuth token for that account, mirroring the active getter's per-provider
+     * refresh policy). `null` when the account is unknown/expired/tokenless.
+     */
+    getAccessTokenForAccount?(providerId: SubscriptionProviderId, accountId: string): Promise<string | null>;
+    /**
+     * Force a refresh of a SPECIFIC account's OAuth token by id; `true` on success.
+     * Static-key providers (opencodego) return `false` — they don't refresh.
+     */
+    refreshAccountToken?(providerId: SubscriptionProviderId, accountId: string): Promise<boolean>;
+    /**
+     * Best-effort record of a selection's time onto the account's `lastUsedAt`
+     * (throttled by the selector so the hot path does not rewrite the store every
+     * request). Durability only — never affects which credential is valid.
+     */
+    touchAccountLastUsed?(providerId: SubscriptionProviderId, accountId: string, iso: string): Promise<void>;
+}
+
+/**
+ * SubscriptionAccountSelector — the pure, in-memory account scheduler
+ * (subscription-account-scheduling, design D3).
+ *
+ * Given a provider's account list (+ an optional session key) it decides WHICH
+ * account of the pool serves the outbound request:
+ *
+ *   filter `schedulable !== false`
+ *     → session-affinity short-circuit (sticky `sessionKey → accountId`, TTL 1h)
+ *     → sort by `priority` asc → effective `lastUsedAt` asc (LRU) → `createdAt` asc
+ *     → `[0]`.
+ *
+ * A faithful port of CRS `sortAccountsByPriority` + `unifiedClaudeScheduler`
+ * session mapping. The class holds process-lived state — the affinity map and an
+ * in-memory `lastUsedAt` overlay (the authoritative live tie-break value, seeded
+ * from the persisted field and advanced to `now` on each selection so repeated
+ * selections round-robin fairly even before any durable persist). ONE instance is
+ * constructed at bootstrap and SHARED by all three auth strategies (each scopes
+ * its calls by `providerId`), mirroring the single long-lived CRS scheduler.
+ *
+ * ZERO-REGRESSION CARRIER: `select()` returns `null` when the schedulable account
+ * count is ≤ 1. Callers treat `null` (and an `isActive` result) as "use the
+ * existing active-mirror path", so a single-account provider exercises NO new
+ * code and its token read is byte-identical to before this change.
+ *
+ * @module scheduler/SubscriptionAccountSelector
+ */
+
+/** Sticky session→account affinity TTL (CRS parity: 1 hour). */
+declare const SESSION_AFFINITY_TTL_MS = 3600000;
+/** Min gap between best-effort `lastUsedAt` durable persists, per account. */
+declare const LAST_USED_PERSIST_THROTTLE_MS = 60000;
+/** Precedence assumed for an account with no `priority` (CRS `|| 50`). */
+declare const DEFAULT_ACCOUNT_PRIORITY = 50;
+/** One schedulable candidate — the scheduling projection of an account entry. */
+interface SchedulableAccount {
+    id: string;
+    /** Default `50` (lower = higher precedence). */
+    priority?: number;
+    /** ISO — LRU tie-break; absent ⇒ treated as least-recently-used (`0`). */
+    lastUsedAt?: string;
+    /** ISO — final tie-break; absent ⇒ oldest (`0`). */
+    createdAt?: string;
+    /** Default `true`; child #2 (account health) sets `false` for an unhealthy
+     *  account and the selector skips it. */
+    schedulable?: boolean;
+}
+interface SelectInput {
+    providerId: SubscriptionProviderId;
+    accounts: readonly SchedulableAccount[];
+    /** The persistent active-account pointer (for the `isActive` discriminant). */
+    activeAccountId?: string;
+    /** Stable per-conversation key for session affinity; absent ⇒ pure priority/LRU. */
+    sessionKey?: string;
+    /** Injectable clock for tests (default `Date.now()`). */
+    now?: number;
+}
+interface SelectResult {
+    accountId: string;
+    /** `true` when the chosen account is the active one — the caller then runs the
+     *  existing active-mirror getter verbatim (no by-id read). */
+    isActive: boolean;
+}
+declare class SubscriptionAccountSelector {
+    /** `providerId\0accountId → live lastUsedAt ms` (authoritative tie-break). */
+    private readonly lastUsedOverlay;
+    /** `providerId\0sessionKey → { accountId, expiresAt }`. */
+    private readonly affinity;
+    /** `providerId\0accountId → last durable-persist ms` (throttle state). */
+    private readonly lastPersist;
+    /**
+     * Choose the account to serve this request, or `null` when there are ≤ 1
+     * schedulable accounts (the zero-regression signal — caller uses the active
+     * account). Updates the live `lastUsedAt` overlay for the chosen account and,
+     * when a `sessionKey` is given, records/extends the affinity mapping.
+     */
+    select(input: SelectInput): SelectResult | null;
+    /**
+     * Drop every session-affinity mapping bound to this account (subscription-account-
+     * health, task 4.1). Called when a selected account's by-id token turns out
+     * null/invalid or an affinity-bound account becomes unhealthy, so the next
+     * selection for those sessions picks a fresh account instead of re-sticking to
+     * the bad one. O(affinity entries) — the map is tiny (one entry per live
+     * conversation).
+     */
+    evictAffinity(providerId: SubscriptionProviderId, accountId: string): void;
+    /**
+     * Whether a best-effort `lastUsedAt` durable persist is DUE for this account
+     * (≥ `LAST_USED_PERSIST_THROTTLE_MS` since the last one). Records the persist
+     * time when it returns `true`, so the strategy calls `touchAccountLastUsed`
+     * sparingly and the request hot path does not rewrite the store every request.
+     */
+    duePersist(providerId: SubscriptionProviderId, accountId: string, now?: number): boolean;
+    /** Sort by `priority` asc → effective `lastUsedAt` asc → `createdAt` asc → `[0]`. */
+    private pickOrdered;
+    /** The live tie-break value: the in-memory overlay when set, else the persisted
+     *  `lastUsedAt` (0 when absent). */
+    private effectiveLastUsed;
+    private markUsed;
 }
 
 /**
@@ -57,6 +183,9 @@ interface SubscriptionCredentialStore {
 
 declare class SubscriptionAccountService {
     private readonly mutex;
+    /** ONE account-pool scheduler (subscription-account-scheduling) shared by all
+     *  four strategies so they share the affinity map + the `lastUsedAt` overlay. */
+    private readonly selector;
     private readonly strategies;
     constructor(tokens: SubscriptionCredentialStore);
     /** Returns the strategy bound to a subscription provider, or `null` for unknown ids. */
@@ -136,7 +265,17 @@ interface DispatcherHooks {
     readonly executor: TransformerChainExecutor;
     /** Shared transformer service registry — looks up transformer-by-name. */
     readonly transformerService: TransformerService;
-    /** Fetch + retry helper from the proxy (semaphore, 429/5xx loop). */
+    /**
+     * Fetch + retry helper from the proxy (semaphore, 429/5xx loop). On a non-ok
+     * upstream it throws a `ProviderApiError`-shaped error carrying `.status`.
+     *
+     * ACCOUNT-HEALTH CONTRACT (subscription-account-health): for the daemon-path
+     * 429-reset cooldown + 403-ban sniff to function, the thrown error SHOULD also
+     * carry the upstream response `headers` (a `Headers` or a plain record) and, on
+     * a 403, a bounded `bodyText`/`body` string. The dispatcher reads them
+     * STRUCTURALLY (`errHeaders`/`errBodyText`) — absent ⇒ the account-health mark
+     * gracefully degrades to a bare-429 (unmarked, lazy re-probe), never an error.
+     */
     fetchWithRetry(url: string, headers: Record<string, string>, body: unknown, model: string): Promise<Response>;
     /** Forward the upstream response to the SDK + tap usage. */
     writeProxyResponse(res: http.ServerResponse, providerResponse: Response, isStream: boolean, reqId?: number): Promise<void>;
@@ -185,6 +324,17 @@ declare class SubscriptionDispatcher {
      */
     private maybeRetryAfterError;
     private applyHeadersWithRetry;
+    /**
+     * Mark the served account's health against ONE attempt's outcome
+     * (subscription-account-health, task 3.4). No-op when no account was reported
+     * (non-pooled / single-account) or on a session-cancel (status 0). On a caught
+     * error `err` is passed so the 429-reset / 403-ban drivers are read STRUCTURALLY
+     * from the error's upstream `headers` + `bodyText` (the `fetchWithRetry`
+     * contract) — so daemon-path 429 cooldown + ban blocking function for
+     * multi-account codex/gemini/opencodego pools; absent headers ⇒ a bare-429
+     * (unmarked, lazy re-probe). Success (2xx) clears; 401/5xx/thrown → transient.
+     */
+    private markHealth;
     /**
      * Resolve the Code Assist project for the gemini subscription profile. Pulls
      * the Bearer the bound `AuthStrategy` would inject (so the strategy stays the
@@ -199,4 +349,4 @@ declare class SubscriptionDispatcher {
     private buildRequestSummary;
 }
 
-export { type DispatchRequest, type DispatcherHooks, SubscriptionAccountService, type SubscriptionCredentialStore, SubscriptionDispatcher, SubscriptionProviderRegistry, getSubscriptionAccountService, getSubscriptionProviderRegistry, setSubscriptionAccountService, setSubscriptionProviderRegistry };
+export { DEFAULT_ACCOUNT_PRIORITY, type DispatchRequest, type DispatcherHooks, LAST_USED_PERSIST_THROTTLE_MS, SESSION_AFFINITY_TTL_MS, type SchedulableAccount, type SelectInput, type SelectResult, SubscriptionAccountSelector, SubscriptionAccountService, type SubscriptionCredentialStore, SubscriptionDispatcher, SubscriptionProviderRegistry, getSubscriptionAccountService, getSubscriptionProviderRegistry, setSubscriptionAccountService, setSubscriptionProviderRegistry };

package/dist/index.d.ts

@@ -27,7 +27,15 @@ export { claudeOAuth, codexOAuth, geminiOAuth } from './oauth.js';
  * subscriptions layer).
  */
 
-/** The six methods the subscription block consumes from the host credential store. */
+/**
+ * The credential surface the subscription block consumes from the host store.
+ *
+ * The six ORIGINAL methods (active-account getters + refreshers) are REQUIRED;
+ * the three by-id methods (subscription-account-scheduling, design D6) are
+ * OPTIONAL and feature-detected so every existing lightweight test double that
+ * implements only the six keeps compiling and the single-account active path is
+ * untouched.
+ */
 interface SubscriptionCredentialStore {
     /** Full decrypted account-tokens config (all subscription providers). */
     getFullConfig(): Promise<AccountTokensConfig>;
@@ -41,6 +49,124 @@ interface SubscriptionCredentialStore {
     refreshGeminiToken(): Promise<boolean>;
     /** Current valid OpenCodeGo static API key; `null` if none. */
     getValidOpenCodeGoApiKey(): Promise<string | null>;
+    /**
+     * Resolve a SPECIFIC account's access token by id (refreshing a near-expiry
+     * OAuth token for that account, mirroring the active getter's per-provider
+     * refresh policy). `null` when the account is unknown/expired/tokenless.
+     */
+    getAccessTokenForAccount?(providerId: SubscriptionProviderId, accountId: string): Promise<string | null>;
+    /**
+     * Force a refresh of a SPECIFIC account's OAuth token by id; `true` on success.
+     * Static-key providers (opencodego) return `false` — they don't refresh.
+     */
+    refreshAccountToken?(providerId: SubscriptionProviderId, accountId: string): Promise<boolean>;
+    /**
+     * Best-effort record of a selection's time onto the account's `lastUsedAt`
+     * (throttled by the selector so the hot path does not rewrite the store every
+     * request). Durability only — never affects which credential is valid.
+     */
+    touchAccountLastUsed?(providerId: SubscriptionProviderId, accountId: string, iso: string): Promise<void>;
+}
+
+/**
+ * SubscriptionAccountSelector — the pure, in-memory account scheduler
+ * (subscription-account-scheduling, design D3).
+ *
+ * Given a provider's account list (+ an optional session key) it decides WHICH
+ * account of the pool serves the outbound request:
+ *
+ *   filter `schedulable !== false`
+ *     → session-affinity short-circuit (sticky `sessionKey → accountId`, TTL 1h)
+ *     → sort by `priority` asc → effective `lastUsedAt` asc (LRU) → `createdAt` asc
+ *     → `[0]`.
+ *
+ * A faithful port of CRS `sortAccountsByPriority` + `unifiedClaudeScheduler`
+ * session mapping. The class holds process-lived state — the affinity map and an
+ * in-memory `lastUsedAt` overlay (the authoritative live tie-break value, seeded
+ * from the persisted field and advanced to `now` on each selection so repeated
+ * selections round-robin fairly even before any durable persist). ONE instance is
+ * constructed at bootstrap and SHARED by all three auth strategies (each scopes
+ * its calls by `providerId`), mirroring the single long-lived CRS scheduler.
+ *
+ * ZERO-REGRESSION CARRIER: `select()` returns `null` when the schedulable account
+ * count is ≤ 1. Callers treat `null` (and an `isActive` result) as "use the
+ * existing active-mirror path", so a single-account provider exercises NO new
+ * code and its token read is byte-identical to before this change.
+ *
+ * @module scheduler/SubscriptionAccountSelector
+ */
+
+/** Sticky session→account affinity TTL (CRS parity: 1 hour). */
+declare const SESSION_AFFINITY_TTL_MS = 3600000;
+/** Min gap between best-effort `lastUsedAt` durable persists, per account. */
+declare const LAST_USED_PERSIST_THROTTLE_MS = 60000;
+/** Precedence assumed for an account with no `priority` (CRS `|| 50`). */
+declare const DEFAULT_ACCOUNT_PRIORITY = 50;
+/** One schedulable candidate — the scheduling projection of an account entry. */
+interface SchedulableAccount {
+    id: string;
+    /** Default `50` (lower = higher precedence). */
+    priority?: number;
+    /** ISO — LRU tie-break; absent ⇒ treated as least-recently-used (`0`). */
+    lastUsedAt?: string;
+    /** ISO — final tie-break; absent ⇒ oldest (`0`). */
+    createdAt?: string;
+    /** Default `true`; child #2 (account health) sets `false` for an unhealthy
+     *  account and the selector skips it. */
+    schedulable?: boolean;
+}
+interface SelectInput {
+    providerId: SubscriptionProviderId;
+    accounts: readonly SchedulableAccount[];
+    /** The persistent active-account pointer (for the `isActive` discriminant). */
+    activeAccountId?: string;
+    /** Stable per-conversation key for session affinity; absent ⇒ pure priority/LRU. */
+    sessionKey?: string;
+    /** Injectable clock for tests (default `Date.now()`). */
+    now?: number;
+}
+interface SelectResult {
+    accountId: string;
+    /** `true` when the chosen account is the active one — the caller then runs the
+     *  existing active-mirror getter verbatim (no by-id read). */
+    isActive: boolean;
+}
+declare class SubscriptionAccountSelector {
+    /** `providerId\0accountId → live lastUsedAt ms` (authoritative tie-break). */
+    private readonly lastUsedOverlay;
+    /** `providerId\0sessionKey → { accountId, expiresAt }`. */
+    private readonly affinity;
+    /** `providerId\0accountId → last durable-persist ms` (throttle state). */
+    private readonly lastPersist;
+    /**
+     * Choose the account to serve this request, or `null` when there are ≤ 1
+     * schedulable accounts (the zero-regression signal — caller uses the active
+     * account). Updates the live `lastUsedAt` overlay for the chosen account and,
+     * when a `sessionKey` is given, records/extends the affinity mapping.
+     */
+    select(input: SelectInput): SelectResult | null;
+    /**
+     * Drop every session-affinity mapping bound to this account (subscription-account-
+     * health, task 4.1). Called when a selected account's by-id token turns out
+     * null/invalid or an affinity-bound account becomes unhealthy, so the next
+     * selection for those sessions picks a fresh account instead of re-sticking to
+     * the bad one. O(affinity entries) — the map is tiny (one entry per live
+     * conversation).
+     */
+    evictAffinity(providerId: SubscriptionProviderId, accountId: string): void;
+    /**
+     * Whether a best-effort `lastUsedAt` durable persist is DUE for this account
+     * (≥ `LAST_USED_PERSIST_THROTTLE_MS` since the last one). Records the persist
+     * time when it returns `true`, so the strategy calls `touchAccountLastUsed`
+     * sparingly and the request hot path does not rewrite the store every request.
+     */
+    duePersist(providerId: SubscriptionProviderId, accountId: string, now?: number): boolean;
+    /** Sort by `priority` asc → effective `lastUsedAt` asc → `createdAt` asc → `[0]`. */
+    private pickOrdered;
+    /** The live tie-break value: the in-memory overlay when set, else the persisted
+     *  `lastUsedAt` (0 when absent). */
+    private effectiveLastUsed;
+    private markUsed;
 }
 
 /**
@@ -57,6 +183,9 @@ interface SubscriptionCredentialStore {
 
 declare class SubscriptionAccountService {
     private readonly mutex;
+    /** ONE account-pool scheduler (subscription-account-scheduling) shared by all
+     *  four strategies so they share the affinity map + the `lastUsedAt` overlay. */
+    private readonly selector;
     private readonly strategies;
     constructor(tokens: SubscriptionCredentialStore);
     /** Returns the strategy bound to a subscription provider, or `null` for unknown ids. */
@@ -136,7 +265,17 @@ interface DispatcherHooks {
     readonly executor: TransformerChainExecutor;
     /** Shared transformer service registry — looks up transformer-by-name. */
     readonly transformerService: TransformerService;
-    /** Fetch + retry helper from the proxy (semaphore, 429/5xx loop). */
+    /**
+     * Fetch + retry helper from the proxy (semaphore, 429/5xx loop). On a non-ok
+     * upstream it throws a `ProviderApiError`-shaped error carrying `.status`.
+     *
+     * ACCOUNT-HEALTH CONTRACT (subscription-account-health): for the daemon-path
+     * 429-reset cooldown + 403-ban sniff to function, the thrown error SHOULD also
+     * carry the upstream response `headers` (a `Headers` or a plain record) and, on
+     * a 403, a bounded `bodyText`/`body` string. The dispatcher reads them
+     * STRUCTURALLY (`errHeaders`/`errBodyText`) — absent ⇒ the account-health mark
+     * gracefully degrades to a bare-429 (unmarked, lazy re-probe), never an error.
+     */
     fetchWithRetry(url: string, headers: Record<string, string>, body: unknown, model: string): Promise<Response>;
     /** Forward the upstream response to the SDK + tap usage. */
     writeProxyResponse(res: http.ServerResponse, providerResponse: Response, isStream: boolean, reqId?: number): Promise<void>;
@@ -185,6 +324,17 @@ declare class SubscriptionDispatcher {
      */
     private maybeRetryAfterError;
     private applyHeadersWithRetry;
+    /**
+     * Mark the served account's health against ONE attempt's outcome
+     * (subscription-account-health, task 3.4). No-op when no account was reported
+     * (non-pooled / single-account) or on a session-cancel (status 0). On a caught
+     * error `err` is passed so the 429-reset / 403-ban drivers are read STRUCTURALLY
+     * from the error's upstream `headers` + `bodyText` (the `fetchWithRetry`
+     * contract) — so daemon-path 429 cooldown + ban blocking function for
+     * multi-account codex/gemini/opencodego pools; absent headers ⇒ a bare-429
+     * (unmarked, lazy re-probe). Success (2xx) clears; 401/5xx/thrown → transient.
+     */
+    private markHealth;
     /**
      * Resolve the Code Assist project for the gemini subscription profile. Pulls
      * the Bearer the bound `AuthStrategy` would inject (so the strategy stays the
@@ -199,4 +349,4 @@ declare class SubscriptionDispatcher {
     private buildRequestSummary;
 }
 
-export { type DispatchRequest, type DispatcherHooks, SubscriptionAccountService, type SubscriptionCredentialStore, SubscriptionDispatcher, SubscriptionProviderRegistry, getSubscriptionAccountService, getSubscriptionProviderRegistry, setSubscriptionAccountService, setSubscriptionProviderRegistry };
+export { DEFAULT_ACCOUNT_PRIORITY, type DispatchRequest, type DispatcherHooks, LAST_USED_PERSIST_THROTTLE_MS, SESSION_AFFINITY_TTL_MS, type SchedulableAccount, type SelectInput, type SelectResult, SubscriptionAccountSelector, SubscriptionAccountService, type SubscriptionCredentialStore, SubscriptionDispatcher, SubscriptionProviderRegistry, getSubscriptionAccountService, getSubscriptionProviderRegistry, setSubscriptionAccountService, setSubscriptionProviderRegistry };