@cortexkit/anthropic-auth-core 1.1.0 → 1.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @cortexkit/anthropic-auth-core
 
-Shared Anthropic OAuth, quota, cache, fast mode, relay, dump, and request-signing helpers used by CortexKit's OpenCode and Pi integrations.
+Shared Anthropic OAuth, quota, 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

@@ -20,6 +20,9 @@ export type OAuthAccount = {
 export type AccountOperationError = {
     message: string;
     checkedAt: number;
+    nextRetryAt?: number;
+    retryCount?: number;
+    tokenHash?: string;
 };
 export type AccountQuotaWindow = {
     usedPercent: number;
@@ -38,6 +41,10 @@ export type AccountStorage = {
         enabled?: boolean;
         intervalMinutes?: number;
         refreshBeforeExpiryMinutes?: number;
+        mainLastRefreshError?: AccountOperationError;
+        mainRefreshLeaseId?: string;
+        mainRefreshLeaseUntil?: number;
+        mainRefreshLeaseTokenHash?: string;
     };
     quota?: {
         enabled?: boolean;
@@ -55,6 +62,11 @@ export type AccountStorage = {
     claudeFast?: {
         enabled?: boolean;
     };
+    cacheKeep?: {
+        enabled?: boolean;
+        startHour?: number;
+        endHour?: number;
+    };
     relay?: {
         enabled?: boolean;
         url?: string;
@@ -85,7 +97,19 @@ export declare function isDumpPersistentlyEnabled(storage: AccountStorage | null
 export declare function setDumpPersistentEnabled(enabled: boolean, path?: string): Promise<AccountStorage>;
 export declare function isFastModePersistentlyEnabled(storage: AccountStorage | null): boolean;
 export declare function setFastModePersistentEnabled(enabled: boolean, path?: string): Promise<AccountStorage>;
+export declare function setCacheKeepPersistentWindow(startHour: number, endHour: number, path?: string): Promise<AccountStorage>;
+export declare function setCacheKeepPersistentEnabled(enabled: boolean, path?: string): Promise<AccountStorage>;
 export declare function shouldFallbackStatus(status: number, storage: AccountStorage | null): boolean;
+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;
+    previous?: AccountOperationError;
+}): AccountOperationError;
+export declare function refreshBackoffActive(error: AccountOperationError | undefined, refreshToken: string | undefined, now: number): boolean;
+export declare function formatRefreshBackoffMessage(error: AccountOperationError, now: number): string;
 export declare function getQuotaCheckIntervalMs(storage: AccountStorage | null): number;
 export declare function quotaSnapshotPassesPolicy(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null): boolean;
 export declare function getQuotaNextRefreshAt(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null, now: number): number;

package/dist/accounts.js

@@ -1,13 +1,18 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { refreshClaudeOAuthToken } from "./auth.js";
+import { ClaudeOAuthRefreshError, refreshClaudeOAuthToken } from "./auth.js";
 import { CACHE_1H_MODES, CLAUDE_CODE_VERSION, DEFAULT_CACHE_1H_MODE, } from "./constants.js";
+import { log } from "./logger.js";
 export const ACCOUNT_FILE_NAME = 'anthropic-auth.json';
 export const QUOTA_URL = 'https://api.anthropic.com/api/oauth/usage';
 const DEFAULT_FALLBACK_ON = [401, 403, 429];
 const DEFAULT_REFRESH_BEFORE_EXPIRY_MINUTES = 30;
+const DEFAULT_REFRESH_INTERVAL_MINUTES = 10;
+const MIN_REFRESH_RETRY_DELAY_MS = 5 * 60_000;
+const MAX_REFRESH_RETRY_DELAY_MS = 60 * 60_000;
+const NON_TRANSIENT_REFRESH_RETRY_DELAY_MS = 24 * 60 * 60_000;
 const DEFAULT_QUOTA_CHECK_INTERVAL_MINUTES = 5;
 const DEFAULT_MINIMUM_REMAINING = {
     five_hour: 0,
@@ -63,7 +68,15 @@ function normalizeOperationError(value) {
     const checkedAt = Number(value.checkedAt);
     if (!Number.isFinite(checkedAt))
         return undefined;
-    return { message: value.message, checkedAt };
+    const nextRetryAt = Number(value.nextRetryAt);
+    const retryCount = Number(value.retryCount);
+    return {
+        message: value.message,
+        checkedAt,
+        nextRetryAt: Number.isFinite(nextRetryAt) ? nextRetryAt : undefined,
+        retryCount: Number.isFinite(retryCount) ? retryCount : undefined,
+        tokenHash: typeof value.tokenHash === 'string' ? value.tokenHash : undefined,
+    };
 }
 function normalizeQuota(value) {
     if (!isRecord(value))
@@ -104,6 +117,7 @@ function normalizeStorage(value) {
         claudeCache: isRecord(value.claudeCache) ? value.claudeCache : undefined,
         dump: isRecord(value.dump) ? value.dump : undefined,
         claudeFast: isRecord(value.claudeFast) ? value.claudeFast : undefined,
+        cacheKeep: isRecord(value.cacheKeep) ? value.cacheKeep : undefined,
         relay: isRecord(value.relay) ? value.relay : undefined,
         accounts: value.accounts
             .map(normalizeAccount)
@@ -217,6 +231,33 @@ export async function setFastModePersistentEnabled(enabled, path = getAccountSto
     await saveAccounts(storage, path);
     return storage;
 }
+export async function setCacheKeepPersistentWindow(startHour, endHour, path = getAccountStoragePath()) {
+    const storage = (await loadAccounts(path)) ?? {
+        version: 1,
+        main: { type: 'opencode', provider: 'anthropic' },
+        accounts: [],
+    };
+    storage.cacheKeep = {
+        enabled: true,
+        startHour,
+        endHour,
+    };
+    await saveAccounts(storage, path);
+    return storage;
+}
+export async function setCacheKeepPersistentEnabled(enabled, path = getAccountStoragePath()) {
+    const storage = (await loadAccounts(path)) ?? {
+        version: 1,
+        main: { type: 'opencode', provider: 'anthropic' },
+        accounts: [],
+    };
+    storage.cacheKeep = {
+        ...(storage.cacheKeep ?? {}),
+        enabled,
+    };
+    await saveAccounts(storage, path);
+    return storage;
+}
 function getFallbackStatuses(storage) {
     return storage?.fallbackOn?.length ? storage.fallbackOn : DEFAULT_FALLBACK_ON;
 }
@@ -245,6 +286,54 @@ function refreshBeforeExpiryMs(storage) {
         DEFAULT_REFRESH_BEFORE_EXPIRY_MINUTES;
     return Math.max(0, minutes) * 60_000;
 }
+export function getRefreshIntervalMs(storage) {
+    const minutes = storage?.refresh?.intervalMinutes ?? DEFAULT_REFRESH_INTERVAL_MINUTES;
+    return Math.max(1, minutes) * 60_000;
+}
+export function hashRefreshToken(refreshToken) {
+    return createHash('sha256').update(refreshToken).digest('hex');
+}
+function isTransientRefreshError(error) {
+    if (error instanceof ClaudeOAuthRefreshError) {
+        return error.status === 429 || error.status >= 500;
+    }
+    if (!(error instanceof Error))
+        return false;
+    return (error.message.includes('fetch failed') ||
+        ('code' in error &&
+            (error.code === 'ECONNRESET' ||
+                error.code === 'ECONNREFUSED' ||
+                error.code === 'ETIMEDOUT' ||
+                error.code === 'UND_ERR_CONNECT_TIMEOUT')));
+}
+export function buildRefreshOperationError(input) {
+    const tokenHash = hashRefreshToken(input.refreshToken);
+    const previousRetryCount = input.previous?.tokenHash === tokenHash
+        ? (input.previous.retryCount ?? 0)
+        : 0;
+    const retryCount = previousRetryCount + 1;
+    const delay = isTransientRefreshError(input.error)
+        ? Math.min(MAX_REFRESH_RETRY_DELAY_MS, MIN_REFRESH_RETRY_DELAY_MS * 2 ** Math.min(retryCount - 1, 6))
+        : NON_TRANSIENT_REFRESH_RETRY_DELAY_MS;
+    return {
+        message: formatErrorMessage(input.error),
+        checkedAt: input.now,
+        nextRetryAt: input.now + delay,
+        retryCount,
+        tokenHash,
+    };
+}
+export function refreshBackoffActive(error, refreshToken, now) {
+    if (!error?.nextRetryAt || error.nextRetryAt <= now)
+        return false;
+    if (!refreshToken)
+        return true;
+    return error.tokenHash === hashRefreshToken(refreshToken);
+}
+export function formatRefreshBackoffMessage(error, now) {
+    const seconds = Math.max(1, Math.ceil(((error.nextRetryAt ?? now) - now) / 1000));
+    return `Claude OAuth refresh is backed off for ${seconds}s after: ${error.message}`;
+}
 export function getQuotaCheckIntervalMs(storage) {
     const minutes = storage?.quota?.checkIntervalMinutes ?? DEFAULT_QUOTA_CHECK_INTERVAL_MINUTES;
     return Math.max(1, minutes) * 60_000;
@@ -353,16 +442,21 @@ function formatErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function recordRefreshError(account, error, now) {
-    account.lastRefreshError = {
-        message: formatErrorMessage(error),
-        checkedAt: now,
-    };
+    account.lastRefreshError = buildRefreshOperationError({
+        error,
+        now,
+        refreshToken: account.refresh,
+        previous: account.lastRefreshError,
+    });
 }
 function recordQuotaRefreshError(account, error, now) {
     account.lastQuotaRefreshError = {
         message: formatErrorMessage(error),
         checkedAt: now,
     };
+    if (error instanceof ClaudeOAuthRefreshError) {
+        recordRefreshError(account, error, now);
+    }
 }
 export class FallbackAccountManager {
     now;
@@ -383,22 +477,18 @@ export class FallbackAccountManager {
         await saveAccounts(storage, this.configPath);
     }
     startBackgroundRefresh() {
-        void this.refreshDueAccounts().catch(() => { });
-        void this.refreshQuotaForDueAccounts().catch(() => { });
+        const run = async () => {
+            await this.refreshDueAccounts();
+            await this.refreshQuotaForDueAccounts();
+        };
+        void run().catch(() => { });
         if (!this.refreshTimer) {
             this.refreshTimer = setInterval(() => {
-                void this.refreshDueAccounts().catch(() => { });
+                void run().catch(() => { });
             }, BACKGROUND_TICK_MS);
             if ('unref' in this.refreshTimer)
                 this.refreshTimer.unref();
         }
-        if (!this.quotaTimer) {
-            this.quotaTimer = setInterval(() => {
-                void this.refreshQuotaForDueAccounts().catch(() => { });
-            }, BACKGROUND_TICK_MS);
-            if ('unref' in this.quotaTimer)
-                this.quotaTimer.unref();
-        }
     }
     stopBackgroundRefresh() {
         if (this.refreshTimer)
@@ -420,6 +510,11 @@ export class FallbackAccountManager {
             try {
                 let next = account;
                 if (tokenNeedsRefresh(next, storage, this.now())) {
+                    const refreshError = next.lastRefreshError;
+                    if (refreshError &&
+                        refreshBackoffActive(refreshError, next.refresh, this.now())) {
+                        throw new Error(formatRefreshBackoffMessage(refreshError, this.now()));
+                    }
                     next = await this.refreshAccount(next, storage);
                     changed = true;
                 }
@@ -462,11 +557,29 @@ export class FallbackAccountManager {
                 continue;
             if (!tokenNeedsRefresh(account, storage, this.now()))
                 continue;
+            if (refreshBackoffActive(account.lastRefreshError, account.refresh, this.now())) {
+                log('[refresh] fallback oauth skipped backoff', {
+                    accountId: account.id,
+                    nextRetryAt: account.lastRefreshError?.nextRetryAt,
+                    retryCount: account.lastRefreshError?.retryCount,
+                });
+                continue;
+            }
             try {
+                log('[refresh] fallback oauth background due', {
+                    accountId: account.id,
+                    expiresInMs: account.expires
+                        ? account.expires - this.now()
+                        : undefined,
+                });
                 await this.refreshAccount(account, storage);
                 changed = true;
             }
             catch (error) {
+                log('[refresh] fallback oauth background failed', {
+                    accountId: account.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
                 recordRefreshError(account, error, this.now());
                 updateStoredAccount(storage, account);
                 changed = true;
@@ -487,6 +600,9 @@ export class FallbackAccountManager {
             let next = account;
             try {
                 if (tokenNeedsRefresh(next, storage, this.now())) {
+                    if (refreshBackoffActive(next.lastRefreshError, next.refresh, this.now())) {
+                        continue;
+                    }
                     next = await this.refreshAccount(next, storage);
                     changed = true;
                 }
@@ -517,6 +633,11 @@ export class FallbackAccountManager {
             let next = account;
             try {
                 if (tokenNeedsRefresh(next, storage, this.now())) {
+                    const refreshError = next.lastRefreshError;
+                    if (refreshError &&
+                        refreshBackoffActive(refreshError, next.refresh, this.now())) {
+                        throw new Error(formatRefreshBackoffMessage(refreshError, this.now()));
+                    }
                     next = await this.refreshAccount(next, storage);
                     changed = true;
                 }
@@ -563,6 +684,13 @@ export class FallbackAccountManager {
         }
         const sourceAccount = latestAccount ?? account;
         const refreshToken = sourceAccount.refresh;
+        log('[refresh] fallback oauth refresh request start', {
+            accountId: sourceAccount.id,
+            force: options.force === true,
+            expiresInMs: sourceAccount.expires
+                ? sourceAccount.expires - this.now()
+                : undefined,
+        });
         const refreshed = await refreshClaudeOAuthToken({
             refreshToken,
             fetchImpl: this.fetchImpl,
@@ -575,6 +703,12 @@ export class FallbackAccountManager {
             refreshed.expires - refreshed.expiresIn * 1000;
         sourceAccount.lastRefreshError = undefined;
         updateStoredAccount(storage, sourceAccount);
+        log('[refresh] fallback oauth refresh succeeded', {
+            accountId: sourceAccount.id,
+            expiresInMs: sourceAccount.expires
+                ? sourceAccount.expires - this.now()
+                : undefined,
+        });
         return sourceAccount;
     }
     async refreshAccountQuota(account, storage) {

package/dist/cachekeep.d.ts

@@ -0,0 +1,92 @@
+import type { AccountStorage } from './accounts.ts';
+export declare const CLAUDE_CACHE_KEEP_COMMAND_NAME = "claude-cachekeep";
+export declare const CACHE_KEEP_TTL_MS: number;
+export declare const CACHE_KEEP_PREWARM_LEAD_MS: number;
+export declare const CACHE_KEEP_TICK_MS = 60000;
+export declare const CACHE_KEEP_EXTENDED_TTL_BETA = "extended-cache-ttl-2025-04-11";
+export type CacheKeepWindow = {
+    startHour: number;
+    endHour: number;
+};
+export type CacheKeepCommandAction = {
+    type: 'status';
+} | {
+    type: 'disable';
+} | {
+    type: 'window';
+    startHour: number;
+    endHour: number;
+} | {
+    type: 'usage';
+};
+export type CacheKeepStatus = {
+    enabled: boolean;
+    window?: CacheKeepWindow;
+    trackedSessions?: number;
+    nextPrewarmAt?: number;
+    hybridActive?: boolean;
+};
+export declare function parseCacheKeepCommandAction(input: string): CacheKeepCommandAction;
+export declare function getCacheKeepWindow(storage: AccountStorage | null): CacheKeepWindow | undefined;
+export declare function isCacheKeepPersistentlyEnabled(storage: AccountStorage | null): boolean;
+export declare function isCacheKeepHybridActive(storage: AccountStorage | null): boolean;
+export declare function isWithinCacheKeepWindow(window: CacheKeepWindow | undefined, now?: Date): boolean;
+export declare function localDayKey(now?: Date): string;
+export declare function buildCacheKeepStatusSummary(status: CacheKeepStatus): string;
+export declare function executeCacheKeepCommand(input: {
+    argumentsText: string;
+    enabled?: boolean;
+    window?: CacheKeepWindow;
+    trackedSessions?: number;
+    nextPrewarmAt?: number;
+    hybridActive?: boolean;
+}): string;
+export declare function buildCacheKeepPrewarmBody(bodyText: string): Promise<{
+    ok: true;
+    bodyText: string;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export type CacheKeepTarget = {
+    id: string;
+    url: string;
+    headers: Record<string, string>;
+    bodyText: string;
+    cacheExpiresAt: number;
+    dayKey: string;
+};
+export declare class CacheKeepManager {
+    private readonly options;
+    private readonly targets;
+    private timer;
+    constructor(options: {
+        loadStorage: () => Promise<AccountStorage | null>;
+        fetchImpl?: typeof fetch;
+        now?: () => number;
+        prepareHeaders?: (headers: Headers, target: CacheKeepTarget) => Promise<Headers> | Headers;
+        log?: (message: string, data?: Record<string, unknown>) => void;
+    });
+    start(): void;
+    stop(): void;
+    stats(window?: CacheKeepWindow, now?: number): {
+        trackedSessions: number;
+        nextPrewarmAt: number | undefined;
+    };
+    track(input: {
+        sessionId?: string | null;
+        url: string;
+        headers: Headers;
+        bodyText: string;
+        storage: AccountStorage | null;
+        cacheMode: string;
+    }): {
+        tracked: boolean;
+        reason: string;
+    } | {
+        tracked: boolean;
+        reason?: undefined;
+    };
+    tick(): Promise<void>;
+    private prewarm;
+}

package/dist/cachekeep.js

@@ -0,0 +1,297 @@
+import { CCH_PATTERN, signRequestBody } from "./cch.js";
+import { orderClaudeCodeBody } from "./claude-code.js";
+export const CLAUDE_CACHE_KEEP_COMMAND_NAME = 'claude-cachekeep';
+export const CACHE_KEEP_TTL_MS = 60 * 60_000;
+export const CACHE_KEEP_PREWARM_LEAD_MS = 5 * 60_000;
+export const CACHE_KEEP_TICK_MS = 60_000;
+export const CACHE_KEEP_EXTENDED_TTL_BETA = 'extended-cache-ttl-2025-04-11';
+const STATUS_TITLE = '## Claude Cache Keep Status';
+const ENABLED_TITLE = '## Claude Cache Keep Enabled';
+const DISABLED_TITLE = '## Claude Cache Keep Disabled';
+const USAGE_TITLE = '## Claude Cache Keep Usage';
+const USAGE = 'Usage: `/claude-cachekeep`, `/claude-cachekeep off`, or `/claude-cachekeep HH-HH`.';
+function padHour(hour) {
+    return String(hour).padStart(2, '0');
+}
+export function parseCacheKeepCommandAction(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return { type: 'status' };
+    if (trimmed === 'off')
+        return { type: 'disable' };
+    const match = /^(\d{1,2})-(\d{1,2})$/.exec(trimmed);
+    if (!match)
+        return { type: 'usage' };
+    const startHour = Number(match[1]);
+    const endHour = Number(match[2]);
+    if (!Number.isInteger(startHour) ||
+        !Number.isInteger(endHour) ||
+        startHour < 0 ||
+        startHour > 23 ||
+        endHour < 0 ||
+        endHour > 23 ||
+        startHour === endHour) {
+        return { type: 'usage' };
+    }
+    return { type: 'window', startHour, endHour };
+}
+export function getCacheKeepWindow(storage) {
+    const startHour = Number(storage?.cacheKeep?.startHour);
+    const endHour = Number(storage?.cacheKeep?.endHour);
+    if (!Number.isInteger(startHour) ||
+        !Number.isInteger(endHour) ||
+        startHour < 0 ||
+        startHour > 23 ||
+        endHour < 0 ||
+        endHour > 23 ||
+        startHour === endHour) {
+        return undefined;
+    }
+    return { startHour, endHour };
+}
+export function isCacheKeepPersistentlyEnabled(storage) {
+    return storage?.cacheKeep?.enabled === true && !!getCacheKeepWindow(storage);
+}
+export function isCacheKeepHybridActive(storage) {
+    return (isCacheKeepPersistentlyEnabled(storage) &&
+        storage?.claudeCache?.enabled === true &&
+        storage.claudeCache.mode === 'hybrid');
+}
+export function isWithinCacheKeepWindow(window, now = new Date()) {
+    if (!window)
+        return false;
+    const hour = now.getHours();
+    if (window.startHour < window.endHour) {
+        return hour >= window.startHour && hour < window.endHour;
+    }
+    return hour >= window.startHour || hour < window.endHour;
+}
+export function localDayKey(now = new Date()) {
+    return `${now.getFullYear()}-${padHour(now.getMonth() + 1)}-${padHour(now.getDate())}`;
+}
+function localWindowKey(window, now = new Date()) {
+    if (window &&
+        window.startHour > window.endHour &&
+        now.getHours() < window.endHour) {
+        const previous = new Date(now);
+        previous.setDate(previous.getDate() - 1);
+        return localDayKey(previous);
+    }
+    return localDayKey(now);
+}
+export function buildCacheKeepStatusSummary(status) {
+    const window = status.window
+        ? `${padHour(status.window.startHour)}-${padHour(status.window.endHour)}`
+        : 'not configured';
+    const lines = [
+        `Cache keep: ${status.enabled ? 'enabled' : 'disabled'}`,
+        `Window: ${window}`,
+        'Mode requirement: `/claude-cache mode hybrid` must be active.',
+    ];
+    if (typeof status.hybridActive === 'boolean') {
+        lines.push(`Hybrid active: ${status.hybridActive ? 'yes' : 'no'}`);
+    }
+    if (typeof status.trackedSessions === 'number') {
+        lines.push(`Tracked sessions: ${status.trackedSessions}`);
+    }
+    if (status.nextPrewarmAt) {
+        lines.push(`Next prewarm: ${new Date(status.nextPrewarmAt).toLocaleString()}`);
+    }
+    return lines.join('\n');
+}
+export function executeCacheKeepCommand(input) {
+    const action = parseCacheKeepCommandAction(input.argumentsText);
+    const status = {
+        enabled: input.enabled ?? false,
+        window: input.window,
+        trackedSessions: input.trackedSessions,
+        nextPrewarmAt: input.nextPrewarmAt,
+        hybridActive: input.hybridActive,
+    };
+    if (action.type === 'status') {
+        return [STATUS_TITLE, '', buildCacheKeepStatusSummary(status)].join('\n');
+    }
+    if (action.type === 'disable') {
+        return [
+            DISABLED_TITLE,
+            '',
+            buildCacheKeepStatusSummary({ ...status, enabled: false }),
+        ].join('\n');
+    }
+    if (action.type === 'window') {
+        return [
+            ENABLED_TITLE,
+            '',
+            buildCacheKeepStatusSummary({
+                ...status,
+                enabled: true,
+                window: { startHour: action.startHour, endHour: action.endHour },
+            }),
+        ].join('\n');
+    }
+    return [USAGE_TITLE, '', USAGE, '', buildCacheKeepStatusSummary(status)].join('\n');
+}
+function hasExplicitCacheControl(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return value.some(hasExplicitCacheControl);
+    const record = value;
+    const cacheControl = record.cache_control;
+    if (cacheControl &&
+        typeof cacheControl === 'object' &&
+        cacheControl.type === 'ephemeral') {
+        return true;
+    }
+    return Object.values(record).some(hasExplicitCacheControl);
+}
+export async function buildCacheKeepPrewarmBody(bodyText) {
+    let body;
+    try {
+        body = JSON.parse(bodyText);
+    }
+    catch {
+        return { ok: false, reason: 'body is not valid JSON' };
+    }
+    if (!hasExplicitCacheControl(body)) {
+        return { ok: false, reason: 'body has no explicit cache breakpoints' };
+    }
+    const warm = structuredClone(body);
+    warm.max_tokens = 0;
+    delete warm.stream;
+    const thinking = warm.thinking;
+    if (thinking?.type === 'enabled')
+        delete warm.thinking;
+    const outputConfig = warm.output_config;
+    if (outputConfig?.format)
+        delete warm.output_config;
+    const toolChoice = warm.tool_choice;
+    if (toolChoice?.type === 'tool' || toolChoice?.type === 'any') {
+        delete warm.tool_choice;
+    }
+    const unsignedBodyText = JSON.stringify(orderClaudeCodeBody(warm)).replace(CCH_PATTERN, 'cch=00000;');
+    const signedBodyText = await signRequestBody(unsignedBodyText);
+    return { ok: true, bodyText: signedBodyText };
+}
+export class CacheKeepManager {
+    options;
+    targets = new Map();
+    timer = null;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.tick().catch((error) => {
+                this.options.log?.('[cachekeep] tick failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }, CACHE_KEEP_TICK_MS);
+        if ('unref' in this.timer)
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    stats(window, now = this.options.now?.() ?? Date.now()) {
+        const today = localWindowKey(window, new Date(now));
+        const targets = [...this.targets.values()].filter((target) => target.dayKey === today);
+        const nextPrewarmAt = targets.length
+            ? Math.min(...targets.map((target) => target.cacheExpiresAt - CACHE_KEEP_PREWARM_LEAD_MS))
+            : undefined;
+        return { trackedSessions: targets.length, nextPrewarmAt };
+    }
+    track(input) {
+        if (!input.sessionId)
+            return { tracked: false, reason: 'missing session id' };
+        if (!isCacheKeepPersistentlyEnabled(input.storage)) {
+            return { tracked: false, reason: 'cachekeep disabled' };
+        }
+        if (input.cacheMode !== 'hybrid') {
+            return { tracked: false, reason: 'cache mode is not hybrid' };
+        }
+        const now = this.options.now?.() ?? Date.now();
+        const window = getCacheKeepWindow(input.storage);
+        if (!isWithinCacheKeepWindow(window, new Date(now))) {
+            return { tracked: false, reason: 'outside configured window' };
+        }
+        const headers = {};
+        input.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        this.targets.set(input.sessionId, {
+            id: input.sessionId,
+            url: input.url,
+            headers,
+            bodyText: input.bodyText,
+            cacheExpiresAt: now + CACHE_KEEP_TTL_MS,
+            dayKey: localWindowKey(window, new Date(now)),
+        });
+        this.start();
+        return { tracked: true };
+    }
+    async tick() {
+        const storage = await this.options.loadStorage();
+        const window = getCacheKeepWindow(storage);
+        const now = this.options.now?.() ?? Date.now();
+        const today = localWindowKey(window, new Date(now));
+        for (const [id, target] of this.targets) {
+            if (target.dayKey !== today)
+                this.targets.delete(id);
+        }
+        if (!this.targets.size) {
+            this.stop();
+            return;
+        }
+        if (!isCacheKeepHybridActive(storage))
+            return;
+        if (!isWithinCacheKeepWindow(window, new Date(now)))
+            return;
+        const dueAt = now + CACHE_KEEP_PREWARM_LEAD_MS;
+        for (const target of this.targets.values()) {
+            if (target.cacheExpiresAt > dueAt)
+                continue;
+            await this.prewarm(target, now);
+        }
+    }
+    async prewarm(target, now) {
+        const prewarm = await buildCacheKeepPrewarmBody(target.bodyText);
+        if (!prewarm.ok) {
+            this.options.log?.('[cachekeep] prewarm skipped', {
+                session: target.id,
+                reason: prewarm.reason,
+            });
+            this.targets.delete(target.id);
+            return;
+        }
+        const fetchImpl = this.options.fetchImpl ?? fetch;
+        const prewarmTarget = { ...target, bodyText: prewarm.bodyText };
+        const headers = this.options.prepareHeaders
+            ? await this.options.prepareHeaders(new Headers(target.headers), prewarmTarget)
+            : new Headers(target.headers);
+        headers.delete('content-length');
+        headers.delete('transfer-encoding');
+        const response = await fetchImpl(target.url, {
+            method: 'POST',
+            headers,
+            body: prewarm.bodyText,
+        });
+        if (!response.ok) {
+            this.options.log?.('[cachekeep] prewarm failed', {
+                session: target.id,
+                status: response.status,
+                body: await response.text().catch(() => ''),
+            });
+            target.cacheExpiresAt = now + CACHE_KEEP_PREWARM_LEAD_MS + 5 * 60_000;
+            return;
+        }
+        await response.body?.cancel().catch(() => { });
+        target.cacheExpiresAt = now + CACHE_KEEP_TTL_MS;
+        this.options.log?.('[cachekeep] prewarm succeeded', { session: target.id });
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './accounts.ts';
 export * from './auth.ts';
 export * from './cache1h.ts';
+export * from './cachekeep.ts';
 export * from './cch.ts';
 export * from './claude-code.ts';
 export * from './constants.ts';

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./accounts.js";
 export * from "./auth.js";
 export * from "./cache1h.js";
+export * from "./cachekeep.js";
 export * from "./cch.js";
 export * from "./claude-code.js";
 export * from "./constants.js";

package/package.json

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