@cortexkit/anthropic-auth-core 1.19.1 → 1.21.0

package/README.md

@@ -1,6 +1,6 @@
 # @cortexkit/anthropic-auth-core
 
-Shared Anthropic OAuth, quota, routing, cache, cache-keepalive, fast mode, relay, dump, and request-signing helpers used by CortexKit's OpenCode and Pi integrations.
+Shared Anthropic OAuth, stable account identity, quota, host-local quota feed, routing, cache, cache-keepalive, fast mode, relay, dump, and request-signing helpers used by CortexKit's OpenCode and Pi integrations.
 
 User-facing packages:
 

package/dist/accounts.d.ts

@@ -13,6 +13,7 @@ export type AccountBase = {
 };
 export type OAuthAccount = AccountBase & {
     type: 'oauth';
+    authLineageId?: string;
     access?: string;
     refresh: string;
     expires?: number;
@@ -21,6 +22,11 @@ export type OAuthAccount = AccountBase & {
     lastQuotaRefreshError?: AccountOperationError;
     quota?: OAuthQuotaSnapshot;
     profile?: OAuthAccountProfile;
+    /**
+     * Per-fallback cumulative prime counters. Lives in the runtime-state file
+     * (scoped under `accounts[id].prime`) and never in `anthropic-auth.json`.
+     */
+    prime?: PrimeUsageCounters;
 };
 export type ApiKeyAccount = AccountBase & {
     type: 'api';
@@ -37,6 +43,7 @@ export type AccountOperationError = {
     checkedAt: number;
     nextRetryAt?: number;
     retryCount?: number;
+    accountIdentity?: string;
     tokenHash?: string;
     /**
      * HTTP status of the underlying refresh/quota failure, when known. Lets
@@ -83,9 +90,13 @@ export type OAuthAccountProfile = {
     tier: string;
     orgType: string;
     checkedAt: number;
+    /** Stable account identity; tokenFingerprint remains loadable for legacy state. */
+    accountIdentity?: string;
     tokenFingerprint?: string;
 };
 export type OAuthQuotaSnapshot = Partial<Record<QuotaWindowName, AccountQuotaWindow>> & {
+    /** Stable main/fallback account identity; access tokens are fetch credentials only. */
+    accountIdentity?: string;
     scoped?: AccountScopedQuotaWindow[];
     extraUsage?: OAuthExtraUsageSnapshot;
     bindingWindow?: string;
@@ -94,6 +105,27 @@ export type OAuthQuotaSnapshot = Partial<Record<QuotaWindowName, AccountQuotaWin
     source?: 'poll' | 'headers';
     checkedAt?: number;
 };
+export type PrimeUsageCounters = {
+    count: number;
+    inputTokens: number;
+    outputTokens: number;
+    since: number;
+};
+export type PrimeUsageDelta = {
+    inputTokens?: number;
+    outputTokens?: number;
+};
+export type PrimeRuntimeState = {
+    enabled?: boolean;
+    mainAuthLineageId?: string;
+    mainAuthLineageRefreshTokenFingerprint?: string;
+    /**
+     * Main account prime counters. Persisted only on the main side of the
+     * runtime-state file — `configFromStorage()` never writes them to the config
+     * file so they cannot leak into `anthropic-auth.json`.
+     */
+    main?: PrimeUsageCounters;
+};
 export type RoutingMode = 'main-first' | 'fallback-first' | 'sticky-balanced';
 export type KillswitchThresholds = Partial<Record<QuotaWindowName | '5h' | '1w' | 'scoped', number>>;
 export type KillswitchConfig = {
@@ -105,6 +137,7 @@ export type KillswitchConfig = {
 };
 export type AccountStorage = {
     version: 1;
+    mainAccountId?: string;
     main?: {
         type: 'opencode';
         provider: 'anthropic';
@@ -135,6 +168,11 @@ export type AccountStorage = {
         mainQuotaCheckedAt?: number;
         mainQuotaToken?: string;
         mainLastQuotaApiError?: AccountOperationError;
+        mainQuotaErrorGeneration?: number;
+        mainQuotaErrorClearedAt?: number;
+    };
+    quotaHeaderFeed?: {
+        enabled?: boolean;
     };
     claudeCache?: {
         enabled?: boolean;
@@ -164,6 +202,13 @@ export type AccountStorage = {
         endHour?: number;
         subagents?: boolean;
     };
+    /**
+     * Opt-in flag and runtime metadata for `/claude-prime`. The `enabled` flag
+     * belongs on the config side; counters and main lineage bindings live in the
+     * state file and must never appear in `anthropic-auth.json`. See
+     * `configFromStorage()` for the write-side filter.
+     */
+    prime?: PrimeRuntimeState;
     relay?: {
         enabled?: boolean;
         url?: string;
@@ -180,7 +225,7 @@ export type AccountStorage = {
  * (to display the provider's real model costs).
  */
 export declare function isCostZeroingEnabled(storage: Pick<AccountStorage, 'costZeroing'>): boolean;
-export type AccountRuntimeEntry = Partial<Pick<OAuthAccount, 'access' | 'refresh' | 'expires' | 'lastUsed' | 'lastRefreshedAt' | 'lastRefreshError' | 'lastQuotaRefreshError' | 'quota' | 'profile'> & Pick<ApiKeyAccount, 'apiKey' | 'lastUsed'>>;
+export type AccountRuntimeEntry = Partial<Pick<OAuthAccount, 'access' | 'authLineageId' | 'refresh' | 'expires' | 'lastUsed' | 'lastRefreshedAt' | 'lastRefreshError' | 'lastQuotaRefreshError' | 'quota' | 'profile' | 'prime'> & Pick<ApiKeyAccount, 'apiKey' | 'lastUsed'>>;
 export type AccountRuntimeState = {
     version: 1;
     main?: {
@@ -190,10 +235,15 @@ export type AccountRuntimeState = {
         quotaCheckedAt?: number;
         quotaToken?: string;
         lastQuotaApiError?: AccountOperationError;
+        quotaErrorGeneration?: number;
+        quotaErrorClearedAt?: number;
         lastRefreshError?: AccountOperationError;
         refreshLeaseId?: string;
         refreshLeaseUntil?: number;
         refreshLeaseTokenHash?: string;
+        prime?: PrimeUsageCounters;
+        primeAuthLineageId?: string;
+        primeAuthLineageRefreshTokenFingerprint?: string;
     };
     accounts?: Record<string, AccountRuntimeEntry>;
 };
@@ -201,6 +251,7 @@ export type AccountStateSaveScope = {
     mainProfile?: boolean;
     mainQuota?: boolean;
     mainRefresh?: boolean;
+    mainPrime?: boolean;
     accounts?: true | string[];
 };
 export type AccountManagerOptions = {
@@ -219,7 +270,11 @@ export type AccountRefreshError = {
 export declare function getAccountStoragePath(): string;
 export declare function getAccountStatePath(configPath?: string): string;
 export declare function createEmptyStorage(): AccountStorage;
+export declare function mergeMainQuotaErrorClearedAt(existing: number | undefined, incoming: number | undefined): number | undefined;
 export declare function loadAccounts(path?: string): Promise<AccountStorage | null>;
+/** Returns the latest timestamp carried by any quota snapshot window. */
+export declare function quotaSnapshotCheckedAt(quota: OAuthQuotaSnapshot | undefined): number;
+export declare function mergeHeaderQuotaForPersistence(existing: OAuthQuotaSnapshot | undefined, incoming: OAuthQuotaSnapshot): OAuthQuotaSnapshot;
 export interface SaveAccountsOptions {
     /** Account ids intentionally removed by this mutation. */
     removedAccountIds?: readonly string[];
@@ -227,11 +282,12 @@ export interface SaveAccountsOptions {
     preserveExistingAccountOrder?: boolean;
 }
 export declare function saveAccounts(storage: AccountStorage, path?: string, options?: SaveAccountsOptions): Promise<void>;
+export declare function getOrCreateMainAccountId(path?: string, createId?: () => string): Promise<string>;
 export declare function saveAccountState(storage: AccountStorage, path?: string, scope?: AccountStateSaveScope): Promise<void>;
 export declare function saveOAuthProfileState(input: {
     accountId: 'main' | string;
     profile: OAuthAccountProfile | undefined;
-    expectedTokenFingerprint: string;
+    accountIdentity?: string;
 }, path?: string): Promise<boolean>;
 export declare function acquireRefreshFileLock(options: {
     name: string;
@@ -257,6 +313,19 @@ export declare function setCacheKeepPersistentAlways(path?: string): Promise<Acc
 export declare function setCacheKeepPersistentEnabled(enabled: boolean, path?: string): Promise<AccountStorage>;
 export declare function isCacheKeepSubagentsEnabled(storage: AccountStorage | null): boolean;
 export declare function setCacheKeepSubagentsEnabled(enabled: boolean, path?: string): Promise<AccountStorage>;
+export declare function isPrimePersistentlyEnabled(storage: AccountStorage | null): boolean;
+export declare function setPrimePersistentEnabled(enabled: boolean, path?: string): Promise<AccountStorage>;
+/** Return the stable prime marker identity for an OAuth account. */
+export declare function getOrCreatePrimeAuthLineageId(accountId: 'main' | string, path?: string): Promise<string | undefined>;
+/**
+ * Atomically increment an account's cumulative prime counters and persist via
+ * the scoped runtime-state path. The `main` account lives at state.main.prime;
+ * every other account lives at state.accounts[id].prime. Config-side writes
+ * are intentionally NOT triggered so prime counters cannot leak into
+ * `anthropic-auth.json`. Callers should not depend on this function to mutate
+ * the caller's storage object.
+ */
+export declare function incrementPrimeUsagePersistent(accountId: 'main' | string, usage: PrimeUsageDelta, path?: string, now?: number): Promise<PrimeUsageCounters>;
 export declare function shouldFallbackStatus(status: number, storage: AccountStorage | null): boolean;
 export declare function getQuotaMinimumRemainingThresholds(storage: AccountStorage | null): {
     five_hour: number;
@@ -267,7 +336,7 @@ export declare function hashRefreshToken(refreshToken: string): string;
 export declare function buildRefreshOperationError(input: {
     error: unknown;
     now: number;
-    refreshToken: string;
+    accountIdentity: string | undefined;
     previous?: AccountOperationError;
 }): AccountOperationError;
 /**
@@ -286,12 +355,14 @@ export declare function buildRefreshOperationError(input: {
  *     the error with the explicit field.
  */
 export declare function isPermanentRefreshError(error: AccountOperationError | undefined): boolean;
-export declare function refreshBackoffActive(error: AccountOperationError | undefined, refreshToken: string | undefined, now: number): boolean;
+export declare function refreshBackoffActive(error: AccountOperationError | undefined, accountIdentity: string | undefined, now: number): boolean;
 export declare function formatRefreshBackoffMessage(error: AccountOperationError, now: number): string;
+export declare function getFallbackReauthLabels(storage: AccountStorage | null | undefined): string[];
 export declare function isQuotaPolicyAuthError(error: unknown): boolean;
 export declare function buildQuotaOperationError(input: {
     error: unknown;
     now: number;
+    accountIdentity?: string;
     previous?: AccountOperationError;
 }): AccountOperationError;
 export declare function quotaBackoffActive(error: AccountOperationError | undefined, now: number): boolean;
@@ -303,6 +374,7 @@ export declare function getPersistedMainQuota(storage: AccountStorage | null): {
     quota: OAuthQuotaSnapshot;
     checkedAt: number;
     tokenFingerprint?: string;
+    accountIdentity?: string;
 } | null;
 /**
  * How often (in requests) to force a quota refresh, independent of the timer.
@@ -313,6 +385,7 @@ export declare function getScopedQuotaWindowForModel(quota: OAuthQuotaSnapshot |
 export declare function quotaSnapshotModelScopeIsExhausted(quota: OAuthQuotaSnapshot | undefined, model: unknown): boolean;
 export declare function quotaSnapshotPassesModelScope(quota: OAuthQuotaSnapshot | undefined, model: unknown): boolean;
 export declare function quotaSnapshotPassesPolicy(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null): boolean;
+export declare function quotaSnapshotHasStandardWindows(quota: OAuthQuotaSnapshot | undefined): quota is OAuthQuotaSnapshot;
 export declare const DEFAULT_KILLSWITCH_THRESHOLDS: Record<QuotaWindowName | 'scoped', number>;
 export declare function normalizeKillswitchThresholds(thresholds: KillswitchThresholds | undefined): Record<QuotaWindowName | 'scoped', number>;
 export declare function isKillswitchEnabled(storage: AccountStorage | null): boolean;
@@ -403,5 +476,8 @@ export declare class FallbackAccountManager {
     }): Promise<OAuthAccount>;
     private waitForConcurrentFallbackRefresh;
     private refreshAccountNow;
-    refreshAccountQuota(account: OAuthAccount, storage: AccountStorage): Promise<OAuthAccount>;
+    refreshAccountQuota(account: OAuthAccount, storage: AccountStorage): Promise<{
+        account: OAuthAccount;
+        fetched: boolean;
+    }>;
 }