From b1a42ec4e03309cc5482dc0317c3c0b04a90b21a Mon Sep 17 00:00:00 2001
From: Mr-Neutr0n <64578610+Mr-Neutr0n@users.noreply.github.com>
Date: Fri, 6 Feb 2026 23:33:38 +0530
Subject: [PATCH] fix: improve error messaging for agent output validation
 failures

Add troubleshooting tips and more detailed error messages when agents
fail to create required deliverable files, especially for pre-recon.

Changes:
- Add troubleshooting tips to OutputValidationError for pre-recon agent
  (check repo path, router mode model, agent logs, target URL accessibility)
- Log expected file path when validation fails to help debug issues
- Include guidance to check audit logs for detailed agent output

This helps users diagnose common issues like:
- Using router mode with models that don't follow instructions well
- Repository path not accessible from Docker
- Target URL not reachable

Fixes #62
---
 src/ai/claude-executor.ts  |  9 +++++++++
 src/temporal/activities.ts | 12 +++++++++++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/ai/claude-executor.ts b/src/ai/claude-executor.ts
index bd194e2d..bcd4e59f 100644
--- a/src/ai/claude-executor.ts
+++ b/src/ai/claude-executor.ts
@@ -181,6 +181,15 @@ export async function validateAgentOutput(
       console.log(chalk.green(`    Validation passed: Required files/structure present`));
     } else {
       console.log(chalk.red(`    Validation failed: Missing required deliverable files`));
+      // Log which file is expected for common agents to help with debugging
+      const expectedFiles: Record<string, string> = {
+        'pre-recon': 'deliverables/code_analysis_deliverable.md',
+        'recon': 'deliverables/recon_deliverable.md',
+        'report': 'deliverables/comprehensive_security_assessment_report.md',
+      };
+      if (agentName && expectedFiles[agentName]) {
+        console.log(chalk.yellow(`    Expected file: ${sourceDir}/${expectedFiles[agentName]}`));
+      }
     }
 
     return validationResult;
diff --git a/src/temporal/activities.ts b/src/temporal/activities.ts
index 90572b03..c5716378 100644
--- a/src/temporal/activities.ts
+++ b/src/temporal/activities.ts
@@ -229,8 +229,18 @@ async function runAgentActivity(
 
       // Limit output validation retries (unlikely to self-heal)
       if (attemptNumber >= MAX_OUTPUT_VALIDATION_RETRIES) {
+        // Build helpful troubleshooting message
+        const troubleshootingTips = agentName === 'pre-recon'
+          ? `\n\nTroubleshooting tips:
+  1. Check if the repository path is accessible: ${repoPath}
+  2. If using ROUTER mode, ensure the model supports tool use and follows instructions well
+  3. Check agent logs at: audit-logs/*/agents/${agentName}*.jsonl
+  4. Try running with a different model (Claude models recommended)
+  5. Ensure the target URL is reachable from the Docker container`
+          : '';
+
         throw ApplicationFailure.nonRetryable(
-          `Agent ${agentName} failed output validation after ${attemptNumber} attempts`,
+          `Agent ${agentName} failed output validation after ${attemptNumber} attempts. Required deliverable files were not created.${troubleshootingTips}`,
           'OutputValidationError',
           [{ agentName, attemptNumber, elapsed: Date.now() - startTime }]
         );