@link-assistant/hive-mind 0.44.0 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @link-assistant/hive-mind
 
+## 0.46.0
+
+### Minor Changes
+
+- a436ee4: Add --prompt-case-studies CLI option for comprehensive issue analysis. When enabled, instructs the AI to download logs, create case study documentation in ./docs/case-studies/issue-{id}/, perform deep analysis, reconstruct timeline, identify root causes, and propose solutions. Works only with --tool claude, disabled by default.
+
+### Patch Changes
+
+- 1110e7a: Add comprehensive changeset documentation to CONTRIBUTING.md explaining how contributors should use the changesets workflow for version management and changelog generation
+
+## 0.45.0
+
+### Minor Changes
+
+- 81f8da0: Add `--tokens-budget-stats` option for detailed token usage analysis. This experimental feature shows context window usage and output token usage in absolute values and ratios when using `--tool claude`. Disabled by default.
+
 ## 0.44.0
 
 ### Minor Changes

package/package.json

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

package/src/claude.budget-stats.lib.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Token budget statistics display module
+// Extracted from claude.lib.mjs to maintain file line limits
+
+import { formatNumber } from './claude.lib.mjs';
+
+/**
+ * Display token budget statistics (context window usage and ratios)
+ * @param {Object} usage - Usage data for a model
+ * @param {Function} log - Logging function
+ */
+export const displayBudgetStats = async (usage, log) => {
+  const modelInfo = usage.modelInfo;
+  if (!modelInfo?.limit) {
+    await log('\n      ⚠️  Budget stats not available (no model limits found)');
+    return;
+  }
+
+  await log('\n      📊 Token Budget Statistics:');
+
+  // Context window usage
+  if (modelInfo.limit.context) {
+    const contextLimit = modelInfo.limit.context;
+    // Input tokens include regular input + cache creation + cache read
+    const totalInputUsed = usage.inputTokens + usage.cacheCreationTokens + usage.cacheReadTokens;
+    const contextUsageRatio = totalInputUsed / contextLimit;
+    const contextUsagePercent = (contextUsageRatio * 100).toFixed(2);
+
+    await log('        Context window:');
+    await log(`          Used: ${formatNumber(totalInputUsed)} tokens`);
+    await log(`          Limit: ${formatNumber(contextLimit)} tokens`);
+    await log(`          Ratio: ${contextUsageRatio.toFixed(4)} (${contextUsagePercent}%)`);
+  }
+
+  // Output tokens usage
+  if (modelInfo.limit.output) {
+    const outputLimit = modelInfo.limit.output;
+    const outputUsageRatio = usage.outputTokens / outputLimit;
+    const outputUsagePercent = (outputUsageRatio * 100).toFixed(2);
+
+    await log('        Output tokens:');
+    await log(`          Used: ${formatNumber(usage.outputTokens)} tokens`);
+    await log(`          Limit: ${formatNumber(outputLimit)} tokens`);
+    await log(`          Ratio: ${outputUsageRatio.toFixed(4)} (${outputUsagePercent}%)`);
+  }
+
+  // Total session tokens (input + cache_creation + output)
+  const totalSessionTokens = usage.inputTokens + usage.cacheCreationTokens + usage.outputTokens;
+  await log(`        Total session tokens: ${formatNumber(totalSessionTokens)}`);
+};

package/src/claude.lib.mjs

@@ -13,6 +13,7 @@ import { reportError } from './sentry.lib.mjs';
 import { timeouts, retryLimits } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
 import { createInteractiveHandler } from './interactive-mode.lib.mjs';
+import { displayBudgetStats } from './claude.budget-stats.lib.mjs';
 /**
  * Format numbers with spaces as thousands separator (no commas)
  * Per issue #667: Use spaces for thousands, . for decimals
@@ -1279,6 +1280,10 @@ export const executeClaudeCommand = async (params) => {
               const usage = tokenUsage.modelUsage[modelId];
               await log(`\n   📊 ${usage.modelName || modelId}:`);
               await displayModelUsage(usage, log);
+              // Display budget stats if flag is enabled
+              if (argv.tokensBudgetStats && usage.modelInfo?.limit) {
+                await displayBudgetStats(usage, log);
+              }
             }
             // Show totals if multiple models were used
             if (modelIds.length > 1) {

package/src/claude.prompts.lib.mjs

@@ -145,7 +145,7 @@ Initial research.
    - When you are fixing a bug, please make sure you first find the actual root cause, do as many experiments as needed.
    - When you are fixing a bug and code does not have enough tracing/logs, add them and make sure they stay in the code, but are switched off by default.
    - When you need latest comments on pull request (sorted newest first), use appropriate GitHub API commands.
-   - When you need latest comments on issue (sorted newest first), use appropriate GitHub API commands.${argv && argv.promptGeneralPurposeSubAgent ? '\n   - When the task is big and requires processing of lots of files or folders, you should use the `general-purpose` sub agents to delegate work. Each separate file or folder can be delegated to a sub agent for more efficient processing.' : ''}
+   - When you need latest comments on issue (sorted newest first), use appropriate GitHub API commands.${argv && argv.promptGeneralPurposeSubAgent ? '\n   - When the task is big and requires processing of lots of files or folders, you should use the `general-purpose` sub agents to delegate work. Each separate file or folder can be delegated to a sub agent for more efficient processing.' : ''}${argv && argv.promptCaseStudies ? `\n   - When working on this issue, create a comprehensive case study in the ./docs/case-studies/issue-${issueNumber}/ directory. Download all logs and data related to the issue to the repository. Perform deep case study analysis by searching online for additional facts and data, reconstructing the timeline/sequence of events, identifying root causes of the problem, and proposing possible solutions. Include files like README.md (executive summary, problem statement, timeline, root cause), TECHNICAL_SUMMARY.md (deep technical analysis), ANALYSIS.md (detailed investigation findings), improvements.md (proposed solutions), and supporting logs/data files.` : ''}
 
 Solution development and testing.
    - When issue is solvable, implement code with tests.

package/src/hive.config.lib.mjs

@@ -251,11 +251,21 @@ export const createYargsConfig = (yargsInstance) => {
       description: 'Prompt AI to use general-purpose sub agents for processing large tasks with multiple files/folders. Only supported for --tool claude.',
       default: false
     })
+    .option('tokens-budget-stats', {
+      type: 'boolean',
+      description: '[EXPERIMENTAL] Show detailed token budget statistics including context window usage and ratios. Only supported for --tool claude.',
+      default: false
+    })
     .option('prompt-issue-reporting', {
       type: 'boolean',
       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-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.',
+      default: false
+    })
     .parserConfiguration({
       'boolean-negation': true,
       'strip-dashed': false,

package/src/hive.mjs

@@ -758,7 +758,7 @@ async function worker(workerId) {
         const interactiveModeFlag = argv.interactiveMode ? ' --interactive-mode' : '';
         const promptExploreSubAgentFlag = argv.promptExploreSubAgent ? ' --prompt-explore-sub-agent' : '';
         const promptIssueReportingFlag = argv.promptIssueReporting ? ' --prompt-issue-reporting' : '';
-
+        const promptCaseStudiesFlag = argv.promptCaseStudies ? ' --prompt-case-studies' : '';
         // Use spawn to get real-time streaming output while avoiding command-stream's automatic quote addition
         const { spawn } = await import('child_process');
 
@@ -808,9 +808,10 @@ async function worker(workerId) {
         if (argv.interactiveMode) args.push('--interactive-mode');
         if (argv.promptExploreSubAgent) args.push('--prompt-explore-sub-agent');
         if (argv.promptIssueReporting) args.push('--prompt-issue-reporting');
+        if (argv.promptCaseStudies) args.push('--prompt-case-studies');
 
         // Log the actual command being executed so users can investigate/reproduce
-        const command = `${solveCommand} "${issueUrl}" --model ${argv.model}${toolFlag}${forkFlag}${autoForkFlag}${verboseFlag}${attachLogsFlag}${targetBranchFlag}${logDirFlag}${dryRunFlag}${skipToolConnectionCheckFlag}${autoContinueFlag}${thinkFlag}${promptPlanSubAgentFlag}${noSentryFlag}${watchFlag}${prefixForkNameWithOwnerNameFlag}${interactiveModeFlag}${promptExploreSubAgentFlag}${promptIssueReportingFlag}`;
+        const command = `${solveCommand} "${issueUrl}" --model ${argv.model}${toolFlag}${forkFlag}${autoForkFlag}${verboseFlag}${attachLogsFlag}${targetBranchFlag}${logDirFlag}${dryRunFlag}${skipToolConnectionCheckFlag}${autoContinueFlag}${thinkFlag}${promptPlanSubAgentFlag}${noSentryFlag}${watchFlag}${prefixForkNameWithOwnerNameFlag}${interactiveModeFlag}${promptExploreSubAgentFlag}${promptIssueReportingFlag}${promptCaseStudiesFlag}`;
         await log(`   📋 Command: ${command}`);
 
         let exitCode = 0;
@@ -1497,5 +1498,4 @@ try {
   console.error('\nPlease report this issue at: https://github.com/link-assistant/hive-mind/issues');
   process.exit(1);
 }
-
 } // End of main execution block

package/src/solve.config.lib.mjs

@@ -255,11 +255,21 @@ export const createYargsConfig = (yargsInstance) => {
       description: 'Prompt AI to use general-purpose sub agents for processing large tasks with multiple files/folders. Only supported for --tool claude.',
       default: false
     })
+    .option('tokens-budget-stats', {
+      type: 'boolean',
+      description: '[EXPERIMENTAL] Show detailed token budget statistics including context window usage and ratios. Only supported for --tool claude.',
+      default: false
+    })
     .option('prompt-issue-reporting', {
       type: 'boolean',
       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-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.',
+      default: false
+    })
     .parserConfiguration({
       'boolean-negation': true
     })