tachibot-mcp 2.0.2

package/dist/src/modes/shared/helpers/scout-helpers.js

@@ -0,0 +1,270 @@
+/**
+ * Scout Helper Functions
+ *
+ * Pure, composable functions extracted from Scout mode.
+ * Used by workflows/system/scout.yaml
+ *
+ * SOLID Principles:
+ * - Single Responsibility: Each function does ONE transformation
+ * - Open/Closed: Functions are closed for modification, open for extension
+ * - Liskov Substitution: All functions are predictable pure functions
+ * - Interface Segregation: Small, focused function signatures
+ * - Dependency Inversion: Functions depend on types, not concrete implementations
+ */
+// ============================================================================
+// Query Preparation
+// ============================================================================
+/**
+ * Prepend current date to query for temporal context
+ *
+ * @example
+ * prepareQuery("What's new in React?", "October 21, 2025")
+ * // => "[Current date: October 21, 2025] What's new in React?"
+ */
+export const prepareQuery = (query, date) => {
+    return `[Current date: ${date}] ${query}`;
+};
+/**
+ * Craft targeted probe based on query type detection
+ *
+ * Identifies question type (latest, technical, comparison) and
+ * reformulates query for better search results.
+ */
+export const craftTargetedProbe = (query) => {
+    const keywords = extractKeywords(query);
+    const questionType = identifyQuestionType(query);
+    switch (questionType) {
+        case 'latest':
+            return `Latest information about ${keywords.join(' ')} as of 2025`;
+        case 'technical':
+            return `Technical documentation and API details for ${keywords.join(' ')}`;
+        case 'comparison':
+            return `Compare ${keywords.join(' vs ')} with current data`;
+        default:
+            return query;
+    }
+};
+// ============================================================================
+// Fact Extraction & Validation
+// ============================================================================
+/**
+ * Extract structured facts from search result text
+ *
+ * Returns array of fact strings (lines > 20 chars, max 5 facts)
+ */
+export const extractFacts = (searchResult) => {
+    const lines = searchResult.split('\n');
+    const facts = lines
+        .filter(line => line.trim().length > 20)
+        .slice(0, 5)
+        .map(line => line.trim());
+    const sources = extractSources(searchResult);
+    const reliability = assessReliability(searchResult);
+    return {
+        facts,
+        sources,
+        timestamp: new Date().toISOString(),
+        reliability
+    };
+};
+/**
+ * Validate fact quality and reliability
+ *
+ * Returns true if facts are sufficient for analysis
+ */
+export const validateFacts = (facts) => {
+    return facts.facts.length > 0 && facts.reliability > 0.5;
+};
+/**
+ * Select best facts from quick scan or deep search
+ */
+export const selectBestFacts = (quickFacts, deepFacts, valid) => {
+    if (valid && quickFacts) {
+        return quickFacts;
+    }
+    return deepFacts;
+};
+/**
+ * Verify fact reliability
+ */
+export const verifyFacts = (facts) => {
+    return {
+        verified: true,
+        confidence: facts.reliability
+    };
+};
+// ============================================================================
+// Context Building
+// ============================================================================
+/**
+ * Build context string from facts for model analysis
+ */
+export const buildContext = (facts, timestamp) => {
+    const ts = timestamp || facts.timestamp;
+    const sourceList = facts.sources?.join(', ') || 'Not specified';
+    return `Context (${ts}):\n${facts.facts.join('\n')}\n\nSources: ${sourceList}`;
+};
+// ============================================================================
+// Insight Extraction
+// ============================================================================
+/**
+ * Extract key insights from model analyses
+ *
+ * Returns array of AnalysisResult with extracted insights
+ */
+export const extractInsights = (analyses) => {
+    return analyses.map(({ model, content }) => ({
+        model,
+        analysis: content,
+        insights: extractInsightsFromText(content)
+    }));
+};
+/**
+ * Extract insight bullet points from text
+ */
+const extractInsightsFromText = (text) => {
+    const lines = text.split('\n');
+    return lines
+        .filter(line => line.includes('insight') ||
+        line.includes('Key') ||
+        line.startsWith('•') ||
+        line.startsWith('-'))
+        .map(line => line.replace(/^[•\-]\s*/, '').trim())
+        .filter(line => line.length > 10)
+        .slice(0, 3);
+};
+// ============================================================================
+// Synthesis
+// ============================================================================
+/**
+ * Synthesize facts and analyses into readable report
+ */
+export const synthesizeScoutReport = (facts, insights) => {
+    let synthesis = '';
+    // Add facts section
+    if (facts && facts.facts.length > 0) {
+        synthesis += `Current Information (${facts.timestamp}):\n`;
+        facts.facts.slice(0, 3).forEach(fact => {
+            synthesis += `• ${fact}\n`;
+        });
+        synthesis += '\n';
+    }
+    // Add analysis section
+    synthesis += 'Analysis:\n';
+    insights.forEach(analysis => {
+        synthesis += `${analysis.model}:\n`;
+        analysis.insights.slice(0, 2).forEach(insight => {
+            synthesis += `• ${insight}\n`;
+        });
+    });
+    return synthesis;
+};
+/**
+ * Synthesize waterfall verification results
+ */
+export const synthesizeScoutWaterfall = (facts, verification) => {
+    return `Verified Information:\n${facts.facts.join('\n')}\n\nReliability: ${facts.reliability}`;
+};
+// ============================================================================
+// Report Formatting
+// ============================================================================
+/**
+ * Format final Scout report with metadata
+ */
+export const formatScoutReport = (config) => {
+    return {
+        synthesis: config.synthesis,
+        facts: config.facts || undefined,
+        analyses_count: config.analyses_count,
+        execution_time: config.execution_time,
+        warning: config.warning || undefined,
+        verification: config.verification
+    };
+};
+// ============================================================================
+// Internal Utilities (not exported, used by public functions)
+// ============================================================================
+/**
+ * Extract keywords from query (remove stop words)
+ */
+const extractKeywords = (query) => {
+    const words = query.toLowerCase().split(/\s+/);
+    const stopWords = ['what', 'how', 'why', 'when', 'where', 'is', 'are', 'the', 'a', 'an'];
+    return words.filter(w => !stopWords.includes(w) && w.length > 2);
+};
+/**
+ * Identify question type from query text
+ */
+const identifyQuestionType = (query) => {
+    const lower = query.toLowerCase();
+    if (lower.includes('latest') || lower.includes('current') || lower.includes('new')) {
+        return 'latest';
+    }
+    if (lower.includes('api') || lower.includes('function') || lower.includes('method')) {
+        return 'technical';
+    }
+    if (lower.includes('vs') || lower.includes('compare') || lower.includes('difference')) {
+        return 'comparison';
+    }
+    return 'general';
+};
+/**
+ * Extract source citations from text
+ */
+const extractSources = (text) => {
+    const sourcePattern = /\[(\d+)\]\s*([^\n]+)/g;
+    const sources = [];
+    let match;
+    while ((match = sourcePattern.exec(text)) !== null) {
+        sources.push(match[2]);
+    }
+    return sources;
+};
+/**
+ * Assess reliability score based on content indicators
+ *
+ * Scoring:
+ * - Base: 0.5
+ * - Has sources/citations: +0.2
+ * - Has recent dates (2024/2025): +0.1
+ * - Has verification keywords: +0.1
+ * - Lengthy content (> 500 chars): +0.1
+ * - Max: 1.0
+ */
+const assessReliability = (text) => {
+    let score = 0.5;
+    if (text.includes('source') || text.includes('['))
+        score += 0.2;
+    if (text.includes('2025') || text.includes('2024'))
+        score += 0.1;
+    if (text.includes('verified') || text.includes('confirmed'))
+        score += 0.1;
+    if (text.length > 500)
+        score += 0.1;
+    return Math.min(score, 1.0);
+};
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Check if value is a valid FactResult
+ */
+export const isFactResult = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const obj = value;
+    return (Array.isArray(obj.facts) &&
+        typeof obj.timestamp === 'string' &&
+        typeof obj.reliability === 'number');
+};
+/**
+ * Check if value is a valid AnalysisResult
+ */
+export const isAnalysisResult = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const obj = value;
+    return (typeof obj.model === 'string' &&
+        typeof obj.analysis === 'string' &&
+        Array.isArray(obj.insights));
+};

package/dist/src/modes/shared/helpers/verifier-helpers.js

@@ -0,0 +1,332 @@
+/**
+ * Verifier Helper Functions
+ *
+ * Pure, composable functions for multi-model verification and consensus analysis.
+ * Used by workflows/system/verifier.yaml
+ *
+ * SOLID Principles:
+ * - Single Responsibility: Each function does ONE transformation
+ * - Open/Closed: Functions are closed for modification, open for extension
+ * - Liskov Substitution: All functions are predictable pure functions
+ * - Interface Segregation: Small, focused function signatures
+ * - Dependency Inversion: Functions depend on types, not concrete implementations
+ */
+// ============================================================================
+// Prompt Building
+// ============================================================================
+/**
+ * Build verification prompt with optional source requirements
+ */
+export const buildPrompt = (config) => {
+    const basePrompt = `Analyze the following query/statement critically and provide your assessment.
+
+Query: ${config.query}
+
+Please provide:
+1. Your conclusion (true/false/uncertain/needs-context)
+2. Key reasoning points
+3. Confidence level (0-100%)`;
+    if (config.include_sources) {
+        return basePrompt + `
+4. Supporting evidence or sources
+5. Any contradicting information found`;
+    }
+    return basePrompt;
+};
+// ============================================================================
+// Response Extraction
+// ============================================================================
+/**
+ * Extract structured data from raw model responses
+ */
+export const extractModelResponses = (config) => {
+    return config.raw_responses.map((response, index) => ({
+        model: config.models[index] || response.model,
+        response: response.content,
+        conclusion: extractConclusion(response.content),
+        evidence: config.include_sources ? extractEvidence(response.content) : undefined,
+        confidence: extractConfidence(response.content),
+        tokens: estimateTokens(response.content)
+    }));
+};
+/**
+ * Extract conclusion from response text
+ *
+ * Patterns checked (in order):
+ * 1. "conclusion: ..." / "answer: ..." / "verdict: ..." / "result: ..."
+ * 2. Keywords: "true", "false", "uncertain"
+ * 3. Default: "unknown"
+ */
+export const extractConclusion = (content) => {
+    const patterns = [
+        /conclusion:\s*([^\n]+)/i,
+        /answer:\s*([^\n]+)/i,
+        /verdict:\s*([^\n]+)/i,
+        /result:\s*([^\n]+)/i
+    ];
+    for (const pattern of patterns) {
+        const match = content.match(pattern);
+        if (match) {
+            return match[1].trim().toLowerCase();
+        }
+    }
+    // Fallback keyword detection
+    const lower = content.toLowerCase();
+    if (lower.includes('true'))
+        return 'true';
+    if (lower.includes('false'))
+        return 'false';
+    if (lower.includes('uncertain'))
+        return 'uncertain';
+    return 'unknown';
+};
+/**
+ * Extract evidence/sources from response text
+ */
+export const extractEvidence = (content) => {
+    const evidence = [];
+    const patterns = [
+        /evidence:\s*([^\n]+)/gi,
+        /source:\s*([^\n]+)/gi,
+        /citation:\s*([^\n]+)/gi,
+        /\[(\d+)\]\s*([^\n]+)/g
+    ];
+    for (const pattern of patterns) {
+        const matches = content.matchAll(pattern);
+        for (const match of matches) {
+            evidence.push(match[1] || match[2]);
+        }
+    }
+    return evidence;
+};
+/**
+ * Extract confidence score from response text
+ *
+ * Patterns checked:
+ * - "confidence: 80%" / "certainty: 80%"
+ * - "80% confident"
+ * - Default: 0.5 (50%)
+ */
+export const extractConfidence = (content) => {
+    const patterns = [
+        /confidence:\s*(\d+)%?/i,
+        /certainty:\s*(\d+)%?/i,
+        /(\d+)%\s*confident/i
+    ];
+    for (const pattern of patterns) {
+        const match = content.match(pattern);
+        if (match) {
+            return parseInt(match[1]) / 100;
+        }
+    }
+    return 0.5; // Default 50% confidence
+};
+// ============================================================================
+// Consensus Analysis
+// ============================================================================
+/**
+ * Calculate consensus by clustering responses by conclusion
+ *
+ * Returns:
+ * - agreement: ratio of models in majority cluster
+ * - clusters: Map of conclusion → responses
+ * - majorityCluster: conclusion with most models
+ * - outlierModels: models not in majority cluster
+ */
+export const calculateConsensus = (config) => {
+    const clusters = new Map();
+    // Cluster responses by conclusion
+    for (const response of config.responses) {
+        const conclusion = response.conclusion || 'unknown';
+        if (!clusters.has(conclusion)) {
+            clusters.set(conclusion, []);
+        }
+        clusters.get(conclusion).push(response);
+    }
+    // Find majority cluster
+    const sortedClusters = Array.from(clusters.entries())
+        .sort((a, b) => b[1].length - a[1].length);
+    const majorityCluster = sortedClusters[0][0];
+    const majorityCount = sortedClusters[0][1].length;
+    const agreement = majorityCount / config.responses.length;
+    // Identify outliers (models not in majority cluster)
+    const outlierModels = sortedClusters
+        .slice(1)
+        .flatMap(([_, responses]) => responses.map(r => r.model));
+    return {
+        agreement,
+        clusters: new Map(clusters), // Convert to readonly
+        majorityCluster,
+        outlierModels
+    };
+};
+/**
+ * Find outlier responses (dissenting views)
+ */
+export const findOutliers = (config) => {
+    return config.responses.filter(r => config.consensus.outlierModels.includes(r.model));
+};
+/**
+ * Calculate overall confidence score
+ *
+ * Weighted formula:
+ * - 50% weight: consensus agreement
+ * - 30% weight: average model confidence
+ * - 20% weight: number of responses (more models = higher confidence)
+ */
+export const calculateConfidence = (config) => {
+    const agreementScore = config.consensus.agreement;
+    const avgModelConfidence = config.responses
+        .map(r => r.confidence || 0.5)
+        .reduce((a, b) => a + b, 0) / config.responses.length;
+    const responseCount = config.responses.length;
+    const responseScore = Math.min(responseCount / 5, 1); // Max at 5 models
+    return (agreementScore * 0.5 + avgModelConfidence * 0.3 + responseScore * 0.2);
+};
+// ============================================================================
+// Synthesis
+// ============================================================================
+/**
+ * Generate beautiful verification report with table
+ */
+export const synthesizeVerifierReport = (config) => {
+    const majorityResponses = config.consensus.clusters.get(config.consensus.majorityCluster) || [];
+    const outlierCount = config.responses.length - majorityResponses.length;
+    const consensusPercent = (config.consensus.agreement * 100).toFixed(1);
+    let synthesis = `## 🔍 Multi-Model Verification Report\n\n`;
+    // Consensus indicator
+    synthesis += `### 📊 Consensus: ${consensusPercent}%\n\n`;
+    const consensusBar = Math.round(config.consensus.agreement * 10);
+    synthesis += `\`\`\`\n`;
+    synthesis += `[${'█'.repeat(consensusBar)}${'░'.repeat(10 - consensusBar)}] ${consensusPercent}% agreement\n`;
+    synthesis += `\`\`\`\n\n`;
+    // Model responses table
+    synthesis += `### 🤖 Model Responses\n\n`;
+    synthesis += buildResponseTable(config.responses, majorityResponses);
+    // Majority analysis
+    synthesis += `### 🎯 Majority View\n\n`;
+    synthesis += `**Conclusion:** ${config.consensus.majorityCluster}\n`;
+    synthesis += `**Models in agreement:** ${majorityResponses.length}/${config.responses.length}\n\n`;
+    if (majorityResponses.length > 0) {
+        synthesis += `**Key reasoning points:**\n`;
+        const points = extractKeyPoints(majorityResponses);
+        if (points.length > 0) {
+            points.forEach(point => synthesis += `- ${point}\n`);
+        }
+        else {
+            // Fallback: show first sentence from each response
+            majorityResponses.slice(0, 3).forEach(resp => {
+                const firstSentence = resp.response.split(/[.!?]/)[0];
+                if (firstSentence && firstSentence.length > 10) {
+                    synthesis += `- ${firstSentence.trim()}.\n`;
+                }
+            });
+        }
+        synthesis += `\n`;
+    }
+    // Dissenting views
+    if (outlierCount > 0) {
+        synthesis += `### ⚠️ Dissenting Views (${outlierCount})\n\n`;
+        config.outliers.forEach(outlier => {
+            synthesis += `**${outlier.model}:** "${outlier.conclusion || 'unknown'}"\n`;
+            const preview = (outlier.response || '').substring(0, 150).replace(/\n/g, ' ');
+            if (preview) {
+                synthesis += `> ${preview}${outlier.response.length > 150 ? '...' : ''}\n\n`;
+            }
+        });
+    }
+    // Summary
+    synthesis += `### 📋 Summary\n\n`;
+    synthesis += `\`\`\`\n`;
+    synthesis += `Total Models:     ${config.responses.length}\n`;
+    synthesis += `Consensus:        ${consensusPercent}%\n`;
+    synthesis += `Majority View:    ${config.consensus.majorityCluster}\n`;
+    synthesis += `Agreeing Models:  ${majorityResponses.length}\n`;
+    synthesis += `Dissenting:       ${outlierCount}\n`;
+    synthesis += `High Confidence:  ${config.consensus.agreement >= 0.8 ? 'YES ✓' : 'NO'}\n`;
+    synthesis += `\`\`\`\n`;
+    return synthesis;
+};
+/**
+ * Format final verification result
+ */
+export const formatVerifierResult = (config) => {
+    return {
+        consensus: config.consensus,
+        majority: config.majority,
+        outliers: config.outliers,
+        responses: config.responses,
+        synthesis: config.synthesis,
+        confidence: config.confidence,
+        shouldTerminate: config.should_terminate
+    };
+};
+// ============================================================================
+// Internal Utilities
+// ============================================================================
+/**
+ * Build response table with status icons
+ */
+const buildResponseTable = (responses, majorityResponses) => {
+    // Simple table format (without TableBuilder dependency)
+    let table = '| Status | Model | Conclusion | Confidence | Preview |\n';
+    table += '|:------:|:------|:----------:|-----------:|:--------|\n';
+    responses.forEach((resp) => {
+        const isMajority = majorityResponses.includes(resp);
+        const statusIcon = isMajority ? '✅' : '⚠️';
+        const conclusionIcon = resp.conclusion === 'true' ? '✓' :
+            resp.conclusion === 'false' ? '✗' :
+                resp.conclusion === 'uncertain' ? '❓' : '❔';
+        const confidence = resp.confidence ? `${Math.round(resp.confidence * 100)}%` : 'N/A';
+        const preview = (resp.response || '').substring(0, 60).replace(/\n/g, ' ').trim();
+        const previewText = preview ? `${preview}...` : 'No response';
+        table += `| ${statusIcon} | ${resp.model} | ${conclusionIcon} ${resp.conclusion || 'unknown'} | ${confidence} | ${previewText} |\n`;
+    });
+    table += '\n';
+    return table;
+};
+/**
+ * Extract key reasoning points from responses
+ */
+const extractKeyPoints = (responses) => {
+    const points = new Set();
+    for (const response of responses) {
+        const content = response.response || '';
+        const lines = content.split('\n')
+            .filter((line) => line.trim().startsWith('-') || line.trim().startsWith('•'))
+            .map((line) => line.replace(/^[-•]\s*/, '').trim())
+            .filter((line) => line.length > 10 && line.length < 200);
+        lines.forEach((line) => points.add(line));
+    }
+    return Array.from(points).slice(0, 5);
+};
+/**
+ * Estimate tokens from text length
+ */
+const estimateTokens = (text) => {
+    return Math.floor(text.length / 4);
+};
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Check if value is a valid ModelResponse
+ */
+export const isModelResponse = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const obj = value;
+    return (typeof obj.model === 'string' &&
+        typeof obj.response === 'string');
+};
+/**
+ * Check if value is a valid ConsensusAnalysis
+ */
+export const isConsensusAnalysis = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const obj = value;
+    return (typeof obj.agreement === 'number' &&
+        typeof obj.majorityCluster === 'string' &&
+        Array.isArray(obj.outlierModels));
+};