@cortexkit/opencode-anthropic-auth 1.1.1 → 1.1.2

package/README.md

@@ -19,7 +19,7 @@ This repo is a Bun workspace monorepo with two user-facing integrations and one
 | Primary Claude Pro/Max OAuth | OpenCode `/connect anthropic` | Pi `/login anthropic` |
 | Provider integration point | OpenCode plugin fetch/request transform | Pi `registerProvider("anthropic")` provider override |
 | Sidecar config | `~/.config/opencode/anthropic-auth.json` | `~/.pi/agent/anthropic-auth.json` |
-| Commands | `/claude-cache`, `/claude-fast`, `/claude-quota`, `/claude-dump` | `/claude-cache`, `/claude-fast`, `/claude-quota`, `/claude-dump` |
+| Commands | `/claude-cache`, `/claude-cachekeep`, `/claude-fast`, `/claude-quota`, `/claude-dump` | `/claude-cache`, `/claude-cachekeep`, `/claude-fast`, `/claude-quota`, `/claude-dump` |
 | Fallback accounts, quota routing, relay, dumps, fast mode | Supported | Supported through the same shared core and Pi sidecar |
 
 ## What CortexKit adds over the original plugin
@@ -27,6 +27,7 @@ This repo is a Bun workspace monorepo with two user-facing integrations and one
 - **Fallback Claude accounts**: keep each agent's normal Anthropic login as the primary account, then route to ordered fallback OAuth accounts on auth/quota/rate-limit failures.
 - **Quota-aware routing**: skip main or fallback accounts when their 5-hour or 7-day Claude quota falls below your configured minimum.
 - **Persistent Claude cache controls**: manage Anthropic 1-hour prompt caching from `/claude-cache` with explicit, automatic, or hybrid modes.
+- **Cache keepalive**: use `/claude-cachekeep HH-HH` to pre-warm hybrid cache anchors for active sessions before the 1-hour TTL expires.
 - **Fast mode toggle**: use `/claude-fast on|off` to request Anthropic fast mode for supported Opus models.
 - **Live quota visibility**: use `/claude-quota` to see main and fallback quota state, reset times, and refresh errors.
 - **User-owned Cloudflare relay**: optionally provision your own Worker relay to reduce repeated client upload bytes for large OpenCode or Pi requests.
@@ -41,7 +42,7 @@ This repo is a Bun workspace monorepo with two user-facing integrations and one
 - Support fallback Claude accounts stored in a local per-agent sidecar file.
 - Keep fallback OAuth tokens fresh in the background.
 - Apply quota thresholds before routing to main or fallback accounts.
-- Add `/claude-cache`, `/claude-fast`, `/claude-quota`, and `/claude-dump` commands.
+- Add `/claude-cache`, `/claude-cachekeep`, `/claude-fast`, `/claude-quota`, and `/claude-dump` commands.
 - Optionally relay large requests through a Cloudflare Worker owned by the user.
 
 ## Install
@@ -172,6 +173,11 @@ Example:
     "enabled": false,
     "mode": "explicit"
   },
+  "cacheKeep": {
+    "enabled": false,
+    "startHour": 9,
+    "endHour": 23
+  },
   "dump": {
     "enabled": false
   },
@@ -189,7 +195,7 @@ Example:
 }
 ```
 
-The `claudeCache` block controls the `/claude-cache` command's persisted mode, and `claudeFast` controls `/claude-fast`. The `main` field identifies OpenCode's primary auth entry; Pi keeps primary OAuth credentials in Pi's own credential store, but uses the same sidecar shape for CortexKit settings and fallback accounts.
+The `claudeCache` block controls the `/claude-cache` command's persisted mode, `cacheKeep` controls `/claude-cachekeep`, and `claudeFast` controls `/claude-fast`. The `main` field identifies OpenCode's primary auth entry; Pi keeps primary OAuth credentials in Pi's own credential store, but uses the same sidecar shape for CortexKit settings and fallback accounts.
 
 ## Fallback accounts
 
@@ -275,6 +281,22 @@ Modes:
 
 In OpenCode, subagent requests do not receive 1-hour TTL caching. The plugin detects child sessions through OpenCode's `x-parent-session-id` header, strips that internal header before forwarding to Anthropic, and leaves default ephemeral caching in place for those requests.
 
+### Cache keepalive
+
+`/claude-cachekeep` keeps recently used hybrid-mode session caches warm while the agent process is running:
+
+```text
+/claude-cachekeep
+/claude-cachekeep 09-23
+/claude-cachekeep off
+```
+
+The hour range uses local 24-hour time and is start-inclusive/end-exclusive. `09-23` means cache keepalive may run from 09:00 until 22:59. Overnight windows such as `23-09` are accepted.
+
+Cache keepalive only tracks requests when `/claude-cache` is enabled in `hybrid` mode. For each active session seen that day, the package keeps an in-memory clone of the latest rewritten Anthropic request and sends a non-streaming `max_tokens: 0` pre-warm request about five minutes before the 1-hour cache entry would expire. Nothing is written to disk except the schedule configuration.
+
+Pre-warm requests preserve explicit cache anchors but remove response-only fields that Anthropic rejects with `max_tokens: 0`, such as streaming, enabled thinking, structured output format, and forced/any tool choice. The feature works only while OpenCode or Pi is running and the machine is awake, and cache writes are still billed when the cache entry is no longer warm.
+
 ## Claude fast mode
 
 Both OpenCode and Pi packages can persistently request Anthropic fast mode for supported Opus models:

package/dist/index.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { authorize, buildClaudeQuotaSummary, buildFallbackQuotaSummaries, buildRefreshOperationError, CACHE_1H_COMMAND_NAME, CLAUDE_DUMP_COMMAND_NAME, CLAUDE_FAST_COMMAND_NAME, CLAUDE_QUOTAS_COMMAND_NAME, ClaudeOAuthRefreshError, exchange, executeCache1hCommand, executeDumpCommand, executeFastModeCommand, FallbackAccountManager, fetchOAuthQuotaSnapshot, formatRefreshBackoffMessage, getCache1hMode, getCache1hPersistentMode, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getRelayConfig, hashRefreshToken, isCache1hEnabled, isCache1hPersistentlyEnabled, isDumpPersistentlyEnabled, isFastModeEnabled, isFastModePersistentlyEnabled, isFastModeSupportedModel, loadAccounts, log, parseCache1hCommandAction, parseDumpCommandAction, parseFastModeCommandAction, quotaSnapshotPassesPolicy, refreshBackoffActive, refreshClaudeOAuthToken, resolveClaudeCodeIdentity, saveAccounts, sendViaRelay, setCache1hPersistentEnabled, setCache1hPersistentMode, setCache1hState, setDumpEnabled, setDumpPersistentEnabled, setFastModeEnabled, setFastModePersistentEnabled, shouldFallbackStatus, } from '@cortexkit/anthropic-auth-core';
+import { authorize, buildClaudeQuotaSummary, buildFallbackQuotaSummaries, buildRefreshOperationError, CACHE_1H_COMMAND_NAME, CACHE_KEEP_EXTENDED_TTL_BETA, CacheKeepManager, CLAUDE_CACHE_KEEP_COMMAND_NAME, CLAUDE_DUMP_COMMAND_NAME, CLAUDE_FAST_COMMAND_NAME, CLAUDE_QUOTAS_COMMAND_NAME, ClaudeOAuthRefreshError, exchange, executeCache1hCommand, executeCacheKeepCommand, executeDumpCommand, executeFastModeCommand, FallbackAccountManager, fetchOAuthQuotaSnapshot, formatRefreshBackoffMessage, getCache1hMode, getCache1hPersistentMode, getCacheKeepWindow, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getRelayConfig, hashRefreshToken, isCache1hEnabled, isCache1hPersistentlyEnabled, isCacheKeepHybridActive, isCacheKeepPersistentlyEnabled, isDumpPersistentlyEnabled, isFastModeEnabled, isFastModePersistentlyEnabled, isFastModeSupportedModel, loadAccounts, log, mergeAnthropicBetas, parseCache1hCommandAction, parseCacheKeepCommandAction, parseDumpCommandAction, parseFastModeCommandAction, quotaSnapshotPassesPolicy, refreshBackoffActive, refreshClaudeOAuthToken, resolveClaudeCodeIdentity, saveAccounts, sendViaRelay, setCache1hPersistentEnabled, setCache1hPersistentMode, setCache1hState, setCacheKeepPersistentEnabled, setCacheKeepPersistentWindow, setDumpEnabled, setDumpPersistentEnabled, setFastModeEnabled, setFastModePersistentEnabled, shouldFallbackStatus, } from '@cortexkit/anthropic-auth-core';
 import { resolvePromptContext } from "./prompt-context.js";
 import { addFastModeBetaHeader, createStrippedStream, isInsecure, mergeHeaders, rewriteRequestBody, rewriteUrl, setOAuthHeaders, } from "./transform.js";
 const HANDLED_SENTINEL = '__OPENCODE_ANTHROPIC_AUTH_COMMAND_HANDLED__';
@@ -7,6 +7,9 @@ const MAIN_AUTH_REFRESH_TICK_MS = 60_000;
 const DEFAULT_MAIN_REFRESH_BEFORE_EXPIRY_MINUTES = 30;
 let nextPerfRequestId = 1;
 let eventLoopLagMonitorStarted = false;
+function perfLoggingEnabled() {
+    return process.env.OPENCODE_ANTHROPIC_AUTH_PERF === '1';
+}
 function nowMs() {
     return performance.now();
 }
@@ -14,8 +17,11 @@ function roundMs(value) {
     return Math.round(value * 10) / 10;
 }
 function startEventLoopLagMonitor() {
-    if (eventLoopLagMonitorStarted || process.env.NODE_ENV === 'test')
+    if (eventLoopLagMonitorStarted ||
+        process.env.NODE_ENV === 'test' ||
+        !perfLoggingEnabled()) {
         return;
+    }
     eventLoopLagMonitorStarted = true;
     const intervalMs = 100;
     const thresholdMs = 250;
@@ -40,28 +46,37 @@ function createPerfTrace(data) {
         last: start,
         mark(stage, stageData) {
             const current = nowMs();
-            log('[perf] opencode request stage', {
-                requestId: trace.requestId,
-                stage,
-                deltaMs: roundMs(current - trace.last),
-                totalMs: roundMs(current - trace.start),
-                ...stageData,
-            });
+            if (perfLoggingEnabled()) {
+                log('[perf] opencode request stage', {
+                    requestId: trace.requestId,
+                    stage,
+                    deltaMs: roundMs(current - trace.last),
+                    totalMs: roundMs(current - trace.start),
+                    ...stageData,
+                });
+            }
             trace.last = current;
         },
         done(stage, stageData) {
             const current = nowMs();
-            log('[perf] opencode request done', {
-                requestId: trace.requestId,
-                stage,
-                deltaMs: roundMs(current - trace.last),
-                totalMs: roundMs(current - trace.start),
-                ...stageData,
-            });
+            if (perfLoggingEnabled()) {
+                log('[perf] opencode request done', {
+                    requestId: trace.requestId,
+                    stage,
+                    deltaMs: roundMs(current - trace.last),
+                    totalMs: roundMs(current - trace.start),
+                    ...stageData,
+                });
+            }
             trace.last = current;
         },
     };
-    log('[perf] opencode request start', { requestId: trace.requestId, ...data });
+    if (perfLoggingEnabled()) {
+        log('[perf] opencode request start', {
+            requestId: trace.requestId,
+            ...data,
+        });
+    }
     return trace;
 }
 async function sendIgnoredMessage(ctx, sessionId, text) {
@@ -98,6 +113,43 @@ export const AnthropicAuthPlugin = async (ctx) => {
     const { client } = ctx;
     const fallbackManager = new FallbackAccountManager();
     fallbackManager.startBackgroundRefresh();
+    let latestRefreshMainAccessToken = null;
+    const cacheKeepManager = new CacheKeepManager({
+        loadStorage: () => loadAccounts(),
+        prepareHeaders: async (headers, target) => {
+            if (!latestGetAuth)
+                return headers;
+            const auth = await latestGetAuth();
+            if (auth.type !== 'oauth')
+                return headers;
+            if (!auth.access || (auth.expires && auth.expires < Date.now())) {
+                if (!latestRefreshMainAccessToken)
+                    return headers;
+                auth.access = await latestRefreshMainAccessToken();
+            }
+            if (!auth.access)
+                return headers;
+            try {
+                const parsedBody = JSON.parse(target.bodyText);
+                const identity = await resolveClaudeCodeIdentity(auth.access, typeof parsedBody.model === 'string' ? parsedBody.model : undefined);
+                headers.delete('anthropic-beta');
+                setOAuthHeaders(headers, auth.access, {
+                    body: parsedBody,
+                    identity,
+                });
+                headers.set('anthropic-beta', mergeAnthropicBetas(headers.get('anthropic-beta'), [
+                    CACHE_KEEP_EXTENDED_TTL_BETA,
+                ]));
+                if (parsedBody.speed === 'fast')
+                    addFastModeBetaHeader(headers);
+            }
+            catch {
+                setOAuthHeaders(headers, auth.access);
+            }
+            return headers;
+        },
+        log,
+    });
     const initialCache1hStorage = await loadAccounts();
     const relayConfig = getRelayConfig(initialCache1hStorage);
     setCache1hState({
@@ -116,6 +168,24 @@ export const AnthropicAuthPlugin = async (ctx) => {
     function mainRefreshEnabled(storage) {
         return storage?.refresh?.enabled !== false;
     }
+    async function clearStaleMainRefreshError(refreshToken) {
+        if (!refreshToken)
+            return;
+        const storage = await loadAccounts();
+        const error = storage?.refresh?.mainLastRefreshError;
+        if (!storage?.refresh || !error?.tokenHash)
+            return;
+        const tokenHash = hashRefreshToken(refreshToken);
+        if (error.tokenHash === tokenHash)
+            return;
+        storage.refresh.mainLastRefreshError = undefined;
+        await saveAccounts(storage);
+        log('[refresh] opencode main oauth cleared stale backoff after token rotation', {
+            previousCheckedAt: error.checkedAt,
+            previousNextRetryAt: error.nextRetryAt,
+            previousRetryCount: error.retryCount,
+        });
+    }
     async function buildQuotaCommandSummary() {
         const accounts = [];
         if (latestGetAuth) {
@@ -180,6 +250,26 @@ export const AnthropicAuthPlugin = async (ctx) => {
         setCache1hState({ enabled, mode });
         return executeCache1hCommand({ argumentsText, enabled, mode });
     }
+    async function executePersistentCacheKeepCommand(argumentsText) {
+        const action = parseCacheKeepCommandAction(argumentsText);
+        let storage = await loadAccounts();
+        if (action.type === 'window') {
+            storage = await setCacheKeepPersistentWindow(action.startHour, action.endHour);
+        }
+        else if (action.type === 'disable') {
+            storage = await setCacheKeepPersistentEnabled(false);
+        }
+        const window = getCacheKeepWindow(storage);
+        const stats = cacheKeepManager.stats(window);
+        return executeCacheKeepCommand({
+            argumentsText,
+            enabled: isCacheKeepPersistentlyEnabled(storage),
+            window,
+            hybridActive: isCacheKeepHybridActive(storage),
+            trackedSessions: stats.trackedSessions,
+            nextPrewarmAt: stats.nextPrewarmAt,
+        });
+    }
     async function executePersistentDumpCommand(argumentsText) {
         const action = parseDumpCommandAction(argumentsText);
         if (action.type === 'enable' || action.type === 'disable') {
@@ -214,6 +304,10 @@ export const AnthropicAuthPlugin = async (ctx) => {
                     template: CACHE_1H_COMMAND_NAME,
                     description: 'Show or toggle 1-hour Anthropic ephemeral prompt cache TTL.',
                 },
+                [CLAUDE_CACHE_KEEP_COMMAND_NAME]: {
+                    template: CLAUDE_CACHE_KEEP_COMMAND_NAME,
+                    description: 'Keep hybrid Claude cache warm for recently used sessions during a local time window.',
+                },
                 [CLAUDE_QUOTAS_COMMAND_NAME]: {
                     template: CLAUDE_QUOTAS_COMMAND_NAME,
                     description: 'Show current Claude OAuth quota usage for all accounts.',
@@ -233,6 +327,10 @@ export const AnthropicAuthPlugin = async (ctx) => {
                 await sendIgnoredMessage(ctx, input.sessionID, await executePersistentCache1hCommand(input.arguments));
                 throwHandledSentinel();
             }
+            if (input.command === CLAUDE_CACHE_KEEP_COMMAND_NAME) {
+                await sendIgnoredMessage(ctx, input.sessionID, await executePersistentCacheKeepCommand(input.arguments));
+                throwHandledSentinel();
+            }
             if (input.command === CLAUDE_QUOTAS_COMMAND_NAME) {
                 await sendIgnoredMessage(ctx, input.sessionID, await buildQuotaCommandSummary());
                 throwHandledSentinel();
@@ -303,14 +401,33 @@ export const AnthropicAuthPlugin = async (ctx) => {
                                         const storage = await loadAccounts();
                                         const refreshTokenHash = hashRefreshToken(freshAuth.refresh);
                                         const mainError = storage?.refresh?.mainLastRefreshError;
+                                        log('[refresh] opencode main oauth refresh check', {
+                                            attempt,
+                                            expiresInMs: freshAuth.expires
+                                                ? freshAuth.expires - Date.now()
+                                                : undefined,
+                                            hasBackoff: Boolean(mainError),
+                                            backoffActive: mainError
+                                                ? refreshBackoffActive(mainError, freshAuth.refresh, Date.now())
+                                                : false,
+                                            retryCount: mainError?.retryCount,
+                                            nextRetryAt: mainError?.nextRetryAt,
+                                        });
                                         if (mainError &&
                                             refreshBackoffActive(mainError, freshAuth.refresh, Date.now())) {
+                                            log('[refresh] opencode main oauth refresh skipped backoff', {
+                                                nextRetryAt: mainError.nextRetryAt,
+                                                retryCount: mainError.retryCount,
+                                            });
                                             throw new Error(formatRefreshBackoffMessage(mainError, Date.now()));
                                         }
                                         if (storage?.refresh?.mainRefreshLeaseUntil &&
                                             storage.refresh.mainRefreshLeaseUntil > Date.now() &&
                                             storage.refresh.mainRefreshLeaseTokenHash ===
                                                 refreshTokenHash) {
+                                            log('[refresh] opencode main oauth refresh skipped lease', {
+                                                leaseUntil: storage.refresh.mainRefreshLeaseUntil,
+                                            });
                                             throw new Error('Claude OAuth refresh is already in progress');
                                         }
                                         leaseId = randomUUID();
@@ -325,11 +442,18 @@ export const AnthropicAuthPlugin = async (ctx) => {
                                                 refreshTokenHash;
                                         });
                                         const latestLease = await loadAccounts();
+                                        log('[refresh] opencode main oauth refresh lease acquired', {
+                                            attempt,
+                                            leaseUntil: Date.now() + 2 * 60_000,
+                                        });
                                         if (latestLease?.refresh?.mainRefreshLeaseId !== leaseId ||
                                             latestLease.refresh.mainRefreshLeaseTokenHash !==
                                                 refreshTokenHash) {
                                             throw new Error('Claude OAuth refresh is already in progress');
                                         }
+                                        log('[refresh] opencode main oauth refresh request start', {
+                                            attempt,
+                                        });
                                         const refreshed = await refreshClaudeOAuthToken({
                                             refreshToken: freshAuth.refresh,
                                         });
@@ -355,6 +479,10 @@ export const AnthropicAuthPlugin = async (ctx) => {
                                                 storage.refresh.mainRefreshLeaseTokenHash = undefined;
                                             }
                                         });
+                                        log('[refresh] opencode main oauth refresh succeeded', {
+                                            attempt,
+                                            expiresInMs: refreshed.expires - Date.now(),
+                                        });
                                         return refreshed.access;
                                     }
                                     catch (error) {
@@ -371,6 +499,13 @@ export const AnthropicAuthPlugin = async (ctx) => {
                                                     error.status >= 500))) {
                                             continue;
                                         }
+                                        log('[refresh] opencode main oauth refresh attempt failed', {
+                                            attempt,
+                                            error: error instanceof Error
+                                                ? error.message
+                                                : String(error),
+                                            transient: isNetworkError,
+                                        });
                                         const failedRefreshToken = freshAuth?.refresh;
                                         if (failedRefreshToken &&
                                             error instanceof ClaudeOAuthRefreshError) {
@@ -412,6 +547,7 @@ export const AnthropicAuthPlugin = async (ctx) => {
                         }
                         return refreshPromise;
                     }
+                    latestRefreshMainAccessToken = refreshMainAccessToken;
                     function startMainBackgroundRefresh() {
                         if (mainBackgroundRefreshTimer) {
                             clearInterval(mainBackgroundRefreshTimer);
@@ -425,14 +561,24 @@ export const AnthropicAuthPlugin = async (ctx) => {
                                 const latestAuth = await getAuth();
                                 if (latestAuth.type !== 'oauth')
                                     return;
+                                await clearStaleMainRefreshError(latestAuth.refresh);
                                 if (!latestAuth.expires)
                                     return;
-                                if (latestAuth.expires - Date.now() >
-                                    mainRefreshBeforeExpiryMs(storage)) {
+                                const expiresInMs = latestAuth.expires - Date.now();
+                                const refreshBeforeMs = mainRefreshBeforeExpiryMs(storage);
+                                if (expiresInMs > refreshBeforeMs) {
                                     return;
                                 }
+                                log('[refresh] opencode main oauth background due', {
+                                    expiresInMs,
+                                    refreshBeforeMs,
+                                });
                                 if (latestAuth.refresh &&
                                     refreshBackoffActive(storage?.refresh?.mainLastRefreshError, latestAuth.refresh, Date.now())) {
+                                    log('[refresh] opencode main oauth background skipped backoff', {
+                                        nextRetryAt: storage?.refresh?.mainLastRefreshError?.nextRetryAt,
+                                        retryCount: storage?.refresh?.mainLastRefreshError?.retryCount,
+                                    });
                                     return;
                                 }
                                 if (latestAuth.refresh &&
@@ -607,6 +753,24 @@ export const AnthropicAuthPlugin = async (ctx) => {
                             });
                         }
                         const rewritten = rewriteUrl(input);
+                        if (route === 'main' &&
+                            typeof body === 'string' &&
+                            !subagentRequest &&
+                            isCache1hEnabled() &&
+                            getCache1hMode() === 'hybrid') {
+                            const storage = await loadAccounts();
+                            const tracked = await cacheKeepManager.track({
+                                sessionId: relayAffinity,
+                                url: rewritten.url?.toString() ?? rewritten.input.toString(),
+                                headers: requestHeaders,
+                                bodyText: body,
+                                storage,
+                                cacheMode: 'hybrid',
+                            });
+                            if (tracked.tracked) {
+                                trace?.mark('cachekeep_track', { session: relayAffinity });
+                            }
+                        }
                         const directFetch = () => fetch(rewritten.input, {
                             ...init,
                             body,
@@ -746,7 +910,14 @@ export const AnthropicAuthPlugin = async (ctx) => {
                                 trace.done('non_oauth_passthrough', { status: response.status });
                                 return response;
                             }
+                            await clearStaleMainRefreshError(auth.refresh);
                             if (!auth.access || !auth.expires || auth.expires < Date.now()) {
+                                log('[refresh] opencode main oauth refresh required for request', {
+                                    hasAccess: Boolean(auth.access),
+                                    expiresInMs: auth.expires
+                                        ? auth.expires - Date.now()
+                                        : undefined,
+                                });
                                 const refreshStart = nowMs();
                                 auth.access = await refreshMainAccessToken();
                                 trace.mark('refresh_main_access', {

package/dist/prompt-context.js

@@ -63,7 +63,10 @@ export async function resolvePromptContext(client, sessionId) {
         return null;
     let messages = [];
     try {
-        messages = extractMessages(await Promise.resolve(typedClient.session.messages({ path: { id: sessionId } })));
+        messages = extractMessages(await Promise.resolve(typedClient.session.messages({
+            path: { id: sessionId },
+            query: { limit: 100 },
+        })));
     }
     catch {
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/opencode-anthropic-auth",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "type": "module",
   "repository": {
     "type": "git",
@@ -40,6 +40,6 @@
     "@opencode-ai/plugin": "*"
   },
   "dependencies": {
-    "@cortexkit/anthropic-auth-core": "1.1.1"
+    "@cortexkit/anthropic-auth-core": "1.1.2"
   }
 }