fix(ai): add OpenCode agent support with correct CLI configuration

Update AI runner to support OpenCode agent with proper configuration and JSON parsing:

- Configure OpenCode with correct CLI syntax: ['run', '--format', 'json']
- Add markdown-wrapped JSON parsing via parseStringResult helper
- Handle multiple response formats: raw JSON, markdown-wrapped JSON, plain text
- Refactor parseOpenCodeNDJSON with functional .reduce() pattern
- Replace plain Error with structured createError() for rich error metadata
- Maintain backward compatibility with Claude and Cursor agents
- Update dependencies (npm install)
- Update tests to verify OpenCode configuration, parsing, and error handling
- Archive completed OpenCode agent task documentation
- Update plan.md to reflect OpenCode support status

Tested with OpenCode v1.1.50 CLI. All 184 tests passing (78 main suite + 103 Vitest + 3 bin tests).

Author: ianwhitedeveloper

bin/riteway.js

@@ -7,7 +7,7 @@ import minimist from 'minimist';
 import { globSync } from 'glob';
 import dotignore from 'dotignore';
 import { errorCauses, createError } from 'error-causes';
-import { runAITests, verifyAgentAuthentication, validateFilePath } from '../source/ai-runner.js';
+import { runAITests, verifyAgentAuthentication, validateFilePath, parseOpenCodeNDJSON } from '../source/ai-runner.js';
 import { recordTestOutput, generateLogFilePath } from '../source/test-output.js';
 
 const resolveModule = resolve.sync;
@@ -48,7 +48,8 @@ export const getAgentConfig = (agentName = 'claude') => {
     },
     opencode: {
       command: 'opencode',
-      args: ['--output-format', 'json']
+      args: ['run', '--format', 'json'],
+      parseOutput: (stdout, logger) => parseOpenCodeNDJSON(stdout, logger)
     },
     cursor: {
       command: 'agent',

bin/riteway.test.js

@@ -408,50 +408,90 @@ describe('getAgentConfig()', async assert => {
   assert({
     given: 'agent name "claude"',
     should: 'return claude agent configuration',
-    actual: getAgentConfig('claude'),
+    actual: (() => {
+      const config = getAgentConfig('claude');
+      return {
+        command: config.command,
+        args: config.args,
+        hasParseOutput: config.parseOutput !== undefined
+      };
+    })(),
     expected: {
       command: 'claude',
-      args: ['-p', '--output-format', 'json', '--no-session-persistence']
+      args: ['-p', '--output-format', 'json', '--no-session-persistence'],
+      hasParseOutput: false
     }
   });
 
   assert({
     given: 'agent name "opencode"',
-    should: 'return opencode agent configuration',
-    actual: getAgentConfig('opencode'),
+    should: 'return opencode agent configuration with run subcommand',
+    actual: (() => {
+      const config = getAgentConfig('opencode');
+      return {
+        command: config.command,
+        args: config.args,
+        hasParseOutput: typeof config.parseOutput === 'function'
+      };
+    })(),
     expected: {
       command: 'opencode',
-      args: ['--output-format', 'json']
+      args: ['run', '--format', 'json'],
+      hasParseOutput: true
     }
   });
 
   assert({
     given: 'agent name "cursor"',
     should: 'return cursor agent configuration using OAuth',
-    actual: getAgentConfig('cursor'),
+    actual: (() => {
+      const config = getAgentConfig('cursor');
+      return {
+        command: config.command,
+        args: config.args,
+        hasParseOutput: config.parseOutput !== undefined
+      };
+    })(),
     expected: {
       command: 'agent',
-      args: ['--print', '--output-format', 'json']
+      args: ['--print', '--output-format', 'json'],
+      hasParseOutput: false
     }
   });
 
   assert({
     given: 'no agent name (undefined)',
     should: 'return default claude configuration',
-    actual: getAgentConfig(),
+    actual: (() => {
+      const config = getAgentConfig();
+      return {
+        command: config.command,
+        args: config.args,
+        hasParseOutput: config.parseOutput !== undefined
+      };
+    })(),
     expected: {
       command: 'claude',
-      args: ['-p', '--output-format', 'json', '--no-session-persistence']
+      args: ['-p', '--output-format', 'json', '--no-session-persistence'],
+      hasParseOutput: false
     }
   });
 
   assert({
     given: 'agent name in mixed case',
-    should: 'handle case-insensitive lookup',
-    actual: getAgentConfig('OpenCode'),
+    should: 'handle case-insensitive lookup with correct args',
+    actual: (() => {
+      const config = getAgentConfig('OpenCode');
+      return {
+        command: config.command,
+        args: config.args,
+        hasParseOutput: typeof config.parseOutput === 'function'
+      };
+    })(),
     expected: {
       command: 'opencode',
-      args: ['--output-format', 'json']
+      args: ['run', '--format', 'json'],
+      hasParseOutput: true
     }
   });
 

package-lock.json

@@ -9,6 +9,12 @@
 
 ## Completed Epics
 
+### ✅ OpenCode Agent Support Fix Epic
+**Status**: ✅ COMPLETED (2026-02-05)  
+**File**: [`tasks/archive/2026-01-22-riteway-ai-testing-framework/2026-02-04-opencode-agent-support-fix.md`](./tasks/archive/2026-01-22-riteway-ai-testing-framework/2026-02-04-opencode-agent-support-fix.md)  
+**Goal**: Fix OpenCode agent integration to properly handle NDJSON streaming output format  
+**Result**: Successfully fixed OpenCode agent to parse NDJSON streaming output and handle markdown-wrapped JSON responses. Implemented structured error handling following error-causes.mdc standard. All 184 tests passing, live testing confirmed working.
+
 ### ✅ RiteWay AI Testing Framework Epic
 **Status**: ✅ COMPLETED (2026-01-23)  
 **File**: [`tasks/archive/2026-01-22-riteway-ai-testing-framework.md`](./tasks/archive/2026-01-22-riteway-ai-testing-framework.md)  

plan.md

@@ -70,6 +70,48 @@ export const parseStringResult = (result, logger) => {
   return result;
 };
 
+/**
+ * Parse OpenCode's NDJSON (newline-delimited JSON) output format.
+ * OpenCode emits multiple JSON objects separated by newlines, with different event types.
+ * We extract and concatenate all "text" events to get the final response.
+ * @param {string} ndjson - NDJSON output from OpenCode
+ * @param {Object} logger - Debug logger instance
+ * @returns {string} Concatenated text from all text events
+ */
+export const parseOpenCodeNDJSON = (ndjson, logger) => {
+  logger.log('Parsing OpenCode NDJSON output...');
+  
+  const lines = ndjson.trim().split('\n').filter(line => line.trim());
+  
+  const textEvents = lines.reduce((acc, line) => {
+    try {
+      const event = JSON.parse(line);
+      if (event.type === 'text' && event.part?.text) {
+        logger.log(`Found text event with ${event.part.text.length} characters`);
+        acc.push(event.part.text);
+      }
+    } catch (err) {
+      logger.log(`Warning: Failed to parse NDJSON line: ${err.message}`);
+    }
+    return acc;
+  }, []);
+  
+  if (textEvents.length === 0) {
+    throw createError({
+      name: 'ParseError',
+      message: 'No text events found in OpenCode output',
+      code: 'NO_TEXT_EVENTS',
+      ndjsonLength: ndjson.length,
+      linesProcessed: lines.length
+    });
+  }
+  
+  const combinedText = textEvents.join('');
+  logger.log(`Combined ${textEvents.length} text event(s) into ${combinedText.length} characters`);
+  
+  return combinedText;
+};
+
 /**
  * Read the contents of a test file.
  * @param {string} filePath - Path to the test file
@@ -160,6 +202,7 @@ export const verifyAgentAuthentication = async ({ agentConfig, timeout = 30000,
  * @param {Object} options.agentConfig - Agent configuration
  * @param {string} options.agentConfig.command - Command to execute
  * @param {Array<string>} [options.agentConfig.args=[]] - Command arguments
+ * @param {Function} [options.agentConfig.parseOutput] - Optional function to preprocess stdout before JSON parsing
  * @param {string} options.prompt - Prompt to send to the agent
  * @param {number} [options.timeout=300000] - Timeout in milliseconds (default: 5 minutes)
  * @param {boolean} [options.debug=false] - Enable debug logging
@@ -169,7 +212,7 @@ export const verifyAgentAuthentication = async ({ agentConfig, timeout = 30000,
  */
 export const executeAgent = ({ agentConfig, prompt, timeout = 300000, debug = false, logFile }) => {
   return new Promise((resolve, reject) => {
-    const { command, args = [] } = agentConfig;
+    const { command, args = [], parseOutput } = agentConfig;
     const allArgs = [...args, prompt];
     const logger = createDebugLogger({ debug, logFile });
 
@@ -225,10 +268,23 @@ export const executeAgent = ({ agentConfig, prompt, timeout = 300000, debug = fa
       }
 
       try {
-        const parsed = JSON.parse(stdout);
+        // Apply parseOutput function if provided (e.g., for NDJSON preprocessing)
+        const processedOutput = parseOutput ? parseOutput(stdout, logger) : stdout;
+        
+        // Parse the processed output - handles both raw JSON and markdown-wrapped JSON
+        let result = parseStringResult(processedOutput, logger);
+        
+        // If result is still a string (not parsed as JSON), that's an error
+        if (typeof result === 'string') {
+          throw new Error(`Agent output is not valid JSON: ${result.slice(0, 100)}`);
+        }
+        
         // Claude CLI wraps response in envelope with "result" field
-        let result = parsed.result !== undefined ? parsed.result : parsed;
+        if (result.result !== undefined) {
+          result = result.result;
+        }
 
+        // If result is a string after unwrapping, try to parse it again
         logger.log(`Parsed result type: ${typeof result}`);
         if (typeof result === 'string') {
           logger.log('Result is string, attempting to parse as JSON');
@@ -244,11 +300,15 @@ export const executeAgent = ({ agentConfig, prompt, timeout = 300000, debug = fa
         logger.log('JSON parsing failed:', err.message);
         logger.flush();
 
-        reject(new Error(
-          `Failed to parse agent output as JSON: ${err.message}\n` +
-          `Command: ${command} ${args.join(' ')}\n` +
-          `Stdout preview: ${truncatedStdout}`
-        ));
+        reject(createError({
+          name: 'ParseError',
+          message: `Failed to parse agent output as JSON: ${err.message}`,
+          code: 'AGENT_OUTPUT_PARSE_ERROR',
+          command,
+          args: args.join(' '),
+          stdoutPreview: truncatedStdout,
+          cause: err
+        }));
       }
     });