@cortexkit/anthropic-auth-core 1.1.1 → 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

@@ -62,6 +62,11 @@ export type AccountStorage = {
     claudeFast?: {
         enabled?: boolean;
     };
+    cacheKeep?: {
+        enabled?: boolean;
+        startHour?: number;
+        endHour?: number;
+    };
     relay?: {
         enabled?: boolean;
         url?: string;
@@ -92,6 +97,8 @@ 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;

package/dist/accounts.js

@@ -4,6 +4,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 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];
@@ -116,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)
@@ -229,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;
 }
@@ -278,7 +307,11 @@ function isTransientRefreshError(error) {
                 error.code === 'UND_ERR_CONNECT_TIMEOUT')));
 }
 export function buildRefreshOperationError(input) {
-    const retryCount = (input.previous?.retryCount ?? 0) + 1;
+    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;
@@ -287,7 +320,7 @@ export function buildRefreshOperationError(input) {
         checkedAt: input.now,
         nextRetryAt: input.now + delay,
         retryCount,
-        tokenHash: hashRefreshToken(input.refreshToken),
+        tokenHash,
     };
 }
 export function refreshBackoffActive(error, refreshToken, now) {
@@ -525,13 +558,28 @@ export class FallbackAccountManager {
             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;
@@ -636,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,
@@ -648,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.1",
+  "version": "1.1.2",
   "type": "module",
   "repository": {
     "type": "git",