@cortexkit/anthropic-auth-core 1.19.1 → 1.20.0

package/dist/quota-manager.d.ts

@@ -12,6 +12,11 @@ export type QuotaEntry = {
     refreshAfter: number;
     checkedAt: number;
 };
+export type QuotaRefreshResult = {
+    quota: OAuthQuotaSnapshot;
+    /** False when backoff or a cross-process lock served the existing cache. */
+    fetched: boolean;
+};
 export type QuotaManagerOptions = {
     storage: AccountStorage | null;
     fetchImpl?: typeof fetch;
@@ -58,7 +63,9 @@ export declare class QuotaManager {
     pushMainFromHeaders(accessToken: string, incoming: OAuthQuotaSnapshot): QuotaEntry;
     pushFallbackFromHeaders(accountId: string, accessToken: string, incoming: OAuthQuotaSnapshot): QuotaEntry;
     refreshMain(accessToken: string): Promise<OAuthQuotaSnapshot>;
+    refreshMainWithMetadata(accessToken: string): Promise<QuotaRefreshResult>;
     refreshFallback(accountId: string, accessToken: string): Promise<OAuthQuotaSnapshot>;
+    refreshFallbackWithMetadata(accountId: string, accessToken: string): Promise<QuotaRefreshResult>;
     refreshAllFallbacks(accounts: OAuthAccount[]): Promise<void>;
     /**
      * Fire-and-forget refresh. Does not await, swallows errors.

package/dist/quota-manager.js

@@ -5,10 +5,10 @@
  * share one QuotaManager instance so they see the same in-memory cache.
  * Handles deduplication, rate-limiting (429 backoff), and staleness.
  */
-import { acquireRefreshFileLock, buildQuotaOperationError, fetchOAuthQuotaSnapshot, getPersistedMainQuota, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getQuotaRefreshEveryNRequests, getScopedQuotaWindowForModel, isQuotaPolicyAuthError, quotaBackoffActive, } from "./accounts.js";
-import { mergeHeaderQuotaSnapshot } from "./quota-headers.js";
-export { tokenFingerprint } from "./token-fingerprint.js";
-import { tokenFingerprint } from "./token-fingerprint.js";
+import { acquireRefreshFileLock, buildQuotaOperationError, fetchOAuthQuotaSnapshot, getPersistedMainQuota, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getQuotaRefreshEveryNRequests, getScopedQuotaWindowForModel, isQuotaPolicyAuthError, quotaBackoffActive, quotaSnapshotCheckedAt, } from './accounts.js';
+import { mergeHeaderQuotaSnapshot } from './quota-headers.js';
+export { tokenFingerprint } from './token-fingerprint.js';
+import { tokenFingerprint } from './token-fingerprint.js';
 // Capture real setTimeout before tests can mock globalThis.setTimeout
 const nativeSetTimeout = globalThis.setTimeout;
 function mergePollCompletionWithNewerHeaders(current, polled) {
@@ -158,6 +158,9 @@ export class QuotaManager {
     // Refresh (async, deduplicated, rate-limited)
     // =========================================================================
     async refreshMain(accessToken) {
+        return (await this.refreshMainWithMetadata(accessToken)).quota;
+    }
+    async refreshMainWithMetadata(accessToken) {
         // If the main account/token changed, invalidate the cache (including a
         // persisted seed) BEFORE the backoff short-circuit so a different account's
         // stale quota is never returned while the quota API is backed off.
@@ -172,7 +175,7 @@ export class QuotaManager {
         // Rate-limit — if API recently 429'd, return stale or throw
         if (this.isBackedOff()) {
             if (this.main)
-                return this.main.quota;
+                return { quota: this.main.quota, fetched: false };
             throw new Error('Quota API rate-limited — try again later');
         }
         this.inflightMainFp = fp;
@@ -180,6 +183,10 @@ export class QuotaManager {
         return this.inflightMain;
     }
     async refreshFallback(accountId, accessToken) {
+        return (await this.refreshFallbackWithMetadata(accountId, accessToken))
+            .quota;
+    }
+    async refreshFallbackWithMetadata(accountId, accessToken) {
         // Deduplicate per account+token so a same-label re-login never joins a
         // quota probe that was started with the previous credentials.
         const inflightKey = QuotaManager.fallbackInflightKey(accountId, accessToken);
@@ -190,7 +197,7 @@ export class QuotaManager {
         if (this.isFallbackBackedOff(accountId, accessToken)) {
             const cached = this.getFallback(accountId, accessToken);
             if (cached)
-                return cached.quota;
+                return { quota: cached.quota, fetched: false };
             throw new Error('Quota API rate-limited — try again later');
         }
         const promise = this._fetchFallback(accountId, accessToken);
@@ -319,7 +326,7 @@ export class QuotaManager {
                 continue;
             if (!account.quota)
                 continue;
-            const checkedAt = Math.max(account.quota.five_hour?.checkedAt ?? 0, account.quota.seven_day?.checkedAt ?? 0);
+            const checkedAt = quotaSnapshotCheckedAt(account.quota);
             if (checkedAt <= 0)
                 continue;
             const existing = this.getFallback(account.id, account.access);
@@ -397,7 +404,7 @@ export class QuotaManager {
                 // a preceding queued call while we waited
                 if (this.isBackedOff()) {
                     if (this.main)
-                        return this.main.quota;
+                        return { quota: this.main.quota, fetched: false };
                     throw new Error('Quota API rate-limited — try again later');
                 }
                 const fileLock = await acquireRefreshFileLock({
@@ -406,8 +413,9 @@ export class QuotaManager {
                 });
                 if (!fileLock) {
                     const cached = this.main;
-                    if (cached && this.now() < cached.refreshAfter)
-                        return cached.quota;
+                    if (cached && this.now() < cached.refreshAfter) {
+                        return { quota: cached.quota, fetched: false };
+                    }
                     throw new Error('Quota refresh is already in progress');
                 }
                 try {
@@ -427,7 +435,7 @@ export class QuotaManager {
                     };
                     this.mainLastApiError = undefined;
                     this.onMainQuotaFetched?.(completedQuota, now, this.mainTokenFp, fetchStartedAt);
-                    return completedQuota;
+                    return { quota: completedQuota, fetched: true };
                 }
                 catch (error) {
                     this._handleMainFetchError(error);
@@ -452,7 +460,7 @@ export class QuotaManager {
                 if (this.isFallbackBackedOff(accountId, accessToken)) {
                     const cached = this.getFallback(accountId, accessToken);
                     if (cached)
-                        return cached.quota;
+                        return { quota: cached.quota, fetched: false };
                     throw new Error('Quota API rate-limited — try again later');
                 }
                 const fileLock = await acquireRefreshFileLock({
@@ -461,8 +469,9 @@ export class QuotaManager {
                 });
                 if (!fileLock) {
                     const cached = this.getFallback(accountId, accessToken);
-                    if (cached && this.now() < cached.refreshAfter)
-                        return cached.quota;
+                    if (cached && this.now() < cached.refreshAfter) {
+                        return { quota: cached.quota, fetched: false };
+                    }
                     throw new Error('Quota refresh is already in progress');
                 }
                 try {
@@ -480,7 +489,7 @@ export class QuotaManager {
                     }, accessToken);
                     this.fallbackApiErrors.delete(accountId);
                     this.fallbackErrorTokenFps.delete(accountId);
-                    return completedQuota;
+                    return { quota: completedQuota, fetched: true };
                 }
                 finally {
                     await fileLock.release();

package/dist/quotas.d.ts

@@ -11,13 +11,13 @@ export type QuotaAccountSummary = {
 };
 export declare function formatQuotaMoney(money: QuotaMoney): string;
 export declare function buildFallbackQuotaSummaries(storage: AccountStorage | null, errors?: ReadonlyMap<string, string>): {
-    error?: string | undefined;
-    lastRefreshedAt: number | undefined;
-    tierLabel?: string | undefined;
     name: string;
-    role: "fallback";
+    role: 'fallback';
     enabled: boolean;
     quota: OAuthQuotaSnapshot | undefined;
+    tierLabel?: string | undefined;
+    lastRefreshedAt: number | undefined;
+    error?: string | undefined;
 }[];
 export declare function buildClaudeQuotaSummary(input: {
     accounts: QuotaAccountSummary[];

package/dist/quotas.js

@@ -1,5 +1,5 @@
-import { isOAuthAccount } from "./accounts.js";
-import { formatOAuthAccountTier } from "./oauth-profile.js";
+import { isOAuthAccount } from './accounts.js';
+import { formatOAuthAccountTier } from './oauth-profile.js';
 export const CLAUDE_QUOTAS_COMMAND_NAME = 'claude-quota';
 const WINDOW_LABELS = {
     five_hour: '5h',

package/dist/relay.d.ts

@@ -31,6 +31,8 @@ export declare function sendViaRelay(options: {
      * within an attempt are ignored.
      */
     onResponseHeaders?: (headers: Headers) => void;
+    dumpTag?: import('./dump.ts').DumpTag;
+    onDumpCreated?: (handle: import('./dump.ts').DumpHandle) => void;
     setTimeoutImpl?: typeof globalThis.setTimeout;
     clearTimeoutImpl?: typeof globalThis.clearTimeout;
 }): Promise<Response>;

package/dist/relay.js

@@ -1,7 +1,7 @@
 import { Buffer } from 'node:buffer';
 import { createHash, randomBytes } from 'node:crypto';
-import { dumpRelayRequest } from "./dump.js";
-import { relayLog } from "./logger.js";
+import { dumpRelayRequest } from './dump.js';
+import { relayLog } from './logger.js';
 class RelayStateMismatchError extends Error {
 }
 class RelayWebSocketConnectionResetError extends Error {
@@ -752,7 +752,7 @@ function getPersistentRelaySession(config, affinity, timers) {
     return session;
 }
 export async function sendViaRelay(options) {
-    const { config, input, init, headers, body, fallback, affinity: explicitAffinity, optimisticResponse, onResponseHeaders, setTimeoutImpl = globalThis.setTimeout, clearTimeoutImpl = globalThis.clearTimeout, } = options;
+    const { config, input, init, headers, body, fallback, affinity: explicitAffinity, optimisticResponse, onResponseHeaders, dumpTag, onDumpCreated, setTimeoutImpl = globalThis.setTimeout, clearTimeoutImpl = globalThis.clearTimeout, } = options;
     if (!config || !isRelayableAnthropicRequest(input, body))
         return fallback();
     const affinity = explicitAffinity ||
@@ -848,7 +848,7 @@ export async function sendViaRelay(options) {
         });
         relayLog(`used relay transport=${result.transport} protocol=${result.protocol} mode=${result.payload.mode} status=${result.response.status} session=${shortAffinity(affinity)} bodyBytes=${bodyText.length} relayBytes=${actualPayloadBytes}`);
         const dumpStart = perfNowMs();
-        await dumpRelayRequest({
+        const dumpHandle = await dumpRelayRequest({
             affinity,
             transport: result.transport,
             protocol: result.protocol,
@@ -858,7 +858,13 @@ export async function sendViaRelay(options) {
             previousBodyText: previous?.body,
             payload: result.payload,
             relayBytes: actualPayloadBytes,
+            tag: dumpTag,
         });
+        try {
+            if (dumpHandle)
+                onDumpCreated?.(dumpHandle);
+        }
+        catch { }
         relayPerfLog('dump', {
             session: shortAffinity(affinity),
             ms: formatMs(perfNowMs() - dumpStart),

package/dist/routing.d.ts

@@ -1,6 +1,6 @@
 import { type AccountStorage, type RoutingMode } from './accounts.ts';
 export declare const CLAUDE_ROUTING_COMMAND_NAME = "claude-routing";
-export declare const ROUTING_MODES: readonly ["main-first", "fallback-first", "sticky-balanced"];
+export declare const ROUTING_MODES: readonly ['main-first', 'fallback-first', 'sticky-balanced'];
 export declare const DEFAULT_ROUTING_MODE: RoutingMode;
 type RoutingCommandAction = {
     type: 'status';

package/dist/routing.js

@@ -1,4 +1,4 @@
-import { createEmptyStorage, getAccountStoragePath, loadAccounts, saveAccounts, } from "./accounts.js";
+import { createEmptyStorage, getAccountStoragePath, loadAccounts, saveAccounts, } from './accounts.js';
 export const CLAUDE_ROUTING_COMMAND_NAME = 'claude-routing';
 export const ROUTING_MODES = [
     'main-first',

package/dist/start.d.ts

@@ -0,0 +1,13 @@
+export declare const CLAUDE_START_COMMAND_NAME = "claude-start";
+export type LaneStartCommandAction = {
+    type: 'fire';
+} | {
+    type: 'usage';
+};
+export declare function parseLaneStartCommandAction(input: string): LaneStartCommandAction;
+export declare function executeLaneStartCommand(input: {
+    argumentsText: string;
+}): {
+    action: LaneStartCommandAction;
+    text: string;
+};

package/dist/start.js

@@ -0,0 +1,29 @@
+export const CLAUDE_START_COMMAND_NAME = 'claude-start';
+const START_STATUS_TITLE = '## Claude Lane Start Status';
+const START_QUEUED_TITLE = '## Claude Lane Start Queued';
+const START_USAGE_TITLE = '## Claude Lane Start Usage';
+const START_USAGE = 'Usage: `/claude-start`.';
+export function parseLaneStartCommandAction(input) {
+    const normalized = input.trim().split(/\s+/).filter(Boolean);
+    if (normalized.length === 0)
+        return { type: 'fire' };
+    return { type: 'usage' };
+}
+export function executeLaneStartCommand(input) {
+    const action = parseLaneStartCommandAction(input.argumentsText);
+    if (action.type === 'fire') {
+        return {
+            action,
+            text: [
+                START_QUEUED_TITLE,
+                '',
+                '- Queued an explicit lane-start request.',
+                '- This is a billed request: the one-token limit does not remove prompt-cache read or write charges.',
+            ].join('\n'),
+        };
+    }
+    return {
+        action,
+        text: [START_USAGE_TITLE, '', START_USAGE, '', START_STATUS_TITLE].join('\n'),
+    };
+}

package/dist/sticky-routing.d.ts

@@ -40,6 +40,7 @@ export type StickyQuotaFailureDecision = {
  */
 export declare function createStickyNoRouteResponse(input: {
     mainRefreshError?: AccountOperationError;
+    fallbackReauthLabels?: readonly string[];
     routeQuotas: readonly OAuthQuotaSnapshot[];
     modelId?: string;
     now?: number;

package/dist/sticky-routing.js

@@ -1,8 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
-import { acquireRefreshFileLock, getKillswitchThresholdsForAccount, getQuotaCheckIntervalMs, getQuotaMinimumRemainingThresholds, getScopedQuotaWindowForModel, isKillswitchEnabled, isPermanentRefreshError, killswitchRetryAfterSeconds, quotaSnapshotPassesModelScope, } from "./accounts.js";
-import { isClaudeFableOrMythos5Model } from "./models.js";
+import { acquireRefreshFileLock, getKillswitchThresholdsForAccount, getQuotaCheckIntervalMs, getQuotaMinimumRemainingThresholds, getScopedQuotaWindowForModel, isKillswitchEnabled, isPermanentRefreshError, killswitchRetryAfterSeconds, quotaSnapshotPassesModelScope, } from './accounts.js';
+import { isClaudeFableOrMythos5Model } from './models.js';
 export const STICKY_ROUTING_MAIN_ACCOUNT_ID = 'main';
 export const STICKY_ROUTING_SHORT_RESET_GRACE_MS = 15 * 60_000;
 export const STICKY_ROUTING_ASSIGNMENT_TTL_MS = 7 * 24 * 60 * 60_000;
@@ -24,13 +24,23 @@ export function createStickyNoRouteResponse(input) {
             .map((quota) => getScopedQuotaWindowForModel(quota, modelId))
             .find(Boolean)?.modelName
         : undefined;
+    let authenticationMessage;
     if (isPermanentRefreshError(input.mainRefreshError)) {
-        const message = modelName
+        authenticationMessage = modelName
             ? `Main Claude OAuth account requires re-login, and no fallback OAuth account is currently routable for ${modelName}.`
             : 'Main Claude OAuth account requires re-login, and no fallback OAuth account is currently routable.';
+    }
+    else if (input.fallbackReauthLabels?.length) {
+        const scope = modelName ? ` for ${modelName}` : '';
+        authenticationMessage = `No OAuth account is currently routable${scope}. Fallback Claude OAuth accounts require re-login: ${input.fallbackReauthLabels.join(', ')}.`;
+    }
+    if (authenticationMessage) {
         return new Response(JSON.stringify({
             type: 'error',
-            error: { type: 'authentication_error', message },
+            error: {
+                type: 'authentication_error',
+                message: authenticationMessage,
+            },
         }), {
             status: 401,
             headers: { 'content-type': 'application/json' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/anthropic-auth-core",
-  "version": "1.19.1",
+  "version": "1.20.0",
   "type": "module",
   "repository": {
     "type": "git",