@link-assistant/hive-mind 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @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
+
+- 2a3848d: Add --prompt-architecture-care flag for managing REQUIREMENTS.md and ARCHITECTURE.md files
+
+  Adds an optional experimental flag `--prompt-architecture-care` that provides guidance for:
+  - Managing REQUIREMENTS.md (high-level why/what documentation)
+  - Managing ARCHITECTURE.md (high-level how documentation)
+  - TODO.md workflow management for task persistence across sessions
+
+  The flag is disabled by default and works with all tools (claude, agent, opencode, codex).
+
+- a18a664: Fix session ID extraction error for --tool agent
+  - Fixed JSON parsing logic in agent tool to extract session IDs from NDJSON output
+  - Modified session summary to show informational message for agent tool instead of error
+
 ## 1.0.0
 
 ### Major Changes

package/package.json

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

package/src/agent.lib.mjs

@@ -405,7 +405,26 @@ export const executeAgentCommand = async params => {
       for await (const chunk of execCommand.stream()) {
         if (chunk.type === 'stdout') {
           const output = chunk.data.toString();
-          await log(output);
+          // Split output into individual lines for NDJSON parsing
+          // Agent outputs NDJSON (newline-delimited JSON) format where each line is a separate JSON object
+          // This allows us to parse each event independently and extract structured data like session IDs
+          const lines = output.split('\n');
+          for (const line of lines) {
+            if (!line.trim()) continue;
+            try {
+              const data = JSON.parse(line);
+              // Output formatted JSON
+              await log(JSON.stringify(data, null, 2));
+              // Capture session ID from the first message
+              if (!sessionId && data.sessionID) {
+                sessionId = data.sessionID;
+                await log(`📌 Session ID: ${sessionId}`);
+              }
+            } catch {
+              // Not JSON - log as plain text
+              await log(line);
+            }
+          }
           lastMessage = output;
           fullOutput += output; // Collect for both pricing calculation and error detection
         }

package/src/agent.prompts.lib.mjs

@@ -3,6 +3,8 @@
  * Handles building prompts for Agent commands
  */
 
+import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+
 /**
  * Build the user prompt for Agent
  * @param {Object} params - Parameters for building the user prompt
@@ -183,7 +185,7 @@ GitHub CLI command patterns.
    - When adding PR comment, use gh pr comment NUMBER --body "text" --repo OWNER/REPO.
    - When adding issue comment, use gh issue comment NUMBER --body "text" --repo OWNER/REPO.
    - When viewing PR details, use gh pr view NUMBER --repo OWNER/REPO.
-   - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.`;
+   - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${getArchitectureCareSubPrompt(argv)}`;
 };
 
 // Export all functions as default object too

package/src/architecture-care.prompts.lib.mjs

@@ -0,0 +1,52 @@
+/**
+ * Architecture care sub-prompt module
+ * Provides guidance for managing REQUIREMENTS.md, ARCHITECTURE.md, and TODO.md files
+ *
+ * This is an experimental feature enabled via --prompt-architecture-care flag
+ */
+
+/**
+ * Build the architecture care sub-prompt content
+ * @returns {string} The formatted sub-prompt for architecture documentation care
+ */
+export const buildArchitectureCareSubPrompt = () => {
+  return `
+Architecture and Requirements Documentation Care.
+   - REQUIREMENTS.md is a file that gives high level description on why/what it is for and so on relative to the entire repository.
+   - ARCHITECTURE.md is a file that gives high level description on how it was implemented so far.
+   - When any issue or comment changes how we see REQUIREMENTS.md or ARCHITECTURE.md, these files should be updated accordingly.
+   - When REQUIREMENTS.md or ARCHITECTURE.md files get too large, consider creating additional README.md, REQUIREMENTS.md, and ARCHITECTURE.md files in separate folders.
+   - When creating nested documentation files, make sure the root files have references to inner level documentation.
+   - When working with documentation, each README.md, REQUIREMENTS.md, and ARCHITECTURE.md scope should be related to the entire folder where such file exists.
+   - When you make changes that affect the high-level purpose, goals, or requirements of the project, update REQUIREMENTS.md.
+   - When you make changes that affect the implementation, architecture, or design patterns of the project, update ARCHITECTURE.md.
+   - When reviewing your changes before committing, check if REQUIREMENTS.md or ARCHITECTURE.md need updates based on the scope of your changes.
+
+TODO.md Workflow Management.
+   - At the start of each working session, check if TODO.md exists in the repository root.
+   - When TODO.md exists, read it first and continue finishing all items listed in it before starting any new work.
+   - When all items in TODO.md are completed, delete the TODO.md file to indicate work is done.
+   - When you cannot finish all tasks in the current working session, create or update TODO.md with all remaining tasks that need to be completed.
+   - When creating TODO.md, use a clear markdown checklist format with each item as a separate line.
+   - When updating TODO.md during a session, remove completed items and add any newly discovered tasks that couldn't be finished.
+   - TODO.md serves as a persistent task list across working sessions, ensuring continuity and nothing is forgotten between sessions.
+   - When starting work on a repository, the priority is: (1) Check TODO.md, (2) Complete TODO.md items, (3) Work on current issue/task, (4) Update TODO.md if needed before ending session.`;
+};
+
+/**
+ * Get the architecture care sub-prompt if enabled
+ * @param {Object} argv - Command line arguments
+ * @returns {string} The sub-prompt content or empty string if disabled
+ */
+export const getArchitectureCareSubPrompt = argv => {
+  if (argv && argv.promptArchitectureCare) {
+    return buildArchitectureCareSubPrompt();
+  }
+  return '';
+};
+
+// Export all functions as default object too
+export default {
+  buildArchitectureCareSubPrompt,
+  getArchitectureCareSubPrompt,
+};

package/src/claude.prompts.lib.mjs

@@ -3,6 +3,8 @@
  * Handles building prompts for Claude commands
  */
 
+import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+
 /**
  * Build the user prompt for Claude
  * @param {Object} params - Parameters for building the user prompt
@@ -241,7 +243,7 @@ Plan sub-agent usage.
    - When using the Plan sub-agent, you can add it as the first item in your todo list.
    - When you delegate planning, use the Task tool with subagent_type="Plan" before starting implementation work.`
        : ''
-   }`;
+   }${getArchitectureCareSubPrompt(argv)}`;
 };
 
 // Export all functions as default object too

package/src/codex.prompts.lib.mjs

@@ -3,6 +3,8 @@
  * Handles building prompts for Codex CLI commands
  */
 
+import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+
 /**
  * Build the user prompt for Codex
  * @param {Object} params - Parameters for building the user prompt
@@ -191,7 +193,7 @@ GitHub CLI command patterns.
    - When adding PR comment, use gh pr comment NUMBER --body "text" --repo OWNER/REPO.
    - When adding issue comment, use gh issue comment NUMBER --body "text" --repo OWNER/REPO.
    - When viewing PR details, use gh pr view NUMBER --repo OWNER/REPO.
-   - When filtering with jq, use gh api repos/\${owner}/\${repo}/pulls/\${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.`;
+   - When filtering with jq, use gh api repos/\${owner}/\${repo}/pulls/\${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${getArchitectureCareSubPrompt(argv)}`;
 };
 
 // Export all functions as default object too

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/hive.config.lib.mjs

@@ -281,6 +281,11 @@ export const createYargsConfig = yargsInstance => {
       description: 'Include prompt to check related/sibling pull requests when studying related work. Enabled by default, use --no-prompt-check-sibling-pull-requests to disable.',
       default: true,
     })
+    .option('prompt-architecture-care', {
+      type: 'boolean',
+      description: '[EXPERIMENTAL] Include guidance for managing REQUIREMENTS.md and ARCHITECTURE.md files. When enabled, agents will update these documentation files when changes affect requirements or architecture.',
+      default: false,
+    })
     .parserConfiguration({
       'boolean-negation': true,
       'strip-dashed': false,

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;
 }
 

package/src/opencode.prompts.lib.mjs

@@ -3,6 +3,8 @@
  * Handles building prompts for OpenCode commands
  */
 
+import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+
 /**
  * Build the user prompt for OpenCode
  * @param {Object} params - Parameters for building the user prompt
@@ -182,7 +184,7 @@ GitHub CLI command patterns.
    - When adding PR comment, use gh pr comment NUMBER --body "text" --repo OWNER/REPO.
    - When adding issue comment, use gh issue comment NUMBER --body "text" --repo OWNER/REPO.
    - When viewing PR details, use gh pr view NUMBER --repo OWNER/REPO.
-   - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.`;
+   - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${getArchitectureCareSubPrompt(argv)}`;
 };
 
 // Export all functions as default object too

package/src/solve.config.lib.mjs

@@ -278,6 +278,11 @@ export const createYargsConfig = yargsInstance => {
         description: 'Enable automatic issue creation for spotted bugs/errors not related to main task. Issues will include reproducible examples, workarounds, and fix suggestions. Works for both current and third-party repositories. Only supported for --tool claude.',
         default: false,
       })
+      .option('prompt-architecture-care', {
+        type: 'boolean',
+        description: '[EXPERIMENTAL] Include guidance for managing REQUIREMENTS.md and ARCHITECTURE.md files. When enabled, agents will update these documentation files when changes affect requirements or architecture.',
+        default: false,
+      })
       .option('prompt-case-studies', {
         type: 'boolean',
         description: 'Create comprehensive case study documentation for the issue including logs, analysis, timeline, root cause investigation, and proposed solutions. Organizes findings into ./docs/case-studies/issue-{id}/ directory. Only supported for --tool claude.',

package/src/solve.results.lib.mjs

@@ -354,7 +354,6 @@ export const showSessionSummary = async (sessionId, limitReached, argv, issueUrl
   if (sessionId) {
     await log(`✅ Session ID: ${sessionId}`);
     // Always use absolute path for log file display
-    const path = await use('path');
     const absoluteLogPath = path.resolve(getLogFile());
     await log(`✅ Complete log file: ${absoluteLogPath}`);
 
@@ -402,7 +401,12 @@ export const showSessionSummary = async (sessionId, limitReached, argv, issueUrl
 
     // Don't show log preview, it's too technical
   } else {
-    await log('❌ No session ID extracted');
+    // For agent tool, session IDs may not be meaningful for resuming, so don't show as error
+    if (argv.tool !== 'agent') {
+      await log('❌ No session ID extracted');
+    } else {
+      await log('ℹ️  Agent tool completed (session IDs not used for resuming)');
+    }
     // Always use absolute path for log file display
     const logFilePath = path.resolve(getLogFile());
     await log(`📁 Log file available: ${logFilePath}`);