jiva-core 0.3.1 → 0.3.3-dev.24b219d

package/dist/core/client-agent.js

@@ -9,137 +9,204 @@
  * - STANDARD: Creation requests → file existence + basic validation
  * - THOROUGH: Complex/testing requests OR failures → full E2E validation with tools
  */
+import { serializeAgentContext } from './utils/serialize-agent-context.js';
 import { logger } from '../utils/logger.js';
+import { orchestrationLogger } from '../utils/orchestration-logger.js';
 export var InvolvementLevel;
 (function (InvolvementLevel) {
     InvolvementLevel["MINIMAL"] = "minimal";
     InvolvementLevel["STANDARD"] = "standard";
     InvolvementLevel["THOROUGH"] = "thorough";
 })(InvolvementLevel || (InvolvementLevel = {}));
+/**
+ * Normalize the LLM-returned mustUseTools value to string[] | undefined.
+ * The LLM may return null, a string, or an array.
+ */
+function normalizeMustUseTools(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === 'string' && value)
+        return [value];
+    return undefined;
+}
 export class ClientAgent {
     orchestrator;
     mcpManager;
     mcpClient;
     failureCount = 0;
-    // Read-only tools Client can use for validation
-    ALLOWED_TOOLS = [
-        'filesystem__read_text_file',
-        'filesystem__list_directory',
-        'filesystem__directory_tree',
-        'filesystem__search_files',
-        'playwright__browser_navigate',
-        'playwright__browser_console_messages',
-        'playwright__browser_take_screenshot',
-        'playwright__browser_evaluate',
-    ];
+    // Lazily cached list of all available tool names (populated on first use)
+    _availableTools = null;
     constructor(orchestrator, mcpManager) {
         this.orchestrator = orchestrator;
         this.mcpManager = mcpManager;
         this.mcpClient = mcpManager.getClient();
     }
+    // ─── Tool Discovery ───────────────────────────────────────────────────────
     /**
-     * Determine involvement level based on user request complexity
+     * Returns all tool names currently available from connected MCP servers.
+     * Result is cached after the first call; call resetToolCache() if servers change.
      */
-    determineInvolvementLevel(userMessage, subtasks) {
-        const messageLower = userMessage.toLowerCase();
-        const subtasksLower = subtasks.join(' ').toLowerCase();
-        // THOROUGH: User explicitly requests testing/verification
-        const testKeywords = ['test', 'verify', 'check', 'make sure', 'ensure', 'validate'];
-        if (testKeywords.some(kw => messageLower.includes(kw))) {
-            logger.debug('[Client] THOROUGH mode: Testing/verification requested');
-            return InvolvementLevel.THOROUGH;
-        }
-        // THOROUGH: After failures (user frustrated)
-        if (this.failureCount > 0) {
-            logger.debug(`[Client] THOROUGH mode: ${this.failureCount} previous failures detected`);
-            return InvolvementLevel.THOROUGH;
-        }
-        // THOROUGH: Complex multi-file operations
-        if (subtasks.length > 3 || (messageLower.includes('component') && messageLower.includes('index.html'))) {
-            logger.debug('[Client] THOROUGH mode: Complex multi-file operation');
-            return InvolvementLevel.THOROUGH;
-        }
-        // MINIMAL: Information-only requests
-        const infoKeywords = ['what', 'list', 'show', 'explain', 'describe', 'how', 'tell me'];
-        const creationKeywords = ['create', 'build', 'write', 'generate', 'make', 'add'];
-        const hasInfoKeyword = infoKeywords.some(kw => messageLower.includes(kw));
-        const hasCreationKeyword = creationKeywords.some(kw => messageLower.includes(kw));
-        if (hasInfoKeyword && !hasCreationKeyword) {
-            logger.debug('[Client] MINIMAL mode: Information request');
-            return InvolvementLevel.MINIMAL;
-        }
-        // STANDARD: Default for creation/modification tasks
-        logger.debug('[Client] STANDARD mode: Regular creation task');
-        return InvolvementLevel.STANDARD;
+    getAvailableTools() {
+        if (this._availableTools === null) {
+            this._availableTools = this.mcpClient.getAllTools().map(t => t.name);
+            logger.debug(`[Client] Discovered ${this._availableTools.length} available tools: ${this._availableTools.join(', ')}`);
+        }
+        return this._availableTools;
+    }
+    /** Reset the tool cache (e.g. after MCP server reconnects). */
+    resetToolCache() {
+        this._availableTools = null;
     }
     /**
-     * Parse requirements from user message
+     * Find the first available tool whose name contains any of the given substrings.
+     * Returns null if no match is found.
      */
-    parseRequirements(userMessage, subtasks) {
-        const requirements = [];
-        const messageLower = userMessage.toLowerCase();
-        const combined = (messageLower + ' ' + subtasks.join(' ').toLowerCase());
-        // Detect file creation requirements
-        const fileMatches = userMessage.match(/(?:create|build|generate|write|save as)\s+([a-zA-Z0-9._/-]+\.(html|js|css|md|json|txt|py|ts|tsx|jsx))/gi);
-        if (fileMatches) {
-            fileMatches.forEach(match => {
-                const filename = match.split(/\s+/).pop();
-                if (filename) {
-                    requirements.push({
-                        type: 'file_creation',
-                        description: `Create file: ${filename}`,
-                        filePath: filename,
-                    });
-                }
-            });
+    findTool(...patterns) {
+        const tools = this.getAvailableTools();
+        for (const pattern of patterns) {
+            const found = tools.find(t => t.includes(pattern));
+            if (found)
+                return found;
         }
-        // Detect testing requirements (explicit verification requests)
-        const testKeywords = ['test', 'verify', 'check', 'make sure', 'ensure'];
-        if (testKeywords.some(kw => combined.includes(kw))) {
-            requirements.push({
-                type: 'testing',
-                description: 'Verify functionality through testing',
-                mustUseTools: ['playwright__'],
-            });
+        return null;
+    }
+    /**
+     * Build a human-readable summary of available tool categories for LLM prompts.
+     */
+    buildToolContextForPrompt() {
+        const tools = this.getAvailableTools();
+        if (tools.length === 0) {
+            return 'No MCP tools are currently available.';
         }
-        // Detect browser verification requirements - ONLY for file verification, not general browsing
-        // This should trigger for "open index.html in browser" but NOT for "open linkedin.com"
-        const isLocalFileOpen = (combined.includes('open') && combined.includes('.html')) ||
-            (combined.includes('browser') && combined.includes('.html'));
-        const isExternalUrl = combined.match(/open\s+(?:https?:\/\/)?(?:www\.)?[a-z0-9-]+\.[a-z]{2,}/i);
-        if (isLocalFileOpen && !isExternalUrl) {
-            requirements.push({
-                type: 'verification',
-                description: 'Browser testing required for local HTML file',
-                mustUseTools: ['playwright__browser_navigate', 'playwright__browser_console_messages'],
-            });
+        // Group by server prefix (everything before __)
+        const byServer = {};
+        for (const tool of tools) {
+            const [server] = tool.split('__');
+            if (!byServer[server])
+                byServer[server] = [];
+            byServer[server].push(tool);
         }
-        // For external URLs, don't require specific tools - just opening the page is enough
-        if (isExternalUrl) {
-            requirements.push({
-                type: 'verification',
-                description: 'Open external URL',
-                // No mustUseTools - Worker just needs to navigate, Client shouldn't demand specific validation tools
+        return Object.entries(byServer)
+            .map(([server, serverTools]) => `- ${server}: ${serverTools.join(', ')}`)
+            .join('\n');
+    }
+    // ─── Task Analysis ────────────────────────────────────────────────────────
+    /**
+     * Use LLM to analyze the task and determine involvement level + requirements.
+     * Replaces keyword-based determineInvolvementLevel() and parseRequirements()
+     * with semantic understanding that avoids false positives.
+     *
+     * NOTE: failureCount escalation has been removed. Involvement level is now
+     * determined purely by task type. Per-subtask correction is handled by
+     * CompletionSignal + DualAgent retry budget instead.
+     */
+    async analyzeTaskRequirements(userMessage, subtasks, workerResult, agentContext) {
+        const workerContext = workerResult
+            ? `\nWorker Result (first 500 chars): ${workerResult.result.substring(0, 500)}\nWorker Success: ${workerResult.success}\nTools Used: ${workerResult.toolsUsed.join(', ') || 'none'} (${workerResult.toolsUsed.length} total)`
+            : '';
+        const availableToolsContext = this.buildToolContextForPrompt();
+        // Include serialized agent context for richer analysis
+        const contextBlock = agentContext
+            ? `\nAGENT CONTEXT:\n${serializeAgentContext(agentContext, 'client')}`
+            : '';
+        const analysisPrompt = `You are a task analyst for a software agent system. Analyze the user's request to determine:
+1. How deeply to validate the Worker's output (involvement level)
+2. What specific requirements the task implies
+
+USER MESSAGE: ${userMessage}
+
+SUBTASKS: ${JSON.stringify(subtasks)}
+${workerContext}
+${contextBlock}
+
+AVAILABLE TOOLS (what the Worker and Client can actually use):
+${availableToolsContext}
+
+Respond ONLY with valid JSON in this exact format (no other text):
+{
+  "involvementLevel": "<MINIMAL | STANDARD | THOROUGH>",
+  "involvementReasoning": "<brief explanation of why this level>",
+  "requirements": [
+    {
+      "type": "<file_creation | file_modification | testing | verification | information | other>",
+      "description": "<what this requirement entails>",
+      "filePath": null,
+      "mustUseTools": null
+    }
+  ]
+}
+
+CRITICAL RULES for involvementLevel:
+- THOROUGH: ONLY when the user EXPLICITLY asks to test or verify something, OR for complex multi-file operations (>3 subtasks)
+- MINIMAL: Information-only requests (listing files, explaining code, describing something, answering questions) where no files are created or modified
+- STANDARD: Default for creation, modification, or action tasks
+
+CRITICAL RULES for requirements:
+- Only set mustUseTools to tool names listed in AVAILABLE TOOLS above — do NOT reference tools that are not available
+- If the required tool is not in AVAILABLE TOOLS, set mustUseTools to null
+- "testing" type should only be set when the user explicitly wants something executed and verified
+- If no specific tools are required, set mustUseTools to null
+- Always include at least one requirement entry`;
+        try {
+            const response = await this.orchestrator.chat({
+                messages: [
+                    { role: 'system', content: 'You are a strict task analyst. Respond only with valid JSON.' },
+                    { role: 'user', content: analysisPrompt },
+                ],
+                temperature: 0.1,
             });
+            const jsonMatch = response.content.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+                const analysis = JSON.parse(jsonMatch[0]);
+                // Map string to enum
+                let level;
+                switch (analysis.involvementLevel?.toUpperCase()) {
+                    case 'THOROUGH':
+                        level = InvolvementLevel.THOROUGH;
+                        break;
+                    case 'MINIMAL':
+                        level = InvolvementLevel.MINIMAL;
+                        break;
+                    default:
+                        level = InvolvementLevel.STANDARD;
+                }
+                // NOTE: failureCount escalation removed — involvement level is determined
+                // purely by task type. Per-subtask correction is handled by CompletionSignal.
+                const requirements = (analysis.requirements || []).map((req) => ({
+                    type: req.type || 'other',
+                    description: req.description || 'General task completion',
+                    filePath: req.filePath || undefined,
+                    mustUseTools: normalizeMustUseTools(req.mustUseTools),
+                }));
+                // Ensure at least one requirement
+                if (requirements.length === 0) {
+                    requirements.push({ type: 'other', description: 'General task completion' });
+                }
+                logger.info(`[Client] LLM task analysis: ${level.toUpperCase()} involvement — ${analysis.involvementReasoning || 'no reasoning provided'}`);
+                logger.debug(`[Client] Requirements: ${JSON.stringify(requirements.map(r => ({ type: r.type, desc: r.description })))}`);
+                return { level, requirements };
+            }
         }
-        // Default: at least verify Worker did some work
-        if (requirements.length === 0) {
-            requirements.push({
-                type: 'other',
-                description: 'General task completion',
-            });
+        catch (error) {
+            logger.warn(`[Client] LLM task analysis failed: ${error}, falling back to STANDARD`);
         }
-        return requirements;
+        // Fallback: STANDARD with generic requirement (no failureCount escalation)
+        return {
+            level: InvolvementLevel.STANDARD,
+            requirements: [{ type: 'other', description: 'General task completion' }],
+        };
     }
+    // ─── Main Validation Entry Point ──────────────────────────────────────────
     /**
      * Validate Worker's work at appropriate involvement level
      */
-    async validate(userMessage, subtasks, workerResult, involvementLevel) {
-        let level = involvementLevel || this.determineInvolvementLevel(userMessage, subtasks);
-        const requirements = this.parseRequirements(userMessage, subtasks);
+    async validate(userMessage, subtasks, workerResult, involvementLevel, agentContext) {
+        // Use LLM-based analysis instead of keyword matching
+        const { level: analyzedLevel, requirements } = await this.analyzeTaskRequirements(userMessage, subtasks, workerResult, agentContext);
+        let level = involvementLevel || analyzedLevel;
         // CRITICAL: Use LLM to check for unjustified failure claims BEFORE other validation
         // Even in MINIMAL mode, we must catch agents giving up without trying
-        const failureAnalysis = await this.analyzeForUnjustifiedFailure(userMessage, workerResult);
+        const failureAnalysis = await this.analyzeForUnjustifiedFailure(userMessage, workerResult, agentContext);
         if (failureAnalysis.claimsFailure && !failureAnalysis.hasEvidence) {
             logger.info(`[Client] Detected unjustified failure claim - escalating from ${level} to STANDARD`);
             logger.info(`[Client] LLM reasoning: ${failureAnalysis.reasoning}`);
@@ -150,6 +217,8 @@ export class ClientAgent {
             }
         }
         logger.info(`[Client] Validating with ${level.toUpperCase()} involvement`);
+        // Log the analysis for orchestration tracing
+        orchestrationLogger.logClientAnalysis(level, requirements.length, `Requirements: ${requirements.map(r => r.type).join(', ')}`);
         const result = {
             approved: false,
             requirementsMet: false,
@@ -162,8 +231,26 @@ export class ClientAgent {
                 `REJECTED: Worker claims failure without sufficient evidence. ${failureAnalysis.reasoning}`;
             result.issues.push(failureIssue);
         }
+        // Layer 0.5: Result-vs-Evidence Coherence Check (always done, catches hallucinated accomplishments)
+        // This detects when the Worker claims to have done things its tool usage doesn't support
+        const coherenceAnalysis = await this.analyzeResultCoherence(userMessage, workerResult, agentContext);
+        orchestrationLogger.logClientCoherenceCheck(coherenceAnalysis.isCoherent, coherenceAnalysis.unsupportedClaims, coherenceAnalysis.reasoning);
+        if (!coherenceAnalysis.isCoherent) {
+            logger.info(`[Client] Detected incoherent result — Worker claims not supported by tool usage`);
+            logger.info(`[Client] Unsupported claims: ${coherenceAnalysis.unsupportedClaims.join('; ')}`);
+            logger.info(`[Client] Coherence reasoning: ${coherenceAnalysis.reasoning}`);
+            const coherenceIssue = coherenceAnalysis.suggestedAction ||
+                `REJECTED: Worker's result contains claims not supported by its actual tool usage. ${coherenceAnalysis.reasoning}`;
+            result.issues.push(coherenceIssue);
+            // Escalate involvement level — the Worker is hallucinating, we need stricter validation
+            if (level === InvolvementLevel.MINIMAL) {
+                level = InvolvementLevel.STANDARD;
+                result.involvementLevel = level;
+                logger.info(`[Client] Escalating to STANDARD due to incoherent result`);
+            }
+        }
         // Layer 1: Process Validation (always done, no tools needed)
-        const processValidation = this.validateProcess(requirements, workerResult);
+        const processValidation = this.validateProcess(requirements, workerResult, level);
         if (processValidation.issues.length > 0) {
             result.issues.push(...processValidation.issues);
         }
@@ -178,24 +265,31 @@ export class ClientAgent {
         result.requirementsMet = result.issues.length === 0;
         result.approved = result.requirementsMet;
         if (!result.approved && result.issues.length > 0) {
-            result.nextAction = result.issues[0]; // Most critical issue becomes next action
-            this.failureCount++;
+            // Generate an actionable correction instruction via LLM instead of echoing raw validation issues
+            result.nextAction = await this.generateCorrectionInstruction(userMessage, subtasks.join('; '), result.issues, workerResult, agentContext);
+            this.failureCount++; // Telemetry only — no longer drives escalation
         }
         else {
-            this.failureCount = 0; // Reset on success
+            this.failureCount = 0;
         }
+        // Analyze CompletionSignal (LLM-based per-subtask assessment)
+        result.completionSignal = await this.analyzeCompletionSignal(userMessage, workerResult, result.issues, agentContext);
+        // Log the validation outcome
+        orchestrationLogger.logClientValidation(result.approved, result.issues, result.nextAction);
         return result;
     }
     /**
      * Use LLM to analyze worker result for unjustified failure claims
      * This is language-agnostic and captures semantic meaning
      */
-    async analyzeForUnjustifiedFailure(userMessage, workerResult) {
+    async analyzeForUnjustifiedFailure(userMessage, workerResult, agentContext) {
         const toolCount = workerResult.toolsUsed.length;
         const toolList = workerResult.toolsUsed.join(', ') || 'none';
+        const contextBlock = agentContext ? `\n${serializeAgentContext(agentContext, 'client')}` : '';
         const analysisPrompt = `You are a quality control agent. Analyze the following Worker response to determine if it's claiming failure and whether that failure is justified.
 
 USER REQUEST: ${userMessage}
+${contextBlock}
 
 WORKER RESPONSE:
 ${workerResult.result}
@@ -245,28 +339,112 @@ Respond ONLY with the JSON, no other text.`;
             reasoning: 'Analysis could not be performed',
         };
     }
+    /**
+     * Use LLM to cross-check the Worker's result claims against its actual tool usage.
+     * Catches hallucinated accomplishments — e.g., Worker claims "I inspected all source files
+     * and found no bugs" but only used list_directory and never read a single file.
+     * This runs at ALL involvement levels including MINIMAL.
+     */
+    async analyzeResultCoherence(userMessage, workerResult, agentContext) {
+        // Skip coherence check if Worker used no tools (caught by zero-tools guard)
+        // or if Worker explicitly failed (caught by failure analysis)
+        if (workerResult.toolsUsed.length === 0 || !workerResult.success) {
+            return { isCoherent: true, reasoning: 'Skipped — handled by other checks', unsupportedClaims: [] };
+        }
+        const toolList = workerResult.toolsUsed.join(', ');
+        const uniqueTools = [...new Set(workerResult.toolsUsed)].join(', ');
+        const availableToolsContext = this.buildToolContextForPrompt();
+        const contextBlock = agentContext ? `\n${serializeAgentContext(agentContext, 'client')}` : '';
+        const coherencePrompt = `You are a strict quality auditor. Your job is to determine whether a Worker agent's result is SUPPORTED by the tools it actually used, or whether it fabricated/hallucinated claims.
+
+USER REQUEST: ${userMessage}
+${contextBlock}
+
+WORKER RESULT:
+${workerResult.result.substring(0, 1000)}
+
+TOOLS ACTUALLY USED (in order): ${toolList}
+UNIQUE TOOLS USED: ${uniqueTools}
+TOTAL TOOL CALLS: ${workerResult.toolsUsed.length}
+
+AVAILABLE TOOLS IN THIS SYSTEM:
+${availableToolsContext}
+
+CRITICAL: Analyze whether the claims in the Worker's result are supported by the tools it used.
+
+Key tool semantics to apply:
+- Tools with names like "list_directory", "directory_tree", "search_files" show file/folder NAMES only — they do NOT read file contents
+- Tools with names like "read_text_file", "read_file", "get_file_content" actually read file content
+- Tools with names like "shell_exec", "run_command", "bash", "execute" run shell commands — infer what was run from the worker's result
+- For any other tool, infer its semantics from its name
+
+Common hallucination patterns to detect:
+1. Worker claims to have "inspected", "reviewed", "analyzed", or "scanned" source code but never used read_text_file — it only listed directories
+2. Worker claims "no bugs found" or "code is correct" without reading any source files
+3. Worker claims to have run tests or builds but no shell_exec tool was used (or the result doesn't reference actual test output)
+4. Worker provides specific code details (line numbers, variable names, function logic) without having read the files containing them
+5. Worker makes definitive statements about code quality, correctness, or behavior without having read the relevant code
+
+Respond ONLY with valid JSON:
+{
+  "isCoherent": <true if ALL claims in the result are supported by actual tool usage, false if any claims are fabricated>,
+  "reasoning": "<brief explanation of what's supported vs what's fabricated>",
+  "unsupportedClaims": ["<list each specific claim that is NOT supported by tool usage>"],
+  "suggestedAction": "<if not coherent, what the Worker should actually do — e.g., 'Read the source files using filesystem__read_text_file before claiming to have analyzed them'>"
+}`;
+        try {
+            const response = await this.orchestrator.chat({
+                messages: [
+                    { role: 'system', content: 'You are a strict quality auditor. Respond only with valid JSON.' },
+                    { role: 'user', content: coherencePrompt },
+                ],
+                temperature: 0.1,
+            });
+            const jsonMatch = response.content.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+                const analysis = JSON.parse(jsonMatch[0]);
+                return analysis;
+            }
+        }
+        catch (error) {
+            logger.debug(`[Client] Failed to analyze result coherence: ${error}`);
+        }
+        // Default: assume coherent if analysis fails
+        return {
+            isCoherent: true,
+            reasoning: 'Coherence analysis could not be performed',
+            unsupportedClaims: [],
+        };
+    }
     /**
      * Layer 1: Process Validation (metadata only, no tools)
      */
-    validateProcess(requirements, workerResult) {
+    validateProcess(requirements, workerResult, involvementLevel) {
         const issues = [];
+        // Zero-tools guard: if Worker used no tools at all and this is not a purely
+        // informational/conversational task, reject immediately
+        if (workerResult.toolsUsed.length === 0 && involvementLevel !== InvolvementLevel.MINIMAL) {
+            const isConversational = requirements.every(r => r.type === 'information' || r.type === 'other');
+            if (!isConversational) {
+                issues.push('Worker completed the task without using any tools. ' +
+                    'The task requires actual tool usage (file operations, shell commands, browser actions, etc.) — ' +
+                    'not just generating a text response. Use the available tools to actually perform the task.');
+            }
+        }
         // Check if Worker used appropriate tools for requirements
         for (const req of requirements) {
             if (req.mustUseTools && req.mustUseTools.length > 0) {
                 const usedRequiredTool = req.mustUseTools.some(requiredTool => {
-                    // Match if required tool is contained in actual tool name (e.g., 'playwright__browser' matches 'playwright__browser_navigate')
-                    // OR if actual tool exactly matches the required tool
                     return workerResult.toolsUsed.some(actualTool => actualTool === requiredTool || actualTool.startsWith(requiredTool) || requiredTool.startsWith(actualTool.split('__')[0] + '__'));
                 });
                 if (!usedRequiredTool) {
-                    issues.push(`${req.description} requires using ${req.mustUseTools.join(' or ')} but Worker did not use these tools. ` +
-                        `Create a subtask specifically for ${req.description.toLowerCase()}.`);
+                    issues.push(`${req.description} requires using ${req.mustUseTools.join(' or ')} but Worker did not use these tools.`);
                 }
             }
         }
         // Check if Worker succeeded
         if (!workerResult.success) {
-            issues.push(`Worker did not complete the task successfully. This suggests the task needs to be broken down differently or requires clarification.`);
+            issues.push('Worker did not complete the task successfully. The task needs to be retried with appropriate tool usage.');
         }
         return { issues };
     }
@@ -296,111 +474,276 @@ Respond ONLY with the JSON, no other text.`;
                 }
             }
         }
-        // Browser testing validation (only for THOROUGH)
+        // Shell-based deep verification (THOROUGH only)
         if (level === InvolvementLevel.THOROUGH) {
-            for (const req of requirements) {
-                if ((req.type === 'testing' || req.type === 'verification') &&
-                    workerResult.result.includes('.html')) {
-                    // Extract HTML filename from result
-                    const htmlMatch = workerResult.result.match(/([a-zA-Z0-9._-]+\.html)/);
-                    if (htmlMatch) {
-                        const htmlFile = htmlMatch[1];
-                        const browserValidation = await this.validateInBrowser(htmlFile);
-                        if (!browserValidation.valid) {
-                            issues.push(browserValidation.issue);
-                        }
-                    }
-                }
-            }
+            const shellIssues = await this.validateWithShell(requirements, workerResult);
+            issues.push(...shellIssues.issues);
         }
         return { issues };
     }
+    // ─── Tool-Based Verification ────────────────────────────────────────────────────
     /**
-     * Check if file exists using read tool
+     * Check whether a file exists, using whichever MCP tool is available.
+     * Tries filesystem read tools first, then falls back to shell.
      */
     async fileExists(filePath) {
+        const readTool = this.findTool('read_text_file', 'read_file', 'get_file_content');
+        if (readTool) {
+            try {
+                await this.mcpClient.executeTool(readTool, { path: filePath, head: 1 });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        const shellTool = this.findTool('shell_exec', 'run_command', 'bash', 'execute');
+        if (shellTool) {
+            try {
+                const result = await this.mcpClient.executeTool(shellTool, {
+                    command: `test -f "${filePath}" && echo "exists" || echo "not_found"`,
+                });
+                return String(result).includes('exists');
+            }
+            catch {
+                return false;
+            }
+        }
+        logger.debug('[Client] No tool available to verify file existence');
+        return false;
+    }
+    /**
+     * Use LLM to generate an actionable correction instruction from raw validation issues.
+     * Translates internal validation failures into concrete, tool-specific directions
+     * for the Worker, referencing only the tools actually available in the system.
+     */
+    async generateCorrectionInstruction(userMessage, subtask, issues, workerResult, agentContext) {
+        const availableToolsContext = this.buildToolContextForPrompt();
+        const contextBlock = agentContext ? `\nAGENT CONTEXT:\n${serializeAgentContext(agentContext, 'client')}` : '';
+        const correctionPrompt = `You are generating a correction instruction for a Worker agent that failed to complete a task properly.
+
+ORIGINAL USER REQUEST: ${userMessage}
+
+SUBTASK THAT WAS ATTEMPTED: ${subtask}
+
+VALIDATION ISSUES FOUND:
+${issues.map((issue, i) => `${i + 1}. ${issue}`).join('\n')}
+
+WORKER'S RESULT (first 300 chars): ${workerResult.result.substring(0, 300)}
+TOOLS WORKER USED: ${workerResult.toolsUsed.join(', ') || 'none'}
+
+AVAILABLE TOOLS THE WORKER CAN USE:
+${availableToolsContext}
+${contextBlock}
+
+Generate a CLEAR, ACTIONABLE instruction that tells the Worker exactly what to do to fix the issues.
+The instruction should:
+- Be a direct command referencing specific available tools by name
+- Be concise (1-2 sentences)
+- NOT include validation jargon like "mustUseTools", "requirements", or "involvement level"
+- NOT be a generic statement like "retry the task" — be specific about WHAT to do
+
+Respond ONLY with the correction instruction text, nothing else.`;
         try {
-            await this.mcpClient.executeTool('filesystem__read_text_file', {
-                path: filePath,
-                head: 1,
+            const response = await this.orchestrator.chat({
+                messages: [
+                    { role: 'system', content: 'You generate concise, actionable correction instructions for a Worker agent. Respond with only the instruction text.' },
+                    { role: 'user', content: correctionPrompt },
+                ],
+                temperature: 0.1,
             });
-            return true;
+            const instruction = response.content.trim();
+            if (instruction.length > 10 && instruction.length < 500) {
+                return instruction;
+            }
         }
         catch (error) {
-            return false;
+            logger.warn(`[Client] Failed to generate correction instruction: ${error}`);
         }
+        // Fallback: use first issue with a prefix
+        return `Fix the following issue and retry: ${issues[0]}`;
     }
     /**
-     * Validate file contents for common issues
+     * Validate file contents for common issues, using whichever MCP tool is available.
      */
     async validateFileContents(filePath) {
-        try {
-            const content = await this.mcpClient.executeTool('filesystem__read_text_file', {
-                path: filePath,
-                head: 200,
-            });
-            const contentStr = typeof content === 'string' ? content : JSON.stringify(content);
-            // Check for HTML path mismatches
-            if (filePath.endsWith('.html')) {
-                const hrefMatches = contentStr.match(/href="([^"]+)"/g) || [];
-                const srcMatches = contentStr.match(/src="([^"]+)"/g) || [];
-                for (const match of [...hrefMatches, ...srcMatches]) {
-                    const pathMatch = match.match(/(?:href|src)="([^"]+)"/);
-                    if (pathMatch) {
-                        const referencedPath = pathMatch[1];
-                        if (!referencedPath.startsWith('http') && !referencedPath.startsWith('data:')) {
-                            const exists = await this.fileExists(referencedPath);
-                            if (!exists) {
-                                return {
-                                    valid: false,
-                                    issue: `HTML references non-existent file: ${referencedPath}. Fix file paths or create missing files.`
-                                };
-                            }
+        const readTool = this.findTool('read_text_file', 'read_file', 'get_file_content');
+        const shellTool = this.findTool('shell_exec', 'run_command', 'bash', 'execute');
+        let contentStr = null;
+        if (readTool) {
+            try {
+                const content = await this.mcpClient.executeTool(readTool, { path: filePath, head: 200 });
+                contentStr = typeof content === 'string' ? content : JSON.stringify(content);
+            }
+            catch (error) {
+                return { valid: false, issue: `Could not read file: ${error}` };
+            }
+        }
+        else if (shellTool) {
+            try {
+                const content = await this.mcpClient.executeTool(shellTool, {
+                    command: `head -200 "${filePath}" 2>&1`,
+                });
+                contentStr = String(content);
+            }
+            catch (error) {
+                return { valid: false, issue: `Could not read file via shell: ${error}` };
+            }
+        }
+        if (contentStr === null) {
+            return { valid: true }; // No read tool available; skip content check
+        }
+        // Check path reference integrity in HTML files
+        if (filePath.endsWith('.html')) {
+            const hrefMatches = contentStr.match(/href="([^"]+)"/g) || [];
+            const srcMatches = contentStr.match(/src="([^"]+)"/g) || [];
+            for (const match of [...hrefMatches, ...srcMatches]) {
+                const pathMatch = match.match(/(?:href|src)="([^"]+)"/);
+                if (pathMatch) {
+                    const referencedPath = pathMatch[1];
+                    if (!referencedPath.startsWith('http') && !referencedPath.startsWith('data:')) {
+                        const exists = await this.fileExists(referencedPath);
+                        if (!exists) {
+                            return {
+                                valid: false,
+                                issue: `HTML references non-existent file: ${referencedPath}. Fix file paths or create missing files.`,
+                            };
                         }
                     }
                 }
             }
-            return { valid: true };
         }
-        catch (error) {
-            return { valid: false, issue: `Could not read file: ${error}` };
+        return { valid: true };
+    }
+    /**
+     * THOROUGH-level shell-based verification: runs lightweight, read-only shell
+     * commands to confirm work was actually done (file sizes, test output presence, etc.).
+     * Skips gracefully when no shell tool is available.
+     */
+    async validateWithShell(requirements, workerResult) {
+        const issues = [];
+        const shellTool = this.findTool('shell_exec', 'run_command', 'bash', 'execute');
+        if (!shellTool) {
+            logger.debug('[Client] No shell tool available for THOROUGH shell validation — skipping');
+            return { issues };
         }
+        for (const req of requirements) {
+            if ((req.type === 'file_creation' || req.type === 'file_modification') && req.filePath) {
+                try {
+                    const result = await this.mcpClient.executeTool(shellTool, {
+                        command: `wc -c "${req.filePath}" 2>&1`,
+                    });
+                    const resultStr = String(result);
+                    if (resultStr.includes('No such file') || resultStr.includes('cannot access')) {
+                        issues.push(`Shell verification failed: ${req.filePath} does not exist on disk.`);
+                    }
+                    else {
+                        const sizeMatch = resultStr.match(/^\s*(\d+)/);
+                        if (sizeMatch && parseInt(sizeMatch[1], 10) === 0) {
+                            issues.push(`File ${req.filePath} was created but is empty.`);
+                        }
+                    }
+                }
+                catch (error) {
+                    logger.debug(`[Client] Shell validation error for ${req.filePath}: ${error}`);
+                }
+            }
+            if (req.type === 'testing') {
+                const hasTestOutput = workerResult.result.match(/passed|failed|error|PASS|FAIL|✓|✗|tests run|test suite/i);
+                if (!hasTestOutput) {
+                    logger.debug('[Client] THOROUGH: testing requirement but no test output detected in worker result');
+                }
+            }
+        }
+        return { issues };
     }
+    // ─── Completion Signal Analysis ──────────────────────────────────────────────
     /**
-     * Validate HTML file in browser
+     * LLM-based per-subtask assessment of completion confidence, blocker type,
+     * and suggested corrective strategy. Called at the end of validate().
      */
-    async validateInBrowser(htmlFile) {
+    async analyzeCompletionSignal(userMessage, workerResult, issues, agentContext) {
+        // If approved with no issues, high confidence
+        if (issues.length === 0) {
+            return { confidence: 'high', progressMade: true };
+        }
+        const contextBlock = agentContext ? `\n${serializeAgentContext(agentContext, 'client')}` : '';
+        const signalPrompt = `You are analyzing a subtask execution to produce a CompletionSignal.
+
+USER REQUEST: ${userMessage}
+${contextBlock}
+
+WORKER RESULT (first 500 chars): ${workerResult.result.substring(0, 500)}
+WORKER SUCCESS: ${workerResult.success}
+TOOLS USED: ${workerResult.toolsUsed.join(', ') || 'none'} (${workerResult.toolsUsed.length} total)
+
+VALIDATION ISSUES:
+${issues.map((issue, i) => `${i + 1}. ${issue}`).join('\n')}
+
+Analyze and respond ONLY with valid JSON:
+{
+  "confidence": "<high | medium | low | none>",
+  "progressMade": <true if Worker made any measurable forward progress, false otherwise>,
+  "blockerType": "<tool_failure | hallucination | scope_drift | partial | loop | capability_gap | null>",
+  "suggestedStrategy": "<retry | rephrase | decompose | skip | escalate>"
+}
+
+RULES:
+- confidence "high": all issues are minor or cosmetic
+- confidence "medium": some progress but incomplete
+- confidence "low": significant issues, little useful work
+- confidence "none": no useful work done at all
+- blockerType "tool_failure": Worker tried but tool errored
+- blockerType "hallucination": Worker claimed work it didn't do
+- blockerType "scope_drift": Worker did something unrelated
+- blockerType "partial": Worker made progress but didn't finish
+- blockerType "loop": Worker is repeating the same action
+- blockerType "capability_gap": Task requires tools/capabilities not available
+- suggestedStrategy: recommend the best recovery approach`;
         try {
-            // Navigate to file
-            const workspaceDir = process.cwd();
-            const fileUrl = `file://${workspaceDir}/${htmlFile}`;
-            await this.mcpClient.executeTool('playwright__browser_navigate', {
-                url: fileUrl,
-            });
-            // Check for console errors
-            const errors = await this.mcpClient.executeTool('playwright__browser_console_messages', {
-                level: 'error',
+            const response = await this.orchestrator.chat({
+                messages: [
+                    { role: 'system', content: 'You are a strict completion analyst. Respond only with valid JSON.' },
+                    { role: 'user', content: signalPrompt },
+                ],
+                temperature: 0.1,
             });
-            const errorStr = typeof errors === 'string' ? errors : JSON.stringify(errors);
-            if (errorStr && errorStr.length > 0 && !errorStr.includes('[]')) {
+            const jsonMatch = response.content.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+                const parsed = JSON.parse(jsonMatch[0]);
                 return {
-                    valid: false,
-                    issue: `Browser errors detected in ${htmlFile}: ${errorStr}. Fix these errors before delivery.`
+                    confidence: parsed.confidence || 'low',
+                    progressMade: parsed.progressMade ?? false,
+                    blockerType: parsed.blockerType === 'null' ? undefined : parsed.blockerType,
+                    suggestedStrategy: parsed.suggestedStrategy,
                 };
             }
-            return { valid: true };
         }
         catch (error) {
-            logger.debug(`[Client] Browser validation error: ${error}`);
-            // Don't fail validation if browser test fails - might not have browser available
-            return { valid: true };
+            logger.debug(`[Client] Failed to analyze completion signal: ${error}`);
         }
+        // Fallback: conservative signal
+        return {
+            confidence: 'low',
+            progressMade: workerResult.toolsUsed.length > 0,
+            blockerType: 'partial',
+            suggestedStrategy: 'retry',
+        };
     }
+    // ─── Session Management ─────────────────────────────────────────────────────
     /**
-     * Reset failure tracking (for new conversation/session)
+     * Reset session state (call at the start of each new conversation/session).
+     * Renamed from resetFailureTracking() for clarity — failureCount is now
+     * telemetry-only and does not drive involvement escalation.
      */
-    resetFailureTracking() {
+    resetSessionState() {
         this.failureCount = 0;
     }
+    /**
+     * @deprecated Use resetSessionState() instead.
+     */
+    resetFailureTracking() {
+        this.resetSessionState();
+    }
 }
 //# sourceMappingURL=client-agent.js.map