@link-assistant/hive-mind 1.13.0 → 1.14.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @link-assistant/hive-mind
 
+## 1.14.1
+
+### Patch Changes
+
+- b139b00: fix: detect agent tool errors during streaming for reliable failure detection (Issue #1201)
+
+  Previously, agent tool errors (`"type": "error"`) could be missed when the post-hoc
+  detection function failed to parse NDJSON lines that were concatenated without newline
+  delimiters. Now errors are detected inline during stream processing, ensuring
+  `"type": "error"` events always trigger a failure exit regardless of output buffering.
+
+## 1.14.0
+
+### Minor Changes
+
+- 3a48254: Add configurable experiments/examples folder paths with ability to disable
+
+  New CLI options for both `solve` and `hive` commands:
+  - `--prompt-experiments-folder <path>`: Path to experiments folder used in system prompt. Set to empty string to disable experiments folder prompt. Default: `./experiments`
+  - `--prompt-examples-folder <path>`: Path to examples folder used in system prompt. Set to empty string to disable examples folder prompt. Default: `./examples`
+
+  Features:
+  - Backwards compatible: defaults to `./experiments` and `./examples` as before
+  - Custom paths: Specify custom folder paths for experiments and examples
+  - Disable functionality: Set to empty string (`''`) to disable the experiments/examples prompt section entirely
+  - Works with all AI tools: claude, opencode, codex, and agent
+
 ## 1.13.0
 
 ### Minor Changes

package/README.md

@@ -106,7 +106,40 @@ bun install -g @link-assistant/hive-mind
 npm install -g @link-assistant/hive-mind
 ```
 
-### Docker Installation
+### Installing Docker
+
+If you don't have Docker installed yet, follow these steps to install Docker Engine on Ubuntu:
+
+```bash
+# Install prerequisites
+sudo apt update
+sudo apt install ca-certificates curl
+
+# Add Docker's official GPG key
+sudo install -m 0755 -d /etc/apt/keyrings
+sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
+sudo chmod a+r /etc/apt/keyrings/docker.asc
+
+# Add Docker repository
+sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
+Types: deb
+URIs: https://download.docker.com/linux/ubuntu
+Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
+Components: stable
+Signed-By: /etc/apt/keyrings/docker.asc
+EOF
+
+# Install Docker
+sudo apt update
+sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+
+# Verify installation
+sudo docker run hello-world
+```
+
+**For other operating systems** or detailed instructions, see the [official Docker documentation](https://docs.docker.com/engine/install/).
+
+### Using Docker
 
 Run the Hive Mind using Docker for safer local installation - no manual setup required:
 

package/package.json

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

package/src/agent.lib.mjs

@@ -418,6 +418,10 @@ export const executeAgentCommand = async params => {
       let limitResetTime = null;
       let lastMessage = '';
       let fullOutput = ''; // Collect all output for pricing calculation and error detection
+      // Issue #1201: Track error events detected during streaming for reliable error detection
+      // Post-hoc detection on fullOutput can miss errors if NDJSON lines get concatenated without newlines
+      let streamingErrorDetected = false;
+      let streamingErrorMessage = null;
 
       for await (const chunk of execCommand.stream()) {
         if (chunk.type === 'stdout') {
@@ -437,6 +441,12 @@ export const executeAgentCommand = async params => {
                 sessionId = data.sessionID;
                 await log(`📌 Session ID: ${sessionId}`);
               }
+              // Issue #1201: Detect error events during streaming for reliable detection
+              if (data.type === 'error' || data.type === 'step_error') {
+                streamingErrorDetected = true;
+                streamingErrorMessage = data.message || data.error || line.substring(0, 100);
+                await log(`⚠️  Error event detected in stream: ${streamingErrorMessage}`, { level: 'warning' });
+              }
             } catch {
               // Not JSON - log as plain text
               await log(line);
@@ -463,6 +473,12 @@ export const executeAgentCommand = async params => {
                   sessionId = stderrData.sessionID;
                   await log(`📌 Session ID: ${sessionId}`);
                 }
+                // Issue #1201: Detect error events during streaming (stderr) for reliable detection
+                if (stderrData.type === 'error' || stderrData.type === 'step_error') {
+                  streamingErrorDetected = true;
+                  streamingErrorMessage = stderrData.message || stderrData.error || stderrLine.substring(0, 100);
+                  await log(`⚠️  Error event detected in stream: ${streamingErrorMessage}`, { level: 'warning' });
+                }
               } catch {
                 // Not JSON - log as plain text
                 await log(stderrLine);
@@ -496,7 +512,7 @@ export const executeAgentCommand = async params => {
 
             // Check for explicit error message types from agent
             if (msg.type === 'error' || msg.type === 'step_error') {
-              return { detected: true, type: 'AgentError', match: msg.message || line.substring(0, 100) };
+              return { detected: true, type: 'AgentError', match: msg.message || msg.error || line.substring(0, 100) };
             }
           } catch {
             // Not JSON - ignore for error detection
@@ -510,6 +526,15 @@ export const executeAgentCommand = async params => {
       // Only check for JSON error messages, not pattern matching in output
       const outputError = detectAgentErrors(fullOutput);
 
+      // Issue #1201: Use streaming detection as primary, post-hoc as fallback
+      // Streaming detection is more reliable because it parses each JSON line as it arrives,
+      // avoiding issues where NDJSON lines get concatenated without newline delimiters in fullOutput
+      if (!outputError.detected && streamingErrorDetected) {
+        outputError.detected = true;
+        outputError.type = 'AgentError';
+        outputError.match = streamingErrorMessage;
+      }
+
       if (exitCode !== 0 || outputError.detected) {
         // Build JSON error structure for consistent error reporting
         const errorInfo = {
@@ -545,7 +570,7 @@ export const executeAgentCommand = async params => {
             await log(line, { level: 'warning' });
           }
         } else if (outputError.detected) {
-          // Explicit JSON error message from agent
+          // Explicit JSON error message from agent (Issue #1201: includes streaming-detected errors)
           errorInfo.message = `Agent reported error: ${outputError.match}`;
           await log(`\n\n❌ ${errorInfo.message}`, { level: 'error' });
         } else {

package/src/agent.prompts.lib.mjs

@@ -4,6 +4,7 @@
  */
 
 import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 
 /**
  * Build the user prompt for Agent
@@ -137,9 +138,7 @@ ${workspaceInstructions}General guidelines.
    - When CI is failing, make sure you download the logs locally and carefully investigate them.
    - When a code or log file has more than 1500 lines, read it in chunks of 1500 lines.
    - When facing a complex problem, do as much tracing as possible and turn on all verbose modes.
-   - When you create debug, test, or example/experiment scripts for fixing, always keep them in an examples and/or experiments folders so you can reuse them later.
-   - When testing your assumptions, use the experiment scripts, and add it to experiments folder.
-   - When your experiments can show real world use case of the software, add it to examples folder.
+${getExperimentsExamplesSubPrompt(argv)}
    - When you face something extremely hard, use divide and conquer — it always helps.
 
 Initial research.

package/src/claude.prompts.lib.mjs

@@ -4,6 +4,7 @@
  */
 
 import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 
 /**
  * Build the user prompt for Claude
@@ -163,9 +164,7 @@ ${workspaceInstructions}General guidelines.
       Note: If user says "failing" but tools show "passing", this might indicate stale data - consider downloading fresh logs and checking timestamps to resolve the discrepancy.
    - When a code or log file has more than 1500 lines, read it in chunks of 1500 lines.
    - When facing a complex problem, do as much tracing as possible and turn on all verbose modes.
-   - When you create debug, test, or example/experiment scripts for fixing, always keep them in an examples and/or experiments folders so you can reuse them later.
-   - When testing your assumptions, use the experiment scripts, and add it to experiments folder.
-   - When your experiments can show real world use case of the software, add it to examples folder.
+${getExperimentsExamplesSubPrompt(argv)}
    - When you face something extremely hard, use divide and conquer — it always helps.
 
 Initial research.

package/src/codex.prompts.lib.mjs

@@ -4,6 +4,7 @@
  */
 
 import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 
 /**
  * Build the user prompt for Codex
@@ -144,9 +145,7 @@ ${workspaceInstructions}General guidelines.
       Note: If user says "failing" but tools show "passing", this might indicate stale data - consider downloading fresh logs and checking timestamps to resolve the discrepancy.
    - When a code or log file has more than 1500 lines, read it in chunks of 1500 lines.
    - When facing a complex problem, do as much tracing as possible and turn on all verbose modes.
-   - When you create debug, test, or example/experiment scripts for fixing, always keep them in an examples and/or experiments folders so you can reuse them later.
-   - When testing your assumptions, use the experiment scripts, and add it to experiments folder.
-   - When your experiments can show real world use case of the software, add it to examples folder.
+${getExperimentsExamplesSubPrompt(argv)}
    - When you face something extremely hard, use divide and conquer — it always helps.
 
 Initial research.

package/src/experiments-examples.prompts.lib.mjs

@@ -0,0 +1,48 @@
+/**
+ * Experiments and examples folder prompts module
+ * Handles building configurable prompts for experiments/examples folders
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1199
+ */
+
+/**
+ * Build the experiments/examples sub-prompt based on configuration
+ * @param {Object} argv - Command line arguments
+ * @param {string} argv.promptExperimentsFolder - Path to experiments folder (empty string to disable)
+ * @param {string} argv.promptExamplesFolder - Path to examples folder (empty string to disable)
+ * @returns {string} The formatted sub-prompt for experiments/examples folders
+ */
+export const getExperimentsExamplesSubPrompt = argv => {
+  const experimentsFolder = argv?.promptExperimentsFolder ?? './experiments';
+  const examplesFolder = argv?.promptExamplesFolder ?? './examples';
+
+  // If both are disabled, return empty string
+  if (!experimentsFolder && !examplesFolder) {
+    return '';
+  }
+
+  const lines = [];
+
+  // Both folders are enabled (with their respective paths)
+  if (experimentsFolder && examplesFolder) {
+    lines.push(`   - When you create debug, test, or example/experiment scripts for fixing, always keep them in an ${examplesFolder} and/or ${experimentsFolder} folders so you can reuse them later.`);
+    lines.push(`   - When testing your assumptions, use the experiment scripts, and add it to ${experimentsFolder} folder.`);
+    lines.push(`   - When your experiments can show real world use case of the software, add it to ${examplesFolder} folder.`);
+  }
+  // Only experiments folder is enabled
+  else if (experimentsFolder) {
+    lines.push(`   - When you create debug or test scripts for fixing, always keep them in ${experimentsFolder} folder so you can reuse them later.`);
+    lines.push(`   - When testing your assumptions, use the experiment scripts, and add it to ${experimentsFolder} folder.`);
+  }
+  // Only examples folder is enabled
+  else if (examplesFolder) {
+    lines.push(`   - When you create example scripts that show real world use cases, keep them in ${examplesFolder} folder.`);
+    lines.push(`   - When your experiments can show real world use case of the software, add it to ${examplesFolder} folder.`);
+  }
+
+  return lines.join('\n');
+};
+
+export default {
+  getExperimentsExamplesSubPrompt,
+};

package/src/hive.config.lib.mjs

@@ -301,6 +301,16 @@ 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-experiments-folder', {
+      type: 'string',
+      description: 'Path to experiments folder used in system prompt. Set to empty string to disable experiments folder prompt. Default: ./experiments',
+      default: './experiments',
+    })
+    .option('prompt-examples-folder', {
+      type: 'string',
+      description: 'Path to examples folder used in system prompt. Set to empty string to disable examples folder prompt. Default: ./examples',
+      default: './examples',
+    })
     .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.',

package/src/hive.mjs

@@ -770,6 +770,8 @@ if (isDirectExecution) {
             if (argv.promptIssueReporting) args.push('--prompt-issue-reporting');
             if (argv.promptCaseStudies) args.push('--prompt-case-studies');
             if (argv.promptPlaywrightMcp !== undefined) args.push(argv.promptPlaywrightMcp ? '--prompt-playwright-mcp' : '--no-prompt-playwright-mcp');
+            if (argv.promptExperimentsFolder !== undefined) args.push('--prompt-experiments-folder', argv.promptExperimentsFolder);
+            if (argv.promptExamplesFolder !== undefined) args.push('--prompt-examples-folder', argv.promptExamplesFolder);
             if (argv.executeToolWithBun) args.push('--execute-tool-with-bun');
             if (argv.autoMerge) args.push('--auto-merge');
             if (argv.autoRestartUntilMergable) args.push('--auto-restart-until-mergable');

package/src/opencode.prompts.lib.mjs

@@ -4,6 +4,7 @@
  */
 
 import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 
 /**
  * Build the user prompt for OpenCode
@@ -139,9 +140,7 @@ General guidelines.
    - When CI is failing, make sure you download the logs locally and carefully investigate them.
    - When a code or log file has more than 1500 lines, read it in chunks of 1500 lines.
    - When facing a complex problem, do as much tracing as possible and turn on all verbose modes.
-   - When you create debug, test, or example/experiment scripts for fixing, always keep them in an examples and/or experiments folders so you can reuse them later.
-   - When testing your assumptions, use the experiment scripts, and add it to experiments folder.
-   - When your experiments can show real world use case of the software, add it to examples folder.
+${getExperimentsExamplesSubPrompt(argv)}
    - When you face something extremely hard, use divide and conquer — it always helps.
 ${workspaceInstructions}
 Initial research.

package/src/solve.config.lib.mjs

@@ -358,6 +358,16 @@ 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-experiments-folder', {
+        type: 'string',
+        description: 'Path to experiments folder used in system prompt. Set to empty string to disable experiments folder prompt. Default: ./experiments',
+        default: './experiments',
+      })
+      .option('prompt-examples-folder', {
+        type: 'string',
+        description: 'Path to examples folder used in system prompt. Set to empty string to disable examples folder prompt. Default: ./examples',
+        default: './examples',
+      })
       .option('playwright-mcp-auto-cleanup', {
         type: 'boolean',
         description: 'Automatically remove .playwright-mcp/ folder before checking for uncommitted changes. This prevents browser automation artifacts from triggering auto-restart. Use --no-playwright-mcp-auto-cleanup to keep the folder for debugging.',