@link-assistant/hive-mind 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @link-assistant/hive-mind
 
+## 1.0.2
+
+### Patch Changes
+
+- 1a96d9f: Fix Claude Usage API rate limiting by increasing cache TTL to 20 minutes
+  - The Claude Usage API (`/api/oauth/usage`) was returning null values due to rate limiting when called too frequently
+  - Increased default cache TTL from 3 minutes to 20 minutes for Claude Usage API
+  - Added configurable environment variable `HIVE_MIND_USAGE_API_CACHE_TTL_MS` (default: 1200000ms = 20 minutes)
+  - Added HTTP response status logging for easier debugging
+  - Added explicit 429 rate limit error handling
+  - Updated documentation in `docs/CONFIGURATION.md`
+
+  See: https://github.com/link-assistant/hive-mind/issues/1074
+
 ## 1.0.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/config.lib.mjs

@@ -78,6 +78,19 @@ export const retryLimits = {
   initial503RetryDelayMs: parseIntWithDefault('HIVE_MIND_INITIAL_503_RETRY_DELAY_MS', 5 * 60 * 1000), // 5 minutes
 };
 
+// Cache TTL configurations (in milliseconds)
+// The Usage API (Claude limits) has stricter rate limiting than regular APIs
+// See: https://github.com/link-assistant/hive-mind/issues/1074
+export const cacheTtl = {
+  // General API cache TTL (GitHub API, etc.)
+  api: parseIntWithDefault('HIVE_MIND_API_CACHE_TTL_MS', 3 * 60 * 1000), // 3 minutes
+  // Claude Usage API cache TTL - must be at least 20 minutes to avoid rate limiting
+  // The API returns null values when called too frequently
+  usageApi: parseIntWithDefault('HIVE_MIND_USAGE_API_CACHE_TTL_MS', 20 * 60 * 1000), // 20 minutes
+  // System metrics cache TTL (RAM, CPU, disk)
+  system: parseIntWithDefault('HIVE_MIND_SYSTEM_CACHE_TTL_MS', 2 * 60 * 1000), // 2 minutes
+};
+
 // File and path configurations
 export const filePaths = {
   tempDir: getenv('HIVE_MIND_TEMP_DIR', '/tmp'),
@@ -177,6 +190,7 @@ export function getAllConfigurations() {
     githubLimits,
     systemLimits,
     retryLimits,
+    cacheTtl,
     filePaths,
     textProcessing,
     display,

package/src/limits.lib.mjs

@@ -10,6 +10,9 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 
+// Import cache TTL configuration
+import { cacheTtl } from './config.lib.mjs';
+
 const execAsync = promisify(exec);
 
 /**
@@ -532,6 +535,11 @@ export async function getClaudeUsageLimits(verbose = false, credentialsPath = DE
       },
     });
 
+    // Log HTTP response status for debugging (always, not just on error)
+    if (verbose) {
+      console.log(`[VERBOSE] /limits API HTTP status: ${response.status} ${response.statusText}`);
+    }
+
     if (!response.ok) {
       const errorText = await response.text();
       if (verbose) {
@@ -546,6 +554,15 @@ export async function getClaudeUsageLimits(verbose = false, credentialsPath = DE
         };
       }
 
+      // Check for rate limiting (429 Too Many Requests)
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('retry-after');
+        return {
+          success: false,
+          error: `Rate limited by Claude Usage API. ${retryAfter ? `Retry after: ${retryAfter}s` : 'Try again later.'}`,
+        };
+      }
+
       return {
         success: false,
         error: `Failed to fetch usage from API: ${response.status} ${response.statusText}`,
@@ -786,10 +803,21 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
 
 /**
  * Cache TTL constants (in milliseconds)
+ * Values are loaded from config.lib.mjs which supports environment variable overrides.
+ *
+ * IMPORTANT: The Claude Usage API has stricter rate limiting than regular APIs.
+ * Calling it more frequently than every 20 minutes may result in null values being returned.
+ * See: https://github.com/link-assistant/hive-mind/issues/1074
+ *
+ * Configurable via environment variables:
+ * - HIVE_MIND_API_CACHE_TTL_MS: General API cache TTL (default: 180000 = 3 minutes)
+ * - HIVE_MIND_USAGE_API_CACHE_TTL_MS: Claude Usage API cache TTL (default: 1200000 = 20 minutes)
+ * - HIVE_MIND_SYSTEM_CACHE_TTL_MS: System metrics cache TTL (default: 120000 = 2 minutes)
  */
 export const CACHE_TTL = {
-  API: 180000, // 3 minutes for API calls (Claude, GitHub)
-  SYSTEM: 120000, // 2 minutes for system metrics (RAM, CPU, disk)
+  API: cacheTtl.api, // 3 minutes for regular API calls (GitHub)
+  USAGE_API: cacheTtl.usageApi, // 20 minutes for Claude Usage API (rate limited)
+  SYSTEM: cacheTtl.system, // 2 minutes for system metrics (RAM, CPU, disk)
 };
 
 /**
@@ -852,13 +880,17 @@ export function resetLimitCache() {
 
 export async function getCachedClaudeLimits(verbose = false) {
   const cache = getLimitCache();
-  const cached = cache.get('claude', CACHE_TTL.API);
+  // Use USAGE_API TTL (20 minutes) for Claude limits to avoid rate limiting
+  // The Claude Usage API returns null values when called too frequently
+  // See: https://github.com/link-assistant/hive-mind/issues/1074
+  const cached = cache.get('claude', CACHE_TTL.USAGE_API);
   if (cached) {
-    if (verbose) console.log('[VERBOSE] /limits-cache: Using cached Claude limits');
+    if (verbose) console.log('[VERBOSE] /limits-cache: Using cached Claude limits (TTL: ' + Math.round(CACHE_TTL.USAGE_API / 60000) + ' minutes)');
     return cached;
   }
+  if (verbose) console.log('[VERBOSE] /limits-cache: Cache miss for Claude limits, fetching from API...');
   const result = await getClaudeUsageLimits(verbose);
-  if (result.success) cache.set('claude', result, CACHE_TTL.API);
+  if (result.success) cache.set('claude', result, CACHE_TTL.USAGE_API);
   return result;
 }