@cortexkit/anthropic-auth-core 1.20.0 → 1.22.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, optional Claustrum fallback-custody primitives, model metadata, quota, host-local quota feed, routing, cache, cache-keepalive, fast mode, relay, dump, request-signing, thinking-binding, and Fable 5.1 mid-conversation effort helpers used by CortexKit's OpenCode and Pi integrations.
 
 User-facing packages:
 

package/dist/accounts.d.ts

@@ -4,6 +4,10 @@ export declare const ACCOUNT_FILE_NAME = "anthropic-auth.json";
 export declare const ACCOUNT_STATE_FILE_NAME = "anthropic-auth-state.json";
 export declare const QUOTA_URL = "https://api.anthropic.com/api/oauth/usage";
 export type QuotaWindowName = 'five_hour' | 'seven_day';
+export declare const QUOTA_FIELD_NAMES: readonly ['five_hour', 'seven_day', 'scoped', 'extraUsage', 'bindingWindow', 'fallbackAdvised'];
+export type QuotaFieldName = (typeof QUOTA_FIELD_NAMES)[number];
+export type QuotaFieldSource = 'poll' | 'headers';
+export type QuotaFieldSources = Partial<Record<QuotaFieldName, QuotaFieldSource>>;
 export type AccountBase = {
     id: string;
     label?: string;
@@ -14,6 +18,7 @@ export type AccountBase = {
 export type OAuthAccount = AccountBase & {
     type: 'oauth';
     authLineageId?: string;
+    claustrumHandle?: string;
     access?: string;
     refresh: string;
     expires?: number;
@@ -35,6 +40,12 @@ export type ApiKeyAccount = AccountBase & {
     authHeader?: 'authorization-bearer' | 'x-api-key';
 };
 export type FallbackAccount = OAuthAccount | ApiKeyAccount;
+export type ClaustrumAccountGate = {
+    enabled?: boolean;
+};
+export type ClaustrumConfig = {
+    accounts?: Record<string, ClaustrumAccountGate>;
+};
 export declare function isOAuthAccount(account: FallbackAccount): account is OAuthAccount;
 export declare function isApiKeyAccount(account: FallbackAccount): account is ApiKeyAccount;
 export declare function isValidApiBaseURL(value: string | undefined): boolean;
@@ -43,7 +54,10 @@ export type AccountOperationError = {
     checkedAt: number;
     nextRetryAt?: number;
     retryCount?: number;
+    accountIdentity?: string;
     tokenHash?: string;
+    /** Fingerprint of the refresh token that produced this error. */
+    refreshTokenFingerprint?: string;
     /**
      * HTTP status of the underlying refresh/quota failure, when known. Lets
      * consumers distinguish a permanently-dead token (400 invalid_grant →
@@ -89,13 +103,18 @@ 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;
     bindingWindowSource?: 'poll' | 'headers';
+    fieldSources?: QuotaFieldSources;
     fallbackAdvised?: boolean;
     source?: 'poll' | 'headers';
     checkedAt?: number;
@@ -132,6 +151,7 @@ export type KillswitchConfig = {
 };
 export type AccountStorage = {
     version: 1;
+    mainAccountId?: string;
     main?: {
         type: 'opencode';
         provider: 'anthropic';
@@ -146,6 +166,7 @@ export type AccountStorage = {
         intervalMinutes?: number;
         refreshBeforeExpiryMinutes?: number;
         mainLastRefreshError?: AccountOperationError;
+        mainRefreshErrorClearedAt?: number;
         mainRefreshLeaseId?: string;
         mainRefreshLeaseUntil?: number;
         mainRefreshLeaseTokenHash?: string;
@@ -162,6 +183,11 @@ export type AccountStorage = {
         mainQuotaCheckedAt?: number;
         mainQuotaToken?: string;
         mainLastQuotaApiError?: AccountOperationError;
+        mainQuotaErrorGeneration?: number;
+        mainQuotaErrorClearedAt?: number;
+    };
+    quotaHeaderFeed?: {
+        enabled?: boolean;
     };
     claudeCache?: {
         enabled?: boolean;
@@ -176,6 +202,9 @@ export type AccountStorage = {
     claudeFast?: {
         enabled?: boolean;
     };
+    thinkingBinding?: {
+        prefixMismatchBehavior?: 'account-default' | 'error' | 'drop_block';
+    };
     /**
      * Zero out Anthropic OAuth model costs in the provider hook. Default: enabled
      * (OAuth usage is quota-based, not per-token billed, so costs show as $0).
@@ -205,6 +234,7 @@ export type AccountStorage = {
         fallbackToDirect?: boolean;
         transport?: 'http' | 'websocket';
     };
+    claustrum?: ClaustrumConfig;
     killswitch?: KillswitchConfig;
     accounts: FallbackAccount[];
 };
@@ -214,7 +244,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' | 'authLineageId' | 'refresh' | 'expires' | 'lastUsed' | 'lastRefreshedAt' | 'lastRefreshError' | 'lastQuotaRefreshError' | 'quota' | 'profile' | 'prime'> & Pick<ApiKeyAccount, 'apiKey' | 'lastUsed'>>;
+export type AccountRuntimeEntry = Partial<Pick<OAuthAccount, 'access' | 'authLineageId' | 'claustrumHandle' | 'refresh' | 'expires' | 'lastUsed' | 'lastRefreshedAt' | 'lastRefreshError' | 'lastQuotaRefreshError' | 'quota' | 'profile' | 'prime'> & Pick<ApiKeyAccount, 'apiKey' | 'lastUsed'>>;
 export type AccountRuntimeState = {
     version: 1;
     main?: {
@@ -224,7 +254,10 @@ export type AccountRuntimeState = {
         quotaCheckedAt?: number;
         quotaToken?: string;
         lastQuotaApiError?: AccountOperationError;
+        quotaErrorGeneration?: number;
+        quotaErrorClearedAt?: number;
         lastRefreshError?: AccountOperationError;
+        refreshErrorClearedAt?: number;
         refreshLeaseId?: string;
         refreshLeaseUntil?: number;
         refreshLeaseTokenHash?: string;
@@ -246,6 +279,13 @@ export type AccountManagerOptions = {
     fetchImpl?: typeof fetch;
     configPath?: string;
     quotaManager?: import('./quota-manager.ts').QuotaManager;
+    isFallbackAccountVaultServed?: (accountId: string, storage: AccountStorage) => boolean;
+    isFallbackAccountVaultEnabled?: (accountId: string, storage: AccountStorage) => boolean;
+    resolveFallbackAccessToken?: (account: OAuthAccount, storage: AccountStorage) => {
+        token: string;
+        source: 'vault' | 'sidecar';
+    } | undefined;
+    onBackgroundRefresh?: (initial?: boolean) => Promise<void> | void;
     onFallbackStorageChanged?: () => void;
     setIntervalImpl?: typeof globalThis.setInterval;
     clearIntervalImpl?: typeof globalThis.clearInterval;
@@ -254,12 +294,18 @@ export type AccountRefreshError = {
     accountId: string;
     message: string;
 };
+export declare const FALLBACK_BACKGROUND_TICK_MS = 60000;
 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 mergeMainRefreshErrorClearedAt(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 quotaFieldSource(snapshot: OAuthQuotaSnapshot | undefined, field: QuotaFieldName): QuotaFieldSource | undefined;
+export declare function mergeHeaderQuotaForPersistence(existing: OAuthQuotaSnapshot | undefined, incoming: OAuthQuotaSnapshot): OAuthQuotaSnapshot;
+export declare function isClaustrumEnabledForAccount(storage: AccountStorage, accountId: string): boolean;
 export interface SaveAccountsOptions {
     /** Account ids intentionally removed by this mutation. */
     removedAccountIds?: readonly string[];
@@ -267,12 +313,14 @@ 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 clearClaustrumRefreshErrorPersistent(accountId: string, handle: string, path?: string): Promise<boolean>;
 export declare function acquireRefreshFileLock(options: {
     name: string;
     ttlMs: number;
@@ -299,17 +347,8 @@ export declare function isCacheKeepSubagentsEnabled(storage: AccountStorage | nu
 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, seeding it in
- * runtime state when older storage has no lineage yet. Main lookups return
- * undefined when the live refresh token is unavailable and no lineage exists.
- */
-export declare function getOrCreatePrimeAuthLineageId(accountId: 'main' | string, path?: string, mainRefreshToken?: string): Promise<string | undefined>;
-/** Advance a main lineage across a refresh performed by this plugin. */
-export declare function continueMainPrimeAuthLineageAfterRefresh(input: {
-    previousRefreshToken: string;
-    currentRefreshToken: string;
-}, path?: string): Promise<void>;
+/** 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;
@@ -324,12 +363,14 @@ export declare function getQuotaMinimumRemainingThresholds(storage: AccountStora
     five_hour: number;
     seven_day: number;
 };
+export declare function getRefreshBeforeExpiryMs(storage: AccountStorage | null): number;
 export declare function getRefreshIntervalMs(storage: AccountStorage | null): number;
 export declare function hashRefreshToken(refreshToken: string): string;
 export declare function buildRefreshOperationError(input: {
     error: unknown;
     now: number;
-    refreshToken: string;
+    accountIdentity: string | undefined;
+    refreshTokenFingerprint?: string;
     previous?: AccountOperationError;
 }): AccountOperationError;
 /**
@@ -348,13 +389,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, currentRefreshTokenFingerprint: string | undefined): 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;
@@ -366,6 +408,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.
@@ -376,6 +419,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;
@@ -426,6 +470,10 @@ export declare class FallbackAccountManager {
     private refreshTimer;
     private quotaTimer;
     readonly quotaManager: import('./quota-manager.ts').QuotaManager | null;
+    private readonly isFallbackAccountVaultServed;
+    private readonly isFallbackAccountVaultEnabled;
+    private readonly resolveFallbackAccessToken;
+    private readonly onBackgroundRefresh;
     private readonly onFallbackStorageChanged;
     private readonly setIntervalImpl;
     private readonly clearIntervalImpl;
@@ -437,7 +485,7 @@ export declare class FallbackAccountManager {
     private seedFallbackQuota;
     load(): Promise<AccountStorage | null>;
     save(storage: AccountStorage, accountIds?: string[]): Promise<void>;
-    startBackgroundRefresh(): void;
+    startBackgroundRefresh(): Promise<void>;
     stopBackgroundRefresh(): void;
     getUsableFallbackAccounts(existingStorage?: AccountStorage | null, options?: {
         modelId?: string;
@@ -463,11 +511,13 @@ export declare class FallbackAccountManager {
     }>;
     refreshAccount(account: OAuthAccount, storage: AccountStorage, options?: {
         force?: boolean;
+        persistError?: boolean;
     }): Promise<OAuthAccount>;
     private waitForConcurrentFallbackRefresh;
     private refreshAccountNow;
     refreshAccountQuota(account: OAuthAccount, storage: AccountStorage): Promise<{
         account: OAuthAccount;
         fetched: boolean;
+        changed: boolean;
     }>;
 }