jiva-core 0.3.2 → 0.3.3-dev.bd250bd

package/dist/core/client-agent.js

@@ -9,6 +9,7 @@
  * - 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;
@@ -17,36 +18,97 @@ export var InvolvementLevel;
     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 ───────────────────────────────────────────────────────
+    /**
+     * Returns all tool names currently available from connected MCP servers.
+     * Result is cached after the first call; call resetToolCache() if servers change.
+     */
+    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;
+    }
+    /**
+     * Find the first available tool whose name contains any of the given substrings.
+     * Returns null if no match is found.
+     */
+    findTool(...patterns) {
+        const tools = this.getAvailableTools();
+        for (const pattern of patterns) {
+            const found = tools.find(t => t.includes(pattern));
+            if (found)
+                return found;
+        }
+        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.';
+        }
+        // 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);
+        }
+        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) {
+    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
@@ -55,8 +117,10 @@ USER MESSAGE: ${userMessage}
 
 SUBTASKS: ${JSON.stringify(subtasks)}
 ${workerContext}
+${contextBlock}
 
-PREVIOUS FAILURE COUNT: ${this.failureCount}
+AVAILABLE TOOLS (what the Worker and Client can actually use):
+${availableToolsContext}
 
 Respond ONLY with valid JSON in this exact format (no other text):
 {
@@ -73,19 +137,14 @@ Respond ONLY with valid JSON in this exact format (no other text):
 }
 
 CRITICAL RULES for involvementLevel:
-- THOROUGH: ONLY when the user EXPLICITLY asks to test or verify something in a browser/test environment, OR after previous failures (failureCount > 0), OR for complex multi-file operations (>3 subtasks)
+- 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:
-- "testing" type with mustUseTools ["playwright__"] should ONLY be set when the user wants browser-based testing or verification of a web page/HTML/UI
-- Words like "check", "find", "verify" in the context of system administration (disk space, processes, configurations) are NOT browser testing — they are "information" type WITHOUT playwright tools
-- Examples:
-  - "check how much space my caches use" = type "information", mustUseTools null
-  - "find the biggest files in Downloads" = type "information", mustUseTools null
-  - "test the login page in the browser" = type "testing", mustUseTools ["playwright__"]
-  - "create index.html and verify it works" = type "file_creation" + type "testing" with playwright
-  - "make sure the server is running" = type "verification", mustUseTools null
+- 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 {
@@ -111,16 +170,13 @@ CRITICAL RULES for requirements:
                     default:
                         level = InvolvementLevel.STANDARD;
                 }
-                // Hard override: escalate to THOROUGH after failures
-                if (this.failureCount > 0 && level !== InvolvementLevel.THOROUGH) {
-                    logger.debug(`[Client] Escalating to THOROUGH due to ${this.failureCount} previous failures`);
-                    level = InvolvementLevel.THOROUGH;
-                }
+                // 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: req.mustUseTools || undefined,
+                    mustUseTools: normalizeMustUseTools(req.mustUseTools),
                 }));
                 // Ensure at least one requirement
                 if (requirements.length === 0) {
@@ -134,118 +190,23 @@ CRITICAL RULES for requirements:
         catch (error) {
             logger.warn(`[Client] LLM task analysis failed: ${error}, falling back to STANDARD`);
         }
-        // Fallback: STANDARD with generic requirement
+        // Fallback: STANDARD with generic requirement (no failureCount escalation)
         return {
-            level: this.failureCount > 0 ? InvolvementLevel.THOROUGH : InvolvementLevel.STANDARD,
+            level: InvolvementLevel.STANDARD,
             requirements: [{ type: 'other', description: 'General task completion' }],
         };
     }
-    /**
-     * @deprecated Use analyzeTaskRequirements() instead. Kept for reference.
-     * Determine involvement level based on user request complexity
-     */
-    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;
-    }
-    /**
-     * @deprecated Use analyzeTaskRequirements() instead. Kept for reference.
-     * Parse requirements from user message
-     */
-    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,
-                    });
-                }
-            });
-        }
-        // 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__'],
-            });
-        }
-        // 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'],
-            });
-        }
-        // 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
-            });
-        }
-        // Default: at least verify Worker did some work
-        if (requirements.length === 0) {
-            requirements.push({
-                type: 'other',
-                description: 'General task completion',
-            });
-        }
-        return requirements;
-    }
+    // ─── Main Validation Entry Point ──────────────────────────────────────────
     /**
      * Validate Worker's work at appropriate involvement level
      */
-    async validate(userMessage, subtasks, workerResult, involvementLevel) {
+    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);
+        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}`);
@@ -272,7 +233,7 @@ CRITICAL RULES for requirements:
         }
         // 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);
+        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`);
@@ -305,12 +266,14 @@ CRITICAL RULES for requirements:
         result.approved = result.requirementsMet;
         if (!result.approved && result.issues.length > 0) {
             // Generate an actionable correction instruction via LLM instead of echoing raw validation issues
-            result.nextAction = await this.generateCorrectionInstruction(userMessage, subtasks.join('; '), result.issues, workerResult);
-            this.failureCount++;
+            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;
@@ -319,12 +282,14 @@ CRITICAL RULES for requirements:
      * 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}
@@ -380,7 +345,7 @@ Respond ONLY with the JSON, no other text.`;
      * 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) {
+    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) {
@@ -388,9 +353,12 @@ Respond ONLY with the JSON, no other text.`;
         }
         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)}
@@ -399,13 +367,16 @@ 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:
-- filesystem__list_directory / filesystem__directory_tree / filesystem__search_files = only shows file/folder NAMES and structure, does NOT read file contents
-- filesystem__read_text_file / filesystem__read_file = actually reads file content
-- mcp-shell-server__shell_exec = runs a shell command (check what command was likely run based on context)
-- playwright__* = browser automation tools
+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
@@ -452,7 +423,10 @@ Respond ONLY with valid JSON:
         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) {
+        // Exception: if the Worker has structured failedTools, it DID try — the
+        // tools simply errored. Raising a "no tools used" issue on top of real
+        // failures creates a misleading retry loop rather than an honest exit.
+        if (workerResult.toolsUsed.length === 0 && workerResult.failedTools.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. ' +
@@ -471,8 +445,12 @@ Respond ONLY with valid JSON:
                 }
             }
         }
-        // Check if Worker succeeded
-        if (!workerResult.success) {
+        // Check if Worker succeeded.
+        // If failedTools is non-empty the Worker already proved it tried — the failure
+        // is evidence-backed. Raising a generic "retry with appropriate tool usage"
+        // issue would just queue another pointless attempt. Let it through; synthesis
+        // will report the specific failures to the user.
+        if (!workerResult.success && workerResult.failedTools.length === 0) {
             issues.push('Worker did not complete the task successfully. The task needs to be retried with appropriate tool usage.');
         }
         return { issues };
@@ -503,46 +481,52 @@ Respond ONLY with valid JSON:
                 }
             }
         }
-        // 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) {
-        try {
-            await this.mcpClient.executeTool('filesystem__read_text_file', {
-                path: filePath,
-                head: 1,
-            });
-            return true;
+        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;
+            }
         }
-        catch (error) {
-            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.
-     * Instead of echoing "requires using playwright__ but Worker did not use these tools",
-     * produces something like "Use the filesystem tools to list ~/Library/Caches and report sizes".
+     * 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) {
+    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}
@@ -555,10 +539,13 @@ ${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 (e.g., "Use the run_process tool to execute 'du -sh ~/Library/Caches' and report the output")
-- Reference specific tools or actions the Worker should take
+- 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
@@ -584,76 +571,202 @@ Respond ONLY with the correction instruction text, nothing else.`;
         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 };
+        }
+        // Data-driven short-circuit: if the Worker reported structured tool failures,
+        // we know exactly what happened — no LLM inference needed.
+        // suggestedStrategy is 'escalate' because rephrasing the instruction cannot
+        // fix a tool that is fundamentally erroring (wrong path, permissions, etc.).
+        if (workerResult.failedTools.length > 0) {
+            const failureSummary = workerResult.failedTools
+                .map(f => `${f.toolName} (${f.attempts} attempt${f.attempts !== 1 ? 's' : ''}) — ${f.lastError}`)
+                .join('; ');
+            logger.info(`[Client] Data-driven CompletionSignal: tool_failure — ${failureSummary}`);
+            return {
+                confidence: 'none',
+                progressMade: false,
+                blockerType: 'tool_failure',
+                suggestedStrategy: 'escalate',
+            };
+        }
+        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