@dotsetlabs/bellwether 0.10.0

package/dist/docs/agents.js

@@ -0,0 +1,995 @@
+import { formatDateISO, formatDuration, escapeTableCell, mermaidLabel, validateJsonForCodeBlock } from '../utils/index.js';
+import { DISPLAY_LIMITS, MATH_FACTORS } from '../constants.js';
+import { calculatePerformanceMetrics, extractParameters, looksLikeError } from './shared.js';
+/**
+ * Detect configuration issues based on error patterns.
+ * Returns a warning message if issues detected, null otherwise.
+ */
+function detectConfigurationIssues(profiles, metadata) {
+    if (metadata.toolCallCount === 0)
+        return null;
+    const errorRate = metadata.errorCount / metadata.toolCallCount;
+    if (errorRate < 0.7)
+        return null; // Less than 70% errors is probably fine
+    // Look for access-related errors in interactions
+    let accessErrors = 0;
+    let totalErrors = 0;
+    for (const profile of profiles) {
+        for (const interaction of profile.interactions) {
+            // Get response text content
+            const textContent = interaction.response?.content?.find(c => c.type === 'text');
+            const responseText = textContent && 'text' in textContent ? String(textContent.text) : '';
+            const errorText = interaction.error || '';
+            const combined = errorText + responseText;
+            // Count as error if flagged as error OR if content looks like an error
+            const isError = interaction.error || interaction.response?.isError || looksLikeError(responseText);
+            if (isError) {
+                totalErrors++;
+                if (/access denied|outside.*(allowed|predefined)|not allowed|permission denied|cannot.*(access|read|write|create|list).*outside|restricted to.*(predefined|allowed)/i.test(combined)) {
+                    accessErrors++;
+                }
+            }
+        }
+    }
+    // If we found access-related errors, show warning
+    if (totalErrors > 0 && accessErrors / totalErrors > 0.5) {
+        return 'Most tool calls failed with access-related errors. The server may not have been configured with allowed directories. ' +
+            'For filesystem servers, try: `bellwether check npx @modelcontextprotocol/server-filesystem /path/to/allowed/dir`';
+    }
+    // Also check synthesized limitations for access patterns (fallback)
+    let accessRelatedLimitations = 0;
+    let totalLimitations = 0;
+    for (const profile of profiles) {
+        for (const limitation of profile.limitations) {
+            totalLimitations++;
+            if (/outside.*(allowed|predefined)|restricted|access.*(denied|control)|cannot.*(access|read|write)/i.test(limitation)) {
+                accessRelatedLimitations++;
+            }
+        }
+    }
+    // If most tools have access-related limitations and high error rate, show warning
+    if (totalLimitations > 0 && accessRelatedLimitations / totalLimitations > 0.5 && errorRate > 0.8) {
+        return 'Most tool calls failed, likely due to missing allowed directories configuration. ' +
+            'For filesystem servers, try: `bellwether check npx @modelcontextprotocol/server-filesystem /path/to/allowed/dir`';
+    }
+    return null;
+}
+export function generateAgentsMd(result) {
+    const lines = [];
+    const { discovery, toolProfiles, summary, limitations, recommendations, metadata } = result;
+    // Header
+    lines.push(`# ${discovery.serverInfo.name}`);
+    lines.push('');
+    lines.push(`> Generated by [Bellwether](https://github.com/dotsetlabs/bellwether) on ${formatDateISO(metadata.startTime)}`);
+    lines.push('');
+    // Check for configuration issues (high error rate with access-related errors)
+    const configWarning = detectConfigurationIssues(toolProfiles, metadata);
+    if (configWarning) {
+        lines.push('> ⚠️ **Configuration Issue Detected**');
+        lines.push('>');
+        lines.push(`> ${configWarning}`);
+        lines.push('');
+    }
+    // Overview
+    lines.push('## Overview');
+    lines.push('');
+    lines.push(summary);
+    lines.push('');
+    lines.push(`**Server Version:** ${discovery.serverInfo.version}`);
+    lines.push(`**Protocol Version:** ${discovery.protocolVersion}`);
+    // Show personas used
+    if (metadata.personas && metadata.personas.length > 0) {
+        const personaNames = metadata.personas.map(p => p.name).join(', ');
+        lines.push(`**Interview Personas:** ${personaNames}`);
+    }
+    lines.push('');
+    // Capabilities summary
+    lines.push('## Capabilities');
+    lines.push('');
+    if (discovery.capabilities.tools) {
+        lines.push(`- **Tools:** ${discovery.tools.length} available`);
+    }
+    if (discovery.capabilities.prompts) {
+        lines.push(`- **Prompts:** ${discovery.prompts.length} available`);
+    }
+    if (discovery.capabilities.resources) {
+        lines.push(`- **Resources:** ${(discovery.resources ?? []).length} available`);
+    }
+    if (discovery.capabilities.logging) {
+        lines.push('- **Logging:** Supported');
+    }
+    lines.push('');
+    // Extract common constraints across all tools
+    const { common: commonConstraints, byTool: toolSpecificConstraints } = extractCommonConstraints(toolProfiles);
+    // Quick Reference section
+    if (toolProfiles.length > 0) {
+        lines.push(...generateQuickReference(discovery.tools, toolProfiles));
+    }
+    // Global Constraints section (common restrictions)
+    if (commonConstraints.length > 0) {
+        lines.push(...generateGlobalConstraintsSection(commonConstraints));
+    }
+    // Security Considerations section (aggregated)
+    const securitySection = generateSecuritySection(toolProfiles);
+    if (securitySection.length > 0) {
+        lines.push(...securitySection);
+    }
+    // Performance section
+    const performanceSection = generatePerformanceSection(toolProfiles);
+    if (performanceSection.length > 0) {
+        lines.push(...performanceSection);
+    }
+    // Tools section
+    if (toolProfiles.length > 0) {
+        lines.push('## Tools');
+        lines.push('');
+        for (const profile of toolProfiles) {
+            lines.push(`### ${profile.name}`);
+            lines.push('');
+            lines.push(profile.description);
+            lines.push('');
+            // Find the original tool to get schema
+            const tool = discovery.tools.find(t => t.name === profile.name);
+            if (tool?.inputSchema) {
+                lines.push('**Input Schema:**');
+                // Validate JSON and escape for code block
+                const schemaJson = validateJsonForCodeBlock(tool.inputSchema);
+                lines.push('```json');
+                lines.push(schemaJson.content);
+                lines.push('```');
+                lines.push('');
+            }
+            // Add sample response if we have successful calls
+            const sampleResponse = generateSampleResponse(profile);
+            if (sampleResponse.length > 0) {
+                lines.push(...sampleResponse);
+            }
+            if (profile.behavioralNotes.length > 0) {
+                lines.push('**Observed Behavior:**');
+                for (const note of profile.behavioralNotes) {
+                    lines.push(`- ${note}`);
+                }
+                lines.push('');
+            }
+            // Only show tool-specific limitations (common ones are in Global Constraints)
+            const specificLimitations = toolSpecificConstraints.get(profile.name) ?? [];
+            if (specificLimitations.length > 0) {
+                lines.push('**Limitations:**');
+                for (const limitation of specificLimitations) {
+                    lines.push(`- ${limitation}`);
+                }
+                lines.push('');
+            }
+            if (profile.securityNotes.length > 0) {
+                lines.push('**Security Considerations:**');
+                for (const note of profile.securityNotes) {
+                    lines.push(`- ${note}`);
+                }
+                lines.push('');
+            }
+            // Findings by persona (if multiple personas used)
+            if (profile.findingsByPersona && profile.findingsByPersona.length > 1) {
+                lines.push('<details>');
+                lines.push('<summary><strong>Findings by Persona</strong></summary>');
+                lines.push('');
+                for (const personaFindings of profile.findingsByPersona) {
+                    lines.push(`#### ${personaFindings.personaName}`);
+                    lines.push('');
+                    if (personaFindings.behavioralNotes.length > 0) {
+                        for (const note of personaFindings.behavioralNotes) {
+                            lines.push(`- ${note}`);
+                        }
+                    }
+                    if (personaFindings.limitations.length > 0) {
+                        lines.push('');
+                        lines.push('*Limitations:*');
+                        for (const limitation of personaFindings.limitations) {
+                            lines.push(`- ${limitation}`);
+                        }
+                    }
+                    if (personaFindings.securityNotes.length > 0) {
+                        lines.push('');
+                        lines.push('*Security:*');
+                        for (const note of personaFindings.securityNotes) {
+                            lines.push(`- ${note}`);
+                        }
+                    }
+                    lines.push('');
+                }
+                lines.push('</details>');
+                lines.push('');
+            }
+        }
+    }
+    // Common Workflows section (summarized view of successful workflows)
+    if (result.workflowResults && result.workflowResults.length > 0) {
+        const successfulWorkflows = result.workflowResults.filter(wr => wr.success);
+        if (successfulWorkflows.length > 0) {
+            lines.push('## Common Workflows');
+            lines.push('');
+            lines.push('These workflows demonstrate recommended patterns for using tools together:');
+            lines.push('');
+            for (const wr of successfulWorkflows) {
+                const toolSequence = wr.workflow.steps.map(s => `\`${s.tool}\``).join(' → ');
+                lines.push(`### ${wr.workflow.name}`);
+                lines.push('');
+                lines.push(wr.workflow.description);
+                lines.push('');
+                lines.push(`**Tool Sequence:** ${toolSequence}`);
+                lines.push('');
+                // Generate mermaid workflow diagram
+                lines.push('```mermaid');
+                lines.push('flowchart LR');
+                for (let i = 0; i < wr.workflow.steps.length; i++) {
+                    const step = wr.workflow.steps[i];
+                    const nodeId = `S${i}`;
+                    const nextNodeId = `S${i + 1}`;
+                    // Use mermaidLabel to safely escape tool names
+                    if (i === 0) {
+                        lines.push(`    ${nodeId}[${mermaidLabel(step.tool)}]`);
+                    }
+                    if (i < wr.workflow.steps.length - 1) {
+                        const nextStep = wr.workflow.steps[i + 1];
+                        lines.push(`    ${nodeId} --> ${nextNodeId}[${mermaidLabel(nextStep.tool)}]`);
+                    }
+                }
+                lines.push('```');
+                lines.push('');
+            }
+        }
+    }
+    // Detailed Workflows section (with full test results)
+    if (result.workflowResults && result.workflowResults.length > 0) {
+        lines.push('## Workflow Test Results');
+        lines.push('');
+        lines.push('The following workflows were tested to verify tool chaining behavior:');
+        lines.push('');
+        for (const workflowResult of result.workflowResults) {
+            const statusIcon = workflowResult.success ? '✅' : '❌';
+            lines.push(`### ${statusIcon} ${workflowResult.workflow.name}`);
+            lines.push('');
+            lines.push(workflowResult.workflow.description);
+            lines.push('');
+            if (workflowResult.summary) {
+                lines.push(`> ${workflowResult.summary}`);
+                lines.push('');
+            }
+            // Show steps
+            lines.push('**Steps:**');
+            lines.push('');
+            for (let i = 0; i < workflowResult.steps.length; i++) {
+                const stepResult = workflowResult.steps[i];
+                const stepIcon = stepResult.success ? '✓' : '✗';
+                lines.push(`${i + 1}. ${stepIcon} **${stepResult.step.tool}**: ${stepResult.step.description}`);
+                if (stepResult.analysis) {
+                    lines.push(`   - ${stepResult.analysis}`);
+                }
+                if (stepResult.error) {
+                    lines.push(`   - ⚠️ Error: ${stepResult.error}`);
+                }
+            }
+            lines.push('');
+            // Show data flow diagram if present
+            if (workflowResult.dataFlow && workflowResult.dataFlow.length > 0) {
+                lines.push('**Data Flow:**');
+                lines.push('');
+                lines.push('```mermaid');
+                lines.push('flowchart LR');
+                // Add nodes first - escape tool names for Mermaid
+                for (let i = 0; i < workflowResult.steps.length; i++) {
+                    const stepResult = workflowResult.steps[i];
+                    const status = stepResult.success ? ':::success' : ':::failure';
+                    lines.push(`    Step${i}[${mermaidLabel(stepResult.step.tool)}]${status}`);
+                }
+                // Add edges - escape parameter names
+                for (const edge of workflowResult.dataFlow) {
+                    const param = mermaidLabel(edge.targetParam).replace(/"/g, '');
+                    lines.push(`    Step${edge.fromStep} -->|${param}| Step${edge.toStep}`);
+                }
+                // Add styling
+                lines.push('    classDef success fill:#90EE90');
+                lines.push('    classDef failure fill:#FFB6C1');
+                lines.push('```');
+                lines.push('');
+            }
+        }
+    }
+    // Prompts section - use profiles if available, otherwise basic listing
+    if (result.promptProfiles && result.promptProfiles.length > 0) {
+        lines.push('## Prompts');
+        lines.push('');
+        lines.push('Prompts are reusable templates that generate structured messages for LLM interactions.');
+        lines.push('');
+        for (const profile of result.promptProfiles) {
+            lines.push(`### ${profile.name}`);
+            lines.push('');
+            lines.push(profile.description);
+            lines.push('');
+            if (profile.arguments.length > 0) {
+                lines.push('**Arguments:**');
+                for (const arg of profile.arguments) {
+                    const required = arg.required ? ' (required)' : '';
+                    lines.push(`- \`${arg.name}\`${required}: ${arg.description ?? 'No description'}`);
+                }
+                lines.push('');
+            }
+            if (profile.exampleOutput) {
+                lines.push('**Example Output:**');
+                lines.push('```');
+                lines.push(profile.exampleOutput.length > DISPLAY_LIMITS.DOCS_EXAMPLE_LENGTH
+                    ? profile.exampleOutput.substring(0, DISPLAY_LIMITS.DOCS_EXAMPLE_LENGTH) + '...'
+                    : profile.exampleOutput);
+                lines.push('```');
+                lines.push('');
+            }
+            if (profile.behavioralNotes.length > 0) {
+                lines.push('**Observed Behavior:**');
+                for (const note of profile.behavioralNotes) {
+                    lines.push(`- ${note}`);
+                }
+                lines.push('');
+            }
+            if (profile.limitations.length > 0) {
+                lines.push('**Limitations:**');
+                for (const limitation of profile.limitations) {
+                    lines.push(`- ${limitation}`);
+                }
+                lines.push('');
+            }
+        }
+    }
+    else if (discovery.prompts.length > 0) {
+        // Fallback to basic listing if no profiles
+        lines.push('## Prompts');
+        lines.push('');
+        for (const prompt of discovery.prompts) {
+            lines.push(`### ${prompt.name}`);
+            lines.push('');
+            if (prompt.description) {
+                lines.push(prompt.description);
+                lines.push('');
+            }
+            if (prompt.arguments && prompt.arguments.length > 0) {
+                lines.push('**Arguments:**');
+                for (const arg of prompt.arguments) {
+                    const required = arg.required ? ' (required)' : '';
+                    lines.push(`- \`${arg.name}\`${required}: ${arg.description ?? 'No description'}`);
+                }
+                lines.push('');
+            }
+        }
+    }
+    // Resources section - use profiles if available, otherwise basic listing
+    if (result.resourceProfiles && result.resourceProfiles.length > 0) {
+        lines.push('## Resources');
+        lines.push('');
+        lines.push('Resources are data sources exposed by the server that can be read by clients.');
+        lines.push('');
+        for (const profile of result.resourceProfiles) {
+            lines.push(`### ${profile.name}`);
+            lines.push('');
+            lines.push(`**URI:** \`${profile.uri}\``);
+            if (profile.mimeType) {
+                lines.push(`**MIME Type:** ${profile.mimeType}`);
+            }
+            lines.push('');
+            lines.push(profile.description);
+            lines.push('');
+            if (profile.contentPreview) {
+                lines.push('**Content Preview:**');
+                lines.push('```');
+                lines.push(profile.contentPreview);
+                lines.push('```');
+                lines.push('');
+            }
+            if (profile.behavioralNotes.length > 0) {
+                lines.push('**Observed Behavior:**');
+                for (const note of profile.behavioralNotes) {
+                    lines.push(`- ${note}`);
+                }
+                lines.push('');
+            }
+            if (profile.limitations.length > 0) {
+                lines.push('**Limitations:**');
+                for (const limitation of profile.limitations) {
+                    lines.push(`- ${limitation}`);
+                }
+                lines.push('');
+            }
+        }
+    }
+    else if ((discovery.resources ?? []).length > 0) {
+        // Fallback to basic listing if no profiles
+        lines.push('## Resources');
+        lines.push('');
+        lines.push('Resources are data sources exposed by the server that can be read by clients.');
+        lines.push('');
+        for (const resource of discovery.resources ?? []) {
+            lines.push(`### ${resource.name}`);
+            lines.push('');
+            lines.push(`**URI:** \`${resource.uri}\``);
+            if (resource.mimeType) {
+                lines.push(`**MIME Type:** ${resource.mimeType}`);
+            }
+            lines.push('');
+            if (resource.description) {
+                lines.push(resource.description);
+                lines.push('');
+            }
+        }
+    }
+    // Overall limitations
+    if (limitations.length > 0) {
+        lines.push('## Known Limitations');
+        lines.push('');
+        for (const limitation of limitations) {
+            lines.push(`- ${limitation}`);
+        }
+        lines.push('');
+    }
+    // Recommendations
+    if (recommendations.length > 0) {
+        lines.push('## Recommendations');
+        lines.push('');
+        for (const rec of recommendations) {
+            lines.push(`- ${rec}`);
+        }
+        lines.push('');
+    }
+    // Behavioral Matrix (tool × persona findings)
+    if (metadata.personas && metadata.personas.length > 1 && toolProfiles.length > 0) {
+        const matrixSection = generateBehavioralMatrix(toolProfiles, metadata.personas);
+        if (matrixSection.length > 0) {
+            lines.push(...matrixSection);
+        }
+    }
+    // Metadata footer
+    lines.push('---');
+    lines.push('');
+    // Check if check mode (no LLM, deterministic)
+    const isCheckMode = metadata.model === 'check';
+    // Basic stats - simpler for check mode
+    let statsLine;
+    if (isCheckMode) {
+        statsLine = `*Check analysis completed in ${formatDuration(metadata.durationMs)}.*`;
+        lines.push(statsLine);
+    }
+    else {
+        // Explore mode: show more details
+        statsLine = `*Interview completed in ${formatDuration(metadata.durationMs)} with ${metadata.toolCallCount} tool interactions`;
+        // Add persona breakdown if multiple personas
+        if (metadata.personas && metadata.personas.length > 1) {
+            statsLine += '.*';
+            lines.push(statsLine);
+            lines.push('');
+            lines.push('**Persona Breakdown:**');
+            for (const persona of metadata.personas) {
+                lines.push(`- ${persona.name}: ${persona.questionsAsked} questions, ${persona.toolCallCount} calls`);
+            }
+        }
+        else {
+            statsLine += '.*';
+            lines.push(statsLine);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Generate Quick Reference section with tool signatures.
+ */
+function generateQuickReference(tools, profiles) {
+    const lines = [];
+    lines.push('## Quick Reference');
+    lines.push('');
+    lines.push('| Tool | Parameters | Returns |');
+    lines.push('|------|------------|---------|');
+    for (const tool of tools) {
+        const params = extractParameters(tool.inputSchema);
+        const profile = profiles.find(p => p.name === tool.name);
+        const returnType = inferReturnTypeDetailed(profile);
+        // Escape table cell content to prevent broken tables
+        lines.push(`| \`${escapeTableCell(tool.name)}\` | ${escapeTableCell(params)} | ${escapeTableCell(returnType)} |`);
+    }
+    lines.push('');
+    // Only add example section if we have at least one successful example
+    const successfulExamples = [];
+    for (const tool of tools) {
+        const profile = profiles.find(p => p.name === tool.name);
+        const example = generateExampleSnippet(tool, profile);
+        if (example) {
+            successfulExamples.push({ tool, example });
+        }
+    }
+    if (successfulExamples.length > 0) {
+        lines.push('### Example Usage');
+        lines.push('');
+        lines.push('*Examples shown are from successful tool calls during the interview.*');
+        lines.push('');
+        for (const { tool, example } of successfulExamples) {
+            lines.push(`#### ${tool.name}`);
+            lines.push('');
+            // Validate and escape JSON for code block
+            const jsonResult = validateJsonForCodeBlock(example);
+            lines.push('```json');
+            lines.push(jsonResult.content);
+            lines.push('```');
+            lines.push('');
+        }
+    }
+    return lines;
+}
+/**
+ * Infer return type from tool description when we can't observe actual responses.
+ */
+function inferReturnTypeFromDescription(description) {
+    const patterns = [
+        [/returns?\s+(the\s+)?base64[\s-]?encoded/i, 'base64 data (expected)'],
+        [/returns?\s+(a\s+)?json/i, 'JSON (expected)'],
+        [/returns?\s+(the\s+)?contents?\s+of/i, 'file content (expected)'],
+        [/returns?\s+(a\s+)?list(ing)?\s+of/i, 'list (expected)'],
+        [/returns?\s+(the\s+)?tree\s+(view|structure)/i, 'tree structure (expected)'],
+        [/returns?\s+(detailed\s+)?metadata/i, 'metadata (expected)'],
+        [/returns?\s+full\s+paths?/i, 'file paths (expected)'],
+        [/returns?\s+(a\s+)?git-style\s+diff/i, 'diff output (expected)'],
+        [/returns?\s+(a\s+)?recursive\s+tree/i, 'tree structure (expected)'],
+        [/read\s+(the\s+)?(complete\s+)?contents/i, 'file content (expected)'],
+        [/get\s+(a\s+)?(detailed\s+)?listing/i, 'directory listing (expected)'],
+        [/retrieve\s+(detailed\s+)?metadata/i, 'metadata (expected)'],
+        [/search\s+(for\s+)?files/i, 'file paths (expected)'],
+        [/create\s+(a\s+)?new\s+(file|directory)/i, 'success/error status (expected)'],
+        [/move\s+or\s+rename/i, 'success/error status (expected)'],
+    ];
+    for (const [pattern, returnType] of patterns) {
+        if (pattern.test(description)) {
+            return returnType;
+        }
+    }
+    return null;
+}
+/**
+ * Infer return type with more detail for Quick Reference.
+ */
+function inferReturnTypeDetailed(profile) {
+    if (!profile || profile.interactions.length === 0) {
+        return 'unknown';
+    }
+    // Look at successful interactions that don't have error-like content
+    const successful = profile.interactions.find(i => {
+        if (i.error || !i.response || i.response.isError)
+            return false;
+        const textContent = i.response.content?.find(c => c.type === 'text');
+        if (textContent && 'text' in textContent) {
+            if (looksLikeError(String(textContent.text)))
+                return false;
+        }
+        return true;
+    });
+    if (!successful || !successful.response) {
+        // No successful calls - try to infer from description
+        const inferred = inferReturnTypeFromDescription(profile.description);
+        if (inferred) {
+            return inferred;
+        }
+        return 'unknown';
+    }
+    const content = successful.response.content;
+    if (!content || content.length === 0) {
+        return 'empty response';
+    }
+    // Check content types
+    const types = new Set(content.map(c => c.type));
+    if (types.size === 1) {
+        const type = content[0].type;
+        if (type === 'text') {
+            const text = content[0].text || '';
+            // Try to identify JSON structure
+            if (text.startsWith('{')) {
+                try {
+                    const parsed = JSON.parse(text);
+                    const keys = Object.keys(parsed).slice(0, 3);
+                    if (keys.length > 0) {
+                        return `JSON object {${keys.join(', ')}${Object.keys(parsed).length > 3 ? ', ...' : ''}}`;
+                    }
+                    return 'JSON object';
+                }
+                catch {
+                    return 'JSON-like text';
+                }
+            }
+            if (text.startsWith('[')) {
+                try {
+                    const parsed = JSON.parse(text);
+                    if (Array.isArray(parsed)) {
+                        return `JSON array (${parsed.length} items)`;
+                    }
+                }
+                catch {
+                    return 'JSON-like text';
+                }
+            }
+            // Check for common patterns
+            if (text.includes('\n')) {
+                const lines = text.split('\n').length;
+                return `multi-line text (${lines} lines)`;
+            }
+            if (text.length > 100) {
+                return `text (${text.length} chars)`;
+            }
+            return 'text';
+        }
+        if (type === 'image') {
+            return 'base64 image';
+        }
+        return type;
+    }
+    return `mixed (${Array.from(types).join(', ')})`;
+}
+/**
+ * Generate example code snippet for a tool.
+ * Only returns examples from successful calls - returns null if no successful calls.
+ */
+function generateExampleSnippet(tool, profile) {
+    // ONLY use successful interactions - never generate synthetic examples
+    if (!profile || profile.interactions.length === 0) {
+        return null;
+    }
+    // Find a successful interaction (not an error) that doesn't have error-like content
+    const successful = profile.interactions.find(i => {
+        if (i.error || !i.response || i.response.isError)
+            return false;
+        const textContent = i.response.content?.find(c => c.type === 'text');
+        if (textContent && 'text' in textContent) {
+            if (looksLikeError(String(textContent.text)))
+                return false;
+        }
+        return true;
+    });
+    if (!successful) {
+        // No successful calls - don't generate fake examples
+        return null;
+    }
+    return JSON.stringify({
+        tool: tool.name,
+        arguments: successful.question.args,
+    }, null, 2);
+}
+/**
+ * Generate sample response section for a tool if we have successful calls.
+ */
+function generateSampleResponse(profile) {
+    const lines = [];
+    // Find a successful interaction with a response that doesn't look like an error
+    const successful = profile.interactions.find(i => {
+        if (i.error || !i.response || i.response.isError)
+            return false;
+        // Also check if the response content looks like an error
+        const textContent = i.response.content?.find(c => c.type === 'text');
+        if (textContent && 'text' in textContent) {
+            if (looksLikeError(String(textContent.text)))
+                return false;
+        }
+        return true;
+    });
+    if (!successful || !successful.response?.content) {
+        return lines;
+    }
+    const textContent = successful.response.content.find(c => c.type === 'text');
+    if (!textContent || !('text' in textContent)) {
+        return lines;
+    }
+    const text = String(textContent.text);
+    if (!text || text.length === 0) {
+        return lines;
+    }
+    // Truncate very long responses
+    const maxLength = 500;
+    let displayText = text;
+    let truncated = false;
+    if (text.length > maxLength) {
+        displayText = text.substring(0, maxLength);
+        truncated = true;
+    }
+    // Try to pretty-print JSON and validate/escape
+    const jsonResult = validateJsonForCodeBlock(displayText, {
+        maxLength: truncated ? maxLength : undefined,
+        truncationIndicator: '  ...',
+    });
+    lines.push('**Sample Response:**');
+    lines.push('```');
+    lines.push(jsonResult.content);
+    lines.push('```');
+    lines.push('');
+    return lines;
+}
+/**
+ * Extract common constraints that apply to multiple tools.
+ * Returns { common: string[], byTool: Map<string, string[]> }
+ */
+function extractCommonConstraints(profiles) {
+    // Count how many tools have each constraint (normalized)
+    const constraintCounts = new Map();
+    const toolConstraints = new Map();
+    const normalizeConstraint = (c) => {
+        return c.toLowerCase()
+            .replace(/['"`]/g, '')
+            .replace(/\s+/g, ' ')
+            .trim();
+    };
+    // Common patterns that should be grouped
+    const commonPatterns = [
+        { pattern: /directory.*restriction|access.*control|allowed.*director|within allowed/i, label: 'Directory access restrictions apply' },
+        { pattern: /path.*restriction|access denied.*path|outside.*allowed/i, label: 'Path access is restricted' },
+        { pattern: /requires.*parameter|parameter.*required|missing.*parameter/i, label: 'Validates required parameters' },
+    ];
+    for (const profile of profiles) {
+        const toolSpecific = [];
+        for (const limitation of profile.limitations) {
+            const normalized = normalizeConstraint(limitation);
+            // Check if this matches a common pattern
+            let isCommon = false;
+            for (const { pattern, label } of commonPatterns) {
+                if (pattern.test(limitation)) {
+                    const existing = constraintCounts.get(label);
+                    if (existing) {
+                        existing.count++;
+                    }
+                    else {
+                        constraintCounts.set(label, { count: 1, original: label });
+                    }
+                    isCommon = true;
+                    break;
+                }
+            }
+            if (!isCommon) {
+                // Check for exact/similar matches
+                const existing = constraintCounts.get(normalized);
+                if (existing) {
+                    existing.count++;
+                }
+                else {
+                    constraintCounts.set(normalized, { count: 1, original: limitation });
+                    toolSpecific.push(limitation);
+                }
+            }
+        }
+        if (toolSpecific.length > 0) {
+            toolConstraints.set(profile.name, toolSpecific);
+        }
+    }
+    // Constraints that appear in more than half of tools are "common"
+    const threshold = Math.max(MATH_FACTORS.MIN_COMMON_CONSTRAINT_THRESHOLD, Math.floor(profiles.length / 2));
+    const common = [];
+    for (const [, { count, original }] of constraintCounts) {
+        if (count >= threshold) {
+            common.push(original);
+        }
+    }
+    // Remove common constraints from per-tool lists
+    if (common.length > 0) {
+        for (const [toolName, constraints] of toolConstraints) {
+            const filtered = constraints.filter(c => {
+                const normalized = normalizeConstraint(c);
+                // Keep if it's tool-specific
+                return !common.some(common => normalizeConstraint(common) === normalized ||
+                    commonPatterns.some(p => p.label === common && p.pattern.test(c)));
+            });
+            toolConstraints.set(toolName, filtered);
+        }
+    }
+    return { common, byTool: toolConstraints };
+}
+/**
+ * Generate Global Constraints section for common restrictions.
+ */
+function generateGlobalConstraintsSection(common) {
+    if (common.length === 0) {
+        return [];
+    }
+    const lines = [];
+    lines.push('## Global Constraints');
+    lines.push('');
+    lines.push('The following restrictions apply to all tools:');
+    lines.push('');
+    for (const constraint of common) {
+        lines.push(`- ${constraint}`);
+    }
+    lines.push('');
+    return lines;
+}
+/**
+ * Generate Security Considerations section.
+ */
+function generateSecuritySection(profiles) {
+    const lines = [];
+    // Collect all security notes
+    const securityFindings = [];
+    for (const profile of profiles) {
+        for (const note of profile.securityNotes) {
+            const severity = classifySecuritySeverity(note);
+            securityFindings.push({ tool: profile.name, note, severity });
+        }
+    }
+    if (securityFindings.length === 0) {
+        return [];
+    }
+    lines.push('## Security Considerations');
+    lines.push('');
+    // Group by severity
+    const critical = securityFindings.filter(f => f.severity === 'critical');
+    const warnings = securityFindings.filter(f => f.severity === 'warning');
+    const info = securityFindings.filter(f => f.severity === 'info');
+    if (critical.length > 0) {
+        lines.push('### Critical Issues');
+        lines.push('');
+        for (const finding of critical) {
+            lines.push(`- **${finding.tool}**: ${finding.note}`);
+        }
+        lines.push('');
+    }
+    if (warnings.length > 0) {
+        lines.push('### Warnings');
+        lines.push('');
+        for (const finding of warnings) {
+            lines.push(`- **${finding.tool}**: ${finding.note}`);
+        }
+        lines.push('');
+    }
+    if (info.length > 0) {
+        lines.push('### Informational');
+        lines.push('');
+        for (const finding of info) {
+            lines.push(`- **${finding.tool}**: ${finding.note}`);
+        }
+        lines.push('');
+    }
+    return lines;
+}
+/**
+ * Classify security note severity.
+ */
+function classifySecuritySeverity(note) {
+    const lowerNote = note.toLowerCase();
+    const criticalKeywords = ['injection', 'rce', 'remote code', 'arbitrary code', 'command execution', 'sql injection', 'xss'];
+    const warningKeywords = ['risk', 'vulnerab', 'dangerous', 'unsafe', 'leak', 'exposure', 'sensitive'];
+    if (criticalKeywords.some(kw => lowerNote.includes(kw))) {
+        return 'critical';
+    }
+    if (warningKeywords.some(kw => lowerNote.includes(kw))) {
+        return 'warning';
+    }
+    return 'info';
+}
+/**
+ * Generate Performance section for AGENTS.md.
+ */
+function generatePerformanceSection(profiles) {
+    const lines = [];
+    const metrics = calculatePerformanceMetrics(profiles);
+    if (metrics.length === 0) {
+        return [];
+    }
+    lines.push('## Performance');
+    lines.push('');
+    lines.push('Response time metrics from interview sessions (in milliseconds):');
+    lines.push('');
+    lines.push('| Tool | Calls | Avg | P50 | P95 | Max | Error Rate |');
+    lines.push('|------|-------|-----|-----|-----|-----|------------|');
+    for (const m of metrics) {
+        const errorPct = (m.errorRate * 100).toFixed(0);
+        const errorDisplay = m.errorRate > 0.5 ? `**${errorPct}%**` : `${errorPct}%`;
+        // Escape table cell content
+        lines.push(`| \`${escapeTableCell(m.toolName)}\` | ${m.callCount} | ${m.avgMs}ms | ${m.p50Ms}ms | ${m.p95Ms}ms | ${m.maxMs}ms | ${errorDisplay} |`);
+    }
+    lines.push('');
+    // Add timing breakdown if separate timing data is available
+    const metricsWithBreakdown = metrics.filter(m => m.avgToolMs !== undefined && m.avgAnalysisMs !== undefined);
+    if (metricsWithBreakdown.length > 0) {
+        lines.push('### Timing Breakdown');
+        lines.push('');
+        lines.push('Breakdown of total time into tool execution (MCP) and LLM analysis:');
+        lines.push('');
+        lines.push('| Tool | Total Avg | Tool Exec | LLM Analysis | Tool % |');
+        lines.push('|------|-----------|-----------|--------------|--------|');
+        for (const m of metricsWithBreakdown) {
+            const toolPct = m.avgToolMs !== undefined && m.avgMs > 0
+                ? Math.round((m.avgToolMs / m.avgMs) * 100)
+                : 0;
+            lines.push(`| \`${escapeTableCell(m.toolName)}\` | ${m.avgMs}ms | ${m.avgToolMs}ms | ${m.avgAnalysisMs}ms | ${toolPct}% |`);
+        }
+        lines.push('');
+    }
+    // Add performance insights
+    const slowTools = metrics.filter(m => m.avgMs > 1000);
+    const unreliableTools = metrics.filter(m => m.errorRate > 0.3);
+    // Identify tools where LLM analysis dominates (>70% of total time)
+    const llmDominatedTools = metricsWithBreakdown.filter(m => {
+        const toolPct = m.avgToolMs !== undefined && m.avgMs > 0 ? (m.avgToolMs / m.avgMs) : 0;
+        return toolPct < 0.3; // Tool execution is < 30% means LLM is > 70%
+    });
+    if (slowTools.length > 0 || unreliableTools.length > 0 || llmDominatedTools.length > 0) {
+        lines.push('### Performance Insights');
+        lines.push('');
+        if (slowTools.length > 0) {
+            lines.push('**Slow Tools** (avg > 1s):');
+            for (const tool of slowTools) {
+                // Include breakdown if available
+                if (tool.avgToolMs !== undefined && tool.avgAnalysisMs !== undefined) {
+                    lines.push(`- \`${tool.toolName}\`: ${tool.avgMs}ms average (tool: ${tool.avgToolMs}ms, analysis: ${tool.avgAnalysisMs}ms)`);
+                }
+                else {
+                    lines.push(`- \`${tool.toolName}\`: ${tool.avgMs}ms average`);
+                }
+            }
+            lines.push('');
+        }
+        if (llmDominatedTools.length > 0) {
+            lines.push('**LLM Analysis Dominated** (tool execution < 30% of total):');
+            lines.push('');
+            lines.push('These timings are dominated by LLM analysis rather than actual tool execution:');
+            for (const tool of llmDominatedTools) {
+                lines.push(`- \`${tool.toolName}\`: tool exec ${tool.avgToolMs}ms vs analysis ${tool.avgAnalysisMs}ms`);
+            }
+            lines.push('');
+        }
+        if (unreliableTools.length > 0) {
+            lines.push('**Unreliable Tools** (error rate > 30%):');
+            for (const tool of unreliableTools) {
+                const errorPct = (tool.errorRate * 100).toFixed(0);
+                lines.push(`- \`${tool.toolName}\`: ${errorPct}% error rate`);
+            }
+            lines.push('');
+        }
+    }
+    return lines;
+}
+/**
+ * Generate Behavioral Matrix (tool × persona findings).
+ */
+function generateBehavioralMatrix(profiles, personas) {
+    const lines = [];
+    // Check if we have findings by persona
+    const hasPersonaFindings = profiles.some(p => p.findingsByPersona && p.findingsByPersona.length > 0);
+    if (!hasPersonaFindings) {
+        return [];
+    }
+    lines.push('## Behavioral Matrix');
+    lines.push('');
+    lines.push('Summary of findings by tool and persona:');
+    lines.push('');
+    // Build header - escape persona names in case they contain special characters
+    const header = ['Tool', ...personas.map(p => escapeTableCell(p.name))];
+    lines.push(`| ${header.join(' | ')} |`);
+    lines.push(`| ${header.map(() => '---').join(' | ')} |`);
+    // Build rows
+    for (const profile of profiles) {
+        const row = [escapeTableCell(profile.name)];
+        for (const persona of personas) {
+            const findings = profile.findingsByPersona?.find(f => f.personaId === persona.id);
+            if (findings) {
+                const count = findings.behavioralNotes.length +
+                    findings.limitations.length +
+                    findings.securityNotes.length;
+                const hasWarnings = findings.securityNotes.length > 0 || findings.limitations.length > 0;
+                const icon = hasWarnings ? '⚠️' : '✓';
+                row.push(`${icon} ${count} finding${count !== 1 ? 's' : ''}`);
+            }
+            else {
+                row.push('-');
+            }
+        }
+        lines.push(`| ${row.join(' | ')} |`);
+    }
+    lines.push('');
+    // Add legend
+    lines.push('<details>');
+    lines.push('<summary>Matrix Legend</summary>');
+    lines.push('');
+    lines.push('- ✓ = No warnings or limitations found');
+    lines.push('- ⚠️ = Warnings or limitations detected');
+    lines.push('- Numbers indicate total findings (behavioral notes + limitations + security notes)');
+    lines.push('');
+    lines.push('</details>');
+    lines.push('');
+    return lines;
+}
+//# sourceMappingURL=agents.js.map